XSLT and XPath function reference in alphabetical order

(Excerpt from “XSLT 2.0 & XPath 2.0” by Frank Bongers, chapter 5, translated from German)

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

fn:compare

Category:

String functions – analysis

Origin:

XPath 2.0

Return value:

The integers −1, 0 or +1 − depending on whether the first comparative value is evaluated as less, equal or greater than the second one –, or the empty sequence in case one of the values to be compared is the empty sequence.

Call/Arguments:

fn:compare($string1?, $string2?, $collation?)

$string1:

A xs:string string which is compared with the second input value. If an empty sequence is passed on as first argument, the function returns an empty sequence.

$string2:

A xs:string string which is compared with the first input value. If an empty sequence is passed on as second argument, the function returns an empty sequence.

$collation:

Optional. The third argument being of xs:string type determines a comparison rule set (collation) which is used as the basis of the string comparison. The string must lexically correspond to the xs:anyURI type.

Purpose of use:

The function is used in order to compare two strings and can firstly determine their identities (also by using a collation). The order in which the strings to be compared are passed on is relevant.

If the strings are entirely unequal, they are compared character by character. If a substring is the same at the beginning of both strings, comparison is made starting from the first character following the identical substring. If one of both strings contains at the beginning the respectively other comparison string entirely, it is evaluated as »greater«.

The result of the character comparison depends on the collation used. In general, the following applies analogous to the string comparison by means of the ASCII value:

A < a and a < b

The function uses the default collation of the system environment provided that as third argument no string is passed on which – evaluated as URI – determines an alternative collation. If the third argument cannot be lexically interpreted as xs:anyURI, an error message occurs. If there is no default collation in the system environment, the Unicode codepoint collation is used for the function.

On the basis of the fn:compare() function, also the application of the following operators on string values is defined:

OperatorApplicationDescription
eq $string1 eq $string2 true for string1 'equals' string2
ne $string1 ne $string2 true for string1 'does not equal' string2
gt $string1 gt $string2 true for string1 'greater than' string2
lt $string1 lt $string2 true for string1 'less than' string2
le $string1 le $string2 true for string1 'less than or equal' string2
ge $string1 ge $string2 true for string1 'greater than or equal' string2

Table: application of operators on string values for the fn:compare() function

Example 1 - comparison of two identical strings:

fn:compare('abc', 'abc') results in: 0

Both strings are identical – as a consequence, the return value of the function is 0.

Example 2 - comparison of two partly identical strings:

fn:compare('abc', 'abcd') results in: −1

In this case, the second string is equal to the first string regarding the first three characters. Since the first string is shorter, it is evaluated as »less« (in other words: "" < d). If the arguments were interchanged, the function would return +1.

Example 3 - comparison of two partly identical strings:

fn:compare('abce', 'abcd') results in: +1

The strings are identical regarding the first three characters, but for the fourth character applies e > d, therefore the first string is evaluated as »greater«.

Example 4 - comparison of two different strings:

fn:compare('def', 'abcd') results in: +1

In this comparison already the first character is crucial: d > a, therefore the first string is evaluated as »greater«. It is not relevant that the second string has more characters than the first one.

Example 5 - comparison depending on the default collation:

fn:compare('Strasse', 'Straße') results in: 0

In case the default collation evaluates the 'ß' as identical to 'ss' in the string comparison, both strings apply as identical and the function returns the value 0. Otherwise the result depends on how – by means of the rules of the collation – the comparison between 's' and 'ß' which follow as fourth character the identical substring 'Stra' (the German 'Straße' means 'street') turns out.

Function definition:

XPath 1.0:

The function is not available.

XPath 2.0:

fn:compare($comparand1 as xs:string?,

$comparand2 as xs:string?) as xs:integer?

fn:compare($comparand1 as xs:string?,

$comparand2 as xs:string?,

$collationLiteral as xs:string) as xs:integer?

   

<< back next >>

 

 

 


Copyright © Galileo Press, Bonn 2008
Printing of the online version is permitted exclusively for private use. Otherwise this chapter from the book "XSLT 2.0 & XPath 2.0" is subject to the same provisions as those applicable for the hardcover edition: The work including all its components is protected by copyright. All rights reserved, including reproduction, translation, microfilming as well as storage and processing in electronic systems.


Galileo Press, Rheinwerkallee 4, 53227 Bonn, Germany