The presentation of this document has been augmented to identify changes from the version 3.1 Recommendation published on 21 March 2017. Three kinds of changes are highlighted: new, added text, changed text, and deleted text.
Please check the errata for any errors or issues reported since publication.
See also translations.
This document is also available in these nonnormative formats: Specification in XML format using HTML5 vocabulary, XML function catalog, and HTML with change markings relative to version 3.0.
Copyright © 2000 W3C^{®} (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
This document defines constructor functions, operators, and functions on the datatypes defined in [XML Schema Part 2: Datatypes Second Edition] and the datatypes defined in [XQuery and XPath Data Model (XDM) 3.1]. It also defines functions and operators on nodes and node sequences as defined in the [XQuery and XPath Data Model (XDM) 3.1]. These functions and operators are defined for use in [XML Path Language (XPath) 4.0] and [XQuery 4.1: An XML Query Language] and [XSL Transformations (XSLT) Version 4.0] and other related XML standards. The signatures and summaries of functions defined in this document are available at: http://www.w3.org/2005/xpathfunctions/.
A summary of changes since version 3.1 is provided at G Changes since version 3.1.
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 History notes. Comments are invited, in the form of GitHub issues at https://github.com/qt4cg/qtspecs.
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 [XML Path Language (XPath) 4.0], [XQuery 4.1: An XML Query Language] and [XSL Transformations (XSLT) Version 4.0].
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 [XQuery and XPath Data Model (XDM) 3.1].
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 [XML Path Language (XPath) 4.0] and [XQuery 4.1: An XML Query Language]. These exist for specification purposes only, and are not intended for direct calling from userwritten code.
[XML Schema Part 2: Datatypes Second Edition] defines a number of primitive and derived datatypes, collectively known as builtin datatypes. This document defines functions and operations on these datatypes as well as the other types (for example, nodes and sequences of nodes) defined in Section 2.7 Schema Information ^{DM31} of the [XQuery and XPath Data Model (XDM) 3.1]. These functions and operations are available for use in [XML Path Language (XPath) 4.0], [XQuery 4.1: An XML Query Language] and any other host language that chooses to reference them. In particular, they may be referenced in future versions of XSLT and related XML standards.
[Schema 1.1 Part 2] adds to the datatypes defined
in [XML Schema Part 2: Datatypes Second Edition]. It introduces a new derived type 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 may support either XSD 1.0 or XSD 1.1 or both.
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 [XQuery 4.1: An XML Query Language], XT [XSL Transformations (XSLT) Version 4.0], XP [XML Path Language (XPath) 4.0], and DM [XQuery and XPath Data Model (XDM) 3.1].
Despite its title, this document does not attempt to define the semantics of all the operators available
in the [XML Path Language (XPath) 4.0] language; indeed, in the interests of avoiding duplication, the majority of
operators (including all higherorder operators such as 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 [XML Path Language (XPath) 4.0].
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 general comparison operators =
, !=
, <
,
>
, <=
, and >=
are defined by reference to
eq
, ne
, lt
,
gt
, le
, and ge
respectively.
Note:
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 ·execution scope·, the requirements of this recommendation regarding the ·determinism· of results are satisfied (see 1.8.4 Properties of functions).
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 ·execution scope·;
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.
Note:
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 ·implementationdefined· which version of Unicode is supported, but it is recommended that the most recent version of Unicode be used.
It is ·implementationdefined· whether the type system is based on XML Schema 1.0 or XML Schema 1.1.
It is ·implementationdefined· whether definitions that rely on XML (for example, the set of valid XML characters) should use the definitions in XML 1.0 or XML 1.1.
Note:
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 [XQuery and XPath Data Model (XDM) 3.1].
Furthermore, XSD 1.1
includes the option of supporting revised definitions of types such as xs:NCName
based on the rules in XML 1.1 rather than 1.0.
The [XQuery and XPath Data Model (XDM) 4.0] allows flexibility in the repertoire of characters permitted during processing that goes beyond even what version of XML is supported. A processor may allow the user to construct nodes and atomic values that contain characters not allowed by any version of XML. [Definition] A permitted character is one within the repertoire accepted by the implementation.
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 [Namespaces in XML]) and referenced using an
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 20 Constructor functions defines
constructor functions for the builtin datatypes defined
in [XML Schema Part 2: Datatypes Second Edition] and in Section
2.7 Schema Information
^{DM31}
of [XQuery and XPath Data Model (XDM) 3.1]. These datatypes and the corresponding constructor functions
are in the XML Schema namespace, 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
18.2 Functions that Operate on Maps). The namespace
prefix used in this document for these functions is 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
19.1 Functions that Operate on Arrays). The namespace
prefix used in this document for these functions is 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 [XSLT and XQuery Serialization 3.1]
Functions defined with the op
prefix are described here to
underpin the definitions of the operators in [XML Path Language (XPath) 4.0], [XQuery 4.1: An XML Query Language]
and [XSL Transformations (XSLT) Version 4.0]. These functions are not available
directly to users, and there is no requirement that implementations should
actually provide these functions. For this reason, no namespace is associated
with the op
prefix. For example, multiplication is generally
associated with the *
operator, but it is described as a function
in this document:
op:numericmultiply ( 

$arg1 
as , 

$arg2 
as


) as

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.
Note:
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 [XML Schema Part 2: Datatypes Second Edition]
and must adhere to its syntactic conventions. Following the precedent set by [XML Path Language (XPath) Version 1.0],
function names are generally composed of English words separated by hyphens (
). 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 [XML Schema Part 2: Datatypes Second Edition] datatype name, it may have
intercapitalized spelling and is used in the function name as such. An example is 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:
fn:functionname ( 

$parametername 
as , 

$... 
as


) as

