Chapter 7: XSLT Functions

Overview

This chapter describes all the standard functions included in the XSLT 2.0 specifications for use in XPath expressions. These functions are XSLT-specific additions to the standard XPath 2.0 function library, which is described in XPath 2.0 Programmer's Reference . The functions defined in the XPath specification are also summarized in Appendix B.

The description of each function includes its name , a brief description of its purpose, a list of the arguments it expects and the value it returns, the formal rules defining what the function does, and finally usage advice and examples.

If you are using XPath in a context other than XSLT, you should be aware that the functions described in this chapter will not be available.

The syntax and semantics of a function call are described as part of the XPath expression syntax in XPath 2.0 Programmer's Reference . A function call can be used anywhere within an expression, so long as it returns the proper type of value expected in the context where it appears. For example, on the right-hand side of the «/ » operator, a function call must return a sequence that consists entirely of nodes. Similarly, within a function call, the values supplied as arguments can be any XPath expression, subject only to the rules on data types.

The functions in this chapter are arranged in alphabetical order so you can find them quickly if you know what you're looking for. In case you only know the general area you are interested in, you may find the following quick reference useful.

Function	Purpose	Page
current()	Returns the current item in the stylesheet	526
current- group ()	Returns the contents of the current group of items being processed by <xsl:for-each-group>	529
current-grouping-key ()	Returns the value of the key value shared by all the items in the current group	530
document()	Loads an external document identified by URI	532
element-available()	Tests whether a given XSLT or extension instruction is available for use	542
format-date ()	Formats an xs:date value	548
format-dateTime()	Formats an xs:dateTime value	550
format-number()	Formats a number	558
format-time ()	Formats an xs:time value	562
function-available()	Tests whether a given function is available for use	564
generate-id ()	Generates a unique identifier for a node	568
key()	Locates nodes given the value of a key declared using <xsl:key>	572
regex-group ()	Returns a captured subgroup within a string matched using <xsl:analyze-string>	580
system-property ()	Returns information about the implementation	581
unparsed-entity-public-id ()	Returns the public identifier of an unparsed entity within a source document	584
unparsed-entity-uri ()	Returns the system identifier of an unparsed entity within a source document	585
unparsed-text ()	Reads the content of an external text file identified by its URI	587

All these functions are technically in the same namespace as the core XPath functions. This namespace is currently defined by the URI http://www.w3.org/2003/11/xpath-functions but this will change in subsequent drafts, until XPath is issued as a Candidate Recommendation. This namespace is conventionally used with the prefix «fn » However, within XSLT stylesheets, this namespace is the default namespace for function calls, so these functions can always be called without specifying a prefix. This distinguishes them clearly from user -defined functions, which always carry a namespace prefix.

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 backwards compatibility is activated or not, which in turn depends on the value of the [xsl:]version attribute on the innermost containing element that has such an attribute.

• If the effective version is «2.0 » or greater, then the standard conversion rules listed under <xsl:variable> (page 476) in Chapter 5 are used. These rules 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

  • Casting of a value of type xdt:untypedAtomic to the required type. Such values generally arise by extracting the content of a node that has not been schema validated

• If the effective version is «1.0 » , then 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 when the supplied value contains more than one item, all items except the first are ignored.

So, 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). With 1.0 compatibility mode on, you can also supply values of other types, for example an xs:integer or an xs:anyURI , 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.

The function descriptions use a common structure wherever possible. This includes the following subsections:

• The name of the function is followed by a very brief statement of the purpose of the function, sometimes with a quick example.

• The section Changes in 2.0 summarizes any significant changes in the function since XSLT 1.0.

• The Signature section includes a table listing the names and types of the arguments, with the meaning of each argument. It also defines the type of the result. Note that technically, functions are identified by their name and arity, so the document() function with two arguments is a different function from document() with one argument. However, the core function library has been designed so that different functions with the same name are always closely related , so it is simpler to describe these as two variants of the same function, in which the second argument is optional.

• The Effect section says what the function does, with each possible combination of input arguments.

• The Usage section contains advice on how the function can be used.

• The Examples section contains examples showing the function in use. Where appropriate, the examples are merged with the Usage section.

• The See Also section points you to other relevant information in this book or in XPath 2.0 Programmer's Reference .

For some functions (notably document()) , the description of the function is subdivided into a number of modes of use, each with its own Effect, Usage, and Examples subsections.