XPath and XQuery Functions and Operators 4.0

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?	:= 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.Any absent components, other than the timezone, are substituted with the corresponding components of the xs:dateTime value 1972-01-01T00:00:00 to produce an xs:dateTime value.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.

         Note:

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

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

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

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

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

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

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

   Note:

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

   • When both values are zero-length durations.

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

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

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

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

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

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

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

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

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

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

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

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

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

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