XSLT and XPath function reference in alphabetical order

(Excerpt from “XSLT 2.0 & XPath 2.0” by Frank Bongers, chapter 5, translated from German)

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

key

Category:

Association and localisation of nodes and resources at runtime

Origin:

XSLT 1.0

Return value:

A node sequence whose composition is determined by the combination passed on of a name and a desired value of a key definition.

Call/Arguments:

key($key-name, $comparativeValues?, $subtreeStartNode?)

$key-name:

Obligatory. The first argument informs the function about the identifier of the xsl:key key definition(s) to which the function refers. The argument is interpreted as string which has to correspond to the QName of a xsl:key key definition. If there are several identically named key declarations, they are used combined. (The case that same-named xsl:key declarations refer to different collations cannot occur since this would cause a static error.) A possible difference in their import precedence (see xsl:import) does not matter. It will result in a runtime error if no declaration with the appropriate QName exists or a non-valid QName has been passed on at the moment of the evaluation of the function.

$comparativeValues:

Optional. The second argument passes on a sequence to the function from which the comparative values are derived. This is done by atomisation of all non-atomic items, so that a sequence of xs:anyAtomicType atomic values is generated, each of which can be individually used as key value. The comparison is made according to the eq operator and according to the collation arranged in the xsl:key declaration. If an empty string or an empty sequence is passed on as second argument, the return value of the function is also empty.

$subtreeStartNode:

Optional. A single node of any type (reasonably an element node of the processed document). The third argument can limit the effect of the function on a subtree of the document tree. The node passed on is considered as start node of the subtree to which the examined nodes are in relation ancestor-or-self. If the third argument is not passed on, its default value / becomes effective which indicates the document node of the context node. In this case, the function operates in the whole processed document.

Purpose of use:

The key() function composes a sequence of those nodes in the processed document whose associated key definition resembles one or more of those values which result from the atomised sequence passed on as second argument during the function call. The node sequence generated in this way is organised in document order and does not contain any duplicates.

key('key-name', value-sequence)

The key() function can exploit its strengths where large amounts of elements are to be examined. One can imagine it like this: Already while reading in the document, the parser generates an index in the form of a look-up table of the elements indicated by the xsl:key declaration. Accordingly, this saved table can be accessed quickly.

An analogous result would also be achievable via a XPath predicate, but much slower: The parser must first »inspect« all appropriate elements, whereas it already »knows« them thanks to a key declaration.

Example - loop with key:

In this example, a list of book titles of an author (here passed on as a string) is outputted. The book elements in the source document are catalogued by authors via a xsl:key key definition. The xsl:for-each instruction forms a loop over all books of the respective author, whereby the key() function is used for dereferencing the key. For this, the identifier of the key and the name of an author are passed on as arguments.

Function definition:

XSLT 1.0:

key(string, object) -> node set

XSLT 2.0:

key($key-name as xs:string,

$key-value as xs:anyAtomicType*) as node()*

key($key-name as xs:string,

$key-value as xs:anyAtomicType*,

$top as node()) as node()*

Possible compatibility problems XSLT 2.0 to XSLT 1.0:

None. Indeed, XSLT 2.0 does not build a result node set but a result sequence which, however, also does not allow any duplications of contained nodes. In this respect, it is equivalent to a node set.