XPath Functions (XML in a Nutshell, 2nd Edition)

22.5. XPath Functions

XPath 1.0 defines 27 built-in functions for use in XPath expressions. Various technologies that use XPath, such as XSLT and XPointer, also extend this list with functions they need. XSLT even allows user-defined extension functions.

Every function is evaluated in the context of a particular node, called the context node. The higher-level specification in which XPath is used, such as XSLT or XPointer, decides exactly how this context node is determined. In some cases the function operates on the context node. In other cases it operates on the argument, if present, and the context node, if no argument exists. The context node is ignored in other cases.

In the following sections, each function is described with at least one signature in this form:

return-type function-name(type argument, type argument, ...)

Compared to languages like Java, XPath argument lists are quite loose. Some XPath functions take a variable number of arguments and fill in the arguments that are omitted with default values or the context node.

Furthermore, XPath is weakly typed. If you pass an argument of the wrong type to an XPath function, it generally converts that argument to the appropriate type using the boolean( ), string( ), or number( ) functions, described later. The exceptions to the weak-typing rule are the functions that take a node-set as an argument. Standard XPath 1.0 provides no means of converting anything that isn't a node-set into a node-set. In some cases a function can operate equally well on multiple argument types. In this case, its type is given simply as object.

boolean( )

boolean boolean(object o)

The boolean( ) function converts its argument to a Boolean according to these rules:

Zero and NaN are false. All other numbers are true.
Empty node-sets are false. Nonempty node-sets are true.
Empty strings are false. Nonempty strings are true.

ceiling( )

number ceiling(number x)

The ceiling( ) function returns the smallest integer greater than or equal to x. For example, ceiling(3.141592) is 4. ceiling(-3.141592) is -3. Before the ceiling is calculated, non-number types are converted to numbers as if by the number( ) function.

concat( )

string concat(string s1, string s2)
string concat(string s1, string s2, string s3)
string concat(string s1, string s2, string s3, string s4)
...

This function concatenates its arguments in order from left to right and returns the combined string. It may take two or more arguments. Nonstrings may be passed to this function as well, in which case they're converted to strings automatically as if by the string( ) function.

contains( )

boolean contains(string s1, string s2)

This function returns true if s2 is a substring of s1--that is, if s1 contains s2--false otherwise. For example, contains("A very Charming cat", "Charm") is true, but contains("A very Charming cat", "Marjorie") is false. The test is case-sensitive. For example, contains("A very charming cat", "Charm") is false. Nonstrings may also be passed to this function, in which case they're automatically converted to strings as if by the string( ) function.

count( )

number count(node-set set)

The count( ) function returns the number of nodes in the argument node-set, that is, the length of the set.

false( )

boolean false( )

The false( ) function always returns false. It makes up for the lack of Boolean literals in XPath.

floor(3e )

number floor(number x)

The floor( ) function returns the greatest integer less than or equal to x. For example, floor(3.141592) is 3. floor(-3.141592) is -4. Before their floor is calculated, non-number types are converted to numbers as if by the number( ) function.

id( )

node-set id(string IDs)
node-set id(node-set IDs)

The id( ) function returns a node-set containing all elements in the document with any of the specified IDs. If the argument is a string, then this string is interpreted as a whitespace-separated list of IDs, and the function returns a node-set containing any elements that have an ID matching one of these IDs. If the argument is a node-set, then each node in the set is converted to a string, which is in turn treated as a white-space-separated list of IDs. The returned node-set contains all the elements whose ID matches any ID in the string value of any of these nodes. Finally, if the argument is any other type, then it's converted to a string, as by the string( ) function, and it returns the same result as passing that string value to id( ) directly.

lang( )

boolean lang(string languageCode)

The lang( ) function returns true if the context node is written in the language specified by the languageCode argument; false otherwise. The nearest xml:lang attribute on the context node or one of its ancestors determines the language of any given node. If no such xml:lang attribute exists, then lang( ) returns false.

The lang( ) function takes into account country and other subcodes before making its determination. For example, lang('fr') returns true for elements whose language code is fr-FR, fr-CA, or fr. However, lang('fr-FR') is not true for elements whose language code is fr-CA or fr.

last( )

number last( )

The last( ) function returns the size of (i.e., the number of nodes in) the context node-set.

local-name( )

string local-name( )
string local-name(node-set nodes)

