XPath and XQuery Functions and Operators 4.0

1.9.1 Atomic items

The following definitions are adopted from [XQuery and XPath Data Model (XDM) 4.0].

• [Definition] An atomic item is a pair (T, D) where T (the type annotation) is an atomic type, and D (the datum) is a point in the value space of T.[Definition: [Definition: An atomic item is a pair (T, D) where T (the type annotation) is an atomic type, and D (the datum) is a point in the value space of T.][Definition: [Definition: [Definition] An atomic item is a pair (T, D) where T (the type annotation) is an atomic type, and D (the datum) is a point in the value space of T.]

• [Definition] A primitive type is one of the 19 primitive atomic types defined in 3.2 Primitive datatypes^XS2 of [XML Schema Part 2: Datatypes Second Edition], or the type xs:untypedAtomic defined in [XQuery and XPath Data Model (XDM) 4.0].[Definition: [Definition: A primitive type is one of the 19 primitive atomic types defined in 3.2 Primitive datatypes^XS2 of [XML Schema Part 2: Datatypes Second Edition], or the type xs:untypedAtomic defined in [XQuery and XPath Data Model (XDM) 4.0].][Definition: [Definition: [Definition] A primitive type is one of the 19 primitive atomic types defined in 3.2 Primitive datatypes^XS2 of [XML Schema Part 2: Datatypes Second Edition], or the type xs:untypedAtomic defined in [XQuery and XPath Data Model (XDM) 4.0].]

• [Definition] The datum of an atomic item is a point in the value space of its type, which is also a point in the value space of the primitive type from which that type is derived. There are 20 primitive atomic types (19 defined in XSD, plus xs:untypedAtomic), and these have non-overlapping value spaces, so each datum belongs to exactly one primitive atomic type.[Definition: [Definition: The datum of an atomic item is a point in the value space of its type, which is also a point in the value space of the primitive type from which that type is derived.] There are 20 primitive atomic types (19 defined in XSD, plus xs:untypedAtomic), and these have non-overlapping value spaces, so each datum belongs to exactly one primitive atomic type.[Definition: [Definition: [Definition] The datum of an atomic item is a point in the value space of its type, which is also a point in the value space of the primitive type from which that type is derived.] There are 20 primitive atomic types (19 defined in XSD, plus xs:untypedAtomic), and these have non-overlapping value spaces, so each datum belongs to exactly one primitive atomic type.

• [Definition] The type annotation of an atomic item is the most specific atomic type that it is an instance of (it is also an instance of every type from which that type is derived).[Definition: [Definition: The type annotation of an atomic item is the most specific atomic type that it is an instance of (it is also an instance of every type from which that type is derived).][Definition: [Definition: [Definition] The type annotation of an atomic item is the most specific atomic type that it is an instance of (it is also an instance of every type from which that type is derived).]

1.9.2 Strings, characters, and codepoints

This document uses the terms string, character, and codepoint with meanings that are normatively defined in [XQuery and XPath Data Model (XDM) 4.0], and which are paraphrased here for ease of reference:

[Definition] A character is an instance of the Char^XML production of [Extensible Markup Language (XML) 1.0 (Fifth Edition)].[Definition: [Definition: A character is an instance of the Char^XML production of [Extensible Markup Language (XML) 1.0 (Fifth Edition)].][Definition: [Definition: [Definition] A character is an instance of the Char^XML production of [Extensible Markup Language (XML) 1.0 (Fifth Edition)].]

[Definition] A string is a sequence of zero or more characters, or equivalently, a value in the value space of the xs:string datatype.[Definition: [Definition: A string is a sequence of zero or more characters, or equivalently, a value in the value space of the xs:string datatype.][Definition: [Definition: [Definition] A string is a sequence of zero or more characters, or equivalently, a value in the value space of the xs:string datatype.]

[Definition] A codepoint is an integer assigned to a character by the Unicode consortium, or reserved for future assignment to a character.[Definition: [Definition: A codepoint is an integer assigned to a character by the Unicode consortium, or reserved for future assignment to a character.][Definition: [Definition: [Definition] A codepoint is an integer assigned to a character by the Unicode consortium, or reserved for future assignment to a character.]

Because these terms appear so frequently, they are hyperlinked to the definition only when there is a particular desire to draw the reader’s attention to the definition; the absence of a hyperlink does not mean that the term is being used in some other sense.

It is implementation-defined which version of [The Unicode Standard] is supported, but it is recommended that the most recent version of Unicode be used.

This specification adopts the Unicode notation U+xxxx to refer to a codepoint by its hexadecimal value (always four to six hexadecimal digits). This is followed where appropriate by the official Unicode character name and its graphical representation: for example U+20AC (EURO SIGN, €) .

Unless explicitly stated, the functions in this document do not ensure that any returned xs:string values are normalized in the sense of [Character Model for the World Wide Web 1.0: Fundamentals].

Wherever encoding names (such as UTF-8 and UTF-16) are used in this specification, they are compared without regard to case: the strings "UTF-8" and "utf-8" both refer to the same encoding.

1.9.3 Namespaces and URIs

This document uses the phrase “namespace URI” to identify the concept identified in [Namespaces in XML] as “namespace name”, and the phrase “local name” to identify the concept identified in [Namespaces in XML] as “local part”.

It also uses the term “expanded-QName” defined below.

[Definition] An expanded-QName is a value in the value space of the xs:QName datatype as defined in the XDM data model (see [XQuery and XPath Data Model (XDM) 4.0]): that is, a triple containing namespace prefix (optional), namespace URI (optional), and local name. Two expanded QNames are equal if the namespace URIs are the same (or both absent) and the local names are the same. The prefix plays no part in the comparison, but is used only if the expanded QName needs to be converted back to a string.[Definition: [Definition:  An expanded-QName is a value in the value space of the xs:QName datatype as defined in the XDM data model (see [XQuery and XPath Data Model (XDM) 4.0]): that is, a triple containing namespace prefix (optional), namespace URI (optional), and local name. Two expanded QNames are equal if the namespace URIs are the same (or both absent) and the local names are the same. The prefix plays no part in the comparison, but is used only if the expanded QName needs to be converted back to a string.][Definition: [Definition: [Definition] An expanded-QName is a value in the value space of the xs:QName datatype as defined in the XDM data model (see [XQuery and XPath Data Model (XDM) 4.0]): that is, a triple containing namespace prefix (optional), namespace URI (optional), and local name. Two expanded QNames are equal if the namespace URIs are the same (or both absent) and the local names are the same. The prefix plays no part in the comparison, but is used only if the expanded QName needs to be converted back to a string.]

The term URI is used as follows:

[Definition] Within this specification, the term URI refers to Universal Resource Identifiers as defined in [RFC 3986] and extended in [RFC 3987] with a new name IRI. The term URI Reference, unless otherwise stated, refers to a string in the lexical space of the xs:anyURI datatype as defined in [XML Schema Part 2: Datatypes Second Edition].[Definition: [Definition: Within this specification, the term URI refers to Universal Resource Identifiers as defined in [RFC 3986] and extended in [RFC 3987] with a new name IRI. The term URI Reference, unless otherwise stated, refers to a string in the lexical space of the xs:anyURI datatype as defined in [XML Schema Part 2: Datatypes Second Edition].][Definition: [Definition: [Definition] Within this specification, the term URI refers to Universal Resource Identifiers as defined in [RFC 3986] and extended in [RFC 3987] with a new name IRI. The term URI Reference, unless otherwise stated, refers to a string in the lexical space of the xs:anyURI datatype as defined in [XML Schema Part 2: Datatypes Second Edition].]

1.9.4 Conformance terminology

In this specification:

• The auxiliary verb must, when rendered in small capitals, indicates a precondition for conformance.

  • When the sentence relates to an implementation of a function (for example "All implementations must recognize URIs of the form ...") then an implementation is not conformant unless it behaves as stated.

  • When the sentence relates to the result of a function (for example "The result must have the same type as $arg") then the implementation is not conformant unless it delivers a result as stated.

  • When the sentence relates to the arguments to a function (for example "The value of $argmust be a valid regular expression") then the implementation is not conformant unless it enforces the condition by raising a dynamic error whenever the condition is not satisfied.

• The auxiliary verb may, when rendered in small capitals, indicates optional or discretionary behavior. The statement “An implementation may do X” implies that it is implementation-dependent whether or not it does X.

• The auxiliary verb should, when rendered in small capitals, indicates desirable or recommended behavior. The statement “An implementation should do X” implies that it is desirable to do X, but implementations may choose to do otherwise if this is judged appropriate.

[Definition] Where behavior is described as implementation-defined, variations between processors are permitted, but a conformant implementation must document the choices it has made.[Definition: [Definition: Where behavior is described as implementation-defined, variations between processors are permitted, but a conformant implementation must document the choices it has made.][Definition: [Definition: [Definition] Where behavior is described as implementation-defined, variations between processors are permitted, but a conformant implementation must document the choices it has made.]

[Definition] Where behavior is described as implementation-dependent, variations between processors are permitted, and conformant implementations are not required to document the choices they have made.[Definition: [Definition: Where behavior is described as implementation-dependent, variations between processors are permitted, and conformant implementations are not required to document the choices they have made.][Definition: [Definition: [Definition] Where behavior is described as implementation-dependent, variations between processors are permitted, and conformant implementations are not required to document the choices they have made.]

1.9.5 Properties of functions

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

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

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

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

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

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

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

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

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

5. Both items are function items, neither item is a map or array, and the two function items have the same function identity. The concept of function identity is explained in [XQuery and XPath Data Model (XDM) 4.0] section 8.1 Function Items.

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

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

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

The main categories of context-dependent functions are:

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

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

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

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

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

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

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

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

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

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

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

• [Definition] Some functions (such as fn:in-scope-prefixes, fn:load-xquery-module, and fn:unordered) produce result sequences or result maps in an implementation-defined or implementation-dependent order. In such cases two calls with the same arguments are not guaranteed to produce the results in the same order. These functions are said to be nondeterministic with respect to ordering.[Definition: [Definition: Some functions (such as fn:in-scope-prefixes, fn:load-xquery-module, and fn:unordered) produce result sequences or result maps in an implementation-defined or implementation-dependent order. In such cases two calls with the same arguments are not guaranteed to produce the results in the same order. These functions are said to be nondeterministic with respect to ordering.][Definition: [Definition: [Definition] Some functions (such as fn:in-scope-prefixes, fn:load-xquery-module, and fn:unordered) produce result sequences or result maps in an implementation-defined or implementation-dependent order. In such cases two calls with the same arguments are not guaranteed to produce the results in the same order. These functions are said to be nondeterministic with respect to ordering.]

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

• Some functions (such as fn:doc and fn:collection) create new nodes by reading external documents. Such functions are guaranteed to be deterministic by default (some such functions have an option "stable":false() that makes them nondeterministic as a user option, and implementations may also provide configuration options to change the default).

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

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

2.3.1 fn:exactly-one

Summary

Returns $input if it contains exactly one item. Otherwise, raises an error.

Signature

fn:exactly-one(
$input	as item()*
) as item()

Properties

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

Rules

Except in error cases, the function returns $input unchanged.

Formal Equivalent

The effect of the function is equivalent to the result of the following XPath expression, except in error cases.

if (count($input) eq 1) 
then $input 
else error(parse-QName('Q{http://www.w3.org/2005/xqt-errors}FORG0005'))

if (count($input) eq 1) 
then $input 
else error(#Q{http://www.w3.org/2005/xqt-errors}FORG0005))

Error Conditions

A dynamic error is raised [err:FORG0005] if $input is an empty sequence or a sequence containing more than one item.

2.3.2 fn:one-or-more

Summary

Returns $input if it contains one or more items. Otherwise, raises an error.

Signature

fn:one-or-more(
$input	as item()*
) as item()+

Properties

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

Rules

Except in error cases, the function returns $input unchanged.

Formal Equivalent

The effect of the function is equivalent to the result of the following XPath expression, except in error cases.

if (count($input) ge 1) 
then $input 
else error(parse-QName('Q{http://www.w3.org/2005/xqt-errors}FORG0004'))

if (count($input) ge 1) 
then $input 
else error(#Q{http://www.w3.org/2005/xqt-errors}FORG0004))

Error Conditions

A dynamic error is raised [err:FORG0004] if $input is an empty sequence.

2.3.3 fn:zero-or-one

Summary

Returns input if it contains zero or one items. Otherwise, raises an error.

Signature

fn:zero-or-one(
$input	as item()*
) as item()?

Properties

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

Rules

Except in error cases, the function returns $input unchanged.

Formal Equivalent

The effect of the function is equivalent to the result of the following XPath expression, except in error cases.

if (count($input) le 1) 
then $input 
else error(parse-QName('Q{http://www.w3.org/2005/xqt-errors}FORG0003'))

if (count($input) le 1) 
then $input 
else error(#Q{http://www.w3.org/2005/xqt-errors}FORG0003))

Error Conditions

A dynamic error is raised [err:FORG0003] if $input contains more than one item.

2.5.18 fn:sort-by

Summary

Sorts a supplied sequence, based on the value of a number of sort keys supplied as functions.

Signature

fn:sort-by(
$input	as item()*,
$keys	as record(key? as (fn(item()) as xs:anyAtomicType*)?, collation? as xs:string?, order? as enum('ascending', 'descending')?)*
) as item()*

Properties

This function is deterministic, context-dependent, and focus-independent. It depends on collations.

Rules

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 a record with three parts:

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

2. collation: A collation, which is used when comparing sort key values that are of type xs:string or xs:untypedAtomic. If no collation is supplied, the default collation from the static context is used.

   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 5.3.7 Choosing a collation.

3. order: An order direction, either "ascending" or "descending". The default is "ascending".

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 using the function data#1, using the default collation from the static context, and with order ascending.

The result of the fn:sort-by function is obtained as follows:

1. The result sequence contains the same items as the input sequence $input, but generally in a different order.

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

3. 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:

   1. The sort key value for $A is less than the sort key value for $B, as defined below.

   2. The order direction in the corresponding sort key definition is "ascending".

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

   Note:

   That is, the sort is stable.

5. 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:

   1. Let $C be the collation in the corresponding sort key definition.

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

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

      Note:

      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.

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

Error Conditions

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 ([err:XPTY0004]^XP).

Notes

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.

Examples

Expression:	sort-by((1, 4, 6, 5, 3), ())
Result:	1, 3, 4, 5, 6
Expression:	sort-by((1, 4, 4e0, 6, 5, 3), { 'order': 'descending' })
Result:	6, 5, 4, 4e0, 3, 1
Expression:	sort-by((1, -2, 5, 10, -10, 10, 8), { 'key': abs#1 })
Result:	1, -2, 5, 8, 10, -10, 10
Expression:	let $SWEDISH := collation({ 'lang': 'se' }) return sort-by($in, { 'collation': $SWEDISH }) let $SWEDISH := collation({ 'lang': 'se' }) return sort-by(//name, { 'collation': $SWEDISH })
Result:	The names in //name sorted using Swedish collation.
Expression:	sort-by(//employee, { 'key': fn { name ! (last, first) } })
Result:	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
Expression:	sort-by( $employees, ({ 'key': fn { name/last }, 'collation': collation({ 'lang': 'se' }) }, { 'key': fn { xs:decimal(salary) }, 'order': 'descending' })) sort-by( //employee, ({ 'key': fn { name/last }, 'collation': collation({ 'lang': 'se' }) }, { 'key': fn { xs:decimal(salary) }, 'order': 'descending' }))
Result:	Sorts a sequence of employees first by increasing last name (using Swedish collation order) and then by decreasing salary

4.6.1 fn:format-integer

Summary

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

Signature

fn:format-integer(
$value	as xs:integer?,
$picture	as xs:string,
$language	as xs:string?	:= ()
) as xs:string

Properties

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

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

Rules

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:

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

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

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

4. 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:

1. 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 [err:FODF1310].

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

   Note:

   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-signmust 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 (ARABIC-INDIC DIGIT ONE, ١) 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:

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

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

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

      1. There is at least one grouping separator.

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

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

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

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

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

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

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

   7. Note:

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

   The number is formatted as follows:

   1. Let S₁ 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.

   2. Let S₂ be the result of padding S₁ 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.

   3. Let S₃ be the result of replacing all decimal digits (0-9) in S₂ 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.)

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

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

   6. The result of the function is then S₅.

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

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

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

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

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

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

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

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

   Note:

   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 (DEXIA KERAIA, ʹ) and sometimes U+0375 (ARISTERI KERAIA, ͵) . 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 (CIRCLED DIGIT ONE, ①) 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 (CYRILLIC CAPITAL LETTER A, А) . 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 [Extensible Markup Language (XML) 1.0 (Fifth Edition)]). 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.

Error Conditions

A dynamic error is raised [err:FODF1310] 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.

Notes

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

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

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

   2. 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 zeros to be present.

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

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

3. 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 [ICU], or any other library making use of the Unicode Common Locale Data Repository [Unicode CLDR], 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).

4. 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 (GREEK SMALL LETTER TAU, τ) , but the implementation might return the eighteenth one, U+03C3 (GREEK SMALL LETTER SIGMA, σ) , 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 (GREEK SMALL LETTER FINAL SIGMA, ς) ). 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 (GREEK CAPITAL LETTER SIGMA, Σ) , but an implementation might return U+03A2, the eighteenth position in the sequence of Greek capital letters, but unassigned to any character.

Examples

Expression	Result
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".If supported, might return the string "Vierzehnte".If supported, might return the string "Vierzehnte"..
1 to 10 ! format-integer(., "1;o(-º)", language:="it") (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") (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"

4.7.1 Defining a decimal format

Decimal formats are defined in the static context, and the way they are defined is therefore outside the scope of this specification. XSLT and XQuery both provide custom syntax for creating a decimal format.

The static context provides a set of decimal formats. One of the decimal formats is unnamed, the others (if any) are identified by a QName. There is always an unnamed decimal format available, but its contents are implementation-defined.

Each decimal format provides a set of named properties.

[Definition] The decimal digit family of a decimal format is the sequence of ten digits with consecutive Unicode codepoints starting with the character that is the value of the zero-digit^XP31 property.[Definition: [Definition: The decimal digit family of a decimal format is the sequence of ten digits with consecutive Unicode codepoints starting with the character that is the value of the zero-digit^XP31 property.][Definition: [Definition: [Definition] The decimal digit family of a decimal format is the sequence of ten digits with consecutive Unicode codepoints starting with the character that is the value of the zero-digit^XP31 property.]

[Definition] The optional digit character is the character that is the value of the digit^XP31 property.[Definition: [Definition: The optional digit character is the character that is the value of the digit^XP31 property.][Definition: [Definition: [Definition] The optional digit character is the character that is the value of the digit^XP31 property.]

For any decimal format, the properties representing characters used in a picture string must have distinct values. These properties are decimal-separator^XP31 , grouping-separator^XP31, exponent-separator^XP31, percent^XP31, per-mille^XP31, digit^XP31, and pattern-separator^XP31. Furthermore, none of these properties may be equal to any character in the decimal digit family.

4.7.3 Syntax of the picture string

[Definition] The formatting of a number is controlled by a picture string. The picture string is a sequence of characters, in which the characters assigned to the properties decimal-separator^XP31 , exponent-separator^XP31, grouping-separator^XP31, digit^XP31, and pattern-separator^XP31 and the members of the decimal digit family, are classified as active characters, and all other characters (including the values of the properties percent^XP31 and per-mille^XP31) are classified as passive characters.[Definition: [Definition: The formatting of a number is controlled by a picture string. The picture string is a sequence of characters, in which the characters assigned to the properties decimal-separator^XP31 , exponent-separator^XP31, grouping-separator^XP31, digit^XP31, and pattern-separator^XP31 and the members of the decimal digit family, are classified as active characters, and all other characters (including the values of the properties percent^XP31 and per-mille^XP31) are classified as passive characters.][Definition: [Definition: [Definition] The formatting of a number is controlled by a picture string. The picture string is a sequence of characters, in which the characters assigned to the properties decimal-separator^XP31 , exponent-separator^XP31, grouping-separator^XP31, digit^XP31, and pattern-separator^XP31 and the members of the decimal digit family, are classified as active characters, and all other characters (including the values of the properties percent^XP31 and per-mille^XP31) are classified as passive characters.]

A dynamic error is raised [err:FODF1310] if the picture string does not conform to the following rules. Note that in these rules the words "preceded" and "followed" refer to characters anywhere in the string; they are not to be read as "immediately preceded" and "immediately followed".

• A picture-string consists either of a sub-picture, or of two sub-pictures separated by the pattern-separator^XP31 character. A picture-string must not contain more than one instance of the pattern-separator^XP31 character. If the picture-string contains two sub-pictures, the first is used for positive and unsigned zero values and the second for negative values.

• A sub-picture must not contain more than one instance of the decimal-separator^XP31 character.

• A sub-picture must not contain more than one instance of the percent^XP31 or per-mille^XP31 characters, and it must not contain one of each.

• The mantissa part of a sub-picture (defined below) must contain at least one character that is either an optional digit character or a member of the decimal digit family.

• A sub-picture must not contain a passive character that is preceded by an active character and that is followed by another active character.

• A sub-picture must not contain a grouping-separator^XP31 character that appears adjacent to a decimal-separator^XP31 character, or in the absence of a decimal-separator^XP31 character, at the end of the integer part.

• A sub-picture must not contain two adjacent instances of the grouping-separator^XP31 character.

• The integer part of a sub-picture (defined below) must not contain a member of the decimal digit family that is followed by an instance of the optional digit character. The fractional part of a sub-picture (defined below) must not contain an instance of the optional digit character that is followed by a member of the decimal digit family.

• A character that matches the exponent-separator^XP31 property is treated as an exponent-separator-sign if it is both preceded and followed within the sub-picture by an active character. Otherwise, it is treated as a passive character. A sub-picture must not contain more than one character that is treated as an exponent-separator-sign.

• A sub-picture that contains a percent^XP31 or per-mille^XP31 character must not contain a character treated as an exponent-separator-sign.

• If a sub-picture contains a character treated as an exponent-separator-sign then this must be followed by one or more characters that are members of the decimal digit family, and it must not be followed by any active character that is not a member of the decimal digit family.

The mantissa part of the sub-picture is defined as the part that appears to the left of the exponent-separator-sign if there is one, or the entire sub-picture otherwise. The exponent part of the subpicture is defined as the part that appears to the right of the exponent-separator-sign; if there is no exponent-separator-sign then the exponent part is absent.

The integer part of the sub-picture is defined as the part that appears to the left of the decimal-separator^XP31 character if there is one, or the entire mantissa part otherwise.

The fractional part of the sub-picture is defined as that part of the mantissa part that appears to the right of the decimal-separator^XP31 character if there is one, or the part that appears to the right of the rightmost active character otherwise. The fractional part may be zero-length.

5.3.1 Collations

[Definition] A collation is an algorithm that determines, for any two given strings S₁ and S₂, whether S₁ is less than, equal to, or greater than S₂. In this specification, a collation is identified by an absolute URI.[Definition: [Definition:  A collation is an algorithm that determines, for any two given strings S₁ and S₂, whether S₁ is less than, equal to, or greater than S₂. In this specification, a collation is identified by an absolute URI.][Definition: [Definition: [Definition] A collation is an algorithm that determines, for any two given strings S₁ and S₂, whether S₁ is less than, equal to, or greater than S₂. In this specification, a collation is identified by an absolute URI.]

The [Character Model for the World Wide Web 1.0: Fundamentals] observes that different applications may require different comparison and ordering behaviors. Similarly, different users with different linguistic expectations may require different behaviors. Consequently, the collation must be taken into account when comparing strings.

Collations can indicate that two different codepoints are to be considered equal for comparison purposes (for example, “v” and “w” are considered equivalent in some Swedish collations). Strings can be compared codepoint-by-codepoint or in a linguistically appropriate manner.

This specification defines some collation URIs that provide interoperable sorting behavior across applications. Other collation URIs are defined only partially (leaving some aspects implementation-defined). Implementations may define further collation URIs, or may allow users or third parties to define them.

The Unicode codepoint collation is available in every implementation. This collation sorts based on codepoint values. For further details see 5.3.3 The Unicode Codepoint Collation.

Collations may or may not perform Unicode normalization on strings before comparing them.

This specification allows a collation name to be provided as an argument to many string functions. Although collations are defined to be URIs, they are supplied as instances of xs:string.

The XQuery/XPath static context supplies a default collation for use when the collation argument is not specified. (see 2.1.1 Static Context ^XP31). If the default collation is not specified by the user or the system, the default collation is the Unicode codepoint collation.

If the collation is specified using a relative URI reference, it is resolved relative to an implementation-defined base URI.

This specification does not define whether or not the collation URI is dereferenced. The collation URI may be an abstract identifier, or it may refer to an actual resource describing the collation. If it refers to a resource, this specification does not define the nature of that resource. One possible candidate is that the resource is a locale description expressed using the Locale Data Markup Language: see [UTS #35].

5.3.3 The Unicode Codepoint Collation

[Definition] The collation URI http://www.w3.org/2005/xpath-functions/collation/codepoint identifies a collation which must be recognized by every implementation: it is referred to as the Unicode codepoint collation (not to be confused with the Unicode collation algorithm).[Definition: [Definition: The collation URI http://www.w3.org/2005/xpath-functions/collation/codepoint identifies a collation which must be recognized by every implementation: it is referred to as the Unicode codepoint collation (not to be confused with the Unicode collation algorithm).][Definition: [Definition: [Definition] The collation URI http://www.w3.org/2005/xpath-functions/collation/codepoint identifies a collation which must be recognized by every implementation: it is referred to as the Unicode codepoint collation (not to be confused with the Unicode collation algorithm).]

The Unicode codepoint collation does not perform any normalization on the supplied strings.

The collation is defined as follows. Each of the two strings is converted to a sequence of integers using the fn:string-to-codepoints function. These two sequences $A and $B are then compared as follows:

1. If both sequences are empty, the strings are equal.

2. If one sequence is empty and the other is not, then the string corresponding to the empty sequence is less than the other string.

3. If the first integer in $A is less than the first integer in $B, then the string corresponding to $A is less than the string corresponding to $B.

4. If the first integer in $A is greater than the first integer in $B, then the string corresponding to $A is greater than the string corresponding to $B.

5. Otherwise (the first pair of integers are equal), the result is obtained by applying the same rules recursively to fn:tail($A) and fn:tail($B)

6.1.1 Processing model for regular expressions

As well as extending the XSD 1.1 syntax for regular expressions, this specification also extends the processing model.

In XSD, a regular expression is defined to denote a set of strings, and the only functionality offered is to test whether a string matches a regular expression: that is, whether it is a member of the set of strings denoted by the regular expression.

In this specification, matching a string S against a regular expression delivers a more complex outcome.

First some terminology:

• [Definition] A string of length N has N+1character positions: one immediately before each character in the string, and one after the last character. In interfaces where character positions are exposed, they are numbered from 1 to N+1.[Definition: [Definition: A string of length N has N+1character positions: one immediately before each character in the string, and one after the last character. In interfaces where character positions are exposed, they are numbered from 1 to N+1.][Definition: [Definition: [Definition] A string of length N has N+1character positions: one immediately before each character in the string, and one after the last character. In interfaces where character positions are exposed, they are numbered from 1 to N+1.]

• [Definition] A segment of a string S is a sequence of zero or more contiguous characters starting at a given character position within S. Segments of a string are uniquely identified by their start position and length. The sequence of characters making up a segment is referred to as the string value of the segment.[Definition: [Definition: A segment of a string S is a sequence of zero or more contiguous characters starting at a given character position within S.] Segments of a string are uniquely identified by their start position and length. The sequence of characters making up a segment is referred to as the string value of the segment.[Definition: [Definition: [Definition] A segment of a string S is a sequence of zero or more contiguous characters starting at a given character position within S.] Segments of a string are uniquely identified by their start position and length. The sequence of characters making up a segment is referred to as the string value of the segment.

• [Definition] The end position of a segment is the start position of the segment plus its length.[Definition: [Definition: The end position of a segment is the start position of the segment plus its length.][Definition: [Definition: [Definition] The end position of a segment is the start position of the segment plus its length.]

The operation of matching a string S against a regular expression delivers:

• A set of matching segments. The string S as a whole is said to match the regular expression if the set of matching segments is non-empty.

• For each matching segmentM, a collection of captured groups. This is a mapping from positive integers to segments. The integer is called the group number, and corresponds to the ordinal sequence of opening parentheses of capturing subexpressions within the regular expression, as explained below. The corresponding segment is always a segment of S, but in the case of capturing expressions within lookahead assertions, it is not necessarily a segment of M.

The semantics of particular constructs in a regular expression are affected by a set of flags. The available flags and their effect are defined in 6.2 Flags.

The different functions available, such as fn:replace and fn:tokenize, are defined in terms of this outcome. For example:

• The function fn:matches returns true if the set of matching segments is non-empty.

• The function fn:replace replaces matching segments of the input string with a replacement string.

• The function fn:tokenize returns the segments of the input string that appear between the matching segments.

In principle the set of segments that match a regular expression can be determined by enumerating all the segments of the input string and examining each one independently to establish whether it matches. In practice, however:

• If several matching segments have the same starting position, then only one of them is returned. This is chosen as follows:

  • In the case of a choice (operator "|") the first matching branch is chosen.

  • In the case of a repetition with a greedy quantifier (for example "+" or "*") the longest matching segment is chosen.

  • In the case of a repetition with a reluctant quantifier (for example "+?" or "*?") the shortest matching segment is chosen.

• A matching segment is not included in the result if it overlaps an earlier matching segment: specifically, a segment with start position S₁ is excluded if there is a segment that has start position S₀ and length L₀, where S0 < S1 < S0+L0.

[Definition] The disjoint matching segments obtained by applying a regular expression R to a string S in the presence of a set of flags F are the segments of S that match R (using flags F), after elimination of overlapping segments.[Definition: [Definition: The disjoint matching segments obtained by applying a regular expression R to a string S in the presence of a set of flags F are the segments of S that match R (using flags F), after elimination of overlapping segments.][Definition: [Definition: [Definition] The disjoint matching segments obtained by applying a regular expression R to a string S in the presence of a set of flags F are the segments of S that match R (using flags F), after elimination of overlapping segments.]

The semantics of a regular expression are thus defined by stating which segments of an input string it matches, and what the captured groups corresponding to this match are. This is defined recursively for each construct that may appear within a regular expression, in terms of the outcome of applying its subexpressions.

For constructs defined in XSD 1.1 (branch, piece, NormalChar, charClass), XSD defines a set of strings denoted by the construct. The corresponding semantics for this specification are that the segments matched by such a construct are the segments whose string value is contained in this set.

For constructs added to the XSD 1.1 baseline by this specification, the semantics are defined in the sections that follow.

6.1.5 Captured groups

The regular expression syntax defined by [XML Schema Part 2: Datatypes Second Edition] allows a regular expression to contain parenthesized subexpressions, but attaches no special significance to them. Some operations associated with regular expressions (for example, back-references, and the fn:replace function) allow access to the parts of the input string that matched a parenthesized subexpression (called captured groups).

[Definition] A left parenthesis is recognized as a capturing left parenthesis provided it is not immediately followed by ? or * (see below), is not within a character group (square brackets), and is not escaped with a backslash. The sub-expression enclosed by a capturing left parenthesis and its matching right parenthesis is referred to as a capturing subexpression.[Definition: [Definition: A left parenthesis is recognized as a capturing left parenthesis provided it is not immediately followed by ? or * (see below), is not within a character group (square brackets), and is not escaped with a backslash. The sub-expression enclosed by a capturing left parenthesis and its matching right parenthesis is referred to as a capturing subexpression.][Definition: [Definition: [Definition] A left parenthesis is recognized as a capturing left parenthesis provided it is not immediately followed by ? or * (see below), is not within a character group (square brackets), and is not escaped with a backslash. The sub-expression enclosed by a capturing left parenthesis and its matching right parenthesis is referred to as a capturing subexpression.]

More specifically, the capturing subexpression enclosed by the Nth capturing left parenthesis within the regular expression (determined by its character position in left-to-right order, and counting from one) is referred to as the Nth capturing subexpression.

For example, in the regular expression A(BC(?:D(EF(GH[()])))), the subexpression BC(?:D(EF(GH[()]))) is capturing subexpression 1, the string subexpression EF(GH[()]) is capturing subexpression 2, and the subexpression GH[()] is capturing subexpression 3.

When, in the course of evaluating a regular expression, a particular segment of the input matches a capturing subexpression, that segment becomes available as a captured group. The segment matched by the Nth capturing subexpression is referred to as the Nth captured group. By convention, the segment captured by the entire regular expression is treated as captured group 0 (zero).

When a capturing subexpression is matched more than once (because it is within a construct that allows repetition), then only the last substring that it matched will be captured. Note that this rule is not sufficient in all cases to ensure an unambiguous result, especially in cases where (a) the regular expression contains nested repeating constructs, and/or (b) the repeating construct matches a zero-length string. In such cases it is implementation-dependent which substring is captured. For example given the regular expression (a*)+ and the input string "aaaa", an implementation might legitimately capture either "aaaa" or a zero length string as the content of the captured subgroup.

Parentheses that are required to group terms within the regular expression, but which are not required for capturing of substrings, can be represented using the syntax (?:xxxx).

In the absence of back-references (see below), the presence of the optional ?: has no effect on the set of strings that match the regular expression, but causes the left parenthesis not to be counted by operations (such as fn:replace and back-references) that number the capturing sub-expressions within a regular expression.

9.6.16 fn:parts-of-dateTime

Summary

Returns all the components of a Gregorian value.

Signature

fn:parts-of-dateTime(
$value	as (xs:dateTime | xs:date | xs:time | xs:gYear | xs:gYearMonth | xs:gMonth | xs:gMonthDay | xs:gDay)?
) as dateTime-record?

Properties

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

Rules

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

Otherwise, the function returns a record whose fields are as follows. All entries will be present, even when the value is an empty sequence.

Key	Value
year	The value of fn:year-from-dateTime($value)
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)

Examples

Expression:	parts-of-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") )
Result:	{ "year": 1999, "month": 5, "day": 31, "hours": 13, "minutes": 20, "seconds": 0, "timezone": xs:dayTimeDuration("-PT5H") }
Expression:	parts-of-dateTime( xs:time("13:30:04.2678") )
Result:	{ "year": (), "month": (), "day": (), "hours": 13, "minutes": 30, "seconds": 4.2678, "timezone": () }
Expression:	parts-of-dateTime( xs:gYearMonth("2007-05Z") )
Result:	{ "year": 2007, "month": 5, "day": (), "hours": (), "minutes": (), "seconds": (), "timezone": xs:dayTimeDuration("-PT0S") } { "year": 2007, "month": 5, "day": (), "hours": (), "minutes": (), "seconds": (), "timezone": xs:dayTimeDuration("PT0S") }

9.9.4 The date/time formatting functions

The fn:format-dateTime, fn:format-date, and fn:format-time functions format $value as a string using the picture string specified by the $picture argument, the calendar specified by the $calendar argument, the language specified by the $language argument, and the country or other place name specified by the $place argument. The result of the function is the formatted string representation of the supplied xs:dateTime, xs:date, or xs:time value.

[Definition] The three functions fn:format-dateTime, fn:format-date, and fn:format-time are referred to collectively as the date formatting functions.[Definition: [Definition: The three functions fn:format-dateTime, fn:format-date, and fn:format-time are referred to collectively as the date formatting functions.][Definition: [Definition: [Definition] The three functions fn:format-dateTime, fn:format-date, and fn:format-time are referred to collectively as the date formatting functions.]

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

Calling the two-argument form of each of the three functions is equivalent to calling the five-argument form with each of the last three arguments set to the empty sequence.

For details of the $language, $calendar, and $place arguments, see 9.9.4.8 The language, calendar, and place arguments.

In general, the use of an invalid $picture, $language, $calendar, or $place argument results in a dynamic error [err:FOFD1340]. By contrast, use of an option in any of these arguments that is valid but not supported by the implementation is not an error, and in these cases the implementation is required to output the value in a fallback representation. More detailed rules are given below.

10.1.2 fn:parse-QName

Summary

Returns an xs:QName value formed by parsing an EQName.

Signature

fn:parse-QName(
$value	as xs:string?
) as xs:QName?

Properties

This function is deterministic, context-dependent, and focus-independent. It depends on namespaces.

Rules

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^XP (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 BracedURILiteral^XP within a URIQualifiedName^XP are the XPath rules, not the XQuery rules (the XQuery rules require special characters such as < and & to be escaped).

Error Conditions

A dynamic error is raised [err:FOCA0002] if the supplied value of $value, after whitespace normalization, does not match the XPath production EQName^XP, 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 [err:FONS0004] 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.

Examples

Expression:	fn:parse-QName("Q{http://www.example.com/ns}person")
Result:	fn:QName("http://www.example.com/ns", "person")
Expression:	fn:parse-QName("person")
Result:	fn:QName("", "person")
Expression:	fn:parse-QName("Q{}person")
Result:	fn:QName("", "person")
Expression:	fn:parse-QName("Q{http://www.example.com/ns}xmp:person")
Result:	fn:QName("http://www.example.com/ns", "xmp:person")
Expression:	declare namespace xmp = "http://www.example.com/ns"; fn:parse-QName("xmp:person")
Result:	fn:QName("http://www.example.com/ns", "xmp:person") #Q{http://www.example.com/ns}xmp:person

10.2.2 fn:local-name-from-QName

Summary

Returns the local part of the supplied QName.

Signature

fn:local-name-from-QName(
$value	as xs:QName?
) as xs:NCName?

Properties

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

Rules

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.

Examples

Expression:	local-name-from-QName( QName("http://www.example.com/example", "person") ) local-name-from-QName(#Q{http://www.example.com/ns}person)
Result:	"person"

10.2.3 fn:namespace-uri-from-QName

Summary

Returns the namespace URI part of the supplied QName.

Signature

fn:namespace-uri-from-QName(
$value	as xs:QName?
) as xs:anyURI?

Properties

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

Rules

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.

Examples

Expression:	namespace-uri-from-QName( QName("http://www.example.com/example", "person") ) namespace-uri-from-QName(#Q{http://www.example.com/ns}person)
Result:	xs:anyURI("http://www.example.com/example") xs:anyURI("http://www.example.com/ns")

12.2.1 fn:has-children

Summary

Returns true if the supplied GNode has one or more child nodes (of any kind).

Signature

fn:has-children(
$node	as gnode()?	:= .
) as xs:boolean

Properties

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

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

Rules

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

Provided that the supplied argument $node matches the expected type gnode()?, 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::gnode()).

Error Conditions

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

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

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

Notes

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 [XSL Transformations (XSLT) Version 4.0], the following construct is not streamable:

<xsl:if test="exists(row)">
  <ulist>
    <xsl:for-each select="row">
      <item><xsl:value-of select="."/></item>
    </xsl:for-each>
  </ulist>
</xsl:if>

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.

Examples

Variables
let $e := <doc> <p id="alpha">One</p> <p/> <p>Three</p> <?pi 3.14159?> </doc>

Expression	Result
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()
[1,2,3] => has-children() jtree([1,2,3]) => has-children()	true()
[] => has-children() jtree([]) => has-children()	false()

14.4.1 map:build

Summary

Returns a map that typically contains one entry for each item in a supplied input sequence.

Signature

map:build(
$input	as item()*,
$key	as (fn($item as item(), $position as xs:integer) as xs:anyAtomicType*)?	:= fn:identity#1,
$value	as (fn($item as item(), $position as xs:integer) as item()*)?	:= fn:identity#1,
$options	as map(*)?	:= {}
) as map(*)

Properties

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

Rules

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^XP of the supplied values.

  • The position of the combined entry in the entry order^DM 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 implementation-dependent 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:

  record(
  duplicates?	as (enum( "reject", "use-first", "use-last", "use-any", "combine") | fn(item()*, item()*) as item()*)?
  )

  Key	Value	Meaning
  duplicates?	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. Type: (enum( "reject", "use-first", "use-last", "use-any", "combine") | fn(item()*, item()*) as item()*)? Default: "combine"
  	"reject"	Equivalent to supplying a function that raises a dynamic error with error code "FOJS0003". The effect is that duplicate keys result in an error.
  	"use-first"	Equivalent to supplying the function fn($a, $b){ $a }. The effect is that the first of the duplicates is chosen.
  	"use-last"	Equivalent to supplying the function fn($a, $b){ $b }. The effect is that the last of the duplicates is chosen.
  	"use-any"	Equivalent to supplying the function fn($a, $b){ one-of($a, $b) } where one-of chooses either $a or $b in an implementation-dependent way. The effect is that it is implementation-dependent which of the duplicates is chosen.
  	"combine"	Equivalent to supplying the function fn($a, $b){ $a, $b } (or equivalently, the function op(",")). The effect is that the result contains the sequence concatenationXP of the values having the same key, retaining order.
  	function(*)	A function with signature fn(item()*, item()*) as item()*. The function is called for any entry in the input sequence that has the same key 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).

Formal Equivalent

The effect of the function is equivalent to the result of the following XPath expression.

for-each(
  $input, 
  fn($item, $pos) {
    for-each($key($item, $pos), fn($k) {
      map:entry($k, $value($item, $pos))
    }
  )}
)
=> map:merge($options)

Error Conditions

An error is raised [err:FOJS0003] if the value of $options indicates that duplicates are to be rejected, and a duplicate key is encountered.

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

Notes

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.

Examples

Expression:	map:build((), string#1)
Result:	{}
Expression:	map:build(1 to 10, fn { . mod 3 })
Result:	{ 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.)
Expression:	map:build( 1 to 5, value := format-integer(?, "w") )
Result:	{ 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.)
Expression:	map:build( ("January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"), substring(?, 1, 1) )
Result:	{ "A": ("April", "August"), "D": ("December"), "F": ("February"), "J": ("January", "June", "July"), "M": ("March", "May"), "N": ("November"), "O": ("October"), "S": ("September") }
Expression:	map:build(1 to 5, { 1: ("eins", "one"), 4: ("vier", "four") })
Result:	{ "eins": 1, "one": 1, "vier": 4, "four": 4 }
Expression:	map:build( ("apple", "apricot", "banana", "blueberry", "cherry"), substring(?, 1, 1), string-length#1, { "duplicates": op("+") } )
Result:	{ "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.)
Expression:	map:build( ('Wang', 'Liu', 'Zhao'), key := fn($name, $pos) { $name }, value := fn($name, $pos) { $pos } )
Result:	{ "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.)
Expression:	let $titles := <titles> <title>A Beginner’s Guide to <ix>Java</ix></title> <title>Learning <ix>XML</ix></title> <title>Using <ix>XML</ix> with <ix>Java</ix></title> </titles> return map:build($titles/title, fn($title) { $title/ix })
Result:	{ "Java": ( <title>A Beginner’s Guide to <ix>Java</ix></title>, <title>Using <ix>XML</ix> with <ix>Java</ix></title> ), "XML": ( <title>Learning <ix>XML</ix></title>, <title>Using <ix>XML</ix> with <ix>Java</ix></title> ) }
Expression:	map:build(//employee, fn { @ssn })
Result:	A map whose keys are employee @ssn values, and whose corresponding values are the employee nodes
Expression:	map:build(//employee, fn { @location }, fn { 1 }, { "duplicates": op("+") })
Result:	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.
Expression:	map:build( //employee, key := fn { @location }, combine := fn($a, $b) { highest(($a, $b), fn { xs:decimal(@salary) }) } ) map:build( //employee, key := fn { @location }, options := {"duplicates" : fn($a, $b) { highest(($a, $b), (), fn { xs:decimal(@salary) }) } } )
Result:	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
Expression:	map:build(//*, generate-id#1)
Result:	A map allowing efficient access to every element in a document by means of its fn:generate-id value.
Expression:	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::~[record(type, name, content?)], fn{?ancestor-or-self::name => reverse() => string-join(,)}, fn{`{?type} {?name}`}) 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::jnode(*, record(type, name, content?)), fn{./ancestor-or-self::jnode()?name => string-join(".")}, fn{`{?type} {?name}`})
Result:	{ "org.xml.sax.Attributes": "class Attributes", "org.xml.sax.ContentHandler": "class ContentHandler", "org.xml.sax.XMLReader": "class XMLReader" } { "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).

15.2.26 array:sort-by

Summary

Sorts a supplied array, based on the value of a number of sort keys supplied as functions.

Signature

array:sort-by(
$array	as array(*),
$keys	as record(key? as (fn(item()*) as xs:anyAtomicType*)?, collation? as xs:string?, order? as enum('ascending', 'descending')?)*
) as array(*)

Properties

This function is deterministic, context-dependent, and focus-independent. It depends on collations.

Rules

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 a record with three parts:

1. key: A sort key function, which is applied to each member of the input sequence to determine a sort key value. If no function is supplied, the default is fn:data#1, which atomizes the value of the array member.

2. collation: A collation, which is used when comparing sort key values that are of type xs:string or xs:untypedAtomic. If no collation is supplied, the default collation from the static context is used.

   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 5.3.7 Choosing a collation.

3. order: An order direction, either "ascending" or "descending". The default is "ascending".

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 using the function data#1, using the default collation from the static context, and with order ascending.

The result of the array:sort-by function is obtained as follows:

1. The result array contains the same members as $array, but generally in a different order.

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

3. 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:

   1. The sort key value for $A is less than the sort key value for $B, as defined below.

   2. The order direction in the corresponding sort key definition is "ascending".

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

   Note:

   That is, the sort is stable.

5. 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:

   1. Let $C be the collation in the corresponding sort key definition.

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

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

      Note:

      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.

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

Formal Equivalent

The effect of the function is equivalent to the result of the following XPath expression.

$array
=> 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()

$array
=> 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()

Error Conditions

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 ([err:XPTY0004]^XP).

Notes

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.

Examples

Expression:	array:sort-by([1, 4, 6, 5, 3], {})
Result:	[1, 3, 4, 5, 6]
Expression:	array:sort-by([1, 4, 4e0, 6, 5, 3], {'order': 'descending'})
Result:	[6, 5, 4, 4e0, 3, 1]
Expression:	array:sort-by([(1,4,3), 4, (5,6), 2], ({'key': count#1}, {}))
Result:	[2, 4, (5,6), (1,4,3)]

16.1.1 fn:jtree

Summary

Delivers a root JNode^DM wrapping a map or array, enabling the use of lookup expression to navigate a JTree^DM rooted at that map or array.

Signature

fn:jtree(
$input	as (map(*)|array(*))
) as jnode((map(*)|array(*)))) as jnode((), (map(*)|array(*)))) as jnode((), (map(*)|array(*)))

Properties

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

Rules

The function creates a JNode^DM that wraps the supplied map or array. Specifically, it creates a root JNode whose ·content· property is $input, and whose ·parent·, ·position·, and ·selector· properties are absent.

This has the effect that lookup expressions starting from this JNode retain information for subsequent navigation.

A JNode has unique identity. If two maps or arrays M₁ and M₂ have the same function identity, as determined by the function-identity function, then jtree(M1) is jtree(M2)must return true: that is, the same JNode must be delivered for both.

Notes

It is to some extent implementation-defined whether two maps or arrays have the same function identity. Processors should ensure as a minimum that when a variable $m is bound to a map or array, calling jtree($m) more than once (with the same variable reference) will deliver the same JNode each time.

The effect of the coercion rules is technically that if an existing JNode is supplied as $input, the wrapped value will be extracted, and then rewrapped as a JNode: in practice, this can be short-circuited by returning the supplied JNode unchanged.

Although fn:jnode 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 JNode.

The effect of applying fn:jnode 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::* => jnode-selector() 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/..

There are two situations where a map or array is implicitly wrapped in a JNode:

• When the value of the left-hand operand of the / operator includes a map or array;

• When the context value for evaluation of an AxisStep includes a map or array.

Examples

Expression:	jtree([ "a", "b", "c" ])/*[1]/../*[last()] => string()
Result:	"c" (The call on fn:jnode would happen automatically).
Expression:	jtree([ "a", "b", "c", "d" ])/* =!> jnode-selector()
Result:	1, 2, 3, 4
Expression:	let $data := { "fr": { "capital": "Paris", "languages": [ "French" ] }, "de": { "capital": "Berlin", "languages": [ "German" ] } } return jtree($data)//languages[. = 'German']/../capital =!> string()
Result:	"Berlin"

16.1.4 fn:jnode-position

Summary

Returns the ·position· property of a JNode.

Signature

fn:jnode-position(
$input	as jnode()?	:= .
) as xs:anyAtomicType?) as xs:integer?) as xs:anyAtomicTypexs:integer?

Properties

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

Rules

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

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

If $input is a root JNode (one in which the ·position· property is absent), the function returns the empty sequence.

Otherwise, the function returns the ·position· 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.

Error Conditions

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

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

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

Notes

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.

Examples

Expression:	let $input := { "a": [10, 20, 30], "b": ([40, 50, 60], [], 0, [70, 80, (90, 100)]) } return $input / child::b / * ! { "position": jnode-position(), "index": jnode-selector(), "value": jnode-content() }
Result:	{ "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) }
Expression:	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 / child::b / * ! { "position": jnode-position(), "key": jnode-selector(), "value": jnode-content() }
Result:	{ "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) }

21.2.1 fn:trace

Summary

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

Signature

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

Properties

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

Rules

The function returns $input, unchanged.

In addition, the values of $input, typically serialized and converted to an xs:string, and $label (if supplied and non-empty) may be output to an implementation-defined 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 10 Adaptive Output Method ^SER31).

The format of the trace output and its order are implementation-dependent. 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.

Notes

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

Examples

Expression:	fn:trace($v, 'the value of $v is: ') let $v := 124.84 return fn:trace($v, 'the value of $v is: ')
Result:	Supposing that $v is an xs:decimal with the value 124.84, the function returns the value 124.84, while outputting a message such as "the value of $v is: 124.84" to an implementation-defined destination. The format of the message is also implementation-defined.The function returns the xs:decimal value 124.84, while outputting a message such as "the value of $v is: 124.84" to an implementation-defined destination. The format of the message is also implementation-defined.Supposing thatThe function $vreturns is anthe xs:decimal with the value 124.84, the function returns the value 124.84, while outputting a message such as "the value of $v is: 124.84" to an implementation-defined destination. The format of the message is also implementation-defined.
Expression:	//book[xs:decimal(@price) gt 100] => trace('books more expensive than €100:')
Result:	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.