XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (520 page)

Summary

This chapter described the syntax and meanings of patterns, whose main use in an XSLT stylesheet is to define which template rules apply to which nodes in the source document, but which are also used in the

,

, and

elements.

Patterns, although their syntax is a subset of that for XPath expressions, are evaluated in a different way from expressions, though we saw that the formal rules express the meaning of a pattern in terms of the corresponding expression.

The next chapter describes the library of standard functions that can be used within XPath expressions in a stylesheet.

Chapter 13

The Function Library

This chapter describes all the standard functions included in the XSLT 2.0 and XPath 2.0 specifications for use in XPath expressions. Most of these functions are defined in the W3 C specification
XPath 2.0 and XQuery 1.0 Functions and Operators
, and these should be available in all XPath 2.0 implementations. Others, marked as XSLT-only, are defined in the XSLT 2.0 specification, and are available only in XPath expressions used within an XSLT stylesheet.

For each function, I give its name, a brief description of its purpose, a list of the arguments it expects and the value it returns, the formal rules defining what the function does, and finally usage advice and examples.

These are not the only functions you can call from an XPath expression:

• So-called
  constructor functions
  are available, corresponding to built-in and user-defined atomic types. For example, there is a function called
  xs:float()
  to create values of type
  xs:float
  ,
  xs:date()
  to create values of type
  xs:date
  , and so on. These functions are also available for user-defined atomic types. They are described in Chapter 11.
  
• User-defined functions can be created using the XSLT
  
  declaration; these functions are available for calling from XPath expressions in the stylesheet.
  
• Vendor-defined functions may be available. These will be in a namespace controlled by the vendor of the particular product.
  
• It may be possible to call functions written in external languages such as Java, JavaScript, or C#. See Chapter 16 for details.
  
• When XPath is used within another host language, additional functions may be defined. For example, the XForms specification uses XPath and defines a number of XForms-specific functions for use in that environment.
  

The syntax of a function call is described in Chapter 7. This defines where a function call can be used in an expression, and where it can't. You can use a function call anywhere that an expression or value can be used, provided that the type of value it returns is appropriate to the context where it used. (Unlike XPath 1.0, this includes the ability to use a function call as a step in a path expression.) Within a function call, the values supplied as arguments can be any XPath expression, subject only to the rules on types (for example, some functions require an argument that is a sequence of nodes). So a function call such as
count(..)
, though it looks strange, is perfectly legal:
..
is a valid XPath expression that returns the parent of the context node (it's described in Chapter 9, on page 623).

I've arranged the functions in alphabetical order (combining the XPath-defined and XSLT-defined functions into a single sequence), so you can find a function quickly if you know what you're looking for. However, in case you only know the general area you are interested in, you may find the classification that follows in the section
Functions by Category
useful. This is followed by a section called
Notation
, which describes the notation used for function specifications in this chapter. The rest of the chapter is taken up with the functions themselves, in alphabetical order.

A Word about Naming

Function names such as
current-dateTime()
seem very strange when you first come across them. Why the mixture of camelCasing and hyphenation? The reason they arise is that XPath 1.0 decided to use hyphenated lower-case names for all functions, while XML Schema decided to use camelCase for the names of built-in types. Wherever the XPath 2.0 function library uses a schema-defined type name as part of a function name, it therefore uses the camelCase type name as a single word within the hyphenated function name.

So it may be madness, but there is method in it!

Throughout this book, I write these function names without a namespace prefix. In fact the functions are defined to be within the namespace
http://www.w3.org/2005/xpath-functions
, which is often referred to using the namespace prefix
fn
. (Earlier drafts of the specification used different namespaces, which you may still encounter). In XSLT this is the default namespace for function names, so you will never need to write them with a namespace prefix. I have therefore omitted the prefix when referring to the names in this book. In the W3 C specifications, however, you will often see the functions referred to by names such as
fn:position()
or
fn:count()
.

Functions by Category

Any attempt to classify functions is bound to be arbitrary, but I'll attempt it anyway. A few functions appear in more than one category. The number after each function is a page reference to the entry where the function is described. Functions marked † are available in XSLT only (that is, they are not available when executing freestanding XPath expressions or in XQuery).

Boolean Functions

boolean()
721,
false()
779,
not()
850,
true()
899.

Numeric Functions

abs()
714,
avg()
718,
ceiling()
723,
floor()
779, †
format-number()
788,
max()
830,
min()
830,
number()
851,
round()
870,
round-half-to-even()
872,
sum()
889.

String Functions

codepoints-to-string()
725,
compare()
727,
concat()
729,
contains()
730,
ends-with()
773,
lower-case()
827,
matches()
828,
normalize-space()
845,
normalize-unicode()
847,
replace()
862,
starts-with()
875,
string()
877,
string-join()
879,
string-length()
880,
string-to-codepoints()
881,
substring()
883,
substring-after()
885,
substring- before()
887,
tokenize()
894,
upper-case()
910.

Date and Time Functions

adjust-date-to-timezone()
715,
adjust-dateTime-to-timezone()
715,
adjust-time-to-timezone()
715,
current-date()
738,
current-dateTime()
738,
current-time()
738,
day-from-date()
744,
day-from-dateTime()
744,
†format-date()
781,
†format-dateTime()
781,
†format-time()
781,
hours-from-dateTime()
800,
hours-from-time()
800,
implicit-timezone()
806,
minutes-from-dateTime()
832,
minutes-from-time()
832,
month-from-date()
833,
month-from-dateTime()
833,
seconds-from-dateTime()
873,
seconds-from-time()
873,
timezone-from-date()
893,
timezone-from-dateTime()
893,
timezone-from-time()
893,
year-from-date()
911,
year-from-dateTime()
911.

Duration Functions

days-from-duration()
745,
hours-from-duration()
801,
minutes-from-duration()
832,
months-from-duration()
834,
seconds-from-duration()
874,
years-from-duration()
911.

Aggregation Functions

avg()
718,
count()
733,
max()
830,
min()
830,
sum()
889.

Functions on URIs

base-uri()
719,
collection()
726,
doc()
750,
doc-available()
750,
document-uri()
764,
encode-for-uri()
771,
escape-html-uri()
775,
iri-to-uri()
811,
resolve-uri()
867,
static-base-uri()
876, †
unparsed-text()
904, †
unparsed-text-available()
904.