Introduction to XPath

Introduction

XPath is a language used to identify particular parts of XML documents. It lets you write expressions that refer to elements and their attributes in a DOM document. XPath indicates nodes by position, relative position, type, content, and other criteria.

XPath expressions can represent data types such as numbers, strings, or booleans, so it is possible to carry out simple arithmetic operations and comparisons. String manipulation in XPath gives you powerful control over text content in a DOM document.

The Tree Structure of an XML Document

An XML document is a tree made up of nodes. Some nodes contain other nodes. One root node ultimately contains all other nodes. The collection of nodes is arranged in a tree structure called the Document Object Model (DOM) . XPath is a language that operates on the DOM for picking nodes and sets of nodes out of this tree. From the perspective of XPath, there are seven kinds of nodes:

  1. The root node
  2. Element nodes
  3. Text nodes
  4. Attribute nodes
  5. Comment nodes
  6. Processing instruction nodes
  7. Namespace nodes

Note the following types are not included in this list: CDATA sections , entity references , and document type declarations. XPath operates on a XML document after these items have merged into the document. For instance, XPath cannot identify the first CDATA section in a document or tell whether a particular attribute value was included directly in the source element start tag or merely defaulted from the declaration of the attribute in the DTD.

Consider the document below. This document contains all seven types of nodes. Figure XX is a diagram of this document's tree structure.

<soap-env:Envelope 
    soap-env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
    xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:xlink="http://www.w3.org/1999/xlink">
    <soap-env:Header/>
    <soap-env:Body>
        <people>
                <person born="1912" died="1954" id="p342">
                        <name>
                                <first_name>Alan</first_name>
                                <last_name>Turing</last_name>
                        </name>
                        <!-- Mathematician and computer scientist were synonymous in those days -->
                        <profession>computer scientist</profession>
                        <profession>mathematician</profession>
                        <profession>cryptographer</profession>
                        <homepage xlink:href="http://www.turing.org.uk/"/>
                </person>
 
                <person born="1918" died="1988" id="p4567">
                        <name>
                                <first_name>Richard</first_name>
                                <middle_initial>M</middle_initial>
                                <last_name>Feynman</last_name>
                        </name>
                        <profession>physicist</profession>
                        <hobby>Playing the bongoes</hobby>
                </person>
        </people>
    </soap-env:Body>

</soap-env:Envelope>

The XPath data model has several inobvious features. First, the tree's root node is not the same as its root element. The tree's root node contains the entire document, including the root element and comments and processing instructions that occur before the root element start tag or after the root element end tag. In the example given, the root node contains the xml-stylesheet processing instruction and the root element people.

The XPath data model does not include everything in the document. In particular, the XML declaration and 'DTD are not addressable via XPath. However, if the DTD provides default values for any attributes, then XPath recognizes those attributes. The homepage element has an xlink:type attribute supplied by the DTD. Similarly, any references to parsed entities are resolved. Entity references, character references, and CDATA sections are not individually identifiable, though any data they contain is addressable.

Finally, xmlns attributes are reported as namespace nodes '. They are not considered attribute nodes , though a non-namespace aware parser will see them as such. Furthermore these nodes are attached to every element and attribute node for which that declaration has scope. They are not just attached to the single element where the namespace is declared.

Location Paths

The most used XPath expression is a location path. A location path uses at least one location step to identify a set of nodes in a document. This set may be empty, contain a single node, or contain several nodes. These nodes can be element, attribute, namespace, text, comment, processing instruction, root nodes, or any combination of them.

The Root Location Path

The simplest location path is the one that selects the document's root node. This path is simply the forward slash / (a lot of XPath syntax was deliberately chosen to be similar to the syntax used by the Unix shell). Here / is the root of a Unix filesystem and / is the root node of an XML document).

The forward slash / is an absolute location path because no matter what the context node is, no matter where you were in the input document when this template was applied, it always means the same thing: the root node of the document. It is relative to the document you process, but not to anything within that document.

So applying the expression / to the example yields the document node of the XML document. It's first child is the soap-env:Envelope node. Running the FilterNodes example program from the xoap library gives the following output:

% ./run_test.sh FilterNodes.exe example2.soap '/'
Applying filter '/' to message yielded 1 nodes
Name: #document, namespace: 
  --> Child name: Envelope, namespace: http://schemas.xmlsoap.org/soap/envelope/

Child Element Location Steps

