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

Category:

Type conversion and output formatting

Origin:

XPath 1.0

Return value:

A xs:string string, depending on the type of the argument passed on.

Call/Arguments:

fn:string($inputSequence)

$inputSequence:

Optional. The argument is a sequence of one or more items of any data type which shall be converted to a string, whereby only the first item is taken into account. If the empty sequence is passed on, the function returns an empty string. If, however, no argument is passed on, the string value of the context node is returned.

Purpose of use:

All input data types can be converted to strings by means of fn:string(). Because XPath 2.0 does not know an implicit type conversion, in order to prevent type errors, it must be explicitly performed, where appropriate, for input values of certain functions with fn:string() or (for single atomic values) by the cast as xs:string casting function in case a xs:string string is required for the further processing.

In XPath 1.0 this conversion is often implicit, but it can also be forced with the string() function.

The function accepts an input sequence. If this input sequence is empty, the function returns an empty string. If no argument is passed on, it automatically refers to the context item and returns its string value. If no argument was passed on, but the context item is not defined at the moment of the evaluation, a runtime error occurs (err:XPDY0002).

Behaviour in XPath 2.0:

When explicitly using fn:string(), in XPath 2.0 distinction is made between three groups of input values:

Input value is (directly) an atomic value

In principle, the conversion of an atomic value into a string is possible in all cases. The conversion of any value into a string follows its canonical form according to XML Schema Part 2 »Datatypes«.

For a xs:boolean Boolean value the canonical form is true or false being converted to the strings 'true' and 'false' (this also applies if the Boolean values are available as 0 or 1, which is allowed, but does not correspond to the canonical form).

For numbers (numeric type) this simply means that a number of any type is converted to an appropriate string of digits (where applicable with a negative leading sign and decimal point). Prepended positive leading signs (before the number itself and also before the exponent!) as well as leading and following zeros are omitted, unless they directly border on the decimal point. In xs:float floating point numbers containing an exponent, this string is introduced by a capital E. Other number values are converted to the appropriate string literal: NaN to 'NaN', INF into 'INF', -INF to '-INF' (Attention: here an incompatibility to XPath 1.0 exists!).

If the value to be converted is a URI string of xs:anyURI type, it is converted – in contrast to the casting function for string values – without escaping contained space characters and special characters. This is regulated in this way because space characters are allowed and wanted under certain circumstances within fragment identifiers. Therefore, if URI escaping shall be enforced, this must be done via the fn:escape-html-uri() function.

A xs:QName QName is converted as if firstly the individual components would be determined and afterwards concatenated with a joining colon by means of the functions fn:prefix-from-QName($QName) and fn:local-name-from-QName($QName). So, the result is a string in the lexical form of a prefix:local-name QName.

The conversion of date values into a string requires the inclusion of timezone indications (explicitly and implicitly), provided that such indications exisit. If the date/time indication is available as Universal Time Coordinated (UTC), a Z is added in order to make this clear.

If a xs:hexBinary binary value is converted to a string, the hex numbers A to F are principally represented with upper case letters.

Input value is a node

The string value of a text node is its text content, the string value of a comment is the comment content. As string value of a PI the data portion of the instruction applies. The string value of a namespace node is the namespace URI string. The string value of an attribute node is the attribute value, the string value of a document node or of another element consists of the text nodes combined in the document order of all descendending elements.

Input value is a sequence

If the sequence is empty, fn:string() returns the empty string. If the sequence is not empty, the first item is converted to a string, depending on whether it is a node or an atomic value. This is accomplished according to one of the two procedures described above. The remaining items of the sequence are rejected.

Bahaviour in XPath 1.0:

If the string() function is used in XPath 1.0, explicitly or implicitly, it converts the input value as follows:

Number

NaN is converted to the 'NaN' string. A positive and a negative 0 are represented as '0'. Positive infinite becomes 'Infinity', negative infinite becomes '-Infinity' (Attention: incompatibility to XPath 2.0!). An integer is represented decimally without leading zeros, possibly with a preceded minus sign in case it is a negative number. The result is a valid XPath number. Any other (decimal) number is converted to a string in decimal form. In doing so, at least one digit is before and after the decimal point. In case of a negative number, a minus sign is prepended directly. Leading zeros are rejected, unless they are directly before the decimal point. The number of decimal places is not limited. Here, too, the result is a valid XPath number.

Boolean

The Boolean value false becomes the 'false' string, the Boolean value true is converted to the 'true' string.

String

The value remains unchanged.

Node

The string conversion of the nodes is made depending on the type as in XPath 2.0 (see above).

Nodeset

The string value of an empty node set is the empty string. For a non-empty node set, the string value of the node is outputted which comes in the document order as first node in the set.

Result Tree Fragment

The string value of a Result Tree Fragment is – in document order – the combination of all text nodes containd in it in direction of the descendant axis. In XPath 2.0 the concept of the »Result Tree Fragments« is abolished.

Difference between xs:string() constructor and fn:string()
In XPath 2.0 there is additionally for strings a constructor function xs:string() whose return value differs from the one of fn:string() with the same argument because not the string value of the argument is returned, but the string value of the argument after its performed atomisation.

Example – string value of a node sequence:

Sometimes it may be helpful to explicitly call the fn:string() function, for example in case two strings shall be compared directly instead of a comparison between a string and a node sequence.

In this example file books with several authors are indicated:

In this document such books shall be found whose main author corresponds to a predefined name of an author. The main author shall always be the first-mentioned author in the book element.

The following does not lead to the desired result:

In this case, each book is outputted having an author element which contains the comparison string, which means also the second author element , the third author element, etc.

With the help of the fn:string() function the following expression can be formulated which only takes into account the string value of the first author element:

This test is only successful if the 'Anthony Author' string appears as the name of the main author in the first author element, because for a node sequence passed on – and exactly this is the case here – the string value of the first node is returned.

Function definition:

XPath 1.0:

string(object) => string

XPath 2.0:

fn:string() as xs:string

fn:string($arg as item()?) as xs:string