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

Category:

Type conversion and output formatting

Origin:

XPath 1.0

Return value:

A number of xs:double type (in XPath 1.0 of number type) or the value NaN.

Call/Arguments:

fn:number($inputValue?)

$inputValue:

Optional. A node or any atomic value which shall be converted to a number. If the input value is not convertible to a xs:double number or if it is the empty sequence, the function returns the NaN value. In case no argument is passed on, the function works with the respective context item whose value is converted to a xs:double number. If the context item is not defined, an error (err:XPDY0002) is reported.

Purpose of use:

In XPath 2.0 a conversion of an expression into a xs:double number is required where a numerical input value is expected – for example for rounding functions. Since no implicit type conversion is performed, a type error would otherwise be reported.

By means of fn:number() it can be ensured that the value in question can be converted or the NaN value is passed on which, however, does not cause a type error (as numerical value).

However, in XPath 1.0 a type conversion is implicitly made if the expression is used in a context in which only numbers are allowed. Therefore, the number() function is normally only required in such cases in which the implicit conversion does not reliably take place, which means in the predicate of a XPath expression.

Behaviour in XPath 2.0:

In XPath 2.0 distinction is made between three groups of input values when using, explicitly or implicitly, the fn:number() function:

Input value is (directly) an atomic value

In general, the atomic input value must lexically correspond to a xs:double number. This is trivially the case for all number types.

Strings are convertible if they consist of digits (possibly with leading sign and decimal point) or of the character strings 'inf', '-inf', 'NaN' (optional in upper case or lower case letters).

The Boolean value true is converted to 1.0 and the Boolean value false to 0.0.

For all other atomic types, for example date values, durations and the like, a conversion is not possible. For these types as well as for strings which lexically do not meet the requirements, the fn:number() function returns the NaN value.

Input value is a node with an atomic value

The atomic value of the node is converted to a xs:double number according to the rules set out above. If the conversion is not possible, the function returns NaN.

Input value is a node with a non-atomic value

At first, the non-atomic value of the node is converted to a string, analogous to the application of fn:string(). Then, the attempt is made to convert the result string of this operation to a xs:double number according to the rules set out above. If the conversion fails, which means the string does not lexically correspond to a number, also in this case the function returns NaN.

Behaviour in XPath 1.0:

When using number(), explicitly or implicitly, the following return values result for different data types:

Number

If the input value is already a number, it remains unchanged.

Boolean

If the input value is a Boolean value, the function returns the number 1 for the input value true and the number 0 for the input value false.

String

If the input string is an empty or a non-empty string, the function returns the NaN (Not a Number) value. Unless the string consists of a non-interrupted sequence of digits with maximally one decimal point and maximally one directly(!) prefixed minus sign. In this case, the positive or negative decimal number corresponding to the digit sequence is returned. The digit string may have leading and trailing whitespace characters which are removed by normalisation as with normalize-space() during the conversion.

Node set

At first, a node set is implictly converted to a character string by using string(). This string corresponds to the text value of the node set or results in the empty string for an empty node set. The usage of number() following this intermediate step corresponds to the one for strings described above.

Usage in a XPath predicate

In case the value of an expression within a XPath predicate shall be interpreted as a number, for example for the comparison of the position of the context node with the position of the current node, it should be explicitly converted by means of the fn:number() function as a precaution:

example[fn:position() = fn:number($expression)]

Here, <example> elements are selected whose positions in a node set correspond to the number value of $expression.

Examples:

Function call	Result
fn:number(true)	1.0
fn:number(-3.895)	-3.895
fn:number('1.63')	1.63
fn:number('-1.63') Remark: Leading signs are allowed!	-1.63
fn:number(' -1.63 ') Remark: Leading and trailing space characters are allowed!	-1.63
fn:number(' - 1.63 ') Remark: Space characters in the value are forbidden!	NaN
fn:number('any string')	NaN
fn:number('') Remark: The empty string is a string, too!	NaN

Table: results of the call of fn:number() with different values

Function definition:

XPath 1.0:

number(object?)=> number

XPath 2.0:

fn:number() as xs:double

fn:number($arg as xs:anyAtomicType?) as xs:double

Possible compatibility problems XPath 2.0 to XPath 1.0:

The XPath 2.0 function fn:number() tries to convert the input value to a number of xs:double type. Therefore, the function returns for the Boolean values true and false the numbers 1.0 respectively 0.0, but in XPath 1.0 the numbers 1 and 0. In case the conversion fails (type error: »invalid lexical value«), it returns like in XPath 1.0 the value NaN, more precisely the xs:double value NaN.

   

<< back

next >>