XPath and XQuery Functions and Operators 4.0

Returns the first item in a sequence.

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

The function returns the first item in $input; if $input is empty, it returns an empty sequence.The function returns the first item in $input; if $input is empty, it returns the empty sequence.The function returns the first item in $input; if $input is empty, it returns anthe empty sequence.

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

filter($input, fn($item, $pos) { $pos eq 1 })

Returns a sequence containing the items from $input at positions defined by $at, in the order specified.

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

Returns the items in $input at the positions listed in $at, in order of the integers in the $at argument.

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

for-each($at, fn($index) { subsequence($input, $index, 1) })

Returns a new sequence containing all the items of $inputexcept those at specified positions.

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

The function returns a sequence consisting of all items of $inputwhose 1-based position is not equal to any of the integers in $positions.

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

filter($input, fn($item, $pos) { not($pos = $positions) })

Returns the contiguous sequence of items in $input beginning at the position indicated by $start and continuing for the number of items indicated by $length.

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

In the two-argument case (or where the third argument is an empty sequence), the function returns:In the two-argument case (or where the third argument is the empty sequence), the function returns:In the two-argument case (or where the third argument is anthe empty sequence), the function returns:

$input[round($start) le position()]

In the three-argument case, the function returns:

$input[round($start) le position() 
         and position() lt round($start) + round($length)]

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

filter(
  $input,
  if (empty($length)) then (
    fn($item, $pos) { round($start) le $pos }
  ) else (
    fn($item, $pos) { round($start) le $pos and $pos lt round($start) + round($length) }
  )
)

Absorbs the argument.

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

The function absorbs the supplied $input argument and returns an empty sequence.The function absorbs the supplied $input argument and returns the empty sequence.The function absorbs the supplied $input argument and returns anthe empty sequence.

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

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

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

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

This function is transitive and symmetric. For example:

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

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

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

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

Otherwise, the result is determined as follows:

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

   The collation is determined according to the rules in 5.3.7 Choosing a collation.

   Note:

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

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

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

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

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

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

   5. Negative zero is equal to positive zero.

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

   Note:

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

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

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

   Note:

   This means that false is treated as less than true.

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

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

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

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

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

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

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

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

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

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

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

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

         Note:

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

   2. The result of the function is then the result of comparing the starting instants of these two xs:dateTime values according to the algorithm defined in section 3.2.7.4 of [XML Schema Part 2: Datatypes Second Edition] ( “Order relation on dateTime” for xs:dateTime values with timezones).

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

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

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

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

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

   Note:

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

   • When both values are zero-length durations.

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

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

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

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

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

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

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

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

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

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

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

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

9. For any other combination of types, a type error [err:XPTY0004]^XP is raised. In particular, this means that an error is raised when comparing two atomic items that belong to different [XQuery and XPath Data Model (XDM) 4.0] section .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. All of the following conditions are true:

   1. $i1 is an atomic item.

   2. $i2 is an atomic item.

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

   4. One of the following conditions is true:

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

      2. Otherwise, fn:compare($i1, $i2) returns zero.

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

   5. One of the following conditions is true:

      1. Option namespace-prefixes is false.

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

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

   6. One of the following conditions is true:

      1. Option timezones is false.

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

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

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

2. All of the following conditions are true:

   1. $i1 is a map.

   2. $i2 is a map.

   3. Both maps have the same number of entries.

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

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

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

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

3. All the following conditions are true:

   1. $i1 is an array.

   2. $i2 is an array.

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

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

4. All the following conditions are true:

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

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

   3. $i1 and $i2 have the same function identity. The concept of function identity is explained in [XQuery and XPath Data Model (XDM) 4.0] section 8.1 Function Items.

5. All the following conditions are true:

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

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

   3. Both nodes have the same node kind.

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

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

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

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

      3. Adjacent text nodes are merged.

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

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

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

         Note:

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

   6. One of the following conditions is true.

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

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

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

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

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

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

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

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

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

         8. One of the following conditions is true:

            1. The option type-variety is false.

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

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

            Note:

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

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

            Note:

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

         10. One of the following conditions holds:

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

                Note:

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

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

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

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

                Note:

                Elements annotated as xs:untyped fall into this category.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

         Note:

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

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

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

6. All the following conditions are true:

   1. $i1 is a JNode.

   2. $i2 is a JNode.

   3. The ·content· property of $i1 is deep-equal to the ·content· property of $i2.

      Note:

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

In all other cases the result is false.

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

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

Returns the values that appear in a sequence more than once.

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

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

