XSLT and XPath function reference in alphabetical order
(Excerpt from “XSLT 2.0 & XPath 2.0” by Frank Bongers, chapter 5, translated from German)
Type conversion and output formatting
A number of xs:double type (in XPath 1.0 of number type) or the value NaN.
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:
If the input value is already a number, it remains unchanged.
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.
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.
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.
Remark: Leading signs are allowed!
|fn:number(' -1.63 ')|
Remark: Leading and trailing space characters are allowed!
|fn:number(' - 1.63 ') |
Remark: Space characters in the value are forbidden!
Remark: The empty string is a string, too!
Table: results of the call of fn:number() with different values
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 >>|
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