XPath and XQuery Functions and Operators 4.0

1.8.1 Item Types

The first diagram illustrates the relationship of various item types.

Item types are used to characterize the various types of item that can appear in a sequence (nodes, atomic items, and functions), and they are therefore used in declaring the types of variables or the argument types and result types of functions.

In XDM, item types include node types, function types, and built-in atomic types. Item types form a directed graph, rather than a hierarchy or lattice: in the relationship defined by the derived-from(A, B) function, some types are derived from more than one other type. Examples include functions (function(xs:string) as xs:int is substitutable for function(xs:NCName) as xs:int and also for function(xs:string) as xs:decimal), and choice types (A is substitutable for the choice type (A | B) and also for (A | C). Record types provide an alternative way of categorizing maps: the instances of record(longitude, latitude) overlap with the instances of map(xs:string, xs:double). The diagram, which shows only hierarchic relationships, is therefore a simplification of the full model.

1.9.5 Properties of functions

This section is concerned with the question of whether two calls on a function, with the same arguments, may produce different results.

In this section the term function, unless otherwise specified, applies equally to function definitions^XP (which can be the target of a static function call) and function items^DM (which can be the target of a dynamic function call).

[Definition] An execution scope is a sequence of calls to the function library during which certain aspects of the state are required to remain invariant. For example, two calls to fn:current-dateTime within the same execution scope will return the same result. The execution scope is defined by the host language that invokes the function library. In XSLT, for example, any two function calls executed during the same transformation are in the same execution scope (except that static expressions, such as those used in use-when attributes, are in a separate execution scope).

The following definition explains more precisely what it means for two function calls to return the same result:

[Definition] Two values $V1 and $V2 are defined to be identical if they contain the same number of items and the items are pairwise identical. Two items are identical if and only if one of the following conditions applies:

1. Both items are atomic items, of precisely the same type, and the values are equal as defined using the eq operator, using the Unicode codepoint collation when comparing strings.

2. Both items are nodes, and represent the same node.

3. Both items are maps, both maps have the same number of entries, and for every entry E₁ in the first map there is an entry E₂ in the second map such that the keys of E₁ and E₂ are the same key, and the corresponding values V₁ and V₂ are identical.

4. Both items are arrays, both arrays have the same number of members, and the members are pairwise identical.

5. Both items are function items, neither item is a map or array, and the two function items have the same function identity. The concept of function identity is explained in Section 7.1 Function Items^DM.Both items are function items, neither item is a map or array, and the two function items have the same function identity. The concept of function identity is explained in Section 8.1 Function Items^DM.Both items are function items, neither item is a map or array, and the two function items have the same function identity. The concept of function identity is explained in Section 7.18.1 Function Items^DM.

Some functions produce results that depend not only on their explicit arguments, but also on the static and dynamic context.

[Definition] A function definition^XP may have the property of being context-dependent: the result of such a function depends on the values of properties in the static and dynamic evaluation context of the caller as well as on the actual supplied arguments (if any). A function definition may be context-dependent for some arities in its arity range, and context-independent for others: for example fn:name#0 is context-dependent while fn:name#1 is context-independent.

[Definition] A function definition^XP that is not context-dependent is called context-independent.

The main categories of context-dependent functions are:

• Functions that explicitly deliver the value of a component of the static or dynamic context, for example fn:static-base-uri, fn:default-collation, fn:position, or fn:last.

• Functions with an optional parameter whose default value is taken from the static or dynamic context of the caller, usually either the context value (for example, fn:node-name) or the default collation (for example, fn:index-of).

• Functions that use the static context of the caller to expand or disambiguate the values of supplied arguments: for example fn:doc expands its first argument using the static base URI of the caller, and xs:QName expands its first argument using the in-scope namespaces of the caller.

[Definition] A function is focus-dependent if its result depends on the focus^XP31 (that is, the context item, position, or size) of the caller.

[Definition] A function that is not focus-dependent is called focus-independent.

A function definition that is context-dependent can be used as the target of a named function reference, can be partially applied, and can be found using fn:function-lookup. The principle in such cases is that the static context used for the function evaluation is taken from the static context of the named function reference, partial function application, or the call on fn:function-lookup; and the dynamic context for the function evaluation is taken from the dynamic context of the evaluation of the named function reference, partial function application, or the call of fn:function-lookup. These constructs all deliver a function item^DM having a captured context based on the static and dynamic context of the construct that created the function item. This captured context forms part of the closure of the function item.

The result of a dynamic call to a function item never depends on the static or dynamic context of the dynamic function call, only (where relevant) on the captured context held within the function item itself.

The fn:function-lookup function is a special case because it is potentially dependent on everything in the static and dynamic context. This is because the static and dynamic context of the call to fn:function-lookupform the captured context of the function item that fn:function-lookup returns.

[Definition] A function that is guaranteed to produce identical results from repeated calls within a single execution scope if the explicit and implicit arguments are identical is referred to as deterministic.

[Definition] A function that is not deterministic is referred to as nondeterministic.

All functions defined in this specification are deterministic unless otherwise stated. Exceptions include the following:

• [Definition] Some functions (such as fn:distinct-values, fn:unordered, map:keys, and map:for-each) produce results in an implementation-defined or implementation-dependent order. In such cases two calls with the same arguments are not guaranteed to produce the results in the same order. These functions are said to be nondeterministic with respect to ordering.

• Some functions (such as fn:analyze-string, fn:parse-xml, fn:parse-xml-fragment, fn:parse-html, and fn:json-to-xml) construct a tree of nodes to represent their results. There is no guarantee that repeated calls with the same arguments will return the same identical node (in the sense of the is operator). However, if non-identical nodes are returned, their content will be the same in the sense of the fn:deep-equal function. Such a function is said to be nondeterministic with respect to node identity.

• Some functions (such as fn:doc and fn:collection) create new nodes by reading external documents. Such functions are guaranteed to be deterministic with the exception that an implementation is allowed to make them nondeterministic as a user option.

Where the results of a function are described as being (to a greater or lesser extent) implementation-defined or implementation-dependent, this does not by itself remove the requirement that the results should be deterministic: that is, that repeated calls with the same explicit and implicit arguments must return identical results.

[Definition] The function fn:concat is defined to be variadic: it accepts any number of arguments. No other function has this property.

2.1.1 fn:node-name

Summary

Returns the name of a node, as an xs:QName.

Signature

fn:node-name(
$node	as node()?	:= .
) as xs:QName?

Properties

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.

Rules

If the argument is omitted, it defaults to the context value (.).

If $node is the empty sequence, the empty sequence is returned.

Otherwise, the function returns the result of the dm:node-name accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 6.7.10 node-name Accessor^DM).Otherwise, the function returns the result of the dm:node-name accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 7.5.10 node-name Accessor^DM).Otherwise, the function returns the result of the dm:node-name accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 6.7.107.5.10 node-name Accessor^DM).

Error Conditions

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

• If the context value is absent^DM, type error [err:XPDY0002]^XP.

• If the context value is not an instance of the sequence type node()?, type error [err:XPTY0004]^XP.

Notes

For element and attribute nodes, the name of the node is returned as an xs:QName, retaining the prefix, namespace URI, and local part.

For processing instructions, the name of the node is returned as an xs:QName in which the prefix and namespace URI are absent^DM.

For a namespace node, the function returns an empty sequence if the node represents the default namespace; otherwise it returns an xs:QName in which prefix and namespace URI are absent^DM and the local part is the namespace prefix being bound.

For all other kinds of node, the function returns the empty sequence.

Examples

Variables
let $e := <doc> <p id="alpha" xml:id="beta">One</p> <p id="gamma" xmlns="http://example.com/ns">Two</p> <ex:p id="delta" xmlns:ex="http://example.com/ns">Three</ex:p> <?pi 3.14159?> </doc>