The items of $values are compared against each other, according to the rules of fn:distinct-values and with $coll as the collation selected according to the rules in 5.3.7 Choosing a collation.The items of $values are compared against each other, according to the rules of fn:distinct-values and with $collation as the collation selected according to the rules in 5.3.7 Choosing a collation.The items of $values are compared against each other, according to the rules of fn:distinct-values and with $collcollation as the collation selected according to the rules in 5.3.7 Choosing a collation.

From each resulting set of values that are considered equal, one value will be returned if the set contains more than one value.

Specifically, the function returns those items in $values that are contextually equal to exactly one item appearing earlier in the sequence.

This means that the ordering of the result is as follows:

• For any set of values that compare equal, the one that is returned is the one that appears second in $values.

• The items that are returned appear in the order of their second appearance within $values.

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

filter(
  $values, 
  fn($item, $pos) {
    count(
      filter(
        subsequence($values, 1, $pos - 1),
        deep-equal(?, $item, $collation)
      )
    ) eq 1
  }
)

Processes a supplied value repeatedly, continuing when some condition is false, and returning the value that satisfies the condition.

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

Informally, the function behaves as follows:

1. $pos is initially set to 1.

2. $action($input, $pos) is evaluated, and the resulting value is used as a new $input.

3. $predicate($input, $pos) is evaluated. If the result is true, the function returns the value of $input. Otherwise, the process repeats from step 2 with $pos incremented by 1.

   When the predicate returns an empty sequence, this is treated as false.When the predicate returns the empty sequence, this is treated as false.When the predicate returns anthe empty sequence, this is treated as false.

The function delivers the same result as the following XQuery implementation.

declare %private function do-until-helper(
  $input     as item()*,
  $action    as fn(item()*, xs:integer) as item()*,
  $predicate as fn(item()*, xs:integer) as xs:boolean?,
  $pos       as xs:integer
) as item()* {
  let $result := $action($input, $pos)
  return if ($predicate($result, $pos)) then (
    $result
  ) else (
    do-until-helper($result, $action, $predicate, $pos + 1)
  )
};

declare function do-until(
  $input     as item()*,
  $action    as fn(item()*, xs:integer) as item()*,
  $predicate as fn(item()*, xs:integer) as xs:boolean?
) as item()* {
  do-until-helper($input, $action, $predicate, 1)
};

Returns true if every item in the input sequence matches a supplied predicate.

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

The function returns true if $input is empty, or if $predicate($item, $pos) returns true for every item $item at position $pos (1-based) in $input.

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

count(filter($input, $predicate)) = count($input)

An error is raised if the $predicate function raises an error. In particular, when the default predicate fn:boolean#1 is used, an error is raised if an item has no effective boolean value.

Returns those items from the sequence $input for which the supplied function $predicate returns true.

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

The function returns a sequence containing those items from $input for which $predicate($item, $pos) returns true, where $item is the item in question, and $pos is its 1-based ordinal position within $input.

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

for-each(
  $input,
  fn($item, $pos) { if ($predicate($item, $pos)) { $item } }
)

As a consequence of the function signature and the function calling rules, a type error occurs if the supplied $predicate function returns anything other than a single xs:boolean item or an empty sequence; there is no conversion to an effective boolean value, but an empty sequence is interpreted as false.As a consequence of the function signature and the function calling rules, a type error occurs if the supplied $predicate function returns anything other than a single xs:boolean item or the empty sequence; there is no conversion to an effective boolean value, but the empty sequence is interpreted as false.As a consequence of the function signature and the function calling rules, a type error occurs if the supplied $predicate function returns anything other than a single xs:boolean item or anthe empty sequence; there is no conversion to an effective boolean value, but anthe empty sequence is interpreted as false.

Returns the positions in an input sequence of items that match a supplied predicate.

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

The result of the function is a sequence of integers, in monotonic ascending order, representing the 1-based positions in the input sequence of those items for which the supplied predicate function returns true. A return value of () from the predicate function is treated as false.

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

for-each(
  $input,
  fn($item, $pos) { if ($predicate($item, $pos)) { $pos } }
)

Returns those items from a supplied sequence that have the lowest value of a sort key, where the sort key can be computed using a caller-supplied function.

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

The second argument, $collation, defaults to ().

Supplying an empty sequence as $collation is equivalent to supplying fn:default-collation(). For more information on collations see 5.3.7 Choosing a collation.Supplying the empty sequence as $collation is equivalent to supplying fn:default-collation(). For more information on collations see 5.3.7 Choosing a collation.Supplying anthe empty sequence as $collation is equivalent to supplying fn:default-collation(). For more information on collations see 5.3.7 Choosing a collation.

