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

Category:

String functions – analysis and manipulation

Origin:

XPath 1.0

Return value:

A Boolean value true or false, depending on whether the tested string starts with the comparison string or not.

Call/Arguments:

fn:starts-with($teststring?, $comparisonString?, $collation-URI?)

$teststring:

Optional. An input value of xs:string string type which shall be tested for whether it starts 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. In XPath 1.0 the value, in case it is not a string, is converted to a string according to the rules of the conversion function string().

$comparisonString:

Optional. The xs:string string is tested for whether it appears at the beginning 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. For XPath 1.0 the same behaviour applies as described above.

$collation-URI:

(new in XPath 2.0)
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. This argument is not available in XPath 1.0.

Purpose of use:

The return value of fn:starts-with() is true in case the tested string starts with the comparison string or is identical with it. In more complicated words: The tested string must start 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:starts-with("abc","a") results in true.

If the empty string is passed on as comparison string, the return value is always true. However, if the tested string is empty itself, 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 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:starts-with() is in conformity with those string functions using regular expressions like fn:matches(), fn:replace() and fn:tokenize().

Bahaviour under XPath 1.0:

In XPath 1.0 the test for Unicode value is, due to the absence of collations, not in all cases as clear as it would be desirable: characters containing accents, tildes or similar additions, which means composite characters, can be represented in Unicode in different ways. Therefore, a character comparison fails for optically identical represented but differently coded characters.

In case the first argument is an empty node set (which is converted to the empty string) and the second argument is a non-empty string, the value false is returned for XPath 1.0.

Example 1 – Testing a string for a substring at the beginning:

results in true.

The tested string starts with the comparison string.

Example 2 – Testing a string with empty comparison string:

results in true.

The comparison string is empty, therefore the function returns the value true (the empty string is, so to say, contained at the beginning of the string).

Example 3 – Failed test of a string starting with the comparison string:

results in false.

The tested string contains the comparison string but it does not start with it. Therefore, the fn:starts-with() function returns false.

Example 4 – Filtering according to first letter of a string:

In this example, titles and author of books are outputted, for which the surname of the author starts with 'B'.

Function definition:

XPath 1.0:

starts-with(string, string) => boolean

XPath 2.0:

fn:starts-with($arg1 as xs:string?,
                     $arg2 as xs:string?)  as xs:boolean

fn:starts-with($arg1 as xs:string?,
                     $arg2 as xs:string?,
                     $collation as xs:string) as xs:boolean