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

XSLT 2.0 allows the pattern in the
match
attribute, and the expression in the
use
attribute, to reference global variables and to use the
key()
function to access other keys. But the definitions must not be circular; for example, if a key K makes use of the global variable V, then the value of V must not depend in any way on the key K.

There is no rule that stops two nodes having the same key value. For example, declaring a key for vehicle registration numbers in the example above does not mean that each registration number must be different. So a node can have more than one key value, and a key value can refer to more than one node.

To complicate things a bit further, there can be more than one

declaration in the stylesheet with the same name. The set of indexed values for the key is then the union of the sets produced by each

declaration independently. The import precedence of the key declarations makes no difference. All the

declarations with a given name must have the same values for the
collation
attribute, if present.

A key can be used to select nodes in any document, not just the principal source document. This includes a temporary document constructed within the stylesheet.

The effect of calling
key(K, V, R)
, where
K
is a key name,
V
is a value, and
R
is a node, is to select every node
N
that satisfies all the following conditions:

• The node
  N
  must be in the subtree rooted at
  R
  , that is, it must have
  R
  on its
  ancestor-or-self
  axis.
  
• The node
  N
  must match the pattern defined in the
  match
  attribute of an
  
  definition named
  K
  .
  
• One of the values in the sequence
  V
  must be equal to one of the values in the sequence obtained by evaluating the
  use
  attribute (or sequence constructor) of that key definition, with
  N
  as the context node. Values are compared using the XPath
  eq
  operator, with the specified collation.
  

If there are several nodes that satisfy these conditions, they are returned in document order, with duplicates eliminated.

If the third argument R is omitted, its effective value is
/
, which means that the function searches the whole of the document containing the context node.

Usage and Examples

Declaring a key has two effects: it simplifies the code you need to write to find the nodes with given values, and it is likely to make access faster.

The performance effect, of course, depends entirely on the implementation. It would be quite legitimate for an implementation to conduct a full search of the document each time the
key()
function was called. In practice, however, most implementations are likely to build an index or hash table, so there will be a one-time cost in building the index (for each document), but after this, access to nodes whose key value is known should be very fast.

The

element is usually used to index elements, but in principle it can be used to index any kind of node except namespace nodes.

Keys versus IDs

An alternative to using keys is to use XML-defined IDs. If you have attributes defined in a DTD or schema as being of type ID, you can find an element with a particular ID value using the
id()
function described in Chapter 13.

Why would you prefer to use keys, rather than relying on ID values? Keys have many advantages:

• ID values must be simple attributes of the elements they identify, they cannot be anything more complex.
  
• ID values must be unique.
  
• You cannot have two different sets of ID values in the same document, for example ISBNs and acquisition numbers; if you do, you have to be sure they will not clash with each other.
  
• ID values must take the form of XML names, for example they cannot contain characters such as
  /
  and
  +
  .
  
• ID values are not recognized in a source document unless it is parsed with a validating XML parser or schema processor that reports attribute types to the XSLT processor. XML parsers are not required to behave in this way, so it is easy to end up with configuration problems that result in IDs not being recognized.
  
• Recognizing ID attributes in temporary trees is particularly troublesome, as it requires the temporary tree to be validated.