The third argument defaults to the function data#1.

Let $modified-key be the function:

fn($item) {
  $key($item) => data() ! (
    if (. instance of xs:untypedAtomic) then xs:double(.) else .
  )
}

That is, the supplied function for computing key values is wrapped in a function that converts any xs:untypedAtomic values in its result to xs:double. This makes the function consistent with the behavior of fn:min and fn:max, but inconsistent with fn:sort, which treats untyped values as strings.

The result of the function is obtained as follows:

• If the input is anthe empty sequence, the result is anthe empty sequence.

• The input sequence is sorted, by applying the function fn:sort($input, $collation, $modified-key).

• Let $C be the selected collation, or the default collation where applicable.

• Let $B be the first item in the sorted sequence.

• The function returns those items $A from the input sequence that are contextually equal to $B, retaining their order.

If the set of computed keys contains xs:untypedAtomic values that are not castable to xs:double then the operation will fail with a dynamic error ([err:FORG0001]^FO).

If the set of computed keys contains values that are not comparable using the lt operator then the sort operation will fail with a type error ([err:XPTY0004]^XP).

Performs partial application of a function item by binding values to selected arguments.

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

The result is a function obtained by binding values to selected arguments of the function item $function. The arguments to be bound are represented by entries in the $arguments map: an entry with key $i and value $v causes the argument at position $i (1-based) to be bound to $v.

Any entries in $arguments whose keys are greater than the arity of $function are ignored.

If $arguments is an empty map then the function returns $function unchanged.If $arguments is the empty map then the function returns $function unchanged.If $arguments is anthe empty map then the function returns $function unchanged.

For example, the effect of calling fn:partial-apply($f, { 2: $x }) is the same as the effect of the partial appplication $f(?, $x, ?, ?, ....). The coercion rules are applied to the supplied arguments in the usual way.

Unlike a partial application using place-holder arguments:

• The arity of $function need not be statically known.

• It is possible to bind all the arguments of $function: the effect is to return a zero-arity function.

The result is a partially applied function^XP having the following properties (which are defined in [XQuery and XPath Data Model (XDM) 4.0] section 8.1 Function Items):

• name: absent.

• identity: A new function identity distinct from the identity of any other function item.

  Note:

  See also [XML Path Language (XPath) 4.0] section 4.6.7 Function Identity.

• arity: The arity of $function minus the number of parameters in $function that map to supplied arguments in $arguments.

• parameter names: The names of the parameters of $function that do not map to supplied arguments in $arguments.

• signature: The parameters in the returned function are the parameters of $function that do not map to supplied arguments in $arguments, retaining order. The result type of the returned function is the same as the result type of $function.

  An implementation that can determine a more specific signature (for example, through use of type analysis) is permitted to do so.

• body: The body of $function.

• captured context: The static and dynamic context of $function, augmented, for each supplied argument, with a binding of the converted argument value to the corresponding parameter name.

A type error is raised if any of the supplied arguments, after applying the coercion rules, does not match the required type of the corresponding function parameter.

In addition, a dynamic error may be raised if any of the supplied arguments does not match other constraints on the value of that argument (for example, if the value supplied for a parameter expecting a regular expression is not a valid regular expression); or if the processor is able to establish that evaluation of the resulting function will fail for any other reason (for example, if an error is raised while evaluating a subexpression in the function body that depends only on explicitly supplied and defaulted parameters).

Returns true if at least one item in the input sequence matches a supplied predicate.

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

The function returns true if (and only if) there is an item $item at position $pos in the input sequence such that $predicate($item, $pos) returns true.

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

exists(filter($input, $predicate))

An error is raised if the $predicate function raises an error. In particular, when the default predicate fn:boolean#1 is used, an error is raised if an item has no effective boolean value.

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

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

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

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

Returns items from the input sequence prior to the first one that fails to match a supplied predicate.

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

The function returns all items in the sequence prior to the first one where the result of calling the supplied $predicate function, with the current item and its position as arguments, returns the value false or ().

If every item in the sequence satisfies the predicate, then $input is returned in its entirety.

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

for $item at $pos in $input
while $predicate($item, $pos)
return $item

Returns all the GNodes reachable from a given start GNode by applying a supplied function repeatedly.

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

The function works with both XNodes and JNodes.

The value of $node is a node from which navigation starts. If $node is an empty sequence, the function returns an empty sequence. The value of $node is a node from which navigation starts. If $node is an empty sequence, the function returns the empty sequence. The value of $node is a node from which navigation starts. If $node is an empty sequence, the function returns anthe empty sequence.

