XPath and XQuery Functions and Operators 4.0

1.5.3 Function signature

Each function is then defined by specifying its signature(s), which define the types of the parameters and of the result value.

Where functions take a variable number of arguments, two conventions are used:a single function signature is used giving default values for those parameters that can be omitted.

• Wherever possible, a single function signature is used giving default values for those parameters that can be omitted.

• If this is not possible, because the effect of omitting a parameter cannot be specified by giving a default value, multiple signatures are given for the function.

Each function signature is presented in a form like this:

In this notation, function-name, in bold-face, is the local name of the function whose signature is being specified. The prefix fn indicates that the function is in the namespace http://www.w3.org/2005/xpath-functions: this is one of the conventional prefixes listed in 1.3 Namespaces and prefixes. If the function takes no parameters, then the name is followed by an empty parameter list: (); otherwise, the name is followed by a parenthesized list of parameter declarations. Each parameter declaration includes:

• The name of the parameter (which in 4.0 is significant because it can be used as a keyword in a function call)

• The static type of the parameter (in italics)

• If the parameter is optional, then an expression giving the default value (preceded by the symbol :=).

  The default value expression is evaluated using the static and dynamic context of the function caller (or of a named function reference). For example, if the default value is given as ., then it evaluates to the context value from the dynamic context of the function caller; if it is given as default-collation, then its value is the default collation from the static context of the function caller; if it is given as deep-equal#2, then the third argument supplied to deep-equal is the default collation from the static context of the caller.

If there are two or more parameter declarations, they are separated by a comma.

The return-type, also in italics, specifies the static type of the value returned by the function. The dynamic type of the value returned by the function is the same as its static type or derived from the static type. All parameter types and return types are specified using the SequenceType notation defined in 2.5.4 SequenceType Syntax ^XP31.

2.1.12 fn:slice

Summary

Returns a sequence containing selected items from a supplied input sequence based on their position.

Signature

fn:slice(
$input	as item()*,
$start	as xs:integer?as xs:integeras xs:integer?	:= (),:= 0,:= ()0,
$end	as xs:integer?as xs:integeras xs:integer?	:= (),:= 0,:= ()0,
$step	as xs:integer?as xs:integeras xs:integer?	:= ():= 0:= ()0
) as item()*

Properties

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

Rules

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

Let $S be the first of the following that applies:

• If $start is absent, empty, or zero, then 1.If $start is zero, then 1.If $start is absent, empty, or zero, then 1.

• If $start is negative, then fn:count($input) + $start + 1.

• Otherwise, $start.

Let $E be the first of the following that applies:

• If $end is absent, empty, or zero, then fn:count($input).If $end is zero, then fn:count($input).If $end is absent, empty, or zero, then fn:count($input).

• If $end is negative, then fn:count($input) + $end + 1.

• Otherwise, $end.

Let $STEP be the first of the following that applies:

• If $step is absent, empty, or zero, then:If $step is zero, then:If $step is absent, empty, or zero, then:

  • If $E ge $S, then +1

  • Otherwise -1

• Otherwise, $step.

If $STEP is negative, the function returns $input => fn:reverse() => fn:slice(-$S, -$E, -$STEP).

Otherwise the function returns the result of the expression:

$input[position() ge $S and position() le $E and (position() - $S) mod $STEP eq 0]

Editorial note
TBA: define formal equivalent.

Notes

The function is inspired by the slice operators in Javascript and Python, but it differs in detail to accommodate the tradition of 1-based addressing in XPath. The end position is inclusive rather than exclusive, so that in the simple case where $start and $end are positive and $end > $start, fn:slice($in, $start, $end) returns the same result as $in[position() = $start to $end].

This function can be used to enhance the RangeExpression, defined in [XML Path Language (XPath) 4.0] section 4.8.2 Range Expressions, to construct a sequence of integers based on steps other than 1.

Examples

Variables
let $in := ('a', 'b', 'c', 'd', 'e')

Expression	Result
slice($in, start := 2, end := 4)	"b", "c", "d"
slice($in, start := 2)	"b", "c", "d", "e"
slice($in, end := 2)	"a", "b"
slice($in, start := 3, end := 3)	"c"
slice($in, start := 4, end := 3)	"d", "c"
slice($in, start := 2, end := 5, step := 2)	"b", "d"
slice($in, start := 5, end := 2, step := -2)	"e", "c"
slice($in, start := 2, end := 5, step := -2)	()
slice($in, start := 5, end := 2, step := 2)	()
slice($in)	"a", "b", "c", "d", "e"
slice($in, start := -1)	"e"
slice($in, start := -3)	"c", "d", "e"
slice($in, end := -2)	"a", "b", "c", "d"
slice($in, start := 2, end := -2)	"b", "c", "d"
slice($in, start := -2, end := 2)	"d", "c", "b"
slice($in, start := -4, end := -2)	"b", "c", "d"
slice($in, start := -2, end := -4)	"d", "c", "b"
slice($in, start := -4, end := -2, step := 2)	"b", "d"
slice($in, start := -2, end := -4, step := -2)	"d", "b"
slice(("a", "b", "c", "d"), 0)	"a", "b", "c", "d"
slice((1 to 5), step := 2)	1, 3, 5

2.1.13 fn:subsequence

Summary

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

Signature

fn:subsequence(
$input	as item()*,
$start	as xs:double,
$length	as xs:double?	:= ()
) as item()*

Properties

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

Rules

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

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

In the three-argument caseOtherwise, the function returns:

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

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

Formal Equivalent

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

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

Notes

The first item of a sequence is located at position 1, not position 0.

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

In the two-argument case, the function returns a sequence comprising those items of $input whose 1-based position is greater than or equal to $start (rounded to an integer). No error occurs if $start is zero or negative.

In the three-argument case, The function returns a sequence comprising those items of $input whose 1-based position is greater than or equal to $start (rounded to an integer), and less than the sum of $start and $length (both rounded to integers). No error occurs if $start is zero or negative, or if $start plus $length exceeds the number of items in the sequence, or if $length is negative.

As a consequence of the general rules, if $start is -INF and $length is +INF, then fn:round($start) + fn:round($length) is NaN; since position() lt NaN always returns false, the result is an empty sequence.

The reason the function accepts arguments of type xs:double is that many computations on untyped data return an xs:double result; and the reason for the rounding rules is to compensate for any imprecision in these floating-point computations.

Examples

Variables
let $seq := ("item1", "item2", "item3", "item4", "item5")

Expression	Result
subsequence($seq, 4)	"item4", "item5"
subsequence($seq, 3, 2)	"item3", "item4"

2.2.2 fn:compare

Summary

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

Signature

fn:compare(
$value1	as xs:anyAtomicType?,
$value2	as xs:anyAtomicType?,
$collation	as xs:string?as xs:stringas xs:string?	:= fn:default-collation()
) as xs:integer?

Properties

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

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

Rules

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

This function is transitive and symmetric. For example:

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

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

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

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

Otherwise, the result is determined as follows:

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

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

   Note:

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

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

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

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

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

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

   5. Negative zero is equal to positive zero.

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

   Note:

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

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

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

   Note:

   This means that false is treated as less than true.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   Note:

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

   • When both values are zero-length durations.

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

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

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

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

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

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

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

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

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

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

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

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

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

Notes

For numeric values, consider the xs:double value written as 0.1e0 and the xs:decimal value written as 0.1: The mathematical magnitude of this xs:double value is 0.1000000000000000055511151231257827021181583404541015625. Therefore, compare(0.1e0, 0.1) returns +1. By contrast, 0.1e0 lt 0.1 is false and 0.1e0 eq 0.1 is true, because those expressions convert the xs:decimal value 0.1 to the xs:double value 0.1e0 before the comparison.

Although operations such as sorting and the fn:min and fn:max functions invoke fn:compare to perform numeric comparison, these functions in some cases treat NaN differently.

Examples

