This document defines constructor functions, operators, and functions on the datatypes defined in
A summary of changes since version 3.1 is provided at
This version of the specification is work in progress. It is produced by the QT4 Working Group, officially
the W3C XSLT 4.0 Extensions Community Group. Individual functions specified in the document may be at
different stages of review, reflected in their
The purpose of this document is to define functions and operators for inclusion in
XPath 4.0, XQuery 4.0, and XSLT 4.0.
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 userwritten 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 builtin 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
crossdocument 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
Despite its title, this document does not attempt to define the semantics of all the operators available
in the x/y
, x!y
, and x[y]
,
as well simple operators such as x,y
, x and y
, x or y
,
x<<y
, x>>y
, x is y
, xy
, xy
,
x union y
, x except y
, x intersect y
, x to y
and x otherwise y
) are now defined entirely within
The remaining operators that are described in this publication are those where the semantics of the operator
depend on the types of the arguments. For these operators, the language specification describes rules for selecting
an internal function defined in this specification to underpin the operator. For example, when the operator x+y
is applied to two operands of type xs:double
, the function op:numericadd
is selected.
XPath defines a range of comparison operators x=y
, x!=y
, x<y
,
x>y
, x<=y
, x>=y
, x eq y
, x ne y
, x lt y
,
x gt y
, x le y
, x ge y
, which apply to a variety of operand types including
for example numeric values, strings, dates and times, and durations. For each relevant data type, two functions
are defined in this specification, for example op:dateequal
and op:datelessthan
.
These define the semantics of the eq
and lt
operators applied to operands of that data type. The operators
x ne y
, x gt y
, x le y
, and x ge y
are defined by reference to
these two; and the =
, !=
, <
,
>
, <=
, and >=
are defined by reference to
eq
, ne
, lt
,
gt
, le
, and ge
respectively.
Previous versions of this specification also defined a third comparison function of the form
op:dategreaterthan
. This has been dropped, as it is always the inverse of the lessthan
form.
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 raises (in some way appropriate to the calling environment) a dynamic error.
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 (implementationdefined or implementationdependent) 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 reuse 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.
The
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. Userwritten
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/xpathfunctions
, 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/xpathfunctions
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/xpathfunctions/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/xpathfunctions/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/xpathfunctions/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/xqterrors
— 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/xqterrors
, 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/xsltxqueryserialization
— 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:
Sometimes there is a need to use an operator as a function.
To meet this requirement, the function fn:op
takes any simple binary operator as its argument,
and returns a corresponding function. So for example fn:foreachpair($seq1, $seq2, op("+"))
performs a pairwise addition of the values in two input sequences.
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 builtin 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 
). Abbreviations are
used only where there is a strong precedent in other programming languages (as with math:sin
and
math:cos
for sine and cosine). If a
function name contains a fn:timezonefromdateTime
.
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(s), which define the types of the parameters and of the result value.
Where functions take a variable number of arguments, two conventions are used:
Wherever possible, a single function signature is used giving default values for those parameters that can be omitted.
If this is not possible, because the effect of omitting a parameter cannot be specified by giving a default value, multiple signatures are given for the function.
Each function signature is presented in a form like this:
In this notation, http://www.w3.org/2005/xpathfunctions
:
this is one of the conventional prefixes listed in ()
; otherwise, the name is followed by a parenthesized list of
parameter declarations. Each parameter declaration includes:
The name of the parameter (which in 4.0 is significant because it can be used as a keyword in a function call)
The static type of the parameter (in italics)
If the parameter is optional, then an expression giving the default value
(preceded by the symbol :=
).
The default value expression is evaluated using the static and
dynamic context of the function caller (or of a named function reference). For example,
if the default value is given as .
, then it evaluates to the context value
from the dynamic context of the function caller; if it is given as defaultcollation
,
then its value is the default collation from the static context of the function caller;
if it is given as deepequal#2
, then the third argument supplied to deepequal
is the default collation from the static context of the caller.
If there are two or more parameter declarations, they are separated by a comma.
The returntype
One function, fn:concat
, has a variable number of arguments (zero or more).
More strictly, there is an infinite set of functions having the name fn:concat
, with arity
ranging from 0 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 nonerror 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 value, 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.
In XPath 4.0, the arguments in a function call can be supplied by
keyword as an alternative to supplying them positionally. For example the call
resolveuri(@href, staticbaseuri())
can now be written
resolveuri(base: staticbaseuri(), relative: @href)
. The order in which
arguments are supplied can therefore differ from the order in which they are declared.
The specification, however, continues to use phrases such as “the second argument” as a
convenient shorthand for "the value of the argument that is bound to the second parameter
declaration".
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:xmltojson
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 fn:atomicequal
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
.
Implementations xs:QName
as the option
names, using an appropriate namespace.
If an option is not described in the specification,
if it is not supported by the implementation and if its name is in no namespace,
a type error
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 functioncalling rules.
In cases where an option is listvalued, 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:jsondoc
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 former are always below and to the right of the latter.
The xs:IDREFS
, xs:NMTOKENS
,
xs:ENTITIES
types, and xs:numeric
and both the
userdefined list types
and
userdefined union types
are special types in that these types are lists or unions
rather than types derived by extension or restriction.
The first diagram illustrates 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
derivedfrom(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 builtin atomic types. The diagram, which shows
only hierarchic relationships, is therefore a simplification of the
full model.
The next diagram illustrate the schema type subsystem, in which
all types are derived from xs:anyType
.
Schema types include builtin types defined in the XML Schema specification, and userdefined 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.
The final diagram shows all of the atomic types, including the primitive simple types and the
builtin types derived from the primitive simple types.
This includes all the builtin 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.
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 functions in this document do not ensure that any
returned xs:string
values are normalized in the sense of
In functions that involve character counting such
as fn:substring
, fn:stringlength
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 expandedQName
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
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 implementationdefined or implementationdependent, 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.
In this section the term
fn:currentdateTime
within the same execution scope will return the same result.
The execution scope is defined by the host language that invokes the function library.usewhen
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:
$V1
and $V2
are
defined to be
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,
neither item is a map or array, and the two function items have the same function identity.
The concept of function identity is explained in
Some functions produce results that depend not only on their explicit arguments, but also on the static and dynamic context.
fn:name#0
is contextdependent
while fn:name#1
is contextindependent.
The main categories of contextdependent functions are:
Functions that explicitly deliver the value of a component of the static or dynamic context,
for example fn:staticbaseuri
, fn:defaultcollation
,
fn:position
, or fn:last
.
Functions with an optional parameter whose default value is taken from the static
or dynamic context of the caller, usually either the context value (for example, fn:nodename
)
or the default collation (for example, fn:indexof
).
Functions that use the static context of the caller to expand or disambiguate
the values of supplied arguments: for example fn:doc
expands its first
argument using the static base URI of the caller, and xs:QName
expands its first argument
using the inscope namespaces of the caller.
Some functions depend on aspects of the dynamic context that remain invariant
within an
Userdefined functions in XQuery and XSLT may depend on the static context of the function definition (for example, the inscope namespaces) and also in a limited way on the dynamic context (for example, the values of global variables). However, the only way they can depend on the static or dynamic context of the caller — which is what concerns us here — is by defining optional parameters whose default values are contextdependent.
Because the focus is a specific part of the dynamic context, all
A fn:functionlookup
.
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:functionlookup
; 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:functionlookup
.
The result of a dynamic call to a function item never depends on the static or dynamic context of the dynamic function call, only (where relevant) on the the captured context held within the function item itself.
Contextdependent functions fall into a number of categories:
The functions fn:currentdate
, fn:currentdateTime
, fn:currenttime
,
fn:defaultlanguage
, fn:implicittimezone
,
fn:adjustdatetotimezone
, fn:adjustdateTimetotimezone
, and
fn:adjusttimetotimezone
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:baseuri#0
, fn:data#0
,
fn:documenturi#0
, fn:elementwithid#1
, fn:id#1
,
fn:idref#1
, fn:lang#1
, fn:last#0
, fn:localname#0
,
fn:name#0
, fn:namespaceuri#0
, fn:normalizespace#0
,
fn:number#0
, fn:path#0
, fn:position#0
,
fn:root#0
, fn:string#0
, and
fn:stringlength#0
depend on the
A function is
A function that
is not
The function fn:defaultcollation
and many
stringhandling operators and functions depend
on the default collation and the inscope 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:staticbaseuri
, 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:functionlookup
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:functionlookup
fn:functionlookup
returns.
All functions defined in this specification are
fn:distinctvalues
, fn:unordered
, map:keys
,
and map:foreach
) produce results in an
Some functions (such as fn:analyzestring
,
fn:parsexml
, fn:parsexmlfragment
, and fn:jsontoxml
)
construct a tree of nodes to
represent their 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 nonidentical nodes are returned, their content will be the
same in the sense of the fn:deepequal
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)
Accessors and their semantics are described in
Each of these functions has an arityzero signature which is equivalent to the arityone
form, with the context value supplied as the implicit first argument. In addition, each of the
arityone functions accepts an empty sequence as the argument, in which case it generally delivers
an empty sequence as the result: the exception is fn:string
, which delivers
a zerolength string.
Function  Accessor  Accepts  Returns 

fn:nodename

nodename
 node (optional)  xs:QName (optional)

fn:nilled

nilled
 node (optional)  xs:boolean (optional)

fn:string

stringvalue
 item (optional) 
xs:string

fn:data

typedvalue
 zero or more items  a sequence of atomic values 
fn:baseuri

baseuri
 node (optional)  xs:anyURI (optional)

fn:documenturi

documenturi
 node (optional)  xs:anyURI (optional)

Returns the name of a node, as an xs:QName
.
The zeroargument form of this function is
The oneargument form of this function is
If the argument is omitted, it defaults to the context value (.
).
If $node
is the empty sequence, the empty sequence is returned.
Otherwise, the function returns the result of the dm:nodename
accessor as
defined in
The following errors may be raised when $node
is omitted:
If the context value is
If the context value is not a single node, type error
For element and attribute nodes, the name of the node is returned as an
xs:QName
, retaining the prefix, namespace URI, and local part.
For processing instructions, the name of the node is returned as an
xs:QName
in which the prefix and namespace URI are
For a namespace node, the function returns an empty sequence if the node represents the
default namespace; otherwise it returns an xs:QName
in which prefix and
namespace URI are
For all other kinds of node, the function returns the empty sequence.
Variables  

Expression  Result 

