XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (522 page)

Note the difference between an argument that is optional, and an argument that has an occurrence indicator of
?
. When the argument is optional, it can be omitted from the function call. When the occurrence indicator is
?
, the value must be supplied, but the empty sequence
()
is an acceptable value for the argument.

Many functions follow the convention of allowing an empty sequence for the first argument, or for subsequent arguments that play a similar role to the first argument, and returning an empty sequence if any of these arguments is an empty sequence. This is designed to make these functions easier to use in predicates. However, this is only a convention, and it is not followed universally. Most of the string functions instead treat an empty sequence the same way as a zero-length string.

When these functions are called, the supplied arguments are converted to the required type in the standard way defined by the XPath 2.0 function calling mechanism. The details of this depend on whether XPath 1.0 backward compatibility is activated or not. In XSLT this depends on the value of the
[xsl:]version
attribute in the stylesheet, as follows:

• In 2.0 mode, the standard conversion rules apply. These rules appear in Chapter 6 on page 505, under the heading
  Converting the Arguments and the Result
  . They permit only the following kinds of conversion:
  
  • Atomization of nodes to extract their numeric values
    
  • Promotion of numeric values to a different numeric type; for example,
    xs:integer
    to
    xs:double
    
  • Promotion of
    xs:anyURI
    values to
    xs:string
    
  • Casting of a value of type
    xs:untypedAtomic
    to the required type. Such values generally arise by extracting the content of a node that has not been schema-validated. The rules for casting from
    xs:untypedAtomic
    values to values of other types are essentially the rules defined in XML Schema for conversion from the lexical space of the type to the value space: more details are given in Chapter 11 (see
    Converting from string
    on page 663).
    
• In 1.0 mode, two additional conversions are allowed:
  
  • If the required type is
    xs:string
    or
    xs:double
    (perhaps with an occurrence indicator of
    ?
    ), then the first value in the supplied sequence is converted to the required type using the
    string()
    or
    number()
    function as appropriate, and other values in the sequence are discarded.
    
  • If the required type is
    node()
    or
    item()
    (perhaps with an occurrence indicator of
    ?
    ), then if the supplied value contains more than one item, all items except the first are ignored.
    

The effect of these rules is that even though the function signature might give the expected type of an argument as
xs:string
, say, the value you supply can be a node containing a string, or a node whose value is untyped (because it has not been validated using a schema), or an
xs:anyURI
value. With 1.0 compatibility mode on, you can also supply values of other types; for example, an
xs:integer
or an
xs:date
; but when compatibility mode is off, you will need to convert such values to an
xs:string
yourself, which you can achieve most simply by calling the
string()
function.

Code Samples

Most of the examples for this chapter are single XPath expressions. In the download file for this book, these code snippets are gathered into stylesheets, which in turn are organized according to the name of the function they exercise. In many cases the examples use no source document, in which case the stylesheet generally has a single template named
main
, which should be used as the entry point. In other cases the source document is generally named
source.xml
, and it should be used as the principal input to the stylesheet. Any stylesheets that require a schema-aware processor have names of the form
xxx-sa.xsl
.

Function Definitions

The remainder of this chapter gives the definitions of all the functions, in alphabetical order.

abs

The
abs()
function returns the absolute value of a number. For example,
abs(-3)
returns 3.