With no arguments, this function returns the context node's local name, that is, the part of the name after the colon, or the entire name if it isn't prefixed. For a node-set argument, it returns the local name of the first node in the node-set. If the node-set is empty or the first node in the set does not have a name (e.g., it's a comment or root node), then it returns the empty string.

name( )

string name( )
string name(node-set nodes)

With no arguments, this function returns the qualified (prefixed) name of the context node or the empty string if the context node does not have a name (e.g., it's a comment or root node). With a node-set as an argument, it returns the qualified name of the first node in the node-set. If the node-set is empty or if the set's first node does not have a name, then it returns the empty string.

namespace-uri( )

string namespace-uri( )
string namespace-uri(node-set nodes)

With no arguments, this function returns the namespace URI of the context node. With a node-set as an argument, it returns the namespace URI of the first node in the node-set. If this node does not have a namespace URI (i.e., it's not an element or an attribute node; it is an element or attribute node, but is not in any namespace; or the node-set is empty), then it returns the empty string.

normalize-space( )

string normalize-space( )
string normalize-space(string s)

The normalize-space( ) function strips all leading and trailing whitespace from its argument and replaces each run of whitespace with a single space character. Among other effects, this removes all line breaks. If the argument is omitted, it normalizes the string value of the context node. A nonstring may be passed to this function, in which case it's automatically converted to a string, as if by the string( ) function, and that string is normalized and returned.

not( )

boolean not(boolean b)

The not( ) function inverts its argument; that is, false becomes true and true becomes false. For example, not(3 > 2) is false, and not(2+2=5) is true. Non-Booleans are converted as by the boolean( ) function before being processed.

number( )

number number( )
number number(object o)

The number( ) function converts its argument to a number according to these rules:

A string is converted by first stripping leading and trailing whitespace and then picking the IEEE 754 value that is closest (according to the IEEE 754 round-to-nearest rule) to the mathematical value represented by the string. If the string does not seem to represent a number, it is converted to NaN. Exponential notation (e.g., 75.2E-12) is not recognized.
True Booleans are converted to 1; false Booleans are converted to 0.
Node-sets are first converted to a string as if by the string( ) function. The resulting string is then converted to a number.

If the argument is omitted, then it converts the context node.

position( )

number position( )

The position( ) function returns a number equal to the position of the current node in the context node-set. For most axes it counts forward from the context node. However, if the axis in use is ancestor, ancestor-or-self, preceding, or preceding-sibling, then it counts backward from the context node instead.

round( )

number round(number x)

The round( ) function returns the integer closest to x. For example, round(3.141592) returns 3. round(-3.141592) returns -3. If two integers are equally close to x, then the one that is closer to positive infinity is returned. For example, round(3.5) returns 4, and round(-3.5) returns -3. Non-number types are converted to numbers as if by the number( ) function, before rounding.

starts-with( )

boolean starts-with(string s1, string s2)

The starts-with( ) function returns true if s1 starts with s2; false otherwise. For example, starts-with("Charming cat", "Charm") is true, but starts-with ("Charming cat", "Marjorie") is false. The test is case-sensitive. For example, starts-with("Charming cat", "charm") is false. Nonstrings may be passed to this function as well, in which case they're automatically converted to strings as if by the string( ) function, before the test is made.

string( )

string string( )
string string(object o)

The string( ) function converts an object to a string according to these rules:

A node-set is converted to the string value of the first node in the node-set. If the node-set is empty, it's converted to the empty string.
A number is converted to a string as follows:
- NaN is converted to the string NaN.
- Positive Inf is converted to the string Infinity.
- Negative Inf is converted to the string -Infinity.
- Integers are converted to their customary English form with no decimal point and no leading zeros. A minus sign is used if the number is negative, but no plus sign is used for positive numbers.
- Nonintegers (numbers with nonzero fractional parts) are converted to their customary English form with a decimal point, with at least one digit before the decimal point and at least one digit after the decimal point. A minus sign is used if the number is negative, but no plus sign is used for positive numbers.
A Boolean with the value true is converted to the English word "true." A Boolean with the value false is converted to the English word "false." Lowercase is always used.

The object to be converted is normally passed as an argument, but if omitted, the context node is converted instead.

WARNING: The XPath specification specifically notes that the "string function is not intended for converting numbers into strings for presentation to users." The primary problem is that it's not localizable and not attractive for large numbers. If you intend to show a string to an end user, use the format-number( ) function and/or xsl:number element in XSLT instead.

string-length( )

number string-length(string s)
number string-length( )

The string-length( ) function returns the number of characters in its argument. For example, string-length("Charm") returns 5. If the argument is omitted, it returns the number of characters in the string value of the context node. A nonstring may be passed to this function, in which case it's automatically converted to a string, as if by the string( ) function, and that string's length is returned.

substring( )

string substring(string s, number index, number length)
string substring(string s, number index)

The substring( ) function returns the substring of s starting at index and continuing for length characters. The first character in the string is at position 1 (not 0, as in Java and JavaScript). For example, substring('Charming cat', 1, 5) returns "Charm". If length is omitted, then the substring to the end of the string is returned. For example, substring('Charming cat', 10) returns "cat". As usual, any type of object may be passed to this function in place of the normal argument, in which case it is automatically converted to the correct type.

substring-after( )

string substring-after(string s1, string s2)

The substring-after( ) function returns the substring of s1 that follows the first occurrence of s2 in s1, or it returns the empty string, if s1 does not contain s2. For example, substring-after('Charming cat', 'harm') returns "ing cat". The test is case-sensitive. As usual, nonstring objects may be passed to this function, in which case they're automatically converted to strings as if by the string( ) function.

substring-before( )

string substring-before(string s1, string s2)

The substring-before( ) function returns the substring of s1 that precedes the first occurrence of the s2 in s1, or it returns the empty string if s1 does not contain s2. For example, substring-before('Charming cat', 'ing') returns "Charm". The test is case-sensitive. Nonstring objects may be passed to this function, in which case they're automatically converted to strings as if by the string( ) function.

sum( )

number sum(node-set nodes)

The sum( ) function converts each node in the node-set to a number, as if by the number( ) function, then it adds up those numbers and returns the sum.

translate( )

string translate(string s1, string s2, string s3)

The translate( ) function looks in s1 for any characters found in s2. It replaces each character with the corresponding character from s3. For example, translate("XML in a Nutshell", " ", "_") replaces the spaces with underscores and returns "XML_in_a_Nutshell". translate("XML in a Nutshell", "XMLN", "xmln") replaces the uppercase letters with lowercase letters and returns "xml in a nutshell". If s3 is shorter than s2, then characters in s1 and s2 with no corresponding character in s3 are simply deleted. For example, translate("XML in a Nutshell", " ", "") deletes the spaces and returns "XMLinaNutshell". Once again, nonstring objects may be passed to this function, in which case they're automatically converted to strings, as if by the string( ) function.

true( )

boolean true( )

The true( ) function simply returns true. It makes up for the lack of Boolean literals in XPath.