In this notation, functionname, in boldface, is the
local name of the
function whose signature is being specified. The prefix fn
indicates that the function is in the namespace http://www.w3.org/2005/xpathfunctions
:
this is one of the conventional prefixes listed in 1.3 Namespaces and prefixes.
If the function takes no
parameters, then the name is followed by an empty parameter list:
()
; 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
, also in italics, specifies the static type of the value returned by the
function. The dynamic type of the value returned by the function is the same as its static
type or derived from the static type. All parameter types and return types are
specified using the SequenceType notation defined in Section
2.5.4 SequenceType Syntax
^{XP31}.
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 Section 2.3.4 Errors and Optimization ^{XP31} apply by default: to paraphrase, if the result of the function can be determined without evaluating all its arguments, then it is not necessary to evaluate the remaining arguments merely in order to determine whether any error conditions apply.
Where the proforma includes sections headed Notes or Examples, these are nonnormative.
Rules for passing parameters to operators are described in the relevant sections
of [XQuery 4.1: An XML Query Language] and [XML Path Language (XPath) 4.0]. For example, the rules for
passing parameters to arithmetic operators are described in Section
3.5 Arithmetic Expressions
^{XP31}. Specifically, rules for parameters of
type 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 subtype substitution (See Section
2.5.5 SequenceType Matching
^{XP31}). In addition, numeric type instances and
instances of type xs:anyURI
can be promoted to produce an argument
of the required type. (See Section
B.1 Type Promotion
^{XP31}).
Subtype Substitution: A derived type may substitute for
its base type. In particular, xs:integer
may be used
where xs:decimal
is expected.
Numeric Type Promotion: 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.
anyURI Type Promotion: A value of
type 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.
fn:functionname ( 

$parametername 
as


) as

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.
fn:median ( 

$arg 
as


) as

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:
xmltojson($input, { 'indent': true() })
[Definition] Functions that take an options parameter adopt common conventions on how the options are used. These are referred to as the option parameter conventions. These rules apply only to functions that explicitly refer to them.
Where a function adopts the ·option parameter conventions·, the following rules apply:
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.
Note:
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 may attach an
·implementationdefined· meaning to
options in the map that are not described in this specification. These options
should use values of type 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 [err:FORG0013] must be raised.
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 coercion rules^{XP40}. This will result in an error (typically [err:XPTY0004]^{XP} or [err:FORG0001]^{FO}) if conversion of the supplied value to the required type is not possible. A type error also occurs if this conversion delivers a coerced function whose invocation fails with a type error. A dynamic error occurs if the supplied value after conversion is not one of the permitted values for the option in question: the error codes for this error are defined in the specification of each function.
Note:
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.
item (abstract)
anyAtomicType (builtin atomic)
node (node)
attribute (node)
userdefined attribute types (userdefined)
document (node)
userdefined document types (userdefined)
element (node)
userdefined element types (userdefined)
text (node)
comment (node)
processinginstruction (node)
namespace (node)
function(*) (function item)
array(*) (function item)
map(*) (function item)
Legend:
Supertype
subtype
Abstract types (abstract)
Builtin atomic types (builtin atomic)
Node types (node)
Function item types (function item)
Userdefined types (userdefined)
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.
XML Schema types (abstract)
anyType (builtin complex)
Simple types (abstract)
anySimpleType (builtinlist)
Atomic types (abstract)
anyAtomicType (builtin atomic)
list types (abstract)
ENTITIES (builtin list)
IDREFS (builtin list)
NMTOKENS (builtin list)
userdefined list types (userdefined)
union types (abstract)
numeric (builtin complex)
userdefined union types (userdefined)
complex types (complex)
untyped (builtin complex)
userdefined complex types (userdefined)
Legend:
Supertype
subtype
Abstract types (abstract)
Builtin atomic types (builtin atomic)
Builtin complex types (builtin complex)
Builtin list types (builtin list)
Userdefined types (userdefined)
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 [XML Schema Part 2: Datatypes Second Edition].
Atomic types are both item types and schema types, so the root type xs:anyAtomicType
may be found
in both the previous diagrams.
anyAtomicType
anyURI
base64Binary
boolean
date
dateTime
dateTimeStamp
decimal
integer
long
int
short
byte
nonNegativeInteger
positiveInteger
unsignedLong
unsignedInt
unsignedShort
unsignedByte
nonPositiveInteger
negativeInteger
double
duration
dayTimeDuration
yearMonthDuration
float
gDay
gMonth
gMonthDay
gYear
gYearMonth
hexBinary
NOTATION
QName
string
normalizedString
token
NMTOKEN
Name
NCName
ENTITY
ID
IDREF
language
time
Legend:
Supertype
subtype
Builtin atomic types
The terminology used to describe the functions and operators on types defined in [XML Schema Part 2: Datatypes Second Edition] is defined in the body of this specification. The terms defined in this section are used in building those definitions.
Note:
Following in the tradition of [XML Schema Part 2: Datatypes Second Edition], the terms type and datatype are used interchangeably.
This document uses the terms string
, character
, and codepoint
with meanings that are normatively defined in [XQuery and XPath Data Model (XDM) 3.1], and which are paraphrased here
for ease of reference:
[Definition] A character is an instance of the Char^{XML} production of [Extensible Markup Language (XML) 1.0 (Fifth Edition)].
Note:
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.
[Definition] A string is a sequence of zero or more
·characters·, or equivalently,
a value in the value space of the xs:string
datatype.
[Definition] A codepoint is an integer assigned to a ·character· by the Unicode consortium, or reserved for future assignment to a character.
Note:
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 [Character Model for the World Wide Web 1.0: Fundamentals]
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 ·implementationdefined· which version of [The Unicode Standard] is supported, but it is recommended that the most recent version of Unicode be used.
Unless explicitly stated, the functions in this document do not ensure that any
returned xs:string
values are normalized in the sense of [Character Model for the World Wide Web 1.0: Fundamentals].
Note:
In functions that involve character counting such
as fn:substring
, fn:stringlength
and
fn:translate
, what is counted is the number of XML ·characters·
in the string (or equivalently, the number of Unicode codepoints). Some
implementations may represent a codepoint above xFFFF using two 16bit
values known as a surrogate pair. A surrogate pair counts as one character, not two.
This document uses the phrase “namespace URI” to identify the concept identified in [Namespaces in XML] as “namespace name”, and the phrase “local name” to identify the concept identified in [Namespaces in XML] as “local part”.
It also uses the term “expandedQName” defined below.
[Definition] An expandedQName
is a value in the value space of the xs:QName
datatype as defined in the XDM data model
(see [XQuery and XPath Data Model (XDM) 3.1]): that is, a triple containing namespace prefix (optional), namespace URI (optional),
and local name. Two expanded QNames are equal if the namespace URIs are the same (or both absent)
and the local names are the same. The prefix plays no part in the comparison, but is used only
if the expanded QName needs to be converted back to a string.
The term URI is used as follows:
[Definition] Within this specification, the term URI refers to Universal Resource Identifiers as
defined in [RFC 3986] and extended in [RFC 3987] with a new name IRI. The term URI
Reference, unless otherwise stated, refers to a string in the lexical space of the xs:anyURI
datatype
as defined in [XML Schema Part 2: Datatypes Second Edition].
Note:
This means, in practice, that where this
specification requires a “URI Reference”, an IRI as defined in [RFC 3987] will be
accepted, provided that other relevant specifications also permit an IRI. The term URI has been
retained in preference to IRI to avoid introducing new names for concepts such as “Base URI” that
are defined or referenced across the whole family of XML specifications. Note also that the
definition of xs:anyURI
is a wider definition than the definition in [RFC 3987];
for example it does not require nonASCII characters to be escaped.
In this specification:
The auxiliary verb must, when rendered in small capitals, indicates a precondition for conformance.
When the sentence relates to an implementation of a function (for example "All implementations must recognize URIs of the form ...") then an implementation is not conformant unless it behaves as stated.
When the sentence relates to the result of a function (for example "The result must have the same type as
$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
must
be a valid regular expression") then the implementation is not conformant unless it enforces the condition by raising a dynamic error
whenever the condition is not satisfied.
The auxiliary verb may, when rendered in small capitals, indicates optional or discretionary behavior. The statement “An implementation may do X” implies that it is implementationdependent whether or not it does X.
The auxiliary verb should, when rendered in small capitals, indicates desirable or recommended behavior. The statement “An implementation should do X” implies that it is desirable to do X, but implementations may choose to do otherwise if this is judged appropriate.
[Definition] Where behavior is described as implementationdefined, variations between processors are permitted, but a conformant implementation must document the choices it has made.
[Definition] Where behavior is described as implementationdependent, variations between processors are permitted, and conformant implementations are not required to document the choices they have made.
Note:
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 function, unless otherwise specified, applies equally to function definitions^{XP40} (which can be the target of a static function call) and function items^{DM40} (which can be the target of a dynamic function call).
[Definition] An execution scope is a sequence of
calls to the function library during which certain aspects of the state are required to remain invariant.
For example, two calls to 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.
In XSLT, for example, any two function calls executed during
the same transformation are in the same execution scope (except that static expressions, such as those used in
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:
[Definition] Two values $V1
and $V2
are
defined to be identical if they contain the same number of items and the items are pairwise identical. Two items are identical
if and only if one of the following conditions applies:
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 E_{1} in the first map there is an entry E_{2} in the second map such that the keys of E_{1} and E_{2} are ·the same key·, and the corresponding values V_{1} and V_{2} are ·identical·.
Both items are arrays, both arrays have the same number of members, and the members are pairwise ·identical·.
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 Section 2.9.4 Function Items^{DM40}.
Some functions produce results that depend not only on their explicit arguments, but also on the static and dynamic context.
[Definition] A
function definition^{XP40}
may have the property of being contextdependent: the result of such a
function depends on the values of properties in the static and dynamic
evaluation context of the caller
as well as on the actual supplied arguments (if any). A function definition may
be contextdependent for some arities in its arity range, and contextindependent
for others: for example fn:name#0
is contextdependent
while fn:name#1
is contextindependent.
[Definition] A function definition^{XP40} that is not ·contextdependent· is called 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.
[Definition] A function is focusdependent if its result depends on the focus^{XP31} (that is, the context item, position, or size) of the caller.
[Definition] A function that is not ·focusdependent· is called focusindependent.
Notes:
Note:
Some functions depend on aspects of the dynamic context that remain invariant within an ·execution scope·, such as the implicit timezone. Formally this is treated in the same way as any other context dependency, but internally, the implementation may be able to take advantage of the fact that the value is invariant.
Note:
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.
Note:
Because the focus is a specific part of the dynamic context, all ·focusdependent· functions are also ·contextdependent·. A ·contextdependent· function, however, may be either ·focusdependent· or ·focusindependent·.
A function definition that is contextdependent
can be used as the target of a named
function reference, can be partially applied, and can be found using 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
. These constructs all deliver a
function item^{DM40}
having a captured context based on the static and dynamic
context of the construct that created the function item. This captured context forms
part of the closure of the function item.
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 ·execution scope·. The same applies to a
number of functions in 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 ·execution scope·.
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 focus^{XP31}.
These functions will in general return
different results on different calls if the focus is different.
A function is focusdependent if its result depends on the focus^{XP31} (that is, the context value, position, or size).
A function that is not ·focusdependent· is called focusindependent
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
form the captured context of the
function item that fn:functionlookup
returns.
[Definition] For a ·contextdependent· function, the parts of the context on which it depends are referred to as implicit arguments.
[Definition] A function that is guaranteed to produce ·identical· results from repeated calls within a single ·execution scope· if the explicit and ·implicit· arguments are identical is referred to as deterministic.
[Definition] A function that is not ·deterministic· is referred to as nondeterministic.
All functions defined in this specification are ·deterministic· unless otherwise stated. Exceptions include the following:
[Definition] Some
functions (such as fn:distinctvalues
, fn:unordered
, map:keys
,
and map:foreach
) produce results in an
·implementationdefined· or
·implementationdependent· order.
In such cases two calls with the same arguments are not guaranteed to produce the results in the same order. These functions are
said to be nondeterministic with respect to ordering.
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 nondeterministic with respect to node identity.
Some functions (such as fn:doc
and fn:collection
) create new nodes by reading external
documents. Such functions are guaranteed to be ·deterministic· with the exception that
an implementation is allowed to make them nondeterministic as a user option.
Where the results of a function are described as being (to a greater or lesser extent) ·implementationdefined· or ·implementationdependent·, this does not by itself remove the requirement that the results should be deterministic: that is, that repeated calls with the same explicit and implicit arguments must return identical results.
Accessors and their semantics are described in [XQuery and XPath Data Model (XDM) 3.1]. Some of these accessors are exposed to the user through the functions described below.
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
.
fn:nodename ( 

$node 
as

:= . 
) as

The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
If the argument is omitted, it defaults to the context value (.
). The
behavior of the function if the argument is omitted is exactly the same as if the
context value had been passed as the argument.
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 [XQuery and XPath Data Model (XDM) 3.1] (see Section 4.10 nodename Accessor^{DM40}).
The following errors may be raised when $node
is omitted:
If the context value is absent^{DM40}, type error [err:XPDY0002]^{XP}.
If the context value is not a single node, type error [err:XPTY0004]^{XP}.
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 absent^{DM40}.
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 absent^{DM40} and the local
part is the namespace prefix being bound.
For all other kinds of node, the function returns the empty sequence.
Variables  

let $e := <doc> <p id="alpha" xml:id="beta">One</p> <p id="gamma" xmlns="http://example.com/ns">Two</p> <ex:p id="delta" xmlns:ex="http://example.com/ns">Three</ex:p> <?pi 3.14159?> </doc> 
Expression  Result 


QName("", "p") 

QName("http://example.com/ns", "p") 

QName("http://example.com/ns", "ex:p") 

QName("", "pi") 

() 

QName("", "id") 

xs:QName("xml:id") 
Returns true
for an element that is nilled.
fn:nilled ( 

$node 
as

:= . 
) as

The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
If the argument is omitted, it defaults to the context value (.
). The
behavior of the function if the argument is omitted is exactly the same as if the
context value had been passed as the argument.
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 [XQuery and XPath Data Model (XDM) 3.1] (see Section 4.8 nilled Accessor^{DM40}).
The following errors may be raised when $node
is omitted:
If the context value is absent^{DM40}, type error [err:XPDY0002]^{XP}
If the context value is not a single node, type error [err:XPTY0004]^{XP}.
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 [XQuery and XPath Data Model (XDM) 3.1].
Returns the value of $value
represented as an xs:string
.
fn:string ( 

$value 
as

:= . 
) as

The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 [XQuery and XPath Data Model (XDM) 3.1] (see Section 4.12 stringvalue Accessor^{DM40}).
If $value
is an atomic value, the function returns the result of the expression $value cast
as xs:string
(see 21 Casting).
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 absent^{DM40}, type error [err:XPDY0002]^{XP}.
If the context value is not a single item, type error [err:XPTY0004]^{XP}.
A type error is raised [err:FOTY0014] if
$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  

let $para := <para>There lived a <term author="Tolkien">hobbit</term>.</para> 
Expression  Result 


"23" 

"false" 

"Paris" 

Raises error XPTY0004. 

Raises error FOTY0014. 

Raises error FOTY0014. 

"There lived a hobbit." 
Returns the result of atomizing a sequence. This process flattens arrays, and replaces nodes by their typed values.
fn:data ( 

$input 
as

:= . 
) as

The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
If the argument is omitted, it defaults to the context value (.
). The
behavior of the function if the argument is omitted is exactly the same as if the
context value had been passed as the argument.
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
[XQuery and XPath Data Model (XDM) 3.1] (See Section 4.14 typedvalue Accessor^{DM40}).
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 [err:FOTY0012] if an item in the
sequence $input
is a node that does not have a typed value.
A type error is raised [err:FOTY0013] if an item in
the sequence $input
is a function item other than
an array.
A type error is raised [err:XPDY0002]^{XP}
if $input
is omitted and the context value is
absent^{DM40}.
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  

let $para := <para>There lived a <term author="Tolkien">hobbit</term>.</para> 
Expression  Result 


123 

123, 456 

1, 2, 3, 4 

xs:untypedAtomic("There lived a hobbit.") 

xs:untypedAtomic("Tolkien") 

Raises error FOTY0013. 
Returns the base URI of a node.
fn:baseuri ( 

$node 
as

:= . 
) as

The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 Section 4.2 baseuri Accessor^{DM40}).
Note:
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 absent^{DM40}, type error [err:XPDY0002]^{XP}
If the context value is not a single node, type error [err:XPTY0004]^{XP}.
Returns the URI of a resource where a document can be found, if available.
fn:documenturi ( 

$node 
as

:= . 
) as

The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
If the argument is omitted, it defaults to the context value (.
). The
behavior of the function if the argument is omitted is exactly the same as if the
context value had been passed as the argument.
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 [XQuery and XPath Data Model (XDM) 3.1] (See
Section 5.1.2 Accessors^{DM40}).
The following errors may be raised when $node
is omitted:
If the context value is absent^{DM40}, type error [err:XPDY0002]^{XP}
If the context value is not a single node, type error [err:XPTY0004]^{XP}.
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 recommended that implementations of 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 [XQuery 4.1: An XML Query Language] and [XML Path Language (XPath) 4.0],
the phrase “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
“[error code ]” 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 Section
2.3.3 Handling Dynamic Errors
^{XP31}.
The fn:error
function is a general function that may be called as above
but may also be called from [XQuery 4.1: An XML Query Language] or [XML Path Language (XPath) 4.0]
applications with, for example, an xs:QName
argument.
Calling the fn:error
function raises an applicationdefined error.
fn:error ( 

$code 
as

:= () , 
$description 
as

:= () , 
$value 
as

:= . 
) as

This function is ·nondeterministic·, ·contextindependent·, and ·focusindependent·.
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 ·implementationdependent·.
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, or if the value supplied
is an empty sequence,
the effective value of the error code is 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, or if the value supplied
is an empty sequence, then the
effective value of the description is ·implementationdependent·.
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 or if the value supplied
is an empty sequence, then the
effective value of the error object is ·implementationdependent·.
This function always raises a dynamic error. By default, it raises [err:FOER0000]
The value of the $description
parameter may need to be localized.
The type “none” is a special type defined in [XQuery 1.0 and XPath 2.0 Formal Semantics] and is not available to the user. It indicates that the function never returns and ensures that it has the correct static type.
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. (This returns the URI

Expression: 
error( QName('http://www.example.com/HR', 'myerr:toohighsal'), 'Salary is too high' ) 
Result: 
Raises error myerr:toohighsal. (This returns 
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.
fn:trace ( 

$input 
as , 

$label 
as

:= () 
) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The function returns $input
, unchanged.
In addition, the values of $input
, typically serialized and converted
to an xs:string
, and $label
(if supplied
and nonempty) may
be output to an ·implementationdefined· destination.
Any serialization of the implementation's trace output must not raise an error. This can be achieved (for example) by using a serialization method that can handle arbitrary input, such as the adaptive output method (see Section 10 Adaptive Output Method ^{SER31}).
The format of the trace output and its order are ·implementationdependent·. Therefore, the order in which the output appears is not predictable. This also means that if dynamic errors occur (whether or not they are caught using try/catch), it may be unpredictable whether any output is reported before the error occurs.
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.
fn:message ( 

$input 
as , 

$label 
as

:= () 
) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
Similar to fn:trace
, the values of $input
,
typically serialized and converted to an xs:string
, and $label
(if supplied and nonempty) may be output to an
·implementationdefined· destination.
In contrast to fn:trace
, the function returns an empty sequence.
Any serialization of the implementation’s log output must not raise an error. This can e.g. be achieved by using a serialization method that can handle arbitrary input, such as the Section 10 Adaptive Output Method ^{SER31}.
The format of the log output and its order are ·implementationdependent·. Therefore, the order in which the output appears is not predictable. This also means that if dynamic errors occur (whether or not they are caught using try/catch), it may be unpredictable whether any output is logged before the error occurs.
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.
fn:stacktrace () as xs:string 
This function is ·nondeterministic·, ·contextindependent·, and ·focusindependent·.
The result of the function is an ·implementationdependent· string containing diagnostic information about the current state of execution.
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 [XML Schema Part 2: Datatypes Second Edition].
The operators described in this section are defined on the following atomic types.
decimal
integer
double
float
Legend:
Supertype
subtype
Builtin 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 21.3.5 Casting to union types.
Because the lexical space of 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.
Note:
This specification uses [IEEE 7542008] arithmetic for 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 [XML Schema Part 2: Datatypes Second Edition], which defines
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 [IEEE 7542008]. A conformant implementation must
respect these semantics. In consequence, the expression 0.0e0
(which is actually a unary minus operator
applied to an xs:double
value) will always return negative zero: see 4.2.8 op:numericunaryminus.
As a concession to implementations that rely on implementations of XSD 1.0, however, when casting from string to double
the lexical form 0
may be converted to positive zero, though negative zero
is recommended.
XML Schema 1.1 introduces support for positive and negative zero as distinct values, and also uses the [IEEE 7542008]
semantics for comparisons involving NaN
.
The following functions define the semantics of arithmetic operators defined in [XQuery 4.1: An XML Query Language] and [XML Path Language (XPath) 4.0] on these numeric types.
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, subtype substitution and numeric type promotion are used to obtain two operands of the same type. Section B.1 Type Promotion ^{XP31} and Section B.2 Operator Mapping ^{XP31} describe the semantics of these operations in detail.
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:
op:operation(xs:int, xs:double) => op:operation(xs:double, xs:double)
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.
op:operation(fenceHeight, xs:integer) => op:operation(xs:integer, xs:integer)
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 [IEEE 7542008]. The rules for handling
division and modulus operations, as well as the rules for handling special values such as infinity and 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 must behave as follows:
For xs:float
and xs:double
operations, overflow
behavior must be conformant with [IEEE 7542008]. This specification allows the following options:
Raising a dynamic error [err:FOAR0002] via an overflow trap.
Returning INF
or INF
.
Returning the largest (positive or negative) noninfinite number.
For xs:float
and xs:double
operations,
underflow behavior must be conformant with [IEEE 7542008]. This specification allows the following options:
Raising a dynamic error [err:FOAR0002] via an underflow trap.
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 must
raise a dynamic error [err:FOAR0002]. On
underflow, 0.0
must be returned.
For xs:integer
operations, implementations that support
limitedprecision integer operations must select from
the following options:
They may choose to always raise a dynamic error [err:FOAR0002].
They may provide an ·implementationdefined· mechanism that allows users to choose between raising an error and returning a result that is modulo the largest representable integer value. See [ISO 10967].
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 should be accurate to N digits of precision, and for division and modulus operations,
the returned result should be accurate to at least M digits of precision.
The actual precision is ·implementationdefined·. If the number
of digits in the mathematical result exceeds the number of digits that the implementation
retains for that operation, the result is truncated or rounded in an ·implementationdefined· manner.
Note:
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 [IEEE 7542008] specification also describes handling of
two exception conditions called 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 may be notified to the application
or to the user by some ·implementationdefined·
warning condition, but the observable effect on an application
using the functions and operators defined in this specification is simply to return
the defined result (typically INF
, +INF
, or NaN
) with no error.
The [IEEE 7542008] specification distinguishes two 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 ·implementationdefined·
warning conditions, but such distinctions do not affect the observable behavior of an application
using the functions and operators defined in this specification.
Returns the arithmetic sum of its operands: ($arg1 + $arg2
).
Defines the semantics of the +
operator when
applied to two numeric values
op:numericadd ( 

$arg1 
as , 

$arg2 
as


) as

General rules: see 4.2 Arithmetic operators on numeric values.
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.
op:numericsubtract ( 

$arg1 
as , 

$arg2 
as


) as

General rules: see 4.2 Arithmetic operators on numeric values.
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.
op:numericmultiply ( 

$arg1 
as , 

$arg2 
as


) as

General rules: see 4.2 Arithmetic operators on numeric values.
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.
op:numericdivide ( 

$arg1 
as , 

$arg2 
as


) as

General rules: see 4.2 Arithmetic operators on numeric values.
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 [err:FOAR0001] for 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 [IEEE 7542008]. A positive number divided by
positive zero returns 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.
op:numericintegerdivide ( 

$arg1 
as , 

$arg2 
as


) as

General rules: see 4.2 Arithmetic operators on numeric values.
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
:
abs($N * $arg2) le abs($arg1) and compare($N * $arg2, 0) eq compare($arg1, 0).
Note:
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 ·implementationdependent· or ·implementationdefined· behavior does not affect the outcome, for example,
the implementationdefined precision of the result of xs:decimal
division.
A dynamic error is raised [err:FOAR0001] if the divisor is (positive or negative) zero.
A dynamic error is raised [err:FOAR0002] if either operand is
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 


3 

1 

1 

1 

3 

1 

0 

5 

4 
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.
op:numericmod ( 

$arg1 
as , 

$arg2 
as


) as

General rules: see 4.2 Arithmetic operators on numeric values.
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 [IEEE 7542008] rounding division i.e. additional digits are truncated,
not rounded to the required precision.
A dynamic error is raised [err:FOAR0001] for xs:integer
and xs:decimal
operands, if $arg2
is zero.
Expression  Result 


1 

0 

0.9 

3.0E0 
Returns its operand with the sign unchanged: (+ $arg
).
Defines the semantics of the unary +
operator
applied to a numeric value.
op:numericunaryplus ( 

$arg 
as


) as

General rules: see 4.2 Arithmetic operators on numeric values.
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.
op:numericunaryminus ( 

$arg 
as


) as

General rules: see 4.2 Arithmetic operators on numeric values.
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 4.2 Arithmetic operators on numeric values. Each comparison operator returns a
boolean value. If either, or both, operands are NaN
,
false
is returned.
Note:
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 Section H Atomic Comparisons: An Overview (NonNormative)^{XP40}.
Note:
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
.
op:numericequal ( 

$arg1 
as , 

$arg2 
as


) as

General rules: see 4.2 Arithmetic operators on numeric values and 4.3 Comparison operators on numeric values.
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
.
op:numericlessthan ( 

$arg1 
as , 

$arg2 
as


) as

General rules: see 4.2 Arithmetic operators on numeric values and 4.3 Comparison operators on numeric values.
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 . 
Note:
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
.
fn:abs ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
General rules: see 4.4 Functions on numeric values.
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 may
also be an instance of a type derived from one of these four by restriction. For example, if
$value
is an instance of xs:positiveInteger
then the value of
$value
may be returned unchanged.
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 


10.5 

10.5 

xs:double('INF') 
Rounds $value
upwards to a whole number.
fn:ceiling ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
General rules: see 4.4 Functions on numeric values.
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 may
also be an instance of a type derived from one of these four by restriction. For example, if
$value
is an instance of xs:decimal
then the result may
be an instance of 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 


11 

10 

xs:double('INF') 
Rounds $value
downwards to a whole number.
fn:floor ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
General rules: see 4.4 Functions on numeric values.
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 may
also be an instance of a type derived from one of these four by restriction. For example, if
$value
is an instance of xs:decimal
then the result may
be an instance of 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 


10 

11 

xs:double('INF') 
Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near.
fn:round ( 

$value 
as , 

$precision 
as

:= 0 
) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
General rules: see 4.4 Functions on numeric values.
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 may
also be an instance of a type derived from one of these four by restriction. For example, if
$value
is an instance of xs:decimal
and $precision
is
less than one, then the result may
be an instance of 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 


3.0 

2.0 

2.0 (Not the possible alternative, 

1.13 

8500 

3.14e0 

xs:double('INF') 
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:roundhalftoeven ( 

$value 
as , 

$precision 
as

:= 0 
) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
General rules: see 4.4 Functions on numeric values.
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 may
also be an instance of a type derived from one of these four by restriction. For example, if
$value
is an instance of xs:decimal
and $precision
is less than one, then the result may
be an instance of 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 


0.0 

2.0 

2.0 

3567.81e0 

0.0e0 

35600 

xs:double('INF') 
Returns true
if the argument is the xs:float
or xs:double
value NaN
.
fn:isNaN ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The function returns true
if the argument is the xs:float
or xs:double
value NaN
;
otherwise it returns false
.
Expression  Result 


false() 

false() 

true() 

true() 
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 20 Constructor functions
or using cast
expressions as described in 21 Casting.
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
.
fn:number ( 

$value 
as

:= . 
) as

The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 21.1.2.2 Casting to xs:double. If the conversion to xs:double
fails, the xs:double
value NaN
is returned.
A type error is raised [err:XPDY0002]^{XP}
if $value
is omitted and the context value is absent^{DM40}.
As a consequence of the rules given above, a type error is raised [err:XPTY0004]^{XP} if the context value cannot be atomized, or if the result of atomizing the context value is a sequence containing more than one atomic value.
XSD 1.1 allows the string +INF
as a representation of positive infinity;
XSD 1.0 does not. It is ·implementationdefined· whether XSD 1.1 is
supported.
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  

let $e := <e price="12.1" discount="NONE"/> 
Expression  Result 


1.2e1 

1.2e1 

xs:double('INF') 

xs:double('NaN') 

xs:double('NaN') 

1.21e1 

xs:double('NaN') 

xs:double('NaN') 

1.0e1, 1.1e1, 1.2e1 
Converts a string to an integer, recognizing any radix in the range 2 to 36.
fn:parseinteger ( 

$value 
as , 

$radix 
as

:= 10 
) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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:
let $alphabet := characters("0123456789abcdefghijklmnopqrstuvwxyz") let $preprocessedvalue := translate($value, "_ 	
", "") let $digits := translate($preprocessedvalue, "+", "") let $abs := sum( for $char at $p in reverse(characters($digits)) return (indexof($alphabet, $char)  1) * xs:integer(math:pow($radix, $p  1))) return if (startswith($preprocessedvalue, "")) then $abs else +$abs
A dynamic error is raised [err:FORG0011]
if $radix
is not in the range 2 to 36.
A dynamic error is raised [err:FORG0012]
if, after stripping whitespace and underscores and the optional leading sign,
$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 [err:FOCA0003]
if the value of the resulting integer exceeds the implementationdependent
limit on the size of an 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: 
200 
Expression: 

Result: 
20 
Expression: 

Result: 
100 
Expression: 

Result: 
255 
Expression: 

Result: 
4294967295 
Expression: 

Result: 
4294967295 
Expression: 

Result: 
255 
Expression: 

Result: 
5 
Expression: 

Result: 
1023 
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: 
lowercase("AAB") => translate("abcdefghijklmnopqrstuvwxyz", "0123456789abcdefghijklmnop") => parseinteger(26) 
Result: 
1 
Digitbased numeration systems comparable to the Arabic numbers 0 through 9 can be parsed via translation. 

Expression: 
translate(value := '٢٠٢٣', replace := '٠١٢٣٤٥٦٧٨٩', with := '0123456789') => parseinteger() 
Result: 
2023 
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.
fn:formatinteger ( 

$value 
as , 

$picture 
as , 

$language 
as

:= () 
) as

The twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on default language.
The threeargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 must not be zerolength.
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 #
.
If the radix is absent, then
a mandatorydigitsign is a ·character· in Unicode category Nd. All
mandatorydigitsigns within the format token
must be from the same digit family, where a digit
family is a sequence of ten consecutive characters in Unicode category Nd,
having digit values 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 must match the
regular expression ^((\p{Nd}#[^\p{N}\p{L}])+?)$
. If it contains a
digit but does not match this pattern, a dynamic error is raised [err:FODF1310].
If the radix (call it R) is
present (including the case where an explicit radix of 10 is used), then
the character used as the mandatorydigitsign is either "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 must match the
regular expression ^(([Xx#][^\p{N}\p{L}])+?)$
a groupingseparatorsign is a nonalphanumeric character, that is a ·character· whose Unicode category is other than Nd, Nl, No, Lu, Ll, Lt, Lm or Lo.
Note:
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 must be at least one mandatorydigitsign. There may be zero or more optionaldigitsigns, and (if present) these must precede all mandatorydigitsigns. There may be zero or more groupingseparatorsigns. A groupingseparatorsign must not appear at the start or end of the digitpattern, nor adjacent to another groupingseparatorsign.
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 position of a grouping separator is the number of optionaldigitsigns and mandatorydigitsigns appearing between the grouping separator and the righthand end of the primary format token.
Grouping separators are defined to be regular if the following conditions apply:
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 grouping separator template is a (possibly infinite) set of (position, character) pairs.
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.
Note:
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
in the appropriate radix:
for radix 10 this will be the value obtained by casting
it to 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. (This has no effect when the selected digit family uses ASCII digits (09), which will always be the case if a radix is specified.)
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 ·implementationdefined· which
numbering sequences, additional to those listed above, are supported. If an
implementation does not support a numbering sequence represented by the given
token, it must use a format token of 1
.
Note:
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 dexia keraia (x0374, ʹ) and sometimes the aristeri keraia (x0375, ͵). These should not be included in the format token.
For all format tokens other than a digitpattern, there
may be ·implementationdefined· lower and upper bounds on the range of numbers that
can be formatted using this format token; indeed, for some numbering sequences there may
be intrinsic limits. For example, the format token ①
(circled
digit one, ①) has a range imposed by the Unicode character repertoire — zero to 20
in Unicode versions prior to 3.2, or zero to 50 in subsequent versions. For the numbering
sequences described above any upper bound imposed by the implementation must
not be less than 1000 (one thousand) and any lower bound must not be
greater than 1. Numbers that fall outside this range must be
formatted using the format token 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
should be either an empty sequence or a value that would be valid
for the xml:lang
attribute (see [Extensible Markup Language (XML) 1.0 (Fifth Edition)]). Note that this
permits the identification of sublanguages based on country codes (from ISO 31661) as
well as identification of dialects and regions within a country.
The set of languages for which numbering is supported is ·implementationdefined·. If the $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 must be a string that matches the regular
expression ^([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 ·implementationdefined·.
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 ·implementationdefined·. No error occurs if the implementation does not define any interpretation for the defined string.
It is ·implementationdefined· what combinations of values of the format token, the language, and the cardinal/ordinal modifier are supported. If ordinal numbering is not supported for the combination of the format token, the language, and the string appearing in parentheses, the request is ignored and cardinal numbers are generated instead.
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 ·implementationdefined·.
A dynamic error is raised [err:FODF1310] if the format token is invalid, that is, if it violates any mandatory rules (indicated by an emphasized must or required keyword in the above rules). For example, the error is raised if the primary format token contains a digit but does not match the required regular expression.
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 not designed for effects such as
formatting a US telephone number as (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 [ICU], or any other library making use of the
Unicode Common Locale Data Repository [Unicode CLDR], is to allow the value in parentheses
to be the name of a registered numbering rule set for the language in question,
conventionally prefixed with a percent sign: for example,
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: 
"0123" 


Ordinal numbering in Italian: The specification 

1º 2º 3º 4º ... 

The specification 

Primo Secondo Terzo Quarto Quinto ... 

Expression: 

Result: 
"21st" 


Expression: 

Result: 
"g" 
Expression: 

Result: 
"aa" 
Expression: 

Result: 
"LVII" 
Expression: 

Result: 
"1;234" 
Expression: 

Result: 
"04d2" 
Expression: 

Result: 
"4D2" 
Expression: 

Result: 
"00bc_614e" 
Expression: 

Result: 
"bc_614e" 
Expression: 

Result: 
"1111 1111" 
Expression: 

Result: 
"00VV" 
Expression: 

Result: 
"1023" 
Expression: 

Result: 
"10^23" 
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. 
Note:
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 ·implementationdefined·.
Each decimal format provides a set of named properties.
Note:
A phrase such as "The minussign^{XP31} character" is to be read as “the character assigned to the minussign^{XP31} property in the relevant decimal format”.
[Definition] The decimal digit family of a decimal format is the sequence of ten digits with consecutive Unicode ·codepoints· starting with the character that is the value of the zerodigit^{XP31} property.
[Definition] The optional digit character is the character that is the value of the digit^{XP31} property.
For any decimal format, the properties representing characters used in a ·picture string· must have distinct values. These properties are decimalseparator^{XP31} , groupingseparator^{XP31}, exponentseparator^{XP31}, percent^{XP31}, permille^{XP31}, digit^{XP31}, and patternseparator^{XP31}. Furthermore, none of these properties may be equal to any ·character· in the ·decimal digit family·.
Returns a string containing a number formatted according to a given picture string and decimal format.
fn:formatnumber ( 

$value 
as , 

$picture 
as , 

$options 
as

:= () 
) as

The twoargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The threeargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on decimal formats, and namespaces.
The function formats $value
as a string using the ·picture string· specified by 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
must be a string which after removal of leading
and trailing whitespace is in the form of an 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 ·option parameter conventions· apply. The detailed rules
for the interpretation of each option appear later. In the table, the type 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 4.7.4 Analyzing the picture string and a
formatting phase described in 4.7.5 Formatting the number.
The analysis phase takes as its inputs the ·picture string· and the variables derived from the relevant decimal format in the static context, and produces as its output a number of variables with defined values. The formatting phase takes as its inputs the number to be formatted and the variables produced by the analysis phase, and produces as its output a string containing a formatted representation of the number.
The result of the function is the formatted string representation of the supplied number.
A dynamic error is raised [err:FODF1280]
if
the $options
argument is supplied as an xs:string
that is neither a valid lexical QName nor a
valid URIQualifiedName
, 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 may optionally signal this as a static error.
A dynamic error is raised [err:FODF1290] if a value of
$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: 
"12,345.60" 
Expression: 

Result: 
"12,345,678.90" 
Expression: 

Result: 
"0124" 
Expression: 

Result: 
"14%" 
Expression: 

Result: 
"006" 
Expression: 
formatnumber(1234567.8, '0.000,0', { 'groupingseparator': '.', 'decimalseparator': ',' }) 
Result: 
"1.234.567,8" 
The following examples assume the existence of a decimal format named


Expression: 

Result: 
"1.234,57" 
Expression: 
formatnumber(12345, '0,###^0', { 'formatname': 'de', 'exponentseparator': '^' }) 
Result: 
"1,234^4" 
The following examples assume that the exponent separator
in decimal format 

Expression: 

Result: 
"12.346E2" 
Expression: 

Result: 
"2.3E1" 
Expression: 

Result: 
"0.23E0" 
Expression: 

Result: 
".23E0" 
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
.
Note:
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
).
[Definition] The formatting of a number is controlled by a picture string. The picture string is a sequence of ·characters·, in which the characters assigned to the properties decimalseparator^{XP31} , exponentseparator^{XP31}, groupingseparator^{XP31}, digit^{XP31}, and patternseparator^{XP31} and the members of the ·decimal digit family·, are classified as active characters, and all other characters (including the values of the properties percent^{XP31} and permille^{XP31}) are classified as passive characters.
A dynamic error is raised [err:FODF1310] if the ·picture string· does not conform to the following rules. Note that in these rules the words "preceded" and "followed" refer to characters anywhere in the string; they are not to be read as "immediately preceded" and "immediately followed".
A picturestring consists either of a subpicture, or of two subpictures separated by the patternseparator^{XP31} character. A picturestring must not contain more than one instance of the patternseparator^{XP31} character. If the picturestring contains two subpictures, the first is used for positive and unsigned zero values and the second for negative values.
A subpicture must not contain more than one instance of the decimalseparator^{XP31} character.
A subpicture must not contain more than one instance of the percent^{XP31} or permille^{XP31} characters, and it must not contain one of each.
The mantissa part of a subpicture (defined below) must contain at least one character that is either an ·optional digit character· or a member of the ·decimal digit family·.
A subpicture must not contain a passive character that is preceded by an active character and that is followed by another active character.
A subpicture must not contain a groupingseparator^{XP31} character that appears adjacent to a decimalseparator^{XP31} character, or in the absence of a decimalseparator^{XP31} character, at the end of the integer part.
A subpicture must not contain two adjacent instances of the groupingseparator^{XP31} character.
The integer part of a subpicture (defined below) must not contain a member of the ·decimal digit family· that is followed by an instance of the ·optional digit character·. The fractional part of a subpicture (defined below) must not contain an instance of the ·optional digit character· that is followed by a member of the ·decimal digit family·.
A character that matches the exponentseparator^{XP31} property is treated as an exponentseparatorsign if it is both preceded and followed within the subpicture by an active character. Otherwise, it is treated as a passive character. A subpicture must not contain more than one character that is treated as an exponentseparatorsign.
A subpicture that contains a percent^{XP31} or permille^{XP31} character must not contain a character treated as an exponentseparatorsign.
If a subpicture contains a character treated as an exponentseparatorsign then this must be followed by one or more characters that are members of the ·decimal digit family·, and it must not be followed by any active character that is not a member of the ·decimal digit family·.
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 decimalseparator^{XP31} character if there is one, or the entire mantissa part otherwise.
The fractional part of the subpicture is defined as that part of the mantissa part that appears to the right of the decimalseparator^{XP31} character if there is one, or the part that appears to the right of the rightmost active character otherwise. The fractional part may be zerolength.
This phase of the algorithm analyzes the ·picture string· and the properties from the selected decimal format in the static context, and it has the effect of setting the values of various variables, which are used in the subsequent formatting phase. These variables are listed below. Each is shown with its initial setting and its datatype.
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 groupingseparator^{XP31} character that appears within the integer part of the subpicture, this sequence contains an integer that is equal to the total number of ·optional digit character· and ·decimal digit family· characters that appear within the integer part of the subpicture and to the right of the groupingseparator^{XP31} character.
The grouping is defined to be regular if the following conditions apply:
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 ·decimal digit family· characters found in the integer part of the subpicture, but may be adjusted as described below.
Note:
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 ·optional digit character· and ·decimal digit family· characters in the subpicture.
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 ·decimal digit family· characters found in the integer part of the subpicture.
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 minussign^{XP31} character and the prefix for the positive subpicture (if any), in that order.
The fractionalpartgroupingpositions is a sequence of integers representing the positions of grouping separators within the fractional part of the subpicture. For each groupingseparator^{XP31} character that appears within the fractional part of the subpicture, this sequence contains an integer that is equal to the total number of ·optional digit character· and ·decimal digit family· characters that appear within the fractional part of the subpicture and to the left of the groupingseparator^{XP31} character.
Note:
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 ·optional digit character· and ·decimal digit family· characters in the fractional part of the subpicture.
The minimumfractionalpartsize is set to the number of ·decimal digit family· characters found in the fractional part of the subpicture.
The maximumfractionalpartsize is set to the total number of ·optional digit character· and ·decimal digit family· characters found in the fractional part of the subpicture.
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).
Note:
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).
Note:
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 ·optional digit character· in the integer part of the subpicture
then the minimumintegerpartsize is changed to 1 (one).
Note:
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 ·decimal digit family· characters found in the exponent part of the subpicture if present, or zero otherwise.
Note:
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.
Note:
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 minussign^{XP31} character.
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 input number), and the variables set up by
analyzing the decimal format in the static context and the
·picture string·, as described above.
The result of this phase is a string, which forms the return value of
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 pattern separator^{XP31} property (with no
prefix or suffix).
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 percent^{XP31} character, the adjusted number is the input number multiplied by 100.
If the subpicture contains a permille^{XP31} character, the adjusted number is the input number multiplied by 1000.
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 infinity^{XP31} property, and the appropriate suffix.
If the minimum exponent size is nonzero, and the adjusted number is nonzero, then the adjusted number is scaled to establish a mantissa and an integer exponent. The mantissa and exponent are chosen such that all the following conditions are true:
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 (unless it is zero) is less than 10^{N}, and at least 10^{N1}, where N is the scaling factor.
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 should be one with the smallest possible number of digits
not counting leading or trailing zeroes (whether significant or insignificant).
For example, 1.0 is preferred to
0.9999999999, and 100000000 is preferred to 100000001. This value is then
rounded so that it uses no more than 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 ·decimal digit family· to represent the ten decimal digits, and the decimalseparator^{XP31} character to separate the integer part and the fractional part. This string must always contain a decimalseparator^{XP31}, and it must contain no leading zeroes and no trailing zeroes. The value zero will at this stage be represented by a decimalseparator^{XP31} on its own.
If the number of digits to the left of the decimalseparator^{XP31} character is less than minimumintegerpartsize, leading zero digit^{XP31} characters are added to pad out to that size.
If the number of digits to the right of the decimalseparator^{XP31} character is less than minimumfractionalpartsize, trailing zero digit^{XP31} characters are added to pad out to that size.
For each integer N in the integerpartgroupingpositions list, a groupingseparator^{XP31} character is inserted into the string immediately after that digit that appears in the integer part of the number and has N digits between it and the decimalseparator^{XP31} character, if there is such a digit.
For each integer N in the fractionalpartgroupingpositions list, a groupingseparator^{XP31} character is inserted into the string immediately before that digit that appears in the fractional part of the number and has N digits between it and the decimalseparator^{XP31} character, if there is such a digit.
If there is no decimalseparator^{XP31} character in the subpicture, or if there are no digits to the right of the decimalseparator character in the string, then the decimalseparator character is removed from the string (it will be the rightmost character in the string).
If an exponent exists, then the string produced from the mantissa as described above is extended with the following, in order: (a) the exponentseparator^{XP31} character; (b) if the exponent is negative, the minussign^{XP31} character; (c) the value of the exponent represented as a decimal integer, extended if necessary with leading zeroes to make it up to the minimum exponent size, using digits taken from the ·decimal digit family·.
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 [IEEE 7542008], where
they appear as Recommended operations in section 9. IEEE defines
these functions for a variety of floating point formats; this specification
defines them only for xs:double
values. The IEEE specification
applies with the following caveats:
IEEE states that the preferred quantum is languagedefined. In this specification, it is ·implementationdefined·.
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 ·implementationdefined·.
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 4.2 Arithmetic operators on numeric values.
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 π.
math:pi () as xs:double 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
This function returns the xs:double
value whose lexical representation is
3.141592653589793e0
Expression  Result 


6.283185307179586e0 
The expression 
Returns the value of e^{x} where x is the argument value.
math:exp ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 [IEEE 7542008] specification of
the exp
function applied to 64bit binary floating point values.
The treatment of overflow and underflow is defined in 4.2 Arithmetic operators on numeric values.
Expression  Result 


() 

1.0e0 

2.7182818284590455e0 (approximately) 

7.38905609893065e0 

0.36787944117144233e0 

23.140692632779267e0 

xs:double('NaN') 

xs:double('INF') 

0.0e0 
Returns the value of 10
^{x}, where x is the supplied argument value.
math:exp10 ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
[IEEE 7542008] specification of the exp10
function applied
to 64bit binary floating point values.
The treatment of overflow and underflow is defined in 4.2 Arithmetic operators on numeric values.
Expression  Result 


() 

1.0e0 

1.0e1 

3.1622776601683795e0 

1.0e1 

xs:double('NaN') 

xs:double('INF') 

0.0e0 
Returns the natural logarithm of the argument.
math:log ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
[IEEE 7542008] specification of the log
function applied
to 64bit binary floating point values.
The treatment of divideByZero
and invalidOperation
exceptions
is defined in 4.2 Arithmetic operators on numeric values. The effect is that if the argument is
zero, the result is INF
, and if it is negative, the result is NaN
.
Expression  Result 


() 

xs:double('INF') 

1.0e0 

6.907755278982137e0 

0.6931471805599453e0 

xs:double('NaN') 

xs:double('NaN') 

xs:double('INF') 

xs:double('NaN') 
Returns the baseten logarithm of the argument.
math:log10 ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
[IEEE 7542008] specification of the log10
function applied
to 64bit binary floating point values.
The treatment of divideByZero
and invalidOperation
exceptions
is defined in 4.2 Arithmetic operators on numeric values. The effect is that if the argument is
zero, the result is INF
, and if it is negative, the result is NaN
.
Expression  Result 


() 

xs:double('INF') 

3.0e0 

3.0e0 

0.3010299956639812e0 

xs:double('NaN') 

xs:double('NaN') 

xs:double('INF') 

xs:double('NaN') 
Returns the result of raising the first argument to the power of the second.
math:pow ( 

$x 
as , 

$y 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 [IEEE 7542008] specification of 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 [IEEE 7542008] specification of the
pow
function applied to two 64bit binary floating point values.
The treatment of the divideByZero
and invalidOperation
exceptions is defined in 4.2 Arithmetic operators on numeric values. Some of the consequences are
illustrated in the examples below.
Expression  Result 


() 

8.0e0 

8.0e0 

0.125e0 

0.125e0 

1.0e0 

1.0e0 

1.0e0 

1.0e0 

1.0e0 

0.0e0 

0.0e0 

0.0e0 

0.0e0 

xs:double('INF') 

xs:double('INF') 

xs:double('INF') 

xs:double('INF') 

4.0e0 

2.0e0 

xs:double('INF') 

xs:double('INF') (Oddvalued whole numbers are treated specially). 

xs:double('INF') 

xs:double('INF') 

0.0e0 

0.0e0 (Oddvalued whole numbers are treated specially). 

0.0e0 

0.0e0 

1.0e0 

1.0e0 

1.0e0 

1.0e0 

1.0e0 

6.25e0 

xs:double('NaN') 
Returns the nonnegative square root of the argument.
math:sqrt ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 [IEEE 7542008] specification of the
squareRoot
function applied to 64bit binary floating point values.
The treatment of the invalidOperation
exception is defined in 4.2 Arithmetic operators on numeric values. The effect is that if the argument is less than zero, the result
is 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 


() 

0.0e0 

0.0e0 

1.0e3 

1.4142135623730951e0 

xs:double('NaN') 

xs:double('NaN') 

xs:double('INF') 

xs:double('NaN') 
Returns the sine of the argument. The argument is an angle in radians.
math:sin ( 

$radians 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 [IEEE 7542008] specification of the
sin
function applied to 64bit binary floating point values.
The treatment of the invalidOperation
and underflow
exceptions
is defined in 4.2 Arithmetic operators on numeric values.
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 


() 

0.0e0 

0.0e0 

1.0e0 (approximately) 

1.0e0 (approximately) 

0.0e0 (approximately) 

xs:double('NaN') 

xs:double('NaN') 

xs:double('NaN') 
Returns the cosine of the argument. The argument is an angle in radians.
math:cos ( 

$radians 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 [IEEE 7542008] specification of the
cos
function applied to 64bit binary floating point values.
The treatment of the invalidOperation
exception is defined in 4.2 Arithmetic operators on numeric values.
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 


() 

1.0e0 

1.0e0 

0.0e0 (approximately) 

0.0e0 (approximately) 

1.0e0 (approximately) 

xs:double('NaN') 

xs:double('NaN') 

xs:double('NaN') 
Returns the tangent of the argument. The argument is an angle in radians.
math:tan ( 

$radians 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 [IEEE 7542008] specification of the
tan
function applied to 64bit binary floating point values.
The treatment of the invalidOperation
and underflow
exceptions
is defined in 4.2 Arithmetic operators on numeric values.
If $radians
is positive or negative infinity, or NaN
,
then the result is NaN
.
Expression  Result 


() 

0.0e0 

0.0e0 

1.0e0 (approximately) 

1.0e0 (approximately) 

0.0e0 (approximately) (Mathematically, tan(π/2) is positive infinity. But because 

0.0e0 (approximately) (Mathematically, tan(π/2) is negative infinity. But because 

0.0e0 (approximately) 

xs:double('NaN') 

xs:double('NaN') 

xs:double('NaN') 
Returns the arc sine of the argument.
math:asin ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 [IEEE 7542008] specification of 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 4.2 Arithmetic operators on numeric values.
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 


() 

0.0e0 

0.0e0 

1.5707963267948966e0 (approximately) 

1.5707963267948966e0 (approximately) 

xs:double('NaN') 

xs:double('NaN') 

xs:double('NaN') 

xs:double('NaN') 
Returns the arc cosine of the argument.
math:acos ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 [IEEE 7542008] specification of 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 4.2 Arithmetic operators on numeric values.
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 


() 

1.5707963267948966e0 (approximately) 

1.5707963267948966e0 (approximately) 

0.0e0 

3.141592653589793e0 (approximately) 

xs:double('NaN') 

xs:double('NaN') 

xs:double('NaN') 

xs:double('NaN') 
Returns the arc tangent of the argument.
math:atan ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 [IEEE 7542008] specification of 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 4.2 Arithmetic operators on numeric values.
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 


() 

0.0e0 

0.0e0 

0.7853981633974483e0 (approximately) 

0.7853981633974483e0 (approximately) 

xs:double('NaN') 

1.5707963267948966e0 (approximately) 

1.5707963267948966e0 (approximately) 
Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive xaxis.
math:atan2 ( 

$y 
as , 

$x 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The result is the value of atan2(y, x)
as defined in the [IEEE 7542008] specification of 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 4.2 Arithmetic operators on numeric values. The following rules apply when the values are finite and nonzero,
(subject to rules for overflow, underflow and approximation).
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 


0.0e0 

0.0e0 

3.141592653589793e0 

3.141592653589793e0 

1.5707963267948966e0 

1.5707963267948966e0 

3.141592653589793e0 

3.141592653589793e0 

0.0e0 

+0.0e0 
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.
fn:randomnumbergenerator ( 

$seed 
as

:= () 
) as randomnumbergeneratorrecord 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The function returns a random number generator. A random number generator is represented as a value of type
randomnumbergeneratorrecord
, defined as follows:
randomnumbergeneratorrecord : 

record( 

number 
as xs:double , 
next 
as function() as randomnumbergeneratorrecord , 
permute 
as function(item()*) as item()* , 
* 

) 
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 ·deterministic·: calling the function twice with the same arguments, within a single ·execution scope·, produces the same results.
The value of the number
entry should be such that all eligible xs:double
values are equally likely to be chosen the distribution of numbers is uniform: for example, the probability of the
number being in the range 0.1e0 to 0.2e0 is the same as the probability of its being in the range 0.8e0 to 0.9e0.
The function returned in the permute
entry should be such that all permutations
of the supplied sequence are equally likely to be chosen.
The map returned by the fn:randomnumbergenerator
function may contain additional entries beyond
those specified here, but it must match the
record type defined above. The meaning of any additional entries
is ·implementationdefined·. To avoid conflict with any future version of this specification, the keys of any
such entries should start with an underscore character.
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 recommended that when the same seed is provided explicitly, the same random number sequence
should be delivered even in different execution scopes; while if no seed is provided, the processor should choose a seed
that is likely to be different from one execution scope to another. (The same effect can be achieved explicitly by using
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 

declare %public function local:randomsequence($length as xs:integer) as xs:double* { local:randomsequence($length, randomnumbergenerator()) }; declare %private function local:randomsequence( $length as xs:integer, $record as record(number as xs:double, next as function(*), *) ) as xs:double* { if ($length != 0) { $record?number, local:randomsequence($length  1, $record?next()) } }; local:randomsequence(200) 

An equivalent result can be achieved with 

tail(foldleft( (1 to 200), randomnumbergenerator(), fn($result) { head($result) ! (?next(), ?number), tail($result) } )) 
This section specifies functions and operators on the [XML Schema Part 2: Datatypes Second Edition]
xs:string
datatype and the datatypes derived from it.
The operators described in this section are defined on the following types.
string
normalizedString
token
language
NMTOKEN
Name
NCName
ENTITY
ID
IDREF
Legend:
Supertype
subtype
Builtin atomic 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 ·codepoints·. 
fn:stringtocodepoints 
Returns the sequence of ·codepoints· that constitute an
xs:string value. 
Returns an xs:string
whose characters have supplied ·codepoints·.
fn:codepointstostring ( 

$values 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The function returns the string made up from the ·characters· whose Unicode ·codepoints· are
supplied in $values
. This will be the zerolength string if $values
is the empty sequence.
A dynamic error is raised [err:FOCH0001] if any of the codepoints in
$values
is not a
·permitted character·.
Expression  Result 


"BACH" 

"अशॊक" 

"" 

Raises error FOCH0001. 
Returns the sequence of ·codepoints· that constitute an
xs:string
value.
fn:stringtocodepoints ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The function returns a sequence of integers, each integer being the Unicode ·codepoint· of the corresponding ·character· in $value
.
If $value
is a zerolength string or the empty sequence, the function returns
the empty sequence.
Expression  Result 


(84, 104, 233, 114, 232, 115, 101) 
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 ·strings· are
compared and, by extension, ordered. When values whose type is
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 [Character Model for the World Wide Web 1.0: Fundamentals] observes that
some applications may require different comparison and ordering behaviors
than other applications. Similarly, some users having particular linguistic
expectations may require different behaviors than other users. Consequently,
the collation must be taken into account when comparing strings in any
context. Several functions in this and the following section make use of a
collation.
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 [UTS #10]) can be “tailored” for various purposes. This document does not discuss such tailoring, nor does it provide a mechanism to perform tailoring. Instead, it assumes that the collation argument to the various functions below is a tailored and named collation.
The ·Unicode codepoint collation· is a collation available in every implementation, which sorts based on codepoint values. For further details see 5.3.2 The Unicode Codepoint Collation.
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 ·implementationdefined· base URI.
Note:
Previous versions of this specification stated that it must be resolved against the Static Base URI^{XP40}, but this is not always operationally convenient. It is recommended that processors should provide a means of setting the base URI for resolving collation URIs independently of the Static Base URI^{XP40}, though for backwards compatibility, the Static Base URI^{XP40} or Executable Base URI^{XP40} should be used as a default.
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 [UTS #35].
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 Section 2.1.1 Static Context ^{XP31}. If the default collation is not specified by the user or the system, the default collation is the ·Unicode codepoint collation·.
Note:
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.
[Definition] The collation URI
http://www.w3.org/2005/xpathfunctions/collation/codepoint
identifies
a collation which must be recognized by every implementation: it is referred to as
the Unicode codepoint collation (not to be confused with the Unicode collation algorithm).
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)
Note:
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 [UTS #10]. The parameters used for tailoring the UCA are based on the parameters defined in the Locale Data Markup Language (LDML), defined in [UTS #35].
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 must either use a collation that conforms with
the rules in the Unicode specifications for the requested tailoring, or fail with a static or dynamic error indicating that it
does not provide the collation (the error code should be the same as if the collation URI were not recognized).
If the 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 must accept the collation URI, and should use the available
collation that most closely reflects the user’s intentions. For example, if the collation URI requested is
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 may choose to use a Swedish collation that is known to differ
from the UCA definition, or one whose conformance has not been established. It might even, as a last resort, fall back to using
codepoint collation.
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 ·implementationdefined·. If the implementation recognizes
the meaning of the keyword and value then it should interpret it accordingly; if it does not recognize
the keyword or value then if the 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 ·implementationdefined· except where otherwise stated. The meaning given for each parameter is nonnormative; the normative specification is found in [UTS #35].
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 [ISO 15924 Register], the register
of scripts maintained by the Unicode Consortium in its capacity as registration authority
for [ISO 15924]. 
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. 
Note:
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 designed to be compatible with
the HTML ASCII caseinsensitive collation as defined in [HTML: Living Standard] (section 4.6, Strings),
which is used, for example, when matching HTML 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)
.
Note:
HTML5 defines the semantics of equality matching using this collation; this
specification additionally defines ordering rules.
The collation supports collation units and can therefore
be used with functions such as 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 [err:FOCH0002].
If no collation is explicitly specified for the function
(that is,
if the $collation
argument is omitted or is set to an
empty sequence), and the
default collation in the XQuery/XPath static context is CollationB, then:
If CollationB is supported by the implementation, then CollationB is used.
Otherwise, a dynamic error is raised [err:FOCH0002].
Note:
Because the set of collations that are supported is ·implementationdefined·, an implementation has the option to support all collation URIs, in which case it will never raise this error.
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 [err:FOCH0002].
Note:
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 relevant base URI.
Returns true
if two strings are equal, considered codepointbycodepoint.
fn:codepointequal ( 

$value1 
as , 

$value2 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 


true() 

false() 

true() 

() 

() 
Constructs a collation URI with requested properties.
fn:collation ( 

$options 
as


) as

This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations.
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 [err:FOCH0002] otherwise.
The properties available are as defined for the Unicode Collation Algorithm (see 5.3.3 The Unicode Collation Algorithm). Additional ·implementationdefined· properties may be specified as described in the rules for UCA collation URIs.
The ·option parameter conventions· apply, except as regards the handling of options not defined in this specification. Specifically:
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 5.3.3 The Unicode Collation Algorithm.
If the option key is of any other type then the function fails with a type error [err:XPTY0004]^{XP}.
The following options are defined:
Key  Meaning 

fallback 
See 5.3.3 The Unicode Collation Algorithm.

lang 
See 5.3.3 The Unicode Collation Algorithm.

version 
See 5.3.3 The Unicode Collation Algorithm.

strength 
See 5.3.3 The Unicode Collation Algorithm.

maxVariable 
See 5.3.3 The Unicode Collation Algorithm.

alternate 
See 5.3.3 The Unicode Collation Algorithm.

backwards 
See 5.3.3 The Unicode Collation Algorithm.

normalization 
See 5.3.3 The Unicode Collation Algorithm.

caseLevel 
See 5.3.3 The Unicode Collation Algorithm.

caseFirst 
See 5.3.3 The Unicode Collation Algorithm.

numeric 
See 5.3.3 The Unicode Collation Algorithm.

reorder 
See 5.3.3 The Unicode Collation Algorithm.

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 [err:FOCH0002]
if no collation is available with the required properties.
Note that conformant implementations must accept
any collation constructed with the option {'fallback':true()}
.
A type error is raised [err:XPTY0004]^{XP} if
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: 
"http://www.w3.org/2013/collation/UCA" 
Expression: 

Result: 
"http://www.w3.org/2013/collation/UCA?lang=de" 
Expression: 

Result: 
"http://www.w3.org/2013/collation/UCA?lang=de;strength=primary" (The order of query parameters may vary.) 
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.
fn:collationkey ( 

$value 
as , 

$collation 
as

:= fn:defaultcollation() 
) as

This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations.
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 ·implementationdependent·
value with the property that,
for any two strings $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 5.3.5 Choosing a collation. Collation keys are defined as 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 ·execution scope·; an implementation is under no obligation to generate the same collation keys during a subsequent unrelated query or transformation.
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 ·implementationdefined· property of the collation.
An error is raised [err:FOCH0004] if the specified collation does not support the generation of collation keys.
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 [UTS #10]. Implementations are not required to use this algorithm.
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  

let $C := collation(map{'strength':'primary'}) 
Expression: 
map:merge( ({ collationkey("A", $C): 1 }, { collationkey("a", $C): 2 }), { "duplicates": "uselast" } )(collationkey("A", $C)) 

Result: 
2 (Given that the keys of the two entries are equal under the rules of the chosen collation, only one of the entries can appear in the result; the one that is chosen is the one from the last map in the input sequence.) 
Expression: 
let $M := { collationkey("A", $C): 1, collationkey("B", $C): 2 } return $M(collationkey("a", $C)) 
Result: 
1 (The strings 
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.
fn:containstoken ( 

$value 
as , 

$token 
as , 

$collation 
as

:= fn:defaultcollation() 
) as

The twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations.
The threeargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and static base URI.
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 5.3.5 Choosing a collation.
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:
some $t in $input ! tokenize(.) satisfies compare($t, replace($token, '^\s*\s*$', ''), $collation) eq 0)
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 5.3.4 The HTML ASCII CaseInsensitive Collation.
Expression: 


Result: 
true() 
Expression: 

Result: 
true() 
Expression: 

Result: 
false() 
Expression: 
containstoken( "red green blue", "RED", "http://www.w3.org/2005/xpathfunctions/collation/htmlasciicaseinsensitive" ) 
Result: 
true() 
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 ·characters· indicated by $length . 
fn:stringlength 
Returns the number of ·characters· in a string. 
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. 
Notes:
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.
fn:char ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The function returns a string, generally containing a single ·character· or glyph, identified by $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 https://html.spec.whatwg.org/multipage/namedcharacters.html. The name is
written with no leading ampersand and no trailing semicolon.
For example fn:char("pi")
represents the character
π
(x3C0
) and fn:char("nbsp")
returns the
nonbreaking space character, xA0
.
A processor may recognize additional character reference names defined in other versions of HTML. Character reference names are casesensitive.
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
·permitted characters·.
For example fn:char(0xDEAD)
is invalid because it is in the surrogate range.
The function fails with a dynamic error [err:FOCH0005] if $value
is not a valid
representation of a ·permitted character·
or sequence of permitted characters.
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 


"á" 

"ð" 

codepointstostring(9) (The character tab). 

codepointstostring(9) (The character tab). 

" " 

"𝇊" (The character MUSICAL SYMBOL TEMPUS IMPERFECTUM CUM PROLATIONE PERFECTA). 

codepointstostring((8770, 824)) (This HTML5 character reference name expands to multiple codepoints.) 
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.
fn:characters ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The function returns a sequence of strings, each string having length 1, containing
the corresponding ·character· in $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 


("T", "h", "é", "r", "è", "s", "e") 

() 

() 

(2, 4, 6) 

"stretch" 
"Banana" => characters() => reverse() => stringjoin() 
"ananaB" 
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.
fn:concat ( 

$... 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 [XML Path Language (XPath) Version 1.0].
As mentioned in 5.1 String types Unicode normalization is not automatically
applied to the result of fn:concat
. If a normalized result is required,
fn:normalizeunicode
can be applied to the xs:string
returned by fn:concat
. The following XQuery:
let $v1 := "I plan to go to Mu" let $v2 := "?nchen in September" return concat($v1, $v2)
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:
let $v1 := "I plan to go to Mu" let $v2 := "?nchen in September" return normalizeunicode(concat($v1, $v2))
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: 
"ungrateful" 
Expression: 
concat( 'Thy ', (), 'old ', "groans", "", ' ring', ' yet', ' in', ' my', ' ancient',' ears.' ) 
Result: 
"Thy old groans ring yet in my ancient ears." 
Expression: 

Result: 
"Ciao!" 
Expression: 

Result: 
"Ingratitude, thou marblehearted fiend!" 
Expression: 

Result: 
"1234true" 
Expression: 

Result: 
"" 
Expression: 

Result: 
"10/6" 
Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items.
fn:stringjoin ( 

$values 
as , 

$separator 
as

:= "" 
) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 casting each item
in the sequence $values
to an xs:string
,
and then concatenating the result strings in order,
using the value of $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  

let $doc := <doc> <chap> <section xml:id="xyz"/> </chap> </doc> 
Expression: 


Result: 
"123456789" 
Expression: 

Result: 
"Now is the time ..." 
Expression: 
stringjoin( ('Blow, ', 'blow, ', 'thou ', 'winter ', 'wind!'), '' ) 
Result: 
"Blow, blow, thou winter wind!" 
Expression: 

Result: 
"" 
Expression: 

Result: 
"1, 2, 3, 4, 5" 
Expression: 
$doc//@xml:id ! stringjoin((nodename(), '="', ., '"')) 
Result: 
'xml:id="xyz"' 
Expression: 
$doc//section ! stringjoin(ancestororself::*/name(), '/') 
Result: 
"doc/chap/section" 
Returns the part of $value
beginning at the position
indicated by $start
and continuing for the number of ·characters· indicated by $length
.
fn:substring ( 

$value 
as , 

$start 
as , 

$length 
as

:= () 
) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
If $value
is the empty sequence, the function returns
the zerolength string.
Otherwise, the function returns a string comprising those ·characters· of $value
whose index position (counting
from one) is greater than or equal to $start
(rounded to an
integer), and (if $length
is specified
and nonempty) less than the sum of
$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 ·characters· in
$value
whose position $p
satisfies:
fn:round($start) <= $p
In the above computations, the rules for op:numericlessthan
and
op:numericgreaterthan apply.
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 


" car" (Characters starting at position 6 to the end of


"ada" (Characters at positions greater than or equal to 4 and less than 7 are selected.) 

"234" (Characters at positions greater than or equal to 2 and less than 5 are selected.) 

"12" (Characters at positions greater than or equal to 0 and less than 3 are selected. Since the first position is 1, these are the characters at positions 1 and 2.) 

"" (Characters at positions greater than or equal to 5 and less than 2 are selected.) 

"1" (Characters at positions greater than or equal to 3 and less than 2 are selected. Since the first position is 1, this is the character at position 1.) 

"" (Since 

"" (As above.) 

"" 

"12345" (Characters at positions greater than or equal to 42 and less than


"" (Since the value of 
Changed in 4.0: The third argument can now be supplied as an empty sequence.
Returns the number of ·characters· in a string.
fn:stringlength ( 

$value 
as

:= fn:string(.) 
) as

The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The function returns an xs:integer
equal to the length in ·characters· of $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 absent^{DM40}, a type error is raised: [err:XPDY0002]^{XP}.
As a consequence of the rules given above, a type error is raised [err:XPTY0004]^{XP} if the context value cannot be atomized, or if the result of atomizing the context value is a sequence containing more than one atomic value.
Unlike some programming languages, a ·codepoint· greater than 65535 counts as one character, not two.
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: 
stringlength( "Harp not on that string, madam; that is past." ) 

Result: 
45 
Expression: 
"ᾧ" => stringlength() 
Result: 
1 
Expression: 
"ᾧ" => normalizeunicode("NFD") => stringlength() 
Result: 
4 (For strings that consist of a base character with combining characters, each combining character is length 1.) 
Expression: 

Result: 
0 
Returns $value
with leading and trailing whitespace removed, and
sequences of internal whitespace reduced to a single space character.
fn:normalizespace ( 

$value 
as

:= fn:string(.) 
) as

The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 [Extensible Markup Language (XML) 1.0 (Fifth Edition)].
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 absent^{DM40}, a type error is raised [err:XPDY0002]^{XP}.
As a consequence of the rules given above, a type error is raised [err:XPTY0004]^{XP} if the context value cannot be atomized, or if the result of atomizing the context value is a sequence containing more than one atomic value.
The definition of whitespace is unchanged in [Extensible Markup Language (XML) 1.1 Recommendation]. It is repeated here for convenience:
S ::= (#x20  #x9  #xD  #xA)+
Expression: 
normalizespace(" The wealthy curled darlings of our nation. ") 

Result: 
"The wealthy curled darlings of our nation." 
Expression: 

Result: 
"" 
Returns $value
after applying Unicode normalization.
fn:normalizeunicode ( 

$value 
as , 

$form 
as

:= "NFC" 
) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 [UAX #15].
The motivation for normalization form FULLYNORMALIZED is explained in [Character Model for the World Wide Web 1.0: Normalization]. However, as that specification did not progress beyond working draft status, the normative specification is as follows:
A string is fullynormalized if (a) it is in normalization form NFC as defined in [UAX #15], and (b) it does not start with a composing character.
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 [UAX #15];
of nonzero canonical combining class (as defined in [The Unicode Standard]).
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 must support normalization form NFC
and
may support normalization forms NFD
, NFKC
, NFKD
, and
FULLYNORMALIZED
. They may also support other normalization forms
with ·implementationdefined· semantics.
It is ·implementationdefined· which
version of Unicode (and therefore, of the normalization algorithms and their underlying
data) is supported by the implementation. See [UAX #15] for
details of the stability policy regarding changes to the normalization rules in future
versions of Unicode. If the input string contains codepoints that are unassigned in the
relevant version of Unicode, or for which no normalization rules are defined, the
fn:normalizeunicode
function leaves such codepoints unchanged. If the
implementation supports the requested normalization form then it must
be able to handle every input string without raising an error.
A dynamic error is raised [err:FOCH0003] if the
effective value of the $form
argument is not one of the values
supported by the implementation.
Converts a string to upper case.
fn:uppercase ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
If $value
is the empty sequence, the zerolength string is
returned.
Otherwise, the function returns $value
after translating every
·character· to its uppercase correspondent as
defined in the appropriate case mappings section in the Unicode standard [The Unicode Standard]. For versions of Unicode beginning with the 2.1.8 update, only
localeinsensitive case mappings should be applied. Beginning with version 3.2.0 (and
likely future versions) of Unicode, precise mappings are described in default case
operations, which are full case mappings in the absence of tailoring for particular
languages and environments. Every lowercase character that does not have an uppercase
correspondent, as well as every uppercase character, is included in the returned value
in its original form.
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 


"ABCD0" 
Converts a string to lower case.
fn:lowercase ( 

$value 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
If t$value
is the empty sequence, the zerolength string is
returned.
Otherwise, the function returns $value
after translating every
·character· to its lowercase correspondent as
defined in the appropriate case mappings section in the Unicode standard [The Unicode Standard]. For versions of Unicode beginning with the 2.1.8 update, only
localeinsensitive case mappings should be applied. Beginning with version 3.2.0 (and
likely future versions) of Unicode, precise mappings are described in default case
operations, which are full case mappings in the absence of tailoring for particular
languages and environments. Every uppercase character that does not have a lowercase
correspondent, as well as every lowercase character, is included in the returned value
in its original form.
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 


"abc!d" 
Returns $value
modified by replacing or removing individual
characters.
fn:translate ( 

$value 
as , 

$replace 
as , 

$with 
as


) as

This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
If $value
is the empty sequence, the function returns the
zerolength string.
Otherwise, the function returns a result string constructed by processing each ·character· in $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 M, where the value of $with
is
M or more characters in length, then the character at position
M in $with
is added to the result string.
If the character first appears in $replace
at some
position M, where $with
is less than
M characters in length, then the character is omitted from the
result string.
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 


"BAr" 

"AAA" 

"ABdAB" 
Returns a string representation of the results from a specified hash, checksum, or cyclic redundancy check function upon the input.
fn:hash ( 

$value 
as , 

$options 
as

:= {} 
) as

The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The twoargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The $options
argument, if present, defines additional parameters
controlling how the process is conducted. The ·option parameter conventions· apply.
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 must support the following options and the functions referred to by them:
Conforming implementations may support other checksum and hash functions with implementationdefined semantics.

A dynamic error is raised [err:FOHA0001] if the effective value of the option
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 [RFC 1321] and
[FIPS 1804]) requires further adjustment.
Variables  

let $doc := <doc>abc</doc> 

let $salt := "D;%yL9TS:5PalS/d" 
Expression: 
hash("abc") => string() 

Result: 
"900150983CD24FB0D6963F7D28E17F72" 
Expression: 
hash("ABC") => string() => lowercase() 
Result: 
"902fbdd2b1df0c4f70b4a5d23525e932" 
Expression: 
hash("") => string() 
Result: 
"D41D8CD98F00B204E9800998ECF8427E" 
Expression: 
hash("ABC", { "algorithm": "SHA1" }) => string() 
Result: 
"3C01BDBB26F358BAB27F267924AA2C9A03FCFDB8" 
Expression: 
hash("ABC", { "algorithm": "sha256" }) => string() 
Result: 
"B5D4045C3F466FA91FE2CC6ABE79232A1A57CDF104F7A26E716E0A1E2789DF78" 
Expression: 
hash($doc) => string() 
Result: 
"900150983CD24FB0D6963F7D28E17F72" 
Expression: 
hash(serialize($doc), { "algorithm": "sha1" }) => xs:base64Binary() => string() 
Result: 
"8PzN28NtxQv5RlxQ5/w6DcnrpEU=" 
Expression: 
hash("password123"  $salt, { "algorithm": "SHA256" }) => string() 
Result: 
"9C9B913EB1B6254F4737CE947EFD16F16E916F9D6EE5C1102A2002E48D4C88BD" 
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 ·characters· in $arg1
which $arg2
matches.
When the ·Unicode codepoint collation·
is used, this simply involves determining whether $arg1
contains a
contiguous sequence of characters whose ·codepoints· are the same, one for one,
with the codepoints of the characters in $arg2
.
When a collation is specified, the rules are more complex.
All collations support the capability of deciding whether two ·strings· are
considered equal, and if not, which of the strings should be regarded as
preceding the other. For functions such as 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 [UTS #10].) The string
$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 match and minimal match as defined in definitions DS2 and DS4 of [UTS #10]. In applying these definitions:
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 [UTS #10]). It is not satisfied between two characters that belong to the same collation unit.
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 ·implementationdefined· property of the collation.
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.
fn:contains ( 

$value 
as , 

$substring 
as , 

$collation 
as

:= fn:defaultcollation() 
) as

The twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations.
The threeargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and static base URI.
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 5.3.5 Choosing a collation.
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 minimal match to the
collation units in $substring
, according to the collation that is
used.
Note:
Minimal match is defined in [UTS #10].
A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.
Variables  

let $coll := "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" 
Expression  Result 

The collation used in some of these examples, 

“Ignorable collation unit” is equivalent to “ignorable collation element” in [UTS #10]. 


true() 

false() 

true() (The first rule is applied, followed by the second rule.) 
contains( "abcdefghi", "def", $coll ) 
true() 
contains( "a*b*c*d*e*f*g*h*i*", "def", $coll ) 
true() 
contains( "abcd***ef**ghi", "def", $coll ) 
true() 
contains( (), "****", $coll ) 
true() (The second argument contains only ignorable collation units and is equivalent to the zerolength string.) 
Returns true
if the string $value
contains $substring
as a leading
substring, taking collations into account.
fn:startswith ( 

$value 
as , 

$substring 
as , 

$collation 
as

:= fn:defaultcollation() 
) as

The twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations.
The threeargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and static base URI.
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 5.3.5 Choosing a collation.
The function returns an xs:boolean
indicating whether or not
$value
starts with a sequence of collation units that provides a
match to the collation units of $substring
according to the
collation that is used.
Note:
Match is defined in [UTS #10].
A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.
Variables  

let $coll := "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" 
Expression  Result 

The collation used in some of these examples, 

“Ignorable collation unit” is equivalent to “ignorable collation element” in [UTS #10]. 


true() 

false() 

true() 
startswith( "abcdefghi", "abc", $coll ) 
true() 
startswith( "a*b*c*d*e*f*g*h*i*", "abc", $coll ) 
true() 
startswith( "abcd***ef**ghi", "abcdef", $coll ) 
true() 
startswith( (), "****", $coll ) 