XPath and XQuery Functions and Operators 4.0

Returns true if all items in a supplied sequence (after atomization) are contextually equal.

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

Omitting the second argument, $collation, is equivalent to supplying fn:default-collation(). For more information on collations see 5.3.7 Choosing a collation.

The result of the function fn:all-equal($values, $collation) is true if and only if the result of fn:count(fn:distinct-values($values, $collation)) le 1 is true (that is, if the sequence is empty, or if all the items in the sequence are equal under the rules of the fn:distinct-values function).

Returns true if no two items in a supplied sequence are contextually equal.

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

Omitting the second argument, $collation, is equivalent to supplying fn:default-collation(). For more information on collations see 5.3.7 Choosing a collation.

The result of the function fn:all-different($values, $collation) is true if and only if the result of fn:count(fn:distinct-values($values, $collation)) eq fn:count($values) is true (that is, if the sequence is empty, or if all the items in the sequence are contextually unequal under the rules used by the fn:distinct-values function).

Returns the average of the values in the input sequence $values, that is, the sum of the values divided by the number of values.

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

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

Any item in $values that is an instance of xs:untypedAtomic is cast to xs:double.

After this conversion, one of the following conditions must be true:

1. Every item in $values is an instance of xs:yearMonthDuration.

2. Every item in $values is an instance of xs:dayTimeDuration.

3. Every item in $values is an instance of xs:numeric.

The function returns the average of the values as sum($values) div count($values); but the implementation may use an otherwise equivalent algorithm that avoids arithmetic overflow. Note that the fn:sum function allows the input sequence to be reordered, which may affect the result in edge cases when the sequence contains a mixture of different numeric types.

A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.

Returns a value that is greater than or equal to every other value appearing in the input sequence.

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.

Any item in $values that is an instance of xs:untypedAtomic is first cast to xs:double. The resulting sequence is referred to as the converted sequence.

All pairs of values in the converted sequence must be mutually comparable. Two values A and B are mutually comparable if fn:compare(A, B) raises no error.

If the converted sequence is empty, the function returns the empty sequence.

If the converted sequence contains the value NaN, the value NaN is returned (as an xs:float or xs:double as appropriate).

Two items A and B from the converted sequence are compared by calling fn:compare(A, B, $collation), where $collation is determined by the rules in 5.3.7 Choosing a collation:

The result of the function is a value from the converted sequence that is greater than or equal to every other value under the above rules. If there is more than one such value, then it is implementation-dependent which of them is returned.

A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.

Returns a value that is less than or equal to every other value appearing in the input sequence.

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.

Any item in $values that is an instance of xs:untypedAtomic is first cast to xs:double. The resulting sequence is referred to as the converted sequence.

All pairs of values in the converted sequence must be mutually comparable. Two values A and B are mutually comparable if fn:compare(A, B) raises no error.

If the converted sequence is empty, the function returns the empty sequence.

If the converted sequence contains the value NaN, the value NaN is returned (as an xs:float or xs:double as appropriate).

Two items A and B from the converted sequence are compared by calling fn:compare(A, B, $collation), where $collation is determined by the rules in 5.3.7 Choosing a collation:

The result of the function is a value from the converted sequence that is less than or equal to every other value under the above rules. If there is more than one such value, then it is implementation-dependent which of them is returned.

A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.

Returns a value obtained by adding together the values in $values.

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

Any value of type xs:untypedAtomic in $values is cast to xs:double. The items in the resulting sequence may be reordered in an arbitrary order. The resulting sequence is referred to below as the converted sequence.

If the converted sequence is empty, then the function returns the value of the argument $zero, which defaults to the xs:integer value 0.

In other cases the items in the converted sequence are added pairwise according the rules of the + operator.

Specifically, the result of the function is the value of the expression:

if (empty($c)) then $zero
else if (count($c) eq 1) then $c
else head($c) + sum(tail($c))

where $c is the converted sequence.

This has the effect that a type error will occur unless one of the following conditions is satisfied:

1. Every item in $values is an instance of xs:yearMonthDuration.

2. Every item in $values is an instance of xs:dayTimeDuration.

3. Every item in $values is an instance of xs:numeric.