The second simplest location path is a single element name. This selects all child elements with the specified name. For example, the XPath profession refers to all profession child elements of the context node. Exactly which elements they are depends on what the context node is, so this is a relative XPath. If the context node is the Alan Turing person element in the example document, then the location path profession refers to that element's three profession child elements:

    <profession>computer scientist</profession>
    <profession>mathematician</profession>
    <profession>cryptographer</profession>

However, if the context node is the Richard Feynman person element, then the XPath profession refers to its single profession child element:

    <profession>physicist</profession>

If the context node is the name child element of Richard Feynman or Alan Turing 's person element, then this XPath doesn't refer to anything at all because neither of these elements has profession child elements.

By default, the context node is the root node / , thus running our example program with the expression soap-env:Envelope gives the following, reproduced output (the program prints the name and namespace of the found node as well as a list of its direct decendents).

% ./run_test.sh FilterNodes.exe example2.soap 'soap-env:Envelope'
Applying filter 'soap-env:Envelope' to message yielded 1 nodes
Name: Envelope, namespace: http://schemas.xmlsoap.org/soap/envelope/
  --> Child name: #text, namespace: 
  --> Child name: Header, namespace: http://schemas.xmlsoap.org/soap/envelope/
  --> Child name: #text, namespace: 
  --> Child name: Body, namespace: http://schemas.xmlsoap.org/soap/envelope/
  --> Child name: #text, namespace: 

Attribute Location Steps

Attributes are also part of XPath. To select a particular attribute of an element, use an at sign @ followed by the name of the attribute you want. For example, the XPath expression @born selects the born attribute of the context node.

Four kinds of nodes still need to be addressed: namespace nodes, text nodes, processing instruction nodes, and comment nodes. Namespace nodes are rarely invoked explicitly. Instead, the stylesheet uses its own xmlns attributes and prefixes, and the processor handles any necessary conversion between input namespace prefixes and namespace prefixes (as long as the URIs match).

The other three node types have special functions to match them:

  • comment( )
  • text( )
  • processing-instruction( )

Since comments and text nodes don't have names, the comment( ) and text( ) functions match any comment or text node that's an immediate child of the context node . Each comment is a separate comment node. Each text node contains the maximum possible contiguous run of text not interrupted by a tag. Entity references and CDATA sections are resolved into text and markup and do not interrupt text nodes.

With no arguments, the processing-instruction( ) function selects all the context node's processing instruction children. If it has an argument, it selects only the processing instruction children with the specified target. For example, the XPath expression processing-instruction('xml-stylesheet') selects all processing instruction children of the context node whose target is xml-stylesheet .

Wildcards

Wildcards allow you to match different element and node types at the same time. There are three wild cards: * , node( ) , and @* .

The asterisk * matches any element node, regardless of type. The * does not match attributes, text nodes, comments, or processing instruction nodes. Thus in this example, output comes only from child elements that have their own templates that override this one.

You can put a namespace prefix in front of the asterisk. In this case, only elements in the same namespace are matched. For example, soap-env:* matches all elements with the same namespace URI as the soap-env prefix is mapped to. As usual, the URI, not the prefix, matters . Applied to the example, the XPath expression soap-env:* will be applied to the root node and thus result in

<soap-env:Envelope 
    soap-env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
    xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xlink="http://www.w3.org/1999/xlink">

The node( ) wild card matches all nodes: element nodes, text nodes, attribute nodes, processing instruction nodes, namespace nodes, and comment nodes.

The @* wild card matches all attribute nodes. For example the expression //person/@* returns

born
died
id
born
died
id

As with elements, you can attach a namespace prefix to the wild card to match only attributes in a specific namespace. For instance, @soap-env:* matches the attribute encodingStyle namespace http://schemas.xmlsoap.org/soap/envelope/ . Again, the URI, not the actual prefix, matters.

Multiple Matches with |

You may want to match more than one type of element or attribute, but not all types. For example, you may want an expression that applies to the profession and hobby elements, but not to the name , person , or people elements. You can combine individual location steps with the vertical bar | to indicate that you want to match any of the named elements. For instance, profession|hobby matches profession and hobby child elements of the context node. The reproduced example here uses already an expression to find all nodes in the document that match a node name. This will be explained later on.

Applying filter '//profession|//hobby' to message yielded 5 nodes
Name: profession, namespace: 
Name: profession, namespace: 
Name: profession, namespace: 
Name: profession, namespace: 
Name: hobby, namespace: 

