XPath and XQuery Functions and Operators 4.0

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

fold-left($input, (), fn($partitions, $next, $pos) {
  if (empty($partitions) or $split-when(foot($partitions)?*, $next, $pos))
  then ($partitions, [ $next ])
  else (trunk($partitions), array { foot($partitions)?*, $next })
})

Produces the complete (ordered) sequence of all partial results from every new value the accumulator is assigned to during the evaluation of fn:fold-left.

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

The function is equivalent to the following implementation in XPath (return clause added in comments for completeness):

let $scan-left-inner := fn(
  $input  as item()*, 
  $zero   as item()*, 
  $action as fn(item()*, item()) as item()*,
  $self   as fn(*)
) as array(*)* {
  let $result := [$zero]
  return if (empty($input)) then (
    $result
  ) else (
    $result, $self(tail($input), $action($zero, head($input)), $action, $self)
  )
}
let $scan-left := fn(
  $input  as item()*, 
  $zero   as item()*, 
  $action as fn(item()*, item()) as item()*
) as array(*)*  {
  $scan-left-inner($input, $zero, $action, $scan-left-inner)
}
(: return $scan-left(1 to 10, 0, op('+'))  :)

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 $zero or the result of a previous application of $action, and the second is any single item from the sequence $input.

Produces the complete (ordered) sequence of all partial results from every new value the accumulator is assigned to during the evaluation of fn:fold-right.

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

The function is equivalent to the following implementation in XPath (return clause in comments added for completeness):

let $scan-right-inner := fn(
  $input  as item()*,
  $zero   as item()*,
  $action as fn(item()*, item()) as item()*, $self as fn(*)
) as array(*)* {
  if (empty($input)) then (
    [ $zero ]
  ) else (
    let $rightResult := $self(tail($input), $zero, $action, $self)
    return ([ $action(head($input), head($rightResult)) ], $rightResult)
  )
}
let $scan-right := function(
  $input as item()*,
  $zero  as item()*,
  $f     as fn(item()*, item()) as item()*
) as array(*)* {
  $scan-right-inner($input, $zero, $f, $scan-right-inner)
}        
(: return $scan-right(1 to 10, 0, op('+')) :)

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 $zero or the result of a previous application of $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.

fold-left($input, false(), fn($result, $item, $pos) {
   $result or $predicate($item, $pos)
})

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)
};