nodename($e//*[@id = 'alpha'])  
nodename($e//*[@id = 'gamma'])  
nodename($e//*[@id = 'delta'])  
nodename($e//processinginstruction())  
nodename($e//*[@id = 'alpha']/text())  
nodename($e//*[@id = 'alpha']/@id)  
nodename($e//*[@id = 'alpha']/@xml:id) 
Returns true
for an element that is
The zeroargument form of this function is
The oneargument form of this function is
If the argument is omitted, it defaults to the context value (.
).
If $node
is the empty sequence, the function returns the empty sequence.
Otherwise the function returns the result of the dm:nilled
accessor as
defined in
The following errors may be raised when $node
is omitted:
If the context value is
If the context value is not a single node, type error
If $node
is not an element node, the function returns the empty
sequence.
If $node
is an untyped element node, the function returns false
.
In practice, the function returns true
only for an element node that has
the attribute xsi:nil="true"
and that is successfully validated against a
schema that defines the element to be nillable; the detailed rules, however, are defined
in
Returns the value of $value
represented as an xs:string
.
The zeroargument form of this function is
The oneargument form of this function is
In the zeroargument version of the function, $value
defaults to the context
value. That is, calling fn:string()
is equivalent to calling
fn:string(.)
.
If $value
is the empty sequence, the function returns the zerolength
string.
If $value
is a node, the function returns the string value of the node, as obtained using the
dm:stringvalue
accessor defined in
If $value
is an atomic value, the function returns the result of the expression $value cast
as xs:string
(see
In all other cases, a dynamic error occurs (see below).
The following errors may be raised when $value
is omitted:
If the context value is
If the context value is not a single item, type error
A type error is raised $value
is a function item (this includes maps and arrays).
Every node has a string value, even an element with elementonly content (which has no typed value). Moreover, casting an atomic value to a string always succeeds. Functions, maps, and arrays have no string value, so these are the only arguments that satisfy the type signature but cause failure.
Variables  

Expression  Result 

string(23)  
string(false())  
string("Paris")  
string((1, 2, 3))  Raises error XPTY0004. 
string([ [ 1, 2 ], [ 3, 4 ] ])  Raises error FOTY0014. 
string(abs#1)  Raises error FOTY0014. 
string($para) 
Returns the result of atomizing a sequence. This process flattens arrays, and replaces nodes by their typed values.
The zeroargument form of this function is
The oneargument form of this function is
If the argument is omitted, it defaults to the context value (.
).
The result of fn:data
is the sequence of atomic values produced by
applying the following rules to each item in $input
:
If the item is an atomic value, it is appended to the result sequence.
If the item is a node, the typed value of the node is appended to the result
sequence. The typed value is a sequence of zero or more atomic values:
specifically, the result of the dm:typedvalue
accessor as defined in
If the item is an array, the result of applying fn:data
to
each member of the array, in order, is appended to the result sequence.
A type error is raised $input
is a node that does not have a typed value.
A type error is raised $input
is a function item other than
an array.
A type error is raised $input
is omitted and the context value is
The process of applying the fn:data
function to a sequence is referred to
as atomization
. In many cases an explicit call on fn:data
is
not required, because atomization is invoked implicitly when a node or sequence of nodes
is supplied in a context where an atomic value or sequence of atomic values is
required.
The result of atomizing an empty sequence is an empty sequence.
The result of atomizing an empty array is an empty sequence.
Variables  

Expression  Result 

data(123)  
data((123, 456))  
data([ [ 1, 2 ], [ 3, 4 ] ])  
data($para)  
data($para/term/@author)  
data(abs#1)  Raises error FOTY0013. 
Returns the base URI of a node.
The zeroargument form of this function is
The oneargument form of this function is
The zeroargument version of the function returns the base URI of the context node: it
is equivalent to calling fn:baseuri(.)
.
The singleargument version of the function behaves as follows:
If $node
is the empty sequence, the function returns the empty
sequence.
Otherwise, the function returns the value of the dm:baseuri
accessor
applied to the node $node
. This accessor is defined, for each kind of
node, in the XDM specification (See
As explained in XDM, document, element and processinginstruction nodes have a baseuri property which may be empty. The baseuri property for all other node kinds is the empty sequence. The dm:baseuri accessor returns the baseuri property of a node if it exists and is nonempty; otherwise it returns the result of applying the dm:baseuri accessor to its parent, recursively. If the node does not have a parent, or if the recursive ascent up the ancestor chain encounters a parentless node whose baseuri property is empty, the empty sequence is returned. In the case of namespace nodes, however, the result is always an empty sequence — it does not depend on the base URI of the parent element.
See also fn:staticbaseuri
.
The following errors may be raised when $node
is omitted:
If the context value is
If the context value is not a single node, type error
Returns the URI of a resource where a document can be found, if available.
The zeroargument form of this function is
The oneargument form of this function is
If the argument is omitted, it defaults to the context value (.
).
If $node
is the empty sequence, the function returns the empty sequence.
If $node
is not a document node, the function returns the empty
sequence.
Otherwise, the function returns the value of the documenturi
accessor
applied to $node
, as defined in
The following errors may be raised when $node
is omitted:
If the context value is
If the context value is not a single node, type error
In the case of a document node $D
returned by the fn:doc
function, it will generally be the case that fn:documenturi($D)
returns a URI $U
such that a call on fn:doc($U)
in the same dynamic context will return the same document
node $D
. The URI $U
will not necessarily be the same URI that was originally
passed to the fn:doc
function, since several URIs may identify the same resource.
This equivalence
does not apply if the second call on fn:doc
uses a different dynamic context. For example,
in XSLT, a call on fn:doc
in one stylesheet package might perform whitespace stripping
or schema validation, while the same call in a different stylesheet package does not; the two calls
might therefore return different documents both having the same fn:documenturi
property.
It is fn:collection
should follow the same principle: any documents included in the returned collection, if they have a nonempty
fn:documenturi
property, should be such that a call on fn:doc
supplying this URI
(in the same dynamic context) returns the same document node.
The same guarantees do not hold for document nodes obtained by other mechanisms,
for example document nodes supplied as external parameters to a query or stylesheet. The fn:documenturi
property of such documents is under user control; it is entirely possible for two such documents to have
the same fn:documenturi
property, in which case it is clearly impossible to use this property
to retrieve the original document.
In this document, as well as in an error is raised
is used. Raising an error is equivalent to calling the fn:error
function defined in this section with the provided error code. Except where otherwise
specified, errors defined in this specification are dynamic errors. Some errors,
however, are classified as type errors. Type errors are typically used where the presence
of the error can be inferred from knowledge of the type of the actual arguments to a function, for
example with a call such as fn:string(fn:abs#1)
. Host languages may allow type errors
to be reported statically if they are discovered during static analysis.
When function specifications indicate that an error is to be raised, the notation
[
is used to specify an error code. Each error defined
in this document is identified by an xs:QName
that is in the
http://www.w3.org/2005/xqterrors
namespace, represented in this document by the err
prefix. It is this
xs:QName
that is actually passed as an argument to the
fn:error
function. Calling this function raises an error. For a
more detailed treatment of error handing, see
The fn:error
function is a general function that may be called as above
but may also be called from xs:QName
argument.
Calling the fn:error
function raises an applicationdefined error.
This function is
This function never returns a value. Instead it always raises an error. The effect of the error is identical to the effect of dynamic errors raised implicitly, for example when an incorrect argument is supplied to a function.
The parameters to the fn:error
function supply information that is
associated with the error condition and that is made available to a caller that asks for
information about the error. The error may be caught either by the host language (using
a try/catch construct in XSLT or XQuery, for example), or by the calling application or
external processing environment. The way in which error information is returned to the
external processing environment is
There are three pieces of information that may be associated with an error.
The $code
is an error code that distinguishes this error from others.
It is an xs:QName
; the namespace URI conventionally identifies the
component, subsystem, or authority responsible for defining the meaning of the
error code, while the local part identifies the specific error condition. The
namespace URI http://www.w3.org/2005/xqterrors
is used for errors
defined in this specification; other namespace URIs may be used for errors defined
by the application.
If the external processing environment expects the error code to be returned as a
URI or a string rather than as an xs:QName
, then an error code with
namespace URI NS
and local part LP
will be returned in
the form NS#LP
. The namespace URI part of the error code should
therefore not include a fragment identifier.
If no value is supplied for the $code
argument, fn:QName('http://www.w3.org/2005/xqterrors', 'err:FOER0000')
.
The $description
is a naturallanguage description of the error
condition.
If no value is supplied for the $description
argument,
The $value
is an arbitrary value used to convey additional
information about the error, and may be used in any way the application
chooses.
If no value is supplied for the $value
argument
This function always raises a dynamic error. By default, it raises
The value of the $description
parameter may need to be localized.
The type none
is a special type defined in
Any QName may be used as an error code; there are no reserved names or namespaces. The error is always classified as a dynamic error, even if the error code used is one that is normally used for static errors or type errors.
Expression: 


Result:  Raises error FOER0000.

Expression:  
Result:  Raises error myerr:toohighsal.

Changed in 4.0: All three arguments are now optional, and each argument can be set
to an empty sequence. Previously if $description
was supplied, it could not be empty.
Provides an execution trace intended to be used in debugging queries.
This function is
The function returns $input
, unchanged.
In addition, the values of $input
, typically serialized and converted
to an xs:string
, and $label
(if supplied
Any serialization of the implementation's trace output
The format of the trace output and its order are
If the trace information is unrelated to a specific value,
fn:message
can be used instead.
Consider a situation in which a user wants to investigate the actual value passed to
a function. Assume that in a particular execution,  
The following two XPath expressions are identical, but only the second provides trace feedback to the user:  

Changed in 4.0: The $label
argument can now be set
to an empty sequence. Previously if $label
was supplied, it could not be empty.
Outputs trace information and discards the result.
This function is
Similar to fn:trace
, the values of $input
,
typically serialized and converted to an xs:string
, and $label
(if supplied and nonempty)
In contrast to fn:trace
, the function returns an empty sequence.
Any serialization of the implementation’s log output
The format of the log output and its order are
The function can be used for debugging. It can also be helpful in productive environments, e.g. to store dynamic input and evaluations to log files.
The following two XPath expressions are identical, but only the second logs any feedback:  

New function.
Returns implementationdependent information about the current state of execution.
This function is
The result of the function is an
The function is nondeterministic: multiple calls will typically produce different results.
The function will typically be called to assist in diagnosing dynamic errors.
This section specifies arithmetic operators on the numeric datatypes defined in
The operators described in this section are defined on the following atomic types.
They also apply to types derived by restriction from the above types.
The type xs:numeric
is defined as a union type whose member types are
(in order) xs:double
, xs:float
, and xs:decimal
. This type is implicitly imported
into the static context, so it can also be used in defining the signature of userwritten functions. Apart from the fact that
it is implicitly imported, it behaves exactly like a userdefined type with the same definition. This means, for example:
If the expected type of a function parameter is given as xs:numeric
, the actual value supplied
can be an instance of any of these three types, or any type derived from these three by restriction (this includes the builtin
type xs:integer
, which is derived from xs:decimal
).
If the expected type of a function parameter is given as xs:numeric
, and the actual value supplied
is xs:untypedAtomic
(or a node whose atomized value is xs:untypedAtomic
), then it will
be cast to the union type xs:numeric
using the rules in xs:double
subsumes the lexical space of the other member types, and
xs:double
is listed first, the effect is that if the untyped atomic value is in the lexical space of
xs:double
, it will be converted to an xs:double
, and if not, a dynamic error occurs.
When the return type of a function is given as xs:numeric
, the actual value returned will be
an instance of one of the three member types (and perhaps also of types derived from these by restriction). The rules
for the particular function will specify how the type of the result depends on the values supplied as arguments.
In many cases, for the functions in this specification, the result is defined to be the same type as the first
argument.
This specification uses xs:float
and xs:double
values.
One consequence of this is that some operations result in the value NaN
(not a number), which
has the unusual property that it is not equal to itself. Another consequence is that some operations return the value negative zero.
This differs from NaN
as being equal to itself and defines only a single zero in the value space.
The text accompanying several functions defines behavior for both positive and negative zero inputs and outputs
in the interest of alignment with 0.0e0
(which is actually a unary minus operator
applied to an xs:double
value) will always return negative zero: see 0
XML Schema 1.1 introduces support for positive and negative zero as distinct values, and also uses the NaN
.
The following functions define the semantics of arithmetic operators defined in
Operator  Meaning 

op:numericadd
 Addition 
op:numericsubtract
 Subtraction 
op:numericmultiply
 Multiplication 
op:numericdivide
 Division 
op:numericintegerdivide
 Integer division 
op:numericmod
 Modulus 
op:numericunaryplus
 Unary plus 
op:numericunaryminus
 Unary minus (negation) 
The parameters and return types for the above operators are in most cases declared to be of type
xs:numeric
, which permits the basic numeric
types: xs:integer
, xs:decimal
, xs:float
and xs:double
, and types derived from them.
In general the twoargument functions require that both arguments are of the same primitive type,
and they return a value of this same type.
The exceptions are op:numericdivide
, which returns
an xs:decimal
if called with two xs:integer
operands,
and op:numericintegerdivide
which always returns an xs:integer
.
If the two operands of an arithmetic expression are not of the same type,
The result type of operations depends on their argument datatypes and is defined in the following table:
Operator  Returns 

op:operation(xs:integer, xs:integer)

xs:integer (except for op:numericdivide(integer,
integer) , which returns xs:decimal ) 
op:operation(xs:decimal, xs:decimal)

xs:decimal

op:operation(xs:float, xs:float)

xs:float

op:operation(xs:double, xs:double)

xs:double

op:operation(xs:integer)

xs:integer

op:operation(xs:decimal)

xs:decimal

op:operation(xs:float)

xs:float

op:operation(xs:double)

xs:double

These rules define any operation on any pair of arithmetic types. Consider the following example:
For this operation, xs:int
must be converted to
xs:double
. This can be done, since by the rules above:
xs:int
can be substituted for xs:integer
,
xs:integer
can be substituted for xs:decimal
,
xs:decimal
can be promoted to xs:double
. As far as possible, the promotions should be done in a
single step. Specifically, when an xs:decimal
is promoted to an
xs:double
, it should not be converted to an xs:float
and then to xs:double
, as this risks loss of precision.
As another example, a user may define height
as a derived type of
xs:integer
with a minimum value of 20 and a maximum value of 100.
They may then derive fenceHeight
using an enumeration to restrict the
permitted set of values to, say, 36, 48 and 60.
fenceHeight
can be substituted for its base type
height
and height
can be substituted for its base type
xs:integer
.
The basic rules for addition, subtraction, and multiplication
of ordinary numbers are not set out in this specification; they are taken as given. In the case of xs:double
and xs:float
the rules are as defined in NaN
,
and exception conditions such as overflow and underflow, are described more explicitly since they are not necessarily obvious.
On overflow and underflow situations during arithmetic operations, conforming
implementations
For xs:float
and xs:double
operations, overflow
behavior
Raising a dynamic error
Returning INF
or INF
.
Returning the largest (positive or negative) noninfinite number.
For xs:float
and xs:double
operations,
underflow behavior
Raising a dynamic error
Returning 0.0E0
or +/ 2**Emin
or a
denormalized value; where Emin
is the smallest
possible xs:float
or xs:double
exponent.
For xs:decimal
operations, overflow behavior 0.0
must be returned.
For xs:integer
operations, implementations that support
limitedprecision integer operations
They
They
The functions op:numericadd
, op:numericsubtract
,
op:numericmultiply
, op:numericdivide
,
op:numericintegerdivide
and op:numericmod
are each
defined for pairs of numeric operands, each of which has the same
type:xs:integer
, xs:decimal
, xs:float
, or
xs:double
. The functions op:numericunaryplus
and
op:numericunaryminus
are defined for a single operand whose type
is one of those same numeric types.
For xs:float
and xs:double
arguments, if either
argument is NaN
, the result is NaN
.
For xs:decimal
values, let N be the number of digits
of precision supported by the implementation, and let M (M <= N
) be the minimum limit on the number of digits
required for conformance (18 digits for XSD 1.0, 16 digits for XSD 1.1). Then for addition, subtraction, and multiplication
operations, the returned result
This specification does not determine whether xs:decimal
operations are fixed point or floating point.
In an implementation using floating point it is possible for very simple operations to require more digits of precision than
are available; for example, adding 1e100
to 1e100
requires 200 digits of precision for an
accurate representation of the result.
The divideByZero
and invalidOperation
. The
IEEE divideByZero
exception is raised not only by a direct attempt to divide by zero, but also by
operations such as log(0)
. The IEEE invalidOperation
exception is raised by
attempts to call a function with an argument that is outside the function’s domain (for example,
sqrt(1)
or log(1)
).
Although IEEE defines these as exceptions, it also defines “default nonstop exception handling” in
which the operation returns a defined result, typically positive or negative infinity, or NaN
. With this
function library,
these IEEE exceptions do not cause a dynamic error
at the application level; rather they result in the relevant function or operator returning
the defined nonerror result.
The underlying IEEE exception INF
, +INF
, or NaN
) with no error.
The NaN
values:
a quiet NaN
and a signaling NaN
. These two values are not distinguishable in the XDM model:
the value spaces of xs:float
and xs:double
each include only a single
NaN
value. This does not prevent the implementation distinguishing them internally,
and triggering different
Returns the arithmetic sum of its operands: ($arg1 + $arg2
).
Defines the semantics of the +
operator when
applied to two numeric values
General rules: see
For xs:float
or xs:double
values, if one of the operands is a
zero or a finite number and the other is INF
or INF
,
INF
or INF
is returned. If both operands are
INF
, INF
is returned. If both operands are
INF
, INF
is returned. If one of the operands is
INF
and the other is INF
, NaN
is
returned.
Returns the arithmetic difference of its operands: ($arg1  $arg2
).
Defines the semantics of the 
operator when
applied to two numeric values.
General rules: see
For xs:float
or xs:double
values, if one of the operands is a
zero or a finite number and the other is INF
or INF
, an
infinity of the appropriate sign is returned. If both operands are INF
or
INF
, NaN
is returned. If one of the operands is
INF
and the other is INF
, an infinity of the appropriate
sign is returned.
Returns the arithmetic product of its operands: ($arg1 * $arg2
).
Defines the semantics of the *
operator when
applied to two numeric values.
General rules: see
For xs:float
or xs:double
values, if one of the operands is a
zero and the other is an infinity, NaN
is returned. If one of the operands
is a nonzero number and the other is an infinity, an infinity with the appropriate sign
is returned.
Returns the arithmetic quotient of its operands: ($arg1 div $arg2
).
Defines the semantics of the div
operator when
applied to two numeric values.
General rules: see
As a special case, if the types of both $arg1
and $arg2
are
xs:integer
, then the return type is xs:decimal
.
A dynamic error is raised xs:decimal
and xs:integer
operands, if the divisor is (positive or negative) zero.
For xs:float
and xs:double
operands, floating point division
is performed as specified in INF
. A negative number divided by positive zero
returns INF
. Division by negative zero returns INF
and
INF
, respectively. Positive or negative zero divided by positive or
negative zero returns NaN
. Also, INF
or INF
divided by INF
or INF
returns NaN
.
Performs an integer division.
Defines the semantics of the idiv
operator when
applied to two numeric values.
General rules: see
If $arg2
is INF
or INF
, and $arg1
is not INF
or INF
, then the result is zero.
Otherwise, subject to limits of precision and overflow/underflow conditions, the result
is the largest (furthest from zero) xs:integer
value $N
such
that the following expression is true
:
The second term in this condition ensures that the result has the correct sign.
The implementation may adopt a different algorithm provided that it is equivalent to
this formulation in all cases where xs:decimal
division.
A dynamic error is raised
A dynamic error is raised NaN
or if $arg1
is INF
or
INF
.
Except in situations involving errors, loss of precision, or overflow/underflow, the
result of $a idiv $b
is the same as ($a div $b) cast as
xs:integer
.
The semantics of this function are different from integer division as defined in programming languages such as Java and C++.
Expression  Result 

op:numericintegerdivide(10, 3)  
op:numericintegerdivide(3, 2)  
op:numericintegerdivide(3, 2)  
op:numericintegerdivide(3, 2)  
op:numericintegerdivide(9.0, 3)  
op:numericintegerdivide(3.5, 3)  
op:numericintegerdivide(3.0, 4)  
op:numericintegerdivide(3.1E1, 6)  
op:numericintegerdivide(3.1E1, 7) 
Returns the remainder resulting from dividing $arg1
, the dividend, by
$arg2
, the divisor.
Defines the semantics of the mod
operator when
applied to two numeric values.
General rules: see
The operation a mod b
for operands that are xs:integer
or
xs:decimal
, or types derived from them, produces a result such that
(a idiv b) * b + (a mod b)
is equal to a
and the magnitude of
the result is always less than the magnitude of b
. This identity holds even
in the special case that the dividend is the negative integer of largest possible
magnitude for its type and the divisor is 1 (the remainder is 0). It follows from this
rule that the sign of the result is the sign of the dividend.
For xs:float
and xs:double
operands the following rules
apply:
If either operand is NaN
, the result is NaN
.
If the dividend is positive or negative infinity, or the divisor is positive or
negative zero (0), or both, the result is NaN
.
If the dividend is finite and the divisor is an infinity, the result equals the dividend.
If the dividend is positive or negative zero and the divisor is finite, the result is the same as the dividend.
In the remaining cases, where neither positive or negative infinity, nor positive
or negative zero, nor NaN
is involved, the result obeys (a idiv
b)*b+(a mod b)
= a
.
Division is truncating division, analogous to integer division, not
A dynamic error is raised xs:integer
and xs:decimal
operands, if $arg2
is zero.
Expression  Result 

op:numericmod(10, 3)  
op:numericmod(6, 2)  
op:numericmod(4.5, 1.2)  
op:numericmod(1.23E2, 0.6E1) 
Returns its operand with the sign unchanged: (+ $arg
).
Defines the semantics of the unary +
operator
applied to a numeric value.
General rules: see
The returned value is equal to $arg
, and is an instance of
xs:integer
, xs:decimal
, xs:double
, or
xs:float
depending on the type of $arg
.
Because function conversion rules are applied in the normal way, the unary
+
operator can be used to force conversion of an untyped node to a
number: the result of +@price
is the same as xs:double(@price)
if the type of @price
is xs:untypedAtomic
.
Returns its operand with the sign reversed: $arg
.
Defines the semantics of the unary 
operator when
applied to a numeric value.
General rules: see
The returned value is an instance of xs:integer
, xs:decimal
,
xs:double
, or xs:float
depending on the type of
$arg
.
For xs:integer
and xs:decimal
arguments, 0
and
0.0
return 0
and 0.0
, respectively. For
xs:float
and xs:double
arguments, NaN
returns
NaN
, 0.0E0
returns 0.0E0
and vice versa.
INF
returns INF
. INF
returns
INF
.
The six value comparison operators eq
, ne
, lt
,
le
, gt
, and ge
are defined in terms of two
underlying functions: op:numericequal
and op:numericlessthan
.
These functions are defined to operate on values of the same type.
If the arguments are of different types, one argument is promoted to the type of the other
as described above in NaN
,
false
is returned.
For a description of the different ways of comparing numeric
values using the operators =
and eq
and the functions
fn:deepequal
and fn:atomicequal
,
see
See also the function fn:compare
.
Function  Meaning 

op:numericequal  Returns true if and only if the value of $arg1 is equal to the value of
$arg2 . 
op:numericlessthan  Returns true if and only if $arg1 is numerically less than
$arg2 . 
Returns true
if and only if the value of $arg1
is equal to the value of
$arg2
.
Defines the semantics of
the eq
operator when applied to two numeric values, and is also used in defining the
semantics of ne
, le
and ge
.
General rules: see
For xs:float
and xs:double
values, positive zero and negative
zero compare equal. INF
equals INF
and INF
equals INF
. If $arg1
or $arg2
is
NaN
, the function returns false
.
Returns true
if and only if $arg1
is numerically less than
$arg2
.
Defines the semantics of the
lt
operator when applied to two numeric values, and is also used in defining the
semantics of le
, gt
, and ge
.
General rules: see
For xs:float
and xs:double
values, positive infinity is
greater than all other nonNaN
values; negative infinity is less than all
other nonNaN
values. Positive and negative zero compare equal.
If $arg1
or $arg2
is
NaN
, the function returns false
.
The following functions are defined on numeric types. Each function returns a value of the same type as the type of its argument.
If the argument is the empty sequence, the empty sequence is returned.
For xs:float
and xs:double
arguments, if the
argument is NaN
, NaN
is returned.
With the exception of fn:abs
, functions with arguments of
type xs:float
and xs:double
that are positive or
negative infinity return positive or negative infinity.
Function  Meaning 

fn:abs  Returns the absolute value of $value . 
fn:ceiling  Rounds $value upwards to a whole number. 
fn:floor  Rounds $value downwards to a whole number. 
fn:round  Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near. 
fn:roundhalftoeven  Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near. 
fn:isNaN  Returns true if the argument is the xs:float or xs:double value NaN . 
fn:round
and fn:roundhalftoeven
produce the same
result in all cases except when the argument is exactly midway between two values
with the required precision.
Other ways of rounding midway values can be achieved as follows:
Towards negative infinity: round($x)
Away from zero: round(abs($x)) * compare($x, 0)
Towards zero: abs(round($x)) * compare($x, 0)
Returns the absolute value of $value
.
This function is
General rules: see
If $value
is negative the function returns $value
, otherwise it
returns $value
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result $value
is an instance of xs:positiveInteger
then the value of
$value
For xs:float
and xs:double
arguments, if the argument is
positive zero or negative zero, then positive zero is returned. If the argument is
positive or negative infinity, positive infinity is returned.
Expression  Result 

abs(10.5)  
abs(10.5)  
abs(math:log(0)) 
Rounds $value
upwards to a whole number.
This function is
General rules: see
The function returns the smallest (closest to negative infinity) number with no
fractional part that is not less than $value
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result $value
is an instance of xs:decimal
then the result xs:integer
.
For xs:float
and xs:double
arguments, if the argument is
positive zero, then positive zero is returned. If the argument is negative zero, then
negative zero is returned. If the argument is less than zero and greater than 1,
negative zero is returned. If the argument is positive or negative infinity,
the value of the argument is returned.
Expression  Result 

ceiling(10.5)  
ceiling(10.5)  
ceiling(math:log(0)) 
Rounds $value
downwards to a whole number.
This function is
General rules: see
The function returns the largest (closest to positive infinity) number with no
fractional part that is not greater than $value
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result $value
is an instance of xs:decimal
then the result xs:integer
.
For xs:float
and xs:double
arguments, if the argument is
positive zero, then positive zero is returned. If the argument is negative zero, then
negative zero is returned. If the argument is positive or negative infinity,
the value of the argument is returned.
Expression  Result 

floor(10.5)  
floor(10.5)  
math:log(0) => floor() 
Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near.
This function is
General rules: see
The function returns the nearest (that is, numerically closest) value to
$value
that is a multiple of ten to the power of minus
$precision
. If two such values are equally near (for example, if the
fractional part in $value
is exactly .5), the function returns the one that
is closest to positive infinity.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result $value
is an instance of xs:decimal
and $precision
is
less than one, then the result xs:integer
.
If the second argument is omitted or an empty sequence,
the function produces the same result as the twoargument version with
$precision = 0
(that is, it rounds to a whole number).
When $value
is of type xs:float
and xs:double
:
If $value
is NaN
, positive or negative zero, or positive or negative
infinity, then the result is the same as the argument.
For other values, the argument is cast to xs:decimal
using an
implementation of xs:decimal
that imposes no limits on the number of
digits that can be represented. The function is applied to this
xs:decimal
value, and the resulting xs:decimal
is
cast back to xs:float
or xs:double
as appropriate to
form the function result. If the resulting xs:decimal
value is zero,
then positive or negative zero is returned according to the sign of
$value
.
This function is typically used with a nonzero $precision
in financial
applications where the argument is of type xs:decimal
. For arguments of
type xs:float
and xs:double
the results may be
counterintuitive. For example, consider round(35.425e0, 2)
. The result is
not 35.43
, as might be expected, but 35.42
.
This is because the xs:double
written as 35.425e0
has an exact value equal to 35.42499999999...
, which is closer to
35.42
than to 35.43
.
Expression  Result 

round(2.5)  
round(2.4999)  
round(2.5) 

round(1.125, 2)  
round(8452, 2)  
round(3.1415e0, 2)  
math:log(0) => round() 
Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near.
This function is
General rules: see
The function returns the nearest (that is, numerically closest) value to
$value
that is a multiple of ten to the power of minus
$precision
. If two such values are equally near (e.g. if the fractional
part in $value
is exactly .500...), the function returns the one whose least
significant digit is even.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result $value
is an instance of xs:decimal
and $precision
is less than one, then the result xs:integer
.
If the second argument is omitted or an empty sequence,
the function produces the same result as the twoargument version with
$precision = 0
.
For arguments of type xs:float
and xs:double
:
If the argument is NaN
, positive or negative zero, or positive or
negative infinity, then the result is the same as the argument.
In all other cases, the argument is cast to xs:decimal
using an
implementation of xs:decimal
that imposes no limits on the number of digits that
can be represented. The function is applied to this xs:decimal
value,
and the resulting xs:decimal
is cast back to xs:float
or
xs:double
as appropriate to form the function result. If the
resulting xs:decimal
value is zero, then positive or negative zero is
returned according to the sign of the original argument.
This function is typically used in financial applications where the argument is of type
xs:decimal
. For arguments of type xs:float
and
xs:double
the results may be counterintuitive. For example, consider
roundhalftoeven(xs:float(150.015), 2)
.
The result is not 150.02
as might be expected, but 150.01
.
This is because the conversion of the
xs:float
value represented by the literal 150.015
to an
xs:decimal
produces the xs:decimal
value 150.014999389...
, which is closer to
150.01
than to 150.02
.
Expression  Result 

roundhalftoeven(0.5)  
roundhalftoeven(1.5)  
roundhalftoeven(2.5)  
roundhalftoeven(3.567812e+3, 2)  
roundhalftoeven(4.7564e3, 2)  
roundhalftoeven(35612.25, 2)  
math:log(0) => roundhalftoeven() 
Returns true
if the argument is the xs:float
or xs:double
value NaN
.
This function is
The function returns true
if the argument is the xs:float
or xs:double
value NaN
;
otherwise it returns false
.
Expression  Result 

isNaN(23)  
isNaN("NaN")  
isNaN(number("twentythree"))  
isNaN(math:sqrt(1)) 
New in 4.0. Accepted 20220920.
It is possible to convert strings to values of type xs:integer
,
xs:float
, xs:decimal
, or xs:double
using the constructor functions described in cast
expressions as described in
In addition the fn:number
function is available to convert strings
to values of type xs:double
. It differs from the xs:double
constructor function in that any value outside the lexical space of the xs:double
datatype is converted to the xs:double
value NaN
.
Function  Meaning 

fn:number  Returns the value indicated by $value or, if $value is not
specified, the context value after atomization, converted to an xs:double .

fn:parseinteger  Converts a string to an integer, recognizing any radix in the range 2 to 36. 
Returns the value indicated by $value
or, if $value
is not
specified, the context value after atomization, converted to an xs:double
.
The zeroargument form of this function is
The oneargument form of this function is
Calling the zeroargument version of the function is defined to give the same result as
calling the singleargument version with the context value (.
). That is,
fn:number()
is equivalent to fn:number(.)
, as defined by
the rules that follow.
If $value
is the empty sequence or if $value
cannot be converted
to an xs:double
, the xs:double
value NaN
is
returned.
Otherwise, $value
is converted to an xs:double
following the
rules of xs:double
fails, the xs:double
value NaN
is returned.
A type error is raised $value
is omitted and the context value is
As a consequence of the rules given above, a type error is raised
XSD 1.1 allows the string +INF
as a representation of positive infinity;
XSD 1.0 does not. It is
Generally fn:number
returns NaN
rather than raising a dynamic
error if the argument cannot be converted to xs:double
. However, a type
error is raised in the usual way if the supplied argument cannot be atomized or if the
result of atomization does not match the required argument type.
Variables  

Expression  Result 

number(12)  
number('12')  
number('INF')  
number('NaN')  
number('nonnumeric')  
number($e/@price)  
number($e/@discount)  
number($e/@misspelt)  
("10", "11", "12") ! number() 
Converts a string to an integer, recognizing any radix in the range 2 to 36.
This function is
The supplied $radix
must be in the range 2 to 36 inclusive.
The string $value
is preprocessed by stripping all whitespace characters (including internal whitespace)
and underscore characters.
After this process, the supplied value
must consist of an optional sign (+
or 
)
followed by a sequence of one or more generalized digits drawn from the first $radix
characters
in the alphabet 0123456789abcdefghijklmnopqrstuvwxyz
; uppercase alphabetics
AZ
may be used in place of their lowercase equivalents.
The value of a generalized digit corresponds to its position in this alphabet. More formally, in nonerror cases the result of the function is given by the XQuery expression:
A dynamic error is raised $radix
is not in the range 2 to 36.
A dynamic error is raised $value
is a zerolength string,
or if it contains a character
that is not among the first $radix
characters in the
alphabet 0123456789abcdefghijklmnopqrstuvwxyz
, or the
uppercase equivalent of such a character.
A dynamic error is raised xs:integer
.
When $radix
takes its default value of 10
,
the function delivers the same result as casting $value
(after removal of whitespace and underscores) to xs:integer
.
If underscores or whitespace in the input need to be rejected, then
the string should first be validated, perhaps using fn:matches
.
If other characters may legitimately appear in the input, for example
a leading 0x
, then this must first be removed by preprocessing the input.
If the input uses a different family of digits, then the value should first
be converted to the required digits using fn:translate
.
A string in the lexical space of xs:hexBinary
will always
be an acceptable input, provided it is not too long. So, for example, the expression
"1DE=" => xs:base64Binary() => xs:hexBinary() => xs:string() => parseinteger(16)
can be used to convert the Base 64 value 1DE=
to the integer 54321, via the
hexadecimal string D431
.
Expression: 


Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Alphabetic base26 numbering systems (hexavigesimal) can be parsed via translation. Note, enumerating systems that do not assign a symbol to zero (e.g., spreadsheet columns) must be preprocessed in a different fashion.  
Expression:  
Result:  
Digitbased numeration systems comparable to the Arabic numbers 0 through 9 can be parsed via translation.  
Expression:  
Result: 
Function  Meaning 

fn:formatinteger  Formats an integer according to a given picture string, using the conventions of a given natural language if specified. 
Formats an integer according to a given picture string, using the conventions of a given natural language if specified.
The twoargument form of this function is
The threeargument form of this function is
If $value
is an empty sequence, the function returns a zerolength
string.
In all other cases, the $picture
argument describes the format in which
$value
is output.
The rules that follow describe how nonnegative numbers are output. If the value of
$value
is negative, the rules below are applied to the absolute value of
$value
, and a minus sign is prepended to the result.
The value of $picture
consists of the following, in order:
An optional radix, which is an integer in the range 2 to 36, written using ASCII
digits (09
) without any leading zero;
A circumflex (^
), which is present if the radix is present, and absent otherwise.
A circumflex is recognized as marking the presence of a radix only
if (a) it is immediately preceded by an integer
in the range 2 to 36, and (b) it is
followed (somewhere within the primary format token) by an "X"
or "x"
. In other cases, the circumflex is treated as a grouping separator.
For example, the picture 9^000
outputs the number
2345 as "2^345"
, whereas 9^XXX
outputs "3185"
.
This rule is to ensure backwards compatibility.
A primary format token. This is always present and
An optional format modifier.
If the string contains one or more semicolons then the last semicolon is taken as terminating the primary format token, and everything that follows is taken as the format modifier; if the string contains no semicolon then the format modifier is taken to be absent (which is equivalent to supplying a zerolength string).
If a radix is present, then the primary format token must follow the rules for a digitpattern.
The primary format token is classified as one of the following:
A digitpattern made up of optionaldigitsigns, mandatorydigitsigns, and groupingseparatorsigns.
The optionaldigitsign is the character #
.
0
through 9
.
Within the format token, these digits are
interchangeable: a threedigit number may thus be indicated equivalently by
000
, 001
, or 999
.
If the primary format token contains at least one Unicode digit,
then the primary format token is taken
as a decimal digit pattern, and in this case it ^((\p{Nd}#[^\p{N}\p{L}])+?)$
. If it contains a
digit but does not match this pattern, a dynamic error is raised
"x"
or "X"
. If any mandatorydigitsign is uppercase "X"
, then all
mandatorydigitsigns must be uppercase "X"
. The digit family
used in the output comprises the first R characters of the
alphabet 0123456789abcdefghijklmnopqrstuvwxyz
, but using uppercase
letters in place of lowercase if an uppercase "X"
is used
as the mandatorydigitsign.
In this case the primary format token ^(([Xx#][^\p{N}\p{L}])+?)$
a groupingseparatorsign is a nonalphanumeric character, that
is a
If a semicolon is to be used as a grouping separator, then the primary format token as a whole must be followed by another semicolon, to ensure that the grouping separator is not mistaken as a separator between the primary format token and the format modifier.
There
The corresponding output is a number in the specified radix, using this digit family, with at least as many digits as there are mandatorydigitsigns in the format token. Thus:
A format token 1
generates the sequence 0 1
2 ... 10 11 12 ...
A format token 01
(or equivalently,
00
or 99
) generates the sequence 00 01 02 ...
09 10 11 12 ... 99 100 101
A format token of ١
(ArabicIndic digit one) generates the sequence ١
then ٢
then ٣
...
A format token of 16^xx
generates the sequence 00 01 02 03
... 08 09 0a 0b 0c 0d 0e 0f 10 11 ...
A format token of 16^X
generates the sequence 0 1 2 3
... 8 9 A B C D E F 10 11 ...
The groupingseparatorsigns are handled as follows:
The position of grouping separators within the format token, counting backwards from the last digit, indicates the position of grouping separators to appear within the formatted number, and the character used as the groupingseparatorsign within the format token indicates the character to be used as the corresponding grouping separator in the formatted number.
More specifically, the
Grouping separators are defined to be
There is at least one grouping separator.
Every grouping separator is the same character (call it C).
There is a positive integer G (the grouping size) such that:
The position of every grouping separator is an integer multiple of G, and
Every positive integer multiple of G that is less than the number of optionaldigitsigns and mandatorydigitsigns in the primary format token is the position of a grouping separator.
The
If grouping separators are regular, then the grouping separator template contains one pair of the form (n×G, C)
for every positive integer n where G is the grouping size and C is the grouping character.
Otherwise (when grouping separators are not regular), the grouping separator template contains one pair of the form
(P, C)
for every grouping separator found in the primary formatting token, where C is the grouping
separator character and P is its position.
If there are no grouping separators, then the grouping separator template is an empty set.
The number is formatted as follows:
Let S/1 be the result of formatting the supplied number
xs:string
.
Let S/2 be the result of padding S/1 on the left with as many leading zeroes as are needed to ensure that it contains at least as many digits as the number of mandatorydigitsigns in the primary format token.
Let S/3 be the result of replacing all decimal digits (09) in S/2 with the corresponding
digits from the selected digit family.
Let S/4 be the result of inserting grouping separators into S/3: for every (position P, character C) pair in the grouping separator template where P is less than the number of digits in S/3, insert character C into S/3 at position P, counting from the righthand end.
Let S/5 be the result of converting S/4 into ordinal form, if an ordinal modifier is present, as described below.
The result of the function is then S/5.
The format token A
, which generates the sequence A B C ... Z AA
AB AC...
.
The format token a
, which generates the sequence a b c ... z aa
ab ac...
.
The format token i
, which generates the sequence i ii iii iv v
vi vii viii ix x ...
.
The format token I
, which generates the sequence I II III IV V
VI VII VIII IX X ...
.
The format token w
, which generates numbers written as lowercase
words, for example in English, one two three four ...
The format token W
, which generates numbers written as uppercase
words, for example in English, ONE TWO THREE FOUR ...
The format token Ww
, which generates numbers written as titlecase
words, for example in English, One Two Three Four ...
Any other format token, which indicates a numbering sequence in which that token
represents the number 1 (one) (but see the note below).
It is 1
.
In some traditional numbering sequences additional signs are added to denote
that the letters should be interpreted as numbers, for example, in ancient Greek
the
For all format tokens other than a digitpattern, there
①
(circled
digit one, ①) has a range imposed by the Unicode character repertoire — 1
.
The above expansions of numbering sequences for format tokens such as a
and
i
are indicative but not prescriptive. There are various conventions in
use for how alphabetic sequences continue when the alphabet is exhausted, and differing
conventions for how roman numerals are written (for example, IV
versus
IIII
as the representation of the number 4). Sometimes alphabetic
sequences are used that omit letters such as i
and o
. This
specification does not prescribe the detail of any sequence other than those sequences
consisting entirely of decimal digits.
Many numbering sequences are languagesensitive. This applies especially to the sequence
selected by the tokens w
, W
and Ww
. It also
applies to other sequences, for example different languages using the Cyrillic alphabet
use different sequences of characters, each starting with the letter #x410 (Cyrillic
capital letter A). In such cases, the $language
argument specifies which
language conventions are to be used. If the argument is specified, the value
xml:lang
attribute (see
The set of languages for which numbering is supported is $language
argument is absent, or is
set to an empty sequence, or is invalid, or is not a language supported by the
implementation, then the number is formatted using the default language from the dynamic
context.
The format modifier ^([co](\(.+\))?)?[at]?$
. That is, if it is present it must
consist of one or more of the following, in order:
either c
or o
, optionally followed by a sequence of
characters enclosed between parentheses, to indicate cardinal or ordinal numbering
respectively, the default being cardinal numbering
either a
or t
, to indicate alphabetic or traditional
numbering respectively, the default being
If the o
modifier is present, this indicates a request to output ordinal
numbers rather than cardinal numbers. For example, in English, when used with the format
token 1
, this outputs the sequence 1st 2nd 3rd 4th ...
, and
when used with the format token w
outputs the sequence first second
third fourth ...
.
The string of characters between the parentheses, if present, is used to select between
other possible variations of cardinal or ordinal numbering sequences. The interpretation
of this string is
It is
The use of the a
or t
modifier disambiguates between numbering
sequences that use letters. In many languages there are two commonly used numbering
sequences that use letters. One numbering sequence assigns numeric values to letters in
alphabetic sequence, and the other assigns numeric values to each letter in some other
manner traditional in that language. In English, these would correspond to the numbering
sequences specified by the format tokens a
and i
. In some
languages, the first member of each sequence is the same, and so the format token alone
would be ambiguous. In the absence of the a
or t
modifier, the
default is
A dynamic error is raised
Note the careful distinction between conditions that are errors and conditions where fallback occurs. The principle is that an error in the syntax of the format picture will be reported by all processors, while a construct that is recognized by some implementations but not others will never result in an error, but will instead cause a fallback representation of the integer to be used.
The following notes apply when a digitpattern is used:
If groupingseparatorsigns
appear at regular intervals within the format token, then the sequence is extrapolated to
the left, so grouping separators will be used in the formatted number at every
multiple of N. For example, if the format token is 0'000
then the number one million will be formatted as 1'000'000
, while the
number fifteen will be formatted as 0'015
.
The only purpose of optionaldigitsigns is to mark the position of
groupingseparatorsigns. For example, if the format token is
#'##0
then the number one million will be formatted as
1'000'000
, while the number fifteen will be formatted as
15
. A grouping separator is included in the formatted number only
if there is a digit to its left, which will only be the case if either (a) the
number is large enough to require that digit, or (b) the number of
mandatorydigitsigns in the format token requires insignificant
leading zeros to be present.
Grouping separators are (365)1239876
. In general they are not
suitable for such purposes because (a) only single characters are allowed, and (b) they
cannot appear at the beginning or end of the number.
Numbers will never be truncated. Given the digitpattern
01
, the number three hundred will be output as 300
,
despite the absence of any optionaldigitsign.
The following notes apply when ordinal numbering is selected using the o
modifier.
In some languages, the form of numbers (especially ordinal numbers) varies depending
on the grammatical context: they may have different genders and may decline with the
noun that they qualify. In such cases the string appearing in parentheses after the
letter c
or o
may be used to indicate the variation of the
cardinal or ordinal number required.
The way in which the variation is indicated will depend on the conventions of the language.
For inflected languages that vary the ending of the word, the approach recommended
in the previous version of this specification was to indicate the required ending,
preceded by a hyphen: for example in German, appropriate values might be
o(e)
, o(er)
, o(es)
, o(en)
.
Another approach, which might usefully be adopted by an implementation based on the
opensource ICU localization library o(%spelloutordinalmasculine)
, or c(%spelloutcardinalyear)
.
The following notes apply when the primary format token is neither a digitpattern nor one of the seven other defined format tokens (A, a, i, I, w, W, Ww), but is an arbitrary token representing the number 1:
Unexpected results may occur for traditional numbering. For example, in an
implementation that supports traditional numbering system in Greek, the example
formatinteger(19, "α;t")
might return δπιιιι
or
ιθ
, depending upon whether the ancient acrophonic or late antique
alphabetic system is supported.
Unexpected results may also occur for alphabetic numbering. For example, in an
implementation that supports alphabetic numbering system in Greek, someone
writing formatinteger(19, "α;a")
might expect the nineteenth Greek
letter, #x3C4 τ
, but the implementation might return the eighteenth one,
#x3C3 σ
, because the latter is the nineteenth item in the sequence of
lowercase Greek letters in Unicode (the sequence is interrupted because of the final
form of the sigma, #x3C2 ς). Because Greek never had a final capital sigma,
Unicode has marked #x3A2, the eighteenth codepoint in the sequence of Greek capital
letters, as reserved, to ensure that every Greek uppercase letter is always 32 codepoints
less than its lowercase counterpart. Therefore, someone writing
formatinteger(18, "Α;a")
might expect the eighteenth Greek capital letter,
#x3A3 Σ
, but an implementation might return #x3a2, the eighteenth position
in the sequence of Greek capital letters, but unassigned to any character.
Expression: 


Result:  
 
Ordinal numbering in Italian: The specification  
The specification  
Expression: 

Result:  
 
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result: 
This section defines a function for formatting decimal and floating point numbers.
Function  Meaning 

fn:formatnumber  Returns a string containing a number formatted according to a given picture string and decimal format. 
This function can be used to format any numeric quantity, including an integer. For integers, however,
the fn:formatinteger
function offers additional possibilities. Note also that the picture
strings used by the two functions are not 100% compatible, though they share some options in common.
Decimal formats are defined in the static context, and the way they are defined is therefore outside the scope of this specification. XSLT and XQuery both provide custom syntax for creating a decimal format.
The static context provides a set of decimal formats. One of the decimal formats is unnamed, the others (if any)
are identified by a QName. There is always an unnamed decimal format available, but its contents are
Each decimal format provides a set of named properties.
A phrase such as "The
For any decimal format, the properties
representing characters used in a
Returns a string containing a number formatted according to a given picture string and decimal format.
The twoargument form of this function is
The threeargument form of this function is
The function formats $value
as a string using the $picture
argument and a decimal format.
The $value
argument may be of any numeric data type
(xs:double
, xs:float
, xs:decimal
, or their
subtypes including xs:integer
). Note that if an xs:decimal
is
supplied, it is not automatically promoted to an xs:double
, as such
promotion can involve a loss of precision.
If the supplied value of the $value
argument is an empty sequence, the
function behaves as if the supplied value were the xs:double
value
NaN
.
If $options
is absent, or if it is supplied as an empty sequence or an empty
map, then the number is formatted using the properties of the unnamed
decimal format in the static context.
For backwards compatibility reasons, the decimal format can be supplied as
an instance of xs:string
. If the value of the $options
argument is an xs:string
, then its value
EQName
as defined in the XPath 4.0 grammar, that is one of the following:
A lexical QName, which is expanded using the statically known namespaces. The default namespace is not used (no prefix means no namespace).
A URIQualifiedName
using the syntax Q{uri}local
,
where the URI can be zerolength to indicate a name in no namespace.
The effective value of the $options
argument is then the map
{'formatname':$FN}
where $FN
is the xs:QName
result of expanding
this EQName
.
The entries that may appear in the $options
map are as follows.
The character
represents a singlecharacter string, that is, a restriction of xs:string
with the facet length="1"
. The default value for absent options (other than
formatname
) is taken from a decimal format in the static context; the default
values shown in the table are the values used if no specific value is assigned in the
static context.
Key  Meaning 

formatname 
The name of a decimal format in the static context; if absent, the unnamed
decimal format in the static context is used. An xs:NCName
represents the local part of an xs:QName in no namespace.

decimalseparator  The character used to represent the decimal point
both in the picture string and in the formatted number.

groupingseparator  The character used to separate groups of digits
both in the picture string and in the formatted number.

exponentseparator  The character used to separate the mantissa from the exponent
in scientific notation both in the picture
string and in the formatted number.

infinity  The string used to represent the value positive or negative infinity
in the formatted number.

minussign  The character used as a minus sign in the formatted number if
there is no subpicture for formatting negative numbers.

NaN  The string used to represent the value NaN
in the formatted number.

percent  The character used as a percent sign
both in the picture string and in the formatted number.

permille  The character used as a permille sign
both in the picture string and in the formatted number.

zerodigit  Defines the characters used in the picture string to represent a mandatory digit:
for example, if the zerodigit is 0 then any of the
digits 0 to 9 may be used (interchangeably)
in the picture string to represent a mandatory digit,
and in the formatted number the characters 0 to 9
will be used to represent the digits zero to nine. The value must be
a character in Unicode category Nd with decimal digit value 0 (zero).

digit  The character used in the picture string to represent
an optional digit.

patternseparator  The character used in the picture string to separate the positive
and negative subpictures.

A base decimal format is established as follows:
If the formatname
option is present, then
the decimal format in the static context identified by this name.
Otherwise, the unnamed decimal format in the static context.
The base decimal format is then modified using the other entries in the
supplied $options
map.
The evaluation of the fn:formatnumber
function takes place in two
phases, an analysis phase described in
The analysis phase takes as its inputs the
The result of the function is the formatted string representation of the supplied number.
A dynamic error is raised $options
argument is supplied as an xs:string
that isURIQualifiedName
, or if it uses a prefix that is not found in the
statically known namespaces; or if the static context does not contain a declaration of
a decimal format with a matching expanded QName; or if $options?formatname
is present and the static context does
not contain a declaration of a decimal format whose name matches $options?formatname
.
If the processor is able to detect the
error statically (for example, when the argument is supplied as a string literal), then
the processor
A dynamic error is raised $format
is not valid for the associated property, or if the properties
of the decimal format resulting from a supplied $options
map do not have distinct values.
A string is an ordered sequence of characters, and this specification uses terms such as “left” and “right”, “preceding” and “following” in relation to this ordering, irrespective of the position of the characters when visually rendered on some output medium. Both in the picture string and in the result string, digits with higher significance (that is, representing higher powers of ten) always precede digits with lower significance, even when the rendered text flow is from right to left.
In previous versions of XSLT and XQuery, decimal formats were typically defined in the
static context using custom declarations (<xsl:decimalformat>
in XSLT,
declare decimalformat
in XQuery) and then selected by name in a call on
fn:formatnumber
. This mechanism remains available, but in 4.0,
it may be more convenient to dispense with these
declarations, and instead to define a decimal format as a map bound to a global
variable, which can be referenced in the $options
argument of the
fn:formatnumber
call.
The following examples assume a default decimal format in which the chosen digits are
the ASCII digits 09, the decimal separator is  
Expression: 


Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression:  
Result:  
The following examples assume the existence of a decimal format named
 
Expression: 

Result:  
Expression:  
Result:  
The following examples assume that the exponent separator
in decimal format  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result: 
Changed in 4.0: The decimal format name can now be supplied as a value of type xs:QName
,
as an alternative to supplying a lexical QName as an instance of xs:string
.
This differs from the formatnumber
function previously defined in XSLT 2.0 in that
any digit can be used in the picture string to represent a mandatory digit: for example the picture
strings "000"
, "001"
, and "999"
are equivalent.
The digits will all be from the same decimal digit family,
specifically, the sequence of ten consecutive digits starting with the digit assigned to the zerodigit property.
This change is to align formatnumber
(which previously used "000"
) with formatdateTime
(which used 001
).
A dynamic error is raised
A picturestring consists either of a subpicture, or of
two subpictures separated by the
A subpicture
A subpicture
The mantissa part of a
subpicture (defined below)
A subpicture
A subpicture
A subpicture
The integer part of a subpicture (defined below)
A character that matches the
A subpicture that contains a
If a subpicture contains a character treated as an
exponentseparatorsign then this
The mantissa part of the subpicture is defined as the part that appears to the left of the exponentseparatorsign if there is one, or the entire subpicture otherwise. The exponent part of the subpicture is defined as the part that appears to the right of the exponentseparatorsign; if there is no exponentseparatorsign then the exponent part is absent.
The integer part of the subpicture is defined as the part that
appears to the left of the
The fractional part of the subpicture is defined as that
part of the mantissa part that
appears to the right of the
This phase of the algorithm analyzes
the
Several variables are associated with each subpicture. If there are two subpictures, then these rules are applied to one subpicture to obtain the values that apply to positive and unsigned zero numbers, and to the other to obtain the values that apply to negative numbers. If there is only one subpicture, then the values for both cases are derived from this subpicture.
The variables are as follows:
The integerpartgroupingpositions is a sequence of integers
representing the positions of grouping separators within the integer part of the
subpicture. For each
The grouping is defined to be
There is an least one groupingseparator in the integer part of the subpicture.
There is a positive integer G (the grouping size) such that the position of every groupingseparator in the integer part of the subpicture is a positive integer multiple of G.
Every position in the integer part of the subpicture that is a positive integer multiple of G is occupied by a groupingseparator.
If the grouping is regular, then the integerpartgroupingpositions sequence contains all integer multiples of G as far as necessary to accommodate the largest possible number.
The minimumintegerpartsize is an integer indicating the minimum number of digits that will
appear to the left of the decimalseparator character. It is initially set to
the number of
There is no maximum integer part size. All significant digits in the integer part of the
number will be displayed, even if this exceeds the number of
The scaling factor is a nonnegative integer used to determine the scaling of the mantissa
in exponential notation. It is set to the number of
The prefix is set to contain all passive characters
in the subpicture to the left of the leftmost active character.
If the picture string contains only one subpicture,
the prefix
for the negative subpicture is set by concatenating the
The fractionalpartgroupingpositions is a sequence of integers
representing the positions of grouping separators within the fractional part of the
subpicture. For each
There is no need to extrapolate grouping positions on the fractional side,
because the number of digits in the output will never exceed the number of
The minimumfractionalpartsize is set to the number of
The maximumfractionalpartsize is set to the total number of
If the effect of the above rules is that minimumintegerpartsize and maximumfractionalpartsize are both zero, then an adjustment is applied as follows:
If an exponent separator is present then:
minimumfractionalpartsize is changed to 1 (one).
maximumfractionalpartsize is changed to 1 (one).
This has the effect that with the picture #.e9
, the value 0.123
is formatted as 0.1e0
Otherwise:
minimumintegerpartsize is changed to 1 (one).
This has the effect that with the picture #
, the value 0.23
is formatted
as 0
If all the following conditions are true:
An exponent separator is present
The minimumintegerpartsize is zero
There is at least one
then the minimumintegerpartsize is changed to 1 (one).
This has the effect that with the picture .9e9
, the value 0.1
is formatted
as .1e0
, while with the picture #.9e9
, it is formatted as 0.1e0
If (after making the above adjustments) the minimumintegerpartsize and the minimumfractionalpartsize are both zero, then the minimumfractionalpartsize is set to 1 (one).
The minimumexponentsize is set to the number of
The rules for the syntax of the picture string ensure that if an exponent separator is present, then the minimumexponentsize will always be greater than zero.
The suffix is set to contain all passive characters to the right of the rightmost active character in the subpicture.
If there is only one subpicture, then all variables
for positive numbers and negative numbers will be the same, except for
prefix: the prefix for negative numbers will
be preceded by the
This section describes the second phase of processing of the
fn:formatnumber
function. This phase takes as input a number to be formatted
(referred to as the fn:formatnumber
function.
The algorithm for this second stage of processing is as follows:
If the input number is NaN
(not a number), the result is the
value of the
In the rules below, the positive subpicture and its associated variables are used
if the input number is positive, and the negative subpicture and its associated
variables are used if it is negative. For xs:double
and xs:float
,
negative zero is taken as negative, positive zero as positive. For xs:decimal
and xs:integer
, the positive subpicture is used for zero.
The adjusted number is determined as follows:
If the subpicture contains a
If the subpicture contains a
Otherwise, the adjusted number is the input number.
If the multiplication causes numeric overflow, no error occurs, and the adjusted number is positive or negative infinity as appropriate.
If the adjusted number is positive or negative infinity, the result is the
concatenation of the appropriate prefix, the value of the
If the minimum exponent size is nonzero,
The primitive type of the mantissa is the same as the primitive type of the adjusted number (integer, decimal, float, or double).
The mantissa multiplied by ten to the power of the exponent is equal to the adjusted number.
The mantissa
If the minimum exponent size is zero, then the mantissa is the adjusted number and there is no exponent.
If the minimum exponent size is nonzero and the adjusted number is zero, then the mantissa is the adjusted number and the exponent is zero.
The mantissa is converted (if necessary) to
an xs:decimal
value,
using an implementation of xs:decimal
that imposes no limits on the
totalDigits
or fractionDigits
facets. If there are several
such values that
are numerically equal to the mantissa (bearing in mind that if the
mantissa is an xs:double
or xs:float
, the comparison will be done by
converting the decimal value back to an xs:double
or xs:float
), the one that
is chosen maximumfractionalpartsize
digits in
its fractional part. The rounded number is defined to be the result of
converting the mantissa to an xs:decimal
value, as described above,
and then calling the function fn:roundhalftoeven
with this converted number
as the first argument and the maximumfractionalpartsize
as the second
argument, again with no limits on the totalDigits
or fractionDigits
in the
result.
The absolute value of the rounded number is converted to a string in decimal notation,
using the digits in the
If the number of digits to the left of the
If the number of digits to the right of the
For each integer N in the integerpartgroupingpositions list,
a
For each integer N in the fractionalpartgroupingpositions list,
a
If there is no
If an exponent exists, then the string
produced from the mantissa as described above is extended with
the following, in order:
(a) the
The result of the function is the concatenation of the appropriate prefix, the string conversion of the number as obtained above, and the appropriate suffix.
The functions in this section perform trigonometric and other mathematical calculations on xs:double
values. They
are provided primarily for use in applications performing geometrical computation, for example when generating
SVG graphics.
Functions are provided to support the six most commonly used trigonometric calculations: sine, cosine and tangent, and their inverses arc sine, arc cosine, and arc tangent. Other functions such as secant, cosecant, and cotangent are not provided because they are easily computed in terms of these six.
The functions in this section (with the exception of math:pi
)
are specified by reference to xs:double
values. The IEEE specification
applies with the following caveats:
IEEE states that the preferred quantum is languagedefined. In this
specification, it is
IEEE states that certain functions should raise the inexact exception if the result is inexact. In this specification, this exception if it occurs does not result in an error. Any diagnostic information is outside the scope of this specification.
IEEE defines various rounding algorithms for inexact results, and states
that the choice of rounding direction, and the mechanisms for influencing this choice,
are languagedefined. In this specification, the rounding direction and any mechanisms for
influencing it are
Certain operations (such as taking the square root of a negative number)
are defined in IEEE to signal the invalid operation exception and return a
quiet NaN
. In this specification, such operations return NaN
and do not raise an error. The same policy applies to operations (such as taking
the logarithm of zero) that raise a dividebyzero exception. Any diagnostic
information is outside the scope of this specification.
Operations whose mathematical result is greater than the largest finite xs:double
value are defined in IEEE to signal the overflow exception; operations whose mathematical
result is closer to zero than the smallest nonzero xs:double
value are similarly
defined in IEEE to signal the underflow exception. The treatment of these exceptions in
this specification is defined in
Function  Meaning 

math:pi  Returns an approximation to the mathematical constant π. 
math:exp  Returns the value of e^{x} where x is the argument value. 
math:exp10  Returns the value of 10 ^{x}, where x is the supplied argument value. 
math:log  Returns the natural logarithm of the argument. 
math:log10  Returns the baseten logarithm of the argument. 
math:pow  Returns the result of raising the first argument to the power of the second. 
math:sqrt  Returns the nonnegative square root of the argument. 
math:sin  Returns the sine of the argument. The argument is an angle in radians. 
math:cos  Returns the cosine of the argument. The argument is an angle in radians. 
math:tan  Returns the tangent of the argument. The argument is an angle in radians. 
math:asin  Returns the arc sine of the argument. 
math:acos  Returns the arc cosine of the argument. 
math:atan  Returns the arc tangent of the argument. 
math:atan2  Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive xaxis. 
Returns an approximation to the mathematical constant π.
This function is
This function returns the xs:double
value whose lexical representation is
3.141592653589793e0
Expression  Result 

2 * math:pi()  
The expression 
Returns the value of e^{x} where x is the argument value.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the mathematical constant e raised to the power of
$value
, as defined in the exp
function applied to 64bit binary floating point values.
The treatment of overflow and underflow is defined in
Expression  Result 

math:exp(())  
math:exp(0)  
math:exp(1)  (approximately) 
math:exp(2)  
math:exp(1)  
math:exp(math:pi())  
math:exp(xs:double('NaN'))  
math:exp(xs:double('INF'))  
math:exp(xs:double('INF')) 
Returns the value of 10
^{x}, where x is the supplied argument value.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is ten raised to the power of $value
, as defined in the
exp10
function applied
to 64bit binary floating point values.
The treatment of overflow and underflow is defined in
Expression  Result 

math:exp10(())  
math:exp10(0)  
math:exp10(1)  
math:exp10(0.5)  
math:exp10(1)  
math:exp10(xs:double('NaN'))  
math:exp10(xs:double('INF'))  
math:exp10(xs:double('INF')) 
Returns the natural logarithm of the argument.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the natural logarithm of $value
, as defined in the
log
function applied
to 64bit binary floating point values.
The treatment of divideByZero
and invalidOperation
exceptions
is defined in INF
, and if it is negative, the result is NaN
Expression  Result 

math:log(())  
math:log(0)  
math:log(math:exp(1))  
math:log(1.0e3)  
math:log(2)  
math:log(1)  
math:log(xs:double('NaN'))  
math:log(xs:double('INF'))  
math:log(xs:double('INF')) 
Returns the baseten logarithm of the argument.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the base10 logarithm of $value
, as defined in the
log10
function applied
to 64bit binary floating point values.
The treatment of divideByZero
and invalidOperation
exceptions
is defined in INF
, and if it is negative, the result is NaN
Expression  Result 

math:log10(())  
math:log10(0)  
math:log10(1.0e3)  
math:log10(1.0e3)  
math:log10(2)  
math:log10(1)  
math:log10(xs:double('NaN'))  
math:log10(xs:double('INF'))  
math:log10(xs:double('INF')) 
Returns the result of raising the first argument to the power of the second.
This function is
If $x
is the empty sequence, the function returns the empty sequence.
If $y
is an instance of xs:integer
, the result is
$x
raised to the power of $y
as defined in the pown
function applied to a
64bit binary floating point value and an integer.
Otherwise $y
is converted to an xs:double
by numeric
promotion, and the result is $x
raised to the power of
$y
as defined in the pow
function applied to two 64bit binary floating point values.
The treatment of the divideByZero
and invalidOperation
exceptions is defined in
Expression  Result 

math:pow((), 93.7)  
math:pow(2, 3)  
math:pow(2, 3)  
math:pow(2, 3)  
math:pow(2, 3)  
math:pow(2, 0)  
math:pow(0, 0)  
math:pow(xs:double('INF'), 0)  
math:pow(xs:double('NaN'), 0)  
math:pow(math:pi(), 0)  
math:pow(0e0, 3)  
math:pow(0e0, 4)  
math:pow(0e0, 3)  
math:pow(0, 4)  
math:pow(0e0, 3)  
math:pow(0e0, 4)  
math:pow(0e0, 3)  
math:pow(0, 4)  
math:pow(16, 0.5e0)  
math:pow(16, 0.25e0)  
math:pow(0e0, 3.0e0)  
math:pow(0e0, 3.0e0)  
math:pow(0e0, 3.1e0)  
math:pow(0e0, 3.1e0)  
math:pow(0e0, 3.0e0)  
math:pow(0e0, 3.0e0)  
math:pow(0e0, 3.1e0)  
math:pow(0e0, 3.1e0)  
math:pow(1, xs:double('INF'))  
math:pow(1, xs:double('INF'))  
math:pow(1, xs:double('INF'))  
math:pow(1, xs:double('INF'))  
math:pow(1, xs:double('NaN'))  
math:pow(2.5e0, 2.0e0)  
math:pow(2.5e0, 2.00000001e0) 
Returns the nonnegative square root of the argument.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the mathematical nonnegative square root of $value
as defined in the squareRoot
function applied to 64bit binary floating point values.
The treatment of the invalidOperation
exception is defined in NaN
.
If $value
is positive or negative zero, positive infinity, or
NaN
, then the result is $value
. (Negative zero is the only
case where the result can have negative sign)
Expression  Result 

math:sqrt(())  
math:sqrt(0.0e0)  
math:sqrt(0.0e0)  
math:sqrt(1.0e6)  
math:sqrt(2.0e0)  
math:sqrt(2.0e0)  
math:sqrt(xs:double('NaN'))  
math:sqrt(xs:double('INF'))  
math:sqrt(xs:double('INF')) 
Returns the sine of the argument. The argument is an angle in radians.
This function is
If $radians
is the empty sequence, the function returns the empty
sequence.
Otherwise the result is the sine of $radians
(which is treated as an angle in
radians) as defined in the sin
function applied to 64bit binary floating point values.
The treatment of the invalidOperation
and underflow
exceptions
is defined in
If $radians
is positive or negative zero, the result is
$radians
.
If $radians
is positive or negative infinity, or NaN
,
then the result is NaN
.
Otherwise the result is always in the range 1.0e0 to +1.0e0
Expression  Result 

math:sin(())  
math:sin(0)  
math:sin(0.0e0)  
math:sin(math:pi() div 2)  (approximately) 
math:sin(math:pi() div 2)  (approximately) 
math:sin(math:pi())  (approximately) 
math:sin(xs:double('NaN'))  
math:sin(xs:double('INF'))  
math:sin(xs:double('INF')) 
Returns the cosine of the argument. The argument is an angle in radians.
This function is
If $radians
is the empty sequence, the function returns the empty
sequence.
If $radians
is positive or negative infinity, or NaN
,
then the result is NaN
.
Otherwise the result is the cosine of $
radians (which is treated as an angle in
radians) as defined in the cos
function applied to 64bit binary floating point values.
The treatment of the invalidOperation
exception is defined in
If $radians
is positive or negative zero, the result is
$radians
.
If $radians
is positive or negative infinity, or NaN
,
then the result is NaN
.
Otherwise the result is always in the range 1.0e0 to +1.0e0
Expression  Result 

math:cos(())  
math:cos(0)  
math:cos(0.0e0)  
math:cos(math:pi() div 2)  (approximately) 
math:cos(math:pi() div 2)  (approximately) 
math:cos(math:pi())  (approximately) 
math:cos(xs:double('NaN'))  
math:cos(xs:double('INF'))  
math:cos(xs:double('INF')) 
Returns the tangent of the argument. The argument is an angle in radians.
This function is
If $radians
is the empty sequence, the function returns the empty
sequence.
Otherwise the result is the tangent of $radians
(which is treated as an angle
in radians) as defined in the tan
function applied to 64bit binary floating point values.
The treatment of the invalidOperation
and underflow
exceptions
is defined in
If $radians
is positive or negative infinity, or NaN
,
then the result is NaN
.
Expression  Result 

math:tan(())  
math:tan(0)  
math:tan(0.0e0)  
math:tan(math:pi() div 4)  (approximately) 
math:tan(math:pi() div 4)  (approximately) 
1 div math:tan(math:pi() div 2)  (approximately)

1 div math:tan(math:pi() div 2)  (approximately)

math:tan(math:pi())  (approximately) 
math:tan(xs:double('NaN'))  
math:tan(xs:double('INF'))  
math:tan(xs:double('INF')) 
Returns the arc sine of the argument.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the arc sine of $value
as defined in the asin
function applied to 64bit binary floating point values.
The result is in the range π/2 to +π/2 radians.
The treatment of the invalidOperation
and underflow
exceptions
is defined in
If $value
is positive or negative zero, the result is $value
.
If $value
is NaN
, or if its absolute value is greater than one,
then the result is NaN
.
In other cases the result is an xs:double
value representing an angle
θ in radians in the range π/2 <=
θ <= +
π/2
.
Expression  Result 

math:asin(())  
math:asin(0)  
math:asin(0.0e0)  
math:asin(1.0e0)  (approximately) 
math:asin(1.0e0)  (approximately) 
math:asin(2.0e0)  
math:asin(xs:double('NaN'))  
math:asin(xs:double('INF'))  
math:asin(xs:double('INF')) 
Returns the arc cosine of the argument.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the arc cosine of $value
, as defined in the acos
function applied to 64bit binary floating point values.
The result is in the range zero to +π radians.
The treatment of the invalidOperation
exception is defined in
If $value
is NaN
, or if its absolute value is greater than one,
then the result is NaN
.
In other cases the result is an xs:double
value representing an angle
θ in radians in the range 0 <=
θ <=
+
π.
Expression  Result 

math:acos(())  
math:acos(0)  (approximately) 
math:acos(0.0e0)  (approximately) 
math:acos(1.0e0)  
math:acos(1.0e0)  (approximately) 
math:acos(2.0e0)  
math:acos(xs:double('NaN'))  
math:acos(xs:double('INF'))  
math:acos(xs:double('INF')) 
Returns the arc tangent of the argument.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the arc tangent of $value
, as defined
in the atan
function applied to 64bit binary floating point values.
The result is in the range π/2
to +π/2 radians.
The treatment of the underflow
exception is defined in
If $value
is positive or negative zero, the result is $value
.
If $value
is NaN
then the result is NaN
.
In other cases the result is an xs:double
value representing an angle
θ in radians in the range π/2 <=
θ <= +
π/2
.
Expression  Result 

math:atan(())  
math:atan(0)  
math:atan(0.0e0)  
math:atan(1.0e0)  (approximately) 
math:atan(1.0e0)  (approximately) 
math:atan(xs:double('NaN'))  
math:atan(xs:double('INF'))  (approximately) 
math:atan(xs:double('INF'))  (approximately) 
Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive xaxis.
This function is
The result is the value of atan2(y, x)
as defined in the atan2
function applied to
64bit binary floating point values. The result is in the range π
to +π radians.
The treatment of the underflow
exception is defined in
If either argument is NaN
then the result is NaN
.
If $x
is positive, then the value of
atan2($y, $x)
is atan($y div $x)
.
If $x
is negative, then:
If $y
is positive, then the value of atan2($y, $x)
is
atan($y div $x) +
π.
If $y
is negative, then the value of atan2($y, $x)
is
atan($y div $x) 
π.
Some results for special values of the arguments are shown in the examples below.
Expression  Result 

math:atan2(+0.0e0, 0.0e0)  
math:atan2(0.0e0, 0.0e0)  
math:atan2(+0.0e0, 0.0e0)  
math:atan2(0.0e0, 0.0e0)  
math:atan2(1, 0.0e0)  
math:atan2(+1, 0.0e0)  
math:atan2(0.0e0, 1)  
math:atan2(+0.0e0, 1)  
math:atan2(0.0e0, +1)  
math:atan2(+0.0e0, +1) 
Function  Meaning 

fn:randomnumbergenerator  Returns a random number generator, which can be used to generate sequences of random numbers. 
Returns a random number generator, which can be used to generate sequences of random numbers.
This function is
The function returns a random number generator. A random number generator is represented as a value of type
randomnumbergeneratorrecord
, defined as follows:
That is, the result of the function is a map containing three entries. The keys of each entry are strings:
The entry with key "number"
holds a random number; it is an xs:double
greater than or equal
to zero (0.0e0), and less than one (1.0e0).
The entry with key "next"
is a zeroarity function that can be called to return another random number
generator.
The properties of this function are as follows:
name: absent
parameter names: ()
signature: () => map(xs:string, item())
nonlocal variable bindings: none
implementation: implementationdependent
The entry with key "permute"
is a function with arity 1 (one), which takes an arbitrary sequence
as its argument, and returns a random permutation of that sequence.
The properties of this function are as follows:
name: absent
parameter names: "arg"
signature: (item()*) => item()*
nonlocal variable bindings: none
implementation: implementationdependent
Calling the fn:randomnumbergenerator
function with no arguments is equivalent to calling the singleargument
form of the function with an implementationdependent seed.
Calling the fn:randomnumbergenerator
function with an empty sequence as $seed
is equivalent to calling the singleargument form of the function with an implementationdependent seed.
If a $seed
is supplied, it may be an atomic value of any type.
Both forms of the function are
The value of the number
entry xs:double
values are equally likely to be chosen
The function returned in the permute
entry
The map returned by the fn:randomnumbergenerator
function
It is not meaningful to ask whether the functions returned in the next
and permute
functions resulting from two separate calls with the same seed are “the same function”, but the functions must be equivalent in the sense
that calling them produces the same sequence of random numbers.
The repeatability of the results of function calls in different execution scopes is outside the scope of this
specification. It is fn:currentdateTime()
as a seed.)
The specification does not place strong conformance requirements on the actual randomness of the result; this is left to the implementation. It is desirable, for example, when generating a sequence of random numbers that the sequence should not get into a repeating loop; but the specification does not attempt to dictate this.
The following example returns a random permutation of the integers in the range
 
 
The following example returns a 10% sample of the items in an input sequence  
 
The following XQuery code produces a random sequence of 200  
An equivalent result can be achieved with  
This section specifies functions and operators on the xs:string
datatype and the datatypes derived from it.
The operators described in this section are defined on the following types.
They also apply to userdefined types derived by restriction from the above types.
Function  Meaning 

fn:codepointstostring  Returns an xs:string whose characters have supplied 
fn:stringtocodepoints  Returns the sequence of xs:string value. 
Returns an xs:string
whose characters have supplied
This function is
The function returns the string made up from the $values
. This will be the zerolength string if $values
is the empty sequence.
A dynamic error is raised $values
is not a
Expression  Result 

codepointstostring((66, 65, 67, 72))  
codepointstostring((2309, 2358, 2378, 2325))  
codepointstostring(())  
codepointstostring(0)  Raises error FOCH0001. 
Returns the sequence of xs:string
value.
This function is
The function returns a sequence of integers, each integer being the Unicode $value
.
If $value
is a zerolength string or the empty sequence, the function returns
the empty sequence.
Expression  Result 

stringtocodepoints("Thérèse") 
Function  Meaning 

fn:codepointequal  Returns true if two strings are equal, considered codepointbycodepoint. 
fn:collation  Constructs a collation URI with requested properties. 
fn:collationkey  Given a string value and a collation, generates an internal value called a collation key, with the property that the matching and ordering of collation keys reflects the matching and ordering of strings under the specified collation. 
fn:containstoken  Determines whether or not any of the supplied strings, when tokenized at whitespace boundaries, contains the supplied token, under the rules of the supplied collation. 
A collation is a specification of the manner in which xs:string
or a type derived from xs:string
are
compared (or, equivalently, sorted), the comparisons are inherently
performed according to some collation (even if that collation is defined
entirely on codepoint values). The
Collations can indicate that two different codepoints are, in fact, equal for comparison purposes (e.g., “v” and “w” are considered equivalent in some Swedish collations). Strings can be compared codepointbycodepoint or in a linguistically appropriate manner, as defined by the collation.
Some collations, especially those based on the
Unicode Collation Algorithm (see
The
Collations may or may not perform Unicode normalization on strings before comparing them.
This specification assumes that collations are named and that the collation
name may be provided as an argument to string functions. Functions that
allow specification of a collation do so with an argument whose type is
xs:string
but whose lexical form must conform to an
xs:anyURI
.
This specification also defines the manner in which a
default collation is determined if the collation argument is not specified
in calls of functions that use a collation but allow it to be omitted.
If the collation is specified using a relative URI reference,
it is resolved relative to an
Previous versions of this specification stated that it must
be resolved against the
This specification does not define whether or not the collation URI is
dereferenced. The collation URI may be an abstract identifier, or it may
refer to an actual resource describing the collation. If it refers to a
resource, this specification does not define the nature of that resource.
One possible candidate is that the resource is a locale description
expressed using the Locale Data Markup Language: see
Functions such as fn:compare
and fn:max
that
compare xs:string
values use a single collation URI to identify
all aspects of the collation rules. This means that any parameters such as
the strength of the collation must be specified as part of the collation
URI. For example, suppose there is a collation
http://www.example.com/collations/French
that refers to a French collation that compares on the basis of
base characters. Collations that use the same basic rules, but with higher
strengths, for example, base characters and accents, or base characters,
accents and case, would need to be given different names, say
http://www.example.com/collations/French1
and
http://www.example.com/collations/French2
.
Note that some specifications use the term collation to refer to
an algorithm that can be parameterized, but in this specification, each
possible parameterization is considered to be a distinct collation.
The XQuery/XPath static context includes a provision for a default collation
that can be used for string comparisons and ordering operations. See the
description of the static context in
XML allows elements to specify the xml:lang
attribute to
indicate the language associated with the content of such an element.
This specification does not use xml:lang
to identify the
default collation because using
xml:lang
does not produce desired effects when the two
strings to be compared have different xml:lang
values or
when a string is multilingual.
http://www.w3.org/2005/xpathfunctions/collation/codepoint
identifies
a collation which must be recognized by every implementation: it is referred to as
the
The Unicode codepoint collation does not perform any normalization on the supplied strings.
The collation is defined as follows. Each of the two strings is
converted to a sequence of integers using the fn:stringtocodepoints
function. These two sequences $A
and $B
are then compared as follows:
If both sequences are empty, the strings are equal.
If one sequence is empty and the other is not, then the string corresponding to the empty sequence is less than the other string.
If the first integer in $A
is less than the first integer in $B
, then
the string corresponding to $A
is less than the string corresponding to
$B
.
If the first integer in $A
is greater than the first integer in $B
, then
the string corresponding to $A
is greater than the string corresponding to
$B
.
Otherwise (the first pair of integers are equal), the result is obtained
by applying the same rules recursively to fn:tail($A)
and
fn:tail($B)
While the Unicode codepoint collation does not produce results suitable for quality publishing of printed indexes or directories, it is adequate for many purposes where a restricted alphabet is used, such as sorting of vehicle registrations.
This specification defines a family of collation URIs representing tailorings of the Unicode Collation
Algorithm (UCA) as defined in
This family of URIs use the scheme and path http://www.w3.org/2013/collation/UCA
followed by an optional query part. The query part, if present, consists of a question mark followed
by a sequence of zero or more semicolonseparated parameters. Each parameter is a keywordvalue pair, the
keyword and value being separated by an equals sign.
All implementations must recognize URIs in this family in the collation
argument of functions that
take a collation argument.
If the fallback
parameter is
present with the value no
, then the implementation fallback
parameter
is omitted or takes the value yes
, and if the collation URI is wellformed according to the rules in this section,
then the implementation http://www.w3.org/2013/collation/UCA?lang=se;fallback=yes
and the implementation does not include a fully
conformant version of the UCA tailored for Swedish, then it
If two query parameters use the same keyword then the last one wins. If a query parameter uses a keyword or value which is not
defined in this specification then the meaning is fallback
parameter is present with the value no
it should reject
the collation as unsupported, otherwise it should ignore the unrecognized parameter.
The following query parameters are defined. If any parameter is absent, the default is
Keyword  Values  Meaning 

fallback  yes  no (default yes)  Determines whether the processor uses a fallback collation if a conformant collation is not available. 
lang  language code: a string in the lexical space of xs:language .  The language whose collation conventions are to be used. 
version  string  The version number of the UCA to be used. 
strength  primary  secondary  tertiary  quaternary  identical, or 12345 as synonyms (default tertiary / 3)  The collation strength as defined in UCA. Primary
strength takes only the base form of the character into account (so A=a=Ä=ä); secondary strength ignores case but considers accents
and diacritics as significant (so A=a and Ä=ä but ä≠a); tertiary considers case as significant (A≠a≠Ä≠ä); quaternary strength always considers as significant spaces and punctuation
(database≠database; if maxVariable is punct or higher and
alternate is not nonignorable , lower strengths will treat database=database). 
maxVariable  space  punct  symbol  currency (default punct) 
Given the sequence space , punct , symbol , currency ,
all characters in the specified group and earlier groups are treated as “noise” characters
to be handled as defined by the alternate parameter. For example, maxVariable=punct indicates
that characters classified as whitespace or punctuation get this treatment. 
alternate  nonignorable  shifted  blanked (default nonignorable)  Controls the handling of characters such as spaces and hyphens;
specifically, the "noise" characters in the groups selected by the maxVariable parameter. The value nonignorable
indicates that such characters are treated as distinct at the primary level (so data base sorts before database );
shifted indicates that they are used to differentiate two strings only at the quaternary level,
and blanked indicates that they are taken into account only at the identical level. 
backwards  yes  no (default no)  The value backwards=yes indicates that the last accent in the
string is the most significant. 
normalization  yes  no (default no)  Indicates whether strings are converted to normalization form D. 
caseLevel  yes  no (default no)  When used with primary strength, setting caseLevel=yes has the effect of ignoring accents
while taking account of case. 
caseFirst  upper  lower (default lower)  Indicates whether uppercase precedes lowercase or vice versa. 
numeric  yes  no (default no)  When numeric=yes is specified, a sequence of consecutive digits is interpreted as a number,
for example chap2 sorts before chap12 . 
reorder  a commaseparated sequence of reorder codes, where a reorder code is one of space , punct ,
symbol , currency , digit , or a fourletter script code defined in  Determines the relative ordering of text in different scripts; for example the value digit,Grek,Latn indicates
that digits precede Greek letters, which precede Latin letters. 
This list excludes parameters that are inconvenient to express in a URI, or that are applicable only to substring matching.
UCA collation URIs can be conveniently generated using the
fn:collation
function.
The collation URI http://www.w3.org/2005/xpathfunctions/collation/htmlasciicaseinsensitive
must be recognized
by every implementation. It is class
attribute values.
The collation is defined as follows:
Let $HACI
be the collation URI
"http://www.w3.org/2005/xpathfunctions/collation/htmlasciicaseinsensitive"
.
Let $UCC
be the Unicode Codepoint Collation URI
http://www.w3.org/2005/xpathfunctions/collation/codepoint
.
Let $lc
be the function
fn:translate(?, "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "abcdefghijklmnopqrstuvwxyz")
.
Then for any two strings $A
and $B
, the result
of the comparison fn:compare($A, $B, $HACI)
is defined to be the same as
the result of fn:compare($lc($A), $lc($B), $UCC)
.
HTML5 defines the semantics of equality matching using this collation; fn:contains
; each Unicode codepoint is a single collation unit.
The corresponding HTML5 definition is: A string A is an ASCII caseinsensitive match for a string B, if the ASCII lowercase of A is the ASCII lowercase of B.
Many functions have a signature that includes a $collation
argument, which is generally optional and takes defaultcollation()
as its default value.
The collation to use for these functions is determined by the following rules:
If the function specifies an explicit collation, CollationA (e.g., if
the optional collation argument is specified in a call of the
fn:compare
function), then:
If CollationA is supported by the implementation, then CollationA is used.
Otherwise, a dynamic error is raised
If no collation is explicitly specified for the function
$collation
argument is omitted or is set to an
empty sequence)
If CollationB is supported by the implementation, then CollationB is used.
Otherwise, a dynamic error is raised
Because the set of collations that are supported is
If the value of the collation argument is a relative URI reference, it is resolved against the baseURI from the
static context. If it is a relative URI reference and cannot be resolved, perhaps because the baseURI property in the static context
is absent, a dynamic error is raised
There is no explicit requirement that the string used as a collation URI be a valid URI.
Implementations will in many cases reject such strings on the grounds that do not identify a supported collation; they
may also cause an error if they cannot be resolved against the
Returns true
if two strings are equal, considered codepointbycodepoint.
This function is
If either argument is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns true
or false
depending on
whether $value1
is equal to
$value2
, according to the Unicode codepoint collation
(http://www.w3.org/2005/xpathfunctions/collation/codepoint
).
This function allows xs:anyURI
values to be compared without having to
specify the Unicode codepoint collation.
Expression  Result 

codepointequal("abcd", "abcd")  
codepointequal("abcd", "abcd ")  
codepointequal("", "")  
codepointequal("", ())  
codepointequal((), ()) 
Constructs a collation URI with requested properties.
This function is
The function is supplied with a map defining the properties required of the collation, and returns a collation URI with these properties.
Specifically:
It first constructs a string in the form of a URI with the scheme and path
http://www.w3.org/2013/collation/UCA
followed by an optional
query part. The query part is absent if options
is empty.
Otherwise it consists of a question mark followed
by a sequence of one or more semicolonseparated parameters. Each parameter
is a keywordvalue pair, the keyword and value being separated by an equals sign.
There is one keywordvalue pair for each entry in the options
map:
the keyword is the same as the string value of the key in the map, and the value
is the string value of the corresponding value, except where the value is of
type xs:boolean
, in which case true
and false
are translated to yes
and no
.
It then returns this string if it is a collation URI supported by the
implementation, and raises an error
The properties available are as defined for the Unicode Collation Algorithm
(see
The
If the option key is of type xs:string
, xs:anyURI
,
or xs:untypedAtomic
then it is converted to a string, and produces
a URI query parameter which is handled as described in
If the option key is of any other type then the function fails with a
type error
The following options are defined:
Key  Meaning 

fallback  See

lang  See

version  See

strength  See

maxVariable  See

alternate  See

backwards  See

normalization  See

caseLevel  See

caseFirst  See

numeric  See

reorder  See

If no suitable collation is available, the function raises an error, rather than returning a URI that fails when subsequently used.
There is no guarantee that the returned collation URI is usable if used within a different execution scope.
An error is raised {'fallback':true()}
.
A type error is raised options
includes an entry whose key is not of
type xs:string
, xs:anyURI
,
or xs:untypedAtomic
, or whose corresponding value
is not castable to xs:string
.
Expression: 


Result:  
Expression: 

Result:  
Expression: 

Result:  
The expression 
Given a string value and a collation, generates an internal value called a collation key, with the property that the matching and ordering of collation keys reflects the matching and ordering of strings under the specified collation.
This function is
Calling the oneargument version of this function is equivalent to calling the twoargument version supplying the default collation as the second argument.
The function returns an $K1
and $K2
:
collationkey($K1, $C) eq collationkey($K2, $C)
if and only if
compare($K1, $K2, $C) eq 0
collationkey($K1, $C) lt collationkey($K2, $C)
if and only if
compare($K1, $K2, $C) lt 0
The collation used by this function is determined according to the rules in xs:base64Binary
values
to ensure unambiguous and contextfree comparison semantics.
An implementation is free to generate a collation key in any convenient way provided
that it always generates the same collation key for two strings that are equal under the
collation, and different collation keys for strings that are not equal. This holds only
within a single
It is possible to define collations that do not have the ability to generate collation
keys. Supplying such a collation will cause the function to fail. The ability to
generate collation keys is an
An error is raised
The function is provided primarily for use with maps. If a map is required where
codepoint equality is inappropriate for comparing keys, then a common technique is to
normalize the key so that equality matching becomes feasible. There are many ways
keys can be normalized, for example by use of functions such as
fn:uppercase
, fn:lowercase
,
fn:normalizespace
, or fn:normalizeunicode
, but this
function provides a way of normalizing them according to the rules of a specified
collation. For example, if the collation ignores accents, then the function will
generate the same collation key for two input strings that differ only in their use of
accents.
The result of the function is defined to be an xs:base64Binary
value. Binary values
are chosen because they have unambiguous and contextfree comparison semantics, because the value space
is unbounded, and because the ordering rules are such that between any two values in the ordered value space, an
arbitrary number of further values can be interpolated. The choice between xs:base64Binary
and xs:hexBinary
is arbitrary; the only operation that behaves differently between the two binary
data types is conversion to/from a string, and this operation is not one that is normally required for
effective use of collation keys.
For collations based on the Unicode Collation Algorithm, an algorithm for computing
collation keys is provided in
The fact that collation keys are ordered can be exploited in XQuery, whose order by
clause does not allow the collation to be selected dynamically. This restriction can be circumvented
by rewriting the clause order by $e/@key collation "URI"
as order by fn:collationkey($e/@key, $collation)
,
where $collation
allows the collation to be chosen dynamically.
Note that xs:base64Binary
becomes an ordered type
in XPath 3.1, making binary collation keys possible.
Variables  

Expression:  

Result:  
Expression:  
Result: 

As the above examples illustrate, it is important that when the

Determines whether or not any of the supplied strings, when tokenized at whitespace boundaries, contains the supplied token, under the rules of the supplied collation.
The twoargument form of this function is
The threeargument form of this function is
If $value
is the empty sequence, the function returns false
.
Leading and trailing whitespace is trimmed from $token
.
If the trimmed value of $token
is a zerolength string, the function returns false
.
The collation used by this function is determined according to the rules in
The function returns true
if and only if there is string in $value
which,
after tokenizing at whitespace boundaries, contains a token
that is equal to the trimmed value of $token
under
the rules of the selected collation.
More formally, the function returns the value of the expression:
Interior whitespace within $token
will cause the function to return false
,
unless such whitespace is ignored by the selected collation.
This function can be used for processing spaceseparated attribute values
(for example, the XHTML and DITA class attribute),
where one often needs to test for the presence
of a single token in a spaceseparated list. The function is designed to work
both when the attribute has been validated against an XSD list type, and when it
appears as a single untyped string. It differs from the
HTML 5 definition in that HTML 5 recognizes form feed (x0C) as a separator.
To reproduce the HTML token matching behavior, the HTML ASCII caseinsensitive collation
should be used: see
Expression: 


Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression:  
Result: 
The following functions are defined on values of type xs:string
and
types derived from it.
Function  Meaning 

fn:char  Returns a string containing a particular character or glyph. 
fn:characters  Splits the supplied string into a sequence of singlecharacter strings. 
fn:concat  Returns the concatenation of the string values of the arguments. 
fn:stringjoin  Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items. 
fn:substring  Returns the part of $value beginning at the position
indicated by $start and continuing for the number of $length . 
fn:stringlength  Returns the number of 
fn:normalizespace  Returns $value with leading and trailing whitespace removed, and
sequences of internal whitespace reduced to a single space character. 
fn:normalizeunicode  Returns $value after applying Unicode normalization. 
fn:uppercase  Converts a string to upper case. 
fn:lowercase  Converts a string to lower case. 
fn:translate  Returns $value modified by replacing or removing individual
characters. 
fn:hash  Returns a string representation of the results from a specified hash, checksum, or cyclic redundancy check function upon the input. 
When the above operators and functions are applied to datatypes derived from
xs:string
, they are guaranteed to return values that are instances of
xs:string
, but the value might or might not be an instance of the
particular subtype of xs:string
to which they were applied.
The strings returned by fn:concat
and fn:stringjoin
are not guaranteed to be normalized.
But see note in fn:concat
.
Returns a string containing a particular character or glyph.
This function is
The function returns a string, generally containing a single $value
.
The supplied value of $value
must be one of the following:
A Unicode codepoint, supplied as an integer. For example fn:char(9)
returns the tab character.
An HTML5 character reference name (often referred to as an entity name) as defined
at fn:char("pi")
represents the character
π
(x3C0
) and fn:char("nbsp")
returns the
nonbreaking space character, xA0
.
A processor
In the event that the HTML5 character reference name identifies a string comprising multiple codepoints, that string is returned.
[TODO: add a proper bibliographic reference.]
A backslashescape sequence from the set \n
(newline, x0A
),
\r
(carriage return, x0D
),
or \t
(tab, x09
).
The result must consist of
fn:char(0xDEAD)
is invalid because it is in the surrogate range.
The function fails with a dynamic error $value
is not a valid
representation of a
Although all Unicode characters can appear in string literals (the delimiting quotation marks can be escaped by doubling them), some characters are not visually distinctive, so representing them by name may make code more readable. In addition, there may be contexts where it is necessary or prudent to write XPath expressions using ASCII characters only, for example where an expression is used in the query part of a URI.
A few HTML5 character reference names identify glyphs whose Unicode
representation uses multiple codepoints. For example, the name
NotEqualTilde
refers to the glyph ≂̸
which is expressed
using the two codepoints #x2242 #x0338
. In such cases the string length of
the result of the function will exceed one.
Expression  Result 

char("aacute")  
char("eth")  
char(9)  
char("\t")  
char(0x20)  
char(0x1D1CA)  
char("NotEqualTilde") 
Accepted for 4.0 on 20230110; with actions on the editor for revision. See issue #121.
Splits the supplied string into a sequence of singlecharacter strings.
This function is
The function returns a sequence of strings, each string having length 1, containing
the corresponding $value
.
If $value
is a zerolength string or the empty sequence, the function returns
the empty sequence.
More formally, the function returns the result of the expression fn:stringtocodepoints($value) ! fn:codepointstostring(.)
Expression  Result 

characters("Thérèse")  
characters("")  
characters(())  
characters("Banana") => indexof("a")  
characters("stretch") => stringjoin("")  
New in 4.0. Accepted 20220920, subject to improving the description.
Returns the concatenation of the string values of the arguments.
The twoargument form of
this function defines the semantics of the 
operator.
This function is
This function accepts zero or more arguments, each declared with the required type
xs:anyAtomicType*
. The value $v
supplied for each argument
is first reduced to a single string as follows:
If XPath 1.0 compatibility mode is set to true in the static context of the
function call, then the result of xs:string($v[1])
.
Otherwise, the result of fn:stringjoin($v)
.
The resulting sequence of strings (one for each supplied argument) is then reduced
to a single string by applying fn:stringjoin#1
to the sequence.
The fn:concat
function is specified to allow zero or more arguments, which
are concatenated together. This is the only function specified in this document that
allows a variable number of arguments. This capability is retained for compatibility
with
As mentioned in fn:concat
. If a normalized result is required,
fn:normalizeunicode
can be applied to the xs:string
returned by fn:concat
. The following XQuery:
where the ?
represents either the actual Unicode character COMBINING DIARESIS
(Unicode codepoint U+0308
) or ̈
, will return:
"I plan to go to Mu?nchen in September"
where the ?
represents either the actual Unicode character COMBINING DIARESIS
(Unicode codepoint U+0308
) or ̈
.
It is worth noting that the returned value is not normalized in NFC; however, it is normalized in NFD.
However, the following XQuery:
where ?
represents either the actual Unicode character COMBINING DIARESIS
(Unicode codepoint U+0308
) or ̈
, will return:
"I plan to go to München in September"
This returned result is normalized in NFC.
Expression: 


Result:  
Expression:  
Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result: 
Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items.
This function is
If the second argument is omitted or an empty sequence, the effect is the same as
calling the twoargument version with $separator
set to a zerolength
string.
The function returns an xs:string
created by $values
to an xs:string
,
and then concatenating the result strings in order,$separator
as a
separator between adjacent strings. If $separator
is the zerolength
string, then the items in $values
are concatenated without a separator.
If $values
is the empty sequence, the function returns the
zerolength string.
Variables  

Expression: 


Result:  
Expression: 

Result:  
Expression:  
Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression:  
Result:  
Expression:  
Result: 
Returns the part of $value
beginning at the position
indicated by $start
and continuing for the number of $length
.
This function is
If $value
is the empty sequence, the function returns
the zerolength string.
Otherwise, the function returns a string comprising those $value
whose index position (counting
from one) is greater than or equal to $start
(rounded to an
integer), and (if $length
is specified
$start
and $length
(both rounded to integers).
The characters returned do not extend beyond $value
. If
$start
is zero or negative, only those characters in positions greater
than zero are returned.
More specifically, the three argument version of the function returns the characters in
$value
whose position $p
satisfies:
fn:round($start) <= $p and $p < fn:round($start) + fn:round($length)
The two argument version of the function assumes that $length
is infinite
and thus returns the $value
whose position $p
satisfies:
fn:round($start) <= $p
In the above computations, the rules for op:numericlessthan
The first character of a string is located at position 1, not position 0.
The second and third arguments allow xs:double
values (rather than
requiring xs:integer
) in order to achieve compatibility with XPath 1.0.
A surrogate pair counts as one character, not two.
The consequences of supplying values such as NaN
or positive or negative
infinity for the $start
or $length
arguments follow from the
above rules, and are not always intuitive.
Expression  Result 

substring("motor car", 6) 

substring("metadata", 4, 3)  
substring("12345", 1.5, 2.6)  
substring("12345", 0, 3)  
substring("12345", 5, 3)  
substring("12345", 3, 5)  
substring("12345", 0 div 0E0, 3) 

substring("12345", 1, 0 div 0E0)  
substring((), 1, 3)  
substring("12345", 42, 1 div 0E0) 

substring("12345", 1 div 0E0, 1 div 0E0) 

Changed in 4.0: The third argument can now be supplied as an empty sequence.
Returns the number of
The zeroargument form of this function is
The oneargument form of this function is
The function returns an xs:integer
equal to the length in $value
.
Calling the zeroargument version of the function is equivalent to calling
fn:stringlength(fn:string(.))
.
If $value
is the empty sequence, the function returns the
xs:integer
value 0
.
If $value
is not specified and the context value is
As a consequence of the rules given above, a type error is raised
Unlike some programming languages, a
There are situations where fn:stringlength()
has a different effect
from fn:stringlength(.)
. For example, if the context value
is an attribute node typed as an xs:integer
with the string value 000001
,
then fn:stringlength()
returns 6
(the length of the string value of the node), while
fn:stringlength(.)
raises a type error (because the result of atomization
is not an xs:string
).
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression: 

Result: 
Returns $value
with leading and trailing whitespace removed, and
sequences of internal whitespace reduced to a single space character.
The zeroargument form of this function is
The oneargument form of this function is
If $value
is the empty sequence, the function returns the
zerolength string.
The function returns a string constructed by stripping leading and trailing whitespace
from $value
, and replacing sequences of one or more adjacent
whitespace characters with a single space, #x20
.
The whitespace characters are defined in the metasymbol S (Production 3) of
If no argument is supplied, then $value
defaults to the string value
(calculated using fn:string
) of the context value (.
).
If no argument is supplied and the context value is
As a consequence of the rules given above, a type error is raised
The definition of whitespace is unchanged in
S ::= (#x20  #x9  #xD  #xA)+
Expression:  

Result:  
Expression: 

Result: 
Returns $value
after applying Unicode normalization.
This function is
If $value
is the empty sequence, the function returns the
zerolength string.
If the second argument is omitted or an empty sequence, the result is the same as
calling the twoargument version with $form
set to the string
"NFC"
.
Otherwise, the function returns $value
normalized according to
the rules of the normalization form identified by the value of
$form
.
The effective value of $form
is the value of the expression
fn:uppercase(fn:normalizespace($form))
.
If the effective value of $form
is NFC
,
then the function returns $value
converted to Unicode
Normalization Form C (NFC).
If the effective value of $form
is NFD
,
then the function returns $value
converted to Unicode
Normalization Form D (NFD).
If the effective value of $form
is NFKC
,
then the function returns $value
in Unicode Normalization
Form KC (NFKC).
If the effective value of $form
is NFKD
,
then the function returns $value
converted to Unicode
Normalization Form KD (NFKD).
If the effective value of $form
is
FULLYNORMALIZED
, then the function returns
$value
converted to fully normalized form.
If the effective value of $form
is the zerolength
string, no normalization is performed and $value
is returned.
Normalization forms NFC, NFD, NFKC, and NFKD, and the algorithms to be used for
converting a string to each of these forms, are defined in
The motivation for normalization form FULLYNORMALIZED is explained in
A string is
A composing character is a character that is one or both of the following:
the second character in the canonical decomposition mapping of some
character that is not listed in the Composition Exclusion Table defined in
of nonzero canonical combining class (as defined in
A string is converted to FULLYNORMALIZED form as follows:
if the first character in the string is a composing character, prepend a single space (x20);
convert the resulting string to normalization form NFC.
Conforming implementations NFC
and
NFD
, NFKC
, NFKD
, and
FULLYNORMALIZED
. They
It is fn:normalizeunicode
function leaves such codepoints unchanged. If the
implementation supports the requested normalization form then it
A $form
argument is not one of the values
supported by the implementation.
Converts a string to upper case.
This function is
If $value
is the empty sequence, the zerolength string is
returned.
Otherwise, the function returns $value
after translating every
Case mappings may change the length of a string. In general, the
fn:uppercase
and fn:lowercase
functions are not inverses
of each other: fn:lowercase(fn:uppercase($s))
is not guaranteed to
return $s
, nor is fn:uppercase(fn:lowercase($s))
. The
Latin small letter dotless i (ı, U+0131, used in Turkish) is perhaps the most prominent
lowercase letter which will not roundtrip. The Latin capital letter i with dot above (İ, U+0130)
is the most prominent uppercase letter which will not round trip; there are others,
such as Latin capital letter sharp S (ẞ, U+1E9E), which was introduced in Unicode 5.1.
These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.
Because the function is not sensitive to locale, results will not always match user
expectations. In Quebec, for example, the standard uppercase equivalent of è
is È
,
while in metropolitan France it is more commonly E
; only one of these is supported by
the functions as defined.
Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.
Expression  Result 

uppercase("abCd0") 
Converts a string to lower case.
This function is
If t$value
is the empty sequence, the zerolength string is
returned.
Otherwise, the function returns $value
after translating every
Case mappings may change the length of a string. In general, the
fn:uppercase
and fn:lowercase
functions are not inverses
of each other: fn:lowercase(fn:uppercase($s))
is not guaranteed to
return $s
, nor is fn:uppercase(fn:lowercase($s))
. The
Latin small letter dotless i (ı, U+0131, used in Turkish) is perhaps the most prominent
lowercase letter which will not roundtrip. The Latin capital letter i with dot above (İ, U+0130)
is the most prominent uppercase letter which will not round trip; there are others,
such as Latin capital letter sharp S (ẞ, U+1E9E), which was introduced in Unicode 5.1.
These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.
Because the function is not sensitive to locale, results will not always match user
expectations. In Quebec, for example, the standard uppercase equivalent of è
is È
,
while in metropolitan France it is more commonly E
; only one of these is supported by
the functions as defined.
Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.
Expression  Result 

lowercase("ABc!D") 
Returns $value
modified by replacing or removing individual
characters.
This function is
If $value
is the empty sequence, the function returns the
zerolength string.
Otherwise, the function returns a result string constructed by processing each $value
, in order,
according to the following rules:
If the character does not appear in $replace
then it
is added to the result string unchanged.
If the character first appears in $replace
at some
position $with
is
$with
is added to the result string.
If the character first appears in $replace
at some
position $with
is less than
If $replace
is the zerolength string then the function returns
$value
unchanged.
If a character occurs more than once in $replace
, then the first
occurrence determines the action taken.
If $with
is longer than $replace
, the excess
characters are ignored.
Expression  Result 

translate("bar", "abc", "ABC")  
translate("aaa", "abc", "ABC")  
translate("abcdabc", "abc", "AB") 
Returns a string representation of the results from a specified hash, checksum, or cyclic redundancy check function upon the input.
The oneargument form of this function is
The twoargument form of this function is
The $options
argument, if present, defines additional parameters
controlling how the process is conducted. The
If the oneargument version of the function is used, the result is the same as calling
the twoargument version, with the default $options
settings.
If $value
is the empty sequence, the function returns the empty sequence.
If $value
is an instance of xs:string
, it is converted to a sequence
of octets on the basis of UTF8 encoding. If $value
is an instance of
xs:base64Binary
or xs:hexBinary
, it is converted to a sequence of
octets.
The function returns as xs:hexBinary
the octets returned by passing
$value
as an octet sequence through the hash, checksum, or cyclical
redundancy check function specified by the options map. The process is followed even if
the input octet sequence is empty.
The entries that may appear in the $options
map are as follows. The detailed rules
for the interpretation of each option appear later.
Key  Meaning 

algorithm 
Determines the algorithm to be used to calculate a checksum, hash, or cyclic
redundancy check. The effective value is determined by first passing
the value through Conforming implementations
Conforming implementations

A dynamic error is raised algorithm
is not one of the values supported by the implementation.
It is common for secure algorithms to be cryptographically broken, as has happened to
the algorithms MD5
and SHA1
. Developers are responsible for
ensuring that the algorithm chosen meets any expected security protocols, if
relevant.
Additional security practices, such as salting, may be applied as a preprocessing step,
or fn:hash()
can be incorporated into more complex functions.
In most cases, the xs:hexBinary
output of the function will be sought in
string form. Because of serialization rules, casting to a string renders the hash in
uppercase, and rendering in lowercase (as adopted by
Variables  

Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result: 
New in 4.0.
The functions described in this section examine a string $arg1
to see
whether it contains another string $arg2
as a substring. The result
depends on whether $arg2
is a substring of $arg1
, and
if so, on the range of $arg1
which $arg2
matches.
When the $arg1
contains a
contiguous sequence of characters whose $arg2
.
When a collation is specified, the rules are more complex.
All collations support the capability of deciding whether two fn:compare
, this is
all that is required. For other functions, such as fn:contains
,
the collation needs to support an additional property: it must be able to
decompose the string into a sequence of collation units, each unit consisting of
one or more characters, such that two strings can be compared by pairwise
comparison of these units. (“collation unit” is equivalent to "collation
element" as defined in $arg1
is then considered to contain $arg2
as a
substring if the sequence of collation units corresponding to $arg2
is a subsequence of the sequence of the collation units corresponding to
$arg1
. The characters in $arg1
that match are the
characters corresponding to these collation units.
This rule may occasionally lead to surprises. For example, consider a collation
that treats "Jaeger"
and "Jäger"
as equal. It might do this by treating "ä"
as representing
two collation units, in which case the
expression fn:contains("Jäger", "eg")
will return
true
. Alternatively, a collation might treat "ae" as a single
collation unit, in which case the expression fn:contains("Jaeger",
"eg")
will return false
. The results of these functions thus
depend strongly on the properties of the collation that is used.
In addition,
collations may specify that some collation units should be ignored during matching. If hyphen is an ignored
collation unit, then fn:contains("codepoint", "codepoint")
will be true
,
and fn:contains("codepoint", "")
will also be true
.
In the definitions below, we refer to the terms
C is the collation; that is, the value of the $collation
argument if specified, otherwise the default collation.
P is the (candidate) substring $arg2
Q is the (candidate) containing string $arg1
The boundary condition B is satisfied at the start and end of a
string, and between any two characters that belong to different collation units
(“collation elements” in the language of
It is possible to define collations that do not have the ability to decompose a
string into units suitable for substring matching. An argument to a function
defined in this section may be a URI that identifies a collation that is able to
compare two strings, but that does not have the capability to split the string
into collation units. Such a collation may cause the function to fail, or to
give unexpected results, or it may be rejected as an unsuitable argument. The
ability to decompose strings into collation units is an
Function  Meaning 

fn:contains  Returns true if the string $value contains $substring as a
substring, taking collations into account. 
fn:startswith  Returns true if the string $value contains $substring as a leading
substring, taking collations into account. 
fn:endswith  Returns true if the string $value contains $substring as a trailing
substring, taking collations into account. 
fn:substringbefore  Returns the part of $value that precedes the first occurrence of
$substring , taking collations into account. 
fn:substringafter  Returns the part of $value that follows the first occurrence of
$substring , taking collations into account. 
Returns true
if the string $value
contains $substring
as a
substring, taking collations into account.
The twoargument form of this function is
The threeargument form of this function is
If $value
or $substring
is the empty sequence, or
contains only ignorable collation units, it is interpreted as the zerolength
string.
If $substring
is the zerolength string, then the function returns
true
.
If $value
is the zerolength string, the function returns
false
.
The collation used by this function is determined according to the rules in
The function returns an xs:boolean
indicating whether or not
$value
contains (at the beginning, at the end, or anywhere within) at
least one sequence of collation units that provides a $substring
, according to the collation that is
used.
A
Variables  

Expression  Result 

The collation used in some of these examples,  
“Ignorable collation unit” is equivalent to “ignorable collation element” in  
contains("tattoo", "t")  
contains("tattoo", "ttt")  
contains("", ())  
Returns true
if the string $value
contains $substring
as a leading
substring, taking collations into account.
The twoargument form of this function is
The threeargument form of this function is
If $value
or $substring
is the empty sequence, or
contains only ignorable collation units, it is interpreted as the zerolength
string.
If $substring
is the zerolength string, then the function returns
true
. If $value
is the zerolength string and
$substring
is not the zerolength string, then the function returns
false
.
The collation used by this function is determined according to the rules in
The function returns an xs:boolean
indicating whether or not
$value
starts with a sequence of collation units that provides a
$substring
according to the
collation that is used.
A
Variables  

Expression  Result 

The collation used in some of these examples,  
“Ignorable collation unit” is equivalent to “ignorable collation element” in  
startswith("tattoo", "tat")  
startswith("tattoo", "att")  
startswith((), ())  
Returns true
if the string $value
contains $substring
as a trailing
substring, taking collations into account.
The twoargument form of this function is
The threeargument form of this function is
If $value
or $substring
is the empty sequence, or
contains only ignorable collation units, it is interpreted as the zerolength
string.
If $substring
is the zerolength string, then the function returns
true
. If $value
is the zerolength string and
the value of $substring
is not the zerolength string, then the function returns
false
.
The collation used by this function is determined according to the rules in
The function returns an xs:boolean
indicating whether or not
$value
ends with a sequence of collation units that provides a
$substring
according to the
collation that is used.
A
Variables  

Expression  Result 

The collation used in some of these examples,  
“Ignorable collation unit” is equivalent to “ignorable collation element” in  
endswith("tattoo", "tattoo")  
endswith("tattoo", "atto")  
endswith((), ())  
Returns the part of $value
that precedes the first occurrence of
$substring
, taking collations into account.
The twoargument form of this function is
The threeargument form of this function is
If $value
or $substring
is the empty sequence, or
contains only ignorable collation units, it is interpreted as the zerolength
string.
If $substring
is the zerolength string, then the function returns
the zerolength string.
If $value
does not contain a string that is equal to
$substring
, then the function returns the zerolength string.
The collation used by this function is determined according to the rules in
The function returns the substring of $value
that precedes in
$value
the first occurrence of a sequence of collation units
that provides a $substring
according to the collation that is used.
A
Variables  

Expression  Result 

The collation used in some of these examples,  
“Ignorable collation unit” is equivalent to “ignorable collation element” in  
substringbefore("tattoo", "attoo")  
substringbefore("tattoo", "tatto")  
substringbefore((), ())  
Returns the part of $value
that follows the first occurrence of
$substring
, taking collations into account.
The twoargument form of this function is
The threeargument form of this function is
If $value
or $substring
is the empty sequence, or
contains only ignorable collation units, it is interpreted as the zerolength
string.
If $substring
is the zerolength string, then the function returns
the value of $value
.
If $value
does not contain a string that is equal to
$substring
, then the function returns the zerolength string.
The collation used by this function is determined according to the rules in
The function returns the substring of $value
that follows in
$value
the first occurrence of a sequence of collation units
that provides a $substring
according to the collation that is used.
A dynamic error
Variables  

Expression  Result 

The collation used in some of these examples,  
“Ignorable collation unit” is equivalent to “ignorable collation element” in  
substringafter("tattoo", "tat")  
substringafter("tattoo", "tattoo")  
substringafter((), ())  
The four functions described in this section make use of a regular expression syntax for pattern matching, described below.
Function  Meaning 

fn:matches  Returns true if the supplied string matches a given regular expression. 
fn:replace  Returns a string produced from the input string by replacing any substrings that match a
given regular expression with a supplied replacement string 
fn:tokenize  Returns a sequence of strings constructed by splitting the input wherever a separator is found; the separator is any substring that matches a given regular expression. 
fn:analyzestring  Analyzes a string using a regular expression, returning an XML structure that identifies which parts of the input string matched or failed to match the regular expression, and in the case of matched substrings, which substrings matched each capturing group in the regular expression. 
The regular expression syntax used by these functions is defined in terms of
the regular expression syntax specified in XML Schema (see
It is recommended that implementers consult
The regular expression syntax and semantics are identical to those
defined in
In
Implementers, even in cases where XSD 1.1 is not supported, are advised to consult the XSD 1.1 regular expression specification for guidance on how to handle cases where the XSD 1.0 specification is unclear or inconsistent.
Two metacharacters, ^
and $
are
added. By default, the metacharacter ^
matches the
start of the entire string, while $
matches the end
of the entire string. In multiline mode, ^
matches
the start of any line (that is, the start of the entire string,
and the position immediately after a newline character), while
$
matches the end of any line (that is, the end of
the entire string, and the position immediately before a newline
character). Newline here means the character #x0A
only.
This means that the production in
[10] Char ::= [^.\?*+()#x5B#x5D]
is modified to read:
[10] Char ::= [^.\?*+{}()^$#x5B#x5D]
The XSD 1.1 grammar for regular expressions uses the same
production rule, but renumbered and renamed [73] NormalChar
; it
is affected in the same way.
The characters #x5B
and #x5D
correspond
to [
and ]
respectively.
The definition of Char (production [10]) in {
) and right brace (}
). That error is corrected here.
The following production:
[11] charClass ::= charClassEsc  charClassExpr  WildCardEsc
is modified to read:
[11] charClass ::= charClassEsc  charClassExpr 
WildCardEsc  "^"  "$"
Using XSD 1.1 as the baseline the equivalent is to change the production:
[74] charClass ::= SingleCharEsc  charClassEsc  charClassExpr  WildCardEsc
to read:
[74] charClass ::= SingleCharEsc  charClassEsc  charClassExpr 
WildCardEsc  "^"  "$"
Single character escapes are extended to allow the
$
character to be escaped. #
character may be escaped: see
[24]SingleCharEsc ::= '\' [nrt\.?*+(){}#x2D#x5B#x5D#x5E]
to
[24]SingleCharEsc ::= '\' [nrt\.?*+(){}$#x2D#x5B#x5D#x5E\#]
(In the XSD 1.1 version of the regular expression grammar, the production rule
for SingleCharEsc
is unchanged from 1.0, but is renumbered [84])
?
following a quantifier. Specifically:
X??
matches X, once or not at all
X*?
matches X, zero or more times
X+?
matches X, one or more times
X{n}?
matches X, exactly n times
X{n,}?
matches X, at least n times
X{n,m}?
matches X, at least n times, but
not more than m times
The effect of these quantifiers is that the regular expression
matches the ?
, the regular expression matches the
To achieve this, the production in
[4] quantifier ::= [?*+]  ( '{' quantity '}' )
is changed to:
[4] quantifier ::= ( [?*+]  ( '{' quantity '}' ) ) '?'?
(In the XSD 1.1 version of the regular expression grammar, this rule is unchanged from 1.0, but is renumbered [67])
Reluctant quantifiers have no effect on the results of the
boolean fn:matches
function, since this
function is only interested in discovering whether a match
exists, and not where it exists.
Subexpressions (groups) within the regular expression are
recognized. The regular expression syntax defined by fn:replace
function) allow access to the parts of the
input string that matched a subexpression (called captured substrings).
?:
(see below), is not within a character group (square brackets),
and is not escaped with a backslash. The subexpression enclosed by a capturing left
parenthesis and its matching right parenthesis is referred to as a
More specifically, the
For example, in the regular expression A(BC(?:D(EF(GH[()]))))
, the string matched
by the subexpression BC(?:D(EF(GH[()])))
is capturing subexpression 1, the string
matched by EF(GH[()])
is capturing subexpression 2, and the string matched by
GH[()]
is capturing subexpression 3.
When, in the course of evaluating a regular expression, a particular substring of the input
matches a capturing subexpression, that substring becomes available as a
When a (a*)+
and the input string "aaaa"
, an implementation
might legitimately capture either "aaaa"
or a zero length string as the content
of the captured subgroup.
Parentheses that are required to group terms within the regular expression, but which are
not required for capturing of substrings, can be represented using
the syntax (?:xxxx)
. To achieve this, the production rule for atom
in
( '(' regExp ')' )
with:
( '(' '?:'? regExp ')' )
(For the new versions of the XSD 1.0 and XSD 1.1 production rules for
atom
, see below.)
In the absence of backreferences (see below),
the presence of the optional ?:
has no effect on the set of strings
that match the regular expression, but causes the left parenthesis not to be counted
by operations (such as fn:replace
and backreferences) that number the capturing subexpressions
within a regular expression.
Backreferences are allowed
outside a character class expression.
A backreference is an additional kind of atom.
The construct \N
where
N
is a single digit is always recognized as a
backreference; if this is followed by further digits, these
digits are taken to be part of the backreference if and only if
the resulting number NN is such that
the backreference is preceded by the opening parenthesis of the NNth
capturing left parenthesis.
The regular expression is invalid if a backreference refers to a
capturing subexpression that does not exist or whose
closing right parenthesis occurs after the backreference.
A backreference with number N matches a string that is the same as
the value of the N
th captured substring.
For example, the regular expression
('").*\1
matches a sequence of characters
delimited either by an apostrophe at the start and end, or by a
quotation mark at the start and end.
If no string has been matched by the N
th capturing
subexpression, the backreference is interpreted as matching
a zerolength string.
Combining this change with the introduction of noncapturing groups (see above), backreferences change the following production:
[9] atom ::= Char  charClass  ( '(' regExp ')' )
to
[9] atom ::= Char  charClass  ( '(' '?:'? regExp ')' )  backReference
[9a] backReference ::= "\" [19][09]*
With respect to the XSD 1.1 version of the regular expression grammar, the effect is to change:
[72] atom ::= NormalChar  charClass  ( '(' regExp ')' )
to
[72] atom ::= NormalChar  charClass  ( '(' '?:'? regExp ')' )  backReference
[72a] backReference ::= "\" [19][09]*
Within a character class expression,
\
followed by a digit is invalid.
Some other regular expression languages interpret this as an octal character reference.
A regular expression that uses a Unicode block name that is not defined in the version(s) of Unicode
supported by the processor (for example \p{IsBadBlockName}
) is deemed to be invalid
XSD 1.0 does not say how this situation should be handled; XSD 1.1 says that it should be handled by treating all characters as matching.
Comments are enabled in regular expressions if the c
flag is present.
A comment starts with a #
character that is not escaped with an immediately
preceding backslash, and that is not contained in a CharClassExpr
(that is,
in square brackets). It ends with the following #
character, or with the
end of the string containing the regular expression.
Whether or not the c
flag is present, the production for
SingleCharEsc
is extended to allow the #
character
to be escaped.
All these functions provide an optional parameter, $flags
,
to set options for the interpretation of the regular expression. The
parameter accepts a xs:string
, in which individual letters
are used to set options. The presence of a letter within the string
indicates that the option is on; its absence indicates that the option
is off. Letters may appear in any order and may be repeated. They are casesensitive. If there
are characters present that are not defined here as flags, then a dynamic error
is raised
The following options are defined:
s
: If present, the match operates in “dotall”
mode. (Perl calls this the singleline mode.) If the
s
flag is not specified, the metacharacter
.
matches any character except a newline
(#x0A
) or carriage return (#x0D
)
character. In dotall mode, the
metacharacter .
matches any character whatsoever.
Suppose the input contains the strings "hello"
and
"world"
on two lines.
This will not be matched by the regular expression
"hello.*world"
unless dotall mode is enabled.
m
: If present, the match operates in multiline
mode. By default, the metacharacter ^
matches the
start of the entire string, while $ matches the end of the
entire string. In multiline mode, ^
matches the
start of any line (that is, the start of the entire string, and
the position immediately after a newline character
other than a newline
that appears as the last character in the string), while
$
matches the end of any line
(that is, the position immediately
before a newline character, and the end of the entire string if there is no
newline character at the end of the string).
Newline here means the character #x0A
only.
i
: If present, the match operates in
caseinsensitive mode. The detailed rules are as follows.
In these
rules, a character C2 is considered to be a true
when the two characters
are considered as strings of length one, and the
fn:lowercase(C1) eq fn:lowercase(C2) or
fn:uppercase(C1) eq fn:uppercase(C2)
Note that the casevariants of a character under this definition are always single characters.
When a normal character (Char
) is used as an atom,
it represents
the set containing that character and all its casevariants.
For example, the regular expression "z"
will
match both "z"
and "Z"
.
A character range (production charRange
in the XSD 1.0 grammar, replaced by productions charRange
and singleChar
in XSD 1.1) represents the set
containing all the characters that it would match in the absence
of the i
flag, together with their casevariants.
For example,
the regular expression "[AZ]"
will match all
the letters A
to Z
and all the letters
a
to z
. It will also match
certain other characters such as #x212A
(KELVIN SIGN), since
fn:lowercase("#x212A")
is k
.
This rule applies also to a character range used in a character
class subtraction (charClassSub
): thus [AZ[IO]] will match
characters such as A
, B
, a
, and b
, but will not match
I
, O
, i
, or o
.
The rule also applies to a character range used as part of a
negative character group: thus "[^Q]"
will match every character
except Q
and q
(these being the only casevariants of Q
in
Unicode).
A backreference is compared using caseblind comparison:
that is, each character must either be the same as the
corresponding character of the previously matched string, or must
be a casevariant of that character. For example, the strings
"Mum"
, "mom"
, "Dad"
,
and "DUD"
all match the regular
expression "([md])[aeiou]\1"
when the i
flag is used.
All other constructs are unaffected by the i
flag.
For example,
"\p{Lu}"
continues to match uppercase letters only.
x
: If present, whitespace characters
(#x9
, #xA
, #xD
and #x20
)
in the regular expression are removed prior to matching with one exception:
whitespace characters within character class expressions
(charClassExpr
) are not removed. This flag can be used,
for example, to break up long regular expressions into readable lines.
Examples:
fn:matches("helloworld", "hello world", "x")
returns true()
fn:matches("helloworld", "hello[ ]world", "x")
returns false()
fn:matches("hello world", "hello\ sworld", "x")
returns true()
fn:matches("hello world", "hello world", "x")
returns false()
Whitespace is treated as a lexical construct to be removed before the regular expression is parsed; it is therefore not explicit in the regular expression grammar.
q
: if present, all characters in the regular expression
are treated as representing themselves, not as metacharacters. In effect, every
character that would normally have a special meaning in a regular expression is implicitly escaped
by preceding it with a backslash.
Furthermore, when this flag is present, the characters $
and
\
have no special significance when used in the replacement string
supplied to the fn:replace
function.
This flag can be used in conjunction with the i
flag. If it is used
together with the m
, s
, x
,
c
Examples:
tokenize("12.3.5.6", ".", "q")
returns ("12", "3", "5", "6")
replace("a\b\c", "\", "\\", "q")
returns "a\\b\\c"
replace("a/b/c", "/", "$", "q")
returns "a$b$c"
matches("abcd", ".*", "q")
returns false()
matches("Mr. B. Obama", "B. OBAMA", "iq")
returns true()
c
: if present, comments are enabled
in the regular expression. This flag has no effect if the q
flag is
present. A comment is recognized by the presence of a #
character that
is not escaped by a backslash or contained in a character class expression
(charClassExpr
), and it is terminated by the following #
character or by the end of the regular expression string.
For example:
replace("03/24/2025", "(..#month#)/(..#day#)/(....#year#)", "$3$1$2", "c")
Comments are treated as a lexical construct to be removed before the regular expression is parsed; they are therefore not explicit in the regular expression grammar.
Returns true
if the supplied string matches a given regular expression.
This function is
If $value
is the empty sequence, it is interpreted as the zerolength
string.
If the $flags
argument is omitted or if it is an empty sequence,
the effect is the same as setting $flags
to a zerolength string.
Flags are defined in
The function returns true
if $value
or some substring of
$value
matches the regular expression supplied as $pattern
,
and the associated $flags
. Otherwise, the function returns false
.
A dynamic error is raised $pattern
is invalid according to the rules described in
A dynamic error is raised $flags
is invalid according to the rules described in
Unless the metacharacters ^
and $
are used as anchors, the
string is considered to match the pattern if any substring matches the pattern. But if
anchors are used, the anchors must match the start/end of the string (in string mode),
or the start/end of a line (in multiline mode).
This is different from the behavior of patterns in
Regular expression matching is defined on the basis of Unicode code points; it takes no account of collations.
Variables  

Expression  Result 

matches("abracadabra", "bra")  
matches("abracadabra", "^a.*a$")  
matches("abracadabra", "^bra")  
Given the source document:  
the following function calls produce the following results, with the
 
matches($poem, "Kaum.*krähen")  
matches($poem, "Kaum.*krähen", "s")  
matches($poem, "^Kaum.*gesehen,$", "m")  
matches($poem, "^Kaum.*gesehen,$")  
matches($poem, "kiki", "i") 
Returns a string produced from the input string by replacing any substrings that match a
given regular expression with a supplied replacement string
This function is
If $value
is the empty sequence, it is interpreted as the zerolength
string.
The replacement string is determined by the values of the
$replacement
and/or $action
arguments:
If the $action
argument is present and is not an empty sequence,
the string is obtained by calling the $action
function.
The first argument to the $action
function is the string to be replaced,
provided as xs:untypedAtomic
.
The second argument to the $action
function provides the captured
substrings as an xs:untypedAtomic
sequence.
The Nth
item in this sequence is the substring captured by
the Nth
parenthesized subexpression. If the
Nth
parenthesized subexpression was not matched, the Nth
item
will be the zerolength string.
Note that the rules for function coercion mean that the function actually
supplied for the $action
parameter may be an arity1 function: the
second argument does not need to be declared if it is not used.
The replacement string is obtained by invoking fn:string
for the result of the function call.
Otherwise, if the $replacement
argument is present and is not
an empty sequence, the replacement string is the value of $replacement
.
Otherwise, the replacement string is the zerolength string.
If the $flags
argument is omitted or if it is an empty sequence,
the effect is the same as setting $flags
to a zerolength string.
Flags are defined in
The function returns the xs:string
that is obtained by replacing each
nonoverlapping substring of $value
that matches the given
$pattern
with
If two overlapping substrings of $value
both match the
$pattern
, then only the first one (that is, the one whose first $value
string) is
replaced.
If the q
flag is present, or if the replacement string was obtained
by calling the $action
function, then the replacement string is used
Otherwise, within the replacement string, a variable $N
may
be used to refer to the substring captured by the Nth parenthesized subexpression in
the regular expression. For each match of the pattern, these variables are assigned the
value of the content matched by the relevant subexpression, and the modified
replacement string is then substituted for the $value
that matched the pattern.
$0
refers to the substring captured by the regular expression as a
whole.
More specifically, the rules are as follows, where S
is the number of
parenthesized subexpressions in the regular expression, and N
is the
decimal number formed by taking all the digits that consecutively follow the
$
character:
If N
=0
, then the variable is replaced by the substring
matched by the regular expression as a whole.
If 1
<=N
<=S
, then the variable is
replaced by the substring captured by the Nth parenthesized subexpression. If the
Nth
parenthesized subexpression was not matched, then the
variable is replaced by the zerolength string.
If S
<N
<=9
, then the variable is
replaced by the zerolength string.
Otherwise (if N
>S
and
N
>9
), the last digit of N
is taken to
be a literal character to be included “as is” in the replacement string, and the
rules are reapplied using the number N
formed by stripping off this
last digit.
For example, if the replacement string is
"$23"
and there are 5 substrings, the result contains the value of the substring that
matches the second subexpression, followed by the digit
3
.
Unless the q
flag is used, a literal $
character within the
replacement string must be written as \$
, and a literal \
character must be written as \\
.
If two alternatives within the pattern both match at the same position in the
$input
, then the match that is chosen is the one matched by the first
alternative. For example:
A dynamic error is raised $pattern
is invalid according to the rules described in section
A dynamic error is raised $flags
is invalid according to the rules described in section
A dynamic error is raised fn:matches("", $pattern,
$flags)
returns true
. It is not an error, however, if a captured
substring is zerolength.
In the absence of the q
flag,
a dynamic error is raised $replacement
contains a dollar sign ($
) character that is not
immediately followed by a digit 09
and not immediately preceded by a
backslash (\
).
In the absence of the q
flag,
a dynamic error is raised $replacement
contains a backslash (\
) character that is not part of a
\\
pair, unless it is immediately followed by a dollar sign ($
)
character.
A dynamic error is raised $replacement
and $action
arguments are supplied, and neither is an empty sequence.
If the input string contains no substring that matches the regular expression, the result of the function is a single string identical to the input string.
Expression: 


Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result: 

Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
The expression 
Changed in 4.0: $action
argument new in 4.0. Accepted 20230718.
Returns a sequence of strings constructed by splitting the input wherever a separator is found; the separator is any substring that matches a given regular expression.
This function is
The following rules apply when the $pattern
argument is omitted,
or is set to an empty sequence:
The function splits the supplied string at whitespace boundaries.
More specifically, calling fn:tokenize($value)
fn:tokenize($value, ())
fn:tokenize(fn:normalizespace($value), ' '))
where the second argument
is a single space character (x20).
The $flags
argument is ignored.
The following rules apply when the $pattern
argument is supplied as a single string:
If the $flags
argument is omitted or if it is an empty sequence,
the effect is the same as setting $flags
to a zerolength string.
Flags are defined in
If $value
is the empty sequence, or if $value
is the
zerolength string, the function returns the empty sequence.
The function returns a sequence of strings formed by breaking the $value
string into a sequence of strings, treating any substring that matches
$pattern
as a separator. The separators themselves are not returned.
If a separator occurs at the start of the $value
string, the result
sequence will start with a zerolength string. Similarly, zerolength strings will also occur in
the result sequence if a separator occurs at the end of the $value
string,
or if two adjacent substrings match the supplied $pattern
.
If two alternatives within the supplied $pattern
both match at the same
position in the $value
string, then the match that is chosen is the first.
For example:
A dynamic error is raised $pattern
is invalid according to the rules described in section
A dynamic error is raised $flags
is invalid according to the rules described in section
A dynamic error is raised $pattern
matches a zerolength string, that is, if fn:matches("",
$pattern, $flags)
returns true
.
If the input string is not zero length, and no separators are found in the input string, the result of the function is a single string identical to the input string.
The oneargument form of the function has a similar effect to
the twoargument form with \s+
as the separator pattern, except that the oneargument
form strips leading and trailing whitespace, whereas the twoargument form delivers an extra
zerolength token if leading or trailing whitespace is present.
The function returns no information about the separators that were found
in the string. If this information is required, the fn:analyzestring
function
can be used instead.
The separator used by the oneargument form of the function is any sequence
of tab (x09
), newline (x0A
), carriage return
(x0D
) or space (x20
) characters. This is the same as the
separator recognized by listvalued attributes as defined in XSD.
It is not the same as the separator recognized by listvalued attributes in HTML5,
which also treats formfeed (x0C
) as whitespace. If it is necessary
to treat formfeed as a separator, an explicit separator pattern should be used.
Expression: 


Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
 
Expression:  
Result: 
Changed in 4.0: allow the second argument to be an empty sequence.
Analyzes a string using a regular expression, returning an XML structure that identifies which parts of the input string matched or failed to match the regular expression, and in the case of matched substrings, which substrings matched each capturing group in the regular expression.
This function is
If the $flags
argument is omitted or if it is an empty sequence,
the effect is the same as setting $flags
to a zerolength string.
Flags are defined in
If $value
is the empty sequence the function behaves as if
$value
were the zerolength string. In this situation the result will be
an element node with no children.
The function returns an element node whose local name is
analyzestringresult
. This element and all its descendant elements have
the namespace URI http://www.w3.org/2005/xpathfunctions
. The namespace
prefix is fn:match
and fn:nonmatch
elements. This sequence
is formed by breaking the $value
string into a sequence of strings,
returning any substring that matches $pattern
as the content of a
match
element, and any intervening substring as the content of a
nonmatch
element.
More specifically, the function starts at the beginning of the input string and attempts
to find the first substring that matches the regular expression. If there are several
matches, the first match is defined to be the one whose starting position comes first in
the string. If several alternatives within the regular expression both match at the same
position in the input string, then the match that is chosen is the first alternative
that matches. For example, if the input string is The quick brown fox jumps
and the regular expression is jumpjumps
, then the match that is chosen is
jump
.
Having found the first match, the instruction proceeds to find the second and subsequent
matches by repeating the search, starting at the first
The input string is thus partitioned into a sequence of substrings, some of which match
the regular expression, others which do not match it. Each substring will contain at
least one character. This sequence is represented in the result by the sequence of
fn:match
and fn:nonmatch
children of the returned element
node; the string value of the fn:match
or fn:nonmatch
element
will be the corresponding substring of $input
, and the string value of the
returned element node will therefore be the same as $input
.
The content of an fn:nonmatch
element is always a single text node.
The content of a fn:match
element, however, is in general a sequence of
text nodes and fn:group
element children. An fn:group
element
with a nr
attribute having the integer value N identifies the
substring captured by the Nth parenthesized subexpression in the regular
expression. For each capturing subexpression there will be at most one corresponding
fn:group
element in each fn:match
element in the
result.
If the function is called twice with the same arguments, it is
The base URI of the element nodes in the result is
A schema is defined for the structure of the returned element: see
The result of the function will always be such that validation against this schema would succeed.
However, it is
A dynamic error is raised $pattern
is invalid according to the rules described in section
A dynamic error is raised $flags
is invalid according to the rules described in section
A dynamic error is raised $pattern
matches a zerolength string, that is, if fn:matches("",
$pattern, $flags)
returns true
.
It is
The declarations and definitions in the schema are not automatically available in
the static context of the fn:analyzestring
call (or of any other
expression). The contents of the static context are hostlanguage defined, and in some
host languages are implementationdefined.
The schema defines the outermost element, analyzestringresult
, in such
a way that mixed content is permitted. In fact the element will only have element nodes (match
and nonmatch
) as its children, never text nodes. Although this might have originally been an
oversight, defining the analyzestringresult
element with mixed="true"
allows it
to be atomized, which is potentially useful (the atomized value will be the original input string),
and the capability has therefore been retained for compatibility with the 3.0 version of this
specification.
In the following examples, the result document is shown in serialized form, with whitespace between the element nodes. This whitespace is not actually present in the result.  
Expression: 


Result:  (with whitespace added for legibility) 
Expression:  
Result:  (with whitespace added for legibility) 
Expression:  
Result:  (with whitespace added for legibility) 
This section specifies functions that manipulate URI values, either as instances
of xs:anyURI
or as strings.
Function  Meaning 

fn:resolveuri  Resolves a relative IRI reference against an absolute IRI. 
fn:encodeforuri  Encodes reserved characters in a string that is intended to be used in the path segment of a URI. 
fn:decodefromuri  Decodes URIescaped characters in a string. 
fn:iritouri  Converts a string containing an IRI into a URI according to the rules of 
fn:escapehtmluri  Escapes a URI in the same way that HTML user agents handle attribute values expected to contain URIs. 
Resolves a relative IRI reference against an absolute IRI.
This function is
The function is defined to operate on IRI references as defined in
The following rules apply in order:
If $href
is the empty sequence, the function returns the empty
sequence.
If $href
is an absolute IRI (as defined above), then it is returned
unchanged.
If the $base
argument is not supplied,
If the static base URI in the static context is not absent, it is used as the effective
value of $base
.
Otherwise, a dynamic error is raised:
The function resolves the relative IRI reference $href
against the base IRI $base
using the algorithm defined in
The first form of this function resolves $href
against the value of the
baseuri property from the static context. A dynamic error is raised
A dynamic error is raised $href
is not a valid IRI according to the rules of RFC3987, extended with an
implementationdefined subset of the extensions permitted in LEIRI, or if it is not a
suitable relative reference to use as input to the RFC3986 resolution algorithm extended
to handle additional unreserved characters.
A dynamic error is raised $base
is
not a valid IRI according to the rules of RFC3987, extended with an
implementationdefined subset of the extensions permitted in LEIRI, or if it is not a
suitable IRI to use as input to the chosen resolution algorithm (for example, if it is a
relative IRI reference
A dynamic error is raised
Resolving a URI does not dereference it. This is merely a syntactic operation on two
The algorithms in the cited RFCs include some variations that are optional or recommended rather than mandatory; they also describe some common practices that are not recommended, but which are permitted for backwards compatibility. Where the cited RFCs permit variations in behavior, so does this specification.
Throughout this family of specifications, the phrase "resolving a relative URI (or IRI) reference" should be understood as using the rules of this function, unless otherwise stated.
RFC3986 defines an algorithm for resolving relative references
in the context of the URI syntax defined in that RFC. RFC3987 describes a modification
to that algorithm to make it applicable to IRIs (specifically: additional characters
permitted in an IRI are handled the same way that RFC3986 handles unreserved characters).
The LEIRI specification does not explicitly define a resolution algorithm, but suggests
that it
Changed in 4.0: The optional second argument can now be supplied as an empty sequence.
Encodes reserved characters in a string that is intended to be used in the path segment of a URI.
This function is
If $value
is the empty sequence, the function returns the zerolength
string.
This function applies the URI escaping rules defined in section 2 of xs:string
supplied as $value
. The
effect of the function is to escape reserved characters. Each such character in the
string is replaced with its percentencoded form as described in
Since
All characters are escaped except those identified as “unreserved” by A
to Z
,
the digits 0
to 9
, HYPHENMINUS (
),
LOW LINE (_
), FULL STOP (.
), and TILDE (~
).
This function escapes URI delimiters and therefore cannot be used indiscriminately to encode “invalid” characters in a path segment.
This function is invertible but not idempotent. This is because a string containing a
percent character will be modified by applying the function: for example
100%
becomes 100%25
, while 100%25
becomes
100%2525
.
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result: 
Decodes URIescaped characters in a string.
This function is
This function returns the original representation of a URIescaped string.
If $value
is the empty sequence, the function returns the zerolength
string.
Otherwise, the value is first converted to a sequence of octets. Each plus sign
(+
) is replaced with the octet representing a space character
(x20
), and any substring that matches the regular expression
%[afAF09][afAF09]
is replaced with an octet for the twodigit
hexadecimal number that follows the percent sign. Characters that are not part of
such a substring are replaced with the octets of their UTF8 encoding.
For example, "A%42+C"
results in the octets x41
,
x42
, x20
, x43
, and "💡"
yields
xF0
, x9F
, x92
, and xA1
.
If %
is followed by up to two characters that are not hexadecimal digits,
these characters are replaced by octets xEF
, xBF
,
and xBD
, that is, the UTF8 encoding of the Unicode replacement character
(U+FFFD
). For example, the incomplete or invalid percentencoded strings
"%"
, "%X"
, "%AX"
, and "%XA"
are all
replaced with these octets. For the string "%1X!"
, the octets xEF
,
xBF
, xBD
, and x21
are returned.
Next, the resulting octets are interpreted as UTF8. For example,
x41
, x42
, x20
, and x43
becomes "AB C"
, and xF0
, x9F
,
x92
, and xA1
becomes "💡"
.
If an invalid UTF8 octet sequence is encountered, the octets that have successfully been parsed are replaced with a Unicode replacement character. Examples:
The single octet xF0
is converted to "�"
.
The octets xF0
, x9F
, x92
, and
x41
are converted to "�A"
:
The bit pattern of the first octet indicates that the UTF8 character comprises
four octets. As the fourth octet is invalid, a Unicode replacement character is
added for the first three octets, and the fourth (invalid) octet is parsed as a
new character.
Similarly, the octets xF0
, xF0
, x9F
,
x92
, and xA1
are converted to "�💡"
:
The second octet is invalid, but it becomes valid when being parsed as the
first octet of the remaining UTF8 sequence.
Similarly, a UTF8 octet sequence that represents a codepoint that is not a
valid XML character is replaced with a Unicode replacement character.
For example, x00
becomes "�"
.
Expression  Result 

decodefromuri("http://example.com/")  
decodefromuri("~b%C3%A9b%C3%A9?a=b+c")  
decodefromuri("%00%XX%F0%9F%92%41%F0%F0%9F%92%A1") 
Converts a string containing an IRI into a URI according to the rules of
This function is
If $value
is the empty sequence, the function returns the zerolength
string.
Otherwise, the function converts $value
into a URI according to
the rules given in Section 3.1 of $value
contains a character
that is invalid in an IRI, such as the space character (see note below), the invalid
character is replaced by its percentencoded form as described in
Since
The function is idempotent but not invertible. Both the inputs My Documents
and My%20Documents
will be converted to the output
My%20Documents
.
This function does not check whether $iri
is a valid IRI. It treats it as
an
The following printable ASCII characters are invalid in an IRI: <
, >
,
"
,
, {
, }
, 
,
\
, ^
, and `
. Since these
characters should not appear in an IRI, if they do appear in $iri
they will
be percentencoded. In addition, characters outside the range x20x7E will be
percentencoded because they are invalid in a URI.
Since this function does not escape the PERCENT SIGN %
and this character is not
allowed in data within a URI, users wishing to convert character strings (such as file
names) that include %
to a URI should manually escape %
by replacing it with %25
.
Expression:  

Result:  
Expression: 

Result: 
Escapes a URI in the same way that HTML user agents handle attribute values expected to contain URIs.
This function is
If $value
is the empty sequence, the function returns the zerolength
string.
Otherwise, the function escapes all $uri
to be escaped is replaced by an escape sequence, which is
formed by encoding the character as a sequence of octets in UTF8, and then representing
each of these octets in the form %HH, where HH is the hexadecimal representation of the
octet. This function must always generate hexadecimal values using the uppercase
letters AF.
The behavior of this function corresponds to the recommended handling of nonASCII
characters in URI attribute values as described in
Expression:  

Result:  
Expression:  
Result: 
This section specifies functions that parse strings as URIs, to identify their structure, and construct URI strings from their structured representation.
Some URI schemes are hierarchical and some are nonhierarchical.
Implementations must treat the following schemes as nonhierarchical:
jar
, mailto
, news
, tag
,
tel
, and urn
. Whether additional schemes
are known to be nonhierarchical
Function  Meaning 

fn:parseuri  Parses the URI provided and returns a map of its parts. 
fn:builduri  Constructs a URI from the parts provided. 
The structured representation of a URI is described by the
uristructurerecord
:
The parts of this structure are:
uri  The original URI. This element is returned by fn:parseuri ,
but ignored by fn:builduri . 
scheme  The URI scheme (e.g., “https” or “file”). 
hierarchical  Whether the URI is hierarchical or not. 
authority  The authority portion of the URI (e.g., “example.com:8080”). 
userinfo  Any userinfo that was passed as part of the authority. 
host  The host passed as part of the authority (e.g., “example.com”). 
port  The port passed as part of the authority (e.g., “8080”). 
path  The path portion of the URI. 
query  Any query string. 
fragment  Any fragment identifier. 
pathsegments  Parsed and unescaped path segments. 
queryparameters  Parsed and unescaped query keyvalue pairs. 
filepath  The path of the URI, treated as a filepath. 
*  Additional, information defined structures are allowed. 
The segmented forms of the path and query parameters provide convenient access to commonly used information.
The path, if there is one, is tokenized on “/” characters and
each segment is unescaped (as per the fn:decodefromuri
function). Consider the URI
http://example.com/path/to/a%2fb
.
The path portion has to be returned as /path/to/a%2fb
because
decoding the %2f
would change the nature of the path.
The unescaped form is easily accessible from pathsegments
:
Note that the presence or absence of a leading slash on the path will affect whether or not the sequence begins with an empty string.
The query parameters are decoded into a map. Consider the URI:
http://example.com/path?a=1&b=2%264&a=3
.
The decoded form in the queryparameters is the following map:
Note that both keys and values are unescaped. If a key
is repeated in the query string, the map will contain a
sequence of values for that key, as seen for a
in this example.
Parses the URI provided and returns a map of its parts.
This function is
The function parses the $uri
provided,
returning a map containing its constituent parts: scheme,
authority components, path, etc.
In addition to parsing URIs as defined by
The following options are available:
Key  Meaning 

pathseparator  Identifies the path separator

queryseparator  Identifies the query separator

allowdeprecatedfeatures  Indicates that deprecated URI
features should be returned

omitdefaultports  Indicates that a port number that is the same as
the default port for a given scheme should be omitted.

uncpath  Indicates that an input URI that begins
with two or more leading slashes should be interprted
as a Windows Universal Naming Convention
Path. (Specifically: that it has the file: scheme.)

This function is described as a series of transformations over the input string to identify the parts of a URI that are present. Some portions of the URI are identified by matching with a regular expression. This approach is designed to make the description clear and unambiguous; it is not implementation advice.
Processing begins with a $uri
. If the \
), replace them with forward
slashes (/
).
Strip off the fragment identifier and any query:
If the ^(.*?)#(.*)$
,
the
If the ^(.*?)\?(.*)$
,
the
Attempt to identify the scheme:
If the ^[azAZ][:].*$
:
the file
;
if the second character in the 
, it is changed to :
;
the
a leading slash /
is added to the
Otherwise, if the ^([azAZ][AZaz09\+\\.]*):(.*)$
:
the
the
the
Finally, if the
the
the
the
Now that the scheme, if there is one, has been identified, determine if the URI is hierarchical:
If the true
if /
and
false
otherwise.
Then examine the remaining parts of the string.
If the uncpath
option is true
, and the
^//[^/].*$
, then the
scheme is file
, the
Otherwise:
If the scheme is not known or is known to be file
and the ^/*(/[azAZ][:].*)$
,
the 
,
it is changed to :
.
Otherwise, if the ^///*([^/]+)?(/.*)?$
, the
Finally, if the
If the ^(([^@]*)@)(.*)(:([^:]*))?$
,
then the allowdeprecatedfeatures
option is true
.
When parsing the example.com
), an IPv4 address (e.g., 127.0.0.1
),
an IPv6 (or IPvFuture) address (e.g., [::1]
), or an error
if there is an open square bracket ([
) not matched by a
close square bracket (]
). In a properly
constructed RFC 3986 URI, the only place where square
brackets may occur is around the IPv6/IPvFuture IP address.
If the ^(([^@]*)@)?(\[[^\]]*\])(:([^:]*))?$
,
then the
If the ^(([^@]*)@)?\[.*$
then
If the ^(([^@]*)@)?([^:]+)(:([^:]*))?$
,
then the
the
This function does not attempt to decode the components of the
Similar care must be taken to match the port because an IPv6/IPvFuture address may contain a colon.
If the ^(([^@]*)@)?(\[[^\]]*\])(:([^:]*))?$
,
then the
Otherwise, if the ^(([^@]*)@)?([^:]+)(:([^:]*))?$
,
then the
Otherwise, the
If the omitdefaultports
option is true
, the port
is discarded and set to the empty sequence if the port number is the same
as the default port for the given scheme. Implementations http
(80), https
(443),
ftp
(21), and ssh
(22). Exactly which ports are
recognized
is
If the file
or the empty sequence, and
The pathseparator
option. A
Applying fn:decodefromuri
on the string.
The queryseparator
option, and is used to construct
a =
), the
If the
The following map is returned:
The map should be populated with only those keys that have a nonempty value (keys
whose value is the empty sequence
Implementations may implement additional or different rules for URIs that
have a scheme or pattern that they recognize. An implementation might choose
to parse jar:
URIs with special rules, for example, since they extend the
syntax in ways not defined by
A dynamic error is raised
Like fn:resolveuri
, this function handles the additional characters
allowed in
Unlike fn:resolveuri
, this function is not attempting to resolve
one URI against another and consequently, the errors that can arise under those
circumstances do not apply here. The fn:parseuri
function will
accept strings that would raise errors if resolution was attempted;
see fn:builduri
.
In the examples that follow, keys with values that are null or an empty sequence
are elided for editorial clarity. String literals that include an ampersand character
are written as string templates (for example  
Expression:  

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression:  
Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression: 

Result:  
Expression:  
Result:  
Expression: 

Result:  
Expression: 

Result:  
This example uses the algorithm described above, not an algorithm that is
specifically aware of the  
Expression:  
Result:  
This example demonstrates that parsing the URI treats nonURI characters in
lexical IRIs as “unreserved characters”. The rationale for this is given in the
description of  
Expression: 

Result:  
This example demonstrates a nonstandard query separator.  
Expression:  
Result:  
This example uses an invalid query separator so raises an error.  
Expression:  
Result:  Raises error FOXX0000. 
This example demonstrates the use of  
Expression: 

Result:  
This example demonstrates the use of  
Expression: 

Result: 
Proposed on 17 Oct 2022 to resolve
Constructs a URI from the parts provided.
This function is
A URI is composed from a scheme, authority, path, query, and fragment.
The following options are available:
Key  Meaning 

pathseparator  Identifies the path separator

queryseparator  Identifies the query separator

allowdeprecatedfeatures  Indicates that deprecated URI
features should be returned

omitdefaultports  Indicates that a port number that is the same as
the default port for a given scheme should be omitted.

uncpath  Indicates that the URI represents
a Windows Universal Naming Convention
Path.

The components are derived from the contents of the
$parts
map. To simplify the description below, a
value is considered to be present in the map if the relevant
field exists and is nonempty.
If the scheme
key is present in the map,
the URI begins with the value of that key. A URI is considered to be
nonhierarchical if either the hierarchical
key
is present in the $parts
map with the value
false()
or if the scheme is known to be
nonhierarchical. (In other words, schemes are hierarchical by
default.)
If the scheme
is
known to be nonhierarchical, it is delimited by a trailing
:
.
Otherwise, if the scheme
is file
and the uncpath
option is true
, the scheme is delimited by a trailing :////
.
Otherwise, the scheme is delimited by
a trailing ://
.
For simplicity of exposition, we take the
userinfo
, host
, and
port
values from the map and imagine they are
stored in variables with the same name. If the key is not
present in the map, the value of the variable is set to the
empty sequence.
If $userinfo
is nonempty and contains a
nonempty password, then $userinfo
is set to the
empty sequence unless the
allowdeprecatedfeatures
option is true
.
If the omitdefaultports
option is true
then the $port
is set to the empty sequence if
the port number is the same as the default port for the given
scheme. Implementations http
(80),
https
(443), ftp
(21), and
ssh
(22). Exactly which ports are recognized is
If any of $userinfo
, $host
, or $port
exist, the following authority is added to the URI under construction:
If none of userinfo
, host
, or port
is present, and authority
is present, the value of the
authority
key is added to the URI. (In this case, no attempt
is made to determine if a password or standard port are present,
the authority
value is simply added to the string.)
If the pathsegments
key exists in the map, then the
path is constructed from the parts, with nonURI characters encoded:
stringjoin($parts?pathsegments ! encodeforuri(.), $options?pathseparator)
,
otherwise the value of the path
key is used.
If the path
value is the empty sequence,
the empty string is used for the path. The path is added to the URI.
If the queryparameters
key exists in the map, its value
must be a map. A sequence of strings is constructed from the values in the map.
For each
If the encodeforuri
.
Otherwise, the string constructed is the value of the
=
),
followed by the
The query is constructed by joining the resulting
strings into a single string, separated by $options?queryseparator
).
If the queryparameters
key does not exist in the map, but
the query
key does, then the query is the value of the
query
key. If there is a query, it is added to the URI with
a preceding question mark (?
).
If the fragment
key exists in the map, then
the value of that key is added to the URI with
a preceding hash mark (#
).
The resulting URI is returned.
Expression:  

Result: 
Proposed on 17 Oct 2022 to resolve
This section defines functions and operators on the xs:boolean
datatype.
Since no literals are defined in XPath to reference the constant boolean values true
and false
,
two functions are provided for the purpose.
Function  Meaning 

fn:true  Returns the xs:boolean value true . 
fn:false  Returns the xs:boolean value false . 
Returns the xs:boolean
value true
.
This function is
The result is equivalent to xs:boolean("1")
.
Expression  Result 

true() 
Returns the xs:boolean
value false
.
This function is
The result is equivalent to xs:boolean("0")
.
Expression  Result 

false() 
The following functions define the semantics of operators on boolean values in
Function  Meaning 

op:booleanequal  Returns true if the two arguments are the same boolean value. 
op:booleanlessthan  Returns true if the first argument is false and the second is true . 
The ordering operator op:booleanlessthan
is provided for application purposes
and for compatibility with xs:boolean
is not ordered.
Returns true
if the two arguments are the same boolean value.
Defines the semantics of the eq
operator when applied to two xs:boolean
values.
The function returns true
if both arguments are true
or if
both arguments are false
. It returns false
if one of the
arguments is true
and the other argument is false
.
Returns true
if the first argument is false
and the second is true
.
Defines the
semantics of the lt
operator when applied to two xs:boolean
values. Also
used in the definition of the ge
operator.
The function returns true
if $arg1
is false
and
$arg2
is true
. Otherwise, it returns
false
.
The following functions are defined on boolean values:
Function  Meaning 

fn:boolean  Computes the effective boolean value of the sequence $input . 
fn:not  Returns true if the effective boolean value of $input is
false , or false if it is true . 
Computes the effective boolean value of the sequence $input
.
The function computes the effective boolean value of a sequence, defined according to
the following rules. See also
If $input
is the empty sequence, fn:boolean
returns
false
.
If $input
is a sequence whose first item is a node,
fn:boolean
returns true
.
If $input
is a singleton value of type xs:boolean
or a
derived from xs:boolean
, fn:boolean
returns
$input
.
If $input
is a singleton value of type xs:untypedAtomic
,
xs:string
, xs:anyURI
, or a type derived from xs:string
or xs:anyURI
, fn:boolean
returns false
if the operand value has
zero length; otherwise it returns true
.
If $input
is a singleton value of any numeric type or a type derived
from a numeric type, fn:boolean
returns false
if the
operand value is NaN
or is numerically equal to zero; otherwise it
returns true
.
In all cases other than those listed above, fn:boolean
raises a type error
The result of this function is not necessarily the same as $input cast as
xs:boolean
. For example, fn:boolean("false")
returns the value
true
whereas "false" cast as xs:boolean
(which can also be
written xs:boolean("false")
) returns false
.
Variables  

Expression  Result 

boolean($abc[1])  
boolean($abc[0])  
boolean($abc[3])  
 

Returns true
if the effective boolean value of $input
is
false
, or false
if it is true
.
This function is
The value of $input
is first reduced to an effective boolean value by
applying the fn:boolean()
function. The function returns true
if the effective boolean value is false
, or false
if the
effective boolean value is true
.
Expression  Result 

not(true())  
not(())  
not("false")  

Operators are defined on the following type:
xs:duration
and on the two defined subtypes (see
xs:yearMonthDuration
xs:dayTimeDuration
No ordering relation is defined on xs:duration
values.
Two xs:duration
values may however be compared for equality.
A value of type xs:duration
is considered to comprise two parts:
The total number of months, represented as a signed integer.
The total number of seconds, represented as a signed decimal number.
If one of these values is negative (less than zero), the other must not be positive (greater than zero).
In effect this means that operations on durations (including equality comparison,
casting to string, and extraction of components)
all treat the duration as normalized. The duration PT1M30S
(one minute and
thirty seconds), for example,
is precisely equivalent to the duration PT90S
(ninety seconds); these are
different representations of the same value, and the result of any operation will be
the same regardless which representation is used. For example, the function
fn:secondsfromduration
returns 30 in both cases.
The information content of an xs:duration
value can be reduced to an xs:integer
number of months, and an xs:decimal
number of seconds. For the two defined subtypes this is further simplified so that one of these two
components is fixed at zero. Operations such as comparison of durations and arithmetic on durations
can be expressed in terms of numeric operations applied to these two components.
Two subtypes of xs:duration
, namely xs:yearMonthDuration
and xs:dayTimeDuration
, are defined in
The significance of these subtypes is that arithmetic and ordering become well defined; this is not the
case for xs:duration
values in general, because of the variable number of days in a month. For this reason, many of the functions
and operators on durations require the arguments/operands to belong to these two subtypes.
In an xs:yearMonthDuration
, the seconds component is always zero.
In an xs:dayTimeDuration
, the months component is always zero.
All
The total number of months can be represented as a signed xs:int
value;
The total number of seconds can be represented as a signed xs:decimal
value with facets totalDigits=18
and fractionalDigits=3
. That is,
durations must be supported to millisecond precision.
Processors
A processor that limits the range or precision of duration values
may encounter overflow and underflow conditions when it
tries to evaluate operations on durations. In
these situations, the processor
Similarly, a processor may be unable accurately to represent the result of dividing a duration
by 2, or multiplying a duration by 0.5. A processor that limits the precision of the seconds component
of duration values
Function  Meaning 

op:yearMonthDurationlessthan  Returns true if $arg1 is a shorter duration than $arg2 . 
op:dayTimeDurationlessthan  Returns true if $arg1 is a shorter duration than $arg2 . 
op:durationequal  Returns true if $arg1 and $arg2 are durations of the same
length. 
The following comparison operators are defined on the xs:boolean
result. As discussed in xs:duration
is a partial order rather than
a total order. For this reason, only equality is defined on xs:duration
.
A full complement of comparison and
arithmetic functions are defined on the two subtypes of duration described in
Returns true
if $arg1
is a shorter duration than $arg2
.
Defines
the semantics of the lt
operator when applied to two xs:yearMonthDuration
values. Also used in the definition of the ge
operator.
If the number of months in $arg1
is numerically less than the
number of months in $arg2
, the function returns true
.
Otherwise, the function returns false
.
Either or both durations may be negative.
Returns true
if $arg1
is a shorter duration than $arg2
.
Defines the
semantics of the lt
operator when applied to two xs:dayTimeDuration
values.
Also used in the definition of the ge
operator.
If the number of seconds in $arg1
is numerically less than the
number of seconds in $arg2
, the function returns true
.
Otherwise, the function returns false
.
Either or both durations may be negative
Returns true
if $arg1
and $arg2
are durations of the same
length.
Defines the
semantics of the eq
operators when applied to two xs:duration
values. Also
used in the definition of the ne
operator.
If the xs:yearMonthDuration
components of $arg1
and
$arg2
are equal and the xs:dayTimeDuration
components of
$arg1
and $arg2
are equal, the function returns
true
.
Otherwise, the function returns false
.
The semantics of this function are:
that is, the function returns true
if the months and seconds values of the
two durations are equal.
Note that this function, like any other, may be applied to arguments that are derived
from the types given in the function signature, including the two subtypes
xs:dayTimeDuration
and xs:yearMonthDuration
. With the
exception of the zerolength duration, no instance of xs:dayTimeDuration
can ever be equal to an instance of xs:yearMonthDuration
.
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result: 
The duration datatype may be considered to be a composite datatype
in that it contains distinct properties or components. The extraction functions specified
below extract a single component from a duration value.
For xs:duration
and its subtypes, including the two subtypes xs:yearMonthDuration
and
xs:dayTimeDuration
, the components are normalized: this means that the seconds and minutes
components will always be less than 60, the hours component less than 24, and the months component less than 12.
Function  Meaning 

fn:yearsfromduration  Returns the number of years in a duration. 
fn:monthsfromduration  Returns the number of months in a duration. 
fn:daysfromduration  Returns the number of days in a duration. 
fn:hoursfromduration  Returns the number of hours in a duration. 
fn:minutesfromduration  Returns the number of minutes in a duration. 
fn:secondsfromduration  Returns the number of seconds in a duration. 
Returns the number of years in a duration.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the years
component in $value
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($months idiv 12)
.
If $value
is a negative duration then the result will be negative.
If $value
is an xs:dayTimeDuration
the function
returns 0
.
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result: 

Returns the number of months in a duration.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the months
component in $value
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($months mod 12)
.
If $value
is a negative duration then the result will be negative.
If $value
is an xs:dayTimeDuration
the function
returns 0
.
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result: 

Returns the number of days in a duration.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the days
component in $value
. Given that a duration
is a ($months, $seconds)
tuple, the result is ($seconds idiv 86400)
.
If $value
is a negative duration then the result will be negative.
If $value
is an xs:yearMonthDuration
the function returns 0
.
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result: 

Returns the number of hours in a duration.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the hours
component in $value
. ($months, $seconds)
tuple, the result is the value of ($seconds mod 86400) idiv 3600
If $value
is a negative duration then the result will be negative.
If $value
is an xs:yearMonthDuration
the function returns 0
.
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result: 

Returns the number of minutes in a duration.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the minutes
component in $value
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($seconds mod 3600) idiv 60
.
If $value
is a negative duration then the result will be negative.
If $value
is an xs:yearMonthDuration
the function returns 0
.
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result: 

Returns the number of seconds in a duration.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:decimal
representing the seconds
component in $value
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($seconds mod 60)
as an xs:decimal
.
If $value
is a negative duration then the result will be negative.
If $value
is an xs:yearMonthDuration
the function returns 0
.
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result: 

Expression:  
Result: 

This section decribes the fn:seconds
function, which constructs
an xs:dayTimeDuration
value representing a decimal number of seconds.
Function  Meaning 

fn:seconds  Returns an xs:dayTimeDuration whose length is a given number of seconds. 
Returns an xs:dayTimeDuration
whose length is a given number of seconds.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:dayTimeDuration
value whose length
in seconds is equal to $value
.
If $value
is negative then the result will be a negative duration.
For handling of overflow and underflow, see
The result of seconds($n)
is approximately equal to the result of
the expression xs:dayTimeDuration('PT1S') * $n
. The equivalence is only
approximate, because seconds($n)
uses the exact xs:decimal
value supplied, whereas multiplying a duration by a number first promotes the number
to an xs:double
value, which may lose precision.
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result: 

Expression:  
Result: 

Function  Meaning 

op:addyearMonthDurations  Returns the result of adding two xs:yearMonthDuration values. 
op:subtractyearMonthDurations  Returns the result of subtracting one xs:yearMonthDuration value from
another. 
op:multiplyyearMonthDuration  Returns the result of multiplying $arg1 by $arg2 .
The result is rounded to the nearest month. 
op:divideyearMonthDuration  Returns the result of dividing $arg1 by $arg2 .
The result is rounded to the nearest month. 
op:divideyearMonthDurationbyyearMonthDuration  Returns the ratio of two xs:yearMonthDuration values. 
op:adddayTimeDurations  Returns the sum of two xs:dayTimeDuration values. 
op:subtractdayTimeDurations  Returns the result of subtracting one xs:dayTimeDuration from another. 
op:multiplydayTimeDuration  Returns the result of multiplying a xs:dayTimeDuration by a number. 
op:dividedayTimeDuration  Returns the result of multiplying a xs:dayTimeDuration by a number. 
op:dividedayTimeDurationbydayTimeDuration  Returns the ratio of two xs:dayTimeDuration values, as a decimal
number. 
For operators that combine a duration and a date/time value, see
Returns the result of adding two xs:yearMonthDuration
values.
Defines the semantics of the
+
operator when applied to two xs:yearMonthDuration
values.
The function returns the result of adding $arg1
to $arg2
.
The result will be an xs:yearMonthDuration
whose
length in months is equal to the length in months of $arg1
plus the length
in months of $arg2
.
For handling of overflow, see
Either duration (and therefore the result) may be negative.
Expression:  

Result: 
Returns the result of subtracting one xs:yearMonthDuration
value from
another.
Defines the semantics of the

operator when applied to two xs:yearMonthDuration
values.
The function returns the result of subtracting $arg2
from
$arg1
. The result will be an xs:yearMonthDuration
whose length in months is equal to the length in months of $arg1
minus the
length in months of $arg2
.
For handling of overflow, see
Either duration (and therefore the result) may be negative.
Expression:  

Result: 
Returns the result of multiplying $arg1
by $arg2
.
The result is rounded to the nearest month.
Defines the semantics of the
*
operator when applied to an xs:yearMonthDuration
and a numeric
value.
The result is the xs:yearMonthDuration
whose length in months is equal to
the result of applying the fn:round
function to the value obtained by
multiplying the length in months of $arg1
by the value of
$arg2
.
If $arg2
is positive or negative zero, the result is a zerolength
duration. If $arg2
is positive or negative infinity, the result overflows
and is handled as described in
For handling of overflow, underflow, and rounding, see
A dynamic error is raised $arg2
is
NaN
.
Either duration (and therefore the result) may be negative.
Expression:  

Result: 
Returns the result of dividing $arg1
by $arg2
.
The result is rounded to the nearest month.
Defines the semantics of the
div
operator when applied to an xs:yearMonthDuration
and a numeric
value.
The result is the xs:yearMonthDuration
whose length in months is equal to
the result of applying the fn:round
function to the value obtained by
dividing the length in months of $arg1
by the value of
$arg2
.
If $arg2
is positive or negative infinity, the result is a zerolength
duration. If $arg2
is positive or negative zero, the result overflows and
is handled as described in
For handling of overflow, underflow, and rounding,
see
A dynamic error is raised $arg2
is
NaN
.
Either operand (and therefore the result) may be negative.
Expression:  

Result: 
Returns the ratio of two xs:yearMonthDuration
values.
Defines the semantics of the
div
operator when applied to two xs:yearMonthDuration
values.
The function returns the result of dividing the length in months of $arg1
by the length in months of $arg2
, according to the rules of the
op:numericdivide
function for integer operands.
For handling of overflow, underflow, and rounding,
see
Either duration (and therefore the result) may be negative.
Expression:  

Result:  
The following example demonstrates how to calculate the length of an
 
Expression:  
Result: 
Returns the sum of two xs:dayTimeDuration
values.
Defines the semantics of the +
operator when applied to two xs:dayTimeDuration
values.
The function returns the result of adding $arg1
to
$arg2
. The result is the xs:dayTimeDuration
whose length in
seconds is equal to the sum of the length in seconds of the two input durations.
For handling of overflow, see
Either duration (and therefore the result) may be negative.
Expression:  

Result: 
Returns the result of subtracting one xs:dayTimeDuration
from another.
Defines the semantics of the 
operator when applied to two xs:dayTimeDuration
values.
The function returns the result of subtracting $arg2
from
$arg1
. The result is the xs:dayTimeDuration
whose
length in seconds is equal to the length in seconds of $arg1
minus the
length in seconds of $arg2
.
For handling of overflow, see
Either duration (and therefore the result) may be negative.
Expression:  

Result: 
Returns the result of multiplying a xs:dayTimeDuration
by a number.
Defines the semantics of the *
operator when applied to an xs:dayTimeDuration
and a numeric
value.
The function returns the result of multiplying $arg1
by
$arg2
. The result is the xs:dayTimeDuration
whose length in
seconds is equal to the length in seconds of $arg1
multiplied by the
numeric value $arg2
.
If $arg2
is positive or negative zero, the result is a zerolength
duration. If $arg2
is positive or negative infinity, the result overflows
and is handled as described in
For handling of overflow, underflow, and rounding, see
A dynamic error is raised $arg2
is
NaN
.
Either operand (and therefore the result) may be negative.
Expression:  

Result: 
Returns the result of multiplying a xs:dayTimeDuration
by a number.
Defines the semantics of the
div
operator when applied to two xs:dayTimeDuration
values.
The function returns the result of dividing $arg1
by
$arg2
. The result is the xs:dayTimeDuration
whose length in
seconds is equal to the length in seconds of $arg1
divided by the numeric
value $arg2
.
If $arg2
is positive or negative infinity, the result is a zerolength
duration. If $arg2
is positive or negative zero, the result overflows and
is handled as described in
For handling of overflow, underflow, and rounding, see
A dynamic error is raised $arg2
is
NaN
.
Either operand (and therefore the result) may be negative.
Expression:  

Result: 
Returns the ratio of two xs:dayTimeDuration
values, as a decimal
number.
Defines the semantics of the
div
operator when applied to two xs:dayTimeDuration
values.
The function returns the result of dividing $arg1
by
$arg2
. The result is the xs:dayTimeDuration
whose length in
seconds is equal to the length in seconds of $arg1
divided by the length in
seconds of $arg2
. The calculation is performed by applying
op:numericdivide
to the two xs:decimal
operands.
For handling of overflow, underflow, and rounding,
see
Either operand (and therefore the result) may be negative.
Expression:  

Result:  
This examples shows how to determine the number of seconds in a duration.  
Expression:  
Result: 
This section defines operations on the
See
The operators described in this section are defined on the following date and time types:
xs:dateTime
xs:date
xs:time
xs:gYearMonth
xs:gYear
xs:gMonthDay
xs:gMonth
xs:gDay
The only operation defined on
xs:gYearMonth
, xs:gYear
,
xs:gMonthDay
, xs:gMonth
and xs:gDay
values is
equality comparison.
For other types, further operations are provided, including component extraction,
order comparisons, arithmetic, formatted display, and timezone
adjustment.
All
A processor that limits the number of digits in date and time datatype
representations may encounter overflow and underflow conditions when it
tries to execute the functions in
Similarly, a processor that limits the precision of the seconds component
of date and time or duration values may need to deliver a rounded result for arithmetic operations.
Such a processor
As defined in xs:dateTime
,
xs:date
, xs:time
, xs:gYearMonth
, xs:gYear
,
xs:gMonthDay
, xs:gMonth
, xs:gDay
values,
referred to collectively as date/time values, are represented as seven components or properties:
year
, month
, day
, hour
, minute
,
second
and timezone
. The first five components are
xs:integer
values. The value of the second
component is an xs:decimal
and the value of the timezone
component is an xs:dayTimeDuration
.
For all the primitive date/time datatypes, the timezone
property is optional and may or may not
be present. Depending on the datatype, some of the remaining six properties must be present and
some must be xs:dateTime
values, this local value
For xs:time
, 00:00:00
and 24:00:00
are alternate lexical forms
for the same value, whose canonical representation is 00:00:00
. For xs:dateTime
,
a time component 24:00:00
translates to 00:00:00
of the following day.
An xs:dateTime
with lexical
representation 19990531T05:00:00
is represented in the datamodel by { 1999, 5, 31, 5, 0, 0.0, () }
.
An xs:dateTime
with lexical
representation 19990531T13:20:0005:00
is represented by { 1999, 5, 31, 13, 20, 0.0, xs:dayTimeDuration("PT5H") }
.
An xs:dateTime
with lexical
representation 19991231T24:00:00
is represented by { 2000, 1, 1, 0, 0, 0.0, () }
.
An xs:date
with lexical
representation 20050228+8:00
is represented by { 2005, 2, 28, (), (), (), xs:dayTimeDuration("PT8H") }
.
An xs:time
with lexical
representation 24:00:00
is represented by { (), (), (), 0, 0, 0, () }
.
A function is provided for constructing a
xs:dateTime
value from a xs:date
value and a
xs:time
value.
Function  Meaning 

fn:dateTime  Returns an xs:dateTime value created by combining an xs:date
and an xs:time . 
Returns an xs:dateTime
value created by combining an xs:date
and an xs:time
.
This function is
If either $date
or $time
is the empty sequence the function
returns the empty sequence.
Otherwise, the function returns an xs:dateTime
whose date component is
equal to $date
and whose time component is equal to $time
.
The timezone of the result is computed as follows:
If neither argument has a timezone, the result has no timezone.
If exactly one of the arguments has a timezone, or if both arguments have the same timezone, the result has this timezone.
A dynamic error is raised
Expression  Result 


Function  Meaning 

op:dateTimeequal  Returns true if the two supplied xs:dateTime values refer to the same
instant in time. 
op:dateTimelessthan  Returns true if the first argument represents an earlier instant in time
than the second argument. 
op:dateequal  Returns true if and only if the starting instants of the two supplied
xs:date values are the same. 
op:datelessthan  Returns true if and only if the starting instant of $arg1 is
less than the starting instant of $arg2 . Returns false
otherwise. 
op:timeequal  Returns true if the two xs:time values represent the same
instant in time, when treated as being times on the same date, before adjusting the
timezone. 
op:timelessthan  Returns true if the first xs:time value represents an earlier
instant in time than the second, when both are treated as being times on the same date,
before adjusting the timezone. 
op:gYearMonthequal  Returns true if the two xs:gYearMonth values have the same starting
instant. 
op:gYearequal  Returns true if the two xs:gYear values have the same starting instant. 
op:gMonthDayequal  Returns true if the two xs:gMonthDay values have the same starting instant,
when considered as days in the same year. 
op:gMonthequal  Returns true if the two xs:gMonth values have the same starting instant,
when considered as months in the same year. 
op:gDayequal  Returns true if the two xs:gDay values have the same starting instant, when
considered as days in the same month of the same year. 
The following comparison operators are defined on the xs:boolean
result.
An xs:dateTime
can be considered to consist of seven components:
year
, month
, day
, hour
, minute
,
second
and timezone
. For xs:dateTime
six components (year
,
month
, day
, hour
, minute
and second
) are required
and timezone
is optional. For other date/time values, of the first six components, some are required
and others must be Timezone
is always optional. For example, for xs:date
,
the year
, month
and day
components are required and hour
,
minute
and second
components must be absent; for xs:time
the hour
,
minute
and second
components are required and year
, month
and
day
are missing; for xs:gDay
, day
is required and year
,
month
, hour
, minute
and second
are missing.
In explicitTimezone
facet is available with values
optional
, required
, or prohibited
to
enable the timezone to be defined as mandatory or disallowed.
Values of the date/time datatypes xs:time
, xs:gMonthDay
, xs:gMonth
,
and xs:gDay
, can be considered to represent a sequence of recurring time instants or time periods.
An xs:time
occurs every day. An xs:gMonth
occurs every year. Comparison operators
on these datatypes compare the starting instants of equivalent occurrences in the recurring series.
These xs:dateTime
values are calculated as described below.
Comparison operators on xs:date
, xs:gYearMonth
and xs:gYear
compare
their starting instants. These xs:dateTime
values are calculated as described below.
The starting instant of an occurrence of a date/time value is an xs:dateTime
calculated by filling
in the missing components of the local value from a reference xs:dateTime
. An example of a suitable
reference xs:dateTime
is 19720101T00:00:00
. Then, for example, the starting
instant corresponding to the xs:date
value 20090312
is
20090312T00:00:00
; the starting instant corresponding to the xs:time
value
13:30:02
is 19720101T13:30:02
; and the starting instant corresponding to the
gMonthDay
value 0229
is 19720229T00:00:00
(which explains
why a leap year was chosen for the reference).
In the previous version of this specification, the reference date/time chosen was
19721231T00:00:00
. While this gives the same results, it produces a "starting instant" for
a gMonth
or gMonthDay
that bears no
relation to the ordinary meaning of the term, and it also required special handling of short months.
The original choice was made to allow for leap seconds; but since leap seconds are not recognized
in date/time arithmetic, this is not actually necessary.
If the xs:time
value written as
24:00:00
is to be compared, filling in the missing components gives 19720101T00:00:00
,
because 24:00:00
is an alternative representation of 00:00:00
(the lexical value
"24:00:00"
is
converted to the time components { 0, 0, 0 } before the missing components are filled
in). This has the consequence that when ordering xs:time
values,
24:00:00
is
considered to be earlier than 23:59:59
. However, when ordering
xs:dateTime
values, a time component of 24:00:00
is considered equivalent to 00:00:00
on the
following day.
Note that the reference xs:dateTime
does not have a timezone. The timezone
component
is never filled in from the reference xs:dateTime
. In some cases, if the date/time value does not
have a timezone, the implicit timezone from the dynamic context is used as the timezone.
This specification uses the reference xs:dateTime 19720101T00:00:00
in the description of the
comparison operators. Implementations may use other reference xs:dateTime
values
as long as they yield the same results. The reference xs:dateTime
used must meet the following
constraints: when it is used to supply components into xs:gMonthDay
values, the year must allow
for February 29 and so must be a leap year; when it is used to supply missing components into xs:gDay
values, the month must allow for 31 days. Different reference xs:dateTime
values may be used for
different operators.
Returns true
if the two supplied xs:dateTime
values refer to the same
instant in time.
Defines the
semantics of the eq
operator when applied to two xs:dateTime
values. Also
used in the definition of the ne
, le
and ge
operators.
This function is
If either $arg1
or $arg2
has no timezone component, the
effective value of the argument is obtained by substituting the implicit timezone from
the dynamic evaluation context.
The function then returns true
if and only if the effective value of
$arg1
is equal to the effective value of $arg2
according to
the algorithm defined in section 3.2.7.4 of Order relation on dateTime
for xs:dateTime
values with
timezones. Otherwise the function returns false
.
Assume that the dynamic context provides an implicit timezone value of
 
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result: 
Returns true
if the first argument represents an earlier instant in time
than the second argument.
Defines the
semantics of the lt
operator when applied to two xs:dateTime
values. Also
used in the definition of the ge
operator.
This function is
If either $arg1
or $arg2
has no timezone component, the
effective value of the argument is obtained by substituting the implicit timezone from
the dynamic evaluation context.
The function then returns true
if and only if the effective value of
$arg1
is less than the effective value of $arg2
according
to the algorithm defined in section 3.2.7.4 of Order relation on dateTime
for xs:dateTime
values with
timezones. Otherwise the function returns false
.
Returns true
if and only if the starting instants of the two supplied
xs:date
values are the same.
Defines the
semantics of the eq
operator when applied to two xs:date
values. Also used
in the definition of the ne
, le
and ge
operators.
This function is
The starting instant of an xs:date
is the xs:dateTime
at time
00:00:00
on that date.
The function returns the result of the expression:
Expression  Result 

 
Returns true
if and only if the starting instant of $arg1
is
less than the starting instant of $arg2
. Returns false
otherwise.
Defines the semantics
of the lt
operator when applied to two xs:date
values. Also used in the
definition of the ge
operator.
The starting instant of an xs:date
is the xs:dateTime
at time
00:00:00
on that date.
The function returns the result of the expression:
Expression  Result 

Returns true
if the two xs:time
values represent the same
instant in time, when treated as being times on the same date, before adjusting the
timezone.
Defines the
semantics of the eq
operator when applied to two xs:time
values. Also used
in the definition of the ne
, le
and ge
operators.
This function is
Each of the supplied xs:time
values is expanded to an
xs:dateTime
value by associating the time with an arbitrary date. The
function returns the result of comparing these two xs:dateTime
values using
op:dateTimeequal
.
The result of the function is thus the same as the value of the expression:
Expression  Result 

Assume that the date components from the reference  
 

Returns true
if the first xs:time
value represents an earlier
instant in time than the second, when both are treated as being times on the same date,
before adjusting the timezone.
Defines the semantics
of the lt
operator when applied to two xs:time
values. Also used in the
definition of the ge
operator.
This function is
Each of the supplied xs:time
values is expanded to an
xs:dateTime
value by associating the time with an arbitrary date. The
function returns the result of comparing these two xs:dateTime
values using
op:dateTimelessthan
.
The result of the function is thus the same as the value of the expression:
Expression  Result 

Assume that the dynamic context provides an implicit timezone value of
 
Returns true
if the two xs:gYearMonth
values have the same starting
instant.
Defines the
semantics of the eq
operator when applied to two xs:gYearMonth
values. Also
used in the definition of the ne
operator.
This function is
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template xxxxxx01T00:00:00
. The function
returns the result of comparing these two starting instants using
op:dateTimeequal
.
Assume that the dynamic context provides an implicit timezone value of
 
 

Returns true
if the two xs:gYear
values have the same starting instant.
Defines the semantics
of the eq
operator when applied to two xs:gYear
values. Also used in the
definition of the ne
operator.
This function is
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template xxxx0101T00:00:00
. The function
returns the result of comparing these two starting instants using
op:dateTimeequal
.
Expression  Result 

Assume that the dynamic context provides an implicit timezone value of
 
 
Returns true
if the two xs:gMonthDay
values have the same starting instant,
when considered as days in the same year.
Defines the
semantics of the eq
operator when applied to two xs:gMonthDay
values. Also
used in the definition of the ne
operator.
This function is
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template 1972xxxxT00:00:00
or an equivalent.
The function returns the result of comparing these two starting instants using
op:dateTimeequal
.
Assume that the dynamic context provides an implicit timezone value of
 
Expression:  

Result: 

Expression:  
Result: 
Returns true
if the two xs:gMonth
values have the same starting instant,
when considered as months in the same year.
Defines the
semantics of the eq
operator when applied to two xs:gMonth
values. Also used
in the definition of the ne
operator.
This function is
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template 1972xx01T00:00:00
or an equivalent.
The function returns the result of comparing these two starting instants using
op:dateTimeequal
.
Expression  Result 

Assume that the dynamic context provides an implicit timezone value of
 
 
Returns true
if the two xs:gDay
values have the same starting instant, when
considered as days in the same month of the same year.
Defines the semantics
of the eq
operator when applied to two xs:gDay
values. Also used in the
definition of the ne
operator.
This function is
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template 197212xxT00:00:00
or an equivalent.
The function returns the result of comparing these two starting instants using
op:dateTimeequal
.
Expression  Result 

Assume that the dynamic context provides an implicit timezone value of
 
 
op:gDayequal(xs:gDay("12"), xs:gDay("12Z")) 
The date and time datatypes may be considered to be composite datatypes in that they contain distinct properties or components. The extraction functions specified below extract a single component from a date or time value. In all cases the local value (that is, the original value as written, without any timezone adjustment) is used.
A time written as 24:00:00
is treated as 00:00:00
on the
following day.
Function  Meaning 

fn:yearfromdateTime  Returns the year component of an xs:dateTime . 
fn:monthfromdateTime  Returns the month component of an xs:dateTime . 
fn:dayfromdateTime  Returns the day component of an xs:dateTime . 
fn:hoursfromdateTime  Returns the hours component of an xs:dateTime . 
fn:minutesfromdateTime  Returns the minute component of an xs:dateTime . 
fn:secondsfromdateTime  Returns the seconds component of an xs:dateTime . 
fn:timezonefromdateTime  Returns the timezone component of an xs:dateTime . 
fn:yearfromdate  Returns the year component of an xs:date . 
fn:monthfromdate  Returns the month component of an xs:date . 
fn:dayfromdate  Returns the day component of an xs:date . 
fn:timezonefromdate  Returns the timezone component of an xs:date . 
fn:hoursfromtime  Returns the hours component of an xs:time . 
fn:minutesfromtime  Returns the minutes component of an xs:time . 
fn:secondsfromtime  Returns the seconds component of an xs:time . 
fn:timezonefromtime  Returns the timezone component of an xs:time . 
Returns the year component of an xs:dateTime
.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the year
component in the local value of $value
. The result may be negative.
Ignoring complications that arise with midnight on the last day of the year, the year returned is the same numeric value that appears in the lexical representation, which for negative years means the meaning may vary depending on whether XSD 1.0 or XSD 1.1 conventions are in use.
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result: 
Returns the month component of an xs:dateTime
.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between 1
and
12
, both inclusive, representing the month component in the
local value of $value
.
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result: 
Returns the day component of an xs:dateTime
.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between 1
and
31
, both inclusive, representing the day component in the
local value of $value
.
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result: 
Returns the hours component of an xs:dateTime
.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between 0
and
23
, both inclusive, representing the hours component in the local value
of $value
.
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result: 
Returns the minute component of an xs:dateTime
.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
value between 0
and 59
, both inclusive, representing the minute component in the local value of
$value
.
Expression:  

Result:  
Expression:  
Result: 
Returns the seconds component of an xs:dateTime
.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:decimal
value greater than or equal
to zero and less than 60, representing the seconds and fractional seconds in the local
value of $value
.
Expression:  

Result: 
Returns the timezone component of an xs:dateTime
.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns the timezone component of $value
, if any. If
$value
has a timezone component, then the result is an
xs:dayTimeDuration
that indicates deviation from UTC; its value may
range from +14:00 to 14:00 hours, both inclusive. If $value
has no timezone
component, the result is the empty sequence.
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result: 
Returns the year component of an xs:date
.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the year in the
local value of $value
. The value may be negative.
The year returned is the same numeric value that appears in the lexical representation, which for negative years means the meaning may vary depending on whether XSD 1.0 or XSD 1.1 conventions are in use.
Expression  Result 

Returns the month component of an xs:date
.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between
1
and 12
, both
inclusive, representing the month component in the local value of $value
.
Expression  Result 

Returns the day component of an xs:date
.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between
1
and 31
, both
inclusive, representing the day component in the localized value of
$value
.
Expression  Result 

Returns the timezone component of an xs:date
.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns the timezone component of $value
, if any. If
$value
has a timezone component, then the result is an
xs:dayTimeDuration
that indicates deviation from UTC; its value may
range from +14:00 to 14:00 hours, both inclusive. If $value
has no timezone
component, the result is the empty sequence.
Expression  Result 

Returns the hours component of an xs:time
.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between
0
and 23
, both
inclusive, representing the value of the hours component in the local value of
$value
.
Expression  Result 

Assume that the dynamic context provides an implicit timezone value of
 
hoursfromtime(xs:time("11:23:00"))  
hoursfromtime(xs:time("21:23:00"))  
hoursfromtime(xs:time("01:23:00+05:00"))  
hoursfromtime(xs:time("24:00:00")) 
Returns the minutes component of an xs:time
.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
value between 0
and 59
, both inclusive, representing the value of the minutes component
in the local value of $value
.
Expression  Result 

minutesfromtime(xs:time("13:00:00Z")) 
Returns the seconds component of an xs:time
.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:decimal
value greater than or equal
to zero and less than 60, representing the seconds and fractional seconds in the local
value of $value
.
Expression  Result 

secondsfromtime(xs:time("13:20:10.5")) 
Returns the timezone component of an xs:time
.
This function is
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns the timezone component of $value
, if any. If
$value
has a timezone component, then the result is an
xs:dayTimeDuration
that indicates deviation from UTC; its value may
range from +14:00 to 14:00 hours, both inclusive. If $value
has no timezone
component, the result is the empty sequence.
Expression  Result 

timezonefromtime(xs:time("13:20:0005:00"))  
timezonefromtime(xs:time("13:20:00")) 
Function  Meaning 

fn:adjustdateTimetotimezone  Adjusts an xs:dateTime value to a specific timezone, or to no timezone at
all. 
fn:adjustdatetotimezone  Adjusts an xs:date value to a specific timezone, or to no timezone at all;
the result is the date in the target timezone that contains the starting instant of the
supplied date. 
fn:adjusttimetotimezone  Adjusts an xs:time value to a specific timezone, or to no timezone at
all. 
These functions adjust the timezone component of an xs:dateTime
, xs:date
or
xs:time
value. The $timezone
argument to these functions is defined as an
xs:dayTimeDuration
but must be a valid timezone value.
Adjusts an xs:dateTime
value to a specific timezone, or to no timezone at
all.
The oneargument form of this function is
The twoargument form of this function is
If $timezone
is not specified, then the effective value of
$timezone
is the value of the implicit timezone in the dynamic
context.
If $value
is the empty sequence, then the function returns the empty
sequence.
If $value
does not have a timezone component and $timezone
is
the empty sequence, then the result is $value
.
If $value
does not have a timezone component and $timezone
is
not the empty sequence, then the result is $value
with $timezone
as the timezone component.
If $value
has a timezone component and $timezone
is the empty
sequence, then the result is the local value of $value
without its timezone
component.
If $value
has a timezone component and $timezone
is not the
empty sequence, then the result is the xs:dateTime
value that is equal to
$value
and that has a timezone component equal to
$timezone
.
A dynamic error is raised $timezone
is less than PT14H
or greater than PT14H
or is not an
integral number of minutes.
Variables  

Assume the dynamic context provides an implicit timezone of  
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result:  
Expression:  
Result: 
Adjusts an xs:date
value to a specific timezone, or to no timezone at all;
the result is the date in the target timezone that contains the starting instant of the
supplied date.
The oneargument form of this function is
The twoargument form of this function is
If $timezone
is not specified, then the effective value of
$timezone
is the value of the implicit timezone in the dynamic
context.
If $value
is the empty sequence, then the function returns the empty
sequence.
If $value
does not have a timezone component and $timezone
is
the empty sequence, then the result is $value
.
If $value
does not have a timezone component and $timezone
is
not the empty sequence, then the result is $value
with $timezone
as the timezone component.
If $value
has a timezone component and $timezone
is the empty
sequence, then the result is the local value of $value
without its timezone
component.
If $value
has a timezone component and $timezone
is not the
empty sequence, then:
Let $dt
be the value of fn:dateTime($arg,
xs:time('00:00:00'))
.
Let $adt
be the value of fn:adjustdateTimetotimezone($dt,
$timezone)
The function returns the value of xs:date($adt)
A dynamic error is raised $timezone
is less than PT14H
or greater than PT14H
or is not an
integral number of minutes.
Variables  

Expression  Result 

Assume the dynamic context provides an implicit timezone of  
 
 
Adjusts an xs:time
value to a specific timezone, or to no timezone at
all.
The oneargument form of this function is
The twoargument form of this function is
If $timezone
is not specified, then the effective value of
$timezone
is the value of the implicit timezone in the dynamic
context.
If $value
is the empty sequence, then the function returns the empty
sequence.
If $value
does not have a timezone component and $timezone
is
the empty sequence, then the result is $value
.
If $value
does not have a timezone component and $timezone
is
not the empty sequence, then the result is $value
with $timezone
as the timezone component.
If $value
has a timezone component and $timezone
is the empty
sequence, then the result is the localized value of $value
without its
timezone component.
If $value
has a timezone component and $timezone
is not the
empty sequence, then:
Let $dt
be the xs:dateTime
value
fn:dateTime(xs:date('19721231'), $value)
.
Let $adt
be the value of fn:adjustdateTimetotimezone($dt,
$timezone)
The function returns the xs:time
value
xs:time($adt)
.
A dynamic error is raised $timezone
is less than PT14H
or greater than PT14H
or if does not
contain an integral number of minutes.
Variables  

Expression  Result 

Assume the dynamic context provides an implicit timezone of  
These functions support adding or subtracting a duration value to or from an
xs:dateTime
, an xs:date
or an xs:time
value. Appendix E of
Function  Meaning 

op:subtractdateTimes  Returns an xs:dayTimeDuration representing the amount of elapsed time
between the instants arg2 and arg1 . 
op:subtractdates  Returns the xs:dayTimeDuration that corresponds to the elapsed time between
the starting instant of $arg2 and the starting instant of
$arg2 . 
op:subtracttimes  Returns the xs:dayTimeDuration that corresponds to the elapsed time between
the values of $arg2 and $arg1 treated as times on the same
date. 
op:addyearMonthDurationtodateTime  Returns the xs:dateTime that is a given duration after a specified
xs:dateTime (or before, if the duration is negative). 
op:adddayTimeDurationtodateTime  Returns the xs:dateTime that is a given duration after a specified
xs:dateTime (or before, if the duration is negative). 
op:subtractyearMonthDurationfromdateTime  Returns the xs:dateTime that is a given duration before a specified
xs:dateTime (or after, if the duration is negative). 
op:subtractdayTimeDurationfromdateTime  Returns the xs:dateTime that is a given duration before a specified
xs:dateTime (or after, if the duration is negative). 
op:addyearMonthDurationtodate  Returns the xs:date that is a given duration after a specified
xs:date (or before, if the duration is negative). 
op:adddayTimeDurationtodate  Returns the xs:date that is a given duration after a specified
xs:date (or before, if the duration is negative). 
op:subtractyearMonthDurationfromdate  Returns the xs:date that is a given duration before a specified
xs:date (or after, if the duration is negative). 
op:subtractdayTimeDurationfromdate  Returns the xs:date that is a given duration before a specified
xs:date (or after, if the duration is negative). 
op:adddayTimeDurationtotime  Returns the xs:time value that is a given duration after a specified
xs:time (or before, if the duration is negative or causes wraparound
past midnight) 
op:subtractdayTimeDurationfromtime  Returns the xs:time value that is a given duration before a specified
xs:time (or after, if the duration is negative or causes wraparound
past midnight) 
A processor that limits the number of digits in date and time datatype
representations may encounter overflow and underflow conditions when it
tries to execute the functions in this section. In
these situations, the processor
The value spaces of the two totally ordered subtypes of
xs:duration
described in xs:integer
months for xs:yearMonthDuration
and xs:decimal
seconds for xs:dayTimeDuration
. If
a processor limits the number of digits allowed in the representation of
xs:integer
and xs:decimal
then overflow and
underflow situations can arise when it tries to execute the functions in
Returns an xs:dayTimeDuration
representing the amount of elapsed time
between the instants arg2
and arg1
.
Defines the semantics of the 
operator when applied to two xs:dateTime
values.
This function is
If either $arg1
or $arg2
do not contain an explicit timezone
then, for the purpose of the operation, the implicit timezone provided by the dynamic
context (See
The function returns the elapsed time between the date/time instant arg2
and the date/time instant arg1
, computed according to the algorithm given
in Appendix E of xs:dayTimeDuration
.
If the normalized value of $arg1
precedes in time the normalized value of
$arg2
, then the returned value is a negative duration.
Assume that the dynamic context provides an implicit timezone value of
 
Expression:  

Result: 
Returns the xs:dayTimeDuration
that corresponds to the elapsed time between
the starting instant of $arg2
and the starting instant of
$arg2
.
Defines the semantics of the 
operator
when applied to two xs:date
values.
This function is
If either $arg1
or $arg2
do not contain an explicit timezone
then, for the purpose of the operation, the implicit timezone provided by the dynamic
context (See
The starting instant of an xs:date
is the xs:dateTime
at
00:00:00
on that date.
The function returns the result of subtracting the two starting instants using
op:subtractdateTimes
.
If the starting instant of $arg1
precedes in time the starting instant of
$arg2
, then the returned value is a negative duration.
Expression  Result 

Assume that the dynamic context provides an implicit timezone value of
 
 
Now assume that the dynamic context provides an implicit timezone value of
 
 
Returns the xs:dayTimeDuration
that corresponds to the elapsed time between
the values of $arg2
and $arg1
treated as times on the same
date.
Defines the semantics of the 
operator
when applied to two xs:time
values.
This function is
The function returns the result of the expression:
Any other reference date would work equally well.
Expression  Result 

Assume that the dynamic context provides an implicit timezone value of
 
 
 
 

Returns the xs:dateTime
that is a given duration after a specified
xs:dateTime
(or before, if the duration is negative).
Defines the
semantics of the +
operator when applied to an xs:dateTime
and an
xs:yearMonthDuration
value.
This function is
The function returns the result of adding $arg2
to the value of
$arg1
using the algorithm described in Appendix E of $arg2
is negative, then the result xs:dateTime
precedes $arg1
.
The result has the same timezone as $arg1
. If $arg1
has no
timezone, the result has no timezone.
Expression:  

Result: 
Returns the xs:dateTime
that is a given duration after a specified
xs:dateTime
(or before, if the duration is negative).
Defines the semantics
of the +
operator when applied to an xs:dateTime
and an
xs:dayTimeDuration
value.
This function is
The function returns the result of adding $arg2
to the value of
$arg1
using the algorithm described in Appendix E of $arg2
is negative, then the result xs:dateTime
precedes $arg1
.
The result has the same timezone as $arg1
. If $arg1
has no
timezone, the result has no timezone.
Expression:  

Result: 
Returns the xs:dateTime
that is a given duration before a specified
xs:dateTime
(or after, if the duration is negative).
Defines the
semantics of the 
operator when applied to an xs:dateTime
and an
xs:yearMonthDuration
value.
This function is
The function returns the xs:dateTime
computed by negating
$arg2
and adding the result to $arg1
using the
function op:addyearMonthDurationtodateTime
.
Expression:  

Result: 
Returns the xs:dateTime
that is a given duration before a specified
xs:dateTime
(or after, if the duration is negative).
Defines the semantics
of the 
operator when applied to an xs:dateTime
an and
xs:dayTimeDuration
values
The function returns the xs:dateTime
computed by negating
$arg2
and adding the result to $arg1
using the
function op:adddayTimeDurationtodateTime
.
Expression:  

Result: 
Returns the xs:date
that is a given duration after a specified
xs:date
(or before, if the duration is negative).
Defines the semantics
of the +
operator when applied to an xs:date
and an
xs:yearMonthDuration
value.
This function is
The function returns the result of casting $arg1
to an
xs:dateTime
, adding $arg2
using the function
op:addyearMonthDurationtodateTime
, and casting the result back to an
xs:date
.
Expression:  

Result: 
Returns the xs:date
that is a given duration after a specified
xs:date
(or before, if the duration is negative).
Defines the semantics of
the +
operator when applied to an xs:date
and an
xs:dayTimeDuration
value.
This function is
The function returns the result of casting $arg1
to an
xs:dateTime
, adding $arg2
using the function
op:adddayTimeDurationtodateTime
, and casting the result back to an
xs:date
.
Expression:  

Result: 

Returns the xs:date
that is a given duration before a specified
xs:date
(or after, if the duration is negative).
Defines the semantics
of the 
operator when applied to an xs:date
and an
xs:yearMonthDuration
value.
This function is
Returns the xs:date
computed by negating $arg2
and adding the
result to $arg1
using the function
op:addyearMonthDurationtodate
.
Expression:  

Result:  
Expression:  
Result:  
Expression:  
Result: 
Returns the xs:date
that is a given duration before a specified
xs:date
(or after, if the duration is negative).
Defines the semantics of
the 
operator when applied to an xs:date
and an
xs:dayTimeDuration
.
This function is
Returns the xs:date
computed by negating $arg2
and adding the
result to $arg1
using the function
op:adddayTimeDurationtodate
.
Expression:  

Result: 
Returns the xs:time
value that is a given duration after a specified
xs:time
(or before, if the duration is negative or causes wraparound
past midnight)
Defines the semantics of
the +
operator when applied to an xs:time
and an
xs:dayTimeDuration
value.
First, the days component in the canonical lexical representation of $arg2
is set to zero (0) and the value of the resulting xs:dayTimeDuration
is
calculated. Alternatively, the value of $arg2
modulus 86,400 is used as the
second argument. This value is added to the value of $arg1
converted to an
xs:dateTime
using a reference date such as 19721231
, and
the time component of the result is returned. Note that the xs:time
returned may occur in a following or preceding day and may be less than
$arg1
.
The result has the same timezone as $arg1
. If $arg1
has no
timezone, the result has no timezone.
Expression:  

Result:  
Expression:  
Result: 

Returns the xs:time
value that is a given duration before a specified
xs:time
(or after, if the duration is negative or causes wraparound
past midnight)
Defines the semantics of
the 
operator when applied to an xs:time
and an
xs:dayTimeDuration
value.
This function is
The function returns the result of negating $arg2
and adding the result to
$arg1
using the function op:adddayTimeDurationtotime
.
Expression:  

Result:  
Expression:  
Result: 
Function  Meaning 

fn:formatdateTime  Returns a string containing an xs:dateTime value formatted for display. 
fn:formatdate  Returns a string containing an xs:date value formatted for display. 
fn:formattime  Returns a string containing an xs:time value formatted for display. 
Three functions are provided to represent dates and times as a string, using the conventions of a selected calendar,
language, and country. The functions are presented in their customary fashion,
except for the rules and examples, which are described en bloc at
Returns a string containing an xs:dateTime
value formatted for display.
The twoargument form of this function is
The fiveargument form of this function is
See
The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.
Returns a string containing an xs:date
value formatted for display.
The twoargument form of this function is
The fiveargument form of this function is
See
The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.
Returns a string containing an xs:time
value formatted for display.
The twoargument form of this function is
The fiveargument form of this function is
See
The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.
The fn:formatdateTime
, fn:formatdate
,
and fn:formattime
functions format $value
as a string using
the picture string specified by the $picture
argument,
the calendar specified by the $calendar
argument,
the language specified by the $language
argument,
and the country or other place name specified by the $place
argument.
The result of the function is the formatted string representation of the supplied
xs:dateTime
, xs:date
, or xs:time
value.
fn:formatdateTime
, fn:formatdate
,
and fn:formattime
are referred to collectively as the
If $value
is the empty sequence, the function returns the empty sequence.
Calling the twoargument form of each of the three functions is equivalent to calling the fiveargument form with each of the last three arguments set to an empty sequence.
For details of the $language
, $calendar
, and
$place
arguments, see
In general, the use of an invalid $picture
,
$language
, $calendar
, or
$place
argument results in a dynamic error
The picture consists of a sequence of variable markers and literal substrings.
A substring enclosed in square brackets is interpreted as a variable marker; substrings
not enclosed in square brackets are taken as literal substrings.
The literal substrings are optional and if present are rendered unchanged, including any whitespace.
If an opening or closing square bracket
is required within a literal substring, it
A variable marker consists of a component specifier followed optionally by one or two presentation modifiers and/or optionally by a width modifier. Whitespace within a variable marker is ignored.
The variable marker may be separated into its components by applying the following rules:
The component specifier is always present and is always a single letter.
The width modifier may be recognized by the presence of a comma.
The substring between the component specifier and the comma (if present) or the end of the string (if there is no comma) contains the first and second presentation modifiers, both of which are optional. If this substring contains a single character, this is interpreted as the first presentation modifier. If it contains more than one character, the last character is examined: if it is valid as a second presentation modifier then it is treated as such, and the preceding part of the substring constitutes the first presentation modifier. Otherwise, the second presentation modifier is presumed absent and the whole substring is interpreted as the first presentation modifier.
The
Specifier  Meaning  Default Presentation Modifier 

Y  year (absolute value)  1 
M  month in year  1 
D  day in month  1 
d  day in year  1 
F  day of week  n 
W  week in year  1 
w  week in month  1 
H  hour in day (24 hours)  1 
h  hour in halfday (12 hours)  1 
P  am/pm marker  n 
m  minute in hour  01 
s  second in minute  01 
f  fractional seconds  1 
Z  timezone  01:01 
z  timezone (Same as Z, but modified where appropriate to include a prefix
as a time offset using GMT, for example GMT+1 or GMT05:00. For this component there is a fixed
prefix of GMT , or a localized
variation thereof for the chosen language, and the remainder of the value is formatted as for specifier Z .)
 01:01 
C  calendar: the name or abbreviation of a calendar name  n 
E  era: the name of a baseline for the numbering of years, for example the reign of a monarch  n 
A dynamic error is reported
A dynamic error is reported $value
,
for example if the picture supplied to the fn:formattime
refers
to the year, month, or day component.
It is not an error to include a timezone component when the supplied value has no timezone. In these circumstances the timezone component will be ignored.
The first
any format token permitted as a primary format token in the second argument
of the fn:formatinteger
function, indicating
that the value of the component is to be output numerically using the specified number format (for example,
1
, 01
, i
, I
, w
, W
,
or Ww
) or
the format token n
, N
,
or Nn
, indicating that the value of the component is to be output by name,
in lowercase, uppercase, or titlecase respectively. Components that can be output by name
include (but are not limited to) months, days of the week, timezones, and eras.
If the processor cannot output these components by name for the chosen calendar and language
then it must use an
If a comma is to be used as a grouping separator within the format token, then there must be a width
specifier. More specifically: if a variable marker
contains one or more commas, then the last comma is treated as introducing the width modifier, and all others
are treated as grouping separators. So [Y9,999,*]
will output the year as 2,008
.
It is not possible to use a closing square bracket as a grouping separator within the format token.
If the implementation does not support the use of the requested format token, it
If the first presentation modifier is present, then it may optionally be followed by a second presentation modifier as follows:
Modifier  Meaning 

either a or t  indicates alphabetic or traditional numbering respectively,
the default being fn:formatinteger . 
either c or o  indicates cardinal or ordinal numbering respectively, for example
7 or seven for a cardinal number, or 7th ,
seventh , or 7º
for an ordinal number.
This has the same meaning as
in the second argument of fn:formatinteger .
The actual representation of the ordinal form of a number
may depend not only on the language, but also on the grammatical context (for example,
in some languages it must agree in gender). 
Although the formatting rules are expressed in terms of the rules
for format tokens in fn:formatinteger
, the formats actually used may be specialized
to the numbering of date components where appropriate. For example, in Italian, it is conventional to
use an ordinal number (primo
) for the first day of the month, and cardinal numbers
(due, tre, quattro ...
) for the remaining days. A processor may therefore use
this convention to number days of the month, ignoring the presence or absence of the ordinal
presentation modifier.
Whether or not a presentation modifier is included, a width modifier may be supplied. This indicates the number of characters to be included in the representation of the value.
The width modifier, if present, is introduced by a comma. It takes the form:
"," minwidth ("" maxwidth)?
where minwidth
is either an unsigned integer indicating the minimum number of characters to
be output, or *
indicating that there is no explicit minimum, and
maxwidth
is either an unsigned integer indicating the maximum number of characters to
be output, or *
indicating that there is no explicit maximum; if maxwidth
is omitted then *
is assumed.
A dynamic error (minwidth
is present and less than one, or if
maxwidth
is present and less than one or less than minwidth
.
A format token containing more than one digit, such as 001
or 9999
, sets the
minimum and maximum width to the number of digits appearing in the format token; if a width
modifier is also present, then the width modifier takes precedence.
The rules in this section apply to the majority of integervalued components: specifically M D d F W w H h m s
.
In the rules below, the term
If the first presentation modifier takes the form of a
If there is no width modifier, then the value is formatted according to
the rules of the formatinteger
function.
If there is a width modifier, then the first presentation modifier is adjusted as follows:
If the decimal digit pattern includes a grouping separator, the output is implementationdefined (but this is not an error).
Use of a width modifier together with grouping separators is inadvisable for this reason. It is never necessary to use a width modifier with a decimal digit pattern, since the same effect can be achieved by use of optional digit signs.
Otherwise, the number of mandatorydigitsign characters in the presentation modifier is increased if necessary. This is done first by replacing optionaldigitsigns with mandatorydigitsigns, starting from the right, and then prepending mandatorydigitsigns to the presentation modifier, until the number of mandatorydigitsigns is equal to the minimum width. Any mandatorydigitsigns that are added by this process must use the same decimal digit family as existing mandatorydigitsigns in the presentation modifier if there are any, or ASCII digits otherwise.
The maximum width, if specified, is ignored.
The output is then as defined using the formatinteger
function with this adjusted decimal digit pattern.
If the first presentation modifiers is one of N
, n
, or Nn
:
Let FN be the full name of the component, that is, the form of the name that would be used in the absence of any width modifier.
If FN is shorter than the minimum width, then it is padded by appending spaces to the end of the name.
If FN is longer than the maximum width, then it is abbreviated, either by choosing a conventional abbreviation that fits within the maximum width (for example, “Wednesday” might be abbreviated to “Weds”), or by removing characters from the end of FN until it fits within the maximum width.
For other presentation modifiers:
Any adjustment of the value to fit within the requested width range is implementationdefined.
The value should not be truncated if this results in output that will not be meaningful to users (for example, there is no sensible way to truncate Roman numerals).
If shorter than the minimum width, the value should be padded to the minimum width, either by appending spaces, or in some other way appropriate to the numbering scheme.
The rules for the year component (Y) are the same as those in
If the width modifier is present and defines a finite maximum width, then that maximum width.
Otherwise, if the first presentation modifier takes the form of a decimaldigitpattern, then:
Let W be the number of optionaldigitsigns and mandatorydigitsigns in that decimaldigitpattern.
If W is 2 or more, then W.
Otherwise, N is infinity (that is, the year is output in full).
The output for the fractional seconds component (f
) is equivalent to the result of the following algorithm:
If the first presentation modifier contains no Unicode digit, then the output is implementationdefined.
Otherwise, the value of the fractional seconds is output as follows:
If there is no width modifier and the first presentation modifier comprises in its
entirety a single mandatorydigitsign (for example the default 1
), then
the presentation modifier is extended on the right with as many optionaldigitsigns as
are needed to accommodate the actual fractional seconds precision encountered in the
value to be formatted.
If there is a width modifier, then the first presentation modifier is adjusted as follows:
If a minimum width is specified, and if this exceeds the number of mandatorydigitsign characters in the first presentation modifier, then the first presentation modifier is adjusted. This is done first by replacing optionaldigitsigns with mandatorydigitsigns, starting from the left, and then appending mandatorydigitsigns to the presentation modifier, until the number of mandatorydigitsigns is equal to the minimum width. Any mandatorydigitsigns that are added by this process must use the same decimal digit family as existing mandatorydigitsigns in the presentation modifier.
If a maximum width is specified, the first presentation modifier is extended on the right with as many optionaldigitsigns as are needed to ensure that the number of mandatorydigitsigns and optionaldigitsigns is at least equal to the maximum width.
The sequence of characters in the (adjusted) first presentation modifier is reversed (for example,
999'###
becomes ###'999
).
If the result is not a valid
The sequence of digits in the conventional decimal representation of the fractional seconds component
is reversed, with insignificant zeroes removed, and the result is treated as an integer. For example, if the
seconds value is 25.8235
, the reversed fractional seconds value is 5328
.
The reversed fractional seconds value is formatted using the reversed decimal digit pattern according to the
rules of the fn:formatinteger
function. Given the examples above, the result is 5'328
The resulting string is reversed. In our example, the result is 823'5
.
If the result contains more digits than the number of mandatorydigitsigns and optionaldigitsigns in the decimal digit pattern, then excess digits are removed from the right hand end (that is, the value is truncated towards zero rather than being rounded). Any grouping separator that immediately precedes a removed digit is also removed.
The reason for presenting the algorithm in this way is that it enables maximum reuse of the rules defined for
fn:formatinteger
. Since the fractional seconds value is not properly an integer, the rules do not
work if used directly: for example, the positions of grouping separators need to be counted from the left rather
than from the right. Implementations, as always, are free to use a different algorithm that yields the same result.
A format token consisting of a single digit,
such as 1
, does not constrain the number of digits in the output.
In the case of fractional seconds in particular, [f001]
requests three decimal digits,
[f01]
requests two digits, but [f1]
will retain all digits in the
supplied date/time value (the maximum number of digits is implementationdefined).
If exactly one digit is required, this can be achieved using the component specifier
[f1,11]
.
Special rules apply to the formatting of timezones. When the component specifiers Z
or z
are used, the rules in this section override any rules given elsewhere in the case of
discrepancies.
If the date/time value to be formatted does not include a timezone offset, then the timezone component
specifier is generally ignored (results in no output). The exception is where military timezones are used
(format ZZ
) in which case the string "J"
is output, indicating local time.
When the component specifier is z
, the output is the same as for component specifier
Z
, except that it is prefixed by the characters GMT
or some localized
equivalent. The prefix is omitted, however, in cases where the timezone is identified by name rather than by
a numeric offset from UTC.
If the first presentation modifier is numeric and comprises one or two digits
with no groupingseparator (for example 1
or 01
), then the timezone is formatted as a displacement from UTC in hours, preceded by a plus or minus
sign: for example 5
or +03
. If the actual timezone offset is not an integral number of hours,
then the minutes part of the offset is appended, separated by a colon: for example +10:30
or
1:15
.
If the first presentation modifier is numeric with a groupingseparator (for example 1:01
or 01.01
), then the timezone offset is output in hours and minutes, separated by the grouping separator,
even if the number of minutes is zero: for example +5:00
or +10.30
.
If the first presentation modifier is numeric and comprises three or four digits with no
groupingseparator, for example 001
or 0001
, then the timezone offset
is shown in hours and minutes with no separator, for example 0500
or +1030
.
If the first presentation modifier is numeric, in any of the above formats, and the second
presentation modifier is t
, then a zero timezone offset (that is, UTC) is output as Z
instead
of a signed numeric value. In this presentation modifier is absent or if the timezone offset is nonzero,
then the displayed timezone offset is preceded by a 
sign for negative offsets
or a +
sign for nonnegative offsets.
If the first presentation modifier is Z
, then the timezone is formatted
as a military timezone letter, using the convention Z = +00:00, A = +01:00, B = +02:00, ..., M = +12:00,
N = 01:00, O = 02:00, ... Y = 12:00. The letter J (meaning local time) is used in the case of a
value that does not specify a timezone offset. Timezone offsets that have no representation in this system
(for example Indian Standard Time, +05:30) are output as if the format 01:01
had been requested.
If the first presentation modifier is N
, then the timezone is output
(where possible) as a timezone name, for example EST
or CET
. The same timezone
offset has different names in different places; it is therefore $place
argument.
In the absence of this information, the implementation may apply a default, for example by using the timezone
names that are conventional in North America. If no timezone name can be identified, the timezone offset is
output using the fallback format 01:01
The following examples illustrate options for timezone formatting.
Variable marker  $place  Timezone offsets (with time = 12:00:00)  

10:00  05:00  +00:00  +05:30  +13:00  
[Z]  ()  10:00  05:00  +00:00  +05:30  +13:00 
[Z0]  ()  10  5  +0  +5:30  +13 
[Z0:00]  ()  10:00  5:00  +0:00  +5:30  +13:00 
[Z00:00]  ()  10:00  05:00  +00:00  +05:30  +13:00 
[Z0000]  ()  1000  0500  +0000  +0530  +1300 
[Z00:00t]  ()  10:00  05:00  Z  +05:30  +13:00 
[z]  ()  GMT‑10:00  GMT‑05:00  GMT+00:00  GMT+05:30  GMT+13:00 
[ZZ]  ()  W  R  Z  +05:30  +13:00 
[ZN]  "us"  HST  EST  GMT  IST  +13:00 
[H00]:[M00] [ZN]  "America/New_York"  06:00 EST  12:00 EST  07:00 EST  01:30 EST  18:00 EST 
If a width specifier is present when formatting a timezone, then the representation as defined in this section is padded to the minimum
width as described in
This section applies to the remaining components: P
(am/pm marker), C
(calendar),
and E
(era).
The output for these components is entirely n
, indicating that they are output as names (or
conventional abbreviations), and the chosen names will in many cases depend on the chosen language: see
The set of languages, calendars, and places that are supported in the
If the fallback representation uses a different calendar from that requested,
the output string [Calendar: X]
(where X is the calendar actually used),
localized as appropriate to the
requested language. If the fallback representation uses a different language
from that requested, the output string [Language: Y]
(where Y is the language
actually used) localized in an
implementationdependent way. If a particular component of the value cannot be output in
the requested format, it
The $language
argument specifies the language to be used for the result string
of the function. The value of the argument xml:lang
attribute (see
If the $language
argument is omitted or is set to an empty sequence, or if it is set to an invalid value or a
value that the implementation does not recognize,
then the processor uses the default language defined in the dynamic context.
The language is used to select the appropriate languagedependent forms of:
names (for example, of months)
numbers expressed as words or as ordinals (twenty, 20th, twentieth
)
hour convention (023 vs 124, 011 vs 112)
first day of week, first week of year
Where appropriate this choice may also take into account the value of the
$place
argument, though this language
argument.
The choice of the names and abbreviations used in any given language is
Jul
while another uses Jly
. In German,
one implementation might represent Saturday as Samstag
while another
uses Sonnabend
. Implementations
Where ordinal numbers are used, the selection of the correct representation of the
ordinal (for example, the grammatical gender)
The calendar
attribute specifies that the dateTime
, date
,
or time
supplied in the $value
argument
The calendar value if present EQName
(dynamic error: QName
then it is expanded into an expanded QName
using the statically known namespaces; if it has no prefix then it represents an expandedQName in no namespace.
If the expanded QName is in no namespace,
then it
If the $calendar
argument is omitted or is set to an empty sequence
then the default calendar defined in the dynamic context is used.
The calendars listed below were known to be in use during the last hundred years. Many other calendars have been used in the past.
This specification does not define any of these calendars, nor the way that they
map to the value space of the xs:date
datatype in $place
and/or $language
arguments, with the
$place
argument taking precedence.
Information about some of these calendars, and algorithms for converting between them, may
be found in
Designator  Calendar 

AD  Anno Domini (Christian Era) 
AH  Anno Hegirae (Islamic Era) 
AME  Mauludi Era (solar years since Muhammad’s birth) 
AM  Anno Mundi (Jewish Calendar) 
AP  Anno Persici 
AS  Aji Saka Era (Java) 
BE  Buddhist Era 
CB  Cooch Behar Era 
CE  Common Era 
CL  Chinese Lunar Era 
CS  Chula Sakarat Era 
EE  Ethiopian Era 
FE  Fasli Era 
ISO  ISO 8601 calendar 
JE  Japanese Calendar 
KE  Khalsa Era (Sikh calendar) 
KY  Kali Yuga 
ME  Malabar Era 
MS  Monarchic Solar Era 
NS  Nepal Samwat Era 
OS  Old Style (Julian Calendar) 
RS  Rattanakosin (Bangkok) Era 
SE  Saka Era 
SH  Solar Hijri (Islamic Era, used in Iran and Afghanistan) 
SS  Saka Samvat 
TE  Tripurabda Era 
VE  Vikrama Era 
VS  Vikrama Samvat Era 
At least one of the above calendars
The ISO 8601 calendar (ISO
,
is very similar to the Gregorian calendar designated AD
, but it
differs in several ways. The ISO calendar
is intended to ensure that date and time formats can be read
easily by other software, as well as being legible for human
users. The ISO calendar
prescribes the use of particular numbering conventions as defined in
ISO 8601, rather than allowing these to be localized on a perlanguage basis.
In particular it
provides a numeric “week date” format which identifies dates by
year, week of the year, and day in the week;
in the ISO calendar the days of the week are numbered from 1 (Monday) to 7 (Sunday), and
week 1 in any calendar year is the week (from Monday to Sunday) that includes the first Thursday
of that year. The numeric values of the components year, month, day, hour, minute, and second
are the same in the ISO calendar as the values used in the lexical representation of the date and
time as defined in E
component)
with this calendar is either a minus sign (for negative years) or a zerolength string (for positive years).
For dates before 1 January, AD 1, year numbers in
the ISO and AD calendars are off by one from each other: ISO year
0000 is 1 BC, 0001 is 2 BC, etc.
ISO 8601 does not define a numbering for weeks within a month. When the w
component is used, the convention to be adopted is that each MondaytoSunday week is considered to
fall within a particular month if its Thursday occurs in that month; the weeks that fall in a particular
month under this definition are numbered starting from 1. Thus, for example,
29 January 2013 falls in week 5 because the Thursday of the week (31 January 2013) is the fifth Thursday
in January, and 1 February 2013 is also in week 5 for the same reason.
The value space of the date and time datatypes, as defined in XML Schema, is based on
absolute points in time. The lexical space of these datatypes defines a
representation of these absolute points in time using the proleptic Gregorian calendar,
that is, the modern Western calendar extrapolated into the past and the future; but the value space
is calendarneutral. The
15020111
(the day on which Pope Gregory XIII was born) might be
formatted using the Old Style (Julian) calendar as 1 January 1502
. This reflects the fact
that there was at that time a tenday difference between the two calendars. It would be
incorrect, and would produce incorrect results, to represent this date in an element or attribute
of type xs:date
as 15020101
, even though this might reflect the way
the date was recorded in contemporary documents.
When referring to years occurring in antiquity, modern historians generally
use a numbering system in which there is no year zero (the year before 1 CE
is thus 1 BCE). This is the convention that xs:date
and xs:dateTime
does not include a year zero: however, XSD 1.1 endorses the ISO 8601 convention. This means that the date on
which Julius Caesar was assassinated has the ISO 8601 lexical representation
00430313, but will be formatted as 15 March 44 BCE in the Julian calendar
or 13 March 44 BCE in the Gregorian calendar (dependent on the chosen
localization of the names of months and eras).
The intended use of the $place
argument is to identify
the place where an event
represented by the dateTime
, date
,
or time
supplied in the $value
argument took place or will take place.
If the $place
argument is omitted or is set
to an empty sequence, then the default place defined in the dynamic context is used.
If the value is supplied, and is not the empty sequence, then it
Country codes are defined in "de"
for Germany
and "jp"
for Japan. Implementations
IANA timezone names are defined in the IANA timezone database "America/New_York"
and "Europe/Rome"
.
This argument is not intended to identify the location of the user
for whom the date or time is being formatted;
that should be done by means of the $language
attribute.
This information
The geographical area identified by a country code is defined by the boundaries as they existed at the time of the date to be formatted, or the presentday boundaries for dates in the future.
If the $place
argument is supplied in the form
of an IANA timezone name that is recognized by the implementation, then the date or
time being formatted is adjusted to the timezone offset applicable in that timezone.
For example, if the xs:dateTime
value 20100215T12:00:00Z
is formatted with the $place
argument set to
America/New_York
, then the output will be as if the value
20100215T07:00:0005:00
had been supplied. This adjustment takes daylight
savings time into account where possible; if the date in question falls during
daylight savings time in New York, then it is adjusted to timezone offset PT4H
rather than PT5H
. Adjustment using daylight savings time is only possible
where the value includes a date, and where the date is within the range covered
by the timezone database.
The following examples show a selection of dates and times and the way they might be formatted. These examples assume the use of the Gregorian calendar as the default calendar.
Required Output  Expression 

20021231

formatdate($d, "[Y0001][M01][D01]")

12312002

formatdate($d, "[M][D][Y]")

31122002

formatdate($d, "[D][M][Y]")

31 XII 2002

formatdate($d, "[D1] [MI] [Y]")

31st December, 2002

formatdate($d, "[D1o] [MNn], [Y]", "en", (), ())

31 DEC 2002

formatdate($d, "[D01] [MN,*3] [Y0001]", "en", (), ())

December 31, 2002

formatdate($d, "[MNn] [D], [Y]", "en", (), ())

31 Dezember, 2002

formatdate($d, "[D] [MNn], [Y]", "de", (), ())

Tisdag 31 December 2002

formatdate($d, "[FNn] [D] [MNn] [Y]", "sv", (), ())

[20021231]

formatdate($d, "[[[Y0001][M01][D01]]]")

Two Thousand and Three

formatdate($d, "[YWw]", "en", (), ())

einunddreißigste Dezember

formatdate($d, "[Dwo] [MNn]", "de", (), ())

3:58 PM

formattime($t, "[h]:[m01] [PN]", "en", (), ())

3:58:45 pm

formattime($t, "[h]:[m01]:[s01] [Pn]", "en", (), ())

3:58:45 PM PDT

formattime($t, "[h]:[m01]:[s01] [PN] [ZN,*3]", "en", (), ())

3:58:45 o'clock PM PDT

formattime($t, "[h]:[m01]:[s01] o'clock [PN] [ZN,*3]", "en", (), ())

15:58

formattime($t, "[H01]:[m01]")

15:58:45.762

formattime($t, "[H01]:[m01]:[s01].[f001]")

15:58:45 GMT+02:00

formattime($t, "[H01]:[m01]:[s01] [z,66]", "en", (), ())

15.58 Uhr GMT+2

formattime($t, "[H01]:[m01] Uhr [z]", "de", (), ())

3.58pm on Tuesday, 31st December

formatdateTime($dt, "[h].[m01][Pn] on [FNn], [D1o] [MNn]")

12/31/2002 at 15:58:45

formatdateTime($dt, "[M01]/[D01]/[Y0001] at [H01]:[m01]:[s01]")

The following examples use calendars other than the Gregorian calendar.
Description  Request  Result 

Islamic 
formatdate($d, "[D١] [Mn] [Y١]", "ar", "AH", ())
 ٢٦ ﺸﻭّﺍﻝ ١٤٢٣ 
Jewish (with Western numbering) 
formatdate($d, "[D] [Mn] [Y]", "he", "AM", ())
 26 טבת 5763 
Jewish (with traditional numbering) 
formatdate($d, "[Dאt] [Mn] [Yאt]", "he", "AM", ())
 כ״ו טבת תשס״ג 
Julian (Old Style) 
formatdate($d, "[D] [MNn] [Y]", "en", "OS", ())
 18 December 2002 
Thai 
formatdate($d, "[D๑] [Mn] [Y๑]", "th", "BE", ())
 ๓๑ ธันวาคม ๒๕๔๕ 
Function  Meaning 

fn:parseietfdate  Parses a string containing the date and time in IETF format, returning the corresponding
xs:dateTime value. 
A function is provided to parse dates and times expressed using syntax that is commonly encountered in internet protocols.
Parses a string containing the date and time in IETF format, returning the corresponding
xs:dateTime
value.
This function is
The function accepts a string matching the production input
in the
following grammar:
input

::=

S? (dayname ","? S)? ((datespec S time)  asctime) S?

dayname

::=

"Mon"  "Tue"  "Wed"  "Thu"  "Fri"  "Sat"  "Sun"  "Monday  "Tuesday"
 "Wednesday"  "Thursday"  "Friday"  "Saturday"  "Sunday"

datespec

::=

daynum dsep monthname dsep year

asctime

::=

monthname dsep daynum S time S year

dsep

::=

S  (S? "" S?)

daynum

::=

digit digit?

year

::=

digit digit (digit digit)?

digit

::=

[09]

monthname

::=

"Jan"  "Feb"  "Mar"  "Apr"  "May"  "Jun"  "Jul"  "Aug"  "Sep" 
"Oct"  "Nov"  "Dec"

time

::=

hours ":" minutes (":" seconds)? (S? timezone)?

hours

::=

digit digit? 
minutes

::=

digit digit

seconds

::=

digit digit ("." digit+)?

timezone

::=

tzname  tzoffset (S? "(" S? tzname S? ")")?

tzname

::=

"UT"  "UTC"  "GMT"  "EST"  "EDT"  "CST"  "CDT"  "MST"  "MDT"  "PST"
 "PDT"

tzoffset

::=

("+""") hours ":"? minutes? 
S

::=

(x09  x0A  x0D  x20)+

The input is caseinsensitive: uppercase and lowercase distinctions in the above grammar show the conventional usage, but otherwise have no significance.
If the input is an empty sequence, the result is an empty sequence.
The dayname
, if present, is ignored.
The daynum
, monthname
, and year
supply the day,
month, and year of the resulting xs:dateTime
value. A twodigit year
The hours
, minutes
, and seconds
(including
fractional seconds) values supply the corresponding components of the resulting
xs:dateTime
value; if the seconds
value
If both a tzoffset
and a tzname
are supplied then the
tzname
is ignored.
If a tzoffset
is supplied then this defines the hours and minutes parts of the timezone offset:
If it contains a colon, this separates the hours part from the minutes part.
Otherwise, the grammar allows a sequence of from one to four digits. These are interpreted
as H
, HH
, HMM
, or HHMM
respectively, where H
or HH
is the hours part, and MM
(if present) is the minutes part.
If the minutes part is absent it defaults to 00
.
If a tzname
is supplied with no tzoffset
then it is translated
to a timezone offset as follows:
tzname  Offset 

UT, UTC, GMT  00:00 
EST  05:00 
EDT  04:00 
CST  06:00 
CDT  05:00 
MST  07:00 
MDT  06:00 
PST  08:00 
PDT  07:00 
If neither a tzoffset
nor tzname
is supplied, a timezone
offset of 00:00
is assumed.
A dynamic error is raised "31 February"
).
The parseietfdate
function attempts to interpret its input as a date
in any of the three formats specified by HTTP
These formats are used widely on the Internet to represent timestamps, and were specified in:
POSIX asctime()
format
The grammar for this function is slightly more liberal than the RFCs (reflecting the internet tradition of being liberal in what is accepted). For example the function:
Accepts a singledigit value where appropriate in place of a twodigit value with a leading zero (so
"Wed 1 Jun"
is acceptable in place of "Wed 01 Jun"
,
"5:00"
is equivalent to "05:00"
)
Accepts one or more whitespace characters (x20, x09, x0A, x0D) wherever a single space is required, and allows whitespace to be omitted where it is not required for parsing
Accepts and ignores whitespace characters (x20, x09, x0A, x0D) at the start or end of the string.
In new protocols IETF recommends the format of
An fn:formatdateTime
with a picture
string of "[FNn3], [D01] [MNn3] [Y04] [H01]:[m01]:[s01] [Z0000]"
.
Expression  Result 

parseietfdate("Wed, 06 Jun 1994 07:29:35 GMT")  
parseietfdate("Wed, 6 Jun 94 07:29:35 GMT")  
parseietfdate("Wed Jun 06 11:54:45 EST 2013")  
parseietfdate("Sunday, 06Nov94 08:49:37 GMT")  
parseietfdate("Wed, 6 Jun 94 07:29:35 +0500") 
In addition to the xs:QName
constructor function, QName values can
be constructed by combining a namespace URI, prefix, and local name, or by resolving
a lexical QName against the inscope namespaces of an element node. This section
defines functions that perform these operations.
Leading and trailing whitespace, if present, is stripped from
string arguments before the result is constructed.
Function  Meaning 

fn:QName  Returns an xs:QName value formed using a supplied namespace URI and lexical QName. 
fn:parseQName  Returns an xs:QName value formed by parsing an EQName. 
fn:resolveQName  Returns an xs:QName value (that is, an expandedQName) by taking an
xs:string that has the lexical form of an xs:QName (a
string in the form "prefix:localname" or "localname" )
and resolving it using the inscope namespaces for a given element. 