A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.

Returns a value that is greater than or equal to every other value appearing in the input sequence.

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.

The third argument, $key, defaults to the function data#1.

Let $modified-key be the function:

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

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

The result of the function is obtained as follows:

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

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

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

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

• The function returns those items $A from the input sequence that are 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).

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

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

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

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

• The function returns those items $A from the input sequence that are 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).

Sorts a supplied sequence, based on the value of a sort key supplied as a function.

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

This function is retained for compatibility from version 3.1 of this specification. Version 4.0 introduces two more powerful functions, fn:sort-by and fn:sort-with.

The function call fn:sort($input, $collation, $key) is defined to have the same effect as the call fn:sort-by($input, { 'key': $key, 'collation': $collation, 'order': 'ascending'}). See fn:sort-by.

The result of the function is a sequence that contains all the items from $input, typically in a different order, the order being defined by the supplied sort key definitions.

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

fn:sort-by($input, { 'key':$key, 'collation':$collation, 'order':'ascending' })

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

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

Computes the effective boolean value of the sequence $input.

The function computes the effective boolean value of a sequence, defined according to the following rules. See also [XML Path Language (XPath) 4.0] section 2.6.4 Effective Boolean Value.

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

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

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

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

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

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

Returns true if the effective boolean value of $input is false, or false if it is true.

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

The value of $input is first reduced to an effective boolean value by applying the fn:boolean() function. The function returns true if the effective boolean value is false, or false if the effective boolean value is true.

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

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 an approximation to the mathematical constant π.

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

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

Returns a random number generator, which can be used to generate sequences of random numbers.

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

The function returns a random number generator. A random number generator is represented as a value of type random-number-generator-record, defined in 4.9.1 Record fn:random-number-generator-record.

Calling the fn:random-number-generator function with no arguments is equivalent to calling the single-argument form of the function with an implementation-dependent seed.

Calling the fn:random-number-generator function with the empty sequence as $seed is equivalent to calling the single-argument form of the function with an implementation-dependent seed.

If a $seed is supplied, it may be an atomic item of any type.

Both forms of the function are deterministic: calling the function twice with the same arguments, within a single execution scope, produces the same results.

The value of the number entry should be such that the distribution of numbers is uniform: for example, the probability of the number being in the range 0.1e0 to 0.2e0 is the same as the probability of its being in the range 0.8e0 to 0.9e0.

The function returned in the permute entry should be such that all permutations of the supplied sequence are equally likely to be chosen.

The map returned by the fn:random-number-generator function may contain additional entries beyond those specified here, but it must match the record type defined above. The meaning of any additional entries is implementation-defined. To avoid conflict with any future version of this specification, the keys of any such entries should start with an underscore character.

Constructs a collation URI with requested properties.

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

The function is supplied with a map defining the properties required of the collation, and returns a collation URI with these properties.

Specifically, it returns a string in the form of a URI with the scheme and path http://www.w3.org/2013/collation/UCA followed by an optional query part. The query part is absent if options is empty. Otherwise it consists of a question mark followed by a sequence of one or more semicolon-separated parameters. Each parameter is a keyword-value pair, the keyword and value being separated by an equals sign. There is one keyword-value pair for each entry in the options map: the keyword is the same as the string value of the key in the map, and the value is the string value of the corresponding value, except where the value is of type xs:boolean, in which case true and false are translated to yes and no.

The function does not check whether the implementation actually recognizes the resulting collation URI: that can be achieved using the fn:collation-available function.

The properties available are as defined for the Unicode Collation Algorithm (see 5.3.4 The Unicode Collation Algorithm). Additional implementation-defined properties may be specified as described in the rules for UCA collation URIs.

The option parameter conventions apply, except as regards the handling of options not defined in this specification. Specifically:

• If the option key is of type xs:string, xs:anyURI, or xs:untypedAtomic then it is converted to a string, and produces a URI query parameter which is handled as described in 5.3.4 The Unicode Collation Algorithm.

• If the option key is of any other type then the function fails with a type error [err:XPTY0004]^XP.

The following options are defined:

A type error is raised [err:XPTY0004]^XP if options includes an entry whose key is not of type xs:string, xs:anyURI, or xs:untypedAtomic, or whose corresponding value is not castable to xs:string.

Asks whether a collation URI is recognized by the implementation, and whether it has required properties.

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

The first argument is a candidate collation URI.

The second argument establishes the intended usage of the collation URI. The value is a sequence containing zero or more of the following:

• compare indicates that the intended purpose of the collation URI is to compare strings for equality or ordering, for example in functions such as fn:index-of, fn:deep-equal, fn:compare, and fn:sort.

• key indicates that the intended purpose of the collation URI is to obtain collation keys for strings using the fn:collation-key function.

• substring indicates that the intended purpose of the collation URI is to establish whether one string is a substring of another, for example in functions such as fn:contains or fn:starts-with.

The function returns true if and only if the implementation recognizes the candidate collation URI as one that can be used for each of the purposes listed in the $usage argument. If the $usage argument is absent or set to the empty sequence, the function returns true only if the collation is available for all purposes.

Returns the timezone offset from UTC that is in conventional use at a given place and time.

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

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

This function uses a database of civil timezones (including daylight savings time) to return the timezone offset for a given date/time and place. For example, the timezone offset for New York on 31 December 2024 would be -PT5H.

If the $place argument is omitted or empty then the default place^XP from the dynamic context is used.

If the supplied $value has no timezone then the implicit timezone from the dynamic context is used. This is unrelated to the timezone applicable to the requested $place.

The intended use of the $place argument is to identify the place where an event represented by the $value argument took place or will take place. The value must be an IANA timezone name as defined in the IANA timezone database [IANA Timezone Database]. Examples are "America/New_York" and "Europe/Rome".

The result of the function is the civil timezone offset applicable to the given date/time and place, as determined by the IANA timezone database or an alternative authoritative source.

A dynamic error is raised [err:FODT0004] if no timezone information is available for the given date/time and place. This includes the case where the given place is not present in the timezone database, and also the case where the information available for that place does not cover a sufficient range of dates.

Returns an xs:QName value formed using a supplied namespace URI and lexical QName.

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

The namespace URI in the returned QName is taken from $uri. If $uri is the zero-length string or the empty sequence, it represents “no namespace”.

The prefix (or absence of a prefix) in $qname is retained in the returned xs:QName value.

The local name in the result is taken from the local part of $qname.

A dynamic error is raised [err:FOCA0002] if $qname does not have the correct lexical form for an instance of xs:QName.

A dynamic error is raised [err:FOCA0002] if $uri is the zero-length string or the empty sequence, and the value of $qname contains a colon (:).

A dynamic error may be raised [err:FOCA0002] if $uri is not a valid URI (XML Namespaces 1.0) or IRI (XML Namespaces 1.1).

Returns an xs:QName value (that is, an expanded-QName) by taking an xs:string that has the lexical form of an xs:QName (a string in the form "prefix:local-name" or "local-name") and resolving it using the in-scope namespaces for a given element.

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

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

More specifically, the function searches the namespace bindings of $element for a binding whose name matches the prefix of $value, or the zero-length string if it has no prefix, and returns an expanded-QName whose local name is taken from the supplied $value, and whose namespace URI is taken from the string value of the namespace binding.

If the $value has no prefix, and there is no namespace binding for $element corresponding to the default (unnamed) namespace, then the resulting expanded-QName has no namespace part.

The prefix (or absence of a prefix) in the supplied $value argument is retained in the returned expanded-QName, as described in [XQuery and XPath Data Model (XDM) 4.0] section 2.1 Terminology.

A dynamic error is raised [err:FOCA0002] if $value does not have the correct lexical form for an instance of xs:QName.

A dynamic error is raised [err:FONS0004] if $value has a prefix and there is no namespace binding for $element that matches this prefix.

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

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

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

If the argument is omitted, it defaults to the context 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()).

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.

This function tests whether the language of $node, or the context value if the second argument is omitted, as specified by xml:lang attributes is the same as, or is a sublanguage of, the language specified by $language.

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

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

The behavior of the function if the second argument is omitted is exactly the same as if the context value (.) had been passed as the second argument.

