The purpose of this document is to catalog the functions and operators required for
XPath 3.0, XQuery 3.0 and XSLT 3.0. The exact syntax used to call these
functions and operators is specified in
This document defines constructor functions and functions that take typed values as
arguments. Some of the functions specify the semantics of operators defined in
xs:dateTimeStamp, and it
incorporates as built-in types the two types xs:yearMonthDuration and xs:dayTimeDuration
which were previously XDM additions to the type system. In addition, XSD 1.1 clarifies and updates many
aspects of the definitions of the existing data types: for example, it extends the value space of
xs:double to allow both positive and negative zero, and extends the lexical space to allow +INF;
it modifies the value space of xs:Name
to permit additional Unicode characters; it allows year zero and disallows leap seconds in xs:dateTime
values; and it allows any character string to appear as the value of an xs:anyURI item.
Implementations of this specification
References to specific sections of some of the above documents are indicated by
cross-document links in this document. Each such link consists of a pointer to a
specific section followed a superscript specifying the linked document. The
superscripts have the following meanings: 'XQ'
The Functions and Operators specification is intended primarily as a
component that can be used by other specifications. Therefore, Functions
and Operators relies on specifications that use it (such as
Authors of conformance criteria for the use of the Functions and Operators should pay particular attention to the following features:
It is
It is
Support for XML 1.0 and XML 1.1 by the datatypes used in Functions and Operators.
The XML Schema 1.1 recommendation
introduces one new concrete data type: xs:dateTimeStamp; it also incorporates
the types xs:dayTimeDuration, xs:yearMonthDuration,
and xs:anyAtomicType which were previously defined as part of xs:NCName
based on the rules in XML 1.1 rather than 1.0.
In this document, text labeled as an example or as a Note is provided for explanatory purposes and is not normative.
The functions and operators defined in this document are contained in one of
several namespaces (see xs:QName.
This document uses conventional prefixes to refer to these namespaces. User-written
applications can choose a different prefix to refer to the namespace, so long as it is
bound to the correct URI. The host language may also define a default namespace for
function calls, in which case function names in that namespace need not be prefixed
at all. In many cases the default namespace will be
http://www.w3.org/2005/xpath-functions, allowing a call on the fn:name
function (for example) to be written as name() rather than fn:name();
in this document, however, all example function calls are explicitly prefixed.
The URIs of the namespaces and the conventional prefixes associated with them are:
http://www.w3.org/2001/XMLSchema for constructors —
associated with xs.
The section http://www.w3.org/2001/XMLSchema,
and are named in this document using the xs prefix.
http://www.w3.org/2005/xpath-functions
for functions — associated with fn.
The namespace
prefix used in this document for most functions that are available to users is
fn.
http://www.w3.org/2005/xpath-functions/math
for functions — associated with math.
This namespace is used for some mathematical functions. The namespace
prefix used in this document for these functions is math.
These functions are available to users in exactly the same way as those in the
fn namespace.
http://www.w3.org/2005/xqt-errors — associated with
err.
There are no functions in this namespace; it is used for error codes.
This document uses the prefix err to represent the namespace URI
http://www.w3.org/2005/xqt-errors, which is the namespace for all XPath
and XQuery error codes and messages. This namespace prefix is not predeclared and
its use in this document is not normative.
The namespace URI associated with the err prefix is not
expected to change from one version of this document to another. The
contents of this namespace may be extended to allow additional errors to be returned.
http://www.w3.org/2010/xslt-xquery-serialization — associated with
output.
There are no functions in this namespace: it is
used for serialization parameters, as described in
Functions defined with the op prefix are described here to
underpin the definitions of the operators in op prefix. For example, multiplication is generally
associated with the * operator, but it is described as a function
in this document:
In general, the specifications named above do not support function overloading
in the sense that functions that have multiple signatures with the same name and
the same number of parameters are not supported. Consequently, there are no such
overloaded functions in this document except for legacy fn:string, which accepts a single parameter of
a variety of types. In addition, it should be noted that the functions defined
in numeric
parameters accept arguments of type xs:integer,
xs:decimal, xs:float or xs:double. See
Each function is defined by specifying its signature, a description of the return type and each of the parameters and its semantics. For many functions, examples are included to illustrate their use.
Each function's signature is presented in a form like this:
In this notation, ()"; otherwise, the name is followed by a parenthesized list of
parameter declarations, each declaration specifies the static type of the
parameter, in italics, and a descriptive, but non-normative, name. If there are
two or more parameter declarations, they are separated by a comma. The return-type
One function, fn:concat, has a variable number of arguments (two or more).
More strictly, there is an infinite set of functions having the name fn:concat, with arity
ranging from 2 to infinity. For this special case, a single function signature is given, with an ellipsis
indicating an indefinite number of arguments.
In some cases the word
is used in function signatures as a shorthand to indicate the four
numeric types: numeric
xs:integer, xs:decimal,
xs:float and xs:double. For example, a function with
the signature:
represents the following four function signatures:
For most functions there is an initial paragraph describing what the function does followed by semantic rules. These rules are meant to be followed in the order that they appear in this document.
In some cases, the static type returned by a function depends on the type(s) of
its argument(s). These special functions are indicated by using
The function name is a QName as defined in fn:timezone-from-dateTime.
Rules for passing parameters to operators are described in the relevant sections
of xs:untypedAtomic and the empty sequence are specified in this section.
As is customary, the parameter type name indicates that the function or operator
accepts arguments of that type, or types derived from it, in that position. This
is called xs:anyURI can be promoted to produce an argument
of the required type. (See
xs:integer may be used
where xs:decimal is expected.
xs:decimal may be
promoted to xs:float or xs:double.
Promotion to xs:double should be done directly, not via
xs:float, to avoid loss of precision.
xs:anyURI can be promoted to the
type xs:string.
Some functions accept a single value or the empty sequence as an argument and
some may return a single value or the empty sequence. This is indicated in the
function signature by following the parameter or return type name with a
question mark: "?", indicating that either a single value or the
empty sequence must appear. See below.
Note that this function signature is different from a signature in which the
parameter is omitted. See, for example, the two signatures
for fn:string. In the first signature, the parameter is omitted
and the argument defaults to the context item, referred to as .
.
In the second signature, the argument must be present but may be the empty
sequence, written as ().
Some functions accept a sequence of zero or more values as an argument. This is
indicated by following the name of the type of the items in the sequence with
*. The sequence may contain zero or more items of the named type.
For example, the function below accepts a sequence of xs:double and
returns a xs:double or the empty sequence.
The diagrams below show how nodes, function items, primitive simple types, and user defined types fit together into a type system. This type system comprises two distinct hierarchies that both include the primitive simple types. In the diagrams, connecting lines represent relationships between derived types and the types from which they are derived; the arrowheads point toward the type from which they are derived. The dashed line represents relationships not present in this diagram, but that appear in one of the other diagrams. Dotted lines represent additional relationships that follow an evident pattern. The information that appears in each diagram is recapitulated in tabular form.
The xs:IDREFS, xs:NMTOKENS, and
xs:ENTITIES types and the user-defined list and union types
are special types in that these types are lists or unions
rather than types derived by extension or restriction.
The first diagram and its corresponding table illustrate
the relationship of various item types. Item types in the data model
form a lattice rather than a hierarchy: in the relationship defined
by the derived-from(A, B) function, some types are derived
from more than one other type. Examples include functions (function(xs:string) as xs:int
is substitutable for function(xs:NCName) as xs:int and also for
function(xs:string) as xs:decimal), and union types (A
is substitutable for union(A, B) and also for union(A, C).
In XDM, item types include node types, function types, and built-in atomic types.
The diagram, which shows only hierarchic relationships, is therefore a simplification of
the full model.
In the table, each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.
| item | |||
| xs:anyAtomicType | |||
| function(*) | |||
| function(item()*) as item()* | |||
| function(item()*) as item() | |||
| function(item()*) as item()? | |||
| function(item()*, item()*) as item()* | |||
| node | |||
| attribute | |||
| user-defined attribute types | |||
| comment | |||
| document | |||
| user-defined document types | |||
| element | |||
| user-defined element types | |||
| namespace | |||
| processing-instruction | |||
| text |
The next diagram and table illustrate the any type
type hierarchy, in which
all types are derived from distinguished type xs:anyType.
In the table, each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.
| xs:anyType | ||
| user-defined complex types | ||
| xs:untyped | ||
| xs:anySimpleType | ||
| user-defined list and union types | ||
| xs:IDREFS | ||
| xs:NMTOKENS | ||
| xs:ENTITIES | ||
| xs:anyAtomicType |
The final diagram and table show all of the atomic types, including the primitive simple types and the
built-in types derived from the primitive simple types.
This includes all the built-in datatypes defined in
In the table, each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.
| xs:untypedAtomic | ||||||
| xs:dateTime | ||||||
| xs:dateTimeStamp | ||||||
| xs:date | ||||||
| xs:time | ||||||
| xs:duration | ||||||
| xs:yearMonthDuration | ||||||
| xs:dayTimeDuration | ||||||
| xs:float | ||||||
| xs:double | ||||||
| xs:decimal | ||||||
| xs:integer | ||||||
| xs:nonPositiveInteger | ||||||
| xs:negativeInteger | ||||||
| xs:long | ||||||
| xs:int | ||||||
| xs:short | ||||||
| xs:byte | ||||||
| xs:nonNegativeInteger | ||||||
| xs:unsignedLong | ||||||
| xs:unsignedInt | ||||||
| xs:unsignedShort | ||||||
| xs:unsignedByte | ||||||
| xs:positiveInteger | ||||||
| xs:gYearMonth | ||||||
| xs:gYear | ||||||
| xs:gMonthDay | ||||||
| xs:gDay | ||||||
| xs:gMonth | ||||||
| xs:string | ||||||
| xs:normalizedString | ||||||
| xs:token | ||||||
| xs:language | ||||||
| xs:NMTOKEN | ||||||
| xs:Name | ||||||
| xs:NCName | ||||||
| xs:ID | ||||||
| xs:IDREF | ||||||
| xs:ENTITY | ||||||
| xs:boolean | ||||||
| xs:base64Binary | ||||||
| xs:hexBinary | ||||||
| xs:anyURI | ||||||
| xs:QName | ||||||
| xs:NOTATION |
When XSD 1.1 is supported, one additional type needs to be added to these
diagrams: the type xs:dateTimeStamp, which is derived from xs:dateTime.
The terminology used to describe the functions and operators on
This document uses the terms string, character, and codepoint
with the following meanings:
This definition excludes Unicode characters in the surrogate blocks as well as xFFFE and xFFFF, while including characters with codepoints greater than xFFFF which some programming languages treat as two characters. The valid characters are defined by their codepoints, and include some whose codepoints have not been assigned by the Unicode consortium to any character.
xs:string data type.
The set of codepoints is thus wider than the set of characters.
This specification spells "codepoint" as one word; the Unicode specification spells
it as "code point".
Equivalent terms found in other specifications are
"character number" or "code position". See
Because these terms appear so frequently, they are hyperlinked to the definition only when there is a particular desire to draw the reader's attention to the definition; the absence of a hyperlink does not mean that the term is being used in some other sense.
It is
Unless explicitly stated, the xs:string values returned by the
functions in this document are not normalized in the sense of
In functions that involve character counting such
as fn:substring, fn:string-length and
fn:translate, what is counted is the number of XML
This document uses the phrase "namespace URI" to identify the concept identified
in
It also uses the term expanded-QName
defined below.
xs:QName. When this document
refers to xs:QName we always mean the value space, i.e.
a namespace URI, local name pair (and not the lexical space
referring to constructs of the form prefix:local-name).
The term URI is used as follows:
xs:anyURI datatype
as defined in
Note that this means, in practice, that where this
specification requires a "URI Reference", an IRI as defined in xs:anyURI is a wider definition than the definition in
A feature of this specification included to ensure that
implementations that use this feature remain compatible with
Conforming documents and processors are permitted to, but need not, behave as described.
Conforming documents and processors are required to behave as described; otherwise, they are either non-conformant or else in error.
Possibly differing between implementations, but specified and documented by the implementor for each particular implementation.
Possibly differing between implementations, but not specified by this or other W3C specification, and not required to be specified by the implementor for any particular implementation.
This section is concerned with the question of whether two calls on a function, with the same arguments, may produce different results.
The following definition explains more precisely what it means for two function calls to return the same result:
Both items are atomic values, of precisely the same type, and the values are equal as defined using the eq operator,
using the Unicode codepoint collation when comparing strings
Both items are nodes, and represent the same node
Both items are function items, and have the same name (or absence of a name), arity, function signature, and closure. (Note that there is no function or operator defined in the specification that tests whether two function items are identical.)
Some functions produce results that depend not only on their explicit arguments, but also on the static and dynamic context.
A function that is context-dependent can be used as a named
function reference, can be partially applied, and can be found using fn:function-lookup.
The principle in such cases is that the static context used for the function evaluation
is taken from the static context of the named function reference, partial function application, or the call
on fn:function-lookup; and the dynamic context for the function evaluation is taken from the dynamic
context of the evaluation of the named function reference, partial function application, or the call
of fn:function-lookup. In effect, the static and dynamic part of the context thus act
as part of the closure of the function item.
Context-dependent functions fall into a number of categories:
The functions fn:current-date, fn:current-dateTime, fn:current-time, fn:implicit-timezone,
fn:adjust-date-to-timezone, fn:adjust-dateTime-to-timezone, and
fn:adjust-time-to-timezone depend on properties of the dynamic context that are
fixed within the op: namespace that manipulate dates and times and
that make use of the implicit timezone. These functions will return the same
result if called repeatedly during a single
A number of functions including fn:base-uri#0, fn:data#0,
fn:document-uri#0, fn:position, fn:last, fn:id#1,
fn:idref#1, fn:element-with-id#1, fn:lang#1, fn:local-name#0,
fn:name#0, fn:namespace-uri#0, fn:normalize-space#0, fn:number#0,
fn:root#0, fn:string#0,
fn:string-length#0, and fn:path#0 depend on the focus. These functions will in general return
different results on different calls if the focus is different.
The function fn:default-collation and many string-handling operators and functions depend
on the default collation and the in-scope collations, which are both properties
of the static context. If a particular call of one of these functions is
evaluated twice with the same arguments then it will return the same result
each time (because the static context, by definition, does not change at run
time). However, two distinct calls (that is, two calls on the function
appearing in different places in the source code) may produce different results
even if the explicit arguments are the same.
Functions such as fn:static-base-uri, fn:doc, and fn:collection depend on
other aspects of the static context. As with functions that depend on
collations, a single call will produce the same results on each call if the
explicit arguments are the same, but two calls appearing in different places in
the source code may produce different results.
The fn:function-lookup function is a special case because it is
potentially dependent on everything in the static and dynamic context. This is because the static and dynamic
context of the call to fn:function-lookup are used as the static and dynamic context of the
function that fn:function-lookup returns.
All functions defined in this specification are
Some functions (such as fn:distinct-values and fn:unordered) produce results in an
The function fn:analyze-string constructs an element node to
represent its results. There is no guarantee that repeated calls with the same
arguments will return the same identical node (in the sense of the is
operator). However, if non-identical nodes are returned, their content will be the
same in the sense of the fn:deep-equal function. Such a function is said
to be
Some functions (such as fn:doc and fn:collection) create new nodes by reading external
documents. Such functions are guaranteed to be
Where the results of a function are described as being (to a greater or lesser
extent)