Expression	Result
node-name($e//*[@id = 'alpha'])	QName("", "p")
node-name($e//*[@id = 'gamma'])	QName("http://example.com/ns", "p")
node-name($e//*[@id = 'delta'])	QName("http://example.com/ns", "ex:p")
node-name($e//processing-instruction())	QName("", "pi")
node-name($e//*[@id = 'alpha']/text())	()
node-name($e//*[@id = 'alpha']/@id)	QName("", "id")
node-name($e//*[@id = 'alpha']/@xml:id)	#xml:id

2.1.2 fn:nilled

Summary

Returns true for an element that is nilled.

Signature

fn:nilled(
$node	as node()?	:= .
) as xs:boolean?

Properties

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.

Rules

If the argument is omitted, it defaults to the context value (.).

If $node is the empty sequence, the function returns the empty sequence.

Otherwise the function returns the result of the dm:nilled accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 6.7.8 nilled Accessor^DM).Otherwise the function returns the result of the dm:nilled accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 7.5.8 nilled Accessor^DM).Otherwise the function returns the result of the dm:nilled accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 6.7.87.5.8 nilled Accessor^DM).

Error Conditions

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

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not an instance of the sequence type node()?, type error [err:XPTY0004]^XP.

Notes

If $node is not an element node, the function returns the empty sequence.

If $node is an untyped element node, the function returns false.

In practice, the function returns true only for an element node that has the attribute xsi:nil="true" and that is successfully validated against a schema that defines the element to be nillable; the detailed rules, however, are defined in [XQuery and XPath Data Model (XDM) 3.1].

2.1.3 fn:string

Summary

Returns the value of $value represented as an xs:string.

Signature

fn:string(
$value	as item()?	:= .
) as xs:string

Properties

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.

Rules

In the zero-argument version of the function, $value defaults to the context value. That is, calling fn:string() is equivalent to calling fn:string(.).

If $value is the empty sequence, the function returns the zero-length string.

If $value is a node, the function returns the string value of the node, as obtained using the dm:string-value accessor defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 6.7.12 string-value Accessor^DM).If $value is an XNode^DM, the function returns the string value of the node, as obtained using the dm:string-value accessor defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 7.5.12 string-value Accessor^DM).If $value is aan XNode^nodeDM, the function returns the string value of the node, as obtained using the dm:string-value accessor defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 6.7.127.5.12 string-value Accessor^DM).

If $value is a JNode^DM, the function returns the result of string(JNode-value($value)). This will fail in the case where JNode-value($value) is a map or an array.

If $value is an atomic item, the function returns the result of the expression $value cast as xs:string (see 22 Casting22 Casting).If $value is an atomic item, the function returns the result of the expression $value cast as xs:string (see 23 Casting23 Casting).If $value is an atomic item, the function returns the result of the expression $value cast as xs:string (see 22 Casting23 Casting2223 Casting).

In all other cases, a dynamic error occurs (see below).

Error Conditions

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

• If the context value is absent^DM, type error [err:XPDY0002]^XP.

• If the context value is not an instance of the sequence type item()?, type error [err:XPTY0004]^XP.

A type error is raised [err:FOTY0014] if $value is a function item (this includes maps and arrays).

Notes

Every node has a string value, even an element with element-only content (which has no typed value). Moreover, casting an atomic item to a string always succeeds. Functions, maps, and arrays have no string value, so these are the only arguments that satisfy the typesatisfy the type signature but cause failure. Applying the string signature but cause failurefunction to a JNode succeeds if the JNode wraps a simple value such as a string, number, or boolean, or if it wraps an XNode, but it fails in the case where the JNode wraps a map or an array.

Examples

Variables
let $para := <para>There lived a <term author="Tolkien">hobbit</term>.</para>

Expression	Result
string(23)	"23"
string(false())	"false"
string("Paris")	"Paris"
string((1, 2, 3))	Raises error XPTY0004.
string([ [ 1, 2 ], [ 3, 4 ] ])	Raises error FOTY0014.
string(abs#1)	Raises error FOTY0014.
string(JNode({"x": [10, 20, 30]}) ? x ? 3)	"30"
string(JNode({"x": [10, 20, 30]}) ? x ? 3)	"30"
string($para)	"There lived a hobbit."

2.1.4 fn:data

Summary

Returns the result of atomizing a sequence. This process flattens arrays, and replaces nodes by their typed values.

Signature

fn:data(
$input	as item()*	:= .
) as xs:anyAtomicType*

Properties

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.

Rules

If the argument is omitted, it defaults to the context value (.).

The result of fn:data is the sequence of atomic items produced by applying the following rules to each item in $input:

• If the item is an atomic item, it is appended to the result sequence.

• If the item is a node, the typed value of the node is appended to the result sequence. The typed value is a sequence of zero or more atomic items: specifically, the result of the dm:typed-value accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (See Section 6.7.14 typed-value Accessor^DM).If the item is an XNode^DM, the typed value of the node is appended to the result sequence. The typed value is a sequence of zero or more atomic items: specifically, the result of the dm:typed-value accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (See Section 7.5.14 typed-value Accessor^DM).If the item is aan XNode^nodeDM, the typed value of the node is appended to the result sequence. The typed value is a sequence of zero or more atomic items: specifically, the result of the dm:typed-value accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (See Section 6.7.147.5.14 typed-value Accessor^DM).

• If the item is a JNode^DM, the atomized value of its ¶value property is appended to the result sequence.

• If the item is a JNode^DM, the atomized value of its ¶value property is appended to the result sequence.

• If the item is an array, the result of applying fn:data to each member of the array, in order, is appended to the result sequence.

Error Conditions

A type error is raised [err:FOTY0012] if an item in the sequence $input is a node that does not have a typed value.

A type error is raised [err:FOTY0013] if an item in the sequence $input is a function item other than an array.

A type error is raised [err:XPDY0002]^XP if $input is omitted and the context value is absent^DM.

Notes

The process of applying the fn:data function to a sequence is referred to as atomization. In many cases an explicit call on fn:data is not required, because atomization is invoked implicitly when a node or sequence of nodes is supplied in a context where an atomic item or sequence of atomic items is required.

The result of atomizing an empty sequence is an empty sequence.

The result of atomizing an empty array is an empty sequence.

Examples

Variables
let $para := <para>There lived a <term author="Tolkien">hobbit</term>.</para>

Expression	Result
data(123)	123
data((123, 456))	123, 456
data([ [ 1, 2 ], [ 3, 4 ] ])	1, 2, 3, 4
data($para)	xs:untypedAtomic("There lived a hobbit.")
data($para/term/@author)	xs:untypedAtomic("Tolkien")
data(abs#1)	Raises error FOTY0013.

2.1.5 fn:base-uri

Summary

Returns the base URI of a node.

Signature

fn:base-uri(
$node	as node()?	:= .
) as xs:anyURI?

Properties

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.

Rules

The zero-argument version of the function returns the base URI of the context node: it is equivalent to calling fn:base-uri(.).

The single-argument version of the function behaves as follows:

1. If $node is the empty sequence, the function returns the empty sequence.

2. Otherwise, the function returns the value of the dm:base-uri accessor applied to the node $node. This accessor is defined, for each kind of node, in the XDM specification (See Section 6.7.2 base-uri Accessor^DM).Otherwise, the function returns the value of the dm:base-uri accessor applied to the node $node. This accessor is defined, for each kind of node, in the XDM specification (See Section 7.5.2 base-uri Accessor^DM).Otherwise, the function returns the value of the dm:base-uri accessor applied to the node $node. This accessor is defined, for each kind of node, in the XDM specification (See Section 6.7.27.5.2 base-uri Accessor^DM).

Note:

As explained in XDM, document, element and processing-instruction nodes have a base-uri property which may be empty. The base-uri property for all other node kinds is the empty sequence. The dm:base-uri accessor returns the base-uri property of a node if it exists and is non-empty; otherwise it returns the result of applying the dm:base-uri accessor to its parent, recursively. If the node does not have a parent, or if the recursive ascent up the ancestor chain encounters a parentless node whose base-uri property is empty, the empty sequence is returned. In the case of namespace nodes, however, the result is always an empty sequence — it does not depend on the base URI of the parent element.

See also fn:static-base-uri.

Error Conditions

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

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not an instance of the sequence type node()?, type error [err:XPTY0004]^XP.

2.1.6 fn:document-uri

Summary

Returns the URI of a resource where a document can be found, if available.

Signature

fn:document-uri(
$node	as node()?	:= .
) as xs:anyURI?

Properties

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.

Rules

If the argument is omitted, it defaults to the context value (.).

If $node is the empty sequence, the function returns the empty sequence.

If $node is not a document node, the function returns the empty sequence.

Otherwise, the function returns the value of the document-uri accessor applied to $node, as defined in [XQuery and XPath Data Model (XDM) 3.1] (See Section 6.6.1.2 Accessors^DM).Otherwise, the function returns the value of the document-uri accessor applied to $node, as defined in [XQuery and XPath Data Model (XDM) 3.1] (See Section 7.4.1.2 Accessors^DM).Otherwise, the function returns the value of the document-uri accessor applied to $node, as defined in [XQuery and XPath Data Model (XDM) 3.1] (See Section 6.6.1.27.4.1.2 Accessors^DM).

Error Conditions

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

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not an instance of the sequence type node()?, type error [err:XPTY0004]^XP.

Notes

In the 3.1 version of this specification, it was mandated that two distinct documents could not have the same document-uri property: more specifically, it was guaranteed that for any document node $D, either document-uri($D) would be absent, or doc(document-uri($D)) would return $D.

For various reasons, this constraint has proved impractical. Different parts of an application may read the same external resource in different ways, for example with or without validation or whitespace stripping, leading to different document nodes derived from the same external resource having the same document-uri property. In addition, the specification explicitly allows implementations, at user request, to relax the requirements for determinism of resource access functions, which makes it possible for multiple calls of functions such as fn:doc, fn:json-doc, or fn:collection to return different results for the same supplied URI.

Although the uniqueness of the document-uri property is no longer an absolute constraint, it is still desirable that implementations should where possible respect the principle that URIs are usable as identifiers for resources.

In the case of a document node $D returned by the fn:doc function, it will generally be the case that fn:document-uri($D) returns a URI $U such that a call on fn:doc($U) in the same dynamic context will return the same document node $D. The URI $U will not necessarily be the same URI that was originally passed to the fn:doc function, since several URIs may identify the same resource.

It is recommended that implementations of fn:collection should ensure that any documents included in the returned collection, if they have a non-empty fn:document-uri property, should be such that a call on fn:doc supplying this URI returns the same document node.

2.2.2 fn:local-name

Summary

Returns the local part of the name of $node as an xs:string that is either the zero-length string, or has the lexical form of an xs:NCName.

Signature

fn:local-name(
$node	as node()?	:= .
) as xs:string

Properties

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.

Rules

If the argument is omitted, it defaults to the context value (.).

If the argument is supplied and is the empty sequence, the function returns the zero-length string.

If the node identified by $node has no name (that is, if it is a document node, a comment, a text node, or a namespace node having no name), the function returns the zero-length string.

Otherwise, the function returns the local part of the expanded-QName of the node identified by $node, as determined by the dm:node-name accessor defined in Section 6.7.10 node-name Accessor^DM. This will be an xs:string whose lexical form is an xs:NCName.Otherwise, the function returns the local part of the expanded-QName of the node identified by $node, as determined by the dm:node-name accessor defined in Section 7.5.10 node-name Accessor^DM. This will be an xs:string whose lexical form is an xs:NCName.Otherwise, the function returns the local part of the expanded-QName of the node identified by $node, as determined by the dm:node-name accessor defined in Section 6.7.107.5.10 node-name Accessor^DM. This will be an xs:string whose lexical form is an xs:NCName.

Error Conditions

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

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not a single node, type error [err:XPTY0004]^XP.

Examples

Variables
let $e := <doc> <p id="alpha" xml:id="beta">One</p> <p id="gamma" xmlns="http://example.com/ns">Two</p> <ex:p id="delta" xmlns:ex="http://example.com/ns">Three</ex:p> <?pi 3.14159?> </doc>

Expression	Result
local-name($e//*[@id = 'alpha'])	"p"
local-name($e//*[@id = 'gamma'])	"p"
local-name($e//*[@id = 'delta'])	"p"
local-name($e//processing-instruction())	"pi"
local-name($e//*[@id = 'alpha']/text())	""
local-name($e//*[@id = 'alpha']/@id)	"id"
local-name($e//*[@id = 'alpha']/@xml:id)	"id"

2.2.3 fn:namespace-uri

Summary

Returns the namespace URI part of the name of $node, as an xs:anyURI value.

Signature

fn:namespace-uri(
$node	as node()?	:= .
) as xs:anyURI

Properties

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.

Rules

If the argument is omitted, it defaults to the context node (.).

If the node identified by $node is neither an element nor an attribute node, or if it is an element or attribute node whose expanded-QName (as determined by the dm:node-name accessor in the Section 6.7.10 node-name Accessor^DM) is in no namespace, then the function returns the zero-length xs:anyURI value.If the node identified by $node is neither an element nor an attribute node, or if it is an element or attribute node whose expanded-QName (as determined by the dm:node-name accessor in the Section 7.5.10 node-name Accessor^DM) is in no namespace, then the function returns the zero-length xs:anyURI value.If the node identified by $node is neither an element nor an attribute node, or if it is an element or attribute node whose expanded-QName (as determined by the dm:node-name accessor in the Section 6.7.107.5.10 node-name Accessor^DM) is in no namespace, then the function returns the zero-length xs:anyURI value.

Otherwise, the result will be the namespace URI part of the expanded-QName of the node identified by $node, as determined by the dm:node-name accessor defined in Section 6.7.10 node-name Accessor^DM), returned as an xs:anyURI value.Otherwise, the result will be the namespace URI part of the expanded-QName of the node identified by $node, as determined by the dm:node-name accessor defined in Section 7.5.10 node-name Accessor^DM), returned as an xs:anyURI value.Otherwise, the result will be the namespace URI part of the expanded-QName of the node identified by $node, as determined by the dm:node-name accessor defined in Section 6.7.107.5.10 node-name Accessor^DM), returned as an xs:anyURI value.

Error Conditions

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

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not an instance of the sequence type node()?, type error [err:XPTY0004]^XP.

Examples

Variables
let $e := <doc> <p id="alpha" xml:id="beta">One</p> <p id="gamma" xmlns="http://example.com/ns">Two</p> <ex:p id="delta" xmlns:ex="http://example.com/ns">Three</ex:p> <?pi 3.14159?> </doc>

Expression	Result
namespace-uri($e//*[@id = 'alpha'])	""
namespace-uri($e//*[@id = 'gamma'])	"http://example.com/ns"
namespace-uri($e//*[@id = 'delta'])	"http://example.com/ns"
namespace-uri($e//processing-instruction())	""
namespace-uri($e//*[@id = 'alpha']/text())	""
namespace-uri($e//*[@id = 'alpha']/@id)	""
namespace-uri($e//*[@id = 'alpha']/@xml:id)	"http://www.w3.org/XML/1998/namespace"

2.2.5 fn:root

Summary

Returns the root of the tree to which $node belongs. This will usually, but not necessarily, be a document node.Returns the root of the tree to which $node belongs. The function can be applied both to XNodes^DM and to JNodes^DM.Returns the root of the tree to which $node belongs. This will usually, but not necessarily, be a document nodeThe function can be applied both to XNodes^DM and to JNodes^DM.

Signature

fn:root(
$node	as node()?as GNode()?as nodeGNode()?	:= .
) as node()?) as GNode()?) as nodeGNode()?

Properties

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.

Rules

If the function is called without an argument, the context value (.) is used as the default argument.

The function returns the value of the expression ($arg/ancestor-or-self::node())[1].If the (explicit or implicit) argument is a XNode^DM, the function returns the value of the expression $arg/ancestor-or-self::node()[last()].TheIf the (explicit or implicit) argument is a XNode^DM, the function returns the value of the expression ($arg/ancestor-or-self::node())[1[last()].

If the (explicit or implicit) argument is a JNode^DM, the function returns the value of the expression $arg?ancestor-or-self::*[last()].

Error Conditions

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

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not an instance of the sequence type node()?, type error [err:XPTY0004]^XP.If the context value is not an instance of the sequence type GNode()?, type error [err:XPTY0004]^XP.If the context value is not an instance of the sequence type nodeGNode()?, type error [err:XPTY0004]^XP.

Examples

These examples use some variables which could be defined in [XQuery 4.0: An XML Query Language] as:

let $i := <tool>wrench</tool> let $o := <order>{ $i }<quantity>5</quantity></order> let $odoc := document { $o } let $newi := $o/tool

Or they could be defined in [XSL Transformations (XSLT) Version 4.0] as:

<xsl:variable name="i" as="element()"> <tool>wrench</tool> </xsl:variable> <xsl:variable name="o" as="element()"> <order> <xsl:copy-of select="$i"/> <quantity>5</quantity> </order> </xsl:variable> <xsl:variable name="odoc"> <xsl:copy-of select="$o"/> </xsl:variable> <xsl:variable name="newi" select="$o/tool"/>

root($i) returns the element node $i

root($o/quantity) returns the element node $o

root($odoc//quantity) returns the document node $odoc

root($newi) returns the element node $o

The final three examples could be made type-safe by wrapping their operands with exactly-one().

2.3.1 fn:distinct-ordered-nodes

Summary

Removes duplicate nodesGNodes and sorts the input into document order.

Signature

fn:distinct-ordered-nodes(
$nodes	as node()*as GNode()*as nodeGNode()*
) as node()*) as GNode()*) as nodeGNode()*

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

Any duplicate nodes in the input (based on node identity) are discarded. The remaining nodes are returned in document order^XP.Any duplicate GNodes (that is, XNodes or JNodes) in the input (based on node identity) are discarded. The remaining GNodes are returned in document order^XP.Any duplicate nodesGNodes (that is, XNodes or JNodes) in the input (based on node identity) are discarded. The remaining nodesGNodes are returned in document order^XP.

Notes

Document order is implementation-dependent (but stable) for nodes in different documents. If some node in document A precedes some node in document B, then every node in A precedes every node in B.Document order is implementation-dependent (but stable) for GNodes in different trees. If some GNode in tree A precedes some GNode in tree B, then every GNode in A precedes every GNode in B.Document order is implementation-dependent (but stable) for nodesGNodes in different documentstrees. If some node in documentGNode in tree A precedes some node in documentGNode in tree B, then every nodeGNode in A precedes every nodeGNode in B.

Examples

Expression:	let $x := parse-xml('<doc><a/><b/><c/><d/><c/><e/></doc>') return distinct-ordered-nodes(($x//c, $x//b, $x//a, $x//b)) ! name()
Result:	"a", "b", "c", "c" (The two $x//b expressions select the same node; one of these is eliminated as a duplicate. The $x//c expression selects two nodes that have distinct identity, so both are retained.)
Expression:	let $x := {"a":{"a":{"a":1}}} return distinct-ordered-nodes( $x ? descendant::a ? descendant::a) => count()
Expression:	let $x := {"a":{"a":{"a":1}}} return distinct-ordered-nodes( $x ? descendant::a ? descendant::a) => count()
Result:	3 (The innermost map entry "a":1 is selected by two different routes; the lookup operator does not eliminate duplicate JNodes.)
Result:	3 (The innermost map entry "a":1 is selected by two different routes; the lookup operator does not eliminate duplicate JNodes.)

4.5.1 fn:number

Summary

Returns the value indicated by $value or, if $value is not specified, the context value after atomization, converted to an xs:double.

Signature

fn:number(
$value	as xs:anyAtomicType?	:= .
) as xs:double

Properties

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.

Rules

Calling the zero-argument version of the function is defined to give the same result as calling the single-argument version with the context value (.). That is, fn:number() is equivalent to fn:number(.), as defined by the rules that follow.

If $value is the empty sequence or if $value cannot be converted to an xs:double, the xs:double value NaN is returned.

Otherwise, $value is converted to an xs:double following the rules of 22.1.3.2 Casting to xs:double22.1.3.2 Casting to xs:double. If the conversion to xs:double fails, the xs:double value NaN is returned.Otherwise, $value is converted to an xs:double following the rules of 23.1.3.2 Casting to xs:double23.1.3.2 Casting to xs:double. If the conversion to xs:double fails, the xs:double value NaN is returned.Otherwise, $value is converted to an xs:double following the rules of 22.1.3.2 Casting to xs:double23.1.3.2 Casting to xs:double22.1.3.223.1.3.2 Casting to xs:double. If the conversion to xs:double fails, the xs:double value NaN is returned.

Error Conditions

A type error is raised [err:XPDY0002]^XP if $value is omitted and the context value is absent^DM.

As a consequence of the rules given above, a type error is raised [err:XPTY0004]^XP if the context value cannot be atomized, or if the result of atomizing the context value is a sequence containing more than one atomic item.

Notes

XSD 1.1 allows the string +INF as a representation of positive infinity; XSD 1.0 does not. It is implementation-defined whether XSD 1.1 is supported.

Generally fn:number returns NaN rather than raising a dynamic error if the argument cannot be converted to xs:double. However, a type error is raised in the usual way if the supplied argument cannot be atomized or if the result of atomization does not match the required argument type.

Examples

Variables
let $e := <e price="12.1" discount="NONE"/>

Expression	Result
number(12)	1.2e1
number('12')	1.2e1
number('INF')	xs:double('INF')
number('NaN')	xs:double('NaN')
number('non-numeric')	xs:double('NaN')
number($e/@price)	1.21e1
number($e/@discount)	xs:double('NaN')
number($e/@misspelt)	xs:double('NaN')
("10", "11", "12") ! number()	1.0e1, 1.1e1, 1.2e1

8.3.1 fn:boolean

Summary

Computes the effective boolean value of the sequence $input.

Signature

fn:boolean(
$input	as item()*
) as xs:boolean

Rules

The function computes the effective boolean value of a sequence, defined according to the following rules. See also Section 2.5.4 Effective Boolean Value^XP.

• If $input is the empty sequence, fn:boolean returns false.

• If $input is a sequence whose first item is a node, fn:boolean returns true.If $input is a sequence whose first item is a GNode^DM (a generalized node), fn:boolean returns true.If $input is a sequence whose first item is a GNode^DMnode (a generalized node), fn:boolean returns true.

• If $input is a singleton value of type xs:boolean or a derived from xs:boolean, fn:boolean returns $input.If $input is a singleton value of type xs:boolean or of a type derived from xs:boolean, fn:boolean returns $input.If $input is a singleton value of type xs:boolean or of a type derived from xs:boolean, fn:boolean returns $input.

• If $input is a singleton value of type xs:untypedAtomic, xs:string, xs:anyURI, or a type derived from xs:string or xs:anyURI, fn:boolean returns false if the operand value has zero length; otherwise it returns true.

• If $input is a singleton value of any numeric type or a type derived from a numeric type, fn:boolean returns false if the operand value is NaN or is numerically equal to zero; otherwise it returns true.

Error Conditions

In all cases other than those listed above, fn:boolean raises a type error [err:FORG0006].

Notes

The result of this function is not necessarily the same as $input cast as xs:boolean. For example, fn:boolean("false") returns the value true whereas "false" cast as xs:boolean (which can also be written xs:boolean("false")) returns false.

Examples

Variables
let $abc := ("a", "b", "")

Expression	Result
boolean($abc[1])	true()
boolean($abc[0])	false()
boolean($abc[3])	false()
fn:boolean($abc) raises a type error [err:FORG0006].
fn:boolean([]) raises a type error [err:FORG0006].

14.2.2 fn:deep-equal

Summary

This function assesses whether two sequences are deep-equal to each other. To be deep-equal, they must contain items that are pairwise deep-equal; and for two items to be deep-equal, they must either be atomic items that compare equal, or nodes of the same kind, with the same name, whose children are deep-equal, or maps with matching entries, or arrays with matching members.

Signature

fn:deep-equal(
$input1	as item()*,
$input2	as item()*,
$options	as (xs:string | map(*))?	:= {}
) as xs:boolean

Properties

The two-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on collations, and implicit timezone.

The three-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on collations, and static base URI, and implicit timezone.

Rules

The $options argument, if present, defines additional parameters controlling how the comparison is done. If it is supplied as a map, then the option parameter conventions apply.

For backwards compatibility reasons, the $options argument can also be set to a string containing a collation name. Supplying a string $S for this argument is equivalent to supplying the map { 'collation': $S }. Omitting the argument, or supplying the empty sequence, is equivalent to supplying an empty map.

If the two sequences ($input1 and $input2) are both empty, the function returns true.

If the two sequences are of different lengths, the function returns false.

If the two sequences are of the same length, the comparison is controlled by the ordered option:

• By default, the option is true: The function returns true if and only if every item in the sequence $input1 is deep-equal to the item at the same position in the sequence $input2.

• If the option is set to false, the function returns false if and only if every item in the sequence $input1 is deep-equal to an item at some position in the sequence $input2, and vice versa.

The rules for deciding whether two items are deep-equal appear below.

The entries that may appear in the $options map are as follows. The detailed rules for the interpretation of each option appear later.

record(
base-uri?	as xs:boolean,
collation?	as xs:string,
comments?	as xs:boolean,
debug?	as xs:boolean,
id-property?	as xs:boolean,
idrefs-property?	as xs:boolean,
in-scope-namespaces?	as xs:boolean,
items-equal?	as fn(item(), item()) as xs:boolean?,
map-order?	as xs:boolean,
namespace-prefixes?	as xs:boolean,
nilled-property?	as xs:boolean,
normalization-form?	as xs:string?,
ordered?	as xs:boolean,
processing-instructions?	as xs:boolean,
timezones?	as xs:boolean,
type-annotations?	as xs:boolean,
type-variety?	as xs:boolean,
typed-values?	as xs:boolean,
unordered-elements?	as xs:QName*,
whitespace?	as enum("preserve", "strip", "normalize")
)

Key	Meaning
base-uri?	Determines whether the base-uri of a node is significant. Type: xs:boolean Default: false()
collation?	Identifies a collation which is used at all levels of recursion when strings are compared (but not when names are compared), according to the rules in 5.3.7 Choosing a collation. If the argument is not supplied, or if it is empty, then the default collation from the dynamic context of the caller is used. Type: xs:string Default: fn:default-collation()
comments?	Determines whether comments are significant. Type: xs:boolean Default: false()
debug?	Requests diagnostics in the case where the function returns false. When this option is set and the two inputs are found to be not equal, the implementation should output messages (in an implementation-dependent format and to an implementation-dependent destination) indicating the nature of the differences that were found. Type: xs:boolean Default: false()
id-property?	Determines whether the id property of elements and attributes is significant. Type: xs:boolean Default: false()
idrefs-property?	Determines whether the idrefs property of elements and attributes is significant. Type: xs:boolean Default: false()
in-scope-namespaces?	Determines whether the in-scope namespaces of elements are significant. Type: xs:boolean Default: false()
items-equal?	A user-supplied function to test whether two items are considered equal. The function can return true or false to indicate that two items are or are not equal, overriding the normal rules that would apply to those items; or it can return an empty sequence, to indicate that the normal rules should be followed. Note that returning () is not equivalent to returning false. Type: fn(item(), item()) as xs:boolean? Default: fn:void#0
map-order?	Determines whether the order of entries in maps is significant. Type: xs:boolean Default: false()
namespace-prefixes?	Determines whether namespace prefixes in xs:QName values (particularly the names of elements and attributes) are significant. Type: xs:boolean Default: false()
nilled-property?	Determines whether the nilled property of elements and attributes is significant. Type: xs:boolean Default: false()
normalization-form?	If present, indicates that text and attributes are converted to the specified Unicode normalization form prior to comparison. The value is as for the corresponding argument of fn:normalize-unicode. Type: xs:string? Default: ()
ordered?	Controls whether the top-level order of the items of the input sequences is considered. Type: xs:boolean Default: true()
processing-instructions?	Determines whether processing instructions are significant. Type: xs:boolean Default: false()
timezones?	Determines whether timezones in date/time values are significant. Type: xs:boolean Default: false()
type-annotations?	Determines whether type annotations are significant. Type: xs:boolean Default: false()
type-variety?	Determines whether the variety of the type annotation of an element (whether it has complex content or simple content) is significant. Type: xs:boolean Default: true()
typed-values?	Determines whether nodes are compared using their typed values rather than their string values. Type: xs:boolean Default: true()
unordered-elements?	A list of QNames of elements considered to be unordered: that is, their child elements may appear in any order. Type: xs:QName* Default: ()
whitespace?	Determines the extent to which whitespace is treated as significant. The value preserve retains all whitespace. The value strip ignores text nodes consisting entirely of whitespace. The value normalize ignores whitespace text nodes in the same way as the strip option, and additionally compares text and attribute nodes after normalizing whitespace in accordance with the rules of the fn:normalize-space function. The detailed rules, given below, also take into account type annotations and xml:space attributes. Type: enum("preserve", "strip", "normalize") Default: preserve

Note:

As a general rule for boolean options (but not invariably), the value true indicates that the comparison is more strict.

In the following rules, where a recursive call on fn:deep-equal is made, this is assumed to use the same values of $options as the original call.

The rules reference a function equal-strings which compares two xs:string or xs:anyURI values as follows:

1. If the whitespace option is set to normalize, then each string is processed by calling the fn:normalize-space function.

2. If the normalization-form option is present, each string is then normalized by calling the fn:normalize-unicode function, supplying the specified normalization form.

3. The two strings are then compared for equality under the requested collation.

More formally, the equal-strings function is equivalent to the following implementation in XQuery:

declare function equal-strings(
  $string1  as xs:string,
  $string2  as xs:string, 
  $options  as map(*)
) as xs:boolean {
  let $n1 := if ($options?normalization-form)
             then normalize-unicode(?, $options?normalization-form) 
             else identity#1
  let $n2 := if ($options?whitespace = "normalize")
             then normalize-space#1 
             else identity#1               
  return compare($n1($n2($string1)), $n1($n2($string2)), $options?collation) eq 0    
}

The rules for deciding whether two items $i1 and $i2 are deep-equal are as follows.

Labels (see Section 3.3 Labeled Items^DM) are ignored. Specifically, if $i1 or $i2 is a labeled item then it is replaced by its subject.

The two items are next compared using the function supplied in the items-equal option. If this returns true then the items are deep-equal. If it returns false then the items are not deep-equal. If it returns an empty sequence (which is always the case if the option is not explicitly specified) then the two items are deep-equal if one or more of the following conditions are true:The two items are first compared using the function supplied in the items-equal option. If this returns true then the items are deep-equal. If it returns false then the items are not deep-equal. If it returns an empty sequence (which is always the case if the option is not explicitly specified) then the two items are deep-equal if one or more of the following conditions are true:The two items are nextfirst compared using the function supplied in the items-equal option. If this returns true then the items are deep-equal. If it returns false then the items are not deep-equal. If it returns an empty sequence (which is always the case if the option is not explicitly specified) then the two items are deep-equal if one or more of the following conditions are true:

1. All of the following conditions are true:

   1. $i1 is an atomic item.

   2. $i2 is an atomic item.

   3. Either the type-annotations option is false, or both atomic items have the same type annotation.

   4. One of the following conditions is true:

      1. If both $i1 and $i2 are instances of xs:string, xs:untypedAtomic, or xs:anyURI, equal-strings($i1, $i2, $collation, $options) returns true.

      2. If both $i1 and $i2 are instances of xs:date, xs:time or xs:dateTime, $i1 eq $i2 returns true.

      3. If both $i1 and $i2 are instances of xs:hexBinary or xs:base64Binary, $i1 eq $i2 returns true.

      4. Otherwise, fn:atomic-equal($i1, $i2) returns true.

      Note:

      If $i1 and $i2 are not comparable, that is, if the expression ($i1 eq $i2) would raise an error, then the function returns false; it does not report an error.

   5. One of the following conditions is true:

      1. Option namespace-prefixes is false.

      2. Neither $i1 nor $i2 is of type xs:QName or xs:NOTATION.

      3. $i1 and $i2 are qualified names with the same namespace prefix.

   6. One of the following conditions is true:

      1. Option timezones is false.

      2. Neither $i1 nor $i2 is of type xs:date, xs:time, xs:dateTime, xs:gYear, xs:gYearMonth, xs:gMonth, xs:gMonthDay, or xs:gDay.

      3. Neither $i1 nor $i2 has a timezone component.

      4. Both $i1 and $i2 have a timezone component and the timezone components are equal.

2. All of the following conditions are true:

   1. $i1 is a map.

   2. $i2 is a map.

   3. Both maps have the same number of entries.

   4. For every entry in the first map, there is an entry in the second map that:

      1. has the same key (note that the collation is not used when comparing keys), and

      2. has the same associated value (compared using the fn:deep-equal function, recursively).

   5. Either map-order is false, or the entries in both maps appear in the same order, that is, the Nth key in the first map is the same key as the Nth key in the second map, for all N.

3. All the following conditions are true:

   1. $i1 is an array.

   2. $i2 is an array.

   3. Both arrays have the same number of members (array:size($i1) eq array:size($i2)).

   4. Members in the same position of both arrays are deep-equal to each other: that is, every $p in 1 to array:size($i1) satisfies deep-equal($i1($p), $i2($p), $collation, $options).

4. All the following conditions are true:

   1. $i1 is a function item and is not a map or array.

   2. $i2 is a function item and is not a map or array.

   3. $i1 and $i2 have the same function identity. The concept of function identity is explained in Section 7.1 Function Items^DM.$i1 and $i2 have the same function identity. The concept of function identity is explained in Section 8.1 Function Items^DM.$i1 and $i2 have the same function identity. The concept of function identity is explained in Section 7.18.1 Function Items^DM.

5. All the following conditions are true:

   1. $i1 is a node.$i1 is a node (specifically, an XNode).$i1 is a node (specifically, an XNode).

   2. $i2 is a node.$i2 is a node (specifically, an XNode).$i2 is a node (specifically, an XNode).

   3. Both nodes have the same node kind.

   4. Either the base-uri option is false, or both nodes have the same value for their base URI property, or both nodes have an absent base URI.

   5. Let significant-children($parent) be the sequence of nodes obtained by applying the following steps to the children of $parent, in turn:

      1. Comment nodes are discarded if the option comments is false.

      2. Processing instruction nodes are discarded if the option processing-instructions is false.

      3. Adjacent text nodes are merged.

      4. Whitespace-only text nodes are discarded if both the following conditions are true:

         1. The option whitespace is set to strip or normalize; and

         2. The text node is not within the scope of an element that has the attribute xml:space="preserve".

         Note:

         Whitespace text nodes will already have been discarded if $parent is a schema-validated element node whose type annotation is a complex type with an element-only or empty content model.

   6. One of the following conditions is true.

      1. Both nodes are document nodes, and the sequence significant-children($i1) is deep-equal to the sequence significant-children($i2).

      2. Both nodes are element nodes, and all the following conditions are true:

         1. The two nodes have the same name, that is (node-name($i1) eq node-name($i2)).

         2. Either the option namespace-prefixes is false, or both element names have the same prefix.

         3. Either the option in-scope-namespaces is false, or both element nodes have the same in-scope namespace bindings.

         4. Either the option type-annotations is false, or both element nodes have the same type annotation.

         5. Either the option id-property is false, or both element nodes have the same value for their is-id property.

         6. Either the option idrefs-property is false, or both element nodes have the same value for their is-idrefs property.

         7. Either the option nilled-property is false, or both element nodes have the same value for their nilled property.

         8. One of the following conditions is true:

            1. The option type-variety is false.

            2. Both nodes are annotated as having simple content. For this purpose simple content means either a simple type or a complex type with simple content.

            3. Both nodes are annotated as having complex content. For this purpose complex content means a complex type whose variety is mixed, element-only, or empty.

            Note:

            It is a consequence of this rule that, by default, validating a document D against a schema will usually (but not necessarily) result in a document that is not deep-equal to D. The exception is when the schema allows all elements to have mixed content.

         9. The two nodes have the same number of attributes, and for every attribute $a1 in $i1/@* there exists an attribute $a2 in $i2/@* such that node-name($a1) eq node-name($a2) and $a1 and $a2 are deep-equal.

            Note:

            Attributes, like other items, may be compared using the supplied items-equal function. However, this function will not be called to compare two attribute nodes unless they have the same name.

         10. One of the following conditions holds:

             1. Both element nodes are annotated as having simple content (as defined above), the typed-values option is true, and the typed value of $i1 is deep-equal to the typed value of $i2.

                Note:

                The typed value of an element node is used only when the element has simple content, which means that no error can occur as a result of atomizing a node with no typed value.

             2. Both element nodes are annotated as having simple content (as defined above), the typed-values option is false, and the equal-strings function returns true when applied to the string value of $i1 and the string value of $i2.

             3. Both element nodes have a type annotation that is a complex type with element-only, mixed, or empty content, the (common) element name is not present in the unordered-elements option, and the sequence significant-children($i1) is deep-equal to the sequence significant-children($i2).

             4. Both element nodes have a type annotation that is a complex type with element-only, mixed, or empty content, the (common) element name is present in the unordered-elements option, and the sequence significant-children($i1) is deep-equal to some permutation of the sequence significant-children($i2).

                Note:

                Elements annotated as xs:untyped fall into this category.

                Including an element name in the unordered-elements list is unlikely to be useful except when the relevant elements have element-only content, but this is not a requirement: the rules apply equally to elements with mixed content, or even (trivially) to elements with empty content.

      3. Both nodes are attribute nodes, and all the following conditions are true:

         1. The two attribute nodes have the same name, that is (node-name($i1) eq node-name($i2)).

         2. Either the option namespace-prefixes is false, or both attribute names have the same prefix.

         3. Either the option type-annotations is false, or both attribute nodes have the same type annotation.

         4. Either the option id-property is false, or both attribute nodes have the same value for their is-id property.

         5. Either the option idrefs-property is false, or both attribute nodes have the same value for their is-idrefs property.

         6. Let T be true if the option typed-value is true and both attributes $i1 and $i2 have a type annotation other than xs:untypedAtomic.

            Then either T is true and the typed value of $i1 is deep-equal to the typed value of $i2, or T is false and the equal-strings function returns true when applied to the string value of $i1 and the string value of $i2.

      4. Both nodes are processing instruction nodes, and all the following conditions are true:

         1. The two nodes have the same name, that is (node-name($i1) eq node-name($i2)).

         2. The equal-strings function returns true when applied to the string value of $i1 and the string value of $i2.

      5. Both nodes are namespace nodes, and all the following conditions are true:

         1. The two nodes either have the same name or are both nameless, that is fn:deep-equal(node-name($i1), node-name($i2)).

         2. The string value of $i1 is equal to the string value of $i2 when compared using the Unicode codepoint collation.

         Note:

         Namespace nodes are not considered directly unless they appear in the top-level sequences passed explicitly to the fn:deep-equal function.

      6. Both nodes are comment nodes, and the equal-strings function returns true when applied to their string values.

      7. Both nodes are text nodes, and the equal-strings function returns true when applied to their string values.

6. All the following conditions are true:

   1. $i1 is a JNode.

   2. $i2 is a JNode.

   3. The ¶value property of $i1 is deep-equal to the ¶value property of $i2.

      Note:

      The other properties of the two JNodes, such as ¶parent and ¶selector, are ignored. As with XNodes, deep equality considers only the subtree rooted at the node, and not its position within a containing tree.

7. All the following conditions are true:

   1. $i1 is a JNode.

   2. $i2 is a JNode.

   3. The ¶value property of $i1 is deep-equal to the ¶value property of $i2.

      Note:

      The other properties of the two JNodes, such as ¶parent and ¶selector, are ignored. As with XNodes, deep equality considers only the subtree rooted at the node, and not its position within a containing tree.

In all other cases the result is false.

Error Conditions

A type error is raised [err:XPTY0004]^XP if the value of $options includes an entry whose key is defined in this specification, and whose value is not of the permitted type for that key.

A dynamic error is raised [err:FOJS0005] if the value of $options includes an entry whose key is defined in this specification, and whose value is not a permitted value for that key.

Notes

By default, whitespace in text nodes and attributes is considered significant. There are various ways whitespace differences can be ignored:

• If nodes have been schema-validated, setting the typed-values option to true causes the typed values rather than the string values to be compared. This will typically cause whitespace to be ignored except where the type of the value is xs:string.

• Setting the whitespace option to normalize causes all text and attribute nodes to have leading and trailing whitespace removed, and intermediate whitespace reduced to a single character.

By default, two nodes are not required to have the same type annotation, and they are not required to have the same in-scope namespaces. They may also differ in their parent, their base URI, and the values returned by the is-id and is-idrefs accessors (see Section 6.7.5 is-id Accessor^DM and Section 6.7.6 is-idrefs Accessor^DM). The order of children is significant, but the order of attributes is insignificant. By default, two nodes are not required to have the same type annotation, and they are not required to have the same in-scope namespaces. They may also differ in their parent, their base URI, and the values returned by the is-id and is-idrefs accessors (see Section 7.5.5 is-id Accessor^DM and Section 7.5.6 is-idrefs Accessor^DM). The order of children is significant, but the order of attributes is insignificant. By default, two nodes are not required to have the same type annotation, and they are not required to have the same in-scope namespaces. They may also differ in their parent, their base URI, and the values returned by the is-id and is-idrefs accessors (see Section 6.7.57.5.5 is-id Accessor^DM and Section 6.7.67.5.6 is-idrefs Accessor^DM). The order of children is significant, but the order of attributes is insignificant.

By default, the contents of comments and processing instructions are significant only if these nodes appear directly as items in the two sequences being compared. The content of a comment or processing instruction that appears as a descendant of an item in one of the sequences being compared does not affect the result. In previous versions of this specification, the presence of a comment or processing instruction, if it caused text to be split across two text nodes, might affect the result; this has been changed in 4.0 so that adjacent text nodes are merged after comments and processing instructions have been stripped.

Comparing items of different kind (for example, comparing an atomic item to a node, or a map to an array, or an integer to an xs:date) returns false, it does not return an error. So the result of fn:deep-equal(1, current-dateTime()) is false.

The items-equal callback function may be used to override the default rules for comparing individual items. For example, it might return true unconditionally when comparing two @timestamp attributes, if there is no expectation that the two trees will have identical timestamps. Given two nodes $n1 and $n2, it might compare them using the is operator, so that instead of comparing the descendants of the two nodes, the function simply checks whether they are the same node. Given two function items $f1 and $f2 it might return true unconditionally, knowing that there is no effective way to test if the functions are equivalent. Given two numeric values, it might return true if they are equal to six decimal places.

It is good practice for the items-equal callback function to be reflexive, symmetric, and transitive; if it is not, then the fn:deep-equal function itself will lack these qualities. Reflexive means that every item (including NaN) should be equal to itself; symmetric means that items-equal(A, B) should return the same result as items-equal(B, A), and transitive means that items-equal(A, B) and items-equal(B, C) should imply items-equal(A, C).

Setting the ordered option to false or supplying the unordered-elements option may result in poor performance when comparing long sequences, especially if the items-equal callback function is supplied.

Examples

Variables
let $at := <attendees> <name last="Parker" first="Peter"/> <name last="Barker" first="Bob"/> <name last="Parker" first="Peter"/> </attendees>

Expression:	deep-equal($at, $at/*)
Result:	false()
Expression:	deep-equal($at/name[1], $at/name[2])
Result:	false()
Expression:	deep-equal($at/name[1], $at/name[3])
Result:	true()
Expression:	deep-equal($at/name[1], 'Peter Parker')
Result:	false()
Expression:	deep-equal( $at//name[@first="Bob"], $at//name[@last="Barker"], options := { 'items-equal': op('is') } )
Result:	true() (Tests whether the two input sequences contain exactly the same nodes.)
Expression:	deep-equal([ 1, 2, 3], [ 1, 2, 3 ])
Result:	true()
Expression:	deep-equal((1, 2, 3), [ 1, 2, 3 ])
Result:	false()
Expression:	deep-equal( { 1: 'a', 2: 'b' }, { 2: 'b', 1: 'a' } )
Result:	true()
Expression:	deep-equal( (1, 2, 3, 4), (1, 4, 3, 2), options := { 'ordered': false() } )
Result:	true()
Expression:	deep-equal( (1, 1, 2, 3), (1, 2, 3, 3), options := { 'ordered': false() } )
Result:	false()
Expression:	deep-equal( parse-xml("<a xmlns='AA'/>"), parse-xml("<p:a xmlns:p='AA'/>") )
Result:	true() (By default, namespace prefixes are ignored).
Expression:	deep-equal( parse-xml("<a xmlns='AA'/>"), parse-xml("<p:a xmlns:p='AA'/>"), options := { 'namespace-prefixes': true() } )
Result:	false() (False because the namespace prefixes differ).
Expression:	deep-equal( parse-xml("<a xmlns='AA'/>"), parse-xml("<p:a xmlns:p='AA'/>"), options := { 'in-scope-namespaces': true() } )
Result:	false() (False because the in-scope namespace bindings differ).
Expression:	deep-equal( parse-xml("<a><b/><c/></a>"), parse-xml("<a><c/><b/></a>") )
Result:	false() (By default, order of elements is significant).
Expression:	deep-equal( parse-xml("<a><b/><c/></a>"), parse-xml("<a><c/><b/></a>"), options := { 'unordered-elements': #a) } )
Result:	true() (The unordered-elements option means that the ordering of the children of a is ignored.)
Expression:	deep-equal( parse-xml("<para style='bold'><span>x</span></para>"), parse-xml("<para style=' bold'> <span>x</span></para>") )
Result:	false() (By default, both the leading whitespace in the style attribute and the whitespace text node preceding the span element are significant.)
Expression:	deep-equal( parse-xml("<para style='bold'><span>x</span></para>"), parse-xml("<para style=' bold'> <span>x</span></para>"), options := { 'whitespace': 'normalize' } )
Result:	true() (The whitespace option causes both the leading space in the attribute value and the whitespace preceding the span element to be ignored.)
Expression:	deep-equal( (1, 2, 3), (1.0007, 1.9998, 3.0005), options := { 'items-equal': fn($x, $y) { if (($x, $y) instance of xs:numeric+) { abs($x - $y) lt 0.001 } } } )
Result:	true() (For numeric values, the callback function tests whether they are approximately equal. For any other items, it returns an empty sequence, so the normal comparison rules apply.)
Expression:	deep-equal( (1, 2, 3, 4, 5), (1, 2, 3, 8, 5), options := { 'items-equal': fn($x, $y) { trace((), `comparing { $x } and { $y }`) } } )
Result:	false() (The callback function traces which items are being compared, without changing the result of the comparison.)

14.5.1 fn:id

Summary

Returns the sequence of element nodes that have an ID value matching the value of one or more of the IDREF values supplied in $values.

Signature

fn:id(
$values	as xs:string*,
$node	as node()	:= .
) as element()*

Properties

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

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

Rules

The function returns a sequence, in document order with duplicates eliminated, containing every element node E that satisfies all the following conditions:

1. E is in the target document. The target document is the document containing $node, or the document containing the context value (.) if the second argument is omitted. The behavior of the function if $node is omitted is exactly the same as if the context value had been passed as $node.

2. E has an ID value equal to one of the candidate IDREF values, where:

   • An element has an ID value equal to V if either or both of the following conditions are true:

     • The is-id property (See Section 6.7.5 is-id Accessor^DM.) of the element node is true, and the typed value of the element node is equal to V under the rules of the eq operator using the Unicode codepoint collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).The is-id property (See Section 7.5.5 is-id Accessor^DM.) of the element node is true, and the typed value of the element node is equal to V under the rules of the eq operator using the Unicode codepoint collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).The is-id property (See Section 6.7.57.5.5 is-id Accessor^DM.) of the element node is true, and the typed value of the element node is equal to V under the rules of the eq operator using the Unicode codepoint collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

     • The element has an attribute node whose is-id property (See Section 6.7.5 is-id Accessor^DM.) is true and whose typed value is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).The element has an attribute node whose is-id property (See Section 7.5.5 is-id Accessor^DM.) is true and whose typed value is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).The element has an attribute node whose is-id property (See Section 6.7.57.5.5 is-id Accessor^DM.) is true and whose typed value is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

   • Each xs:string in $values is parsed as if it were of type IDREFS, that is, each xs:string in $values is treated as a whitespace-separated sequence of tokens, each acting as an IDREF. These tokens are then included in the list of candidate IDREFs. If any of the tokens is not a lexically valid IDREF (that is, if it is not lexically an xs:NCName), it is ignored. Formally, the candidate IDREF values are the strings in the sequence given by the expression:

     for $s in $values
     return tokenize(normalize-space($s), ' ')[. castable as xs:IDREF]

3. If several elements have the same ID value, then E is the one that is first in document order.

Error Conditions

A dynamic error is raised [err:FODC0001] if $node, or the context value if the second argument is absent, is a node in a tree whose root is not a document node.

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

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not a single node, type error [err:XPTY0004]^XP.

Notes

The effect of this function is anomalous in respect of element nodes with the is-id property. For legacy reasons, this function returns the element that has the is-id property, whereas it would be more appropriate to return its parent, that being the element that is uniquely identified by the ID. A new function fn:element-with-id has been introduced with the desired behavior.

If the data model is constructed from an Infoset, an attribute will have the is-id property if the corresponding attribute in the Infoset had an attribute type of ID: typically this means the attribute was declared as an ID in a DTD.

If the data model is constructed from a PSVI, an element or attribute will have the is-id property if its typed value is a single atomic item of type xs:ID or a type derived by restriction from xs:ID.

No error is raised in respect of a candidate IDREF value that does not match the ID of any element in the document. If no candidate IDREF value matches the ID value of any element, the function returns the empty sequence.

It is not necessary that the supplied argument should have type xs:IDREF or xs:IDREFS, or that it should be derived from a node with the is-idrefs property.

An element may have more than one ID value. This can occur with synthetic data models or with data models constructed from a PSVI where the element and one of its attributes are both typed as xs:ID.

If the source document is well-formed but not valid, it is possible for two or more elements to have the same ID value. In this situation, the function will select the first such element.

It is also possible in a well-formed but invalid document to have an element or attribute that has the is-id property but whose value does not conform to the lexical rules for the xs:ID type. Such a node will never be selected by this function.

Examples

Variables
let $emp := validate lax { document { <employee xml:id="ID21256" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <empnr xsi:type="xs:ID">E21256</empnr> <first>John</first> <last>Brown</last> </employee> } }

Expression	Result
$emp/id('ID21256')/name()	"employee" (The xml:id attribute has the is-id property, so the employee element is selected.)
$emp/id('E21256')/name()	"empnr" (Assuming the empnr element is given the type xs:ID as a result of schema validation, the element will have the is-id property and is therefore selected. Note the difference from the behavior of fn:element-with-id.)

14.5.2 fn:element-with-id

Summary

Returns the sequence of element nodes that have an ID value matching the value of one or more of the IDREF values supplied in $values.

Signature

fn:element-with-id(
$values	as xs:string*,
$node	as node()	:= .
) as element()*

Properties

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

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

Rules

Note:

The effect of this function is identical to fn:id in respect of elements that have an attribute with the is-id property. However, it behaves differently in respect of element nodes with the is-id property. Whereas the fn:id function, for legacy reasons, returns the element that has the is-id property, this function returns the element identified by the ID, which is the parent of the element having the is-id property.

The function returns a sequence, in document order with duplicates eliminated, containing every element node E that satisfies all the following conditions:

1. E is in the target document. The target document is the document containing $node, or the document containing the context value (.) if the second argument is omitted. The behavior of the function if $node is omitted is exactly the same as if the context value had been passed as $node.

2. E has an ID value equal to one of the candidate IDREF values, where:

   • An element has an ID value equal to V if either or both of the following conditions are true:

     • The element has an child element node whose is-id property (See Section 6.7.5 is-id Accessor^DM.) is true and whose typed value is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).The element has an child element node whose is-id property (See Section 7.5.5 is-id Accessor^DM.) is true and whose typed value is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).The element has an child element node whose is-id property (See Section 6.7.57.5.5 is-id Accessor^DM.) is true and whose typed value is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

     • The element has an attribute node whose is-id property (See Section 6.7.5 is-id Accessor^DM.) is true and whose typed value is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).The element has an attribute node whose is-id property (See Section 7.5.5 is-id Accessor^DM.) is true and whose typed value is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).The element has an attribute node whose is-id property (See Section 6.7.57.5.5 is-id Accessor^DM.) is true and whose typed value is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

   • Each xs:string in $values is parsed as if it were of type IDREFS, that is, each xs:string in $values is treated as a whitespace-separated sequence of tokens, each acting as an IDREF. These tokens are then included in the list of candidate IDREFs. If any of the tokens is not a lexically valid IDREF (that is, if it is not lexically an xs:NCName), it is ignored. Formally, the candidate IDREF values are the strings in the sequence given by the expression:

     for $s in $arg
     return tokenize(normalize-space($s), ' ')[. castable as xs:IDREF]

3. If several elements have the same ID value, then E is the one that is first in document order.

Error Conditions

A dynamic error is raised [err:FODC0001] if $node, or the context value if the second argument is omitted, is a node in a tree whose root is not a document node.

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

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not a single node, type error [err:XPTY0004]^XP.

Notes

This function is equivalent to the fn:id function except when dealing with ID-valued element nodes. Whereas the fn:id function selects the element containing the identifier, this function selects its parent.

If the data model is constructed from an Infoset, an attribute will have the is-id property if the corresponding attribute in the Infoset had an attribute type of ID: typically this means the attribute was declared as an ID in a DTD.

If the data model is constructed from a PSVI, an element or attribute will have the is-id property if its typed value is a single atomic item of type xs:ID or a type derived by restriction from xs:ID.

No error is raised in respect of a candidate IDREF value that does not match the ID of any element in the document. If no candidate IDREF value matches the ID value of any element, the function returns the empty sequence.

It is not necessary that the supplied argument should have type xs:IDREF or xs:IDREFS, or that it should be derived from a node with the is-idrefs property.

An element may have more than one ID value. This can occur with synthetic data models or with data models constructed from a PSVI where the element and one of its attributes are both typed as xs:ID.

If the source document is well-formed but not valid, it is possible for two or more elements to have the same ID value. In this situation, the function will select the first such element.

It is also possible in a well-formed but invalid document to have an element or attribute that has the is-id property but whose value does not conform to the lexical rules for the xs:ID type. Such a node will never be selected by this function.

Examples

Variables
let $emp := validate lax { document { <employee xml:id="ID21256" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <empnr xsi:type="xs:ID">E21256</empnr> <first>John</first> <last>Brown</last> </employee> } }

Expression:	$emp/element-with-id('ID21256')/name()
Result:	"employee" (The xml:id attribute has the is-id property, so the employee element is selected.)
Expression:	$emp/element-with-id('E21256')/name()
Result:	"employee" (Assuming the empnr element is given the type xs:ID as a result of schema validation, the element will have the is-id property and is therefore its parent is selected. Note the difference from the behavior of fn:id.)

14.5.3 fn:idref

Summary

Returns the sequence of element or attribute nodes with an IDREF value matching the value of one or more of the ID values supplied in $values.

Signature

fn:idref(
$values	as xs:string*,
$node	as node()	:= .
) as node()*

Properties

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

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

Rules

The function returns a sequence, in document order with duplicates eliminated, containing every element or attribute node $N that satisfies all the following conditions:

1. $N is in the target document. The target document is the document containing $node, or the document containing the context value (.) if the second argument is omitted. The behavior of the function if $node is omitted is exactly the same as if the context value had been passed as $node.

2. $N has an IDREF value equal to one of the candidate ID values, where:

   • A node $N has an IDREF value equal to V if both of the following conditions are true:

     • The is-idrefs property (see Section 6.7.6 is-idrefs Accessor^DM) of $N is true.The is-idrefs property (see Section 7.5.6 is-idrefs Accessor^DM) of $N is true.The is-idrefs property (see Section 6.7.67.5.6 is-idrefs Accessor^DM) of $N is true.

     • The sequence

       tokenize(normalize-space(string($N)), ' ')

       contains a string that is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

   • Each xs:string in $values is parsed as if it were of lexically of type xs:ID. These xs:strings are then included in the list of candidate xs:IDs. If any of the strings in $values is not a lexically valid xs:ID (that is, if it is not lexically an xs:NCName), it is ignored. More formally, the candidate ID values are the strings in the sequence:

     $values[. castable as xs:NCName]

Error Conditions

A dynamic error is raised [err:FODC0001] if $node, or the context value if the second argument is omitted, is a node in a tree whose root is not a document node.

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

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not a single node, type error [err:XPTY0004]^XP.

Notes

An element or attribute typically acquires the is-idrefs property by being validated against the schema type xs:IDREF or xs:IDREFS, or (for attributes only) by being described as of type IDREF or IDREFS in a DTD.

Because the function is sensitive to the way in which the data model is constructed, calls on this function are not always interoperable.

No error is raised in respect of a candidate ID value that does not match the IDREF value of any element or attribute in the document. If no candidate ID value matches the IDREF value of any element or attribute, the function returns the empty sequence.

It is possible for two or more nodes to have an IDREF value that matches a given candidate ID value. In this situation, the function will return all such nodes. However, each matching node will be returned at most once, regardless how many candidate ID values it matches.

It is possible in a well-formed but invalid document to have a node whose is-idrefs property is true but that does not conform to the lexical rules for the xs:IDREF type. The effect of the above rules is that ill-formed candidate ID values and ill-formed IDREF values are ignored.

If the data model is constructed from a PSVI, the typed value of a node that has the is-idrefs property will contain at least one atomic item of type xs:IDREF (or a type derived by restriction from xs:IDREF). It may also contain atomic items of other types. These atomic items are treated as candidate ID values if two conditions are met: their lexical form must be valid as an xs:NCName, and there must be at least one instance of xs:IDREF in the typed value of the node. If these conditions are not satisfied, such values are ignored.

Examples

Variables

let $emp := validate lax { document { <employees xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <employee xml:id="ID21256"> <empnr xsi:type="xs:ID">E21256</empnr> <first>Anil</first> <last>Singh</last> <deputy xsi:type="xs:IDREF">E30561</deputy> </employee> <employee xml:id="ID30561"> <empnr xsi:type="xs:ID">E30561</empnr> <first>John</first> <last>Brown</last> <manager xsi:type="xs:IDREF">ID21256</manager> </employee> </employees> } }

Expression:	$emp/( element-with-id('ID21256')/@xml:id => idref() )/ancestor::employee/last => string()
Result:	"Brown" (Assuming that manager has the is-idref property, the call on fn:idref selects the manager element. If, instead, the manager had a ref attribute with the is-idref property, the call on fn:idref would select the attribute node.)
Expression:	$emp/( element-with-id('E30561')/empnr => idref() )/ancestor::employee/last => string()
Result:	"Singh" (Assuming that employee/deputy has the is-idref property, the call on fn:idref selects the deputy element.)

14.5.4 fn:generate-id

Summary

This function returns a string that uniquely identifies a given nodeGNode.

Signature

fn:generate-id(
$node	as node()?as GNode()?as nodeGNode()?	:= .
) as xs:string

Properties

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.

Rules

If the argument is omitted, it defaults to the context value (.).

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.

Error Conditions

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

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not an instance of the sequence type node()?, type error [err:XPTY0004]^XP.If the context value is not an instance of the sequence type GNode()?, type error [err:XPTY0004]^XP.If the context value is not an instance of the sequence type nodeGNode()?, type error [err:XPTY0004]^XP.

Notes

An implementation is free to generate an identifier in any convenient way provided that it always generates the same identifier for the same nodeGNode and that different identifiers are always generated from different nodesGNodes. 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].There is no inverse to this function; it is not directly possible to find the GNode with a given generated ID. Of course, it is possible to search a given sequence of GNodes using an expression such as $nodes[generate-id()=$id].There is no inverse to this function; it is not directly possible to find the nodeGNode with a given generated ID. Of course, it is possible to search a given sequence of nodesGNodes 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.

Examples

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="{ generate-id($sect) }"/>

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

see <a href="#{ 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 items, 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 exists($N intersect $S) may be expensive; there may then be performance benefits in creating a map:

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

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

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

15.1.4 XSD validation

This section describes a process called XSD validation, which validates a supplied node against a supplied XSD schema. The validation process refers to the process defined in [XML Schema Part 1: Structures Second Edition] or [XSD 1.1 Part 1].

The validation process takes the following inputs:

• A schema to be used for validation, called the effective schema.

• A boolean indicating whether any xsi:schemaLocation or xsi:noNamespaceSchemaLocation attributes are to be taken into consideration.

• A document, element, or attribute node to be validated; this is called the operand node.

• A validation mode, which is one of strictlax, or by-type.

  Note:

  XSLT also allows the value strip, but this does not invoke validation (instead, it invokes stripping of existing type annotations, and re-annotation of nodes as xs:untyped.)

• If the validation mode is by-type, then a schema type to be used for validating the operand node. This may be any simple or complex type present in the effective schema: it must not be xs:untyped or xs:untypedAtomic.

  Note:

  An XQuery ValidateExpr allows the type to be specified as xs:untyped or xs:untypedAtomic, but this does not invoke validation (instead, it invokes stripping of existing type annotations and re-annotation of nodes as untyped.)

The output of the validation process comprises one or more of the following:

• A boolean indicating whether the operand node was found to be valid.

• If the operand node was found to be valid, a deep copy of the operand node augmented with type annotations corresponding to the types against which they were validated, the copies may also include expanded values for element and attribute defaults defined in the schema.

  This creates a new node with its own identity and with no parent.

  The base URI property of every node in the resulting XDM tree is the same as the base URI property of the corresponding node in the input tree.

• If the operand node was not found to be valid, then optionally, a set of error diagnostics in implementation-defined format.

The operand node must be one of:

• An element node

• An attribute node

• A well-formed document node, that is, a document node having among its children exactly one element node and zero or more comment and processing instruction nodes.

The term validation root is used to refer to the operand node if it is an element or attribute node, or to the single element child of the operand node when the operand node is a document node.

Note that a schema is defined as a collection of schema components (for example, element and attribute declarations, complex and simple type definitions). In some cases the schema that is used is the set of schema components found in the in-scope schema definitions^XP, but this is not the only possibility.

The result of the validation process is defined by the following rules.

1. The invoking application determines whether the validity assessment process takes account of any xsi:schemaLocation or xsi:noNamespaceSchemaLocation attributes in the tree being validated. If it does so, then it should adhere to the following rules:

   1. Any schema loaded using these attributes must be compatible^DM with the existing effective schema.

   2. Any schema loaded using these attributes must not override or redefine any schema components in the effective schema.

   3. Any schema components loaded using this mechanism must be used for this validity assessment only, and must not affect the outcome of any subsequent validity assessments of other documents.

      Note:

      A processor may choose to cache such schema components but the existence of such a cache should only affect performance, not the validation outcome.

   A consequence of validating a document using schema components that are not in the static context is that nodes may be annotated with types that are not in the static context. But the rules for schema compatibility^DM mean that this is not a problem.

2. If the instance being validated contains any xml:id attributes, such attributes are validated against the type xs:ID, making the containing element eligible as a target for the id function. Uniqueness checking of elements and attributes typed as xs:ID, however, is carried out only if the operand node is a document node.

3. If the operand node is a document node:

   1. The children of the document node must consist of exactly one element node and zero or more comment and processing instruction nodes, in any order.

   2. The element node child is validated, as described below.

   3. The validation rule “Validation Root Valid (ID/IDREF)” is applied to the single element node child of the document node. This means that validation will fail if there are non-unique ID values or dangling IDREF values in the document tree.

      Note:

      This rule is not applied when the operand node is an element or attribute node.

   4. There is no check that the tree contains unparsed entities whose names match the values of nodes of type xs:ENTITY or xs:ENTITIES. This is because it is not possible (either in XSLT or XQuery) to construct a tree containing unparsed entities. It is possible to add unparsed entity declarations to the result document by referencing a suitable DOCTYPE during serialization.

   5. All other children of the document node (comments and processing instructions) are copied unchanged, and the results become the children of a new document node, which is returned as the validation result.

4. If the operand node is an element node, then:

   1. For specification purposes, because the XSD specifications require the input document to be expressed as an XML Information Set ([XML Infoset]), the operand node is first converted to an Infoset according to the “Infoset Mapping” rules defined in [XQuery and XPath Data Model (XDM) 4.0]. Note that this process discards any existing type annotations.

      Validity assessment is carried out on the root element information item of the resulting Infoset, using the supplied schema. The process of validation applies recursively to contained elements and attributes to the extent required by the supplied schema.

      Note:

      A practical implementation is unlikely to perform any physical conversion, but the process is defined this way in order to align with the XSD specification.

   2. If the validation mode is by-type, then Schema-validity assessment is carried out according to the rules defined in [XML Schema Part 1: Structures Second Edition] or [XSD 1.1 Part 1] Part 1, section 3.3.4 "Element Declaration Validation Rules", “Validation Rule: Schema-Validity Assessment (Element)”, clauses 1.2 and 2, using this type definition as the “processor-stipulated type definition” for validation.

   3. If validation mode is strict, then strict validation is carried out as described in [XML Schema Part 1: Structures Second Edition] Part 1, section 5.2, “Assessing Schema-Validity”, item 2, or its counterpart in XSD 1.1. This means that the root element information item in the Infoset must either:

      1. have a name that matches a top-level element declaration in the effective schema, or

      2. have an xsi:type attribute whose value matches the name of a top-level type definition in the effective schema

      If there is no such element declaration or type definition, the element is assessed as invalid.

   4. If validation mode is lax, then schema-validity assessment is carried out in accordance with [XML Schema Part 1: Structures Second Edition] Part 1, section 5.2, “Assessing Schema-Validity”, item 3, or its counterpart in XSD 1.1.

      If validation mode is lax and the root element information item has neither a top-level element declaration nor an xsi:type attribute, XSD 1.0 and XSD 1.1 define the recursive checking of children and attributes as optional. This specification prescribes that this recursive checking is required.

      Note:

      This means, for example, that when an instance document is structured as having an envelope in one namespace wrapping a payload in a different namespaces, and when schema definitions are available for the payload but not for the envelope, lax validation of the envelope may trigger validation of the payload.

   5. If the operand node is an element node, the validation rules named “Validation Root Valid (ID/IDREF)” are not applied. This means that document-level constraints relating to uniqueness and referential integrity are not enforced.

   6. There is no check that the document contains unparsed entities whose names match the values of nodes of type xs:ENTITY or xs:ENTITIES.

5. If the operand node is an attribute node, in particular when it is a parentless attribute node, then validation cannot be defined directly in terms of the XSD-defined validation process. Instead, conceptually, a copy of the attribute is first added to an element node that is created for the purpose, and namespace fixup is performed on this element node to ensure that it has an in-scope namespace binding for the prefix and namespace of the attribute name. The name of this element is of no consequence, but it must be the same as the name of a synthesized element declaration of the form:

   <xs:element name="E">
     <xs:complexType>
       <xs:sequence/>
       <xs:attribute ref="A"/>
     </xs:complexType>
   </xs:element>

   where A is the name of the attribute being validated.

   This synthetic element is then validated using the procedure given above for validating elements, and if it is found to be valid, a copy of the validated attribute is made, retaining its type annotation, but detaching it from the containing element (and thus, from any in-scope namespace bindings).

   The XDM data model does not permit an attribute node with no parent to have a typed value that includes a namespace-qualified name, that is, a value whose type is derived from xs:QName or xs:NOTATION. This restriction is imposed because these types rely on the in-scope namespaces of a containing element to resolve namespace prefixes. Therefore, a parentless attribute is considered to be invalid against such a type.

6. The outcome of the validation expression depends on the validity property of the root element information item in the PSVI that results from the XSD validation process.

   1. If the validity property of the root element information item is valid, or if validation mode is lax and the validity property of the root element information item is notKnown, the PSVI is converted back into a data model instance as described in [XQuery and XPath Data Model (XDM) 4.0] Section 3.3, “Construction from a PSVI”. The resulting node (a new node of the same kind as the operand node) is returned as the result of the validate expression.

      Otherwise, the operand node is deemed invalid.

15.2.1 XDM Mapping from HTML DOM Nodes

The fn:parse-html function conceptually works in two phases:

1. The lexical HTML (supplied as a string) is parsed into an HTML DOM as defined by the HTML5 specification: see [HTML: Living Standard] and [DOM: Living Standard].

2. The resulting DOM is converted to an XDM tree as described in this section. This is described by defining the actions of the accessor functions defined in Section 6.7 Accessors^DM.The resulting DOM is converted to an XDM tree as described in this section. This is described by defining the actions of the accessor functions defined in Section 7.5 Accessors^DM.The resulting DOM is converted to an XDM tree as described in this section. This is described by defining the actions of the accessor functions defined in Section 6.77.5 Accessors^DM.

The [DOM: Living Standard] defines parsing algorithms for two different formats, which it refers to as the HTML and XML serializations (or concrete syntaxes). The XML serialization is an XML document which typically uses the namespace http://www.w3.org/1999/xhtml and the content type application/xhtml+xml, and is popularly referred to as XHTML. The HTML parsing algorithm constructs an HTML DOM HTMLDocument document object for the HTML document. The XHTML parsing algorithm constructs an HTML DOM XMLDocument object for the HTML document, following XML parsing rules. This mapping supports both of these document types.

The [DOM: Living Standard] specification defines HTML DOM nodes that are mapped to XDM nodes as follows:

1. The HTML DOM Document interface maps to Section 6.6.1 Document nodes^DM.The HTML DOM Document interface maps to Section 7.4.1 Document nodes^DM.The HTML DOM Document interface maps to Section 6.6.17.4.1 Document nodes^DM.

2. The HTML DOM Element interface maps to Section 6.6.2 Element nodes^DM.The HTML DOM Element interface maps to Section 7.4.2 Element nodes^DM.The HTML DOM Element interface maps to Section 6.6.27.4.2 Element nodes^DM.

3. The HTML DOM Attr interface maps to Section 6.6.3 Attribute nodes^DM.The HTML DOM Attr interface maps to Section 7.4.3 Attribute nodes^DM.The HTML DOM Attr interface maps to Section 6.6.37.4.3 Attribute nodes^DM.

   Note:

   Any HTML DOM Attr instances in an HTML DOM HTMLDocument that represent namespace declarations will have been filtered out: see 15.2.1.1 attributes Accessor.

4. The HTML DOM ProcessingInstruction interface maps to Section 6.6.5 Processing instruction nodes^DM.The HTML DOM ProcessingInstruction interface maps to Section 7.4.5 Processing instruction nodes^DM.The HTML DOM ProcessingInstruction interface maps to Section 6.6.57.4.5 Processing instruction nodes^DM.

   Note:

   The HTML parsing algorithm does not generate processing instruction nodes. If encountered they are parsed as comment nodes. The HTML DOM ProcessingInstruction interface is relevant only when the XHTML parsing algorithm is used.

5. The HTML DOM Comment interface maps to Section 6.6.6 Comment nodes^DM.The HTML DOM Comment interface maps to Section 7.4.6 Comment nodes^DM.The HTML DOM Comment interface maps to Section 6.6.67.4.6 Comment nodes^DM.

6. The HTML DOM Text interface maps to Section 6.6.7 Text nodes^DM. Adjacent HTML DOM Text nodes are combined into a single Section 6.6.7 Text nodes^DM.The HTML DOM Text interface maps to Section 7.4.7 Text nodes^DM. Adjacent HTML DOM Text nodes are combined into a single Section 7.4.7 Text nodes^DM.The HTML DOM Text interface maps to Section 6.6.77.4.7 Text nodes^DM. Adjacent HTML DOM Text nodes are combined into a single Section 6.6.77.4.7 Text nodes^DM.

   Note:

   The HTML DOM CDATASection interface is an instance of HTML DOM Text, so CDATA sections also map to Section 6.6.7 Text nodes^DM.The HTML DOM CDATASection interface is an instance of HTML DOM Text, so CDATA sections also map to Section 7.4.7 Text nodes^DM.The HTML DOM CDATASection interface is an instance of HTML DOM Text, so CDATA sections also map to Section 6.6.77.4.7 Text nodes^DM.

   The use of CDATA sections can result in the HTML DOM containing adjacent text nodes, which the mapping to XDM will merge into a single node.

15.3.8 fn:pin

Summary

Adapts a map or array so that retrieval operations retain additional information.

Signature

fn:pin(
$input	as (map(*)|array(*))
) as (map(*)|array(*))

Properties

This function is nondeterministic, context-independent, and focus-independent.

Rules

The function creates a deep copy of the supplied map or array, adapted so that navigation within the deep copy returns items that are labeled with additional information about their position within the containing tree structure.

Note:

The formal specification of the function describes it as constructing a deep copy of the entire tree, but a practical implementation is likely to use a lazy evaluation strategy, so the only costs incurred are for items actually selected within the tree.

The function makes use of the concept of labeled items, an extension to the data model described in Section 3.3 Labeled Items^DM.

The supplied value of $input must be either a map or an array.

The result is as follows:

1. If $input is a map M, the result is a map M′ derived from M as follows:

   1. Any existing label on M is discarded.

   2. M′ acquires a label having the property pinned set to the value true, and the property id set to an arbitrary xs:string value that is unique within the execution scope.

   3. For every key-value pair (K, V) in M, M′ will have a key-value pair (K, V′) in which the key K is unchanged, and the value V′ is derived from V by applying the function derived-value(M', K, V), defined below.

   4. The entry order^DM of M is retained in M′.

2. If $input is an array A, the result is an array A′ derived from A as follows:

   1. Any existing label on A is discarded.

   2. A′ acquires a label having the property pinned set to the value true, and the property id set to an arbitrary xs:string value that is unique within the execution scope.

   3. For every member V in A, whose 1-based index position in A is X, A′ will have a member V′ derived from V by applying the function derived-value(A', X, V), defined below.

3. The id property described in the previous paragraphs is allocated only to the top-level map or array (the one supplied as an explicit argument to the fn:pin function). The function is notdeterministic: that is, if the function is called twice with the same arguments, it is implementation-dependent whether the same id property is allocated on both occasions.

4. If $input is anything other than a map or an array, a type error is raised.

5. The function derived-value(P, K, V) has the following logic. For every item J in V, V′ will contain an item J′ that is derived from J as follows:

   1. Let TEMP be:

      1. If J is a map or array, then fn:pin(J).

         Note:

         Note however that the id property of TEMP is not used, so there is no need to generate it.

      2. Otherwise, J.

   2. J′ is then a labeled item having the same subject as TEMP, together with a label having the following properties:

      pinned

      true

      key

      K

      position

      The 1-based position of J within V.

      parent

      P

      ancestors

      A zero-arity function item delivering the value of (?parent, ?parent ! label(.)?ancestors()).

      path

      A zero-arity function item delivering the value of (?parent ! label(.)?path(), ?key).

Notes

The effect of calling pin on a map or array is that subsequent retrieval operations within the pinned map or array return labeled results, whose labels contain useful information about where the results were found. For example, an expression such as json-doc($source)??name will return the values of all entries in the JSON tree having the key "name"; but very little can be done with this information because the result is simply a sequence of (typically) strings with no context. By contrast, the result of pin(json-doc($source))??name is the same set of strings, labeled with information about where they were found. For example, if $result is the result of the expression pin(json-doc($source))??name, then:

• $result => label()?parent?ssn locates the map that contained each name, and returns the value of the ssn entry in that map.

• $result => label()?ancestors()?course returns the values of any course entries in containing maps.

• $result => label()?path() returns a sequence of map keys and array index values representing the location of the found entries within the JSON structure.

Editorial note
The id property on the root of a pinned map or array is intended to support deep update operations, which have not yet been defined.

Examples

Expression:	pin([ "a", "b", "c" ])?1 ! label(.)?parent ! array:foot(.)
Result:	"c"
Expression:	pin([ "a", "b", "c", "d" ]) ! array:remove(., 2)?* ! label(.)?key
Result:	1, 3, 4
Expression:	let $data := { "fr": { "capital": "Paris", "languages": [ "French" ] }, "de": { "capital": "Berlin", "languages": [ "German" ] } } return pin($data)??languages[. = 'German'] ! label(.)?path()[1]
Result:	"de"

15.3.9 fn:label

Summary

Returns the label associated with a labeled item, as a map.

Signature

fn:label(
$input	as item()?
) as map(xs:string, item()*)?

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

If $input is an empty sequence, the function returns an empty sequence.

If $input is an item that has no label, the function returns an empty map.

If $input is a labeled item, the function returns the label, as a map.

Notes

The function makes use of the concept of labeled items, an extension to the data model described in Section 3.3 Labeled Items^DM.

The data model allows any item to be labeled, and allows the label to be any map with string-valued keys. Currently the only operation that creates labeled values is the fn:pin function. For examples illustrating the use of fn:label, see fn:pin.