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:substring-before

Category:

String functions – analysis and manipulation

Origin:

XPath 1.0

Return value:

xs:string string; the substring of an input string, starting at the beginning of the input string up to the first character before the first occurrence of a comparison string passed on.

Call/Arguments:

fn:substring-before($input, $comparisonString, $collation-URI?)

$input:

Obligatory. The xs:string string to be examined. 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:

Obligatory. A value in form of a xs:string string whose first occurrence in the input string is searched for. The substring starting from the beginning of the input string up to before the first occurrence of the comparison string is outputted. If the argument is not a string, a type error is reported. The empty sequence is permitted as a value and treated like the empty string.

$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 used. 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. This argument is not available in XPath 1.0.

Purpose of use:

The fn:substring-before() function returns that part of an input string which precedes the first occurrence of a comparison string in the input string. The comparison string may consist of a single character or a character string.

If the test string is not contained in the input string or if the input string or the comparison string is empty (example 2), an empty string is returned. However, the same also happens if the input string starts with the comparison string. In order to test this case, fn:contains() can be used.

If no third argument for the naming of a collation is passed on to the function, the string comparison takes place by means of the Unicode Codepoint collation. So, the default collation of the system is expressly not used. As a consequence, the behaviour of fn:substring-before() conforms with those string functions using regular expressions, which means fn:matches(), fn:replace() and fn:tokenize().

Notice: test for match at the start of the string
When testing the start of a string, the fn:starts-with() function is more suitable.

Behaviour under XPath 1.0:

In XPath 1.0 the arguments, in case they are no strings, are automatically converted to strings according to the rules of the conversion function string(). If the first argument is an empty node set, an empty string is returned. However, in XPath 2.0 an empty sequence () is returned in case any operand of the first two operands is the empty sequence.

Example 1 – simple application on two strings:

fn:substring-before('This is an example', 'is')

results in: 'This '.

The substring of the input string immediately preceding the comparison string is returned – in this case with trailing space character.

Example 2 – empty string as comparison string:

fn:substring-before('This is an example', '')

results in: ''.

The empty string is returned. This is based on the premise that at the beginning of each string always an empty string exists. The fact that one can imagine an empty string also at the end of each string does not change anything, because the substring is returned before the first occurrence of the comparison string. Here, the case applies that the input string starts with the comparison string.

Example 3 – application for recursive string processing:

A detailed example can be found in the descriptions for the fn:substring-after() function.

Function definition:

XPath 1.0:

substring-before(string, string) => string

XPath 2.0:

fn:substring-before($arg1 as xs:string?,

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

fn:substring-before($arg1 as xs:string?,

 $arg2 as xs:string?,

 $collation as xs:string) as xs:string

   

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