XPath and XQuery Functions and Operators 4.0

Applies a sequence of functions starting with an initial input.

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

Informally, the function behaves as follows:

1. If $functions is empty, then $input is returned, otherwise let $f be the first member of $functions.

2. Let $current-output be the result of fn:apply($f, $input-array) where $input-array is constructed according to the following rules.

   1. If $f has arity 1, let $input-array be an array containing $input as a single member.

   2. Otherwise ($f has arity not equal to 1) if $input is not an array then let $input-array be an array containing each item of $input as a separate member.

   3. Otherwise ($f has arity not equal to 1 and $input is already an array) let $input-array be $input itself.

3. Repeat the process from step 1, passing $current-output as $input and fn:tail($functions) as $functions.

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

let $apply := fn($x, $f)  {
  fn:apply($f,
    if (function-arity($f) eq 1) then [ $x ]
    else if ($x instance of array(*)) then $x 
    else array { $x }
  )
}
return fn($input as item()*, $functions as fn(*)*) as item()* {
  fold-left($functions, $input, $apply)
}

An error [err:FOAP0001] is raised if the arity of any function $f in $functions is different from the number of members in the array that is passed to fn:apply.

An error [err:FORG0006] is raised if any item supplied as a function argument cannot be coerced to the required type.

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.

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.

Processes the supplied sequence from left to right, applying the supplied function repeatedly to each item in turn, together with an accumulated result value.

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

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

If $input contains at least one item, the function calls $action($init, $input[1]), returning a value A₁.

If $input contains a second item, the function then calls $action(A1, $input[2]), returning A₂; to process the nth item it calls $action(An-1, $input[N]).

This continues in the same way until the end of the $input sequence; the final result is the result of the last call on $action.

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

declare function fold-left(
  $input  as item()*,
  $init   as item()*,
  $action as function(item()*, item()) as item()*
) as item()* {
  if (empty($input)) 
  then $init
  else fold-left(tail($input), $action($init, head($input)), $action)
};

As a consequence of the function signature and the function calling rules, a type error occurs if the supplied function $action cannot be applied to two arguments, where the first argument is either the value of $init or the result of a previous application of $action, and the second is any single item from the sequence $input.

Processes the supplied sequence from right to left, applying the supplied function repeatedly to each item in turn, together with an accumulated result value.

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

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

Let I_n be the last item in $input, and let A_n be $init. The function starts by calling $action(In, $init), producing a result A_n-1.

If there is a previous item, I_n-1, the function then calls $action(In-1, An-1), producing the result A_n-2.

This continues in the same way until the start of the $input sequence is reached; the final result is the value A₀.

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

declare function fold-right(
  $input  as item()*,
  $init   as item()*,
  $action as function(item(), item()*) as item()*
) as item()* {
  if (empty($input))
  then $init
  else $action(head($input), fold-right(tail($input), $init, $action))
};

As a consequence of the function signature and the function calling rules, a type error occurs if the supplied function $action cannot be applied to two arguments, where the first argument is any item in the sequence $input, and the second is either the value of $init or the result of a previous application of $action.

Applies the function item $action to every item from the sequence $input in turn, returning the concatenation of the resulting sequences in order.

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

The function calls $action($item, $pos) for each item in $input, where $item is the item in question and $pos is its 1-based ordinal position in $input. The final result is the sequence concatenation of the result of these calls, preserving order.

The function is defined as follows, making use of primitive constructors and accessors defined in [XQuery and XPath Data Model (XDM) 4.0].

dm:iterate-sequence($input, $action)

Applies the function item $action to successive pairs of items taken one from $input1 and one from $input2, returning the concatenation of the resulting sequences in order.

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

The function returns the value of the expression:

for $pos in 1 to min(count($input1), count($input2))
return $action($input1[$pos], $input2[$pos], $pos)