first_name|middle_initial|last_name matches first_name , middle_initial , and last_name child elements of the context node. @id|@xlink:href matches id and xlink:href attributes of the context node. *|@* matches elements and attributes, but does not match text nodes, comment nodes, or processing instruction nodes.

Compound Location Paths

The XPath expressions you've seen so far - element names, @ plus an attribute name, / , comment( ) , text( ) , node() , and processing-instruction( ) - are all single location steps . You can combine these location steps with the forward slash to move down the hierarchy from the matched node to other nodes. You can also use a period to refer to the current node , a double period to refer to the parent node , and a double forward slash to refer to descendants of the context node . With the exception of // , these are all similar to Unix shell syntax for navigating a hierarchical file system.

Building Compound Location Paths from Location Steps with /

The forward slash / combines different location steps to make a compound location path. Each step in the path is relative to the one that preceded it. If the path begins with / , then the first step in the path is relative to the root node. Otherwise, it is relative to the context node. For example, consider the XPath expression /soap-env:Envelope/soap-env:Body/people/person/name/first_name . This expression begins at the root node, selects subsequently all people element children of the soap Envelope and Body nodes, selects all person element children of those nodes, then all name children of those nodes, and finally, all first_name children of the nodes. Applied to the example document, the expression indicates these two elements:

<first_name>Alan</first_name>
<first_name>Richard</first_name>

or as reported by our example program

Applying filter '/soap-env:Envelope/soap-env:Body/people/person/name/first_name' to message yielded 2 nodes
Name: first_name, namespace: 
  --> Child name: #text, namespace: 

Name: first_name, namespace: 
  --> Child name: #text, namespace:

To indicate only the textual content of those two nodes, we must go one step further. The XPath expression /soap-env:Envelope/soap-env:Body/people/person/name/first_name/text() selects the strings "Alan" and "Richard".

Applying filter '/soap-env:Envelope/soap-env:Body/people/person/name/first_name/text()' to message yielded 2 nodes
Name: #text, namespace: 
Node text value: Alan
Name: #text, namespace: 
Node text value: Richard 

These two XPath expressions both began with /, so they're absolute location paths that start at the root. Relative location paths can also count down from the context node. For example, the XPath expression person/@id selects the id attribute of the person child element of the context node.

Selecting from All Descendants with //

A double forward slash // selects from all descendants of the context node as well as the context node itself. At the beginning of an XPath expression, it selects from all descendants of the root node. For example, the XPath expression //name selects all name elements in the document.

Applying filter '//name' to message yielded 2 nodes
Name: name, namespace: 
  --> Child name: #text, value: , namespace: 
  --> Child name: first_name, value: Alan, namespace: 
  --> Child name: #text, value: , namespace: 
  --> Child name: last_name, value: Turing, namespace: 
  --> Child name: #text, value: , namespace: 

Name: name, namespace: 
  --> Child name: #text, value: , namespace: 
  --> Child name: first_name, value: Richard, namespace: 
  --> Child name: #text, value: , namespace: 
  --> Child name: middle_initial, value: M, namespace: 
  --> Child name: #text, value: , namespace: 
  --> Child name: last_name, value: Feynman, namespace: 
  --> Child name: #text, value: , namespace: 

Selecting the Parent Element with ..

A double period .. indicates the parent of the current node. For example, the expression //@id identifies all id attributes in the document. The expression person//@id selects all the id attributes of any element that is contained in the person child element of the context node. Therefore, //@id/.. identifies all elements in the document that have id attributes. In our example document these are the two person nodes.

The XPath expression //middle_initial/../first_name identifies all first_name elements that are siblings of middle_initial elements in the document. Applied to our example, the expression selects

Applying filter '//middle_initial/../first_name' to message yielded 1 nodes
Name: first_name, namespace: 
  --> Child name: #text, value: , namespace:

printing the text value with //middle_initial/../first_name/text() gives

Applying filter '//middle_initial/../first_name/text()' to message yielded 1 nodes
Name: #text, namespace: 
Node text value: Richard

, but not Alan, since this node does not have a child node middle_initial .

Selecting the Current Element with .

The single period indicates the current node. It is most commonly used when you need to take the value of the currently matched element. For example to match the content of a comment the expression comment()/. can be used. This works equally well for element nodes, attribute nodes, and all the other kinds of nodes.