The value of $step is a function that takes a single GNode as input, and returns a set of GNodes as its result.

The result of the fn:transitive-closure function is the set of GNodes that are reachable from $node by applying the $step function one or more times.

Although $step may return any sequence of GNodes, the result is treated as a set: the order of GNodes in the sequence is ignored, and duplicates are ignored. The result of of the transitive-closure function will always be a sequence of GNodes in document order with no duplicates.

The function delivers the same result as the following XQuery implementation.

declare %private function tc-inclusive(
  $nodes as gnode()*,
  $step  as fn(gnode()) as gnode()*
) as gnode()* {
  let $nextStep := $nodes/$step(.)
  let $newNodes := $nextStep except $nodes
  return if (exists($newNodes))
         then $nodes union tc-inclusive($newNodes, $step)
         else $nodes
};

declare function transitive-closure (
  $node as gnode(),
  $step as fn(gnode()) as gnode()*
) as gnode()* {
  tc-inclusive($node/$step(.), $step)
};

(: Explanation:

   The private helper function tc-inclusive takes a set of GNodes as input,
   and calls the $step function on each one of those GNodes; if the result 
   includes GNodes that are not already present in the input, then it makes 
   a recursive call to find GNodes reachable from these new GNodes, and returns
   the union of the supplied GNodes and the GNodes returned from the recursive
   call (which will always include the new GNodes selected in the first step).
   
   If there are no new GNodes, the recursion ends, returning the GNodes that 
   have been found up to this point.
   
   The main function fn:transitive-closure finds the nodes that are reachable 
   from the start GNodes in a single step, and then invokes the helper function 
   tc-inclusive to add GNodes that are reachable in multiple steps.
:)

Processes a supplied value repeatedly, continuing while some condition remains true, and returning the first value that does not satisfy the condition.

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

Informally, the function behaves as follows:

1. $pos is initially set to 1.

2. $predicate($input, $pos) is evaluated. If the result is false or (), the function returns the value of $input.

3. Otherwise, $action($input, $pos) is evaluated, the resulting value is used as a new $input, and the process repeats from step 2 with $pos incremented by 1.

The function delivers the same result as the following XQuery implementation.

declare %private function while-do-helper(
  $input     as item()*,
  $predicate as fn(item()*, xs:integer) as xs:boolean?,
  $action    as fn(item()*, xs:integer) as item()*,
  $pos       as xs:integer
) as item()* {
  if ($predicate($input, $pos))
  then while-do-helper($action($input, $pos), $predicate, $action, $pos + 1)
  else $input
};

declare function while-do(
  $input     as item()*,
  $predicate as fn(item()*, xs:integer) as xs:boolean?,
  $action    as fn(item()*, xs:integer) as item()*
) as item()* {
  while-do-helper($input, $predicate, $action, 1)
};

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

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

General rules: see 4.4 Functions on numeric values.

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

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

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

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

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

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

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

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

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

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

General rules: see 4.4 Functions on numeric values.

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

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

If the second argument is omitted or an empty sequence, the function produces the same result as the two-argument version with $precision = 0. If the second argument is omitted or the empty sequence, the function produces the same result as the two-argument version with $precision = 0. If the second argument is omitted or anthe empty sequence, the function produces the same result as the two-argument version with $precision = 0.

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

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

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

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

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

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

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

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

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

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

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

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

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

A dynamic error is raised [err:FORG0011] if $radix is not in the range 2 to 36.

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

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

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

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.

If $value is an empty sequence, the function returns a zero-length string.If $value is the empty sequence, the function returns a zero-length string.If $value is anthe 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 anthe 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 an 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.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.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 anthe 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 an 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 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 set of languages for which numbering is supported is implementation-defined. If the $language argument is absent, or is set to anthe empty sequence, or is invalid, or is not a language supported by the implementation, then the number is formatted using the default language from the dynamic context.

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

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

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

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

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

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

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

A dynamic error is raised [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.

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

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

The three-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on decimal formats, and namespaces.

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

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

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

If $options is absent, or if it is supplied as an empty sequence or an empty map, then the number is formatted using the properties of the unnamed decimal format in the static context.If $options is absent, or if it is supplied as the empty sequence or the empty map, then the number is formatted using the properties of the unnamed decimal format in the static context.If $options is absent, or if it is supplied as anthe empty sequence or anthe empty map, then the number is formatted using the properties of the unnamed decimal format in the static context.

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

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

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

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

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

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

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

A base decimal format is established as follows:

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

• Otherwise, the unnamed decimal format in the static context.

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

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

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

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

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

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