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:ends-with

Category:

String functions – analysis and manipulation

Origin:

XPath 2.0

Return value:

A Boolean value true or false depending on whether a string passed on ends with a comparison string also passed on or not.

Call/Arguments:

fn:ends-with($testString?, $comparisonString?, $collation-URI?)

$testString:

Optional. An input value of xs:string string type which shall be tested for whether it ends with the comparison string passed on as second argument. If the argument is not a string, a type error is reported. The empty sequence is permitted as value and is treated like the empty string.

$comparisonString:

Optional. The xs:string string is tested for whether it appears at the end of the test string of the first argument. If the first argument is not a string, a type error is reported. The empty sequence is permitted as value and is treated like the empty string.

$collation-URI:

Optional. The third argument consists of a xs:string string which names the URI string of the collation to be applied. The value has to lexically correspond to the xs:anyURI type. If this is not the case, an error message (»Invalid collationURI«) is outputted. If no third argument is passed on, the Unicode Codepoint Collation is used for the comparison.

Purpose of use:

The return value of fn:ends-with() is true in case the tested string ends with the comparison string or is identical with it. In more complicated words: The tested string must end with a related sequence of characters whose Unicode values (by means of the used collation) correspond to the corresponding characters in the comparison string. In all other cases, the return value of the function is false.

In the simplest case two strings are passed on directly:

fn:ends-with("abc","c") results in: true.

Exceptions and remarks:

If the empty string or – equivalent – the empty sequence is passed on as comparison string, the return value is always true. However, if the tested string is empty itself or the empty sequence is passed on as first argument, the return value is always false, unless the comparison string is also an empty string.

With the help of the optional third function argument, it is possible to consult a predefined comparison list (collation) for the string comparison – for example, in order to be able to recognise »realisation« and »realization« as identical according to their meaning. The method of how the collation is integrated is dependent on the implementation. The string which makes the connection to the collation has to lexically correspond to the xs:anyURI type, but is passed on as xs:string.

If no appropriate third argument is passed on, the string comparison is made by means of the Unicode Codepoint Collation. Therefore, the default collation of the system is not explicitely used! The behaviour of fn:ends-with() is in conformity with those string functions using regular expressions like fn:matches(), fn:replace() and fn:tokenize().

Example 1 – comparison of two strings:

fn:ends-with("butterfly","fly") results in true.

Example 2 – comparison with the empty string:

fn:ends-with("", "fly") results in false.

Example 3 – comparison with the empty sequence:

fn:ends-with((), "fly") results in false.

Example 4 – comparison with the empty string:

fn:ends-with("butterfly", "") results in true.

Example 5 – comparison of two empty strings:

fn:ends-with("", "") results in true.

Example 6 – comparison of the empty sequence and the empty string:

fn:ends-with((), "") results in true.

Function definition:

XPath 1.0:

The function is not available.

XPath 2.0:

fn:ends-with($arg1 as xs:string?,

$arg2 as xs:string?) as xs:boolean

fn:ends-with($arg1 as xs:string?,

$arg2 as xs:string?,

$collationLiteral as xs:string) as xs:boolean

   

<< back

next >>