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:contains

Category:

String functions – analysis

Origin:

XPath 1.0

Return value:

A Boolean value – true or false, depending on whether a test string is contained in the tested expression or not.

Call/Arguments:

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

$testString:

Optional. An input value of xs:string type; it shall be checked whether it contains as substring the comparison string passed on to it as second argument. If the argument is not a string, a type error is reported. The empty sequence as argument is treated like the empty string. If $testString is the empty string, the function returns the value false. (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 being tested as substring in the string of the first argument. If the argument is not a string, a type error is reported. The empty sequence is treated like the empty string. If $comparisonString is the empty string, the function returns the value true (the empty string is always included in another string provided that this string is not empty itself).

$collation-URI:

Optional. The third argument consists of a xs:string string which names the URI string of the applicable collation. The value has to lexically correspond to the xs:anyURI type. If no third argument is passed on, the Unicode Codepoint Collation is used for the comparison. (See Unicode Technical Standard #10 - Unicode Collation Algorithm). XPath 1.0 does not know collations and therefore, does not accept a third argument.

Purpose of use:

The return value of fn:contains() is true if the tested string contains the test string or is identical to it. Formally the tested string must have a related sequence of characters whose Unicode values are equivalent to the corresponding characters in the test string. In all other cases, the return value of the function is false.

In the simplest case, two strings are passed on directly:

fn:contains("abc","b") results in true.

Exceptions and remarks:

If the empty string or – as an 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 if the empty sequence is passed on as first argument, the return value is always false – unless the comparison string would also be an empty string.

It is possible to use a predefined comparison list (collation) for the text comparison with the help of an optional third function argument – for instance in order to be able to recognise »realisation« and »realization«, »monopolise« and »monopolize« as identical in their meanings. The way in which the collation is embedded depends on the implementation. The string which creates the connection to the collation must 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. The default collation of the system is not used. The behaviour of fn:contains() conforms to those string functions using regular expressions like fn:matches(), fn:replace() and fn:tokenize(). Those functions also work on the basis of the Unicode Codepoint collation. However, no other collation can be assigned to these functions.

Example 1 - comparison string contained in the input string:

fn:contains('example', 'exam')

returns true.

The comparison string is contained in the input string – therefore the function returns the Boolean value true.

Example 2 - comparison string not contained in the input string:

fn:contains('example', 'no')

returns false.

The comparison string is not contained in the input string – therefore the function returns the Boolean value false.

Example 3 - comparison string is the empty string:

fn:contains('example', '')

returns true.

The comparison string is the empty string. It is considered to be contained in any test string – therefore the function returns the Boolean value true. This also applies in case the test string is empty, too:

fn:contains('', '')

also returns true.

Example 4 - application of a collation:

If a collation which determines certain characters as »to be ignored« is used as text comparison statement in order to evaluate the text comparison, these characters are removed from the second argument string before the comparison.

fn:contains('example', '-e-x-a-m-', exampleCollation)

returns true. Supposing the hyphen is defined as »to be ignored« within exampleCollation, the '-e-x-a-m-' string is interpreted as 'exam'. The comparison made in this example thus corresponds to:

fn:contains('example', 'exam')

and therefore results in true. In case $comparisonString only contains characters to be ignored (if, for example, also * shall be ignored), it will be evaluated the same way as the empty string.

fn:contains('example', '-*-*-*-'‚ exampleCollation)

results in true, because it corresponds to fn:contains('example', '').

Example 5 - formulation of a condition:

The search for a compound term which is not clearly defined can be made easier by fn:contains(), but has its difficulties. Assuming in an $authorName variable the name of a book author is saved:

This test is successful for $authorName="Karl May", $authorName="May, Karl", but in the preset form also for $authorName="Karlheinz Mayer". In XPath 1.0, it is not possible to search for word boundaries without regular expressions which are not permitted for this function.

Function definition:

XPath 1.0:

contains(string, string) => boolean

XPath 2.0:

fn:contains($arg1 as xs:string?,

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

fn:contains($arg1 as xs:string?,

$arg2 as xs:string?,

$collation as xs:string) as xs:boolean

In XPath 1.0 the test for Unicode values is not in each case as clear as it would have been desirable because of the absence of collations: characters containing accents, tildes or similar additions, thus being composite characters, can be expressed in different ways in Unicode. However, a character comparison fails for optically identical represented but differently encoded characters.