Expression:	compare('abc', 'abc')
Result:	0
Expression:	compare('Strasse', 'Straße')
Result:	-1
Expression:	compare('Strasse', 'Straße')
Result:	0 (Assuming the default collation equates “ss” and the German letter “ß”.)
Expression:	compare( 'Strasse', 'Straße', collation({ 'lang': 'de', 'strength': 'primary' }) )
Result:	0 (The specified collation equates “ss” and the German letter “ß”.)
Expression:	compare('text', parse-xml('<xml>text</xml>'))
Result:	0
Expression:	compare(9, 10)
Result:	-1
Expression:	compare(123, 123.0)
Result:	0
Expression:	compare(xs:double('NaN'), xs:float('NaN'))
Result:	0
Expression:	compare(xs:double('NaN'), xs:double('-INF'))
Result:	-1
Expression:	compare(xs:double('-INF'), -23)
Result:	-1
Expression:	compare(1, 1e0)
Result:	0
Expression:	compare(1.1, 1.1e0)
Result:	-1
Expression:	compare(1.2, 1.2e0)
Result:	+1
Expression:	compare(9999, xs:double('INF'))
Result:	-1
Expression:	compare(false(), true())
Result:	-1
Expression:	compare(xs:hexBinary(''), xs:base64Binary(''))
Result:	0
Expression:	compare(xs:hexBinary('0001'), xs:hexBinary('0002'))
Result:	-1
Expression:	compare(xs:hexBinary('00FF'), xs:hexBinary('FF'))
Result:	-1
Expression:	compare(xs:time('23:59:59'), xs:time('00:00:00'))
Result:	1
Expression:	compare(xs:time('12:00:00Z'), xs:time('13:00:00+01:00'))
Result:	0
Expression:	compare(xs:date('2001-01-01+01:00'), xs:date('2001-01-01+00:00'))
Result:	-1
Expression:	compare(xs:duration('P1Y'), xs:duration('P13M'))
Result:	-1
Expression:	compare(xs:duration('P1Y'), xs:duration('P1Y3M4D'))
Result:	-1
Expression:	compare(xs:duration('P1Y'), xs:duration('P1000D'))
Result:	+1
Expression:	compare(#space, #xml:space)
Result:	-1
Expression:	compare(#Q{http://example.com/ns}index, #Q{http://example.com/ns}xmp:index)
Result:	0

2.2.3 fn:contains-subsequence

Summary

Determines whether one sequence contains another as a contiguous subsequence, using a supplied callback function to compare items.

Signature

fn:contains-subsequence(
$input	as item()*,
$subsequence	as item()*,
$compare	as (fn(item(), item()) as xs:boolean?)?as fn(item(), item()) as xs:boolean?as (fn(item(), item()) as xs:boolean?)?	:= fn:deep-equal#2
) as xs:boolean

Properties

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

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

Rules

Informally, the function returns true if $input contains a consecutive subsequence matching $subsequence, when items are compared using the supplied (or default) $compare function.Informally, the function returns true if $input contains a consecutive subsequence matching $subsequence, when items are compared using the $compare function.Informally, the function returns true if $input contains a consecutive subsequence matching $subsequence, when items are compared using the supplied (or default) $compare function.

Formal Equivalent

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

some $i in 0 to count($input) - count($subsequence)
satisfies (
  every $j in 1 to count($subsequence)
  satisfies $compare($input[$i + $j], $subsequence[$j])   
)

Notes

There is no requirement that the $compare function should have the traditional qualities of equality comparison. The result is well-defined, for example, even if $compare is not transitive or not symmetric.

A return value of () from the function is treated as false.

Examples

Expression:	contains-subsequence((), ())
Result:	true()
Expression:	contains-subsequence(1 to 10, 3 to 6)
Result:	true()
Expression:	contains-subsequence(1 to 10, (2, 4, 6))
Result:	false()
Expression:	contains-subsequence(1 to 10, ())
Result:	true()
Expression:	contains-subsequence(1 to 10, 1 to 10)
Result:	true()
Expression:	contains-subsequence(1 to 10, 5)
Result:	true()
Expression:	contains-subsequence( 1 to 10, 103 to 105, fn($x, $y) { $x mod 100 = $y mod 100 } )
Result:	true()
Expression:	contains-subsequence( ("A", "B", "C", "D"), ("b", "c"), fn($x, $y) { compare( $x, $y, "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) eq 0 } )
Result:	true()
Expression:	let $chap := parse-xml("<doc><chap><h1/><p/><p/><footnote/></chap></doc>")//chap return contains-subsequence( $chap ! child::*, $chap ! child::p, op("is") )
Result:	true() (True because the p children of the chap element form a contiguous subsequence.)
Expression:	contains-subsequence(10 to 20, (5, 3, 1), op("gt"))
Result:	true()
Expression:	contains-subsequence( ("Alpha", "Beta", "Gamma", "Delta"), ("B", "G"), starts-with#2 )
Result:	true()
Expression:	contains-subsequence( ("Zero", "Alpha", "Beta", "Gamma", "Delta", "Epsilon"), 1 to 4, fn($x, $y) { ends-with($x, 'a') } )
Result:	true() (True because there is a run of 4 consecutive items ending in "a".)

2.2.4 fn:deep-equal

Summary

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

Signature

fn:deep-equal(
$input1	as item()*,
$input2	as item()*,
$options	as (xs:string | map(*))?as (xs:string | map(*))as (xs:string | map(*))?	:= {}
) as xs:boolean

Properties

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

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

Rules

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

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

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

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

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

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

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

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

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

record(
base-uri?	as xs:boolean,
collation?	as xs:string,
comments?	as xs:boolean,
debug?	as xs:boolean,
id-property?	as xs:boolean,
idrefs-property?	as xs:boolean,
in-scope-namespaces?	as xs:boolean,
items-equal?	as fn(item(), item()) as xs:boolean?,
map-order?	as xs:boolean,
namespace-prefixes?	as xs:boolean,
nilled-property?	as xs:boolean,
normalization-form?	as xs:string?,
ordered?	as xs:boolean,
processing-instructions?	as xs:boolean,
timezones?	as xs:boolean,
type-annotations?	as xs:boolean,
type-variety?	as xs:boolean,
typed-values?	as xs:boolean,
unordered-elements?	as xs:QName*,
whitespace?	as enum("preserve", "strip", "normalize")
)

Key	Meaning
base-uri?	Determines whether the base-uri of a node is significant. Type: xs:boolean Default: false
collation?	Identifies a collation which is used at all levels of recursion when strings are compared (but not when names are compared), according to the rules in 5.3.7 Choosing a collation. If the argument is not supplied, or if it is empty, then the default collation from the dynamic context of the caller is used. Type: xs:string Default: fn:default-collation()
comments?	Determines whether comments are significant. Type: xs:boolean Default: false
debug?	Requests diagnostics in the case where the function returns false. When this option is set and the two inputs are found to be not equal, the implementation should output messages (in an implementation-dependent format and to an implementation-dependent destination) indicating the nature of the differences that were found. Type: xs:boolean Default: false
id-property?	Determines whether the id property of elements and attributes is significant. Type: xs:boolean Default: false
idrefs-property?	Determines whether the idrefs property of elements and attributes is significant. Type: xs:boolean Default: false
in-scope-namespaces?	Determines whether the in-scope namespaces of elements are significant. Type: xs:boolean Default: false
items-equal?	A user-supplied function to test whether two items are considered equal. The function can return true or false to indicate that two items are or are not equal, overriding the normal rules that would apply to those items; or it can return an empty sequence, to indicate that the normal rules should be followed. Note that returning () is not equivalent to returning false. Type: fn(item(), item()) as xs:boolean? Default: fn:void#0
map-order?	Determines whether the order of entries in maps is significant. Type: xs:boolean Default: false
namespace-prefixes?	Determines whether namespace prefixes in xs:QName values (particularly the names of elements and attributes) are significant. Type: xs:boolean Default: false
nilled-property?	Determines whether the nilled property of elements and attributes is significant. Type: xs:boolean Default: false
normalization-form?	If present, indicates that text and attributes are converted to the specified Unicode normalization form prior to comparison. The value is as for the corresponding argument of fn:normalize-unicode. Type: xs:string? Default: ()
ordered?	Controls whether the top-level order of the items of the input sequences is considered. Type: xs:boolean Default: true
processing-instructions?	Determines whether processing instructions are significant. Type: xs:boolean Default: false
timezones?	Determines whether timezones in date/time values are significant. Type: xs:boolean Default: false
type-annotations?	Determines whether type annotations are significant. Type: xs:boolean Default: false
type-variety?	Determines whether the variety of the type annotation of an element (whether it has complex content or simple content) is significant. Type: xs:boolean Default: true
typed-values?	Determines whether nodes are compared using their typed values rather than their string values. Type: xs:boolean Default: true
unordered-elements?	A list of QNames of elements considered to be unordered: that is, their child elements may appear in any order. Type: xs:QName* Default: ()
whitespace?	Determines the extent to which whitespace is treated as significant. The value preserve retains all whitespace. The value strip ignores text nodes consisting entirely of whitespace. The value normalize ignores whitespace text nodes in the same way as the strip option, and additionally compares text and attribute nodes after normalizing whitespace in accordance with the rules of the fn:normalize-space function. The detailed rules, given below, also take into account type annotations and xml:space attributes. Type: enum("preserve", "strip", "normalize") Default: preserve

Note:

As a general rule for boolean options (but not invariably), the value true indicates that the comparison is more strict.

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

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

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

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

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

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

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

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

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

1. All of the following conditions are true:

   1. $i1 is an atomic item.

   2. $i2 is an atomic item.

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

   4. One of the following conditions is true:

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

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

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

   5. One of the following conditions is true:

      1. Option namespace-prefixes is false.

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

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

   6. One of the following conditions is true:

      1. Option timezones is false.

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

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

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

2. All of the following conditions are true:

   1. $i1 is a map.

   2. $i2 is a map.

   3. Both maps have the same number of entries.

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

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

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

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

3. All the following conditions are true:

   1. $i1 is an array.

   2. $i2 is an array.

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

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

4. All the following conditions are true:

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

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

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

5. All the following conditions are true:

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

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

   3. Both nodes have the same node kind.

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

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

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

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

      3. Adjacent text nodes are merged.

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

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

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

         Note:

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

   6. One of the following conditions is true.

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

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

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

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

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

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

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

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

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

         8. One of the following conditions is true:

            1. The option type-variety is false.

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

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

            Note:

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

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

            Note:

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

         10. One of the following conditions holds:

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

                Note:

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

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

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

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

                Note:

                Elements annotated as xs:untyped fall into this category.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

         Note:

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

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

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

6. All the following conditions are true:

   1. $i1 is a JNode.

   2. $i2 is a JNode.

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

      Note:

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

In all other cases the result is false.

Error Conditions

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

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

Notes

By default, whitespace in text nodes and attributes is considered significant. There are various ways whitespace differences can be ignored:

• If nodes have been schema-validated, setting the typed-values option to true causes the typed values rather than the string values to be compared. This will typically cause whitespace to be ignored except where the type of the value is xs:string.

• Setting the whitespace option to normalize causes all text and attribute nodes to have leading and trailing whitespace removed, and intermediate whitespace reduced to a single character.

By default, two nodes are not required to have the same type annotation, and they are not required to have the same in-scope namespaces. They may also differ in their parent, their base URI, and the values returned by the is-id and is-idrefs accessors (see [XQuery and XPath Data Model (XDM) 4.0] section 7.6.5 is-id Accessor and [XQuery and XPath Data Model (XDM) 4.0] section 7.6.6 is-idrefs Accessor). The order of children is significant, but the order of attributes is insignificant.

By default, the contents of comments and processing instructions are significant only if these nodes appear directly as items in the two sequences being compared. The content of a comment or processing instruction that appears as a descendant of an item in one of the sequences being compared does not affect the result. In previous versions of this specification, the presence of a comment or processing instruction, if it caused text to be split across two text nodes, might affect the result; this has been changed in 4.0 so that adjacent text nodes are merged after comments and processing instructions have been stripped.

Comparing items of different kind (for example, comparing an atomic item to a node, or a map to an array, or an integer to an xs:date) returns false, it does not return an error. So the result of fn:deep-equal(1, current-dateTime()) is false.

The items-equal callback function may be used to override the default rules for comparing individual items. For example, it might return true unconditionally when comparing two @timestamp attributes, if there is no expectation that the two trees will have identical timestamps. Given two nodes $n1 and $n2, it might compare them using the is operator, so that instead of comparing the descendants of the two nodes, the function simply checks whether they are the same node. Given two function items $f1 and $f2 it might return true unconditionally, knowing that there is no effective way to test if the functions are equivalent. Given two numeric values, it might return true if they are equal to six decimal places.

It is good practice for the items-equal callback function to be reflexive, symmetric, and transitive; if it is not, then the fn:deep-equal function itself will lack these qualities. Reflexive means that every item (including NaN) should be equal to itself; symmetric means that items-equal(A, B) should return the same result as items-equal(B, A), and transitive means that items-equal(A, B) and items-equal(B, C) should imply items-equal(A, C).

Setting the ordered option to false or supplying the unordered-elements option may result in poor performance when comparing long sequences, especially if the items-equal callback function is supplied.

Examples

Variables
let $at := <attendees> <name last="Parker" first="Peter"/> <name last="Barker" first="Bob"/> <name last="Parker" first="Peter"/> </attendees>

Expression:	deep-equal($at, $at/*)
Result:	false()
Expression:	deep-equal($at/name[1], $at/name[2])
Result:	false()
Expression:	deep-equal($at/name[1], $at/name[3])
Result:	true()
Expression:	deep-equal($at/name[1], 'Peter Parker')
Result:	false()
Expression:	deep-equal( $at//name[@first="Bob"], $at//name[@last="Barker"], options := { 'items-equal': op('is') } )
Result:	true() (Tests whether the two input sequences contain exactly the same nodes.)
Expression:	deep-equal([ 1, 2, 3], [ 1, 2, 3 ])
Result:	true()
Expression:	deep-equal((1, 2, 3), [ 1, 2, 3 ])
Result:	false()
Expression:	deep-equal( { 1: 'a', 2: 'b' }, { 2: 'b', 1: 'a' } )
Result:	true()
Expression:	deep-equal( (1, 2, 3, 4), (1, 4, 3, 2), options := { 'ordered': false() } )
Result:	true()
Expression:	deep-equal( (1, 1, 2, 3), (1, 2, 3, 3), options := { 'ordered': false() } )
Result:	false()
Expression:	deep-equal( parse-xml("<a xmlns='AA'/>"), parse-xml("<p:a xmlns:p='AA'/>") )
Result:	true() (By default, namespace prefixes are ignored).
Expression:	deep-equal( parse-xml("<a xmlns='AA'/>"), parse-xml("<p:a xmlns:p='AA'/>"), options := { 'namespace-prefixes': true() } )
Result:	false() (False because the namespace prefixes differ).
Expression:	deep-equal( parse-xml("<a xmlns='AA'/>"), parse-xml("<p:a xmlns:p='AA'/>"), options := { 'in-scope-namespaces': true() } )
Result:	false() (False because the in-scope namespace bindings differ).
Expression:	deep-equal( parse-xml("<a><b/><c/></a>"), parse-xml("<a><c/><b/></a>") )
Result:	false() (By default, order of elements is significant).
Expression:	deep-equal( parse-xml("<a><b/><c/></a>"), parse-xml("<a><c/><b/></a>"), options := { 'unordered-elements': #a } )
Result:	true() (The unordered-elements option means that the ordering of the children of a is ignored.)
Expression:	deep-equal( parse-xml("<para style='bold'><span>x</span></para>"), parse-xml("<para style=' bold'> <span>x</span></para>") )
Result:	false() (By default, both the leading whitespace in the style attribute and the whitespace text node preceding the span element are significant.)
Expression:	deep-equal( parse-xml("<para style='bold'><span>x</span></para>"), parse-xml("<para style=' bold'> <span>x</span></para>"), options := { 'whitespace': 'normalize' } )
Result:	true() (The whitespace option causes both the leading space in the attribute value and the whitespace preceding the span element to be ignored.)
Expression:	deep-equal( (1, 2, 3), (1.0007, 1.9998, 3.0005), options := { 'items-equal': fn($x, $y) { if (($x, $y) instance of xs:numeric+) { abs($x - $y) lt 0.001 } } } )
Result:	true() (For numeric values, the callback function tests whether they are approximately equal. For any other items, it returns an empty sequence, so the normal comparison rules apply.)
Expression:	deep-equal( (1, 2, 3, 4, 5), (1, 2, 3, 8, 5), options := { 'items-equal': fn($x, $y) { trace((), `comparing { $x } and { $y }`) } } )
Result:	false() (The callback function traces which items are being compared, without changing the result of the comparison.)

2.2.5 fn:distinct-values

Summary

Returns the values that appear in a sequence, with duplicates eliminated.

Signature

fn:distinct-values(
$values	as xs:anyAtomicType*,
$collation	as xs:string?as xs:stringas xs:string?	:= fn:default-collation()
) as xs:anyAtomicType*

Properties

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.

Rules

The function returns the sequence that results from removing from $values all but one of a set of values that are contextually equal to one another, when compared using the collation selected according to the rules in 5.3.7 Choosing a collation and the implicit timezone from the dynamic context.

The ordering of the result is as follows:

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

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

Formal Equivalent

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

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

Notes

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

Values of type xs:untypedAtomic are compared as if they were of type xs:string.

Values that cannot be compared, because the eq operator is not defined for their types, are considered to be distinct.

For numeric values, the rules are the same as fn:atomic-equal: positive and negative zero are treated as equal, NaN is treated as equal to NaN, and values of different numeric types are converted to unlimited-precision decimals for comparison purposes.

If xs:dateTime, xs:date or xs:time values do not have a timezone, they are considered to have the implicit timezone provided by the dynamic context for the purpose of comparison. Note that xs:dateTime, xs:date or xs:time values can compare equal even if their timezones are different.

Examples

Expression	Result
distinct-values((1, 2.0, 3, 2))	1, 2.0, 3
distinct-values(( xs:untypedAtomic("cherry"), xs:untypedAtomic("plum"), xs:untypedAtomic("plum") ))	xs:untypedAtomic("cherry"), xs:untypedAtomic("plum")

2.2.6 fn:duplicate-values

Summary

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

Signature

fn:duplicate-values(
$values	as xs:anyAtomicType*,
$collation	as xs:string?as xs:stringas xs:string?	:= fn:default-collation()
) as xs:anyAtomicType*

Properties

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.

Rules

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

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

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

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

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

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

Formal Equivalent

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

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

Notes

The comparison rules are exactly the same as the fn:distinct-values function.

Examples

Expression:	duplicate-values((1, 2, 3, 1.0, 1e0))
Result:	1.0
Expression:	duplicate-values(1 to 100)
Result:	()
Expression:	duplicate-values(('1', <x>1</x>, '2', 2))
Result:	xs:untypedAtomic("1") (The string "1" and the untyped value of the element node are considered equal, whereas the string "2" and the integer are considered unequal.)
Raise an error for duplicates in an ID sequence:
let $ids := duplicate-values(//@id) where exists($ids) return error((), 'Duplicate IDs found: ' || string-join($ids, ', '))

2.2.7 fn:ends-with-subsequence

Summary

Determines whether one sequence ends with another, using a supplied callback function to compare items.

Signature

fn:ends-with-subsequence(
$input	as item()*,
$subsequence	as item()*,
$compare	as (fn(item(), item()) as xs:boolean?)?as fn(item(), item()) as xs:boolean?as (fn(item(), item()) as xs:boolean?)?	:= fn:deep-equal#2
) as xs:boolean

Properties

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

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

Rules

Informally, the function returns true if $input ends with $subsequence, when items are compared using the supplied (or default) $compare function.Informally, the function returns true if $input ends with $subsequence, when items are compared using the $compare function.Informally, the function returns true if $input ends with $subsequence, when items are compared using the supplied (or default) $compare function.

Formal Equivalent

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

starts-with-subsequence(reverse($input), reverse($subsequence), $compare)

Notes

There is no requirement that the $compare function should have the traditional qualities of equality comparison. The result is well-defined, for example, even if $compare is not transitive or not symmetric.

A return value of () from the function is treated as false.

Examples

Expression:	ends-with-subsequence((), ())
Result:	true()
Expression:	ends-with-subsequence(1 to 10, 5 to 10)
Result:	true()
Expression:	ends-with-subsequence(1 to 10, ())
Result:	true()
Expression:	ends-with-subsequence(1 to 10, 1 to 10)
Result:	true()
Expression:	ends-with-subsequence(1 to 10, 10)
Result:	true()
Expression:	ends-with-subsequence( 1 to 10, 108 to 110, fn($x, $y) { $x mod 100 = $y mod 100 } )
Result:	true()
Expression:	ends-with-subsequence( ("A", "B", "C"), ("b", "c"), fn($x, $y) { compare( $x, $y, "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) eq 0 } )
Result:	true()
Expression:	let $p := parse-xml("<doc><chap><p/><p/></chap></doc>")//p[2] return ends-with-subsequence( $p/ancestor::node()[last()], $p/root(), op("is") )
Result:	true()
Expression:	ends-with-subsequence(10 to 20, 1 to 5, op("gt"))
Result:	true()
Expression:	ends-with-subsequence( ("Alpha", "Beta", "Gamma"), ("B", "G"), starts-with#2 )
Result:	true()
Expression:	ends-with-subsequence( ("Alpha", "Beta", "Gamma", "Delta"), 1 to 2, fn($x, $y) { string-length($x) eq 5 } )
Result:	true() (True because the last two items in the input sequence have a string length of 5.)

2.2.8 fn:index-of

Summary

Returns a sequence of positive integers giving the positions within the sequence $input of items that are contextually equal to $target.

Signature

fn:index-of(
$input	as xs:anyAtomicType*,
$target	as xs:anyAtomicType,
$collation	as xs:string?as xs:stringas xs:string?	:= fn:default-collation()
) as xs:integer*

Properties

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

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

Rules

The function returns a sequence of positive integers giving the 1-based positions within the sequence $input of items that are contextually equal to $target.

The collation used by this function is determined according to the rules in 5.3.7 Choosing a collation. This collation is used when string comparison is required.

The result sequence is in ascending numeric order.

Notes

If $input is the empty sequence, or if no item in $input matches $target, then the function returns the empty sequence.

No error occurs if non-comparable values are encountered. So when comparing two atomic items, the effective boolean value of fn:index-of($a, $b) is true if $a and $b are equal, false if they are not equal or not comparable.

Examples

Expression:	index-of((10, 20, 30, 40), 35)
Result:	()
Expression:	index-of((10, 20, 30, 30, 20, 10), 20)
Result:	2, 5
Expression:	index-of( ("a", "sport", "and", "a", "pastime"), "a" )
Result:	1, 4
Expression:	index-of( ("a", "b", "c"), "B", "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" )
Result:	2
Expression:	index-of(current-date(), 23)
Result:	()
Expression:	index-of([ 1, [ 5, 6 ], [ 6, 7 ] ], 6)
Result:	3, 4 (The array is atomized to a sequence of five integers).
If @a is an attribute of type xs:NMTOKENS whose string value is "red green blue", and whose typed value is therefore ("red", "green", "blue"), then fn:index-of(@a, "blue") returns 3. This is because the function calling mechanism atomizes the attribute node to produce a sequence of three xs:NMTOKEN values.

2.2.9 fn:starts-with-subsequence

Summary

Determines whether one sequence starts with another, using a supplied callback function to compare items.

Signature

fn:starts-with-subsequence(
$input	as item()*,
$subsequence	as item()*,
$compare	as (fn(item(), item()) as xs:boolean?)?as fn(item(), item()) as xs:boolean?as (fn(item(), item()) as xs:boolean?)?	:= fn:deep-equal#2
) as xs:boolean

Properties

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

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

Rules

Informally, the function returns true if $input starts with $subsequence, when items are compared using the supplied (or default) $compare function.Informally, the function returns true if $input starts with $subsequence, when items are compared using the $compare function.Informally, the function returns true if $input starts with $subsequence, when items are compared using the supplied (or default) $compare function.

Formal Equivalent

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

count($input) ge count($subsequence) and
every(for-each-pair($input, $subsequence, $compare))

Notes

There is no requirement that the $compare function should have the traditional qualities of equality comparison. The result is well-defined, for example, even if $compare is not transitive or not symmetric. A return value of () from the function is treated as false.

Examples

Expression:	starts-with-subsequence((), ())
Result:	true()
Expression:	starts-with-subsequence(1 to 10, 1 to 5)
Result:	true()
Expression:	starts-with-subsequence(1 to 10, ())
Result:	true()
Expression:	starts-with-subsequence(1 to 10, 1 to 10)
Result:	true()
Expression:	starts-with-subsequence(1 to 10, 1)
Result:	true()
Expression:	starts-with-subsequence( 1 to 10, 101 to 105, fn($x, $y) { $x mod 100 = $y mod 100 } )
Result:	true()
Expression:	starts-with-subsequence( ("A", "B", "C"), ("a", "b"), fn($x, $y) { compare( $x, $y, "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) eq 0 } )
Result:	true()
Expression:	let $p := parse-xml("<doc><chap><p/><p/></chap></doc>")//p[2] return starts-with-subsequence( $p/ancestor::*[1], $p/parent::*, op("is") )
Result:	true()
Expression:	starts-with-subsequence(10 to 20, 1 to 5, op("gt"))
Result:	true()
Expression:	starts-with-subsequence( ("Alpha", "Beta", "Gamma"), ("A", "B"), starts-with#2 )
Result:	true()
Expression:	starts-with-subsequence( ("Alpha", "Beta", "Gamma", "Delta"), 1 to 3, fn($x, $y) { ends-with($x, 'a' ) } )
Result:	true() (True because the first three items in the input sequence end with "a".)

2.4.2 fn:all-equal

Summary

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

Signature

fn:all-equal(
$values	as xs:anyAtomicType*,
$collation	as xs:string?as xs:stringas xs:string?	:= fn:default-collation()
) as xs:boolean

Properties

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

Rules

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 collation used by this function is determined according to the rules in 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).

Examples

Expression:	all-equal((1, 2, 3))
Result:	false()
Expression:	all-equal((1, 1.0, 1.0e0))
Result:	true()
Expression:	all-equal("one")
Result:	true()
Expression:	all-equal(())
Result:	true()
Expression:	all-equal((xs:float('NaN'), xs:double('NaN')))
Result:	true()
Expression:	all-equal( ("ABC", "abc"), "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" )
Result:	true()
The expression fn:all-equal(//p/@class) returns true if all p elements have the same value for @class.
The expression fn:all-equal(* ! fn:node-name()) returns true if all element children of the context node have the same name.

2.4.3 fn:all-different

Summary

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

Signature

fn:all-different(
$values	as xs:anyAtomicType*,
$collation	as xs:string?as xs:stringas xs:string?	:= fn:default-collation()
) as xs:boolean

Properties

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

Rules

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 collation used by this function is determined according to the rules in 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).

Examples

Expression:	all-different((1, 2, 3))
Result:	true()
Expression:	all-different((1, 1.0, 1.0e0))
Result:	false()
Expression:	all-different("one")
Result:	true()
Expression:	all-different(())
Result:	true()
Expression:	all-different( ("ABC", "abc"), "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" )
Result:	false()
The expression fn:all-different(//employee/@ssn) is true if no two employees have the same value for their @ssn attribute.
The expression fn:all-different(* ! fn:node-name()) returns true if all element children of the context node have distinct names.

2.4.5 fn:max

Summary

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

Signature

fn:max(
$values	as xs:anyAtomicType*,
$collation	as xs:string?as xs:stringas xs:string?	:= fn:default-collation()
) as xs:anyAtomicType?

Properties

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.

Rules

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.

Error Conditions

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

Notes

If there are two or items that are “equal highest”, the specific item whose value is returned is implementation-dependent. This can arise for example if two different strings compare equal under the selected collation, or if two different xs:dateTime values compare equal despite being in different timezones.

If the converted sequence contains exactly one value then that value is returned.

The default type when the fn:max function is applied to xs:untypedAtomic values is xs:double. This differs from the default type for operators such as lt, and for sorting in XQuery and XSLT, which is xs:string.

In version 4.0, if $values is a sequence of xs:decimal values (including the case where it is a sequence of xs:integer values), then the result will be one of these xs:decimal or xs:integer values. In earlier versions it would be the result of converting this xs:decimal to xs:float or xs:double.

Examples

Expression	Result
max((3, 2, 1))	3
max([ 3, 2, 1 ])	3 (Arrays are atomized).
max(( xs:integer(5), xs:float(5), xs:double(0) ))	5 (The result may be either the xs:integer or the xs:float, since they are equal.)
max(( xs:float(0.0E0), xs:float(-0.0E0) ))	xs:float(0.0e0) (The result may be either positive or negative zero, since they are equal.)
max(( current-date(), xs:date("2100-01-01") ))	xs:date("2100-01-01") (Assuming that the current date is during the 21st century.)
max(("a", "b", "c"))	"c" (Assuming a typical default collation.)
max((3, 4, "Zero")) raises a type error [err:FORG0006].

2.4.6 fn:min

Summary

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

Signature

fn:min(
$values	as xs:anyAtomicType*,
$collation	as xs:string?as xs:stringas xs:string?	:= fn:default-collation()
) as xs:anyAtomicType?

Properties

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.

Rules

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.

Error Conditions

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

Notes

If there are two or items that are “equal lowest”, the specific item whose value is returned is implementation-dependent. This can arise for example if two different strings compare equal under the selected collation, or if two different xs:dateTime values compare equal despite being in different timezones.

If the converted sequence contains exactly one value then that value is returned.

The default type when the fn:min function is applied to xs:untypedAtomic values is xs:double. This differs from the default type for operators such as lt, and for sorting in XQuery and XSLT, which is xs:string.

In version 4.0, if $values is a sequence of xs:decimal values (including the case where it is a sequence of xs:integer values), then the result will be one of these xs:decimal or xs:integer values. In earlier versions it would be the result of converting this xs:decimal to xs:float or xs:double.

Examples

Expression	Result
min((3, 4, 5))	3
min([ 3, 4, 5 ])	3 (Arrays are atomized).
min(( xs:integer(5), xs:float(5), xs:double(10) ))	5 (The result may be either the xs:integer or the xs:float, since they are equal.)
min(( xs:float(0.0E0), xs:float(-0.0E0) ))	xs:float(0.0e0) (The result may be either positive or negative zero, since they are equal.)
min(( current-date(), xs:date("1900-01-01") ))	xs:date("1900-01-01") (Assuming that the current date is set to a reasonable value.)
min(("a", "b", "c"))	"a" (Assuming a typical default collation.)
min((3, 4, "Zero")) raises a type error [err:FORG0006].

2.4.7 fn:sum

Summary

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

Signature

fn:sum(
$values	as xs:anyAtomicType*,
$zero	as xs:anyAtomicType?	:= 0
) as xs:anyAtomicType?

Properties

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

Rules

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.If the converted sequence is empty, then the function returns the value of the argument $zero.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.

Error Conditions

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

Notes

The second argument allows an appropriate value to be defined to represent the sum of an empty sequence. For example, when summing a sequence of durations it would be appropriate to return a zero-length duration of the appropriate type. This argument is necessary because a system that does dynamic typing cannot distinguish “an empty sequence of integers", for example, from “an empty sequence of durations”.

The explicit or implicit value of the $zero argument is used only when the input sequence is empty, not when a non-empty sequence sums to zero. For example, sum((-1, +1), xs:double('NaN')) returns the xs:integer value 0, not NaN.

The sum of a sequence of integers will be an integer, while the sum of a numeric sequence that includes at least one xs:double will be an xs:double.

If the converted sequence contains exactly one value then that value is returned.

If the converted sequence contains the value NaN, NaN is returned.

In edge cases the fact that the input sequence may be reordered makes the result slightly unpredictable. For example, if the input contains two xs:decimal values and an xs:float, then the decimal values might be added using decimal arithmetic, or they might both be converted to xs:float (potentially losing precision) before any arithmetic is performed.

Examples

Variables
let $d1 := xs:yearMonthDuration("P20Y")
let $d2 := xs:yearMonthDuration("P10M")
let $seq1 := ($d1, $d2)
let $seq3 := (3, 4, 5)

Expression:	sum(($d1, $d2))
Result:	xs:yearMonthDuration("P20Y10M")
Expression:	sum( $seq1[. lt xs:yearMonthDuration('P3M')], xs:yearMonthDuration('P0M') )
Result:	xs:yearMonthDuration("P0M")
Expression:	sum($seq3)
Result:	12
Expression:	sum(())
Result:	0
Expression:	sum((),())
Result:	()
Expression:	sum((1 to 100)[. lt 0], 0)
Result:	0
Expression:	sum(($d1, $d2), "ein Augenblick")
Result:	xs:yearMonthDuration("P20Y10M") (There is no requirement that the $zero value should be the same type as the items in $value, or even that it should belong to a type that supports addition.)
Expression:	sum([ 1, 2, 3 ])
Result:	6 (Atomizing an array returns the sequence obtained by atomizing its members.)
Expression:	sum([ [ 1, 2 ], [ 3, 4 ] ])
Result:	10 (Atomizing an array returns the sequence obtained by atomizing its members.)
fn:sum(($d1, 9E1)) raises a type error [err:FORG0006].

2.5.3 fn:every

Summary

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

Signature

fn:every(
$input	as item()*,
$predicate	as (fn(item(), xs:integer) as xs:boolean?)?as fn(item(), xs:integer) as xs:boolean?as (fn(item(), xs:integer) as xs:boolean?)?	:= fn:boolean#1
) as xs:boolean

Properties

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

Rules

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.

Formal Equivalent

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

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

Error Conditions

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.

Notes

If the second argument is omitted or an empty sequence, the predicate defaults to fn:boolean#1, which takes the effective boolean value of each item.

It is possible for the supplied $predicate to be a function whose arity is less than two. The coercion rules mean that the additional parameters are effectively ignored. Frequently a predicate function will only consider the item itself, and disregard its position in the sequence.

The predicate is required to return either true, false, or an empty sequence (which is treated as false). A predicate such as fn { self::h1 } results in a type error because it returns a node, not a boolean.

The implementation may deliver a result as soon as one item is found for which the predicate returns false; it is not required to evaluate the predicate for every item, nor is it required to examine items sequentially from left to right.

Examples

Expression:	every(())
Result:	true()
Expression:	every((1 = 1, 2 = 2, 3 = 4))
Result:	false()
Expression:	every((), boolean#1)
Result:	true()
Expression:	every((1, 3, 7), fn { . mod 2 = 1 })
Result:	true()
Expression:	every(-5 to +5, fn { . ge 0 })
Result:	false()
Expression:	every( ("January", "February", "March", "April", "September", "October", "November", "December"), contains(?, "r") )
Result:	true()
Expression:	every( ("January", "February", "March", "April", "September", "October", "November", "December") =!> contains("r") )
Result:	true()
Expression:	every((1, 2, number('NaN')))
Result:	false() (The effective boolean value of NaN is false.)
Expression:	every(1 to 5, fn($num, $pos) { $num = $pos })
Result:	true()
Expression:	let $dl := <dl><dt>Morgawr</dt><dd>Sea giant</dd></dl> return every($dl/*, fn($elem, $pos) { name($elem) = ( if (($pos mod 2)) then "dt" else "dd" ) })
Result:	true()

2.5.9 fn:highest

Summary

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

Signature

fn:highest(
$input	as item()*,
$collation	as xs:string?as xs:stringas xs:string?	:= fn:default-collation(),
$key	as (fn(item()) as xs:anyAtomicType*)?as fn(item()) as xs:anyAtomicType*as (fn(item()) as xs:anyAtomicType*)?	:= fn:data#1
) as item()*

Properties

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

Rules

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.

Error Conditions

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

Examples

Variables
let $e := <a x="10" y="5" z="2"/>

Expression:	highest($e/@*) ! name()
Result:	"x" (By default, untyped values are compared as numbers.)
Expression:	highest($e/@*, (), string#1) ! name()
Result:	"y" (Here, the attribute values are compared as strings.)
Expression:	highest(("red", "green", "blue"), (), string-length#1)
Result:	"green"
Expression:	highest( ("red", "green", "blue"), key := { "red" : xs:hexBinary('FF0000'), "green": xs:hexBinary('008000'), "blue" : xs:hexBinary('0000FF') } )
Result:	"red"
Expression:	highest( ("red", "orange", "yellow", "green", "blue", "indigo", "violet"), key := string-length#1 )
Result:	"orange", "yellow", "indigo", "violet"
Expression:	highest(1 to 25, (), fn { . idiv 10 })
Result:	20, 21, 22, 23, 24, 25
To find employees having the highest salary:
highest($employees, (), fn { xs:decimal(salary) })

2.5.11 fn:lowest

Summary

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.

Signature

fn:lowest(
$input	as item()*,
$collation	as xs:string?as xs:stringas xs:string?	:= fn:default-collation(),
$key	as (fn(item()) as xs:anyAtomicType*)?as fn(item()) as xs:anyAtomicType*as (fn(item()) as xs:anyAtomicType*)?	:= fn:data#1
) as item()*

Properties

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

Rules

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.

The collation used by this function is determined according to the rules in 5.3.7 Choosing a collation.

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 that are contextually equal to $B, retaining their order.

Error Conditions

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

Examples

Variables
let $e := <a x="10" y="5" z="2"/>

Expression:	lowest($e/@*) ! name()
Result:	"z" (By default, untyped values are compared as numbers.)
Expression:	lowest($e/@*, (), string#1) ! name()
Result:	"x" (Here, the attribute values are compared as strings.)
Expression:	lowest(("red", "green", "blue"), (), string-length#1)
Result:	"red"
Expression:	lowest( ("red", "green", "blue"), key := { "red" : xs:hexBinary('FF0000'), "green": xs:hexBinary('008000'), "blue" : xs:hexBinary('0000FF') } )
Result:	"blue"
Expression:	lowest( ("April", "June", "July", "August"), key := string-length#1 )
Result:	"June", "July"
Expression:	lowest(1 to 25, (), fn { . idiv 10 })
Result:	1, 2, 3, 4, 5, 6, 7, 8, 9
To find employees having the lowest salary:
lowest($employees, (), fn { xs:decimal(salary) })

2.5.16 fn:some

Summary

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

Signature

fn:some(
$input	as item()*,
$predicate	as (fn(item(), xs:integer) as xs:boolean?)?as fn(item(), xs:integer) as xs:boolean?as (fn(item(), xs:integer) as xs:boolean?)?	:= fn:boolean#1
) as xs:boolean

Properties

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

Rules

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.

Formal Equivalent

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

exists(filter($input, $predicate))

Error Conditions

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.

Notes

If the second argument is omitted or an empty sequence, the predicate defaults to fn:boolean#1, which takes the effective boolean value of each item.

It is possible for the supplied $predicate to be a function whose arity is less than two. The coercion rules mean that the additional parameters are effectively ignored. Frequently a predicate function will only consider the item itself, and disregard its position in the sequence.

The predicate is required to return either true, false, or an empty sequence (which is treated as false). A predicate such as fn { self::h1 } results in a type error because it returns a node, not a boolean.

The implementation may deliver a result as soon as one item is found for which the predicate returns true; it is not required to evaluate the predicate for every item, nor is it required to examine items sequentially from left to right.

Examples

Expression:	some(())
Result:	false()
Expression:	some((1 = 1, 2 = 2, 3 = 4))
Result:	true()
Expression:	some((), boolean#1)
Result:	false()
Expression:	some((1, 3, 7), fn { . mod 2 = 1 })
Result:	true()
Expression:	some(-5 to +5, fn { . ge 0 })
Result:	true()
Expression:	some( ("January", "February", "March", "April", "September", "October", "November", "December"), contains(?, "z") )
Result:	false()
Expression:	some( ("January", "February", "March", "April", "September", "October", "November", "December") =!> contains("r") )
Result:	true()
Expression:	some(("", 0, number('NaN')))
Result:	false() (The effective boolean value in each case is false.)
Expression:	some(reverse(1 to 5), fn($num, $pos) { $num = $pos })
Result:	true()

2.5.17 fn:sort

Summary

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

Signature

fn:sort(
$input	as item()*,
$collation	as xs:string?as xs:stringas xs:string?	:= fn:default-collation(),
$key	as fn(item()) as xs:anyAtomicType*	:= fn:data#1
) as item()*

Properties

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

Rules

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.

Formal Equivalent

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

Error Conditions

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

Examples

Expression:	sort((1, 4, 6, 5, 3))
Result:	1, 3, 4, 5, 6
Expression:	sort((1, -2, 5, 10, -10, 10, 8), (), abs#1)
Result:	1, -2, 5, 8, 10, -10, 10
To sort a set of strings $in using Swedish collation:
let $SWEDISH := collation({ 'lang': 'se' }) return sort($in, $SWEDISH)
To sort a sequence of employees by last name as the major sort key and first name as the minor sort key, using the default collation:
sort($employees, (), fn { name ! (last, first) })

2.5.20 fn:subsequence-where

Summary

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

Signature

fn:subsequence-where(
$input	as item()*,
$from	as (fn(item(), xs:integer) as xs:boolean?)?as fn(item(), xs:integer) as xs:booleanas (fn(item(), xs:integer) as xs:boolean?)?	:= true#0,
$to	as (fn(item(), xs:integer) as xs:boolean?)?as fn(item(), xs:integer) as xs:booleanas (fn(item(), xs:integer) as xs:boolean?)?	:= false#0
) as item()*

Properties

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

Rules

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.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 true#0, it matches for the first item; if $to is false#0, it accepts all remaining items. 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.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 suppliedtrue#0, it defaults to the start of matches for the first item$input; if $to is not suppliedfalse#0, it defaults to the end of accepts all remaining items$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.

Formal Equivalent

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)

Notes

The result includes both the item that matches the $from condition and the item that matches the $to condition. To select a subsequence that starts after the $from item, apply the fn:tail function to the result. To select a subsequence that ends before the $to item, apply the fn:trunk function to the result.

The predicate functions supplied to the $from and $to parameters can include an integer position argument as well as the item itself. This position will always be 1-based, relative to the start of $input. This means it is possible to select items based on their absolute position in the $input sequence, but there is no mechanism to select an end position relative to the start position. If this is needed, the function can be combined with others: for example, to select a subsequence of four items starting with "Barbara", use $input => subsequence-where(fn { . eq "Barbara" }) => slice(end := 4).

If the requirement is to select all elements stopping before the first h2 element if it exists, or up to the end of the sequence otherwise, the simplest solution is perhaps to write:

slice($input, end:=index-where($input, fn { boolean(self::h2) })[1])

A return value of () from the $from or $to predicate is treated as false.

Examples

Variables
let $names := ("Anna", "Barbara", "Catherine", "Delia", "Eliza", "Freda", "Gertrude", "Hilda")

Expression:	subsequence-where($names, starts-with(?, "E"))
Result:	"Eliza", "Freda", "Gertrude", "Hilda"
Expression:	subsequence-where($names, to := starts-with(?, "D"))
Result:	"Anna", "Barbara", "Catherine", "Delia"
Expression:	subsequence-where($names, to := starts-with(?, "D")) => trunk()
Result:	"Anna", "Barbara", "Catherine"
Expression:	subsequence-where($names, starts-with(?, "E"), starts-with(?, "G"))
Result:	"Eliza", "Freda", "Gertrude"
Expression:	subsequence-where( $names, starts-with(?, "D"), fn { string-length(.) gt 5 } )
Result:	"Delia", "Eliza", "Freda", "Gertrude"
Expression:	subsequence-where($names, starts-with(?, "M"))
Result:	()
Expression:	subsequence-where($names, starts-with(?, "G"), starts-with(?, "Z"))
Result:	"Gertrude", "Hilda"
Expression:	subsequence-where($names)
Result:	"Anna", "Barbara", "Catherine", "Delia", "Eliza", "Freda", "Gertrude", "Hilda"
Expression:	subsequence-where( $names, fn($it, $pos) { ends-with($it, "a") and $pos gt 5 } )
Result:	"Freda", "Gertrude", "Hilda"
Expression:	subsequence-where( $names, to := fn($it, $pos) { ends-with($it, "a") and $pos ge 5 } )
Result:	"Anna", "Barbara", "Catherine", "Delia", "Eliza"

4.4.3 fn:divide-decimals

Summary

Divides one xs:decimal by another to a defined precision, returning both the quotient and the remainder.

Signature

fn:divide-decimals(
$value	as xs:decimal,
$divisor	as xs:decimal,
$precision	as xs:integer?as xs:integeras xs:integer?	:= 0
) as record(quotient as xs:decimal, remainder as xs:decimal)

Properties

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

Rules

The function returns a record with two fields:

1. quotient is the xs:decimal value furthest from zero such that:

   1. quotient is an exact multiple of ten to the power of minus $precision;

   2. the absolute value of quotient multipled by $divisor is less than or equal to the absolute value of $value;

   3. the sign of quotient is the same as the sign of op:numeric-divide($value, $divisor).

2. remainder is the exact result of subtracting quotient multiplied by $divisor from $value.

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

Error Conditions

A dynamic error is raised [err:FOAR0001] if $divisor is zero.

Examples

Expression	Result
divide-decimals(120.6, 60.3, 4)	{ "quotient": 2, "remainder": 0 }
divide-decimals(10, 3)	{ "quotient": 3, "remainder": 1 }
divide-decimals(10, -3)	{ "quotient": -3, "remainder": 1 }
divide-decimals(-10, 3)	{ "quotient": -3, "remainder": -1 }
divide-decimals(-10, -3)	{ "quotient": 3, "remainder": -1 }
divide-decimals(10, 3, 6)	{ "quotient": 3.333333, "remainder": 0.000001 }
divide-decimals(100, 30)	{ "quotient": 3, "remainder": 10 }
divide-decimals(150_862, 7, -3)	{ "quotient": 21_000, "remainder": 3_862 }

4.4.6 fn:round

Summary

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

Signature

fn:round(
$value	as xs:numeric?,
$precision	as xs:integer?as xs:integeras xs:integer?	:= 0,
$mode	as enum('floor', 'ceiling', 'toward-zero', 'away-from-zero', 'half-to-floor', 'half-to-ceiling', 'half-toward-zero', 'half-away-from-zero', 'half-to-even')?	:= 'half-to-ceiling'
) as xs:numeric?

Properties

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

Rules

General rules: see 4.4 Functions on numeric values.

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

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

Rounding Modes

Rounding Mode	Meaning
'floor'	Returns L.
'ceiling'	Returns U.
'toward-zero'	Returns L if $value is positive, otherwise U.
'away-from-zero'	Returns U if $value is positive, otherwise L
'half-to-floor'	Returns N, unless midway, in which case L.
'half-to-ceiling'	Returns N, unless midway, in which case U. This is the default.
'half-toward-zero'	Returns N, unless midway, in which case it returns L if $value is positive, otherwise U.
'half-away-from-zero'	Returns N, unless midway, in which case it returns U if $value is positive, otherwise L.
'half-to-even'	Returns N, unless midway, in which case it returns whichever of L and U has a last significant digit that is even.

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

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

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

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

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

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

Notes

This function is typically used with a non-zero $precision in financial applications where the argument is of type xs:decimal. For arguments of type xs:float and xs:double the results may be counter-intuitive. For example, consider round(35.425e0, 2). The result is not 35.43, as might be expected, but 35.42. This is because the xs:double written as 35.425e0 has an exact value equal to 35.42499999999..., which is closer to 35.42 than to 35.43.

The call round($v, 0, "floor") is equivalent to floor($v).

The call round($v, 0, "ceiling") is equivalent to ceiling($v).

The call round($v, $p, "half-to-even") is equivalent to round-half-to-even($v, $p).

Examples

Expression	Result
round(2.5)	3.0
round(2.4999)	2.0
round(-2.5)	-2.0
round(1.125, 2)	1.13
round(8452, -2)	8500
round(3.1415e0, 2)	3.14e0
math:log(0) => round()	-xs:double('INF')
round(1.7, 0, "floor")	1
round(-1.7, 0, "floor")	-2
round(1.7, 0, "ceiling")	2
round(-1.7, 0, "ceiling")	-1
round(1.7, 0, "toward-zero")	1
round(-1.7, 0, "toward-zero")	-1
round(1.7, 0, "away-from-zero")	2
round(-1.7, 0, "away-from-zero")	-2
round(1.125, 2, "half-to-floor")	1.12
round(-1.125, 2, "half-to-floor")	-1.13
round(1.125, 2, "half-to-ceiling")	1.13
round(-1.125, 2, "half-to-ceiling")	-1.12
round(1.125, 2, "half-toward-zero")	1.12
round(-1.125, 2, "half-toward-zero")	-1.12
round(1.125, 2, "half-away-from-zero")	1.13
round(-1.125, 2, "half-away-from-zero")	-1.13
round(1.125, 2, "half-to-even")	1.12
round(-1.125, 2, "half-to-even")	-1.12

4.4.7 fn:round-half-to-even

Summary

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

Signature

fn:round-half-to-even(
$value	as xs:numeric?,
$precision	as xs:integer?as xs:integeras xs:integer?	:= 0
) as xs:numeric?

Properties

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

Rules

General rules: see 4.4 Functions on numeric values.

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

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

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

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

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

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

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

Notes

This function is typically used in financial applications where the argument is of type xs:decimal. For arguments of type xs:float and xs:double the results may be counter-intuitive. For example, consider round-half-to-even(xs:float(150.015), 2). The result is not 150.02 as might be expected, but 150.01. This is because the conversion of the xs:float value represented by the literal 150.015 to an xs:decimal produces the xs:decimal value 150.014999389..., which is closer to 150.01 than to 150.02.

From 4.0, the effect of this function can also be achieved by calling fn:round with the third argument set to "half-to-even".

Examples

Expression	Result
round-half-to-even(0.5)	0.0
round-half-to-even(1.5)	2.0
round-half-to-even(2.5)	2.0
round-half-to-even(3.567812e+3, 2)	3567.81e0
round-half-to-even(4.7564e-3, 2)	0.0e0
round-half-to-even(35612.25, -2)	35600
math:log(0) => round-half-to-even()	-xs:double('INF')

4.5.1 fn:number

Summary

Returns the value indicated by $value or, if $value is not specified, the context value after atomization, converted to an xs:double.

Signature

fn:number(
$value	as xs:anyAtomicType?	:= .
) as xs:double

Properties

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

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

Rules

Calling the zero-argument version of the function is defined to give the same result as calling the single-argument version with the context value (.). That is, fn:number() is equivalent to fn:number(.), as defined by the rules that follow.

If $value is the empty sequence or if $value cannot be converted to an xs:double, the xs:double value NaN is returned.

Otherwise, $value is converted to an xs:double following the rules of 23.1.3.2 Casting to xs:double. If the conversion to xs:double fails, the xs:double value NaN is returned.

Error Conditions

A type error is raised [err:XPDY0002]^XP if $value is omitted and the context value is absent^DM.

As a consequence of the rules given above, a type error is raised [err:XPTY0004]^XP if the context value cannot be atomized, or if the result of atomizing the context value is a sequence containing more than one atomic item.

Notes

XSD 1.1 allows the string +INF as a representation of positive infinity; XSD 1.0 does not. It is implementation-defined whether XSD 1.1 is supported.

Generally fn:number returns NaN rather than raising a dynamic error if the argument cannot be converted to xs:double. However, a type error is raised in the usual way if the supplied argument cannot be atomized or if the result of atomization does not match the required argument type.

Examples

Variables
let $e := <e price="12.1" discount="NONE"/>

Expression	Result
number(12)	1.2e1
number('12')	1.2e1
number('INF')	xs:double('INF')
number('NaN')	xs:double('NaN')
number('non-numeric')	xs:double('NaN')
number($e/@price)	1.21e1
number($e/@discount)	xs:double('NaN')
number($e/@misspelt)	xs:double('NaN')
("10", "11", "12") ! number()	1.0e1, 1.1e1, 1.2e1

4.5.2 fn:parse-integer

Summary

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

Signature

fn:parse-integer(
$value	as xs:string?,
$radix	as xs:integer?as xs:integeras xs:integer?	:= 10
) as xs:integer?

Properties

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

Rules

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

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

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

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

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

Formal Equivalent

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

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

Error Conditions

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

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

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

Notes

When $radix takes its default value of 10, the function delivers the same result as casting $value (after removal of whitespace and underscores) to xs:integer.

If underscores or whitespace in the input need to be rejected, then the string should first be validated, perhaps using fn:matches.

If other characters may legitimately appear in the input, for example a leading 0x, then this must first be removed by pre-processing the input.

If the input uses a different family of digits, then the value should first be converted to the required digits using fn:translate.

A string in the lexical space of xs:hexBinary will always be an acceptable input, provided it is not too long. So, for example, the expression "1DE=" => xs:base64Binary() => xs:hexBinary() => xs:string() => parse-integer(16) can be used to convert the Base 64 value 1DE= to the integer 54321, via the hexadecimal string D431.

Examples

Expression:	parse-integer(" 200 ")
Result:	200
Expression:	parse-integer("-20")
Result:	-20
Expression:	parse-integer(" +100")
Result:	100
Expression:	parse-integer("ff", 16)
Result:	255
Expression:	parse-integer("FFFF FFFF", 16)
Result:	4294967295
Expression:	parse-integer("-FFFF_FFFF", 16)
Result:	-4294967295
Expression:	parse-integer("377", 8)
Result:	255
Expression:	parse-integer("101", 2)
Result:	5
Expression:	parse-integer("vv", 32)
Result:	1023
Alphabetic base-26 numbering systems (hexavigesimal) can be parsed via translation. Note, enumerating systems that do not assign a symbol to zero (e.g., spreadsheet columns) must be preprocessed in a different fashion.
Expression:	lower-case("AAB") => translate("abcdefghijklmnopqrstuvwxyz", "0123456789abcdefghijklmnop") => parse-integer(26)
Result:	1
Digit-based numeration systems comparable to the Arabic numbers 0 through 9 can be parsed via translation.
Expression:	translate(value := '٢٠٢٣', replace := '٠١٢٣٤٥٦٧٨٩', with := '0123456789') => parse-integer()
Result:	2023