Predicates

In general an XPath expression may refer to more than one node. Sometimes this is what you want, but sometimes you need to skim the node set further to select only some of the nodes the expression returns. Each step in a location path may have a predicate that selects from the node list that is current at that step in the expression. The predicate contains a boolean expression, which is tested for each node in the context node list. If the expression is false, that node is deleted from the list; otherwise, it's retained.

For example, suppose you want to find all profession elements whose value is physicist . The XPath expression //profession[.="physicist"] finds one element. Here the period stands for the string value of the current node. You can use single instead of double quotes around the string, which is often useful when the XPath expression appears inside an already-quoted attribute value.

Applying filter '//profession[.="physicist"]' to message yielded 1 nodes
Name: profession, namespace: 
  --> Child name: #text, value: , namespace: 

Use the XPath expression //person [profession="physicist"] to ask for all person elements that have a profession child element with the value physicist . If you want to find the person element with id p4567 , put an @ in front of the attribute name, as in //person[@id="p4567"] .

As well as the equals sign, XPath supports a full complement of relational operators, including < , > , >= , <= , and != . The expression //person[@born<=1976] , for example, locates all the document's person elements with a born attribute whose numeric value is less than or equal to 1976 . Note that if < or <= is used inside an XML document, you still must escape the less-than sign as < ; for example <xsl:apply-templates select="//person[@born<=1976]"/> is one example when using XSLT. XPath doesn't get special exemptions from the normal well-formedness rules of XML. On the other hand, if the XPath expression appears outside an XML document, you may not need to escape the less-than sign.

XPath also provides boolean and and or operators to combine expressions logically. For example, the XPath expression //person[@born<=1920and@born>=1910] selects all person elements with born attribute values between 1910 and 1920, inclusive.

Tip: Do not use any whitespaces inside the [] clause. Use () brackets to separate sub-clauses.

//name[(first_name='Richard')or(first_name='Alan')] selects all name elements that have a first_name child with the value Richard or Alan.

% ./run_test.sh FilterNodes.exe example2.soap "//name[(first_name='Richard')or(first_name='Alan')]"
Applying filter '//name[(first_name='Richard')or(first_name='Alan')]' to message yielded 2 nodes

In some cases the predicate may not be a boolean, but converting it to one can be straightforward. Predicates that evaluate to numbers are true if they are equal to the position of the context node, false otherwise. Predicates that indicate node sets are true if the node set is nonempty and false if it is empty. String values are true if the string is not the empty string, false if it is. Suppose you want to select only the name elements in the document that have a middle_initial child element. The XPath expression //name selects all name elements. The XPath expression //name[middle_initial] selects all name elements and then checks each one to see if it has a middle_initial child element. Only those that do are retained. When applied to the example document, this expression indicates Richard M. Feynman's name element, but not Alan Turing's.

% ./run_test.sh FilterNodes.exe example2.soap "//name[middle_initial]"
Applying filter '//name[middle_initial]' to message yielded 1 nodes
Name: name, namespace: 
  --> Child name: #text, value: , namespace: 
  --> Child name: first_name, value: Richard, namespace: 
  --> Child name: #text, value: , namespace: 
  --> Child name: middle_initial, value: M, namespace: 
  --> Child name: #text, value: , namespace: 
  --> Child name: last_name, value: Feynman, namespace: 
  --> Child name: #text, value: , namespace: 

Any or all location steps in a location path can have predicates. For example, the XPath expression //people/person[@born<1950]/name[first_name = "Alan"] first selects all people elements. Then it chooses all person elements whose born attribute has a value numerically less than 1950 from those elements. Finally, it selects all name child elements that have a first_name child element with the value Alan from that group of elements.

% ./run_test.sh FilterNodes.exe example2.soap '//people/person[@born<1950]/name[first_name="Alan"]'
Applying filter '//people/person[@born<1950]/name[first_name="Alan"]' to message yielded 1 nodes
Name: name, namespace: 
  --> Child name: #text, value: , namespace: 
  --> Child name: first_name, value: Alan, namespace: 
  --> Child name: #text, value: , namespace: 
  --> Child name: last_name, value: Turing, namespace: 
  --> Child name: #text, value: , namespace: 

Unabbreviated Location Paths

