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



String functions – analysis and manipulation


XPath 1.0

Return value:

xs:string string; that substring of an input string whose start and length are determined by the number values for start index and character number also passed on.


fn:substring($inputValue, $startIndex, $length?)


Obligatory. A xs:string string; the input string to be processed. 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, in case it is not a string, the value is converted to a string according to the conversion function string().


Obligatory. The second argument must be a xs:double number which determines the position of the first character of the input string which shall be contained in the result string. If this argument is not a number, it is converted to a number according to the rules of fn:number(). If a fraction number results from this, it is rounded with fn:round().


Optional. The third argument, in case it is passed on, must also be a xs:double number which determines the length of the substring to be extracted in characters. If the argument is not a number, it is converted to a number according to the rules of fn:number() and, where applicable, rounded. If no third argument is passed on, which means there is no length indication of the substring, a substring is generated starting from the start index up to the end of the input string (internally, the argument virtually adopts the value +INF).

Purpose of use:

The fn:substring() function extracts from an input string a substring with a defined start and a length to be determined. Reasonably, the start index of the substring is indicated by a positive integer.

In the case that values for start index and/or substring length result from the evaluation of an expression, where appropriate, the functions fn:number() and fn:round() are implicitly used.

If the start index is less than zero, it is determined that as substring the output occurs starting from this virtual position. Similarly, for a start index which is greater than the string length of the input string always an empty string is returned as substring. Thus, also the cases are covered that – for example, from the evaluation of an expression – the start index could be plus or minus infinite (in each case the empty string).

The same applies for the length indication of the substring. If it is equal to zero or negative (less than zero), an empty string is returned. If the length indication exceeds the remaining length of the input string starting from the start index, only the residual string starting from the start index is outputted (no infilling with space characters).

The function returns the empty string if, instead of an input string, the empty sequence was passed on.

XML characters (or Unicode Codepoints) are regarded as characters. In other words: characters consisting of Surrogate Pairs are evaluated as characters.

Attention – index numbers for strings in XSLT start with 1!
In XSLT, the index numbers for characters in strings start with 1, not with 0, as is the case, for example, in Java, C or JavaScript!


Remark: In the following table, leading or trailing space characters in the result string are illustrated by an underscore!

Function callResult
fn:substring('One test string', 1) One test string
fn:substring('One test string', 1, 4) One_
fn:substring('One test string', 1, 3) One
fn:substring('One test string', 0, 3)On
fn:substring('One test string', -3, 5)O
fn:substring('One test string', 20, 5)"" (no output!)
fn:substring('One test string', 1, -4) "" (no output!)
fn:substring('One test string', 4) _test string
fn:substring('One test string', 5.6, 3.2) est
fn:substring('One test string', NaN)"" (no output!)
fn:substring('One test string', NaN, 5)"" (no output!)
fn:substring('One test string', 5, NaN)"" (no output!)
fn:substring('One test string', -50, INF)One test string
fn:substring('One teststring', -INF, INF)"" (no output!)

Table: function call of fn:substring()

Explanation of the examples:

The function logic for the determination of the substring allocates a character with $p index of the input string to the result string, if its position in the string meets the following condition:


<= $p <

fn:round($startIndex) + fn:round($length)

If the number values passed on for index and length are no integers (see example 9 in the table), they are rounded.

Therefore, by rounding substring('One test string', 5.6, 3.2)

results in:

substring('One test string', 6, 3)

If the value passed on as start index is equal to or less than 0 (the position of the first character is 1), a substring is generated starting from this virtual position: fn:substring('One test string', -3, 5) results in 'O', because no characters with index -3, -2, -1 and 0 exist. Therefore, the fifth character starting from and including the virtual start position is the character with the index number 1.

If the length of the substring to be extracted is too small compared to the absolute value of the negative start index, consequentially the empty string is returned: fn:substring('One test string', -10, 5) results in ''.

If as start index the value NaN is passed on (see example 10 in the table), the empty string is likewiese outputted: substring('One test string', NaN). (According to the function logic illustrating this case with NaN <= $p < NaN, no character of the string can meet this condition.)

The empty string is also outputted if the second as well as the third argument is passed on and one of them or both are NaN. This is based on the fact that NaN as value is regarded as unequal to any other number and, as a consequence, it is not possible to build the sum (right expression of the function logic) of rounded start index and rounded length and to make a subsequent comparison for the selection of the substring.

A similar situation arises if -INF is passed on as lower limit and +INF as upper limit (see last example in the table). Not the entire string is outputted (as maybe expected), but the empty string because the right side (-INF + INF) of the expression above results in NaN per definition.

Function definition:

XPath 1.0:

substring(string, number, number?) => string

XPath 2.0:

fn:substring($sourceString as xs:string?,

$startingLoc as xs:double?) as xs:string?

fn:substring($sourceString as xs:string?,

$startingLoc as xs:double?,

$length as xs:double?) 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