<PurchaseOrder> <line-item> <description>Large widget</description> <price>8.95</price> <quantity>5.0</quantity> </line-item> <line-item> <description>Small widget</description> <price>3.99</price> <quantity>2.0</quantity> </line-item> <line-item> <description>Tiny widget</description> <price>1.49</price>a <quantity>805</quantity> </line-item> </PurchaseOrder>

This record type represents the components of a URI.

The original URI. This element is returned by fn:parse-uri, but ignored by fn:build-uri.

The URI scheme (e.g., “https” or “file”).

The URI is an absolute URI.

Whether the URI is hierarchical or not.

The authority portion of the URI (e.g., “example.com:8080”).

Any userinfo that was passed as part of the authority.

The host passed as part of the authority (e.g., “example.com”).

The port passed as part of the authority (e.g., “8080”).

The path portion of the URI.

Any query string.

Any fragment identifier.

Parsed and unescaped path segments.

Parsed and unescaped query key-value pairs.

The path of the URI, treated as a filepath.

This record type represents a plan for converting elements to maps during evaluation of fn:element-to-map.

Defines the overall strategy for converting the element content.

For list layouts, defines the name of the child element type contained in the list.

For elements with simple content, defines whether they should be represented as numbers or booleans instead of the default representation as strings. The field is empty unless the layout is simple or simple-plus.

This record type represents a plan for converting attributes to atomic items during evaluation of fn:element-to-map.

Defines whether attributes should be represented as numbers or booleans instead of the default representation as strings; alternatively, indicates that the attribute should be omitted.

This record type represents location information identifying the position within source XML text of the lexical representation of a particular node.

Defines the URI of the document or external entity in which the lexical representation of a node is found.

Defines the public identifier of the document or external entity in which the lexical representation of a node is found.

Defines the line number within the containing document or external entity at which the lexical representation of a node is found. If the lexical representation spans several lines then it is implementation-defined which of the relevant line numbers is returned. The first line of a resource is numbered 1 (one)..

Defines the column number within the containing document or external entity at which the lexical representation of a node is found. Within the range of columns occupied by the lexical representation of a node, it is implementation-defined which of the relevant column numbers is returned. The first column of a line is numbered 1 (one).

This record type represents the properties of a simple or complex type in a schema.

The name of the type. Empty in the case of an anonymous type. Corresponds to {name} and {target namespace} in the XSD component model for simple and complex type components.

True for a simple type, false for a complex type.

Function item returning the base type (the type from which this type is derived by restriction or extension). The function is always present, and returns the empty sequence in the case of the type xs:anyType. Corresponds to the {base type definition} property in the XSD component model.

For an atomic type, a function item returning the primitive type from which this type is ultimately derived. Corresponds to the {primitive type definition} in the XSD component model for simple types. Absent if the type is non atomic, or if it is the simple type xs:anyAtomicType. If this is a primitive type, the function item is idempotent.

For a simple type, one of "atomic", "list", or "union", corresponding to the {variety} of the simple type in the XSD component model. For a complex type, one of "empty", "simple", "element-only", or "mixed", corresponding to the {content type}.{variety} of the complex type in the XSD component model. The value is absent in cases where the {variety} in the XSD component model is absent, for example for the type xs:anySimpleType.

For a simple type with variety "union", a function that returns a sequence of records representing the member types of the union, in order, corresponding to the {member type definitions} property in the XSD component model. For a simple type with variety "list", a function that returns a record representing the item type of the list type, corresponding to the {item type definition} property in the XSD component model. In all other cases, absent.

For a complex type with variety "simple" (that is, a complex type with simple content), a function that returns a record representing the relevant simple type, corresponding to the {content type}.{simple type definition} property in the XSD complex type component. In all other cases, absent.

For a , a function item that can be called to establish whether the supplied atomic item is an instance of this type. In all other cases, absent.

For a simple type, a function item that can be used to construct instances of this type. In the case of a named type that is present in the dynamic context, the result is the same function as returned by fn:function-lookup applied to the type name (with arity one). For details see and . Constructor function items are also available for anonymous types, and for types that might not be present in the dynamic context. The field is absent for complex types and for the abstract types xs:anyAtomicType, xs:anySimpleType, and xs:NOTATION. It is also absent for all types.

This record type represents the results of processing a regular expression, together with a set of flags, It contains function items that can be used to evaluate the regular expression in various ways.

The supplied regular expression, as a string.

The supplied flags, as a string; or the zero-length string if no flags were supplied.

An arity-one function that can be used to test whether the supplied string $s matches the regular expression. If R is a compiled-regex-record produced by the function fn:regex, then the effect of the expression R?matches($s) is defined to be the same as the result of fn:matches($s, R?pattern, R?flags).

An arity-one function that can be used to split the supplied string $s on separators that match the regular expression. If R is a compiled-regex-record produced by the function fn:regex, then the effect of the expression R?tokenize($s) is defined to be the same as the result of fn:tokenize($s, R?pattern, R?flags).

An arity-two function that can be used to replace parts of the supplied string $s that match the regular expression. If R is a compiled-regex-record produced by the function fn:regex, then the effect of the expression R?replace($s, $r) is defined to be the same as the result of fn:replace($s, R?pattern, $r, R?flags).

An arity-one function that can be used to process a string against the regular expression and return all the matching and non-matching substrings, plus matching groups, in an XML structure. If R is a compiled-regex-record produced by the function fn:regex, then the effect of the expression R?analyze-string($s) is defined to be the same as the result of fn:analyze-string($s, R?pattern, R?flags).

An arity-one function that can be used to process a string against the regular expression and return details of all the matching substrings, together with their captured groups. If R is a compiled-regex-record produced by the function fn:regex, then the effect of the expression R?matching-segments($s) is defined to be the same as the result of fn:matching-segments($s, R?pattern, R?flags).

This record type represents a of an input string that matched a regular expression, together with any captured groups found during the matching process.

The substring of the original input that matched the regular expression. May be zero-length.

The 1-based position of the matching segment within the original input string.

The captured groups for this matching segment. This is represented as a map whose keys identify the captured groups and whose values give details of each captured group, in the form of a captured group record: see .

Note that where groups are captured within a lookahead, the captured group is not necessarily a substring of the matching segment.

The key for a group that is a named capturing group is its name, supplied as an xs:string. The key for any other captured group is its group number (corresponding to the position of the left parenthesis introducing the capturing subexpression among all capturing subexpressions of the regular expression), supplied as an xs:integer.

The entry order of the map follows the order of the capturing subexpressions in the regular expression, whether an entry is keyed by group number or by group name.

Because a named capturing group is keyed by its name rather than by its number, the integer keys of the map do not necessarily form a contiguous sequence: an integer N may be absent even though the regular expression contains an Nth capturing subexpression. A numbered key is also absent if the corresponding group did not participate in the match (for example, a group within an alternative branch that was not taken).

This record type represents a captured group appearing in the result of a regular expression match.

The string value of the captured group.

The one-based position of the captured group within the original input string.

The numeric identifier of the captured group, based on counting left parentheses within the regular expression.

The name of the captured group, present if the group was given a name using the syntax (?<name>…) within the regular expression.

This record type is used to hold the result of the fn:load-xquery-module function.

 global variable declared in the library module. The key of the

This map (V ) contains one entry for each public entry is the name of the variable, as an xs:QName value; the associated value is the value of the variable.

This map (F ) contains one entry for each distinct QName Q that represents the name of a public and non-external function declared in the library module. The key of the entry is Q, as an xs:QName value; the associated value is a map A. This map (A) contains one entry for each arity N within the arity range of any of the function declarations with the given name; its key is N, as an xs:integer value, and its associated value is a function item obtained as if by evaluating a named function reference Q#N, using the static and dynamic context of the call on fn:load-xquery-module. The function item can be invoked using the rules for dynamic function invocation.

This record type is used to represent the components of a value of type xs:dateTime, xs:date, xs:time, xs:gYear, xs:gYearMonth, xs:gMonth, xs:gMonthDay, or xs:gDay.

The value of the year component. Range is implementation-defined. If years less than one are supported, then the integer zero represents the year before year one, and the integer -1 represents the year before year zero.

The value of the month component. A valid value is in the range 1 to 12 inclusive.

The value of the day component. A valid value is in the range 1 to 31 inclusive.

The value of the hours component. A valid value is in the range 0 to 23 inclusive.

The value of the minutes component. A valid value is in the range 0 to 59 inclusive.

The value of the seconds component. A valid value is in the range 0 (inclusive) to 60 (exclusive). (Thus 59.9999999 is valid, but 60 is not.)

The timezone offset, if the value has a timezone. A valid value corresponds to an integral number of minutes between -840 and +840 inclusive.

This record type is used to hold the result of the fn:parse-csv function.

This entry holds a sequence of strings containing column names. The content depends on the setting of the header entry in $options:

With "header":false() (which is the default), the value of this entry is the empty sequence.

With "header":true(), the value is a sequence of strings taken from the first row of the data. The strings have leading and trailing whitespace trimmed, regardless of the value of the trim-whitespace option and of whether the field is quoted. The sequence of strings will potentially be truncated and reordered if the select-columns option is specified. Any strings that are zero-length or duplicated are retained as-is.

If the value of the header option is a sequence of strings, then the value is taken from the supplied sequence.

The order of names is not adjusted based on the select-columns option; the supplied list of names is expected to refer to columns in the result, not to columns in the input.

This entry holds a map from column names (as strings) to column positions (as 1-based positive integers). The content depends on the setting of the header entry in $options:

With "header":false() (which is the default), the value of this entry is the empty map.

With "header":true(), the map contains entries based on the contents of the first row of the data. The strings have leading and trailing whitespace trimmed, regardless of the value of the trim-whitespace option and of whether the field is quoted. Any string appearing in the header row that is non-zero-length and is not equal (using codepoint collation) to any previous string appearing in the header results in an entry pairing that string to its 1-based position in the header row.

If the select-columns option is present then the entries are adjusted (or removed) to reflect their position in the adjusted data rows.

If the value of the header option is a sequence of strings, then the map contains entries based on the supplied value. Any string appearing in the option value that is non-zero-length and is not equal (using codepoint collation) to any previous string results in an entry pairing that string to its 1-based position in the sequence.

The allocation of column numbers is not adjusted based on the select-columns option; the supplied list of names is expected to refer to columns in the result, not to columns in the input.

This entry is a sequence of arrays of strings, holding the parsed rows of the CSV data. The format is the same as the result of the fn:csv-to-arrays function, except that the first row is omitted in the case where the header option is true. If there are no data rows in the CSV, the value will be the empty sequence.

A function providing ready access to a given field in a given row. The get function has signature:

fn($r as xs:positiveInteger, $c as (xs:positiveInteger | xs:string)) as xs:string

The function takes two arguments: $r, an integer giving the row number (1-based), and $c, which identifies a column either by its name or by its 1-based position.

Except in error cases (described below), the function call $csv?get($r, $c), where $c is an integer, returns the value of $csv?rows[$r] => array:get($c, ""), and the function call $csv?get($r, $c), where $c is a string, returns the value of $csv?get($r, $csv?column-index($c)).

The properties of the function are as follows:

Absent

(xs:positiveInteger, (xs:positiveInteger | xs:string)) => xs:string

None

As described in the specification above

A dynamic error occurs if the supplied $c is a string and does not occur in the map of column names.

The function returns a field in the result.

The first argument $r selects a row within the sequence of rows returned as rows by position (one-based). If the value is out of range for the number of rows returned, the get function returns a zero-length string.

The second argument $c may be either an integer or a string.

If $c is an integer then it selects a field within the selected row by position (one-based). If the value is out of range for the number of fields in the selected row, the get function returns a zero-length string.

If $c is a string, the string is mapped to an integer using the map in the returned column-index. If the string is not present in this map, then an error is raised . The resulting integer is then used as if it were supplied as $c directly.

This record type is used to represent the result of a call on the fn:random-number-generator function.

An xs:double greater than or equal to zero (0.0e0), and less than one (1.0e0).

A zero-arity function that can be called to return another random number generator.

The properties of this function are as follows:

name: absent

parameter names: ()

signature: () => random-number-generator-record

non-local variable bindings: none

implementation: implementation-dependent

A function with arity 1 (one), which takes an arbitrary sequence as its argument, and returns a random permutation of that sequence.

The properties of this function are as follows:

name: absent

parameter names: "arg"

signature: (item()*) => item()*

non-local variable bindings: none

body: implementation-dependent

This record type is used to represent the result of a call on the fn:divide-decimals function.

The result of the division, expressed to the requested precision.

The part of the dividend that is not accounted for by the quotient.

This record type is used to represent a sort key definition supplied to the fn:sort-by function.

A sort key function, applied to each item in the input sequence to determine a sort key value. The default is fn:data#1.

A collation, used when comparing sort key values of type xs:string or xs:untypedAtomic. The default is the default collation from the static context.

An order direction. The default is "ascending".

This record type is used to represent a sort key definition supplied to the array:sort-by function. It differs from fn:sort-key-record in that the sort key function is applied to a member of an array, which may be any sequence.

A sort key function, applied to each member of the input array to determine a sort key value. The default is fn:data#1.

A collation, used when comparing sort key values of type xs:string or xs:untypedAtomic. The default is the default collation from the static context.

An order direction. The default is "ascending".

This record type is used to represent the outcome of validating a node against a schema, as delivered by the function returned by the fn:xsd-validator function.

Whether the supplied node was found to be valid against the schema.

The root of a deep copy of the input tree, augmented with type annotations and default values.

A sequence of maps, each containing details of one invalidity that was found.

 deterministic context-dependent focus-dependent deterministic context-independent focus-independent

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

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 (see ).

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

If the context value is absent, type error .

If the context value is not an instance of the sequence type xnode()?, type error .

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.

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

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

One

Two

Three ]]> 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 deterministic context-independent focus-independent

Returns information about the type of a value, as a string.

The function returns a string, whose lexical form will always match the grammar of SequenceType, representing a sequence type that matches $value.

If $value is the empty sequence, the function returns the string "empty-sequence()".

Otherwise, the returned string is the concatenation of:

A string representing the distinct item types that are present in $value, formed as follows:

For each item in $value, construct a string representing its item type as described below.

Eliminate duplicate strings from this list by applying the fn:distinct-values function, forming a sequence of strings $ss.

If $ss contains only one string, use that string.

Otherwise, return the result of the expression `({ fn:string-join($ss, "|") })`.

An occurrence indicator: absent if $value contains exactly one item, or "+" if it contains more than one item.

The string representing the type of an individual item J is constructed as follows:

If J is an , the result is one of the following strings, determined by the node kind of the node (see ):

"document-node()" "element()" "attribute()" "text()" "processing-instruction()" "comment()" "namespace-node()"

If J is a , the result is the string "jnode()".

If J is an atomic item, the result is a string chosen as follows:

Let T be the type denoted by the type annotation of J.

If T is an anonymous type, set T to the base type of T, and repeat until a type is reached that is not anonymous.

If the name of T is in the namespace http://www.w3.org/2001/XMLSchema, return the string "xs:local" where local is the local part of the name of T.

Otherwise, return the name of T in the form of a URIQualifiedName (that is, "Q{uri}local", or "Q{}local" if the name is in no namespace).

If J is a function item:

If J is an array, return "array(*)".

If J is a map, return "map(*)".

Otherwise, return "fn(*)".

If the $value argument is omitted and the context value is absent, the function raises type error .

In general, an item matches more than one type, and there are cases where there is no single matching type that is more specific than all the others. This is especially true with functions, maps, and arrays. This function therefore selects one of the types that matches the item, which is not necessarily the most specific type.

This function should not be used as a substitute for an instance of test. The precise type annotation of the result of an expression is not always predictable, because processors are free to deliver a more specific type than is mandated by the specification. For example, if $n is of type xs:positiveInteger, then the result of abs($n) is guaranteed to be an instance of xs:integer, but an implementation might reasonably return the supplied value unchanged: that is, a value whose actual type annotation is xs:positiveInteger. Similarly the type annotation of the value returned by position() might be xs:long rather than xs:integer.

Implementations should, however, refrain from exposing types that are purely internal. For example, an implementation might have an optimized internal representation for strings consisting entirely of ASCII characters, or for single-character strings; if this is the case then the type annotation returned by this function should be a user-visible supertype such as xs:string.

One

Two

Three ]]> type-of($e//*[@id = 'alpha']) "element()" type-of($e//*) "element()+" type-of($e//@id[. = 'gamma']) "attribute()" type-of($e//node()[. = '3.14159']) "processing-instruction()" type-of($e//no-such-node) "empty-sequence()" type-of($e/child::node()) "(element()|processing-instruction())+" type-of(1) "xs:integer" type-of(1 to 5) "xs:integer+" type-of((1, 1.2, 2)) "(xs:integer|xs:decimal)+" type-of([ 1, 2, 3 ]) "array(*)" type-of({ 'a': 1 }) "map(*)" type-of(type-of#1) "fn(*)" type-of(jtree([])) "jnode()"

New in 4.0

 deterministic context-dependent focus-dependent deterministic context-independent focus-independent

Returns true for an element that is nilled.

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 (see ).

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

If the context value is absent, type error

If the context value is not an instance of the sequence type xnode()?, type error .

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 .

 deterministic context-dependent focus-dependent deterministic context-independent focus-independent

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

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

If $value is an , the function returns the string value of the node, as obtained using the dm:string-value accessor defined in (see ).

If $value is a , the function returns the result of string(jvalue($value)). This will fail in the case where jvalue($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 ).

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

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

If the context value is absent, type error .

If the context value is not an instance of the sequence type item()?, type error .

A type error is raised if $value is a function item (this includes maps and arrays).

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 satisfy the type signature but cause failure. Applying the string function 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.

 string(23) "23" string(false()) "false" string("Paris") "Paris" string((1, 2, 3)) string([ [ 1, 2 ], [ 3, 4 ] ]) string(abs#1) string({ "x": [10, 20, 30] }/x/*[3]) "30" There lived a hobbit.]]> string($para) "There lived a hobbit." deterministic context-dependent focus-dependent deterministic context-independent focus-independent

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

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 an , 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 (See ).

If the item is a , the atomized value of its ·jvalue· 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.

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

A type error is raised if an item in the sequence $input is a function item other than an array.

A type error is raised if $input is omitted and the context value is absent.

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 the empty sequence is the empty sequence.

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

 data(123) 123 data((123, 456)) 123, 456 data([ [ 1, 2 ], [ 3, 4 ] ]) 1, 2, 3, 4 There lived a hobbit.]]> data($para) xs:untypedAtomic("There lived a hobbit.") data($para/term/@author) xs:untypedAtomic("Tolkien") data(abs#1) deterministic context-dependent focus-dependent deterministic context-independent focus-independent

Returns the base URI of a node.

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

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 ).

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 the empty sequence — it does not depend on the base URI of the parent element.

See also fn:static-base-uri.

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

If the context value is absent, type error

If the context value is not an instance of the sequence type xnode()?, type error .

A dynamic error may be raised if the base URI is not a valid Legacy Extended IRI reference (see ).

An error may now be raised if the base URI is not a valid LEIRI reference.

 deterministic context-dependent focus-dependent deterministic context-independent focus-independent

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

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 (See ).

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

If the context value is absent, type error

If the context value is not an instance of the sequence type xnode()?, type error .

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.

The constraints on the result of the function have been relaxed.

 deterministic context-dependent focus-dependent deterministic context-independent focus-independent

Returns information about the location of the lexical representation of a node within the XML source document from which it was derived, if the information is available.

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

Otherwise, the function returns the value of the location accessor applied to $node, as defined in (See ).

If location information is available, it is returned as a location-record

It is whether and under what circumstances location information is available for a node. If no location information is available, the function typically returns an empty sequence; alternatively it may return a record each of whose four fields (system-id, public-id, line-number, and column-number) is an empty sequence.

Functions such as fn:doc and fn:parse-xml allow the caller to request that location information be maintained in nodes of the returned tree. There is no guarantee, however, that an implementation will act on this request.

Two implementations that both return location information for a node may differ in the information that they return. For example, one implementation might return the line and column number of the "<" character at the start of an element's start tag, another might return the position of the ">" character at the end of the start tag. A third implementation might return a line number but no column number.

Location information will generally be available only for a node constructed directly by an XML parser. The property will not be available on nodes constructed programmatically (for example in XQuery or XSLT), or on nodes produced by copying another node.

New in 4.0.

 nondeterministic context-independent focus-independent

Calling the fn:error function raises an application-defined error.

This function never returns a value. Instead it always raises an error. The effect of the error is identical to the effect of dynamic errors raised implicitly, for example when an incorrect argument is supplied to a function.

The parameters to the fn:error function supply information that is associated with the error condition and that is made available to a caller that asks for information about the error. The error may be caught either by the host language (using a try/catch construct in XSLT or XQuery, for example), or by the calling application or external processing environment. The way in which error information is returned to the external processing environment is implementation-dependent.

There are three pieces of information that may be associated with an error.

The $code is an error code that distinguishes this error from others. It is an xs:QName; the namespace URI conventionally identifies the component, subsystem, or authority responsible for defining the meaning of the error code, while the local part identifies the specific error condition. The namespace URI http://www.w3.org/2005/xqt-errors is used for errors defined in this specification; other namespace URIs may be used for errors defined by the application.

If the external processing environment expects the error code to be returned as a URI or a string rather than as an xs:QName, then an error code with namespace URI NS and local part LP will be returned in the form NS#LP. The namespace URI part of the error code should therefore not include a fragment identifier.

If $code is the empty sequence, the effective value of the error code is fn:QName('http://www.w3.org/2005/xqt-errors', 'err:FOER0000').

The $description is a natural-language description of the error condition.

If the value is the empty sequence, then the effective value of the description is implementation-dependent.

The $value is an arbitrary value used to convey additional information about the error, and may be used in any way the application chooses.

If the value supplied is the empty sequence, then the effective value of the error object is implementation-dependent.

This function always raises a dynamic error. By default, it raises

The value of the $description parameter may need to be localized.

Any QName may be used as an error code; there are no reserved names or namespaces. The error is always classified as a dynamic error, even if the error code used is one that is normally used for static errors or type errors.

 error() This returns the URI http://www.w3.org/2005/xqt-errors#FOER0000 (or the corresponding xs:QName) to the external processing environment, unless the error is caught using a try/catch construct in the host language. error( QName('http://www.example.com/HR', 'myerr:toohighsal'), 'Salary is too high' ) This returns http://www.example.com/HR#toohighsal and the xs:string "Salary is too high" (or the corresponding xs:QName) to the external processing environment, unless the error is caught using a try/catch construct in the host language.

All three arguments are now optional, and each argument can be set to the empty sequence. Previously if $description was supplied, it could not be empty.

The return type of the function has been changed to xs:error.

 nondeterministic context-independent focus-independent

Provides an execution trace intended to be used in debugging queries.

The function returns $input, unchanged.

In addition, the values of $input, typically serialized and converted to an xs:string, and $label (if non-empty) may be output to an destination.

Any serialization of the implementation’s trace output must not raise an error. This can be achieved (for example) by using a serialization method that can handle arbitrary input, such as the adaptive output method (see ).

The format of the trace output and its order are . Therefore, the order in which the output appears is not predictable. This also means that if dynamic errors occur (whether or not they are caught using try/catch), it may be unpredictable whether any output is reported before the error occurs.

If the trace information is unrelated to a specific value, fn:message can be used instead.

The function is classified as , on the grounds that its output can be regarded as a side effect, even though this side effect has no consequences on the outcome of the application. The practical effect of marking it as nondeterministic may be to encourage an optimizer to exercise restraint in rewriting expressions that include a call to fn:trace. (This in turn may mean that adding a call to fn:trace could change the execution plan for an expression, which may not be the desired effect.)

 let $v := 124.84 return fn:trace($v, 'the value of $v is: ') The function returns the xs:decimal value 124.84, while outputting a message such as "the value of $v is: 124.84" to an destination. The format of the message is also . //book[xs:decimal(@price) gt 100] => trace('books more expensive than €100:') The result of the expression is the same as the result of //book[xs:decimal(@price) gt 100], but evaluation has the side-effect of providing diagnostic feedback to the user.

The $label argument can now be set to the empty sequence. Previously if $label was supplied, it could not be empty.

 nondeterministic context-independent focus-independent

Outputs trace information and discards the result.

Similar to fn:trace, the values of $input, typically serialized and converted to an xs:string, and $label (if non-empty) may be output to an destination.

In contrast to fn:trace, the function returns the empty sequence.

Any serialization of the implementation’s log output must not raise an error. This can e.g. be achieved by using a serialization method that can handle arbitrary input, such as the .

The format of the log output and its order are . Therefore, the order in which the output appears is not predictable. This also means that if dynamic errors occur (whether or not they are caught using try/catch), it may be unpredictable whether any output is logged before the error occurs.

The function can be used for debugging. It can also be helpful in production environments, for example, to save information to a log file for audit purposes.

The function is classified as , on the grounds that its output can be regarded as a side effect, even though this side effect has no consequences on the outcome of the application. The practical effect of marking it as nondeterministic may be to encourage an optimizer to evaluate the expression even though its result is not needed.

 //book[if (xs:decimal(@price) lt 1000) then true() else message(@price, @title || ' is unexpectedly expensive: ')] The result of the expression is the same as the result of //book[xs:decimal(@price) lt 1000], but evaluation has the side-effect of providing diagnostic feedback to the user relating to books above this price threshold.

New in 4.0

 Defines the semantics of the + operator when applied to two numeric values

Returns the arithmetic sum of its operands: ($arg1 + $arg2).

General rules: see .

For xs:float or xs:double values, if one of the operands is a zero or a finite number and the other is INF or -INF, INF or -INF is returned. If both operands are INF, INF is returned. If both operands are -INF, -INF is returned. If one of the operands is INF and the other is -INF, NaN is returned.

 Defines the semantics of the - operator when applied to two numeric values.

Returns the arithmetic difference of its operands: ($arg1 - $arg2).

General rules: see .

For xs:float or xs:double values, if one of the operands is a zero or a finite number and the other is INF or -INF, an infinity of the appropriate sign is returned. If both operands are INF or -INF, NaN is returned. If one of the operands is INF and the other is -INF, an infinity of the appropriate sign is returned.

 Defines the semantics of the * operator when applied to two numeric values.

Returns the arithmetic product of its operands: ($arg1 * $arg2).

General rules: see .

For xs:float or xs:double values, if one of the operands is a zero and the other is an infinity, NaN is returned. If one of the operands is a non-zero number and the other is an infinity, an infinity with the appropriate sign is returned.

 Defines the semantics of the div operator when applied to two numeric values.

Returns the arithmetic quotient of its operands: ($arg1 div $arg2).

General rules: see .

As a special case, if the types of both $arg1 and $arg2 are xs:integer, then the return type is xs:decimal.

A dynamic error is raised for xs:decimal and xs:integer operands, if the divisor is (positive or negative) zero.

For xs:float and xs:double operands, floating point division is performed as specified in . A positive number divided by positive zero returns INF. A negative number divided by positive zero returns -INF. Division by negative zero returns -INF and INF, respectively. Positive or negative zero divided by positive or negative zero returns NaN. Also, INF or -INF divided by INF or -INF returns NaN.

 Defines the semantics of the idiv operator when applied to two numeric values.

Performs an integer division.

General rules: see .

If $arg2 is INF or -INF, and $arg1 is not INF or -INF, then the result is zero.

Otherwise, subject to limits of precision and overflow/underflow conditions, the result is the largest (furthest from zero) xs:integer value $N such that the following expression is true:

abs($N * $arg2) le abs($arg1) and compare($N * $arg2, 0) eq compare($arg1, 0).

The second term in this condition ensures that the result has the correct sign.

The implementation may adopt a different algorithm provided that it is equivalent to this formulation in all cases where implementation-dependent or implementation-defined behavior does not affect the outcome, for example, the implementation-defined precision of the result of xs:decimal division.

A dynamic error is raised if the divisor is (positive or negative) zero.

A dynamic error is raised if either operand is NaN or if $arg1 is INF or -INF.

Except in situations involving errors, loss of precision, or overflow/underflow, the result of $a idiv $b is the same as ($a div $b) cast as xs:integer.

The semantics of this function are different from integer division as defined in programming languages such as Java and C++.

 op:numeric-integer-divide(10, 3) 3 op:numeric-integer-divide(3, -2) -1 op:numeric-integer-divide(-3, 2) -1 op:numeric-integer-divide(-3, -2) 1 op:numeric-integer-divide(9.0, 3) 3 op:numeric-integer-divide(-3.5, 3) -1 op:numeric-integer-divide(3.0, 4) 0 op:numeric-integer-divide(3.1E1, 6) 5 op:numeric-integer-divide(3.1E1, 7) 4 Defines the semantics of the mod operator when applied to two numeric values.

Returns the remainder resulting from dividing $arg1, the dividend, by $arg2, the divisor.

General rules: see .

The operation a mod b for operands that are xs:integer or xs:decimal, or types derived from them, produces a result such that (a idiv b) * b + (a mod b) is equal to a and the magnitude of the result is always less than the magnitude of b. This identity holds even in the special case that the dividend is the negative integer of largest possible magnitude for its type and the divisor is -1 (the remainder is 0). It follows from this rule that the sign of the result is the sign of the dividend.

For xs:float and xs:double operands the following rules apply:

If either operand is NaN, the result is NaN.

If the dividend is positive or negative infinity, or the divisor is positive or negative zero (0), or both, the result is NaN.

If the dividend is finite and the divisor is an infinity, the result equals the dividend.

If the dividend is positive or negative zero and the divisor is finite, the result is the same as the dividend.

In the remaining cases, where neither positive or negative infinity, nor positive or negative zero, nor NaN is involved, the result obeys (a idiv b)*b+(a mod b) = a. Division is truncating division, analogous to integer division, not rounding division i.e. additional digits are truncated, not rounded to the required precision.

A dynamic error is raised for xs:integer and xs:decimal operands, if $arg2 is zero.

 op:numeric-mod(10, 3) 1 op:numeric-mod(6, -2) 0 op:numeric-mod(4.5, 1.2) 0.9 op:numeric-mod(1.23E2, 0.6E1) 3.0E0 Defines the semantics of the unary + operator applied to a numeric value.

Returns its operand with the sign unchanged: (+ $arg).

General rules: see .

The returned value is equal to $arg, and is an instance of xs:integer, xs:decimal, xs:double, or xs:float depending on the type of $arg.

Because coercion rules are applied in the normal way, the unary + operator can be used to force conversion of an untyped node to a number: the result of +@price is the same as xs:double(@price) if the type of @price is xs:untypedAtomic.

 Defines the semantics of the unary - operator when applied to a numeric value.

Returns its operand with the sign reversed: -$arg.

General rules: see .

The returned value is an instance of xs:integer, xs:decimal, xs:double, or xs:float depending on the type of $arg.

For xs:integer and xs:decimal arguments, 0 and 0.0 return 0 and 0.0, respectively. For xs:float and xs:double arguments, NaN returns NaN, 0.0E0 returns -0.0E0 and vice versa. INF returns -INF. -INF returns INF.

 deterministic context-independent focus-independent

Returns the absolute value of $value.

General rules: see .

If $value is negative the function returns -$value, otherwise it returns $value.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $value is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $value is an instance of xs:positiveInteger then the value of $value may be returned unchanged.

For xs:float and xs:double arguments, if the argument is positive zero or negative zero, then positive zero is returned. If the argument is positive or negative infinity, positive infinity is returned.

 abs(10.5) 10.5 abs(-10.5) 10.5 abs(-math:log(0)) xs:double('INF') deterministic context-independent focus-independent

Rounds $value upwards to a whole number.

General rules: see .

The function returns the smallest (closest to negative infinity) number with no fractional part that is not less than $value.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $value is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $value is an instance of xs:decimal then the result may be an instance of xs:integer.

For xs:float and xs:double arguments, if the argument is positive zero, then positive zero is returned. If the argument is negative zero, then negative zero is returned. If the argument is less than zero and greater than -1, negative zero is returned. If the argument is positive or negative infinity, the value of the argument is returned.

 ceiling(10.5) 11 ceiling(-10.5) -10 ceiling(math:log(0)) -xs:double('INF') deterministic context-independent focus-independent

Rounds $value downwards to a whole number.

General rules: see .

The function returns the largest (closest to positive infinity) number with no fractional part that is not greater than $value.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $value is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $value is an instance of xs:decimal then the result may be an instance of xs:integer.

For xs:float and xs:double arguments, if the argument is positive zero, then positive zero is returned. If the argument is negative zero, then negative zero is returned. If the argument is positive or negative infinity, the value of the argument is returned.

 floor(10.5) 10 floor(-10.5) -11 math:log(0) => floor() -xs:double('INF') deterministic context-independent focus-independent

Rounds a value to a specified number of decimal places, with control over how the rounding takes place.

General rules: see .

The function returns a value that is close to $value and that is a multiple of ten to the power of minus $precision. The default value of $precision is zero, in which case the function returns a whole number (but not necessarily an xs:integer).

The detailed way in which rounding is performed depends on the value of $mode, as follows. Here L means the highest multiple of ten to the power of minus $precision that is less than or equal to $value, U means the lowest multiple of ten to the power of minus $precision that is greater than or equal to $value, N means the multiple of ten to the power of minus $precision that is numerically closest to $value, and midway means that $value is equal to the arithmetic mean of L and U.

Rounding Modes
Rounding Mode Meaning

'floor'

Returns L.

'ceiling'

Returns U.

'toward-zero'

Returns L if $value is positive, otherwise U.

'away-from-zero'

Returns U if $value is positive, otherwise L

'half-to-floor'

Returns N, unless midway, in which case L.

'half-to-ceiling'

Returns N, unless midway, in which case U. This is the default.

'half-toward-zero'

Returns N, unless midway, in which case it returns L if $value is positive, otherwise U.

'half-away-from-zero'

Returns N, unless midway, in which case it returns U if $value is positive, otherwise L.

'half-to-even'

Returns N, unless midway, in which case it returns whichever of L and U has a last significant digit that is even.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $value is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $value is an instance of xs:decimal and $precision is less than one, then the result may be an instance of xs:integer.

If the second argument is omitted or is the empty sequence, the function produces the same result as when $precision = 0 (that is, it rounds to a whole number).

When $value is of type xs:float and xs:double:

If $value is NaN, positive or negative zero, or positive or negative infinity, then the result is the same as the argument.

For other values, the argument is cast to xs:decimal using an implementation of xs:decimal that imposes no limits on the number of digits that can be represented. The function is applied to this xs:decimal value, and the resulting xs:decimal is cast back to xs:float or xs:double as appropriate to form the function result. If the resulting xs:decimal value is zero, then positive or negative zero is returned according to the sign of $value.

There may be limits on the precision available. If the requested $precision is outside this range, it should be adjusted to the nearest value supported by the implementation.

This function is typically used with a non-zero $precision in financial applications where the argument is of type xs:decimal. For arguments of type xs:float and xs:double the results may be counter-intuitive. For example, consider round(35.425e0, 2). The result is not 35.43, as might be expected, but 35.42. This is because the xs:double written as 35.425e0 has an exact value equal to 35.42499999999..., which is closer to 35.42 than to 35.43.

The call round($v, 0, "floor") is equivalent to floor($v).

The call round($v, 0, "ceiling") is equivalent to ceiling($v).

The call round($v, $p, "half-to-even") is equivalent to round-half-to-even($v, $p).

 round(2.5) 3.0 round(2.4999) 2.0 round(-2.5) -2.0 round(1.125, 2) 1.13 round(8452, -2) 8500 round(3.1415e0, 2) 3.14e0 math:log(0) => round() -xs:double('INF') round(1.7, 0, "floor") 1 round(-1.7, 0, "floor") -2 round(1.7, 0, "ceiling") 2 round(-1.7, 0, "ceiling") -1 round(1.7, 0, "toward-zero") 1 round(-1.7, 0, "toward-zero") -1 round(1.7, 0, "away-from-zero") 2 round(-1.7, 0, "away-from-zero") -2 round(1.125, 2, "half-to-floor") 1.12 round(-1.125, 2, "half-to-floor") -1.13 round(1.125, 2, "half-to-ceiling") 1.13 round(-1.125, 2, "half-to-ceiling") -1.12 round(1.125, 2, "half-toward-zero") 1.12 round(-1.125, 2, "half-toward-zero") -1.12 round(1.125, 2, "half-away-from-zero") 1.13 round(-1.125, 2, "half-away-from-zero") -1.13 round(1.125, 2, "half-to-even") 1.12 round(-1.125, 2, "half-to-even") -1.12

A third argument has been added, providing control over the rounding mode.

It is explicitly stated that the limits for $precision are implementation-defined.

 deterministic context-independent focus-independent

Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near.

General rules: see .

The function returns the nearest (that is, numerically closest) value to $value that is a multiple of ten to the power of minus $precision. If two such values are equally near (e.g. if the fractional part in $value is exactly .500...), the function returns the one whose least significant digit is even.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $value is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $value is an instance of xs:decimal and $precision is less than one, then the result may be an instance of xs:integer.

For arguments of type xs:float and xs:double:

If the argument is NaN, positive or negative zero, or positive or negative infinity, then the result is the same as the argument.

In all other cases, the argument is cast to xs:decimal using an implementation of xs:decimal that imposes no limits on the number of digits that can be represented. The function is applied to this xs:decimal value, and the resulting xs:decimal is cast back to xs:float or xs:double as appropriate to form the function result. If the resulting xs:decimal value is zero, then positive or negative zero is returned according to the sign of the original argument.

There may be limits on the precision available. If the requested $precision is outside this range, it should be adjusted to the nearest value supported by the implementation.

This function is typically used in financial applications where the argument is of type xs:decimal. For arguments of type xs:float and xs:double the results may be counter-intuitive. For example, consider round-half-to-even(xs:float(150.015), 2). The result is not 150.02 as might be expected, but 150.01. This is because the conversion of the xs:float value represented by the literal 150.015 to an xs:decimal produces the xs:decimal value 150.014999389..., which is closer to 150.01 than to 150.02.

From 4.0, the effect of this function can also be achieved by calling fn:round with the third argument set to "half-to-even".

 round-half-to-even(0.5) 0.0 round-half-to-even(1.5) 2.0 round-half-to-even(2.5) 2.0 round-half-to-even(3.567812e+3, 2) 3567.81e0 round-half-to-even(4.7564e-3, 2) 0.0e0 round-half-to-even(35612.25, -2) 35600 math:log(0) => round-half-to-even() -xs:double('INF')

It is explicitly stated that the limits for $precision are implementation-defined.

 deterministic context-independent focus-independent

Divides one xs:decimal by another to a defined precision, returning both the quotient and the remainder.

The function returns a record with two fields:

quotient is the xs:decimal value furthest from zero such that:

quotient is an exact multiple of ten to the power of minus $precision;

the absolute value of quotient multipled by $divisor is less than or equal to the absolute value of $value;

the sign of quotient is the same as the sign of op:numeric-divide($value, $divisor).

remainder is the exact result of subtracting quotient multiplied by $divisor from $value.

There may be limits on the precision available. If the requested $precision is outside this range, it should be adjusted to the nearest value supported by the implementation.

A dynamic error is raised if $divisor is zero.

 divide-decimals(120.6, 60.3, 4) { "quotient": 2, "remainder": 0 } divide-decimals(10, 3) { "quotient": 3, "remainder": 1 } divide-decimals(10, -3) { "quotient": -3, "remainder": 1 } divide-decimals(-10, 3) { "quotient": -3, "remainder": -1 } divide-decimals(-10, -3) { "quotient": 3, "remainder": -1 } divide-decimals(10, 3, 6) { "quotient": 3.333333, "remainder": 0.000001 } divide-decimals(100, 30) { "quotient": 3, "remainder": 10 } divide-decimals(150_862, 7, -3) { "quotient": 21_000, "remainder": 3_862 }

New in 4.0.

 deterministic context-dependent focus-independent deterministic context-independent focus-independent

Formats an integer according to a given picture string, using the conventions of a given natural language if specified.

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

In all other cases, the $picture argument describes the format in which $value is output.

The rules that follow describe how non-negative numbers are output. If the value of $value is negative, the rules below are applied to the absolute value of $value, and a minus sign is prepended to the result.

The value of $picture consists of the following, in order:

An optional radix, which is an integer in the range 2 to 36, written using ASCII digits (0-9) without any leading zero;

A circumflex (^), which is present if the radix is present, and absent otherwise.

A circumflex is recognized as marking the presence of a radix only if (a) it is immediately preceded by an integer in the range 2 to 36, and (b) it is followed (somewhere within the primary format token) by an "X" or "x". In other cases, the circumflex is treated as a grouping separator. For example, the picture 9^000 outputs the number 2345 as "2^345", whereas 9^XXX outputs "3185". This rule is to ensure backwards compatibility.

A primary format token. This is always present and must not be zero-length.

An optional format modifier.

If the string contains one or more semicolons then the last semicolon is taken as terminating the primary format token, and everything that follows is taken as the format modifier; if the string contains no semicolon then the format modifier is taken to be absent (which is equivalent to supplying a zero-length string).

If a radix is present, then the primary format token must follow the rules for a digit-pattern.

The primary format token is classified as one of the following:

A digit-pattern made up of optional-digit-signs, mandatory-digit-signs, and grouping-separator-signs.

The optional-digit-sign is the character #.

If the radix is absent, then a mandatory-digit-sign is a character in Unicode category Nd. All mandatory-digit-signs within the format token must be from the same digit family, where a digit family is a sequence of ten consecutive characters in Unicode category Nd, having digit values 0 through 9. Within the format token, these digits are interchangeable: a three-digit number may thus be indicated equivalently by 000, 001, or 999.

If the primary format token contains at least one Unicode digit, then the primary format token is taken as a decimal digit pattern, and in this case it must match the regular expression ^((\p{Nd}|#|[^\p{N}\p{L}])+?)$. If it contains a digit but does not match this pattern, a dynamic error is raised .

If the radix (call it R) is present (including the case where an explicit radix of 10 is used), then the character used as the mandatory-digit-sign is either "x" or "X". If any mandatory-digit-sign is upper-case "X", then all mandatory-digit-signs must be upper-case "X". The digit family used in the output comprises the first R characters of the alphabet 0123456789abcdefghijklmnopqrstuvwxyz, but using upper-case letters in place of lower-case if an upper-case "X" is used as the mandatory-digit-sign.

In this case the primary format token must match the regular expression ^(([Xx#]|[^\p{N}\p{L}])+?)$

a grouping-separator-sign is a non-alphanumeric character, that is a character whose Unicode category is other than Nd, Nl, No, Lu, Ll, Lt, Lm or Lo.

If a semicolon is to be used as a grouping separator, then the primary format token as a whole must be followed by another semicolon, to ensure that the grouping separator is not mistaken as a separator between the primary format token and the format modifier.

There must be at least one mandatory-digit-sign. There may be zero or more optional-digit-signs, and (if present) these must precede all mandatory-digit-signs. There may be zero or more grouping-separator-signs. A grouping-separator-sign must not appear at the start or end of the digit-pattern, nor adjacent to another grouping-separator-sign.

The corresponding output is a number in the specified radix, using this digit family, with at least as many digits as there are mandatory-digit-signs in the format token. Thus:

A format token 1 generates the sequence 0 1 2 ... 10 11 12 ...

A format token 01 (or equivalently, 00 or 99) generates the sequence 00 01 02 ... 09 10 11 12 ... 99 100 101

A format token of U+0661 generates the sequence ١ then ٢ then ٣ ...

A format token of 16^xx generates the sequence 00 01 02 03 ... 08 09 0a 0b 0c 0d 0e 0f 10 11 ...

A format token of 16^X generates the sequence 0 1 2 3 ... 8 9 A B C D E F 10 11 ...

The grouping-separator-signs are handled as follows:

The position of grouping separators within the format token, counting backwards from the last digit, indicates the position of grouping separators to appear within the formatted number, and the character used as the grouping-separator-sign within the format token indicates the character to be used as the corresponding grouping separator in the formatted number.

More specifically, the position of a grouping separator is the number of optional-digit-signs and mandatory-digit-signs appearing between the grouping separator and the right-hand end of the primary format token.

Grouping separators are defined to be regular if the following conditions apply:

There is at least one grouping separator.

Every grouping separator is the same character (call it C).

There is a positive integer G (the grouping size) such that:

The position of every grouping separator is an integer multiple of G, and

Every positive integer multiple of G that is less than the number of optional-digit-signs and mandatory-digit-signs in the primary format token is the position of a grouping separator.

The grouping separator template is a (possibly infinite) set of (position, character) pairs.

If grouping separators are regular, then the grouping separator template contains one pair of the form (n×G, C) for every positive integer n where G is the grouping size and C is the grouping character.

Otherwise (when grouping separators are not regular), the grouping separator template contains one pair of the form (P, C) for every grouping separator found in the primary formatting token, where C is the grouping separator character and P is its position.

If there are no grouping separators, then the grouping separator template is the empty set.

The number is formatted as follows:

Let S/1 be the result of formatting the supplied number in the appropriate radix: for radix 10 this will be the value obtained by casting it to xs:string.

Let S/2 be the result of padding S/1 on the left with as many leading zeroes as are needed to ensure that it contains at least as many digits as the number of mandatory-digit-signs in the primary format token.

Let S/3 be the result of replacing all decimal digits (0-9) in S/2 with the corresponding digits from the selected digit family. (This has no effect when the selected digit family uses ASCII digits (0-9), which will always be the case if a radix is specified.)

Let S/4 be the result of inserting grouping separators into S/3: for every (position P, character C) pair in the grouping separator template where P is less than the number of digits in S/3, insert character C into S/3 at position P, counting from the right-hand end.

Let S/5 be the result of converting S/4 into ordinal form, if an ordinal modifier is present, as described below.

The result of the function is then S/5.

The format token A, which generates the sequence A B C ... Z AA AB AC....

The format token a, which generates the sequence a b c ... z aa ab ac....

The format token i, which generates the sequence i ii iii iv v vi vii viii ix x ....

The format token I, which generates the sequence I II III IV V VI VII VIII IX X ....

The format token w, which generates numbers written as lower-case words, for example in English, one two three four ...

The format token W, which generates numbers written as upper-case words, for example in English, ONE TWO THREE FOUR ...

The format token Ww, which generates numbers written as title-case words, for example in English, One Two Three Four ...

Any other format token, which indicates a numbering sequence in which that token represents the number 1 (one) (but see the note below). It is implementation-defined which numbering sequences, additional to those listed above, are supported. If an implementation does not support a numbering sequence represented by the given token, it must use a format token of 1.

In some traditional numbering sequences additional signs are added to denote that the letters should be interpreted as numbers, for example, in ancient Greek U+0374 and sometimes U+0375. These should not be included in the format token.

For all format tokens other than a digit-pattern, there may be implementation-defined lower and upper bounds on the range of numbers that can be formatted using this format token; indeed, for some numbering sequences there may be intrinsic limits. For example, the format token U+2460 has a range imposed by the Unicode character repertoire — zero to 20 in Unicode versions prior to 3.2, or zero to 50 in subsequent versions. For the numbering sequences described above any upper bound imposed by the implementation must not be less than 1000 (one thousand) and any lower bound must not be greater than 1. Numbers that fall outside this range must be formatted using the format token 1.

The above expansions of numbering sequences for format tokens such as a and i are indicative but not prescriptive. There are various conventions in use for how alphabetic sequences continue when the alphabet is exhausted, and differing conventions for how roman numerals are written (for example, IV versus IIII as the representation of the number 4). Sometimes alphabetic sequences are used that omit letters such as i and o. This specification does not prescribe the detail of any sequence other than those sequences consisting entirely of decimal digits.

Many numbering sequences are language-sensitive. This applies especially to the sequence selected by the tokens w, W, and Ww. It also applies to other sequences, for example different languages using the Cyrillic alphabet use different sequences of characters, each starting with the letter U+0410 . In such cases, the $language argument specifies which language conventions are to be used. If the argument is specified, the value should be either the empty sequence or a value that would be valid for the xml:lang attribute (see ). Note that this permits the identification of sublanguages based on country codes (from ISO 3166-1) as well as identification of dialects and regions within a country.

The set of languages for which numbering is supported is implementation-defined. If the $language argument is absent, or is set to the empty sequence, or is invalid, or is not a language supported by the implementation, then the number is formatted using the default language from the dynamic context.

The format modifier must be a string that matches the regular expression ^([co](\(.+\))?)?[at]?$. That is, if it is present it must consist of one or more of the following, in order:

either c or o, optionally followed by a sequence of characters enclosed between parentheses, to indicate cardinal or ordinal numbering respectively, the default being cardinal numbering

either a or t, to indicate alphabetic or traditional numbering respectively, the default being implementation-defined.

If the o modifier is present, this indicates a request to output ordinal numbers rather than cardinal numbers. For example, in English, when used with the format token 1, this outputs the sequence 1st 2nd 3rd 4th ..., and when used with the format token w outputs the sequence first second third fourth ....

The string of characters between the parentheses, if present, is used to select between other possible variations of cardinal or ordinal numbering sequences. The interpretation of this string is implementation-defined. No error occurs if the implementation does not define any interpretation for the defined string.

It is implementation-defined what combinations of values of the format token, the language, and the cardinal/ordinal modifier are supported. If ordinal numbering is not supported for the combination of the format token, the language, and the string appearing in parentheses, the request is ignored and cardinal numbers are generated instead.

The use of the a or t modifier disambiguates between numbering sequences that use letters. In many languages there are two commonly used numbering sequences that use letters. One numbering sequence assigns numeric values to letters in alphabetic sequence, and the other assigns numeric values to each letter in some other manner traditional in that language. In English, these would correspond to the numbering sequences specified by the format tokens a and i. In some languages, the first member of each sequence is the same, and so the format token alone would be ambiguous. In the absence of the a or t modifier, the default is implementation-defined.

A dynamic error is raised if the format token is invalid, that is, if it violates any mandatory rules (indicated by an emphasized must or required keyword in the above rules). For example, the error is raised if the primary format token contains a digit but does not match the required regular expression.

Note the careful distinction between conditions that are errors and conditions where fallback occurs. The principle is that an error in the syntax of the format picture will be reported by all processors, while a construct that is recognized by some implementations but not others will never result in an error, but will instead cause a fallback representation of the integer to be used.

The following notes apply when a digit-pattern is used:

If grouping-separator-signs appear at regular intervals within the format token, then the sequence is extrapolated to the left, so grouping separators will be used in the formatted number at every multiple of N. For example, if the format token is 0'000 then the number one million will be formatted as 1'000'000, while the number fifteen will be formatted as 0'015.

The only purpose of optional-digit-signs is to mark the position of grouping-separator-signs. For example, if the format token is #'##0 then the number one million will be formatted as 1'000'000, while the number fifteen will be formatted as 15. A grouping separator is included in the formatted number only if there is a digit to its left, which will only be the case if either (a) the number is large enough to require that digit, or (b) the number of mandatory-digit-signs in the format token requires insignificant leading zeroes to be present.

Grouping separators are not designed for effects such as formatting a US telephone number as (365)123-9876. In general they are not suitable for such purposes because (a) only single characters are allowed, and (b) they cannot appear at the beginning or end of the number.

Numbers will never be truncated. Given the digit-pattern 01, the number three hundred will be output as 300, despite the absence of any optional-digit-sign.

The following notes apply when ordinal numbering is selected using the o modifier.

In some languages, the form of numbers (especially ordinal numbers) varies depending on the grammatical context: they may have different genders and may decline with the noun that they qualify. In such cases the string appearing in parentheses after the letter c or o may be used to indicate the variation of the cardinal or ordinal number required.

The way in which the variation is indicated will depend on the conventions of the language.

For inflected languages that vary the ending of the word, the approach recommended in the previous version of this specification was to indicate the required ending, preceded by a hyphen: for example in German, appropriate values might be o(-e), o(-er), o(-es), o(-en).

Another approach, which might usefully be adopted by an implementation based on the open-source ICU localization library , or any other library making use of the Unicode Common Locale Data Repository , is to allow the value in parentheses to be the name of a registered numbering rule set for the language in question, conventionally prefixed with a percent sign: for example, o(%spellout-ordinal-masculine), or c(%spellout-cardinal-year).

The following notes apply when the primary format token is neither a digit-pattern nor one of the seven other defined format tokens (A, a, i, I, w, W, Ww), but is an arbitrary token representing the number 1:

Unexpected results may occur for traditional numbering. For example, in an implementation that supports traditional numbering system in Greek, the example format-integer(19, "α;t") might return δπιιιι or ιθ, depending upon whether the ancient acrophonic or late antique alphabetic system is supported.

Unexpected results may also occur for alphabetic numbering. For example, in an implementation that supports alphabetic numbering system in Greek, someone writing format-integer(19, "α;a") might expect the nineteenth Greek letter, U+03C4, but the implementation might return the eighteenth one, U+03C3, because the latter is the nineteenth item in the sequence of lowercase Greek letters in Unicode (the sequence is interrupted because of the final form of the sigma, U+03C2). Because Greek never had a final capital sigma, Unicode has marked U+03A2, the eighteenth codepoint in the sequence of Greek capital letters, as reserved, to ensure that every Greek uppercase letter is always 32 codepoints less than its lowercase counterpart. Therefore, someone writing format-integer(18, "Α;a") might expect the eighteenth Greek capital letter, U+03A3, but an implementation might return U+03A2, the eighteenth position in the sequence of Greek capital letters, but unassigned to any character.

format-integer(123, '0000') "0123" format-integer(123, 'w') Depending on the default language, the expression might return the string "one hundred and twenty-three" format-integer(21, '1;o', 'en') "21st" format-integer(14, 'Ww;o(-e)', 'de') If supported, might return the string "Vierzehnte". (1 to 10) ! format-integer(., "1;o(-º)", language:="it") This requests ordinal numbering in Italian: if supported, this should produce the sequence: 1º 2º 3º 4º ... (1 to 10) ! format-integer(., "Ww;o", language:="it") This requests ordinal numbering in Italian, spelled out as words: if supported, this should produce the sequence: Primo Secondo Terzo Quarto Quinto ... format-integer(7, 'a') "g" format-integer(27, 'a') "aa" format-integer(57, 'I') "LVII" format-integer(1234, '#;##0;') "1;234" format-integer(1234, '16^xxxx') "04d2" format-integer(1234, '16^X') "4D2" format-integer(12345678, '16^xxxx_xxxx') "00bc_614e" format-integer(12345678, '16^#_xxxx') "bc_614e" format-integer(255, '2^xxxx xxxx') "1111 1111" format-integer(1023, '32^XXXX') "00VV" format-integer(1023, '10^XXXX') "1023" format-integer(1023, '10^00') "10^23" format-integer(-5, '001') "-005" format-integer(-5, 'a') "-e" format-integer(-12, '16^XX') "-0C"

The function has been extended to allow output in a radix other than 10, for example in hexadecimal.

 deterministic context-independent focus-independent deterministic context-dependent focus-independent

Returns a string containing a number formatted according to a given picture string and decimal format.

The function formats $value as a string using the picture string specified by the $picture argument and a decimal format.

The $value argument may be of any numeric data type (xs:double, xs:float, xs:decimal, or their subtypes including xs:integer). Note that if an xs:decimal is supplied, it is not automatically converted to an xs:double, as such conversion can involve a loss of precision.

If the supplied value of the $value argument is the empty sequence, the function behaves as if the supplied value were the xs:double value NaN.

If $options is the empty map, then the number is formatted using the properties of the unnamed decimal format in the static context.

For backwards compatibility reasons, the decimal format can be supplied as an instance of xs:string. If the value of the $options argument is an xs:string, then its value must be a string which after removal of leading and trailing whitespace is in the form of an EQName as defined in the XPath 4.0 grammar, that is one of the following:

A lexical QName, which is expanded using the statically known namespaces. The default namespace is not used (no prefix means no namespace).

A URIQualifiedName using the syntax Q{uri}local, where the URI can be zero-length to indicate a name in no namespace.

The effective value of the $options argument is then the map { 'format-name': $FN } where $FN is the xs:QName result of expanding this EQName.

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

In the table, the type xs:string (: matching '.' :) represents a single-character string, that is, a restriction of xs:string with the facet pattern=".", while the type xs:string (: matching '.|.:.*' :) indicates a string that is either a single character, or a single character followed by U+003A followed by an arbitrary string. Such a property identifies two values: a single character called the marker, which is used to represent the property in the picture string; and an arbitrary string called the rendition which is used to represent in the property in the result string. In the absence of the colon the single character value is used both as the marker and the rendition.

The default value for absent options (other than format-name) is taken from a decimal format in the static context; the default values shown in the table are the values used if no specific value is assigned in the static context.

The name of a decimal format in the static context; if absent, the unnamed decimal format in the static context is used. An xs:NCName represents the local part of an xs:QName in no namespace. (xs:NCName | xs:QName)? () The marker used to represent the decimal point in the picture string, and the rendition of the decimal point in the formatted number. xs:string (: matching '.|.:.*' :) "." The marker used to separate groups of digits in the picture string, and the rendition of the grouping separator in the formatted number. xs:string (: matching '.|.:.*' :) "," The marker used to separate the mantissa from the exponent in scientific notation in the picture string, and the rendition of the exponent separator in the formatted number. xs:string (: matching '.|.:.*' :) "e" The string used to represent the value positive or negative infinity in the formatted number. xs:string "Infinity" The string used as a minus sign in the formatted number if there is no subpicture for formatting negative numbers. xs:string "-" The string used to represent the value NaN in the formatted number. xs:string "NaN" The marker used to indicate the presence of a percent sign in the picture string, and the rendition of the percent sign in the formatted number. xs:string (: matching '.|.:.*' :) "%" marker used to indicate the presence of a per-mille sign in the picture string, and the rendition of the per-mille sign in the formatted number. xs:string (: matching '.|.:.*' :) "‰" (0x2030) Defines the characters used in the picture string to represent a mandatory digit: for example, if the zero-digit is 0 then any of the digits 0 to 9 may be used (interchangeably) in the picture string to represent a mandatory digit, and in the formatted number the characters 0 to 9 will be used to represent the digits zero to nine. The value must be a character in Unicode category Nd with decimal digit value 0 (zero). xs:string (: matching '.' :) "0" The character used in the picture string to represent an optional digit. xs:string (: matching '.' :) "#" The character used in the picture string to separate the positive and negative subpictures. xs:string (: matching '.' :) ";"

A base decimal format is established as follows:

If the format-name option is present, then the decimal format in the static context identified by this name.

Otherwise, the unnamed decimal format in the static context.

The base decimal format is then modified using the other entries in the supplied $options map.

The evaluation of the fn:format-number function takes place in two phases, an analysis phase described in and a formatting phase described in .

The analysis phase takes as its inputs the picture string and the variables derived from the relevant decimal format in the static context, and produces as its output a number of variables with defined values. The formatting phase takes as its inputs the number to be formatted and the variables produced by the analysis phase, and produces as its output a string containing a formatted representation of the number.

The result of the function is the formatted string representation of the supplied number.

A dynamic error is raised if the $options argument is supplied as an xs:string that is neither a valid lexical QName nor a valid URIQualifiedName, or if it uses a prefix that is not found in the statically known namespaces; or if the static context does not contain a declaration of a decimal format with a matching expanded QName; or if $options?format-name is present and the static context does not contain a declaration of a decimal format whose name matches $options?format-name. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

A dynamic error is raised if a value of $format is not valid for the associated property, or if the properties of the decimal format resulting from a supplied $options map do not have distinct values.

A string is an ordered sequence of characters, and this specification uses terms such as “left” and “right”, “preceding” and “following” in relation to this ordering, irrespective of the position of the characters when visually rendered on some output medium. Both in the picture string and in the result string, digits with higher significance (that is, representing higher powers of ten) always precede digits with lower significance, even when the rendered text flow is from right to left.

In previous versions of XSLT and XQuery, decimal formats were typically defined in the static context using custom declarations (<xsl:decimal-format> in XSLT, declare decimal-format in XQuery) and then selected by name in a call on fn:format-number. This mechanism remains available, but in 4.0, it may be more convenient to dispense with these declarations, and instead to define a decimal format as a map bound to a global variable, which can be referenced in the $options argument of the fn:format-number call.

Alternative ways to format an xs:double as a string include:

Direct casting to string, for example using the constructor function xs:string($number)

JSON serialization, for example fn:serialize($number, {'method':'json', 'canonical':true()})

In general these will produce different results, for example in the amount of precision that is retained, and in the use of exponential (scientific) notation.

The following examples assume a default decimal format in which the chosen digits are the ASCII digits 0-9, the decimal separator is ., the grouping separator is ,, the minus-sign is -, and the percent-sign is %.

format-number(12345.6, '#,###.00') "12,345.60" format-number(12345678.9, '9,999.99') "12,345,678.90" format-number(123.9, '9999') "0124" format-number(0.14, '01%') "14%" format-number(0.14, '01%', { 'percent': '%:pc' }) "14pc" format-number(12345, '0.0###^0', { 'exponent-separator': '^:×10^' }) "1.2345×10^4" format-number(-6, '000') "-006" format-number(1234567.8, '0.000,0', { 'grouping-separator': '.', 'decimal-separator': ',' }) "1.234.567,8"

The following examples assume the existence of a decimal format named de in which the grouping separator is . and the decimal separator is ,:

format-number(1234.5678, '#.##0,00', { 'format-name': 'de' }) "1.234,57" format-number(12345, '0,###^0', { 'format-name': 'de', 'exponent-separator': '^' }) "1,234^4" format-number(12345, '0,###^0', { 'format-name': 'de', 'exponent-separator': '^:×10^' }) "1,234×10^4"

The following examples assume that the exponent separator in decimal format fortran is E:

format-number(1234.5678, '00.000E0', 'fortran') "12.346E2" format-number(0.234, '0.0E0', 'fortran') "2.3E-1" format-number(0.234, '#.00E0', 'fortran') "0.23E0" format-number(0.234, '.00E0', 'fortran') ".23E0"

The decimal format name can now be supplied as a value of type xs:QName, as an alternative to supplying a lexical QName as an instance of xs:string.

Decimal format parameters can now be supplied directly as a map in the third argument, rather than referencing a format defined in the static context.

For selected properties including percent and exponent-separator, it is now possible to specify a single-character marker to be used in the picture string, together with a multi-character rendition to be used in the formatted output.

 deterministic context-independent focus-independent

Converts a string to an integer, recognizing any radix in the range 2 to 36.

If $value is the empty sequence, the result is the empty sequence.

The supplied $radix must be in the range 2 to 36 inclusive.

The string $value is preprocessed by stripping all whitespace characters (including internal whitespace) and underscore characters.

After this process, the supplied value must consist of an optional sign (+ or -) followed by a sequence of one or more generalized digits drawn from the first $radix characters in the alphabet 0123456789abcdefghijklmnopqrstuvwxyz; upper-case alphabetics A-Z may be used in place of their lower-case equivalents.

The value of a generalized digit corresponds to its position in this alphabet.

 let $alphabet := characters("0123456789abcdefghijklmnopqrstuvwxyz") let $preprocessed := translate( $value, codepoints-to-string((9, 10, 13, 32, 95)), "" ) let $digits := translate($preprocessed, "+-", "") let $abs := sum( for $char at $p in reverse(characters(lower-case($digits))) return (index-of($alphabet, $char) - 1) * xs:integer(math:pow($radix, $p - 1)) ) return if (starts-with($preprocessed, "-")) then -$abs else +$abs

A dynamic error is raised if $radix is not in the range 2 to 36.

A dynamic error is raised if, after stripping whitespace and underscores and the optional leading sign, $value is a zero-length string, or if it contains a character that is not among the first $radix characters in the alphabet 0123456789abcdefghijklmnopqrstuvwxyz, or the upper-case equivalent of such a character.

A dynamic error is raised if the value of the resulting integer exceeds the implementation-dependent limit on the size of an xs:integer.

When $radix takes its default value of 10, the function delivers the same result as casting $value (after removal of whitespace and underscores) to xs:integer.

If underscores or whitespace in the input need to be rejected, then the string should first be validated, perhaps using fn:matches.

If other characters may legitimately appear in the input, for example a leading 0x, then this must first be removed by pre-processing the input.

If the input uses a different family of digits, then the value should first be converted to the required digits using fn:translate.

A string in the lexical space of xs:hexBinary will always be an acceptable input, provided it is not too long. So, for example, the expression "1DE=" => xs:base64Binary() => xs:hexBinary() => xs:string() => parse-integer(16) can be used to convert the Base 64 value 1DE= to the integer 54321, via the hexadecimal string D431.

 parse-integer(" 200 ") 200 parse-integer("-20") -20 parse-integer(" +100") 100 parse-integer("ff", 16) 255 parse-integer("FFFF FFFF", 16) 4294967295 parse-integer("-FFFF_FFFF", 16) -4294967295 parse-integer("377", 8) 255 parse-integer("101", 2) 5 parse-integer("vv", 32) 1023

Alphabetic base-26 numbering systems (hexavigesimal) can be parsed via translation. Note, enumerating systems that do not assign a symbol to zero (e.g., spreadsheet columns) must be preprocessed in a different fashion.

lower-case("AAB") => translate("abcdefghijklmnopqrstuvwxyz", "0123456789abcdefghijklmnop") => parse-integer(26) 1

Digit-based numeration systems comparable to the Arabic numbers 0 through 9 can be parsed via translation.

translate(value := '٢٠٢٣', replace := '٠١٢٣٤٥٦٧٨٩', with := '0123456789') => parse-integer() 2023

New in 4.0

 deterministic context-independent focus-independent

Returns an approximation to the mathematical constant π.

This function returns the xs:double value whose lexical representation is 3.141592653589793e0

 2 * math:pi() 6.283185307179586e0 60 * (math:pi() div 180) Converts an angle of 60 degrees to radians. deterministic context-independent focus-independent

Returns an approximation to the mathematical constant e.

This function returns the xs:double value whose lexical representation is 2.718281828459045e0

 math:pow(math:e(), 0.05 * 3) 1.161834242728283e0

New in 4.0

 deterministic context-independent focus-independent

Returns the value of ex where x is the argument value.

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

Otherwise the result is the mathematical constant e raised to the power of $value, as defined in the specification of the exp function applied to 64-bit binary floating point values.

The treatment of overflow and underflow is defined in .

 math:exp(()) () math:exp(0) 1.0e0 math:exp(1) 2.7182818284590455e0 math:exp(2) 7.38905609893065e0 math:exp(-1) 0.36787944117144233e0 math:exp(math:pi()) 23.140692632779267e0 math:exp(xs:double('NaN')) xs:double('NaN') math:exp(xs:double('INF')) xs:double('INF') math:exp(xs:double('-INF')) 0.0e0 deterministic context-independent focus-independent

Returns the value of 10x, where x is the supplied argument value.

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

Otherwise the result is ten raised to the power of $value, as defined in the specification of the exp10 function applied to 64-bit binary floating point values.

The treatment of overflow and underflow is defined in .

 math:exp10(()) () math:exp10(0) 1.0e0 math:exp10(1) 1.0e1 math:exp10(0.5) 3.1622776601683795e0 math:exp10(-1) 1.0e-1 math:exp10(xs:double('NaN')) xs:double('NaN') math:exp10(xs:double('INF')) xs:double('INF') math:exp10(xs:double('-INF')) 0.0e0 deterministic context-independent focus-independent

Returns the natural logarithm of the argument.

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

Otherwise the result is the natural logarithm of $value, as defined in the specification of the log function applied to 64-bit binary floating point values.

The treatment of divideByZero and invalidOperation exceptions is defined in . The effect is that if the argument is zero, the result is -INF, and if it is negative, the result is NaN.

 math:log(()) () math:log(0) xs:double('-INF') math:log(math:exp(1)) 1.0e0 math:log(1.0e-3) -6.907755278982137e0 math:log(2) 0.6931471805599453e0 math:log(-1) xs:double('NaN') math:log(xs:double('NaN')) xs:double('NaN') math:log(xs:double('INF')) xs:double('INF') math:log(xs:double('-INF')) xs:double('NaN') deterministic context-independent focus-independent

Returns the base-ten logarithm of the argument.

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

Otherwise the result is the base-10 logarithm of $value, as defined in the specification of the log10 function applied to 64-bit binary floating point values.

The treatment of divideByZero and invalidOperation exceptions is defined in . The effect is that if the argument is zero, the result is -INF, and if it is negative, the result is NaN.

 math:log10(()) () math:log10(0) xs:double('-INF') math:log10(1.0e3) 3.0e0 math:log10(1.0e-3) -3.0e0 math:log10(2) 0.3010299956639812e0 math:log10(-1) xs:double('NaN') math:log10(xs:double('NaN')) xs:double('NaN') math:log10(xs:double('INF')) xs:double('INF') math:log10(xs:double('-INF')) xs:double('NaN') deterministic context-independent focus-independent

Returns the non-negative square root of the argument.

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

Otherwise the result is the mathematical non-negative square root of $value as defined in the specification of the squareRoot function applied to 64-bit binary floating point values.

The treatment of the invalidOperation exception is defined in . The effect is that if the argument is less than zero, the result is NaN.

If $value is positive or negative zero, positive infinity, or NaN, then the result is $value. (Negative zero is the only case where the result can have negative sign)

 math:sqrt(()) () math:sqrt(0.0e0) 0.0e0 math:sqrt(-0.0e0) -0.0e0 math:sqrt(1.0e6) 1.0e3 math:sqrt(2.0e0) 1.4142135623730951e0 math:sqrt(-2.0e0) xs:double('NaN') math:sqrt(xs:double('NaN')) xs:double('NaN') math:sqrt(xs:double('INF')) xs:double('INF') math:sqrt(xs:double('-INF')) xs:double('NaN') deterministic context-independent focus-independent

Returns the result of raising the first argument to the power of the second.

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

If $y is an instance of xs:integer, the result is $x raised to the power of $y as defined in the specification of the pown function applied to a 64-bit binary floating point value and an integer.

Otherwise $y is cast to an xs:double, and the result is $x raised to the power of $y as defined in the specification of the pow function applied to two 64-bit binary floating point values.

The treatment of the divideByZero and invalidOperation exceptions is defined in . Some of the consequences are illustrated in the examples below.

 math:pow((), 93.7) () math:pow(2, 3) 8.0e0 math:pow(-2, 3) -8.0e0 math:pow(2, -3) 0.125e0 math:pow(-2, -3) -0.125e0 math:pow(2, 0) 1.0e0 math:pow(0, 0) 1.0e0 math:pow(xs:double('INF'), 0) 1.0e0 math:pow(xs:double('NaN'), 0) 1.0e0 math:pow(-math:pi(), 0) 1.0e0 math:pow(0e0, 3) 0.0e0 math:pow(0e0, 4) 0.0e0 math:pow(-0e0, 3) -0.0e0 math:pow(0, 4) 0.0e0 math:pow(0e0, -3) xs:double('INF') math:pow(0e0, -4) xs:double('INF') math:pow(-0e0, -3) xs:double('-INF') math:pow(0, -4) xs:double('INF') math:pow(16, 0.5e0) 4.0e0 math:pow(16, 0.25e0) 2.0e0 math:pow(0e0, -3.0e0) xs:double('INF') math:pow(-0e0, -3.0e0) xs:double('-INF') Odd-valued whole numbers are treated specially math:pow(0e0, -3.1e0) xs:double('INF') math:pow(-0e0, -3.1e0) xs:double('INF') math:pow(0e0, 3.0e0) 0.0e0 math:pow(-0e0, 3.0e0) -0.0e0 Odd-valued whole numbers are treated specially math:pow(0e0, 3.1e0) 0.0e0 math:pow(-0e0, 3.1e0) 0.0e0 math:pow(-1, xs:double('INF')) 1.0e0 math:pow(-1, xs:double('-INF')) 1.0e0 math:pow(1, xs:double('INF')) 1.0e0 math:pow(1, xs:double('-INF')) 1.0e0 math:pow(1, xs:double('NaN')) 1.0e0 math:pow(-2.5e0, 2.0e0) 6.25e0 math:pow(-2.5e0, 2.00000001e0) xs:double('NaN') deterministic context-independent focus-independent

Returns the sine of the argument. The argument is an angle in radians.

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

Otherwise the result is the sine of $radians (which is treated as an angle in radians) as defined in the specification of the sin function applied to 64-bit binary floating point values.

The treatment of the invalidOperation and underflow exceptions is defined in .

If $radians is positive or negative zero, the result is $radians.

If $radians is positive or negative infinity, or NaN, then the result is NaN.

Otherwise the result is always in the range -1.0e0 to +1.0e0

 math:sin(()) () math:sin(0) 0.0e0 math:sin(-0.0e0) -0.0e0 math:sin(math:pi() div 2) 1.0e0 math:sin(-math:pi() div 2) -1.0e0 math:sin(math:pi()) 0.0e0 math:sin(xs:double('NaN')) xs:double('NaN') math:sin(xs:double('INF')) xs:double('NaN') math:sin(xs:double('-INF')) xs:double('NaN') deterministic context-independent focus-independent

Returns the cosine of the argument. The argument is an angle in radians.

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

If $radians is positive or negative infinity, or NaN, then the result is NaN.

Otherwise the result is the cosine of $radians (which is treated as an angle in radians) as defined in the specification of the cos function applied to 64-bit binary floating point values.

The treatment of the invalidOperation exception is defined in .

If $radians is positive or negative zero, the result is $radians.

If $radiansis positive or negative infinity, or NaN, then the result is NaN.

Otherwise the result is always in the range -1.0e0 to +1.0e0

 math:cos(()) () math:cos(0) 1.0e0 math:cos(-0.0e0) 1.0e0 math:cos(math:pi() div 2) 0.0e0 math:cos(-math:pi() div 2) 0.0e0 math:cos(math:pi()) -1.0e0 math:cos(xs:double('NaN')) xs:double('NaN') math:cos(xs:double('INF')) xs:double('NaN') math:cos(xs:double('-INF')) xs:double('NaN') deterministic context-independent focus-independent

Returns the tangent of the argument. The argument is an angle in radians.

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

Otherwise the result is the tangent of $radians (which is treated as an angle in radians) as defined in the specification of the tan function applied to 64-bit binary floating point values.

The treatment of the invalidOperation and underflow exceptions is defined in .

If $radians is positive or negative infinity, or NaN, then the result is NaN.

 math:tan(()) () math:tan(0) 0.0e0 math:tan(-0.0e0) -0.0e0 math:tan(math:pi() div 4) 1.0e0 math:tan(-math:pi() div 4) -1.0e0 1 div math:tan(math:pi() div 2) 0.0e0 Mathematically, tan(π/2) is positive infinity. But because math:pi() div 2 returns an approximation, the result of math:tan(math:pi() div 2) will be a large but finite number. 1 div math:tan(-math:pi() div 2) -0.0e0 Mathematically, tan(-π/2) is negative infinity. But because -math:pi() div 2 returns an approximation, the result of math:tan(-math:pi() div 2) will be a large but finite negative number. math:tan(math:pi()) 0.0e0 math:tan(xs:double('NaN')) xs:double('NaN') math:tan(xs:double('INF')) xs:double('NaN') math:tan(xs:double('-INF')) xs:double('NaN') deterministic context-independent focus-independent

Returns the arc sine of the argument.

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

Otherwise the result is the arc sine of $value as defined in the specification of the asin function applied to 64-bit binary floating point values. The result is in the range -π/2 to +π/2 radians.

The treatment of the invalidOperation and underflow exceptions is defined in .

If $value is positive or negative zero, the result is $value.

If $value is NaN, or if its absolute value is greater than one, then the result is NaN.

In other cases, the result is an xs:double value representing an angle θ in radians in the range -math:pi() div 2 <= θ <= math:pi() div 2.

math:asin(()) () math:asin(0) 0.0e0 math:asin(-0.0e0) -0.0e0 math:asin(1.0e0) 1.5707963267948966e0 math:asin(-1.0e0) -1.5707963267948966e0 math:asin(2.0e0) xs:double('NaN') math:asin(xs:double('NaN')) xs:double('NaN') math:asin(xs:double('INF')) xs:double('NaN') math:asin(xs:double('-INF')) xs:double('NaN') deterministic context-independent focus-independent

Returns the arc cosine of the argument.

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

Otherwise the result is the arc cosine of $value, as defined in the specification of the acos function applied to 64-bit binary floating point values. The result is in the range zero to +π radians.

The treatment of the invalidOperation exception is defined in .

If $value is NaN, or if its absolute value is greater than one, then the result is NaN.

In other cases, the result is an xs:double value representing an angle θ in radians in the range 0 <= θ <= math:pi().

math:acos(()) () math:acos(0) 1.5707963267948966e0 math:acos(-0.0e0) 1.5707963267948966e0 math:acos(1.0e0) 0.0e0 math:acos(-1.0e0) 3.141592653589793e0 math:acos(2.0e0) xs:double('NaN') math:acos(xs:double('NaN')) xs:double('NaN') math:acos(xs:double('INF')) xs:double('NaN') math:acos(xs:double('-INF')) xs:double('NaN') deterministic context-independent focus-independent

Returns the arc tangent of the argument.

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

Otherwise the result is the arc tangent of $value, as defined in the specification of the atan function applied to 64-bit binary floating point values. The result is in the range -π/2 to +π/2 radians.

The treatment of the underflow exception is defined in .

If $value is positive or negative zero, the result is $value.

If $value is NaN then the result is NaN.

In other cases, the result is an xs:double value representing an angle θ in radians in the range -math:pi() div 2 <= θ <= math:pi() div 2.

math:atan(()) () math:atan(0) 0.0e0 math:atan(-0.0e0) -0.0e0 math:atan(1.0e0) 0.7853981633974483e0 math:atan(-1.0e0) -0.7853981633974483e0 math:atan(xs:double('NaN')) xs:double('NaN') math:atan(xs:double('INF')) 1.5707963267948966e0 math:atan(xs:double('-INF')) -1.5707963267948966e0 deterministic context-independent focus-independent

Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive x-axis.

The result is the value of atan2(y, x) as defined in the specification of the atan2 function applied to 64-bit binary floating point values. The result is in the range -π to +π radians.

The treatment of the underflow exception is defined in . The following rules apply when the values are finite and non-zero, (subject to rules for overflow, underflow, and approximation).

If either argument is NaN then the result is NaN.

If $x is positive, then the value of atan2($y, $x) is atan($y div $x).

If $x is negative, then:

If $y is positive, then the value of atan2($y, $x) is atan($y div $x) + π.

If $y is negative, then the value of atan2($y, $x) is atan($y div $x) - π.

Some results for special values of the arguments are shown in the examples below.

 math:atan2(+0.0e0, 0.0e0) 0.0e0 math:atan2(-0.0e0, 0.0e0) -0.0e0 math:atan2(+0.0e0, -0.0e0) 3.141592653589793e0 math:atan2(-0.0e0, -0.0e0) -3.141592653589793e0 math:atan2(-1, 0.0e0) -1.5707963267948966e0 math:atan2(+1, 0.0e0) 1.5707963267948966e0 math:atan2(-0.0e0, -1) -3.141592653589793e0 math:atan2(+0.0e0, -1) 3.141592653589793e0 math:atan2(-0.0e0, +1) -0.0e0 math:atan2(+0.0e0, +1) +0.0e0 deterministic context-independent focus-independent

Returns the hyperbolic sine of the argument.

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

Otherwise the result is the hyperbolic sine of $value as defined in the specification of the sinh function applied to 64-bit binary floating point values.

The treatment of the overflow and underflow exceptions is defined in .

If $value is positive or negative zero, the result is $value.

If $value is positive or negative infinity, or NaN, the result is NaN.

 math:sinh(1) 1.1752011936438014e0 math:sinh(math:pi()) 11.548739357257748e0

New in 4.0

 deterministic context-independent focus-independent

Returns the hyperbolic cosine of the argument.

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

Otherwise the result is the hyperbolic cosine of $value as defined in the specification of the cosh function applied to 64-bit binary floating point values.

The treatment of the overflow exception is defined in .

If $value is positive or negative zero, the result is 1.

If $value is positive or negative infinity, the result is INF.

If $value is NaN, the result is NaN.

In other cases, the result is an xs:double in the range +1.0 to INF.

 math:cosh(0) 1.0e0 math:cosh(math:pi()) 11.591953275521519e0

New in 4.0

 deterministic context-independent focus-independent

Returns the hyperbolic tangent of the argument.

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

Otherwise the result is the hyperbolic tangent of $value as defined in the specification of the tanh function applied to 64-bit binary floating point values.

The treatment of the underflow exception is defined in .

If $value is positive or negative zero, the result is $value.

If $value is positive infinity, the result is +1.0.

If $value is negative infinity, the result is -1.0.

In other cases, the result is an xs:double in the range -1.0 to +1.0.

 math:tanh(1) 0.7615941559557649e0 math:tanh(math:pi()) 0.99627207622075e0

New in 4.0

 deterministic context-independent focus-independent

Returns an xs:string whose characters have supplied codepoints.

The function returns the string made up from the characters whose Unicode codepoints are supplied in $values. This will be the zero-length string if $values is the empty sequence.

A dynamic error is raised if any of the codepoints in $values is not a .

 codepoints-to-string((66, 65, 67, 72)) "BACH" codepoints-to-string((2309, 2358, 2378, 2325)) "अशॊक" codepoints-to-string(()) "" codepoints-to-string(0) If U+0000 is a , returns a string containing this character. Otherwise raises .

It is no longer automatically an error if the input contains a codepoint that is not valid in XML. Instead, the codepoint must be a . The set of permitted characters is , but it is recommended that all Unicode characters should be accepted.

 deterministic context-independent focus-independent

Returns the sequence of codepoints that constitute an xs:string value.

The function returns a sequence of integers, each integer being the Unicode codepoint of the corresponding character in $value.

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

 string-to-codepoints("Thérèse") 84, 104, 233, 114, 232, 115, 101 deterministic context-dependent focus-independent deterministic context-dependent focus-independent

Returns -1, 0, or 1, depending on whether the first value is less than, equal to, or greater than the second value.

The function compares two atomic items $value1 and $value2 for order, and returns the integer value -1, 0, or +1, depending on whether $value1 is less than, equal to, or greater than $value2, respectively.

This function is transitive and symmetric. For example:

If compare(A, B) returns zero, then compare(B, A) returns zero.

If compare(A, B) returns -1, then compare(B, A) returns +1.

If compare(A, B) and compare(B, C) both return -1, then compare(A, C) also returns -1.

If either $value1 or $value2 is the empty sequence, the function returns the empty sequence.

Otherwise, the result is determined as follows:

If $value1 is an instance of xs:string, xs:anyURI or xs:untypedAtomic, and if $value2 is an instance of xs:string, xs:anyURI or xs:untypedAtomic, the values are compared as strings, and the result reflects the order according to the rules of the collation that is used.

The collation is determined according to the rules in .

Using the default collation may be inappropriate for some strings, for example URIs or manufacturing part numbers. In such cases it is safest to supply "http://www.w3.org/2005/xpath-functions/collation/codepoint" explicitly as the third argument.

If both $value1 and $value2 are instances of xs:numeric, the function relies on a total order, which is defined as follows:

A value $f of type xs:float is in all cases equal to the value xs:double($f). The remaining rules therefore only consider instances of xs:double and xs:decimal.

NaN is equal to itself and less than any other value.

Negative infinity is equal to itself and less than any other value except NaN.

Positive infinity is equal to itself and greater than any other value.

Negative zero is equal to positive zero.

Other xs:double and xs:decimal values (that is, values other than the infinities, NaN, and negative zero) are ordered according to their mathematical magnitude, the comparison being done without any rounding or loss of precision. This effect can be achieved by converting xs:double values to xs:decimal using an implementation of xs:decimal that imposes no limits on precision or scale, or an implementation whose limits are such that all xs:double values can be represented precisely.

Every xs:double other than NaN and ±INF, has a mathematical value of the form m × 2^e, where m is an integer whose absolute value is less than 2^53, and e is an integer between -1075 and 970, inclusive. This is the value that is used in comparisons.

Practical difficulties arise because the typical string representations of an xs:double, such as 3.1, cannot be precisely represented by values of the form m × 2^e, but are instead converted to the best available approximation, which will often not be exactly equal to an xs:decimal expressed using the same lexical form.

If both $value1 and $value2 are instances of xs:boolean, the result is fn:compare(xs:integer($value1), xs:integer($value2))

This means that false is treated as less than true.

If $value1 is an instance of xs:hexBinary or xs:base64Binary, and if $value2 is an instance of xs:hexBinary or xs:base64Binary, then:

Let $A be the sequence of integers, in the range (0 to 255), representing the octets of $value1, in order; and let $B similarly be the sequence of integers representing the octets of $value2.

If $A is empty and $B is empty return zero.

If $A is empty and $B is not empty return -1.

Let $C be the value of fn:compare(fn:head($A), fn:head($B)).

If $C is non-zero, then return $C.

Otherwise, return the result of applying these rules recursively to fn:tail($A) and fn:tail($B)

If both $value1 and $value2 are instances of the same primitive type T, where T is one of the types xs:dateTime, xs:date, xs:time, xs:gYear, xs:gYearMonth, xs:gMonth, gMonthDay, or gDay, then:

Each of the values is converted to an xs:dateTime value as follows:

The value is considered as a tuple with seven fields (year, month, day, hours, minutes, seconds, timezone) as defined by the functions fn:year-from-dateTime, fn:month-from-dateTime, and so on.

Any absent components, other than the timezone, are substituted with the corresponding components of the xs:dateTime value 1972-01-01T00:00:00 to produce an xs:dateTime value.

If the timezone component is absent, it is substituted with the implicit timezone from the dynamic context.

The xs:dateTime 1972-01-01T00:00:00 is arbitrary. The only constraint is that the year must be a leap year (so that the xs:gYearMonth value --02-29 expands to a valid date). XSD originally chose this as the being historically the first date on which there was a leap second, but this is irrelevant as leap seconds are not supported in XDM.

The result of the function is then the result of comparing the starting instants of these two xs:dateTime values according to the algorithm defined in section 3.2.7.4 of ( Order relation on dateTime for xs:dateTime values with timezones).

If both $value1 and $value2 are instances of xs:duration, then:

Let $M1 and $M2 be the months components of the two durations, and let $S1 and $S2 be the seconds components of the two durations.

Let $C be fn:compare($M1, $M2).

If $C is non-zero, return $C.

Otherwise, return fn:compare($S1, $S2).

The result matches the real-world semantics of durations in many cases, for example:

When both values are zero-length durations.

When both values are have an equal months component (in particular when both have a zero months component).

When both values are have an equal seconds component (in particular when both have a zero seconds component).

When both values have a seconds component that is less than the number of seconds in the shortest month.

In other cases the result is well defined and well behaved (for example it is symmetric and transitive) but may be counter-intuitive. For example, one month (PT1M) is considered greater than one hundred days (PT100D).

Previous versions of this specification allowed durations to be compared only if both were instances of xs:dayTimeDuration or xs:yearMonthDuration. This requirement has been relaxed in the interests of allowing all atomic items to be sorted; in some applications the actual sort order matters little, so long as it is consistent.

If both $value1 and $value2 are instances of xs:QName, then:

Let $N1 and $N2 be the result of applying the function fn:namespace-uri-from-QName to the two values, and let $L1 and $L2 be the result of applying the function local-name-from-QName to the two values.

Let $CPC be "http://www.w3.org/2005/xpath-functions/collation/codepoint".

Let $C be fn:compare($N1, $N2, $CPC).

If $C is non-zero, return $C.

Otherwise, return fn:compare($L1, $L2, $CPC).

If both $value1 and $value2 are instances of xs:NOTATION, return fn:compare(xs:QName($value1), xs:QName($value2)).

For any other combination of types, a type error is raised. In particular, this means that an error is raised when comparing two atomic items that belong to different type families.

For numeric values, consider the xs:double value written as 0.1e0 and the xs:decimal value written as 0.1: The mathematical magnitude of this xs:double value is 0.1000000000000000055511151231257827021181583404541015625. Therefore, compare(0.1e0, 0.1) returns +1. By contrast, 0.1e0 lt 0.1 is false and 0.1e0 eq 0.1 is true, because those expressions convert the xs:decimal value 0.1 to the xs:double value 0.1e0 before the comparison.

Although operations such as sorting and the fn:min and fn:max functions invoke fn:compare to perform numeric comparison, these functions in some cases treat NaN differently.

 compare('abc', 'abc') 0 compare('Strasse', 'Straße') -1 compare('Strasse', 'Straße') 0 Assuming the default collation equates ss and the German letter ß. compare( 'Strasse', 'Straße', collation({ 'lang': 'de', 'strength': 'primary' }) ) 0 The specified collation equates ss and the German letter ß. text'))]]> 0 compare(9, 10) -1 compare(123, 123.0) 0 compare(xs:double('NaN'), xs:float('NaN')) 0 compare(xs:double('NaN'), xs:double('-INF')) -1 compare(xs:double('-INF'), -23) -1 compare(1, 1e0) 0 compare(1.1, 1.1e0) -1 compare(1.2, 1.2e0) +1 compare(9999, xs:double('INF')) -1 compare(false(), true()) -1 compare(xs:hexBinary(''), xs:base64Binary('')) 0 compare(xs:hexBinary('0001'), xs:hexBinary('0002')) -1 compare(xs:hexBinary('00FF'), xs:hexBinary('FF')) -1 compare(xs:time('23:59:59'), xs:time('00:00:00')) 1 compare(xs:time('12:00:00Z'), xs:time('13:00:00+01:00')) 0 compare(xs:date('2001-01-01+01:00'), xs:date('2001-01-01+00:00')) -1 compare(xs:duration('P1Y'), xs:duration('P13M')) -1 compare(xs:duration('P1Y'), xs:duration('P1Y3M4D')) -1 compare(xs:duration('P1Y'), xs:duration('P1000D')) +1 compare(#space, #xml:space) -1 compare(#Q{http://example.com/ns}index, #Q{http://example.com/ns}xmp:index) 0

The function has been expanded in scope to handle comparison of values other than strings.

The spec has been corrected to note that the function depends on the implicit timezone.

 deterministic context-independent focus-independent

Returns true if two strings are equal, considered codepoint-by-codepoint.

If either argument is the empty sequence, the function returns the empty sequence.

Otherwise, the function returns true or false depending on whether $value1 is equal to $value2, according to the Unicode codepoint collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

This function allows xs:anyURI values to be compared without having to specify the Unicode codepoint collation.

 codepoint-equal("abcd", "abcd") true() codepoint-equal("abcd", "abcd ") false() codepoint-equal("", "") true() codepoint-equal("", ()) () codepoint-equal((), ()) () The two-argument form of this function defines the semantics of the || operator. deterministic context-independent focus-independent variadic

Returns the concatenation of the arguments, treated as sequences of strings.

Unlike all other functions, this function is defined to be variadic, as indicated by the ellipsis in the function signature. Conceptually, there is an infinite set of functions with different numbers of arguments (minimum arity zero, maximum arity unbounded):

concat() returns a zero-length string, "".

concat("a") returns "a".

concat("a", "b") returns "ab".

concat("a", "b", "c") returns "abc".

concat("a", "b", "c", "d") returns "abcd".

and so on.

It is equally possible to supply a single argument containing a sequence of strings:

concat(()) returns a zero-length string, "".

concat(("a")) returns "a".

concat(("a", "b")) returns "ab".

concat(("a", "b", "c")) returns "abc".

concat(("a", "b", "c", "d")) returns "abcd".

and so on.

More generally, any argument can be a sequence of strings:

concat(("a", "b"), "c") returns "abc".

concat(("a", "b"), (), ("c", "d")) returns "abcd".

A static call on the fn:concat function must use positional arguments, it cannot use keywords.

Each of the parameters has the required type xs:anyAtomicType*. The coercion rules ensure that each supplied argument is first converted to a sequence of atomic items by applying atomization. These sequences are then combined (by sequence concatenation) into a single sequence, and each item in the combined sequence is converted to a string using the fn:string function. The strings are then concatenated with no separator.

If XPath 1.0 compatibility mode is set to true in the static context of a static function call to fn:concat, then each supplied argument $v is first reduced to a single string, the result of the expression xs:string($v[1]). This rule applies only to static function calls.

A named function reference can be used to create a function item with any arity: for example concat#3 returns a function item that takes three arguments, which it concatenates. Similarly partial function application can be used to construct a function that concatenates fixed and variable values: for example concat('[', ?, ']') returns a function item that takes a single argument and wraps the string value of this argument in square brackets. Similarly, concat(?, '-', ?) returns a function item of arity two; it returns the string values of the two arguments separated by a hyphen.

As mentioned in Unicode normalization is not automatically applied to the result of fn:concat. If a normalized result is required, fn:normalize-unicode can be applied to the xs:string returned by fn:concat. The following XQuery:

let $v1 := "I plan to go to Mu" let $v2 := "?nchen in September" return concat($v1, $v2)

where the ? represents either the actual Unicode character U+0308 or the numeric character reference &#x0308;, will return:

"I plan to go to Mu?nchen in September"

where the ? again represents either the actual Unicode character U+0308 or the numeric character reference &#x0308;. It is worth noting that the returned value is not normalized in NFC; however, it is normalized in NFD.

However, the following XQuery:

let $v1 := "I plan to go to Mu" let $v2 := "?nchen in September" return normalize-unicode(concat($v1, $v2))

where ? represents either the actual Unicode character U+0308 or the numeric character reference &#x0308;, will return:

"I plan to go to München in September"

This returned result is normalized in NFC.

Alternatives to the fn:concat function include the concatenation operator || (for example $x || '-' || $y), the use of string templates (for example `{ $x }-{ $y }`), and the fn:string-join function.

 concat('un', 'grateful') "ungrateful" concat(('un', 'grateful')) "ungrateful" concat( 'Thy ', (), 'old ', "groans", "", ' ring', ' yet', ' in', ' my', ' ancient',' ears.' ) "Thy old groans ring yet in my ancient ears." concat('Ciao!', ()) "Ciao!" concat('Ingratitude, ', 'thou ', ('marble-hearted', ' fiend!')) "Ingratitude, thou marble-hearted fiend!" concat(01, 02, 03, 04, true()) "1234true" concat() "" 10 || '/' || 6 "10/6"

The function can now take any number of arguments (previously it had to be two or more), and the arguments can be sequences of strings rather than single strings.

 deterministic context-independent focus-independent

Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items.

The coercion rules ensure that the supplied $values argument is first converted to a sequence of atomic items by applying atomization.

The function then returns an xs:string created by casting each item in the atomized sequence to an xs:string, and then concatenating the result strings in order, using the value of $separator as a separator between adjacent strings. If $separator is the zero-length string, then the items in $values are concatenated without a separator.

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

 string-join(1 to 9) "123456789" string-join(('Now', 'is', 'the', 'time', '...'), ' ') "Now is the time ..." string-join( ('Blow, ', 'blow, ', 'thou ', 'winter ', 'wind!'), '' ) "Blow, blow, thou winter wind!" string-join((), 'separator') "" string-join(1 to 5, ', ') "1, 2, 3, 4, 5" <doc><chap><section xml:id="xyz"/></chap></doc> $doc//@xml:id ! string-join((node-name(), '="', ., '"')) 'xml:id="xyz"' $doc//section ! string-join(ancestor-or-self::*/name(), '/') "doc/chap/section" deterministic context-independent focus-independent

Returns the part of $value beginning at the position indicated by $start and continuing for the number of characters indicated by $length.

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

Otherwise, the function returns a string comprising those characters of $value whose index position (counting from one) is greater than or equal to $start (rounded to an integer), and (if $length is non-empty) less than the sum of $start and $length (both rounded to integers).

The characters returned do not extend beyond $value. If $start is zero or negative, only those characters in positions greater than zero are returned.

More specifically, the three argument version of the function returns the characters in $value whose position $p satisfies:

fn:round($start) <= $p and $p < fn:round($start) + fn:round($length)

The two argument version of the function assumes that $length is infinite and thus returns the characters in $value whose position $p satisfies:

fn:round($start) <= $p

In the above computations, the operators such as <= and + are evaluated according to the rules of the XPath 4.0 specification.

The first character of a string is located at position 1, not position 0.

A surrogate pair counts as one character, not two.

The most common usage pattern is to supply integers as the arguments. In this case the rounding logic is unnecessary: substring($value, $start) returns all characters in $value starting at position $start (one-based), while substring($value, $start, $length) returns the substring starting at position $start and ending at position $start + $length - 1.

In earlier versions the second and third arguments were defined to be of type xs:double, but this potentially leads to unnecessary conversions in the common case where the supplied arguments are integers. The reason for the rounding rules is to compensate for any imprecision in the resulting floating-point computations.

The consequences of supplying values such as NaN or positive or negative infinity for the $start or $length arguments follow from the above rules, and are not always intuitive.

 substring("motor car", 6) " car" Characters starting at position 6 to the end of $sourceString are selected.

substring("metadata", 4, 3) "ada" Characters at positions greater than or equal to 4 and less than 7 are selected. substring("12345", 1.5, 2.6) "234" Characters at positions greater than or equal to 2 and less than 5 are selected. substring("12345", 0, 3) "12" Characters at positions greater than or equal to 0 and less than 3 are selected. Since the first position is 1, these are the characters at positions 1 and 2. substring("12345", 5, -3) "" Characters at positions greater than or equal to 5 and less than 2 are selected. substring("12345", -3, 5) "1" Characters at positions greater than or equal to -3 and less than 2 are selected. Since the first position is 1, this is the character at position 1. substring("12345", 0 div 0E0, 3) "" Since 0 div 0E0 returns NaN, and NaN compared to any other number returns false, no characters are selected. substring("12345", 1, 0 div 0E0) "" As above. substring((), 1, 3) "" substring("12345", -42, 1 div 0E0) "12345" Characters at positions greater than or equal to -42 and less than INF are selected. substring("12345", -1 div 0E0, 1 div 0E0) "" Since the value of -INF + INF is NaN, no characters are selected.

The third argument can now be supplied as the empty sequence.

The argument type for the second and third arguments has changed from xs:double to xs:numeric. This creates a minor incompatibility: when running in XPath 1.0 compatibility mode, it is no longer possible to supply either of these arguments as a string.

 deterministic context-dependent focus-dependent deterministic context-independent focus-independent

Returns the number of characters in a string.

If $value is the empty sequence, the function returns the xs:integer value 0. Otherwise, the value is cast to an xs:string, and an xs:integer is returned that reflects the number of characters in the string.

If $value is not specified and the context value is absent, a type error is raised: .

As a consequence of the rules given above, a type error is raised 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.

Unlike some programming languages, a codepoint greater than 65535 counts as one character, not two.

There are situations where fn:string-length() has a different effect from fn:string-length(.). These situations all involve nodes with non-trivial type annotations. For example:

If the context value is an attribute node typed as an xs:integer with the string value 000001, then fn:string-length() returns 6 (the length of the string value of the node), while fn:string-length(.) returns 1 (the length of the string that results from converting the typed value (1) to a string). In earlier versions of this specification this call would have failed with a type error.

If the context value is the element node NN ]]>, and has the type annotation xs:NCName, then fn:string-length() returns 4 (the length of the string value of the element node), while fn:string-length(.) returns 2 (the length of the typed value of the element node).

If the context value is the attribute node ref="A B C", and has the type annotation xs:IDREFS, then fn:string-length() returns 5 (the length of the string value of the attribute node), while fn:string-length(.) raises an error, because the atomized value of the attribute is a sequence of strings, and calling the fn:string function on a sequence of strings fails.

 string-length( "As long as a piece of string" ) 28 "ᾧ" => string-length() 1 "ᾧ" => normalize-unicode("NFD") => string-length() 4 For strings that consist of a base character with combining characters, each combining character is length 1. string-length(()) 0

The type of $value has been generalized to xs:anyAtomicType?.

 deterministic context-dependent focus-dependent deterministic context-independent focus-independent

Returns $value with leading and trailing whitespace removed, and sequences of internal whitespace reduced to a single space character.

If $value is the empty sequence, the function returns a zero-length string. Otherwise, the value is cast to an xs:string, and a new string is constructed by stripping leading and trailing whitespace from the string, and by replacing sequences of one or more adjacent whitespace characters with a single space, U+0020.

The whitespace characters are defined in the metasymbol S (Production 3) of .

If no argument is supplied and the context value is absent, a type error is raised .

As a consequence of the rules given above, a type error is raised 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.

The definition of whitespace is unchanged in . It is repeated here for convenience:

S ::= (#x20 | #x9 | #xD | #xA)+

There are situations where fn:normalize-space() has a different effect from fn:normalize-space(.). These situations all involve nodes with non-trivial type annotations. For example:

If the context value is an attribute node typed as an xs:integer with the string value 000001, then fn:normalize-space() returns "000001" (the string value of the node, whitespace-normalized), while fn:normalize-space(.) returns "1" (the typed value of the node, converted to a string and then normalized).

If the context value is the attribute node ref=" A B C ", and has the type annotation xs:IDREFS, then fn:normalize-space() returns "A B C" (the string value of the attribute node, whitespace-normalized), while fn:normalize-space(.) raises an error, because the typed value of the attribute is a sequence of strings, and calling the fn:string function on a sequence of strings fails.

The effect of fn:normalize-space is exactly the same as the effect of the whitespace=collapse facet in XSD. Since this facet is implicit for most XSD data types (with the notable exception of xs:string itself), nodes that are validated against types other than xs:string will tend to be implicitly in the form that normalize-string generates. Confusingly, the XSD type xs:normalizedString uses the facet whitespace=replace, which does not have the same effect as the normalize-space function: it replaces all whitespace characters by U+0020, but does not remove leading or trailing spaces, nor does it merge adjacent spaces.

 normalize-space(" The wealthy curled darlings of our nation. ") "The wealthy curled darlings of our nation." normalize-space(()) ""

The type of $value has been generalized to xs:anyAtomicType?.

 deterministic context-independent focus-independent

Returns $value after applying Unicode normalization.

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

Otherwise, the function returns $value normalized according to the rules of the normalization form identified by the value of $form.

The effective value of $form is the value of the expression fn:upper-case(fn:normalize-space($form)).

If the effective value of $form is NFC, then the function returns $value converted to Unicode Normalization Form C (NFC).

If the effective value of $form is NFD, then the function returns $value converted to Unicode Normalization Form D (NFD).

If the effective value of $form is NFKC, then the function returns $value in Unicode Normalization Form KC (NFKC).

If the effective value of $form is NFKD, then the function returns $value converted to Unicode Normalization Form KD (NFKD).

If the effective value of $form is FULLY-NORMALIZED, then the function returns $value converted to fully normalized form.

If the effective value of $form is the zero-length string, no normalization is performed and $value is returned.

Normalization forms NFC, NFD, NFKC, and NFKD, and the algorithms to be used for converting a string to each of these forms, are defined in .

The motivation for normalization form FULLY-NORMALIZED is explained in . However, as that specification did not progress beyond working draft status, the normative specification is as follows:

A string is fully-normalized if (a) it is in normalization form NFC as defined in , and (b) it does not start with a composing character.

A composing character is a character that is one or both of the following:

the second character in the canonical decomposition mapping of some character that is not listed in the Composition Exclusion Table defined in ;

of non-zero canonical combining class (as defined in ).

A string is converted to FULLY-NORMALIZED form as follows:

if the first character in the string is a composing character, prepend a single space (x20);

convert the resulting string to normalization form NFC.

Conforming implementations must support normalization form NFC and may support normalization forms NFD, NFKC, NFKD, and FULLY-NORMALIZED. They may also support other normalization forms with implementation-defined semantics.

It is implementation-defined which version of Unicode (and therefore, of the normalization algorithms and their underlying data) is supported by the implementation. See for details of the stability policy regarding changes to the normalization rules in future versions of Unicode. If the input string contains codepoints that are unassigned in the relevant version of Unicode, or for which no normalization rules are defined, the fn:normalize-unicode function leaves such codepoints unchanged. If the implementation supports the requested normalization form then it must be able to handle every input string without raising an error.

A dynamic error is raised if the effective value of the $form argument is not one of the values supported by the implementation.

 deterministic context-independent focus-independent

Converts a string to upper case.

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

Otherwise, the function returns $value after translating every character to its upper-case correspondent as defined in the appropriate case mappings section in the Unicode standard . For versions of Unicode beginning with the 2.1.8 update, only locale-insensitive case mappings should be applied. Beginning with version 3.2.0 (and likely future versions) of Unicode, precise mappings are described in default case operations, which are full case mappings in the absence of tailoring for particular languages and environments. Every lower-case character that does not have an upper-case correspondent, as well as every upper-case character, is included in the returned value in its original form.

Case mappings may change the length of a string. In general, the fn:upper-case and fn:lower-case functions are not inverses of each other: fn:lower-case(fn:upper-case($s)) is not guaranteed to return $s, nor is fn:upper-case(fn:lower-case($s)). The character U+0131 (used in Turkish) is perhaps the most prominent lower-case letter which will not round-trip. The character U+0130 is the most prominent upper-case letter which will not round trip; there are others, such as U+1E9E, which was introduced in Unicode 5.1.

These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.

Because the function is not sensitive to locale, results will not always match user expectations. In Quebec, for example, the standard uppercase equivalent of è is È, while in metropolitan France it is more commonly E; only one of these is supported by the functions as defined.

Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.

 upper-case("abCd0") "ABCD0" deterministic context-independent focus-independent

Converts a string to lower case.

If t$value is the empty sequence, the zero-length string is returned.

Otherwise, the function returns $value after translating every character to its lower-case correspondent as defined in the appropriate case mappings section in the Unicode standard . For versions of Unicode beginning with the 2.1.8 update, only locale-insensitive case mappings should be applied. Beginning with version 3.2.0 (and likely future versions) of Unicode, precise mappings are described in default case operations, which are full case mappings in the absence of tailoring for particular languages and environments. Every upper-case character that does not have a lower-case correspondent, as well as every lower-case character, is included in the returned value in its original form.

Case mappings may change the length of a string. In general, the fn:upper-case and fn:lower-case functions are not inverses of each other: fn:lower-case(fn:upper-case($s)) is not guaranteed to return $s, nor is fn:upper-case(fn:lower-case($s)). The character U+0131 (used in Turkish) is perhaps the most prominent lower-case letter which will not round-trip. The character U+0130 is the most prominent upper-case letter which will not round trip; there are others, such as U+1E9E, which was introduced in Unicode 5.1.

These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.

Because the function is not sensitive to locale, results will not always match user expectations. In Quebec, for example, the standard uppercase equivalent of è is È, while in metropolitan France it is more commonly E; only one of these is supported by the functions as defined.

Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.

 lower-case("ABc!D") "abc!d" deterministic context-independent focus-independent

Returns $value modified by replacing or removing individual characters.

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

Otherwise, the function returns a result string constructed by processing each character in $value, in order, according to the following rules:

If the character does not appear in $replace then it is added to the result string unchanged.

If the character first appears in $replace at some position M, where the value of $with is M or more characters in length, then the character at position M in $with is added to the result string.

If the character first appears in $replace at some position M, where $with is less than M characters in length, then the character is omitted from the result string.

If $replace is the zero-length string then the function returns $value unchanged.

If a character occurs more than once in $replace, then the first occurrence determines the action taken.

If $with is longer than $replace, the excess characters are ignored.

 translate("bar", "abc", "ABC") "BAr" translate("--aaa--", "abc-", "ABC") "AAA" translate("abcdabc", "abc", "AB") "ABdAB" deterministic context-independent focus-independent

Returns the results of a specified hash, checksum, or cyclic redundancy check function applied to the input.

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

If $value is an instance of xs:string, it is converted to a sequence of octets on the basis of UTF-8 encoding. If $value is an instance of xs:base64Binary or xs:hexBinary, it is converted to a sequence of octets.

The $algorithm argument determines the algorithm to be used to calculate a checksum, hash, or cyclic redundancy check. The effective value of $algorithm is the value of the expression fn:upper-case(fn:normalize-space($algorithm)).

Conforming implementations must support the following options and the functions referred to by them:

MD5: the MD5 Message-Digest algorithm, defined by (update to ).

SHA-1: the SHA-1 algorithm, defined by .

SHA-256: the SHA-256 algorithm, defined by .

BLAKE3: the BLAKE3 algorithm defined by .

CRC-32: the CRC-32 algorithm, defined by . It delivers a 32 bit unsigned integer, which this function returns as a 4-octet xs:hexBinary value representing this integer in big-endian order (that is, most significant byte first).

Some libraries, notably System.IO.Hashing.Crc32 in .NET, return the result in little-endian order.

Conforming implementations may support other checksum and hash functions with implementation-defined semantics. The $options argument, if present, defines additional parameters controlling how the process is conducted.

The function returns as xs:hexBinary the octets returned by passing $value as an octet sequence through the selected algorithm. The process is followed even if the input octet sequence is empty.

A dynamic error is raised if the effective value of $algorithm is not one of the values supported by the implementation.

It is common for secure algorithms to be cryptographically broken, as has happened to the algorithms MD5, SHA-1, and SHA-256. And the CRC-32 algorithm is not intended for cryptographic purposes. Developers are responsible for ensuring that the algorithm chosen meets any expected security protocols, if relevant.

The BLAKE3 algorithm is included in the list of hashing algorithms because at the time of writing it appears to be a promising candidate as a secure and fast algorithm that shows signs of gaining widespread support. However, this is a fast moving field and the community group recognizes that this decision might eventually not stand the test of time. As the technology evolves in the future, implementations are free to drop support for this algorithm and substitute another that appears to better meet requirements.

Additional security practices, such as salting, may be applied as a preprocessing step, or fn:hash() can be incorporated into more complex functions.

In most cases, the xs:hexBinary output of the function will be sought in string form. Because of serialization rules, casting to a string renders the hash in uppercase, and rendering in lowercase (as adopted by and ) requires further adjustment.

 abc]]> hash("abc") xs:hexBinary("900150983CD24FB0D6963F7D28E17F72") hash("ABC") xs:hexBinary("902FBDD2B1DF0C4F70B4A5D23525E932") hash("") xs:hexBinary("D41D8CD98F00B204E9800998ECF8427E") hash("ABC", "SHA-1") xs:hexBinary("3C01BDBB26F358BAB27F267924AA2C9A03FCFDB8") hash("ABC", "BLAKE3") => string() => lower-case() "d1717274597cf0289694f75d96d444b992a096f1afd8e7bbfa6ebb1d360fedfc" hash("ABC", "BLAKE3") => xs:base64Binary() => string() "0XFydFl88CiWlPddltREuZKglvGv2Oe7+m67HTYP7fw=" hash("ABC", "sha-256") => string() "B5D4045C3F466FA91FE2CC6ABE79232A1A57CDF104F7A26E716E0A1E2789DF78" hash("ABC", "sha-256") xs:hexBinary("B5D4045C3F466FA91FE2CC6ABE79232A1A57CDF104F7A26E716E0A1E2789DF78") hash($doc) xs:hexBinary("900150983CD24FB0D6963F7D28E17F72") hash(serialize($doc), "sha-1") => xs:base64Binary() => string() "8PzN28NtxQv5RlxQ5/w6DcnrpEU=" hash("password123" || $salt, "SHA-256") xs:hexBinary("9C9B913EB1B6254F4737CE947EFD16F16E916F9D6EE5C1102A2002E48D4C88BD") hash("", "CRC-32") xs:hexBinary("00000000") hash("input", "CRC-32") xs:hexBinary("D82832D7") hash("password123", "sha-unknown")

New in 4.0

 deterministic context-independent focus-independent

Encodes reserved characters in a string that is intended to be used in the path segment of a URI.

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

This function applies the URI escaping rules defined in section 2 of to the xs:string supplied as $value. The effect of the function is to escape reserved characters. Each such character in the string is replaced with its percent-encoded form as described in .

Since recommends that, for consistency, URI producers and normalizers should use uppercase hexadecimal digits for all percent-encodings, this function must always generate hexadecimal values using the upper-case letters A-F.

All characters are escaped except those identified as “unreserved” by , that is the upper- and lower-case letters A to Z, the digits 0 to 9, HYPHEN-MINUS (-), LOW LINE (_), FULL STOP (.), and TILDE (~).

This function escapes URI delimiters and therefore cannot be used indiscriminately to encode “invalid” characters in a path segment.

This function is invertible but not idempotent. This is because a string containing a percent character will be modified by applying the function: for example 100% becomes 100%25, while 100%25 becomes 100%2525.

 encode-for-uri( "http://example.com/00/Weather/CA/Los%20Angeles#ocean" ) "http%3A%2F%2Fexample.com%2F00%2FWeather%2FCA%2FLos%2520Angeles%23ocean" This is probably not what the user intended because all of the delimiters have been encoded. concat( "http://example.com/", encode-for-uri("~bébé") ) "http://example.com/~b%C3%A9b%C3%A9" concat( "http://example.com/", encode-for-uri("100% organic") ) "http://example.com/100%25%20organic" deterministic context-independent focus-independent

Decodes URI-escaped characters in a string.

This function returns the original representation of a URI-escaped string.

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

Otherwise, the value is first converted to a sequence of octets. Any substring that matches the regular expression %[a-fA-F0-9][a-fA-F0-9] is replaced with an octet for the two-digit hexadecimal number that follows the percent sign. Characters that are not part of such a substring are replaced with the octets of their UTF-8 encoding. For example, "A%42%20C" results in the octets x41, x42, x20, x43, and "💡" yields xF0, x9F, x92, and xA1.

If % is followed by up to two characters that are not hexadecimal digits, these characters are replaced by octets xEF, xBF, and xBD, that is, the UTF-8 encoding of the Unicode replacement character (U+FFFD). For example, the incomplete or invalid percent-encoded strings "%", "%X", "%AX", and "%XA" are all replaced with these octets. For the string "%1X!", the octets xEF, xBF, xBD, and x21 are returned.

Next, the resulting octets are interpreted as UTF-8. For example, x41, x42, x20, and x43 becomes "AB C", and xF0, x9F, x92, and xA1 becomes "💡".

If an invalid UTF-8 octet sequence is encountered, the octets that have successfully been parsed are replaced with a Unicode replacement character. Examples:

The single octet xF0 is converted to "�".

The octets xF0, x9F, x92, and x41 are converted to "�A": The bit pattern of the first octet indicates that the UTF-8 character comprises four octets. As the fourth octet is invalid, a Unicode replacement character is added for the first three octets, and the fourth (invalid) octet is parsed as a new character.

Similarly, the octets xF0, xF0, x9F, x92, and xA1 are converted to "�💡": The second octet is invalid, but it becomes valid when being parsed as the first octet of the remaining UTF-8 sequence.

Similarly, a UTF-8 octet sequence that represents a codepoint that is not a valid XML character is replaced with a Unicode replacement character. For example, x00 becomes "�".

 decode-from-uri("http://example.com/") "http://example.com/" decode-from-uri("~b%C3%A9b%C3%A9?a=b+c") "~bébé?a=b+c" decode-from-uri(translate("~b%C3%A9b%C3%A9?a=b+c", "+", " ")) "~bébé?a=b c" Plus signs can be replaced before decoding to follow the conventions of the application/x-www-form-urlencoded media type, which fn:parse-uri applies to query parameters. decode-from-uri("%00-%XX-%F0%9F%92%41-%F0%F0%9F%92%A1") "�-�-�A-�💡"

Plus signs are no longer decoded as spaces.

New in 4.0

 deterministic context-independent focus-independent

Converts a string containing an IRI into a URI according to the rules of .

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

Otherwise, the function converts $value into a URI according to the rules given in Section 3.1 of by percent-encoding characters that are allowed in an IRI but not in a URI. If $value contains a character that is invalid in an IRI, such as the space character (see note below), the invalid character is replaced by its percent-encoded form as described in before the conversion is performed.

Since recommends that, for consistency, URI producers and normalizers should use uppercase hexadecimal digits for all percent-encodings, this function must always generate hexadecimal values using the upper-case letters A-F.

The function is idempotent but not invertible. Both the inputs My Documents and My%20Documents will be converted to the output My%20Documents.

This function does not check whether $iri is a valid IRI. It treats it as an string and operates on the characters in the string.

The following printable ASCII characters are invalid in an IRI: <, >, ", , {, }, |, \, ^, and `. Since these characters should not appear in an IRI, if they do appear in $iri they will be percent-encoded. In addition, characters outside the range U+0020 to U+007E will be percent-encoded because they are invalid in a URI.

Since this function does not escape the character U+0025 and this character is not allowed in data within a URI, users wishing to convert character strings (such as file names) that include % to a URI should manually escape % by replacing it with %25.

iri-to-uri( "http://www.example.com/00/Weather/CA/Los%20Angeles#ocean" ) "http://www.example.com/00/Weather/CA/Los%20Angeles#ocean" iri-to-uri("http://www.example.com/~bébé") "http://www.example.com/~b%C3%A9b%C3%A9" deterministic context-independent focus-independent

Escapes a URI in the same way that HTML user agents handle attribute values expected to contain URIs.

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

Otherwise, the function escapes all characters except printable characters of the US-ASCII coded character set, specifically the codepoints between 32 and 126 (decimal) inclusive. Each character in $value to be escaped is replaced by an escape sequence, which is formed by encoding the character as a sequence of octets in UTF-8, and then representing each of these octets in the form %HH, where HH is the hexadecimal representation of the octet. This function must always generate hexadecimal values using the upper-case letters A-F.

The behavior of this function corresponds to the recommended handling of non-ASCII characters in URI attribute values as described in Appendix B.2.1.

 escape-html-uri( "http://www.example.com/00/Weather/CA/Los Angeles#ocean" ) "http://www.example.com/00/Weather/CA/Los Angeles#ocean" escape-html-uri( "javascript:if (navigator.browserLanguage == 'fr') window.open('http://www.example.com/~bébé');" ) "javascript:if (navigator.browserLanguage == 'fr') window.open('http://www.example.com/~b%C3%A9b%C3%A9');" deterministic context-dependent focus-independent deterministic context-dependent focus-independent

Returns true if the string $value contains $substring as a substring, taking collations into account.

If $value or $substring is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.

If $substring is the zero-length string, then the function returns true.

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

The collation used by this function is determined according to the rules in .

The function returns an xs:boolean indicating whether or not $value contains (at the beginning, at the end, or anywhere within) at least one sequence of collation units that provides a to the collation units in $substring, according to the collation that is used.

A dynamic error may be raised if the specified collation does not support collation units.

The collation used in some of these examples, $coll, is a collation in which both - and * are ignorable collation units.

“Ignorable collation unit” is equivalent to “ignorable collation element” in .

 contains("tattoo", "t") true() contains("tattoo", "ttt") false() contains("", ()) true() The first rule is applied, followed by the second rule. "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" contains( "abcdefghi", "-d-e-f-", $coll ) true() contains( "a*b*c*d*e*f*g*h*i*", "d-ef-", $coll ) true() contains( "abcd***e---f*--*ghi", "def", $coll ) true() contains( (), "--***-*---", $coll ) true() The second argument contains only ignorable collation units and is equivalent to the zero-length string. deterministic context-dependent focus-independent deterministic context-dependent focus-independent

Returns true if the string $value contains $substring as a leading substring, taking collations into account.

If $value or $substring is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.

If $substring is the zero-length string, then the function returns true. If $value is the zero-length string and $substring is not the zero-length string, then the function returns false.

The collation used by this function is determined according to the rules in .

The function returns an xs:boolean indicating whether or not $value starts with a sequence of collation units that provides a to the collation units of $substring according to the collation that is used.

A dynamic error may be raised if the specified collation does not support collation units.

The collation used in some of these examples, $coll, is a collation in which both - and * are ignorable collation units.

“Ignorable collation unit” is equivalent to “ignorable collation element” in .

 starts-with("tattoo", "tat") true() starts-with("tattoo", "att") false() starts-with((), ()) true() "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" starts-with( "abcdefghi", "-a-b-c-", $coll ) true() starts-with( "a*b*c*d*e*f*g*h*i*", "a-bc-", $coll ) true() starts-with( "abcd***e---f*--*ghi", "abcdef", $coll ) true() starts-with( (), "--***-*---", $coll ) true() The second argument contains only ignorable collation units and is equivalent to the zero-length string. starts-with( "-abcdefghi", "-abc", $coll ) true() deterministic context-dependent focus-independent deterministic context-dependent focus-independent

Returns true if the string $value contains $substring as a trailing substring, taking collations into account.

If $value or $substring is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.

If $substring is the zero-length string, then the function returns true. If $value is the zero-length string and the value of $substring is not the zero-length string, then the function returns false.

The collation used by this function is determined according to the rules in .

The function returns an xs:boolean indicating whether or not $value ends with a sequence of collation units that provides a to the collation units of $substring according to the collation that is used.

A dynamic error may be raised if the specified collation does not support collation units.

The collation used in some of these examples, $coll, is a collation in which both - and * are ignorable collation units.

“Ignorable collation unit” is equivalent to “ignorable collation element” in .

 ends-with("tattoo", "tattoo") true() ends-with("tattoo", "atto") false() ends-with((), ()) true() "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ends-with( "abcdefghi", "-g-h-i-", $coll ) true() ends-with( "abcd***e---f*--*ghi", "defghi", $coll ) true() ends-with( "abcd***e---f*--*ghi", "defghi", $coll ) true() ends-with( (), "--***-*---", $coll ) true() The second argument contains only ignorable collation units and is equivalent to the zero-length string. ends-with( "abcdefghi", "ghi-", $coll ) true() deterministic context-dependent focus-independent deterministic context-dependent focus-independent

Returns the part of $value that precedes the first occurrence of $substring, taking collations into account.

If $value or $substring is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.

If $substring is the zero-length string, then the function returns the zero-length string.

If $value does not contain a string that is equal to $substring, then the function returns the zero-length string.

The collation used by this function is determined according to the rules in .

The function returns the substring of $value that precedes in $value the first occurrence of a sequence of collation units that provides a to the collation units of $substring according to the collation that is used.

A dynamic error may be raised if the specified collation does not support collation units.

The collation used in some of these examples, $coll, is a collation in which both - and * are ignorable collation units.

“Ignorable collation unit” is equivalent to “ignorable collation element” in .

 substring-before("tattoo", "attoo") "t" substring-before("tattoo", "tatto") "" substring-before((), ()) "" "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" substring-before( "abcdefghi", "--d-e-", $coll ) "abc" substring-before( "abc--d-e-fghi", "--d-e-", $coll ) "abc--" substring-before( "a*b*c*d*e*f*g*h*i*", "***cde", $coll ) "a*b*" substring-before( "Eureka!", "--***-*---", $coll ) "" The second argument contains only ignorable collation units and is equivalent to the zero-length string. deterministic context-dependent focus-independent deterministic context-dependent focus-independent

Returns the part of $value that follows the first occurrence of $substring, taking collations into account.

If $value or $substring is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.

If $substring is the zero-length string, then the function returns the value of $value.

If $value does not contain a string that is equal to $substring, then the function returns the zero-length string.

The collation used by this function is determined according to the rules in .

The function returns the substring of $value that follows in $value the first occurrence of a sequence of collation units that provides a to the collation units of $substring according to the collation that is used.

A dynamic error may be raised if the specified collation does not support collation units.

The collation used in some of these examples, $coll, is a collation in which both - and * are ignorable collation units.

“Ignorable collation unit” is equivalent to “ignorable collation element” in .

 substring-after("tattoo", "tat") "too" substring-after("tattoo", "tattoo") "" substring-after((), ()) "" "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" substring-after( "abcdefghi", "--d-e-", $coll ) "fghi" substring-after( "abc--d-e-fghi", "--d-e-", $coll ) "-fghi" substring-after( "a*b*c*d*e*f*g*h*i*", "***cde***", $coll ) "*f*g*h*i*" substring-after( "Eureka!", "--***-*---", $coll ) "Eureka!" The second argument contains only ignorable collation units and is equivalent to the zero-length string. deterministic context-independent focus-independent

Returns true if the supplied string matches a given regular expression.

If $value is the empty sequence, it is interpreted as the zero-length string.

Flags are defined in .

The function returns true if the set of obtained by matching $value against the regular expression $pattern, with the associated $flags, is non-empty. Otherwise, the function returns false.

A dynamic error is raised if $pattern is invalid according to the rules described in .

A dynamic error is raised if $flags is invalid according to the rules described in .

Unless the metacharacters ^ and $ are used as anchors, the string is considered to match the pattern if any substring matches the pattern. But if anchors are used, the anchors must match the start/end of the string (in string mode), or the start/end of a line (in multi-line mode).

This is different from the behavior of patterns in , where regular expressions are implicitly anchored.

Regular expression matching is defined on the basis of Unicode codepoints; it takes no account of collations.

It is valid for the regular expression to match a zero-length segment of $value. For example, the result of the expression matches($s, "") is always true, regardless of the value of $s.

 matches("abracadabra", "bra") true() matches("abracadabra", "^a.*a$") true() matches("abracadabra", "^bra") false() Kaum hat dies der Hahn gesehen, Fängt er auch schon an zu krähen: Kikeriki! Kikikerikih!! Tak, tak, tak! - da kommen sie. ]]> matches($poem, "Kaum.*krähen") false() matches($poem, "Kaum.*krähen", "s") true() matches($poem, "^Kaum.*gesehen,$", "m") true() matches($poem, "^Kaum.*gesehen,$") false() matches($poem, "kiki", "i") true() matches("abcabc", "(abc)\1") true() matches("abcabc", "(?<x>abc)\k<x>") true() matches("abcabd", "(?<x>abc)\k<x>") false() deterministic context-independent focus-independent

Returns a string produced from the input string by replacing any segments that match a given regular expression with a supplied replacement string, provided either literally, or by invoking a supplied function.

If the $flags argument is omitted or if it is the empty sequence, the effect is the same as setting $flags to a zero-length string. Flags are defined in .

The string $value is matched against the regular expression $pattern, using the supplied $flags, to obtain a set of . A replacement string R for each of these segments (say M) is determined by the value of the $replacement argument, by applying the first of the following rules that applies:

If $replacement is a function item F, then R is obtained by calling F, and then applying the function fn:string to the result.

The first argument, $match, is the string to be replaced, provided as xs:untypedAtomic.

The second argument, $groups, provides the captured groups as a map. As in the result of fn:matching-segments, each group is keyed by its name if it is a named capturing group, and by its group number otherwise. The associated value is the string value of the group, supplied as xs:untypedAtomic. Groups that did not participate in the match have no entry.

Note that the rules for function coercion mean that the function actually supplied for F may be an arity-1 function: the $groups argument does not need to be declared if it is not used.

If $replacement is a string and the q flag is present, R is the value of $replacement.

Otherwise, the value of $replacement is processed as follows.

Within the supplied $replacement string, a variable marker $N (where N is an unsigned integer) may be used to refer to the Nth captured group associated with M. The replacement string R is obtained by replacing each of these variable markers with the string value of the relevant captured group. The variable marker $0 refers to the substring captured by the regular expression as a whole.

Similarly, a variable marker $<name> refers to the group captured by the named capturing group with the given name, or to the zero-length string if that group did not participate in the match. A named capturing group can also be referred to by its group number.

A literal $ character within the replacement string must be written as \$, and a literal \ character must be written as \\.

More specifically, the rules for numeric variable markers are as follows, where S is the number of capturing subexpressions in the regular expression, and N is the decimal number formed by taking all the digits that consecutively follow the $ character in $replacement:

If N=0, then the variable is replaced by the string value of M.

If 1<=N<=S, then the variable marker is replaced by the string value of the Nth captured group associated with M. If the Nth parenthesized sub-expression was not matched, then the variable marker is replaced by the zero-length string.

If S<N<=9, then the variable marker is replaced by the zero-length string.

Otherwise (if N>S and N>9), the last digit of N is taken to be a literal character to be included “as is” in the replacement string, and the rules are reapplied using the number N formed by stripping off this last digit.

For example, if the replacement string is "$23" and there are 5 substrings, the result contains the value of the substring that matches the second capturing subexpression, followed by the digit 3.

The function returns the xs:string that is obtained by replacing each of the of $value with the corresponding value of R.

A dynamic error is raised if the value of $pattern is invalid according to the rules described in section .

A dynamic error is raised if the value of $flags is invalid according to the rules described in section .

In the absence of the q flag, a dynamic error is raised if the value of $replacement contains a dollar sign ($) character that is not immediately followed by a digit 0-9 or a left angle bracket (<), and not immediately preceded by a backslash (\).

In the absence of the q flag, a dynamic error is raised if the value of $replacement contains $<, with the dollar sign not immediately preceded by a backslash, unless the following characters, up to the next right angle bracket (>), form the name of a named capturing group in the regular expression.

In the absence of the q flag, a dynamic error is raised if the value of $replacement contains a backslash (\) character that is not part of a \\ pair, unless it is immediately followed by a dollar sign ($) character.

If the input string contains no substring that matches the regular expression, the result of the function is a single string identical to the input string.

If two overlapping substrings of $value both match the $pattern, then only the first one (that is, the one whose first character comes first in the $value string) is replaced.

If two alternatives within the pattern both match at the same position in the $input, then the match that is chosen is the one matched by the first alternative. For example:

replace("abcd", "(ab)|(a)", "[1=$1][2=$2]") returns "[1=ab][2=]cd"

The rules for allow a zero-length matching segment to immediately follow a non-zero-length matching segment (they are not considered to overlap). This means, for example, that the regular expression .* will typically produce two matches: one matching segment containing all the characters in the input string, and a second zero-length matching seqment at the end position of the string.

 replace("abracadabra", "bra", "*") "a*cada*" replace("abracadabra", "a.*a", "*") "*" replace("abracadabra", "a.*?a", "*") "*c*bra" replace("abracadabra", "a", "") "brcdbr" replace("abracadabra", "a(.)", "a$1$1") "abbraccaddabbra" replace("AAAA", "A+", "b") "b" replace("AAAA", "A+?", "b") "bbbb" replace("In the beginning was the Word", "\b", "|") "|In| |the| |beginning| |was| |the| |Word|" replace("abcd!", "[a-z](?=.*(.)$)", "$0$1") "a!b!c!d!!" replace("darted", "^(.*?)d(.*)$", "$1c$2") "carted" Only the first d is replaced. replace("abracadabra", "bra", upper-case#1) "aBRAcadaBRA" replace("Chapter 9", "[0-9]+", fn { . + 1 }) "Chapter 10" replace( "LHR to LAX", "\b[A-Z]{3}\b", { 'LAX': 'Los Angeles', 'LHR': 'London' } ) "London to Los Angeles" replace( "57°43′30″", "([0-9]+)°([0-9]+)′([0-9]+)″", fn($s, $groups) { string($groups?1 + $groups?2 ÷ 60 + $groups?3 ÷ 3600) || '°' } ) "57.725°" replace( "2026-06-25", "(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})", "$<day>/$<month>/$<year>" ) "25/06/2026" replace( "42 plus 7", "(?<first>\d+) plus (?<second>\d+)", fn($s, $groups) { string($groups?first + $groups?second) } ) "49"

The $replacement argument can now be a function that computes the replacement strings.

It is now permitted for the regular expression to match a zero-length string.

Named capturing groups can be referenced in replacement strings; replacement functions receive the captured groups as a map.

 deterministic context-independent focus-independent

Returns a sequence of strings constructed by splitting the input wherever a separator is found; the separator is any substring that matches a given regular expression.

The following rules apply when the $pattern argument is the empty sequence:

The function splits the supplied string at whitespace boundaries.

More specifically, calling fn:tokenize($value) or fn:tokenize($value, ()) is equivalent to calling fn:tokenize(fn:normalize-space($value), ' ')) where the second argument is a single space character (x20).

The $flags argument is ignored.

The following rules apply when the $pattern argument is supplied as a single string:

Flags are defined in .

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

The function returns a sequence of strings formed by breaking the $value string into a sequence of strings, treating any substring that matches $pattern as a separator. The separators themselves are not returned.

More specifically:

Let M0 be the sequence of that results from matching $value against $pattern in the presence of $flags.

Unless the first segment in M0 is zero-length and starts at the first of $value, prepend a zero-length segment that starts at the start of $value: call the result M1.

Unless the last segment in M1 is zero-length and starts at the last of $value (that is, the character position after the last character), append a zero-length segment that starts at the last character position of $value. Call the result M2.

For each pair of adjacent segments in M2 (say, S/n and S/n+1), construct a string (possibly zero-length) that is the substring of $value containing all characters that follow S/n and that precede S/n+1. Return this sequence of strings, in order.

A dynamic error is raised if the value of $pattern is invalid according to the rules described in section .

A dynamic error is raised if the value of $flags is invalid according to the rules described in section .

If the input string is not zero length, and no separators are found in the input string, the result of the function is a single string identical to the input string.

For the one-argument form of the function:

The function has a similar effect to the two-argument form with \s+ as the separator pattern, except that the one-argument form strips leading and trailing whitespace, whereas the two-argument form delivers an extra zero-length token if leading or trailing whitespace is present.

The separator used is any sequence of tab (U+0009), newline (U+000A), carriage return (U+000D) or space (U+0020) characters. This is the same as the separator recognized by list-valued attributes as defined in XSD. It is not the same as the separator recognized by list-valued attributes in HTML5, which also treats form-feed (U+000C) as whitespace. If it is necessary to treat form-feed as a separator, an explicit separator pattern should be used.

For the two-argument form of the function:

The function returns no information about the separators that were found in the string. If this information is required, the fn:analyze-string function can be used instead. Alternatively, zero-width assertions can be used to identify separators. For example, using the regular expression (?<=,) will start a new token after every comma, including the comma as part of the previous token.

If a separator occurs at the start of $value, and is not zero-length, the result sequence will start with a zero-length string. Similarly, zero-length strings will also occur in the result sequence if a non-zero-length separator occurs at the end of $value, or if two adjacent substrings match the supplied $pattern.

If two alternatives within the supplied $pattern both match at the same position in the $value string, then the match that is chosen is the first. For example:

tokenize("abracadabra", "(ab)|(a)") returns ("", "r", "c", "d", "r", "")

The pattern may match zero-length segments of the input string. For example, the expression tokenize("Do not eat", "\b") returns the sequence "Do", " ", "not", " ", "eat".

A string may be split into individual characters (producing the same effect as the fn:characters function) by using the empty regular expression (for example, tokenize("xyz", ""), or any other regular expression such as .?? that matches every zero-length string, regardless of position.

Unlike the split method in some other popular languages, however, not every regular expression that matches a zero-length string produces this behavior: for example the regular expression \b splits the string before and after every word.

 tokenize(" red green blue ") "red", "green", "blue" tokenize("The cat sat on the mat", "\s+") "The", "cat", "sat", "on", "the", "mat" tokenize(" red green blue ", "\s+") "", "red", "green", "blue", "" tokenize("1, 15, 24, 50", ",\s*") "1", "15", "24", "50" tokenize("1,15,,24,50,", ",") "1", "15", "", "24", "50", "" tokenize("the end", "\b") "the", " ", "end" tokenize("California", "") "C", "a", "l", "i", "f", "o", "r", "n", "i", "a" tokenize( "Some unparsed <br> HTML <BR> text", "\s*<br>\s*", "i" ) "Some unparsed", "HTML", "text"

The second argument can now be the empty sequence.

It is now permitted for the regular expression to match a zero-length string.

 deterministic context-independent focus-independent

Applies a regular expression (with flags) to an input string, returning details of all the matches that were found.

If $value is the empty sequence, it is interpreted as the zero-length string.

The value of $regex must be a regular expression as defined in .

The value of $flags (if supplied) must be a string representing a set of flags as defined in .

The function returns a sequence of records of type matching-segment-record, one for each of the of $value that matches the regular expression.

The way in which the disjoint matching segments are identified is described in .

The sequence of matching segments in the result will be sorted in order of ascending position within the input string.

A dynamic error is raised if the value of $pattern is invalid according to the rules described in section .

A dynamic error is raised if the value of $flags is invalid according to the rules described in section .

The information returned by this function is similar to that returned by fn:analyze-string. But because it is returned as a sequence of maps, it may be easier to process.

 matching-segments("a", "b") () matching-segments("a", "a") { "substring": "a", "position": 1, "groups": {} } matching-segments("a", "(a)") { "substring": "a", "position": 1, "groups": { 1: { "value": "a", "position": 1, "nr": 1, "name": () } } } matching-segments("", "b?") { "substring": "", "position": 1, "groups": {} } matching-segments((), "b?") { "substring": "", "position": 1, "groups": {} } matching-segments("The cat sat on the mat.", "\w+") { "substring": "The", "position": 1, "groups": {} }, { "substring": "cat", "position": 5, "groups": {} }, { "substring": "sat", "position": 9, "groups": {} }, { "substring": "on", "position": 13, "groups": {} }, { "substring": "the", "position": 16, "groups": {} }, { "substring": "mat", "position": 20, "groups": {} } matching-segments("08-12-03", "^(\d+)\-(\d+)\-(\d+)$") { "substring": "08-12-03", "position": 1, "groups": { 1: { "value": "08", "position": 1, "nr": 1, "name": () }, 2: { "value": "12", "position": 4, "nr": 2, "name": () }, 3: { "value": "03", "position": 7, "nr": 3, "name": () } } } matching-segments("A1,C15,,D24, X50,", "([A-Z])([0-9]+)") { "substring": "A1", "position": 1, "groups": { 1: { "value": "A", "position": 1, "nr": 1, "name": () }, 2: { "value": "1", "position": 2, "nr": 2, "name": () } } }, { "substring": "C15", "position": 4, "groups": { 1: { "value": "C", "position": 4, "nr": 1, "name": () }, 2: { "value": "15", "position": 5, "nr": 2, "name": () } } }, { "substring": "D24", "position": 9, "groups": { 1: { "value": "D", "position": 9, "nr": 1, "name": () }, 2: { "value": "24", "position": 10, "nr": 2, "name": () } } }, { "substring": "X50", "position": 14, "groups": { 1: { "value": "X", "position": 14, "nr": 1, "name": () }, 2: { "value": "50", "position": 15, "nr": 2, "name": () } } } matching-segments("Chapter 5", "(Chapter|Appendix)(?=\s+([0-9]+))") { "substring": "Chapter", "position": 1, "groups": { 1: { "value": "Chapter", "position": 1, "nr": 1, "name": () }, 2: { "value": "5", "position": 9, "nr": 2, "name": () } } } matching-segments("There we go", "\b(?=(\w+))") { "substring": "", "position": 1, "groups": { 1: { "value": "There", "position": 1, "nr": 1, "name": () } } }, { "substring": "", "position": 7, "groups": { 1: { "value": "we", "position": 7, "nr": 1, "name": () } } }, { "substring": "", "position": 10, "groups": { 1: { "value": "go", "position": 10, "nr": 1, "name": () } } } matching-segments( "2026-06-25", "(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})" ) { "substring": "2026-06-25", "position": 1, "groups": { "year": { "value": "2026", "position": 1, "nr": 1, "name": "year" }, "month": { "value": "06", "position": 6, "nr": 2, "name": "month" }, "day": { "value": "25", "position": 9, "nr": 3, "name": "day" } } }

Although a named capturing group has no integer key in the groups map, the entries of the map hold the group number, so a group can still be selected by number. The following expression returns the second group:

matching-segments( "2026-06-25", "(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})" )/groups/*[?nr = 2]/value => string() "06"

New in 4.0

A named capturing group is keyed in the groups map by its name rather than by its group number.

The information available for each captured group is aligned with the regex-groups function in XSLT 4.0.

 deterministic context-independent focus-independent

Processes a regular expression, plus flags, into a form suitable for repeated use.

The value of $pattern must be a regular expression as defined in .

The value of $flags (if supplied) must be a string representing a set of flags as defined in .

The function returns a record, whose fields are function items that can be used to evaluate the regular expression in various ways. The structure of this record is described in

A dynamic error is raised if the value of $pattern is invalid according to the rules described in section .

A dynamic error is raised if the value of $flags is invalid according to the rules described in section .

The function is designed to allow an implementation to process the regular expression into an internal compiled form, which may yield performance benefits if it is used repeatedly.

 let $regex := regex('^a.*a+$') return ("alpha", "beta", "gamma", "delta")[$regex?matches(.)] "alpha" let $regex := regex('kiki', 'i') return some $k in ("Kikeriki!", "Kikikerikih!!") satisfies $regex?matches($k) true() let $regex := regex('[0-9]+') for $title in ("Chapter 1", "Chapter 2", "Chapter 3", "Appendix 12") return $regex?replace($title, fn { . + 1 }) "Chapter 2", "Chapter 3", "Chapter 4", "Appendix 13" regex("([A-Z])([0-9]+)") ? matching-segments("A1,C15,,D24, X50,") { "substring": "A1", "position": 1, "groups": {1: { "value": "A", "position": 1, "nr": 1, "name": () }, 2: { "value": "1", "position": 2, "nr": 2, "name": () } } }, { "substring": "C15", "position": 4, "groups": {1: { "value": "C", "position": 4, "nr": 1, "name": () }, 2: { "value": "15", "position": 5, "nr": 2, "name": () } } }, { "substring": "D24", "position": 9, "groups": {1: { "value": "D", "position": 9, "nr": 1, "name": () }, 2: { "value": "24", "position": 10, "nr": 2, "name": () } } }, { "substring": "X50", "position": 14, "groups": {1: { "value": "X", "position": 14, "nr": 1, "name": () }, 2: { "value": "50", "position": 15, "nr": 2, "name": () } } }

New in 4.0

 nondeterministic context-independent focus-independent

Analyzes a string using a regular expression, returning an XML structure that identifies which parts of the input string matched or failed to match the regular expression, and in the case of matched substrings, which substrings matched each capturing group in the regular expression.

Flags are defined in .

If $value is the empty sequence, the function behaves as if $value were the zero-length string.

The function returns an element node whose local name is analyze-string-result. This element and all its descendant elements have the namespace URI http://www.w3.org/2005/xpath-functions. The namespace prefix is implementation-dependent. The children of this element are a sequence of fn:match and fn:non-match elements. This sequence is formed by breaking the $value string into a sequence of strings, returning any substring that matches $pattern as the content of an fn:match element, and any intervening substring as the content of an fn:non-match element.

More specifically, the function starts by matching the regular expression against the string, using the supplied $flags, to obtain the . For each such segment it constructs an fn:match child, whose string value is the string value of the segment. Before, between, or after these fn:match elements, as required to ensure that the string value of the fn:analyze-string-result element is the same as $value, it inserts fn:non-match elements. The content of an fn:non-match element is always a single (non-empty) text node, and two fn:non-match elements never appear as adjacent siblings.

The captured groups for each disjoint matching segment are represented using fn:group or fn:lookahead-group children of the corresponding fn:match element. Groups captured by a subexpression within a lookahead assertion are referred to as lookahead groups; those not within a lookahead assertion are called ordinary groups.

The content of an fn:match element is in general:

A sequence of text nodes and fn:group element children, whose string-values when concatenated comprise the string value of the matching segment, followed by

A sequence of zero or more fn:lookahead-group elements, representing the lookahead groups

The string value of an fn:match element may be empty.

An fn:group element with a nr attribute having the integer value N identifies the substring captured by an ordinary group, specifically the string value of the Nth captured group. For each ordinary capturing subexpression there will be at most one corresponding fn:group element in each fn:match element in the result. If the group is a named capturing group, the element also has a name attribute holding its name.

By contrast, lookahead groups are represented by fn:lookahead-group elements, which (if they appear at all) must follow all text node and fn:group element children of the fn:match element. These groups may overlap the matching and non-matching substrings, and indeed may overlap each other. They must appear in ascending numerical order of group number. The attributes of the fn:lookahead-group element are as follows:

nr: the group number, based on the position of the capturing subexpression that captured the group;

name: the name of the group, present only if it is a named capturing group;

value: the string value of the segment that was captured;

position: the one-based start position of the segment within the input string.

If the function is called twice with the same arguments, it is implementation-dependent whether the two calls return the same element node or distinct (but deep equal) element nodes. In this respect it is nondeterministic with respect to node identity.

The base URI of the element nodes in the result is implementation-dependent.

A schema is defined for the structure of the returned element: see .

The result of the function will always be such that validation against this schema would succeed. However, it is implementation-defined whether the result is typed or untyped, that is, whether the elements and attributes in the returned tree have type annotations that reflect the result of validating against this schema.

A dynamic error is raised if the value of $pattern is invalid according to the rules described in section .

A dynamic error is raised if the value of $flags is invalid according to the rules described in section .

It is recommended that a processor that implements schema awareness should return typed nodes. The concept of “schema awareness”, however, is a matter for host languages to define and is outside the scope of the function library specification.

The declarations and definitions in the schema are not automatically available in the static context of the fn:analyze-string call (or of any other expression). The contents of the static context are host-language defined, and in some host languages are implementation-defined.

The schema defines the outermost element, analyze-string-result, in such a way that mixed content is permitted. In fact the element will only have element nodes (match and non-match) as its children, never text nodes. Although this might have originally been an oversight, defining the analyze-string-result element with mixed="true" allows it to be atomized, which is potentially useful (the atomized value will be the original input string), and the capability has therefore been retained for compatibility with the 3.0 version of this specification.

The rules for allow a zero-length matching segment to immediately follow a non-zero-length matching segment (they are not considered to overlap). This means, for example, that the regular expression .* will typically produce two matches: one matching segment containing all the characters in the input string, and a second zero-length matching seqment at the end position of the string.

In the following examples, the result document is shown in serialized form, with whitespace between the element nodes. This whitespace is not actually present in the result.

 analyze-string("The cat sat on the mat.", "\w+") The cat sat on the mat . ]]> analyze-string("08-12-03", "^(\d+)\-(\d+)\-(\d+)$") 08-12-03 ]]> analyze-string("A1,C15,,D24, X50,", "([A-Z])([0-9]+)") A 1 , C 15 ,, D 24 , X 50 , ]]> analyze-string("Chapter 5", "(Chapter|Appendix)(?=\s+([0-9]+))") Chapter 5 ]]> analyze-string("There we go", "\b(?=(\w+))") There we go ]]> analyze-string("2026-06-25", "(?<y>\d{4})-(?<m>\d{2})-(?<d>\d{2})") 2026-06-25 ]]>

The output of the function is extended to allow the represention of captured groups found within lookahead assertions.

It is now permitted for the regular expression to match a zero-length string.

A named capturing group carries a name attribute.

 deterministic context-dependent focus-independent deterministic context-dependent focus-independent

Determines whether or not any of the supplied strings, when tokenized at whitespace boundaries, contains the supplied token, under the rules of the supplied collation.

If $value is the empty sequence, the function returns false.

Leading and trailing whitespace is trimmed from $token. If the trimmed value of $token is a zero-length string, the function returns false.

The collation used by this function is determined according to the rules in .

The function returns true if and only if there is string in $value which, after tokenizing at whitespace boundaries, contains a token that is equal to the trimmed value of $token under the rules of the selected collation.

 some $t in ($value ! tokenize(.)) satisfies compare($t, replace($token, '^\s*|\s*$', ''), $collation) eq 0

Interior whitespace within $token will cause the function to return false, unless such whitespace is ignored by the selected collation.

This function can be used for processing space-separated attribute values (for example, the XHTML and DITA class attribute), where one often needs to test for the presence of a single token in a space-separated list. The function is designed to work both when the attribute has been validated against an XSD list type, and when it appears as a single untyped string. It differs from the HTML 5 definition in that HTML 5 recognizes form feed (x0C) as a separator. To reproduce the HTML token matching behavior, the HTML ASCII case-insensitive collation should be used: see .

 contains-token("red green blue ", "red") true() contains-token(("red", "green", "blue"), " red ") true() contains-token("red, green, blue", "red") false() contains-token( "red green blue", "RED", "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) true() deterministic context-dependent focus-independent

Resolves a relative IRI reference against an absolute IRI.

The function is defined to operate on IRI references as defined in , and the implementation must permit all arguments that are valid according to that specification. In addition, the implementation may accept some or all strings that conform to the rules for (absolute or relative) Legacy Extended IRI references as defined in . For the purposes of this section, the terms IRI and IRI reference include these extensions, insofar as the implementation chooses to support them.

The following rules apply in order:

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

If $href is an absolute IRI (as defined above), then it is returned unchanged.

If the $base argument is the empty sequence, then:

If the executable base URI in the dynamic context is not absent, it is used as the effective value of $base.

Otherwise, a dynamic error is raised: .

The function resolves the relative IRI reference $href against the base IRI $base using the algorithm defined in , adapted by treating any character that would not be valid in an RFC3986 URI or relative reference in the same way that RFC3986 treats unreserved characters. No percent-encoding takes place.

The first form of this function resolves $href against the value of the base-uri property from the static context. A dynamic error is raised if the base-uri property is not initialized in the static context.

A dynamic error is raised if $href is not a valid IRI according to the rules of RFC3987, extended with an implementation-defined subset of the extensions permitted in LEIRI, or if it is not a suitable relative reference to use as input to the RFC3986 resolution algorithm extended to handle additional unreserved characters.

A dynamic error is raised if $base is not a valid IRI according to the rules of RFC3987, extended with an implementation-defined subset of the extensions permitted in LEIRI, or if it is not a suitable IRI to use as input to the chosen resolution algorithm (for example, if it is a relative IRI reference or, if it is a non-hierarchic URI, or if it contains a fragment identifier). In XPath 4.0, attempting to resolve against an absolute URI that includes a fragment identifier is no longer an error, the fragment identifier is simply ignored. A narrow reading of RFC 3986 might seem to forbid this, but in practice the interpretation is non-controversial and the practice is widely supported.

A dynamic error is raised if the chosen resolution algorithm fails for any other reason.

Resolving a URI does not dereference it. This is merely a syntactic operation on two strings.

The algorithms in the cited RFCs include some variations that are optional or recommended rather than mandatory; they also describe some common practices that are not recommended, but which are permitted for backwards compatibility. Where the cited RFCs permit variations in behavior, so does this specification.

Throughout this family of specifications, the phrase "resolving a relative URI (or IRI) reference" should be understood as using the rules of this function, unless otherwise stated.

RFC3986 defines an algorithm for resolving relative references in the context of the URI syntax defined in that RFC. RFC3987 describes a modification to that algorithm to make it applicable to IRIs (specifically: additional characters permitted in an IRI are handled the same way that RFC3986 handles unreserved characters). The LEIRI specification does not explicitly define a resolution algorithm, but suggests that it should not be done by converting the LEIRI to a URI, and should not involve percent-encoding. This specification fills this gap by defining resolution for LEIRIs in the same way that RFC3987 defines resolution for IRIs, that is by specifying that additional characters are handled as unreserved characters.

The optional second argument can now be supplied as the empty sequence.

 deterministic context-independent focus-independent

Returns the xs:boolean value true.

The result is equivalent to xs:boolean("1").

 true() xs:boolean(1) deterministic context-independent focus-independent

Returns the xs:boolean value false.

The result is equivalent to xs:boolean("0").

 false() xs:boolean(0)

Computes the effective boolean value of the sequence $input.

The function computes the effective boolean value of a sequence, defined according to the following rules. See also .

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

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

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.

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

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.

 boolean($abc[1]) true() boolean($abc[0]) false() boolean($abc[3]) false() boolean($abc) boolean([]) deterministic context-independent focus-independent

Returns true if the effective boolean value of $input is false, or false if it is true.

The value of $input is first reduced to an effective boolean value by applying the fn:boolean() function. The function returns true if the effective boolean value is false, or false if the effective boolean value is true.

not(true()) false() not(()) true() not("false") false() not(1 to 10) deterministic context-independent focus-independent

Returns an xs:dayTimeDuration whose length is a given number of seconds.

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

Otherwise, the function returns an xs:dayTimeDuration value whose length in seconds is equal to $value.

If $value is negative then the result will be a negative duration.

For handling of overflow and underflow, see .

The result of seconds($n) is equal to the result of the expression xs:dayTimeDuration('PT1S') × $n.

 seconds(1) xs:dayTimeDuration('PT1S') seconds(0.001) xs:dayTimeDuration('PT0.001S') seconds(60) xs:dayTimeDuration('PT1M') seconds(86400) xs:dayTimeDuration('P1D') seconds(-5400) xs:dayTimeDuration('-PT1H30M') xs:dateTime('1970-01-01T00:00:00Z') + 1_706_702_400 × seconds(1) xs:dateTime('2024-01-31T12:00:00Z') The expression converts a Unix timestamp to an xs:dateTime value ( xs:dateTime('2024-01-31T12:00:00Z') - xs:dateTime('1970-01-01T00:00:00Z') ) div seconds(1) 1706702400 The expression converts an xs:dateTime value to a Unix timestamp

New in 4.0

 deterministic context-independent focus-independent

Returns the number of years in a duration.

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

Otherwise, the function returns an xs:integer representing the years component in $value. Given that a duration is a ($months, $seconds) tuple, the result is the value of ($months idiv 12).

If $value is a negative duration then the result will be negative.

If $value is an xs:dayTimeDuration the function returns 0.

 years-from-duration( xs:yearMonthDuration("P20Y15M") ) 21 years-from-duration( xs:yearMonthDuration("-P15M") ) -1 years-from-duration( xs:dayTimeDuration("-P2DT15H") ) 0 years-from-duration( xs:duration("P1Y1000D") ) 1 To capture whole portions of years reflected in the xs:dayTimeDuration component, it must first be converted to an xs:yearMonthDuration. deterministic context-independent focus-independent

Returns the number of months in a duration.

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

Otherwise, the function returns an xs:integer representing the months component in $value. Given that a duration is a ($months, $seconds) tuple, the result is the value of ($months mod 12).

If $value is a negative duration then the result will be negative.

If $value is an xs:dayTimeDuration the function returns 0.

 months-from-duration( xs:yearMonthDuration("P20Y15M") ) 3 months-from-duration( xs:yearMonthDuration("-P20Y18M") ) -6 months-from-duration( xs:dayTimeDuration("-P2DT15H0M0S") ) 0 months-from-duration( xs:duration("P1M100D") ) 1 To capture whole portions of months reflected in the xs:dayTimeDuration component, it must first be converted to an xs:yearMonthDuration. deterministic context-independent focus-independent

Returns the number of days in a duration.

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

Otherwise, the function returns an xs:integer representing the days component in $value. Given that a duration is a ($months, $seconds) tuple, the result is ($seconds idiv 86400).

If $value is a negative duration then the result will be negative.

If $value is an xs:yearMonthDuration the function returns 0.

 days-from-duration( xs:dayTimeDuration("P3DT10H") ) 3 days-from-duration( xs:dayTimeDuration("P3DT55H") ) 5 days-from-duration( xs:yearMonthDuration("P3Y5M") ) 0 days-from-duration( xs:duration("P1Y1D") ) 1 To capture days reflected in the xs:yearMonthDuration component, it must first be converted to an xs:dayTimeDuration. deterministic context-independent focus-independent

Returns the number of hours in a duration.

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

Otherwise, the function returns an xs:integer representing the hours component in $value. Given that a duration is a ($months, $seconds) tuple, the result is the value of ($seconds mod 86400) idiv 3600.

If $value is a negative duration then the result will be negative.

If $value is an xs:yearMonthDuration the function returns 0.

 hours-from-duration( xs:dayTimeDuration("P3DT10H") ) 10 hours-from-duration( xs:dayTimeDuration("P3DT12H32M12S") ) 12 hours-from-duration( xs:dayTimeDuration("PT123H") ) 3 hours-from-duration( xs:dayTimeDuration("-P3DT10H") ) -10 hours-from-duration( xs:duration("P1YT1H") ) 1 To capture hours reflected in the xs:yearMonthDuration component, it must first be converted to an xs:dayTimeDuration. deterministic context-independent focus-independent

Returns the number of minutes in a duration.

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

Otherwise, the function returns an xs:integer representing the minutes component in $value. Given that a duration is a ($months, $seconds) tuple, the result is the value of ($seconds mod 3600) idiv 60.

If $value is a negative duration then the result will be negative.

If $value is an xs:yearMonthDuration the function returns 0.

 minutes-from-duration( xs:dayTimeDuration("P3DT10H") ) 0 minutes-from-duration( xs:dayTimeDuration("-P5DT12H30M") ) -30 minutes-from-duration( xs:duration("P1YT1M") ) 1 To capture minutes reflected in the xs:yearMonthDuration component, it must first be converted to an xs:dayTimeDuration. deterministic context-independent focus-independent

Returns the number of seconds in a duration.

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

Otherwise, the function returns an xs:decimal representing the seconds component in $value. Given that a duration is a ($months, $seconds) tuple, the result is the value of ($seconds mod 60) as an xs:decimal.

If $value is a negative duration then the result will be negative.

If $value is an xs:yearMonthDuration the function returns 0.

 seconds-from-duration( xs:dayTimeDuration("P3DT10H12.5S") ) 12.5 seconds-from-duration( xs:dayTimeDuration("-PT256S") ) -16.0 seconds-from-duration( xs:duration("P1YT1S") ) 1 To capture seconds reflected in the xs:yearMonthDuration component of an xs:duration, it must first be converted to an xs:dayTimeDuration. seconds-from-duration( xs:duration("P1YT1S") ) 1 To capture seconds reflected in the xs:yearMonthDuration component, it must first be converted to an xs:dayTimeDuration. Defines the semantics of the + operator when applied to two xs:yearMonthDuration values.

Returns the result of adding two xs:yearMonthDuration values.

The function returns the result of adding $arg1 to $arg2. The result will be an xs:yearMonthDuration whose length in months is equal to the length in months of $arg1 plus the length in months of $arg2.

For handling of overflow, see .

Either duration (and therefore the result) may be negative.

 op:add-yearMonthDurations( xs:yearMonthDuration("P2Y11M"), xs:yearMonthDuration("P3Y3M") ) xs:yearMonthDuration("P6Y2M") Defines the semantics of the - operator when applied to two xs:yearMonthDuration values.

Returns the result of subtracting one xs:yearMonthDuration value from another.

The function returns the result of subtracting $arg2 from $arg1. The result will be an xs:yearMonthDuration whose length in months is equal to the length in months of $arg1 minus the length in months of $arg2.

For handling of overflow, see .

Either duration (and therefore the result) may be negative.

 op:subtract-yearMonthDurations( xs:yearMonthDuration("P2Y11M"), xs:yearMonthDuration("P3Y3M") ) xs:yearMonthDuration("-P4M") Defines the semantics of the * or × operator when applied to an xs:duration and a number.

Returns the result of multiplying a duration by a number.

The result is an xs:duration value as follows:

The value of $arg2 is cast to xs:decimal. This raises an error if the value is NaN or infinite.

The value of the months component is formed by multiplying the months component of $arg1 by the decimal value of $arg2 and rounding the result to an integer by applying the fn:round#1 function.

The value of the seconds component is formed by multiplying the seconds component of $arg1 by the decimal value of $arg2 and rounding the result to the maxumum precision supported by the implementation.

If $arg1 is an instance of xs:yearMonthDuration then the result is cast to xs:yearMonthDuration.

If $arg1 is an instance of xs:dayTimeDuration then the result is cast to xs:dayTimeDuration.

For handling of overflow, underflow, and rounding, see .

Either argument (and therefore the result) may be negative.

Because the months and seconds components are rounded independently of each other, the result may be counter-intuitive. For example, the result of xs:duration('P1M1D') × 0.5 is xs:duration('P1MT12H').

 op:multiply-duration-by-number( xs:yearMonthDuration("P2Y11M"), 2.3 ) xs:yearMonthDuration("P6Y9M") op:multiply-duration-by-number( xs:duration("P11M"), 0.5 ) xs:yearMonthDuration("P6M") op:multiply-duration-by-number( xs:dayTimeDuration("PT2H10M"), 2.1 ) xs:dayTimeDuration('PT4H33M') op:multiply-duration-by-number( xs:duration("P1Y1D"), 2 ) xs:duration('P2Y2D') op:multiply-duration-by-number( xs:duration("P1Y1D"), -1 ) xs:duration('-P1Y1D')

The operation now applies to any xs:duration, not exclusively to instances of xs:yearMonthDuration and xs:dayTimeDuration. The second argument is now converted to xs:decimal rather than xs:double. This may affect the result of any rounding, as well as error codes when the argument is NaN or infinity.

 Defines the semantics of the div or ÷ operator when applied to an xs:duration and a number.

Returns the result of dividing a duration by a number.

The result is an xs:duration value as follows:

The value of $arg2 is cast to xs:decimal. This raises an error if the value is NaN or infinite.

The value of the months component is formed by dividing the months component of $arg1 by the decimal value of $arg2 and rounding the result to an integer by applying the fn:round#1 function.

The value of the seconds component is formed by dividing the seconds component of $arg1 by the decimal value of $arg2 and rounding the result to the maxumum precision supported by the implementation.

If $arg1 is an instance of xs:yearMonthDuration then the result is cast to xs:yearMonthDuration.

If $arg1 is an instance of xs:dayTimeDuration then the result is cast to xs:dayTimeDuration.

For handling of overflow, underflow, and rounding, see .

Division by zero raises .

Either argument (and therefore the result) may be negative.

Because the months and seconds components are rounded independently of each other, the result may be counter-intuitive. For example, the result of xs:duration('P1M1D') ÷ 2 is xs:duration('P1MT12H').

 op:divide-duration-by-number( xs:yearMonthDuration("P2Y11M"), 2 ) xs:yearMonthDuration("P1Y6M") op:divide-duration-by-number( xs:duration("P15M"), 2 ) xs:duration("P8M") op:divide-duration-by-number( xs:dayTimeDuration("P1DT2H30M10.5S"), 1.5 ) xs:dayTimeDuration("PT17H40M7S") op:divide-duration-by-number( xs:duration("P2Y10D"), 2 ) xs:dayTimeDuration("P1Y5D")

The function now applies to any xs:duration, not exclusively to instances of xs:yearMonthDuration and xs:dayTimeDuration. The second argument is now defined as xs:decimal rather than xs:double. This may affect the result of any rounding, as well as error codes when the argument is NaN or infinity.

 Defines the semantics of the div operator when applied to two xs:yearMonthDuration values.

Returns the ratio of two xs:yearMonthDuration values.

The function returns the result of dividing the length in months of $arg1 by the length in months of $arg2, according to the rules of the op:numeric-divide function for integer operands.

For handling of overflow, underflow, and rounding, see .

Division by a zero-length duration raises .

Either duration (and therefore the result) may be negative.

 op:divide-yearMonthDuration-by-yearMonthDuration( xs:yearMonthDuration("P3Y4M"), xs:yearMonthDuration("-P1Y4M") ) -2.5

The following example demonstrates how to calculate the length of an xs:yearMonthDuration value in months:

op:divide-yearMonthDuration-by-yearMonthDuration( xs:yearMonthDuration("P3Y4M"), xs:yearMonthDuration("P1M") ) 40 Defines the semantics of the + operator when applied to two xs:dayTimeDuration values.

Returns the sum of two xs:dayTimeDuration values.

The function returns the result of adding $arg1 to $arg2. The result is the xs:dayTimeDuration whose length in seconds is equal to the sum of the length in seconds of the two input durations.

For handling of overflow, see .

Either duration (and therefore the result) may be negative.

 op:add-dayTimeDurations( xs:dayTimeDuration("P2DT12H5M"), xs:dayTimeDuration("P5DT12H") ) xs:dayTimeDuration('P8DT5M') Defines the semantics of the - operator when applied to two xs:dayTimeDuration values.

Returns the result of subtracting one xs:dayTimeDuration from another.

The function returns the result of subtracting $arg2 from $arg1. The result is the xs:dayTimeDuration whose length in seconds is equal to the length in seconds of $arg1 minus the length in seconds of $arg2.

For handling of overflow, see .

Division by a zero-length duration raises .

Either duration (and therefore the result) may be negative.

 op:subtract-dayTimeDurations( xs:dayTimeDuration("P2DT12H"), xs:dayTimeDuration("P1DT10H30M") ) xs:dayTimeDuration('P1DT1H30M') op:subtract-dayTimeDurations( xs:dayTimeDuration("P30D"), xs:dayTimeDuration("P40DT6H") ) xs:dayTimeDuration('-P10DT6H') Defines the semantics of the div operator when applied to two xs:dayTimeDuration values.

Returns the ratio of two xs:dayTimeDuration values, as a decimal number.

The function returns the result of dividing $arg1 by $arg2. The result is the xs:dayTimeDuration whose length in seconds is equal to the length in seconds of $arg1 divided by the length in seconds of $arg2. The calculation is performed by applying op:numeric-divide to the two xs:decimal operands.

For handling of overflow, underflow, and rounding, see .

Division by a zero-length duration raises .

Either operand (and therefore the result) may be negative.

 round-half-to-even( op:divide-dayTimeDuration-by-dayTimeDuration( xs:dayTimeDuration("P2DT53M11S"), xs:dayTimeDuration("P1DT10H") ), 4 ) 1.4378

This examples shows how to determine the number of seconds in a duration.

op:divide-dayTimeDuration-by-dayTimeDuration( xs:dayTimeDuration("P2DT53M11S"), seconds(1) ) 175991.0 deterministic context-independent focus-independent

Returns an xs:dateTime value created by combining an xs:date and an xs:time.

If either $date or $time is the empty sequence, the function returns the empty sequence.

Otherwise, the function returns an xs:dateTime whose date component is equal to $date and whose time component is equal to $time.

The timezone of the result is computed as follows:

If neither argument has a timezone, the result has no timezone.

If exactly one of the arguments has a timezone, or if both arguments have the same timezone, the result has this timezone.

A dynamic error is raised if the two arguments both have timezones and the timezones are different.

dateTime( xs:date("1999-12-31"), xs:time("12:00:00") ) xs:dateTime("1999-12-31T12:00:00") dateTime( xs:date("1999-12-31"), xs:time("24:00:00") ) xs:dateTime("1999-12-31T00:00:00") This is because "24:00:00" is an alternate lexical form for "00:00:00" deterministic context-independent focus-independent

Returns a dateTime value for a Unix time.

The function returns a dateTime value in UTC timezone for the Unix time specified by $value in milliseconds. The Unix time is defined in .

If the implementation supports data types from XSD 1.1 then the returned value will be an instance of xs:dateTimeStamp. Otherwise, the only guarantees are that it will be an instance of xs:dateTime and will have a timezone component.

 xs:dateTime('1970-01-01T00:00:00Z') + ($value otherwise 0) * seconds(0.001)

By calling this convenience function, it can be ensured that the correct timezone is used for computing the Unix time.

Note that Unix time does not account for leap seconds. It assumes that every day has 86,400 seconds.

 unix-dateTime() xs:dateTime('1970-01-01T00:00:00Z') unix-dateTime(1) xs:dateTime('1970-01-01T00:00:00.001Z') unix-dateTime(86400000) xs:dateTime('1970-01-02T00:00:00Z')

Calculate the Unix time associated with a xs:dateTime value:

let $value := current-dateTime() return ($value - unix-dateTime()) div seconds(0.001)

New in 4.0

 deterministic context-independent focus-independent

Returns the year component of a value.

If $value is the empty sequence, or if the year component is absent, the function returns the empty sequence.

Otherwise, the function returns an xs:integer representing the year component in $value. The result may be negative.

The value space for xs:dateTime allows year zero. XSD 1.0, however, does not allow year zero, so if a date earlier that 0001 CE was produced by validating an XML document using an XSD 1.0 processor, the results may be unpredictable.

 year-from-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") ) 1999 year-from-dateTime( xs:dateTime("1999-05-31T21:30:00-05:00") ) 1999 year-from-dateTime( xs:dateTime("1999-12-31T19:20:00") ) 1999 year-from-dateTime( xs:dateTime("1999-12-31T24:00:00") ) 2000 year-from-dateTime( xs:dateTime("-0002-06-06T00:00:00") ) -2 The result is the same whether XSD 1.0 or 1.1 is in use, despite the absence of a year 0 in the XSD 1.0 value space. year-from-dateTime( xs:gYearMonth("2007-05Z") ) 2007 year-from-dateTime( xs:time("12:30:00") ) ()

The function has been extended to handle other Gregorian types such as xs:gYearMonth.

 deterministic context-independent focus-independent

Returns the month component of a value.

If $value is the empty sequence, or if it contains no month component, the function returns the empty sequence.

Otherwise, the function returns an xs:integer between 1 and 12, both inclusive, representing the month component in $value.

 month-from-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") ) 5 month-from-dateTime( xs:dateTime("1999-12-31T19:20:00-05:00") ) 12 month-from-dateTime( adjust-dateTime-to-timezone( xs:dateTime("1999-12-31T19:20:00-05:00"), xs:dayTimeDuration("PT0S") ) ) 1 month-from-dateTime( xs:gYearMonth("2007-05Z") ) 5 month-from-dateTime( xs:time("12:30:00") ) ()

The function has been extended to handle other Gregorian types such as xs:gYearMonth.

 deterministic context-independent focus-independent

Returns the day component of a value.

If $value is the empty sequence, or if it contains no day component, the function returns the empty sequence.

Otherwise, the function returns an xs:integer between 1 and 31, both inclusive, representing the day component in the local value of $value.

 day-from-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") ) 31 day-from-dateTime( xs:dateTime("1999-12-31T20:00:00-05:00") ) 31 day-from-dateTime( adjust-dateTime-to-timezone( xs:dateTime("1999-12-31T19:20:00-05:00"), xs:dayTimeDuration("PT0S") ) ) 1 day-from-dateTime( xs:gMonthDay("--05-31Z") ) 31 day-from-dateTime( xs:time("12:30:00") ) ()

The function has been extended to handle other Gregorian types such as xs:gMonthDay.

 deterministic context-independent focus-independent

Returns the hours component of a value.

If $value is the empty sequence, or if it contains no hours component, the function returns the empty sequence.

Otherwise, the function returns an xs:integer between 0 and 23, both inclusive, representing the hours component in $value.

 hours-from-dateTime( xs:dateTime("1999-05-31T08:20:00-05:00") ) 8 hours-from-dateTime( xs:dateTime("1999-12-31T21:20:00-05:00") ) 21 hours-from-dateTime( adjust-dateTime-to-timezone( xs:dateTime("1999-12-31T21:20:00-05:00"), xs:dayTimeDuration("PT0S") ) ) 2 hours-from-dateTime( xs:dateTime("1999-12-31T12:00:00") ) 12 hours-from-dateTime( xs:dateTime("1999-12-31T24:00:00") ) 0 hours-from-dateTime( xs:gYearMonth("2007-05Z") ) () hours-from-dateTime( xs:time("12:30:00") ) 12

The function has been extended to handle other types including xs:time.

 deterministic context-independent focus-independent

Returns the minute component of a value.

If $value is the empty sequence, or if it contains no minutes component, the function returns the empty sequence.

Otherwise, the function returns an xs:integer value between 0 and 59, both inclusive, representing the minute component in the local value of $value.

 minutes-from-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") ) 20 minutes-from-dateTime( xs:dateTime("1999-05-31T13:30:00+05:30") ) 30 minutes-from-dateTime( xs:gYearMonth("2007-05Z") ) () minutes-from-dateTime( xs:time("12:30:00") ) 30

The function has been extended to handle other types including xs:time.

 deterministic context-independent focus-independent

Returns the seconds component of a value.

If $value is the empty sequence, or if it contains no seconds component, the function returns the empty sequence.

Otherwise, the function returns an xs:decimal value greater than or equal to zero and less than 60, representing the seconds and fractional seconds in $value.

 seconds-from-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") ) 0 seconds-from-dateTime( xs:gYearMonth("2007-05Z") ) () seconds-from-dateTime( xs:time("12:30:14.5") ) 14.5 deterministic context-independent focus-independent

Returns the timezone component of a value.

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

Otherwise, the function returns the timezone component of $value, if any. If $value has a timezone component, then the result is an xs:dayTimeDuration that indicates deviation from UTC; its value may range from +14:00 to -14:00 hours, both inclusive. If $value has no timezone component, the result is the empty sequence.

 timezone-from-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") ) xs:dayTimeDuration("-PT5H") timezone-from-dateTime( xs:dateTime("2000-06-12T13:20:00Z") ) xs:dayTimeDuration("PT0S") timezone-from-dateTime( xs:dateTime("2004-08-27T00:00:00") ) () timezone-from-dateTime( xs:gYearMonth("2007-05Z") ) xs:dayTimeDuration("PT0S") timezone-from-dateTime( xs:time("12:30:00") ) ()

The function has been extended to handle other types such as xs:gYearMonth.

 deterministic context-independent focus-independent

Returns the components of a value.

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

Otherwise, the function returns a record whose fields are as follows. If a particular component is not present in the value, the corresponding field in the returned record will be the empty sequence.

Key Value
year Generally, the value of fn:year-from-dateTime($value): but see the notes below regarding negative years.
month The value of fn:month-from-dateTime($value)
day The value of fn:day-from-dateTime($value)
hours The value of fn:hours-from-dateTime($value)
minutes The value of fn:minutes-from-dateTime($value)
seconds The value of fn:seconds-from-dateTime($value)
timezone The value of fn:timezone-from-dateTime($value)

The range of years supported is . If years earlier than 0001 CE are supported, however, the year number returned by this function follows the proleptic Gregorian calendar as defined in ISO 8601. This means that the year before 0001 CE is numbered zero, and the year before that is numbered -1.

 parts-of-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") ) { "year": 1999, "month": 5, "day": 31, "hours": 13, "minutes": 20, "seconds": 0, "timezone": xs:dayTimeDuration("-PT5H") } parts-of-dateTime( xs:time("13:30:04.2678") ) { "year": (), "month": (), "day": (), "hours": 13, "minutes": 30, "seconds": 4.2678, "timezone": () } parts-of-dateTime( xs:gYearMonth("2007-05Z") ) { "year": 2007, "month": 5, "day": (), "hours": (), "minutes": (), "seconds": (), "timezone": xs:dayTimeDuration("PT0S") }

New in 4.0

 deterministic context-independent focus-independent

Constructs a value from the values of its components.

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

Otherwise, the function returns a value based on the supplied component values. The result will be the value $R such that deep-equal( parts-of-dateTime($R), $value ) is true, where $value is the result of coercing the supplied argument to the required type fn:dateTime-record.

If all seven components are non-empty (year, month, day, hours, minutes, seconds, and timezone) then the result will be of type xs:dateTimeStamp.

The range of years supported is . If years earlier than 0001 CE are supported then the numbering follows the proleptic Gregorian calendar as defined in ISO 8601. This means that the year before 0001 CE is numbered zero, and the year before that is numbered -1.

A dynamic error is raised if the set of fields that are non-empty in $value is not one of the sets:

year, month, day, hours, minutes, seconds, and optional timezone (delivering an xs:dateTime)

year, month, day, and optional timezone (delivering an xs:date)

year, and optional timezone (delivering an xs:gYear)

year, month, and optional timezone (delivering an xs:gYearMonth)

month, and optional timezone (delivering an xs:gMonth)

month, day, and optional timezone (delivering an xs:gMonthDay)

day, and optional timezone (delivering an xs:gDay)

hours, minutes, seconds, and optional timezone (delivering an xs:time)

A dynamic error is raised if the timezone component of $value is outside the range -PT14H to PT14H

A dynamic error is raised if any other component of $value is outside the permitted range specified by the target date/time datatype, for example: if minutes is less than zero or greater than 59; or if day is 30 and month is 2. See .

The timezone, if non-empty, must correspond to an integral number of minutes in the range -840 to +840.

Midnight must be expressed with the hours value set to zero, not 24.

The standard apply, so (for example) the integral components may be supplied as xs:double values, and the timezone may be supplied as an xs:duration. Components that are not required may either be absent from the supplied map, or may be set to the empty sequence.

 build-dateTime({ "year": 1999, "month": 5, "day": 31, "hours": 13, "minutes": 20, "seconds": 0, "timezone": xs:dayTimeDuration("-PT5H") }) xs:dateTimeStamp("1999-05-31T13:20:00-05:00") build-dateTime({ "hours": 13, "minutes": 30, "seconds": 4.2678 }) xs:time("13:30:04.2678") build-dateTime({ "day": (), "hours": 13, "minutes": 30, "seconds": 4.2678 }) xs:time("13:30:04.2678") build-dateTime({ "year": 2007, "month": 5, "timezone": xs:dayTimeDuration("PT0S") }) xs:gYearMonth("2007-05Z")

New in 4.0

 deterministic context-independent focus-independent

Returns the year component of an xs:date.

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

Otherwise, the function returns an xs:integer representing the year in the local value of $value. The value may be negative.

The value space for xs:date allows year zero. XSD 1.0, however, does not allow year zero, so if a date earlier that 0001 CE was produced by validating an XML document using an XSD 1.0 processor, the results may be unpredictable.

 year-from-date( xs:date("1999-05-31") ) 1999 year-from-date( xs:date("2000-01-01+05:00") ) 2000 year-from-date( xs:date("-0002-06-01") ) -2 The result is the same whether XSD 1.0 or 1.1 is in use, despite the absence of a year 0 in the XSD 1.0 value space. deterministic context-independent focus-independent

Returns the month component of an xs:date.

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

Otherwise, the function returns an xs:integer between 1 and 12, both inclusive, representing the month component in the local value of $value.

month-from-date( xs:date("1999-05-31-05:00") ) 5 month-from-date( xs:date("2000-01-01+05:00") ) 1 deterministic context-independent focus-independent

Returns the day component of an xs:date.

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

Otherwise, the function returns an xs:integer between 1 and 31, both inclusive, representing the day component in the localized value of $value.

 day-from-date( xs:date("1999-05-31-05:00") ) 31 day-from-date( xs:date("2000-01-01+05:00") ) 1 deterministic context-independent focus-independent

Returns the timezone component of an xs:date.

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

Otherwise, the function returns the timezone component of $value, if any. If $value has a timezone component, then the result is an xs:dayTimeDuration that indicates deviation from UTC; its value may range from +14:00 to -14:00 hours, both inclusive. If $value has no timezone component, the result is the empty sequence.

 timezone-from-date( xs:date("1999-05-31-05:00") ) xs:dayTimeDuration("-PT5H") timezone-from-date( xs:date("2000-06-12Z") ) xs:dayTimeDuration("PT0S") deterministic context-independent focus-independent

Returns the hours component of an xs:time.

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

Otherwise, the function returns an xs:integer between 0 and 23, both inclusive, representing the value of the hours component in the local value of $value.

Assume that the dynamic context provides an implicit timezone value of -05:00.

hours-from-time(xs:time("11:23:00")) 11 hours-from-time(xs:time("21:23:00")) 21 hours-from-time(xs:time("01:23:00+05:00")) 1 hours-from-time( adjust-time-to-timezone( xs:time("01:23:00+05:00"), xs:dayTimeDuration("PT0S") ) ) 20 hours-from-time(xs:time("24:00:00")) 0 deterministic context-independent focus-independent

Returns the minutes component of an xs:time.

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

Otherwise, the function returns an xs:integer value between 0 and 59, both inclusive, representing the value of the minutes component in the local value of $value.

 minutes-from-time(xs:time("13:00:00Z")) 0 deterministic context-independent focus-independent

Returns the seconds component of an xs:time.

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

Otherwise, the function returns an xs:decimal value greater than or equal to zero and less than 60, representing the seconds and fractional seconds in the local value of $value.

 seconds-from-time(xs:time("13:20:10.5")) 10.5 deterministic context-independent focus-independent

Returns the timezone component of an xs:time.

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

Otherwise, the function returns the timezone component of $value, if any. If $value has a timezone component, then the result is an xs:dayTimeDuration that indicates deviation from UTC; its value may range from +14:00 to -14:00 hours, both inclusive. If $value has no timezone component, the result is the empty sequence.

 timezone-from-time(xs:time("13:20:00-05:00")) xs:dayTimeDuration("-PT5H") timezone-from-time(xs:time("13:20:00")) () deterministic context-dependent focus-independent deterministic context-independent focus-independent

Adjusts an xs:dateTime value to a specific timezone, or to no timezone at all.

If $value is the empty sequence, then the function returns the empty sequence.

If $value does not have a timezone component and $timezone is the empty sequence, then the result is $value.

If $value does not have a timezone component and $timezone is not the empty sequence, then the result is $value with $timezone as the timezone component.

If $value has a timezone component and $timezone is the empty sequence, then the result is the local value of $value without its timezone component.

If $value has a timezone component and $timezone is not the empty sequence, then the result is the xs:dateTime value that is equal to $value and that has a timezone component equal to $timezone.

A dynamic error is raised if $timezone is less than -PT14H or greater than PT14H or is not an integral number of minutes.

Assume the dynamic context provides an implicit timezone of -05:00 (-PT5H0M).

 adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00') ) xs:dateTime('2002-03-07T10:00:00-05:00') adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00-07:00') ) xs:dateTime('2002-03-07T12:00:00-05:00') adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00'), $tz-10 ) xs:dateTime('2002-03-07T10:00:00-10:00') adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00-07:00'), $tz-10 ) xs:dateTime('2002-03-07T07:00:00-10:00') adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00-07:00'), xs:dayTimeDuration("PT10H") ) xs:dateTime('2002-03-08T03:00:00+10:00') adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T00:00:00+01:00'), xs:dayTimeDuration("-PT8H") ) xs:dateTime('2002-03-06T15:00:00-08:00') adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00'), () ) xs:dateTime('2002-03-07T10:00:00') adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00-07:00'), () ) xs:dateTime('2002-03-07T10:00:00') deterministic context-dependent focus-independent deterministic context-independent focus-independent

Adjusts an xs:date value to a specific timezone, or to no timezone at all; the result is the date in the target timezone that contains the starting instant of the supplied date.

If $value is the empty sequence, then the function returns the empty sequence.

If $value does not have a timezone component and $timezone is the empty sequence, then the result is $value.

If $value does not have a timezone component and $timezone is not the empty sequence, then the result is $value with $timezone as the timezone component.

If $value has a timezone component and $timezone is the empty sequence, then the result is the local value of $value without its timezone component.

If $value has a timezone component and $timezone is not the empty sequence, then:

Let $dt be the value of fn:dateTime($arg, xs:time('00:00:00')).

Let $adt be the value of fn:adjust-dateTime-to-timezone($dt, $timezone)

The function returns the value of xs:date($adt)

A dynamic error is raised if $timezone is less than -PT14H or greater than PT14H or is not an integral number of minutes.

Assume the dynamic context provides an implicit timezone of -05:00 (-PT5H0M).

 adjust-date-to-timezone( xs:date("2002-03-07") ) xs:date("2002-03-07-05:00") adjust-date-to-timezone( xs:date("2002-03-07-07:00") ) xs:date("2002-03-07-05:00") $value is converted to xs:dateTime("2002-03-07T00:00:00-07:00"). This is adjusted to the implicit timezone, giving "2002-03-07T02:00:00-05:00". adjust-date-to-timezone( xs:date("2002-03-07"), $tz-10 ) xs:date("2002-03-07-10:00") adjust-date-to-timezone( xs:date("2002-03-07-07:00"), $tz-10 ) xs:date("2002-03-06-10:00") $value is converted to xs:dateTime("2002-03-07T00:00:00-07:00"). This is adjusted to the given timezone, giving "2002-03-06T21:00:00-10:00". adjust-date-to-timezone( xs:date("2002-03-07"), () ) xs:date("2002-03-07") adjust-date-to-timezone( xs:date("2002-03-07-07:00"), () ) xs:date("2002-03-07") deterministic context-dependent focus-independent deterministic context-independent focus-independent

Adjusts an xs:time value to a specific timezone, or to no timezone at all.

If $value is the empty sequence, then the function returns the empty sequence.

If $value does not have a timezone component and $timezone is the empty sequence, then the result is $value.

If $value does not have a timezone component and $timezone is not the empty sequence, then the result is $value with $timezone as the timezone component.

If $value has a timezone component and $timezone is the empty sequence, then the result is the localized value of $value without its timezone component.

If $value has a timezone component and $timezone is not the empty sequence, then:

Let $dt be the xs:dateTime value fn:dateTime(xs:date('1972-12-31'), $value).

Let $adt be the value of fn:adjust-dateTime-to-timezone($dt, $timezone)

The function returns the xs:time value xs:time($adt).

A dynamic error is raised if $timezone is less than -PT14H or greater than PT14H or if does not contain an integral number of minutes.

Assume the dynamic context provides an implicit timezone of -05:00 (-PT5H0M).

 adjust-time-to-timezone( xs:time("10:00:00") ) xs:time("10:00:00-05:00") adjust-time-to-timezone( xs:time("10:00:00-07:00") ) xs:time("12:00:00-05:00") adjust-time-to-timezone( xs:time("10:00:00"), $tz-10 ) xs:time("10:00:00-10:00") adjust-time-to-timezone( xs:time("10:00:00-07:00"), $tz-10 ) xs:time("07:00:00-10:00") adjust-time-to-timezone( xs:time("10:00:00"), () ) xs:time("10:00:00") adjust-time-to-timezone( xs:time("10:00:00-07:00"), () ) xs:time("10:00:00") adjust-time-to-timezone( xs:time("10:00:00-07:00"), xs:dayTimeDuration("PT10H") ) xs:time("03:00:00+10:00") deterministic context-dependent focus-independent deterministic context-independent focus-independent

Returns the timezone offset from UTC that is in conventional use at a given place and time.

This function uses a database of civil timezones (including daylight savings time) to return the timezone offset for a given date/time and place. For example, the timezone offset for New York on 31 December 2024 would be -PT5H.

If the $place argument is empty then the from the dynamic context is used.

If the supplied $value has no timezone then the implicit timezone from the dynamic context is used. This is unrelated to the timezone applicable to the requested $place.

The intended use of the $place argument is to identify the place where an event represented by the $value argument took place or will take place. The value must be an IANA timezone name as defined in the IANA timezone database . Examples are "America/New_York" and "Europe/Rome".

The result of the function is the civil timezone offset applicable to the given date/time and place, as determined by the IANA timezone database or an alternative authoritative source.

A dynamic error is raised if no timezone information is available for the given date/time and place. This includes the case where the given place is not present in the timezone database, and also the case where the information available for that place does not cover a sufficient range of dates.

 civil-timezone( xs:dateTime('2024-12-31T23:59:59'), 'America/New_York') xs:dayTimeDuration('-PT5H') civil-timezone( xs:dateTime('2024-06-30T23:59:59'), 'America/New_York') xs:dayTimeDuration('-PT4H') adjust-dateTime-to-timezone( current-dateTime(), civil-timezone(current-dateTime(), 'America/New_York') ) The current civil date and time in New York. civil-timezone(xs:dateTime('2024-07-01T09:00:00')) If the default place is a location in the same timezone as (say) Paris, then PT2H

New in 4.0

 Defines the semantics of the - operator when applied to two xs:dateTime values. deterministic context-dependent focus-independent

Returns an xs:dayTimeDuration representing the amount of elapsed time between the instants arg2 and arg1.

If either $arg1 or $arg2 do not contain an explicit timezone then, for the purpose of the operation, the implicit timezone provided by the dynamic context (See .) is assumed to be present as part of the value.

The function returns the elapsed time between the date/time instant arg2 and the date/time instant arg1, computed according to the algorithm given in Appendix E of , and expressed as a xs:dayTimeDuration.

If the normalized value of $arg1 precedes in time the normalized value of $arg2, then the returned value is a negative duration.

Assume that the dynamic context provides an implicit timezone value of -05:00.

 op:subtract-dateTimes( xs:dateTime("2000-10-30T06:12:00"), xs:dateTime("1999-11-28T09:00:00Z") ) xs:dayTimeDuration("P337DT2H12M") Defines the semantics of the - operator when applied to two xs:date values. deterministic context-dependent focus-independent

Returns the xs:dayTimeDuration that corresponds to the elapsed time between the starting instant of $arg2 and the starting instant of $arg2.

If either $arg1 or $arg2 do not contain an explicit timezone then, for the purpose of the operation, the implicit timezone provided by the dynamic context (See .) is assumed to be present as part of the value.

The starting instant of an xs:date is the xs:dateTime at 00:00:00 on that date.

The function returns the result of subtracting the two starting instants using op:subtract-dateTimes.

If the starting instant of $arg1 precedes in time the starting instant of $arg2, then the returned value is a negative duration.

Assume that the dynamic context provides an implicit timezone value of Z.

op:subtract-dates( xs:date("2000-10-30"), xs:date("1999-11-28") ) xs:dayTimeDuration("P337D") The normalized values of the two starting instants are { 2000, 10, 30, 0, 0, 0, xs:dayTimeDuration("PT0S") } and { 1999, 11, 28, 0, 0, 0, xs:dayTimeDuration("PT0S") }.

Now assume that the dynamic context provides an implicit timezone value of +05:00.

 op:subtract-dates( xs:date("2000-10-30"), xs:date("1999-11-28Z") ) xs:dayTimeDuration("P336DT19H") The normalized values of the two starting instants are { 2000, 10, 29, 19, 0, 0, xs:dayTimeDuration("PT0S") } and { 1999, 11, 28, 0, 0, 0, xs:dayTimeDuration("PT0S") }. op:subtract-dates( xs:date("2000-10-15-05:00"), xs:date("2000-10-10+02:00") ) xs:dayTimeDuration("P5DT7H") Defines the semantics of the - operator when applied to two xs:time values. deterministic context-dependent focus-independent

Returns the xs:dayTimeDuration that corresponds to the elapsed time between the values of $arg2 and $arg1 treated as times on the same date.

The function returns the result of the expression:

op-subtract-dateTimes( dateTime(xs:date('1972-12-31'), $arg1), dateTime(xs:date('1972-12-31'), $arg2))

Any other reference date would work equally well.

Assume that the dynamic context provides an implicit timezone value of -05:00. Assume, also, that the date components of the reference xs:dateTime correspond to "1972-12-31".

 op:subtract-times( xs:time("11:12:00Z"), xs:time("04:00:00") ) xs:dayTimeDuration("PT2H12M") This is obtained by subtracting from the xs:dateTime value { 1972, 12, 31, 11, 12, 0, xs:dayTimeDuration("PT0S") } the xs:dateTime value { 1972, 12, 31, 9, 0, 0, xs:dayTimeDuration("PT0S") }. op:subtract-times( xs:time("11:00:00-05:00"), xs:time("21:30:00+05:30") ) xs:dayTimeDuration("PT0S") The two xs:dateTime values are { 1972, 12, 31, 11, 0, 0, xs:dayTimeDuration("-PT5H") } and { 1972, 12, 31, 21, 30, 0, xs:dayTimeDuration("PT5H30M") }. These normalize to { 1972, 12, 31, 16, 0, 0, xs:dayTimeDuration("PT0S") } and { 1972, 12, 31, 16, 0, 0, xs:dayTimeDuration("PT0S") }. op:subtract-times( xs:time("17:00:00-06:00"), xs:time("08:00:00+09:00") ) xs:dayTimeDuration("P1D") The two normalized xs:dateTime values are { 1972, 12, 31, 23, 0, 0, xs:dayTimeDuration("PT0S") } and { 1972, 12, 30, 23, 0, 0, xs:dayTimeDuration("PT0S") }. op:subtract-times( xs:time("24:00:00"), xs:time("23:59:59") ) xs:dayTimeDuration("-PT23H59M59S") The two normalized xs:dateTime values are { 1972, 12, 31, 0, 0, 0, () } and { 1972, 12, 31, 23, 59, 59.0, () }. Defines the semantics of the + operator when applied to an xs:dateTime and an xs:yearMonthDuration value. deterministic context-independent focus-independent

Returns the xs:dateTime that is a given duration after a specified xs:dateTime (or before, if the duration is negative).

The function returns the result of adding $arg2 to the value of $arg1 using the algorithm described in Appendix E of , disregarding the rule about leap seconds. If $arg2 is negative, then the result xs:dateTime precedes $arg1.

The result has the same timezone as $arg1. If $arg1 has no timezone, the result has no timezone.

op:add-yearMonthDuration-to-dateTime( xs:dateTime("2000-10-30T11:12:00"), xs:yearMonthDuration("P1Y2M") ) xs:dateTime("2001-12-30T11:12:00") Defines the semantics of the + operator when applied to an xs:dateTime and an xs:dayTimeDuration value. deterministic context-independent focus-independent

Returns the xs:dateTime that is a given duration after a specified xs:dateTime (or before, if the duration is negative).

The function returns the result of adding $arg2 to the value of $arg1 using the algorithm described in Appendix E of , disregarding the rule about leap seconds. If $arg2 is negative, then the result xs:dateTime precedes $arg1.

The result has the same timezone as $arg1. If $arg1 has no timezone, the result has no timezone.

op:add-dayTimeDuration-to-dateTime( xs:dateTime("2000-10-30T11:12:00"), xs:dayTimeDuration("P3DT1H15M") ) xs:dateTime("2000-11-02T12:27:00") Defines the semantics of the - operator when applied to an xs:dateTime and an xs:yearMonthDuration value. deterministic context-independent focus-independent

Returns the xs:dateTime that is a given duration before a specified xs:dateTime (or after, if the duration is negative).

The function returns the xs:dateTime computed by negating $arg2 and adding the result to $arg1 using the function op:add-yearMonthDuration-to-dateTime.

 op:subtract-yearMonthDuration-from-dateTime( xs:dateTime("2000-10-30T11:12:00"), xs:yearMonthDuration("P1Y2M") ) xs:dateTime("1999-08-30T11:12:00") Defines the semantics of the - operator when applied to an xs:dateTime an and xs:dayTimeDuration values

Returns the xs:dateTime that is a given duration before a specified xs:dateTime (or after, if the duration is negative).

The function returns the xs:dateTime computed by negating $arg2 and adding the result to $arg1 using the function op:add-dayTimeDuration-to-dateTime.

 op:subtract-dayTimeDuration-from-dateTime( xs:dateTime("2000-10-30T11:12:00"), xs:dayTimeDuration("P3DT1H15M") ) xs:dateTime("2000-10-27T09:57:00") Defines the semantics of the + operator when applied to an xs:date and an xs:yearMonthDuration value. deterministic context-independent focus-independent

Returns the xs:date that is a given duration after a specified xs:date (or before, if the duration is negative).

The function returns the result of casting $arg1 to an xs:dateTime, adding $arg2 using the function op:add-yearMonthDuration-to-dateTime, and casting the result back to an xs:date.

 op:add-yearMonthDuration-to-date( xs:date("2000-10-30"), xs:yearMonthDuration("P1Y2M") ) xs:date("2001-12-30") Defines the semantics of the + operator when applied to an xs:date and an xs:dayTimeDuration value. deterministic context-independent focus-independent

Returns the xs:date that is a given duration after a specified xs:date (or before, if the duration is negative).

The function returns the result of casting $arg1 to an xs:dateTime, adding $arg2 using the function op:add-dayTimeDuration-to-dateTime, and casting the result back to an xs:date.

 op:add-dayTimeDuration-to-date( xs:date("2004-10-30Z"), xs:dayTimeDuration("P2DT2H30M0S") ) xs:date("2004-11-01Z") The starting instant of the first argument is the xs:dateTime value { 2004, 10, 30, 0, 0, 0, xs:dayTimeDuration("PT0S") }. Adding the second argument to this gives the xs:dateTime value { 2004, 11, 1, 2, 30, 0, xs:dayTimeDuration("PT0S") }. The time components are then discarded. Defines the semantics of the - operator when applied to an xs:date and an xs:yearMonthDuration value. deterministic context-independent focus-independent

Returns the xs:date that is a given duration before a specified xs:date (or after, if the duration is negative).

Returns the xs:date computed by negating $arg2 and adding the result to $arg1 using the function op:add-yearMonthDuration-to-date.

 op:subtract-yearMonthDuration-from-date( xs:date("2000-10-30"), xs:yearMonthDuration("P1Y2M") ) xs:date("1999-08-30") op:subtract-yearMonthDuration-from-date( xs:date("2000-02-29Z"), xs:yearMonthDuration("P1Y") ) xs:date("1999-02-28Z") op:subtract-yearMonthDuration-from-date( xs:date("2000-10-31-05:00"), xs:yearMonthDuration("P1Y1M") ) xs:date("1999-09-30-05:00") Defines the semantics of the - operator when applied to an xs:date and an xs:dayTimeDuration. deterministic context-independent focus-independent

Returns the xs:date that is a given duration before a specified xs:date (or after, if the duration is negative).

Returns the xs:date computed by negating $arg2 and adding the result to $arg1 using the function op:add-dayTimeDuration-to-date.

 op:subtract-dayTimeDuration-from-date( xs:date("2000-10-30"), xs:dayTimeDuration("P3DT1H15M") ) xs:date("2000-10-26") Defines the semantics of the + operator when applied to an xs:time and an xs:dayTimeDuration value.

Returns the xs:time value that is a given duration after a specified xs:time (or before, if the duration is negative or causes wrap-around past midnight)

First, the days component in the canonical lexical representation of $arg2 is set to zero (0) and the value of the resulting xs:dayTimeDuration is calculated. Alternatively, the value of $arg2 modulus 86,400 is used as the second argument. This value is added to the value of $arg1 converted to an xs:dateTime using a reference date such as 1972-12-31, and the time component of the result is returned. Note that the xs:time returned may occur in a following or preceding day and may be less than $arg1.

The result has the same timezone as $arg1. If $arg1 has no timezone, the result has no timezone.

 op:add-dayTimeDuration-to-time( xs:time("11:12:00"), xs:dayTimeDuration("P3DT1H15M") ) xs:time("12:27:00") op:add-dayTimeDuration-to-time( xs:time("23:12:00+03:00"), xs:dayTimeDuration("P1DT3H15M") ) xs:time("02:27:00+03:00") That is, { 0, 0, 0, 2, 27, 0, xs:dayTimeDuration("PT3H") } Defines the semantics of the - operator when applied to an xs:time and an xs:dayTimeDuration value. deterministic context-independent focus-independent

Returns the xs:time value that is a given duration before a specified xs:time (or after, if the duration is negative or causes wrap-around past midnight)

The function returns the result of negating $arg2 and adding the result to $arg1 using the function op:add-dayTimeDuration-to-time.

 op:subtract-dayTimeDuration-from-time( xs:time("11:12:00"), xs:dayTimeDuration("P3DT1H15M") ) xs:time("09:57:00") op:subtract-dayTimeDuration-from-time( xs:time("08:20:00-05:00"), xs:dayTimeDuration("P23DT10H10M") ) xs:time("22:10:00-05:00") deterministic context-dependent focus-independent

Returns a string containing an xs:dateTime value formatted for display.

See .

The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.

 deterministic context-dependent focus-independent

Returns a string containing an xs:date value formatted for display.

See .

The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.

 deterministic context-dependent focus-independent

Returns a string containing an xs:time value formatted for display.

See .

The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.

 deterministic context-independent focus-independent

Parses a string containing the date and time in IETF format, returning the corresponding xs:dateTime value.

The function accepts a string matching the production input in the following grammar:

input ::= S? (dayname ","? S)? ((datespec S time) | asctime) S?
dayname ::= "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat" | "Sun" | "Monday | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday"
datespec ::= daynum dsep monthname dsep year
asctime ::= monthname dsep daynum S time S year
dsep ::= S | (S? "-" S?)
daynum ::= digit digit?
year ::= digit digit (digit digit)?
digit ::= [0-9]
monthname ::= "Jan" | "Feb" | "Mar" | "Apr" | "May" | "Jun" | "Jul" | "Aug" | "Sep" | "Oct" | "Nov" | "Dec"
time ::= hours ":" minutes (":" seconds)? (S? timezone)?
hours ::= digit digit?
minutes ::= digit digit
seconds ::= digit digit ("." digit+)?
timezone ::= tzname | tzoffset (S? "(" S? tzname S? ")")?
tzname ::= "UT" | "UTC" | "GMT" | "EST" | "EDT" | "CST" | "CDT" | "MST" | "MDT" | "PST" | "PDT"
tzoffset ::= ("+"|"-") hours ":"? minutes?
S ::= (x09 | x0A | x0D | x20)+

The input is case-insensitive: upper-case and lower-case distinctions in the above grammar show the conventional usage, but otherwise have no significance.

If the input is the empty sequence, the result is the empty sequence.

The dayname, if present, is ignored.

The daynum, monthname, and year supply the day, month, and year of the resulting xs:dateTime value. A two-digit year must have 1900 added to it. A year such as 0070 is to be treated as given; negative years are not permitted.

The hours, minutes, and seconds (including fractional seconds) values supply the corresponding components of the resulting xs:dateTime value; if the seconds value or the fractional seconds value is absent then zero is assumed.

If both a tzoffset and a tzname are supplied then the tzname is ignored.

If a tzoffset is supplied then this defines the hours and minutes parts of the timezone offset:

If it contains a colon, this separates the hours part from the minutes part.

Otherwise, the grammar allows a sequence of from one to four digits. These are interpreted as H, HH, HMM, or HHMM respectively, where H or HH is the hours part, and MM (if present) is the minutes part.

If the minutes part is absent it defaults to 00.

If a tzname is supplied with no tzoffset then it is translated to a timezone offset as follows:

tzname Offset
UT, UTC, GMT 00:00
EST -05:00
EDT -04:00
CST -06:00
CDT -05:00
MST -07:00
MDT -06:00
PST -08:00
PDT -07:00

If neither a tzoffset nor tzname is supplied, a timezone offset of 00:00 is assumed.

A dynamic error is raised if the input does not match the grammar, or if the resulting date/time value is invalid (for example, "31 February").

The parse-ietf-date function attempts to interpret its input as a date in any of the three formats specified by HTTP .

These formats are used widely on the Internet to represent timestamps, and were specified in:

(electronic mail), extended in to allow four-digit years;

(Usenet Messages), obsoleted by ;

POSIX asctime() format

(HTTP) officially uses a subset of those three formats restricted to GMT.

The grammar for this function is slightly more liberal than the RFCs (reflecting the internet tradition of being liberal in what is accepted). For example the function:

Accepts a single-digit value where appropriate in place of a two-digit value with a leading zero (so "Wed 1 Jun" is acceptable in place of "Wed 01 Jun", and the timezone offset "-5:00" is equivalent to "-05:00")

Accepts one or more whitespace characters (x20, x09, x0A, x0D) wherever a single space is required, and allows whitespace to be omitted where it is not required for parsing

Accepts and ignores whitespace characters (x20, x09, x0A, x0D) at the start or end of the string.

In new protocols IETF recommends the format of , which is based on a profile of ISO 8601 similar to that already used in XPath and XSD, but the “approximate” format described here is very widely used.

An date can be generated approximately using fn:format-dateTime with a picture string of "[FNn3], [D01] [MNn3] [Y04] [H01]:[m01]:[s01] [Z0000]".

 parse-ietf-date("Wed, 06 Jun 1994 07:29:35 GMT") xs:dateTime("1994-06-06T07:29:35Z") parse-ietf-date("Wed, 6 Jun 94 07:29:35 GMT") xs:dateTime("1994-06-06T07:29:35Z") parse-ietf-date("Wed Jun 06 11:54:45 EST 2013") xs:dateTime("2013-06-06T11:54:45-05:00") parse-ietf-date("Sunday, 06-Nov-94 08:49:37 GMT") xs:dateTime("1994-11-06T08:49:37Z") parse-ietf-date("Wed, 6 Jun 94 07:29:35 +0500") xs:dateTime("1994-06-06T07:29:35+05:00") deterministic context-independent focus-independent

Returns an xs:QName value (that is, an expanded-QName) by taking an xs:string that has the lexical form of an xs:QName (a string in the form "prefix:local-name" or "local-name") and resolving it using the in-scope namespaces for a given element.

If $value is the empty sequence, returns the empty sequence.

More specifically, the function searches the namespace bindings of $element for a binding whose name matches the prefix of $value, or the zero-length string if it has no prefix, and returns an expanded-QName whose local name is taken from the supplied $value, and whose namespace URI is taken from the string value of the namespace binding.

If the $value has no prefix, and there is no namespace binding for $element corresponding to the default (unnamed) namespace, then the resulting expanded-QName has no namespace part.

The prefix (or absence of a prefix) in the supplied $value argument is retained in the returned expanded-QName, as described in .

A dynamic error is raised if $value does not have the correct lexical form for an instance of xs:QName.

A dynamic error is raised if $value has a prefix and there is no namespace binding for $element that matches this prefix.

Sometimes the requirement is to construct an xs:QName without using the default namespace. This can be achieved by writing:

if (contains($value, ":")) then resolve-QName($value, $element) else QName("", $value)

If the requirement is to construct an xs:QName using the namespaces in the static context, then the xs:QName constructor should be used.

 ]]> fn:resolve-QName("hello", $element) #Q{}hello fn:resolve-QName("eg:myFunc", $element) #Q{http://ns.example.com/}eg:myFunc deterministic context-independent focus-independent

Returns an xs:QName value formed using a supplied namespace URI and lexical QName.

The namespace URI in the returned QName is taken from $uri. If $uri is the zero-length string or the empty sequence, it represents “no namespace”.

The prefix (or absence of a prefix) in $qname is retained in the returned xs:QName value.

The local name in the result is taken from the local part of $qname.

A dynamic error is raised if $qname does not have the correct lexical form for an instance of xs:QName.

A dynamic error is raised if $uri is the zero-length string or the empty sequence, and the value of $qname contains a colon (:).

A dynamic error may be raised if $uri is not a valid URI (XML Namespaces 1.0) or IRI (XML Namespaces 1.1).

QName("http://www.example.com/example", "person") #Q{http://www.example.com/example}person QName("http://www.example.com/example", "ht:person") #Q{http://www.example.com/example}ht:person deterministic context-dependent focus-independent

Returns an xs:QName value formed by parsing an EQName.

If $value is the empty sequence, the result is the empty sequence.

Otherwise, leading and trailing whitespace in $value is stripped: call the result V

If V is castable to xs:NCName, the result is fn:QName("", $value): that is, a QName in no namespace.

If V is in the lexical space of xs:QName (that is, if it is in the form prefix:local), the result is xs:QName($value). Note that this result depends on the in-scope prefixes in the static context, and may result in various error conditions.

If V takes the form of a XPath URIQualifiedName (that is, Q{uri}local, where the uri part may be zero-length, or Q{uri}prefix:local), then the result is fn:QName(uri, local) or fn:QName(uri, prefix:local) respectively.

The rules used for parsing a within a URIQualifiedName are the XPath rules, not the XQuery rules (the XQuery rules require special characters such as < and & to be escaped).

A dynamic error is raised if the supplied value of $value, after whitespace normalization, does not match the XPath production EQName, or if the input is a URIQualifiedName in which the namespace prefix is present but the namespace URI is absent.

A dynamic error is raised if the supplied value of $value, after whitespace normalization, is in the form prefix:local (with a non-absent prefix), and the prefix cannot be resolved to a namespace URI using the in-scope namespace bindings from the static context.

 fn:parse-QName("Q{http://www.example.com/ns}person") fn:QName("http://www.example.com/ns", "person") fn:parse-QName("person") fn:QName("", "person") fn:parse-QName("Q{}person") fn:QName("", "person") fn:parse-QName("Q{http://www.example.com/ns}xmp:person") fn:QName("http://www.example.com/ns", "xmp:person") declare namespace xmp = "http://www.example.com/ns"; fn:parse-QName("xmp:person") #Q{http://www.example.com/ns}xmp:person

New in 4.0

 deterministic context-independent focus-independent

Returns a string representation of an xs:QName in the format Q{uri}local.

If $value is the empty sequence, returns the empty sequence.

The result is a string in the format Q{uri}local, where:

uri is the result of fn:string(fn:namespace-uri-from-QName($value)) (which will be a zero-length string if the QName is in no namespace), and

local is the result of fn:local-name-from-QName($value).

There is no escaping of special characters in the namespace URI. If the namespace URI contains curly braces, the resulting string will not be a valid BracedURILiteral.

 QName("http://example.com/", "person") => expanded-QName() "Q{http://example.com/}person" QName("", "person") => expanded-QName() "Q{}person"

New in 4.0

 deterministic context-independent focus-independent

Returns the prefix component of the supplied QName.

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

If $value has no prefix component the function returns the empty sequence.

Otherwise, the function returns an xs:NCName representing the prefix component of $value.

 deterministic context-independent focus-independent

Returns the local part of the supplied QName.

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

Otherwise, the function returns an xs:NCName representing the local part of $value.

 local-name-from-QName(#Q{http://www.example.com/ns}person) "person" deterministic context-independent focus-independent

Returns the namespace URI part of the supplied QName.

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

Otherwise, the function returns an xs:anyURI representing the namespace URI part of $value.

If $value is in no namespace, the function returns the zero-length xs:anyURI.

 namespace-uri-from-QName(#Q{http://www.example.com/ns}person) xs:anyURI("http://www.example.com/ns") deterministic context-independent focus-independent

Returns the namespace URI of one of the in-scope namespaces for $element, identified by its namespace prefix.

The function returns the result of the expression map:get(fn:in-scope-namespaces($element), string($value)).

 ]]> namespace-uri-for-prefix("z", $e) "http://example.org/two" namespace-uri-for-prefix("", $e) "http://example.org/one" namespace-uri-for-prefix((), $e) "http://example.org/one" namespace-uri-for-prefix("xml", $e) "http://www.w3.org/XML/1998/namespace" deterministic context-independent focus-independent

Returns the in-scope namespaces of an element node, as a map.

The function returns a map representing the prefixes of the in-scope namespaces for $element. The map contains one entry for each in-scope namespace: the key of the entry is the namespace prefix or a zero-length string, and the corresponding value is the namespace URI.

For namespace bindings that have a prefix, the key represents the prefix as an instance of xs:NCName. For the default namespace, which has no prefix, the key is the zero-length string as an instance of xs:string.

The order of entries in the returned map is .

The XML namespace is in scope for every element, so the result will always include an entry with key "xml" and corresponding value http://www.w3.org/XML/1998/namespace.

 ]]> in-scope-namespaces($e) { "": "http://example.org/one", "z": "http://example.org/two", "xml": "http://www.w3.org/XML/1998/namespace" }

New in 4.0

 nondeterministic-wrt-ordering context-independent focus-independent

Returns the prefixes of the in-scope namespaces for an element node.

The function returns the result of the expression map:keys(fn:in-scope-namespaces($element)) (but in no defined order).

The XML namespace is in scope for every element, so the result will always include the string "xml".

 deterministic context-dependent focus-dependent deterministic context-independent focus-independent

Returns the name of a node, as an xs:string that is either the zero-length string, or has the lexical form of an xs:QName.

If $node 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 value of the expression fn:string(fn:node-name($node)).

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

If the context value is absent, type error

If the context value is not an instance of the sequence type xnode()?, type error .

Because the result depends on the choice of namespace prefixes in the source document, it is not good practice to use the result of this function for anything other than display purposes. For example, the test name(.) = 'my:profile' will fail if the source document uses an unexpected namespace prefix. Such a test (assuming it relates to an element node) is better written as boolean(self::my:profile).

One

Two

Three ]]> name($e//*[@id = 'alpha']) "p" name($e//*[@id = 'gamma']) "p" name($e//*[@id = 'delta']) "ex:p" name($e//processing-instruction()) "pi" name($e//*[@id = 'alpha']/text()) "" name($e//*[@id = 'alpha']/@id) "id" name($e//*[@id = 'alpha']/@xml:id) "xml:id" deterministic context-dependent focus-dependent deterministic context-independent focus-independent

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.

If $node 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 . This will be an xs:string whose lexical form is an xs:NCName.

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

If the context value is absent, type error

If the context value is not a single node, type error .

One

Two

Three ]]> 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" deterministic context-dependent focus-dependent deterministic context-independent focus-independent

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

If $node is the empty sequence, if the node identified by 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 ) 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 ), returned as an xs:anyURI value.

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

If the context value is absent, type error

If the context value is not an instance of the sequence type xnode()?, type error .

One

Two

Three ]]> 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" deterministic context-dependent focus-dependent deterministic context-independent focus-independent

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

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 . If the conversion to xs:double fails, the xs:double value NaN is returned.

A type error is raised if $value is omitted and the context value is absent.

As a consequence of the rules given above, a type error is raised 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.

The string +INF is permitted as a representation of positive infinity, whether or not XSD 1.1 is supported. Similarly, -0 and 0 produce negative zero and positive zero respectively.

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.

 ]]> 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 deterministic context-dependent focus-dependent deterministic context-independent focus-independent

This function tests whether the language of $node, or the context value if the second argument is omitted, as specified by xml:lang attributes is the same as, or is a sublanguage of, the language specified by $language.

The language of the argument $node is determined by the value of the xml:lang attribute on the node, or, if the node has no such attribute, by the value of the xml:lang attribute on the nearest ancestor of the node that has an xml:lang attribute. If there is no such ancestor, then the function returns false.

If $language is the empty sequence, it is interpreted as the zero-length string.

The relevant xml:lang attribute is determined by the value of the XPath expression:

(ancestor-or-self::*/@xml:lang)[last()]

If this expression returns the empty sequence, the function returns false.

Otherwise, the function returns true if and only if, based on a caseless default match as specified in section 3.13 of , either:

$language is equal to the string-value of the relevant xml:lang attribute, or

$language is equal to some substring of the string-value of the relevant xml:lang attribute that starts at the start of the string-value and ends immediately before a hyphen, - (HYPHEN-MINUS, #x002D).

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

If the context value is absent, type error

If the context value is not a single node, type error .

 <para xml:lang="en"/> -> fn:lang("en") true() <div xml:lang="en"><para>And now, and forever!</para></div> -> fn:lang("en") true() <para xml:lang="EN"/> -> fn:lang("en") true() <para xml:lang="en-us"/> -> fn:lang("en") true() <para xml:lang="EN"/> -> fn:lang("fr") false() <para xml:lang="en-us"/> -> fn:lang("en-GB") false() deterministic context-dependent focus-dependent deterministic context-independent focus-independent deterministic context-independent focus-independent

Returns a path expression that can be used to select the supplied node relative to the root of its containing document.

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

The $options argument defines additional parameters controlling how the output is formatted. The option parameter conventions apply. The options available are as follows:

A GNode, which must be an ancestor of $node. If present, the returned path will be a relative path that selects $node starting from the supplied origin node, rather than from the root of the containing tree. node()? () If true, the names of element nodes in the path are represented by the result of a call on the name function applied to each element. The result in this case does not contain sufficient information to identify the namespace URI of the element. xs:boolean false A map from namespace prefixes to namespace URIs, such as might be returned by the function fn:in-scope-namespaces. If a prefix is available for a given URI, it is used in preference to using Q{uri}local notation. map((xs:NCName | enum('')), xs:anyURI)? () If true, the returned path includes the index positions of nodes. If false, only the node names are included. xs:boolean true

Let R be the GNode supplied in the origin option, or the root GNode of the tree containing $node otherwise.

If $node is a document node, or a JNode with no parent, the function returns the string "/".

Otherwise, the function returns a string that consists of a sequence of steps, one for each ancestor-or-self of $node that is not an ancestor-or-self of R.

If R is an XNode other than a document node and the origin option is absent or empty, then this string is preceded by a string notionally representing a call to the fn:root function, expressed as follows:

If the lexical option is present with the value true, then the string "fn:root()".

If the namespaces option is present and defines a mapping from a non empty prefix P to the namespace URI http://www.w3.org/2005/xpath-functions, then "P:root()"

If the namespaces option is present and defines a mapping from the empty string to the namespace URI http://www.w3.org/2005/xpath-functions, then "root()"

Otherwise, "Q{http://www.w3.org/2005/xpath-functions}root()".

Each step is the concatenation of:

The character "/", which is omitted for the first step if the origin option is present;

A string whose form depends on the kind of node selected by that step, as follows:

For an element node, the concatenation of:

A representation of the element name, chosen as follows:

If the lexical option is present with the value true, then the result of applying the name function to the element node.

Otherwise, if the namespaces option is present and the element is in a namespace U and the namespaces option includes a mapping from a prefix P to the namespace U, then the string P:L, where L is the local part of the element name. If there is more than one such prefix, then one of them is chosen arbitrarily.

Otherwise, if the namespaces option is present and the element is in a namespace U and the namespaces option includes a mapping from the zero-length string to the namespace U, then the local part of the element name.

Otherwise, if the namespaces option is present and the element is in no namespace and the namespaces option includes no mapping from the zero-length string to any namespace, then the local part of the element name.

Otherwise, the string Q{U}L, where U is the namespace URI of the element name or the empty string if the element is in no namespace, and L is the local part of the element name.

Unless the indexes option is present with the value false, a string in the form [position] where position is an integer representing the one-based position of the selected node among its like-named siblings.

For an attribute node, the concatenation of:

The character "@"

If the lexical option is present with the value true, then the result of applying the name function to the attribute node.

Otherwise, if the attribute node is in no namespace, the local part of the attribute name.

Otherwise, if the namespaces option is present, and if it includes a mapping from a non-empty namespace prefix P to the namespace URI of the attribute, then a string in the form P:L, where L is the local part of the attribute name. If there is more than one such prefix, then one of them is chosen arbitrarily.

Otherwise, the string Q{U}L, where U is the namespace URI of the attribute name, and L is the local part of the attribute name.

For a text node: text()[position] where position is an integer representing the position of the selected node among its text node siblings.

The suffix [position] is omitted if the indexes option is present with the value false.

For a comment node: comment()[position] where position is an integer representing the position of the selected node among its comment node siblings.

The suffix [position] is omitted if the indexes option is present with the value false.

For a processing-instruction node: processing-instruction(local)[position] where local is the name of the processing instruction node and position is an integer representing the position of the selected node among its like-named processing-instruction node siblings.

The suffix [position] is omitted if the indexes option is present with the value false.

For a namespace node:

If the namespace node has a name: namespace::prefix, where prefix is the local part of the name of the namespace node (which represents the namespace prefix).

If the namespace node has no name (that is, if it represents the default namespace): namespace::*[Ulocal-name() = ""]

Here Ulocal-name() represents a call on the function fn:local-name and is formatted using the same conventions as the call on fn:root described earlier.

For a JNode:

Let K be the value of the ·jkey· property.

If K is an xs:string, xs:untypedAtomic, or xs:anyURI that is castable to xs:NCName, then the result of casting K to xs:NCName.

If the value is an xs:string, xs:untypedAtomic, or xs:anyURI that is not castable to xs:NCName, then the string "K" (including the quotation marks), with any contained quotation marks escaped by doubling them.

If K is numeric, then the string N where N is the result of casting K to xs:string.

This includes the case where the parent of the JNode is an array.

If K is an xs:QName, then the string #Q{uri}local where uri and local are the namespace URI and local name parts of the QName.

If K is an xs:boolean, then the string true() or false().

If K is of any other type, then as the string child::{xs:T("S")} (including the enclosing braces) where T is the local part of the name of the most specific built-in atomic type of which the value is an instance, and S is the result of casting K to xs:string.

Escaping of embedded quotation marks is not necessary in this case, because they will never arise for the types covered by this rule.

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

If the context value is absent, type error

If the context value is not an instance of the sequence type node()?, type error .

If the value of the origin option is a node that is not an ancestor of $node (or in the absence of $node, the context value), dynamic error .

Using the namespaces option to shorten the generated path is often convenient, but the resulting path may be unusable if the input tree contains multiple bindings for the same prefix.

Similarly, using the lexical option is convenient if there is no need for precise namespace information: it is especially suitable when the containing node tree declares no namespaces.

If the supplied argument is a map or an array, it will automatically be coerced to a JNode. This however is not useful, because this will be a root JNode, yielding the path /.

If there is a requirement to use the generated path as an XPath expression in order to retrieve nodes, perhaps from a different document $doc, this can be achieved as follows:

Call the fn:path function with default options: let the result be $path.

Choose some arbitrary XQuery module URI, say "http://example.com/pathfinder".

Set the variable $module to the string:

"module namespace f = 'http://example.com/pathfinder'; declare function f:eval($root) { $root " || $path || "};"

Construct a function, say $evalPath:

let $evalPath := fn:load-xquery-module($module-uri, {'content': $module} ?functions/?#Q{http://example.com/pathfinder}eval

Call this function to evaluate the path with a given root:

return $evalPath($doc) Freude, schöner Götterfunken,
Tochter aus Elysium,
Wir betreten feuertrunken,
Himmlische, dein Heiligtum.

}]]> path($e) '/' path($e/*:p) '/Q{http://example.com/one}p[1]' path($e/*:p, { 'namespaces': in-scope-namespaces($e/*) }) '/p[1]' path($e/*:p, { 'indexes': false() }) '/Q{http://example.com/one}p' path($e/*:p/@xml:lang) '/Q{http://example.com/one}p[1]/@Q{http://www.w3.org/XML/1998/namespace}lang' path($e//@xml:lang, { 'namespaces': in-scope-namespaces($e/*) }) '/p[1]/@xml:lang' path($e/*:p/@author) '/Q{http://example.com/one}p[1]/@author' path($e/*:p/*:br[2]) '/Q{http://example.com/one}p[1]/Q{http://example.com/one}br[2]' path($e/*:p/*:br[2], { 'namespaces': { 'N': 'http://example.com/one' }, 'indexes': false() }) '/N:p/N:br' path($e//text()[starts-with(normalize-space(), 'Tochter')]) '/Q{http://example.com/one}p[1]/text()[2]' path($e/*:p/*:br[2], { 'lexical': true() }) '/p[1]/br[2]' path($e/*:p/*:br[2], { 'lexical': true(), 'origin': $e/*:p }) 'br[2]' E21256 John Brown ]]> path($emp) 'Q{http://www.w3.org/2005/xpath-functions}root()' path($emp/@xml:id) 'Q{http://www.w3.org/2005/xpath-functions}root()/@Q{http://www.w3.org/XML/1998/namespace}id' path($emp/empnr) 'Q{http://www.w3.org/2005/xpath-functions}root()/Q{}empnr[1]' path($emp/empnr, { 'lexical': true() }) 'fn:root()/empnr[1]' path($emp/empnr, { 'namespaces': { 'fn': 'http://www.w3.org/2005/xpath-functions', '': '' } }) 'fn:root()/empnr[1]' let $in := [ { "b": [ 3, 4 ] } ] return path($in/*[1]/b/*[2]) "/1/b/2" let $in := [ [ { 'a': 1 } ], [ { 'a': 2 } ] ] return path($in//a[. = 2]) "/2/1/a" let $in := [ { "London": 1, "New York": 2 } ] return path($in/*/*[. = 2]) '/1/"New York"' let $in := [ { xs:date('2026-04-18'): 1, xs:date('2026-03-04'): 2 } ] return path($in/*/*[. = 2]) '/1/child::{xs:date("2026-03-04")}'

Options are added to customize the form of the output.

The function is extended to handle JNodes.

 deterministic context-dependent focus-dependent special-streaming-rules deterministic context-independent focus-independent special-streaming-rules

Returns the root of the tree to which $node belongs. The function can be applied both to XNodes and to JNodes.

The function returns the value of the expression $node/ancestor-or-self::node()[last()].

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

If the context value is absent, type error

If the context value is not an instance of the sequence type node()?, type error .

These examples use some variables which could be defined in 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 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().

 deterministic context-dependent focus-dependent deterministic context-independent focus-independent

Returns true if the supplied GNode has one or more child nodes (of any kind).

Provided that the supplied argument $node matches the expected type node()?, the result of the function call fn:has-children($node) is defined to be the same as the result of the expression fn:exists($node/child::node()).

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

If the context value is absent, type error

If the context value is not an instance of the sequence type node()?, type error .

If $node is the empty sequence, the result is false.

The motivation for this function is to support streamed evaluation. According to the streaming rules in , the following construct is not streamable:

]]>

This is because it makes two downward selections to read the child row elements. The use of fn:has-children in the xsl:if conditional is intended to circumvent this restriction.

Although the function was introduced to support streaming use cases, it has general utility as a convenience function.

If the supplied argument is a map or an array, it will automatically be coerced to a JNode.

One

Three

]]> has-children($e) true() has-children($e//p[1]) true() has-children($e//p[2]) false() has-children($e//p[3]) true() has-children($e//processing-instruction()) false() has-children($e//p[1]/text()) false() has-children($e//p[1]/@id) false() jtree([1,2,3]) => has-children() true() jtree([]) => has-children() false()

Generalized to work with JNodes as well as XNodes.

 deterministic context-independent focus-independent special-streaming-rules

Removes duplicate GNodes and sorts the input into document order.

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.

Document order is (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.

 ') return distinct-ordered-nodes(($x//c, $x//b, $x//a, $x//b)) ! name() ]]> "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. 1 The root JNode is constructed once, so the first array member is selected by two different routes as the same JNode; the duplicate is eliminated.

New in 4.0

 deterministic context-independent focus-independent special-streaming-rules

Returns every GNode within the input sequence that is not an ancestor of another member of the input sequence; the GNodes are returned in document order with duplicates eliminated.

The effect of the function call fn:innermost($nodes) is defined to be equivalent to the result of the expression:

$nodes except $nodes/ancestor::node()

That is, the function takes as input a sequence of GNodes, and returns every GNode within the sequence that is not an ancestor of another GNode within the sequence; the GNodes are returned in document order with duplicates eliminated.

If the supplied argument includes a map or an array, it will automatically be coerced to a JNode.
" -> parse-xml(.)//div -> innermost(.) -> for-each(., fn { string(@id) }) ]]> "c" innermost() =!> jvalue() ]]> [ 1, 2 ], [ 3, 4 ], [ 5, 6 ], [ 7, 8 ]

Generalized to work with JNodes as well as XNodes.

 deterministic context-independent focus-independent special-streaming-rules

Returns every GNode within the input sequence that has no ancestor that is itself a member of the input sequence; the nodes are returned in document order with duplicates eliminated.

The effect of the function call fn:outermost($nodes) is defined to be equivalent to the result of the expression:

$nodes[not(ancestor::node() intersect $nodes)]/.

That is, the function takes as input a sequence of GNodes, and returns every GNode within the sequence that does not have another GNode within the sequence as an ancestor; the GNodes are returned in document order with duplicates eliminated.

The formulation $nodes except $nodes/descendant::node() might appear to be simpler, but does not correctly account for attribute nodes, as these are not descendants of their parent element.

The motivation for the function was based on XSLT streaming use cases. There are cases where the streaming rules allow the construct outermost(//section) but do not allow //section; the function can therefore be useful in cases where it is known that sections will not be nested, as well as cases where the application actually wishes to process all sections except those that are nested within another.

If the supplied argument includes a map or an array, it will automatically be coerced to a JNode.
" -> parse-xml(.)//div -> outermost(.) -> for-each(., fn { string(@id) }) ]]> "a" outermost() =!> array:size() ]]> 3

Generalized to work with JNodes as well as XNodes.

 deterministic context-dependent focus-independent deterministic context-dependent focus-independent

Returns a sequence of positive integers giving the positions within the sequence $input of items that are to $target.

The function returns a sequence of positive integers giving the 1-based positions within the sequence $input of items that are to $target.

The collation used by this function is determined according to the rules in . This collation is used when string comparison is required.

The result sequence is in ascending numeric order.

If $input is the empty sequence, or if no item in $input matches $target, then the function returns the empty sequence.

No error occurs if non-comparable values are encountered. So when comparing two atomic items, the effective boolean value of fn:index-of($a, $b) is true if $a and $b are equal, false if they are not equal or not comparable.

 index-of((10, 20, 30, 40), 35) () index-of((10, 20, 30, 30, 20, 10), 20) 2, 5 index-of( ("a", "sport", "and", "a", "pastime"), "a" ) 1, 4 index-of( ("a", "b", "c"), "B", "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) 2 index-of(current-date(), 23) () index-of([ 1, [ 5, 6 ], [ 6, 7 ] ], 6) 3, 4 The array is atomized to a sequence of five integers

If @a is an attribute of type xs:NMTOKENS whose string value is "red green blue", and whose typed value is therefore ("red", "green", "blue"), then fn:index-of(@a, "blue") returns 3. This is because the function calling mechanism atomizes the attribute node to produce a sequence of three xs:NMTOKEN values.

In the interests of consistency, the index-of function now defines equality to mean . This has the implication that NaN is now considered equal to NaN.

 deterministic context-independent focus-independent

Returns true if the argument is the empty sequence.

If $input is the empty sequence, the function returns true; otherwise, the function returns false.

count($input) eq 0 empty((1, 2, 3)[10]) true() empty(remove(("hello", "world"), 1)) false() empty([]) false() empty({}) false() empty("") false()

Assuming $break is an element with no children:

let $break := <br/> return empty($break)

The result is false.

 deterministic context-dependent focus-dependent deterministic context-independent focus-independent

Returns the supplied GNode together with its siblings, in document order.

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

If $node is a child of some parent GNode P, the function returns all the children of P (including $node), in document order, as determined by the value of $node/child::node().

Otherwise (specifically, if $node is parentless, or if it is an attribute or namespace node), the function returns $node.

 if ($node intersect $node/parent::node()/child::node()) then $node/parent::node()/child::node() else $node

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

If the context value is absent, type error

If the context value is not an instance of the sequence type node()?, type error .

The result of siblings($n) (except in error cases) is the same as the result of $n/(preceding-sibling::node() | following-sibling-or-self::node()). It is also the same as $n/(preceding-sibling-or-self::node() | following-sibling::node())

As with names such as parent and child, the word sibling used here as a technical term is not a precise match to its use in describing human family relationships, but is chosen for convenience.

 Atext]]> siblings($e//a) ! string() "A", "text", "3.14159" siblings($e//processing-instruction('pi')) ! string() "A", "text", "3.14159" siblings($e//@x) ! string() "X"

New in 4.0

 deterministic context-independent focus-independent

Returns true if the argument is a non-empty sequence.

If $input is a non-empty sequence, the function returns true; otherwise, the function returns false.

count($input) gt 0 exists(remove(("hello"), 1)) false() exists(remove(("hello", "world"), 1)) true() exists([]) true() exists({}) true() exists("") true()

Assuming $break is an element with no children:

let $break := <br/> return exists($break)

The result is true.

 deterministic context-dependent focus-independent deterministic context-dependent focus-independent

Returns the values that appear in a sequence, with duplicates eliminated.

The function returns the sequence that results from removing from $values all but one of a set of values that are to one another, when compared using the collation selected according to the rules in and the implicit timezone from the dynamic context.

The ordering of the result is as follows:

For any set of values that compare equal, the one that is returned is the one that appears first in $values.

The items that are returned appear in the order of their first appearance within $values.

 filter($values, fn($item, $pos) { empty( filter( subsequence($values, 1, $pos - 1), deep-equal(?, $item, $collation) ) ) } )

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

Values of type xs:untypedAtomic are compared as if they were of type xs:string.

Values that cannot be compared, because the eq operator is not defined for their types, are considered to be distinct.

For numeric values, the rules are the same as fn:atomic-equal: positive and negative zero are treated as equal, NaN is treated as equal to NaN, and values of different numeric types are converted to unlimited-precision decimals for comparison purposes.

If xs:dateTime, xs:date or xs:time values do not have a timezone, they are considered to have the implicit timezone provided by the dynamic context for the purpose of comparison. Note that xs:dateTime, xs:date or xs:time values can compare equal even if their timezones are different.

 distinct-values((1, 2.0, 3, 2)) 1, 2.0, 3 distinct-values(( xs:untypedAtomic("cherry"), xs:untypedAtomic("plum"), xs:untypedAtomic("plum") )) xs:untypedAtomic("cherry"), xs:untypedAtomic("plum")

Changed in 4.0 to use transitive equality comparisons for numeric values.

The order of results is now prescribed; it was previously implementation-dependent.

Atomic items of types xs:hexBinary and xs:base64Binary are now mutually comparable. In rare cases, where an application uses both types and assumes they are distinct, this can represent a backwards incompatibility.

 deterministic context-dependent focus-independent deterministic context-dependent focus-independent

Returns the values that appear in a sequence more than once.

The items of $values are compared against each other, according to the rules of fn:distinct-values and with $collation as the collation selected according to the rules in .

From each resulting set of values that are considered equal, one value will be returned if the set contains more than one value.

Specifically, the function returns those items in $values that are to exactly one item appearing earlier in the sequence.

This means that the ordering of the result is as follows:

For any set of values that compare equal, the one that is returned is the one that appears second in $values.

The items that are returned appear in the order of their second appearance within $values.

 filter( $values, fn($item, $pos) { count( filter( subsequence($values, 1, $pos - 1), deep-equal(?, $item, $collation) ) ) eq 1 } )

The comparison rules are exactly the same as the fn:distinct-values function.

 duplicate-values((1, 2, 3, 1.0, 1e0)) 1.0 duplicate-values(1 to 100) () 1, '2', 2))]]> xs:untypedAtomic("1") The string "1" and the untyped value of the element node are considered equal, whereas the string "2" and the integer are considered unequal.

Raise an error for duplicates in an ID sequence:

let $ids := duplicate-values(//@id) where exists($ids) return error((), 'Duplicate IDs found: ' || string-join($ids, ', '))

New in 4.0

 deterministic context-independent focus-independent

Returns its argument value.

The function returns $input.

 $input

The function is useful in contexts where a function must be supplied, but no processing is required.

 identity(0) 0 identity(1 to 10) 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ') ! (identity(/) is /)]]> true() If the argument is a node, the function returns the identical node, not a copy identity(()) ()

New in 4.0

 deterministic context-independent focus-independent

Returns a sequence constructed by inserting an item or a sequence of items at a given position within an existing sequence.

The value returned by the function consists of all items of $input whose 1-based position is less than $position, followed by all items of $insert, followed by the remaining elements of $input, in that order.

filter($input, fn($item, $pos) { $pos lt $position }), $insert, filter($input, fn($item, $pos) { $pos ge $position })

If $input is the empty sequence, $insert is returned. If $insert is the empty sequence, $input is returned.

If $position is less than one (1), the first position, the effective value of $position is one (1). If $position is greater than the number of items in $input, then the effective value of $position is equal to the number of items in $input plus 1.

The value of $input is not affected by the sequence construction.

 insert-before($abc, 0, "z") "z", "a", "b", "c" insert-before($abc, 1, "z") "z", "a", "b", "c" insert-before($abc, 2, "z") "a", "z", "b", "c" insert-before($abc, 3, "z") "a", "b", "z", "c" insert-before($abc, 4, "z") "a", "b", "c", "z" deterministic context-independent focus-independent

Returns a new sequence containing all the items of $input except those at specified positions.

The function returns a sequence consisting of all items of $input whose 1-based position is not equal to any of the integers in $positions.

filter($input, fn($item, $pos) { not($pos = $positions) })

Any integer in $positions that is less than 1 or greater than the number of items in $input is effectively ignored.

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

If $positions is the empty sequence, the input sequence $input is returned unchanged.

 remove($abc, 0) "a", "b", "c" remove($abc, 1) "b", "c" remove($abc, 6) "a", "b", "c" remove((), 3) () remove($abc, 2 to 3) "a" remove($abc, ()) "a", "b", "c"

The second argument can now be a sequence of integers.

 deterministic context-independent focus-independent

Returns the first item in a sequence.

The function returns the first item in $input; if $input is empty, it returns the empty sequence.

 filter($input, fn($item, $pos) { $pos eq 1 }) head(1 to 5) 1 head(("a", "b", "c")) "a" head(()) () head([ 1, 2, 3 ]) [ 1, 2, 3 ] deterministic context-independent focus-independent

Returns all but the first item in a sequence.

The function all items in $input except the first, retaining order.

 filter($input, fn($item, $pos) { $pos gt 1 })

If $input is the empty sequence, or a sequence containing a single item, then the empty sequence is returned.

tail(1 to 5) 2, 3, 4, 5 tail(("a", "b", "c")) "b", "c" tail("a") () tail(()) () tail([ 1, 2, 3 ]) () deterministic context-independent focus-independent special-streaming-rules

Returns all but the last item in a sequence.

The function returns all items in $input except the last, retaining order.

 filter($input, fn($item, $pos) { $pos ne count($input) })

If $input is the empty sequence, or a sequence containing a single item, then the empty sequence is returned.

trunk(1 to 5) 1, 2, 3, 4 trunk(("a", "b", "c")) "a", "b" trunk("a") () trunk(()) () trunk([ 1, 2, 3 ]) ()

New in 4.0

 deterministic context-independent focus-independent

Produces multiple copies of a sequence.

The function returns the value of (1 to $count) ! $input.

 for-each(1 to $count, fn($item, $pos) { $input })

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

The $count argument is declared as xs:nonNegativeInteger, which means that a type error occurs if it is called with a negative value.

If the input sequence contains nodes, these are not copied: instead, the result sequence contains multiple references to the same node. So, for example, fn:count(fn:replicate(/, 6)|()) returns 1, because the fn:replicate call creates duplicates, and the union operation eliminates them.

 replicate(0, 6) 0, 0, 0, 0, 0, 0 replicate(("A", "B", "C"), 3) "A", "B", "C", "A", "B", "C", "A", "B", "C" replicate((), 5) () replicate(("A", "B", "C"), 1) "A", "B", "C" replicate(("A", "B", "C"), 0) ()

New in 4.0

 deterministic context-independent focus-independent

Inserts a separator between adjacent items in a sequence.

The function inserts a separator between adjacent items in a sequence. The input is returned unchanged if $separator is the empty sequence or if $input contains less than two items.

 for-each($input, fn($item, $pos) { if ($pos gt 1) { $separator }, $item }) insert-separator(1 to 5, "|") 1, "|", 2, "|" , 3, "|", 4, "|", 5 insert-separator((), "|") () insert-separator("A", "|") "A" insert-separator(1 to 3, ("⅓", "⅔")) 1, "⅓", "⅔", 2, "⅓", "⅔", 3

Insert an empty hr element between adjacent paragraphs:

)]]>

New in 4.0

 deterministic context-independent focus-independent special-streaming-rules

Returns the last item in a sequence.

The function returns the value of the expression $input[last()]

 filter($input, fn($item, $pos) { $pos eq count($input) })

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

foot(1 to 5) 5 foot(()) ()

New in 4.0

 deterministic context-independent focus-independent special-streaming-rules

Reverses the order of items in a sequence.

The function returns a sequence containing the items in $input in reverse order.

 fold-left($input, (), fn($result, $item) { $item, $result })

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

reverse($abc) "c", "b", "a" reverse(("hello")) "hello" reverse(()) () reverse([ 1, 2, 3 ]) [ 1, 2, 3 ] The input is a sequence containing a single item (the array) reverse(([ 1, 2, 3 ], [ 4, 5, 6 ])) [ 4, 5, 6 ], [ 1, 2, 3 ] deterministic context-independent focus-independent

Returns the contiguous sequence of items in $input beginning at the position indicated by $start and continuing for the number of items indicated by $length.

If the third argument is the empty sequence, the function returns:

$input[round($start) le position()]

Otherwise, the function returns:

$input[round($start) le position() and position() lt round($start) + round($length)] filter( $input, if (empty($length)) then ( fn($item, $pos) { round($start) le $pos } ) else ( fn($item, $pos) { round($start) le $pos and $pos lt round($start) + round($length) } ) )

The first item of a sequence is located at position 1, not position 0.

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

In the two-argument case, the function returns a sequence comprising those items of $input whose 1-based position is greater than or equal to $start (rounded to an integer). No error occurs if $start is zero or negative.

In the three-argument case, The function returns a sequence comprising those items of $input whose 1-based position is greater than or equal to $start (rounded to an integer), and less than the sum of $start and $length (both rounded to integers). No error occurs if $start is zero or negative, or if $start plus $length exceeds the number of items in the sequence, or if $length is negative.

The most common usage pattern is to supply integers as the arguments. In this case the rounding logic is unnecessary: subsequence($input, $start) returns all items in $input starting at position $start (one-based), while substring($input, $start, $length) returns the all items starting at position $start and ending at position $start + $length - 1.

In earlier versions the second and third arguments were defined to be of type xs:double, but this potentially leads to unnecessary conversions in the common case where the supplied arguments are integers.

The consequences of supplying values such as NaN or positive or negative infinity for the $start or $length arguments follow from the above rules, and are not always intuitive.

 subsequence($seq, 4) "item4", "item5" subsequence($seq, 3, 2) "item3", "item4"

The optional third argument can now be supplied as the empty sequence.

The argument type for the second and third arguments has changed from xs:double to xs:numeric. This creates a minor incompatibility: when running in XPath 1.0 compatibility mode, it is no longer possible to supply either of these arguments as a string.

 deterministic context-independent focus-independent

Returns a contiguous sequence of items from $input, with the start and end points located by applying predicates.

Informally, the function returns the subsequence of $input starting with the first item that matches the $from predicate, and ending with the first subsequent item that matches the $to predicate. If $from is true#0, it matches for the first item; if $to is false#0, it accepts all remaining items. If $from does not match any items in $input, the result is the empty sequence; if $to does not match any items, all items up to the last are included in the result.

 let $start := index-where($input, $from)[1] otherwise count($input) + 1 let $end := index-where($input, $to)[. ge $start][1] otherwise count($input) + 1 return slice($input, $start, $end)

The result includes both the item that matches the $from condition and the item that matches the $to condition. To select a subsequence that starts after the $from item, apply the fn:tail function to the result. To select a subsequence that ends before the $to item, apply the fn:trunk function to the result.

The predicate functions supplied to the $from and $to parameters can include an integer position argument as well as the item itself. This position will always be 1-based, relative to the start of $input. This means it is possible to select items based on their absolute position in the $input sequence, but there is no mechanism to select an end position relative to the start position. If this is needed, the function can be combined with others: for example, to select a subsequence of four items starting with "Barbara", use $input => subsequence-where(fn { . eq "Barbara" }) => slice(end := 4).

If the requirement is to select all elements stopping before the first h2 element if it exists, or up to the end of the sequence otherwise, the simplest solution is perhaps to write:

slice($input, end:=index-where($input, fn { boolean(self::h2) })[1])

A return value of () from the $from or $to predicate is treated as false.

 subsequence-where($names, starts-with(?, "E")) "Eliza", "Freda", "Gertrude", "Hilda" subsequence-where($names, to := starts-with(?, "D")) "Anna", "Barbara", "Catherine", "Delia" subsequence-where($names, to := starts-with(?, "D")) => trunk() "Anna", "Barbara", "Catherine" subsequence-where($names, starts-with(?, "E"), starts-with(?, "G")) "Eliza", "Freda", "Gertrude" subsequence-where( $names, starts-with(?, "D"), fn { string-length(.) gt 5 } ) "Delia", "Eliza", "Freda", "Gertrude" subsequence-where($names, starts-with(?, "M")) () subsequence-where($names, starts-with(?, "G"), starts-with(?, "Z")) "Gertrude", "Hilda" subsequence-where($names) "Anna", "Barbara", "Catherine", "Delia", "Eliza", "Freda", "Gertrude", "Hilda" subsequence-where( $names, fn($it, $pos) { ends-with($it, "a") and $pos gt 5 } ) "Freda", "Gertrude", "Hilda" subsequence-where( $names, to := fn($it, $pos) { ends-with($it, "a") and $pos ge 5 } ) "Anna", "Barbara", "Catherine", "Delia", "Eliza"

New in 4.0

 deterministic context-independent focus-independent

Returns a sequence containing the items from $input at positions defined by $at, in the order specified.

Returns the items in $input at the positions listed in $at, in order of the integers in the $at argument.

 for-each($at, fn($index) { subsequence($input, $index, 1) })

In the simplest case where $at is a single integer, fn:items-at($input, 3) returns the same result as $input[3].

Compared with a simple positional filter expression, the function is useful because:

It can select items at multiple positions, and unlike fn:subsequence, these do not need to be contiguous.

The $at expression can depend on the focus.

The order of the returned items can differ from their order in the $input sequence.

If any integer in $at is outside the range 1 to count($input), that integer is effectively ignored: no error occurs.

If either of the arguments is the empty sequence, the result is the empty sequence.

If $at contains duplicate integers, the result also contains duplicates. No de-duplication occurs. If the input sequence contains nodes, these are not copied: instead, the result sequence contains multiple references to the same node.

 items-at(11 to 20, 4) 14 items-at(11 to 20, 4 to 6) 14, 15, 16 items-at(11 to 20, (7, 3)) 17, 13 items-at(11 to 20, index-of(("a", "b", "c"), "b")) 12 items-at(characters("quintessential"), (4, 8, 3)) "n", "s", "i" items-at(characters("quintessential"), (4, 8, 1, 1)) "n", "s", "q", "q" items-at((), 832) () items-at((), ()) ()

New in 4.0

 deterministic context-independent focus-independent

Returns a sequence containing selected items from a supplied input sequence based on their position.

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

Let $S be the first of the following that applies:

If $start is zero and $step is negative, then fn:count($input).

If $start is zero, then 1.

If $start is negative, then fn:count($input) + $start + 1.

Otherwise, $start.

Let $E be the first of the following that applies:

If $end is zero and $step is negative, then 1.

If $end is zero, then fn:count($input).

If $end is negative, then fn:count($input) + $end + 1.

Otherwise, $end.

Let $STEP be the first of the following that applies:

If $step is zero, then:

If $E ge $S, then +1

Otherwise -1

Otherwise, $step.

If $STEP is negative, the function returns $input => fn:reverse() => fn:slice(-$S, -$E, -$STEP).

Otherwise the function returns the result of the expression:

$input[position() ge $S and position() le $E and (position() - $S) mod $STEP eq 0] TBA: define formal equivalent.

The function is inspired by the slice operators in Javascript and Python, but it differs in detail to accommodate the tradition of 1-based addressing in XPath. The end position is inclusive rather than exclusive, so that in the simple case where $start and $end are positive and $end > $start, fn:slice($in, $start, $end) returns the same result as $in[position() = $start to $end].

This function can be used to enhance the RangeExpression, defined in , to construct a sequence of integers based on steps other than 1.

When $step is negative and $start or $end is omitted, the omitted bound defaults to the opposite end of the sequence. Thus fn:slice($in, step := -1) returns the members of $in in reverse order.

 slice($in, start := 2, end := 4) "b", "c", "d" slice($in, start := 2) "b", "c", "d", "e" slice($in, end := 2) "a", "b" slice($in, start := 3, end := 3) "c" slice($in, start := 4, end := 3) "d", "c" slice($in, start := 2, end := 5, step := 2) "b", "d" slice($in, start := 5, end := 2, step := -2) "e", "c" slice($in, start := 2, end := 5, step := -2) () slice($in, start := 5, end := 2, step := 2) () slice($in) "a", "b", "c", "d", "e" slice($in, step := -1) "e", "d", "c", "b", "a" slice($in, start := -1) "e" slice($in, start := -3) "c", "d", "e" slice($in, end := -2) "a", "b", "c", "d" slice($in, start := 2, end := -2) "b", "c", "d" slice($in, start := -2, end := 2) "d", "c", "b" slice($in, start := -4, end := -2) "b", "c", "d" slice($in, start := -2, end := -4) "d", "c", "b" slice($in, start := -4, end := -2, step := 2) "b", "d" slice($in, start := -2, end := -4, step := -2) "d", "b" slice(("a", "b", "c", "d"), 0) "a", "b", "c", "d" slice((1 to 5), step := 2) 1, 3, 5

New in 4.0

 deterministic context-dependent focus-independent deterministic context-independent focus-independent

Determines whether one sequence starts with another, using a supplied callback function to compare items.

Informally, the function returns true if $input starts with $subsequence, when items are compared using the $compare function.

 count($input) ge count($subsequence) and every(for-each-pair($input, $subsequence, $compare))

There is no requirement that the $compare function should have the traditional qualities of equality comparison. The result is well-defined, for example, even if $compare is not transitive or not symmetric. A return value of () from the function is treated as false.

 starts-with-subsequence((), ()) true() starts-with-subsequence(1 to 10, 1 to 5) true() starts-with-subsequence(1 to 10, ()) true() starts-with-subsequence(1 to 10, 1 to 10) true() starts-with-subsequence(1 to 10, 1) true() starts-with-subsequence( 1 to 10, 101 to 105, fn($x, $y) { $x mod 100 = $y mod 100 } ) true() starts-with-subsequence( ("A", "B", "C"), ("a", "b"), fn($x, $y) { compare( $x, $y, "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) eq 0 } ) true()

")//p[2] return starts-with-subsequence( $p/ancestor::*[1], $p/parent::*, op("is") )]]> true() starts-with-subsequence(10 to 20, 1 to 5, op("gt")) true() starts-with-subsequence( ("Alpha", "Beta", "Gamma"), ("A", "B"), starts-with#2 ) true() starts-with-subsequence( ("Alpha", "Beta", "Gamma", "Delta"), 1 to 3, fn($x, $y) { ends-with($x, 'a' ) } ) true() True because the first three items in the input sequence end with "a".

New in 4.0

 deterministic context-dependent focus-independent deterministic context-independent focus-independent

Determines whether one sequence ends with another, using a supplied callback function to compare items.

Informally, the function returns true if $input ends with $subsequence, when items are compared using the $compare function.

 starts-with-subsequence(reverse($input), reverse($subsequence), $compare)

There is no requirement that the $compare function should have the traditional qualities of equality comparison. The result is well-defined, for example, even if $compare is not transitive or not symmetric.

A return value of () from the function is treated as false.

 ends-with-subsequence((), ()) true() ends-with-subsequence(1 to 10, 5 to 10) true() ends-with-subsequence(1 to 10, ()) true() ends-with-subsequence(1 to 10, 1 to 10) true() ends-with-subsequence(1 to 10, 10) true() ends-with-subsequence( 1 to 10, 108 to 110, fn($x, $y) { $x mod 100 = $y mod 100 } ) true() ends-with-subsequence( ("A", "B", "C"), ("b", "c"), fn($x, $y) { compare( $x, $y, "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) eq 0 } ) true()

")//p[2] return ends-with-subsequence( $p/ancestor::node()[last()], $p/root(), op("is") )]]> true() ends-with-subsequence(10 to 20, 1 to 5, op("gt")) true() ends-with-subsequence( ("Alpha", "Beta", "Gamma"), ("B", "G"), starts-with#2 ) true() ends-with-subsequence( ("Alpha", "Beta", "Gamma", "Delta"), 1 to 2, fn($x, $y) { string-length($x) eq 5 } ) true() True because the last two items in the input sequence have a string length of 5.

New in 4.0

 deterministic context-dependent focus-independent deterministic context-independent focus-independent

Determines whether one sequence contains another as a contiguous subsequence, using a supplied callback function to compare items.

Informally, the function returns true if $input contains a consecutive subsequence matching $subsequence, when items are compared using the $compare function.

 some $i in 0 to count($input) - count($subsequence) satisfies ( every $j in 1 to count($subsequence) satisfies $compare($input[$i + $j], $subsequence[$j]) )

There is no requirement that the $compare function should have the traditional qualities of equality comparison. The result is well-defined, for example, even if $compare is not transitive or not symmetric.

A return value of () from the function is treated as false.

 contains-subsequence((), ()) true() contains-subsequence(1 to 10, 3 to 6) true() contains-subsequence(1 to 10, (2, 4, 6)) false() contains-subsequence(1 to 10, ()) true() contains-subsequence(1 to 10, 1 to 10) true() contains-subsequence(1 to 10, 5) true() contains-subsequence( 1 to 10, 103 to 105, fn($x, $y) { $x mod 100 = $y mod 100 } ) true() contains-subsequence( ("A", "B", "C", "D"), ("b", "c"), fn($x, $y) { compare( $x, $y, "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) eq 0 } ) true()

")//chap return contains-subsequence( $chap ! child::*, $chap ! child::p, op("is") )]]> true() True because the p children of the chap element form a contiguous subsequence. contains-subsequence(10 to 20, (5, 3, 1), op("gt")) true() contains-subsequence( ("Alpha", "Beta", "Gamma", "Delta"), ("B", "G"), starts-with#2 ) true() contains-subsequence( ("Zero", "Alpha", "Beta", "Gamma", "Delta", "Epsilon"), 1 to 4, fn($x, $y) { ends-with($x, 'a') } ) true() True because there is a run of 4 consecutive items ending in "a".

New in 4.0

nondeterministic-wrt-ordering context-independent focus-independent

Returns the items of $input in an implementation-dependent order.

The function returns the items of $input in an implementation-dependent order.

Query optimizers may be able to do a better job if the order of the output sequence is not specified. For example, when retrieving prices from a purchase order, if an index exists on prices, it may be more efficient to return the prices in index order rather than in document order.

This function does not guarantee that the resulting sequence will be in an order different from the input sequence. Many times the two sequences will be identical.

unordered((1, 2, 3, 4, 5)) (1, 2, 3, 4, 5) deterministic context-independent focus-independent

Absorbs the argument.

The function absorbs the supplied $input argument and returns the empty sequence.

The function can be used to discard unneeded output of expressions (functions, third-party libraries, etc.).

It can also be used to discard results during development.

It is implementation-dependent whether the supplied argument is evaluated or ignored. An implementation may decide to evaluate nondeterministic expressions and ignore deterministic ones.

 void(1 to 1000000) () for $f in (identity#1, void#1) return $f(123) 123 let $mapping := () return for-each(1 to 10, $mapping otherwise void#0) () Indicates that if no mapping is supplied, all items are dropped.

New in 4.0

 deterministic context-independent focus-independent

Returns input if it contains zero or one items. Otherwise, raises an error.

Except in error cases, the function returns $input unchanged.

 if (count($input) le 1) then $input else error(#Q{http://www.w3.org/2005/xqt-errors}FORG0003))

A dynamic error is raised if $input contains more than one item.

 deterministic context-independent focus-independent

Returns $input if it contains one or more items. Otherwise, raises an error.

Except in error cases, the function returns $input unchanged.

 if (count($input) ge 1) then $input else error(#Q{http://www.w3.org/2005/xqt-errors}FORG0004))

A dynamic error is raised if $input is an empty sequence.

 deterministic context-independent focus-independent

Returns $input if it contains exactly one item. Otherwise, raises an error.

Except in error cases, the function returns $input unchanged.

 if (count($input) eq 1) then $input else error(#Q{http://www.w3.org/2005/xqt-errors}FORG0005))

A dynamic error is raised if $input is an empty sequence or a sequence containing more than one item.

 deterministic context-dependent focus-independent deterministic context-dependent focus-independent

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, or other function items that are equivalent.

The $options argument 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 }.

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.

Determines whether the base-uri of a node is significant. xs:boolean false 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 . If the argument is not supplied, or if it is empty, then the default collation from the dynamic context of the caller is used. xs:string fn:default-collation() Determines whether comments are significant. xs:boolean false 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. xs:boolean false Determines whether the id property of elements and attributes is significant. xs:boolean false Determines whether the idrefs property of elements and attributes is significant. xs:boolean false Determines whether an empty entry in a map (an entry whose value part is the empty sequence) is to be treated as absent. xs:boolean false Determines whether the in-scope namespaces of elements are significant. xs:boolean false 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 the empty sequence, to indicate that the normal rules should be followed. Note that returning () is not equivalent to returning false. fn($item1 as item(), $item2 as item()) as xs:boolean? fn:void#0 Determines whether the order of entries in maps is significant. xs:boolean false Determines whether namespace prefixes in xs:QName values (particularly the names of elements and attributes) are significant. xs:boolean false Determines whether the nilled property of elements and attributes is significant. xs:boolean false If non-empty, 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; the zero-length string requests no normalization. xs:string "" Controls whether the top-level order of the items of the input sequences is considered. xs:boolean true Determines whether processing instructions are significant. xs:boolean false Determines whether timezones in date/time values are significant. xs:boolean false Determines whether type annotations are significant. xs:boolean false Determines whether the variety of the type annotation of an element (whether it has complex content or simple content) is significant. xs:boolean true Determines whether nodes are compared using their typed values rather than their string values. xs:boolean true A list of QNames of elements considered to be unordered: that is, their child elements may appear in any order. xs:QName* () 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. enum("preserve", "strip", "normalize") preserve

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:

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

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

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:

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

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 the 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:

All of the following conditions are true:

$i1 is an atomic item.

$i2 is an atomic item.

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

One of the following conditions is true:

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

Otherwise, fn:compare($i1, $i2) returns zero.

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

One of the following conditions is true:

Option namespace-prefixes is false.

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

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

One of the following conditions is true:

Option timezones is false.

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

Neither $i1 nor $i2 has a timezone component.

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

All of the following conditions are true:

$i1 is a map.

$i2 is a map.

For the purposes of the rules below, we consider an entry in a map to be significant unless (a) the ignore-empty-entries option is true, and (b) the entry is a key-value pair whose value part is the empty sequence.

Both maps have the same number of significant entries.

For every significant entry in the first map, there is a significant entry in the second map that:

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

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

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

All the following conditions are true:

$i1 is an array.

$i2 is an array.

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

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).

All the following conditions are true:

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

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

Both nodes have the same node kind.

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.

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

Comment nodes are discarded if the option comments is false.

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

Adjacent text nodes are merged.

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

The option whitespace is set to strip or normalize; and

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

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.

One of the following conditions is true.

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

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

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

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

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

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

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

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

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

One of the following conditions is true:

The option type-variety is false.

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.

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.

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.

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.

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.

One of the following conditions holds:

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.

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.

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.

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).

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).

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.

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

All the following conditions are true:

$i1 is a JNode.

$i2 is a JNode.

The ·jvalue· property of $i1 is deep-equal to the ·jvalue· property of $i2.

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

All the following conditions are true:

$i1 is a function item, and is neither a map nor an array.

$i2 is a function item, and is neither a map nor an array.

$i1 and $i2 are equivalent.

In all other cases the result is false.

A type error is raised 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 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.

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 and ). 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.

 ]]> deep-equal($at, $at/*) false() deep-equal($at/name[1], $at/name[2]) false() deep-equal($at/name[1], $at/name[3]) true() deep-equal($at/name[1], 'Peter Parker') false() deep-equal( $at//name[@first="Bob"], $at//name[@last="Barker"], options := { 'items-equal': op('is') } ) true() Tests whether the two input sequences contain exactly the same nodes. deep-equal([ 1, 2, 3], [ 1, 2, 3 ]) true() deep-equal((1, 2, 3), [ 1, 2, 3 ]) false() deep-equal( { 1: 'a', 2: 'b' }, { 2: 'b', 1: 'a' } ) true() deep-equal( (1, 2, 3, 4), (1, 4, 3, 2), options := { 'ordered': false() } ) true() deep-equal( (1, 1, 2, 3), (1, 2, 3, 3), options := { 'ordered': false() } ) false() "), parse-xml("") )]]> true() By default, namespace prefixes are ignored "), parse-xml(""), options := { 'namespace-prefixes': true() } )]]> false() False because the namespace prefixes differ "), parse-xml(""), options := { 'in-scope-namespaces': true() } )]]> false() False because the in-scope namespace bindings differ "), parse-xml("") )]]> false() By default, order of elements is significant "), parse-xml(""), options := { 'unordered-elements': #a } )]]> true() The unordered-elements option means that the ordering of the children of a is ignored. x"), parse-xml(" x") )]]> false() By default, both the leading whitespace in the style attribute and the whitespace text node preceding the span element are significant. x"), parse-xml(" x"), options := { 'whitespace': 'normalize' } )]]> true() The whitespace option causes both the leading space in the attribute value and the whitespace preceding the span element to be ignored. 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 } } } ) true() For numeric values, the callback function tests whether they are approximately equal. For any other items, it returns the empty sequence, so the normal comparison rules apply. deep-equal( (1, 2, 3, 4, 5), (1, 2, 3, 8, 5), options := { 'items-equal': fn($x, $y) { trace((), `comparing { $x } and { $y }`) } } ) false() The callback function traces which items are being compared, without changing the result of the comparison. deep-equal(fn($x) { $x }, fn($y) { $y }) true() The two functions differ only in the name of a bound variable. deep-equal(fn($x) { $x }, fn($x) { $x + 1 }) false() The two functions do not always return deep-equal results. deep-equal(true#0, true#0) true() Two references to the same function are equivalent.

Function items other than maps and arrays are compared for equivalence (replacing the function-identity comparison of issue 520).

When comments and processing instructions are ignored, any text nodes either side of the comment or processing instruction are now merged prior to comparison.

The $options parameter has been added, absorbing the $collation parameter.

A callback function can be supplied for comparing individual items.

Atomic items of types xs:hexBinary and xs:base64Binary are now mutually comparable. In rare cases, where an application uses both types and assumes they are distinct, this can represent a backwards incompatibility.

An option is provided to ignore empty entries in maps.

 deterministic context-independent focus-independent

Returns the number of items in a sequence.

The function returns the number of items in $input.

 dm:count($input)

The function returns 0 if $input is the empty sequence.

]]> count($tree//chap/p) 3 count($seq3) 0 count($seq2) 3 count($seq2[. > 100]) 0 count([]) 1 count([ 1, 2, 3 ]) 1 deterministic context-independent focus-independent

Returns the average of the values in the input sequence $values, that is, the sum of the values divided by the number of values.

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

Any item in $values that is an instance of xs:untypedAtomic is cast to xs:double.

After this conversion, one of the following conditions must be true:

Every item in $values is an instance of xs:yearMonthDuration.

Every item in $values is an instance of xs:dayTimeDuration.

Every item in $values is an instance of xs:numeric.

The function returns the average of the values as sum($values) div count($values); but the implementation may use an otherwise equivalent algorithm that avoids arithmetic overflow. Note that the fn:sum function allows the input sequence to be reordered, which may affect the result in edge cases when the sequence contains a mixture of different numeric types.

A type error is raised if the input sequence contains items of incompatible types, as described above.

 avg($seq3) 4.0 The result is of type xs:decimal. avg(($d1, $d2)) xs:yearMonthDuration("P10Y5M") avg(()) () avg((xs:float('INF'), xs:float('-INF'))) xs:float('NaN') avg(($seq3, xs:float('NaN'))) xs:float('NaN') avg(($d1, $seq3))

In 3.1, given a mixed input sequence such as (1, 3, 4.2e0), the specification was unclear whether it was permitted to add the first two integer items using integer arithmetic, rather than converting all items to doubles before performing any arithmetic. The 4.0 specification is clear that this is permitted; but since the items can be reordered before being added, this is not required.

 deterministic context-dependent focus-independent deterministic context-dependent focus-independent

Returns a value that is greater than or equal to every other value appearing in the input sequence.

Any item in $values that is an instance of xs:untypedAtomic is first cast to xs:double. The resulting sequence is referred to as the converted sequence.

All pairs of values in the converted sequence must be mutually comparable. Two values A and B are mutually comparable if fn:compare(A, B) raises no error.

If the converted sequence is empty, the function returns the empty sequence.

If the converted sequence contains the value NaN, the value NaN is returned (as an xs:float or xs:double as appropriate).

Two items A and B from the converted sequence are compared by calling fn:compare(A, B, $collation), where $collation is determined by the rules in :

The result of the function is a value from the converted sequence that is greater than or equal to every other value under the above rules. If there is more than one such value, then it is implementation-dependent which of them is returned.

A type error is raised if the input sequence contains items of incompatible types, as described above.

If there are two or items that are “equal highest”, the specific item whose value is returned is implementation-dependent. This can arise for example if two different strings compare equal under the selected collation, or if two different xs:dateTime values compare equal despite being in different timezones.

If the converted sequence contains exactly one value then that value is returned.

The default type when the fn:max function is applied to xs:untypedAtomic values is xs:double. This differs from the default type for operators such as lt, and for sorting in XQuery and XSLT, which is xs:string.

In version 4.0, if $values is a sequence of xs:decimal values (including the case where it is a sequence of xs:integer values), then the result will be one of these xs:decimal or xs:integer values. In earlier versions it would be the result of converting this xs:decimal to xs:float or xs:double.

 max((3, 2, 1)) 3 max([ 3, 2, 1 ]) 3 Arrays are atomized max(( xs:integer(5), xs:float(5), xs:double(0) )) 5 The result may be either the xs:integer or the xs:float, since they are equal. max(( xs:float(0.0E0), xs:float(-0.0E0) )) xs:float(0.0e0) The result may be either positive or negative zero, since they are equal. max(( current-date(), xs:date("2100-01-01") )) xs:date("2100-01-01") Assuming that the current date is during the 21st century. max(("a", "b", "c")) "c" Assuming a typical default collation. max((3, 4, "Zero"))

The way that fn:min and fn:max compare numeric values of different types has changed. The most noticeable effect is that when these functions are applied to a sequence of xs:integer or xs:decimal values, the result is an xs:integer or xs:decimal, rather than the result of converting this to an xs:float or xs:double.

 deterministic context-dependent focus-independent deterministic context-dependent focus-independent

Returns a value that is less than or equal to every other value appearing in the input sequence.

Any item in $values that is an instance of xs:untypedAtomic is first cast to xs:double. The resulting sequence is referred to as the converted sequence.

All pairs of values in the converted sequence must be mutually comparable. Two values A and B are mutually comparable if fn:compare(A, B) raises no error.

If the converted sequence is empty, the function returns the empty sequence.

If the converted sequence contains the value NaN, the value NaN is returned (as an xs:float or xs:double as appropriate).

Two items A and B from the converted sequence are compared by calling fn:compare(A, B, $collation), where $collation is determined by the rules in :

The result of the function is a value from the converted sequence that is less than or equal to every other value under the above rules. If there is more than one such value, then it is implementation-dependent which of them is returned.

A type error is raised if the input sequence contains items of incompatible types, as described above.

If there are two or items that are “equal lowest”, the specific item whose value is returned is implementation-dependent. This can arise for example if two different strings compare equal under the selected collation, or if two different xs:dateTime values compare equal despite being in different timezones.

If the converted sequence contains exactly one value then that value is returned.

The default type when the fn:min function is applied to xs:untypedAtomic values is xs:double. This differs from the default type for operators such as lt, and for sorting in XQuery and XSLT, which is xs:string.

In version 4.0, if $values is a sequence of xs:decimal values (including the case where it is a sequence of xs:integer values), then the result will be one of these xs:decimal or xs:integer values. In earlier versions it would be the result of converting this xs:decimal to xs:float or xs:double.

 min((3, 4, 5)) 3 min([ 3, 4, 5 ]) 3 Arrays are atomized min(( xs:integer(5), xs:float(5), xs:double(10) )) 5 The result may be either the xs:integer or the xs:float, since they are equal. min(( xs:float(0.0E0), xs:float(-0.0E0) )) xs:float(0.0e0) The result may be either positive or negative zero, since they are equal. min(( current-date(), xs:date("1900-01-01") )) xs:date("1900-01-01") Assuming that the current date is set to a reasonable value. min(("a", "b", "c")) "a" Assuming a typical default collation. min((3, 4, "Zero"))

The way that fn:min and fn:max compare numeric values of different types has changed. The most noticeable effect is that when these functions are applied to a sequence of xs:integer or xs:decimal values, the result is an xs:integer or xs:decimal, rather than the result of converting this to an xs:float or xs:double.

 deterministic context-independent focus-independent

Returns a value obtained by adding together the values in $values.

Any value of type xs:untypedAtomic in $values is cast to xs:double. The items in the resulting sequence may be reordered in an arbitrary order. The resulting sequence is referred to below as the converted sequence.

If the converted sequence is empty, then the function returns the value of the argument $zero.

In other cases the items in the converted sequence are added pairwise according the rules of the + operator.

Specifically, the result of the function is the value of the expression:

if (empty($c)) then $zero else if (count($c) eq 1) then $c else head($c) + sum(tail($c))

where $c is the converted sequence.

This has the effect that a type error will occur unless one of the following conditions is satisfied:

Every item in $values is an instance of xs:yearMonthDuration.

Every item in $values is an instance of xs:dayTimeDuration.

Every item in $values is an instance of xs:numeric.

A type error is raised if the input sequence contains items of incompatible types, as described above.

The second argument allows an appropriate value to be defined to represent the sum of an empty sequence. For example, when summing a sequence of durations it would be appropriate to return a zero-length duration of the appropriate type. This argument is necessary because a system that does dynamic typing cannot distinguish “an empty sequence of integers", for example, from “an empty sequence of durations”.

The explicit or implicit value of the $zero argument is used only when the input sequence is empty, not when a non-empty sequence sums to zero. For example, sum((-1, +1), xs:double('NaN')) returns the xs:integer value 0, not NaN.

The sum of a sequence of integers will be an integer, while the sum of a numeric sequence that includes at least one xs:double will be an xs:double.

If the converted sequence contains exactly one value then that value is returned.

If the converted sequence contains the value NaN, NaN is returned.

In edge cases the fact that the input sequence may be reordered makes the result slightly unpredictable. For example, if the input contains two xs:decimal values and an xs:float, then the decimal values might be added using decimal arithmetic, or they might both be converted to xs:float (potentially losing precision) before any arithmetic is performed.

sum(($d1, $d2)) xs:yearMonthDuration("P20Y10M") sum( $seq1[. lt xs:yearMonthDuration('P3M')], xs:yearMonthDuration('P0M') ) xs:yearMonthDuration("P0M") sum($seq3) 12 sum(()) 0 sum((),()) () sum((1 to 100)[. lt 0], 0) 0 sum(($d1, $d2), "ein Augenblick") xs:yearMonthDuration("P20Y10M") There is no requirement that the $zero value should be the same type as the items in $value, or even that it should belong to a type that supports addition. sum([ 1, 2, 3 ]) 6 Atomizing an array returns the sequence obtained by atomizing its members. sum([ [ 1, 2 ], [ 3, 4 ] ]) 10 Atomizing an array returns the sequence obtained by atomizing its members. sum(($d1, 9E1))

In 3.1, given a mixed input sequence such as (1, 3, 4.2e0), the specification was unclear whether it was permitted to add the first two integer items using integer arithmetic, rather than converting all items to doubles before performing any arithmetic. The 4.0 specification is clear that this is permitted; but since the items can be reordered before being added, this is not required.

 deterministic context-dependent focus-dependent deterministic context-independent focus-independent

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.

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

E is in the target document. The target document is the document containing $node.

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 .) 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 .) 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]

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

A dynamic error is raised 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, type error

If the context value is not a single node, type error .

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.

 E21256 John Brown } }]]> $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. deterministic context-dependent focus-dependent deterministic context-independent focus-independent

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.

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:

E is in the target document. The target document is the document containing $node.

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 .) 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 .) 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]

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

A dynamic error is raised 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, type error

If the context value is not a single node, type error .

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.

 E21256 John Brown } }]]> $emp/element-with-id('ID21256')/name() "employee" The xml:id attribute has the is-id property, so the employee element is selected. $emp/element-with-id('E21256')/name() "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. deterministic context-dependent focus-dependent deterministic context-independent focus-independent

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.

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

$N is in the target document. The target document is the document containing $node.

$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 ) 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]

A dynamic error is raised 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, type error

If the context value is not a single node, type error .

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.

 E21256 Anil Singh E30561 E30561 John Brown ID21256 } }]]> $emp/( element-with-id('ID21256')/@xml:id => idref() )/ancestor::employee/last => string() "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. $emp/( element-with-id('E30561')/empnr => idref() )/ancestor::employee/last => string() "Singh" Assuming that employee/deputy has the is-idref property, the call on fn:idref selects the deputy element. deterministic context-dependent focus-independent

Retrieves a document using a URI supplied as an xs:string, and returns the corresponding document node.

If $source is the empty sequence, the result is the empty sequence.

If $source is a relative URI reference, it is resolved relative to the value of the executable base URI property from the dynamic context of the caller. The resulting absolute URI is promoted to an xs:string.

The way in which an absolute URI is dereferenced to obtain an external resource is described in .

The ability to access external resources depends on whether the calling code is .

The URI may include a fragment identifier.

The $options argument defines the detailed behavior of the function. The apply. The options available are as follows:

Indicates whether processing the document may cause other external resources to be fetched (including, for example, external entities, an external DTD, or documents referenced using xsi:schemaLocation or XInclude elements). xs:boolean false() The document may include references to other external resources. The document must not include references to other external resources unless access to these resources has been explicitly enabled. Determines whether DTD validation takes place. xs:boolean false The input is parsed using a validating XML parser. The input must contain a DOCTYPE declaration to identify the DTD to be used for validation. The DTD may be internal or external. DTD validation does not take place. However, if a DOCTYPE declaration is present, then it is read, for example to perform entity expansion. Determines whether two calls on the doc function, with the same URI, the same options, and the same context, are guaranteed to return the same document node. The default value is true, but this may be overridden by implementation-defined configuration options. xs:boolean true Given the same explicit and implicit arguments, multiple calls return the same document node. Multiple calls with the same explicit and implicit arguments may return the same document node or different document nodes at the discretion of the implementation. Determines whether whitespace-only text nodes are removed from the resulting document. enum("all", "none", "conditional") "conditional" All whitespace-only text nodes are stripped, unless either (a) they are within the scope of the attribute xml:space="preserve", or (b) XSD validation identifies that the parent element has a simple type or a complex type with simple content. All whitespace-only text nodes are preserved, unless either (a) DTD validation marks them as ignorable, or (b) XSD validation recognizes the containing element as having element-only or empty content. Equivalent to "none", unless there is an external control determining how whitespace-only text nodes are to be handled. An example of such an external control is the set of xsl:strip-space and xsl:preserve-space declarations in a containing XSLT stylesheet package. Determines whether any xi:include elements in the input are to be processed using an XInclude processor. xs:boolean false Any xi:include elements are expanded. If there are xi:include elements and no XInclude processor is available then a dynamic error is raised. Any xi:include elements are handled as ordinary elements without expansion. Determines whether XSD validation takes place, using the schema definitions present in the static context. The effect of requesting validation is the same as invoking the doc function without validation, and then applying an XQuery validate expression to the result, with corresponding options. xs:string "skip" Strict XSD validation takes place Lax XSD validation takes place No XSD validation takes place XSD validation takes place against the schema-defined type, present in the static context, that has the given URI and local name. When XSD validation takes place, determines whether schema components referenced using xsi:schemaLocation or xsi:noNamespaceSchemaLocation attributes within the source document are to be used. The option is ignored if XSD validation does not take place. xs:boolean false XSD validation uses the schema components referenced using xsi:schemaLocation or xsi:noNamespaceSchemaLocation attributes in addition to the schema components present in the static context; these components must be compatible as described in . Any xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes in the document are ignored. Indicates whether the application wants location information to be retained for nodes in the returned tree. xs:boolean false Represents a request that the nodes in the returned tree should include location information, accessible using the fn:location function. The implementation may ignore the request. Indicates that location information is not required: but the implementation may provide it anyway.

The determinism of this function depends on the value of the stable option:

If stable is true (the default), the function is deterministic: two calls on this function within the same execution scope return the same document node if (a) the same URI reference (after resolution to an absolute URI reference) is supplied to both calls, (b) the same values for the other options are supplied to both calls, and (c) the two calls have the same static and dynamic context, to the extent that this is relevant. Thus, each of the following expressions (if it does not raise an error) will always return true:

doc("foo.xml") is doc("foo.xml") doc("foo.xml", { "xinclude": true() }) is doc("foo.xml", { "xinclude": true() })

If stable is false, the function is nondeterministic: two such calls may return different document nodes, and if the underlying resource changes between the calls, the contents of these nodes may differ.

If two calls supply different values for stable, the effect is the same as if both calls supplied false.

If two calls on fn:doc have different dynamic contexts, then the mapping from URIs to document nodes in the two contexts may differ, which means that different document nodes may be returned for the same URI. This can happen, for example, if the two calls appear in different XSLT packages with different validation options or whitespace-stripping options; one call might produce a schema-validated document, the other an untyped document.

The requirement to deliver a deterministic result has performance implications, and for this reason implementations may provide a configuration option to evaluate the function without a guarantee of determinism, even if the stable option is true. The manner in which any such option is provided is . If the stable option is true and no such configuration option has been selected, a call of the function must either return a deterministic result or must raise a dynamic error .

If the $source URI is obtained from a source document, it is generally appropriate to resolve it relative to the base URI property of the relevant node in the source document. This can be achieved by calling the fn:resolve-uri function, and passing the resulting absolute URI as an argument to the fn:doc function.

If two calls to this function supply different absolute URI References as arguments, the same document node may be returned if the implementation can determine that the two arguments refer to the same resource.

By defining the semantics of this function in terms of a string-to-document-node mapping in the dynamic context, the specification is acknowledging that the results of this function are outside the purview of the language specification itself, and depend entirely on the run-time environment in which the expression is evaluated. This run-time environment includes not only an unpredictable collection of resources (“the web”), but configurable machinery for locating resources and turning their contents into document nodes within the XPath data model. Both the set of resources that are reachable, and the mechanisms by which those resources are parsed and validated, are implementation-dependent.

One possible processing model for this function is as follows. The resource identified by the URI Reference is retrieved. If the resource cannot be retrieved, a dynamic error is raised . The data resulting from the retrieval action is then parsed as an XML document and a tree is constructed in accordance with the . If the top-level media type is known and is "text", the content is parsed in the same way as if the media type were text/xml; otherwise, it is parsed in the same way as if the media type were application/xml. If the contents cannot be parsed successfully, a dynamic error is raised . Otherwise, the result of the function is the document node at the root of the resulting tree. This tree is then optionally validated against a schema.

Various aspects of this processing are implementation-defined. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:

The set of URI schemes that the implementation recognizes is implementation-defined. Implementations may allow the mapping of URIs to resources to be configured by the user, using mechanisms such as catalogs or user-written URI handlers.

The handling of non-XML media types is implementation-defined. Implementations may allow instances of the data model to be constructed from non-XML resources, under user control.

It is implementation-defined whether DTD validation and/or schema validation is applied to the source document.

Implementations may provide user-defined error handling options that allow processing to continue following an error in retrieving a resource, or in parsing and validating its content. When errors have been handled in this way, the function may return either the empty sequence, or a fallback document provided by the error handler.

Implementations may provide user options that relax the requirement for the function to return deterministic results.

The effect of a fragment identifier in the supplied URI is implementation-defined. One possible interpretation is to treat the fragment identifier as an ID attribute value, and to return a document node having the element with the selected ID value as its only child.

A dynamic error may be raised if $source is not a valid URI reference.

A dynamic error is raised if a relative URI reference is supplied, and the base-URI property in the static context is absent.

A dynamic error is raised if the available documents provides no mapping for the absolutized URI.

A dynamic error is raised if the resource cannot be retrieved or cannot be parsed successfully as XML using the selected options.

A dynamic error is raised if the implementation is not able to guarantee that the result of the function will be deterministic, and the user has not indicated that a nondeterministic result is acceptable (either by setting the stable option to false, or by selecting an implementation-defined configuration option).

A dynamic error is raised if DTD validation is carried out and the supplied content is not valid against the relevant DTD.

A dynamic error is raised if the value of the xsd-validation option is not one of the permitted values (for example, if the string that follows "type" is not a valid EQName, or if it does not identify a type that is present in the static context).

A dynamic error is raised if the value of the xsd-validation option is set to anything other than skip when the processor is not schema-aware. (XSLT 4.0 and XQuery 4.0 define schema-awareness as an optional feature; other host languages may set their own rules.)

A dynamic error is raised if processor does not have access to an XML parser supporting the requested options, for example the ability to perform DTD validation or XInclude processing or to prevent access to external entities.

A dynamic error is raised if XSD validation is carried out during XML parsing, and the supplied content is not valid against the relevant XSD schema.

A dynamic error is raised if external resources are required (for example, external entities) that are not available because the trust-external option is not set to true.

The rule that multiple calls on fn:doc supplying the same absolute URI must return the same document node has been clarified; in particular the rule does not apply if the dynamic context for the two calls requires different processing of the documents (such as schema validation or whitespace stripping).

An $options parameter is added. Note that the rules for the $options parameter control aspects of processing that were implementation-defined in earlier versions of this specification. An implementation may provide configuration options designed to retain backwards-compatible behavior when no explicit options are supplied.

The determinism rules have been clarified: the guarantee that two calls return the same document node is now stated as a normative rule that is conditional on the stable option, and the function is explicitly defined to be nondeterministic if stable is set to false.

An option has been added to request that location information (for example, line numbers) be maintained.

 deterministic context-dependent focus-independent

The function returns true if and only if the function call fn:doc($source, $options) would return a document node.

If $source is the empty sequence, this function returns false.

If a call on fn:doc($source, $options) would return a document node, this function returns true.

In all other cases this function returns false. This includes the case where an invalid URI is supplied, and also the case where a valid relative URI reference is supplied, and cannot be resolved, for example because the static base URI is absent.

The recognized values for $options are the same as for the fn:doc function. The apply.

The determinism of this function depends on the value of the stable option, in the same way as for the fn:doc function.

If stable is true, it follows that a result of true guarantees that a call on fn:doc with the same explicit and implicit arguments will return a document node, whereas a result of false guarantees that such a call will fail. If stable is false, the result provides no such guarantees.

Like any other function, doc-available fails with an error if invalid arguments are supplied: for example if the first argument is not a string, or if unrecognized options are included in $options. However, it returns false rather than raising an error if the first argument is invalid as a URI.

The function also returns false (rather than raising an error) if the document is unavailable because of processor limitations, for example if schema validation is requested and the processor is not schema-aware.

An $options parameter is added. Note that the rules for the $options parameter control aspects of processing that were implementation-defined in earlier versions of this specification. An implementation may provide configuration options designed to retain backwards-compatible behavior when no explicit options are supplied.

The determinism of the function, and the guarantees its result provides for calls on fn:doc, have been clarified with regard to the stable option.

 deterministic context-dependent focus-independent

Returns a sequence of items identified by a collection URI; or a default collection if no URI is supplied.

This function takes an xs:string as argument and returns a sequence of items obtained by interpreting $source as an xs:anyURI and resolving it according to the mapping specified in available collections described in .

If available collections provides a mapping from this string to a sequence of items, the function returns that sequence. If available collections maps the string to the empty sequence, then the function returns an empty sequence.

If $source is the empty sequence, the function returns the sequence of items in the default collection in the dynamic context. See .

If $source is a relative URI reference, it is resolved relative to the value of the executable base URI property from the dynamic context of the caller. The resulting absolute URI is promoted to an xs:string.

By default, this function is deterministic. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is implementation-defined. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error .

There is no requirement that any nodes in the result should be in document order, nor is there a requirement that the result should contain no duplicates.

The ability to access external resources depends on whether the calling code is .

A dynamic error is raised if no URI is supplied and the value of the default collection is absent.

A dynamic error is raised if a relative URI reference is supplied, and the base-URI property in the static context is absent.

A dynamic error is raised if available node collections provides no mapping for the absolutized URI.

A dynamic error may be raised if $source is not a valid xs:anyURI.

In earlier versions of this specification, the primary use for the fn:collection function was to retrieve a collection of XML documents, perhaps held as lexical XML in operating system filestore, or perhaps held in an XML database. In this release the concept has been generalised to allow other resources to be retrieved: for example JSON documents might be returned as arrays or maps, non-XML text files might be returned as strings, and binary files might be returned as instances of xs:base64Binary.

The abstract concept of a collection might be realized in different ways by different implementations, and the ways in which URIs map to collections can be equally variable. Specifying resources using URIs is useful because URIs are dynamic, can be parameterized, and do not rely on an external environment.

 deterministic context-dependent focus-independent

Returns a sequence of xs:anyURI values representing the URIs in a URI collection.

If $source is the empty sequence, the function returns the URIs in the default URI collection described in .

If $source is a relative URI reference, it is resolved relative to the value of the executable base URI property from the dynamic context of the caller. The resulting absolute URI is promoted to an xs:string.

The single-argument form of the function returns the sequence of URIs corresponding to the supplied URI in the available URI collections described in .

By default, this function is deterministic. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is implementation-defined. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error .

There is no requirement that the URIs returned by this function should all be distinct, and no assumptions can be made about the order of URIs in the sequence, unless the implementation defines otherwise.

The ability to access external resources depends on whether the calling code is .

A dynamic error is raised if no URI is supplied (that is, if the function is called with no arguments, or with a single argument that evaluates to the empty sequence), and the value of the default resource collection is absent.

A dynamic error is raised if a relative URI reference is supplied, and the base-URI property in the static context is absent.

A dynamic error is raised if available resource collections provides no mapping for the absolutized URI.

A dynamic error may be raised if $source is not a valid xs:anyURI.

In some implementations, there might be a close relationship between collections (as retrieved by the fn:collection function), and URI collections (as retrieved by this function). For example, a collection might return XML documents, and the corresponding URI collection might return the URIs of those documents. However, this specification does not impose such a close relationship. For example, there may be collection URIs accepted by one of the two functions and not by the other; a collection might contain items that do not have any URI; or a URI collection might contain URIs that cannot be dereferenced to return any resource.

In the case where fn:uri-collection returns the URIs of resources that could also be retrieved directly using fn:collection, there are several reasons why it might be appropriate to use this function in preference to the fn:collection function. For example:

It allows different URIs for different kinds of resource to be dereferenced in different ways: for example, the returned URIs might be referenced using the fn:unparsed-text function rather than the fn:doc function.

In XSLT 3.0 it allows the documents in a collection to be processed in streaming mode using the xsl:stream instruction.

It allows recovery from failures to read, parse, or validate individual documents, by calling the fn:doc (or other dereferencing) function within the scope of try/catch.

It allows selection of which documents to read based on their URI, for example they can be filtered to select those whose URIs end in .xml, or those that use the https scheme.

An application might choose to limit the number of URIs processed in a single run, for example it might process only the first 50 URIs in the collection; or it might present the URIs to the user and allow the user to select which of them need to be further processed.

It allows the URIs to be modified before they are dereferenced, for example by adding or removing query parameters, or by redirecting the request to a local cache or to a mirror site.

For some of these use cases, this assumes that the cost of calling fn:collection might be significant (for example, it might involving retrieving all the documents in the collection over the network and parsing them). This will not necessarily be true of all implementations.

 nondeterministic context-dependent focus-independent

The fn:unparsed-text function reads an external resource (for example, a file) and returns a string representation of the resource.

The $source argument must be a string in the form of a URI reference, which must contain no fragment identifier, and must identify a resource for which a string representation is available.

If $source is a relative URI reference, it is resolved relative to the value of the executable base URI property from the dynamic context of the caller. The resulting absolute URI is promoted to an xs:string.

The $options argument, for backwards compatibility reasons, may be supplied either as a map, or as a string. Supplying a value $S that is not a map is equivalent to supplying the map { "encoding": $S }. After that substitution, the apply.

The entries that may appear in the $options map are as follows:

Defines the encoding of the resource, as described below. xs:string? () Determines whether CR and CRLF character sequences are treated as equivalent to NL characters. xs:boolean false No normalization of line endings takes place. The character U+000D and the character pair (U+000D, U+000A) are converted to the single character U+000A. If $fallback is true, any character that cannot be decoded or that is not a is replaced by the Unicode replacement character (U+FFFD). xs:boolean false

The way in which an absolute URI is dereferenced to obtain an external resource is described in .

The ability to access external resources depends on whether the calling code is .

If the $source argument is the empty sequence, the function returns the empty sequence.

The encoding option, if non-empty, is the name of an encoding. The values for this option follow the same rules as for the encoding attribute in an XML declaration; every implementation recognizes at least the required encodings.

The encoding candidate is chosen as follows:

external encoding information if available; otherwise

the encoding recognized as specified in if the media type of the resource is text/xml or application/xml (see ), or if it matches the conventions text/*+xml or application/*+xml (see and/or its successors); otherwise

the value of the encoding option if present; otherwise

the empty sequence.

The effective encoding and the effective start position are determined by invoking bin:infer-encoding with the octets of the retrieved resource and the encoding candidate.

As a consequence of these rules, a byte order mark at the start of the resource is not included in the result.

The result of the function is a string containing the string representation of the resource retrieved using the URI, starting at the effective start position, and decoded according to the effective encoding.

A dynamic error is raised if the $source argument contains a fragment identifier, or if it cannot be resolved to an absolute URI (for example, because the base-URI property in the static context is absent), or if it cannot be used to retrieve the string representation of a resource.

A dynamic error is raised if the value of the encoding option is not a valid encoding name, if the processor does not support the specified encoding, if the string representation of the retrieved resource contains octets that cannot be decoded into Unicode characters using the specified encoding, or if any resulting character is not a permitted character.

A dynamic error is raised if the encoding candidate is absent and the string representation of the retrieved resource contains octets that cannot be decoded into Unicode characters using the encoding determined by bin:infer-encoding.

If it is appropriate to use a base URI other than the executable base URI (for example, when resolving a relative URI reference read from a source document) then it is advisable to resolve the relative URI reference using the fn:resolve-uri function before passing it to the fn:unparsed-text function.

There is no essential relationship between the sets of URIs accepted by the two functions fn:unparsed-text and fn:doc (a URI accepted by one may or may not be accepted by the other), and if a URI is accepted by both there is no essential relationship between the results (different resource representations are permitted by the architecture of the web).

There are no constraints on the MIME type of the resource.

The fact that the resolution of URIs is defined by a mapping in the dynamic context means that in effect, various aspects of the behavior of this function are implementation-defined. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:

The set of URI schemes that the implementation recognizes is implementation-defined. Implementations may allow the mapping of URIs to resources to be configured by the user, using mechanisms such as catalogs or user-written URI handlers.

The handling of media types is implementation-defined.

Although the function is , implementations may provide user options that request deterministic (stable) results, so that repeated calls with the same arguments during a single execution return the same result.

Implementations may provide user-defined error handling options that allow processing to continue following an error in retrieving a resource, or in reading its content. When errors have been handled in this way, the function may return a fallback document provided by the error handler.

In earlier versions this function was : repeated reads of the same resource within a single execution returned the same result. From 4.0 it is , so a program that requires consistency across reads should read the resource once and reuse the value.

The rules for determining the encoding are chosen for consistency with . Files with an XML media type are treated specially because there are use cases for this function where the retrieved text is to be included as unparsed XML within a CDATA section of a containing document, and because processors are likely to be able to reuse the code that performs encoding detection for XML external entities.

If the text file contains characters such as < and &, these will typically be output as &lt; and &amp; if the string is serialized as XML or HTML. If these characters actually represent markup (for example, if the text file contains HTML), then an XSLT stylesheet can attempt to write them as markup to the output file using the disable-output-escaping attribute of the xsl:value-of instruction. Note, however, that XSLT implementations are not required to support this feature.

This XSLT example attempts to read a file containing “boilerplate” HTML and copy it directly to the serialized output file:

]]>

The $options parameter has been added.

It is no longer automatically an error if the resource (after decoding) contains a codepoint that is not valid in XML. Instead, the codepoint must be a . The set of permitted characters is , but it is recommended that all Unicode characters should be accepted.

The specification now describes in more detail how to determine the effective encoding value.

A fallback option is now provided to address characters that cannot be decoded or are not permitted.

The encoding and the start position of the content are now determined by invoking bin:infer-encoding; redundant rules have been dropped.

The function is now classified as .

 nondeterministic context-dependent focus-independent

The fn:unparsed-text-lines function reads an external resource (for example, a file) and returns its contents as a sequence of strings, one for each line of text in the string representation of the resource.

The unparsed-text-lines function reads an external resource (for example, a file) and returns its string representation as a sequence of strings, separated at newline boundaries.

The $options argument, for backwards compatibility reasons, may be supplied either as a map, or as a string. Supplying a value $S that is not a map is equivalent to supplying the map { "encoding": $S }. After that substitution, the apply.

The entries that may appear in the $options map are as follows:

Defines the encoding of the resource, following the rules of fn:unparsed-text. xs:string? () If $fallback is true, any character that cannot be decoded or that is not a is replaced by the Unicode replacement character (U+FFFD). xs:boolean false

The result of the function is the same as the result of the expression:

let $text := unparsed-text($source, map:put($options, 'normalize-newlines', true())) let $lines := tokenize($text, '\n') return $lines[not(position() = last() and . = '')]

The result is thus a sequence of strings containing the text of the resource retrieved using the URI, each string representing one line of text. Lines may be delimited by any of the character sequences U+000A, U+000D, or U+000D followed by U+000A. Line ending characters are not included in the returned strings. If there are two adjacent newline sequences, a zero-length string will be returned to represent the empty line; but if the external resource ends with a newline sequence, the result will be as if this final line ending were not present.

The ability to access external resources depends on whether the calling code is .

Error conditions are the same as for the fn:unparsed-text function.

See the notes for fn:unparsed-text.

The $options parameter has been added.

A fallback option is now provided to address characters that cannot be decoded or are not permitted.

The function is now classified as .

 nondeterministic context-dependent focus-independent

Allows an application to determine whether a call on fn:unparsed-text with particular arguments would succeed.

The fn:unparsed-text-available function determines whether a call on the fn:unparsed-text function with identical arguments would return a string.

If the first argument is the empty sequence, the function returns false.

In other cases, the function returns true if a call on fn:unparsed-text or fn:unparsed-text-lines with the same arguments would succeed, and false if a call on fn:unparsed-text or fn:unparsed-text-lines with the same arguments would fail with a non-recoverable dynamic error.

The functions fn:unparsed-text and fn:unparsed-text-available are . This means that a call on fn:unparsed-text-available is not guaranteed to be consistent with the result of a subsequent call on fn:unparsed-text with the same arguments, because the availability or content of the external resource may change between the two calls. Implementations may provide user options that request deterministic (stable) results.

The ability to access external resources depends on whether the calling code is .

This function was introduced before XQuery and XSLT allowed errors to be caught; with current versions of these host languages, catching an error from fn:unparsed-text may provide a better alternative.

The specification requires that the fn:unparsed-text-available function should actually attempt to read the resource identified by the URI, and check that it is correctly encoded and contains only permitted characters. Implementations may avoid the cost of repeating these checks for example by caching the validated contents of the resource, to anticipate a subsequent call on the fn:unparsed-text or fn:unparsed-text-lines function. Alternatively, implementations may be able to rewrite an expression such as if (unparsed-text-available(A)) then unparsed-text(A) else ... to generate a single call internally.

Since the function fn:unparsed-text-lines succeeds or fails under exactly the same circumstances as fn:unparsed-text, the fn:unparsed-text-available function may equally be used to test whether a call on fn:unparsed-text-lines would succeed.

The $options parameter has been added.

The function is now classified as .

 nondeterministic context-dependent focus-independent

The fn:unparsed-binary function reads an external resource (for example, a file) and returns its contents in binary.

The $source argument must be a string in the form of a URI reference, which must contain no fragment identifier, and must identify a resource for which a binary representation is available.

If $source is a relative URI reference, it is resolved relative to the value of the executable base URI property from the dynamic context of the caller. The resulting absolute URI is promoted to an xs:string.

The way in which an absolute URI is dereferenced to obtain an external resource is described in .

If the $source argument is the empty sequence, the function returns the empty sequence.

The result of the function is an atomic item of type xs:base64Binary containing the binary representation of the resource retrieved using the URI.

The ability to access external resources depends on whether the calling code is .

A dynamic error is raised if the $source argument contains a fragment identifier, or if it cannot be resolved to an absolute URI (for example, because the base-URI property in the static context is absent), or if it cannot be used to retrieve the binary representation of a resource.

If it is appropriate to use a base URI other than the executable base URI (for example, when resolving a relative URI reference read from a source document) then it is advisable to resolve the relative URI reference using the fn:resolve-uri function before passing it to the fn:unparsed-text function.

There is no essential relationship between the sets of URIs accepted by the function fn:unparsed-binary and other functions such as fn:doc and fn:unparsed-text (a URI accepted by one may or may not be accepted by the others), and if a URI is accepted by more than one of these functions then there is no essential relationship between the results (different resource representations are permitted by the architecture of the web).

There are no constraints on the MIME type of the resource.

The fact that the resolution of URIs is defined by a mapping in the dynamic context means that in effect, various aspects of the behavior of this function are implementation-defined. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:

The set of URI schemes that the implementation recognizes is implementation-defined. Implementations may allow the mapping of URIs to resources to be configured by the user, using mechanisms such as catalogs or user-written URI handlers.

The handling of media types is implementation-defined.

Although the function is , implementations may provide user options that request deterministic (stable) results, so that repeated calls with the same arguments during a single execution return the same result.

Implementations may provide user-defined error handling options that allow processing to continue following an error in retrieving a resource, or in reading its content. When errors have been handled in this way, the function may return a fallback document provided by the error handler.

There is no function (analogous to fn:doc-available or fn:unparsed-text-available) to determine whether a suitable resource is available. In XQuery and XSLT, try/catch constructs are available to catch the error.

The choice of xs:base64Binary rather than xs:hexBinary for the result is arbitrary. The two types have the same value space and are interchangeable for nearly all purposes, the notable exception being conversion to xs:string.

A comprehensive set of functions for manipulating binary data is available in the EXPath binary module: see . In addition, the EXPath file module provides a function file:read-binary with similar functionality to fn:unparsed-binary, the notable difference being that it takes a file name rather than a URI.

The following XQuery, adapted from an example in the EXPath binary module , reads a JPEG image and determines its size in pixels:

The example assumes that the functions in the EXPath binary module are available.

New in 4.0

The function is now classified as .

 deterministic context-dependent focus-independent

Returns the value of a system environment variable, if it exists.

The set of available environment variables is a set of (name, value) pairs forming part of the dynamic context, in which the name is unique within the set of pairs. The name and value are arbitrary strings.

If the $name argument matches the name of one of these pairs, the function returns the corresponding value.

If there is no environment variable with a matching name, the function returns the empty sequence.

The collation used for matching names is implementation-defined, but must be the same as the collation used to ensure that the names of all environment variables are unique.

The function is deterministic, which means that if it is called several times within the same execution scope, with the same arguments, it must return the same result.

On many platforms, the term “environment variable” has a natural meaning in terms of facilities provided by the operating system. This interpretation of the concept does not exclude other interpretations, such as a mapping to a set of configuration parameters in a database system.

Environment variable names are usually case sensitive. Names are usually of the form (letter|_) (letter|_|digit)*, but this varies by platform.

On some platforms, there may sometimes be multiple environment variables with the same name; in this case, it is implementation-dependent as to which is returned; see for example (Chapter 8, Environment Variables). Implementations may use prefixes or other naming conventions to disambiguate the names.

The requirement to ensure that the function is deterministic means in practice that the implementation must make a snapshot of the environment variables at some time during execution, and return values obtained from this snapshot, rather than using live values that are subject to change at any time.

Operating system environment variables may be associated with a particular process, while queries and stylesheets may execute across multiple processes (or multiple machines). In such circumstances implementations may choose to provide access to the environment variables associated with the process in which the query or stylesheet processing was initiated.

Security advice: Untrusted applications should not be permitted unrestricted access to environment variables. For example, the name of the account under which a query is running may be useful information to a would-be intruder. An implementation may therefore choose to restrict access to the environment, or may provide a facility to make fn:environment-variable always return the empty sequence.

 deterministic context-dependent focus-independent

Returns a list of environment variable names that are suitable for passing to fn:environment-variable, as a (possibly empty) sequence of strings.

The function returns a sequence of strings, being the names of the environment variables in the dynamic context in some implementation-dependent order.

The function is deterministic: that is, the set of available environment variables does not vary during evaluation.

The function returns a list of strings, containing no duplicates.

It is intended that the strings in this list should be suitable for passing to fn:environment-variable.

See also the note on security under the definition of the fn:environment-variable function. If access to environment variables has been disabled, fn:available-environment-variables always returns the empty sequence.

 deterministic context-dependent focus-independent

Returns information about the processor.

The function returns information about the processor, in the form of a map whose keys are QNames identifying the required property. Some property names (listed below) are standardized in this specification; others may be defined by implementers. A product may also provide the capability (via some API) for users to add further system properties.

QNames in no namespace are reserved for properties defined in this specification or in future versions of this specification. Other properties should be identified by QNames in an appropriate namespace.

The following properties must be available in all implementations:

Built-in System Properties
Name Type Value

#xpath-version

xs:decimal

The version of XPath supported by the processor, for example 4.0.

#xsd-version

xs:decimal

The version of XSD (XML Schema) implemented by the processor, typically 1.0 or 1.1. Note that the built-in datatypes (such as xs:anyURI) are based on XSD 1.1 specifications even if schema processing uses an XSD 1.0 processor.

#product-name

xs:string

A string containing the name of the implementation, as defined by the implementer. This should normally remain constant from one release of the product to the next. It should also be constant across platforms in cases where the same source code is used to produce compatible products for multiple execution platforms.

#product-version

xs:string

A string identifying the version of the implementation, as defined by the implementer. This should normally vary from one release of the product to the next, and at the discretion of the implementer it may also vary across different execution platforms.
#schema-aware

xs:boolean

Returns true if the processor offers the ability to add schema components to the static context, using the schema import mechanism of XSLT or XQuery, or false otherwise. The property indicates whether the processor has this capability, not whether a schema has actually been imported.
#accepts-typed-data

xs:boolean

Returns true if the processor is capable of handling nodes with a type annotation other than xs:untyped and xs:untypedAtomic, or false otherwise.
#supports-xinclude

xs:boolean

Returns true if the processor supports the option "xinclude":true() in calls to fn:doc and fn:parse-xml; otherwise false.

#supports-dtd

xs:boolean

Returns true if the processor fully supports validation, entity expansion, and attribute typing (recognition of ID and IDREF attributes) based on DTD processing during XML parsing. Returns false if there are restrictions, even if some of these capabilities are available.
#supports-invisible-xml

xs:boolean

Returns true if the processor supports the use of the fn:invisible-xml function.
#supports-dynamic-xquery

xs:boolean

Returns true if the processor supports the use of the fn:load-xquery-module function.
#supports-dynamic-xslt

xs:boolean

Returns true if the processor supports the use of the fn:transform function.
#supports-binary-library

xs:boolean

Returns true if the static context includes implementations of the functions defined in .
#supports-file-library

xs:boolean

Returns true if the static context includes implementations of the functions defined in .

In XSLT, these built-in properties are augmented with property names in the XSLT namespace. The property names, and their meaning, are the same as the properties defined for the XSLT function fn:system-property (see ); but properties where fn:system-property is defined to return the string "yes" or "no" instead return the xs:boolean value true or false.

As indicated in the examples below, a call on this function will often be be followed by the lookup operator ? and a key specifier in the form of a no-namespace QName literal such as #xpath-version.

In cases where a processor supports capability such as XInclude or DTD processing, but the resources available to that capability are restricted for security or other operational reasons, the returned property value should be true, unless the capability has been disabled completely.

 system-properties()?#xpath-version 4.0 system-properties()?#schema-aware true for a schema-aware processor, otherwise false. system-properties()?#Q{http://www.w3.org/1999/XSL/Transform}supports-streaming When called in XSLT, returns true for a streaming processor or false for a non-streaming processor.

New in 4.0

 deterministic context-dependent focus-dependent deterministic context-independent focus-independent

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

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

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

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

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

If the context value is absent, type error

If the context value is not an instance of the sequence type node()?, type error .

An implementation is free to generate an identifier in any convenient way provided that it always generates the same identifier for the same GNode and that different identifiers are always generated from different GNodes. 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 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].

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

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

]]>

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

here]]>

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))

nondeterministic context-dependent focus-independent

This function takes as input an XML document, and returns the document node at the root of an XDM tree representing the parsed document.

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

In other cases, $value is expected to contain an XML document supplied either as a string or a binary value. If it is supplied as a binary value, an optional byte order mark or XML declaration may contain the input encoding, and the input will be processed like a resource retrieved by the fn:doc function. Otherwise, if the input is a string, any byte order mark as well as the encoding specified in an optional XML declaration should be ignored.

The $options argument defines the detailed behavior of the function. The apply. The options available are as follows:

Determines the base URI. This is used both as the base URI used by the XML parser to resolve relative entity references within the document, and as the base URI of the document node that is returned. It defaults to the static base URI of the function call. xs:anyURI static-base-uri() Determines whether DTD validation takes place. xs:boolean false The input is parsed using a validating XML parser. The input must contain a DOCTYPE declaration to identify the DTD to be used for validation. The DTD may be internal or external. DTD validation does not take place. However, if a DOCTYPE declaration is present, then it is read, for example to perform entity expansion. Determines whether whitespace-only text nodes are removed from the resulting document. enum("all", "none", "conditional") "none" All whitespace-only text nodes are stripped, unless either (a) they are within the scope of the attribute xml:space="preserve", or (b) XSD validation identifies that the parent element has a simple type or a complex type with simple content. All whitespace-only text nodes are preserved, unless either (a) DTD validation marks them as ignorable, or (b) XSD validation recognizes the containing element as having element-only or empty content. Equivalent to "none". Unlike the fn:doc function, this function is not subject to external controls determining how whitespace-only text nodes are to be handled; in particular, the xsl:strip-space and xsl:preserve-space declarations in a containing XSLT stylesheet package are ignored. Indicates whether processing the supplied document may cause external resources to be fetched (including, for example, external entities, an external DTD, or documents referenced using xsi:schemaLocation or XInclude elements). xs:boolean false() The document may include references to external resources. The document must not include references to external resources unless access to these resources has been explicitly enabled. Determines whether any xi:include elements in the input are to be processed using an XInclude processor. xs:boolean false Any xi:include elements are expanded. If there are xi:include elements and no XInclude processor is available then a dynamic error is raised. Any xi:include elements are handled as ordinary elements without expansion. Determines whether XSD validation takes place, using the schema definitions present in the static context. The effect of requesting validation is the same as invoking the parse-xml function without validation, and then applying an XQuery validate expression to the result, with corresponding options. xs:string "skip" Strict XSD validation takes place Lax XSD validation takes place No XSD validation takes place XSD validation takes place against the schema-defined type, present in the static context, that has the given URI and local name. When XSD validation takes place, determines whether schema components referenced using xsi:schemaLocation or xsi:noNamespaceSchemaLocation attributes within the source document are to be used. The option is ignored if XSD validation does not take place. xs:boolean false XSD validation uses the schema components referenced using xsi:schemaLocation or xsi:noNamespaceSchemaLocation attributes in addition to the schema components present in the static context; these components must be compatible as described in . Any xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes in the document are ignored. Indicates whether the application wants location information to be retained for nodes in the returned tree. xs:boolean false Represents a request that the nodes in the returned tree should include location information, accessible using the fn:location function. The implementation may ignore the request. Indicates that location information is not required: but the implementation may provide it anyway.

Except to the extent defined by these options, the precise process used to construct the XDM instance is implementation-defined. In particular, it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used.

The document URI of the returned node is absent.

The function is not deterministic: that is, if the function is called twice with the same arguments, it is implementation-dependent whether the same node is returned on both occasions.

Options set in $options may be supplemented or modified based on configuration options defined externally using mechanisms.

A dynamic error is raised if the content of $value is not a well-formed and namespace-well-formed XML document.

A dynamic error is raised if DTD validation is carried out and the supplied content is not valid against the relevant DTD.

A dynamic error is raised if the value of the xsd-validation option is not one of the permitted values (for example, if the string that follows "type" is not a valid EQName, or if it does not identify a type that is present in the static context).

A dynamic error is raised if the value of the xsd-validation option is set to anything other than skip when the processor is not schema-aware. (XSLT 4.0 and XQuery 4.0 define schema-awareness as an optional feature; other host languages may set their own rules.)

A dynamic error is raised if processor does not have access to an XML parser supporting the requested options, for example the ability to perform DTD validation or XInclude processing or to prevent access to external entities.

A dynamic error is raised if XSD validation is carried out during XML parsing, and the supplied content is not valid against the relevant XSD schema.

A dynamic error is raised if external resources are required (for example, external entities) that are not available because the trust-external option is not set to true.

Since the XML document is presented to the parser as a string, rather than as a sequence of octets, the encoding specified within the XML declaration has no meaning. If the XML parser accepts input only in the form of a sequence of octets, then the processor must ensure that the string is encoded as octets in a way that is consistent with rules used by the XML parser to detect the encoding.

A common use case for this function is to handle input documents that contain nested XML documents embedded within CDATA sections. Since the content of the CDATA section is exposed as text, the receiving query or stylesheet may pass this text to the fn:parse-xml function to create a tree representation of the nested document.

Similarly, nested XML within comments is sometimes encountered, and lexical XML is sometimes returned by extension functions, for example, functions that access web services or read from databases.

A use case arises in XSLT where there is a need to preprocess an input document before parsing. For example, an application might wish to edit the document to remove its DOCTYPE declaration. This can be done by reading the raw text using the fn:unparsed-text function, editing the resulting string, and then passing it to the fn:parse-xml function.

 fn:parse-xml("<alpha>abcd</alpha>") A newly created document node, having an alpha element as its only child; the alpha element in turn is the parent of a text node whose string value is "abcd". fn:parse-xml("<alpha><beta> </beta></alpha>", { "strip-space": "all" }) A newly created document node, having an alpha element as its only child; the alpha element in turn is the parent of a beta element whose content is empty, as a result of whitespace stripping.

The $options parameter has been added.

Additional error conditions have been defined.

Additional options to control DTD and XInclude processing have been added.

Support for binary input has been added.

An option has been added to request that location information (for example, line numbers) be maintained.

 nondeterministic context-dependent focus-independent

This function takes as input an XML external entity represented as a string, and returns the document node at the root of an XDM tree representing the parsed document fragment.

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

If the input is supplied as a binary value, the function detects the encoding using the same rules as the unparsed-text function, except that the special handling of media types such as text/xml and application/xml may be skipped. Otherwise, if the input is a string, any byte order mark as well as the encoding specified in an optional XML declaration should be ignored.

The input must be a namespace-well-formed external general parsed entity. More specifically, it must conform to the production rule extParsedEnt in , it must contain no entity references other than references to predefined entities, and it must satisfy all the rules of for namespace-well-formed documents with the exception that the rule requiring it to be a well-formed document is replaced by the rule requiring it to be a well-formed external general parsed entity.

The input is parsed to form a sequence of nodes which become children of the new document node, in the same way as the content of any element is converted into a sequence of children for the resulting element node.

The $options argument defines the detailed behavior of the function. The apply. The options available are as follows:

Determines the base URI. This is used as the base URI of the document node that is returned. It defaults to the static base URI of the function call. xs:anyURI static-base-uri() Determines whether whitespace-only text nodes are removed from the resulting document. enum("all", "none", "conditional") "none" All whitespace-only text nodes are stripped, unless they are within the scope of the attribute xml:space="preserve". All whitespace-only text nodes are preserved. Equivalent to "none". Unlike the fn:doc function, this function is not subject to external controls determining how whitespace-only text nodes are to be handled; in particular, the xsl:strip-space and xsl:preserve-space declarations in a containing XSLT stylesheet package are ignored. Indicates whether the application wants location information to be retained for nodes in the returned tree. xs:boolean false Represents a request that the nodes in the returned tree should include location information, accessible using the fn:location function. The implementation may ignore the request. Indicates that location information is not required: but the implementation may provide it anyway.

DTD validation is not invoked (an external general parsed entity cannot contain a DOCTYPE declaration.

Schema validation is not invoked, which means that the nodes in the returned document will all be untyped.

XInclude processing is not invoked.

Except as explicitly defined, the precise process used to construct the XDM instance is implementation-defined. In particular, it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used.

The document URI of the returned node is absent.

The function is not deterministic: that is, if the function is called twice with the same arguments, it is implementation-dependent whether the same node is returned on both occasions.

A dynamic error is raised if the content of $value is not a well-formed external general parsed entity, if it contains entity references other than references to predefined entities, or if a document that incorporates this well-formed parsed entity would not be namespace-well-formed.

See also the notes for the fn:parse-xml function.

The main differences between fn:parse-xml and fn:parse-xml-fragment are that for fn:parse-xml, the children of the resulting document node must contain exactly one element node and no text nodes, wheras for fn:parse-xml-fragment, the resulting document node can have any number (including zero) of element and text nodes among its children. An additional difference is that the text declaration at the start of an external entity has slightly different syntax from the XML declaration at the start of a well-formed document.

Note that all whitespace outside the text declaration is significant, including whitespace that precedes the first element node, unless the strip-space option is set to "all".

One use case for this function is to handle XML fragments stored in databases, which frequently allow zero-or-more top level element nodes. Another use case is to parse the contents of a CDATA section embedded within another XML document.

 parse-xml-fragment("<alpha>abcd</alpha><beta>abcd</beta>") A newly created document node, having two elements named alpha and beta as its children; each of these elements in turn is the parent of a text node. parse-xml-fragment("He was <i>so</i> kind") A newly created document node having three children: a text node whose string value is "He was ", an element node named i having a child text node with string value "so", and a text node whose string value is " kind". parse-xml-fragment("") A document node having no children. parse-xml-fragment(" ") A document node whose children comprise a single text node whose string value is a single space. parse-xml-fragment(" ", { "strip-space": "all" }) A document node having no children. parse-xml-fragment('<?xml version="1.0" encoding="UTF-8" standalone="yes"?><a/>') The standalone keyword is not permitted in the text declaration that appears at the start of an external general parsed entity. Thus, it is not the case that any input accepted by the fn:parse-xml function will also be accepted by the fn:parse-xml-fragment.

The $options parameter has been added.

Support for binary input has been added.

An option has been added to request that location information (for example, line numbers) be maintained.

 deterministic context-dependent focus-independent

Given an XSD schema, delivers a function item that can be invoked to validate a document, element, or attribute node against this schema.

The fn:xsd-validator function returns a function item that can be used to validate a document node, element node, or attribute node with respect to a supplied schema.

The details of how the schema is assembled, and the way it is used, are defined by the supplied $options. If the $options argument is empty, the effect is to use the schema components from the static context of the call on fn:xsd-validator. In the general case, however, the schema used for validation may include components from any or all of the following:

The static context of the function call

Explicitly supplied schema documents

Schema components referenced in xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes within the instance document being validated.

More details of schema assembly appear below. Taken together, the assembled components must constitute a valid schema.

The function is designed to separate the process of assembling a schema from the process of performing instance validation. However, if the schema is to include components identified in xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes, then the process of assembling the schema cannot be completed until the instance document is available.

The options recognized are as follows. The apply.

Indicates whether the validation process may cause external resources to be fetched (including, for example, documents referenced using the schema-location property, or xsi:schemaLocation attributes within the document being validated). xs:boolean false() The validation process may retrieve external resources. The validation process must not retrieve any external resources unless access to these resources has been explicitly enabled. If true, the schema to be used for validation includes the schema components available in the static context of the function call. If false, these components are not used. xs:boolean true A list of XDM nodes containing XSD schema documents to be used for validation. element(xs:schema)* () A list of target namespaces identifying schema components to be used for validation. The way in which the processor locates schema components for the specified target namespaces is . A zero-length string denotes a no-namespace schema. xs:anyURI* () A list of locations of XSD schema documents to be used to assemble a schema. Any relative URIs are resolved relative to the base URI of the function call. Access to the schema documents at these locations is allowed regardless of the value of the trust-external option; access to indirectly referenced schema documents (for example, using xs:include) is allowed only if the trust-external option is set to true. xs:anyURI* () If true, the schema to be used for validation includes any schema documents referenced by xsi:schemaLocation or xsi:noNamespaceSchemaLocation attributes in the instance document being validated. If false, these attributes are ignored. xs:boolean false Set to the decimal value 1.0 or 1.1 to indicate which version of XSD is to be used. The default is . A processor may use a later version of XSD than the version requested, but must not use an earlier version. xs:decimal The validation mode. xs:string Validates the input using the element or attribute declaration for the operand node. This element or attribute declaration must exist. This is the default when the type option is absent. Validates the input using the element or attribute declaration for the operand node, if it exists. Validates the input using the supplied governing type. This is the default when the type option is present. Establishes the governing type for validation. The type must be present in the assembled schema. xs:QName? If true, the result of the generated validation function, when validation is successful, includes the property typed-node which contains a copy of the target node augmented with type annotations and expanded default values. If false, the typed node is not included in the result. If a node containing type annotations is to be returned, then the schema used for validation must be compatible with all other schemas used within the same query or stylesheet, as described in ; this is to ensure that the type annotations in the validated document have a consistent interpretation. xs:boolean true If true, the result of the generated validation function, when validation is unsuccessful, includes detailed information about the nature of the validity errors that were found. If false, the result only includes an indication that the document was invalid. Note that setting the value to false means that validation can complete as soon as the first error is found. xs:boolean false

The first task of the function is to assemble a schema (that is, a collection of schema components). Schema components can come from a number of sources, and a schema can be assembled from more than one source, provided that the total collection of components comprises a valid schema: the main thing that will prevent this is if two sources contain conflicting definitions of the same named component.

The default is to use the in-scope schema components from the static context of the function call.

Instead, or in addition, schema components may be loaded explictly for this validator. Supplementary schema components may be requested in a number of ways:

The schema-location option can specify one or more URIs that are interpreted as locations for source XSD schema documents, which are then assembled into a schema as described in the XSD specifications.

The schema option can be used to identify one or more xs:schema element nodes holding source schema documents. This allows a schema to be constructed dynamically by the application, or to be held as a global variable in the source code of a query or stylesheet module.

The target-namespace option can be used to supply the target namespaces of additional schema components that are known to the system or that are made available using some external mechanism. For example, the system might have built-in schemas for common namespaces such as the xml, fn, or xlink namespaces, or it might have a mechanism allowing schemas for a particular namespace to be registered using an external API or configuration mechanism.

The use-xsi-schema-location also allows the application to request that schema documents referenced from xsi:schemaLocation or xsi:noNamespaceSchemaLocation attributes should be included in the schema. By default these attributes are ignored.

It is acceptable to assemble a schema from more than one of these sources. In addition, any of these sources can bring in additional components by the use of the XSD directives xsl:include and xsl:import. The important constraint is that the result should be a valid schema. This will only be the case if the sources used to assemble the schema are compatible with each other: see .

The XSD specification allows a schema to be used for validation even when it contains unresolved references to absent schema components. It is whether this function allows the schema to be incomplete in this way. For example, some processors might allow validation using a schema in which an element declaration contains a reference to a type declaration that is not present in the schema, provided that the element declaration is never needed in the course of a particular validation episode.

Having assembled a schema, the next task is to validate a supplied node (and the subtree rooted at that node).

This description is a deliberate simplification. If the use-xsi-schema-location option is true, then assembly of the schema is not completed until the instance document is available, and in practice overlaps with the validation process.

The xsd-validator function returns a function item (call it V) with the following characteristics:

V has an arity of one. Call the value of the supplied argument $target. The required type of $target is (document-node(*) | element() | attribute())?: that is, it accepts either a well-formed document node, or an element node, or an attribute node, or the empty sequence.

If the argument is the empty sequence then the result of V is also the empty sequence.

In other cases, the result of a call on V is a record containing the following fields:

is-valid as xs:boolean. This field is always present, and indicates whether the supplied $target node was found to be valid against the schema. The value is true if either (a) the validation outcome was valid, or (b) lax validation was requested and the validation outcome was notKnown. In other cases it is false.

typed-node as (document-node(*) | element() | attribute())?. This field is empty unless (a) the option return-typed-node was set (explicitly or implicitly) to true, and (b) the value of the is-valid field is true. It represents the root of a tree that is a deep copy of the input tree, augmented with type annotations and default values.

error-details as map(*)*. This field is empty unless (a) the option return-error-details was set to true, and (b) the supplied document was found to be invalid. The value is a sequence of maps, each containing details of one invalidity that was found. The precise details of the invalidities are , but they may include the following fields, if the information is available:

message. A string containing the text of an error message, intended for a human reader.

rule. A reference to the rule in the XSD specification that was violated. This is a string comprising four parts separated by the character U+007C:

"1.0" or "1.1" indicating whether the reference is to the XSD 1.0 or 1.1 specification.

"1" or "2" indicating whether the reference is to part 1 or part 2 of the specification.

The name of the validation rule (for example "Datatype Valid").

The clause number within that validation rule (for example "2.3").

For example, if an attribute is declared to be of type xs:integer, but the actual value is not in the lexical space of xs:integer, the value of rule might be "1.1|2|Datatype Valid|2.1".

node. The node that was found to be invalid. Note that when a containing element C is invalid because a child element D is not allowed by its content model, the invalid node is C, not D.

error-node. The node whose presence led to detection of the invalidity. In the above example, this would be D.

location. The location of the error, as an instance of the location-record record type.

The validation is performed as described in , with the assembled schema as the effective schema and $target as the operand node.

If the use-xsi-schema-location option is true and a failure occurs processing an xsi:schemaLocation or xsi:noNamespaceSchemaLocation attribute (for example, because a schema document cannot be retrieved, or because the referenced schema document is invalid, or because it is incompatible with other schema components) this is treated as an invalidity, not as a dynamic error: V returns successfully with is-valid set to false.

The function V may fail with a dynamic error if it is not possible to determine whether or not the instance document is valid. This may happen, for example, if processor-defined limits are exceeded.

A dynamic error is raised if the processor is not schema-aware, or if no schema processor with the required capabilities (such as XSD 1.1 support) is available.

A dynamic error is raised if it is not possible to assemble a valid and consistent schema.

Both XQuery and XSLT provide capabilities for XSD-based schema validation in earlier versions of the specifications, and those are retained in 4.0. This function provides additional capability:

It is possible to control validation more precisely, through a wider range of options;

It is possible to validate different instance documents against different schemas;

Information about any invalidities is made available to the application, rather than simply causing a dynamic error;

The capability is provided by means of a function rather than custom syntax, making it easier to integrate into an application.

The capability is available through XPath alone, and therefore with host languages other than XQuery and XSLT.

Three possible ways of using the function include:

To simply test whether or not a document is valid against a schema, set the options return-typed-node and return-error-details to false, and simply test the value of the is-valid field returned when the validation function is called.

To obtain a typed XDM tree from an input document that is expected to be valid, set the option return-typed-node to true. On return from the validation function, test the value of the is-valid field; call fn:error if the value is false; otherwise use the typed-node property of the result. The main benefit of using a typed XDM tree is that it allows static type checking of path expressions: this benefit only applies when the schema used for validation is the imported schema used in the static context. However, there are cases where validation against a different schema is appropriate, for example when validating the result of one query or transformation that is to be used as input to another.

To validate an input document and provide feedback to the document author about any validity problems that were found, set return-error-details to true. If the result of the validation function has is-valid = false(), process the returned error-details. The information available for this part of the processing may not be 100% interoperable, though with care it should be possible to write the query in such a way that it works with different processors.

The function has no effect on the static context. Schemas loaded using this function, either directly or via the effect of xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes, are not added to the static context and have no effect on any other validation episodes. A processor may cache schema components to reduce the cost of processing the same schema repeatedly, but this has no observable effect other than on performance.

 let $validator := xsd-validator({'schema': $schema}) return ($validator(8.5)?is-valid, $validator(8.5km)?is-valid) ]]> true(), false() let $validator := xsd-validator({'schema': $schema}) let $typed-result := $validator(8.5)?typed-node return data($typed-result) instance of xs:decimal ]]> true()

New in 4.0

 deterministic context-independent focus-independent

This function serializes the supplied input sequence $input as described in , returning the serialized representation of the sequence as a string.

The value of the first argument $input acts as the input sequence to the serialization process, which starts with sequence normalization.

The second argument $options provides serialization parameters. These may be supplied in either of two forms:

As an output:serialization-parameters element, having the format described in . In this case the type of the supplied argument must match the required type element(output:serialization-parameters).

As a map. In this case the type of the supplied argument must match the required type map(*)

The single-argument version of this function has the same effect as the two-argument version called with $options set to the empty sequence. This in turn is the same as the effect of passing an output:serialization-parameters element with no child elements.

The final stage of serialization, that is, encoding, is skipped. If the serializer does not allow this phase to be skipped, then the sequence of octets returned by the serializer is decoded into a string by reversing the character encoding performed in the final stage.

If the second argument is omitted, or is supplied in the form of an output:serialization-parameters element, then the values of any serialization parameters that are not explicitly specified is implementation-defined, and may depend on the context.

If the second argument is supplied as a map, then the option parameter conventions apply. In this case:

Each entry in the map defines one serialization parameter.

The key of the entry is an xs:string value in the cases of parameter names defined in these specifications, or an xs:QName (with non-absent namespace) in the case of implementation-defined serialization parameters.

The required type of each parameter, and its default value, are defined by the following table. The default value is used when the map contains no entry for the parameter in question, and also when an entry is present, with the empty sequence as its value. The table also indicates how the value of the map entry is to be interpreted in cases where further explanation is needed.
Parameter Required type Interpretation Default Value
allow-duplicate-names xs:boolean? true means "yes", false means "no" no
byte-order-mark xs:boolean? true means "yes", false means "no" no
canonical xs:boolean? true means "yes", false means "no" no
cdata-section-elements xs:QName* ()
csv-header xs:boolean? true means "yes", false means "no" no
csv-quote-character xs:string? "
csv-separator xs:string? ,
doctype-public xs:string? Zero-length string and () both represent "absent" absent
doctype-system xs:string? Zero-length string and () both represent "absent" absent
encoding xs:string? UTF-8
escape-solidus xs:boolean? true means "yes", false means "no" yes
escape-uri-attributes xs:boolean? true means "yes", false means "no" yes
html-version xs:decimal? 5
include-content-type xs:boolean? true means "yes", false means "no" yes
indent xs:boolean? true means "yes", false means "no" no
indent-attributes xs:boolean? true means "yes", false means "no" no
indent-unit xs:string? absent
item-separator xs:string? absent
json-lines xs:boolean? true means "yes", false means "no" no
json-node-output-method (xs:string | xs:QName)? See Notes 1, 2 xml
line-ending xs:string? absent
media-type xs:string? (a media type suitable for the chosen method)
method (xs:string | xs:QName)? See Notes 1, 2 xml
normalization-form xs:string? none
omit-xml-declaration xs:boolean? true means "yes", false means "no" yes
standalone xs:boolean? true means "yes", false means "no", () means "omit" omit
suppress-indentation xs:QName* ()
undeclare-prefixes xs:boolean? true means "yes", false means "no" no
use-character-maps map(xs:string, xs:string)? See Note 3 {}
version xs:string? 1.0

Notes to the table:

The notation (A | B) represents a union type whose member types are A and B.

If an xs:QName is supplied for the method or json-node-output-method options, then it must have a non-absent namespace URI. This means that system-defined serialization methods such as xml and json are defined as strings, not as xs:QName values.

For the use-character-maps option, the value is a map, whose keys are the characters to be mapped (as xs:string instances), and whose corresponding values are the strings to be substituted for these characters.

A type error occurs if the $options argument is present and does not match either of the types element(output:serialization-parameters)? or map(*).

This is defined as a type error so that it can be enforced via the function signature by implementations that generalize the type system in a suitable way.

If the host language makes serialization an optional feature and the implementation does not support serialization, then a dynamic error is raised.

When the second argument is supplied as a map, and the supplied value is of the wrong type for the particular parameter, for example if the value of indent is a string rather than a boolean, then as defined by the option parameter conventions, a type error is raised. If the value is of the correct type, but does not satisfy the rules for that parameter defined in , then a dynamic error is raised. (For example, this occurs if the map supplied to use-character-maps includes a key that is a string whose length is not one (1)).

If any serialization error occurs, including the detection of an invalid value for a serialization parameter as described above, this results in the fn:serialize call failing with a dynamic error.

One use case for this function arises when there is a need to construct an XML document containing nested XML documents within a CDATA section (or on occasions within a comment). See fn:parse-xml for further details.

Another use case arises when there is a need to call an extension function that expects a lexical XML document as input.

Another use case for this function is serializing instances of the data model into a human readable format for the purposes of debugging. Using the by specifying it as the output method defined in the second argument via output:serialization-parameters, allows for serializing any valid XDM instance without raising a serialization error.

There are also use cases where the application wants to post-process the output of a query or transformation, for example by adding an internal DTD subset, or by inserting proprietary markup delimiters such as the <% ... %> used by some templating languages.

The ability to specify the serialization parameters in an output:serialization-parameters element provides backwards compatibility with the 3.0 version of this specification; the ability to use a map takes advantage of new features in the 3.1 version. The default parameter values are implementation-defined when an output:serialization-parameters element is used (or when the argument is omitted), but are fixed by this specification in the case where a map (including the empty map) is supplied for the argument.

Given the variables:

 ]]> ]]>

The following call might produce the output shown:

 ']]>

The following call would also produce the output shown (though the second argument could equally well be supplied as the empty map ({}), since both parameters are given their default values):

 ']]> serialize({ "a": "AB", "b": "BC" }, { "method": "adaptive" }) '{"a":"AB","b":"BC"}' serialize( array { "a", 3, attribute test { "true" } }, { "method": "adaptive" }) '["a",3,test="true"]'

A new parameter escape-solidus is available to control the escaping of the solidus character in JSON serialization.

A new parameter json-lines is available to serialize a sequence of values in JSON Lines format.

A new parameter canonical is available to give control over serialization of XML, XHTML, and JSON.

New parameters csv-separator, csv-quote-character, and csv-header are available for CSV serialization.

New parameters indent-unit, indent-attributes, and line-ending are available to give control over indentation and line endings.

 nondeterministic context-independent focus-independent

This function takes as input an HTML document, and returns the document node at the root of an XDM tree representing the parsed document.

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

In other cases, $value is expected to contain an HTML document supplied either as a string or a binary value.

The entries that may appear in the $options map are as follows:

The character encoding to use to decode a sequence of octets that represents an HTML document. Note that encoding names are case-insensitive.

 xs:string

Indicates whether the function should fail with a dynamic error if the input is not syntactically valid.

 xs:boolean false Parsing errors should be handled as described in section 13.2.2, Parse Errors. A parsing error should result in the function failing with a dynamic error.

The apply.

If $value is not the empty sequence, an input byte stream is constructed as follows:

If $value is an xs:string, then in principle no decoding is needed. Conceptually, however, the HTML parsing algorithm always starts by decoding an octet stream. The string is therefore first encoded using UTF-8, and the resulting octet stream is then passed to the HTML parser with a known definite encoding of UTF-8, as described in section 13.2.3.1, Parsing with a known character encoding.

If the first codepoint of the string is U+FEFF, this should be stripped, since it might otherwise lead to an incorrect encoding inference.

If the type of $value is a sequence of octets (xs:hexBinary or xs:base64Binary) the encoding of the input byte stream is determined in a way consistent with section 13.2.3.2, Determining the character encoding:

The encoding key of $options is interpreted in step 2 of Determining the character encoding as the user instructing the user agent to override the document’s character encoding with the specified encoding.

If the encoding key of $options is not specified, step 2 of Determining the character encoding is skipped.

Tokenizing the byte stream according to the HTML parsing algorithm as described in section 13.2.5, Tokenization.

Constructing a HTMLDocument object for HTML documents, or an XMLDocument for XML/XHTML documents as described in section 13.2.6, Tree construction.

Building an XDM representation of the HTMLDocument or XMLDocument according to the rules in .

The implementation should process any input HTML that adheres to the current practice of mainstream web browsers, as this evolves over time. Since this is defined by a “living standard” (see ), no specific version is prescribed. An implementation may define additional options to control aspects of the HTML parsing algorithm, including the selection of a specific HTML parsing library; it may also provide options to process alternative HTML versions or dialects.

The implementation should recognize and process XHTML (referred to in as the XML concrete syntax of HTML).

The function is nondeterministic with respect to node identity: that is, if the function is called twice with the same arguments, it is whether the same node is returned on both occasions.

A dynamic error is raised if the content of $value is not a well-formed HTML document. This includes the case where $value cannot be decoded using the specified encoding.

If the HTML parser accepts a string as the input then that may be used directly when $value is an xs:string instead of converting the string to a sequence of octets in an encoding. The HTML parser must not perform character encoding processing on that input, treating the HTML string as being in a known character encoding that matches the encoding of the string.

The WHATWG Encoding specification defines the ISO 8859-1 (latin1) and ASCII encodings as aliases of the windows-1252 encoding.

The expression parse-html(()) returns ().

The expression parse-html("<p>Hello</p>") returns an XDM document node equivalent to the result of parsing the XML

Hello

]]>

The expression parse-html("<p>Hi</p>", method:="html") is equivalent to parse-html("<p>Hi</p>").

New in 4.0

 deterministic context-dependent focus-independent

Reads an external resource containing HTML, and returns the result of parsing the resource as HTML.

The effect of the two-argument function call fn:html-doc($H, $M) is equivalent to the function composition fn:unparsed-binary($H) => fn:parse-html($M).

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

The ability to access external resources depends on whether the calling code is .

The function may raise any error defined for the fn:unparsed-binary or fn:parse-html functions.

New in 4.0

 deterministic context-dependent focus-dependent special-streaming-rules

Returns the context position from the dynamic context.

Returns the context position from the dynamic context. (See .)

A type error is raised if the context value is absent.

 deterministic context-dependent focus-dependent special-streaming-rules

Returns the context size from the dynamic context.

Returns the context size from the dynamic context. (See .)

A type error is raised if the context size is absent.

Under most circumstances, the context size is absent only if the context value is absent. However, XSLT 3.0 with streaming defines situations in which the context value and context position are known, but the context size is unknown.

 (1 to 20)[last() - 1] 19 deterministic context-dependent focus-independent

Returns the current date and time (with timezone).

Returns the current dateTime (with timezone) from the dynamic context. (See .) This is an xs:dateTime that is current at some time during the evaluation of a query or transformation in which fn:current-dateTime is executed.

This function is . The precise instant during the query or transformation represented by the value of fn:current-dateTime() is implementation-dependent.

If the implementation supports data types from XSD 1.1 then the returned value will be an instance of xs:dateTimeStamp. Otherwise, the only guarantees are that it will be an instance of xs:dateTime and will have a timezone component.

The returned xs:dateTime will always have an associated timezone, which will always be the same as the implicit timezone in the dynamic context

 current-dateTime() An xs:dateTimeStamp corresponding to the current date and time. For example, a call of current-dateTime() might return 2024-05-12T18:17:15.125Z corresponding to the current time on May 12, 2024 in timezone Z. deterministic context-dependent focus-independent

Returns the current date.

Returns xs:date(fn:current-dateTime()). This is an xs:date (with timezone) that is current at some time during the evaluation of a query or transformation in which fn:current-date is executed.

This function is . The precise instant during the query or transformation represented by the value of fn:current-date is implementation-dependent.

The returned date will always have an associated timezone, which will always be the same as the implicit timezone in the dynamic context

 current-date() An xs:date corresponding to the current date. For example, a call of current-date() might return 2004-05-12+01:00. deterministic context-dependent focus-independent

Returns the current time.

Returns xs:time(fn:current-dateTime()). This is an xs:time (with timezone) that is current at some time during the evaluation of a query or transformation in which fn:current-time is executed.

This function is . The precise instant during the query or transformation represented by the value of fn:current-time() is implementation-dependent.

The returned time will always have an associated timezone, which will always be the same as the implicit timezone in the dynamic context

 current-time() An xs:time corresponding to the current time. For example, a call of current-time() might return 23:17:00.000-05:00. deterministic context-dependent focus-independent

Returns the value of the implicit timezone property from the dynamic context.

Returns the value of the implicit timezone property from the dynamic context. Components of the dynamic context are described in .

 deterministic context-dependent focus-independent

Returns the value of the default collation property from the dynamic context.

Returns the value of the default collation property from the dynamic context context. Components of the dynamic context are described in .

The default collation property can never be absent. If it is not explicitly defined, a system defined default can be invoked. If this is not provided, the Unicode codepoint collation (http://www.w3.org/2005/xpath-functions/collation/codepoint) is used.

In most cases, the default collation is known statically, and a call on this function can therefore be pre-evaluated during static analysis. The only notable exception is when a call on default-collation() is used to define the default value of a parameter to a user-defined function. In this case it is interpreted as a reference to the default collation in the context of the relevant function call, which may differ from the default collation of the function definition.

 deterministic context-dependent focus-independent

Returns the value of the default language property from the dynamic context.

Returns the value of the default language property from the dynamic context. Components of the dynamic context are described in .

The default language property can never be absent. The functions fn:format-integer, fn:format-date, fn:format-time, and fn:format-dateTime are defined to use the default language if no explicit language is supplied. The default language may play a role in selection of a default collation, but this is not a requirement.

 deterministic context-dependent focus-independent

This function returns the value of the executable base URI property from the dynamic context.

The function (despite its name) returns the value of the executable base URI property from the dynamic context. If the property is absent, the empty sequence is returned.

Components of the dynamic context are described in .

The executable base URI will in many cases be the same as the static base URI in the static context. However, XQuery and XSLT give an implementation freedom to use different base URIs during the static analysis phase and the dynamic evaluation phase, that is, for retrieval of compile-time and run-time resources respectively. This is appropriate when the implementation allows the output of static analysis (a “compiled” query or stylesheet) to be deployed for execution to a different location from the one where static analysis took place. In this situation, the fn:static-base-uri function should return a URI suitable for locating resources needed during dynamic evaluation.

If a call on the fn:static-base-uri function appears within the expression used to define the value of an optional parameter to a user-defined function, then the value supplied to the function (if the argument is omitted) will be the executable base URI from the dynamic context of the function caller. This allows such a function to resolve relative URIs supplied in other parameters to the same function.

 deterministic context-dependent focus-dependent special-streaming-rules

Returns a function item having a given name and arity, if there is one.

A call to fn:function-lookup starts by looking for a function definition in the named functions component of the dynamic context (specifically, the dynamic context of the call to fn:function-lookup), using the expanded QName supplied as $name and the arity supplied as $arity. There can be at most one such function definition.

If no function definition can be identified (by name and arity), then the empty sequence is returned.

If a function definition is identified, then a function item is obtained from the function definition using the same rules as for evaluation of a named function reference (see ). The captured context of the returned function item (if it is context dependent) is the static and dynamic context of the call on fn:function-lookup.

If the arguments to fn:function-lookup identify a function that is present in the static context of the function call, the function will always return the same function that a static reference to this function would bind to. If there is no such function in the static context, then the results depend on what is present in the dynamic context, which is implementation-defined.

An error is raised if the identified function depends on components of the static or dynamic context that are not present, or that have unsuitable values. For example is raised for the call function-lookup( #fn:name, 0 ) if the context value is absent, and is raised for the call function-lookup( #fn:id, 1 ) if the context value is not a single node in a tree that is rooted at a document node. The error that is raised is the same as the error that would be raised by the corresponding function if called with the same static and dynamic context.

This function can be useful where there is a need to make a dynamic decision on which of several statically known functions to call. It can thus be used as a substitute for polymorphism, in the case where the application has been designed so several functions implement the same interface.

The function can also be useful in cases where a query or stylesheet module is written to work with alternative versions of a library module. In such cases the author of the main module might wish to test whether an imported library module contains or does not contain a particular function, and to call a function in that module only if it is available in the version that was imported. A static call would cause a static error if the function is not available, whereas getting the function using fn:function-lookup allows the caller to take fallback action in this situation.

If the function that is retrieved by fn:function-lookup is context-dependent, that is, if it has dependencies on the static or dynamic context of its caller, the context that applies is the static and/or dynamic context of the call to the fn:function-lookup function itself. The context thus effectively forms part of the closure of the returned function. This mainly applies when the target of fn:function-lookup is a built-in function, because user-defined functions typically have no dependency on the static or dynamic context of the function call (an exception arises when the expressions used to define default values for parameters are context-dependent). The rule applies recursively, since fn:function-lookup is itself a context-dependent built-in function.

However, the static and dynamic context of the call to fn:function-lookup may play a role even when the selected function definition is not itself context dependent, if the expressions used to establish default parameter values are context dependent.

User-defined XSLT or XQuery functions should be accessible to fn:function-lookup only if they are statically visible at the location where the call to fn:function-lookup appears. This means that private functions, if they are not statically visible in the containing module, should not be accessible using fn:function-lookup.

These specifications do not define any circumstances in which the dynamic context will contain functions that are not present in the static context, but neither do they rule this out. For example an API may provide the ability to add functions to the dynamic context, and such functions may potentially be context-dependent.

The mere fact that a function exists and has a name does not of itself mean that the function is present in the dynamic context. For example, functions obtained through use of the fn:load-xquery-module function are not added to the dynamic context.

 function-lookup( #fn:substring, 2 )( 'abcd', 2 ) 'bcd' (fn:function-lookup( #xs:dateTimeStamp, 1 ), xs:dateTime#1)[1] ('2011-11-11T11:11:11Z') An xs:dateTime value set to the specified date, time, and timezone; if the implementation supports XSD 1.1 then the result will be an instance of the derived type xs:dateTimeStamp. The query is written to ensure that no failure occurs when the implementation does not recognize the type xs:dateTimeStamp. declare namespace zip = "http://expath.org/ns/zip"; let $f := function-lookup( #zip:binary-entry, 2 ) return if (exists($f)) then $f("file:///temp.zip", "index.xml") else () The result of calling zip:binary-entry("file:///temp.zip", "index.xml") if the function is available, or the empty sequence otherwise. deterministic context-independent focus-independent

Returns the name of the function identified by a function item.

If $function refers to a named function, fn:function-name($func) returns the name of that function.

Otherwise ($function refers to an anonymous function), fn:function-name($function) returns the empty sequence.

The prefix part of the returned QName is implementation-dependent.

 function-name(substring#2) #Q{http://www.w3.org/2005/xpath-functions}substring The namespace prefix of the returned QName is not predictable. function-name(fn($node) { count($node/*) }) () deterministic context-independent focus-independent

Returns the arity of the function identified by a function item.

The fn:function-arity function returns the arity (number of arguments) of the function identified by $function.

 function-arity(substring#2) 2 function-arity(fn($node) { name($node) }) 1 let $initial := substring(?, 1, 1) return function-arity($initial) 1 deterministic context-independent focus-independent

Returns the annotations of the function item.

The fn:function-annotations function returns the annotations of $function as a sequence of single-entry maps, each associating the name of a function annotation with the value of the annotation. Note that several annotations on a function can share the same name. The order of the annotations is retained.

The result is a sequence of single-entry maps, each being an instance of map(xs:QName, xs:anyAtomicType*). If a function (for example, a built-in function) has no annotations, the result of the function is the empty sequence.

For each annotation, a map is returned, with a single entry. The key of the map entry is the name of the annotation as an xs:QName. The value of the entry is the value of the annotation as a sequence of atomic items. If the annotation has no values, the associated value is the empty sequence.

In the common case where the annotation names are all unique, the result of the function can readily be converted into single map by applying the function map:merge.

 function-annotations(true#0) () declare %private function local:inc($c) { $c + 1 }; function-annotations(local:inc#1) { #Q{http://www.w3.org/2012/xquery}private : () } let $old := %local:deprecated('0.1', '0.2') fn() {} let $ann := function-annotations($old) return map:merge($ann) { #Q{http://www.w3.org/2005/xquery-local-functions}deprecated : ("0.1", "0.2") }

New in 4.0

Changes the function to return a sequence of key-value pairs rather than a map.

 deterministic context-independent focus-independent

Applies the function item $action to every item from the sequence $input in turn, returning the concatenation of the resulting sequences in order.

The function calls $action($item, $pos) for each item in $input. The final result is the sequence concatenation of the results of these calls, preserving order.

dm:iterate-sequence($input, $action) for-each(1 to 5, fn($a) { $a * $a }) 1, 4, 9, 16, 25 for-each( ("john", "jane"), string-to-codepoints#1 ) 106, 111, 104, 110, 106, 97, 110, 101 for-each(("23", "29"), xs:int#1) 23, 29 for-each( ('one', 'two', 'three'), fn($item, $pos) { $pos || '. ' || $item } ) "1. one", "2. two", "3. three"

The $action callback function accepts an optional position argument.

 deterministic context-independent focus-independent

Returns those items from the sequence $input for which the supplied function $predicate returns true.

The function returns a sequence containing those items from $input for which $predicate($item, $pos) returns true.

 for-each( $input, fn($item, $pos) { if ($predicate($item, $pos)) { $item } } )

As a consequence of the function signature and the function calling rules, a type error occurs if the supplied $predicate function returns anything other than a single xs:boolean item or the empty sequence; there is no conversion to an effective boolean value, but the empty sequence is interpreted as false.

If $predicate is an arity-1 function, the function call fn:filter($input, $predicate) has a very similar effect to the expression $input[$predicate(.)]. There are some differences, however. In the case of fn:filter, the function $F is required to return an optional boolean; there is no special treatment for numeric predicate values, and no conversion to an effective boolean value. Also, with a filter expression $input[$predicate(.)], the focus within the predicate is different from that outside; this means that the use of a context-sensitive function such as fn:lang#1 will give different results in the two cases.

 filter(1 to 10, fn($a) { $a mod 2 = 0 }) 2, 4, 6, 8, 10 ')//a, fn { @id eq "2" })]]> ]]> The function returns () when there is no @id attribute; this is treated as false. filter((), lang("en", ?)) () let $sequence := (1, 1, 2, 3, 4, 4, 5) return filter( $sequence, fn($item, $pos) { $item = $sequence[$pos - 1] } ) 1, 4

The $predicate callback function accepts an optional position argument.

The $predicate callback function may return the empty sequence (meaning false).

 deterministic context-independent focus-independent

Processes the supplied sequence from left to right, applying the supplied function repeatedly to each item in turn, together with an accumulated result value.

If $input is empty, the function returns $init.

If $input contains at least one item, the function calls $action($init, $input[1]), returning a value A1.

If $input contains a second item, the function then calls $action(A1, $input[2]), returning A2; to process the nth item it calls $action(A/n-1, $input[N]).

This continues in the same way until the end of the $input sequence; the final result is the result of the last call on $action.

 declare function fold-left( $input as item()*, $init as item()*, $action as fn(item()*, item()) as item()* ) as item()* { if (empty($input)) then $init else fold-left(tail($input), $action($init, head($input)), $action) };

As a consequence of the function signature and the function calling rules, a type error occurs if $action cannot be applied to arguments $acc and $item, where $acc is either the value of $init or the result of a previous application of $action, and $item is any single item from the sequence $input.

This operation is often referred to in the functional programming literature as “folding” or “reducing” a sequence. It typically takes a function that operates on a pair of values, and applies it repeatedly, with the accumulated result ($acc) as the first argument, and the next item in the sequence ($item) as the second argument. The accumulated result is initially set to the value of the $init argument, which is conventionally a value (such as zero in the case of addition, one in the case of multiplication, or a zero-length string in the case of string concatenation) that causes the function to return the value of the other argument unchanged.

Unlike other functions that apply a user-supplied callback function to successive items in a sequence, this function does not supply the current position to the callback function as an optional argument. If positional information is required, this can be achieved by first forming the sequence $input ! { 'position': position(), 'item': . } and then applying the fn:fold-left function to this sequence.

The result of the function is not affected if a processor exits the iteration early, at a point where it can establish that all remaining calls on $action will return the accumulated value unchanged. Such an early exit is possible, for example, if the supplied action has the form fn($result, $item) { if (C) then $result else E }, where the condition C is deterministic and depends only on $result. A processor implementing this strategy will evaluate the following expression without iterating over all items:

fold-left( 1 to 1000000000, 0, fn($sum, $n) { if ($sum ge 10) then $sum else $sum + $n } ) fold-left( 1 to 5, 0, fn($a, $b) { $a + $b } ) 15 This returns the sum of the items in the sequence fold-left( (2, 3, 5, 7), 1, fn($a, $b) { $a * $b } ) 210 This returns the product of the items in the sequence fold-left( (true(), false(), false()), false(), fn($a, $b) { $a or $b } ) true() This returns true if any item in the sequence has an effective boolean value of true fold-left( (true(), false(), false()), false(), fn($a, $b) { $a and $b } ) false() This returns true only if every item in the sequence has an effective boolean value of true fold-left( 1 to 5, (), fn($a, $b) { $b, $a } ) 5, 4, 3, 2, 1 This reverses the order of the items in a sequence fold-left( 1 to 5, "", concat(?, ".", ?) ) ".1.2.3.4.5" fold-left( 1 to 5, "$z", concat("$f(", ?, ", ", ?, ")") ) "$f($f($f($f($f($z, 1), 2), 3), 4), 5)" fold-left( 1 to 5, {}, fn($map, $n) { map:put($map, $n, $n * 2) } ) { 1: 2, 2: 4, 3: 6, 4: 8, 5: 10 }

A note was added stating that processors may exit the iteration early if the result can no longer change.

 deterministic context-independent focus-independent special-streaming-rules

Processes the supplied sequence from right to left, applying the supplied function repeatedly to each item in turn, together with an accumulated result value.

If $input is empty, the function returns $init.

Let I/n be the last item in $input, and let A/n be $init. The function starts by calling $action(I/n, $init), producing a result A/n-1.

If there is a previous item, I/n-1, the function then calls $action(I/n-1, A/n-1), producing the result A/n-2.

This continues in the same way until the start of the $input sequence is reached; the final result is the value A/0.

 declare function fold-right( $input as item()*, $init as item()*, $action as fn(item(), item()*) as item()* ) as item()* { if (empty($input)) then $init else $action(head($input), fold-right(tail($input), $init, $action)) };

As a consequence of the function signature and the function calling rules, a type error occurs if $action cannot be applied to arguments $item and $acc, where $item is any item in the sequence $input, and $acc is either the value of $init or the result of a previous application of $action.

This operation is often referred to in the functional programming literature as “folding” or “reducing” a sequence. It takes a function that operates on a pair of values, and applies it repeatedly, with the next item in the sequence as the first argument, and the result of processing the remainder of the sequence as the second argument. The accumulated result is initially set to the value of the $init argument, which is conventionally a value (such as zero in the case of addition, one in the case of multiplication, or a zero-length string in the case of string concatenation) that causes the function to return the value of the other argument unchanged.

In cases where the function performs an associative operation on its two arguments (such as addition or multiplication), fn:fold-right produces the same result as fn:fold-left.

Unlike other functions that apply a user-supplied callback function to successive items in a sequence, this function does not supply the current position to the callback function as an optional argument. If positional information is required, this can be achieved by first forming the sequence $input ! { 'position': position(), 'item': . } and then applying the fn:fold-right function to this sequence.

As with fn:fold-left, a processor may exit the iteration early if it can establish that all remaining calls on $action will return the accumulated value unchanged.

 fold-right( 1 to 5, 0, fn($a, $b) { $a + $b } ) 15 This returns the sum of the items in the sequence fold-right( 1 to 5, "", concat(?, ".", ?) ) "1.2.3.4.5." fold-right( 1 to 5, "$z", concat("$f(", ?, ", ", ?, ")") ) "$f(1, $f(2, $f(3, $f(4, $f(5, $z)))))"

A note was added stating that processors may exit the iteration early if the result can no longer change.

 deterministic context-independent focus-independent

Processes a supplied value repeatedly, continuing while some condition remains true, and returning the first value that does not satisfy the condition.

Informally, the function behaves as follows:

$pos is initially set to 1.

$predicate($input, $pos) is evaluated. If the result is false or (), the function returns the value of $input.

Otherwise, $action($input, $pos) is evaluated, the resulting value is used as a new $input, and the process repeats from step 2 with $pos incremented by 1.

 declare %private function while-do-helper( $input as item()*, $predicate as fn(item()*, xs:integer) as xs:boolean?, $action as fn(item()*, xs:integer) as item()*, $pos as xs:integer ) as item()* { if ($predicate($input, $pos)) then while-do-helper($action($input, $pos), $predicate, $action, $pos + 1) else $input }; declare function while-do( $input as item()*, $predicate as fn(item()*, xs:integer) as xs:boolean?, $action as fn(item()*, xs:integer) as item()* ) as item()* { while-do-helper($input, $predicate, $action, 1) };

While-do loops are very common in procedural programming languages, and this function provides a way to write functionally clean and interruptible iterations without side-effects. As long as a given condition is met, an new value is computed and tested again. Depending on the use case, the value can be a simple atomic item or an arbitrarily complex data structure.

The function fn:do-until can be used to perform the action before the first predicate test.

Note that, just as when writing recursive functions, it is easy to construct infinite loops.

 256 The loop is interrupted as soon as the computed product is greater than 100. 3628800 This returns the factorial of 10, i.e., the product of all integers from 1 to 10. 5 This returns the first positive number missing in a sequence. 5, 6, 7, 8, 9 The first number of a sequence is removed as long as it is smaller than 5. = 0.0000000001 }, fn($guess) { ($guess + $input div $guess) div 2 } ) => round(5) ]]> 1984 This computes the square root of a number.

The following example generates random doubles. It is interrupted once a number exceeds a given limit:

New in 4.0

The $predicate callback function may return the empty sequence (meaning false).

 deterministic context-independent focus-independent

Processes a supplied value repeatedly, continuing when some condition is false, and returning the value that satisfies the condition.

Informally, the function behaves as follows:

$pos is initially set to 1.

$action($input, $pos) is evaluated, and the resulting value is used as a new $input.

$predicate($input, $pos) is evaluated. If the result is true, the function returns the value of $input. Otherwise, the process repeats from step 2 with $pos incremented by 1.

When the predicate returns the empty sequence, this is treated as false.

 declare %private function do-until-helper( $input as item()*, $action as fn(item()*, xs:integer) as item()*, $predicate as fn(item()*, xs:integer) as xs:boolean?, $pos as xs:integer ) as item()* { let $result := $action($input, $pos) return if ($predicate($result, $pos)) then ( $result ) else ( do-until-helper($result, $action, $predicate, $pos + 1) ) }; declare function do-until( $input as item()*, $action as fn(item()*, xs:integer) as item()*, $predicate as fn(item()*, xs:integer) as xs:boolean? ) as item()* { do-until-helper($input, $action, $predicate, 1) };

Do-until loops are very common in procedural programming languages, and this function provides a way to write functionally clean and interruptible iterations without side-effects. A new value is computed and tested until a given condition fails. Depending on the use case, the value can be a simple atomic item or an arbitrarily complex data structure.

The function fn:while-do can be used to perform the action after the first predicate test.

Note that, just as when writing recursive functions, it is easy to construct infinite loops.

 50 } ) ]]> 1, 4, 9, 16, 25, 36, 49, 64 The loop is interrupted once the last value of the generated sequence is greater than 50. 10 } ) ]]> 55, 34, 21, 13, 8, 5, 3, 2, 1, 1, 0 The computation is continued as long as the average of the first Fibonacci numbers is smaller than 10.

New in 4.0

The $predicate callback function may return the empty sequence (meaning false).

 deterministic context-independent focus-independent

Applies the function item $action to successive pairs of items taken one from $input1 and one from $input2, returning the concatenation of the resulting sequences in order.

The function returns the value of the expression:

If one sequence is longer than the other, excess items in the longer sequence are ignored.

 for-each-pair( ("a", "b", "c"), ("x", "y", "z"), concat#2 ) "ax", "by", "cz" for-each-pair( 1 to 5, 1 to 5, fn($a, $b) { 10 * $a + $b } ) 11, 22, 33, 44, 55 let $s := 1 to 8 return for-each-pair($s, tail($s), fn($a, $b) { $a * $b }) 2, 6, 12, 20, 30, 42, 56 "1: 3", "2: 8", "3: 3"

The $action callback function accepts an optional position argument.

 deterministic context-dependent focus-independent

Sorts a supplied sequence, based on the value of a sort key supplied as a function.

This function is retained for compatibility from version 3.1 of this specification. Version 4.0 introduces two more powerful functions, fn:sort-by and fn:sort-with.

The function call fn:sort($input, $collation, $key) is defined to have the same effect as the call fn:sort-by($input, { 'key': $key, 'collation': $collation, 'order': 'ascending'}). See fn:sort-by.

The result of the function is a sequence that contains all the items from $input, typically in a different order, the order being defined by the supplied sort key definitions.

 fn:sort-by($input, { 'key':$key, 'collation':$collation, 'order':'ascending' })

If the set of computed sort keys contains values that are not comparable using the lt operator then the sort operation will fail with a type error ().

sort((1, 4, 6, 5, 3)) 1, 3, 4, 5, 6 sort((1, -2, 5, 10, -10, 10, 8), (), abs#1) 1, -2, 5, 8, 10, -10, 10 let $SWEDISH := collation({ 'lang': 'se' }) return sort(//name!string(), $SWEDISH) The names in //name sorted using Swedish collation. sort(//employee, (), fn { name ! (last, first) }) A sorted sequence of employees by last name as the major sort key and first name as the minor sort key, using the default collation. deterministic context-dependent focus-independent

Sorts a supplied sequence, based on the value of a number of sort keys supplied as functions.

The result of the function is a sequence that contains all the items from $input, typically in a different order, the order being defined by the supplied sort key definitions.

A sort key definition is an instance of the record type fn:sort-key-record (see ). Its key field supplies a sort key function, which is applied to each item in the input sequence to determine a sort key value; its collation field supplies a collation, used when comparing sort key values of type xs:string or xs:untypedAtomic; and its order field supplies an order direction.

When comparing values of types other than xs:string or xs:untypedAtomic, the collation is ignored (but an error may be reported if it is invalid). For more information see .

The number of sort key definitions is determined by the number of records supplied in the $keys argument. If the argument is absent or empty, the default is a single sort key definition in which every field takes its default value.

The result of the fn:sort-by function is obtained as follows:

The result sequence contains the same items as the input sequence $input, but generally in a different order.

The sort key definitions are established as described above. The sort key definitions are in major-to-minor order. That is, the position of two items $A and $B in the result sequence is determined first by the relative magnitude of their primary sort key values, which are computed by evaluating the sort key function in the first sort key definition. If those two sort key values are equal, then the position is determined by the relative magnitude of their secondary sort key values, computed by evaluating the sort key function in the second sort key definition, and so on.

When a pair of corresponding sort key values of $A and $B are found to be not equal, then $A precedes $B in the result sequence if both the following conditions are true, or if both conditions are false:

The sort key value for $A is less than the sort key value for $B, as defined below.

The order direction in the corresponding sort key definition is "ascending".

If all the sort key values for $A and $B are pairwise equal, then $A precedes $B in the result sequence if and only if $A precedes $B in the input sequence.

That is, the sort is stable.

Each sort key value for a given item is obtained by applying the sort key function of the corresponding sort key definition to that item. The result of this function is in the general case a sequence of atomic items. Two sort key values $a and $b are compared as follows:

Let $C be the collation in the corresponding sort key definition.

Let $REL be the result of evaluating op:lexicographic-compare($key($A), $key($B), $C) where op:lexicographic-compare($a, $b, $C) is defined as follows:

if (empty($a) and empty($b)) then 0 else if (empty($a)) then -1 else if (empty($b)) then +1 else let $rel = op:simple-compare(head($a), head($b), $C) return if ($rel eq 0) then op:lexicographic-compare(tail($a), tail($b), $C) else $rel

Here op:simple-compare($k1, $k2) is defined as follows:

if ($k1 instance of (xs:string | xs:anyURI | xs:untypedAtomic) and $k2 instance of (xs:string | xs:anyURI | xs:untypedAtomic)) then compare($k1, $k2, $C) else if ($k1 instance of xs:numeric and $k2 instance of xs:numeric) then compare($k1, $k2) else if ($k1 eq $k2) then 0 else if ($k2 lt $k2) then -1 else +1

This raises an error if two keys are not comparable, for example if one is a string and the other is a number, or if both belong to a non-ordered type such as xs:QName.

If $REL is zero, then the two sort key values are deemed equal; if $REL is -1 then $a is deemed less than $b, and if $REL is +1 then $a is deemed greater than $b

If the set of computed sort keys contains values that are not comparable using the lt operator then the sort operation will fail with a type error ().

The function is a generalization of the fn:sort function available in 3.1, which is retained for compatibility. The enhancements allow multiple sort keys to be defined, each potentially with a different collation, and allow sorting in descending order.

If the sort key for an item evaluates to the empty sequence, the effect of the rules is that this item precedes any value for which the key is non-empty. This is equivalent to the effect of the XQuery option empty least. The effect of the option empty greatest can be achieved by adding an extra sort key definition with { 'key': fn { empty(K(.) } }: when comparing boolean sort keys, false precedes true.

 sort-by((1, 4, 6, 5, 3), ()) 1, 3, 4, 5, 6 sort-by((1, 4, 4e0, 6, 5, 3), { 'order': 'descending' }) 6, 5, 4, 4e0, 3, 1 sort-by((1, -2, 5, 10, -10, 10, 8), { 'key': abs#1 }) 1, -2, 5, 8, 10, -10, 10 let $SWEDISH := collation({ 'lang': 'se' }) return sort-by(//name, { 'collation': $SWEDISH }) The names in //name sorted using Swedish collation. sort-by(//employee, { 'key': fn { name ! (last, first) } }) Sorts a sequence of employees by last name as the major sort key and first name as the minor sort key, using the default collation sort-by( //employee, ({ 'key': fn { name/last }, 'collation': collation({ 'lang': 'se' }) }, { 'key': fn { xs:decimal(salary) }, 'order': 'descending' })) Sorts a sequence of employees first by increasing last name (using Swedish collation order) and then by decreasing salary

New in 4.0.

 deterministic context-independent focus-independent

Sorts a supplied sequence, according to the order induced by the supplied comparator functions.

Informally, the items of the supplied $input are sorted into an order based on the result of evaluating the supplied $comparators. The result is a sorted sequence.

Each comparator function takes two items and returns an xs:integer that defines the relationship between these items, following the conventions of the fn:compare function. Specifically, when a comparator $c is used to compare two items $a and $b, it must return a negative integer if $a is to be sorted before $b, zero if they are considered equal, and a positive integer if $a is to be sorted after $b.

There may be more than one comparator, representing sort keys in major to minor order. To determine the relative position of two items $a and $b:

The first comparator is called: $comparators[1]($a, $b). If the result is non-zero, this determines the relative position of $a and $b in the result sequence, and any further comparators can be ignored.

If the Nth comparator returns zero, then:

If this is the last comparator, then the two items are considered equal, and their relative position in the result sequence will be the same as their relative position in the input sequence (that is, the sort is stable).

Otherwise, the next comparator is evaluated, and so on, until the last comparator is reached or the result of a comparator is non-zero.

To ensure that the sorting algorithm produces predictable results (indeed, to ensure that it terminates), it is necessary for the comparators to have certain properties. Specifically, for every comparator C:

C must be deterministic (if called twice with the same arguments, it must deliver the same result).

Every item must be equal to itself: C($a, $a) must be zero.

The ordering must be consistent: if C($a, $b) < 0, then C($b, $a) > 0, and vice versa, and similarly, if C($a, $b) = 0, then C($b, $a) = 0.

The ordering must be transitive: if C($a, $b) < 0 and C($b, $c) < 0, then C($a, $c) < 0.

If a comparator function raises an error when processing any pair of items from the input sequence (for example, if the comparator function is fn:compare#2 and the two items are of non-comparable types), then the evaluation of fn:sort-with fails with that error.

In general it is unpredictable which pairs of items from the input sequence will actually be compared using each comparator function. However, a comparator function must not be called to compare two items if they have been determined as unequal by an earlier comparator function.

 sort-with((1, 4, 6, 5, 3), compare#2) 1, 3, 4, 5, 6 sort-with((1, 4, 6, 5, 3), op('-')) 1, 3, 4, 5, 6 sort-with((1, 4, 4e0, 6, 5, 3), fn($a, $b) { compare($b, $a) }) 6, 5, 4, 4e0, 3, 1 sort-with( (1, -2, 5, 10, -12, 8), fn($a, $b) { abs($a) - abs($b) } ) 1, -2, 5, 8, 10, -12 return sort-with($persons/person, ( fn($a, $b) { compare($a/@age, $b/@age) }, fn($a, $b) { compare($a/@name, $b/@name) } )) ]]> ]]>

New in 4.0

 deterministic context-independent focus-independent

Returns all the GNodes reachable from a given start GNode by applying a supplied function repeatedly.

The function works with both XNodes and JNodes.

The value of $node is a node from which navigation starts. If $node is an empty sequence, the function returns the empty sequence.

The value of $step is a function that takes a single GNode as input, and returns a set of GNodes as its result.

The result of the fn:transitive-closure function is the set of GNodes that are reachable from $node by applying the $step function one or more times.

Although $step may return any sequence of GNodes, the result is treated as a set: the order of GNodes in the sequence is ignored, and duplicates are ignored. The result of of the transitive-closure function will always be a sequence of GNodes in document order with no duplicates.

 declare %private function tc-inclusive( $nodes as node()*, $step as fn($node as node()) as node()* ) as node()* { let $nextStep := $nodes/$step(.) let $newNodes := $nextStep except $nodes return if (exists($newNodes)) then $nodes union tc-inclusive($newNodes, $step) else $nodes }; declare function transitive-closure ( $node as node(), $step as fn($node as node()) as node()* ) as node()* { tc-inclusive($node/$step(.), $step) }; (: Explanation: The private helper function tc-inclusive takes a set of GNodes as input, and calls the $step function on each one of those GNodes; if the result includes GNodes that are not already present in the input, then it makes a recursive call to find GNodes reachable from these new GNodes, and returns the union of the supplied GNodes and the GNodes returned from the recursive call (which will always include the new GNodes selected in the first step). If there are no new GNodes, the recursion ends, returning the GNodes that have been found up to this point. The main function fn:transitive-closure finds the nodes that are reachable from the start GNodes in a single step, and then invokes the helper function tc-inclusive to add GNodes that are reachable in multiple steps. :)

Cycles in the data are not a problem; the function stops searching when it finds no new GNodes.

The function may fail to terminate if the supplied $step function constructs and returns new GNodes. A processor may detect this condition but is not required to do so.

The $node GNodes is not included in the result, unless it is reachable by applying the $step function one or more times. If a result is required that does include $node, it can be readily added to the result using the union operator: $node | transitive-closure($node, $step).

 }]]> transitive-closure( $data//person[@id = "2"], $direct-reports )/string(@id) "3", "4", "6", "7", "8" transitive-closure( $data, function { child::* } )/@id ! string() "0", "1", "2", "3", "4", "5", "6", "7", "8"

The following example, given $root as the root of an XSLT stylesheet module, returns the URIs of all stylesheet modules reachable using xsl:import and xsl:include declarations:

transitive-closure($root, fn { document(//(xsl:import|xsl:include)/@href) }) =!> document-uri()

This example uses the XSLT-defined document() function.

New in 4.0

 deterministic context-independent focus-independent

Makes a dynamic call on a function with an argument list supplied in the form of an array.

The result of the function is obtained by invoking the supplied function $function with arguments taken from the members of the supplied array $arguments. The first argument of the function call is the first member of $arguments, the second argument is the second member of $arguments, and so on.

The arity of the supplied function $function must be less than or equal to the size of the array $arguments.

The effect of calling fn:apply($f, [$a, $b, $c, ...]) is the same as the effect of the dynamic function call $f($a, $b, $c, ....). For example, the coercion rules are applied to the supplied arguments in the usual way. Among other things this means that excess arguments are ignored.

A dynamic error is raised if the arity of the function $function is greater than the size of the array $arguments ().

The function is useful where the arity of a function item is not known statically.

 apply(concat#3, [ "a", "b", "c" ]) "abc"

The expression apply($f, array:subarray([ "a", "b", "c", "d", "e", "f" ], 1, function-arity($f))) calls the supplied function $f supplying the number of arguments required by its arity.

As a result of changes to the coercion rules, the number of supplied arguments can be greater than the number required: extra arguments are ignored.

 deterministic context-independent focus-independent

Performs partial application of a function item by binding values to selected arguments.

The result is a function obtained by binding values to selected arguments of the function item $function. The arguments to be bound are represented by entries in the $arguments map: an entry with key $i and value $v causes the argument at position $i (1-based) to be bound to $v.

Any entries in $arguments whose keys are greater than the arity of $function are ignored.

If $arguments is the empty map then the function returns $function unchanged.

For example, the effect of calling fn:partial-apply($f, { 2: $x }) is the same as the effect of the partial appplication $f(?, $x, ?, ?, ....). The coercion rules are applied to the supplied arguments in the usual way.

Unlike a partial application using place-holder arguments:

The arity of $function need not be statically known.

It is possible to bind all the arguments of $function: the effect is to return a zero-arity function.

The result is a partially applied function having the following properties (which are defined in ):

name: absent.

arity: The arity of $function minus the number of parameters in $function that map to supplied arguments in $arguments.

parameter names: The names of the parameters of $function that do not map to supplied arguments in $arguments.

signature: The parameters in the returned function are the parameters of $function that do not map to supplied arguments in $arguments, retaining order. The result type of the returned function is the same as the result type of $function.

An implementation that can determine a more specific signature (for example, through use of type analysis) is permitted to do so.

body: The body of $function.

captured context: The static and dynamic context of $function, augmented, for each supplied argument, with a binding of the converted argument value to the corresponding parameter name.

A type error is raised if any of the supplied arguments, after applying the coercion rules, does not match the required type of the corresponding function parameter.

In addition, a dynamic error may be raised if any of the supplied arguments does not match other constraints on the value of that argument (for example, if the value supplied for a parameter expecting a regular expression is not a valid regular expression); or if the processor is able to establish that evaluation of the resulting function will fail for any other reason (for example, if an error is raised while evaluating a subexpression in the function body that depends only on explicitly supplied and defaulted parameters).

See also .

The function is useful where the arity of a function item is not known statically, or where all arguments in a function are to be bound, returning a zero-arity function.

 let $f := partial-apply(dateTime#2, {2: xs:time('00:00:00') }) return $f(xs:date('2025-03-01')) xs:dateTime('2025-03-01T00:00:00')

New in 4.0

 deterministic context-independent focus-independent

Returns a function whose effect is to apply a supplied binary operator to two arguments.

The supplied operator must be one of:

",", "and", "or", "+", "-", "*", "div", "idiv", "mod", "=", "<", "<=", ">", ">=", "!=", "eq", "lt", "le", "gt", "ge", "ne", "<<", ">>", "precedes", "follows", "precedes-or-is", "follows-or-is", "is", "is-not", "||", "|", "union", "except", "intersect", "to", "otherwise".

The result of calling fn:op("⊙"), where ⊙ is one of the above operators, is the function represented by the XPath expression:

fn($x, $y) { $x ⊙ $y }

For example, op("+") returns fn($x, $y) { $x + $y }.

A type error is raised if the supplied argument is not one of the supported operators.

The function is useful in contexts where an arity-2 callback function needs to be supplied, and a standard operator meets the requirement.

For example, the XSLT xsl:map instruction has an on-duplicates attribute that expects such a function. Specifying on-duplicates="op(',')" is equivalent to specifying on-duplicates="fn($x, $y) { $x, $y }

The function is also useful in cases where the choice of operator to apply is made dynamically.

Some operators (such as and, or, and otherwise) have custom error handling semantics, with the effect that evaluating one of the operands cannot cause an error unless the other operand has a particular value (see ). Although implementations are free to make optimizations, it should be assumed that a function call such as op('and')(X, Y) will have the normal semantics of a dynamic function call, where the arguments are evaluated in any order, and a failure evaluating any argument may cause the function call as a whole to fail.

 for-each-pair(21 to 25, 1 to 5, op("+")) 22, 24, 26, 28, 30 for-each-pair(21 to 25, 1 to 5, op("-")) 20, 20, 20, 20, 20

New in 4.0

 deterministic context-independent focus-independent

Returns a record containing information about the type annotation of an atomic item.

Given an atomic item, the function returns a schema-type-record containing information about the atomic type represented by its .

The result will always have ?is-simple = true() and ?variety = "atomic". In a non-schema-aware environment the type will always be a built-in atomic type in the xs namespace: see . Where a schema is in use, however, the result may be an atomic type defined in the schema, which may be an anonymous type.

Note that under the function coercion rules, it is possible to supply a node as the argument, which will then be atomized. In simple cases the type annotation on the atomized value will be the same as the type annotation on the node. But this is not always true: for example the type annotation on the node might be a complex type with simple content, while the type annotation on its atomized value is the corresponding simple content type. To get the type annotation on the node, use the function fn:node-type-annotation.

This function should not be used as a substitute for an instance of test. The precise type annotation of the result of an expression is not always predictable, because processors are free to deliver a more specific type than is mandated by the specification. For example, if $n is of type xs:positiveInteger, then the result of abs($n) is guaranteed to be an instance of xs:integer, but an implementation might reasonably return the supplied value unchanged: that is, a value whose actual type annotation is xs:positiveInteger. Similarly the type annotation of the value returned by position() might be xs:long rather than xs:integer.

Implementations should, however, refrain from exposing types that are purely internal. For example, an implementation might have an optimized internal representation for strings consisting entirely of ASCII characters, or for single-character strings; if this is the case then the type annotation returned by this function should be a user-visible supertype such as xs:string.

 atomic-type-annotation(23) ? name #xs:integer let $x := 23, $y := 93.7 return atomic-type-annotation($x) ? matches($y) false() atomic-type-annotation(xs:numeric('23.2')) ? name #xs:double

New in 4.0

 deterministic context-independent focus-independent

Returns a record containing information about the type annotation of an element or attribute node.

Given an element or attribute node, the function returns a schema-type-record containing information about the schema type represented by its .

For an element that has not been schema-validated, the type annotation is always xs:untyped.

For an attribute that has not been schema-validated, the type annotation is always xs:untypedAtomic.

The type annotation of an attribute node is always a simple type; the type annotation of an element node may be simple or complex.

 ")/* return node-type-annotation($e) ? name]]> #xs:untyped ")//@a return node-type-annotation($a) ? name]]> #xs:untypedAtomic #fn:arrayType #fn:numberType, #fn:finiteNumberType, #xs:double

New in 4.0

 deterministic context-dependent focus-independent

Returns a record containing information about a named schema type in the static context.

If the static context (specifically, the in-scope schema types) includes a schema type whose name matches $name, the function returns a schema-type-record containing information about that schema type. If not, it returns the empty sequence.

 schema-type( #xs:integer ) ? name #xs:integer schema-type( #xs:long ) ? primitive-type() ? name #xs:decimal schema-type( #xs:positiveInteger ) ? base-type() ? name #xs:nonNegativeInteger schema-type( #xs:integer ) ? matches(23) true() schema-type( #xs:numeric ) ? variety "union" schema-type( #xs:numeric ) ? members() ? name #xs:double, #xs:float, #xs:decimal

New in 4.0

 deterministic context-independent focus-independent

Determines whether two atomic items are equal, under the rules used for comparing keys in a map.

The function fn:atomic-equal is used to compare two atomic items for equality. This function has the following properties (which do not all apply to the eq operator):

Any two atomic items can be compared, regardless of their type.

No dynamic error is ever raised (the result is either true or false).

The result of the comparison never depends on the static or dynamic context.

Every value (including NaN) is equal to itself.

The comparison is symmetric: if A equals B, then B equals A.

The comparison is transitive: if A equals B and B equals C, then A equals C.

The function returns true if and only if one of the following conditions is true:

All of the following conditions are true:

$value1 is an instance of xs:string, xs:anyURI, or xs:untypedAtomic

$value2 is an instance of xs:string, xs:anyURI, or xs:untypedAtomic

fn:codepoint-equal($value1, $value2)

Strings are compared without any dependency on collations.

All of the following conditions are true:

$value1 is an instance of xs:decimal, xs:double, or xs:float

$value2 is an instance of xs:decimal, xs:double, or xs:float

fn:compare($value1, $value2) returns zero.

NaN is equal to NaN, INF is equal to INF, -INF is equal to -INF, positive zero equals negative zero. This applies both to xs:double amd xs:float values, including comparisons across these two types.

Ordinary values (numeric values other than the special values mentioned above) are compared according to their mathematical magnitude. Every instance of xs:double, xs:float, and xs:decimal can be represented exactly as a decimal number provided enough digits are available both before and after the decimal point. This comparison is therefore transitive.

All of the following conditions are true:

One of the following conditions is true:

$value1 and $value2 are both instances of xs:date.

$value1 and $value2 are both instances of xs:time.

$value1 and $value2 are both instances of xs:dateTime.

$value1 and $value2 are both instances of xs:gYear.

$value1 and $value2 are both instances of xs:gYearMonth.

$value1 and $value2 are both instances of xs:gMonth.

$value1 and $value2 are both instances of xs:gMonthDay.

$value1 and $value2 are both instances of xs:gDay.

One of the following conditions is true:

Both $value1 and $value2 have a timezone

Neither $value1 nor $value2 has a timezone

fn:compare($value1, $value2) returns zero.

Values having a timezone are never equal to values without one. The implicit timezone is not used.

All of the following conditions are true:

$value1 is an instance of xs:hexBinary or xs:base64Binary

$value2 is an instance of xs:hexBinary or xs:base64Binary

fn:compare($value1, $value2) returns zero.

All of the following conditions are true:

One of the following conditions is true:

$value1 and $value2 are both instances of xs:boolean.

$value1 and $value2 are both instances of xs:QName.

$value1 and $value2 are both instances of xs:NOTATION.

$value1 and $value2 are both instances of xs:duration.

fn:compare($value1, $value2) returns zero.

The internal function op:same-key was introduced in an earlier version of this specification for comparing keys within a map. In this version of the specification, the functionality is unchanged, but the function is exposed so that it is available directly to applications.

The function is used to assess whether two atomic items are considered to be duplicates when used as keys in a map. A map cannot contain two separate entries whose keys are the same as defined by this function. The function is also used when matching keys in functions such as map:get and map:remove.

The rules for comparing keys in a map are chosen to ensure that the comparison is:

Context-free: there is no dependency on the static or dynamic context

Error-free: any two atomic items can be compared, and the result is either true or false, never an error

Transitive: if A is the same key as B, and B is the same key as C, then A is the same key as C.

Two atomic items may be distinguishable even though they are equal under this comparison. For example: they may have different type annotations; dates and times may have different timezones; xs:QName values may have different prefixes.

Unlike previous versions of this specification, xs:hexBinary and xs:base64Binary values are mutually comparable. This decision affects backwards compatibility: it is no longer possible to construct certain maps that could be validly constructed using earlier versions of the specification. This may also cause problems passing data from a 3.1 processor to a 4.0 processor.

As always, any algorithm that delivers the right result is acceptable. For example, when testing whether an xs:double value D is the same key as an xs:decimal value that has N significant digits, it is not necessary to know all the digits in the decimal expansion of D to establish the result: computing the first N+1 significant digits (or indeed, simply knowing that there are more than N significant digits) is sufficient.

 atomic-equal("a", "a") true() atomic-equal("a", "A") false() atomic-equal("a", xs:untypedAtomic("a")) true() atomic-equal( "https://www.w3.org/", xs:anyURI("https://www.w3.org/") ) true() atomic-equal(3, 3) true() atomic-equal(3, 3e0) true() atomic-equal(3.1, 3.1e0) false() atomic-equal(xs:double('NaN'), xs:float('NaN')) true() atomic-equal(12, "12") false() atomic-equal(xs:time('16:00:00Z'), xs:time('17:00:00+01:00')) true() atomic-equal(xs:time('16:00:00Z'), xs:time('16:00:00')) false() atomic-equal(xs:duration('PT1H'), xs:duration('PT60M')) true() atomic-equal(xs:duration('PT0S'), xs:duration('P0Y')) true() atomic-equal(xs:duration('P30D'), xs:duration('P1M')) false() atomic-equal(#Q{http://example.com}name, #Q{http://example.com}prefix:name) true() atomic-equal(xs:hexBinary(""), xs:base64Binary("")) true()

New in 4.0. The function replaces the internal op:same-key function in 3.1

Atomic items of types xs:hexBinary and xs:base64Binary are now mutually comparable. In rare cases, where an application uses both types and assumes they are distinct, this can represent a backwards incompatibility.

 deterministic context-independent focus-independent

Returns a map that combines the entries from a number of existing maps.

The function map:merge returns a map that is formed by combining the contents of the maps supplied in the $maps argument.

Informally, the supplied maps are combined as follows:

There is one entry in the returned map for each distinct key present in the union of the input maps, where two keys are distinct if they are not the same key. The order of the input maps, and of the entries within these input maps, is retained in the of the result map.

If there are duplicate keys, that is, if two or more maps contain entries having the same key, then the relevant entries are combined in a way that is controlled by the supplied $options.

The $options argument takes the same values (with the same meanings) as the map:build function, except that the default is different: for map:merge, the default for duplicate keys is use-first.

The difference is for backwards compatibility reasons.

With the default options, when duplicate entries occur:

There will be a single entry in the result corresponding to a set of duplicate entries in the input.

The value of that entry will be taken from the first of the duplicates.

The position of that entry in the of the result map will correspond to the position of the first of the duplicates.

The key of the combined entry will correspond to the key of one of the duplicates: it is which one is chosen. (Keys may be duplicates even though they differ: for example, they may have different type annotations, or they may be xs:dateTime values in different timezones.)

An error is raised if the value of $options indicates that duplicates are to be rejected, and a duplicate key is encountered.

An error is raised 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.

If the input is the empty sequence, the result is the empty map.

If the input is a sequence of length one, the result map is indistinguishable from the input map.

There is no requirement that the supplied input maps should have the same or compatible types. The type of a map (for example map(xs:integer, xs:string)) is descriptive of the entries it currently contains, but is not a constraint on how the map may be combined with other maps.

The XSLT 3.0 recommendation included a specification of this function that incorrectly used the option value { 'duplicates': 'unspecified' } in place of { 'duplicates': 'use-any' }. XSLT implementations wishing to preserve backwards compatibility may choose to retain support for this setting.

 map:merge(()) {} Returns the empty map map:merge(( map:entry(0, "no"), map:entry(1, "yes") )) { 0: "no", 1: "yes" } Returns a map with two entries map:merge(({ "red": 0 }, { "green": 1}, { "blue": 2 })) => map:keys() "red", "green", "blue" Note the order of the result. map:merge( ($week, { 7: "Unbekannt" }) ) { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Samstag", 7: "Unbekannt" } The value of the existing map is unchanged; the returned map contains all the entries from $week, supplemented with an additional entry. map:merge( ($week, { 6: "Sonnabend" }), { "duplicates": "use-last" } ) { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Sonnabend" } The value of the existing map is unchanged; the returned map contains all the entries from $week, with one entry replaced by a new entry. Both input maps contain an entry with the key 6; the one used in the result is the one that comes last in the input sequence. map:merge( ($week, { 6: "Sonnabend" }), { "duplicates": "use-first" } ) { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Samstag" } The value of the existing map is unchanged; the returned map contains all the entries from $week, with one entry replaced by a new entry. Both input maps contain an entry with the key 6; the one used in the result is the one that comes first in the input sequence. map:merge( ($week, { 6: "Sonnabend" }), { "duplicates": "combine" } ) { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: ("Samstag", "Sonnabend") } The value of the existing map is unchanged; the returned map contains all the entries from $week, with one entry replaced by a new entry. Both input maps contain an entry with the key 6; the entry that appears in the result is the sequence concatenation of the entries in the input maps, retaining order. map:merge( ({ "oxygen": 0.22, "hydrogen": 0.68, "nitrogen": 0.1 }, { "oxygen": 0.24, "hydrogen": 0.70, "nitrogen": 0.06 }), { "duplicates": fn($a, $b) { max(($a, $b)) } }) { "oxygen": 0.24, "hydrogen": 0.70, "nitrogen": 0.1 } The result map holds, for each distinct key, the maximum of the values for that key in the input.

For consistency with the new function map:build, the handling of duplicates may now be controlled by supplying a user-defined callback function as an alternative to the fixed values for the earlier duplicates option.

 deterministic context-independent focus-independent

Returns a sequence containing all the keys present in a map.

Informally, the function map:keys takes any map as its $map argument and returns the keys that are present in the map as a sequence of atomic items, in entry order.

 map:for-each($map, fn($key, $value) { $key })

The number of items in the result will be the same as the number of entries in the map, and the result sequence will contain no duplicate values.

 map:keys({ 1: "yes", 0: "no" }) (1, 0) ({ "red": 0}, { "blue": 1}, { "green": 2 }) => map:merge() => map:keys() ("red", "blue", "green") deterministic context-independent focus-independent

Returns a sequence containing all the values present in a map, in order.

The function map:items takes any map as its $map argument and returns the values that are present in the map as a sequence, in entry order.

The effect of the function is equivalent to $map?*.

 map:for-each($map, fn($key, $value) { $value }) map:items({ 1: "yes", 2: "no" }) ("yes", "no") map:items({ 1: ("red", "green"), 2: ("blue", "yellow"), 3: () }) ("red", "green", "blue", "yellow")

New in 4.0

 deterministic context-independent focus-independent

Returns a sequence containing all the key-value pairs present in a map, each represented as a .

The function map:entries takes any map as its $map argument and returns the key-value pairs that are present in the map as a sequence of single-entry maps, in entry order.

 map:for-each($map, map:entry#2) map:entries( { 1: "yes", 0: "no" } ) ({ 1: "yes" }, { 0: "no" })

New in 4.0

 deterministic context-independent focus-independent

Tests whether a supplied map contains an entry for a given key.

The function map:contains returns true if the map supplied as $map contains an entry with the same key as $key; otherwise it returns false.

 some(map:keys($map), atomic-equal(?, $key)) map:contains($week, 2) true() map:contains($week, 9) false() map:contains({}, "xyz") false() map:contains({ "xyz": 23 }, "xyz") true() map:contains({ "abc": 23, "xyz": () }, "xyz") true() deterministic context-independent focus-independent

Returns true if the supplied map contains no entries.

The function returns true if and only if $map contains no entries, that is, if map:size($map) eq 0.

 map:size($map) eq 0 map:empty({}) true() map:empty({ 1: () }) false()

New in 4.0

 deterministic context-independent focus-independent

Returns the value associated with a supplied key in a given map.

The function map:get attempts to find an entry within the map supplied as $map that has the same key as $key. If there is such an entry, it returns the associated value; if not, it returns the supplied $default value.

 let $entry := dm:iterate-map($map, fn($k, $v) { if (atomic-equal($k, $key)) { map:entry($k, $v) } }) return ( if (exists($entry)) then map:items($entry) else $default )

A return value of () from map:get#2 could indicate that the key is present in the map with an associated value of (), or it could indicate that the key is not present in the map. The two cases can be distinguished by either by calling map:contains to test whether an entry is present, or by using a $default value to return a value known never to appear in the map.

When map:get is applied to a record, the rules are the same as for any other map: there is no error if the supplied $key is not present in the record, instead the value of $default (defaulting to the empty sequence) is returned. When $R is a record, the effect of map:get($R, $K) differs from $R($K).

In other cases (that is, where $map is not a record), invoking map:get($map, $K) returns the same result as $map($K). This means that the expression map:get(map:get(map:get($map, 'employee'), 'name'), 'first') can also be written as $map('employee')('name')('first').

 map:get($week, 4) "Donnerstag" map:get($week, 9) () When the key is not present, the function returns the empty sequence. map:get(map:entry(7,()), 7) () An empty sequence as the result can also signify that the key is present and the associated value is the empty sequence. map:get($week, 7, "n/a") "n/a" The third argument supplies a default value.

A third argument is added, allowing user control of how absent keys should be handled.

 deterministic context-independent focus-independent

Searches the supplied input sequence and any contained maps and arrays for a map entry with the supplied key, and returns the corresponding values.

The function map:find searches the sequence supplied as $input looking for map entries whose key is the same key as $key. The associated value in any such map entry (each being in general a sequence) is returned as a member of the result array.

The search processes the $input sequence using the following recursively defined rules (any equivalent algorithm may be used provided it delivers the same result, respecting those rules that constrain the order of the result):

To process a sequence, process each of its items in order.

To process an item that is an array, process each of its members in order (each member is, in general, a sequence).

To process an item that is a map, then for each key-value entry (K, V) in the map (in entry order) perform both of the following steps, in order:

If K is the same key as $key, then add V as a new member to the end of the result array.

Process V (which is, in general, a sequence).

To process an item that is neither a map nor an array, do nothing. (Such items are ignored).

If $input is the empty sequence, map, or array, or if the requested $key is not found, the result will be a zero-length array.

 map:find($responses, 0) [ 'no', 'non', 'nein' ] map:find($responses, 1) [ 'yes', 'oui', ('ja', 'doch') ] map:find($responses, 2) [] map:find($inventory, "parts") [ [ { "name": "engine", "id": "YW678", "parts": [] } ], [] ]

Enhanced to allow for ordered maps.

 deterministic context-independent focus-independent

Returns a map containing all the contents of the supplied map, but with an additional entry, which replaces any existing entry for the same key.

If $map contains an entry whose key is the same key as $key, the function returns a map in which that entry is replaced (at the same relative position) with a new entry whose value is $value. It is whether the key in the new entry takes its original value or is replaced by the supplied $key. All other entries in the map are unchanged, and retain their relative order.

Otherwise, when $map contains no such entry, the function returns a map containing all entries from the supplied $map (retaining their relative position) followed by a new entry whose key is $key and whose associated value is $value.

 dm:map-put($map, $key, $value)

There is no requirement that the type of $key and $value be consistent with the types of any existing keys and values in the supplied map.

It is possible to force the new entry to go at the end of the sequence by calling map:remove before calling map:put.

It can happen that the supplied $key is the as some existing key present in $map, but nevertheless differs from the existing key in some way: for example, it might have a different type annotation, or it might be an xs:dateTime value in a different timezone. In this situation it is whether the key that appears in the result map is the supplied $key or the existing key.

 map:put($week, 6, "Sonnabend") { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Sonnabend" } map:put($week, -1, "Unbekannt") { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Samstag", -1: "Unbekannt" } parse-json('{ "red": 0, "green": 1, "blue": 2 }') => map:put("yellow", -1) => map:keys() "red", "green", "blue", "yellow" The new entry is added at the end of the list. parse-json('{ "red": 0, "green": 1, "blue": 2 }') => map:put("red", -1) => map:keys() "red", "green", "blue" Changing the value for an existing key does not change the order of the keys.

Enhanced to allow for ordered maps.

It is no longer guaranteed that the new key replaces the existing key.

 deterministic context-independent focus-independent

Returns a that represents a single key-value pair.

The function map:entry returns a map which contains a single entry. The key of the entry in the new map is $key, and its associated value is $value.

 map:put({}, $key, $value)

The function map:entry is intended primarily for use in conjunction with the function map:merge. For example, a map containing seven entries may be constructed like this:

The map:merge function can be used to construct a map with a variable number of entries, for example:

 map:entry("M", "Monday") { "M": "Monday" } deterministic context-independent focus-independent

Returns a map containing all the entries from a supplied map, except those having a specified key.

The function map:remove returns a map containing all the entries in $map except for any entry whose key is the same key as an item in $keys.

No failure occurs if an item in $keys does not correspond to any entry in $map; that key value is simply ignored.

The relative position of retained entries in the result map is the same as their relative position in $map.

 map:filter( $map, fn($k, $v) { not(some($keys, atomic-equal($k, ?))) } ) map:remove($week, 4) { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 5: "Freitag", 6: "Samstag" } map:remove($week, 23) { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Samstag" } map:remove($week, (0, 6 to 7)) { 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag" } map:remove($week, ()) { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Samstag" }

Enhanced to allow for ordered maps.

 deterministic context-independent focus-independent

Applies a supplied function to every entry in a map, returning the sequence concatenation of the results.

The function map:for-each takes any map as its $map argument and applies the supplied function to each entry in the map, in entry order; the result is the of the results of these function calls.

For each entry of the map, the function calls $action($key, $value, $pos), where $key and $value are the key and associated value of the entry.

 dm:iterate-map($map, $action, $position) map:for-each( { 1: "yes", 2: "no" }, fn($k, $v) { $k } ) (1, 2) This function call is equivalent to calling map:keys. distinct-values( map:for-each( { 1: "yes", 2: "no" }, fn($k, $v) { $v } ) ) ("yes", "no") map:merge( map:for-each( { "a": 1, "b": 2 }, fn($k, $v) { map:entry($k, $v + 1) } ) ) { "a": 2, "b": 3 } This function call returns a map with the same keys as the input map, with the value of each entry increased by one.

This XQuery example converts the entries in a map to attributes on a newly constructed element node:

{ map:for-each($dimensions, fn($k, $v) { attribute { $k } { $v } }) }]]>

The result is the element <box height="3" width="4" depth="5"/>.

 "1. one: 一", "2. two: 二", "3. three: 三"

Enhanced to allow for ordered maps.

The $action callback function now accepts an optional position argument.

 context-independent focus-independent

Selects entries from a map, returning a new map.

The function map:filter takes any map as its $map argument and applies the supplied function to each entry in the map; the result is a new map containing those entries for which the function returns true. A return value of () from the predicate is treated as false.

For each entry of the map, the function calls $predicate($key, $value, $pos), where $key and $value are the key and associated value of the entry.

The relative order of entries in the returned map is the same as their relative order in $map.

 map:for-each($map, fn($key, $value, $pos) { if ($predicate($key, $value, $pos)) { map:entry($key, $value) } }) => map:merge() map:filter( { 1: "Sunday", 2: "Monday", 3: "Tuesday", 4: "Wednesday", 5: "Thursday", 6: "Friday", 7: "Saturday" }, fn($k, $v) { $k = (1, 7) } ) { 1: "Sunday", 7: "Saturday" } map:filter( { 1: "Sunday", 2: "Monday", 3: "Tuesday", 4: "Wednesday", 5: "Thursday", 6: "Friday", 7: "Saturday" }, fn($k, $v) { $v = ("Saturday", "Sunday") } ) { 1: "Sunday", 7: "Saturday" } { 'one': '一', 'three': '三' }

New in 4.0

The $predicate callback function may return the empty sequence (meaning false).

Enhanced to allow for ordered maps.

The $action callback function now accepts an optional position argument.

 deterministic context-independent focus-independent

Returns a map that typically contains one entry for each item in a supplied input sequence.

Informally, the function processes each item in $input in order. It calls the $key function on that item to obtain a sequence of key values, and the $value function to obtain an associated value. Then, for each key value:

If the key is not already present in the target map, the processor adds a new key-value pair to the map, with that key and that value.

If the key is already present, the processor combines the new value for the key with the existing value; the way they are combined is determined by the duplicates option.

By default, when two duplicate entries occur:

A single combined entry will be present in the result.

This entry will contain the sequence concatenation of the supplied values.

The position of the combined entry in the of the result map will correspond to the position of the first of the duplicates.

The key of the combined entry will correspond to the key of one of the duplicates: it is which one is chosen. (It is possible for two keys to be considered duplicates even if they differ: for example, they may have different type annotations, or they may be xs:dateTime values in different timezones.)

The $options argument can be used to control the way in which duplicate keys are handled. The option parameter conventions apply. The entries that may appear in the $options map are as follows:

Determines the policy for handling duplicate keys: specifically, the action to be taken if two entries in the input sequence have key values K1 and K2 where K1 and K2 are the same key. (enum( "reject", "use-first", "use-last", "use-any", "combine") | fn(item()*, item()*) as item()*)? "combine" Equivalent to supplying a function that raises a dynamic error with error code "FOJS0003". The effect is that duplicate keys result in an error. Equivalent to supplying the function fn($a, $b){ $a }. The effect is that the first of the duplicates is chosen. Equivalent to supplying the function fn($a, $b){ $b }. The effect is that the last of the duplicates is chosen. Equivalent to supplying the function fn($a, $b){ one-of($a, $b) } where one-of chooses either $a or $b in an way. The effect is that it is which of the duplicates is chosen. Equivalent to supplying the function fn($a, $b){ $a, $b } (or equivalently, the function op(",")). The effect is that the result contains the of the values having the same key, retaining order. A function with signature fn(item()*, item()*) as item()*. The function is called for any entry in the input sequence that has the as a previous entry. The first argument is the existing value associated with the key; the second argument is the value associated with the key in the duplicate input entry, and the result is the new value to be associated with the key. The effect is cumulative: for example if there are three values X, Y, and Z associated with the same key, and the supplied function is F, then the result is an entry whose value is X => F(Y) => F(Z). for-each( $input, fn($item, $pos) { for-each($key($item, $pos), fn($k) { map:entry($k, $value($item, $pos)) } )} ) => map:merge($options)

An error is raised if the value of $options indicates that duplicates are to be rejected, and a duplicate key is encountered.

An error is raised 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.

The default function for both $key and $value is the identity function. Although it is permitted to default both, this serves little purpose: usually at least one of these arguments will be supplied.

 map:build((), string#1) {} map:build(1 to 10, fn { . mod 3 }) { 0: (3, 6, 9), 1: (1, 4, 7, 10), 2: (2, 5, 8) } Returns a map with one entry for each distinct value of . mod 3. The function to compute the value is the identity function, and duplicates are combined by sequence concatenation. map:build( 1 to 5, value := format-integer(?, "w") ) { 1: "one", 2: "two", 3: "three", 4: "four", 5: "five" } Returns a map with five entries. The function to compute the key is an identity function, the function to compute the value invokes fn:format-integer. map:build( ("January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"), substring(?, 1, 1) ) { "A": ("April", "August"), "D": ("December"), "F": ("February"), "J": ("January", "June", "July"), "M": ("March", "May"), "N": ("November"), "O": ("October"), "S": ("September") } map:build(1 to 5, { 1: ("eins", "one"), 4: ("vier", "four") }) { "eins": 1, "one": 1, "vier": 4, "four": 4 } map:build( ("apple", "apricot", "banana", "blueberry", "cherry"), substring(?, 1, 1), string-length#1, { "duplicates": op("+") } ) { "a": 12, "b": 15, "c": 6 } Constructs a map where the key is the first character of an input item, and where the corresponding value is the total string-length of the items starting with that character. map:build( ('Wang', 'Liu', 'Zhao'), key := fn($name, $pos) { $name }, value := fn($name, $pos) { $pos } ) { "Wang": 1, "Liu": 2, "Zhao": 3 } Returns an inverted index for the input sequence with the string stored as key and the position stored as value. A Beginner’s Guide to <ix>Java</ix> Learning <ix>XML</ix> Using <ix>XML</ix> with <ix>Java</ix> return map:build($titles/title, fn($title) { $title/ix }) ]]> A Beginner’s Guide to Java, Using <ix>XML</ix> with <ix>Java</ix> ), "XML": ( Learning <ix>XML</ix>, Using <ix>XML</ix> with <ix>Java</ix> ) }]]> map:build(//employee, fn { @ssn }) A map whose keys are employee @ssn values, and whose corresponding values are the employee nodes map:build(//employee, fn { @location }, fn { 1 }, { "duplicates": op("+") }) A map whose keys are employee @location values, and whose corresponding values represent the number of employees at each distinct location. Any employees that lack an @location attribute will be excluded from the result. map:build( //employee, key := fn { @location }, options := { "duplicates": fn($a, $b) { highest(($a, $b), (), fn { xs:decimal(@salary) }) } } ) A map whose keys are employee @location values, and whose corresponding values contain the employee node for the highest-paid employee at each distinct location map:build(//*, generate-id#1) A map allowing efficient access to every element in a document by means of its fn:generate-id value. let $tree := parse-json('{ "type": "package", "name": "org", "content": [ { "type": "package", "name": "xml", "content": [ { "type": "package", "name": "sax", "content": [ { "type": "class", "name": "Attributes"}, { "type": "class", "name": "ContentHandler"}, { "type": "class", "name": "XMLReader"} ] }] }] }') return map:build($tree/descendant-or-self::type, fn{(ancestor-or-self::jnode(*, map(*)))?name => string-join(".")}, fn{`{.} {(..)?name}`}) { "org":"package org", "org.xml":"package xml", "org.xml.sax":"package sax", "org.xml.sax.Attributes": "class Attributes", "org.xml.sax.ContentHandler": "class ContentHandler", "org.xml.sax.XMLReader": "class XMLReader" } Constructs a map allowing efficient access to values in a recursive JSON structure using hierarchic paths

New in 4.0

 deterministic context-independent focus-independent

Returns the number of entries in the supplied map.

The function map:size takes any map as its $map argument and returns the number of entries that are present in the map.

 count(map:entries($map)) map:size({}) 0 map:size({ "true": 1, "false": 0 }) 2 deterministic context-dependent focus-independent

Constructs a collation URI with requested properties.

The function is supplied with a map defining the properties required of the collation, and returns a collation URI with these properties.

Specifically, it returns a string in the form of a URI with the scheme and path http://www.w3.org/2013/collation/UCA followed by an optional query part. The query part is absent if options is empty. Otherwise it consists of a question mark followed by a sequence of one or more semicolon-separated parameters. Each parameter is a keyword-value pair, the keyword and value being separated by an equals sign. There is one keyword-value pair for each entry in the options map: the keyword is the same as the string value of the key in the map, and the value is the string value of the corresponding value, except where the value is of type xs:boolean, in which case true and false are translated to yes and no.

The function does not check whether the implementation actually recognizes the resulting collation URI: that can be achieved using the fn:collation-available function.

The properties available are as defined for the Unicode Collation Algorithm (see ). Additional properties may be specified as described in the rules for UCA collation URIs.

The option parameter conventions apply, except as regards the handling of options not defined in this specification. Specifically:

If the option key is of type xs:string, xs:anyURI, or xs:untypedAtomic then it is converted to a string, and produces a URI query parameter which is handled as described in .

If the option key is of any other type then the function fails with a type error .

The following options are defined:

See . xs:boolean true See . xs:language default-language() See . xs:string () See . enum("primary", "secondary", "tertiary", "quaternary", "identical", "1", "2", "3", "4", "5") () See . enum("space", "punct", "symbol", "currency") "punct" See . enum("non-ignorable", "shifted", "blanked", "currency") "non-ignorable" See . xs:boolean false See . xs:boolean false See . xs:boolean false See . enum("upper","lower") "lower" See . xs:boolean false See . xs:string ""

A type error is raised if options includes an entry whose key is not of type xs:string, xs:anyURI, or xs:untypedAtomic, or whose corresponding value is not castable to xs:string.

 collation({}) "http://www.w3.org/2013/collation/UCA" collation({ 'lang': 'de' }) "http://www.w3.org/2013/collation/UCA?lang=de" collation({ 'lang': 'de', 'strength': 'primary' }) "http://www.w3.org/2013/collation/UCA?lang=de;strength=primary" http://www.w3.org/2013/collation/UCA?lang=de;strength=primary http://www.w3.org/2013/collation/UCA?strength=primary;lang=de; The order of query parameters may vary. collation({ 'lang': default-language() }) A collation suitable for the default language in the dynamic context.

New in 4.0

 deterministic context-dependent focus-independent

Asks whether a collation URI is recognized by the implementation.

The supplied argument is a candidate collation URI.

The function returns true if and only if the implementation recognizes the candidate collation URI.

If the candidate collation is a UCA collation specifying fallback=yes, then this function will always return true: implementations are required to recognize such a collation and use fallback behavior if there is no direct equivalent available.

 collation-available("http://www.w3.org/2013/collation/UCA?lang=de") true() collation({ 'lang': 'de' }) => collation-available() true()

New in 4.0

 deterministic context-dependent focus-independent

Given a string value and a collation, generates an internal value called a collation key, with the property that the matching and ordering of collation keys reflects the matching and ordering of strings under the specified collation.

Calling the one-argument version of this function is equivalent to calling the two-argument version supplying the default collation as the second argument.

The function returns an implementation-dependent value with the property that, for any two strings $K1 and $K2:

collation-key($K1, $C) eq collation-key($K2, $C) if and only if compare($K1, $K2, $C) eq 0

collation-key($K1, $C) lt collation-key($K2, $C) if and only if compare($K1, $K2, $C) lt 0

The collation used by this function is determined according to the rules in . Collation keys are defined as xs:base64Binary values to ensure unambiguous and context-free comparison semantics.

An implementation is free to generate a collation key in any convenient way provided that it always generates the same collation key for two strings that are equal under the collation, and different collation keys for strings that are not equal. This holds only within a single execution scope; an implementation is under no obligation to generate the same collation keys during a subsequent unrelated query or transformation.

It is possible to define collations that do not have the ability to generate collation keys. Supplying such a collation will cause the function to fail. The ability to generate collation keys is an implementation-defined property of the collation.

An error is raised if the specified collation does not support the generation of collation keys.

The function is provided primarily for use with maps. If a map is required where codepoint equality is inappropriate for comparing keys, then a common technique is to normalize the key so that equality matching becomes feasible. There are many ways keys can be normalized, for example by use of functions such as fn:upper-case, fn:lower-case, fn:normalize-space, or fn:normalize-unicode, but this function provides a way of normalizing them according to the rules of a specified collation. For example, if the collation ignores accents, then the function will generate the same collation key for two input strings that differ only in their use of accents.

The result of the function is defined to be an xs:base64Binary value. Binary values are chosen because they have unambiguous and context-free comparison semantics, because the value space is unbounded, and because the ordering rules are such that between any two values in the ordered value space, an arbitrary number of further values can be interpolated. The choice between xs:base64Binary and xs:hexBinary is arbitrary; the only operation that behaves differently between the two binary data types is conversion to/from a string, and this operation is not one that is normally required for effective use of collation keys.

For collations based on the Unicode Collation Algorithm, an algorithm for computing collation keys is provided in . Implementations are not required to use this algorithm.

The fact that collation keys are ordered can be exploited in XQuery, whose order by clause does not allow the collation to be selected dynamically. This restriction can be circumvented by rewriting the clause order by $e/@key collation "URI" as order by fn:collation-key($e/@key, $collation), where $collation allows the collation to be chosen dynamically.

Note that xs:base64Binary becomes an ordered type in XPath 3.1, making binary collation keys possible.

The fn:collation-available can be used to ask whether a particular collation is capable of delivering collation keys.

 map:merge( ({ collation-key("A", $C): 1 }, { collation-key("a", $C): 2 }), { "duplicates": "use-last" } )(collation-key("A", $C)) 2 Given that the keys of the two entries are equal under the rules of the chosen collation, only one of the entries can appear in the result; the one that is chosen is the one from the last map in the input sequence. let $M := { collation-key("A", $C): 1, collation-key("B", $C): 2 } return $M(collation-key("a", $C)) 1 The strings "A" and "a" have the same collation key under this collation.

As the above examples illustrate, it is important that when the collation-key function is used to add entries to a map, then it must also be used when retrieving entries from the map. This process can be made less error-prone by encapsulating the map within a function: fn($k) { $M(collation-key($k, $collation) }.

 nondeterministic context-dependent focus-independent

Parses a string supplied in the form of a JSON text, returning the results in the form of an XML document node.

If the second argument is omitted or the empty sequence, the result is the same as calling the two-argument form with the empty map as the value of the $options argument.

The first argument is a JSON text as defined in , in the form of a string. The function parses this string to return an XDM node.

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

The $options argument can be used to control the way in which the parsing takes place. The option parameter conventions apply.

The entries that may appear in the $options map are as follows:

Determines whether deviations from the syntax of RFC8259 are permitted. xs:boolean false The input must consist of an optional byte order mark (which is ignored) followed by a string that conforms to the grammar of JSON-text in . An error must be raised (see below) if the input does not conform to the grammar. The input may contain deviations from the grammar of , which are handled in an implementation-defined way. (Note: some popular extensions include allowing quotes on keys to be omitted, allowing a comma to appear after the last item in an array, allowing leading zeroes in numbers, and allowing control characters such as tab and newline to be present in unescaped form.) Since the extensions accepted are implementation-defined, an error may be raised (see below) if the input does not conform to the grammar. Determines the policy for handling duplicate keys in a JSON object. To determine whether keys are duplicates, they are compared using the Unicode codepoint collation, after expanding escape sequences, unless the escape option is set to true, in which case keys are compared in escaped form. xs:string If validate is true then reject, otherwise retain. An error is raised if duplicate keys are encountered. If duplicate keys are present in a JSON object, all but the first of a set of duplicates are ignored. If duplicate keys are present in a JSON object, the XML result of the function will also contain duplicates (making it invalid against the schema). This value is therefore incompatible with the option validate=true Determines whether the generated XML tree is schema-validated. xs:boolean Implementation-defined. Indicates that the resulting XDM instance must be typed; that is, the element and attribute nodes must carry the type annotations that result from validation against the schema given at , or against an implementation-defined schema if the liberal option has the value true. Indicates that the resulting XDM instance must be untyped. Determines whether special characters are represented in the XDM output in backslash-escaped form. xs:boolean false All characters in the input that are valid in the version of XML supported by the implementation, whether or not they are represented in the input by means of an escape sequence, are represented as unescaped characters in the result. Any characters or codepoints that are not valid XML characters (for example, unpaired surrogates) are passed to the fallback function as described below; in the absence of a fallback function, they are replaced by the character U+FFFD. The attributes escaped and escaped-key will not be present in the XDM output. JSON escape sequences are used in the result to represent special characters in the JSON input, as defined below, whether or not they were represented using JSON escape sequences in the input. The characters that are considered “special” for this purpose are:

all codepoints in the range U+0000 to U+001F or U+007F to U+009F;

all codepoints that do not represent characters that are valid in the version of XML supported by the processor, including codepoints representing unpaired surrogates;

the backslash character itself (U+005C).

 Such characters are represented using a two-character escape sequence where available (for example, \t), or a six-character escape sequence otherwise (for example \uDEAD). Characters other than these will not be escaped in the result, even if they were escaped in the input. In the result:

Any string element whose string value contains a backslash character must have the attribute value escaped="true".

Any element that contains a key attribute whose string value contains a backslash character must have the attribute escaped-key="true".

The values of the escaped and escaped-key attributes are immaterial when there is no backslash present, and it is never necessary to include either attribute when its value is false.

 Provides a function which is called when the input contains an escape sequence that represents a character that is not valid in the version of XML supported by the implementation. It is an error to supply the fallback option if the escape option is present with the value true. (fn($escape as xs:string) as xs:anyAtomicType)? fn { char(0xFFFD) } The function is called when the JSON input contains an escape sequence that is valid according to the JSON grammar, but which does not represent a character that is valid in the version of XML supported by the processor. In the case of surrogates, it is called once for any six-character escape sequence that is not properly paired with another surrogate. The untyped atomic item supplied as the argument will always be a two- or six-character escape sequence, starting with a backslash, that conforms to the rules in the JSON grammar (as extended by the implementation if liberal:true() is specified): for example \b or \uFFFF or \uDEAD.

By default, the escape sequence is replaced with the Unicode REPLACEMENT CHARACTER. The function is not called for an escape sequence that is invalid against the grammar (for example \x0A). The string, which results from invoking fn:string on the result of the function, is inserted into the result in place of the invalid character. The function also has the option of raising a dynamic error by calling fn:error.

The various structures that can occur in JSON are transformed recursively to XDM values according to the rules given in .

The function returns a document node, whose only child is the element node representing the outermost construct in the JSON text.

The function is nondeterministic with respect to node identity: that is, if the function is called twice with the same arguments, it is implementation-dependent whether the same node is returned on both occasions.

The base URI of the returned document node is taken from the executable base URI of the function call.

The choice of namespace prefix (or absence of a prefix) in the names of constructed nodes is implementation-dependent.

The XDM tree returned by the function does not contain any unnecessary (albeit valid) nodes such as whitespace text nodes, comments, or processing instructions. It does not include any whitespace in the value of number or boolean element nodes, nor in the value of escaped or escaped-key attribute nodes.

If the result is typed, every element named string will have an attribute named escaped whose value is either true or false, and every element having an attribute named key will also have an attribute named escaped-key whose value is either true or false.

If the result is untyped, the attributes escaped and escaped-key will either be present with the value true, or will be absent. They will never be present with the value false.

An error is raised if the value of $value does not conform to the JSON grammar as defined by , unless the option "liberal":true() is present and the processor chooses to accept the deviation.

An error is raised if the value of the validate option is true and the processor does not support schema validation or typed data.

An error is raised 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.

To read a JSON file, this function can be used in conjunction with the fn:unparsed-text function.

Many JSON implementations allow commas to be used after the last item in an object or array, although the specification does not permit it. The option spec="liberal" is provided to allow such deviations from the specification to be accepted. Some JSON implementations also allow constructors such as new Date("2000-12-13") to appear as values: specifying spec="liberal" allows such extensions to be accepted, but does not guarantee it. If such extensions are accepted, the resulting value is implementation-defined, and will not necessarily conform to the schema at .

If the input starts with a byte order mark, this function ignores it. The byte order mark may have been added to the data stream in order to facilitate decoding of an octet stream to a character string, but since this function takes a character string as input, the byte order mark serves no useful purpose.

The possibility of the input containing characters that are not valid in XML (for example, unpaired surrogates) arises only when such characters are expressed using JSON escape sequences. This is the only possibility because the input to the function is an instance of xs:string, which by definition can contain only those characters that are valid in XML.

 json-to-xml( '{ "x": 1, "y": [ 3, 4, 5 ] }', { "validate": false() } ) 1 3 4 5 ]]> json-to-xml( '"abcd"', { 'liberal': false() } ) abcd]]> json-to-xml( '{ "x": "\\", "y": "\u0025" }', { "validate": false() } ) \ % ]]> json-to-xml( '{ "x": "\\", "y": "\u0025" }', { 'escape': true(), "validate": false() } ) \\ % ]]> But see the detailed rules for alternative values of the escaped attribute on the second string element.

The following example illustrates use of the fallback function to handle characters that are invalid in XML.

 deterministic context-independent focus-independent

Converts an XML tree, whose format corresponds to the XML representation of JSON defined in this specification, into a string conforming to the JSON grammar.

The first argument $node is a node; the subtree rooted at this node will typically be the XML representation of a JSON document as defined in .

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

The $options argument can be used to control the way in which the conversion takes place. The option parameter conventions apply.

The entries that may appear in the $options map are as follows:

Determines whether the character U+002F should be escaped as \/. By default the character is escaped, but this is only necessary when the resulting JSON is embedded in HTML. xs:boolean true The character U+002F is output as is, without escaping. The character U+002F is escaped by preceding it with U+005C. Determines whether additional whitespace should be added to the output to improve readability. xs:boolean false The processor must not insert any insignificant whitespace between JSON tokens. The processor may insert whitespace between JSON tokens in order to improve readability. The specification imposes no constraints on how this is done.

The node supplied as $node must be one of the following:

An element node whose name matches the name of a global element declaration in the schema given in (“the schema”) and that is valid as defined below:

If the type annotation of the element matches the type of the relevant element declaration in the schema (indicating that the element has been validated against the schema), then the element is considered valid.

Otherwise, the processor may attempt to validate the element against the schema, in which case it is treated as valid if and only if the outcome of validation is valid.

Otherwise (if the processor does not attempt validation using the schema), the processor must ensure that the content of the element, after stripping all attributes (at any depth) in namespaces other than http://www.w3.org/2005/xpath-functions, is such that validation against the schema would have an outcome of valid.

The process described here is not precisely equivalent to schema validation. For example, schema validation will fail if there is an invalid xsi:type or xsi:nil attribute, whereas this process will ignore such attributes.

An element node E having a key attribute and/or an escaped-key attribute provided that E would satisfy one of the above conditions if the key and/or escaped-key attributes were removed.

A document node having exactly one element child and no text node children, where the element child satisfies one of the conditions above.

Furthermore, $node must satisfy the following constraint (which cannot be conveniently expressed in the schema). Every element M that is a descendant-or-self of $node and has local name map and namespace URI http://www.w3.org/2005/xpath-functions must satisfy the following rule: there must not be two distinct children of M (say C/1 and C/2) such that the normalized key of C/1 is equal to the normalized key of C/2. The normalized key of an element C is as follows:

If C has the attribute value escaped-key="true", then the value of the key attribute of C, with all JSON escape sequences replaced by the corresponding Unicode characters according to the JSON escaping rules.

Otherwise (the escaped-key attribute of C is absent or set to false), the value of the key attribute of C.

Nodes in the input tree are handled by applying the following rules, recursively. In these rules the phrase “an element named N” means “an element node whose local name is N and whose namespace URI is http://www.w3.org/2005/xpath-functions”.

A document node having a single element node child is processed by processing that child.

An element named null results in the output null.

An element $E named boolean results in the output true or false depending on the result of xs:boolean(fn:string($E)).

An element $E named number is processed as follows.

The input is required to conform to the XSD rules defining a valid instance of xs:double (excluding infinity and NaN), while the output is required to conform to the JSON rules defining a valid JSON number. These rules are slightly different.

Specifically, the XSD rules require the value (after removing leading and trailing whitespace) to match the regular expression:

(\+|-)?([0-9]+(\.[0-9]*)?|\.[0-9]+)([Ee](\+|-)?[0-9]+)?

while the JSON rules require:

-?(0|[1-9][0-9]*)(\.[0-9]+)?([Ee](\+|-)?[0-9]+)?

If the input value does not match the required JSON format, it must therefore be adjusted by applying the following steps:

Remove leading and trailing whitespace.

Remove any leading plus sign.

Remove any leading zero digits in the integer part, while ensuring that at least one digit remains.

If there is a decimal point that is not preceded by a digit, add a zero digit before the decimal point.

If there is a decimal point that is not followed by a digit, add a zero digit after the decimal point.

The output uses exponential notation if and only if the input uses exponential notation.

The rules have changed since version 3.1 of this specification. In previous versions, the supplied number was cast to an xs:double, and then serialized using the rules of the fn:string function. This resulted in JSON numbers using exponential notation for values outside the range 1e-6 to 1e6, and led to a loss of precision for 64-bit integer values.

An element named string results in the output of the string value of the element, enclosed in quotation marks, with any special characters in the string escaped as described below.

An element named array results in the output of the children of the array element, each processed by applying these rules recursively: the items in the resulting list are enclosed between square brackets, and separated by commas.

An element named map results in the output of a sequence of map entries corresponding to the children of the map element, enclosed between curly braces and separated by commas. Each entry comprises the value of the key attribute of the child element, enclosed in quotation marks and escaped as described below, followed by a colon, followed by the result of processing the child element by applying these rules recursively. The order of properties in the output JSON representation retains the order of the children of the map element.

Comments, processing instructions, and whitespace text node children of map and array are ignored.

Strings are escaped as follows:

If the attribute escaped="true" is present for a string value, or escaped-key="true" for a key value, then:

any valid JSON escape sequence present in the string is copied unchanged to the output;

any invalid JSON escape sequence results in a dynamic error ;

any unescaped occurrence of U+0022, U+0008, U+000C, U+000A, U+000D, U+0009, or (subject to the escape-solidus option) U+002F is replaced by \", \b, \f, \n, \r, \t, or \/ respectively;

any other codepoint in the range 1-31 or 127-159 is replaced by an escape in the form \uHHHH where HHHH is the upper-case hexadecimal representation of the codepoint value.

Otherwise (that is, in the absence of the attribute escaped="true" for a string value, or escaped-key="true" for a key value):

any occurrence of backslash is replaced by \\

any occurrence of U+0022, U+0008, U+000C, U+000A, U+000D, or U+0009 is replaced by \", \b, \f, \n, \r, or \t respectively;

any other codepoint in the range 1-31 or 127-159 is replaced by an escape in the form \uHHHH where HHHH is the upper-case hexadecimal representation of the codepoint value.

A dynamic error is raised 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.

A dynamic error is raised if the value of $node is not a document or element node or is not valid according to the schema for the XML representation of JSON, or if a map element has two children whose normalized key values are the same.

A dynamic error is raised if the value of $node includes a string labeled with escaped="true", or a key labeled with escaped-key="true", where the content of the string or key contains an invalid JSON escape sequence: specifically, where it contains a backslash (\) that is not followed by one of the characters ", \, /, b, f, n, r, t, or u, or where it contains the characters \u not followed by four hexadecimal digits (that is [0-9A-Fa-f]{4}).

The rule requiring schema validity has a number of consequences, including the following:

The input cannot contain no-namespace attributes, or attributes in the namespace http://www.w3.org/2005/xpath-functions, except where explicitly allowed by the schema. Attributes in other namespaces, however, are ignored.

Nodes that do not affect schema validity, such as comments, processing instructions, namespace nodes, and whitespace text node children of map and array, are ignored.

Numeric values are restricted to those that are valid in JSON: the schema disallows positive and negative infinity and NaN.

Duplicate key values are not permitted. Most cases of duplicate keys are prevented by the rules in the schema; additional cases (where the keys are equal only after expanding JSON escape sequences) are prevented by the prose rules of this function. For example, the key values \n and \u000A are treated as duplicates even though the rules in the schema do not treat them as such.

The rule allowing the top-level element to have a key attribute (which is ignored) allows any element in the output of the fn:json-to-xml function to be processed: for example, it is possible to take a JSON document, convert it to XML, select a subtree based on the value of a key attribute, and then convert this subtree back to JSON, perhaps after a transformation. The rule means that an element with the appropriate name will be accepted if it has been validated against one of the types mapWithinMapType, arrayWithinMapType, stringWithinMapType, numberWithinMapType, booleanWithinMapType, or nullWithinMapType.

The input 1is1]]> produces the result [ 1, "is", true ].

The input 12]]> produces the result { "Sunday": 1, "Monday": 2 }.

The input 1017e20005]]> produces the result [ 10, 17e2, 5 ].

An option has been added to suppress the escaping of the solidus (forwards slash) character.

Numbers now retain their original lexical form, except for any changes needed to satisfy JSON syntax rules (for example, stripping leading zero digits).

 deterministic context-independent focus-independent

Analyzes sample data to generate a conversion plan suitable for use by the element-to-map function.

The function takes as input a collection of document and element nodes and analyzes the trees rooted at these nodes to determine a conversion plan for converting elements in these trees to maps, suitable for serialization in JSON format. The conversion plan can be used as-is by supplying it directly to the element-to-map function; alternatively it can be amended before use. The plan can also be serialized to a file (in JSON format) allowing the same plan to be used repeatedly for transforming documents with a similar structure to those in the sample provided.

The rules followed by the function, and the detailed format of the conversion plan, are described in .

The conversion plan is organized by element and attribute name, so its effectiveness depends on the $input collection being homogenous in its structure, and representative of the documents that will subsequently be converted using the element-to-map function.

This function is separate from the element-to-map function for a number of reasons:

The collection of documents that need to be analyzed to establish an effective conversion plan might be much smaller than the set of documents actually being converted.

Conversely, it might be that only a small number of documents need to be converted at a particular time, but the conversion plan used needs to take into account variations that might exist within a larger corpus.

If JSON output is required in a particular format, it might be necessary to fine-tune the automatically generated conversion plan to take account of these requirements.

It might be necessary to devise a conversion plan that can be used to convert individual documents as they arrive over a period of time, and to ensure that the same conversion rules are applied to each document even though documents might exhibit variations in structure.

The conversion plan is human-readable, which can help in understanding why the output of element-to-map is in a particular form.

 34) ]]> { 'a': { 'layout': 'list', 'child': 'b', 'type': () }, 'b': { 'layout': 'simple', 'child': (), 'type': 'integer' } } red, blue)) ]]> { 'a': { 'layout': 'simple-plus', 'child': (), 'type': () }, '@x': { 'type': 'integer' } } H2SO4 ) ]]> { 'Q{http://example.ns}a': { 'layout': 'mixed', 'child': (), 'type': () }, 'Q{http://example.ns}sub': { 'layout': 'simple', 'child': (), 'type': 'integer' } } , )) ]]> { 'a': { 'layout': 'sequence', 'child': (), 'type': () }, 'b': { 'layout': 'empty', 'child': (), 'type': () }, 'c': { 'layout': 'empty', 'child': (), 'type': () } }

New in 4.0

 deterministic context-independent focus-independent

Converts an element node into a map that is suitable for JSON serialization.

Supplying a well-formed document node as the value of the first argument has the same effect as supplying the single element node child of that document node.

This function returns a map derived from the element node supplied in $element. The map is in a form that is suitable for JSON serialization, thus providing a mechanism for conversion of arbitrary XML to JSON.

The map that is returned will always be a ; the key of this entry will be a string representing the element name, and the value of the entry will be a representation of the element's attributes and children.

The entries that may appear in the $options map are as follows. The option parameter conventions apply.

A conversion plan, supplied as a map whose keys represent element and attribute names. The plan might be generated using the function element-to-map-plan, or it might be constructed in some other way. The format of the plan is described in . map( xs:string, ( fn:element-conversion-plan-record | fn:attribute-conversion-plan-record ) ) {} A string that is prepended to any key value in the output that represents an XDM attribute node in the input. The string may be empty. If, after applying the requested prefix (or no prefix) there is a conflict between the names of attributes and child elements, then the requested prefix (or lack thereof) is ignored and the default prefix "@" is used. xs:string "@" For layouts that by default use the key value #content to identify content derived from the children of an input element, this option substitutes a different string in place of #content. If the selected value would result in a generated map having duplicate key values, then as many # characters as are needed to make the key unique are prepended to the requested string. xs:string "#content" Indicates how the names of element and attribute nodes are handled. xs:string "default" Names are output in the form produced by the fn:name function. Names are output in the form produced by the fn:local-name function. Names in a namespace are output in the form "Q{uri}local". Names in no namespace are output using the local name alone. An element name is output as a local name alone if either (a) it is a top-level element and is in no namespace, or (b) it is in the same namespace as its parent element. An attribute name is output as a local name alone if it is in no namespace. All other names are output in the format "Q{uri}local" if in a namespace, or "Q{}local" if in no namespace. "Top-level" here means that the element is one that appears explicitly in the sequence of elements passed in the $elements argument, as distinct from a descendant of such an element.

If $element is the empty sequence, the result is the empty sequence.

The principles for conversion from elements to maps are described in , and the rules for selecting an element layout for each element are given in .

In general, every descendant element within the tree rooted at the supplied $element maps to a key-value pair in which the key represents the element name, and the corresponding value represents the attributes and children of the element. This key-value pair will be added to the content representing its parent element, in a way that depends on the parent element's layout.

The representation of a node of any other kind depends on the layout chosen for its parent element.

A dynamic error occurs if any element cannot be processed using the selected layout for that element, unless fallback processing is defined; or if error action is explicitly requested for an element.

Any error in the conversion plan is treated as a type error whether or not it is technically a contravention of the defined type for the value. This relieves users and implementers of the burden of distinguishing different kinds of error in the plan.

 element-to-map(()) () bar)]]> { "foo": "bar" } 12.16, { 'attribute-marker': '', 'content-key': 'value' })]]> { "price": {'currency': 'USD', 'value': 12.16 }} , { 'attribute-marker': '' } )]]> { "list": [ { "value": "1" }, { "value": "2" } ] } Jane Smith )]]> { "name": { "first": "Jane", "last": "Smith" } } Jane Elizabeth Mary Smith , { 'plan': {'Q{http://example.ns/}name': { 'layout': 'record' }}, 'name-format' : 'local' } )]]> { "name": { "first": "Jane", "middle": ["Elizabeth", "Mary"], "last": "Smith" } } Jane Elizabeth Mary Smith , { 'plan': {'Q{http://example.ns/}name': { 'layout': 'record' }, 'Q{http://example.ns/}middle': { 'layout': 'deep-skip' } }, 'name-format' : 'local' } )]]> { "name": { "first": "Jane", "last": "Smith" } }

New in 4.0.

 deterministic context-independent focus-independent

Converts a map into an element node.

This function performs the inverse of element-to-map: it reconstructs an element node from the supplied in $map. The key of the entry represents the element name, and the value of the entry represents the element’s attributes and children.

If $map is the empty sequence, the result is the empty sequence.

Because element-to-map does not preserve all information present in its input (see ), the reconstruction is exact only up to that loss of information, and generally only when the same $options are supplied as were used for the forward conversion.

The entries that may appear in the $options map are the same as for element-to-map but are interpreted in the reverse direction.

The rules for converting a map to an element are described in ; the rules for selecting a layout from the conversion plan are the inverse of those in .

A dynamic error occurs if $map is not a single-entry map, if a map key or the #processing-instruction structure does not have the form required by the selected layout, if a reconstructed element or attribute name is not a valid xs:QName, or if list layout is selected for an array but the conversion plan supplies no child element name.

Any error in the conversion plan is treated as a type error , as for element-to-map.

 map-to-element(()) () bar]]> 12.16]]> Jane Elizabeth Mary Smith ]]> 20232023]]> A fine mess!]]>

New in 4.0.

 deterministic context-independent focus-independent

Parses CSV data, returning the results in the form of a record containing information about the names in the header, as well as the data itself.

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

The input supplied in $value is CSV data, based on the grammar of with the extensions described in . The function first parses the input using fn:csv-to-arrays, and then further processes the result. The initial parsing is exactly as defined for fn:csv-to-arrays, and can be controlled using the same options. Additional options are available to control the way in which header information and column names are handled.

If the input is the a zero-length string, the function returns a parsed-csv-structure-record whose rows entry is the empty sequence.

The $options argument can be used to control the way in which the parsing takes place. The option parameter conventions apply.

The entries that may appear in the $options map are as follows:

The character used to separate fields within a record. An instance of xs:string whose length is exactly one. xs:string "," The character used to quote fields within the CSV string. An instance of xs:string whose length is exactly one. xs:string '"' The character used to mark rows within the CSV string as comment rows. An instance of xs:string whose length is exactly one, or an empty sequence indicating that comments are not recognized. xs:string? () Determines whether leading and trailing whitespace is removed from the content of unquoted fields. xs:boolean false Unquoted fields will be returned with any leading or trailing whitespace intact. Unquoted fields will be returned with leading or trailing whitespace removed, and all other whitespace preserved. Determines whether the first row of the CSV should be treated as a list of column names, or whether column names are being supplied by the caller. The value must either be a single boolean, or a sequence of zero or more strings. (xs:boolean | xs:string)* false Column names are taken from the first row of the CSV data. Column names are not available; all references to columns are by ordinal position. Supplies explicit names for the columns. The Nth name in the list applies to the Nth column after any filtering or rearrangement. A zero-length string can be used when there is a column that requires no name. A sequence of integers indicating which columns to include and in which order. If this option is absent or empty, all columns are returned in their original order. For example, the value 1 to 4 indicates that the output contains the first, second, third, and fourth columns from the input, in order, while (1, 5, 4) indicates that the output contains three columns, taken from the first, fifth, and fourth columns of the input, in that order. An integer in the sequence is treated as the 1-based index of the column to include. Any other columns are dropped. If a particular row includes no field at the specified index, the empty field is included at the relevant position in the result. If an integer appears more than once then the result will include duplicated columns. xs:positiveInteger* () Determines whether all rows should be adjusted to contain the same number of fields. This option is ignored if select-columns is specified. xs:boolean false The number of fields in each row is left unchanged, so rows may vary in length. Fields are added or removed only where the select-columns option requests it. The number of fields in the first row (whether this be a header or a data row) determines the number of fields in every subsequent row; to achieve this, excess fields are removed, or additional zero-length fields are added.

The result of the function is a parsed-csv-structure-record, as defined in .

A dynamic error occurs if the value of $csv does not conform to the required grammar.

A dynamic error occurs if the value of any of the options separator, quote-character, or comment-marker is U+000A, or is not a single character, or if the same character is used in multiple roles.

Rows are delimited by a single newline character U+000A. Alternative line endings such as CR and CRLF will already have been normalized to a single newline.

All fields are returned as xs:string values.

Quoted fields in the input are returned without the quotes.

For more discussion of the returned data, see .

If the source of the CSV input is a resource accessible by URI, then it may be preferable to use the fn:csv-doc function. If the source is a binary value (xs:hexBinary or xs:base64Binary) then this can first be decoded as a string using the functions bin:infer-encoding and bin:decode-string.

 fn($result) { (: tidy up the result for display (function items cannot be properly displayed) :) map:put($result, "get", "(: function :)") }

Default delimiters, no column headers:

let $input := string-join( ("name,city", "Bob,Berlin", "Alice,Aachen"), char('\n') ) let $result := parse-csv($input) return ( $result => $display(), $result?get(1, 2), $result?get(2, 2) ) { "columns": (), "column-index": {}, "rows": ([ "name", "city" ], [ "Bob", "Berlin" ], [ "Alice", "Aachen" ]), "get": "(: function :)" }, "city", "Berlin"

Default delimiters, column headers:

let $input := string-join( ("name,city", "Bob,Berlin", "Alice,Aachen"), char('\n') ) let $result := parse-csv($input, { "header": true() }) return ( $result => $display(), $result?get(1, "name"), $result?get(2, "city") ) { "columns": ("name", "city"), "column-index": { "name": 1, "city": 2 }, "rows": ([ "Bob", "Berlin" ], [ "Alice", "Aachen" ]), "get": "(: function :)" }, "Bob", "Aachen"

Custom separator and quote character, no column headers:

let $options := { "separator": ";", "quote-character": "|" } let $input := string-join( ("|name|;|city|", "|Bob|;|Berlin|", "|Alice|;|Aachen|"), char('\n') ) let $result := parse-csv($input, $options) return ( $result => $display(), $result?get(3, 1) ) { "columns": (), "column-index": {}, "rows": ([ "name", "city" ], [ "Bob", "Berlin" ], [ "Alice", "Aachen" ]), "get": "(: function :)" }, "Alice"

Supplied column names:

let $headers := ("Person", "Location") let $options := { "header": $headers } let $input := "Alice,Aachen" || char('\n') || "Bob,Berlin" || char('\n') let $parsed-csv := parse-csv($input, $options) return ( $parsed-csv => $display(), $parsed-csv?get(2, "Location") ) { "columns": ("Person", "Location"), "column-index": { "Person": 1, "Location": 2 }, "rows": ([ "Alice", "Aachen" ], [ "Bob", "Berlin" ]), "get": "(: function :)" }, "Berlin"

Filtering columns, with ragged input and header: true()

let $input := string-join(( "date,name,city,amount,currency,original amount,note", "2023-07-19,Bob,Berlin,10.00,USD,13.99", "2023-07-20,Alice,Aachen,15.00", "2023-07-20,Charlie,Celle,15.00,GBP,11.99,cake,not a lie" ), char('\n')) let $options := { "header": true(), "select-columns": (2, 1, 4) } let $result := parse-csv($input, $options) return ( $result => $display(), $result?get(2, "amount") ) { "columns": ("name", "date", "amount"), "column-index": { "name": 1, "date": 2, "amount": 3 }, "rows": ( [ "Bob", "2023-07-19", "10.00" ], [ "Alice", "2023-07-20", "15.00" ], [ "Charlie", "2023-07-20", "15.00" ] ), "get": "(: function :)" }, "15.00"

Filtering columns, with supplied column map

let $input := string-join(( "2023-07-20,Alice,Aachen,15.00", "2023-07-19,Bob,Berlin,10.00,USD,13.99", "2023-07-20,Charlie,Celle,15.00,GBP,11.99,cake,not a lie" ), char('\n')) let $options := { "header": ( "Person", "", "Amount" ), "select-columns": (2, 1, 4) } let $result := parse-csv($input, $options) return ( $result => $display(), $result?get(2, "Person"), $result?get(2, "Amount") ) { "columns": ("Person", "", "Amount"), "column-index": { "Person": 1, "Amount": 3 }, "rows": ([ "Alice", "2023-07-20", "15.00" ], [ "Bob", "2023-07-19", "10.00" ], [ "Charlie", "2023-07-20", "15.00" ]), "get": "(: function :)" }, "Bob", "10.00"

Specifying the number of columns explicitly, with header: false()

let $input := string-join(( "date, name, amount, currency, original amount", "2023-07-19,Bob, 10.00, USD, 13.99", "2023-07-20,Alice, 15.00", "2023-07-20,Charlie, 15.00, GBP, 11.99, extra data" ), char('\n')) let $options := { "header": false(), "select-columns": 1 to 5, "trim-whitespace" :true() } let $result := parse-csv($input, $options) return ( $result => $display(), $result?get(4, 3) ) { "columns": (), "column-index": {}, "rows": ( [ "date", "name", "amount", "currency", "original amount" ], [ "2023-07-19", "Bob", "10.00", "USD", "13.99" ], [ "2023-07-20", "Alice", "15.00", "", "" ], [ "2023-07-20", "Charlie", "15.00", "GBP", "11.99" ] ), "get": "(: function :)" }, "15.00"

Specifying the number of columns with a number and header: true()

let $input := string-join(( "date,name,city,amount,currency,original amount,note", "2023-07-19,Bob,Berlin,10.00,USD,13.99", "2023-07-20,Alice,Aachen,15.00", "2023-07-20,Charlie,Celle,15.00,GBP,11.99,cake,not a lie" ), char('\n')) let $options := { "header": true(), "select-columns": 1 to 6 } let $result := parse-csv($input, $options) return ( $result => $display(), $result?get(3, "original amount") ) { "columns": ("date", "name", "city", "amount", "currency", "original amount"), "column-index": { "date": 1, "name": 2, "city": 3, "amount": 4, "currency": 5, "original amount": 6 }, "rows": ( [ "2023-07-19", "Bob", "Berlin", "10.00", "USD", "13.99"], [ "2023-07-20", "Alice", "Aachen", "15.00", "", ""], [ "2023-07-20", "Charlie", "Celle", "15.00", "GBP", "11.99"] ), "get": "(: function :)" }, "11.99"

New in 4.0

Dropped the row-delimiter option, renamed field-delimiter to separator, and merged error CV0003 into CV0002.

Added support for comment rows.

 deterministic context-dependent focus-independent

Reads an external resource containing CSV, and returns the results as a record containing information about the names in the header, as well as the data itself.

The effect of the two-argument function call fn:csv-doc($H, $M) is equivalent to the function composition fn:unparsed-text($H) => fn:parse-csv($M), except that the special handling of media types such as text/xml and application/xml in the selection of the effective encoding may be skipped.

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

The ability to access external resources depends on whether the calling code is .

The function may raise any error defined for the fn:unparsed-text or fn:parse-csv functions.

New in 4.0

 deterministic context-independent focus-independent

Parses CSV data supplied as a string, returning the results in the form of a sequence of arrays of strings.

The $value argument is CSV data, based on the grammar of with the extensions described in , in the form of an xs:string value. The function parses this string, after normalizing newlines so that U+000D and (U+000D, U+000A) sequences are converted to U+000A. The result of the function is a sequence of arrays of strings, that is array(xs:string)*; each array represents one row of the CSV input.

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

The $options argument can be used to control the way in which the parsing takes place. The option parameter conventions apply.

The entries that may appear in the $options map are as follows:

The character used to separate fields within a record. An instance of xs:string whose length is exactly one. xs:string "," The character used to quote fields within the CSV string. An instance of xs:string whose length is exactly one. xs:string '"' The character used to mark rows within the CSV string as comment rows. An instance of xs:string whose length is exactly one, or an empty sequence indicating that comments are not recognized. xs:string? () Determines whether leading and trailing whitespace is removed from the content of unquoted fields. xs:boolean false Unquoted fields will be returned with any leading or trailing whitespace intact. Unquoted fields will be returned with leading or trailing whitespace removed, and all other whitespace preserved.

An empty field is represented by a zero-length string. An empty field is deemed to exist when a separator immediately follows either another separator, or a newline, or the start of $value; or when a newline or the end of $value immediately follows a separator.

A blank row is represented as the empty array (not as an array containing a single empty field). A blank row is deemed to exist when a newline immediately follows either another newline or the start of $value, after trimming of whitespace if the trim-whitespace option is true. No blank row occurs after the final newline.

If $value is a zero-length string, the CSV is considered to contain no rows; while if $value consists of a single newline, it is considered to contain a single blank row. The presence or absence of a final newline generally has no effect on the result, except when it appears at the start of the input, in which case it causes a single blank row to exist.

A dynamic error occurs if the value of $csv does not conform to the required grammar.

A dynamic error occurs if the value of any of the options separator, quote-character, or comment-marker is U+000A, or is not a single character, or if the same character is used in multiple roles.

Rows are delimited by a single newline character U+000A. Alternative line endings such as CR and CRLF will already have been normalized to a single newline.

All fields are returned as xs:string values.

Quoted fields in the input are returned without the quotes.

The first row is not treated specially.

For more discussion of the returned data, see .

Handling trivial input:

csv-to-arrays(()) () csv-to-arrays("") () csv-to-arrays(char('\n')) [] csv-to-arrays(" ", { 'trim-whitespace': true() }) () csv-to-arrays(" ", { 'trim-whitespace': false() }) [ " " ] csv-to-arrays(char('\n'), { 'trim-whitespace': true() }) [] csv-to-arrays(char('\n'), { 'trim-whitespace': false() }) []

Using newline separators:

csv-to-arrays( `name,city{ char('\n') }` || `Bob,Berlin{ char('\n') }` || `Alice,Aachen{ char('\n') }` ) [ "name", "city" ], [ "Bob", "Berlin" ], [ "Alice", "Aachen" ] let $CRLF := char('\r') || char('\n') return csv-to-arrays( `# Use CRLF as line ending { $CRLF }` || `name,city{ $CRLF }` || `Bob,Berlin{ $CRLF }` || `Alice,Aachen{ $CRLF }`, { 'comment-marker': '#' } ) [ "name", "city" ], [ "Bob", "Berlin" ], [ "Alice", "Aachen" ]

Quote handling:

csv-to-arrays( string-join( (`"name","city"`, `"Bob","Berlin"`, `"Alice","Aachen"`), char('\n') ) ) [ "name", "city" ], [ "Bob", "Berlin" ], [ "Alice", "Aachen" ] csv-to-arrays( `"name","city"{ char('\n') }` || `"Bob ""The Exemplar"" Mustermann","Berlin"{ char('\n') }` ) [ "name", "city" ], [ 'Bob "The Exemplar" Mustermann', "Berlin" ]

Non-default field separator:

csv-to-arrays( string-join( ("name;city", "Bob;Berlin", "Alice;Aachen"), char('\n') ), { "separator": ";" } ) [ "name", "city" ], [ "Bob", "Berlin" ], [ "Alice", "Aachen" ]

Non-default quote character:

csv-to-arrays( string-join( ("|name|,|city|", "|Bob|,|Berlin|"), char('\n') ), { "quote-character": "|" } ) [ "name", "city" ], [ "Bob", "Berlin" ]

Trimming whitespace in fields:

csv-to-arrays( string-join( ("name ,city ", "Bob ,Berlin ", "Alice ,Aachen "), char('\n') ), { "trim-whitespace": true() } ) [ "name", "city" ], [ "Bob", "Berlin" ], [ "Alice", "Aachen" ]

New in 4.0

Dropped the row-delimiter option, renamed field-delimiter to separator, and merged error CV0003 into CV0002.

Added support for comment rows.

 nondeterministic context-dependent focus-independent

Parses CSV data supplied as a string, returning the results as an XML document, as described by .

The arguments have the same meaning, and are subject to the same constraints, as the arguments of fn:parse-csv.

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

In other cases, the effect of the function is equivalent to the result of the following XQuery expression (where $options is the empty map if the argument is not supplied):

{ if (exists($lastCol)) { { subsequence($colNames, 1, $lastCol) ! { . } } }, { for $row in $parsedCSV?rows return { for member $field at $col in $row return { if ($colNames[$col] != '') { attribute column { $colNames[$col] } }, $field } } } } }]]>

The elements in the returned XML are in the namespace http://www.w3.org/2005/xpath-functions; the namespace prefix that is used (or its absence) is .

If the function is called twice with the same arguments, it is whether the two calls return the same element node or distinct (but deep equal) element nodes. In this respect it is nondeterministic with respect to node identity.

The base URI of the element nodes in the result is .

A schema is defined for the structure of the returned document: see .

The result of the function will always be such that validation against this schema would succeed. However, it is whether the result is typed or untyped, that is, whether the elements and attributes in the returned tree have type annotations that reflect the result of validating against this schema.

See fn:parse-csv.

 `name,city{ $crlf }Bob,Berlin{ $crlf }Alice,Aachen{ $crlf }`

An empty CSV with default column extraction (false):

csv-to-xml(()) () csv-to-xml("") ]]> csv-to-xml(char('\n')) ]]>

An empty CSV with header extraction:

csv-to-xml("", { "header": true() }) ]]>

An empty CSV with explicit column names:

csv-to-xml("", { "header": ("name", "", "city") }) name city ]]>

With defaults for delimiters and quotes, recognizing headers:

csv-to-xml($csv-string, { "header": true() }) name city Bob Berlin Alice Aachen ]]> concat( `date,name,city,amount,currency,original amount,note{ $crlf }`, `2023-07-19,Bob,Berlin,10.00,USD,13.99{ $crlf }`, `2023-07-20,Alice,Aachen,15.00{ $crlf }`, `2023-07-20,Charlie,Celle,15.00,GBP,11.99,cake,not a lie{ $crlf }` )

Filtering columns

csv-to-xml( $csv-uneven-cols, { "header": true(), "select-columns": (2, 1, 4) } ) name date amount Bob 2023-07-19 10.00 Alice 2023-07-20 15.00 Charlie 2023-07-20 15.00 ]]>

Ragged rows

csv-to-xml( $csv-uneven-cols, { "header": true() } ) date name city amount currency original amount note 2023-07-19 Bob Berlin 10.00 USD 13.99 2023-07-20 Alice Aachen 15.00 2023-07-20 Charlie Celle 15.00 GBP 11.99 cake not a lie ]]>

Trimming rows to constant width

csv-to-xml( $csv-uneven-cols, { "header": true(), "trim-rows": true() } ) date name city amount currency original amount note 2023-07-19 Bob Berlin 10.00 USD 13.99 2023-07-20 Alice Aachen 15.00 2023-07-20 Charlie Celle 15.00 GBP 11.99 cake ]]>

Specifying a fixed number of columns

csv-to-xml( $csv-uneven-cols, { "header": true(), "select-columns": 1 to 6 } ) date name city amount currency original amount 2023-07-19 Bob Berlin 10.00 USD 13.99 2023-07-20 Alice Aachen 15.00 2023-07-20 Charlie Celle 15.00 GBP 11.99 ]]>

Corrected to nondeterministic with respect to node identity.

New in 4.0

 deterministic context-independent focus-independent

Parses input supplied in the form of a JSON text, returning the results typically in the form of a map or array.

If the second argument is omitted or the empty sequence, the result is the same as calling the two-argument form with the empty map as the value of the $options argument.

The first argument is a JSON text as defined in , in the form of a string or binary value. The function parses this input to return an XDM value.

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

If the input is "null", the result will also be the empty sequence.

The $options argument can be used to control the way in which the parsing takes place. The option parameter conventions apply.

The entries that may appear in the $options map are as follows:

Determines whether deviations from the syntax of RFC8259 are permitted. xs:boolean false The input must consist of a string that conforms to the grammar of JSON-text in , optionally preceded by a byte order mark (which is skipped). An error must be raised if the input does not conform to the grammar. The input may contain deviations from the grammar of , which are handled in an implementation-defined way. (Note: some popular extensions include allowing quotes on keys to be omitted, allowing a comma to appear after the last item in an array, allowing leading zeroes in numbers, and allowing control characters such as tab and newline to be present in unescaped form.) Since the extensions accepted are implementation-defined, an error may be raised if the input does not conform to the grammar. Determines the policy for handling duplicate keys in a JSON object. To determine whether keys are duplicates, they are compared using the Unicode codepoint collation, after expanding escape sequences, unless the escape option is set to true, in which case keys are compared in escaped form. xs:string use-first An error is raised if duplicate keys are encountered. If duplicate keys are present in a JSON object, all but the first of a set of duplicates are ignored. If duplicate keys are present in a JSON object, all but the last of a set of duplicates are ignored. Determines whether special characters are represented in the XDM output in backslash-escaped form. xs:boolean false Any in the input, whether or not it is represented in the input by means of an escape sequence, is represented as an unescaped character in the result. Any other character or codepoint (for example, an unpaired surrogate) is passed to the fallback function as described below; in the absence of a fallback function, it is replaced by U+FFFD. JSON escape sequences are used in the result to represent special characters in the JSON input, as defined below, whether or not they were represented using JSON escape sequences in the input. The characters that are considered “special” for this purpose are:

all codepoints in the range U+0000 to U+001F or U+007F to U+009F;

all codepoints that do not represent permitted characters, including codepoints representing unpaired surrogates;

the character U+005C itself.

 Such characters are represented using a two-character escape sequence where available (for example, \t), or a six-character escape sequence otherwise (for example \uDEAD). Characters other than these are not escaped in the result, even if they were escaped in the input. Provides a function which is called when the input contains an escape sequence that represents a character that is not a . It is an error to supply the fallback option if the escape option is present with the value true. (fn($escape as xs:string) as xs:anyAtomicType)? fn { char(0xFFFD) } The function is called when the JSON input contains character that is not a It is called once for any surrogate that is not properly paired with another surrogate. The untyped atomic item supplied as the argument will always be a two- or six-character escape sequence, starting with a backslash, that conforms to the rules in the JSON grammar (as extended by the implementation if liberal:true() is specified): for example \b or \uFFFF or \uDEAD.

By default, the escape sequence is replaced with the Unicode REPLACEMENT CHARACTER. The function is not called for an escape sequence that is invalid against the grammar (for example \x0A). The string, which results from invoking fn:string on the result of the function, is inserted into the result in place of the invalid character. The function also has the option of raising a dynamic error by calling fn:error.

 Determines how the JSON null value should be represented. item()? () The supplied XDM value is used to represent the JSON null value. The default representation of null is the empty sequence, which works well in cases where setting a property of an object to null has the same meaning as omitting the property. It works less well in cases where null is used with some other meaning, because expressions such as the lookup operator ? flatten the result to a single sequence of items, which means that any entries whose value is the empty sequence effectively disappear. The property can be set to any XDM item or to an empty sequence; a suggested value is the xs:QName value fn:QName("http://www.w3.org/2005/xpath-functions", "null"), which is recognized by the JSON serialization method as representing the JSON value null. Determines how numeric values should be processed. enum("double", "decimal", "adaptive") "double" The result of parsing a JSON number will always be an xs:double value, obtained by following the XPath rules for casting xs:string to xs:double, having first checked that the supplied string conforms to the JSON rules for numeric values. The result of parsing a JSON number will always be an xs:decimal value. The input must conform to the JSON rules for numeric values. If the input is a string in the lexical space of xs:decimal then it is cast to xs:decimal following the XPath casting rules. If the resulting xs:decimal has a in the value space of xs:integer then the result is coerced to xs:integer using the . In other cases (specifically, when the JSON value uses exponential notation), the value is first cast to xs:double and the resulting xs:double is then cast to xs:decimal, in both cases by following the XPath casting rules. The result of parsing a JSON number will be either an xs:decimal or an xs:double value, depending on its lexical form. The input must conform to the JSON rules for numeric values. If the input is a string in the lexical space of xs:decimal then it is cast to xs:decimal following the XPath casting rules. If the resulting xs:decimal has a in the value space of xs:integer then the result is coerced to xs:integer using the . In other cases (specifically, when the JSON value uses exponential notation), the value is cast to xs:double, following the XPath rules for casting from xs:string to xs:double.

The various structures that can occur in JSON are transformed recursively to XDM values as follows:

A JSON object is converted to a map. The entries in the map correspond to the key/value pairs in the JSON object. The key is always of type xs:string; the associated value may be of any type, and is the result of converting the JSON value by recursive application of these rules. For example, the JSON text { "x": 2, "y": 5 } is transformed to the value { "x": 2, "y": 5 }.

If duplicate keys are encountered in a JSON object, they are handled as determined by the duplicates option defined above.

The order of entries is retained.

A JSON array is transformed to an array whose members are the result of converting the corresponding member of the array by recursive application of these rules. For example, the JSON text [ "a", "b", null ] is transformed (by default) to the value [ "a", "b", () ].

A JSON string is converted to an xs:string value. The handling of special characters depends on the escape and fallback options, as described in the table above.

A JSON number is processed according to the rules of the number-format option; by default it is converted to an xs:double value using the rules for casting from xs:string to xs:double.

The casting rules leave implementations some flexibility as to how values should be handled when they are too large to represent as an xs:double. It is recommended that when parsing JSON, out-of-range values should be converted to positive or negative infinity. This option enables round-tripping behavior, since the JSON serialization method represents positive and negative infinity as 1e9999 or -1e9999 respectively.

Round-tripping of NaN can be achieved by setting the option "null": number("NaN")

The JSON boolean values true and false are converted to the corresponding xs:boolean values.

The JSON value null is converted to the value given by the null option, which defaults to an empty sequence.

A dynamic error occurs if the value of $value does not conform to the JSON grammar, unless the option "liberal":true() is present and the processor chooses to accept the deviation.

A dynamic error occurs if the option "duplicates": "reject" is present and the value of $value contains a JSON object with duplicate keys.

A dynamic error occurs if the $options map contains an entry whose key is defined in this specification and whose value is not valid for that key, or if it contains an entry with the key fallback when the option "escape":true() is also present.

The result of the function will be an instance of one of the following types. An instance of test (or in XQuery, typeswitch) can be used to distinguish them:

map(xs:string, item()?) for a JSON object

array(item()?) for a JSON array

xs:string for a JSON string

xs:double for a JSON number

xs:decimal for a JSON number

xs:boolean for a JSON boolean

empty-sequence() for a JSON null (or for empty input); or some other type as determined by the null option if set.

If the source of the JSON input is a resource accessible by URI, then it may be preferable to use the fn:json-doc function. If the source is a binary value (xs:hexBinary or xs:base64Binary) then this can first be decoded as a string using the functions bin:infer-encoding and bin:decode-string.

If the input starts with a byte order mark, this function ignores it. The byte order mark may have been added to the data stream in order to facilitate decoding of an octet stream to a character string, but since this function takes a character string as input, the byte order mark serves no useful purpose.

The possibility of the input containing characters that are not valid in XML (for example, unpaired surrogates) arises only when such characters are expressed using JSON escape sequences. This is because the input to the function is an instance of xs:string, which by definition (see ) cannot contain unpaired surrogates.

The serializer provides an option to output data in json-lines format. This is a format for structured data containing one JSON value (usually but not necessarily a JSON object) on each line. There is no corresponding option to parse json-lines input, but this can be achieved using the expression unparsed-text-lines($uri) =!> parse-json().

 parse-json('{ "x": 1, "y": [ 3, 4, 5 ] }') { "x": 1e0, "y": [ 3e0, 4e0, 5e0 ] } parse-json('"abcd"') "abcd" parse-json('{ "x": "\\", "y": "\u0025" }') { "x": "\", "y": "%" } parse-json( '{ "x": "\\", "y": "\u0025" }', { 'escape': true() } ) { "x": "\\", "y": "%" } parse-json( '{ "x": "\\", "y": "\u0000" }' ) { "x": "\", "y": char(0xFFFD) } parse-json( '{ "x": "\\", "y": "\u0000" }', { 'escape': true() } ) { "x": "\\", "y": "\u0000" } parse-json( '{ "x": "\\", "y": "\u0000" }', { 'fallback': fn($s) { '[' || $s || ']' } } ) { "x": "\", "y": "[\u0000]" } parse-json( '[2.0, 1e6]', { 'number-format': 'adaptive' } ) [ xs:integer('2'), xs:double('1.0e6') ] parse-json('[ "a", null, "b" ]', { 'null': #fn:null } ) [ "a", #fn:null, "b" ]

The rules regarding use of non-XML characters in JSON texts have been relaxed.

An option is provided to control how the JSON null value should be handled.

An option is provided to control how JSON numbers should be formatted.

It is now recommended that out-of-range xs:double values should translate to positive or negative infinity.

The default for the escape option has been changed to false. The 3.1 specification gave the default value as true, but this appears to have been an error, since it was inconsistent with examples given in the specification and with tests in the test suite.

The order of entries in maps is retained.

 deterministic context-dependent focus-independent

Reads an external resource containing JSON, and returns the result of parsing the resource as JSON.

The effect of the two-argument function call fn:json-doc($H, $M) is equivalent to the function composition fn:unparsed-text($H) => fn:parse-json($M), except that:

The special handling of media types such as text/xml and application/xml in the selection of the effective encoding may be skipped.

Having established the encoding, the function must accept any codepoint that can validly occur in a JSON text, with the exception of unpaired surrogates.

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

The ability to access external resources depends on whether the calling code is .

The function may raise any error defined for the fn:unparsed-text or fn:parse-json functions.

If the data starts with an initial byte order mark then this is dropped, as with the fn:unparsed-text function.

If the input cannot be decoded (that is, converted into a sequence of Unicode codepoints, which may or may not represent characters), then a dynamic error occurs as with the fn:unparsed-text function.

If the input can be decoded, then the possibility still arises that the resulting sequence of codepoints includes codepoints that are not permitted characters. Such codepoints are translated into JSON escape sequences (for example, \uFFFF), and the JSON escape sequence is then passed to the fallback function specified in the $options argument, which in turn defaults to a function that returns U+FFFD.

requires UTF-8 to be used when JSON data is exchanged between systems that are not part of a closed ecosystem. Nevertheless, the function may accept a resource in any encoding recognized by the fn:unparsed-text function.

Additional options are available, as defined by fn:parse-json.

It is no longer automatically an error if the input contains a codepoint that is not valid in XML. Instead, the codepoint must be a . The set of permitted characters is , but it is recommended that all Unicode characters should be accepted.

 deterministic context-independent focus-independent

Returns the number of members in the supplied array.

The function returns the number of members in the array.

 count(array:members($array))

Note that because an array is an item, the fn:count function when applied to an array always returns 1.

 array:size([ "a", "b", "c" ]) 3 array:size([ "a", [ "b", "c" ] ]) 2 array:size([]) 0 array:size([ [] ]) 1 deterministic context-independent focus-independent

Returns true if the supplied array contains no members.

The function returns true if and only if $array contains no members.

The test for emptiness is not the same as the test used by the xsl:on-empty instruction in XSLT. For example, an array is not considered empty by this function if it contains a single member that is itself the empty array.

 array:empty([ "a", "b", "c" ]) false() array:empty([]) true() array:empty([ [] ]) false() array:empty([ () ]) false()

New in 4.0

 deterministic context-independent focus-independent

Returns the value at the specified position in the supplied array (counting from 1).

Informally, the function returns the member at a specified position in the array.

If $position is out of bounds (that is, if it is less than one or greater than array:size($array)), then the effect depends on the number of arguments:

When there are two arguments, an error is raised ().

When there are three arguments, the value of $default is returned.

 Provide separate "formal equivalents" for the two variants. (: For the two-argument form: :) if ($position = (1 to array:size($array))) then items-at(array:members($array), $position) => jvalue()) else error(), (: For the three-argument form: :) if ($position = (1 to array:size($array))) then items-at(array:members($array), $position) => jvalue()) else $default

In the absence of a $default argument, a dynamic error occurs if $position is not in the range 1 to array:size($array) inclusive.

 [ "a", "b", "c" ] => array:get(2) "b" [ "a", [ "b", "c" ] ] => array:get(2) [ "b", "c" ] [ "a" ] => array:get(1, ()) "a" [ "a" ] => array:get(2, ()) ()

A third argument is added, allowing user control of how index-out-of-bounds conditions should be handled.

 deterministic context-independent focus-independent

Returns an array containing all the members of a supplied array, except for one member which is replaced with a new value.

Informally, the result is an array whose size is array:size($array), in which all members in positions other than $position are the same as the members in the corresponding position of $array, and the member in position $position is $member.

 array:remove($position) => array:insert-before($position, $member) ]]>

A dynamic error occurs if $position is not in the range 1 to array:size($array) inclusive.

This error will always occur if $array is empty.

 array:put([ "a", "b", "c" ], 2, "d") [ "a", "d", "c" ] array:put([ "a", "b", "c" ], 2, ("d", "e")) [ "a", ("d", "e"), "c" ] array:put([ "a" ], 1, [ "d", "e" ]) [ [ "d", "e" ] ] deterministic context-independent focus-independent

Returns an array containing all the members of a supplied array, plus one additional member at the end.

Informally, the result is an array whose size is array:size($array) + 1, in which all members in positions 1 to array:size($array) are the same as the members in the corresponding position of $array, and the member in position array:size($array) + 1 is $member.

 dm:array-append($array, $member) array:append([ "a", "b", "c" ], "d") [ "a", "b", "c", "d" ] array:append([ "a", "b", "c" ], ("d", "e")) [ "a", "b", "c", ("d", "e") ] array:append([ "a", "b", "c" ], [ "d", "e" ]) [ "a", "b", "c", [ "d", "e" ] ] deterministic context-independent focus-independent

Concatenates the contents of several arrays into a single array.

The function concatenates the members of several arrays into a single array.

 for-each(fn($array) { array:members($array) }) => array:of-members() ]]> array:join(()) [] array:join([ 1, 2, 3 ]) [ 1, 2, 3 ] array:join(([ "a", "b" ], [ "c" ])) [ "a", "b", "c" ] array:join(([ "a", "b" ], [ "c" ], [])) [ "a", "b", "c" ] array:join(([ "a", "b" ], [ [ "c" ] ])) [ "a", "b", [ "c" ] ] array { 1 to 3 } => array:split() => array:join() [ 1, 2, 3 ] deterministic context-independent focus-independent

Returns an array containing all members from a supplied array starting at a supplied position, up to a specified length.

Except in error cases, the two-argument version of the function returns the same result as the three-argument version when called with $length equal to the value of array:size($array) - $start + 1.

 array:members() => subsequence($start, $length) => array:of-members() ]]>

A dynamic error is raised if $start is less than one or greater than array:size($array) + 1.

For the three-argument version of the function:

A dynamic error is raised if $length is less than zero.

A dynamic error is raised if $start + $length is greater than array:size($array) + 1.

The value of $start can be equal to array:size($array) + 1 provided that $length is either equal to zero or omitted. In this case the result will be the empty array.

 array:subarray([ "a", "b", "c", "d" ], 2) [ "b", "c", "d" ] array:subarray([ "a", "b", "c", "d" ], 5) [] array:subarray([ "a", "b", "c", "d" ], 2, 0) [] array:subarray([ "a", "b", "c", "d" ], 2, 1) [ "b" ] array:subarray([ "a", "b", "c", "d" ], 2, 2) [ "b", "c" ] array:subarray([ "a", "b", "c", "d" ], 5, 0) [] array:subarray([], 1, 0) []

Supplying the empty sequence as the value of an optional argument is equivalent to omitting the argument.

 deterministic context-dependent focus-independent deterministic context-dependent focus-independent

Returns a sequence of positive integers giving the positions within the array $array of members that are equal to $target.

Informally, all members of $array are compared with $target. An array member is compared to the target value using the rules of the fn:deep-equal function, with the specified (or defaulted) collation. The index position of the member is included in the result sequence if the comparison returns true.

The collation used by this function is determined according to the rules in . This collation is used when string comparison is required.

The first member in an array is at position 1, not position 0.

The result sequence is in ascending numeric order.

 array:index-where($array, deep-equal(?, $target, $collation))

If $array is the empty array, or if no member in $array matches $target, then the function returns the empty sequence.

 array:index-of([ 10, 20, 30, 30, 20, 10 ], 20) 2, 5 array:index-of([ (), 1, (5, 6), (6, 7) ], (6, 7)) 4 array:index-of( [ "a", ("b", "C"), "d" ], ("B", "c"), "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) 2 array:index-of( [ '1', xs:untypedAtomic('1'), 1, current-date() ], '1' ) 1, 2

New in 4.0

 deterministic context-independent focus-independent

Returns the positions in an input array of members that match a supplied predicate.

The result of the function is a sequence of integers, in monotonic ascending order, representing the 1-based positions in the input array of those members for which the supplied predicate function returns true. A return value of () is treated as false.

 dm:iterate-array($array, fn($member, $pos) { if ($predicate($member, $pos)) { $pos } }) array:index-where([], boolean#1) () array:index-where([ 0, (), 4, 9 ], boolean#1) 3, 4 array:index-where( array { 1 to 10 }, function { . mod 2 = 0 } ) 2, 4, 6, 8, 10 array:index-where( [ "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December" ], contains(?, "r") ) 1, 2, 3, 4, 9, 10, 11, 12 array:index-where( [ (1, 2, 3), (4, 5, 6), (7, 8) ], fn($m) { count($m) = 3 } ) 1, 2 2 } )]]> 3, 5

New in 4.0

The $predicate callback function may return the empty sequence (meaning false).

 deterministic context-independent focus-independent

Returns an array containing selected members of a supplied input array based on their position.

Informally, the array is converted to a sequence, the function fn:slice is applied to this sequence, and the resulting sequence is converted back to an array.

 array:members() => slice($start, $end, $step) => array:of-members() ]]>

Note that unlike other operations on arrays, there are no out-of-bounds errors for inappropriate values of $start, $end, or $step.

 array:slice($in, start := 2, end := 4) [ "b", "c", "d" ] array:slice($in, start := 2) [ "b", "c", "d", "e" ] array:slice($in, end := 2) [ "a", "b" ] array:slice($in, start := 3, end := 3) [ "c" ] array:slice($in, start := 4, end := 3) [ "d", "c" ] array:slice($in, start := 2, end := 5, step := 2) [ "b", "d" ] array:slice($in, start := 5, end := 2, step := -2) [ "e", "c" ] array:slice($in, start := 2, end := 5, step := -2) [] array:slice($in, start := 5, end := 2, step := 2) [] array:slice($in) [ "a", "b", "c", "d", "e" ] array:slice($in, start := -1) [ "e" ] array:slice($in, start := -3) [ "c", "d", "e" ] array:slice($in, end := -2) [ "a", "b", "c", "d" ] array:slice($in, start := 2, end := -2) [ "b", "c", "d" ] array:slice($in, start := -2, end := 2) [ "d", "c", "b" ] array:slice($in, start := -4, end := -2) [ "b", "c", "d" ] array:slice($in, start := -2, end := -4) [ "d", "c", "b" ] array:slice($in, start := -4, end := -2, step := 2) [ "b", "d" ] array:slice($in, start := -2, end := -4, step := -2) [ "d", "b" ] array:slice([ "a", "b", "c", "d" ], 0) [ "a", "b", "c", "d" ]

New in 4.0

 deterministic context-independent focus-independent

Returns an array containing all the members of the supplied array, except for the members at specified positions.

Informally, the function returns an array of size array:size($array) - fn:count(fn:distinct-values($positions)) containing all members from $array except the members whose position (counting from 1) is present in the sequence $positions. The order of the remaining members is preserved.

 array:members() => remove($positions) => array:of-members() ]]>

A dynamic error is raised if any integer in $positions is not in the range 1 to array:size($array) inclusive. By implication, an error occurs if $array is empty, unless $positions is also empty.

 array:remove([ "a", "b", "c", "d" ], 1) [ "b", "c", "d" ] array:remove([ "a", "b", "c", "d" ], 2) [ "a", "c", "d" ] array:remove([ "a" ], 1) [] array:remove([ "a", "b", "c", "d" ], 1 to 3) [ "d" ] array:remove([ "a", "b", "c", "d" ], ()) [ "a", "b", "c", "d" ] deterministic context-independent focus-independent

Returns an array containing all the members of the supplied array, with one additional member at a specified position.

Informally, the function returns an array of size array:size($array) + 1 containing all members from $array whose position is less than $position, then a new member given by $member, and then all members from $array whose position is greater than or equal to $position. Positions are counted from 1.

 array:members() => insert-before($position, array:members([$member]) }) => array:of-members() ]]>

A dynamic error occurs if $position is not in the range 1 to array:size($array) + 1 inclusive.

Setting $position to 1 has the effect of prepending the new member at the start of the array. Setting $position to the value array:size($array) + 1 delivers the same result as array:append($array, $member).

 array:insert-before( [ "a", "b", "c", "d" ], 3, ("x", "y") ) [ "a", "b", ("x", "y"), "c", "d" ] array:insert-before( [ "a", "b", "c", "d" ], 5, ("x", "y") ) [ "a", "b", "c", "d", ("x", "y") ] array:insert-before( [ "a", "b", "c", "d" ], 3, [ "x", "y" ] ) [ "a", "b", [ "x", "y" ], "c", "d" ] deterministic context-independent focus-independent

Returns the first member of an array, that is $array(1).

The function returns first member of $array.

 array:get($array, 1)

A dynamic error occurs if $array is empty.

 array:head([ 5, 6, 7, 8 ]) 5 array:head([ [ "a", "b" ], [ "c", "d" ] ]) [ "a", "b" ] array:head([ ("a", "b"), ("c", "d") ]) "a", "b" deterministic context-independent focus-independent special-streaming-rules

Returns the last member of an array.

The function returns the last member of $array.

A dynamic error occurs if $array is empty.

 array:foot([ 5, 6, 7, 8 ]) 8 array:foot([ [ "a", "b" ], [ "c", "d" ] ]) [ "c", "d" ] array:foot([ ("a", "b"), ("c", "d") ]) "c", "d"

New in 4.0

 deterministic context-independent focus-independent

Returns an array containing all members except the first from a supplied array.

The function returns an array containing all members of the supplied array except the first.

A dynamic error occurs if $array is empty.

If the supplied array contains exactly one member, the result will be the empty array.

 array:tail([ 5, 6, 7, 8 ]) [ 6, 7, 8 ] array:tail([ 5 ]) [] deterministic context-independent focus-independent special-streaming-rules

Returns an array containing all members except the last from a supplied array.

The function returns an array containing all members of the supplied array except the last.

A dynamic error occurs if $array is empty.

If the supplied array contains exactly one member, the result will be the empty array.

 array:trunk([ 5, 6, 7, 8 ]) [ 5, 6, 7 ] array:trunk([ 5 ]) []

New in 4.0

 deterministic context-independent focus-independent

Returns an array containing all the members of a supplied array, but in reverse order.

The function returns an array with the same number of members as $array, but in reverse order.

 array:members() => reverse() => array:of-members() ]]> array:reverse([ "a", "b", "c", "d" ]) [ "d", "c", "b", "a" ] array:reverse([ ("a", "b"), ("c", "d") ]) [ ("c", "d"), ("a", "b") ] array:reverse([ 1 to 5 ]) [ (1, 2, 3, 4, 5) ] array:reverse([]) [] deterministic context-independent focus-independent

Returns an array whose size is the same as array:size($array), in which each member is computed by applying $action to the corresponding member of $array.

Informally, the function returns an array whose members are obtained by applying the supplied $action function to each member of the input array in turn.

For each member of the array, the function calls $action($member, $pos); a member is in general an arbitrary sequence.

 array:of-members( for-each(array:members($array), fn($member, $pos) { jtree($action(jvalue($member), $pos)) } }) ) array:for-each( [ "A", "B", 1, 2 ], fn($z) { $z instance of xs:integer } ) [false(), false(), true(), true()] array:for-each( [ "the cat", "sat", "on the mat" ], tokenize#1 ) [ ("the", "cat"), "sat", ("on", "the", "mat") ] array:for-each( [ [ "the", "cat" ], [ "sat" ], [ "on", "the", "mat" ] ], array:flatten#1 ) [ ("the", "cat"), "sat", ("on", "the", "mat") ] array:for-each( [ 'one', 'two', 'three' ], fn($member, $pos) { $pos || '. ' || $member } ) [ "1. one", "2. two", "3. three" ]

The $action callback function now accepts an optional position argument.

 deterministic context-independent focus-independent

Returns an array containing those members of the $array for which $predicate returns true. A return value of () is treated as false.

Informally, the function returns an array containing those members of the input array that satisfy the supplied predicate.

 array:of-members( filter( array:members($array), fn($item, $pos) { $predicate(jvalue($item), $pos) } ) )

As a consequence of the function signature and the function calling rules, a type error occurs if the supplied function $function returns anything other than a single xs:boolean item or the empty sequence; there is no conversion to an effective boolean value.

 array:filter( [ "A", "B", 1, 2 ], fn($x) { $x instance of xs:integer } ) [ 1, 2 ] array:filter( [ "the cat", "sat", "on the mat" ], function { count(tokenize(.)) > 1 } ) [ "the cat", "on the mat" ] array:filter([ "A", "B", "", 0, 1 ], boolean#1) [ "A", "B", 1] let $array := [ 1, 1, 2, 3, 4, 4, 5 ] return array:filter( $array, fn($item, $pos) { $pos > 1 and $item = $array($pos - 1) } ) [ 1, 4 ]

The $predicate callback function now accepts an optional position argument.

The $predicate callback function may return the empty sequence (meaning false).

 deterministic context-independent focus-independent

Evaluates the supplied function cumulatively on successive members of the supplied array.

The function is defined formally below, in terms of the equivalent fn:fold-left function for sequences.

If the supplied array is empty, the function returns $init.

If the supplied array contains a single member $m, the function returns $init => $action($m).

If the supplied array contains two members $m and $n, the function returns $init => $action($m) => $action($n); and similarly for an input array with more than two members.

As with fn:fold-left, a processor may exit the iteration early if it can establish that all remaining calls on $action will return the accumulated value unchanged.

 array:fold-left( [ true(), true(), false() ], true(), fn($x, $y) { $x and $y } ) false() Returns true if every member of the input array has an effective boolean value of true. array:fold-left( [ true(), true(), false() ], false(), fn($x, $y) { $x or $y } ) true() Returns true if at least one member of the input array has an effective boolean value of true. array:fold-left( [ 1, 2, 3 ], [], fn($x, $y) { [ $x, $y ] } ) [ [ [ [], 1 ], 2 ], 3 ]

A note was added stating that processors may exit the iteration early if the result can no longer change.

 deterministic context-independent focus-independent

Evaluates the supplied function cumulatively on successive values of the supplied array.

The function is defined formally below, in terms of the equivalent fn:fold-right function for sequences.

If the supplied array is empty, the function returns $init.

If the supplied array contains a single member $m, the function returns $action($m, $init).

If the supplied array contains two members $m and $n, the function returns $action($m, $action($n, $init)); and similarly for an input array with more than two members.

As with fn:fold-left, a processor may exit the iteration early if it can establish that all remaining calls on $action will return the accumulated value unchanged.

 array:fold-right( [ true(), true(), false() ], true(), fn($x, $y) { $x and $y } ) false() Returns true if every member of the input array has an effective boolean value of true. array:fold-right( [ true(), true(), false() ], false(), fn($x, $y) { $x or $y } ) true() Returns true if at least one member of the input array has an effective boolean value of true. array:fold-right( [ 1, 2, 3 ], [], fn($x, $y) { [ $x, $y ] } ) [ 1, [ 2, [ 3, [] ] ] ]

A note was added stating that processors may exit the iteration early if the result can no longer change.

 deterministic context-independent focus-independent

Returns an array obtained by evaluating the supplied function once for each pair of members at the same position in the two supplied arrays.

Informally, the function applies $action to each pair of values in corresponding positions within $array1 and $array2, ignoring any excess values if one array is longer than the other. The results are then assembed into a new array whose size is equal to the shorter of the two input arrays.

If the arrays have different size, excess members in the longer array are ignored.

 array:for-each-pair( [ "A", "B", "C" ], [ 1, 2, 3 ], fn($x, $y) { array { $x, $y }} ) [ [ "A", 1 ], [ "B", 2 ], [ "C", 3 ] ] let $array := [ "A", "B", "C", "D" ] return array:for-each-pair( $array, array:tail($array), concat#2 ) [ "AB", "BC", "CD" ] [ "1: 3", "2: 8", "3: 3" ]

The $action callback function now accepts an optional position argument.

 deterministic context-independent focus-independent

Returns an array obtained by evaluating the supplied function once for each item in the input sequence.

Informally, the function applies the function to each item in the input sequence, and the resulting sequence becomes one member of the returned array.

 array:of-members( for-each($input, fn($item, $pos) { [$action($item, $pos)]/. } ) )

The single-argument function array:build($input) is equivalent to the XPath expression array { $input }, but it is useful to have this available as a function.

The two-argument form facilitates the construction of arrays whose members are arbitrary sequences.

 array:build(1 to 5) [ 1, 2, 3, 4, 5 ] array:build(1 to 5, fn { 2 * . }) [ 2, 4, 6, 8, 10 ] array:build(1 to 5, fn { 1 to . }) [ 1, (1, 2), (1, 2, 3), (1, 2, 3, 4), (1, 2, 3, 4, 5) ] array:build(("red", "green", "blue"), characters#1) [ ("r", "e", "d"), ("g", "r", "e", "e", "n"), ("b", "l", "u", "e") ] array:build(1 to 5, fn { array { 1 to . } }) [ [ 1 ], [ 1, 2 ], [ 1, 2, 3 ], [ 1, 2, 3, 4 ], [ 1, 2, 3, 4, 5 ] ] array:build( (0x41 to 0x48) ! char(.), fn($char, $pos) { if ($pos mod 2 = 0) then lower-case($char) else $char } ) [ "A", "b", "C", "d", "E", "f", "G", "h" ]

New in 4.0

 deterministic context-independent focus-independent

Delivers the contents of an array as a sequence of JNodes.

The members of the array are delivered as a sequence of JNodes. The effect of the function is equivalent to the expression jtree($array)/child::*.

The JNodes that are returned have the following properties:

Property Value
·jvalue· The content of the array member
·jparent· The root JNode that encapsulates the array as a whole
·jposition· The integer value 1
·jkey· The one-based index of the member within the array.
jtree($array)/child::*

This function is the inverse of array:of-members.

 array:members([]) () array:members([ 1 to 5 ]) =!> jvalue() 1, 2, 3, 4, 5 array:members([ (1, 1), (2, 4), (3, 9), (4, 16), (5, 25) ]) ! sum(jvalue()) 2, 6, 12, 20, 30 let $array := [ "any array" ] return deep-equal( $array, array:of-members(array:members($array)) ) true()

New in 4.0

The function now returns JNodes.

 deterministic context-independent focus-independent

Delivers the contents of an array as a sequence of single-member arrays.

The members of the array are delivered as a sequence of single-member arrays. Each returned array encapsulates the value of one member of $array.

 dm:iterate-array($array, fn($member) { array:append([], $member) })

The function call array:split($array) produces the same result as the expression for member $m in $array return [ $m ].

The expression $A => array:split() => array:join(), applied to any array $A, returns the original array $A.

 array:split([]) () array:split([ () ]) [ () ] array:split([ 1 to 5 ]) [ (1, 2, 3, 4, 5) ] array:split( array { 1 to 5 } ) [ 1 ], [ 2 ], [ 3 ], [ 4 ], [ 5 ] array:split( [ (1, 1), (2, 4), (3, 9), (4, 16), (5, 25) ] ) ! sum(.) 2, 6, 12, 20, 30 let $array := [ "any array" ] return deep-equal( $array, array:join(array:split($array)) ) true()

New in 4.0

 deterministic context-independent focus-independent

Constructs an array from a sequence of JNodes.

The input items must be JNodes, as defined in the type signature. Each JNode in the input produces one member in the constructed array; the value of the member is the ·jvalue· property of the JNode. The other properties of the input JNodes are ignored. Order is retained.

 fold-left($input, [], fn($array, $jnode) { array:append($array, jvalue($jnode)) })

This function is the inverse of array:members. The two functions, used in conjunction, allow arrays to be decomposed and reconstructed in arbitrary ways. For example, given two arrays $A and $B of the same length, they can be combined pairwise into a single array with the expression:

array:of-members( for-each-pair(array:of-members($A), array:of-members($B), op(','))) array:of-members(()) [] array:of-members({'x':23, 'y':(1 to 5)}/y) [ (1, 2, 3, 4, 5) ] array:of-members((1 to 5) =!> jtree()) [ 1, 2, 3, 4, 5 ] array:of-members((1 to 3) ! jtree((., . × .)) ) [ (1, 1), (2, 4), (3, 9) ]

New in 4.0

The input to the function is now a sequence of JNodes.

 deterministic context-dependent focus-independent

Sorts a supplied array, based on the value of a sort key supplied as a function.

This function is retained for compatibility from version 3.1 of this specification. Version 4.0 introduces a more powerful functions, array:sort-by.

The function call array:sort($array, $collation, $key) is defined to have the same effect as the call array:sort-by($array, { 'key': $key, 'collation': $collation, 'order': 'ascending'}). See array:sort-by.

The result of the function is an array that contains all the members from $input, typically in a different order, the order being defined by the supplied sort key definitions.

 array:sort-by($array, { 'key': $key, 'collation': $collation, 'order': 'ascending' })

If the set of computed sort keys contains values that are not comparable using the lt operator then the sort operation will fail with a type error ().

array:sort([ 1, 4, 6, 5, 3 ]) [ 1, 3, 4, 5, 6 ] array:sort([ 1, -2, 5, 10, -10, 10, 8 ], (), abs#1) [ 1, -2, 5, 8, 10, -10, 10 ] array:sort([ [ 2, "i" ], [ 1, "e" ], [ 2, "g" ], [ 1, "f" ] ]) [ [ 1, "e" ], [ 1, "f" ], [ 2, "g" ], [ 2, "i" ] ] deterministic context-dependent focus-independent

Sorts a supplied array, based on the value of a number of sort keys supplied as functions.

The result of the function is an array that contains the same members as $array, typically in a different order, the order being defined by the supplied sort key definitions.

A sort key definition is an instance of the record type fn:array-sort-key-record (see ). Its key field supplies a sort key function, which is applied to each member of the input array to determine a sort key value; its collation field supplies a collation, used when comparing sort key values of type xs:string or xs:untypedAtomic; and its order field supplies an order direction.

When comparing values of types other than xs:string or xs:untypedAtomic, the collation is ignored (but an error may be reported if it is invalid). For more information see .

The number of sort key definitions is determined by the number of records supplied in the $keys argument. If the argument is absent or empty, the default is a single sort key definition in which every field takes its default value.

The result of the array:sort-by function is obtained as follows:

The result array contains the same members as $array, but generally in a different order.

The sort key definitions are established as described above. The sort key definitions are in major-to-minor order. That is, the position of two values $A and $B in the result sequence is determined first by the relative magnitude of their primary sort key values, which are computed by evaluating the sort key function in the first sort key definition. If those two sort key values are equal, then the position is determined by the relative magnitude of their secondary sort key values, computed by evaluating the sort key function in the second sort key definition, and so on.

When a pair of corresponding sort key values of $A and $B are found to be not equal, then $A precedes $B in the result sequence if both the following conditions are true, or if both conditions are false:

The sort key value for $A is less than the sort key value for $B, as defined below.

The order direction in the corresponding sort key definition is "ascending".

If all the sort key values for $A and $B are pairwise equal, then $A precedes $B in the result sequence if and only if $A precedes $B in the input sequence.

That is, the sort is stable.

Each sort key value for a given array member is obtained by applying the sort key function of the corresponding sort key definition to that member. The result of this function is in the general case a sequence of atomic items. Two sort key values $a and $b are compared as follows:

Let $C be the collation in the corresponding sort key definition.

Let $REL be the result of evaluating op:lexicographic-compare($key($A), $key($B), $C) where op:lexicographic-compare($a, $b, $C) is defined as follows:

if (empty($a) and empty($b)) then 0 else if (empty($a)) then -1 else if (empty($b)) then +1 else let $rel = op:simple-compare(head($a), head($b), $C) return if ($rel eq 0) then op:lexicographic-compare(tail($a), tail($b), $C) else $rel

Here op:simple-compare($k1, $k2) is defined as follows:

if ($k1 instance of (xs:string | xs:anyURI | xs:untypedAtomic) and $k2 instance of (xs:string | xs:anyURI | xs:untypedAtomic)) then compare($k1, $k2, $C) else if ($k1 instance of xs:numeric and $k2 instance of xs:numeric) then compare($k1, $k2) else if ($k1 eq $k2) then 0 else if ($k2 lt $k2) then -1 else +1

This raises an error if two keys are not comparable, for example if one is a string and the other is a number, or if both belong to a non-ordered type such as xs:QName.

If $REL is zero, then the two sort key values are deemed equal; if $REL is -1 then $a is deemed less than $b, and if $REL is +1 then $a is deemed greater than $b

 array:members() => fn:sort-by( for $key-spec in ($keys otherwise {}) return map:put($key-spec, 'key', fn($member as record(value)) as xs:anyAtomicType* { map:get($key-spec, 'key', fn:data#1)(map:get($member, 'value')) } ) => array:of-members() ]]>

If the set of computed sort keys contains values that are not comparable using the lt operator then the sort operation will fail with a type error ().

The function is a generalization of the array:sort function available in 3.1, which is retained for compatibility. The enhancements allow multiple sort keys to be defined, each potentially with a different collation, and allow sorting in descending order.

If the sort key for an item evaluates to the empty sequence, the effect of the rules is that this item precedes any value for which the key is non-empty. This is equivalent to the effect of the XQuery option empty least. The effect of the option empty greatest can be achieved by adding an extra sort key definition with {'key': fn{empty(K(.)}}: when comparing boolean sort keys, false precedes true.

 array:sort-by([1, 4, 6, 5, 3], {}) [1, 3, 4, 5, 6] array:sort-by([1, 4, 4e0, 6, 5, 3], {'order': 'descending'}) [6, 5, 4, 4e0, 3, 1] array:sort-by([(1,4,3), 4, (5,6), 2], ({'key': count#1}, {})) [2, 4, (5,6), (1,4,3)]

New in 4.0.

 deterministic context-independent focus-independent

Sorts a supplied array, according to the order induced by the supplied comparator functions.

Informally, the members of the supplied $array are sorted into an order based on the result of evaluating the supplied $comparators. The result is a sorted array.

Each comparator function takes two values and returns an xs:integer that defines the relationship between these values, following the conventions of the fn:compare function. Specifically, when a comparator $c is used to compare two values $a and $b, it must return a negative integer if $a is to be sorted before $b, zero if they are considered equal, and a positive integer if $a is to be sorted after $b.

There may be more than one comparator, representing sort keys in major to minor order. To determine the relative position of two members $a and $b:

The first comparator is called: $comparators[1]($a, $b). If the result is non-zero, this determines the relative position of $a and $b in the result array, and any further comparators can be ignored.

If the Nth comparator returns zero, then:

If this is the last comparator, then the two members are considered equal, and their relative position in the result sequence will be the same as their relative position in the input sequence (that is, the sort is stable).

Otherwise, the next comparator is evaluated, and so on, until the last comparator is reached or the result of a comparator is non-zero.

To ensure that the sorting algorithm produces predictable results (indeed, to ensure that it terminates), it is necessary for the comparators to have certain properties. Specifically, for every comparator C:

C must be deterministic (if called twice with the same arguments, it must deliver the same result).

Every value must be equal to itself: C($a, $a) must be zero.

The ordering must be consistent: if C($a, $b) < 0, then C($b, $a) > 0, and vice versa, and similarly, if C($a, $b) = 0, then C($b, $a) = 0.

The ordering must be transitive: if C($a, $b) < 0 and C($b, $c) < 0, then C($a, $c) < 0.

If a comparator function raises an error when processing any pair of members from the input array (for example, if the comparator function is fn:compare#2 and one of the members is not coercible to xs:anyAtomicType), then the evaluation of fn:sort-with fails with that error.

In general it is unpredictable which pairs of members from the input array will actually be compared using each comparator function. However, a comparator function must not be called to compare two members if they have been determined as unequal by an earlier comparator function.

 array:sort-with([1, 4, 6, 5, 3], compare#2) [1, 3, 4, 5, 6] array:sort-with([1, 4, 6, 5, 3], op('-')) [1, 3, 4, 5, 6] array:sort-with([1, 4, 4e0, 6, 5, 3], fn($a, $b) { compare($b, $a) }) [6, 5, 4, 4e0, 3, 1] array:sort-with( [ { "a": 1, "b": 20 }, { "a": 5, "b": 12 }, { "a": 1, "b": 3 } ], ( fn($x, $y) { compare($x?a, $y?a) }, fn($x, $y) { compare($x?b, $y?b) }) ) [ { "a": 1, "b": 3 }, { "a": 1, "b": 20 }, { "a": 5, "b": 12 } ]

New in 4.0

 deterministic context-independent focus-independent

Replaces any array appearing in a supplied sequence with the members of the array, recursively.

The function processes the items in the supplied sequence $input as follows:

An item that is an array is replaced by its members, retaining order.

Any other item is retained unchanged.

The process is then repeated so long as the sequence contains an array among its items.

The argument to the function will often be a single array item, but this is not essential.

Unlike atomization, this function retains any nodes contained in the array.

 array:flatten([ 1, 4, 6, 5, 3 ]) 1, 4, 6, 5, 3 array:flatten(([ 1, 2 ], [ [ 10, 11 ], 12 ], [], 13)) 1, 2, 10, 11, 12, 13 array:flatten([ (1, 0), (1, 1), (0, 1), (0, 0) ]) 1, 0, 1, 1, 0, 1, 0, 0 deterministic context-independent focus-independent

Returns the sequence concatenation of the members of an array.

The function returns the sequence concatenation of the members of $array, retaining order.

 dm:iterate-array($array, fn($member, $pos) { $member })

Unlike array:flatten, the function does not apply recursively to nested arrays.

If $A is a single array item, then array:items($A) returns the same result as $A?*.

 array:items(["one", "two", "three"]) "one", "two", "three" array:items(["one", ("two", "three")]) "one", "two", "three" array:items(["one", ("two", "three"), ()]) "one", "two", "three" array:items(["one", ["two", "three"]]) "one", ["two", "three"] array:items([ (), 1, (2 to 4), [ 5 ] ]) 1, 2, 3, 4, [ 5 ]

New in 4.0

 deterministic context-dependent focus-dependent

Provides access to the public functions and global variables of a dynamically loaded XQuery library module.

The function loads an implementation-defined set of modules having the target namespace $module-uri.

The $options argument can be used to control the way in which the function operates. The option parameter conventions apply.

If the query module is retrieved as an external resource, this is subject to the trust level of the calling code. In addition, the ability of the loaded query module to access additional resources is subject to the value of the supplied trusted option.

Versions of XQuery prior to 4.0 do not define any constraints on access to external resources. Many XQuery implementations, however, provide such mechanisms. An implementation of fn:load-xquery-module that allows execution of an untrusted query must ensure that the ability of that query to access resources is appropriately restricted, regardless of the version of XQuery in use.

 The minimum level of the XQuery language that the processor must support. xs:decimal The version given in the prolog of the library module; or implementation-defined if this is absent. Indicates whether the returned query module is trusted to access external resources. This applies both to resources statically referenced in the query module (such as imported schemas and imported library modules), and to resources accessed dynamically by invoking functions in the retrieved module, for example by use of the fn:doc function. xs:boolean false() The loaded query has the same level of trust as the caller, and may therefore access all external resources available to the caller. The functions and variables in the returned XQuery module are untrusted, and are therefore unable to access external resources unless these have been made explicitly available by a trusted caller. A sequence of URIs (in the form of xs:string values) which may be used or ignored in an implementation-defined way. xs:string* Empty sequence The content of the query module as a string. When this option is a non-empty string, the location-hints option is ignored. The static base URI of the dynamically loaded module is the same as the executable base URI of the caller. xs:string "" The value to be used as the initial context value when evaluating global variables in the library module. Supplying the empty sequence indicates the absence of a context value. If the library module specifies a required type for the context value, then the supplied value must conform to this type, without conversion. item()* Absent An alternative name for the context-value option, retained for compatibility with earlier versions; it constrains the value to a single item. Supplying the empty sequence is equivalent to omitting the entry from the map, and indicates the absence of a context value. Supplying both this option and the context-value option is an error. item()? Absent Values for external variables defined in the library module. Values must be supplied for external variables that have no default value, and may be supplied for external variables that do have a default value. The supplied value must conform to the required type of the variable, without conversion. The map contains one entry for each external variable: the key is the variable’s name, and the associated value is the variable’s value. The option parameter conventions do not apply to this contained map. map(xs:QName, item()*) The empty map Values for vendor-defined configuration options for the XQuery processor used to process the request. The key is the name of an option, expressed as a QName: the namespace URI of the QName should be a URI controlled by the vendor of the XQuery processor. The meaning of the associated value is implementation-defined. Implementations should ignore options whose names are in an unrecognized namespace. The option parameter conventions do not apply to this contained map. map(xs:QName, item()*) The empty map

The result of the function is a map R with two entries, as defined in .

The static and dynamic context of the library module are established according to the rules in .

It is implementation-defined whether constructs in the library module are evaluated in the same execution scope as the calling module.

The library module that is loaded may import other modules using an import module declaration. The result of fn:load-xquery-module does not include global variables or functions declared in such a transitively imported module. However, the options map supplied in the function call may (and if no default is defined, must) supply values for external variables declared in transitively loaded library modules.

The library module that is loaded may import schema declarations using an import schema declaration. It is implementation-defined whether schema components in the in-scope schema definitions of the calling module are automatically added to the in-scope schema definitions of the dynamically loaded module. The in-scope schema definitions of the calling and called modules must be consistent, according to the rules defined in .

Where nodes are passed to or from the dynamically loaded module, for example as an argument or result of a function, they should if possible retain their node identity, their base URI, their type annotations, and their relationships to all other nodes in the containing tree (including ancestors and siblings). If this is not possible, for example because the only way of passing nodes to the chosen XQuery implementation is by serializing and re-parsing, then a node may be passed in the form of a deep copy, which may lose information about the identity of the node, about its ancestors and siblings, about its base URI, about its type annotations, and about its relationships to other nodes passed across the interface.

If $module-uri is a zero length string, a dynamic error is raised .

If the implementation is not able to find a library module with the specified target namespace, an error is raised .

If a static error (including a statically detected type error) is encountered when processing the library module, a dynamic error is raised .

If a value is supplied for the initial context value or for an external variable and the value does not conform to the required type declared in the dynamically loaded module, a dynamic error is raised . The same error is raised if values are supplied for both the context-value and the context-item options.

If no suitable XQuery processor is available, a dynamic error is raised . This includes (but is not limited to) the following cases:

No XQuery processor is available;

Use of the function has been disabled;

No XQuery processor supporting the requested version of XQuery is available;

No XQuery processor supporting the optional Module Feature is available.

If a dynamic error (including a dynamically detected type error) is encountered when processing the module (for example, when evaluating its global variables), the dynamic error is returned as is.

If a function declaration F in the loaded module declares (say) four parameters of which one is optional, its arity range will be from 3 to 4, so the result will include two function items corresponding to F#3 and F#4. In the lower-arity function item, F#3, the fourth parameter will take its default value. If the expression that initializes the default value is context sensitive, the static and dynamic context for its evaluation are the static and dynamic contexts of the fn:load-xquery-module function call itself.

As with all other functions in this specification, conformance requirements depend on the host language. For example, a host language might specify that provision of this function is optional, or that it is excluded entirely, or that implementations are required to support XQuery modules using a specified version of XQuery.

Even where support for this function is mandatory, it is recommended for security reasons that implementations should provide a user option to disable its use, or to disable aspects of its functionality.

The load-xquery-module function does not modify the static or dynamic context. Functions and variables from the loaded module become available within the result returned by the function, but they are not added to the static or dynamic context of the caller. This means, for example, that function-lookup will not locate functions from the loaded module.

 let $expr := "2 + 2" let $module := ` xquery version "4.0"; module namespace dyn="http://example.com/dyn"; declare %public variable $dyn:value := { $expr }; ` let $exec := load-xquery-module( "http://example.com/dyn", { 'content':$module } ) let $variables := $exec?variables return $variables( #Q{http://example.com/dyn}value ) 4

It has been clarified that loading a module has no effect on the static or dynamic context of the caller.

The return type is now specified more precisely.

A new option is provided to allow the content of the loaded module to be supplied as a string.

A context-value option has been added, accepting an arbitrary sequence. The context-item option is retained for compatibility.

 nondeterministic context-dependent focus-independent

Invokes a transformation using a dynamically loaded XSLT stylesheet.

This function loads an XSLT stylesheet and invokes it to perform a transformation.

The inputs to the transformation are supplied in the form of a map. The option parameter conventions apply to this map; they do not apply to any nested map unless otherwise specified.

The function first identifies the requested XSLT version, as follows:

If the xslt-version option is present, the requested XSLT version is the value of that option.

Otherwise, the requested XSLT version is the value of the [xsl:]version attribute of the outermost element in the supplied stylesheet or package.

The function then attempts to locate an XSLT processor that implements the requested XSLT version.

If a processor that implements the requested XSLT version is available, then it is used.

Otherwise, if a processor that implements a version later than the requested version is available, then it is used.

Otherwise, the function fails indicating that no suitable XSLT processor is available.

The phrase locate an XSLT processor includes the possibility of locating a software product and configuring it to act as an XSLT processor that implements the requested XSLT version.

If more than one XSLT processor is available under the above rules, then the one that is chosen may be selected according to the availability of requested features: see below.

Once an XSLT processor has been selected that implements a given version of XSLT, the processor follows the rules of that version of the XSLT specification. This includes any decision to operate in backwards or forwards compatibility mode. For example, if an XSLT 2.0 processor is selected, and the stylesheet specifies version="1.0", then the processor will operate in backwards compatibility mode; if the same processor is selected and the stylesheet specifies version="3.0", the processor will operate in forwards compatibility mode.

If the stylesheet to be executed is retrieved as an external resource, this is subject to the trust level of the calling code. In addition, the ability of the loaded stylesheet to access additional resources is subject to the value of the supplied trusted option.

Versions of XSLT prior to 4.0 do not define any constraints on access to external resources. Many XSLT implementations, however, provide such mechanisms. An implementation of fn:transform that allows an XSLT processor to execute an untrusted stylesheet must ensure that the ability of that stylesheet to access resources is appropriately restricted, regardless of the version of XSLT.

The combinations of options that are relevant to each version of XSLT, other than xslt-version itself, are listed below. This is followed by a table giving the meaning of each option.

For invocation of an XSLT 1.0 processor (see ), the supplied options must include all of the following (if anything else is present, it is ignored):

The stylesheet, provided by supplying exactly one of the following:

stylesheet-location stylesheet-node stylesheet-text

The source tree, provided as the value of the source-node option.

Zero or more of the following additional options:

stylesheet-base-uri stylesheet-params (defaults to the empty map) initial-mode (defaults to the stylesheet’s default mode) delivery-format (defaults to document) serialization-params (defaults to the empty map) enable-messages (default is implementation-defined) requested-properties (default is the empty map) trusted (default is false) vendor-options (defaults to the empty map) cache (default is implementation-defined)

For invocation of an XSLT 2.0 processor (see ), the supplied options must include all of the following (if anything else is present, it is ignored):

The stylesheet, provided by supplying exactly one of the following:

stylesheet-location stylesheet-node stylesheet-text

Invocation details, as exactly one of the following:

For apply-templates invocation, all of the following:

source-node

Optionally, initial-mode (defaults to the stylesheet’s default mode)

For call-template invocation, all of the following:

initial-template

Optionally, source-node

Zero or more of the following additional options:

stylesheet-base-uri stylesheet-params (defaults to the empty map) base-output-uri (defaults to absent) delivery-format (defaults to document) serialization-params (defaults to the empty map) enable-messages (default is implementation-defined) enable-trace (default is implementation-defined) post-process (defaults to absent) requested-properties (default is the empty map) trusted (default is false) vendor-options (defaults to the empty map) cache (default is implementation-defined)

For invocation of an XSLT 3.0 or XSLT 4.0 processor (see ), the supplied options must include all of the following (if anything else is present, it is ignored):

The stylesheet, provided either by supplying exactly one of the following:

stylesheet-location stylesheet-node stylesheet-text

Or by supplying exactly one of the following:

package-location package-node package-text package-name plus optionally package-version

Invocation details, as exactly one of the following combinations:

For apply-templates invocation, all of the following:

Exactly one of source-node, source-location, or initial-match-selection

Optionally, initial-mode

Optionally, template-params

Optionally, tunnel-params

For call-template invocation using an explicit template name, all of the following:

initial-template

Optionally, template-params

Optionally, tunnel-params

Optionally, source-node

For call-template invocation using the defaulted template name xsl:initial-template, all of the following:

Optionally, template-params

Optionally, tunnel-params

If the source-node or source-locationoption is present and initial-template is absent, then apply-templates invocation will be used. To use call-template invocation on the template named xsl:initial-template while also supplying a context item for use when evaluating global variables, either (a) supply the context item using the global-context-item option, or (b) supply source-node, and set the initial-template option explicitly to the QName xsl:initial-template

For call-function invocation, all of the following:

initial-function

function-params

The invocation method can be determined as the first of the following which applies:

If initial-function is present, then call-function invocation.

If initial-template is present, then call-template invocation.

If source-node or source-location or initial-match-selection is present, then apply-templates invocation.

Otherwise, call-template invocation using the default entry point xsl:initial-template.

Zero or more of the following additional options:

stylesheet-base-uri static-params (defaults to the empty map) stylesheet-params (defaults to the empty map) global-context-item (defaults to absent) base-output-uri (defaults to absent) delivery-format serialization-params (defaults to the empty map) enable-assertions (default is false) enable-messages (default is implementation-defined) enable-trace (default is implementation-defined) requested-properties (default is the empty map) post-process (defaults to absent) trusted (default is false) vendor-options (defaults to the empty map) cache (default is implementation-defined)

The meanings of each option are defined in the table below.

1.0, 2.0, 3.0, 4.0 The URI of the principal result document; also used as the base URI for resolving relative URIs of secondary result documents. If the value is a relative reference, it is resolved against the executable base URI of the fn:transform function call. xs:string The effect of not supplying a base output URI is defined by the XSLT specification; the implementation may supply a default, for example the current working directory. If the fn:transform function is called from XSLT, then the recommended default is the current output URI of the calling transformation. 1.0, 2.0, 3.0, 4.0 This option has no effect on the result of the transformation but may affect efficiency. The value true indicates an expectation that the same stylesheet is likely to be used for more than one transformation; the value false indicates an expectation that the stylesheet will be used once only. xs:boolean true 1.0, 2.0, 3.0, 4.0 The manner in which the transformation results should be delivered. Applies both to the principal result document and to secondary result documents created using xsl:result-document. xs:string document If the relevant xsl:output or xsl:result-document element specifies build-tree="no" (applies to XSLT 3.0 or higher), then the default is raw. The result is delivered as a document node. The result is delivered as a string, representing the results of serialization. Note that (as with the fn:serialize function) the final encoding stage of serialization (which turns a sequence of characters into a sequence of octets) is either skipped, or reversed by decoding the octet stream back into a character stream. The result of the initial template or function is returned as an arbitrary XDM value (after conversion to the declared type, but without wrapping in a document node, and without serialization): when this option is chosen, the returned map contains the raw result. The serialized result is written to persistent storage. This means that the fn:transform function has side-effects and becomes nondeterministic, so the option should be used with care, and the precise behavior may be . When this option is used, the URIs used for the base-output-uri and the URIs of any secondary result documents must be writable locations. 3.0, 4.0 Indicates whether any xsl:assert instructions in the stylesheet are to be evaluated. xs:boolean false 1.0, 2.0, 3.0, 4.0 Indicates whether any xsl:message instructions in the stylesheet are to be evaluated. The destination and formatting of any such messages is . xs:boolean Implementation-defined. 2.0, 3.0, 4.0 Indicates whether any fn:trace functions in the stylesheet are to generate diagnostic messages. The destination and formatting of any such messages is implementation-defined. xs:boolean Implementation-defined. 3.0, 4.0 An array of values to be used as the arguments to the initial function call. The value is converted to the required type of the declared parameter using the function conversion rules. array(item()*) Empty array 3.0, 4.0 The value of the global context item, as defined in XSLT 3.0 item() The value of source-node, if supplied 3.0, 4.0 The name of the initial function to be called for call-function invocation. The arity of the function is inferred from the length of function-params. xs:QName n/a 3.0, 4.0 The value of the initial match selection, as defined in XSLT 3.0 item()* The value of source-node 1.0, 2.0, 3.0, 4.0 The name of the initial processing mode. xs:QName none 2.0, 3.0, 4.0 The name of a named template in the stylesheet to act as the initial entry point. xs:QName xsl:initial-template 3.0, 4.0 The name of the top-level stylesheet package to be invoked (an absolute URI) xs:string n/a 3.0, 4.0 The location of the top-level stylesheet package, as a relative or absolute URI xs:string n/a 3.0, 4.0 A document or element node containing the top-level stylesheet package xnode() n/a 3.0, 4.0 The top-level stylesheet package in the form of unparsed lexical XML. xs:string n/a 3.0, 4.0 The version of the top-level stylesheet package to be invoked. xs:string "*" (any version) 1.0, 2.0, 3.0, 4.0 A function that is used to post-process each result document of the transformation (both the principal result and secondary results), in whatever form it would otherwise be delivered (document, serialized, or raw). The first argument of the function is the key used to identify the result in the map return by the fn:transform function (for example, this will be the supplied base output URI in the case of the principal result, or the string “output” if no base output URI was supplied). The second argument is the actual value. The value that is returned in the result of the fn:transform function is the result of applying this post-processing.

If the implementation provides a way of writing or invoking functions with side-effects, this post-processing function might be used to save a copy of the result document to persistent storage (though in 4.0, this can also be achieved using the option delivery-format="file"). For example, if the implementation provides access to the EXPath File library , then a serialized document might be written to filestore by calling the file:write function. Similar mechanisms might be used to issue an HTTP POST request that posts the result to an HTTP server, or to send the document to an email recipient. The semantics of calling functions with side-effects are entirely implementation-defined.

If the primary purpose of the post-processing function is achieved by means of such side-effects, and if the actual results are not needed by the caller of the fn:transform function, then it does not matter what the post-processing function actually returns (it could be the empty sequence, for example).

Calls to fn:transform can potentially have side-effects even in the absence of the post-processing option, because the XSLT specification allows a stylesheet to invoke extension functions that have side-effects. The semantics in this case are implementation-defined.

 fn(xs:string, item()*) as item()* fn($a, $b) { $b } 1.0, 2.0, 3.0, 4.0 The keys in the map are QNames that could legitimately be supplied in a call to the XSLT system-property function; the values in the map are the requested settings of the corresponding property. The boolean values true and false are equivalent to the string values yes and no. As a special case, setting a value for xsl:version has no effect, because of the potential for conflict with other options. For example:

Setting xsl:product-name to a particular value requests a particular XSLT software product.

Setting xsl:product-version requests a specific version of that product.

Setting xsl:is-schema-aware to true requests a schema-aware processor.

Setting xsl:xsd-version to "1.1" requests a processor that supports XML Schema version 1.1.

 Setting a boolean property such as xsl:supports-dynamic-evaluation to false is interpreted as an explicit request for a processor in which the value of the property is false. The effect if the requests cannot be precisely met is implementation-defined. In some cases it may be appropriate to ignore the request or to provide an alternative (for example, a later version of the product than the one requested); in other cases it may be more appropriate to raise an error indicating that no suitable XSLT processor is available. map(xs:QName, xs:anyAtomicType) Empty map 1.0, 2.0, 3.0, 4.0 Serialization parameters for the principal result document. The supplied map follows the same rules that apply to a map supplied as the second argument of fn:serialize. These parameters interact with serialization parameters defined in the invoked stylesheet, as follows:

When a serialization parameter is present in the map, the corresponding value overrides or augments the value specified in the unnamed xsl:output declaration of the invoked stylesheet (or its default), following the same rules as when one xsl:output declaration overrides another with lower import precedence.

When a serialization parameter is supplied and the corresponding value is the empty sequence (for example, { "standalone": () }), any value specified in the unnamed xsl:output declaration of the invoked stylesheet is overridden by the default value.

When a serialization parameter is not supplied in the map (that is, when the key is absent) the value that applies is the value appearing in the unnamed xsl:output declaration, or its default.

map(xs:anyAtomicType, item()*) Empty map 1.0, 2.0, 3.0, 4.0 When source-location is supplied then it is expected to be an absolute or relative URI identifying an unparsed XML document. If relative, it is resolved against the static base URI of the fn:transform function call. The document at this location is parsed, and the document node acts as the initial-match-selection, that is, stylesheet execution starts by applying templates to this node. If the initial mode is streamable and a streaming XSLT 3.0 or XSLT 4.0 processor is used, then the supplied document is processed in streaming mode. xnode() n/a 1.0, 2.0, 3.0, 4.0 When source-node is supplied then the global-context-item (the context item for evaluating global variables) is the root of the tree containing the supplied node. In addition, for apply-templates invocation, the source-node acts as the initial-match-selection, that is, stylesheet execution starts by applying templates to this node. xnode() n/a 3.0, 4.0 The values of static parameters defined in the stylesheet; the keys are the names of the parameters, and the associated values are their values. The value is converted to the required type of the declared parameter using the coercion rules. map(xs:QName, item()*) Empty map 1.0, 2.0, 3.0, 4.0 A string intended to be used as the static base URI of the principal stylesheet module. This value must be used if no other static base URI is available. If the supplied stylesheet already has a base URI (which will generally be the case if the stylesheet is supplied using stylesheet-node or stylesheet-location) then it is implementation-defined whether this parameter has any effect. If the value is a relative reference, it is resolved against the executable base URI of the fn:transform function call. xs:string n/a 1.0, 2.0, 3.0, 4.0 URI that can be used to locate the principal stylesheet module. If relative, it is resolved against the executable base URI of the fn:transform function call. The value also acts as the default for stylesheet-base-uri. xs:string n/a 1.0, 2.0, 3.0, 4.0 Root of the tree containing the principal stylesheet module, as a document or element node. The base URI of the node acts as the default for stylesheet-base-uri. xnode() n/a 1.0, 2.0, 3.0, 4.0 A map holding values to be supplied for stylesheet parameters. The keys are the parameter names; the values are the corresponding parameter values. The values are converted if necessary to the required type using the coercion rules. The default is the empty map. map(xs:QName, item()*) Empty map 1.0, 2.0, 3.0, 4.0 The principal stylesheet module in the form of unparsed lexical XML. xs:string n/a 3.0, 4.0 The values of non-tunnel parameters to be supplied to the initial template, used with both apply-templates and call-template invocation. Each value is converted to the required type of the declared parameter using the coercion rules. map(xs:QName, item()*) none 3.0, 4.0 The values of tunnel parameters to be supplied to the initial template, used with both apply-templates and call-template invocation. Each value is converted to the required type of the declared parameter using the coercion rules. map(xs:QName, item()*) Empty map Indicates whether the target stylesheet is trusted to access external resources. This applies both to resources statically referenced by the stylesheet (for example using xsl:include, xsl:import, xsl:use-package, or xsl:import-schema), and to resources accessed dynamically by executing the retrieved stylesheet, for example by use of the fn:doc or unparsed-text function. xs:boolean false() The loaded stylesheet has the same level of trust as the caller, and may therefore access all external resources available to the caller. The loaded stylesheet is untrusted, and is therefore unable to access external resources unless these have been made explicitly available by a trusted caller. 1.0, 2.0, 3.0, 4.0 Values for vendor-defined configuration options for the XSLT processor used to process the request. The key is the name of an option, expressed as a QName: the namespace URI of the QName should be a URI controlled by the vendor of the XSLT processor. The meaning of the associated value is implementation-defined. Implementations should ignore options whose names are in an unrecognized namespace. Default is the empty map. { xs:QName, item()* } Empty map 1.0, 2.0, 3.0, 4.0 The minimum level of the XSLT language that the processor must support. xs:decimal The [xsl:]version attribute at the outermost level of the stylesheet.

The result of the transformation is returned as a map. There is one entry in the map for the principal result document, and one for each secondary result document. The key is a URI in the form of an xs:string value. The key for the principal result document is the base output URI if specified, or the string "output" otherwise. The key for secondary result documents is the URI of the document, as an absolute URI. The associated value in each entry depends on the requested delivery format. If the delivery format is document, the value is a document node. If the delivery format is serialized, the value is a string containing the serialized result.

Where nodes are passed to or from the transformation, for example as the value of a stylesheet parameter or the result of a function, they should if possible retain their node identity, their base URI, their type annotations, and their relationships to all other nodes in the containing tree (including ancestors and siblings). If this is not possible, for example because the only way of passing nodes to the chosen XSLT implementation is by serializing and re-parsing, then a node may be passed in the form of a deep copy, which may lose information about the identity of the node, about its ancestors and siblings, about its base URI, about its type annotation, and about its relationships to other nodes passed across the interface.

It is implementation-defined whether the XSLT transformation is executed within the same execution scope as the calling code.

The function is nondeterministic in that it is implementation-dependent whether running the function twice against the same inputs produces identical results. The results of two invocations may differ in the identity of any returned nodes; they may also differ in other respects, for example because the value of fn:current-dateTime is different for the two invocations, or because the contents of external documents accessed using fn:doc or xsl:source-document change between one invocation and the next.

A dynamic error is raised if the transformation cannot be invoked because no suitable XSLT processor is available. This includes (but is not limited to) the following cases:

No XSLT processor is available;

No XSLT processor supporting the requested version of XSLT is available;

The XSLT processor API does not support some requested feature (for example, the ability to supply tunnel parameters externally);

A dynamic error is raised if an error is detected in the supplied parameters (for example if two mutually exclusive parameters are supplied).

If a static or dynamic error is reported by the XSLT processor, this function fails with a dynamic error, retaining the XSLT error code.

A dynamic error is raised if the XSLT transformation invoked by a call on fn:transform fails with a static or dynamic error, and no more specific error code is available.

XSLT 1.0 does not define any error codes, so this is the likely outcome with an XSLT 1.0 processor. XSLT 2.0 and 3.0 do define error codes, but some APIs do not expose them. If multiple errors are signaled by the transformation (which is most likely to happen with static errors) then the error code should where possible be that of one of these errors, chosen arbitrarily; the processor may make details of additional errors available to the application in an implementation-defined way.

A dynamic error is raised if the use of this function (or of selected options) has been externally disabled, for example for security reasons.

A dynamic error is raised if the transformation produces output containing characters available only in XML 1.1, and the calling processor cannot handle such characters.

Recursive use of the fn:transform function may lead to catastrophic failures such as non-termination or stack overflow. No error code is assigned to such conditions, since they cannot necessarily be detected by the processor.

As with all other functions in this specification, conformance requirements depend on the host language. For example, a host language might specify that provision of this function is optional, or that it is excluded entirely, or that implementations are required to support a particular set of values for the xslt-version parameter.

Even where support for this function is mandatory, it is recommended for security reasons that implementations should provide a user option to disable its use, or to disable aspects of its functionality such as the ability to write to persistent resources.

The following example loads a stylesheet from the location render.xsl, applies it to a document loaded from test.xml, and uses an XPath expression to examine the result:

The new option delivery-format="file" is available.

The new option trusted is available.

 deterministic context-independent focus-independent

Returns a random number generator, which can be used to generate sequences of random numbers.

The function returns a random number generator. A random number generator is represented as a value of type random-number-generator-record, defined in .

Calling the fn:random-number-generator function with the empty sequence as $seed is equivalent to calling the single-argument form of the function with an implementation-dependent seed.

If a $seed is supplied, it may be an atomic item of any type.

Both forms of the function are : calling the function twice with the same arguments, within a single execution scope, produces the same results.

The next and permute functions returned by a given random number generator are also . If $rng is the result of a call to random-number-generator, then:

The value of $rng?next()?number = $rng?next()?number will always be true.

For any sequence $seq, deep-equal($rng?permute($seq), $rng?permute($seq) will always be true.

The value of the number entry should be such that all eligible xs:double values are equally likely to be chosen the distribution of numbers is uniform: for example, the probability of the number being in the range 0.1e0 to 0.2e0 is the same as the probability of its being in the range 0.8e0 to 0.9e0.

The function returned in the permute entry should be such that all permutations of the supplied sequence are equally likely to be chosen.

The map returned by the fn:random-number-generator function may contain additional entries beyond those specified here, but it must match the record type defined above. The meaning of any additional entries is implementation-defined. To avoid conflict with any future version of this specification, the keys of any such entries should start with an underscore character.

It is not meaningful to ask whether the functions returned in the next and permute functions resulting from two separate calls with the same seed are “the same function”, but the functions must be equivalent in the sense that calling them produces the same sequence of random numbers.

The repeatability of the results of function calls in different execution scopes is outside the scope of this specification. It is recommended that when the same seed is provided explicitly, the same random number sequence should be delivered even in different execution scopes; while if no seed is provided, the processor should choose a seed that is likely to be different from one execution scope to another. (The same effect can be achieved explicitly by using fn:current-dateTime() as a seed.)

The specification does not place strong conformance requirements on the actual randomness of the result; this is left to the implementation. It is desirable, for example, when generating a sequence of random numbers that the sequence should not get into a repeating loop; but the specification does not attempt to dictate this.

 random-number-generator()?permute(1 to 100) A random permutation of the integers in the range 1 to 100 random-number-generator()?permute($seq)[1 to (count($seq) idiv 10)] A 10% sample of the items in an input sequence $seq, chosen at random

The following XQuery code produces a random sequence of 200 xs:double values in the range zero to one:

declare %public function local:random-sequence($length as xs:integer) as xs:double* { local:random-sequence($length, random-number-generator()) }; declare %private function local:random-sequence( $length as xs:integer, $record as record(number as xs:double, next as fn(*)) ) as xs:double* { if ($length != 0) { $record?number, local:random-sequence($length - 1, $record?next()) } }; local:random-sequence(200)

An equivalent result can be achieved with fn:fold-left:

tail(fold-left( (1 to 200), random-number-generator(), fn($result) { head($result) ! (?next(), ?number), tail($result) } ))

The 3.1 specification suggested that every value in the result range should have the same chance of being chosen. This has been corrected to say that the distribution should be arithmetically uniform (because there are as many xs:double values between 0.01 and 0.1 as there are between 0.1 and 1.0).

 deterministic context-independent focus-independent

Returns true if every item in the input sequence matches a supplied predicate.

The function returns true if $input is empty, or if $predicate($item, $pos) returns true for every item of $input.

 count(filter($input, $predicate)) = count($input)

An error is raised if the $predicate function raises an error. In particular, when the default predicate fn:boolean#1 is used, an error is raised if an item has no effective boolean value.

It is possible for the supplied $predicate to be a function whose arity is less than two. The coercion rules mean that the additional parameters are effectively ignored. Frequently a predicate function will only consider the item itself, and disregard its position in the sequence.

The predicate is required to return either true, false, or the empty sequence (which is treated as false). A predicate such as fn { self::h1 } results in a type error because it returns a node, not a boolean.

The implementation may deliver a result as soon as one item is found for which the predicate returns false; it is not required to evaluate the predicate for every item, nor is it required to examine items sequentially from left to right.

 every(()) true() every((1 = 1, 2 = 2, 3 = 4)) false() every((), boolean#1) true() every((1, 3, 7), fn { . mod 2 = 1 }) true() every(-5 to +5, fn { . ge 0 }) false() every( ("January", "February", "March", "April", "September", "October", "November", "December"), contains(?, "r") ) true() every( ("January", "February", "March", "April", "September", "October", "November", "December") =!> contains("r") ) true() every((1, 2, number('NaN'))) false() The effective boolean value of NaN is false. every(1 to 5, fn($num, $pos) { $num = $pos }) true()
Morgawr
Sea giant
return every($dl/*, fn($elem, $pos) { name($elem) = ( if (($pos mod 2)) then "dt" else "dd" ) })]]> true()

New in 4.0

The $predicate callback function may return the empty sequence (meaning false).

 deterministic context-independent focus-independent

Returns a string containing a particular character or glyph.

The function returns a string, generally containing a single character or glyph, identified by $value.

The supplied value of $value must be one of the following:

A Unicode codepoint, supplied as an integer. For example fn:char(9) returns the tab character.

An HTML5 character reference name (often referred to as an entity name) as defined in (see §13.5, Named character references). The name is written with no leading ampersand and no trailing semicolon. For example fn:char("pi") represents the character U+03C0 and fn:char("nbsp") returns U+00A0.

A processor may recognize additional character reference names defined in other versions of HTML. Character reference names are case-sensitive.

In the event that the HTML5 character reference name identifies a string comprising multiple codepoints, that string is returned.

A backslash-escape sequence from the set \n (U+000A), \r (U+000D), \t (U+0009), \b (U+0008), or \f (U+000C) .

The result must consist of permitted characters. For example fn:char(0xDEAD) is invalid because it is in the surrogate range.

The function fails with a dynamic error if $value is not a valid representation of a or sequence of permitted characters.

Although all Unicode characters can appear in string literals (the delimiting quotation marks can be escaped by doubling them), some characters are not visually distinctive, so representing them by name may make code more readable. In addition, there may be contexts where it is necessary or prudent to write XPath expressions using ASCII characters only, for example where an expression is used in the query part of a URI.

A few HTML5 character reference names identify glyphs whose Unicode representation uses multiple codepoints. For example, the name NotEqualTilde refers to the glyph ≂̸ which is expressed using the two codepoints U+2242, U+0338. In such cases the string length of the result of the function will exceed one.

 char("aacute") "á" char("eth") "ð" char(9) codepoints-to-string(9) The character tab char("\t") codepoints-to-string(9) The character tab char(0x20) " " char(0x1D1CA) "𝇊" The character MUSICAL SYMBOL TEMPUS IMPERFECTUM CUM PROLATIONE PERFECTA char("NotEqualTilde") codepoints-to-string((8770, 824)) This HTML5 character reference name expands to multiple codepoints.

New in 4.0

 deterministic context-independent focus-independent

Splits the supplied string into a sequence of single-character strings.

The function returns a sequence of strings, each string having length 1, containing the corresponding character in $value.

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

 string-to-codepoints($value) ! codepoints-to-string(.) characters("Thérèse") "T", "h", "é", "r", "è", "s", "e" characters("") () characters(()) () characters("Banana") => index-of("a") 2, 4, 6 characters("stretch") => string-join("-") "s-t-r-e-t-c-h" "Banana" => characters() => reverse() => string-join() "ananaB"

New in 4.0

 deterministic context-independent focus-independent

Splits the supplied string into a sequence of single-grapheme strings.

The function returns a sequence of strings. Each string in the sequence contains one or more characters that collectively constitute a single extended grapheme cluster, as defined by .

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

The resultant sequence of strings are extended graphemes, not legacy graphemes (see ).

 graphemes("a" || char(0x308) || "b") "a" || char(0x308), "b" a + ◌̈ + b, three characters, two graphemes graphemes("") () graphemes(()) () graphemes(char('\r') || char('\n')) char('\r') || char('\n') Carriage return + line feed, two characters, one grapheme graphemes(char(0x1F476) || char(0x200D) || char(0x1F6D1)) char(0x1F476) || char(0x200D) || char(0x1F6D1) 👶 +ZWJ + 🛑, three characters, one grapheme graphemes("कत") "क", "त" क + त, two characters, two graphemes graphemes("क" || char(0x93C) || char(0x200D) || char(0x94D) || "त") "क" || char(0x93C) || char(0x200D) || char(0x94D) || "त" क + ◌़ + ZWJ + ◌् + त, five characters, one grapheme

New in 4.0

 deterministic context-independent focus-independent

Returns a string created by extending a value to a given length with padding characters.

The coercion rules ensure that the supplied $value argument is first converted to an atomic item by applying atomization. If $value is the empty sequence, the input string is the zero-length string; otherwise it is the result of casting the atomized item to an xs:string.

The $options argument controls the padding. The apply.

The string that is repeated to form the padding characters. It must not be a zero-length string. xs:string " " The side of the input string on which the padding characters are added. enum('start', 'end', 'both') "end"

If the input string contains $length or more characters, it is returned unchanged: the function never truncates. Otherwise, padding characters are added to bring its length up to $length characters. They are formed by repeating the padding option as often as necessary and truncating the result on the right to the number of characters required: each run of padding characters is thus a prefix of the repeated padding string. For example, seven padding characters formed from "ab" are "abababa".

The side option determines where the padding characters are added: at the end of the input string, at its start, or divided between both sides. In the last case each of the two runs is formed independently, and if an odd number of padding characters is needed, the extra character is added at the end.

A dynamic error is raised if the value of the padding option is a zero-length string.

Padding a number to a fixed width, with leading zeroes or otherwise, can also be achieved with fn:format-integer and fn:format-number, which additionally allow the digits, the sign, and any grouping separators to be controlled.

 pad-string("abc", 6) "abc " pad-string("abc", 6, { "side": "start" }) " abc" pad-string("abc", 7, { "side": "both", "padding": "*" }) "**abc**" pad-string("abc", 8, { "side": "both", "padding": "*" }) "**abc***" pad-string("x", 5, { "padding": "0123456789", "side": "start" }) "0123x" pad-string("x", 8, { "padding": "0123456789", "side": "both" }) "012x0123" pad-string(xs:date("2026-07-12"), 14, { "padding": ".", "side": "both" }) "..2026-07-12.." pad-string("Chapter 1", 20, { "padding": "." }) "Chapter 1..........." pad-string((), 5, { "padding": "*" }) "*****" pad-string("abcdef", 3) "abcdef"

New in 4.0

 deterministic context-dependent focus-independent

Returns a value that is greater than or equal to every other value appearing in the input sequence.

The second argument, $collation, defaults to ().

Supplying an empty sequence as $collation is equivalent to supplying fn:default-collation(). For more information on collations see .

The third argument, $key, defaults to the function data#1.

Let $modified-key be the function:

fn($item) { $key($item) => data() ! ( if (. instance of xs:untypedAtomic) then xs:double(.) else . ) }

That is, the supplied function for computing key values is wrapped in a function that converts any xs:untypedAtomic values in its result to xs:double. This makes the function consistent with the behavior of fn:min and fn:max, but inconsistent with fn:sort, which treats untyped values as strings.

The result of the function is obtained as follows:

If the input is an empty sequence, the result is an empty sequence.

The input sequence is sorted, by applying the function fn:sort($input, $collation, $modified-key).

Let $C be the selected collation, or the default collation where applicable.

Let $B be the last item in the sorted sequence.

The function returns those items $A from the input sequence that are to $B, retaining their order.

If the set of computed keys contains xs:untypedAtomic values that are not castable to xs:double then the operation will fail with a dynamic error ().

If the set of computed keys contains values that are not comparable using the lt operator then the sort operation will fail with a type error ().

]]> highest($e/@*) ! name() "x" By default, untyped values are compared as numbers. highest($e/@*, (), string#1) ! name() "y" Here, the attribute values are compared as strings. highest(("red", "green", "blue"), (), string-length#1) "green" highest( ("red", "green", "blue"), key := { "red" : xs:hexBinary('FF0000'), "green": xs:hexBinary('008000'), "blue" : xs:hexBinary('0000FF') } ) "red" highest( ("red", "orange", "yellow", "green", "blue", "indigo", "violet"), key := string-length#1 ) "orange", "yellow", "indigo", "violet" highest(1 to 25, (), fn { . idiv 10 }) 20, 21, 22, 23, 24, 25 highest(//employee, (), fn { xs:decimal(salary) }) The employees having the highest salary.

New in 4.0

 deterministic context-independent focus-independent

Returns the positions in an input sequence of items that match a supplied predicate.

The result of the function is a sequence of integers, in monotonic ascending order, representing the 1-based positions in the input sequence of those items for which the supplied predicate function returns true. A return value of () from the predicate function is treated as false.

 for-each( $input, fn($item, $pos) { if ($predicate($item, $pos)) { $pos } } ) index-where((), boolean#1) () index-where((0, 4, 9), boolean#1) 2, 3 index-where(1 to 10, fn { . mod 2 = 0 }) 2, 4, 6, 8, 10 index-where( ("January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"), contains(?, "r") ) 1, 2, 3, 4, 9, 10, 11, 12 2 } )]]> 3, 5

New in 4.0

The $predicate callback function may return the empty sequence (meaning false).

 deterministic context-independent focus-independent

Returns true if the argument is the xs:float or xs:double value NaN.

The function returns true if $value is the xs:float or xs:double value NaN; otherwise it returns false.

 is-NaN(23) false() is-NaN("NaN") false() is-NaN(number("twenty-three")) true() is-NaN(math:sqrt(-1)) true()

New in 4.0

 deterministic context-independent focus-independent

Returns items from the input sequence prior to the first one that fails to match a supplied predicate.

The function returns all items in $input prior to the first one for which $predicate($item, $pos) returns the value false or ().

If every item in the sequence satisfies the predicate, then $input is returned in its entirety.

 for $item at $pos in $input while $predicate($item, $pos) return $item

There is no analogous drop-while or skip-while function, as found in some functional programming languages. The effect of drop-while($input, $predicate) can be achieved by calling fn:subsequence-where($input, fn { not($predicate(.)) }).

 take-while(10 to 20, fn { . le 12 }) 10, 11, 12 take-while(10 to 20, fn { . lt 100 }) 10 to 20 take-while((), boolean#1) () take-while( ("A", "B", "C", " ", "E"), fn { boolean(normalize-space()) } ) "A", "B", "C"

")/doc/* => take-while(fn { boolean(self::p) }) => count()]]> 2 take-while(starts-with(?, "A"))]]> "Aardvark", "Antelope" take-while(10 to 20, fn($num, $pos) { $num lt 18 and $pos lt 4 }) 10, 11, 12 take-while( characters("ABCD-123"), fn($ch, $pos) { $pos lt 4 and $ch ne '-' } ) => string-join() "ABC" take-while( ("A", "a", "B", "b", "C", "D", "d"), fn($ch, $pos) { matches($ch, if ($pos mod 2 eq 1) then "\p{Lu}" else "\p{Ll}") } ) "A", "a", "B", "b", "C"

New in 4.0

The $predicate callback function may return the empty sequence (meaning false).

 deterministic context-dependent focus-independent

Returns those items from a supplied sequence that have the lowest value of a sort key, where the sort key can be computed using a caller-supplied function.

The collation used by this function is determined according to the rules in .

Let $modified-key be the function:

fn($item) { $key($item) => data() ! ( if (. instance of xs:untypedAtomic) then xs:double(.) else . ) }

That is, the supplied function for computing key values is wrapped in a function that converts any xs:untypedAtomic values in its result to xs:double. This makes the function consistent with the behavior of fn:min and fn:max, but inconsistent with fn:sort, which treats untyped values as strings.

The result of the function is obtained as follows:

If the input is the empty sequence, the result is the empty sequence.

The input sequence is sorted, by applying the function fn:sort($input, $collation, $modified-key).

Let $C be the selected collation, or the default collation where applicable.

Let $B be the first item in the sorted sequence.

The function returns those items $A from the input sequence that are to $B, retaining their order.

If the set of computed keys contains xs:untypedAtomic values that are not castable to xs:double then the operation will fail with a dynamic error ().

If the set of computed keys contains values that are not comparable using the lt operator then the sort operation will fail with a type error ().

]]> lowest($e/@*) ! name() "z" By default, untyped values are compared as numbers. lowest($e/@*, (), string#1) ! name() "x" Here, the attribute values are compared as strings. lowest(("red", "green", "blue"), (), string-length#1) "red" lowest( ("red", "green", "blue"), key := { "red" : xs:hexBinary('FF0000'), "green": xs:hexBinary('008000'), "blue" : xs:hexBinary('0000FF') } ) "blue" lowest( ("April", "June", "July", "August"), key := string-length#1 ) "June", "July" lowest(1 to 25, (), fn { . idiv 10 }) 1, 2, 3, 4, 5, 6, 7, 8, 9 lowest(//employee, (), fn { xs:decimal(salary) }) The employees having the lowest salary.

New in 4.0

 deterministic context-independent focus-independent

Returns true if at least one item in the input sequence matches a supplied predicate.

The function returns true if (and only if) $predicate($item, $pos) returns true for at least one item of $input.

 exists(filter($input, $predicate))

An error is raised if the $predicate function raises an error. In particular, when the default predicate fn:boolean#1 is used, an error is raised if an item has no effective boolean value.

It is possible for the supplied $predicate to be a function whose arity is less than two. The coercion rules mean that the additional parameters are effectively ignored. Frequently a predicate function will only consider the item itself, and disregard its position in the sequence.

The predicate is required to return either true, false, or the empty sequence (which is treated as false). A predicate such as fn { self::h1 } results in a type error because it returns a node, not a boolean.

The implementation may deliver a result as soon as one item is found for which the predicate returns true; it is not required to evaluate the predicate for every item, nor is it required to examine items sequentially from left to right.

 some(()) false() some((1 = 1, 2 = 2, 3 = 4)) true() some((), boolean#1) false() some((1, 3, 7), fn { . mod 2 = 1 }) true() some(-5 to +5, fn { . ge 0 }) true() some( ("January", "February", "March", "April", "September", "October", "November", "December"), contains(?, "z") ) false() some( ("January", "February", "March", "April", "September", "October", "November", "December") =!> contains("r") ) true() some(("", 0, number('NaN'))) false() The effective boolean value in each case is false. some(reverse(1 to 5), fn($num, $pos) { $num = $pos }) true()

New in 4.0

The $predicate callback function may return the empty sequence (meaning false).

 deterministic context-dependent focus-independent

Returns true if all items in a supplied sequence (after atomization) are .

The collation used by this function is determined according to the rules in .

The result of the function fn:all-equal($values, $collation) is true if and only if the result of fn:count(fn:distinct-values($values, $collation)) le 1 is true (that is, if the sequence is empty, or if all the items in the sequence are equal under the rules of the fn:distinct-values function).

 all-equal((1, 2, 3)) false() all-equal((1, 1.0, 1.0e0)) true() all-equal("one") true() all-equal(()) true() all-equal((xs:float('NaN'), xs:double('NaN'))) true() all-equal( ("ABC", "abc"), "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) true() all-equal(//p/@class) Returns true if all p elements have the same value for @class. all-equal(* ! node-name()) Returns true if all element children of the context node have the same name.

New in 4.0. Originally proposed under the name fn:uniform

 deterministic context-dependent focus-independent

Returns true if no two items in a supplied sequence are .

The collation used by this function is determined according to the rules in .

The result of the function fn:all-different($values, $collation) is true if and only if the result of fn:count(fn:distinct-values($values, $collation)) eq fn:count($values) is true (that is, if the sequence is empty, or if all the items in the sequence are contextually unequal under the rules used by the fn:distinct-values function).

 all-different((1, 2, 3)) true() all-different((1, 1.0, 1.0e0)) false() all-different("one") true() all-different(()) true() all-different( ("ABC", "abc"), "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) false() all-different(//employee/@ssn) Returns true if no two employees have the same value for their @ssn attribute. all-different(* ! node-name()) Returns true if all element children of the context node have distinct names.

New in 4.0. Originally proposed under the name fn:unique

 deterministic context-independent focus-independent

Parses the URI provided and returns a map of its parts.

If $value is the empty sequence, the result is the empty sequence.

The function parses the $value provided, returning a map containing its constituent parts: scheme, authority components, path, etc. In addition to parsing URIs as defined by (and ), this function also attempts to account for strings that are not valid URIs but that often appear in URI-adjacent spaces, such as file names. Not all such strings can be successfully parsed as URIs.

The following options are available:

Indicates that deprecated URI features should be returned xs:boolean false Indicates that a port number that is the same as the default port for a given scheme should be omitted. xs:boolean false Indicates that an input URI that begins with two or more leading slashes should be interprted as a Windows Universal Naming Convention Path. (Specifically: that it has the file: scheme.) xs:boolean false

This function is described as a series of transformations over the input string to identify the parts of a URI that are present. Some portions of the URI are identified by matching with a regular expression. This approach is designed to make the description clear and unambiguous; it is not implementation advice. Comparison of scheme and authority components is case insensitive.

Applying uri decoding is equivalent to calling fn:decode-from-uri on the string.

Applying form decoding is equivalent to replacing each plus sign (U+002B) in the string with a space, and then applying uri decoding. Form decoding is applied to query parameters only, following the conventions of the application/x-www-form-urlencoded media type; a plus sign has no special meaning elsewhere in a URI.

The transformations are applied in the following order:

Processing begins with a string that is equal to the $value. If the string contains any backslashes (U+005C), replace them with forward slashes (U+002F).

Strip off the fragment identifier and any query:

If the string matches ^(.*?)#(.*)$, the string is the first match group and the fragment is the second match group. Otherwise, the string is unchanged and the fragment is the empty sequence. If a fragment is present, it is URI decoded. If the fragment is a zero-length string, it is discarded and the fragment is the empty sequence.

If the string matches ^(.*?)\?(.*)$, the string is the first match group and the query is the second match group. Otherwise, the string is unchanged and the query is the empty sequence. If the query is a zero-length string, it is discarded and the query is the empty sequence.

Attempt to identify the scheme:

If the string matches ^([a-zA-Z][A-Za-z0-9\+\-\.]+):(.*)$:

the scheme is the first match group and

the string is the second match group.

Otherwise, the scheme is the empty sequence and the string is unchanged.

If the scheme is not empty and the fragment is empty, absolute is true. Otherwise, absolute is the empty sequence. (But see the discussion of hierarchical URIs, below.)

If scheme is the empty sequence or file:

If the string matches ^/*([a-zA-Z][:|].*)$:

the scheme is file and

the string is a single solidus (U+002F) followed by the first match group with the second character changed to a colon (U+003A), if necessary.

Otherwise, if unc-path is true:

the scheme is file and

the string is unchanged.

Finally, if neither of the preceding cases apply:

the scheme remains the empty sequence and

the string is unchanged.

Now that the scheme, if there is one, has been identified, determine if the URI is hierarchical:

If the scheme is known to be hierarchical, or known not to be hierarchical, then hierarchical is set accordingly. If the implementation does not know if a scheme is or is not hierarchical, the hierarchical setting depends on the string: if the string is the zero-length string, hierarchical is the empty sequence (i.e. not known), otherwise hierarchical is true if string begins with U+002F and false otherwise.

If the URI is not hierarchical, absolute is the empty sequence.

Identify the remaining components according to the scheme and whether or not the URI is hierarchical.

If the scheme is file:

The authority is the empty sequence.

If unc-path is true and the string matches ^/*(//[^/].*)$: then filepath, and string are both the first match group.

If the string begins ^//*[A-Za-z]:/ then all but one leading slash is removed from string and the filepath is the string with all leading slashes removed.

Otherwise, the filepath and string are the string with any sequence of leading slashes replaced by a single slash.

If the scheme is hierarchical:

If the string matches ^//([^/]+)$, the authority is the first match group and the string is empty.

If the string matches ^//([^/]*)(/.*)$, the authority is the first match group and the string is the second match group.

Otherwise, the authority is the empty sequence and the string is unchanged.

If the scheme is not hierarchical:

The authority is the empty sequence and the string is unchanged.

If the authority matches ^(([^@]*)@)(.*)(:([^:]*))?$, then the userinfo is match group 2, otherwise userinfo is the empty sequence. If userinfo is present and contains a non-empty password, then userinfo is discarded and set to the empty sequence unless the allow-deprecated-features option is true.

When parsing the authority to find the host, there are four possibilities: the host can be a registered name (e.g., example.com), an IPv4 address (e.g., 127.0.0.1), an IPv6 (or IPvFuture) address (e.g., [::1]), or an error if there is an open square bracket (U+005B) not matched by a close square bracket (U+005D). In a properly constructed RFC 3986 URI, the only place where square brackets may occur is around the IPv6/IPvFuture IP address.

If the authority matches ^(([^@]*)@)?(\[[^\]]*\])(:([^:]*))?$, then the host is match group 3, otherwise

If the authority matches ^(([^@]*)@)?\[.*$ then is raised, otherwise

If the authority matches ^(([^@]*)@)?([^:]+)(:([^:]*))?$, then the host is match group 3, otherwise

the host is the empty sequence.

This function does not attempt to decode the components of the host.

Similar care must be taken to match the port because an IPv6/IPvFuture address may contain a colon.

If the authority matches ^(([^@]*)@)?(\[[^\]]*\])(:([^:]*))?$, then the port is match group 5.

Otherwise, if the authority matches ^(([^@]*)@)?([^:]+)(:([^:]*))?$, then the port is match group 5.

Otherwise, the port is the empty sequence.

If the omit-default-ports option is true, the port is discarded and set to the empty sequence if the port number is the same as the default port for the given scheme. Implementations should recognize the default ports for http (80), https (443), ftp (21), and ssh (22). Exactly which ports are recognized is implementation-defined.

If the string is a zero-length string, then path is the empty sequence, otherwise path is the whole string. If the scheme is the empty sequence, filepath is also the whole string.

A path-segments sequence is constructed by tokenizing the string on the solidus (U+002F) and applying uri decoding on each token.

The path and path-segments properties both contain the path portion of the URI. The different formats only become important when the path contains encoded delimiters.

Consider /path%2Fsegment. An application may want to decode that, using /path/segment in a database query, for example. At the same time, an application may wish to modify the URI and then reconstruct it.

In the string form, decoding %2F to a solidus is not reversible. In the path-segments form, the path is broken into discrete segments where the syntactic delimiters occur. This means the encoded delimiters can be decoded without introducing ambiguity: ("", "path/segment"). In this format, the decoding is reversible: escape the non-syntactic delimiters before reconstructing the path with the syntactic ones.

A consequence of constructing the path-segments this way is that a zero-length string appears before the first solidus (U+002F), if the path begins with one, after the last solidus, if the path ends with one, and between consecutive solidus characters. (If the path consists of a single solidus, that solidus counts as both the first and the last, producing a segment list containing two empty strings.)

The empty strings may seem unnecessary at first glance, but they assure that the path can be reconstructed by joining the segments together again without having to handle the presence or absence of a leading or trailing solidus as special cases.

The query-parameters value is constructed as follows. Start with the empty map. Tokenize the query on the ampersand (U+0026). For each token, identify the key and the value. If the token contains an equal sign (U+003D), the key is the string that precedes the first equal sign, form decoded, and the value is the remainder of the token, after the first equal sign, form decoded. If the token does not contain an equal sign, key is the empty string and the value is equal to the token, form decoded. Add the key/value pair to the map. If the key already exists in the map, add the value to a list of values associated with that key. The resulting map, when all tokens have been processed, is the query-parameters map.

If the filepath is not the empty sequence, it is uri decoded. On a Windows system, any forward slashes in the path may be replaced with backslashes.

A uri-structure-record is returned. As with any record, it contains an entry for every field of the record type; components that are not present in the parsed URI are represented by the empty sequence.

Implementations may implement additional or different rules for URIs that have a scheme or pattern that they recognize. An implementation might choose to parse jar: URIs with special rules, for example, since they extend the syntax in ways not defined by . Implementations may add additional keys to the map. The meaning of those keys is implementation-defined.

A dynamic error is raised if the URI contains an open square bracket in the authority component that is not followed by a close square bracket.

Like fn:resolve-uri, this function handles the additional characters allowed in IRIs in the same way that other unreserved characters are handled.

Unlike fn:resolve-uri, this function is not attempting to resolve one URI against another and consequently, the errors that can arise under those circumstances do not apply here. The fn:parse-uri function will accept strings that would raise errors if resolution were attempted; see fn:build-uri.

In the examples that follow, each result contains an entry for every field of the uri-structure-record; components that are not present in the URI are represented by the empty sequence. String literals that include an ampersand character are written as string templates (for example `Barnes&Noble`) to ensure that the examples work in both XPath and XQuery.

parse-uri("http://qt4cg.org/specifications/xpath-functions-40/Overview.html#parse-uri") { "uri": "http://qt4cg.org/specifications/xpath-functions-40/Overview.html#parse-uri", "scheme": "http", "absolute": (), "hierarchical": true(), "authority": "qt4cg.org", "userinfo": (), "host": "qt4cg.org", "port": (), "path": "/specifications/xpath-functions-40/Overview.html", "query": (), "fragment": "parse-uri", "path-segments": ("", "specifications", "xpath-functions-40", "Overview.html"), "query-parameters": (), "filepath": () } parse-uri("http://www.ietf.org/rfc/rfc2396.txt") { "uri": "http://www.ietf.org/rfc/rfc2396.txt", "scheme": "http", "absolute": true(), "hierarchical": true(), "authority": "www.ietf.org", "userinfo": (), "host": "www.ietf.org", "port": (), "path": "/rfc/rfc2396.txt", "query": (), "fragment": (), "path-segments": ("", "rfc", "rfc2396.txt"), "query-parameters": (), "filepath": () } parse-uri("https://example.com/path/to/file") { "uri": "https://example.com/path/to/file", "scheme": "https", "absolute": true(), "hierarchical": true(), "authority": "example.com", "userinfo": (), "host": "example.com", "port": (), "path": "/path/to/file", "query": (), "fragment": (), "path-segments": ("", "path", "to", "file"), "query-parameters": (), "filepath": () } parse-uri( `https://example.com:8080/path?s=%22hello world%22&sort=relevance` ) { "uri": `https://example.com:8080/path?s=%22hello world%22&sort=relevance`, "scheme": "https", "absolute": true(), "hierarchical": true(), "authority": "example.com:8080", "userinfo": (), "host": "example.com", "port": 8080, "path": "/path", "query": `s=%22hello world%22&sort=relevance`, "fragment": (), "path-segments": ("", "path"), "query-parameters": { "s": """hello world""", "sort": "relevance" }, "filepath": () } parse-uri("https://user@example.com/path/to/file") { "uri": "https://user@example.com/path/to/file", "scheme": "https", "absolute": true(), "hierarchical": true(), "authority": "user@example.com", "userinfo": "user", "host": "example.com", "port": (), "path": "/path/to/file", "query": (), "fragment": (), "path-segments": ("", "path", "to", "file"), "query-parameters": (), "filepath": () } parse-uri("ftp://ftp.is.co.za/rfc/rfc1808.txt") { "uri": "ftp://ftp.is.co.za/rfc/rfc1808.txt", "scheme": "ftp", "absolute": true(), "hierarchical": true(), "authority": "ftp.is.co.za", "userinfo": (), "host": "ftp.is.co.za", "port": (), "path": "/rfc/rfc1808.txt", "query": (), "fragment": (), "path-segments": ("", "rfc", "rfc1808.txt"), "query-parameters": (), "filepath": () } parse-uri("file:////uncname/path/to/file") { "uri": "file:////uncname/path/to/file", "scheme": "file", "absolute": true(), "hierarchical": true(), "authority": (), "userinfo": (), "host": (), "port": (), "path": "/uncname/path/to/file", "query": (), "fragment": (), "path-segments": ("", "uncname", "path", "to", "file"), "query-parameters": (), "filepath": "/uncname/path/to/file" } parse-uri("file:///c:/path/to/file") { "uri": "file:///c:/path/to/file", "scheme": "file", "absolute": true(), "hierarchical": true(), "authority": (), "userinfo": (), "host": (), "port": (), "path": "/c:/path/to/file", "query": (), "fragment": (), "path-segments": ("", "c:", "path", "to", "file"), "query-parameters": (), "filepath": "c:/path/to/file" } parse-uri("file:/C:/Program%20Files/test.jar") { "uri": "file:/C:/Program%20Files/test.jar", "scheme": "file", "absolute": true(), "hierarchical": true(), "authority": (), "userinfo": (), "host": (), "port": (), "path": "/C:/Program%20Files/test.jar", "query": (), "fragment": (), "path-segments": ("", "C:", "Program Files", "test.jar"), "query-parameters": (), "filepath": "C:/Program Files/test.jar" } parse-uri("file:\\c:\path\to\file") { "uri": "file:\\c:\path\to\file", "scheme": "file", "absolute": true(), "hierarchical": true(), "authority": (), "userinfo": (), "host": (), "port": (), "path": "/c:/path/to/file", "query": (), "fragment": (), "path-segments": ("", "c:", "path", "to", "file"), "query-parameters": (), "filepath": "c:/path/to/file" } parse-uri("file:\c:\path\to\file") { "uri": "file:\c:\path\to\file", "scheme": "file", "absolute": true(), "hierarchical": true(), "authority": (), "userinfo": (), "host": (), "port": (), "path": "/c:/path/to/file", "query": (), "fragment": (), "path-segments": ("", "c:", "path", "to", "file"), "query-parameters": (), "filepath": "c:/path/to/file" } parse-uri("c:\path\to\file") { "uri": "c:\path\to\file", "scheme": "file", "absolute": (), "hierarchical": true(), "authority": (), "userinfo": (), "host": (), "port": (), "path": "/c:/path/to/file", "query": (), "fragment": (), "path-segments": ("", "c:", "path", "to", "file"), "query-parameters": (), "filepath": "c:/path/to/file" } parse-uri("/path/to/file") { "uri": "/path/to/file", "scheme": (), "absolute": (), "hierarchical": true(), "authority": (), "userinfo": (), "host": (), "port": (), "path": "/path/to/file", "query": (), "fragment": (), "path-segments": ("", "path", "to", "file"), "query-parameters": (), "filepath": "/path/to/file" } parse-uri("#testing") { "uri": "#testing", "scheme": (), "absolute": (), "hierarchical": (), "authority": (), "userinfo": (), "host": (), "port": (), "path": (), "query": (), "fragment": "testing", "path-segments": (), "query-parameters": (), "filepath": () } parse-uri("?q=1") { "uri": "?q=1", "scheme": (), "absolute": (), "hierarchical": (), "authority": (), "userinfo": (), "host": (), "port": (), "path": (), "query": "q=1", "fragment": (), "path-segments": (), "query-parameters": { "q": "1" }, "filepath": () } parse-uri("ldap://[2001:db8::7]/c=GB?objectClass?one") { "uri": "ldap://[2001:db8::7]/c=GB?objectClass?one", "scheme": "ldap", "absolute": true(), "hierarchical": true(), "authority": "[2001:db8::7]", "userinfo": (), "host": "[2001:db8::7]", "port": (), "path": "/c=GB", "query": "objectClass?one", "fragment": (), "path-segments": ("", "c=GB"), "query-parameters": { "": "objectClass?one" }, "filepath": () } parse-uri("mailto:John.Doe@example.com") { "uri": "mailto:John.Doe@example.com", "scheme": "mailto", "absolute": (), "hierarchical": false(), "authority": (), "userinfo": (), "host": (), "port": (), "path": "John.Doe@example.com", "query": (), "fragment": (), "path-segments": "John.Doe@example.com", "query-parameters": (), "filepath": () } parse-uri("news:comp.infosystems.www.servers.unix") { "uri": "news:comp.infosystems.www.servers.unix", "scheme": "news", "absolute": (), "hierarchical": false(), "authority": (), "userinfo": (), "host": (), "port": (), "path": "comp.infosystems.www.servers.unix", "query": (), "fragment": (), "path-segments": "comp.infosystems.www.servers.unix", "query-parameters": (), "filepath": () } parse-uri("tel:+1-816-555-1212") { "uri": "tel:+1-816-555-1212", "scheme": "tel", "absolute": (), "hierarchical": false(), "authority": (), "userinfo": (), "host": (), "port": (), "path": "+1-816-555-1212", "query": (), "fragment": (), "path-segments": "+1-816-555-1212", "query-parameters": (), "filepath": () } parse-uri("telnet://192.0.2.16:80/") { "uri": "telnet://192.0.2.16:80/", "scheme": "telnet", "absolute": true(), "hierarchical": true(), "authority": "192.0.2.16:80", "userinfo": (), "host": "192.0.2.16", "port": 80, "path": "/", "query": (), "fragment": (), "path-segments": ("", ""), "query-parameters": (), "filepath": () } parse-uri("urn:oasis:names:specification:docbook:dtd:xml:4.1.2") { "uri": "urn:oasis:names:specification:docbook:dtd:xml:4.1.2", "scheme": "urn", "absolute": (), "hierarchical": false(), "authority": (), "userinfo": (), "host": (), "port": (), "path": "oasis:names:specification:docbook:dtd:xml:4.1.2", "query": (), "fragment": (), "path-segments": "oasis:names:specification:docbook:dtd:xml:4.1.2", "query-parameters": (), "filepath": () } parse-uri("tag:textalign.net,2015:ns") { "uri": "tag:textalign.net,2015:ns", "scheme": "tag", "absolute": (), "hierarchical": false(), "authority": (), "userinfo": (), "host": (), "port": (), "path": "textalign.net,2015:ns", "query": (), "fragment": (), "path-segments": "textalign.net,2015:ns", "query-parameters": (), "filepath": () } parse-uri("tag:jan@example.com,1999-01-31:my-uri") { "uri": "tag:jan@example.com,1999-01-31:my-uri", "scheme": "tag", "absolute": (), "hierarchical": false(), "authority": (), "userinfo": (), "host": (), "port": (), "path": "jan@example.com,1999-01-31:my-uri", "query": (), "fragment": (), "path-segments": "jan@example.com,1999-01-31:my-uri", "query-parameters": (), "filepath": () }

This example uses the algorithm described above, not an algorithm that is specifically aware of the jar: scheme.

parse-uri("jar:file:/C:/Program%20Files/test.jar!/foo/bar") { "uri": "jar:file:/C:/Program%20Files/test.jar!/foo/bar", "scheme": "jar", "absolute": (), "hierarchical": false(), "authority": (), "userinfo": (), "host": (), "port": (), "path": "file:/C:/Program%20Files/test.jar!/foo/bar", "query": (), "fragment": (), "path-segments": ("file:", "C:", "Program Files", "test.jar!", "foo", "bar"), "query-parameters": (), "filepath": () }

This example demonstrates that parsing the URI treats non-URI characters in lexical IRIs as “unreserved characters”. The rationale for this is given in the description of fn:resolve-uri.

parse-uri("http://www.example.org/Dürst") { "uri": "http://www.example.org/Dürst", "scheme": "http", "absolute": true(), "hierarchical": true(), "authority": "www.example.org", "userinfo": (), "host": "www.example.org", "port": (), "path": "/Dürst", "query": (), "fragment": (), "path-segments": ("", "Dürst"), "query-parameters": (), "filepath": () }

This example demonstrates the use of | instead of : in a Windows path.

parse-uri("c|/path/to/file") { "uri": "c|/path/to/file", "scheme": "file", "absolute": (), "hierarchical": true(), "authority": (), "userinfo": (), "host": (), "port": (), "path": "/c:/path/to/file", "query": (), "fragment": (), "path-segments": ("", "c:", "path", "to", "file"), "query-parameters": (), "filepath": "c:/path/to/file" }

This example demonstrates the use of | instead of : in a Windows path with an explicit file: scheme.

parse-uri("file://c|/path/to/file") { "uri": "file://c|/path/to/file", "scheme": "file", "absolute": true(), "hierarchical": true(), "authority": (), "userinfo": (), "host": (), "port": (), "path": "/c:/path/to/file", "query": (), "fragment": (), "path-segments": ("", "c:", "path", "to", "file"), "query-parameters": (), "filepath": "c:/path/to/file" }

Plus signs are only decoded as spaces in query parameters.

New in 4.0

 deterministic context-dependent focus-independent

Constructs a URI from the parts provided.

A URI is composed from a scheme, authority, path, query, and fragment.

The following options are available:

Indicates that deprecated URI features should be returned xs:boolean false Indicates that a port number that is the same as the default port for a given scheme should be omitted. xs:boolean false Indicates that the URI represents a Windows Universal Naming Convention Path. xs:boolean false

The components are derived from the fields of the $parts record. To simplify the description below, a field is considered to be present if it is supplied and its value is non-empty.

If the scheme field is present, the URI begins with its value. A URI is considered to be non-hierarchical if either the hierarchical field is present with the value false or if the scheme is known to be non-hierarchical. (In other words, schemes are hierarchical by default.)

If the scheme is known to be non-hierarchical, it is delimited by a trailing :.

Otherwise, if the scheme is file and the unc-path option is true, the scheme is delimited by a trailing :////.

Otherwise, the scheme is delimited by a trailing ://.

For simplicity of exposition, we take the userinfo, host, and port values from the record and imagine they are stored in variables with the same name. If the field is not present, the value of the variable is set to the empty sequence.

If $userinfo is non-empty and contains a non-empty password, then $userinfo is set to the empty sequence unless the allow-deprecated-features option is true.

If the omit-default-ports option is true then the $port is set to the empty sequence if the port number is the same as the default port for the given scheme. Implementations should recognize the default ports for http (80), https (443), ftp (21), and ssh (22). Exactly which ports are recognized is implementation-defined.

If any of $userinfo, $host, or $port exist, the following authority is added to the URI under construction: concat( if (exists($userinfo)) { $userinfo || "@" }, $host, if (exists($port)) { ":" || $port } )

If none of userinfo, host, or port is present, and authority is present, the value of the authority field is added to the URI. (In this case, no attempt is made to determine if a password or standard port are present, the authority value is simply added to the string.)

The fn:parse-uri function removes percent-escaping when it constructs the path-segments, query-parameters, and fragment properties. That’s often the most convenient behavior but, in order to reconstruct a URI from them, special escaping rules apply. These rules protect delimiters without encoding additional characters unnecessarily. The rules for path-segments, query-parameters, and fragment are slightly different because the URI encoding conventions are slightly different in each case.

An application with more stringent requirements can construct a path or query that satisfies the requirements and omit the path-segments and/or query-parameters fields.

If the path-segments field is present, then the path is constructed from the segments. To construct the path, the possibly encoded segments are concatentated together, separated by U+002F characters.

The rules for encoding the path segments are different for hierarchical and non-hierarchical URIs. If the URI is non-hierarchical, no encoding is performed on the segments. Otherwise, each segment is encoded by replacing any control characters (codepoints less than 0x20) and exclusively the following characters with their percent-escaped forms: U+0020, U+0025, U+002F, U+003F, U+0023, U+005B, and U+005D. That is “[#0-#20%/\?\#\[\]]”.

Encoding is performed unless the URI is known to be non-hierarchical; in other words, encoding is the default. This heuristic improves the reliability of using fn:build-uri() on the output of fn:parse-uri(). (For example, fn:parse-uri('a+b/c') => fn:build-uri() will return a+b/c.)

It is necessary to avoid encoding non-hierarchical schemes because there is more variation in them. Users working with non-hierarchical schemes may need to address the encoding issue directly bearing in mind the encoding requirements of the particular schemes in use.

Otherwise the value of the path field is used.

If neither are present, a zero-length string is used for the path.

The path is added to the URI.

If the query-parameters field is present, a sequence of strings is constructed from the entries of the map that it supplies.

To construct the string, each key and value is encoded. The encoding performed replaces any control characters (codepoints less than 0x20) and exclusively the following characters with their percent-escaped forms: U+0020, U+0025, U+003D, U+0026, U+0023, U+002B, U+005B, and U+005D. That is “[#0-#20%=&\#\+\[\]]”. (This differs from the path encoding in that it excludes U+002F and U+003F but includes U+003D, U+0026, and U+002B. A plus sign is escaped because query parameters are form decoded by fn:parse-uri.) For each key and each value associated with that key in turn:

If the key is a zero-length string, the string constructed is the encoded value.

Otherwise, the string constructed is the value of the key, encoded, followed by an equal sign (U+003D), followed by the value, encoded.

The query is constructed by joining the resulting strings into a single string, separated by ampersand (U+0026) characters. If the query-parameters field is absent, but the query field is present, then the query is the value of the query field.

If there is a query, it is added to the URI with a preceding U+003F.

If the fragment field is present, then its value is encoded and added to the URI with a preceding U+0023. The encoding performed replaces any control characters (codepoints less than 0x20) and exclusively the following characters with their percent-escaped forms: U+0020, U+0025, U+0023, U+005B, and U+005D. That is “[#0-#20%\#\[\]]”. (This differs from the path encoding in that it excludes U+002F and U+003F.)

The resulting URI is returned.

 build-uri({ "scheme": "https", "host": "qt4cg.org", "port": (), "path": "/specifications/index.html" }) "https://qt4cg.org/specifications/index.html"

Plus signs are only escaped in query parameters.

New in 4.0

 deterministic context-independent focus-independent

Partitions a sequence of items into a sequence of non-empty arrays containing the same items, starting a new partition when a supplied condition is true.

Informally, the function starts by creating a partition containing the first item in the input sequence, if any. For each remaining item $item in the input sequence, other than the first, it calls $split-when($partition, $item, $pos), where $partition is the contents of the current partition and $pos is the position of $item in the input sequence.

Each partition is a sequence of items; the function result wraps each partition as an array, and returns the sequence of arrays.

If $split-when returns true, the current partition is wrapped as an array and added to the result, and a new current partition is created, initially containing $item only. If $split-when returns false or (), $item is added to the current partition.

 for-each( $input, fn($item, $pos) { { 'item': $item, 'pos': $pos } } ) => fold-left((), fn($partitions, $pair) { if (empty($partitions) or $split-when(foot($partitions)?*, $pair?item, $pair?pos)) then ($partitions, [ $pair?item ]) else (trunk($partitions), array { foot($partitions)?*, $pair?item }) })

The function enables a variety of positional grouping problems to be solved. For example:

partition($input, fn($a, $b) { count($a) eq 3 } partitions a sequence into fixed size groups of length 3.

partition($input, fn($a, $b) { boolean($b/self::h1) } starts a new group whenever an h1 element is encountered.

partition($input, fn($a, $b) { $b lt foot($a) } starts a new group whenever an item is encountered whose value is less than the value of the previous item.

$split-when is not called to process the first item in the input sequence, because this will always start a new partition. Its first argument, $partition (the current partition), is always a non-empty sequence.

 partition( ("Anita", "Anne", "Barbara", "Catherine", "Christine"), fn($partition, $next) { substring(head($partition), 1, 1) ne substring($next, 1, 1) } ) [ "Anita", "Anne" ], [ "Barbara" ], [ "Catherine", "Christine" ] partition( (1, 2, 3, 4, 5, 6, 7), fn($partition, $next) { count($partition) eq 2 } ) [ 1, 2 ], [ 3, 4 ], [ 5, 6 ], [ 7 ] partition( (1, 4, 6, 3, 1, 1), fn($partition, $next) { sum($partition) ge 5 } ) [ 1, 4 ], [ 6 ], [ 3, 1, 1 ] partition( tokenize("In the beginning was the word"), fn($partition, $next) { sum(($partition, $next) ! string-length()) gt 10 } ) [ "In", "the" ], [ "beginning" ], [ "was", "the", "word" ] partition( (1, 2, 3, 6, 7, 9, 10), fn($partition, $next) { $next != foot($partition) + 1 } ) [ 1, 2, 3 ], [ 6, 7 ], [ 9, 10 ] partition( ('a', 'b', 'c', 'd', 'e'), fn($all, $next, $p) { $p mod 2 = 1 } ) [ "a", "b" ], [ "c", "d" ], [ "e" ]

New in 4.0

 deterministic context-independent focus-independent

Returns the successive intermediate results of an evaluation of fn:fold-left, including the initial value of the accumulator.

The function returns a sequence of N+1 single-member arrays, where N is the number of items in $input.

The member of the first array in the result is the value of $init.

For each item in $input, taken in order, the function calls $action($acc, $item, $pos), where $acc is the member of the preceding array in the result, $item is the item, and $pos is the position of that item in $input. The result of this call becomes the member of the next array in the result.

If $input is empty, the result is therefore a single array whose member is the value of $init.

 fold-left(1 to count($input), [ $init ], fn($result, $pos) { $result, [ $action(foot($result)?*, $input[$pos], $pos) ] })

As a consequence of the function signature and the function calling rules, a type error occurs if $action cannot be applied to arguments $acc and $item, where $acc is either the value of $init or the result of a previous application of $action, and $item is any single item from the sequence $input.

fn:fold-left returns only the final value of an accumulation; this function returns every intermediate value as well, the last of them being the value that fn:fold-left would return. It is needed whenever those intermediate values matter in their own right: to report a running total alongside each item that contributes to it, or to accumulate only until some condition is met.

Each value is wrapped in an array because the accumulator may itself be a sequence. Where it is a single item, the arrays can be discarded by applying a lookup to the result, as in scan($input, $init, $action)?*.

A practical implementation is expected to produce the result incrementally, in a single pass over $input, applying $action only as far as the result is required. The function can therefore be combined with a consumer that stops early, such as fn:take-while, to accumulate only as far as needed over an input that it would be impractical to process in full.

A right-to-left scan, corresponding to fn:fold-right, is obtained by reversing both the input and the result:

reverse(scan(reverse($input), $init, fn($acc, $item) { $action($item, $acc) })) let $amounts := (150, -60, -40, 300, -25) let $balances := scan($amounts, 0, op('+')) return tail($balances)?* 150, 90, 50, 350, 325 This returns the balance of an account after each transaction in a statement; applying fn:tail to the result of fn:scan discards the opening balance, leaving one value for each transaction let $paths := scan( ("usr", "local", "bin"), "", fn($path, $step) { $path || "/" || $step } ) return tail($paths)?* "/usr", "/usr/local", "/usr/local/bin" This returns the cumulative paths of the steps in a path, as needed for a breadcrumb trail take-while( scan((3, 4, 5, 2), 0, op('+')), fn($total) { $total?* le 7 } ) [ 0 ], [ 3 ], [ 7 ] This returns the running totals of the items in the sequence for as long as they remain within a limit; $action need not be applied to the remaining items

New in 4.0

 deterministic context-independent focus-independent

Creates an Invisible XML parser for a grammar.

Conceptually, an processor takes two arguments: a grammar and an input string. The grammar is a description of some format and the parser will attempt to interpret the input string according to that description. The parser returns an XML representation of the input string as parsed by the provided grammar. If parsing fails, it returns an XML representation that indicates an error occurred and may provide additional error information.

If the function is called twice with the same arguments, it is nondeterministic with respect to node identity.

For example, the following grammar describes a date as consisting of a year, a month, and a day. Each are a sequence of digits and they are separated by hyphens:

date = year, -'-', month, -'-', day . year = d, d, d, d . month = '0', d | '1', ['0'|'1'|'2'] . day = ['0'|'1'|'2'], d | '3', ['0'|'1'] . -d = ['0'-'9'] .

Using this grammar to parse “2023-10-31” will produce:

20231031]]>

Using this grammar to parse “2023-10-32” will produce something like this:

1 10 9 3 '3', ['0'; '1'; '2'] ]]>

The exact format of the error output will vary between implementations. The only required part of the output is the ixml:state attribute that contains the value failed.

The example grammar will parse “2023-00-00” as a date. The grammar could easily be extended to exclude the “00” forms for month and day, but this is only intended to be an illustrative example.

The fn:invisible-xml function takes a grammar and returns a function that can be used to parse input strings. In practice, constructing a parser from a grammar may be an expensive operation. Returning a parsing function makes it easy to efficiently reuse a parser.

The provided grammar must be a string conforming to the Invisible XML specification grammar or an XML representation of such a grammar.

The following options are available. The option parameter conventions apply.

Raise an error if the parse function fails xs:boolean false

Additional, implementation-defined options may be available, for example, to control aspects of the XML serialization, to specify the grammar start symbol, or to produce output formats other than XML.

If $grammar is the empty sequence, a parser is returned for the Invisible XML specification grammar. This should be the same grammar that the implementation uses to parse iXML grammars.

The parsing function that is returned behaves as follows:

It takes a string as input and returns an item as its result, usually an XML document containing the result of the parse. (The return type is item() to allow implementations to provide other sorts of results.)

It is nondeterministic with respect to node identity (that is, if it is called twice with the same input string, it may or may not return the same document node each time).

If $grammar is not empty, it must be a valid Invisible XML grammar. If it is not, fn:invisible-xml raises .

If the fail-on-error option is true, the parsing function will raise if the input provided cannot be parsed successfully. Otherwise, it returns an XML representation of the error (rooted at a document node) as described by the specification.

If no Invisible XML processor is available, a call on fn:invisible-xml raises .

 invisible-xml("S=A. A='a'.")("a") a]]> let $parser := invisible-xml("S=A. A='a'.") let $result := $parser("b") return $result/*/@*:state = 'failed' true() The returned document contains information about the error in the parsed string.

New in 4.0

 nondeterministic context-independent focus-independent

Delivers a root wrapping a supplied value; if the supplied value is a map or array this enables the use of lookup expression to navigate a rooted at that map or array.

The function returns a that wraps the supplied $input value. Specifically, it returns a root JNode whose ·jvalue· property is $input, and whose ·jparent·, ·jposition·, and ·jkey· properties are absent.

The returned JNode acts as the root of a tree. Typical usage is for $input to be a map or array, from which further JNodes may be reached by navigation using axis steps: see .

The function typically returns a new JNode with its own identity. There is, however, no guarantee that it constructs a new JNode on each call: two calls with equal input may return the same JNode, or distinct (but deep-equal) JNodes. Applications should not rely on the identity of the JNodes returned by separate calls. See also .

Unlike expressions and functions that construct new XNodes, there is no guarantee that the jtree function will construct a new JNode each time it is called. This is a deliberate decision, to give processors more freedom for optimization.

Maps and arrays are values: they have no identity of their own, and two maps or arrays are distinguishable only by their content. An implementation is therefore free to return the same JNode, or distinct JNodes, when fn:jtree is called more than once with equal input, and applications should not rely on the identity of the JNodes so returned.

The identity of JNodes usually becomes significant only when eliminating duplicates, for example when the union operator is used; and then, only when multiple JTrees are involved, since the identity of JNodes obtained by navigation within a single tree is unambiguously defined.

Although fn:jtree is available as a function for user applications to call explicitly, it is also invoked implicitly by some expressions, notably when a path expression is written in a form such as $map/child::*. Specifically, if the left-hand operand of the / operator is a map or array, then the supplied map or array is implicitly wrapped in a root JNode. Similarly, if the context item for an axis step includes a map or array, this is implicitly wrapped: the expression child::x works just like ./child::x.

The effect of applying fn:jtree to a map or array is that subsequent retrieval operations within the wrapped map or array return results that retain useful information about where the results were found. For example, consider an expression such as json-doc($source)//name. This expression returns a set of JNodes representing all entries in the JTree having the key "name"; each of these JNodes contains not only the value of the relevant "name" entry, but also the key (which in this simple example is always "name"), and the containing map. This means, for example, if $result is the result of the expression json-doc($source)//name, then:

$result/../ssn locates the map that contained each name, and returns the value of the ssn entry in that map.

$result/ancestor::course returns any course entries in containing maps.

$result/ancestor::* => jkey() returns a sequence of map keys and array index values representing the location of the found entries within the JSON structure.

An alternative way of wrapping a map or array, rather than calling jtree($X), is to use the path expression $X/..

It is possible to use the jtree function to wrap values other than maps or arrays. One use case for this is when constructing input to the array:of-members function (or in XSLT, the xsl:array instruction). Both these constructs take as input a sequence of JNodes, and each JNode in the input is unwrapped to create one member of the new array.

 jtree({"a":1, "b":2})/b/preceding-sibling::* ! jkey() "a" jtree({"a":1, "b":2})/b/preceding-sibling::* ! jvalue() 1 jtree([ "a", "b", "c" ])/*[1]/../*[last()] => string() "c" jtree([ "a", "b", "c", "d" ])/* =!> jkey() 1, 2, 3, 4 let $data := { "fr": { "capital": "Paris", "languages": [ "French" ] }, "de": { "capital": "Berlin", "languages": [ "German" ] } } return jtree($data)//languages[. = 'German']/../capital =!> string() "Berlin" let $data := { "fr": { "capital": "Paris", "language": "French" }, "de": { "capital": "Berlin", "language": "German" } } return array:of-members($data/* ! jtree((jkey(.), jvalue(./capital), jvalue(./language)))) [("fr", "Paris", "French"), ("de", "Berlin", "German")]

New in 4.0

References to function identity removed.

Generalized to accept any value as input.

 deterministic context-independent focus-independent

Returns the ·jkey· property of a JNode.

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

If $input is a root JNode (one in which the ·jkey· property is absent), the function returns the empty sequence.

Otherwise, the function returns the ·jkey· property of $input. In the case where the parent JNode wraps a map, this will be the key of the relevant entry within that map; in the case where the parent JNode wraps an array, it will be the 1-based index of the relevant member of the array.

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

If the context value is absent, type error .

If the context value is not an instance of the sequence type jnode()?, type error .

 let $array := [ 1, 3, 4.5, 7, "eight", 10 ] return $array/jnode(*, xs:integer) =!> jkey() 1, 2, 4, 6 let $map := { 'Mo': 'Monday', 'Tu': 'Tuesday', 'We': 'Wednesday' } return $map/child::{"Mo", "We", "Fr", "Su"} =!> jkey() "Mo", "We" let $array := [ [ 4, 18 ], [ 30, 4, 22 ] ] return $array/descendant::*[. > 25]/ancestor-or-self::* =!> jkey() 2, 1

New in 4.0

 deterministic context-independent focus-independent

Returns the ·jposition· property of a JNode.

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

If $input is a root JNode (one in which the ·jposition· property is absent), the function returns the empty sequence.

Otherwise, the function returns the ·jposition· property of $input. The value of this property will be 1 (one) except in cases where the value of an entry in a map, or a member in an array, is a sequence that contains multiple items including maps and/or arrays; in such cases the position will be the 1-based position of the relevant map or array.

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

If the context value is absent, type error .

If the context value is not an instance of the sequence type jnode()?, type error .

This function is relevant only when there are maps whose entries are multi-item sequences that include maps and arrays, or arrays whose members include such multi-item sequences. Such structures are uncommon, and never arise from parsing of JSON source text. It is generally best to avoid such structures by using arrays rather than sequences within array and map content; apart from other considerations, this allows the data to be serialized in JSON format.

If an entry within a map, or a member of an array, contains a sequence of items that mixes arrays and maps with other content (for example the array [1, 2, ([1,2], [3,4], 5)), then a lookup using the child axis will only construct JNodes in respect of those items that are non-empty maps or arrays. This may leave gaps in the position numbering sequence, as illustrated in the examples below.

 let $input := { "a": [ 10, 20, 30 ], "b": ([ 40, 50, 60 ], [], 0, [ 70, 80, (90, 100) ]) } return $input/b/* ! { "position": jposition(), "index": jkey(), "value": jvalue() } { "position": 1, "index": 1, "value": 40 }, { "position": 1, "index": 2, "value": 50 }, { "position": 1, "index": 3, "value": 60 }, { "position": 4, "index": 1, "value": 70 }, { "position": 4, "index": 2, "value": 80 }, { "position": 4, "index": 3, "value": (90, 100) } let $input := { "a": { "x": 10, "y": 20, "z": 30 }, "b": ({ "x": 40, "y": 50, "z": 60 }, {}, { "x": 70, "y": 80, "z": (90, 100) }) } return $input/b/* ! { "position": jposition(), "key": jkey(), "value": jvalue() } { "position": 1, "key": "x", "value": 40 }, { "position": 1, "key": "y", "value": 50 }, { "position": 1, "key": "z", "value": 60 }, { "position": 3, "key": "x", "value": 70 }, { "position": 3, "key": "y", "value": 80 }, { "position": 3, "key": "z", "value": (90, 100) }

New in 4.0

 deterministic context-independent focus-independent

Returns the ·jvalue· property of a JNode.

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

Otherwise, the function returns the ·jvalue· property of $input.

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

If the context value is absent, type error .

If the context value is not an instance of the sequence type jnode()?, type error .

In many cases it is unnecessary to make an explicit call on jvalue, because the coercion rules will take care of this automatically. For example, in an expression such as $X / descendant::name [matches(., '^J')], the call on matches is supplied with a JNode as its first argument; atomization ensures that the actual value being passed to the first argument of matches is the atomized value of the ·jvalue· property.

Other examples where the ·jvalue· of a JNode is extracted automatically include:

Any context where the required type is an atomic item, for example arithmetic operations, value comparisons and general comparisons, and calls on functions that expect an atomic item.

Any context where the required type is a map or array, for example the first argument of functions such as map:size or array:size, a free-standing expression within a map constructor such as map{ $jnode }, the constructs for member and for key/value, and the left-hand operand of the lookup operator ? (or the context value in the case of a unary lookup operator).

Notable places where the ·jvalue· is not automatically extracted include:

When computing the effective boolean value. As with XNodes, writing if ($array/child::*[1]) ... tests for the existence of a child, it does not test its value. To test its value, write if (jvalue($array/child::*[1])) ..., or equivalently if (xs:boolean($array/child::*[1])) ....

When calling functions that accept arbitrary sequences, such as count or deep-equal.

It is possible (though probably unwise) to construct a JNode whose ·jvalue· property itself contains another JNode. For example, the expression jtree([jtree([]), jtree([])]) creates a JNode whose ·jvalue· is an array of JNodes, and applying the child axis to this JNode will return a sequence of two JNodes that themselves have further JNodes as their content. The jvalue function returns these contained JNodes, it does not recursively extract their content.

 let $array := [ 1, 3, 4.5, 7, "eight", 10 ] return $array/jnode(*, xs:integer) =!> jvalue() 1, 3, 7, 10 let $map := { 'Mo': 'Monday', 'Tu': 'Tuesday', 'We': 'Wednesday' } return $map/child::{"Mo", "We", "Fr", "Su"} =!> jvalue() "Monday", "Wednesday" let $array := [ [ 4, 18 ], [ 30, 4, 22 ] ] return $array/descendant::jnode(*, array(*))[. > 25] =!> jvalue() [ 30, 4, 22 ]

New in 4.0