Up to this point we have used what are called abbreviated location paths . These paths are much easier to type, less verbose, and more familiar to most people. However, XPath also offers an unabbreviated syntax for location paths that is more verbose, but perhaps less cryptic and definitely more flexible .

Every location step in a location path has two required parts , an

  1. axis and
  2. a node test,

and one optional part, the

  • predicates.

The axis tells you which direction to travel from the context node to look for the next nodes. The node test tells you which nodes to include along that axis, and the predicates further winnow the nodes according to an expression.

In an abbreviated location path, the axis and the node test are combined. However, they are separated by a double colon :: in an unabbreviated location path. For example, the abbreviated location path people/person/@id is composed of three location steps. The first step selects people element nodes along the child axis, the second selects person element nodes along the child axis, and the third selects id nodes along the attribute axis. When rewritten using the unabbreviated syntax, the same location path is child::people/child::person/attribute::id .

These full, unabbreviated location paths may be absolute if they start from the root node, just as abbreviated paths can be. The full form /child::soap-env:Envelope/child::soap-env:Body/child::people/child::person , for example, is equivalent to the unabbreviated form /soap-env:Envelope/soap-env:Body/people/person . Unabbreviated location paths may also have predicates. For example, the abbreviated path //people/person[@born<1950]/name[first_name="Alan"] becomes //child::people/child::person[@born<1950]/child::name[first_name="Alan"] in the full form.

Overall the unabbreviated form is verbose and not used much in practice. It is not allowed in XSLT match patterns. However, it does offer one crucial ability that makes it essential to know. The unabbreviated form is the only way to access most of the axes from which XPath expressions can choose nodes. The abbreviated syntax lets you walk along the child, parent, self, attribute, and descendant-or-self axes. The unabbreviated syntax adds eight more axes:

Ancestor axis: All element nodes that contain the context node; the parent node, the parent's parent, the parent's parent's parent, etc., up through the root node in reverse document order:

Following-sibling axis: All nodes that follow the context node and are contained in the same parent element node in document order:

Preceding-sibling axis: All nodes that precede the context node and are contained in the same parent element node in reverse document order:

Following axis: All nodes that follow the end of the context node in document order:

Preceding axis: All nodes that precede the start of the context node in reverse document order:

Namespace axis: All namespaces in scope on the context node, whether declared on the context node or one of its ancestors:

Descendant axis: All the context node's descendants, not including the context node itself:

Ancestor-or-self axis: All the context node's ancestors and the context node itself:

Using unabbreviated XPath syntax /descendant::person/child::name/following-sibling::* we get:

Applying filter '//descendant::person/child::name/following-sibling::*' to message yielded 6 nodes
Name: profession, namespace: 
Name: profession, namespace: 
Name: profession, namespace: 
Name: homepage, namespace: 
Name: profession, namespace: 
Name: hobby, namespace:  

General XPath Expressions

So far we've focused on the subset of XPath expressions called location paths. Location paths identify a set of nodes in an XML document and are used to match patterns and select expressions. However, location paths are not the only possible type of an XPath expression. XPath expressions can also return numbers, booleans, and strings. For instance, all legal XPath expressions include:

  • 3.141529
  • 2+2
  • 'Rosalind Franklin'
  • true( )
  • 32.5 < 76.2E-21
  • position()=last( )

Note though that such XPath expressions that aren't node sets and thus should be used in particular clauses, for instance location path predicates only.

For example, the expression //person[3>5] does not retrieve any node since the boolean test 3>5 fails. //person[3<5> , however returns the results.

% ./run_test.sh FilterNodes.exe example2.soap '//person[3>5]'
Applying filter '//person[3>5]' to message yielded 0 nodes

% ./run_test.sh FilterNodes.exe example2.soap '//person[3<5]'
Applying filter '//person[3<5]' to message yielded 2 nodes

Numbers

No pure integers exist in XPath. All numbers are eight-byte, IEEE 754 floating point doubles, even if they don't have an explicit decimal point. This format is identical to Java's double primitive type. Besides representing floating-point numbers ranging from 4.94065645841246544e-324 to 1.79769313486231570e+308 (positive or negative) and zero, this type includes special representations of positive and negative infinity and a special not a number value (NaN) used as the result of operations, such as dividing zero by zero.

XPath provides the five basic arithmetic operators familiar to any programmer:

+ : Addition: ; - : Subtraction * : Multiplication: ;div: Division

mod
Taking the remainder:

The more common forward slash couldn't be used for division because it's already used to separate location steps in a location path. Consequently, a new operator was chosen. The commonly used % operator was also replaced by the word mod . Aside from these minor differences in syntax, all five operators behave exactly as they do in Java. For instance, 2+2 is 4, 6.5 div 1.5 is 4.33333333, 6.5 mod 1.5 is 0.5, and so on. Placing the element <xsl:value-of select="6*7"/> in an XSLT template would insert the string 42 into the output document when the template was processed. More often, you'll perform simple arithmetic on numbers read from the input document. For instance, the expression //person[(number(@born)div(10))>191.2] divides the birth date of the persons by 10 and checks which one is grater 191.2. The result is shown below.

% ./run_test.sh FilterNodes.exe example2.soap "//person[(number(@born)div(10))>191.2]"
Applying filter '//person[(number(@born)div(10))>191.2]' to message yielded 1 nodes

Strings

XPath strings are ordered sequences of Unicode characters like "Fred," "Ethel," " " or "." String literals may be enclosed in either single or double quotes, as convenient. The quotes are not themselves part of the string. The only restriction XPath places on a string literal is that it does not contain the type of quote that delimits it. If the string contains single quotes, it must be enclosed in double quotes. and vice versa. String literals may contain whitespace, including tabs, carriage returns, line feeds, backslashes, and other characters that would be illegal in many programming languages. However, if the XPath expression is part of an XML document, some of these possibilities may be ruled out by XML's well-formedness rules, depending on context.

You can use the =  and  !  comparison operators to check whether two strings are the same. You can also use the relational  =< , > , <= , and >= operators to compare strings, but unless both strings clearly represent numbers (e.g., -7.5 or 54.2) the results will probably not make sense. In general, you can't define a real notion of string order in Unicode without detailed knowledge of the text being ordered.

Other operations on strings are provided by XPath functions and are discussed in the following sections.

Booleans

A boolean is a value that has exactly two states: true or false . Every boolean must have one of these binary values. XPath does not provide boolean literals. However, the XPath functions true( ) and false( ) can substitute for the missing literals quite easily.

Booleans, however, are usually created by comparisons between other objects, most commonly numbers. XPath provides all the usual relational operators, including = ,  ! ,  =< , > , >= , and <= . The and and or operators can also be used to combine boolean expressions according to the usual rules of boolean logic.

Booleans are most commonly used in predicates of location paths. In the location path //person[profession="physicist"] , profession="physicist" is a boolean. It is either true or false; there is no other possibility.

Finally, a not( ) function reverses the sense of its boolean argument. For example, if .='computer scientist' is true, then not(.='computer scientist') is false, and vice versa.

XPath Functions

XPath provides many functions you may find useful in predicates or in raw expressions. All of these functions are listed in the XPath Function Reference article. For example, the position( ) function returns the current node's position in the context node list as a number. You can use the function to retrieve for instance a specific node from a set of adjacent nodes with //person[position()=2]/name :

%./run_test.sh FilterNodes.exe example2.soap "//person[position()=2]/name"
Applying filter '//person[position()=2]/name' to message yielded 1 nodes
Name: name, namespace: 
  --> Child name: first_name, value: Richard, namespace: 
  --> Child name: middle_initial, value: M, namespace: 
  --> Child name: last_name, value: Feynman, namespace: 

Each XPath function returns one of these four types:

  • boolean
  • number
  • node set
  • string

There are no void functions in XPath. Otherwise, XPath is not as strongly typed as languages such as Java or C. You can often use these types as a function argument, regardless of which type the function expects, and the processor will convert it the best it can. If you insert a boolean where a string is expected, the processor will substitute one of the two strings true and false for the boolean. The one exception is functions that expect to receive node sets as arguments. XPath cannot convert strings, booleans, or numbers to node sets.

Functions are identified by the parentheses at the end of function names. Sometimes these functions take arguments between the parentheses. The round( ) function takes a single number as an argument. It returns the number rounded to the nearest integer.

Other functions take more than one argument. For instance, the starts-with( ) function takes two arguments, both strings. It returns true if the first string starts with the second string. For example, this expression selects all persons whose last name begins with T :

//name[starts-with(last_name,'T')]

Result:

Applying filter '//name[starts-with(last_name,'T')]' to message yielded 1 nodes
Name: name, namespace: 
  --> Child name: first_name, value: Alan, namespace: 
  --> Child name: last_name, value: Turing, namespace: 

