Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki — Fri, 07 Mar 2008 09:45:23 GMT

Initial conversion from Docbook

New page

{{XPath and XPointer/TOC}}
The XPath 1.0 Recommendation specifies a number of ''functions'' and ''numeric operations'' that can be used to refine the results returned by an XPath expression.

Before getting into the details of these features' uses, let's take a look at a fundamental question: what are functions in the first place? (If you're already familiar with the use of functions in programming languages, such as Java, C++, and Visual Basic, feel free to skip this section.)

== Introduction to Functions ==

When I was a kid, I loved watching my father work on cars. He'd been a mechanic all his life, and the automotive toolkit he'd acquired over the course of the years was exotic (to my eyes, anyhow).

One of the smaller items in Dad's toolkit was something he called a "spark-plug gapper." It was something like a Swiss-Army knife, with a half-dozen or so stiff steel prongs that you could swivel out from the tool's main body. Each L-shaped prong was of a slightly different thickness; depending on the model of car you were working on and the specific spark plug's specifications, you'd tap the end of the spark plug on the pavement and, using the gapper, ensure that the distance across which the spark was to jump was just right. There was also a small, stiff plane of sheet metal attached to the gapper, which you could use to spread the gap if you'd already closed it up too much. The objective was the get the gap just right, to ensure that the spark plug fired in just exactly the right way.

A function in computer-language terms is like a spark-plug gapper. It's a tool provided by a software developer. You use the tool in the same general way for a given task, whenever you need to obtain some result you can't obtain (or obtain easily) without the tool.

Almost without exception, regardless of the computer language in question, functions are represented syntactically the same way:

function_name(arg1, ...)

Each function (like each tool in a mechanic's toolbox) has a distinct name. Depending on the function, you may pass one or more arguments to it, which change its behavior in various ways. The arguments are enclosed in parentheses. Thus, the spark-plug gapper might be represented like this:

gapper(prong)

where <tt>gapper</tt> is the function name and <tt>prong</tt>, a single argument provided (or "passed") to the function. Under many circumstances, you wouldn't pass a function like this the literal token <tt>p</tt>, <tt>r</tt>, <tt>o</tt>, <tt>n</tt>, <tt>g</tt>; rather, this is just a placeholder, a reminder to you of what you do pass to it. In this form, the function syntax is called a ''prototype''. When you actually use (or "call" or "invoke") a function, you typically substitute a literal value for each argument. So an actual call to our hypothetical <tt>gapper( )</tt> function might look like this:

gapper(1)

Now, many functions are fussy about both the number of arguments and the type. Depending on how the <tt>gapper( )</tt> function is written, for example, the following might be illegal calls to it:

gapper(3, 6)
gapper("1")

In the first example, there's more than one argument passed; in the second, the argument being passed is a literal string rather than a literal number. If in fact a legal call to <tt>gapper( )</tt> passes only a single numeric argument, either of these two calls will fail — probably resulting in an error message of some kind.

=== What Functions Do ===

The interesting thing about functions is that a call to one of them takes the place of some literal value in a "sentence" in the programming language in question. That is, a function ''returns a value''.

So Dad, in my case, might say to me something like, "Here. Set the gap on this plug to fifteen-thousandths of an inch." This would require me to know how to determine which prong on the gapper produced exactly that effect. More likely, especially if this was my first time handling the tool, he'd say, "Set the gap on this plug with prong number one" (or whatever). In a hypothetical computer language to achieve this purpose, this English-language instruction might be rendered:

setgap '''gapper(1)'''

This would achieve the same effect as:

setgap '''.015'''

That is, in formal terms, the <tt>gapper( )</tt> function, when passed a numeric value of 1, returns the numeric value .015.

=== Functions Within Functions ===

Given, then, that a function returns a value and that the arguments passed to functions are themselves values, it's entirely legal — even desirable, in many circumstances — to pass one function as an argument to another.

Returning to the spark plug-gapping tool, as you can see from the preceding example, the <tt>gapper( )</tt> function returns a value in the form of a fraction of an inch, based on the "prong number" selected. This was eminently reasonable back in Dad's day. Now, though, most spark-plug gaps are expressed in terms of millimeters. So now we'd need a separate method for gapping a plug in metric units instead. The hypothetical computer-language expression of this might look something like:

setgap_mm inches_to_mm('''gapper(1)''')

which is equivalent to:

setgap_mm inches_to_mm('''.015''')

which in turn is equivalent to:

setgap_mm '''.38'''

The <tt>gapper( )</tt> function here still returns .015 — the value in inches of feeler #1's thickness. This value in turn is passed to a hypothetical conversion function, <tt>inches_to_mm( )</tt>, which takes a single argument — a number of inches — and converts it to millimeters.

== XPath Function Types ==

The functions available for use in XPath expressions are categorized by the type of value they return and/or by the type of values they operate on as arguments. These categories are node-set, string, Boolean, and numeric functions.

In each of the function prototypes in this section, I'll use the following scheme to denote the kind of arguments passed:

;<tt>string</tt>
: Argument is a string value, to be enclosed in quotation marks in the function call. If a function call takes more than one string argument, I'll append a number to each, as in <tt>string1</tt>, <tt>string2</tt>, and so on.
;<tt>nodeset</tt>
: Argument is a node-set, represented by an XPath location path. Note that if you're using XPath in an XSLT stylesheet, this location path will (if it's a relative path) be sensitive to the context established by the stylesheet at that point. Whether you're using XPath in XSLT or an XPointer, earlier portions of a complete location path can of course establish a context for node-set references in later portions.
;<tt>boolean</tt>
: Argument has a Boolean value of true or false.
;<tt>number</tt>
: Argument has a numeric value. If a function call takes more than one numeric argument, I'll append a number to each, as in <tt>number1</tt>, <tt>number2</tt>, and so on.
;<tt>anytype</tt>
: Argument can be any of several types. For instance, you can pass certain functions a string or a numeric argument, and the function will handle any necessary data-type conversion.
;<tt>?</tt>
: A question mark appended to one of the above data types means the argument is optional. For instance, a call to a hypothetical <tt>my_func( )</tt> function might come with a prototype such as <tt>my_func(string?)</tt>. This would mean that when you call <tt>my_func( )</tt>, you may supply a string argument or no argument at all. In such a case, the function will usually assume some default value for the argument, perhaps derived from the context node at the point of the function call.

Note that the type of data returned by each function is documented in a table at the start of the section dealing with the appropriate function type. Unlike functions in some traditional programming languages, XPath functions ''always'' return a value.

<div class="tip">
'''Tip'''

XSLT and EXSLT both provide functions that go beyond XPath itself. If you need something beyond what this chapter describes, see [[XPath and XPointer/Extension Functions for XPath in XSLT|Appendix A]].
</div>

=== Node-Set Functions ===

A node-set function, as the name implies, operates on a node-set; one of these functions also ''returns'' a node-set. [[XPath and XPointer/XPath Functions and Numeric Operators#xpathpointer-CHP-4-TABLE-1|Table 4-1]] summarizes the functions in this category. Each function is discussed in detail in a separate subsection following the table. These discussions assume that the source document being referenced by XPath expressions is the following fragment of an XML document:

<nowiki><!DOCTYPE book:book
<!ATTLIST book:section id ID #IMPLIED>
]>
<book:book
xmlns:book="http://mynamespace/uri"
xmlns:xlink="http://www.w3.org/1999/xlink/ "
xmlns="http://www.w3.org/2000/svg">

<book:chapter>
<book:section id="sect_01">
<book:para id="para_01">Some text...
For more information, see:
<book:ref xlink:href="crossref_01.xml">crossref_01.xml</book:ref>
</book:para>
<svg>
<circle style="fill:yellow"
cx="100" cy="100" r="50"/>
</svg>
</book:section>
</book:chapter>

[...remainder of book...]

</book:book></nowiki>

<div class="tip">
'''Tip'''

Note the <tt>ATTLIST</tt> declaration in this document's prolog. As you'll see, your documents may need such a declaration (in either the internal DTD subset, as here, or an external one) to determine that an attribute is of the <tt>ID</tt> type. However, if you're using the MSXML XSLT processor, be aware that the <tt>ATTLIST</tt> declaration alone will not suffice to make the processor recognize the (in this case) <tt>id</tt> attribute; the processor also requires that the attribute's parent ''element'' (<tt>book:section</tt>, here) be declared.
</div>

<div id="xpathpointer-CHP-4-TABLE-1">
'''Table 4-1. Node-set functions'''

{| border="1"
|-
! Function prototype !! Returns !! Description
|-
|

last( )
| Number || Returns the number of nodes in the context node-set
|-
|

position( )
| Number || Returns the ordinal position of the context node within the context node-set
|-
|

count(nodeset)
| Number || Returns the number of nodes in <tt>nodeset</tt>
|-
|

id(string)
| Node-set || Returns the element node with an ID-type attribute equal to the value of the passed argument
|-
|

local-name(nodeset?)
| String || Returns the local name (that is, the QName without a namespace prefix) of the first node in <tt>nodeset</tt>
|-
|

namespace-uri(nodeset?)
| String || Returns the URI associated with the namespace prefix of the first node in <tt>nodeset</tt>
|-
|

name(nodeset?)
| String || Returns the QName of the first node in <tt>nodeset</tt>
|}
</div>

==== last( ) ====

If the context node-set, at the point of the call to <tt>last( )</tt>, contains 12 nodes, <tt>last( )</tt> returns 12.

Assume the context for the call to <tt>last( )</tt> is established by a location path such as the following, referencing the sample XML document above:

//book:section/*

This locates a node-set consisting of two element nodes, <tt>book:para</tt> and <tt>svg</tt>. Therefore, a call to <tt>last( )</tt> at this point returns the value 2.

Probably the most common use of <tt>last( )</tt> is in a location step's predicate, as in:

/book:book/book:chapter['''last( )''']

which selects the last chapter in the book.

==== position( ) ====

This commonly used function returns the integer representing the context node's ordinal position within the context node-set. These positions begin at 1 (for the first node in the node-set) and increment up to the value of the <tt>last( )</tt> function.

The sample XML document's root element, <tt>book:book</tt>, has six element nodes visible along its <tt>descendant</tt>:: axis (<tt>book:chapter</tt>, <tt>book:section</tt>, <tt>book:para</tt>, <tt>book:ref</tt>, <tt>svg</tt>, and <tt>circle</tt>). Therefore, this location path:

/book:book/descendant::*

locates a node-set consisting of those six element nodes. You could locate just the <tt>svg</tt> node by adding a predicate, as here:

/book:book/descendant::*[position( )=5]

That is, "locate the fifth node in the node-set."

Note that the value returned by the <tt>position( )</tt> function is sensitive to the forward or reverse direction of the axis in effect. For forward-type axes, such as <tt>descendant::</tt> in the preceding example, nodes are accessed in their natural document order; for reverse-type axes, nodes are accessed in reverse document order. So we could build a location path beginning, say, at the <tt>svg</tt> element node and locating the ancestor <tt>book:chapter</tt> element with a location path such as:

//svg/ancestor::*[position( )=2]

Here, the <tt>book:section</tt> element is ancestor #1 in reverse document order, and <tt>book:chapter</tt> is ancestor #2.

The <tt>position( )</tt> function is important, as I've said, for two reasons:

<ul>
<li><div>It can be represented in a location step's predicate simply by the value of the position for which you want to test. That is:

//svg/ancestor::*['''position( )=2''']

and:

//svg/ancestor::*['''2''']

are functionally identical.
</div></li>

<li><div>Many XSLT operations must be performed for every ''n''th occurrence of some kind of node in the source tree being transformed. For a simple example, perhaps you want to shade every odd row of a table, leaving the even rows unshaded: in other words, to shade every second row. This kind of processing can be achieved easily using <tt>position( )</tt> together with the <tt>mod</tt> numeric operator. I'll describe <tt>mod</tt> later in this chapter and give an example of its use with <tt>position( )</tt>.
</div></li>

</ul>

==== count(nodeset) ====

In every respect but one, the <tt>count( )</tt> function operates identically to the <tt>last( )</tt> function covered earlier. What makes it different is that <tt>count( )</tt> takes one argument; <tt>last( )</tt>, none. Thus, <tt>count( )</tt> can be used to return the number of nodes in some arbitrary node-set other than the current one.

The following XSLT template displays the number of the current section in the chapter within which it appears, then displays (using <tt>count( )</tt>) the total number of <tt>book:section</tt> nodes in the document as a whole. Note the nested <tt>xsl:for-each</tt> elements, which cause processing in the template rule to "loop" through some set of operations for every node in a select node-set. Here, the outermost <tt>xsl:for-each</tt> element loops through every <tt>book:chapter</tt> element; the innermost <tt>xsl:for-each</tt> element loops through each <tt>book:section</tt> child of the selected <tt>book:chapter</tt>.

<xsl:template match="/">
<xsl:for-each select="book:book/book:chapter">
Chapter <xsl:value-of select="position( )"/>:
<xsl:for-each select="book:section">
This is section #<xsl:value-of select="position( )"/> of
<xsl:value-of select="'''last( )'''"/> within its chapter.
</xsl:for-each>
</xsl:for-each>
The total number of sections in the book is: <xsl:value-of
select="'''count(//book:section)'''"/>
</xsl:template>

When you apply this template to a sample document consisting of three <tt>book:chapter</tt> elements — the first with one <tt>book:section</tt> child elements, the second with three, and the third with two — the result is:

Chapter 1:

This is section #1 of
1 within its chapter.

Chapter 2:

This is section #1 of
3 within its chapter.

This is section #2 of
3 within its chapter.

This is section #3 of
3 within its chapter.

Chapter 3:

This is section #1 of
2 within its chapter.

This is section #2 of
2 within its chapter.

The total number of sections in the whole book is: 6

==== id(anytype) ====

Unlike the other functions in the node-set category, the <tt>id( )</tt> function actually returns a node-set, given its argument. (The argument is usually, but not always, a string; see [[XPath and XPointer/XPath Functions and Numeric Operators#id( ) and node-set arguments|Section 4.2.1.5]], for more information.) The value of the argument locates the set of all element nodes with the indicated ID-type attribute; because the value of an ID-type attribute, by definition, must be unique within a given document, the resulting node-set thus will contain a single element node (or be empty, if no elements have an ID-type attribute with this value). You can also use a whitespace-delimited ''list'' of values to return all element nodes with any matching ID-type attributes. For instance:

id("sect_01 sect_05 sect_88")

returns a node-set consisting of up to three element nodes. If no element nodes match a particular value, no error condition exists. In this example, if no element node has an ID-type attribute whose value is <tt>sect_05</tt> but there ''are'' matches for the other two values, the resulting node-set would contain two elements.

It's important that you heed the phrase "ID-type attribute" here. The <tt>id( )</tt> function ignores any attributes whose ''names'' are "id," unless they are declared in the document's DTD as being of the ID type. Thus:

id("sect_01")

successfully returns the <tt>book:section</tt> element with that <tt>id</tt> attribute value, while:

id("para_01")

returns an empty node-set: the former <tt>id</tt> attribute is expressly declared to be an ID-type attribute in the document's DTD, while the latter is not. Perhaps more importantly, if there is no DTD at all — if the document is simply well formed — it doesn't make any difference what value you pass to the <tt>id( )</tt> function; it will always in this case return an empty node-set. If you're uncertain whether an attribute named <tt>id</tt> is of the ID type — or know for sure that it isn't — test the attribute value in a location step's predicate, as in:

[@id="para_01"]

or, if the context node is already the <tt>id</tt> attribute:

[.="para_01"]

Such an approach, while perhaps more prosaic, is also closer to failure-proof. (XSLT users can also take advantage of <tt>keys</tt> to ensure unique identifiers.)

==== id( ) and node-set arguments ====

The <tt>id( )</tt> function is unique among functions in the XPath spec in one regard. As with the other functions, if you pass it a value that is ''not'' a string, the value is treated as if it had been converted to a string by the <tt>string( )</tt> function (covered later in this chapter). Typically, when you pass <tt>string( )</tt> a node-set, it returns the string-value of only the ''first'' node in the node-set. However, when you pass <tt>id( )</tt> a node-set, the function returns not only a single node (whose ID-type attribute's value would presumably match the string-value of the first node), but rather a node-set containing all element nodes whose ID-type attributes match any of the string-values of nodes in the passed node-set.

==== local-name(nodeset?) ====

The <tt>local-name( )</tt> function returns the name of a node, shorn of any namespace prefix. (You might call this the un-QName.) If the optional argument is not supplied, the function operates as if you had passed it a node-set consisting only of the context node. If the node-set contains more than one node, the function returns the local-name of only the first node (in document order) in the node-set:

local-name(//book:chapter)

returns the string <tt>chapter</tt> and:

local-name(//svg)

returns the string <tt>svg</tt>. On the other hand:

local-name(//book:section | //svg)

(note the compound location path) returns the string <tt>section</tt> — that is, the local-name of only the first node in the node-set.

==== namespace-uri(nodeset?) ====

When you need to know the URI associated with a given element or attribute's namespace in an instance document, call the <tt>namespace-uri( )</tt> function. If you omit the optional argument, its default value is a node-set consisting of just the context node. If the node-set passed as the argument consists of more than one node, the function returns the URI associated with only the first node in the node-set. If the specified element or attribute has no associated URI, the function returns an empty string.

In the sample XML document, each element node is associated with a namespace URI. The elements with explicit <tt>book</tt>: prefixes are associated with the URIs tied to those prefixes via the namespace declarations for that prefix. For instance:

namespace-uri(/book:book)

returns the string "http://mynamespace/uri."

Note that when an attribute node's name is unprefixed — even when there's an explicit ''default'' namespace declaration (<tt>xmlns</tt> attribute) in effect for the node — the <tt>namespace-uri( )</tt> function returns a null value. This expression:

namespace-uri(//circle@style)

returns a null string.

An attribute also does not acquire the namespace URI associated with the corresponding element automatically. For attributes in the sample document such as <tt>id</tt>, <tt>style</tt>, and <tt>cx</tt>, an empty string is returned as the namespace URI. However, this expression:

namespace-uri(//book:ref/@xlink:href)

returns the string "http://www.w3.org/1999/xlink/" — the URI associated (via the <tt>xmlns:xlink</tt> declaration) with the attribute's <tt>xlink</tt>: namespace prefix.

By the way, as always when dealing with namespaces, remember that the exact namespace prefix is seldom relevant: what counts is the URI to which the namespace prefix is bound. For instance, at the time the XPath expression is evaluated — say, in an XSLT stylesheet or an XPointer — the namespace URI "http://mynamespace/uri" might be associated with the prefix <tt>mybook</tt>:. In such a context, the following two function calls return exactly the same results as long as the document containing the XPath expression binds both prefixes to the same URI:

namespace-uri('''/book:'''book)
namespace-uri('''/mybook:'''book)

The document being evaluated by the expression needn't use either of those two prefixes in the element name, as long as whatever prefix it ''does'' use is bound to the "http://mynamespace/uri" URI.

==== name(nodeset?) ====

If your applications must refer to nodes in a namespace-aware fashion (as most applications do), the <tt>name( )</tt> function will probably be the node-name function you'll use least often. That's because it returns the QName of the node-set passed (or defaulted) as its sole argument — the "intuitive" name, including both the namespace prefix and the local-name portion. Therefore, <tt>name( )</tt> is truly reliable only when processing elements and attributes in no namespace at all. As in the other name-related functions, passing no argument at all causes <tt>name( )</tt> to operate on a node-set consisting of just the context node; if the node-set argument includes more than one node, the function operates on only the first.

On the face of it, using a function such as <tt>name( )</tt> might seem superfluous. After all, the most common form of a location step includes an explicit node name, and if you already know the node's name, there's no need for a function to return it.

Where it comes in handy is when you ''don't'' (for one reason or another) know the name of the node in question or simply need to test the name (particularly of an attribute) against a string. For instance, you might need to isolate the ''n''th child of a particular element, displaying its name and the names and values of all its attributes. Here's another example from XSLT using nested <tt>xsl:for-each</tt> elements:


<xsl:template match="/
<xsl:for-each select="book:section/*[1]">

The first child's name is <xsl:value-of select="'''name( )'''"/>,
and it has the following attributes:<br/>
<xsl:for-each select="@*">

<xsl:value-of select="'''name( )'''"/> = <xsl:value-of select="."/><br/>
</xsl:for-each>
</xsl:for-each>
</xsl:template>

Applied to the sample XML document for this section, this template rule generates the text:

The first child's name is book:para, and it has the following attributes:
id = para_01

A special case of "not knowing the name of the node in question" occurs in generic XSLT stylesheets whose purpose is to ''describe'' the documents they process, displaying the names of the various nodes and their values. A portion of such a stylesheet might look something like the following:


<xsl:template match="*">

Child's name: <xsl:value-of select="'''name( )'''"/>

Child's value: <xsl:value-of select="."/>
</xsl:template>

What makes this a special case is not necessarily that you really don't know the node's name — you may know very well what element names occur in your source document — rather, the general-purpose code doesn't ''care'' what the element's name is at this point; it treats all (child) elements the same way.

<div class="tip">
'''Tip'''

In [[XPath and XPointer/XPath Basics|Chapter 2]], you saw something called an "expanded-name" for the various node types. I described an algorithm there for computing an expanded-name, consisting of the namespace URI, a plus sign, and the local-name of the node. You can use the same algorithm for computing the expanded-name with an XPath expression, by concatenating for a given name the value returned by the <tt>namespace-uri( )</tt> function, the <tt>+</tt>, and the value returned by the <tt>local-name( )</tt> function. I'll show you how to do this concatenation in the next section, in the discussion of the <tt>concat( )</tt> string function.
</div>

<div class="sidebar">
'''Names and Nodes'''

Although the node-set functions — such as <tt>count( )</tt>, <tt>position( )</tt>, and <tt>name( )</tt> — are most often (and most "naturally") employed in locating and otherwise processing element and attribute nodes, nothing inherently constrains these functions to operating on only those node types. (The exception is <tt>id( )</tt>. Its focus is strictly on dealing with element nodes, because they're the only node type that can be accessed by way of ID-type attributes.)

For example, you can count the number of text nodes in a document with an expression such as:

count(//text( ))

which uses the <tt>text( )</tt> node-type test to restrict the resulting node-set only to text nodes.

Remember too that not only elements and attributes but also PIs have names. A PI's name isn't associated with any particular namespace so the <tt>name( )</tt> function always returns just the PI's target. In this case, the value returned by the <tt>local-name( )</tt> function is identical to the value returned by the <tt>name( )</tt> function. (Indeed, that is true for ''all'' node types except elements and attributes.) The value returned by the <tt>namespace-uri( )</tt> function when applied to a PI is an empty string.

If the first node in the node-set handled by <tt>local-name( )</tt>, <tt>namespace-uri( )</tt>, or <tt>name( )</tt> is the root node, a comment, or a text node, the returned value is likewise an empty string. These node types do not have anything remotely like a "name."

Rather bizarrely, in my opinion, namespace nodes have expanded names. The local part of a namespace node's expanded-name is the prefix associated with that namespace; if there is no prefix (in the case of elements and attributes in the default namespace), this local-name is an empty string. The namespace URI for a namespace node is always null. In the sample document, which declares three namespaces in the root element, all elements thus have three namespace nodes associated with them (counting the namespace implicitly associated with the built-in <tt>xml</tt>: prefix); their expanded names are, respectively, <tt>book</tt>, <tt>xlink</tt>, <tt>xml</tt>, and an empty string.
</div>

=== String Functions ===

The set of XPath functions that operate on string arguments and/or return strings is extensive. Used in XSLT stylesheets, these functions give you enormous flexibility in terms of generating new content based on content in the source tree. In XPointers, you'll find yourself using them most often in the predicate of XPath location steps.

Examples in this section all assume that the following XML document is being navigated via XPath:

<nowiki><dated_relics xmlns="http://mynamespace">
<relic>
<name>Smurf</name>
<price currency="USD">9.00</price>
</relic>
<relic>
<name>lava lamp</name>
<price currency="GBP">39.95</price>
</relic>
<relic>
<name>beanbag chair</name>
<price currency="EU">70.75</price>
</relic>
<relic>
<name>love bead bracelet</name>
<price currency="GBP">.37</price>
</relic>
<relic>
<name>blacklight</name>
<price currency="USD">323.65</price>
</relic>
<relic>
<name>VW mini-bus</name>
<price currency="USD">8500.00</price>
</relic>
<relic>
<name>open-hand chair</name>
<price currency="JPY">16865.78</price>
</relic>
</dated_relics></nowiki>

[[XPath and XPointer/XPath Functions and Numeric Operators#xpathpointer-CHP-4-TABLE-2|Table 4-2]] summarizes the XPath string functions. A detailed discussion of each follows the table.

<div id="xpathpointer-CHP-4-TABLE-2">
'''Table 4-2. String functions'''

{| border="1"
|-
! Function prototype !! Returns !! Description
|-
|

string(anytype?)
| String || Returns the value of the <tt>anytype</tt> argument converted to a string
|-
|

concat(string1, string2, ...)
| String || Concatenates the values of the passed arguments into a single string and returns that string's value
|-
|

starts-with(string1, string2)
| boolean || Returns true if <tt>string1</tt> begins with <tt>string2</tt>, false otherwise
|-
|

contains(string1, string2)
| boolean || Returns true if <tt>string1</tt> contains <tt>string2</tt>, false otherwise
|-
|

substring(string, number1, number2?)
| String || Returns the portion of <tt>string</tt> starting at character <tt>number1</tt>, for a length of <tt>number2</tt> characters
|-
|

substring-before(string1, string2)
| String || Returns the portion of <tt>string1</tt> occurring before <tt>string2</tt>
|-
|

substring-after(string1, string2)
| String || Returns the portion of <tt>string1</tt> following <tt>string2</tt>
|-
|

string-length(string?)
| Number || Returns the number of characters in <tt>string</tt>
|-
|

normalize-space(string?)
| String || Returns the whitespace-normalized value of <tt>string</tt> (that is, stripped of leading and trailing spaces, with multiple consecutive occurrences of whitespace replaced by a single space)
|-
|

translate(string1, string2, string3)
| String || Replaces individual characters appearing in both <tt>string1</tt> and <tt>string2</tt> with corresponding characters in <tt>string3</tt>
|}
</div>

==== string(anytype?) ====

As you might guess from its name, the <tt>string( )</tt> function converts the optional argument to a string of characters. There's a set of rules for the way in which this conversion takes place, dependent on the data type of the argument:

'''''When anytype is a node-set.''''' When the argument is a node-set (for example, one returned by a location path), <tt>string( )</tt> returns the string-value of the first node in the node-set. If the indicated node-set is empty, the returned value is an empty string. If the argument is missing, it defaults to a node-set whose only member is the context node at the point of the call to <tt>string( )</tt>.

'''''When anytype is a number.''''' If you pass <tt>string( )</tt> an integer numeric argument, results are pretty much what you'd expect: you get back the number in the form of a string (e.g., "365" instead of 365). A fixed- or floating-point number is converted to a string including a decimal point, at least one number to the left and one to the right of the decimal point, and an optional minus sign (for negative numbers only, obviously). The spec says that the number of trailing zeros in the latter case will always be sufficient only to distinguish the number from all other legal (IEEE 754) numeric values.

Refer back to the sample XML document. Passing <tt>string( )</tt> the value of a <tt>price</tt> element should produce different results, depending on the <tt>price</tt> element. Consider:

string(number(price))

Here, the price of a Smurf should be returned as the string "9" (no leading or trailing zeros, because none are needed to distinguish this or any other integer from all other legal numeric values), the price of a love bead bracelet as the string "0.37" (including a leading zero), and the price of any of the other relics in the document as simply the string-value of the element's text node (e.g., the string "39.95" for the lava lamp).

Any form of the number 0, including positive and negative 0, is converted to the string "0." Positive infinity<ref>Which I think of as one more than a gazillion.</ref> is represented as the string "Infinity"; negative infinity is represented the same way, prepended with a minus sign: "-Infinity."

You may encounter one other oddball condition when passing <tt>string( )</tt> a numeric argument, which arises when the argument is only ''supposedly'' a number, but for one reason or another is not. As mentioned in [[XPath and XPointer/XPath Basics|Chapter 2]] in the discussion of data types, XPath represents a number-that-isn't-a-number with the special value, <tt>NaN</tt>; if <tt>NaN</tt> (either literally or as the result of some calculation or function call) is passed to <tt>string( )</tt>, the returned value is the ''string'' "NaN."

<div class="tip">
'''Tip'''

The XPath Recommendation points out that passing numeric values to the <tt>string( )</tt> function is not intended to solve the general problem of formatting numbers as strings — for example, grouping every three positions with commas, forcing specific numbers of leading zeros, and so on. If you're using XSLT, you can do all this with the <tt>format-number( )</tt> function and the <tt>xsl:number</tt> element.
</div>

'''''When anytype is a Boolean.''''' A Boolean argument to <tt>string( )</tt> returns either the value "true" or "false," depending on the value of the argument.

'''''When anytype is a string.''''' A string argument passed to <tt>string( )</tt> returns the same string.

'''''When anytype is any other data type.''''' In a burst of involuted prose, the XPath spec says, "An object of a type other than the four basic types is converted to a string in a way that is dependent on that type." Let's see, the data types allowed under XPath are string, numeric, node-set, Boolean, and, uh....

This clause has been added to future-proof XPath against the introduction of new data types. In theory, the specifier (W3C or otherwise) of such a new data type would be obliged to provide some statement of how its values are to be represented as strings: how to derive their string-values, in short.

For instance, some future version of XPath (or an XPath-aware spec) might include a currency data type. This hypothetical spec might then say something like, "When represented as a string, values of the currency data type will include at least one integer (possibly 0) to the left of the decimal point, the decimal point itself, and at least a two-digit integer to the right of the decimal point, preceded by an optional minus sign and preceded or followed by an optional currency symbol." And there would be your definition of how to expect <tt>string( )</tt> to behave when passed a currency value.

(How, exactly, an XPath function such as <tt>string( )</tt> is to know all these outside-of-XPath data conversion rules is a tricky question wisely sidestepped by the XPath spec.)

==== concat(string1, string2, ...) ====

The <tt>concat( )</tt> function takes at least two arguments and forges them into a single string. The function provides no padding with whitespace, so if you're constructing (say) a list of tokens, or a set of words into a phrase or sentence, you've got to include the " " characters and perhaps punctuation separating one from the other. For instance, assume that the context node at a given point is any of the <tt>relic</tt> elements in the sample XML document. Then:

concat(price, " (", price/@currency, ")")

builds a string consisting of that relic's price, a space an opening parenthesis, the currency in which the price is represented, and a closing parenthesis. Given our sample document, for the seven relics in question, this would yield the strings (respectively):

9.00 (USD)<br/>39.95 (GBP)<br/>70.75 (EU)<br/>.37 (GBP)<br/>323.65 (USD)<br/>8500.00 (USD)

Note that the figures 9.00, .37, and 8500.00 do not follow the rules outlined above for representing numeric values as strings. If for some reason you want to force this representation, you need to explicitly convert the <tt>price</tt> element nodes' string-values to numbers (using the <tt>number( )</tt> function discussed later), pass this result to <tt>string( )</tt>, and finally, pass that function's result to <tt>concat( )</tt> as its first argument. Like this:

concat('''string(number(price))''', " (",
price/@currency, ")")

Also note in this case that the call to <tt>string( )</tt> is optional. Because <tt>concat( )</tt> expects a string-type argument, it does any necessary conversion automatically.

Earlier in this chapter, in the discussion of name-related node-set functions, I mentioned that the <tt>concat( )</tt> function could be used to build an expanded-name for a given element. Following the logic of James Clark's algorithm for this process, you can build an expanded-name for a given name using:

concat(namespace-uri(''node''), "+", local-name(''node''))

Thus, if <tt>node</tt> is a <tt>relic</tt> element from our sample XML document, the function call returns the string "http://mynamespace+relic."

==== starts-with(string1, string2) ====

The <tt>starts-with( )</tt> function takes two arguments, returning either the Boolean value true if the first argument starts with the value of the second, or false otherwise.

Returning Boolean values makes <tt>starts-with()</tt> useful primarily in a location step's predicate. Thus:

//price[starts-with(., ".")]

selects all the <tt>price</tt> elements whose string-values start with decimal points (i.e., no leading zeros or other digits). For our sample document, the resulting node-set consists of a single <tt>price</tt> element: the one for the love bead bracelet, with a string-value of ".37."

==== contains(string1, string2) ====

Like <tt>starts-with( )</tt>, the <tt>contains( )</tt> function returns a Boolean true or false and, hence, is most commonly used in a predicate. And it too takes two arguments. The value returned by the function is true if the first argument contains the second, or false otherwise.

In our sample document, we could extract a node-set consisting of all relics that are chairs using a location path such as:

//relic[contains(name, "chair")]

This would locate a two-node node-set: the <tt>relic</tt> node representing a beanbag chair and the <tt>relic</tt> node representing an open-hand chair.

==== substring(string, number1, number2?) ====

Like most programming languages, XPath provides a <tt>substring( )</tt> function for extracting a portion of a larger string. (Some languages, notably those derived from BASIC, call this the <tt>mid( )</tt> function instead.) It takes at least two arguments: the larger string from which you want to select a portion and the starting point for the selection. A third optional argument can specify the number of characters to be extracted; if this argument isn't supplied, the extraction starts at character <tt>number1</tt> and goes to the end of first string.

<div class="note">
'''Note'''

If you're coming to XPath from a programming language that uses 0-based indexing (such as Java), in which the first item is #0, the second #1, and so on, be aware that XPath is 1-based: the first item is #1, and so on. That is, to select the first character of a string, use:

substring(''string'', '''1''', 1)

not:

substring(''string'', '''0''', 1)
</div>

What happens when the number passed as the third argument exceeds the length of the string in question? This is not an error; the function behaves as though you hadn't passed a third argument at all. If the value of the ''second'' argument is greater than the length of the string, you'll get back an empty string as a result.

One way in which I occasionally use the <tt>substring( )</tt> function is during testing of an XSLT stylesheet. At this point, I really don't care to see the complete contents of text nodes, particularly lengthy ones. All I care to see is that the correct text nodes are showing up in the right places. So I use <tt>substring( )</tt> to return, say, just the first five characters of a text node, with an ellipsis ( <tt>. . .</tt> ) appended. Something like this:

concat(substring(node, 1, 5), "...")

Given the sample XML document used in this section, when iterating through a node-set consisting of all the <tt>name</tt> elements, this returns a series of substrings such as the following:

Smurf...<br/>lava ...<br/>beanb...<br/>love ...<br/>black...<br/>VW mi...<br/>open-...

==== substring-before(string1, string2) and substring-after(string1, string2) ====

These two functions work very similarly. They each take two arguments: a string from which you want a portion of text extracted and a string where you want the extraction terminated or begun, respectively. In either case, the <tt>string2</tt> argument doesn't appear in the result returned by the function; it's simply used as a breakpoint. If <tt>string2</tt> doesn't appear in <tt>string1</tt> at all, the function returns an empty string.

Consider a check-writing application using the values of the <tt>price</tt> elements from this section's sample XML document. Such an application takes a number such as "12.34" (assuming that what is represented is in U.S. dollars) and converts it to a phrase like "12 dollars and 34 cents." You could use the decimal point in the <tt>price</tt> element as the <tt>string2</tt> breakpoint for calling both <tt>substring-before( )</tt> and <tt>substring-after( )</tt>, like this:

concat(substring-before(price, "."), " dollars and ",
substring-after(price, "."), " cents")

This would naturally have to be tweaked in various ways to be perfectly workable. You'd have to come up with alternative phrasing for non-U.S. currency and also provide for the likelihood that a given price (such as that of the love beads) lacks anything at all to the left of its decimal point. But as a demonstration of the two functions in action, it works just fine.

==== string-length(string?) ====

Given a passed string argument, the <tt>string-length( )</tt> function returns the number of characters it contains. If no argument is passed, the function operates on the context node's string-value.

This function is sometimes directly useful in its own right. For example, you can use it to tell you whether one string is longer than another (apply it to the two strings and compare the two values returned). More often, though, you'll see <tt>string-length( )</tt> used as an argument passed to another function — or the values returned by other functions as arguments passed to ''it''. For instance:

string-length(substring-before(price, "."))

This returns the number of digits to the left of the decimal point in a <tt>price</tt> element's string-value, which might be useful information in formatting the number a certain way.

==== normalize-space(string?) ====

If you've spent any time at all poking around XML-related specifications, you've probably come across the verb "normalize" and its variants. The issue here is that an XML parser is required to preserve whitespace found in a source document — to pass it unchanged to a downstream application. To normalize content is to remove extraneous whitespace — to trim leading and trailing whitespace from strings (such as text nodes) and replace multiple successive occurrences of whitespace ''within'' a string with a single blank space.

That's what the <tt>normalize-space( )</tt> function does, cleaning up the extraneous whitespace in a string so that what's left is "pure content." Why would you want to do this? Because if the text content of a document has been hand-entered, you want to be sure that no extra space has crept in as a result of keyboard errors. This extra space can make comparing one string-value to another fail, even when the two nodes are apparently identical. For instance:

item1

and:

item1

are not "equal," although they may appear so to a casual human observer; the second <tt>item1</tt> is preceded and followed by newlines. That is, their ''normalized'' values — as returned by <tt>normalize-space( )</tt>, say — are equal, but their "raw" values are not.

Note that fixing up extraneous whitespace within a string isn't the same as removing whitespace-only text nodes. Needing to do ''that'' isn't necessarily a problem in its own right, but can be a very big problem in XSLT applications, where the extra text nodes can play havoc with operations, such as processing even-numbered nodes one way and odd-numbered nodes a different way. This is such a big issue in XSLT that the specification includes some of its own facilities for handling such text nodes. For example, there are both <tt>xsl:strip-space</tt> and <tt>xsl:preserve-space</tt> elements for identifying the whitespace-only text nodes you want collapsed or preserved, respectively.

The <tt>normalize-space( )</tt> function addresses this potential problem by ensuring that you're dealing only with the true <tt>#PCDATA</tt> content in a complete document or any of its nodes: pass it a string, get back the normalized result; pass it any other data type, get back the normalized corresponding string-value; and pass it nothing at all to get back the normalized string-value of the context node.

==== translate(string1, string2, string3) ====

The <tt>translate( )</tt> function replaces individual characters in one string with ''different'' individual characters. The <tt>string1</tt> argument is the string whose characters you want to replace; <tt>string2</tt> includes the specific characters in <tt>string1</tt> that you want to replace; and <tt>string3</tt> includes the characters with which you want to replace those <tt>string2</tt> characters. So:

translate("1234567890", "126", "ABX")

replaces each occurrence of any of the single characters "1," "2," or "6," with the single character "A," "B," or "X," respectively. The value returned from this function call would thus be the string "AB2345X7890."

Like <tt>normalize-space( )</tt>, the <tt>translate( )</tt> function can be valuable in ensuring that two strings are equal, especially when their case — upper vs. lower — is possibly different, even though they're otherwise apparently identical. Instead of comparing the two strings directly, compare their case-folded values using <tt>translate( )</tt>. Thus:

translate(somestring,
"abcdefghijklmnopqrstuvwxyz",
"ABCDEFGHIJKLMNOPQRSTUVWXYZ")

Every lowercase "a" in <tt>somestring</tt> is replaced with a capital "A," every "b" with a "B," and so on. Characters in <tt>somestring</tt> that don't match any characters in <tt>string2</tt> appear unchanged in the result.

Note that the lengths of <tt>string2</tt> and <tt>string3</tt> are usually identical but don't need to be. If <tt>string2</tt> is longer than <tt>string3</tt>, <tt>translate( )</tt> serves to ''remove'' characters from <tt>string1</tt>. So:

translate(somestring,
"abcdefghijklmnopqrstuvwxyz",
"")

removes from <tt>somestring</tt> all lowercase letters, while:

translate(somestring,
"abcdefghijklmnopqrstuvwxyz",
"ABCDEFGHIJKLM")

uppercases all lowercase letters in <tt>somestring</tt> in the first half of the alphabet and removes all those appearing in the second half. If <tt>somestring</tt> is "VW mini-bus," this returns the string "VW MII-B": the uppercase letters "VW" (uppercase letters don't appear in <tt>string2</tt>, so they're passed unchanged), a space, the uppercased "mi" and "i" from "mini," the hyphen, and the uppercased "b" from "bus." The "n" in "mini" and the "us" in "bus" are suppressed.

If for some reason it's desirable, <tt>string3</tt> may be longer than <tt>string2</tt>. This is not necessary, because the function considers only those characters in <tt>string3</tt> up to the length of <tt>string2</tt>; it's just like you omitted those characters from <tt>string3</tt> in the first place.

One interesting use of <tt>translate( )</tt>, in conjunction with <tt>normalize-space( )</tt>, is to "depunctuate" a string. Thus, you can turn the string "Eek!!! Is that a mouse, or what?" into "Eek Is that a mouse or what" using:

normalize-space(translate("Eek!!! Is that a mouse, or what?", "!,?",
" "))

Here, the <tt>translate( )</tt> function itself replaces each occurrence of the exclamation mark, comma, and question mark characters with a blank space; the outer call to <tt>normalize-space( )</tt> then squashes all the resulting multiple blank spaces between words into one. (If you need to do this, be sure that the length of <tt>string3</tt> — the blank spaces — matches the number of characters in <tt>string2</tt> exactly.)

While <tt>translate( )</tt> can be useful for limited cases, it's not really a good general-purpose "search-and-replace" tool — particularly because you can use it only to do single-character matches and replacements. If you need to replace a single character with two or more characters, two or more characters with a single one, or two or more characters with a different set of characters — or a word or phrase with an entirely different one — <tt>translate( )</tt> won't help much, if at all.

In this case, you'll have to do more exotic string manipulation, perhaps with XSLT or a programming language.

=== Boolean Functions ===

As the term implies, the XPath Boolean functions all return Boolean true or false values. (And when you hear the word Boolean in an XPath context, a little flag should go up in your head as you think, "Predicate." Hold that thought.)

These functions are all quite simple, with few little gotchas or complications. Thus, I don't think it's necessary to provide a sample XML document for them. But following [[XPath and XPointer/XPath Functions and Numeric Operators#xpathpointer-CHP-4-TABLE-3|Table 4-3]], which summarizes the Boolean functions, I will provide discussion and examples of each.

<div id="xpathpointer-CHP-4-TABLE-3">
'''Table 4-3. Boolean functions'''

{| border="1"
|-
! Function prototype !! Returns !! Description
|-
|

boolean(anytype)
| boolean || Converts <tt>anytype</tt> to a Boolean true or false value
|-
|

not(boolean)
| boolean || Returns true if <tt>boolean</tt> is false, and false if <tt>boolean</tt> is true
|-
|

true( )
| boolean || Returns the value true
|-
|

false( )
| boolean || Returns the value false
|-
|

lang(string)
| boolean || Returns true or false, depending on whether the language in which the context node is presented matches the value of the <tt>string</tt> argument
|}
</div>

==== boolean(anytype) ====

The <tt>boolean( )</tt> function is similar to the <tt>string( )</tt> function introduced in the last section: it examines the argument passed to it and returns a value (true or false) depending on the argument's value and data type. Also like the <tt>string( )</tt> function, you will almost never need to use <tt>boolean( )</tt> explicitly: in contexts (particularly predicates) where a logical true or false is expected, the <tt>anytype</tt> argument will be converted implicitly, according to the type (string, numeric, node-set, or Boolean) of the argument. Thus, each of the following subsections describes these implicit conversions as well as the result of explicit calls to <tt>boolean( )</tt>.

'''''When anytype is a string.''''' If <tt>anytype</tt> is at least one character long, the call to <tt>boolean( )</tt> returns true; otherwise, it returns false. Thus, the following two XPath expressions are functionally identical (the value true):

boolean("some string")
string-length("some-string") > 0

Remember that a text node may consist entirely of whitespace, as discussed earlier. This whitespace may fool the human eye but won't fool the <tt>boolean( )</tt> function; newlines, spaces, tabs, and so on each count as a string with a length greater than 0.

'''''When anytype is numeric.''''' A call to <tt>boolean( )</tt> with a numeric argument returns true if the argument is a legitimate number (i.e., not the special <tt>NaN</tt> value) and does not equal either positive or negative zero.

<div class="sidebar">
'''Positive and Negative Zero?'''

This positive-or-negative-zero business is consistent with Java and other specifications, although it seems to fly in the face of common sense. (After all, isn't a number either positive ''or'' negative ''or'' zero? What does it mean when a number is both positive and zero, or both negative and zero?)

In general, the plain-old number 0 is "positive" (but unsigned) zero. Using this in numeric operations with negative numbers can result in what's called "negative" 0; for instance, -2 times 0 equals "negative zero." The rule is that for multiplication and division, if the operands share the same (perhaps implicit) sign, then the result is positive; otherwise, the result is negative.

In other words, while you may be called upon to know the formal distinction between positive and negative zero, in practice, they're both plain old 0. Also in practice, don't expect to be called upon to know the formal distinction (unless you're taking an exam or writing a spec yourself).
</div>

In discussing the behavior of <tt>boolean( )</tt> with a string argument, I showed you two expressions that produced the same result. To these two we can now add a third:

boolean(string-length("some string"))

The nested call to <tt>string-length( )</tt> returns a number, which is then passed to <tt>boolean( )</tt>. If the number passed is 0 — that is, if the string is empty — <tt>boolean( )</tt> returns false, otherwise true.

'''''When anytype is a node-set.''''' You already know, from the previous chapter, that you can use a location path in a predicate to test for a particular node's existence. For example:

//employee[emp_address]

selects only those <tt>employee</tt> elements that have at least one <tt>emp_address</tt> child.

This form of the predicate is essentially a shortcut for using the <tt>boolean( )</tt> function with a node-set argument. It returns true if the node-set has at least one member, or false otherwise. That is, the following is equivalent to the short form just presented:

//employee[boolean(emp_address)]

'''''When anytype is a Boolean value.''''' If <tt>anytype</tt> is itself a Boolean value, the value returned by <tt>boolean( )</tt> is identical to the value of <tt>anytype</tt> itself. If <tt>anytype</tt> is true, <tt>boolean( )</tt> returns true; if false, it returns false.

==== not(boolean) ====

The <tt>not( )</tt> function simply flips the value of its passed argument. If the value of <tt>boolean</tt> is true, <tt>not( )</tt> returns false and vice versa.

This function is rarely useful in its own right; rather, you pass as an argument some other expression returning a true or false value, enabling <tt>not( )</tt> to test for the negation of the other expression's value. So you can select all <tt>employee</tt> elements that do ''not'' have at least one <tt>emp_address</tt> child using an expression such as:

//employee[not(emp_address)]

Many comparison operations in XPath look and behave peculiarly, and a particular trap to watch out for when using <tt>not( )</tt> is how it behaves differently from the <tt>!</tt> (exclamation point) Boolean operator in comparisons. Consider the following two location paths:

//employee[@id != "emp1002"]
//employee[not(@id = "emp1002")]

The first example selects all <tt>employee</tt> element nodes whose <tt>id</tt> attributes' values do not equal <tt>emp1002</tt> (or that do not have an <tt>id</tt> attribute at all); the second selects all <tt>employee</tt> element nodes that do not have an <tt>id</tt> attribute whose value is <tt>emp1002</tt>. If you read those two clauses carefully, you'll realize that the two location paths produce different results when encountering an element such as:

<employee>...</employee>

This <tt>employee</tt> element ''will not'' be located by the first example, because it has no <tt>id</tt> attribute at all; it ''will'' be located by the second example, though, because it has no <tt>id</tt> attribute with a value of <tt>emp1002</tt>.

==== true() and false( ) ====

These two Boolean functions are of rather limited utility. You pass them no arguments, and they always return the Boolean value corresponding to their names: <tt>true( )</tt> always returns the value true, and <tt>false( )</tt> always returns false. I've found them useful in making explicit — documenting, as it were — the purpose of some other Boolean test. Something like this:

//book/title[contains(., "XML") = true( )]

selects a <tt>book</tt> element only if the string-value of its <tt>title</tt> child contains the string "XML." Including the <tt>= true( )</tt> doesn't change the test at all, it simply clarifies what you're testing for.

Maybe the most common use of <tt>true( )</tt> and <tt>false( )</tt>, though, is in XSLT. While I don't want to plunge further here into the details of that language, it's possible to build XSLT-based "subroutines" called ''named templates''. You can pass parameters to a named template in a manner similar to passing arguments to a function; if the named template is driven by parameters whose values it expects to be true or false, the simplest way to pass it either of those values is with the <tt>true( )</tt> or <tt>false( )</tt> function.

==== lang(string) ====

Use of this function depends on the use of an <tt>xml:lang</tt> attribute (either directly, in an instance document, or indirectly, via its DTD). If there is no such attribute in scope at the point of the call to <tt>lang( )</tt>, the function returns false.

However, if there is such an attribute in scope, <tt>lang( )</tt> returns true if the context node is "in" the language specified by the string argument passed to it. Consider this code fragment:

<word xml:lang="EN">tarradiddle</word>

Assuming that this element or its text-node child is the context node, the following function call returns true:

lang("EN")

More subtly, <tt>lang( )</tt> also returns true in a case-''in''sensitive way; you could also use:

lang("en")
lang("En")

and so on, all of which would return true.

Now, the language codes the <tt>xml:lang</tt> attribute uses needn't specify major languages only, such as "EN" for English or "DE" for German. They can also specify sublanguages, or language groups, using a hyphen to separate the major language code from the one for the sublanguage. English, for example, can be represented as American English or British English using <tt>xml:lang</tt> values such as "en-us" and "en-uk." Suppose the code fragment above specified an <tt>xml:lang</tt> attribute as follows:

<word xml:lang="EN-UK">tarradiddle</word>

In this case, both of the following would return true:

lang("EN")
lang("en-uk")

The inverse is ''not'' true. Whether <tt>lang( )</tt> returns true or false, according to the spec, depends on whether the <tt>xml:lang</tt> value in force for the context node "is the same as or is a sublanguage of the language specified by the argument string." Thus, if you pass <tt>lang( )</tt> a string that itself identifies a sublanguage, <tt>lang( )</tt> will ''not'' return true when the <tt>xml:lang</tt> value in force is a major language. That is:

lang("en-uk")

returns false when applied to the following code fragment:

<word xml:lang="EN">tarradiddle</word>

=== Numeric Functions ===

Numeric functions operate on their arguments to produce numeric results. [[XPath and XPointer/XPath Functions and Numeric Operators#xpathpointer-CHP-4-TABLE-4|Table 4-4]] summarizes these functions; each is discussed separately following the table.

Examples in this section refer to the following simple XML document:

<weights>
<weight label="1kg">1</weight>
<weight label="2.5kg">2.5</weight>
<weight label="1ton">1016.0469</weight>
</weights>

<div id="xpathpointer-CHP-4-TABLE-4">
'''Table 4-4. Numeric functions'''

{| border="1"
|-
! Function prototype !! Returns !! Description
|-
|

number(anytype?)
| Number || Converts <tt>anytype</tt> to numeric value
|-
|

sum(nodeset)
| Number || Returns the sum of all nodes in <tt>nodeset</tt>, after converting each to a number
|-
|

floor(number)
| Number || Returns the largest integer that is less than or equal to <tt>number</tt>
|-
|

ceiling(number)
| Number || Returns the smallest integer that is greater than or equal to <tt>number</tt>
|-
|

round(number)
| Number || Returns the integer nearest in value to <tt>number</tt> (rounds up if number has a decimal portion of .5)
|}
</div>

==== number(anytype?) ====

Like the <tt>string( )</tt> and <tt>boolean( )</tt> functions discussed earlier, <tt>number( )</tt> converts an optional argument to some basic XPath data type — numeric, in this case — based on the data type of the passed argument. If no argument is supplied, the function by default converts the context node's string-value to a number.

'''''When anytype is a string.''''' To be converted to a number, a string argument must consist of optional whitespace, followed by an optional minus sign (<tt>-</tt>), followed by the numeric value itself, followed by optional whitespace. Any other kind of string is converted to the special value <tt>NaN</tt>. Note in particular that the string may not include a leading plus sign (<tt>+</tt>) or formatting characters, such as grouping commas or currency symbols. Among other effects, this also causes "strings" expressing numbers as scientific notation (such as "3.296E3") to be converted to <tt>NaN</tt>.

'''''When anytype is a Boolean value.''''' If the Boolean value is true, the value returned by <tt>number( )</tt> is 1; if false, <tt>number( )</tt> returns 0. Thus, in this location step:

weight[number(contains(@label, "kg"))]

<tt>number( )</tt> returns 1 for both the first and second <tt>weight</tt> elements, and 0 for the third.

'''''When anytype is a node-set.''''' In this case, the argument is first converted to a string as if it had been passed to the <tt>string( )</tt> function discussed earlier in this chapter, and then converted to a number according to the rules for converting strings to numbers. This follows common sense; using the sample XML document in this section, for example, this expression:

number((//weight)[3])

first locates the third <tt>weight</tt> element in the document, then returns the numeric value 1016.0469.

'''''When anytype is numeric.''''' Passing the <tt>number( )</tt> function a numeric argument simply returns the value of that argument.

==== sum(nodeset) ====

You can do simple summations across a node-set using the <tt>sum( )</tt> function; just pass it the node-set in question. Each node is first converted to a number using the rules of conversion laid out for the <tt>number( )</tt> function, then the summation is performed. We could sum up the values of all the <tt>weight</tt> elements in the sample document with an expression like:

sum(//weight)

which would return the value 1 + 2.5 + 1016.0469, or 1019.5469.

Be careful when using <tt>sum( )</tt> to ensure that you don't run into a not-a-number wall; it takes only a single node with a non-numeric value to make the sum non-numeric as well. Applied to our sample document, this expression:

sum(//weight/@label)

returns <tt>NaN</tt>, because not all of the <tt>label</tt> attributes in the selected node-set are numeric. (''Any'' node failing the numeric test is sufficient to produce a <tt>NaN</tt> result.)

==== floor(number) and ceiling(number) ====

The <tt>floor( )</tt> and <tt>ceiling( )</tt> functions perform similar operations on their arguments. Both return integers nearest in value to that of the argument. For <tt>floor( )</tt>, the result is the largest integer less than or equal to the argument; for <tt>ceiling( )</tt>, the smallest integer greater than or equal to the argument. So:

floor(//weight[3])

returns 1016, while:

ceiling(//weight[3])

returns 1017.

Note that these are not exactly rounding-down and up functions. Although they consider the fractional part of the passed argument, they simply check that it's greater than 0. If so, <tt>floor( )</tt> returns the integer portion of the argument and <tt>ceiling( )</tt>, the integer portion plus 1. If not, <tt>floor( )</tt> and <tt>ceiling( )</tt> both return the same result: the integer portion of the argument.

Be careful when using <tt>floor( )</tt> and <tt>ceiling( )</tt> with negative arguments. A function call like:

floor(3.2)

returns 3, but:

floor(-3.2)

returns -4.

==== round(number) ====

Unlike <tt>floor( )</tt> and <tt>ceiling( )</tt>, <tt>round( )</tt> rounds the argument up or down, depending on which direction the nearest integer lies. Thus, the result will always be identical to that of either <tt>floor( )</tt> or <tt>ceiling( )</tt>:

round(//weight[3])

returns 1016, for example (the same result obtained using <tt>floor( )</tt>).

If the fractional part of the passed argument is exactly .5, the <tt>round( )</tt> function rounds up, consistent with common use (and therefore always behaving just like <tt>ceiling( )</tt>). So:

round(//weight[2])

returns 3.

As with <tt>floor( )</tt> and <tt>ceiling( )</tt>, <tt>round( )</tt> can produce unexpected effects when passed a negative argument. (At least, they're unexpected until you think a little about them.)

The calls:

round(-3.4)
round(-3.5)
round(-3.8)

Return the values -3, -3, and -4, respectively.

== XPath Numeric Operators ==

XPath includes a set of numeric operators for performing basic arithmetic operations. Don't go looking for net-present-value or square-root operators; they don't exist. But if you simply need to add, subtract, multiply, divide, or find a remainder of two numeric values, here's your answer. [[XPath and XPointer/XPath Functions and Numeric Operators#xpathpointer-CHP-4-TABLE-5|Table 4-5]] summarizes these numeric operators.

<div id="xpathpointer-CHP-4-TABLE-5">
'''Table 4-5. XPath numeric operators'''

{| border="1"
|-
! Operator !! Description !! Example
|-
|

+
| Adds two values ||

(//weight)[1] + (//weight)[2]
|-
|

-
| Subtracts one value from another ||

(//weight)[3] - (//weight)[1]
|-
|

*
| Multiplies one value times another ||

(//weight)[3] * 5
|-
|

div
| Divides one value by another ||

(//weight)[3] div 1016.0469
|-
|

mod
| Returns the remainder after dividing one value by another ||

(//weight)[3] mod 1016.0469
|}
</div>

Most of these are straightforward, not requiring any further explanation; however, both the <tt>div</tt> and <tt>mod</tt> operators could use bit more explanation.

=== div ===

Why use a special <tt>div</tt> operator at all? Why not just use the more familiar forward slash character, <tt>/</tt>, to divide one value by another?

The answer is that a slash in an XPath expression is already freighted with meaning: it operates as a delimiter between location steps. (A good analogy, in XML terms, might be the required use of entity references, such as <tt>&lt;</tt> instead of the literal <tt><</tt> character.)

=== mod ===

Unlike <tt>div</tt>, the <tt>mod</tt> operator is common in other application languages as well as in XPath. The term "mod" comes from modulus or modulo — the formal arithmetic term for the remainder following a division. (Some languages use a single character, like the percent sign, <tt>%</tt>, to perform the same operation.)

I promised, earlier in this chapter, to show you how to use <tt>mod</tt> with the <tt>position( )</tt> function to process every ''n''th node in a given node-set.

The basic idea is first to isolate what ''n'' is, then compare the remainder of dividing a given node's position in the node-set by ''n''. If the remainder is 0, the node in question gets the special "every nth node" processing, otherwise it doesn't.

Suppose we have a list of employees in an XML document, coded something like this (irrelevant details omitted):

<employees>
<employee>...</employee>
<employee>...</employee>
<employee>...</employee>
<employee>...</employee>
<employee>...</employee>
<employee>...</employee>
</employees>

As you can see, this document includes six <tt>employee</tt> elements within the <tt>employees</tt> container element. If we want to perform some particular operation just for the <tt>employee</tt> elements in even-numbered positions within the node-set, we could use an XPath expression such as:

//employee[position( ) mod 2 = 0]

If we want this operation to occur on every odd-numbered employee in the list, we change the predicate as in this example:

//employee[position( ) mod 2 = 1]

If we want to select every third employee, change the 2 in the above examples to 3; for every fourth, change it to 4; and so on.

The <tt>mod( )</tt> function is also useful for certain conversion-type operations, such as converting raw quantities of something to dozens-of-something-plus-leftover-units and four-digit years to their two-digit values. For instance:

1960 mod 100

returns the value 60.
== Notes ==

<references/>

XPath and XPointer/XPath Functions and Numeric Operators - Revision history

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki: Initial conversion from Docbook