Returns those items from a supplied sequence that have the highest 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.

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 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 such that (fn:deep-equal($key($A), $key($B), $C), retaining their order.

If the set of computed keys contains xs:untypedAtomic values that are not castable to xs:double then 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 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.

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 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 first item in the sorted sequence.

• The function returns those items $A from the input sequence such that (fn:deep-equal($key($A), $key($B), $C), retaining their order.

If the set of computed keys contains xs:untypedAtomic values that are not castable to xs:double then 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.

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 Section 7.1 Function Items^DM):

• name: absent.

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

  Note:

  See also Section 4.5.7 Function Identity^XP.

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

Partitions a sequence of items into a sequence of non-empty arrays containing the same items, starting a new partition when a supplied condition is true.

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

Informally, the function starts by creating a partition containing the first item in the input sequence, if any. For each remaining item J in the input sequence, other than the first, it calls the supplied $split-when function with three arguments: the contents of the current partition, the item J, and the current position in the input sequence.

Each partition is a sequence of items; the function result wraps each partition as an array, and returns the sequence of arrays.

If the $split-when function returns true, the current partition is wrapped as an array and added to the result, and a new current partition is created, initially containing the item J only. If the $split-when function returns false or (), the item J is added to the current partition.

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

for-each(
  $input,
  fn($item, $pos) { map{ 'item': $item, 'pos': $pos } }
)
=> fold-left((), fn($partitions, $pair) {
  if (empty($partitions) or $split-when(foot($partitions)?*, $pair?item, $pair?pos))
  then ($partitions, [ $pair?item ])
  else (trunk($partitions), array { foot($partitions)?*, $pair?item })
})

Produces the sequence of successive partial results from the evaluation of fn:fold-left with the same arguments.

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

The function returns a sequence of N+1 single-member arrays^DM, where N is the number of items in $input. For values of $n in the range 0 to N, the value of the single member of array $n+1 in the result sequence is the value of the expression fold-left( subsequence($input, 1, $n), $init, $action ).

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

(0 to count($input)) 
! [fold-left(subsequence($input, 1, .), $init, $action) ]

Produces the sequence of successive partial results from the evaluation of fn:fold-right with the same arguments.

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

The function returns a sequence of N+1 single-member arrays^DM, where N is the number of items in $input. For values of $n in the range 0 to N, the value of the single member of array $n+1 in the result sequence is the value of the expression fold-right( subsequence($input, count($input)-$n+1), $init, $action ).

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

(0 to count($input)) 
! [ fold-right(subsequence($input, count($input)-.+1), $init, $action) ]

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 has three parts:

1. A sort key function, which is applied to each item in the input sequence to determine a sort key value.

2. A collation, which is used when comparing sort key values that are of type xs:string or xs:untypedAtomic.

3. An order direction, which is ascending or descending.

The number of sort key definitions is determined by the number of function items 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.

The $nth sort key definition (where $n counts from one (1)) is established as follows:

1. The sort key function is $keys[$n] otherwise data#1.

2. The collation is $collations[$n] otherwise $collations[last()] otherwise default-collation(). That is, it is the collation supplied in the corresponding item of the supplied $collations argument; or in its absence, the last entry in $collations; or if $collations is absent or empty, the default collation from the static context of the caller.

3. The order direction is $orders[$n] otherwise $orders[last()] otherwise "ascending". That is, it is "ascending" or "descending" according to the value of the corresponding item in the supplied $orders argument; or in its absence, the last entry in $orders; or if $orders is absent or empty, then "ascending".

When comparing values of types other than xs:string or xs:untypedAtomic, the corresponding collation is ignored, and no error is reported if the supplied value is not a known or valid collation name. If it is necessary to supply such an ignored value (for example, in the case where a non-string sort key is followed by another sort key that requires a collation) the empty string can be supplied.

The result of the 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).

Sorts a supplied sequence, according to the order induced by the supplied comparator functions.

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

Informally, the items of the supplied $input are compared against each other, using the supplied $comparators. The result is a sorted sequence.

Each comparator function takes two items and returns an xs:integer that defines the relationship between these items, in accordance with the fn:compare function:

• The comparators are evaluated one after the other, either completely or until the result is an integer other than 0.

• If the last integer returned is negative or 0, the first item is returned before the second.

• Otherwise, the second item is returned first.

Users are responsible for supplying transitive comparators; otherwise, the result might not be correctly sorted. An example for a non-transitive and thus unsuitable comparator is fn($a, $b) { if ($a mod 2 = 1) then 1 else -1 }, as it considers odd numbers to be greater than even numbers.

Sorting is stable, which means that the relative order of the input items is maintained.

More formally, assuming that the comparators raise no errors and are transitive, the effect of the function is equivalent to the following implementation in XQuery:

declare function sort-with(
  $input       as item()*,
  $comparators as (fn(item(), item()) as xs:integer)*
) as item()* {
  if (count($input) < 2) then (
    $input
  ) else (
    let $head := head($input), $sorted-tail := sort-with(tail($input), $comparators)
    let $diff := fold-left($comparators, 0, fn($df, $cmp) {
      if ($df != 0) then $df else $cmp($head, head($sorted-tail))
    })
    return if ($diff <= 0) then (
      $head, $sorted-tail
    ) else (
      head($sorted-tail), sort-with(($head, tail($sorted-tail)), $comparators)
    )
  )
};

Returns a contiguous sequence of items from $input, with the start and end points located by applying predicates.

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

Informally, the function returns the subsequence of $input starting with the first item that matches the $from predicate, and ending with the first subsequent item that matches the $to predicate. If $from is not supplied, it defaults to the start of $input; if $to is not supplied, it defaults to the end of $input. If $from does not match any items in $input, the result is the empty sequence; if $to does not match any items, all items up to the last are included in the result.

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

let $start := index-where($input, $from)[1] otherwise count($input) + 1
let $end   := index-where($input, $to)[. ge $start][1] otherwise count($input) + 1
return slice($input, $start, $end)

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 nodes reachable from a given start node by applying a supplied function repeatedly.

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

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 $step is a function that takes a single node as input, and returns a set of nodes as its result.

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

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

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

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

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

(: Explanation:

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