The purpose of this document is to catalog the functions and operators required for
XPath 3.1, XQuery 3.1, and XSLT 3.0 (at the time of writing, XSLT 3.0 requires support for
version 3.0 of this specification, and makes support for version 3.1 optional).
The exact syntax used to call these
functions and operators is specified in
This document defines three classes of functions:
General purpose functions, available for direct use in user-written queries, stylesheets, and XPath expressions,
whose arguments and results are values defined by the
Constructor functions, used for creating instances of a datatype from values of (in general) a different datatype. These functions are also available for general use; they are named after the datatype that they return, and they always take a single argument.
Functions that 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 datatypes: 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'
This recommendation contains a set of function specifications. It defines conformance at the level of individual functions. An implementation of a function conforms to a function specification in this recommendation if all the following conditions are satisfied:
For all combinations of valid inputs to the function (both explicit arguments and implicit context dependencies), the result of the function meets the mandatory requirements of this specification.
For all invalid inputs to the function, the implementation signals (in some way appropriate to the calling environment) that a dynamic error has occurred.
For a sequence of calls within the same
Other recommendations ("host languages") that reference this document may dictate:
Subsets or supersets of this set of functions to be available in particular environments;
Mechanisms for invoking functions, supplying arguments, initializing the static and dynamic context, receiving results, and handling errors;
A concrete realization of concepts such as
Which versions of other specifications referenced herein (for example, XML, XSD, or Unicode) are to be used.
Any behavior that is discretionary (implementation-defined or implementation-dependent) in this specification may be constrained by a host language.
Adding such constraints in a host language, however, is discouraged because it makes it difficult to re-use implementations of the function library across host languages.
This specification allows flexibility in the choice of versions of specifications on which it depends:
It is
It is
It is
The XML Schema 1.1 recommendation
introduces one new concrete datatype: xs:dateTimeStamp; it also incorporates
the types xs:dayTimeDuration, xs:yearMonthDuration,
and xs:anyAtomicType which were previously defined in earlier versions 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/xpath-functions/map
for functions — associated with map.
This namespace is used for some functions that manipulate maps (see
map.
These functions are available to users in exactly the same way as those in the
fn namespace.
http://www.w3.org/2005/xpath-functions/array
for functions — associated with array.
This namespace is used for some functions that manipulate maps (see
array.
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.
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:
The above namespace URIs are not expected to change from one version of this document to another. The contents of these namespaces may be extended to allow additional functions (and errors, and serialization parameters) to be defined.
A function is uniquely defined by its name and arity (number of arguments); it is therefore
not possible to have two different functions that have the same name and arity, but different
types in their signature. That is, function overloading in this sense of the term is not permitted.
Consequently, functions such as fn:string which accept arguments of many different
types have a signature that defines a very general argument type, in this case item()?
which accepts any single item; supplying an inappropriate item (such as a function item) causes
a dynamic error.
Some functions on numeric types include the type xs:numeric in their signature
as an argument or result type. In this version of the specification, xs:numeric
has been redefined as a built-in union type representing the union of
xs:decimal, xs:float, xs:double (and thus automatically
accepting types derived from these, including xs:integer).
Operators such as "+" may be overloaded: they map to different underlying functions depending on the dynamic types of the supplied operands.
It is possible for two functions to have the same name provided they have different arity (number of arguments). For the functions defined in this specification, where two functions have the same name and different arity, they also have closely related behavior, so they are defined in the same section of this document.
Each function (or group of functions having the same name) is defined in this specification using a standard proforma.
The function name is a QName as defined in math:sin and
math:cos for sine and cosine). If a
function name contains a fn:timezone-from-dateTime.
The first section in the proforma is a short summary of what the function does. This is intended to be informative rather than normative.
Each function is then defined by specifying its signature, which defines the types of the parameters and of the result value.
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, in which 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.
The next section in the proforma defines the semantics of the function as a set of rules.
The order in which the rules appear is significant; they are to be applied in the order in which
they are written. Error conditions, however, are generally listed in a separate section that follows
the main rules, and take precedence over non-error rules except where otherwise stated. The principles outlined
in
Where the proforma includes sections headed
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.
As a matter of convention, a number of functions defined in this document take a parameter whose value is a map, defining options controlling the detail of how the function is evaluated. Maps are a new datatype introduced in XPath 3.1.
For example, the function fn:xml-to-json has an options parameter
allowing specification of whether the output is to be indented. A call might be written:
Where a function adopts the
The value of the relevant argument must be a map. The entries in the map are
referred to as options: the key of the entry is called the option name, and the
associated value is the option value. Option names defined in this specification
are always strings (single xs:string values). Option values may
be of any type.
The type of the options parameter in the function signature is always
given as map(*).
Although option names are described above as strings, the actual key may be
any value that compares equal to the required string (using the eq operator
with Unicode codepoint collation; or equivalently, the op:same-key relation).
For example, instances of xs:untypedAtomic
or xs:anyURI are equally acceptable.
This means that the implementation of the function can check for the
presence and value of particular options using the functions map:contains
and/or map:get.
It is not an error if the options map contains options with names other than those
described in this specification. Implementations xs:QName as the option names, using an appropriate namespace.
All entries in the options map are optional, and supplying an empty map has the same effect as omitting the relevant argument in the function call, assuming this is permitted.
For each named option, the function
specification defines a required type for the option value. The value that is actually
supplied in the map is converted to this required type using the
It is the responsibility of each function implementation to invoke this conversion; it does not happen automatically as a consequence of the function calling rules.
In cases where an option is list-valued, by convention the value may be supplied
either as a sequence or as an array. Accepting a sequence is convenient if the
value is generated programmatically using an XPath expression; while accepting an array
allows the options to be held in an external file in JSON format, to be read using
a call on the fn:json-doc function.
In cases where the value of an option is itself a map, the specification of the particular function must indicate whether or not these rules apply recursively to the contents of that map.
The diagrams in this section show how nodes, functions, primitive simple types, and user defined types fit together into a type system. This type system comprises two distinct subsystems that both include the primitive atomic 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,
xs:ENTITIES types, and xs:numeric and both the
user-defined list types and
user-defined 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 are used to characterize the various types of item that can appear in a sequence (nodes, atomic values, and functions), and they are therefore used in declaring the types of variables or the argument types and result types of functions.
Item types in the data model
form a directed graph, rather than a hierarchy or lattice: 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 | |||
| node | |||
| attribute | |||
| user-defined attribute types | |||
| comment | |||
| document | |||
| user-defined document types | |||
| element | |||
| user-defined element types | |||
| namespace | |||
| processing-instruction | |||
| text | |||
| function(*) | |||
| array(*) | |||
| map(*) |
The next diagram and table illustrate the schema type subsystem, in which
all types are derived from the distinguished type xs:anyType.
Schema types include built-in types defined in the XML Schema specification, and user-defined types defined using mechanisms described in the XML Schema specification. Schema types define the permitted contents of nodes. The main categories are complex types, which define the permitted content of elements, and simple types, which can be used to constrain the values of both elements and attributes.
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 | |||
| xs:anySimpleType | |||
| xs:anyAtomicType | |||
| list types | |||
| xs:IDREFS | |||
| xs:NMTOKENS | |||
| xs:ENTITIES | |||
| user-defined list types | |||
| union types | |||
| xs:numeric | |||
| user-defined union types | |||
| complex types | |||
| xs:untyped | |||
| user-defined complex types |
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
Atomic types are both item types and schema types, so the root type xs:anyAtomicType may be found
in both the previous diagrams.
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 |
The terminology used to describe the functions and operators on types defined in
Following in the tradition of
This document uses the terms string, character, and codepoint
with meanings that are normatively defined in
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 datatype.
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 datatype as defined in the XDM data model
(see
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
In this specification:
The auxiliary verb
When the sentence relates to an implementation of a function (for example "All implementations
When the sentence relates to the result of a function (for example "The result $arg") then the implementation is not conformant unless it delivers a result as stated.
When the sentence relates to the arguments to a function (for example "The value of $arg
The auxiliary verb
The auxiliary verb
Where this specification states that something is implementation-defined or implementation-dependent, it is open to host languages to place further constraints on the behavior.
This section is concerned with the question of whether two calls on a function, with the same arguments, may produce different results.
fn:current-dateTime within the same execution scope will return the same result.
The execution scope is defined by the host language that invokes the function library.use-when attributes, are in a separate execution scope).
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 maps, both maps have the same number of entries,
and for every entry E1 in the first map there is an entry E2 in the second map such
that the keys of E1 and E2 are
Both items are arrays, both arrays have the same number of members, and the members
are pairwise
Both items are function items,
Either both functions have the same name, or both names are
Both functions have the same arity.
Both functions have the same function signature. subtype(S, T) and subtype(T, S)
both hold, where the subtype relation is defined in
Under this definition, a union type with memberTypes="xs:double xs:decimal"
is identical to a union type with memberTypes="xs:decimal xs:double". However, two functions
whose signatures differ in this way will probably be deemed non-identical under rule (e) below, because they are likely to
have different effect when invoked with an argument of type xs:untypedAtomic.
Both functions have the same nonlocal variable bindings (sometimes called the function's closure).
The processor is able to determine that the implementations of the two functions are equivalent, in the sense that for all possible combinations of arguments, the two functions have the same effect.
There is no function or operator defined in the specification that tests whether two function items are identical. Where the specification requires two function items to be identical, for example in the results of repeated calls of a function whose result is a function, then the processor must ensure that it returns functions that are indistinguishable in their observable effect. Where the specification defines behavior conditional on two function items being identical, the determination of identity is to some degree implementation-dependent. There are cases where function items are definitely not identical (for example if they have different name or arity), but positive determination of identity is possible only using implementation-dependent techniques, for example when both items contain references to the same piece of code representing the function's implementation.
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:default-language, 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:element-with-id#1, fn:id#1,
fn:idref#1, fn:lang#1, fn:last#0, fn:local-name#0,
fn:name#0, fn:namespace-uri#0, fn:normalize-space#0,
fn:number#0, fn:path#0, fn:position#0,
fn:root#0, fn:string#0, and
fn:string-length#0 depend on the
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
fn:distinct-values, fn:unordered, map:keys,
and map:for-each
fn:analyze-string,
fn:parse-xml, fn:parse-xml-fragment,fn:json-to-xml) 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)