In this example the first argument to the starts-with( ) function is actually a node set, not a string. The XPath processor converts that node set to its string value (the text content of the last_name element) before checking to see whether it starts with T .

Besides the functions defined in XPath and discussed in this chapter, most uses of XPath define additional functions that are useful in their particular context. You use these extra functions just like built-in functions when you use those applications. XSLT for instance even lets you write extension functions in Java and other languages that can do almost anything, for example, make SQL queries against a remote database server and return the result of the query as a node set.

Node Set Functions

Node set functions either operate on or return information about node sets, ordered collections of XPath nodes. You've already encountered the position( ) function. Two related functions are last( ) and count( ) . The last( ) function returns the number of nodes in the context node set, which is the same as the position of the last node in the set. The count( ) function is similar, except that it returns the number of nodes in its node set argument rather than in the context node list. For example, count(//name) tells you how many name elements exist in the document. The following example uses the position( ) and count( ) functions to return the last person element. Note that the first position() is 1 (not 0).

//people/person[position()=count(//person)]

The result is:

% ./run_test.sh FilterNodes.exe example2.soap "//people/person[position()=count(//person)]"
Applying filter '//people/person[position()=count(//person)]' to message yielded 1 nodes

The id( ) function takes a string containing one or more IDs separated by whitespace as an argument and returns a node set containing all nodes in the document that have those IDs. These are nodes with attributes declared to have type ID in the DTD , not necessarily nodes with attributes named ID or id . Thus in the example, id('p342') indicates Alan Turing's person element and id('p342 p4567') indicates both Alan Turing and Richard Feynman's person elements.

The id( ) function is most commonly used in the abbreviated XPath syntax. It allows you to form absolute location paths that don't start from the root. For example, id('p342')/name refers to Alan Turing's name element, regardless of where Alan Turing's person element is in the document, as long as it hasn't changed ID.

Finally, three node set functions are related to namespaces. The local-name( ) function takes as an argument a node set, most often containing just a single node, and returns the local name of the first node in that set. The namespace-uri( ) function takes a node set as an argument and returns the namespace URI of the set's first node. Finally, the name( ) function takes a node set as an argument and returns the prefixed name of the first node in that set. In all three functions the argument may be omitted, in which case the context node is evaluated. For instance, when applied to the example document the XPath expression, //homepage/@xlink:*[local-name()='href'] selects all attribute nodes of tag homepage in the namespace xlink and checks if the local name without the namespace prefix is euqal to href :

% ./run_test.sh FilterNodes.exe example2.soap "//homepage/@xlink:*[local-name()='href']"
Applying filter '//homepage/@xlink:*[local-name()='href']' to message yielded 1 nodes
Name: href, namespace: http://www.w3.org/1999/xlink

