fn:generate-id

fn:generate-id() as xs:string

fn:generate-id($arg as node()?) as xs:string

The zero-argument form of this function is deterministic, context-dependent, and focus-dependent.

The one-argument form of this function is deterministic, context-independent, and focus-independent.

If the argument is omitted, it defaults to the context item (.). The behavior of the function if the argument is omitted is exactly the same as if the context item had been passed as the argument.

If the argument is the empty sequence, the result is the zero-length string.

In other cases, the function returns a string that uniquely identifies a given node. More formally, it is guaranteed that within a single execution scope, fn:codepoint-equal(fn:generate-id($N), fn:generate-id($M)) returns true if and only if ($M is $N) returns true.

The returned identifier must consist of ASCII alphanumeric characters and must start with an alphabetic character. Thus, the string is syntactically an XML name.

The following errors may be raised when $arg is omitted:

If the context item is absent, dynamic error [ERRXPDY0002]

If the context item is not a node, type error [ERRXPTY0004].

An implementation is free to generate an identifier in any convenient way provided that it always generates the same identifier for the same node and that different identifiers are always generated from different nodes. An implementation is under no obligation to generate the same identifiers each time a document is transformed or queried.

There is no guarantee that a generated unique identifier will be distinct from any unique IDs specified in the source document.

There is no inverse to this function; it is not directly possible to find the node with a given generated ID. Of course, it is possible to search a given sequence of nodes using an expression such as $nodes[generate-id()=$id].

It is advisable, but not required, for implementations to generate IDs that are distinct even when compared using a case-blind collation.

The primary use case for this function is to generate hyperlinks. For example, when generating HTML, an anchor for a given section $sect can be generated by writing (in either XSLT or XQuery):

<a name="{fn:generate-id($sect)}"/>

and a link to that section can then be produced with code such as:

see <a href="#{fn:generate-id($sect)}">here</a>

Note that anchors generated in this way will not necessarily be the same each time a document is republished.

Since the keys in a map must be atomic values, it is possible to use generated IDs as surrogates for nodes when constructing a map. For example, in some implementations, testing whether a node $N is a member of a large node-set $S using the expression fn:exists($N intersect $S) may be expensive; there may then be performance benefits in creating a map:

let $SMap := map:merge($S!map{fn:generate-id(.) : .})

and then testing for membership of the node-set using:

map:contains($SMap, fn:generate-id($N))