XPATH Functions

All tutorials are implemented in text (here), and also with exercises and multimedia in the Tutorial Player. The main home page has a search engines, and more facilities.

Introduction

This tutorial introduces the 27 core functions provided in XPath. They are available in all implementations of XPath.

XPath functions are classified as set-node, string, boolean, number.

Functions

XPath 1.0 specifies 27 core functions which are available in all implementations of XPath by way of the function library. These functions can be used in XPath expressions or predicates.

XSLT, XPointer extend this list of functions, and XSLT allows user-defined functions.

Functions are specified in a function prototype, and a ? character after an argument indicates an optional argument.

XPath is loosely typed, and arguments are converted, if necessary, into a new type. However, a set of nodes must be passed as a set of nodes only, XPath cannot convert something else into a set of nodes.

Types

XPath functions return one of four types:

-node set
-string
- boolean
- number

There are no void functions in XPath.

Set Node Functions

There are seven node-set functions. They return node-sets, or provide information about node-sets.

number last()

This returns the size context node list (ie number of nodes)

number position()

This returns the number of nodes (ie position) from the current node in the context node set. For reserve axis (ie going backwards using ancestor, preceding, and so on), then the number of nodes backwards is counted.

number count(node-set set)

This returns the number of nodes in the node set.

node-set id(object)

This returns a node set of all elements with the specified string ID. If a node-set is specified, then the node set is converted to a collection of strings, and all element ID's matching the members of the collection of strings are returned.

string local-name (node-set?)

If node-set is omitted, then the local-name (ie the name after the : in an expanded-name) is returned as string. If a node-set is passed to local-name, then the local-name of the first node of the passed node-set is returned. This is the empty string, if the first node has no name (for example if it is a comment).

string namespace-uri(node-set?)

This is similar to local-name, except that the namespace URI is returned instead of the local-name. Similarly, the first node is considered if a node-set is passed, and if no namespace URI exists, then an empty string is returned.

name()

This is really a combination of the namespace-uri and local-name in terms of functionality. It returns the full qualified name of the first node of a node-set or of self.

String Functions

There are ten string functions. They provide string handling facilities in XPath.

object string(object?)

This function converts an object to a string.

string concat(string,string,string*)

Argument strings are concatenated. Non-strings in the argument list are converted to a string before concatenation.

boolean starts-with(string1,string2)

True is returned if string1 starts with string2, otherwise false. In other words if string2 is a substring of string1, starting at location 0, then true is returned. for example, string1="XML Tutorial", string2="XML" returns false.

boolean contains(string1,string2)

If string2 is a substring of string1, then true is returned, otherwise false is returned.

string substring-before(string, string)

A substring of the first argument string is returned. This substring consists of the characters from the first character string string until and including the character string specified in the second argument. For example:

string substring-before("XML Tutorial","Tutorial") returns "XML "

string substring-after(string, string)

As with substring-before, except the substring after the first occurrence of the second argument string is returned.

string substring(string, number, number?)

A substring is returned using the number as a character location at 1 and not 0. The length of the substring is specified in the second number argument.

string substring("XML Tutorial",5) returns "Tutorial". Note that the omission of the second number argument means that a default value is assumed, which is equal to the whole (string length - number+1). In other words the whole string is returned starting from position number.

number string-length(string?)

This returns the length of the string. If string is omitted, then the length of the string-value of the context node is returned.

string normalize-space(string?)

The returned string has the leading and trailing whitespaces removed, and replacing sequences of white spaces with a single space.

string translate(string1, string2, string3)

This function translates the characters found in string1 using string2 and string3. For all matches of string2 characters in string1 the translated character is found in string3. If no character is found in string3 (because string3 is shorter than string2), then the translated character is NULL, and therefore the effect is to delete from the returned string.

string translate("logicians","abcdefghijklmnopqrstuvqxwyz", "ABCDEFGHIJKLMNOPQRSTUVWXYZ")
returns LOGICIANS.

But
string translate("logicians","logicians","LOGICIAN") returns LOGICIAN.

Note that W3.org states that the translate function is not a sufficient solution for case conversion in all languages. A future version of XPath may provide additional functions for case conversion.

Boolean Functions

There are five boolean functions. They return boolean values.

boolean boolean(object)

The argument is converted to a boolean.

Argument         True condition
number             not zero of NaN (undefined or infinity)
node-set           non-empty
string	          length is non-zero

boolean not(boolean)

This is a logic not function.

Argument	Return
True		False
False		True

boolean true()

This always returns true.

boolean false()

This always returns false.

boolean lang(string)

This returns if the string argument matches the xml:lang value, or is a sublanguage of xml:lang. the xml:lang attribute can specified on the context node or the nearest ancestor is taken in this match. Cases are not matched, and a prefix can be taken, for example "en" would match against "en-us".

Number Functions

There are five number functions. They provide number handling facilities in XPath.

number number(object?)

This converts strings to numbers using the IEEE 754 value with leading and trailing whitespaces removed. Node-sets are converted to strings, and then numbers as above. Boolean is converted to 1 is true, 0 otherwise.

number sum(node-set)

This converted node-sets to a string and then a number (using number function). The sum of these numbers is returned.

number floor(number)

This returns the integer value not greater than the argument.

Argument                 Return
8.989                        8
-8.989                      -9

number ceiling(number)

Similar to the floor function, but the value not less than the argument is returned.

Argument                 Return
8.989                        9
-8.989                      -8

number round(number)

This returns a number of the argument rounded to the nearest integer.

Argument                 Return
8.989                        9
8.5                             9
-8.989                      -9
-8.5                            -8

The 0.5 value is rounded up to the next highest integer value.

Summary

This tutorial introduced the 27 core functions available in all implementations of XPath.

These functions are classified as set-node, string, boolean, number.