The language of the argument $node, or the context value if the second argument is omitted, is determined by the value of the xml:lang attribute on the node, or, if the node has no such attribute, by the value of the xml:lang attribute on the nearest ancestor of the node that has an xml:lang attribute. If there is no such ancestor, then the function returns false.

If $language is the empty sequence it is interpreted as the zero-length string.

The relevant xml:lang attribute is determined by the value of the XPath expression:

(ancestor-or-self::*/@xml:lang)[last()]

If this expression returns the empty sequence, the function returns false.

Otherwise, the function returns true if and only if, based on a caseless default match as specified in section 3.13 of [The Unicode Standard], either:

1. $language is equal to the string-value of the relevant xml:lang attribute, or

2. $language is equal to some substring of the string-value of the relevant xml:lang attribute that starts at the start of the string-value and ends immediately before a hyphen, - (HYPHEN-MINUS, #x002D).

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

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

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

Returns a path expression that can be used to select the supplied node relative to the root of its containing document.

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.

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

The behavior of the function if the $nodeargument is omitted is exactly the same as if the context value (.) had been passed as the argument.

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

The $options argument, if present, defines additional parameters controlling how the output is formatted. The option parameter conventions apply. The options available are as follows:

Let R be the GNode supplied in the origin option, or the root GNode of the tree containing $node otherwise.

If $node is a document node, or a JNode with no parent, the function returns the string "/".

Otherwise, the function returns a string that consists of a sequence of steps, one for each ancestor-or-self of $node that is not an ancestor-or-self of R.

If R is an XNode other than a document node and the origin option is absent or empty, then this string is preceded by a string notionally representing a call to the fn:root function, expressed as follows:

• If the lexical option is present with the value true, then the string "fn:root()".

• If the namespaces option is present and defines a mapping from a non empty prefix P to the namespace URI http://www.w3.org/2005/xpath-functions, then "P:root()"

• If the namespaces option is present and defines a mapping from the empty string to the namespace URI http://www.w3.org/2005/xpath-functions, then "root()"

• Otherwise, "Q{http://www.w3.org/2005/xpath-functions}root()".

Each step is the concatenation of:

1. The character "/", which is omitted for the first step if the origin option is present;

2. A string whose form depends on the kind of node selected by that step, as follows:

   1. For an element node, the concatenation of:

      1. A representation of the element name, chosen as follows:

         1. If the lexical option is present with the value true, then the result of applying the name function to the element node.

         2. Otherwise, if the namespaces option is present and the element is in a namespace U and the namespaces option includes a mapping from a prefix P to the namespace U, then the string P:L, where L is the local part of the element name. If there is more than one such prefix, then one of them is chosen arbitrarily.

         3. Otherwise, if the namespaces option is present and the element is in a namespace U and the namespaces option includes a mapping from the zero-length string to the namespace U, then the local part of the element name.

         4. Otherwise, if the namespaces option is present and the element is in no namespace and the namespaces option includes no mapping from the zero-length string to any namespace, then the local part of the element name.

         5. Otherwise, the string Q{U}L, where U is the namespace URI of the element name or the empty string if the element is in no namespace, and L is the local part of the element name.

      2. Unless the indexes option is present with the value false, a string in the form [position] where position is an integer representing the one-based position of the selected node among its like-named siblings.

   2. For an attribute node, the concatenation of:

      1. The character "@"

      2. If the lexical option is present with the value true, then the result of applying the name function to the attribute node.

      3. Otherwise, if the attribute node is in no namespace, the local part of the attribute name.

      4. Otherwise, if the namespaces option is present, and if it includes a mapping from a non-empty namespace prefix P to the namespace URI of the attribute, then a string in the form P:L, where L is the local part of the attribute name. If there is more than one such prefix, then one of them is chosen arbitrarily.

      5. Otherwise, the string Q{U}L, where U is the namespace URI of the attribute name, and L is the local part of the attribute name.

   3. For a text node: text()[position] where position is an integer representing the position of the selected node among its text node siblings.

      The suffix [position] is omitted if the indexes option is present with the value false.

   4. For a comment node: comment()[position] where position is an integer representing the position of the selected node among its comment node siblings.

      The suffix [position] is omitted if the indexes option is present with the value false.

   5. For a processing-instruction node: processing-instruction(local)[position] where local is the name of the processing instruction node and position is an integer representing the position of the selected node among its like-named processing-instruction node siblings.

      The suffix [position] is omitted if the indexes option is present with the value false.

   6. For a namespace node:

      1. If the namespace node has a name: namespace::prefix, where prefix is the local part of the name of the namespace node (which represents the namespace prefix).

      2. If the namespace node has no name (that is, if it represents the default namespace): namespace::*[Ulocal-name() = ""]

         Here Ulocal-name() represents a call on the function fn:local-name and is formatted using the same conventions as the call on fn:root described earlier.

   7. For a JNode where the ·content· property of the parent is an array, then as the string *[N] where N is the value of the ·selector· property.

   8. For any other JNode (including the case where the ·content· property of the parent is a map):

      1. If the value is an xs:string, xs:untypedAtomic, or xs:anyURI that is castable to xs:NCName, then the result of casting the value to xs:NCName.

      2. If the value is an xs:string, xs:untypedAtomic, or xs:anyURI that is not castable to xs:NCName, then then as the string get("S") where S is the string value.

      3. If the value is numeric, then as the string get(N) where N is the result of casting the numeric value to xs:string.

      4. If the value is an xs:QName, then as the string get(#Q{uri}local) where uri and local are the namespace URI and local name parts of the QName.

      5. If the value is an xs:boolean, then as the string get(true()) or get(false()).

      6. If the value is of any other type, then as the string get(xs:T("S")) where T is the local part of the most specific built-in atomic type of which the value is an instance, and S is the result of casting the value to xs:string.

      TODO: Better handling of the case where the parent is neither a map nor an array, for example where it is a sequence of several maps or several arrays. It's hard to provide a better path for these when there is no AxisStep for selecting within such values.TODO: Better handling of the case where the parent is neither a map nor an array, for example where it is a sequence of several maps or several arrays. It's hard to provide a better path for these when there is no AxisStep for selecting within such values.TODO: Better handling of the case where the parent is neither a map nor an array, for example where it is a sequence of several maps or several arrays. It's hard to provide a better path for these when there is no AxisStep for selecting within such values.

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.If the context value is not an instance of the sequence type node()?, type error [err:XPTY0004]^XP.If the context value is not an instance of the sequence type gnodenode()?, type error [err:XPTY0004]^XP.

If the value of the origin option is a node that is not an ancestor of $node (or in the absence of $node, the context value), dynamic error [err:FOPA0001].

Returns the supplied GNode together with its siblings, in document order.

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

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

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

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

If $node is a child of some parent GNode P, the function returns all the children of P (including $node), in document order, as determined by the value of $node/child::gnode().

Otherwise (specifically, if $node is parentless, or if it is an attribute or namespace node), the function returns $node.

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

if ($node intersect $node/parent::gnode()/child::gnode())
then $node/parent::gnode()/child::gnode()
else $node

if ($node intersect $node/parent::node()/child::node())
then $node/parent::node()/child::node()
else $node

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

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

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

Removes duplicate GNodes and sorts the input into document order.

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

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

Returns every GNode within the input sequence that is not an ancestor of another member of the input sequence; the GNodes are returned in document order with duplicates eliminated.

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

The effect of the function call fn:innermost($nodes) is defined to be equivalent to the result of the expression:

$nodes except $nodes/ancestor::gnode()

That is, the function takes as input a sequence of GNodes, and returns every GNode within the sequence that is not an ancestor of another GNode within the sequence; the GNodes are returned in document order with duplicates eliminated.

Returns every GNode within the input sequence that has no ancestor that is itself a member of the input sequence; the nodes are returned in document order with duplicates eliminated.

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

The effect of the function call fn:outermost($nodes) is defined to be equivalent to the result of the expression:

$nodes[not(ancestor::gnode() intersect $nodes)]/.

That is, the function takes as input a sequence of GNodes, and returns every GNode within the sequence that does not have another GNode within the sequence as an ancestor; the GNodes are returned in document order with duplicates eliminated.

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

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

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

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)

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.