The namespace definition can be accessed with namespace-uri(//homepage/@xlink:href) and is http://www.w3.org/1999/xlink ; and name(//homepage/@xlink:href) is xlink:href .

String Functions

XPath includes functions for basic string operations, such as finding a string's length or changing letters from uppercase to lowercase. It doesn't have the full power of the string libraries in Python or Perl; for example, there's no regular expression support. However, XPath is sufficient for many simple manipulations.

The string( ) function converts any type of argument to a string in a reasonable fashion. Booleans are converted to the string true or the string false . Node sets are converted to the string value of the first node in the set. The string value of the element is the complete Unicode text of the element after all entity references are resolved and tags, comments, and processing instructions have been stripped out. Numbers are converted to strings in the format used by most programming languages such as "1987," "299792500," "2.71828," or "2.998E+10."

The normal use of most of the remaining string functions is to manipulate or address the text content of XML elements or attributes. If date attributes were given in the format MM/DD/YYYY , then the string functions would allow you to target the month, day, and year separately.

The starts-with( ) function takes two string arguments. It returns true if the first argument starts with the second argument. For example, starts-with('Richard', 'Ric') is true, but starts-with('Richard', 'Rick') is false. There is no corresponding ends-with( ) function.

The contains( ) function also takes two string arguments. However, it returns true if the first argument contains the second argument--that is, if the second argument is a substring of the first argument--regardless of position. For example, contains('Richard','ar') is true, but contains('Richard','art') is false.

The substring-before( ) function takes two string arguments and returns the substring of the first argument string that precedes the second argument's initial appearance. If the second string doesn't appear in the first string, then substring-before( ) returns the empty string. For example, substring-before('MM/DD/YYYY', '/') is MM . The substring-after( ) function also takes two string arguments, but returns the substring of the first argument string that follows the second argument's initial appearance. If the second string doesn't appear in the first string, substring-after( ) returns the empty string. For example, substring-after('MM/DD/YYYY','/') is DD/YYYY , substring-before(substring-after('MM/DD/YYYY','/')','/') is DD . and substring-after(substring-after('MM/DD/YYYY', '/')', '/') is YYYY .

If you know the position of the substring you want in a given string, then use the substring( ) method instead. This method takes three arguments: the string from which the substring is copied, the position in the string from which to start extracting, and the number of characters to copy for the substring. The third argument may be omitted, in which case the substring contains all characters from the specified start position to the end of the string. For example, substring('MM/ DD/YYYY', 1, 2) is MM ; substring('MM/DD/YYYY', 2) is DD ; and substring('MM/DD/YYYY', 7) is YYYY .

The string-length( ) function returns a number giving the length of the string value of its argument, or of the context node if no argument is included. Applied to the example document, string-length(//name[position( )=1]) is 29. If that value seems long, remember that all whitespace characters are included in the count. If it seems short, remember that markup characters are not included in the count.

Theoretically, you could use these functions to trim and normalize whitespace in element content. However, since this process would be relatively complex and is such a common need, XPath provides the normalize-space( ) function to do this. for the example XML the value of string(//name[position( )=1]) using the xoap Evaluate example is:

% ./run_test.sh Evaluate.exe example2.soap "string(//name[position()=1])"
Applying filter 'normalize-space(string(//name[position()=1]))' to message yielded
       Alan
       Turing

This example contains a lot of extra whitespace that was inserted only to make the XML document neater. However, normalize-space(string(//name[position( )=1])) is more reasonable:

% ./run_test.sh Evaluate.exe example2.soap "normalize-space(string(//name[position()=1]))"
Applying filter 'normalize-space(string(//name[position()=1]))' to message yielded Alan Turing

Boolean Functions

The boolean functions are straightforward and few in number. They all return a boolean with the value true or false. The true( ) function always returns true and the false( ) function always returns false. These functions substitute for boolean literals in XPath.

The not( ) function reverses the sense of its boolean argument. For example, not(@id>400) is almost always equivalent to (@id<=400) . (NaN is a special case.)

The boolean( ) function converts its single argument to a boolean and returns the result. If the argument is omitted, it converts the context node. Numbers are converted to false if they're zero or NaN (not a number); all other numbers are true. Node sets are false if they're empty and true if they contain at least one node. Strings are false if they have zero length and true otherwise. Note that according to this rule, the string "false" is in fact true.

Number Functions

XPath includes a few simple numeric functions used for summing groups of numbers and finding the nearest integer to a number. It doesn't have the full power of the math libraries in common programming languages, for instance, there's no square root or exponentiation function, but it's got enough to do most basic math you need for selection.

The number( ) function can take any type as an argument and convert it to a number. If the argument is omitted, it converts the context node. Booleans are converted to 1 if true and 0 if false. Strings are converted in a plausible fashion. For instance, the string "7.5" is converted to the number 7.5 and the string "8.5E2" is converted to the number 8,500. The string "Fred" is converted to NaN. Node sets are converted to numbers by first converting them to their string values and then converting the resulting string to a number. The detailed rules are more complex, but as long as the object you convert can be reasonably interpreted as a single number, the number( ) function will probably do what you expect. If the object you convert can't be reasonably interpreted as a single number, then the number( ) function returns NaN.

The round( ) , floor( ) , and ceiling( ) functions all take a single number as an argument. The floor( ) function returns the greatest integer less than or equal to its argument. The ceiling( ) function returns the smallest integer greater than or equal to its argument. The round( ) function returns its argument rounded to the nearest integer. When rounding numbers like 1.5 and -3.5 that are equally close to two integers, round () returns the larger of the two.

The sum( ) function takes a node set as an argument. It converts each node in the set to its string value, then converts each of those strings to a number. Finally, it adds the numbers and returns the result.

-- VadimKhotilovich - 11-Aug-2011

Edit | Attach | Watch | Print version | History: r1 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r1 - 2011-08-11 - VadimKhotilovich
 
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    Main All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback