Returns the name of a node, as an xs:QName
.
If the argument is omitted, it defaults to the context item (.
).
If $node
is the empty sequence, the empty sequence is returned.
Otherwise, the function returns the result of the dm:nodename
accessor as
defined in
The following errors may be raised when $node
is omitted:
If the context item is
If the context item is not a node, type error
For element and attribute nodes, the name of the node is returned as an
xs:QName
, retaining the prefix, namespace URI, and local part.
For processing instructions, the name of the node is returned as an
xs:QName
in which the prefix and namespace URI are
For a namespace node, the function returns an empty sequence if the node represents the
default namespace; otherwise it returns an xs:QName
in which prefix and
namespace URI are
For all other kinds of node, the function returns the empty sequence.
Returns true
for an element that is
If the argument is omitted, it defaults to the context item (.
).
If $node
is the empty sequence, the function returns the empty sequence.
Otherwise the function returns the result of the dm:nilled
accessor as
defined in
The following errors may be raised when $node
is omitted:
If the context item is
If the context item is not a node, type error
If $node
is not an element node, the function returns the empty
sequence.
If $node
is an untyped element node, the function returns false
.
In practice, the function returns true
only for an element node that has
the attribute xsi:nil="true"
and that is successfully validated against a
schema that defines the element to be nillable; the detailed rules, however, are defined
in
Returns the value of $value
represented as an xs:string
.
In the zeroargument version of the function, $value
defaults to the context
item. That is, calling fn:string()
is equivalent to calling
fn:string(.)
.
If $value
is the empty sequence, the function returns the zerolength
string.
If $value
is a node, the function returns the string value of the node, as obtained using the
dm:stringvalue
accessor defined in
If $value
is an atomic value, the function returns the result of the expression $value cast
as xs:string
(see
In all other cases, a dynamic error occurs (see below).
A dynamic error is raised
A type error is raised $value
is a function item (this includes maps and arrays).
Every node has a string value, even an element with elementonly content (which has no typed value). Moreover, casting an atomic value to a string always succeeds. Functions, maps, and arrays have no string value, so these are the only arguments that satisfy the type signature but cause failure.
Returns the result of atomizing a sequence. This process flattens arrays, and replaces nodes by their typed values.
If the argument is omitted, it defaults to the context item (.
).
The result of fn:data
is the sequence of atomic values produced by
applying the following rules to each item in $input
:
If the item is an atomic value, it is appended to the result sequence.
If the item is a node, the typed value of the node is appended to the result
sequence. The typed value is a sequence of zero or more atomic values:
specifically, the result of the dm:typedvalue
accessor as defined in
If the item is an array, the result of applying fn:data
to
each member of the array, in order, is appended to the result sequence.
A type error is raised $input
is a node that does not have a typed value.
A type error is raised $input
is a function item other than
an array.
A dynamic error is raised if $input
is omitted and the context item is
The process of applying the fn:data
function to a sequence is referred to
as atomization
. In many cases an explicit call on fn:data
is
not required, because atomization is invoked implicitly when a node or sequence of nodes
is supplied in a context where an atomic value or sequence of atomic values is
required.
The result of atomizing an empty sequence is an empty sequence.
The result of atomizing an empty array is an empty sequence.
Returns the base URI of a node.
The zeroargument version of the function returns the base URI of the context node: it
is equivalent to calling fn:baseuri(.)
.
The singleargument version of the function behaves as follows:
If $node
is the empty sequence, the function returns the empty
sequence.
Otherwise, the function returns the value of the dm:baseuri
accessor
applied to the node $node
. This accessor is defined, for each kind of
node, in the XDM specification (See
As explained in XDM, document, element and processinginstruction nodes have a baseuri property which may be empty. The baseuri property for all other node kinds is the empty sequence. The dm:baseuri accessor returns the baseuri property of a node if it exists and is nonempty; otherwise it returns the result of applying the dm:baseuri accessor to its parent, recursively. If the node does not have a parent, or if the recursive ascent up the ancestor chain encounters a parentless node whose baseuri property is empty, the empty sequence is returned. In the case of namespace nodes, however, the result is always an empty sequence — it does not depend on the base URI of the parent element.
See also fn:staticbaseuri
.
The following errors may be raised when $node
is omitted:
If the context item is
If the context item is not a node, type error
Returns the URI of a resource where a document can be found, if available.
If the argument is omitted, it defaults to the context item (.
).
If $node
is the empty sequence, the function returns the empty sequence.
If $node
is not a document node, the function returns the empty
sequence.
Otherwise, the function returns the value of the documenturi
accessor
applied to $node
, as defined in
The following errors may be raised when $node
is omitted:
If the context item is
If the context item is not a node, type error
In the case of a document node $D
returned by the fn:doc
function, or a document node at the root of a tree containing a node returned by the
fn:collection
function, it will always be true that either
fn:documenturi($D)
returns the empty sequence, or that the following
expression is true
: fn:doc(fn:documenturi($D))
is $D
. It is
A consequence of these rules is that it is not possible (within the
execution scope of a transformation) for two different documents to have the same
value for their documenturi
property. This means that in situations where
URI stability is not guaranteed (for example, with streamed input documents in XSLT,
or for documents returned by fn:collection
if document stability has been
disabled), the documenturi
property fn:documenturi
Calling the fn:error
function raises an applicationdefined error.
This function never returns a value. Instead it always raises an error. The effect of the error is identical to the effect of dynamic errors raised implicitly, for example when an incorrect argument is supplied to a function.
The parameters to the fn:error
function supply information that is
associated with the error condition and that is made available to a caller that asks for
information about the error. The error may be caught either by the host language (using
a try/catch construct in XSLT or XQuery, for example), or by the calling application or
external processing environment. The way in which error information is returned to the
external processing environment is
There are three pieces of information that may be associated with an error.
The $code
is an error code that distinguishes this error from others.
It is an xs:QName
; the namespace URI conventionally identifies the
component, subsystem, or authority responsible for defining the meaning of the
error code, while the local part identifies the specific error condition. The
namespace URI http://www.w3.org/2005/xqterrors
is used for errors
defined in this specification; other namespace URIs may be used for errors defined
by the application.
If the external processing environment expects the error code to be returned as a
URI or a string rather than as an xs:QName
, then an error code with
namespace URI NS
and local part LP
will be returned in
the form NS#LP
. The namespace URI part of the error code should
therefore not include a fragment identifier.
If no value is supplied for the $code
argument, fn:QName('http://www.w3.org/2005/xqterrors', 'err:FOER0000')
.
The $description
is a naturallanguage description of the error
condition.
If no value is supplied for the $description
argument,
The $value
is an arbitrary value used to convey additional
information about the error, and may be used in any way the application
chooses.
If no value is supplied for the $value
argument
This function always raises a dynamic error. By default, it raises
The value of the $description
parameter may need to be localized.
The type none
is a special type defined in
Any QName may be used as an error code; there are no reserved names or namespaces. The error is always classified as a dynamic error, even if the error code used is one that is normally used for static errors or type errors.
http://www.w3.org/2005/xqterrors#FOER0000
(or the corresponding
xs:QName
) to the external processing environment, unless the error
is caught using a try/catch construct in the host language.http://www.example.com/HR#toohighsal
and the
xs:string
"Salary is too high"
(or the corresponding
xs:QName
) to the external processing environment, unless the error
is caught using a try/catch construct in the host language.$description
was supplied, it could not be empty.Provides an execution trace intended to be used in debugging queries.
The function returns $input
, unchanged.
In addition, the values of $input
, typically serialized and converted
to an xs:string
, and $label
(if supplied
The serialization of the trace output
The format of the trace output and its order are
If the trace information is unrelated to a specific value,
fn:log
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, $v
is an
xs:decimal
with value 124.84
.
Writing fn:trace($v, 'the value of $v is:')
will output the strings
"124.84"
and "the value of $v is:"
in an implementationdependent order.
$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.
Similar to fn:trace
, the values of $input
,
typically serialized and converted to an xs:string
, and $label
(if supplied and nonempty)
In contrast to fn:trace
, the function returns an empty sequence.
The serialization of the log output
The format of the trace output and its order are
The function can be used for debugging. It can also be helpful in productive environments, e.g. to store dynamic input and evaluations to log files.
+
operator when
applied to two numeric valuesReturns the arithmetic sum of its operands: ($arg1 + $arg2
).
General rules: see
For xs:float
or xs:double
values, if one of the operands is a
zero or a finite number and the other is INF
or INF
,
INF
or INF
is returned. If both operands are
INF
, INF
is returned. If both operands are
INF
, INF
is returned. If one of the operands is
INF
and the other is INF
, NaN
is
returned.

operator when
applied to two numeric values. Returns the arithmetic difference of its operands: ($arg1  $arg2
).
General rules: see
For xs:float
or xs:double
values, if one of the operands is a
zero or a finite number and the other is INF
or INF
, an
infinity of the appropriate sign is returned. If both operands are INF
or
INF
, NaN
is returned. If one of the operands is
INF
and the other is INF
, an infinity of the appropriate
sign is returned.
*
operator when
applied to two numeric values.Returns the arithmetic product of its operands: ($arg1 * $arg2
).
General rules: see
For xs:float
or xs:double
values, if one of the operands is a
zero and the other is an infinity, NaN
is returned. If one of the operands
is a nonzero number and the other is an infinity, an infinity with the appropriate sign
is returned.
div
operator when
applied to two numeric values.Returns the arithmetic quotient of its operands: ($arg1 div $arg2
).
General rules: see
As a special case, if the types of both $arg1
and $arg2
are
xs:integer
, then the return type is xs:decimal
.
A dynamic error is raised xs:decimal
and xs:integer
operands, if the divisor is (positive or negative) zero.
For xs:float
and xs:double
operands, floating point division
is performed as specified in INF
. A negative number divided by positive zero
returns INF
. Division by negative zero returns INF
and
INF
, respectively. Positive or negative zero divided by positive or
negative zero returns NaN
. Also, INF
or INF
divided by INF
or INF
returns NaN
.
idiv
operator when
applied to two numeric values.Performs an integer division.
General rules: see
If $arg2
is INF
or INF
, and $arg1
is not INF
or INF
, then the result is zero.
Otherwise, subject to limits of precision and overflow/underflow conditions, the result
is the largest (furthest from zero) xs:integer
value $N
such
that the following expression is true
:
The second term in this condition ensures that the result has the correct sign.
The implementation may adopt a different algorithm provided that it is equivalent to
this formulation in all cases where xs:decimal
division.
A dynamic error is raised
A dynamic error is raised NaN
or if $arg1
is INF
or
INF
.
Except in situations involving errors, loss of precision, or overflow/underflow, the
result of $a idiv $b
is the same as ($a div $b) cast as
xs:integer
.
The semantics of this function are different from integer division as defined in programming languages such as Java and C++.
mod
operator when
applied to two numeric values.Returns the remainder resulting from dividing $arg1
, the dividend, by
$arg2
, the divisor.
General rules: see
The operation a mod b
for operands that are xs:integer
or
xs:decimal
, or types derived from them, produces a result such that
(a idiv b)*b+(a mod b)
is equal to a
and the magnitude of
the result is always less than the magnitude of b
. This identity holds even
in the special case that the dividend is the negative integer of largest possible
magnitude for its type and the divisor is 1 (the remainder is 0). It follows from this
rule that the sign of the result is the sign of the dividend.
For xs:float
and xs:double
operands the following rules
apply:
If either operand is NaN
, the result is NaN
.
If the dividend is positive or negative infinity, or the divisor is positive or
negative zero (0), or both, the result is NaN
.
If the dividend is finite and the divisor is an infinity, the result equals the dividend.
If the dividend is positive or negative zero and the divisor is finite, the result is the same as the dividend.
In the remaining cases, where neither positive or negative infinity, nor positive
or negative zero, nor NaN
is involved, the result obeys (a idiv
b)*b+(a mod b)
= a
.
Division is truncating division, analogous to integer division, not
A dynamic error is raised xs:integer
and xs:decimal
operands, if $arg2
is zero.
+
operator
applied to a numeric value.Returns its operand with the sign unchanged: (+ $arg
).
General rules: see
The returned value is equal to $arg
, and is an instance of
xs:integer
, xs:decimal
, xs:double
, or
xs:float
depending on the type of $arg
.
Because function conversion rules are applied in the normal way, the unary
+
operator can be used to force conversion of an untyped node to a
number: the result of +@price
is the same as xs:double(@price)
if the type of @price
is xs:untypedAtomic
.

operator when
applied to a numeric value.Returns its operand with the sign reversed: ( $arg
).
General rules: see
The returned value is an instance of xs:integer
, xs:decimal
,
xs:double
, or xs:float
depending on the type of
$arg
.
For xs:integer
and xs:decimal
arguments, 0
and
0.0
return 0
and 0.0
, respectively. For
xs:float
and xs:double
arguments, NaN
returns
NaN
, 0.0E0
returns 0.0E0
and vice versa.
INF
returns INF
. INF
returns
INF
.
eq
operator when applied to two numeric values, and is also used in defining the
semantics of ne
, le
and ge
.Returns true
if and only if the value of $arg1
is equal to the value of
$arg2
.
General rules: see
For xs:float
and xs:double
values, positive zero and negative
zero compare equal. INF
equals INF
and INF
equals INF
. If $arg1
or $arg2
is
NaN
, the function returns false
.
lt
operator when applied to two numeric values, and is also used in defining the
semantics of le
, gt
, and ge
.Returns true
if and only if $arg1
is numerically less than
$arg2
.
General rules: see
For xs:float
and xs:double
values, positive infinity is
greater than all other nonNaN
values; negative infinity is less than all
other nonNaN
values. Positive and negative zero compare equal.
If $arg1
or $arg2
is
NaN
, the function returns false
.
Returns the absolute value of $value
.
General rules: see
If $value
is negative the function returns $value
, otherwise it
returns $value
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result $value
is an instance of xs:positiveInteger
then the value of
$value
For xs:float
and xs:double
arguments, if the argument is
positive zero or negative zero, then positive zero is returned. If the argument is
positive or negative infinity, positive infinity is returned.
Rounds $value
upwards to a whole number.
General rules: see
The function returns the smallest (closest to negative infinity) number with no
fractional part that is not less than $value
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result $value
is an instance of xs:decimal
then the result xs:integer
.
For xs:float
and xs:double
arguments, if the argument is
positive zero, then positive zero is returned. If the argument is negative zero, then
negative zero is returned. If the argument is less than zero and greater than 1,
negative zero is returned. If the argument is positive or negative infinity,
the value of the argument is returned.
Rounds $value
downwards to a whole number.
General rules: see
The function returns the largest (closest to positive infinity) number with no
fractional part that is not greater than $value
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result $value
is an instance of xs:decimal
then the result xs:integer
.
For xs:float
and xs:double
arguments, if the argument is
positive zero, then positive zero is returned. If the argument is negative zero, then
negative zero is returned. If the argument is positive or negative infinity,
the value of the argument is returned.
Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near.
General rules: see
The function returns the nearest (that is, numerically closest) value to
$value
that is a multiple of ten to the power of minus
$precision
. If two such values are equally near (for example, if the
fractional part in $value
is exactly .5), the function returns the one that
is closest to positive infinity.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result $value
is an instance of xs:decimal
and $precision
is
less than one, then the result xs:integer
.
The singleargument version of this 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
.
3
Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near.
General rules: see
The function returns the nearest (that is, numerically closest) value to
$value
that is a multiple of ten to the power of minus
$precision
. If two such values are equally near (e.g. if the fractional
part in $value
is exactly .500...), the function returns the one whose least
significant digit is even.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result $value
is an instance of xs:decimal
and $precision
is less than one, then the result xs:integer
.
The oneargument form of this function produces the same result as the twoargument form
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
.
Formats an integer according to a given picture string, using the conventions of a given natural language if specified.
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 "4451"
.
This rule is to ensure backwards compatibility.
A primary format token. This is always present and
An optional format modifier.
If the string contains one or more semicolons then the last semicolon is taken as terminating the primary format token, and everything that follows is taken as the format modifier; if the string contains no semicolon then the format modifier is taken to be absent (which is equivalent to supplying a zerolength string).
If a radix is present, then the primary format token must follow the rules for a digitpattern.
The primary format token is classified as one of the following:
A digitpattern made up of optionaldigitsigns, mandatorydigitsigns, and groupingseparatorsigns.
The optionaldigitsign is the character #
.
0
through 9
.
Within the format token, these digits are
interchangeable: a threedigit number may thus be indicated equivalently by
000
, 001
, or 999
.
If the primary format token contains at least one Unicode digit,
then the primary format token is taken
as a decimal digit pattern, and in this case it ^((\p{Nd}#[^\p{N}\p{L}])+?)$
. If it contains a
digit but does not match this pattern, a dynamic error is raised
"x"
or "X"
. If any mandatorydigitsign is uppercase "X"
, then all
mandatorydigitsigns must be uppercase "X"
. The digit family
used in the output comprises the first R characters of the
alphabet 0123456789abcdefghijklmnopqrstuvwxyz
, but using uppercase
letters in place of lowercase if an uppercase "X"
is used
as the mandatorydigitsign.
In this case the primary format token ^(([Xx#][^\p{N}\p{L}])+?)$
a groupingseparatorsign is a nonalphanumeric character, that
is a
If a semicolon is to be used as a grouping separator, then the primary format token as a whole must be followed by another semicolon, to ensure that the grouping separator is not mistaken as a separator between the primary format token and the format modifier.
There
The corresponding output is a number in the specified radix, using this digit family, with at least as many digits as there are mandatorydigitsigns in the format token. Thus:
A format token 1
generates the sequence 0 1
2 ... 10 11 12 ...
A format token 01
(or equivalently,
00
or 99
) generates the sequence 00 01 02 ...
09 10 11 12 ... 99 100 101
A format token of ١
(ArabicIndic digit one) generates the sequence ١
then ٢
then ٣
...
A format token of 16^xx
generates the sequence 00 01 02 03
... 08 09 0a 0b 0c 0d 0e 0f 10 11 ...
A format token of 16^X
generates the sequence 0 1 2 3
... 8 9 A B C D E F 10 11 ...
The groupingseparatorsigns are handled as follows:
The position of grouping separators within the format token, counting backwards from the last digit, indicates the position of grouping separators to appear within the formatted number, and the character used as the groupingseparatorsign within the format token indicates the character to be used as the corresponding grouping separator in the formatted number.
More specifically, the
Grouping separators are defined to be
There is at least one grouping separator.
Every grouping separator is the same character (call it C).
There is a positive integer G (the grouping size) such that:
The position of every grouping separator is an integer multiple of G, and
Every positive integer multiple of G that is less than the number of optionaldigitsigns and mandatorydigitsigns in the primary format token is the position of a grouping separator.
The
If grouping separators are regular, then the grouping separator template contains one pair of the form (n×G, C)
for every positive integer n where G is the grouping size and C is the grouping character.
Otherwise (when grouping separators are not regular), the grouping separator template contains one pair of the form
(P, C)
for every grouping separator found in the primary formatting token, where C is the grouping
separator character and P is its position.
If there are no grouping separators, then the grouping separator template is an empty set.
The number is formatted as follows:
Let S/1 be the result of formatting the supplied number
xs:string
.
Let S/2 be the result of padding S/1 on the left with as many leading zeroes as are needed to ensure that it contains at least as many digits as the number of mandatorydigitsigns in the primary format token.
Let S/3 be the result of replacing all decimal digits (09) in S/2 with the corresponding
digits from the selected digit family.
Let S/4 be the result of inserting grouping separators into S/3: for every (position P, character C) pair in the grouping separator template where P is less than the number of digits in S/3, insert character C into S/3 at position P, counting from the righthand end.
Let S/5 be the result of converting S/4 into ordinal form, if an ordinal modifier is present, as described below.
The result of the function is then S/5.
The format token A
, which generates the sequence A B C ... Z AA
AB AC...
.
The format token a
, which generates the sequence a b c ... z aa
ab ac...
.
The format token i
, which generates the sequence i ii iii iv v
vi vii viii ix x ...
.
The format token I
, which generates the sequence I II III IV V
VI VII VIII IX X ...
.
The format token w
, which generates numbers written as lowercase
words, for example in English, one two three four ...
The format token W
, which generates numbers written as uppercase
words, for example in English, ONE TWO THREE FOUR ...
The format token Ww
, which generates numbers written as titlecase
words, for example in English, One Two Three Four ...
Any other format token, which indicates a numbering sequence in which that token
represents the number 1 (one) (but see the note below).
It is 1
.
In some traditional numbering sequences additional signs are added to denote
that the letters should be interpreted as numbers, for example, in ancient Greek
the
For all format tokens other than a digitpattern, there
①
(circled
digit one, ①) has a range imposed by the Unicode character repertoire — 1
.
The above expansions of numbering sequences for format tokens such as a
and
i
are indicative but not prescriptive. There are various conventions in
use for how alphabetic sequences continue when the alphabet is exhausted, and differing
conventions for how roman numerals are written (for example, IV
versus
IIII
as the representation of the number 4). Sometimes alphabetic
sequences are used that omit letters such as i
and o
. This
specification does not prescribe the detail of any sequence other than those sequences
consisting entirely of decimal digits.
Many numbering sequences are languagesensitive. This applies especially to the sequence
selected by the tokens w
, W
and Ww
. It also
applies to other sequences, for example different languages using the Cyrillic alphabet
use different sequences of characters, each starting with the letter #x410 (Cyrillic
capital letter A). In such cases, the $language
argument specifies which
language conventions are to be used. If the argument is specified, the value
xml:lang
attribute (see
The set of languages for which numbering is supported is $language
argument is absent, or is
set to an empty sequence, or is invalid, or is not a language supported by the
implementation, then the number is formatted using the default language from the dynamic
context.
The format modifier ^([co](\(.+\))?)?[at]?$
. That is, if it is present it must
consist of one or more of the following, in order:
either c
or o
, optionally followed by a sequence of
characters enclosed between parentheses, to indicate cardinal or ordinal numbering
respectively, the default being cardinal numbering
either a
or t
, to indicate alphabetic or traditional
numbering respectively, the default being
If the o
modifier is present, this indicates a request to output ordinal
numbers rather than cardinal numbers. For example, in English, when used with the format
token 1
, this outputs the sequence 1st 2nd 3rd 4th ...
, and
when used with the format token w
outputs the sequence first second
third fourth ...
.
The string of characters between the parentheses, if present, is used to select between
other possible variations of cardinal or ordinal numbering sequences. The interpretation
of this string is
It is
The use of the a
or t
modifier disambiguates between numbering
sequences that use letters. In many languages there are two commonly used numbering
sequences that use letters. One numbering sequence assigns numeric values to letters in
alphabetic sequence, and the other assigns numeric values to each letter in some other
manner traditional in that language. In English, these would correspond to the numbering
sequences specified by the format tokens a
and i
. In some
languages, the first member of each sequence is the same, and so the format token alone
would be ambiguous. In the absence of the a
or t
modifier, the
default is
A dynamic error is raised
Note the careful distinction between conditions that are errors and conditions where fallback occurs. The principle is that an error in the syntax of the format picture will be reported by all processors, while a construct that is recognized by some implementations but not others will never result in an error, but will instead cause a fallback representation of the integer to be used.
The following notes apply when a digitpattern is used:
If groupingseparatorsigns
appear at regular intervals within the format token, then the sequence is extrapolated to
the left, so grouping separators will be used in the formatted number at every
multiple of N. For example, if the format token is 0'000
then the number one million will be formatted as 1'000'000
, while the
number fifteen will be formatted as 0'015
.
The only purpose of optionaldigitsigns is to mark the position of
groupingseparatorsigns. For example, if the format token is
#'##0
then the number one million will be formatted as
1'000'000
, while the number fifteen will be formatted as
15
. A grouping separator is included in the formatted number only
if there is a digit to its left, which will only be the case if either (a) the
number is large enough to require that digit, or (b) the number of
mandatorydigitsigns in the format token requires insignificant
leading zeros to be present.
Grouping separators are (365)1239876
. In general they are not
suitable for such purposes because (a) only single characters are allowed, and (b) they
cannot appear at the beginning or end of the number.
Numbers will never be truncated. Given the digitpattern
01
, the number three hundred will be output as 300
,
despite the absence of any optionaldigitsign.
The following notes apply when ordinal numbering is selected using the o
modifier.
In some languages, the form of numbers (especially ordinal numbers) varies depending
on the grammatical context: they may have different genders and may decline with the
noun that they qualify. In such cases the string appearing in parentheses after the
letter c
or o
may be used to indicate the variation of the
cardinal or ordinal number required.
The way in which the variation is indicated will depend on the conventions of the language.
For inflected languages that vary the ending of the word, the approach recommended
in the previous version of this specification was to indicate the required ending,
preceded by a hyphen: for example in German, appropriate values might be
o(e)
, o(er)
, o(es)
, o(en)
.
Another approach, which might usefully be adopted by an implementation based on the
opensource ICU localization library o(%spelloutordinalmasculine)
, or c(%spelloutcardinalyear)
.
The following notes apply when the primary format token is neither a digitpattern nor one of the seven other defined format tokens (A, a, i, I, w, W, Ww), but is an arbitrary token representing the number 1:
Unexpected results may occur for traditional numbering. For example, in an
implementation that supports traditional numbering system in Greek, the example
formatinteger(19, "α;t")
might return δπιιιι
or
ιθ
, depending upon whether the ancient acrophonic or late antique
alphabetic system is supported.
Unexpected results may also occur for alphabetic numbering. For example, in an
implementation that supports alphabetic numbering system in Greek, someone
writing formatinteger(19, "α;a")
might expect the nineteenth Greek
letter, #x3C4 τ
, but the implementation might return the eighteenth one,
#x3C3 σ
, because the latter is the nineteenth item in the sequence of
lowercase Greek letters in Unicode (the sequence is interrupted because of the final
form of the sigma, #x3C2 ς). Because Greek never had a final capital sigma,
Unicode has marked #x3A2, the eighteenth codepoint in the sequence of Greek capital
letters, as reserved, to ensure that every Greek uppercase letter is always 32 codepoints
less than its lowercase counterpart. Therefore, someone writing
formatinteger(18, "Α;a")
might expect the eighteenth Greek capital letter,
#x3A3 Σ
, but an implementation might return #x3a2, the eighteenth position
in the sequence of Greek capital letters, but unassigned to any character.
formatinteger(123, 'w')
might return "one hundred and
twentythree"
Ordinal numbering in Italian: The specification "1;o(º)"
with $language
equal to
it
, if supported, should produce the sequence:
The specification "Ww;o"
with $language
equal to
it
, if supported, should produce the sequence:
formatinteger(14, 'Ww;o(e)', 'de')
might return
"Vierzehnte"
Returns a string containing a number formatted according to a given picture string, taking account of decimal formats specified in the static context.
The effect of the twoargument form of the function is equivalent to calling the threeargument form with an empty sequence as the value of the third argument.
The function formats $value
as a string using the $picture
argument and the decimalformat named by the
$decimalformatname
argument, or the unnamed decimalformat, if there
is no $decimalformatname
argument. The syntax of the picture string is
described in
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
.
The value of $decimalformatname
, if present and nonempty,
xs:QName
,
orEQName
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 decimal format that is used is the decimal format in the static context whose name
matches $decimalformatname
if supplied, or the unnamed decimal format in
the static context otherwise.
The evaluation of the fn:formatnumber
function takes place in two
phases, an analysis phase described in
The analysis phase takes as its inputs the
The result of the function is the formatted string representation of the supplied number.
A dynamic error is raised $decimalformatname
argument is supplied as an xs:string
that isURIQualifiedName
, or if it uses a prefix that is not found in the
statically known namespaces, or if the static context does not contain a declaration of
a decimalformat with a matching expanded QName. If the processor is able to detect the
error statically (for example, when the argument is supplied as a string literal), then
the processor
A 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.
The following examples assume a default decimal format in which the chosen digits are
the ASCII digits 09, the decimal separator is .
, the grouping separator is ,
,
the minussign is 
, and the percentsign is %
.
The following example assumes the existence of a decimal format named ch
in which
the grouping separator is ʹ
and the decimal separator is
·
:
The following examples assume that the exponent separator is
in decimal format fortran
is E
:
xs:QName
,
as an alternative to supplying a lexical QName as an instance of xs:string
.Converts a string to an integer, recognizing any radix in the range 2 to 36.
The supplied $radix
must be in the range 2 to 36 inclusive.
The string $value
is preprocessed by stripping all whitespace characters (including internal whitespace)
and underscore characters.
After this process, the supplied value
must consist of an optional sign (+
or 
)
followed by a sequence of one or more generalized digits drawn from the first $radix
characters
in the alphabet 0123456789abcdefghijklmnopqrstuvwxyz
; uppercase alphabetics
AZ
may be used in place of their lowercase equivalents.
The value of a generalized digit corresponds to its position in this alphabet. More formally, in nonerror cases the result of the function is given by the XQuery expression:
A dynamic error is raised $radix
is not in the range 2 to 36.
A dynamic error is raised $value
is a zerolength string,
or if it contains a character
that is not among the first $radix
characters in the
alphabet 0123456789abcdefghijklmnopqrstuvwxyz
, or the
uppercase equivalent of such a character.
A dynamic error is raised xs:integer
.
When $radix
takes its default value of 10
,
the function delivers the same result as casting $value
(after removal of whitespace and underscores) to xs:integer
.
If underscores or whitespace in the input need to be rejected, then
the string should first be validated, perhaps using fn:matches
.
If other characters may legitimately appear in the input, for example
a leading 0x
, then this must first be removed by preprocessing the input.
If the input uses a different family of digits, then the value should first
be converted to the required digits using fn:translate
.
A string in the lexical space of xs:hexBinary
will always
be an acceptable input, provided it is not too long. So, for example, the expression
"1DE=" => xs:base64Binary() => xs:hexBinary() => xs:string() => parseinteger(16)
can be used to convert the Base 64 value 1DE=
to the integer 54321, via the
hexadecimal string D431
.
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.
Digitbased numeration systems comparable to the Arabic numbers 0 through 9 can be parsed via translation.
Returns an approximation to the mathematical constant π.
This function returns the xs:double
value whose lexical representation is
3.141592653589793e0
The expression 60 * (math:pi() div 180)
converts an angle of 60 degrees
to radians.
Returns the value of e^{x} where x is the argument value.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the mathematical constant e raised to the power of
$value
, as defined in the exp
function applied to 64bit binary floating point values.
The treatment of overflow and underflow is defined in
Returns the value of 10
^{x}, where x is the supplied argument value.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is ten raised to the power of $value
, as defined in the
exp10
function applied
to 64bit binary floating point values.
The treatment of overflow and underflow is defined in
Returns the natural logarithm of the argument.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the natural logarithm of $value
, as defined in the
log
function applied
to 64bit binary floating point values.
The treatment of divideByZero
and invalidOperation
exceptions
is defined in INF
, and if it is negative, the result is NaN
Returns the baseten logarithm of the argument.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the base10 logarithm of $value
, as defined in the
log10
function applied
to 64bit binary floating point values.
The treatment of divideByZero
and invalidOperation
exceptions
is defined in INF
, and if it is negative, the result is NaN
Returns the nonnegative square root of the argument.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the mathematical nonnegative square root of $value
as defined in the squareRoot
function applied to 64bit binary floating point values.
The treatment of the invalidOperation
exception is defined in NaN
.
If $value
is positive or negative zero, positive infinity, or
NaN
, then the result is $value
. (Negative zero is the only
case where the result can have negative sign)
Returns the result of raising the first argument to the power of the second.
If $x
is the empty sequence, the function returns the empty sequence.
If $y
is an instance of xs:integer
, the result is
$x
raised to the power of $y
as defined in the pown
function applied to a
64bit binary floating point value and an integer.
Otherwise $y
is converted to an xs:double
by numeric
promotion, and the result is $x
raised to the power of
$y
as defined in the pow
function applied to two 64bit binary floating point values.
The treatment of the divideByZero
and invalidOperation
exceptions is defined in
Returns the sine of the argument. The argument is an angle in radians.
If $radians
is the empty sequence, the function returns the empty
sequence.
Otherwise the result is the sine of $radians
(which is treated as an angle in
radians) as defined in the sin
function applied to 64bit binary floating point values.
The treatment of the invalidOperation
and underflow
exceptions
is defined in
If $radians
is positive or negative zero, the result is
$radians
.
If $radians
is positive or negative infinity, or NaN
,
then the result is NaN
.
Otherwise the result is always in the range 1.0e0 to +1.0e0
Returns the cosine of the argument. The argument is an angle in radians.
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 $
θ (which is treated as an angle in
radians) as defined in the cos
function applied to 64bit binary floating point values.
The treatment of the invalidOperation
exception is defined in
If $radians
is positive or negative zero, the result is
$radians
.
If $radians
is positive or negative infinity, or NaN
,
then the result is NaN
.
Otherwise the result is always in the range 1.0e0 to +1.0e0
Returns the tangent of the argument. The argument is an angle in radians.
If $radians
is the empty sequence, the function returns the empty
sequence.
Otherwise the result is the tangent of $radians
(which is treated as an angle
in radians) as defined in the tan
function applied to 64bit binary floating point values.
The treatment of the invalidOperation
and underflow
exceptions
is defined in
If $radians
is positive or negative infinity, or NaN
,
then the result is NaN
.
math:pi() div 2
returns an approximation, the result of math:tan(math:pi() div 2)
will be a large
but finite number.math:pi() div 2
returns an approximation, the result of math:tan(math:pi() div 2)
will be a large
but finite negative number.Returns the arc sine of the argument.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the arc sine of $value
as defined in the asin
function applied to 64bit binary floating point values.
The result is in the range π/2 to +π/2 radians.
The treatment of the invalidOperation
and underflow
exceptions
is defined in
If $value
is positive or negative zero, the result is $value
.
If $value
is NaN
, or if its absolute value is greater than one,
then the result is NaN
.
In other cases the result is an xs:double
value representing an angle
θ in radians in the range π/2 <=
θ <= +
π/2
.
Returns the arc cosine of the argument.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the arc cosine of $value
, as defined in the acos
function applied to 64bit binary floating point values.
The result is in the range zero to +π radians.
The treatment of the invalidOperation
exception is defined in
If $value
is NaN
, or if its absolute value is greater than one,
then the result is NaN
.
In other cases the result is an xs:double
value representing an angle
θ in radians in the range 0 <=
θ <=
+
π.
Returns the arc tangent of the argument.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the arc tangent of $value
, as defined
in the atan
function applied to 64bit binary floating point values.
The result is in the range π/2
to +π/2 radians.
The treatment of the underflow
exception is defined in
If $value
is positive or negative zero, the result is $value
.
If $value
is NaN
then the result is NaN
.
In other cases the result is an xs:double
value representing an angle
θ in radians in the range π/2 <=
θ <= +
π/2
.
Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive xaxis.
The result is the value of atan2(y, x)
as defined in the atan2
function applied to
64bit binary floating point values. The result is in the range π
to +π radians.
The treatment of the underflow
exception is defined in
If either argument is NaN
then the result is NaN
.
If $x
is positive, then the value of atan2($y,
$x)
is atan($y div $x)
.
If $x
is negative, then:
If $y
is positive, then the value of atan2($y, $x)
is
atan($y div $x) +
π.
If $y
is negative, then the value of atan2($y, $x)
is
atan($y div $x) 
π.
Some results for special values of the arguments are shown in the examples below.
Returns an xs:string
whose characters have supplied
The function returns the string made up from the $values
. This will be the zerolength string if $values
is the empty sequence.
A dynamic error is raised $values
is not a
Returns the sequence of xs:string
value.
The function returns a sequence of integers, each integer being the Unicode $value
.
If $value
is a zerolength string or the empty sequence, the function returns
the empty sequence.
Returns 1
, 0
, or 1
,
depending on whether $value1
collates before,
equal to, or after $value2
according to the rules of a selected
collation.
Returns 1
, 0
, or 1
,
depending on whether $value1
is
respectively less than, equal to, or greater than $value2
,
according to the rules of the collation that is used.
The collation used by this function is determined according to the rules in
If either $value1
or $value2
is the empty sequence,
the function returns the empty sequence.
This function, eq
, ne
,
gt
, lt
, le
and ge
operators on xs:string
values.
ssand the (German) character
ß(
sharps). Otherwise, the returned value depends on the semantics of the default collation.
ssand the (German) character
ß(
sharps).
ssand the (German) character
ß(
sharps) with less strength than the differences between the base characters, such as the final
n.
Returns true
if two strings are equal, considered codepointbycodepoint.
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.

operator.Returns the concatenation of the string values of the arguments.
This function accepts zero or more arguments, each declared with the required type
xs:anyAtomicType*
. The value $v
supplied for each argument
is first reduced to a single string as follows:
If XPath 1.0 compatibility mode is set to true in the static context of the
function call, then the result of xs:string($v[1])
.
Otherwise, the result of fn:stringjoin($v)
.
The resulting sequence of strings (one for each supplied argument) is then reduced
to a single string by applying fn:stringjoin#1
to the sequence.
The fn:concat
function is specified to allow zero or more arguments, which
are concatenated together. This is the only function specified in this document that
allows a variable number of arguments. This capability is retained for compatibility
with
As mentioned in fn:concat
. If a normalized result is required,
fn:normalizeunicode
can be applied to the xs:string
returned by fn:concat
. The following XQuery:
where the ?
represents either the actual Unicode character COMBINING DIARESIS
(Unicode codepoint U+0308
) or ̈
, will return:
"I plan to go to Mu?nchen in September"
where the ?
represents either the actual Unicode character COMBINING DIARESIS
(Unicode codepoint U+0308
) or ̈
.
It is worth noting that the returned value is not normalized in NFC; however, it is normalized in NFD.
However, the following XQuery:
where ?
represents either the actual Unicode character COMBINING DIARESIS
(Unicode codepoint U+0308
) or ̈
, will return:
"I plan to go to München in September"
This returned result is normalized in NFC.
Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items.
The effect of calling the singleargument version of this function is the same as
calling the twoargument version with $separator
set to a zerolength
string.
The function returns an xs:string
created by $values
to an xs:string
,
and then concatenating the result strings in order,$separator
as a
separator between adjacent strings. If $separator
is the zerolength
string, then the items in $values
are concatenated without a separator.
If $values
is the empty sequence, the function returns the
zerolength string.
Returns the part of $value
beginning at the position
indicated by $start
and continuing for the number of $length
.
If $value
is the empty sequence, the function returns
the zerolength string.
Otherwise, the function returns a string comprising those $value
whose index position (counting
from one) is greater than or equal to $start
(rounded to an
integer), and (if $length
is specified
$start
and $length
(both rounded to integers).
The characters returned do not extend beyond $value
. If
$start
is zero or negative, only those characters in positions greater
than zero are returned.
More specifically, the three argument version of the function returns the characters in
$value
whose position $p
satisfies:
fn:round($start) <= $p and $p < fn:round($start) + fn:round($length)
The two argument version of the function assumes that $length
is infinite
and thus returns the $value
whose position $p
satisfies:
fn:round($start) <= $p
In the above computations, the rules for op:numericlessthan
The first character of a string is located at position 1, not position 0.
The second and third arguments allow xs:double
values (rather than
requiring xs:integer
) in order to achieve compatibility with XPath 1.0.
A surrogate pair counts as one character, not two.
The consequences of supplying values such as NaN
or positive or negative
infinity for the $start
or $length
arguments follow from the
above rules, and are not always intuitive.
$sourceString
are selected.
0 div 0E0
returns NaN
, and
NaN
compared to any other number returns false
, no
characters are selected.INF
are selected.INF + INF
is NaN
, no
characters are selected.
Returns the number of
The function returns an xs:integer
equal to the length in $value
.
Calling the zeroargument version of the function is equivalent to calling
fn:stringlength(fn:string(.))
.
If $value
is the empty sequence, the function returns the
xs:integer
value 0
.
If $value
is not specified and the context item is
Unlike some programming languages, a
There are situations where fn:stringlength()
has a different effect
from fn:stringlength(.)
. For example, if the context item
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
).
Returns $value
with leading and trailing whitespace removed, and
sequences of internal whitespace reduced to a single space character.
If $value
is the empty sequence, the function returns the
zerolength string.
The function returns a string constructed by stripping leading and trailing whitespace
from $value
, and replacing sequences of one or more adjacent
whitespace characters with a single space, #x20
.
The whitespace characters are defined in the metasymbol S (Production 3) of
If no argument is supplied, then $value
defaults to the string value
(calculated using fn:string
) of the context item (.
).
If no argument is supplied and the context item is
The definition of whitespace is unchanged in
S ::= (#x20  #x9  #xD  #xA)+
Returns $value
after applying Unicode normalization.
If $value
is the empty sequence, the function returns the
zerolength string.
If the singleargument version of the function is used, the result is the same as
calling the twoargument version with $form
set to the string
"NFC"
.
Otherwise, the function returns $value
normalized according to
the rules of the normalization form identified by the value of
$form
.
The effective value of $form
is the value of the expression
fn:uppercase(fn:normalizespace($form))
.
If the effective value of $form
is NFC
,
then the function returns $value
converted to Unicode
Normalization Form C (NFC).
If the effective value of $form
is NFD
,
then the function returns $value
converted to Unicode
Normalization Form D (NFD).
If the effective value of $form
is NFKC
,
then the function returns $value
in Unicode Normalization
Form KC (NFKC).
If the effective value of $form
is NFKD
,
then the function returns $value
converted to Unicode
Normalization Form KD (NFKD).
If the effective value of $form
is
FULLYNORMALIZED
, then the function returns
$value
converted to fully normalized form.
If the effective value of $form
is the zerolength
string, no normalization is performed and $value
is returned.
Normalization forms NFC, NFD, NFKC, and NFKD, and the algorithms to be used for
converting a string to each of these forms, are defined in
The motivation for normalization form FULLYNORMALIZED is explained in
A string is
A composing character is a character that is one or both of the following:
the second character in the canonical decomposition mapping of some
character that is not listed in the Composition Exclusion Table defined in
of nonzero canonical combining class (as defined in
A string is converted to FULLYNORMALIZED form as follows:
if the first character in the string is a composing character, prepend a single space (x20);
convert the resulting string to normalization form NFC.
Conforming implementations NFC
and
NFD
, NFKC
, NFKD
, and
FULLYNORMALIZED
. They
It is fn:normalizeunicode
function leaves such codepoints unchanged. If the
implementation supports the requested normalization form then it
A $form
argument is not one of the values
supported by the implementation.
Converts a string to upper case.
If $value
is the empty sequence, the zerolength string is
returned.
Otherwise, the function returns $value
after translating every
Case mappings may change the length of a string. In general, the
fn:uppercase
and fn:lowercase
functions are not inverses
of each other: fn:lowercase(fn:uppercase($s))
is not guaranteed to
return $s
, nor is fn:uppercase(fn:lowercase($s))
. The
Latin small letter dotless i (ı, U+0131, used in Turkish) is perhaps the most prominent
lowercase letter which will not roundtrip. The Latin capital letter i with dot above (İ, U+0130)
is the most prominent uppercase letter which will not round trip; there are others,
such as Latin capital letter sharp S (ẞ, U+1E9E), which was introduced in Unicode 5.1.
These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.
Because the function is not sensitive to locale, results will not always match user
expectations. In Quebec, for example, the standard uppercase equivalent of è
is È
,
while in metropolitan France it is more commonly E
; only one of these is supported by
the functions as defined.
Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.
Converts a string to lower case.
If t$value
is the empty sequence, the zerolength string is
returned.
Otherwise, the function returns $value
after translating every
Case mappings may change the length of a string. In general, the
fn:uppercase
and fn:lowercase
functions are not inverses
of each other: fn:lowercase(fn:uppercase($s))
is not guaranteed to
return $s
, nor is fn:uppercase(fn:lowercase($s))
. The
Latin small letter dotless i (ı, U+0131, used in Turkish) is perhaps the most prominent
lowercase letter which will not roundtrip. The Latin capital letter i with dot above (İ, U+0130)
is the most prominent uppercase letter which will not round trip; there are others,
such as Latin capital letter sharp S (ẞ, U+1E9E), which was introduced in Unicode 5.1.
These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.
Because the function is not sensitive to locale, results will not always match user
expectations. In Quebec, for example, the standard uppercase equivalent of è
is È
,
while in metropolitan France it is more commonly E
; only one of these is supported by
the functions as defined.
Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.
Returns $value
modified by replacing or removing individual
characters.
If $value
is the empty sequence, the function returns the
zerolength string.
Otherwise, the function returns a result string constructed by processing each $value
, in order,
according to the following rules:
If the character does not appear in $replace
then it
is added to the result string unchanged.
If the character first appears in $replace
at some
position $with
is
$with
is added to the result string.
If the character first appears in $replace
at some
position $with
is less than
If $replace
is the zerolength string then the function returns
$value
unchanged.
If a character occurs more than once in $replace
, then the first
occurrence determines the action taken.
If $with
is longer than $replace
, the excess
characters are ignored.
Encodes reserved characters in a string that is intended to be used in the path segment of a URI.
If $value
is the empty sequence, the function returns the zerolength
string.
This function applies the URI escaping rules defined in section 2 of xs:string
supplied as $value
. The
effect of the function is to escape reserved characters. Each such character in the
string is replaced with its percentencoded form as described in
Since
All characters are escaped except those identified as “unreserved” by A
to Z
,
the digits 0
to 9
, HYPHENMINUS (
),
LOW LINE (_
), FULL STOP (.
), and TILDE (~
).
This function escapes URI delimiters and therefore cannot be used indiscriminately to encode “invalid” characters in a path segment.
This function is invertible but not idempotent. This is because a string containing a
percent character will be modified by applying the function: for example
100%
becomes 100%25
, while 100%25
becomes
100%2525
.
Decodes URIescaped characters in a string.
This function returns the original representation of a URIescaped string.
If $value
is the empty sequence, the function returns the zerolength
string.
Otherwise, the value is first converted to an sequence of octets. Each plus sign
(+
) is replaced with the octet representing a space character
(x20
), and any substring that matches the regular expression
%[afAF09][afAF09]
is replaced with an octet for the twodigit
hexadecimal number that follows the percent sign. Characters that are not part of
such a substring are replaced with the octets of their UTF8 encoding.
For example, "A%42+C"
results in the octets x41
,
x42
, x20
, x43
, and "💡"
yields
xF0
, x9F
, x92
, and xA1
.
If %
is followed by up to two characters that are no hexadecimal digits,
these characters are replaced by octets xEF
, xBF
,
and xBD
, that is, the UTF8 encoding of the Unicode replacement character
(0xFFFD
). For example, the incomplete or invalid percentencoded strings
"%"
, "%X"
, and "%AX"
are all replaced with
these octets. For the string "%1X!"
, the octets xEF
,
xBF
, xBD
, and x21
are returned.
Next, the resulting octets are interpreted as UTF8. For example,
x41
, x42
, x20
, and x43
becomes "AB C"
, and xF0
, x9F
,
x92
, and xA1
becomes "💡"
.
If an invalid UTF8 octet sequence is encountered, the octets that have successfully been parsed are replaced with a Unicode replacement character. Examples:
The single octet xF0
is converted to "�"
.
The octets xF0
, x9F
, x92
, and
x41
are converted to "�A"
:
The bit pattern of the first octet indicates that the UTF8 character comprises
four octets. As the fourth octet is invalid, a Unicode replacement character is
added for the first three octets, and the fourth (invalid) octet is parsed as a
new character.
Similarly, the octets xF0
, xF0
, x9F
,
x92
, and xA1
are converted to "�💡"
:
The second octet is invalid, but it becomes valid when being parsed as the
first octet of the remaining UTF8 sequence.
Similarly, a UTF8 octet sequence that represents a codepoint that is not a
valid XML character is replaced with a Unicode replacement character.
For example, x00
becomes "�"
.
Converts a string containing an IRI into a URI according to the rules of
If $value
is the empty sequence, the function returns the zerolength
string.
Otherwise, the function converts $value
into a URI according to
the rules given in Section 3.1 of $value
contains a character
that is invalid in an IRI, such as the space character (see note below), the invalid
character is replaced by its percentencoded form as described in
Since
The function is idempotent but not invertible. Both the inputs My Documents
and My%20Documents
will be converted to the output
My%20Documents
.
This function does not check whether $iri
is a valid IRI. It treats it as
an
The following printable ASCII characters are invalid in an IRI: <
, >
,
"
,
, {
, }
, 
,
\
, ^
, and `
. Since these
characters should not appear in an IRI, if they do appear in $iri
they will
be percentencoded. In addition, characters outside the range x20x7E will be
percentencoded because they are invalid in a URI.
Since this function does not escape the PERCENT SIGN %
and this character is not
allowed in data within a URI, users wishing to convert character strings (such as file
names) that include %
to a URI should manually escape %
by replacing it with %25
.
Escapes a URI in the same way that HTML user agents handle attribute values expected to contain URIs.
If $value
is the empty sequence, the function returns the zerolength
string.
Otherwise, the function escapes all $uri
to be escaped is replaced by an escape sequence, which is
formed by encoding the character as a sequence of octets in UTF8, and then representing
each of these octets in the form %HH, where HH is the hexadecimal representation of the
octet. This function must always generate hexadecimal values using the uppercase
letters AF.
The behavior of this function corresponds to the recommended handling of nonASCII
characters in URI attribute values as described in
Returns true
if the string $value
contains $substring
as a
substring, taking collations into account.
If $value
or $substring
is the empty sequence, or
contains only ignorable collation units, it is interpreted as the zerolength
string.
If $substring
is the zerolength string, then the function returns
true
.
If $value
is the zerolength string, the function returns
false
.
The collation used by this function is determined according to the rules in
The function returns an xs:boolean
indicating whether or not
$value
contains (at the beginning, at the end, or anywhere within) at
least one sequence of collation units that provides a $substring
, according to the collation that is
used.
A
The collation used in these examples, http://example.com/CollationA
is a
collation in which both 
and *
are ignorable collation units.
“Ignorable collation unit” is equivalent to “ignorable collation element” in
Returns true
if the string $value
contains $substring
as a leading
substring, taking collations into account.
If $value
or $substring
is the empty sequence, or
contains only ignorable collation units, it is interpreted as the zerolength
string.
If $substring
is the zerolength string, then the function returns
true
. If $value
is the zerolength string and
$substring
is not the zerolength string, then the function returns
false
.
The collation used by this function is determined according to the rules in
The function returns an xs:boolean
indicating whether or not
$value
starts with a sequence of collation units that provides a
$substring
according to the
collation that is used.
A
The collation used in these examples, http://example.com/CollationA
is a
collation in which both 
and *
are ignorable collation units.
“Ignorable collation unit” is equivalent to “ignorable collation element” in
Returns true
if the string $value
contains $substring
as a trailing
substring, taking collations into account.
If $value
or $substring
is the empty sequence, or
contains only ignorable collation units, it is interpreted as the zerolength
string.
If $substring
is the zerolength string, then the function returns
true
. If $value
is the zerolength string and
the value of $substring
is not the zerolength string, then the function returns
false
.
The collation used by this function is determined according to the rules in
The function returns an xs:boolean
indicating whether or not
$value
ends with a sequence of collation units that provides a
$substring
according to the
collation that is used.
A
The collation used in these examples, http://example.com/CollationA
is a
collation in which both 
and *
are ignorable collation units.
“Ignorable collation unit” is equivalent to “ignorable collation element” in
Returns the part of $value
that precedes the first occurrence of
$substring
, taking collations into account.
If $value
or $substring
is the empty sequence, or
contains only ignorable collation units, it is interpreted as the zerolength
string.
If $substring
is the zerolength string, then the function returns
the zerolength string.
If $value
does not contain a string that is equal to
$substring
, then the function returns the zerolength string.
The collation used by this function is determined according to the rules in
The function returns the substring of $value
that precedes in
$value
the first occurrence of a sequence of collation units
that provides a $substring
according to the collation that is used.
A
The collation used in these examples, http://example.com/CollationA
is a
collation in which both 
and *
are ignorable collation units.
“Ignorable collation unit” is equivalent to “ignorable collation element” in
Returns the part of $value
that follows the first occurrence of
$substring
, taking collations into account.
If $value
or $substring
is the empty sequence, or
contains only ignorable collation units, it is interpreted as the zerolength
string.
If $substring
is the zerolength string, then the function returns
the value of $value
.
If $value
does not contain a string that is equal to
$substring
, then the function returns the zerolength string.
The collation used by this function is determined according to the rules in
The function returns the substring of $value
that follows in
$value
the first occurrence of a sequence of collation units
that provides a $substring
according to the collation that is used.
A dynamic error
The collation used in these examples, http://example.com/CollationA
is a
collation in which both 
and *
are ignorable collation units.
“Ignorable collation unit” is equivalent to “ignorable collation element” in
Returns true
if the supplied string matches a given regular expression.
If $value
is the empty sequence, it is interpreted as the zerolength
string.
If the $flags
argument is omitted or if it is an empty sequence,
the effect is the same as setting $flags
to a zerolength string.
Flags are defined in
The function returns true
if $value
or some substring of
$value
matches the regular expression supplied as $pattern
,
and the associated $flags
. Otherwise, the function returns false
.
A dynamic error is raised $pattern
is invalid according to the rules described in
A dynamic error is raised $flags
is invalid according to the rules described in
Unless the metacharacters ^
and $
are used as anchors, the
string is considered to match the pattern if any substring matches the pattern. But if
anchors are used, the anchors must match the start/end of the string (in string mode),
or the start/end of a line (in multiline mode).
This is different from the behavior of patterns in
Regular expression matching is defined on the basis of Unicode code points; it takes no account of collations.
Given the source document:
the following function calls produce the following results, with the
poem
element as the context node:
Returns a string produced from the input string by replacing any substrings that match a
given regular expression with a supplied replacement string
If $value
is the empty sequence, it is interpreted as the zerolength
string.
The replacement string is determined by the values of the
$replacement
and/or $action
arguments:
If the $action
argument is present and is not an empty sequence,
the string is obtained by calling the $action
function.
The first argument to the $action
function is the string to be replaced,
provided as xs:untypedAtomic
.
The second argument to the $action
function provides the captured
substrings as an xs:untypedAtomic
sequence.
The Nth
item in this sequence is the substring captured by
the Nth
parenthesized subexpression. If the
Nth
parenthesized subexpression was not matched, the Nth
item
will be the zerolength string.
Note that the rules for function coercion mean that the function actually
supplied for the $action
parameter may be an arity1 function: the
second argument does not need to be declared if it is not used.
The replacement string is obtained by invoking fn:string
for the result of the function call.
Otherwise, if the $replacement
argument is present and is not
an empty sequence, the replacement string is the value of $replacement
.
Otherwise, the replacement string is the zerolength string.
If the $flags
argument is omitted or if it is an empty sequence,
the effect is the same as setting $flags
to a zerolength string.
Flags are defined in
The function returns the xs:string
that is obtained by replacing each
nonoverlapping substring of $value
that matches the given
$pattern
with
If two overlapping substrings of $value
both match the
$pattern
, then only the first one (that is, the one whose first $value
string) is
replaced.
If the q
flag is present, or if the replacement string was obtained
by calling the $action
function, then the replacement string is used
Otherwise, within the replacement string, a variable $N
may
be used to refer to the substring captured by the Nth parenthesized subexpression in
the regular expression. For each match of the pattern, these variables are assigned the
value of the content matched by the relevant subexpression, and the modified
replacement string is then substituted for the $value
that matched the pattern.
$0
refers to the substring captured by the regular expression as a
whole.
More specifically, the rules are as follows, where S
is the number of
parenthesized subexpressions in the regular expression, and N
is the
decimal number formed by taking all the digits that consecutively follow the
$
character:
If N
=0
, then the variable is replaced by the substring
matched by the regular expression as a whole.
If 1
<=N
<=S
, then the variable is
replaced by the substring captured by the Nth parenthesized subexpression. If the
Nth
parenthesized subexpression was not matched, then the
variable is replaced by the zerolength string.
If S
<N
<=9
, then the variable is
replaced by the zerolength string.
Otherwise (if N
>S
and
N
>9
), the last digit of N
is taken to
be a literal character to be included “as is” in the replacement string, and the
rules are reapplied using the number N
formed by stripping off this
last digit.
For example, if the replacement string is
"$23"
and there are 5 substrings, the result contains the value of the substring that
matches the second subexpression, followed by the digit
3
.
Unless the q
flag is used, a literal $
character within the
replacement string must be written as \$
, and a literal \
character must be written as \\
.
If two alternatives within the pattern both match at the same position in the
$input
, then the match that is chosen is the one matched by the first
alternative. For example:
A dynamic error is raised $pattern
is invalid according to the rules described in section
A dynamic error is raised $flags
is invalid according to the rules described in section
A dynamic error is raised fn:matches("", $pattern,
$flags)
returns true
. It is not an error, however, if a captured
substring is zerolength.
In the absence of the q
flag,
a dynamic error is raised $replacement
contains a dollar sign ($
) character that is not
immediately followed by a digit 09
and not immediately preceded by a
backslash (\
).
In the absence of the q
flag,
a dynamic error is raised $replacement
contains a backslash (\
) character that is not part of a
\\
pair, unless it is immediately followed by a dollar sign ($
)
character.
A dynamic error is raised $replacement
and $action
arguments are supplied, and neither is an empty sequence.
If the input string contains no substring that matches the regular expression, the result of the function is a single string identical to the input string.
d
is replaced.The expression fn:replace("abracadabra", ".*?", "$1")
raises an error,
because the pattern matches the zerolength string
$action
argument as proposed here has
not been reviewed by the working group.Returns a sequence of strings constructed by splitting the input wherever a separator is found; the separator is any substring that matches a given regular expression.
The following rules apply when the $pattern
argument is omitted,
or is set to an empty sequence:
The function splits the supplied string at whitespace boundaries.
More specifically, calling fn:tokenize($value)
fn:tokenize($value, ())
fn:tokenize(fn:normalizespace($value), ' '))
where the second argument
is a single space character (x20).
The $flags
argument is ignored.
The following rules apply when the $pattern
argument is supplied as a single string:
If the $flags
argument is omitted or if it is an empty sequence,
the effect is the same as setting $flags
to a zerolength string.
Flags are defined in
If $value
is the empty sequence, or if $value
is the
zerolength string, the function returns the empty sequence.
The function returns a sequence of strings formed by breaking the $value
string into a sequence of strings, treating any substring that matches
$pattern
as a separator. The separators themselves are not returned.
If a separator occurs at the start of the $value
string, the result
sequence will start with a zerolength string. Similarly, zerolength strings will also occur in
the result sequence if a separator occurs at the end of the $value
string,
or if two adjacent substrings match the supplied $pattern
.
If two alternatives within the supplied $pattern
both match at the same
position in the $value
string, then the match that is chosen is the first.
For example:
A dynamic error is raised $pattern
is invalid according to the rules described in section
A dynamic error is raised $flags
is invalid according to the rules described in section
A dynamic error is raised $pattern
matches a zerolength string, that is, if fn:matches("",
$pattern, $flags)
returns true
.
If the input string is not zero length, and no separators are found in the input string, the result of the function is a single string identical to the input string.
The oneargument form of the function has a similar effect to
the twoargument form with \s+
as the separator pattern, except that the oneargument
form strips leading and trailing whitespace, whereas the twoargument form delivers an extra
zerolength token if leading or trailing whitespace is present.
The function returns no information about the separators that were found
in the string. If this information is required, the fn:analyzestring
function
can be used instead.
The separator used by the oneargument form of the function is any sequence
of tab (x09
), newline (x0A
), carriage return
(x0D
) or space (x20
) characters. This is the same as the
separator recognized by listvalued attributes as defined in XSD.
It is not the same as the separator recognized by listvalued attributes in HTML5,
which also treats formfeed (x0C
) as whitespace. If it is necessary
to treat formfeed as a separator, an explicit separator pattern should be used.
fn:tokenize("abba", ".?")
raises the dynamic error
Analyzes a string using a regular expression, returning an XML structure that identifies which parts of the input string matched or failed to match the regular expression, and in the case of matched substrings, which substrings matched each capturing group in the regular expression.
If the $flags
argument is omitted or if it is an empty sequence,
the effect is the same as setting $flags
to a zerolength string.
Flags are defined in
If $value
is the empty sequence the function behaves as if
$value
were the zerolength string. In this situation the result will be
an element node with no children.
The function returns an element node whose local name is
analyzestringresult
. This element and all its descendant elements have
the namespace URI http://www.w3.org/2005/xpathfunctions
. The namespace
prefix is fn:match
and fn:nonmatch
elements. This sequence
is formed by breaking the $value
string into a sequence of strings,
returning any substring that matches $pattern
as the content of a
match
element, and any intervening substring as the content of a
nonmatch
element.
More specifically, the function starts at the beginning of the input string and attempts
to find the first substring that matches the regular expression. If there are several
matches, the first match is defined to be the one whose starting position comes first in
the string. If several alternatives within the regular expression both match at the same
position in the input string, then the match that is chosen is the first alternative
that matches. For example, if the input string is The quick brown fox jumps
and the regular expression is jumpjumps
, then the match that is chosen is
jump
.
Having found the first match, the instruction proceeds to find the second and subsequent
matches by repeating the search, starting at the first
The input string is thus partitioned into a sequence of substrings, some of which match
the regular expression, others which do not match it. Each substring will contain at
least one character. This sequence is represented in the result by the sequence of
fn:match
and fn:nonmatch
children of the returned element
node; the string value of the fn:match
or fn:nonmatch
element
will be the corresponding substring of $input
, and the string value of the
returned element node will therefore be the same as $input
.
The content of an fn:nonmatch
element is always a single text node.
The content of a fn:match
element, however, is in general a sequence of
text nodes and fn:group
element children. An fn:group
element
with a nr
attribute having the integer value N identifies the
substring captured by the Nth parenthesized subexpression in the regular
expression. For each capturing subexpression there will be at most one corresponding
fn:group
element in each fn:match
element in the
result.
If the function is called twice with the same arguments, it is
The base URI of the element nodes in the result is
A schema is defined for the structure of the returned element: see
The result of the function will always be such that validation against this schema would succeed.
However, it is
A dynamic error is raised $pattern
is invalid according to the rules described in section
A dynamic error is raised $flags
is invalid according to the rules described in section
A dynamic error is raised $pattern
matches a zerolength string, that is, if fn:matches("",
$pattern, $flags)
returns true
.
It is
The declarations and definitions in the schema are not automatically available in
the static context of the fn:analyzestring
call (or of any other
expression). The contents of the static context are hostlanguage defined, and in some
host languages are implementationdefined.
The schema defines the outermost element, analyzestringresult
, in such
a way that mixed content is permitted. In fact the element will only have element nodes (match
and nonmatch
) as its children, never text nodes. Although this might have originally been an
oversight, defining the analyzestringresult
element with mixed="true"
allows it
to be atomized, which is potentially useful (the atomized value will be the original input string),
and the capability has therefore been retained for compatibility with the 3.0 version of this
specification.
In the following examples, the result document is shown in serialized form, with whitespace between the element nodes. This whitespace is not actually present in the result.
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.
If $value
is the empty sequence, the function returns false
.
Leading and trailing whitespace is trimmed from $token
.
If the trimmed value of $token
is a zerolength string, the function returns false
.
The collation used by this function is determined according to the rules in
The function returns true
if and only if there is string in $value
which,
after tokenizing at whitespace boundaries, contains a token
that is equal to the trimmed value of $token
under
the rules of the selected collation.
That is, the function returns the value of the expression:
Interior whitespace within $token
will cause the function to return false
,
unless such whitespace is ignored by the selected collation.
This function can be used for processing spaceseparated attribute values
(for example, the XHTML and DITA class attribute),
where one often needs to test for the presence
of a single token in a spaceseparated list. The function is designed to work
both when the attribute has been validated against an XSD list type, and when it
appears as a single untyped string. It differs from the
HTML 5 definition in that HTML 5 recognizes form feed (x0C) as a separator.
To reproduce the HTML token matching behavior, the HTML ASCII caseinsensitive collation
should be used: see
Resolves a relative IRI reference against an absolute IRI.
The function is defined to operate on IRI references as defined in
The following rules apply in order:
If $href
is the empty sequence, the function returns the empty
sequence.
If $href
is an absolute IRI (as defined above), then it is returned
unchanged.
If the $base
argument is not supplied,
If the static base URI in the static context is not absent, it is used as the effective
value of $base
.
Otherwise, a dynamic error is raised:
The function resolves the relative IRI reference $href
against the base IRI $base
using the algorithm defined in
The first form of this function resolves $href
against the value of the
baseuri property from the static context. A dynamic error is raised
A dynamic error is raised $href
is not a valid IRI according to the rules of RFC3987, extended with an
implementationdefined subset of the extensions permitted in LEIRI, or if it is not a
suitable relative reference to use as input to the RFC3986 resolution algorithm extended
to handle additional unreserved characters.
A dynamic error is raised $base
is
not a valid IRI according to the rules of RFC3987, extended with an
implementationdefined subset of the extensions permitted in LEIRI, or if it is not a
suitable IRI to use as input to the chosen resolution algorithm (for example, if it is a
relative IRI reference
A dynamic error is raised
Resolving a URI does not dereference it. This is merely a syntactic operation on two
The algorithms in the cited RFCs include some variations that are optional or recommended rather than mandatory; they also describe some common practices that are not recommended, but which are permitted for backwards compatibility. Where the cited RFCs permit variations in behavior, so does this specification.
Throughout this family of specifications, the phrase "resolving a relative URI (or IRI) reference" should be understood as using the rules of this function, unless otherwise stated.
RFC3986 defines an algorithm for resolving relative references
in the context of the URI syntax defined in that RFC. RFC3987 describes a modification
to that algorithm to make it applicable to IRIs (specifically: additional characters
permitted in an IRI are handled the same way that RFC3986 handles unreserved characters).
The LEIRI specification does not explicitly define a resolution algorithm, but suggests
that it
Returns the xs:boolean
value true
.
The result is equivalent to xs:boolean("1")
.
Returns the xs:boolean
value false
.
The result is equivalent to xs:boolean("0")
.
eq
operator when applied to two xs:boolean
values.Returns true
if the two arguments are the same boolean value.
The function returns true
if both arguments are true
or if
both arguments are false
. It returns false
if one of the
arguments is true
and the other argument is false
.
lt
operator when applied to two xs:boolean
values. Also
used in the definition of the ge
operator.Returns true
if the first argument is false
and the second is true
.
The function returns true
if $arg1
is false
and
$arg2
is true
. Otherwise, it returns
false
.
Computes the effective boolean value of the sequence $input
.
The function computes the effective boolean value of a sequence, defined according to
the following rules. See also
If $input
is the empty sequence, fn:boolean
returns
false
.
If $input
is a sequence whose first item is a node,
fn:boolean
returns true
.
If $input
is a singleton value of type xs:boolean
or a
derived from xs:boolean
, fn:boolean
returns
$input
.
If $input
is a singleton value of type xs:string
or a type
derived from xs:string
, xs:anyURI
or a type derived from
xs:anyURI
, or xs:untypedAtomic
,
fn:boolean
returns false
if the operand value has
zero length; otherwise it returns true
.
If $input
is a singleton value of any numeric type or a type derived
from a numeric type, fn:boolean
returns false
if the
operand value is NaN
or is numerically equal to zero; otherwise it
returns true
.
In all cases other than those listed above, fn:boolean
raises a type error
The result of this function is not necessarily the same as $input cast as
xs:boolean
. For example, fn:boolean("false")
returns the value
true
whereas "false" cast as xs:boolean
(which can also be
written xs:boolean("false")
) returns false
.
fn:boolean($abc)
raises a type error
fn:boolean([])
raises a type error
Returns true
if the effective boolean value of $input
is
false
, or false
if it is true
.
The value of $input
is first reduced to an effective boolean value by
applying the fn:boolean()
function. The function returns true
if the effective boolean value is false
, or false
if the
effective boolean value is true
.
fn:not(1 to 10)
raises a type error
lt
operator when applied to two xs:yearMonthDuration
values. Also used in the definition of the ge
operator.Returns true
if $arg1
is a shorter duration than $arg2
.
If the number of months in $arg1
is numerically less than the
number of months in $arg2
, the function returns true
.
Otherwise, the function returns false
.
Either or both durations may be negative.
lt
operator when applied to two xs:dayTimeDuration
values.
Also used in the definition of the ge
operator.Returns true
if $arg1
is a shorter duration than $arg2
.
If the number of seconds in $arg1
is numerically less than the
number of seconds in $arg2
, the function returns true
.
Otherwise, the function returns false
.
Either or both durations may be negative
eq
operators when applied to two xs:duration
values. Also
used in the definition of the ne
operator.Returns true
if $arg1
and $arg2
are durations of the same
length.
If the xs:yearMonthDuration
components of $arg1
and
$arg2
are equal and the xs:dayTimeDuration
components of
$arg1
and $arg2
are equal, the function returns
true
.
Otherwise, the function returns false
.
The semantics of this function are:
that is, the function returns true
if the months and seconds values of the
two durations are equal.
Note that this function, like any other, may be applied to arguments that are derived
from the types given in the function signature, including the two subtypes
xs:dayTimeDuration
and xs:yearMonthDuration
. With the
exception of the zerolength duration, no instance of xs:dayTimeDuration
can ever be equal to an instance of xs:yearMonthDuration
.
Returns the number of years in a duration.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the years
component in $value
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($months idiv 12)
.
If $value
is a negative duration then the result will be negative.
If $value
is an xs:dayTimeDuration
the function
returns 0
.
Returns the number of months in a duration.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the months
component in $value
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($months mod 12)
.
If $value
is a negative duration then the result will be negative.
If $value
is an xs:dayTimeDuration
the function
returns 0
.
Returns the number of days in a duration.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the days
component in $value
. Given that a duration
is a ($months, $seconds)
tuple, the result is ($seconds idiv 86400)
.
If $value
is a negative duration then the result will be negative.
If $value
is an xs:yearMonthDuration
the function returns 0
.
Returns the number of hours in a duration.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the hours
component in $value
. ($months, $seconds)
tuple, the result is the value of ($seconds mod 86400) idiv 3600
If $value
is a negative duration then the result will be negative.
If $value
is an xs:yearMonthDuration
the function returns 0
.
Returns the number of minutes in a duration.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the minutes
component in $value
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($seconds mod 3600) idiv 60
.
If $value
is a negative duration then the result will be negative.
If $value
is an xs:yearMonthDuration
the function returns 0
.
Returns the number of seconds in a duration.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:decimal
representing the seconds
component in $value
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($seconds mod 60)
as an xs:decimal
.
If $value
is a negative duration then the result will be negative.
If $value
is an xs:yearMonthDuration
the function returns 0
.
+
operator when applied to two xs:yearMonthDuration
values.Returns the result of adding two xs:yearMonthDuration
values.
The function returns the result of adding $arg1
to $arg2
.
The result will be an xs:yearMonthDuration
whose
length in months is equal to the length in months of $arg1
plus the length
in months of $arg2
.
For handling of overflow, see
Either duration (and therefore the result) may be negative.

operator when applied to two xs:yearMonthDuration
values.Returns the result of subtracting one xs:yearMonthDuration
value from
another.
The function returns the result of subtracting $arg2
from
$arg1
. The result will be an xs:yearMonthDuration
whose length in months is equal to the length in months of $arg1
minus the
length in months of $arg2
.
For handling of overflow, see
Either duration (and therefore the result) may be negative.
*
operator when applied to an xs:yearMonthDuration
and a numeric
value.Returns the result of multiplying $arg1
by $arg2
.
The result is rounded to the nearest month.
The result is the xs:yearMonthDuration
whose length in months is equal to
the result of applying the fn:round
function to the value obtained by
multiplying the length in months of $arg1
by the value of
$arg2
.
If $arg2
is positive or negative zero, the result is a zerolength
duration. If $arg2
is positive or negative infinity, the result overflows
and is handled as described in
For handling of overflow and underflow, see
A dynamic error is raised $arg2
is
NaN
.
Either duration (and therefore the result) may be negative.
div
operator when applied to an xs:yearMonthDuration
and a numeric
value.Returns the result of dividing $arg1
by $arg2
.
The result is rounded to the nearest month.
The result is the xs:yearMonthDuration
whose length in months is equal to
the result of applying the fn:round
function to the value obtained by
dividing the length in months of $arg1
by the value of
$arg2
.
If $arg2
is positive or negative infinity, the result is a zerolength
duration. If $arg2
is positive or negative zero, the result overflows and
is handled as described in
For handling of overflow and underflow, see
A dynamic error is raised $arg2
is
NaN
.
Either operand (and therefore the result) may be negative.
div
operator when applied to two xs:yearMonthDuration
values.Returns the ratio of two xs:yearMonthDuration
values.
The function returns the result of dividing the length in months of $arg1
by the length in months of $arg2
, according to the rules of the
op:numericdivide
function for integer operands.
For handling of overflow and underflow, see
Either duration (and therefore the result) may be negative.
The following example demonstrates how to calculate the length of an
xs:yearMonthDuration
value in months:
+
operator when applied to two xs:dayTimeDuration
values.Returns the sum of two xs:dayTimeDuration
values.
The function returns the result of adding $arg1
to
$arg2
. The result is the xs:dayTimeDuration
whose length in
seconds is equal to the sum of the length in seconds of the two input durations.
For handling of overflow, see
Either duration (and therefore the result) may be negative.

operator when applied to two xs:dayTimeDuration
values.Returns the result of subtracting one xs:dayTimeDuration
from another.
The function returns the result of subtracting $arg2
from
$arg1
. The result is the xs:dayTimeDuration
whose
length in seconds is equal to the length in seconds of $arg1
minus the
length in seconds of $arg2
.
For handling of overflow, see
Either duration (and therefore the result) may be negative.
*
operator when applied to an xs:dayTimeDuration
and a numeric
value.Returns the result of multiplying a xs:dayTimeDuration
by a number.
The function returns the result of multiplying $arg1
by
$arg2
. The result is the xs:dayTimeDuration
whose length in
seconds is equal to the length in seconds of $arg1
multiplied by the
numeric value $arg2
.
If $arg2
is positive or negative zero, the result is a zerolength
duration. If $arg2
is positive or negative infinity, the result overflows
and is handled as described in
For handling of overflow and underflow, see
A dynamic error is raised $arg2
is
NaN
.
Either operand (and therefore the result) may be negative.
div
operator when applied to two xs:dayTimeDuration
values.Returns the result of multiplying a xs:dayTimeDuration
by a number.
The function returns the result of dividing $arg1
by
$arg2
. The result is the xs:dayTimeDuration
whose length in
seconds is equal to the length in seconds of $arg1
divided by the numeric
value $arg2
.
If $arg2
is positive or negative infinity, the result is a zerolength
duration. If $arg2
is positive or negative zero, the result overflows and
is handled as described in
For handling of overflow and underflow, see
A dynamic error is raised $arg2
is
NaN
.
Either operand (and therefore the result) may be negative.
div
operator when applied to two xs:dayTimeDuration
values.Returns the ratio of two xs:dayTimeDuration
values, as a decimal
number.
The function returns the result of dividing $arg1
by
$arg2
. The result is the xs:dayTimeDuration
whose length in
seconds is equal to the length in seconds of $arg1
divided by the length in
seconds of $arg2
. The calculation is performed by applying
op:numericdivide
to the two xs:decimal
operands.
For handling of overflow and underflow, see
Either operand (and therefore the result) may be negative.
This examples shows how to determine the number of seconds in a duration.
Returns an xs:dateTime
value created by combining an xs:date
and an xs:time
.
If either $date
or $time
is the empty sequence the function
returns the empty sequence.
Otherwise, the function returns an xs:dateTime
whose date component is
equal to $date
and whose time component is equal to $time
.
The timezone of the result is computed as follows:
If neither argument has a timezone, the result has no timezone.
If exactly one of the arguments has a timezone, or if both arguments have the same timezone, the result has this timezone.
A dynamic error is raised
"24:00:00"
is an alternate lexical form
for "00:00:00"
eq
operator when applied to two xs:dateTime
values. Also
used in the definition of the ne
, le
and ge
operators.Returns true
if the two supplied xs:dateTime
values refer to the same
instant in time.
If either $arg1
or $arg2
has no timezone component, the
effective value of the argument is obtained by substituting the implicit timezone from
the dynamic evaluation context.
The function then returns true
if and only if the effective value of
$arg1
is equal to the effective value of $arg2
according to
the algorithm defined in section 3.2.7.4 of Order relation on dateTime
for xs:dateTime
values with
timezones. Otherwise the function returns false
.
Assume that the dynamic context provides an implicit timezone value of
05:00
lt
operator when applied to two xs:dateTime
values. Also
used in the definition of the ge
operator.Returns true
if the first argument represents an earlier instant in time
than the second argument.
If either $arg1
or $arg2
has no timezone component, the
effective value of the argument is obtained by substituting the implicit timezone from
the dynamic evaluation context.
The function then returns true
if and only if the effective value of
$arg1
is less than the effective value of $arg2
according
to the algorithm defined in section 3.2.7.4 of Order relation on dateTime
for xs:dateTime
values with
timezones. Otherwise the function returns false
.
eq
operator when applied to two xs:date
values. Also used
in the definition of the ne
, le
and ge
operators.Returns true
if and only if the starting instants of the two supplied
xs:date
values are the same.
The starting instant of an xs:date
is the xs:dateTime
at time
00:00:00
on that date.
The function returns the result of the expression:
xs:dateTime("20041225T00:00:00Z")
and
xs:dateTime("20041225T00:00:00+07:00")
. These are normalized to
xs:dateTime("20041225T00:00:00Z")
and
xs:dateTime("20041224T17:00:00Z")
. lt
operator when applied to two xs:date
values. Also used in the
definition of the ge
operator.Returns true
if and only if the starting instant of $arg1
is
less than the starting instant of $arg2
. Returns false
otherwise.
The starting instant of an xs:date
is the xs:dateTime
at time
00:00:00
on that date.
The function returns the result of the expression:
eq
operator when applied to two xs:time
values. Also used
in the definition of the ne
, le
and ge
operators.Returns true
if the two xs:time
values represent the same
instant in time, when treated as being times on the same date, before adjusting the
timezone.
Each of the supplied xs:time
values is expanded to an
xs:dateTime
value by associating the time with an arbitrary date. The
function returns the result of comparing these two xs:dateTime
values using
op:dateTimeequal
.
The result of the function is thus the same as the value of the expression:
Assume that the date components from the reference xs:dateTime
correspond to 19721231
.
xs:dateTime
s calculated using the reference date
components are 19721231T08:00:00+09:00
and
19721231T17:00:0006:00
. These normalize to
19721230T23:00:00Z
and 19721231T23:00:00Z
.
xs:dateTime
values, a time of 24:00:00
is equivalent to 00:00:00
on
the following day. For xs:time
, the normalization from
24:00:00
to 00:00:00
happens before the
xs:time
is converted into an xs:dateTime
for the
purpose of the equality comparison. For xs:time
, any operation on
24:00:00
produces the same result as the same operation on
00:00:00
because these are two different lexical representations
of the same value. lt
operator when applied to two xs:time
values. Also used in the
definition of the ge
operator.Returns true
if the first xs:time
value represents an earlier
instant in time than the second, when both are treated as being times on the same date,
before adjusting the timezone.
Each of the supplied xs:time
values is expanded to an
xs:dateTime
value by associating the time with an arbitrary date. The
function returns the result of comparing these two xs:dateTime
values using
op:dateTimelessthan
.
The result of the function is thus the same as the value of the expression:
Assume that the dynamic context provides an implicit timezone value of
05:00
.
eq
operator when applied to two xs:gYearMonth
values. Also
used in the definition of the ne
operator.Returns true
if the two xs:gYearMonth
values have the same starting
instant.
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template xxxxxx01T00:00:00
. The function
returns the result of comparing these two starting instants using
op:dateTimeequal
.
Assume that the dynamic context provides an implicit timezone value of
05:00
.
op:gYearMonthequal(xs:gYearMonth("198602"), xs:gYearMonth("198603"))
returns false()
. The starting instants are
19860201T00:00:0005:00
and 19860301T00:00:00
,
respectively.
op:gYearMonthequal(xs:gYearMonth("197803"), xs:gYearMonth("198603Z"))
returns false()
. The starting instants are
19780301T00:00:0005:00
and 19860301T00:00:00Z
,
respectively.
eq
operator when applied to two xs:gYear
values. Also used in the
definition of the ne
operator.Returns true
if the two xs:gYear
values have the same starting instant.
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template xxxx0101T00:00:00
. The function
returns the result of comparing these two starting instants using
op:dateTimeequal
.
Assume that the dynamic context provides an implicit timezone value of
05:00
. Assume, also, that the xs:dateTime
template is
xxxx0101T00:00:00
.
op:gYearequal(xs:gYear("200512:00"), xs:gYear("2005+12:00"))
returns
false()
. The starting instants are
20050101T00:00:0012:00
and 20050101T00:00:00+12:00
,
respectively, and normalize to 20050101T12:00:00Z
and
20041231T12:00:00Z
.
eq
operator when applied to two xs:gMonthDay
values. Also
used in the definition of the ne
operator.Returns true
if the two xs:gMonthDay
values have the same starting instant,
when considered as days in the same year.
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template 1972xxxxT00:00:00
or an equivalent.
The function returns the result of comparing these two starting instants using
op:dateTimeequal
.
Assume that the dynamic context provides an implicit timezone value of
05:00
. Assume for the purposes of illustration that the
xs:dateTime
template used is 1972xxxxT00:00:00
(this
does not affect the result).
19721225T00:00:0014:00
and
19721226T00:00:00+10:00
, respectively, and normalize to
19721225T14:00:00Z
and 19721225T14:00:00Z
.
eq
operator when applied to two xs:gMonth
values. Also used
in the definition of the ne
operator.Returns true
if the two xs:gMonth
values have the same starting instant,
when considered as months in the same year.
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template 1972xx01T00:00:00
or an equivalent.
The function returns the result of comparing these two starting instants using
op:dateTimeequal
.
Assume that the dynamic context provides an implicit timezone value of
05:00
. Assume, also, that the xs:dateTime
template
chosen is 1972xx01T00:00:00
.
19721201T00:00:0014:00
and
19721201T00:00:00+10:00
, respectively, and normalize to
19721130T14:00:00Z
and 19721201T14:00:00Z
.
eq
operator when applied to two xs:gDay
values. Also used in the
definition of the ne
operator.Returns true
if the two xs:gDay
values have the same starting instant, when
considered as days in the same month of the same year.
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template 197212xxT00:00:00
or an equivalent.
The function returns the result of comparing these two starting instants using
op:dateTimeequal
.
Assume that the dynamic context provides an implicit timezone value of
05:00
. Assume, also, that the xs:dateTime
template is
197212xxT00:00:00
.
19721225T00:00:0014:00
and
19721225T00:00:00+10:00
, respectively, and normalize to
19721225T14:00:00Z
and 19721224T14:00:00Z
.
Returns the year component of an xs:dateTime
.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the year
component in the local value of $value
. The result may be negative.
Ignoring complications that arise with midnight on the last day of the year, the year returned is the same numeric value that appears in the lexical representation, which for negative years means the meaning may vary depending on whether XSD 1.0 or XSD 1.1 conventions are in use.
Returns the month component of an xs:dateTime
.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between 1
and
12
, both inclusive, representing the month component in the
local value of $value
.
Returns the day component of an xs:dateTime
.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between 1
and
31
, both inclusive, representing the day component in the
local value of $value
.
Returns the hours component of an xs:dateTime
.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between 0
and
23
, both inclusive, representing the hours component in the local value
of $value
.
Returns the minute component of an xs:dateTime
.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
value between 0
and 59
, both inclusive, representing the minute component in the local value of
$value
.
Returns the seconds component of an xs:dateTime
.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:decimal
value greater than or equal
to zero and less than 60, representing the seconds and fractional seconds in the local
value of $value
.
Returns the timezone component of an xs:dateTime
.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns the timezone component of $value
, if any. If
$value
has a timezone component, then the result is an
xs:dayTimeDuration
that indicates deviation from UTC; its value may
range from +14:00 to 14:00 hours, both inclusive. If $value
has no timezone
component, the result is the empty sequence.
Returns the year component of an xs:date
.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the year in the
local value of $value
. The value may be negative.
The year returned is the same numeric value that appears in the lexical representation, which for negative years means the meaning may vary depending on whether XSD 1.0 or XSD 1.1 conventions are in use.
Returns the month component of an xs:date
.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between
1
and 12
, both
inclusive, representing the month component in the local value of $value
.
Returns the day component of an xs:date
.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between
1
and 31
, both
inclusive, representing the day component in the localized value of
$value
.
Returns the timezone component of an xs:date
.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns the timezone component of $value
, if any. If
$value
has a timezone component, then the result is an
xs:dayTimeDuration
that indicates deviation from UTC; its value may
range from +14:00 to 14:00 hours, both inclusive. If $value
has no timezone
component, the result is the empty sequence.
Returns the hours component of an xs:time
.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between
0
and 23
, both
inclusive, representing the value of the hours component in the local value of
$value
.
Assume that the dynamic context provides an implicit timezone value of
05:00
.
Returns the minutes component of an xs:time
.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
value between 0
and 59
, both inclusive, representing the value of the minutes component
in the local value of $value
.
Returns the seconds component of an xs:time
.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:decimal
value greater than or equal
to zero and less than 60, representing the seconds and fractional seconds in the local
value of $value
.
Returns the timezone component of an xs:time
.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns the timezone component of $value
, if any. If
$value
has a timezone component, then the result is an
xs:dayTimeDuration
that indicates deviation from UTC; its value may
range from +14:00 to 14:00 hours, both inclusive. If $value
has no timezone
component, the result is the empty sequence.
Adjusts an xs:dateTime
value to a specific timezone, or to no timezone at
all.
If $timezone
is not specified, then the effective value of
$timezone
is the value of the implicit timezone in the dynamic
context.
If $value
is the empty sequence, then the function returns the empty
sequence.
If $value
does not have a timezone component and $timezone
is
the empty sequence, then the result is $value
.
If $value
does not have a timezone component and $timezone
is
not the empty sequence, then the result is $value
with $timezone
as the timezone component.
If $value
has a timezone component and $timezone
is the empty
sequence, then the result is the local value of $value
without its timezone
component.
If $value
has a timezone component and $timezone
is not the
empty sequence, then the result is the xs:dateTime
value that is equal to
$value
and that has a timezone component equal to
$timezone
.
A dynamic error is raised $timezone
is less than PT14H
or greater than PT14H
or is not an
integral number of minutes.
Assume the dynamic context provides an implicit timezone of 05:00
(PT5H0M)
.
Adjusts an xs:date
value to a specific timezone, or to no timezone at all;
the result is the date in the target timezone that contains the starting instant of the
supplied date.
If $timezone
is not specified, then the effective value of
$timezone
is the value of the implicit timezone in the dynamic
context.
If $value
is the empty sequence, then the function returns the empty
sequence.
If $value
does not have a timezone component and $timezone
is
the empty sequence, then the result is $value
.
If $value
does not have a timezone component and $timezone
is
not the empty sequence, then the result is $value
with $timezone
as the timezone component.
If $value
has a timezone component and $timezone
is the empty
sequence, then the result is the local value of $value
without its timezone
component.
If $value
has a timezone component and $timezone
is not the
empty sequence, then the function returns the value of the expression:
Let $dt
be the value of fn:dateTime($arg,
xs:time('00:00:00'))
.
Let $adt
be the value of fn:adjustdateTimetotimezone($dt,
$timezone)
The function returns the value of xs:date($adt)
A dynamic error is raised $timezone
is less than PT14H
or greater than PT14H
or is not an
integral number of minutes.
Assume the dynamic context provides an implicit timezone of 05:00
(PT5H0M)
.
$value
is converted to
xs:dateTime("20020307T00:00:0007:00")
. This is adjusted to the
implicit timezone, giving "20020307T02:00:0005:00"
.
$value
is converted to
xs:dateTime("20020307T00:00:0007:00")
.
This is adjusted to the given timezone,
giving "20020306T21:00:0010:00"
. Adjusts an xs:time
value to a specific timezone, or to no timezone at
all.
If $timezone
is not specified, then the effective value of
$timezone
is the value of the implicit timezone in the dynamic
context.
If $value
is the empty sequence, then the function returns the empty
sequence.
If $value
does not have a timezone component and $timezone
is
the empty sequence, then the result is $value
.
If $value
does not have a timezone component and $timezone
is
not the empty sequence, then the result is $value
with $timezone
as the timezone component.
If $value
has a timezone component and $timezone
is the empty
sequence, then the result is the localized value of $value
without its
timezone component.
If $value
has a timezone component and $timezone
is not the
empty sequence, then:
Let $dt
be the xs:dateTime
value
fn:dateTime(xs:date('19721231'), $value)
.
Let $adt
be the value of fn:adjustdateTimetotimezone($dt,
$timezone)
The function returns the xs:time
value
xs:time($adt)
.
A dynamic error is raised $timezone
is less than PT14H
or greater than PT14H
or if does not
contain an integral number of minutes.
Assume the dynamic context provides an implicit timezone of 05:00
(PT5H0M)
.

operator when applied to two xs:dateTime
values.Returns an xs:dayTimeDuration
representing the amount of elapsed time
between the instants arg2
and arg1
.
If either $arg1
or $arg2
do not contain an explicit timezone
then, for the purpose of the operation, the implicit timezone provided by the dynamic
context (See
The function returns the elapsed time between the date/time instant arg2
and the date/time instant arg1
, computed according to the algorithm given
in Appendix E of xs:dayTimeDuration
.
If the normalized value of $arg1
precedes in time the normalized value of
$arg2
, then the returned value is a negative duration.
Assume that the dynamic context provides an implicit timezone value of
05:00
.

operator
when applied to two xs:date
values.Returns the xs:dayTimeDuration
that corresponds to the elapsed time between
the starting instant of $arg2
and the starting instant of
$arg2
.
If either $arg1
or $arg2
do not contain an explicit timezone
then, for the purpose of the operation, the implicit timezone provided by the dynamic
context (See
The starting instant of an xs:date
is the xs:dateTime
at
00:00:00
on that date.
The function returns the result of subtracting the two starting instants using
op:subtractdateTimes
.
If the starting instant of $arg1
precedes in time the starting instant of
$arg2
, then the returned value is a negative duration.
Assume that the dynamic context provides an implicit timezone value of
Z
.
{2000,
10, 30, 0, 0, 0, PT0S}
and {1999, 11, 28, 0, 0, 0,
PT0S}
.Now assume that the dynamic context provides an implicit timezone value of
+05:00
.
{2000,
10, 29, 19, 0, 0, PT0S}
and {1999, 11, 28, 0, 0, 0,
PT0S}
.
operator
when applied to two xs:time
values.Returns the xs:dayTimeDuration
that corresponds to the elapsed time between
the values of $arg2
and $arg1
treated as times on the same
date.
The function returns the result of the expression:
Any other reference date would work equally well.
Assume that the dynamic context provides an implicit timezone value of
05:00
. Assume, also, that the date components of the reference
xs:dateTime
correspond to "19721231"
.
xs:dateTime
value {1972, 12, 31, 11, 12, 0, PT0S}
the xs:dateTime
value {1972, 12, 31, 9, 0, 0, PT0S}
.xs:dateTime
values are {1972, 12, 31, 11,
0, 0, PT5H}
and {1972, 12, 31, 21, 30, 0, PT5H30M}
. These
normalize to {1972, 12, 31, 16, 0, 0, PT0S}
and {1972, 12, 31,
16, 0, 0, PT0S}
. xs:dateTime
values are {1972,
12, 31, 23, 0, 0, PT0S}
and {1972, 12, 30, 23, 0, 0,
PT0S}
.xs:dateTime
values are {1972,
12, 31, 0, 0, 0, ()}
and {1972, 12, 31, 23, 59, 59.0,
()}
.+
operator when applied to an xs:dateTime
and an
xs:yearMonthDuration
value. Returns the xs:dateTime
that is a given duration after a specified
xs:dateTime
(or before, if the duration is negative).
The function returns the result of adding $arg2
to the value of
$arg1
using the algorithm described in Appendix E of $arg2
is negative, then the result xs:dateTime
precedes $arg1
.
The result has the same timezone as $arg1
. If $arg1
has no
timezone, the result has no timezone.
+
operator when applied to an xs:dateTime
and an
xs:dayTimeDuration
value. Returns the xs:dateTime
that is a given duration after a specified
xs:dateTime
(or before, if the duration is negative).
The function returns the result of adding $arg2
to the value of
$arg1
using the algorithm described in Appendix E of $arg2
is negative, then the result xs:dateTime
precedes $arg1
.
The result has the same timezone as $arg1
. If $arg1
has no
timezone, the result has no timezone.

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

operator when applied to an xs:dateTime
an and
xs:dayTimeDuration
valuesReturns the xs:dateTime
that is a given duration before a specified
xs:dateTime
(or after, if the duration is negative).
The function returns the xs:dateTime
computed by negating
$arg2
and adding the result to $arg1
using the
function op:adddayTimeDurationtodateTime
.
+
operator when applied to an xs:date
and an
xs:yearMonthDuration
value. Returns the xs:date
that is a given duration after a specified
xs:date
(or before, if the duration is negative).
The function returns the result of casting $arg1
to an
xs:dateTime
, adding $arg2
using the function
op:addyearMonthDurationtodateTime
, and casting the result back to an
xs:date
.
+
operator when applied to an xs:date
and an
xs:dayTimeDuration
value. Returns the xs:date
that is a given duration after a specified
xs:date
(or before, if the duration is negative).
The function returns the result of casting $arg1
to an
xs:dateTime
, adding $arg2
using the function
op:adddayTimeDurationtodateTime
, and casting the result back to an
xs:date
.
xs:dateTime
value {2004, 10, 30, 0, 0, 0, PT0S}
.
Adding the second argument to this gives the xs:dateTime
value
{2004, 11, 1, 2, 30, 0, PT0S}
. The time components are then
discarded. 
operator when applied to an xs:date
and an
xs:yearMonthDuration
value. Returns the xs:date
that is a given duration before a specified
xs:date
(or after, if the duration is negative).
Returns the xs:date
computed by negating $arg2
and adding the
result to $arg1
using the function
op:addyearMonthDurationtodate
.

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

operator when applied to an xs:time
and an
xs:dayTimeDuration
value. Returns the xs:time
value that is a given duration before a specified
xs:time
(or after, if the duration is negative or causes wraparound
past midnight)
The function returns the result of negating $arg2
and adding the result to
$arg1
using the function op:adddayTimeDurationtotime
.
Returns a string containing an xs:dateTime
value formatted for display.
See
Returns a string containing an xs:date
value formatted for display.
See
Returns a string containing an xs:time
value formatted for display.
See
Parses a string containing the date and time in IETF format, returning the corresponding
xs:dateTime
value.
The function accepts a string matching the production input
in the
following grammar:
input

::=

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

dayname

::=

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

datespec

::=

daynum dsep monthname dsep year

asctime

::=

monthname dsep daynum S time S year

dsep

::=

S  (S? "" S?)

daynum

::=

digit digit?

year

::=

digit digit (digit digit)?

digit

::=

[09]

monthname

::=

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

time

::=

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

hours

::=

digit digit? 
minutes

::=

digit digit

seconds

::=

digit digit ("." digit+)?

timezone

::=

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

tzname

::=

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

tzoffset

::=

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

::=

(x09  x0A  x0D  x20)+

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

UT, UTC, GMT  00:00 
EST  05:00 
EDT  04:00 
CST  06:00 
CDT  05:00 
MST  07:00 
MDT  06:00 
PST  08:00 
PDT  07:00 
If neither a tzoffset
nor tzname
is supplied, a timezone
offset of 00:00
is assumed.
A dynamic error is raised "31 February"
).
The parseietfdate
function attempts to interpret its input as a date
in any of the three formats specified by HTTP
These formats are used widely on the Internet to represent timestamps, and were specified in:
POSIX asctime()
format
The grammar for this function is slightly more liberal than the RFCs (reflecting the internet tradition of being liberal in what is accepted). For example the function:
Accepts a singledigit value where appropriate in place of a twodigit value with a leading zero (so
"Wed 1 Jun"
is acceptable in place of "Wed 01 Jun"
,
"5:00"
is equivalent to "05:00"
)
Accepts one or more whitespace characters (x20, x09, x0A, x0D) wherever a single space is required, and allows whitespace to be omitted where it is not required for parsing
Accepts and ignores whitespace characters (x20, x09, x0A, x0D) at the start or end of the string.
In new protocols IETF recommends the format of
An fn:formatdateTime
with a picture
string of "[FNn3], [D01] [MNn3] [Y04] [H01]:[m01]:[s01] [Z0000]"
.
Returns an xs:QName
value (that is, an expandedQName) by taking an
xs:string
that has the lexical form of an xs:QName
(a
string in the form "prefix:localname"
or "localname"
)
and resolving it using the inscope namespaces for a given element.
If $value
is the empty sequence, returns the empty sequence.
More specifically, the function searches the namespace bindings of $element
for a binding whose name matches the prefix of $value
, or the zerolength
string if it has no prefix, and returns an expandedQName whose local name is taken
from the supplied $value
, and whose namespace URI is taken from the string
value of the namespace binding.
If the $value
has no prefix, and there is no namespace binding for
$element
corresponding to the default (unnamed) namespace, then the
resulting expandedQName has no namespace part.
The prefix (or absence of a prefix) in the supplied $value
argument is
retained in the returned expandedQName, as described in
A dynamic error is raised $value
does
not have the correct lexical form for an instance of xs:QName
.
A dynamic error is raised $value
has
a prefix and there is no namespace binding for $element
that matches this
prefix.
Sometimes the requirement is to construct an xs:QName
without using the
default namespace. This can be achieved by writing:
If the requirement is to construct an xs:QName
using the namespaces in the
static context, then the xs:QName
constructor should be used.
Assume that the element bound to $element
has a single namespace binding
bound to the prefix eg
.
fn:resolveQName("hello", $element)
returns a QName with local name
"hello"
that is in no namespace.
fn:resolveQName("eg:myFunc", $element)
returns an xs:QName
whose namespace URI is specified by the namespace binding corresponding to the prefix
"eg"
and whose local name is "myFunc"
.
Returns an xs:QName
value formed using a supplied namespace URI and lexical QName.
The namespace URI in the returned QName is taken from $uri
. If
$uri
is the zerolength string or the empty sequence, it represents
“no namespace”.
The prefix (or absence of a prefix) in $qname
is retained in the
returned xs:QName
value.
The local name in the result is taken from the local part of
$qname
.
A dynamic error is raised $qname
does not have the correct lexical form for an instance of xs:QName
.
A dynamic error is raised $uri
is the zerolength string or the empty sequence, and the value of
$qname
contains a colon (:
).
A dynamic error $uri
is not a valid URI (XML Namespaces 1.0) or IRI (XML Namespaces
1.1).
fn:QName("http://www.example.com/example", "person")
returns an
xs:QName
with namespace URI "http://www.example.com/example"
,
local name "person"
and prefix ""
.
fn:QName("http://www.example.com/example", "ht:person")
returns an
xs:QName
with namespace URI "http://www.example.com/example"
,
local name "person"
and prefix "ht"
.
Returns an xs:QName
value formed by parsing an EQName.
Leading and trailing whitespace in $value
is stripped.
If the resulting $value
is castable to xs:NCName
,
the result is fn:QName("", $value)
: that is, a QName in no namespace.
Otherwise, if the resulting $value
is in the lexical space of xs:QName
(that is, if it is in the form prefix:local
), the result is xs:QName($value)
.
Note that this result depends on the inscope prefixes in the static context, and may result in
various error conditions.
Otherwise, if the resulting $value
takes the form of an
XPath Q{uri}local
, where the uri
part may be zerolength),
then the result is fn:QName(uri, local)
.
The rules used for parsing a <
and &
to be escaped).
A dynamic error is raised $value
, after whitespace normalization,
does not match the XPath production
A dynamic error is raised $value
, after whitespace normalization,
is in the form prefix:local
(with a nonabsent prefix), and
the prefix cannot be resolved to a namespace URI using the inscope namespace
bindings from the static context.
fn:parseQName("Q{http://www.example.com/example}person")
returns an
xs:QName
with namespace URI "http://www.example.com/example"
,
local name "person"
and prefix ""
.
fn:parseQName("person")
returns an
xs:QName
with absent namespace URI, local
name "person"
and prefix ""
.
fn:parseQName("Q{}person")
returns an
xs:QName
with absent namespace URI, local
name "person"
and prefix ""
.
fn:parseQName("p:person")
returns an
xs:QName
with namespace URI obtained from the static context, local
name "person"
and prefix "p"
(The result is the same as xs:QName("p:person")
).
Returns a string representation of an xs:QName
in the format Q{uri}local
.
If $value
is the empty sequence, returns the empty sequence.
The result is a string in the format Q{uri}local
, where:
uri
is the result of fn:string(fn:namespaceurifromQName($value))
(which will be a zerolength string if the QName is in no namespace), and
local
is the result of
fn:localnamefromQName($value)
.
There is no escaping of special characters in the namespace URI. If the namespace URI
contains curly braces, the resulting string will not be a valid
eq
and ne
operators when applied to two values of type xs:QName
. Returns true
if two supplied QNames have the same namespace URI and the
same local part.
The function returns true
if the namespace URIs of $arg1
and
$arg2
are equal and the local names of $arg1
and
$arg2
are equal.
Otherwise, the function returns false
.
The namespace URI parts are considered equal if they are both fn:codepointequal
function.
The local parts are also compared under the rules of the fn:codepointequal
function.
The prefix parts of $arg1
and $arg2
, if any, are ignored.
Returns the prefix component of the supplied QName.
If $value
is the empty sequence the function returns the empty sequence.
If $value
has no prefix component the function returns the empty
sequence.
Otherwise, the function returns an xs:NCName
representing the prefix
component of $value
.
Returns the local part of the supplied QName.
If $value
is the empty sequence the function returns the empty sequence.
Otherwise, the function returns an xs:NCName
representing the local part of
$value
.
Returns the namespace URI part of the supplied QName.
If $value
is the empty sequence the function returns the empty sequence.
Otherwise, the function returns an xs:anyURI
representing the namespace URI
part of $value
.
If $value
is in no namespace, the function returns the zerolength
xs:anyURI
.
Returns the namespace URI of one of the inscope namespaces for $element
,
identified by its namespace prefix.
The function returns the result of the expression map:get(fn:inscopenamespaces($element), string($value))
.
fn:inscopenamespaces
function; the semantics are unchanged.Returns the inscope namespaces of an element node, as a map.
The function returns a map representing the prefixes of the inscope
namespaces for $element
. The map contains one entry
for each inscope namespace: the key of the entry is the namespace
prefix or a zerolength string, and the corresponding value is the namespace URI.
For namespace bindings that have a prefix, the key represents the prefix as an
instance of xs:NCName
. For the default namespace, which has no prefix, the key is
the zerolength string as an instance of xs:string
.
The XML namespace is in scope for every element, so the result will always include an entry
with key "xml"
and corresponding value http://www.w3.org/XML/1998/namespace
.
Returns the prefixes of the inscope namespaces for an element node.
The function returns the result of the expression
map:keys(fn:inscopenamespaces($element))
(but in no defined order).
The XML namespace is in scope for every element, so the result will always include the string "xml"
.
fn:inscopenamespaces
function; the semantics are unchanged.eq
and ne
operators when applied to two xs:hexBinary
values.Returns true
if two xs:hexBinary
values contain the same octet
sequence.
The function returns true
if $value1
and $value2
are of the same length, measured in binary octets, and contain the same octets in the
same order. Otherwise, it returns false
.
lt
operator when applied to two xs:hexBinary
values. Also used in the
definition of the ge
operator.Returns true
if the first argument is less than the second.
The function returns true
if any of the following conditions is true
:
$arg1
is zerolength (contains no octets) and $arg2
is
not zerolength.
Neither argument is zerolength, and the first octet of $arg1
is less
than the first octet of $arg2
, treating the value of the octet as an
unsigned integer in the range 0 to 255.
Neither argument is zerolength, the first octet of $arg1
is equal to
the first octet of $arg2
, and the xs:hexBinary
value
formed by taking all octets of arg1
after the first is less than the
xs:hexBinary
value formed by taking all octets of
arg2
after the first.
Otherwise, the function returns false
.
eq
and ne
operators when applied to two xs:base64Binary
values.Returns true
if two xs:base64Binary
values contain the same octet
sequence.
The function returns true
if $value1
and $value2
are of the same length, measured in binary octets, and contain the same octets in the
same order. Otherwise, it returns false
.
lt
operator when applied to two xs:base64Binary
values. Also used in
the definition of the ge
operator.Returns true
if the first argument is less than the second.
The function returns true
if any of the following conditions is true
:
$arg1
is zerolength (contains no octets) and $arg2
is
not zerolength.
Neither argument is zerolength, and the first octet of $arg1
is less
than the first octet of $arg2
, treating the value of the octet as an
unsigned integer in the range 0 to 255.
Neither argument is zerolength, the first octet of $arg1
is equal to
the first octet of $arg2
, and the xs:base64Binary
value
formed by taking all octets of arg1
after the first is less than the
xs:base64Binary
value formed by taking all octets of
arg2
after the first.
Otherwise, the function returns false
.
eq
and ne
operators when applied to two values of type
xs:NOTATION
. Returns true
if the two xs:NOTATION
values have the same
namespace URI and the same local part.
The function returns true
if the namespace URIs of $arg1
and
$arg2
are equal and the local names of $arg1
and
$arg2
are equal.
Otherwise, the function returns false
.
The namespace URI parts are considered equal if they are both fn:codepointequal
function.
The local parts are also compared under the rules of the fn:codepointequal
function.
The prefix parts of $arg1
and $arg2
, if any, are ignored.
Returns the name of a node, as an xs:string
that is either the zerolength
string, or has the lexical form of an xs:QName
.
If the argument is omitted, it defaults to the context item (.
).
If the argument is supplied and is the empty sequence, the function returns the zerolength string.
If the node identified by $node
has no name (that is, if it is a document
node, a comment, a text node, or a namespace node having no name), the function returns
the zerolength string.
Otherwise, the function returns the value of the expression
fn:string(fn:nodename($node))
.
The following errors may be raised when $node
is omitted:
If the context item is
If the context item is not a node, type error
Because the result depends on the choice of namespace prefixes in the source document,
it is not good practice to use the result of this function for anything other than display
purposes. For example, the test name(.) = 'my:profile'
will fail if the source
document uses an unexpected namespace prefix. Such a test (assuming it relates to an element node)
is better written as boolean(self::my:profile)
.
Returns the local part of the name of $node
as an xs:string
that is either the zerolength string, or has the lexical form of an
xs:NCName
.
If the argument is omitted, it defaults to the context item (.
).
If the argument is supplied and is the empty sequence, the function returns the zerolength string.
If the node identified by $node
has no name (that is, if it is a document
node, a comment, a text node, or a namespace node having no name), the function returns
the zerolength string.
Otherwise, the function returns the local part of the expandedQName of the node
identified by $node
, as determined by the dm:nodename
accessor
defined in xs:string
whose lexical form is an xs:NCName
.
The following errors may be raised when $node
is omitted:
If the context item is
If the context item is not a node, type error
Returns the namespace URI part of the name of $node
, as an
xs:anyURI
value.
If the argument is omitted, it defaults to the context node (.
).
If the node identified by $node
is neither an element nor an attribute node,
or if it is an element or attribute node whose expandedQName (as determined by the
dm:nodename
accessor in the xs:anyURI
value.
Otherwise, the result will be the namespace URI part of the expandedQName of the node
identified by $node
, as determined by the dm:nodename
accessor
defined in xs:anyURI
value.
The following errors may be raised when $node
is omitted:
If the context item is
If the context item is not a node, type error
Returns the value indicated by $value
or, if $value
is not
specified, the context item after atomization, converted to an xs:double
.
Calling the zeroargument version of the function is defined to give the same result as
calling the singleargument version with the context item (.
). That is,
fn:number()
is equivalent to fn:number(.)
, as defined by
the rules that follow.
If $value
is the empty sequence or if $value
cannot be converted
to an xs:double
, the xs:double
value NaN
is
returned.
Otherwise, $value
is converted to an xs:double
following the
rules of xs:double
fails, the xs:double
value NaN
is returned.
A dynamic error is raised $value
is omitted and the context item is
As a consequence of the rules given above, a type error occurs if the context item cannot be atomized, or if the result of atomizing the context item 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
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.
Assume that the context item is the xs:string
value "15"
.
Then fn:number()
returns 1.5e1
.
This function tests whether the language of $node
, or the context item if
the second argument is omitted, as specified by xml:lang
attributes is the
same as, or is a sublanguage of, the language specified by $language
.
The behavior of the function if the second argument is omitted is exactly the same as if
the context item (.
) had been passed as the second argument.
The language of the argument $node
, or the context item if the second
argument is omitted, is determined by the value of the xml:lang
attribute
on the node, or, if the node has no such attribute, by the value of the
xml:lang
attribute on the nearest ancestor of the node that has an
xml:lang
attribute. If there is no such ancestor, then the function
returns false
.
If $language
is the empty sequence it is interpreted as the zerolength
string.
The relevant xml:lang
attribute is determined by the value of the XPath
expression:
If this expression returns an empty sequence, the function returns false
.
Otherwise, the function returns true
if and only if, based on a caseless
default match as specified in section 3.13 of
$language
is equal to the stringvalue of the relevant
xml:lang
attribute, or
$language
is equal to some substring of the stringvalue of the
relevant xml:lang
attribute that starts at the start of the
stringvalue and ends immediately before a hyphen, 
(HYPHENMINUS, #x002D
).
The following errors may be raised when $node
is omitted:
If the context item is
If the context item is not a node, type error
The expression fn:lang("en")
would return true
if the
context node were any of the following four elements:
<para xml:lang="en"/>
<div xml:lang="en"><para>And now, and
forever!</para></div>
<para xml:lang="EN"/>
<para xml:lang="enus"/>
The expression fn:lang("fr")
would return false
if the
context node were <para xml:lang="EN"/>
Returns a path expression that can be used to select the supplied node relative to the root of its containing document.
The behavior of the function if the argument is omitted is exactly the same as if the
context item (.
) had been passed as the argument.
If $node
is the empty sequence, the function returns the empty sequence.
If $node
is a document node, the function returns the string
"/"
.
Otherwise, the function returns a string that consists of a sequence of steps, one
for each ancestororself of $node
other than the root node. This string is
prefixed by "Q{http://www.w3.org/2005/xpathfunctions}root()"
if the root
node is not a document node. Each step consists of the character "/"
followed by a string whose form depends on the kind of node selected by that step, as
follows:
For an element node,
Q{
,
where
is the namespace URI of the node name or the
empty string if the node is in no namespace,
is
the local part of the node name, and
is an
integer representing the position of the selected node among its likenamed
siblings.
For an attribute node:
if the node is in no namespace, @
, where
is the local part of the node name
otherwise, @Q{
, where
is the namespace URI of the node name,
and
is the local part of the node name
For a text node: text()[
where
is an integer representing the position
of the selected node among its text node siblings
For a comment node: comment()[
where
is an integer representing the position
of the selected node among its comment node siblings
For a processinginstruction node:
processinginstruction(
where
is the name of the processing instruction
node and
is an integer representing the
position of the selected node among its likenamed processinginstruction node
siblings
For a namespace node:
If the namespace node has a name:
namespace::
, where
is the local part of the name of the
namespace node (which represents the namespace prefix).
If the namespace node has no name (that is, it represents the default
namespace):
namespace::*[Q{http://www.w3.org/2005/xpathfunctions}localname()=""]
The following errors may be raised when $node
is omitted:
If the context item is
If the context item is not a node, type error
Returns the root of the tree to which $node
belongs. This will usually, but
not necessarily, be a document node.
If the function is called without an argument, the context item (.
) is used
as the default argument.
The function returns the value of the expression
($arg/ancestororself::node())[1]
.
The following errors may be raised when $node
is omitted:
If the context item is
If the context item is not a node, type error
These examples use some variables which could be defined in
Or they could be defined in
fn:root($i)
returns the element node $i
fn:root($o/quantity)
returns the element node $o
fn:root($odoc//quantity)
returns the document node $odoc
fn:root($newi)
returns the element node $o
The final three examples could be made typesafe by wrapping their operands with
fn:exactlyone()
.
Returns true
if the supplied node has one or more child nodes (of any kind).
If the argument is omitted, it defaults to the context item (.
).
Provided that the supplied argument $node
matches the expected type
node()?
, the result of the function call
fn:haschildren($node)
is defined to be the same as the result of the
expression fn:exists($node/child::node())
.
The following errors may be raised when $node
is omitted:
If the context item is
If the context item is not a node, type error
If $node
is an empty sequence the result is false
.
The motivation for this function is to support streamed evaluation. According to the
streaming rules in
This is because it makes two downward selections to read the child row
elements. The use of fn:haschildren
in the xsl:if
conditional
is intended to circumvent this restriction.
Although the function was introduced to support streaming use cases, it has general utility as a convenience function.
Returns every node within the input sequence that is not an ancestor of another member of the input sequence; the nodes are returned in document order with duplicates eliminated.
The effect of the function call fn:innermost($nodes)
is defined to be
equivalent to the result of the expression:
That is, the function takes as input a sequence of nodes, and returns every node within the sequence that is not an ancestor of another node within the sequence; the nodes are returned in document order with duplicates eliminated.
If the source document contains nested sections represented by div
elements, the expression innermost(//div)
returns those div
elements that do not contain further div
elements.
Returns every node within the input sequence that has no ancestor that is itself a member of the input sequence; the nodes are returned in document order with duplicates eliminated.
The effect of the function call fn:outermost($nodes)
is defined to be
equivalent to the result of the expression:
That is, the function takes as input a sequence of nodes, and returns every node within the sequence that does not have another node within the sequence as an ancestor; the nodes are returned in document order with duplicates eliminated.
The formulation $nodes except $nodes/descendant::node()
might appear to be
simpler, but does not correctly account for attribute nodes, as these are not
descendants of their parent element.
The motivation for the function was based on XSLT streaming use cases. There are cases
where the outermost(//section)
but do not allow //section
; the
function can therefore be useful in cases where it is known that sections will not be
nested, as well as cases where the application actually wishes to process all sections
except those that are nested within another.
If the source document contains nested sections represented by div
elements, the expression outermost(//div)
returns those div
elements that are not contained within further div
elements.
Returns a sequence of positive integers giving the positions within the sequence
$input
of items that are equal to $search
.
The function returns a sequence of positive integers giving the positions within the
sequence $input
of items that are equal to $search
.
The collation used by this function is determined according to the rules in
The items in the sequence $input
are compared with $search
under
the rules for the eq
operator. Values of type xs:untypedAtomic
are compared as if they were of type xs:string
. Values that cannot be
compared, because the eq
operator is not defined for their types, are
considered to be distinct. If an item compares equal, then the position of that item in
the sequence $input
is included in the result.
The first item in a sequence is at position 1, not position 0.
The result sequence is in ascending numeric order.
If $input
is the empty sequence, or if no item in
$input
matches $search
, then the function returns the empty
sequence.
No error occurs if noncomparable values are encountered. So when comparing two atomic
values, the effective boolean value of fn:indexof($a, $b)
is true
if
$a
and $b
are equal, false
if they are not equal or not
comparable.
If @a
is an attribute of type xs:NMTOKENS
whose string
value is "red green blue"
, and whose typed value is therefore
("red", "green", "blue")
, then fn:indexof(@a, "blue")
returns 3
. This is because the function calling mechanism atomizes the
attribute node to produce a sequence of three xs:NMTOKEN
values.
Returns true
if the argument is the empty sequence.
If $input
is the empty sequence, the function returns
true
; otherwise, the function returns false
.
Assuming $in
is an element with no children:
The result is false()
.
Returns true
if the argument is a nonempty sequence.
If $input
is a nonempty sequence, the function returns
true
; otherwise, the function returns false
.
Assuming $in
is an element with no children:
The result is true()
.
Returns the values that appear in a sequence, with duplicates eliminated.
The function returns the sequence that results from removing from $values
all
but one of a set of values that are considered equal to one another.
fn:deepequal($J, $K, $coll)
is true
,
where $coll
is the collation selected according to the rules in
The order in which the sequence of values is returned is
Which value of a set of values that compare equal is returned is
If the input sequence contains values of different numeric types that differ from each
other by small amounts, then the eq operator is not transitive, because of rounding
effects occurring during type promotion. In the situation where the input contains three
values A
, B
, and C
such that A eq B
,
B eq C
, but A ne C
, then the number of items in the result
of the function (as well as the choice of which items are returned) is
For example, this arises when computing:
because the values of type xs:float
and xs:double
both compare
equal to the value of type xs:decimal
but not equal to each other.
If $values
is the empty sequence, the function returns the empty sequence.
Values of type xs:untypedAtomic
are compared as if they were of type
xs:string
.
Values that cannot be compared, because the eq
operator is not defined for
their types, are considered to be distinct.
For xs:float
and xs:double
values, positive zero is equal to
negative zero and, although NaN
does not equal itself, if $values
contains multiple NaN
values a single NaN
is returned.
If xs:dateTime
, xs:date
or xs:time
values do not
have a timezone, they are considered to have the implicit timezone provided by the
dynamic context for the purpose of comparison. Note that xs:dateTime
,
xs:date
or xs:time
values can compare equal even if their
timezones are different.
xs:integer
2 or the xs:decimal
2.0Returns the values that appear in a sequence more than once.
The items of $values
are compared against each other, according to the
rules of fn:distinctvalues
and with $coll
as the collation
selected according to the rules in
From each resulting set of values that are considered equal, one value will be returned if the set contains more than one value.
The order in which the sequence of values is returned is
Which value of a set of values that compare equal is returned is
The effect of the function is equivalent to the following XSLT expression:
The following XQuery expression is equivalent if no collation is specified
(group by
requires collation URIs to be static):
xs:integer
, xs:decimal
or xs:decimal
value of the input sequence."1"
and the untyped value of the
element node are considered equal, whereas the string "2"
and the integer are considered unequal.Raise an error for duplicates in an ID sequence:
Returns its argument value.
The function returns $input
.
The function is useful in contexts where a function must be supplied, but no processing is required.
Returns a sequence constructed by inserting an item or a sequence of items at a given position within an existing sequence.
The value returned by the function consists of all items of $input
whose
1based position is less than $position
, followed by all items of
$insert
, followed by the remaining elements of $input
, in
that order.
If $input
is the empty sequence, $insert
is returned. If
$insert
is the empty sequence, $input
is returned.
If $position
is less than one (1), the first position, the effective value
of $position
is one (1). If $position
is greater than the
number of items in $input
, then the effective value of
$position
is equal to the number of items in $input
plus
1.
The value of $input
is not affected by the sequence construction.
Returns a new sequence containing all the items of $input
The function returns a sequence consisting of all items of $input
$positions
.
More formally, the function returns the result of the expression $input[not(position() = $positions)]
.
Any integer in $positions
that is less than 1 or greater than the number of items in
$input
is effectively ignored.
If $input
is the empty sequence, the empty sequence is returned.
If $positions
is an empty sequence, the input sequence $input
is returned unchanged.
Returns the first item in a sequence.
The function returns the value of the expression $input[1]
If $input
is the empty sequence, the empty sequence is returned. Otherwise
the first item in the sequence is returned.
Returns all but the first item in a sequence.
The function returns the value of the expression subsequence($input, 2)
If $input
is the empty sequence, or a sequence containing a single item, then
the empty sequence is returned.
Returns all but the last item in a sequence.
The function returns the value of the expression fn:remove($input, count($input))
If $input
is the empty sequence, or a sequence containing a single item, then
the empty sequence is returned.
Produces multiple copies of a sequence.
The function returns the value of (1 to $count) ! $input
.
If $input
is the empty sequence, the empty sequence is returned.
The $count
argument is declared as xs:nonNegativeInteger
,
which means that a type error occurs if it is called with a negative value.
If the input sequence contains nodes, these are not copied: instead, the result sequence contains
multiple references to the same node. So, for example, fn:count(fn:replicate(/, 6)())
returns 1
, because the fn:replicate
call creates duplicates, and the
union operation eliminates them.
[TODO: the use of type xs:nonNegativeInteger
for the second argument
assumes we will accept the proposal to allow downcasting in the coercion rules for
function arguments. MHK 20221004.]
Inserts a separator between adjacent items in a sequence.
The function returns the value of head($input), tail($input) ! ($separator, .)
.
If $input
contains less than two items then it is returned unchanged.
If $separator
is the empty sequence then $input
is returned unchanged.
For example, in XQuery, fn:intersperse(para, <hr/>)
would insert
an empty hr
element between adjacent paragraphs.
Returns the last item in a sequence.
The function returns the value of the expression $input[position() = last()]
If $input
is the empty sequence the empty sequence is returned.
Reverses the order of items in a sequence.
The function returns a sequence containing the items in $input
in reverse
order.
If $input
is the empty sequence, the empty sequence is returned.
Returns the contiguous sequence of items in $input
beginning at the position indicated by $start
and
continuing for the number of items indicated by $length
.
In the twoargument case
In the threeargument case, the function returns:
The first item of a sequence is located at position 1, not position 0.
If $input
is the empty sequence, the empty sequence is returned.
In the twoargument case, the function returns a sequence comprising those items of
$input
whose 1based position
is greater than or equal to $start
(rounded to an integer).
No error occurs if $start
is zero or negative.
In the threeargument case, The function returns a sequence comprising those items of
$input
whose 1based position
is greater than or equal to $start
(rounded to an integer), and
less than the sum of $start
and $length
(both rounded to integers).
No error occurs if $start
is zero or negative, or if $start
plus $length
exceeds the number of items in the sequence, or if
$length
is negative.
As a consequence of the general rules, if $start
is
INF
and $length
is +INF
, then
fn:round($start) + fn:round($length)
is NaN
; since
position() lt NaN
always returns false
, the result is an empty sequence.
The reason the function accepts arguments of type xs:double
is that many
computations on untyped data return an xs:double
result; and the reason for
the rounding rules is to compensate for any imprecision in these floatingpoint
computations.
Returns a sequence containing the items from $input
at positions defined by $at
, in the order specified.
Returns the value of $at ! fn:subsequence($input, ., 1)
The effect of the function is to return those items from $items
at the positions given by the integers in $at
, in the order
represented by the integers in $at
.
In the simplest case where $at
is a single integer,
fn:itemsat($input, 3)
returns the same result as $input[3]
.
Compared with a simple positional filter expression, the function is useful because:
It can select items at multiple positions, and unlike fn:subsequence
,
these do not need to be contiguous.
The $at
expression can depend on the focus.
The order of the returned items can differ from their order in the $input
sequence.
If any integer in $at
is outside the range 1 to count($input)
, that integer
is effectively ignored: no error occurs.
If either of the arguments is an empty sequence, the result is an empty sequence.
Returns a sequence containing selected items from a supplied input sequence based on their position.
If $input
is the empty sequence, the function returns the empty sequence.
Let $S
be the first of the following that applies:
If $start
is absent, empty, or zero, then 1.
If $start
is negative, then fn:count($input) + $start + 1
.
Otherwise, $start
.
Let $E
be the first of the following that applies:
If $end
is absent, empty, or zero, then fn:count($input)
.
If $end
is negative, then fn:count($input) + $end + 1
.
Otherwise, $end
.
Let $STEP
be the first of the following that applies:
If $step
is absent, empty, or zero, then:
If $E ge $S
, then +1
Otherwise 1
Otherwise, $step
.
If $STEP
is negative, the function returns
$input => fn:reverse() => fn:slice($S, $E, $STEP)
.
Otherwise the function returns the result of the expression:
The function is inspired by the slice operators in Javascript and Python, but it differs
in detail to accommodate the tradition of 1based addressing in XPath. The end position is
inclusive rather than exclusive, so that in the simple case where $start
and
$end
are positive and $end > $start
,
fn:slice($in, $start, $end)
returns the same result as $in[position() = $start to $end]
.
Determines whether one sequence starts with another, using a supplied callback function to compare items.
Informally, the function returns true
if $input
starts with $subsequence
,
when items are compared using the supplied (or default) $compare
function.
More formally, the function returns the value of the expression:
There is no requirement that the $compare
function should have the traditional qualities
of equality comparison. The result is welldefined, for example, even if $compare
is not transitive
or not symmetric.
")//p[2]
return startswithsequence(
$p/ancestor::*[1],
$p/parent::*,
op("is")
)]]>
"a"
.
Determines whether one sequence ends with another, using a supplied callback function to compare items.
Informally, the function returns true
if $input
ends with $subsequence
,
when items are compared using the supplied (or default) $compare
function.
More formally, the function returns the value of the expression:
There is no requirement that the $compare
function should have the traditional qualities
of equality comparison. The result is welldefined, for example, even if $compare
is not transitive
or not symmetric.
")//p[2]
return endswithsequence(
$p/ancestor::node()[last()],
$p/root(),
op("is")
)]]>
Determines whether one sequence contains another as a contiguous subsequence, using a supplied callback function to compare items.
Informally, the function returns true
if $input
contains a consecutive subsequence matching $subsequence
,
when items are compared using the supplied (or default) $compare
function.
More formally, the function returns the value of the expression:
There is no requirement that the $compare
function should have the traditional qualities
of equality comparison. The result is welldefined, for example, even if $compare
is not transitive
or not symmetric.
p
children of the chap
element form a contiguous subsequence."a"
.
Returns the items of $input
in an
The function returns the items of $input
in an
Query optimizers may be able to do a better job if the order of the output sequence is not specified. For example, when retrieving prices from a purchase order, if an index exists on prices, it may be more efficient to return the prices in index order rather than in document order.
Absorbs the argument.
The function absorbs the supplied $input
argument and
returns an empty sequence.
The function can be used to discard unneeded output of expressions (functions, thirdparty libraries, etc.).
It can also be used to discard results during development.
The function is utilized by builtin functions such as map:get
to return an empty sequence for arbitrary input.
It is
Returns input
if it contains zero or one items. Otherwise, raises an
error.
Except in error cases, the function returns $input
unchanged.
A dynamic error is raised $input
contains more than one item.
Returns $input
if it contains one or more items. Otherwise, raises an error.
Except in error cases, the function returns $input
unchanged.
A dynamic error is raised $input
is an
empty sequence.
Returns $input
if it contains exactly one item. Otherwise, raises an error.
Except in error cases, the function returns $input
unchanged.
A dynamic error is raised $input
is an
empty sequence or a sequence containing more than one item.
This function assesses whether two sequences are deepequal to each other. To be
deepequal, they must contain items that are pairwise deepequal; and for two items to
be deepequal, they must either be atomic values that compare equal, or nodes of the
same kind, with the same name, whose children are deepequal
The $collation
argument identifies a collation which is used at all levels
of recursion when strings are compared (but not when names are compared), according to
the rules in
The $options
argument, if present, defines additional parameters controlling
how the comparison is done. The
If the two sequences are both empty, the function returns true
.
If the two sequences are of different lengths, the function returns
false
.
If the two sequences are of the same length, the function returns true
if
and only if every item in the sequence $input1
is deepequal to the
item at the same position in the sequence $input2
. The rules for
deciding whether two items are deepequal appear below.
The entries that may appear in the $options
map are as follows. The detailed rules
for the interpretation of each option appear later.
baseuri
of a node is significant.
false
.
When this option is set and the two inputs are found to be not equal, the implementation
true
, then in the event of a dynamic error occurring in the course of
the comparison, the function will return false
rather than throwing the error. (This option does
not affect the handling of errors in the supplied values of the $collation
and $options
arguments.)
id
property of elements and attributes is significant.
idrefs
property of elements and attributes is significant.
xs:QName
values (particularly
the names of elements and attributes) are significant.
nilled
property of elements and attributes is significant.
fn:normalizeunicode
.
preserve
retains all whitespace. The value strip
ignores text nodes
consisting entirely of whitespace.
The value normalize
ignores whitespace text nodes in the same way as
the strip
option, and additionally compares text and attribute nodes after
normalizing whitespace in accordance with the rules of the fn:normalizespace
function. The detailed rules, given below, also take into account type annotations and
xml:space
attributes.
As a general rule for boolean options (but not invariably), the value true
indicates
that the comparison is more strict.
In the following rules, where a recursive call on fn:deepequal
is made, this is assumed
to use the same values of $collation
and $options
as the original call.
The rules reference a function equalstrings
which compares two strings as follows:
If the whitespace
option is set to normalize
, then each string is processed
by calling the fn:normalizespace
function.
If the normalizationform
option is present, each string is then normalized
by calling the fn:normalizeunicode
function, supplying the specified normalization
form.
The two strings are then compared for equality under the requested $collation
.
More formally, the equalstrings
function can be expressed as follows:
The rules for deciding whether two items $i1
and $i2
are deepequal
are as follows. The two items are deepequal
if one or more of the following conditions are true:
All of the following conditions are true:
$i1
is an atomic value.
$i2
is an atomic value.
Either the typeannotations
option is false
, or both atomic values have
the same type annotation.
One of the following conditions is true:
If both $i1
and $i2
are instances of
xs:string
or xs:untypedAtomic
,
equalstrings($i1, $i2, $collation, $options)
returns true
.
If both $i1
and $i2
are instances of
xs:date
, xs:time
or xs:dateTime
,
$i1 eq $i2
returns true
.
Otherwise, fn:atomicequal($i1, $i2)
returns true
.
If $i1
and $i2
are not comparable, that is,
if the expression ($i1 eq $i2)
would raise an error, then the function
returns false
; it does not report an error.
One of the following conditions is true:
Option namespaceprefixes
is false
.
Neither $i1
nor $i2
is of type
xs:QName
or xs:NOTATION
.
$i1
and $i2
are qualified names with the same namespace prefix.
One of the following conditions is true:
Option timezones
is false
.
Neither $i1
nor $i2
is of type
xs:date
, xs:time
, xs:dateTime
,
xs:gYear
, xs:gYearMonth
, xs:gMonth
,
xs:gMonthDay
, or xs:gDay
.
Neither $i1
nor $i2
has a timezone component.
Both $i1
and $i2
have a timezone component and the
timezone components are equal.
All of the following conditions are true:
$i1
is a map.
$i2
is a map.
Both maps have the same number of entries.
For every entry in the first map, there is an entry in the second map that:
has the
has the same associated value (compared using the fn:deepequal
function, recursively).
All the following conditions are true:
$i1
is an array.
$i2
is an array.
Both arrays have the same number of members (array:size($i1) eq
array:size($i2)
).
Members in the same position of both arrays are deepequal to each other: that is,
every $p in 1 to array:size($i1) satisfies deepequal($i1($p), $i2($p),
$collation, $options).
All the following conditions are true:
$i1
is a function item and is not a map or array.
$i2
is a function item and is not a map or array.
$i1
and $i2
have the same function identity.
The concept of function identity is explained in
All the following conditions are true:
$i1
is a node.
$i2
is a node.
Both nodes have the same node kind.
Either the baseuri
option is false
, or both nodes have the same value
for their base URI property, or both nodes have an absent base URI.
Let significantchildren($parent)
be the sequence of nodes obtained by applying the following
steps to the children of $parent
, in turn:
Comment nodes are discarded if the option comments
is false
.
Processing instruction nodes are discarded if the option processinginstructions
is false
.
Adjacent text nodes are merged.
Whitespaceonly text nodes are discarded if both the following conditions are true:
Either:
The option whitespace
is set to strip
or normalize
; or
$parent
is a schemavalidated element node whose type annotation
is a complex type with an elementonly or empty content model.
The text node is not within the scope
of an element that has the attribute xml:space="preserve"
.
One of the following conditions is true.
Both nodes are document nodes, and the sequence significantchildren($i1)
is deepequal to the sequence significantchildren($i2)
.
Both nodes are element nodes, and all the following conditions are true:
The two nodes have the same name, that is (nodename($i1) eq
nodename($i2))
.
Either the option namespaceprefixes
is false
, or both element
names have the same prefix.
Either the option inscopenamespaces
is false
, or both element
nodes have the same inscope namespace bindings.
Either the option typeannotations
is false
, or both
element nodes have the same type annotation.
Either the option idproperty
is false
, or both element
nodes have the same value for their isid
property.
Either the option idrefsproperty
is false
, or both element
nodes have the same value for their isidrefs
property.
Either the option nilledproperty
is false
, or both element
nodes have the same value for their nilled
property.
One of the following conditions is true:
The option typevariety
is false
.
Both nodes are annotated as having simple content.
For this purpose
Both nodes are annotated as having complex content. For this purpose
It is a consequence of this rule that, by default, validating a document D against a schema will usually (but not necessarily) result in a document that is not deepequal to D. The exception is when the schema allows all elements to have mixed content.
The two nodes have the same number of attributes, and for every attribute
$a1
in $i1/@*
there exists an attribute
$a2
in $i2/@*
such that $a1
and
$a2
are deepequal.
One of the following conditions holds:
Both element nodes are annotated as having simple content (as defined
above), the typedvalues
option is true
,
and the typed value of $i1
is deepequal
to the typed value of $i2
.
The typed value of an element node is used only when the element has simple content, which means that no error can occur as a result of atomizing a node with no typed value.
Both element nodes are annotated as having simple content (as defined
above), the typedvalues
option is false
,
and the equalstrings
function returns true
when
applied to the string value of $i1
and the string value of $i2
.
Both element nodes have a type annotation that is a complex type with
elementonly, mixed, or empty content,
the (common) element name is not present in the unorderedelements
option,
and the sequence significantchildren($i1)
is
deepequal to the sequence significantchildren($i2)
.
Both element nodes have a type annotation that is a complex type with
elementonly, mixed, or empty content,
the (common) element name is present in the unorderedelements
option,
and the sequence significantchildren($i1)
is
deepequal to some permutation of the sequence significantchildren($i2)
.
Elements annotated as xs:untyped
fall into this category.
Including an element name in the unorderedelements
list is unlikely
to be useful except when the relevant elements have elementonly content, but
this is not a requirement: the rules apply equally to elements with mixed content,
or even (trivially) to elements with empty content.
Both nodes are attribute nodes, and all the following conditions are true:
The two attribute nodes have the same name, that is (nodename($i1) eq
nodename($i2))
.
Either the option namespaceprefixes
is false
, or both
attribute names have the same prefix.
Either the option typeannotations
is false
, or both
attribute nodes have the same type annotation.
Either the option idproperty
is false
, or both attribute nodes
have the same value for their isid
property.
Either the option idrefsproperty
is false
, or both attribute nodes
have the same value for their isidrefs
property.
Either the option typedvalue
is false
, or
the typed value of $i1
is deepequal to the typed value of
$i2
.
Either the option typedvalue
is true
, or
the equalstrings
function returns true
when applied to the string value of $i1
and the string value of $i2
.
Both nodes are processing instruction nodes, and all the following conditions are true:
The two nodes have the same name, that is (nodename($i1) eq
nodename($i2))
.
The equalstrings
function returns true
when applied to
the string value of $i1
and the string value of $i2
.
Both nodes are namespace nodes, and all the following conditions are true:
The two nodes either have the same name or are both nameless, that is
fn:deepequal(nodename($i1), nodename($i2))
.
The string value of $i1
is equal to the string value of
$i2
when compared using the Unicode codepoint collation.
Namespace nodes are not considered directly unless they appear in the toplevel sequences
passed explicitly to the fn:deepequal
function.
Both nodes are comment nodes, and the equalstrings
function
returns true
when applied to their string values.
Both nodes are text nodes, and the equalstrings
function
returns true
when applied to their string values.
In all other cases the result is false
.
A type error is raised
However, the above error is not raised if the falseonerror
option is
true
; in this case, the function returns false
rather than raising an error.
A type error is raised $options
includes an entry whose key is defined
in this specification, and whose value is not of the permitted type for that key.
A dynamic error is raised $options
includes an entry whose key is defined
in this specification, and whose value is not a permitted value for that key.
By default, whitespace in text nodes and attribute is considered significant. There are various ways whitespace differences can be ignored:
If nodes have been schemavalidated, setting the typedvalues
option to true causes the typed values rather
than the string values to be compared. This will typically cause whitespace to be ignored
except where the type of the value is xs:string
.
Setting the whitespace
option to normalize
causes all
text and attribute nodes to have leading and trailing whitespace removed, and intermediate
whitespace reduced to a single character.
By default, two nodes are not required to have the same type annotation, and they are not
required to have the same inscope namespaces. They may also differ in their parent,
their base URI, and the values returned by the isid
and
isidrefs
accessors (see
By default, the contents of comments and processing instructions are significant only if these nodes appear directly as items in the two sequences being compared. The content of a comment or processing instruction that appears as a descendant of an item in one of the sequences being compared does not affect the result. However, the presence of a comment or processing instruction, if it causes a text node to be split into two text nodes, may affect the result.
Comparing items of different kind (for example, comparing an atomic
value to a node, or a map to an array, or an integer to an xs:date
) returns false
,
it does not return an error. So
the result of fn:deepequal(1, currentdateTime())
is false
.
Comparing a function (other than a map or array) to any other value raises a type error,
unless the error is suppressed using the falseonerror
option.
unorderedelements
option means that the ordering of the children
of a
is ignored.style
attribute
and the whitespace text node preceding the span
element are significant.whitespace
option causes both the leading space
in the attribute value and the whitespace preceding the
span
element to be ignored.Returns the number of items in a sequence.
The function returns the number of items in $input
.
returns 0
.if $input
is the empty sequence.
Returns the average of the values in the input sequence $values
, that is, the
sum of the values divided by the number of values.
If $values
is the empty sequence, the empty sequence is returned.
If $values
contains values of type xs:untypedAtomic
they are cast
to xs:double
.
Duration values must either all be xs:yearMonthDuration
values or must all
be xs:dayTimeDuration
values. For numeric values, the numeric promotion
rules defined in $values
must satisfy the following condition:
There must be a type T such that:
every item in $values
is an instance of T.
T is one of xs:double
, xs:float
,
xs:decimal
, xs:yearMonthDuration
, or
xs:dayTimeDuration
.
The function returns the average of the values as sum($values) div
count($values)
; but the implementation may use an otherwise equivalent algorithm
that avoids arithmetic overflow.
A type error is raised
xs:decimal
.fn:avg(($d1, $seq3))
raises a type error
Returns a value that is equal to the highest value appearing in the input sequence.
The following conversions are applied to the input sequence $values
, in order:
Values of type xs:untypedAtomic
in $values
are cast to
xs:double
.
If the resulting sequence contains values that are instances of more than one primitive type
(meaning the 19 primitive types defined in
If each value is an instance of one of the types xs:string
or xs:anyURI
,
then all the values are cast to type xs:string
.
If each value is an instance of one of the types xs:decimal
or xs:float
,
then all the values are cast to type xs:float
.
If each value is an instance of one of the types xs:decimal
, xs:float
,
or xs:double
, then all the values are cast to type xs:double
.
Otherwise, a type error is raised
The primitive type of an xs:integer
value for this purpose is xs:decimal
.
The items in the resulting sequence may be reordered in an arbitrary order. The resulting sequence is referred to below as the converted sequence. The function returns an item from the converted sequence rather than the input sequence.
If the converted sequence is empty, the function returns the empty sequence.
All items in the converted sequence must be derived from a single base type for which
the le
operator is defined. In addition, the values in the sequence must
have a total order. If date/time values do not have a timezone, they are considered to
have the implicit timezone provided by the dynamic context for the purpose of
comparison. Duration values must either all be xs:yearMonthDuration
values
or must all be xs:dayTimeDuration
values.
If the converted sequence contains the value NaN
, the value
NaN
is returned
xs:float
or xs:double
as appropriate)
If the items in the converted sequence are of type xs:string
or types
derived by restriction from xs:string
, then the determination of the item
with the smallest value is made according to the collation that is used. If the type of
the items in the converted sequence is not xs:string
and
$collation
is specified, the collation is ignored.
The collation used by this function is determined according to the rules in
The function returns the result of the expression:
evaluated with $collation
as the default collation if specified, and with
$c
as the converted sequence.
A type error is raised
Because the rules allow the sequence to be reordered, if there are two or more items that are
“equal highest”, the specific item whose value is returned is xs:dateTime
values compare equal despite being in different timezones.
If the converted sequence contains exactly one value then that value is returned.
The default type when the fn:max
function is applied to
xs:untypedAtomic
values is xs:double
. This differs from the
default type for operators such as gt
, and for sorting in XQuery and XSLT,
which is xs:string
.
The rules for the dynamic type of the result are stricter in version 3.1 of the specification than
in earlier versions. For example, if all the values in the input sequence belong to types derived from
xs:integer
, version 3.0 required only that the result be an instance
of the least common supertype of the types present in the input sequence; Version 3.1
requires that the returned value retains its original type. This does not apply, however, where type promotion
is needed to convert all the values to a common primitive type.
fn:max((3,4,"Zero"))
raises a type error
Returns a value that is equal to the lowest value appearing in the input sequence.
The following rules are applied to the input sequence:
Values of type xs:untypedAtomic
in $values
are cast to
xs:double
.
If the resulting sequence contains values that are instances of more than one primitive type
(meaning the 19 primitive types defined in
If each value is an instance of one of the types xs:string
or xs:anyURI
,
then all the values are cast to type xs:string
.
If each value is an instance of one of the types xs:decimal
or xs:float
,
then all the values are cast to type xs:float
.
If each value is an instance of one of the types xs:decimal
, xs:float
,
or xs:double
, then all the values are cast to type xs:double
.
Otherwise, a type error is raised
The primitive type of an xs:integer
value for this purpose is xs:decimal
.
The items in the resulting sequence may be reordered in an arbitrary order. The resulting sequence is referred to below as the converted sequence. The function returns an item from the converted sequence rather than the input sequence.
If the converted sequence is empty, the empty sequence is returned.
All items in the converted sequence must be derived from a single base type for which
the le
operator is defined. In addition, the values in the sequence must
have a total order. If date/time values do not have a timezone, they are considered to
have the implicit timezone provided by the dynamic context for the purpose of
comparison. Duration values must either all be xs:yearMonthDuration
values
or must all be xs:dayTimeDuration
values.
If the converted sequence contains the value NaN
, the value
NaN
is returned
xs:float
or xs:double
as appropriate)
If the items in the converted sequence are of type xs:string
or types
derived by restriction from xs:string
, then the determination of the item
with the smallest value is made according to the collation that is used. If the type of
the items in the converted sequence is not xs:string
and
$collation
is specified, the collation is ignored.
The collation used by this function is determined according to the rules in
The function returns the result of the expression:
evaluated with $collation
as the default collation if specified, and with
$c
as the converted sequence.
A type error is raised
Because the rules allow the sequence to be reordered, if there are two or items that are
“equal lowest”, the specific item whose value is returned is xs:dateTime
values compare equal despite being in different timezones.
If the converted sequence contains exactly one value then that value is returned.
The default type when the fn:min
function is applied to
xs:untypedAtomic
values is xs:double
. This differs from the
default type for operators such as lt
, and for sorting in XQuery and XSLT,
which is xs:string
.
The rules for the dynamic type of the result are stricter in version 3.1 of the specification than
in earlier versions. For example, if all the values in the input sequence belong to types derived from
xs:integer
, version 3.0 required only that the result be an instance
of the least common supertype of the types present in the input sequence; Version 3.1
requires that the returned value retains its original type. This does not apply, however, where type promotion
is needed to convert all the values to a common primitive type.
fn:min((xs:float(0.0E0), xs:float(0.0E0)))
can return either positive
or negative zero. The two items are equal, so it is
fn:min((3,4,"Zero"))
raises a type error
Returns a value obtained by adding together the values in $values
.
Any values of type xs:untypedAtomic
in $values
are cast to
xs:double
. The items in the resulting sequence may be reordered in an
arbitrary order. The resulting sequence is referred to below as the converted
sequence.
If the converted sequence is empty, then the function returns
the value of the argument $zero
, which defaults to
the xs:integer
value 0
.
If the converted sequence contains the value NaN
, NaN
is
returned.
All items in $values
must be numeric or derived from a single base type. In
addition, the type must support addition. Duration values must either all be
xs:yearMonthDuration
values or must all be
xs:dayTimeDuration
values. For numeric values, the numeric promotion
rules defined in xs:double
will be an
xs:double
.
The result of the function is the value of the expression:
where $c
is the converted sequence.
The result of the function fn:sum($arg, 0)
.
A type error is raised
The second argument allows an appropriate value to be defined to represent the sum of an empty sequence. For example, when summing a sequence of durations it would be appropriate to return a zerolength duration of the appropriate type. This argument is necessary because a system that does dynamic typing cannot distinguish “an empty sequence of integers", for example, from “an empty sequence of durations”.
The explicit or implicit value of
the $zero
argument is used only when the input sequence is empty, not
when a nonempty sequence sums to zero. For example, sum((1, +1), xs:double('NaN'))
returns the xs:integer
value 0
, not NaN
.
If the converted sequence contains exactly one value then that value is returned.
$zero
value should be
the same type as the items in $value
, or even that it should belong to
a type that supports addition.fn:sum(($d1, 9E1))
raises a type error
Returns the sequence of element nodes that have an ID
value matching the
value of one or more of the IDREF
values supplied in $values
.
The function returns a sequence, in document order with duplicates eliminated,
containing every element node E
that satisfies all the following
conditions:
E
is in the target document. The target document is the document
containing $node
, or the document containing the context item
(.
) if the second argument is omitted. The behavior of the
function if $node
is omitted is exactly the same as if the context
item had been passed as $node
.
E
has an ID
value equal to one of the candidate
IDREF
values, where:
An element has an ID
value equal to V
if either
or both of the following conditions are true:
The isid
property (See true
, and the typed value
of the element node is equal to V
under the rules of the
eq
operator using the Unicode codepoint collation
(http://www.w3.org/2005/xpathfunctions/collation/codepoint
).
The element has an attribute node whose isid
property
(See true
and whose typed
value is equal to V
under the rules of the
eq
operator using the Unicode code point collation
(http://www.w3.org/2005/xpathfunctions/collation/codepoint
).
Each xs:string
in $values
is parsed as if it were of
type IDREFS
, that is, each xs:string
in
$values
is treated as a whitespaceseparated sequence of
tokens, each acting as an IDREF
. These tokens are then included
in the list of candidate IDREF
s. If any of the tokens is not a
lexically valid IDREF
(that is, if it is not lexically an
xs:NCName
), it is ignored. Formally, the candidate
IDREF
values are the strings in the sequence given by the
expression:
If several elements have the same ID
value, then E
is
the one that is first in document order.
A dynamic error is raised $node
, or the context item if the second argument is absent, is a node
in a tree whose root is not a document node.
The following errors may be raised when $node
is omitted:
If the context item is
If the context item is not a node, type error
The effect of this function is anomalous in respect of element nodes with the
isid
property. For legacy reasons, this function returns the element
that has the isid
property, whereas it would be more appropriate to return
its parent, that being the element that is uniquely identified by the ID. A new function
fn:elementwithid
has been introduced with the desired
behavior.
If the data model is constructed from an Infoset, an attribute will have the
isid
property if the corresponding attribute in the Infoset had an
attribute type of ID
: typically this means the attribute was declared as an
ID
in a DTD.
If the data model is constructed from a PSVI, an element or attribute will have the
isid
property if its typed value is a single atomic value of type
xs:ID
or a type derived by restriction from xs:ID
.
No error is raised in respect of a candidate IDREF
value that does not
match the ID
of any element in the document. If no candidate
IDREF
value matches the ID
value of any element, the
function returns the empty sequence.
It is not necessary that the supplied argument should have type xs:IDREF
or xs:IDREFS
, or that it should be derived from a node with the
isidrefs
property.
An element may have more than one ID
value. This can occur with synthetic
data models or with data models constructed from a PSVI where the element and one of its
attributes are both typed as xs:ID
.
If the source document is wellformed but not valid, it is possible for two or more
elements to have the same ID
value. In this situation, the function will
select the first such element.
It is also possible in a wellformed but invalid document to have an element or
attribute that has the isid
property but whose value does not conform to
the lexical rules for the xs:ID
type. Such a node will never be selected by
this function.
xml:id
attribute has the isid
property,
so the employee element is selected.empnr
element is given the type
xs:ID
as a result of schema validation, the element will have the
isid
property and is therefore selected. Note the difference from
the behavior of fn:elementwithid
. Returns the sequence of element nodes that have an ID
value matching the
value of one or more of the IDREF
values supplied in $values
.
The effect of this function is identical to fn:id
in respect of
elements that have an attribute with the isid
property. However, it
behaves differently in respect of element nodes with the isid
property.
Whereas the fn:id
function, for legacy reasons, returns the element that has the
isid
property, this function returns the element identified by the ID,
which is the parent of the element having the isid
property.
The function returns a sequence, in document order with duplicates eliminated,
containing every element node E
that satisfies all the following
conditions:
E
is in the target document. The target document is the document
containing $node
, or the document containing the context item
(.
) if the second argument is omitted. The behavior of the
function if $node
is omitted is exactly the same as if the context
item had been passed as $node
.
E
has an ID
value equal to one of the candidate
IDREF
values, where:
An element has an ID
value equal to V
if either
or both of the following conditions are true:
The element has an child element node whose isid
property (See true
and
whose typed value is equal to V
under the rules of the
eq
operator using the Unicode code point collation
(http://www.w3.org/2005/xpathfunctions/collation/codepoint
).
The element has an attribute node whose isid
property
(See true
and whose typed
value is equal to V
under the rules of the
eq
operator using the Unicode code point collation
(http://www.w3.org/2005/xpathfunctions/collation/codepoint
).
Each xs:string
in $values
is parsed as if it were of
type IDREFS
, that is, each xs:string
in
$values
is treated as a whitespaceseparated sequence of
tokens, each acting as an IDREF
. These tokens are then included
in the list of candidate IDREF
s. If any of the tokens is not a
lexically valid IDREF
(that is, if it is not lexically an
xs:NCName
), it is ignored. Formally, the candidate
IDREF
values are the strings in the sequence given by the
expression:
If several elements have the same ID
value, then E
is
the one that is first in document order.
A dynamic error is raised $node
, or the context item if the second argument is omitted, is a node
in a tree whose root is not a document node.
The following errors may be raised when $node
is omitted:
If the context item is
If the context item is not a node, type error
This function is equivalent to the fn:id
function except when dealing with
IDvalued element nodes. Whereas the fn:id
function selects the element
containing the identifier, this function selects its parent.
If the data model is constructed from an Infoset, an attribute will have the
isid
property if the corresponding attribute in the Infoset had an
attribute type of ID
: typically this means the attribute was declared as an
ID
in a DTD.
If the data model is constructed from a PSVI, an element or attribute will have the
isid
property if its typed value is a single atomic value of type
xs:ID
or a type derived by restriction from xs:ID
.
No error is raised in respect of a candidate IDREF
value that does not
match the ID
of any element in the document. If no candidate
IDREF
value matches the ID
value of any element, the
function returns the empty sequence.
It is not necessary that the supplied argument should have type xs:IDREF
or xs:IDREFS
, or that it should be derived from a node with the
isidrefs
property.
An element may have more than one ID
value. This can occur with synthetic
data models or with data models constructed from a PSVI where the element and one of its
attributes are both typed as xs:ID
.
If the source document is wellformed but not valid, it is possible for two or more
elements to have the same ID
value. In this situation, the function will
select the first such element.
It is also possible in a wellformed but invalid document to have an element or
attribute that has the isid
property but whose value does not conform to
the lexical rules for the xs:ID
type. Such a node will never be selected by
this function.
xml:id
attribute has the isid
property,
so the employee element is selected.empnr
element is given the type
xs:ID
as a result of schema validation, the element will have the
isid
property and is therefore its parent is selected. Note the
difference from the behavior of fn:id
.Returns the sequence of element or attribute nodes with an IDREF
value
matching the value of one or more of the ID
values supplied in
$values
.
The function returns a sequence, in document order with duplicates eliminated,
containing every element or attribute node $N
that satisfies all the
following conditions:
$N
is in the target document. The target document is the document
containing $node
or the document containing the context item
(.
) if the second argument is omitted. The behavior of the
function if $node
is omitted is exactly the same as if the context
item had been passed as $node
.
$N
has an IDREF
value equal to one of the candidate
ID
values, where:
A node $N
has an IDREF
value equal to
V
if both of the following conditions are true:
The isidrefs
property (see $N
is true
.
The sequence
contains a string that is
equal to V
under the rules of the eq
operator using the Unicode code point collation
(http://www.w3.org/2005/xpathfunctions/collation/codepoint
).
Each xs:string
in $values
is parsed as if it were of
lexically of type xs:ID
. These xs:string
s are then
included in the list of candidate xs:ID
s. If any of the strings
in $values
is not a lexically valid xs:ID
(that is,
if it is not lexically an xs:NCName
), it is ignored. More
formally, the candidate ID
values are the strings in the
sequence:
A dynamic error is raised $node
, or the context item if the second argument is omitted, is a node
in a tree whose root is not a document node.
The following errors may be raised when $node
is omitted:
If the context item is
If the context item is not a node, type error
An element or attribute typically acquires the isidrefs
property by being
validated against the schema type xs:IDREF
or xs:IDREFS
, or
(for attributes only) by being described as of type IDREF
or
IDREFS
in a DTD.
Because the function is sensitive to the way in which the data model is constructed, calls on this function are not always interoperable.
No error is raised in respect of a candidate ID
value that does not match
the IDREF
value of any element or attribute in the document. If no
candidate ID
value matches the IDREF
value of any element or
attribute, the function returns the empty sequence.
It is possible for two or more nodes to have an IDREF
value that matches a
given candidate ID
value. In this situation, the function will return all
such nodes. However, each matching node will be returned at most once, regardless how
many candidate ID
values it matches.
It is possible in a wellformed but invalid document to have a node whose
isidrefs
property is true
but that does not conform to the lexical
rules for the xs:IDREF
type. The effect of the above rules is that
illformed candidate ID
values and illformed IDREF
values are
ignored.
If the data model is constructed from a PSVI, the typed value of a node that has the
isidrefs
property will contain at least one atomic value of type
xs:IDREF
(or a type derived by restriction from xs:IDREF
).
It may also contain atomic values of other types. These atomic values are treated as
candidate ID
values xs:NCName
, and there must be at least one instance of xs:IDREF
in the typed value of the node. If these conditions are not satisfied, such values are ignored.
manager
has the isidref property, the call on fn:idref
selects
the manager
element. If, instead, the manager
had a ref
attribute with the isidref property, the call on fn:idref
would select the attribute node.employee/deputy
has the isidref property, the call on fn:idref
selects
the deputy
element.Retrieves a document using a URI supplied as an xs:string
, and returns the
corresponding document node.
If $href
is the empty sequence, the result is an empty sequence.
If $href
is a relative URI reference, it is resolved relative to the value
of the xs:string
.
If the
The URI may include a fragment identifier.
By default, this function is true
:
However, for performance reasons, implementations may provide a user option to evaluate
the function without a guarantee of determinism. The manner in which any such option is
provided is implementationdefined. If the user has not selected such an option, a call
of the function must either return a deterministic result or must raise a dynamic error
If $href
is read from a source document, it is generally appropriate to
resolve it relative to the base URI property of the relevant node in the source
document. This can be achieved by calling the fn:resolveuri
function,
and passing the resulting absolute URI as an argument to the fn:doc
function.
If two calls to this function supply different absolute URI References as arguments, the same document node may be returned if the implementation can determine that the two arguments refer to the same resource.
By defining the semantics of this function in terms of a stringtodocumentnode
mapping in the dynamic context, the specification is acknowledging that the results of
this function are outside the purview of the language specification itself, and depend
entirely on the runtime environment in which the expression is evaluated. This runtime
environment includes not only an unpredictable collection of resources (“the web”), but
configurable machinery for locating resources and turning their contents into document
nodes within the XPath data model. Both the set of resources that are reachable, and the
mechanisms by which those resources are parsed and validated, are
One possible processing model for this function is as follows. The resource identified
by the URI Reference is retrieved. If the resource cannot be retrieved, a dynamic error
is raised "text"
, the content is parsed in the same way as if the media type were text/xml;
otherwise, it is parsed in the same way as if the media type were application/xml. If
the contents cannot be parsed successfully, a dynamic error is raised
Various aspects of this processing are
The set of URI schemes that the implementation recognizes is implementationdefined. Implementations may allow the mapping of URIs to resources to be configured by the user, using mechanisms such as catalogs or userwritten URI handlers.
The handling of nonXML media types is implementationdefined. Implementations may allow instances of the data model to be constructed from nonXML resources, under user control.
It is
Implementations may provide userdefined error handling options that allow processing to continue following an error in retrieving a resource, or in parsing and validating its content. When errors have been handled in this way, the function may return either an empty sequence, or a fallback document provided by the error handler.
Implementations may provide user options that relax the requirement for the function to return deterministic results.
The effect of a fragment identifier in the supplied URI
is
A dynamic error $href
is not a valid URI
A dynamic error is raised
A dynamic error is raised
A dynamic error is raised
A dynamic error is raised
The function returns true
if and only if the function call fn:doc($href)
would return a document node.
If $href
is an empty sequence, this function returns false
.
If a call on fn:doc($href)
would return a document node, this function
returns true
.
In all other cases this function returns false
.
If this function returns true
, then calling fn:doc($href)
within the same fn:doc
function,
this guarantee is lost.
Returns a sequence of items identified by a collection URI; or a default collection if no URI is supplied.
This function takes an xs:string
as argument and returns a sequence of
$uri
as an xs:anyURI
and
resolving it according to the mapping specified in
If
If $uri
is not specified, the function returns the sequence of
If $uri
is a relative xs:anyURI
, it is resolved
against the value of the baseURI property from the static context.
If $uri
is the empty sequence, the function behaves as if it had been
called without an argument. See above.
By default, this function is
There is no requirement that
A dynamic error is raised
A dynamic error is raised
A dynamic error is raised
A dynamic error $uri
is not
a valid xs:anyURI
.
In earlier versions of this specification, the primary use for the fn:collection
function
was to retrieve a collection of XML documents, perhaps held as lexical XML in operating
system filestore, or perhaps held in an XML database. In this release the concept has
been generalised to allow other resources to be retrieved: for example JSON documents might
be returned as arrays or maps, nonXML text files might be returned as strings, and binary
files might be returned as instances of xs:base64Binary
.
The abstract concept of a collection might be realized in different ways by different implementations, and the ways in which URIs map to collections can be equally variable. Specifying resources using URIs is useful because URIs are dynamic, can be parameterized, and do not rely on an external environment.
Returns a sequence of xs:anyURI
values representing the URIs in a URI
collection.
The zeroargument form of the function returns the URIs in the
If $uri
is a relative xs:anyURI
, it is resolved
against the value of the baseURI property from the static context.
If $uri
is the empty sequence, the function behaves as if it had been
called without an argument. See above.
The singleargument form of the function returns the sequence of URIs corresponding to
the supplied URI in the
By default, this function is
There is no requirement that the URIs returned by this function should all be distinct, and no assumptions can be made about the order of URIs in the sequence, unless the implementation defines otherwise.
A dynamic error is raised
A dynamic error is raised
A dynamic error is raised
A dynamic error $uri
is not
a valid xs:anyURI
.
In some implementations, there might be a close relationship between fn:collection
function), and
Thus, some implementations might ensure that calling fn:uricollection
and then
applying fn:doc
to each of the returned URIs delivers the same result as
calling fn:collection
with the same argument; however, this is not
guaranteed.
In the case where fn:uricollection
returns the URIs of resources that
could also be retrieved directly using fn:collection
, there are several reasons why it
might be appropriate to use this function in preference
to the fn:collection
function. For example:
It allows different URIs for different kinds of resource to be dereferenced in
different ways: for
example, the returned URIs might be referenced using the
fn:unparsedtext
function rather than the fn:doc
function.
In XSLT 3.0 it allows the documents in a collection to be processed in streaming mode using the
xsl:stream
instruction.
It allows recovery from failures to read, parse, or validate individual documents,
by calling the fn:doc
(or other dereferencing) function within the scope of try/catch.
It allows selection of which documents to read based on their URI, for example
they can be filtered to select those whose URIs end in .xml
, or those
that use the https
scheme.
An application might choose to limit the number of URIs processed in a single run, for example it might process only the first 50 URIs in the collection; or it might present the URIs to the user and allow the user to select which of them need to be further processed.
It allows the URIs to be modified before they are dereferenced, for example by adding or removing query parameters, or by redirecting the request to a local cache or to a mirror site.
For some of these use cases, this assumes that the cost of calling
fn:collection
might be significant (for example, it might involving
retrieving all the documents in the collection over the network and parsing them). This
will not necessarily be true of all implementations.
The fn:unparsedtext
function reads an external resource (for example, a
file) and returns a string representation of the resource.
The $href
argument
The mapping of URIs to the string representation of a resource is the mapping defined in
the
If the $href
argument is an empty sequence, the function
returns an empty sequence.
The $encoding
argument, if present
encoding
attribute in
an XML declaration. The only values which every
implementation is utf8
and utf16
.
The encoding of the external resource is determined as follows:
external encoding information is used if available, otherwise
if the media type of the resource is text/xml
or
application/xml
(see text/*+xml
or application/*+xml
(see
the $encoding
argument is used if present, otherwise
the processor
UTF8 is assumed.
The result of the function is a string containing the string representation of the resource retrieved using the URI.
A dynamic error is raised $href
argument
contains a fragment identifier,
A dynamic error is raised $encoding
argument is not a valid encoding name, if the
processor does not support the specified encoding, if
the string representation of the retrieved resource contains octets that cannot be
decoded into Unicode
A dynamic error is raised $encoding
is absent and the processor cannot infer the
encoding using external information and the encoding is not UTF8.
If it is appropriate to use a base URI other than the dynamic base URI (for example,
when resolving a relative URI reference read from a source document) then it is
advisable to resolve the relative URI reference using the fn:resolveuri
function before passing it to the fn:unparsedtext
function.
There is no essential relationship between the sets of URIs accepted by the two
functions fn:unparsedtext
and fn:doc
(a URI accepted by one
may or may not be accepted by the other), and if a URI is accepted by both there is no
essential relationship between the results (different resource representations are
permitted by the architecture of the web).
There are no constraints on the MIME type of the resource.
The fact that the resolution of URIs is defined by a mapping in the dynamic context
means that in effect, various aspects of the behavior of this function are
The set of URI schemes that the implementation recognizes is implementationdefined. Implementations may allow the mapping of URIs to resources to be configured by the user, using mechanisms such as catalogs or userwritten URI handlers.
The handling of media types is implementationdefined.
Implementations may provide userdefined error handling options that allow processing to continue following an error in retrieving a resource, or in reading its content. When errors have been handled in this way, the function may return a fallback document provided by the error handler.
Implementations may provide user options that relax the requirement for the function to return deterministic results.
The rules for determining the encoding are chosen for consistency with
If the text file contains characters such as <
and &
,
these will typically be output as <
and &
if
the string is serialized as XML or HTML. If these characters actually represent markup
(for example, if the text file contains HTML), then an XSLT stylesheet can attempt to
write them as markup to the output file using the disableoutputescaping
attribute of the xsl:valueof
instruction. Note, however, that XSLT
implementations are not required to support this feature.
This XSLT example attempts to read a file containing “boilerplate” HTML and copy it directly to the serialized output file:
The fn:unparsedtextlines
function reads an external resource (for
example, a file) and returns its contents as a sequence of strings, one for each line of
text in the string representation of the resource.
The unparsedtextlines
function reads an external resource (for example, a
file) and returns its string representation as a sequence of strings, separated at
newline boundaries.
The result of the singleargument function is the same as the result of the expression
fn:tokenize(fn:unparsedtext($href), '\r\n\r\n')[not(position()=last() and
.='')]
. The result of the twoargument function is the same as the result of
the expression fn:tokenize(fn:unparsedtext($href, $encoding),
'\r\n\r\n')[not(position()=last() and .='')]
.
The result is thus a sequence of strings containing the text of the resource retrieved using the URI, each string representing one line of text. Lines are separated by one of the sequences x0A, x0D, or x0Dx0A. The characters representing the newline are not included in the returned strings. If there are two adjacent newline sequences, a zerolength string will be returned to represent the empty line; but if the external resource ends with the sequence x0A, x0D, or x0Dx0A, the result will be as if this final line ending were not present.
Error conditions are the same as for the fn:unparsedtext
function.
See the notes for fn:unparsedtext
.
Because errors in evaluating the fn:unparsedtext
function are
nonrecoverable, these two functions are provided to allow an application to determine
whether a call with particular arguments would succeed.
The fn:unparsedtextavailable
function determines whether a call
on the fn:unparsedtext
function with identical arguments would
return a string.
If the first argument is an empty sequence, the function returns false
.
In other cases, the function returns true
if a call on
fn:unparsedtext
with the same arguments would succeed, and
false
if a call on fn:unparsedtext
with the same arguments would
fail with a nonrecoverable dynamic error.
The functions fn:unparsedtext
and
fn:unparsedtextavailable
have the same requirement for
fn:doc
and fn:docavailable
. This means that unless the
user has explicitly stated a requirement for a reduced level of determinism, either of
these functions if called twice with the same arguments during the course of a
transformation fn:unparsedtextavailable
unparsedtext
with the same arguments.
This requires that the fn:unparsedtextavailable
function should
actually attempt to read the resource identified by the URI, and check that it is
correctly encoded and contains no characters that are invalid in XML. Implementations
may avoid the cost of repeating these checks for example by caching the validated
contents of the resource, to anticipate a subsequent call on the
fn:unparsedtext
or fn:unparsedtextlines
function. Alternatively, implementations may be able to rewrite an expression such as
if (unparsedtextavailable(A)) then unparsedtext(A) else ...
to
generate a single call internally.
Since the function fn:unparsedtextlines
succeeds or fails under
exactly the same circumstances as fn:unparsedtext
, the
fn:unparsedtextavailable
function may equally be used to test
whether a call on fn:unparsedtextlines
would succeed.
Returns the value of a system environment variable, if it exists.
The set of available
If the $name
argument matches the name of one of these pairs, the function
returns the corresponding value.
If there is no environment variable with a matching name, the function returns the empty sequence.
The collation used for matching names is
The function is
On many platforms, the term “environment variable” has a natural meaning in terms of facilities provided by the operating system. This interpretation of the concept does not exclude other interpretations, such as a mapping to a set of configuration parameters in a database system.
Environment variable names are usually case sensitive. Names are usually of the form
(letter_) (letter_digit)*
, but this varies by platform.
On some platforms, there may sometimes be multiple environment variables with the same
name; in this case, it is implementationdependent as to which is returned; see for
example
The requirement to ensure that the function is deterministic means in practice that the implementation must make a snapshot of the environment variables at some time during execution, and return values obtained from this snapshot, rather than using live values that are subject to change at any time.
Operating system environment variables may be associated with a particular process,
while queries and stylesheets may execute across multiple processes (or multiple
machines). In such circumstances implementations
Security advice: Queries from untrusted sources should not be permitted unrestricted
access to environment variables. For example, the name of the account under which the
query is running may be useful information to a wouldbe intruder. An implementation may
therefore choose to restrict access to the environment, or may provide a facility to
make fn:environmentvariable
always return the empty sequence.
Returns a list of environment variable names that are suitable for passing to
fn:environmentvariable
, as a (possibly empty) sequence of strings.
The function returns a sequence of strings, being the names of the environment variables
in the dynamic context in some
The function is
The function returns a list of strings, containing no duplicates.
It is intended that the strings in this list should be suitable for passing to
fn:environmentvariable
.
See also the note on security under the definition of the
fn:environmentvariable
function. If access to environment variables has
been disabled, fn:availableenvironmentvariables
always returns the empty
sequence.
This function returns a string that uniquely identifies a given node.
If the argument is omitted, it defaults to the context item (.
).
If the argument is the empty sequence, the result is the zerolength string.
In other cases, the function returns a string that uniquely identifies a given node.
fn:codepointequal(fn:generateid($N), fn:generateid($M))
returns true
if and only if ($M is $N)
returns true
.
The returned identifier
The following errors may be raised when $node
is omitted:
If the context item is
If the context item is not a node, type error
An implementation is free to generate an identifier in any convenient way provided that it always generates the same identifier for the same node and that different identifiers are always generated from different nodes. An implementation is under no obligation to generate the same identifiers each time a document is transformed or queried.
There is no guarantee that a generated unique identifier will be distinct from any unique IDs specified in the source document.
There is no inverse to this function; it is not directly possible to find the node with
a given generated ID. Of course, it is possible to search a given sequence of nodes
using an expression such as $nodes[generateid()=$id]
.
It is advisable, but not required, for implementations to generate IDs that are distinct even when compared using a caseblind collation.
The primary use case for this function is to generate hyperlinks. For example, when
generating HTML, an anchor for a given section $sect
can be generated by
writing (in either XSLT or XQuery):
]]>
and a link to that section can then be produced with code such as:
here]]>
Note that anchors generated in this way will not necessarily be the same each time a document is republished.
Since the keys in a map must be atomic values, it is possible to use generated IDs
as surrogates for nodes when constructing a map. For example, in some implementations,
testing whether a node $N
is a member of a large nodeset $S
using the expression fn:exists($N intersect $S)
may be expensive; there
may then be performance benefits in creating a map:
let $SMap := map:merge($S!map{fn:generateid(.) : .})
and then testing for membership of the nodeset using:
map:contains($SMap, generateid($N))
This function takes as input an XML document represented as a string, and returns the document node at the root of an XDM tree representing the parsed document.
If $value
is the empty sequence, the function returns the empty sequence.
The precise process used to construct the XDM instance is
The fn:parsexml
function call is used both as the base URI used by the XML parser to resolve relative
entity references within the document, and as the base URI of the document node that is
returned.
The document URI of the returned node is
The function is
A dynamic error is raised $value
is not a wellformed and namespacewellformed XML document.
A dynamic error is raised $value
is not valid against its DTD.
Since the XML document is presented to the parser as a string, rather than as a sequence of octets, the encoding specified within the XML declaration has no meaning. If the XML parser accepts input only in the form of a sequence of octets, then the processor must ensure that the string is encoded as octets in a way that is consistent with rules used by the XML parser to detect the encoding.
The primary use case for this function is to handle input documents that contain nested
XML documents embedded within CDATA sections. Since the content of the CDATA section are
exposed as text, the receiving query or stylesheet may pass this text to the
fn:parsexml
function to create a tree representation of the nested
document.
Similarly, nested XML within comments is sometimes encountered, and lexical XML is sometimes returned by extension functions, for example, functions that access web services or read from databases.
A use case arises in XSLT where there is a need to preprocess an input document before
parsing. For example, an application might wish to edit the document to remove its
DOCTYPE declaration. This can be done by reading the raw text using the
fn:unparsedtext
function, editing the resulting string, and then
passing it to the fn:parsexml
function.
The expression fn:parsexml("<alpha>abcd</alpha>")
returns a newly
created document node, having an alpha
element as its only child; the
alpha
element in turn is the parent of a text node whose string value
is "abcd"
.
This function takes as input an XML external entity represented as a string, and returns the document node at the root of an XDM tree representing the parsed document fragment.
If $value
is the empty sequence, the function returns the empty sequence.
The input must be a namespacewellformed external general parsed entity. More
specifically, it must be a string conforming to the production rule
The string is parsed to form a sequence of nodes which become children of the new document node, in the same way as the content of any element is converted into a sequence of children for the resulting element node.
Schema validation is
The precise process used to construct the XDM instance is
The fn:parsexmlfragment
function call is used as the base URI of the document node that is returned.
The document URI of the returned node is
The function is
A dynamic error is raised $value
is not a wellformed external general parsed entity, if it contains
entity references other than references to predefined entities, or if a document that
incorporates this wellformed parsed entity would not be namespacewellformed.
See also the notes for the fn:parsexml
function.
The main differences between fn:parsexml
and
fn:parsexmlfragment
are that for fn:parsexml
, the
children of the resulting document node must contain exactly one element node and no
text nodes, wheras for fn:parsexmlfragment
, the resulting document node
can have any number (including zero) of element and text nodes among its children. An
additional difference is that the
Note that all whitespace outside the
One use case for this function is to handle XML fragments stored in databases, which
frequently allow zeroormore top level element nodes. Another use case is to parse the
contents of a CDATA
section embedded within another XML document.
The expression
fn:parsexmlfragment("<alpha>abcd</alpha><beta>abcd</beta>")
returns a newly created document node, having two elements named alpha
and beta
as its children; each of these elements in turn is the parent
of a text node.
The expression fn:parsexmlfragment("He was <i>so</i> kind")
returns a newly created document node having three children: a text node whose string
value is "He was "
, an element node named i
having a child
text node with string value "so"
, and a text node whose string value is
" kind"
.
The expression fn:parsexmlfragment("")
returns a document node having
no children.
The expression fn:parsexmlfragment(" ")
returns a document node whose
children comprise a single text node whose string value is a single space.
The expression fn:parsexmlfragment('<?xml version="1.0" encoding="utf8"
standalone="yes"?><a/>')
results in a dynamic error standalone
keyword is not permitted in the text
declaration that appears at the start of an external general parsed entity. (Thus, it
is not the case that any input accepted by the fn:parsexml
function
will also be accepted by fn:parsexmlfragment
.)
This function serializes the supplied input sequence $input
as described in
The value of the first argument $input
acts as the input sequence to the serialization process,
which starts with sequence normalization.
The second argument $options
, if present, provides serialization parameters. These may be supplied in either
of two forms:
As an output:serializationparameters
element, having the format described in element(output:serializationparameters)
.
As a map. In this case the type of the supplied argument must match the required type map(*)
The singleargument version of this function has the same effect as the twoargument
version called with $options
set to an empty sequence. This in turn is the
same as the effect of passing an output:serializationparameters
element
with no child elements.
The final stage of serialization, that is, encoding, is skipped. If the serializer does not allow this phase to be skipped, then the sequence of octets returned by the serializer is decoded into a string by reversing the character encoding performed in the final stage.
If the second argument is omitted, or is supplied in the form of an output:serializationparameters
element, then the values of any serialization parameters that are not explicitly specified is
If the second argument is supplied as a map, then the
Each entry in the map defines one serialization parameter.
The key of the entry is an xs:string
value in the cases of parameter names defined in these specifications, or an
xs:QName
(with nonabsent namespace) in the case of implementationdefined serialization parameters.
The required type of each parameter, and its default value, are defined by the following table. The default value is used when the map contains no entry for the parameter in question, and also when an entry is present, with the empty sequence as its value. The table also indicates how the value of the map entry is to be interpreted in cases where further explanation is needed.
Parameter  Required type  Interpretation  Default Value 

allowduplicatenames

xs:boolean?

true() means "yes" , false() means "no" 
no

byteordermark

xs:boolean?

true() means "yes" , false() means "no" 
no

cdatasectionelements

xs:QName*

()


doctypepublic

xs:string?

Zerolength string and () both represent "absent" 
absent 
doctypesystem

xs:string?

Zerolength string and () both represent "absent" 
absent 
encoding

xs:string?

utf8


escapesolidus

xs:boolean?

true() means "yes" , false() means "no" 
yes

escapeuriattributes

xs:boolean?

true() means "yes" , false() means "no" 
yes

htmlversion

xs:decimal?

5


includecontenttype

xs:boolean?

true() means "yes" , false() means "no" 
yes

indent

xs:boolean?

true() means "yes" , false() means "no" 
no

itemseparator

xs:string?

absent  
jsonnodeoutputmethod

union(xs:string, xs:QName)?

See Notes 1, 2 
xml

mediatype

xs:string?

(a media type suitable for the chosen method ) 

method

union(xs:string, xs:QName)?

See Notes 1, 2 
xml

normalizationform

xs:string?

none


omitxmldeclaration

xs:boolean?

true() means "yes" , false() means "no" 
yes

standalone

xs:boolean?

true() means "yes" , false() means "no" , () means "omit" 
omit

suppressindentation

xs:QName*

()


undeclareprefixes

xs:boolean?

true() means "yes" , false() means "no" 
no

usecharactermaps

map(xs:string, xs:string)?

See Note 3 
map{}

version

xs:string?

1.0

Notes to the table:
The notation union(A, B)
is used to represent a union type whose member types are A
and B
.
If an xs:QName
is supplied method
or jsonnodeoutputmethod
options,xml
and json
are defined as strings, not as xs:QName
values.
usecharactermaps
optionxs:string
instances),
and whose corresponding values are the strings to be substituted for these characters.
A type error $options
argument
is present and does not match either of the types element(output:serializationparameters)?
or map(*)
.
This is defined as a type error so that it can be enforced via the function signature by implementations that generalize the type system in a suitable way.
If the host language makes serialization an optional feature and the implementation does
not support serialization, then a dynamic error
When the second argument is supplied as a map,
and the supplied value is of the wrong type for the particular parameter, for example if the value of indent
is a string rather than a boolean, then as defined by the usecharactermaps
includes a key that is a string whose length is not one (1)).
If any serialization error occurs, including the detection of an invalid value for a
serialization parameter as described above, this results in the fn:serialize
call failing with
a dynamic error.
One use case for this function arises when there is a need to construct an XML document
containing nested XML documents within a CDATA section (or on occasions within a
comment). See fn:parsexml
for further details.
Another use case arises when there is a need to call an extension function that expects a lexical XML document as input.
Another use case for this function is serializing instances of the data model into a human
readable format for the purposes of debugging. Using the output:serializationparameters
, allows for serializing any valid
XDM instance without raising a serialization error.
There are also use cases where the application wants to postprocess the output of a
query or transformation, for example by adding an internal DTD subset, or by inserting
proprietary markup delimiters such as the <% ... %>
used by some
templating languages.
The ability to specify the serialization parameters in an output:serializationparameters
element provides backwards compatibility with the 3.0 version of this specification; the ability to
use a map takes advantage of new features in the 3.1 version. The default parameter values are
implementationdefined when an output:serializationparameters
element is used (or when the argument is omitted), but are fixed by this specification in the
case where a map (including an empty map) is supplied for the argument.
Given the variables:
The following call might produce the output shown:
The following call would also produce the output shown (though the second argument could equally well be supplied
as an empty map (map{}
), since both parameters are given their default values):
The expression fn:serialize(map{"a":"AB", "b": "BC"}, map{"method":"adaptive"})
returns "map{"a":"AB","b":"BC"}"
The expression fn:serialize(array{"a",3, attribute test {"true"}}, map{"method":"adaptive"})
returns "["a",3,test="true"]"
This function takes as input an HTML document represented as a string, and returns the document node at the root of an XDM tree representing the parsed document.
If $html
is the empty sequence, the function returns the empty sequence.
The method
key of $options
specifies the parsing algorithm,
application, or library to use to construct the XDM nodes from the parsed HTML document.
If the type of $html
is an xs:string
, the encoding is determined
in a way consistent with
The HTML specification uses this for when the encoding of the input byte stream is known for certain, such as when the byte stream has already been decoded.
This means that an implementation should set the encoding to the encoding of the underlying string representation. For example, a Java program could specify the encoding as UTF16. If the implementation supports passing native string values then that can be used instead of using a byte stream and encoding.
Be aware that the WHATWG Encoding specification defines the ISO 88591 (latin1) and ASCII encodings as aliases of the windows1252 encoding.
If the type of $html
is a sequence of octets (xs:hexBinary
or
xs:base64Binary
), the encoding is determined in a way consistent with
encoding
key of $options
is used in step 2 as the user
instructing the user agent to override the document’s character encoding with the
specified encoding.
For any given method
key of $options
the implementation must
use a parser and validator consistent with the htmlversion
key of
$options
.
method  htmlversion  Description 

html  3, 3.2, 4, 4.01  An 
html  5, 5.0, 5.1, 5.2  An HTML5 conformant parsing algorithm, tree construction, and validation consistent
with the specified HTML version. An implementation may choose to use LS
for all these HTML versions. 
html  LS  A parsing algorithm, tree construction, and validation consistent with the

xhtml  1.0, 1.1 
An implementation may choose to use an XML parser to directly construct the
XDM nodes, and then use an An implementation may also choose to use 
*  * 
An This allows an implementation to provide their own method, htmlversion
combinations. For example, an implementation could use the values

The
The function is
A dynamic error is raised $html
is not a wellformed HTML document.
A dynamic error is raised method
key of $options
is not supported by the implementation.
A dynamic error is raised $options
, or the value of that key, is not supported by the implementation.
If the HTML parser accepts a string as the input then that may be used directly when
$html
is an xs:string
instead of converting the string to
a sequence of octets in an
The mapping from the HTML document to the XDM nodes can be done in several ways:
An implementation could construct the XDM nodes directly in the HTML tree construction step of the HTML parsing algorithm.
An implementation could take the DOM tree and interfaces generated by the HTML parser
and adapt those to the XDM accessors. The
An implementation could traverse the HTML document returned by the parsing algorithm and create the corresponding XDM nodes.
The expression parsehtml(())
returns ()
.
The expression parsehtml("<p>Hello</p>")
returns an XDM
document node for a HTML document with a single paragraph within the body element.
The expression parsehtml("<p>Hi</p>", method:="html")
is equivalent to parsehtml("<p>Hi</p>")
.
The expression parsehtml($html, method:="tidy")
could use
the $html
if supported
by the implementation. Otherwise an
The expression parsehtml($html, method:="tagsoup", nons:=true())
could use the $html
if supported
by the implementation, passing the nons
argument to the application.
[TODO: The examples depend on keyword arguments.]
Returns the context position from the dynamic context.
Returns the context position from the dynamic context. (See
A dynamic error is raised
Returns the context size from the dynamic context.
Returns the context size from the dynamic context. (See
A dynamic error is raised
Under most circumstances, the context size is absent only if the context item is absent. However, XSLT 3.0 with streaming defines situations in which the context item and context position are known, but the context size is unknown.
Returns the current date and time (with timezone).
Returns the current dateTime (with timezone) from the dynamic context. (See xs:dateTime
that is current at some time during the evaluation of a
query or transformation in which fn:currentdateTime
is executed.
This function is fn:currentdateTime()
is
If the implementation supports data types from XSD 1.1 then the returned value will be
an instance of xs:dateTimeStamp
. Otherwise, the only guarantees are that it
will be an instance of xs:dateTime
and will have a timezone component.
The returned xs:dateTime
will always have an associated timezone, which
will always be the same as the implicit timezone in the dynamic context
fn:currentdateTime()
returns an xs:dateTimeStamp
corresponding to the current date and time. For example, a call of
fn:currentdateTime()
might return
20040512T18:17:15.125Z
corresponding to the current time on May 12,
2004 in timezone Z
.
Returns the current date.
Returns xs:date(fn:currentdateTime())
. This is an xs:date
(with timezone) that is current at some time during the evaluation of a query or
transformation in which fn:currentdate
is executed.
This function is fn:currentdate
is
The returned date will always have an associated timezone, which will always be the same as the implicit timezone in the dynamic context
fn:currentdate()
returns an xs:date
corresponding to the
current date. For example, a call of fn:currentdate()
might return
20040512+01:00
.
Returns the current time.
Returns xs:time(fn:currentdateTime())
. This is an xs:time
(with timezone) that is current at some time during the evaluation of a query or
transformation in which fn:currenttime
is executed.
This function is fn:currenttime()
is
The returned time will always have an associated timezone, which will always be the same as the implicit timezone in the dynamic context
fn:currenttime()
returns an xs:time
corresponding to the
current time. For example, a call of fn:currenttime()
might return
23:17:00.00005:00
.
Returns the value of the implicit timezone property from the dynamic context.
Returns the value of the implicit timezone property from the dynamic context. Components
of the dynamic context are described in
Returns the value of the default collation property from the
Returns the value of the default collation property from the
The default collation property can never be absent. If it is not explicitly defined, a
system defined default can be invoked. If this is not provided, the Unicode codepoint
collation (http://www.w3.org/2005/xpathfunctions/collation/codepoint
) is
used.
In most cases, the default collation is known statically,
and a call on this function can therefore be preevaluated during static analysis. The only
notable exception is when a call on defaultcollation()
is used to define
the default value of a parameter to a userdefined function. In this case it is interpreted
as a reference to the default collation in the context of the relevant function call,
which may differ from the default collation of the function definition.
Returns the value of the default language property from the dynamic context.
Returns the value of the default language property from the dynamic context. Components
of the dynamic context are described in
The default language property can never be absent. The functions fn:formatinteger
,
fn:formatdate
, fn:formattime
, and fn:formatdateTime
are defined to use the default language if no explicit language is supplied. The default language
may play a role in selection of a default collation, but this is not a requirement.
This function returns the value of the
The function (despite its name)
returns the value of the
Components of the dynamic context are described in
The executable base URI will in many cases be the same as the static base URI in the static context.
However, XQuery and XSLT give an implementation freedom to use different base URIs during
the static analysis phase and the dynamic evaluation phase, that is, for retrieval of compiletime
and runtime resources respectively. This is appropriate when the implementation allows
the output of static analysis (a “compiled” query or stylesheet) to be deployed for execution
to a different location from the one where static analysis took place. In this situation, the
fn:staticbaseuri
function should return a URI suitable for locating
resources needed during dynamic evaluation.
If a call on the fn:staticbaseuri
function appears within the expression used
to define the value of an optional parameter to a userdefined function, then the value supplied
to the function (if the argument is omitted) will be the executable base URI from the dynamic
context of the function caller. This allows such a function to resolve relative URIs supplied
in other parameters to the same function.
Returns
A call to fn:functionlookup
starts by looking for a
fn:functionlookup
),
using the expanded QName supplied as $name
and the arity supplied as
$arity
. There can be at most one such function definition.
If no function definition can be identified (by name and arity), then an empty sequence is returned.
If a function definition is identified, then a function item is obtained from the function
definition using the same rules as for evaluation of a named function reference
(see fn:functionlookup
.
If the arguments to fn:functionlookup
identify a function that is present
in the static context of the function call, the function will always return the same
function that a static reference to this function would bind to. If there is no such
function in the static context, then the results depend on what is present in the
dynamic context, which is
This function can be useful where there is a need to make a dynamic decision on which of several statically known functions to call. It can thus be used as a substitute for polymorphism, in the case where the application has been designed so several functions implement the same interface.
The function can also be useful in cases where a query or stylesheet module is written
to work with alternative versions of a library module. In such cases the author of the
main module might wish to test whether an imported library module contains or does not
contain a particular function, and to call a function in that module only if it is
available in the version that was imported. A static call would cause a static error if
the function is not available, whereas getting the function using
fn:functionlookup
allows the caller to take fallback action in this
situation.
If the function that is retrieved by fn:functionlookup
is fn:functionlookup
function itself. The context thus effectively forms part of the closure of the returned
function. In practice this applies only where the target of
fn:functionlookup
is a builtin function, because userdefined
functions never depend on the static or dynamic context of the function call. The rule
applies recursively, since fn:functionlookup
is itself a contextdependent
builtin function.
However, the static and dynamic context of the call to fn:functionlookup
may play a role even when the selected function definition is not itself context dependent,
if the expressions used to establish default parameter values are context dependent.
The function identity is determined in the same way as for
a named function reference. Specifically, if there is no context dependency, two calls
on fn:functionlookup
with the same name and arity must return the same function.
These specifications do not define any circumstances in which the dynamic context will
contain functions that are not present in the static context, but neither do they rule
this out. For example an API
The mere fact that a function exists and has a name does not of itself mean that the
function is present in the dynamic context. For example, functions obtained through
use of the fn:loadxquerymodule
function are not added to the dynamic context.
The expression (fn:functionlookup(xs:QName('xs:dateTimeStamp'), 1),
xs:dateTime#1)[1] ('20111111T11:11:11Z')
returns an
xs:dateTime
value set to the specified date, time, and timezone; if
the implementation supports XSD 1.1 then the result will be an instance of the
derived type xs:dateTimeStamp
. The query is written to ensure that no
failure occurs when the implementation does not recognize the type
xs:dateTimeStamp
.
The expression
zip:binaryentry($href, $entry)
if the function is available, or
an empty sequence otherwise.
Returns the name of the function identified by a function item.
If $function
refers to a named function, fn:functionname($func)
returns the name of that function.
Otherwise ($function
refers to an anonymous function),
fn:functionname($function)
returns an empty sequence.
The prefix part of the returned QName is
Returns the arity of the function identified by a function item.
The fn:functionarity
function returns the arity (number of arguments) of
the function identified by $function
.
Returns the annotations of the function identified by a function item.
The fn:functionannotations
function returns the annotations of
the function identified by $function
as a map.
For each annotation, a map entry is returned: The key is the name of the annotation.
The value is a sequence comprising the annotation values, or an empty sequence
if the annotation has no values.
If a function (for example, a builtin function) has no annotations,
an empty map is returned.
Applies the function item $action
to every item from the sequence $input
in turn, returning the concatenation of the resulting sequences in order.
The effect of the function is equivalent to the following implementation in XQuery:
or its equivalent in XSLT:
The function call fn:foreach($SEQ, $F)
is equivalent to the expression
for $i in $SEQ return $F($i)
, assuming that ordering mode is
ordered
.
See also array:build
, which provides similar functionality for the
case where the input is a sequence rather than an array.
Returns those items from the sequence $input
for which the supplied function
$predicate
returns true
.
The effect of the function is equivalent to the following implementation in XQuery:
or its equivalent in XSLT:
As a consequence of the function signature and the function calling rules, a type error
occurs if the supplied function $predicate
returns anything other than a single
xs:boolean
item; there is no conversion to an effective boolean
value.
The function call fn:filter($SEQ, $F)
has a very similar effect to the
expression $SEQ[$F(.)]
. There are some differences, however. In the case of
fn:filter
, the function $F
is required to return a boolean;
there is no special treatment for numeric predicate values, and no conversion to an
effective boolean value. Also, with a filter expression $SEQ[$F(.)]
, the
focus within the predicate is different from that outside; this means that the use of a
contextsensitive function such as fn:lang#1
will give different results in
the two cases.
Processes the supplied sequence from left to right, applying the supplied function repeatedly to each item in turn, together with an accumulated result value.
The effect of the function is equivalent to the following implementation in XQuery:
or its equivalent in XSLT:
As a consequence of the function signature and the function calling rules, a type error
occurs if the supplied function $action
cannot be applied to two arguments, where
the first argument is either the value of $zero
or the result of a previous
application of $action
, and the second
is any single item from the sequence $input
.
This operation is often referred to in the functional programming literature as
“folding” or “reducing” a sequence. It takes a function that operates on a pair of
values, and applies it repeatedly, with an accumulated result as the first argument, and
the next item in the sequence as the second argument. The accumulated result is
initially set to the value of the $zero
argument, which is conventionally a
value (such as zero in the case of addition, one in the case of multiplication, or a
zerolength string in the case of string concatenation) that causes the function to
return the value of the other argument unchanged.
true
if any item in the sequence has an effective boolean
value of true
true
only if every item in the sequence has an effective
boolean value of true
Processes the supplied sequence from right to left, applying the supplied function repeatedly to each item in turn, together with an accumulated result value.
The effect of the function is equivalent to the following implementation in XQuery:
or its equivalent in XSLT:
As a consequence of the function signature and the function calling rules, a type error
occurs if the supplied function $action
cannot be applied to two arguments, where
the first argument is any item in the sequence $input
, and the second is either
the value of $zero
or the result of a previous application of
$action
.
This operation is often referred to in the functional programming literature as
“folding” or “reducing” a sequence. It takes a function that operates on a pair of
values, and applies it repeatedly, with the next item in the sequence as the first
argument, and the result of processing the remainder of the sequence as the second
argument. The accumulated result is initially set to the value of the $zero
argument, which is conventionally a value (such as zero in the case of addition, one in
the case of multiplication, or a zerolength string in the case of string concatenation)
that causes the function to return the value of the other argument unchanged.
In cases where the function performs an associative operation on its two arguments (such
as addition or multiplication), fn:foldright
produces the same result as
fn:foldleft
.
Processes a supplied value repeatedly, continuing while some condition remains true, and returning the first value that does not satisfy the condition.
Informally, the function behaves as follows:
The supplied $input
value is tested against the supplied
$predicate
.
If the result of the predicate is true
, $action($input)
is evaluated, the resulting value is used as a new $input
, and the
process repeats from step 1.
If the result of the predicate is false
, the function returns the
value of $input
.
More formally, the function is equivalent to the following implementation in XQuery:
Whileloops are very common in procedural programming languages, and this function provides a way to write functionally clean and interruptible iterations without sideeffects. An initial value is tested and replaced by new values until it matches a given condition. Depending on the use case, the value can be a simple atomic item or an arbitrarily complex data structure.
Note that, just as when writing recursive functions, it is easy to construct infinite loops.
The following example generates random doubles. It is interrupted once a number exceeds a given limit:
Applies the function item $action
to successive pairs of items taken one from
$input1
and one from $input2
, returning the concatenation of the
resulting sequences in order.
The effect of the function is equivalent to the following implementation in XQuery:
or its equivalent in XSLT:
If one sequence is longer than the other, excess items in the longer sequence are ignored.
Sorts a supplied sequence, based on the value of one or more supplied sort keys supplied as functions.
The result of the function is a sequence that contains all the items from $input
,
typically in a different order, the order being defined by one or more
A
A
A xs:string
or xs:untypedAtomic
.
An ascending
or
descending
.
The number of sort key definitions is determined by the number of function items supplied
in the $key
argument. If the argument is absent or empty, the default is
a single sort key definition using the function data#1
.
The $n
'th sort key definition (where $n
counts from one (1))
is established as follows:
The $key[$n] otherwise data#1
.
The $collation[$n] otherwise $collation[last()]
otherwise defaultcollation()
.
That is, it is the collation supplied in the corresponding item of the supplied
$collation
argument; or in its absence, the last entry in
$collation
; or if $collation
is absent or empty, the
default collation from the static context of the caller.
The $order[$n] otherwise $order[last()] otherwise "ascending"
.
That is, it is "ascending"
or "descending"
according
to the value of the corresponding item in the supplied $order
argument; or in its absence, the last entry in $order
; or
if $order
is absent or empty, then "ascending"
.
When comparing values of types other than xs:string
or xs:untypedAtomic
,
the corresponding collation is ignored, and no error is reported if the supplied value is
not a known or valid collation name. If it is necessary to supply such an ignored value
(for example, in the case where a nonstring sort key is followed by another sort key
that requires a collation) the empty string can be supplied.
The result of the function is obtained as follows:
The result sequence contains the same items as the input sequence $input
,
but generally in a different order.
The sort key definitions are established as described above.
The sort key definitions are in majortominor order. That is, the position of two
items $A
and $B
in the result sequence is determined first by the
relative magnitude of their
primary sort key values, which are computed by evaluating the
When a pair of corresponding sort key values of $A
and $B
are
found to be not equal,
then $A
precedes $B
in the result sequence
if both the following conditions are true, or if both conditions are false:
The sort key value for $A
is less than the sort key value for $B
,
as defined below.
The "ascending"
.
If all the sort key values for $A
and $B
are pairwise equal, then
$A
precedes $B
in the result sequence if and only if
$A
precedes $B
in the input sequence.
That is, the sort is
Each sort key value for a given item is obtained by applying the sort key
function of the corresponding sort key definition to that item. The result
of this function is in the general case a sequence of atomic values.
Two sort key values $a
and $b
are compared as follows:
Let $C be the collation in the corresponding sort key definition.
Let $REL
be the result of evaluating op:lexicographiccompare($key($A), $key($B), $C)
where op:lexicographiccompare($a, $b, $C)
is defined as follows:
Here op:simplecompare($k1, $k2)
is defined as follows:
This raises an error if two keys are not comparable, for example
if one is a string and the other is a number, or if both belong to a nonordered
type such as xs:QName
.
If $REL
is zero, then the two sort key values are deemed
equal; if $REL
is 1 then $a
is deemed less than
$b
, and if $REL
is +1 then $a
is deemed greater than
$b
If the set of computed sort keys contains values that are not comparable using the lt
operator then the sort
operation will fail with a type error (
XSLT and XQuery both provide native sorting capability, but earlier releases of XPath provided no sorting functionality for use in standalone environments.
In addition there are cases where this function may be more flexible than the builtin sorting capability for XQuery or XSLT, for example when the sort key or collation is chosen dynamically, or when the sort key is a sequence of items rather than a single item.
The results are compatible with the results of XSLT sorting (using xsl:sort
) in the case where the sort key evaluates to a sequence of
length zero or one, given the options stable="yes"
.
The results are compatible with the results of XQuery sorting (using the order by
clause) in the case where the sort key evaluates to a sequence of
length zero or one, given the options stable
, ascending
, and empty least
.
The function has been enhanced in 4.0 to allow multiple sort keys to be defined, each potentially with a different collation, and to allow sorting in descending order.
The effect of the XQuery option empty leastgreatest
, which controls
whether the empty sequence is sorted before or after all other values, can be achieved by adding an
extra sort key definition that evaluates whether or not the actual sort key is empty (when sorting
boolean values, false
precedes true
).
Supplying too many items in the $collation
and/or $order
arguments
is not an error; the excess values are ignored except for typechecking against the function
signature.
To sort a set of strings $in
using Swedish collation:
To sort a sequence of employees by last name as the major sort key and first name as the minor sort key, using the default collation:
To sort a sequence of employees first by increasing last name (using Swedish collation order) and then by decreasing salary:
Given a function F that navigates from one node to other nodes, returns a function that applies F repeatedly.
The argument is a function $step
that takes a single node as input, and returns a set of nodes as its result.
The result of the fn:transitiveclosure
function is a function TC that takes a
single node N as input, and returns all nodes that can be reached from
N by applying $step
repeatedly between $min
and $max
times (inclusive).
Although $step
may return any sequence of nodes, the result is treated as a set: the order of nodes
in the sequence is ignored, and duplicates are ignored. The result of calling TC will always be
a sequence of nodes in document order with no duplicates.
The default value of $min
, if the argument is not supplied or is set to an empty sequence,
is 1 (one). If $min
is zero, the result of calling TC will include the argument node
N. If $min
is greater than zero, the result will include N only if
N is reachable by a cyclic path involving between $min
and $max
steps.
The default value of $max
, if the argument is not supplied or is set to an empty sequence,
is unbounded. In this situation the function TC continues execution until no further nodes
are added to the result set. Note that if the $step
function constructs new nodes, this
can lead to nontermination. Specifying an explicit value for $max
guarantees termination.
Cycles in the data are not a problem, even if $max
is unbounded;
the function stops searching when it finds no new nodes.
min=1
, or the ancestororself axis if min=0
.The following example, given $root
as the root of an XSLT stylesheet module, returns the URIs
of all stylesheet modules reachable using xsl:import
and xsl:include
declarations:
This example uses the XSLTdefined document()
function.
The following example, given $doc
as the root of a document consisting of nested sections with paths
such as article/section/section/section
, returns the headings of all level2 and level3 sections:
Makes a dynamic call on a function with an argument list supplied in the form of an array.
The result of the function is obtained by invoking the supplied function $function
with arguments
taken from the members of the supplied array $arguments
. The first argument of the function call is the first
member of $arguments
, the second argument is the second member of $array
, and so on.
The arity of the supplied function $function
must be the same as the size of the array $array
.
The effect of calling fn:apply($f, [$a, $b, $c, ...])
is the same as the effect of the dynamic function call
$f($a, $b, $c, ....)
. For example, the function conversion rules are applied to the supplied arguments
in the usual way.
A dynamic error is raised if the arity of the function $function
is not the same as the size of the
array $array
(
The function is useful where the arity of a function item is not known statically.
The expression apply($f, array:subarray(["a", "b", "c", "d", "e", "f"], 1, functionarity($f)))
calls the supplied function $f
supplying the number of arguments required by its arity.
Returns a function whose effect is to apply a supplied binary operator to two arguments.
The supplied operator must be one of:
","
, "and"
, "or"
, "+"
,
""
, "*"
, "div"
, "idiv"
,
"mod"
, "="
, "<"
, "<="
,
">"
, ">="
, "!="
, "eq"
,
"lt"
, "le"
, "gt"
, "ge"
,
"ne"
, "<<"
, ">>"
,
"is"
, ""
, ""
, "union"
,
"except"
, "intersect"
, "to"
,
"otherwise"
The result of calling fn:op("⊙")
, where ⊙
is one of the above operators, is
the function represented by the XPath expression:
function($x, $y) { $x ⊙ $y }
For example, op("+")
returns function($x, $y) { $x + $y }
.
A dynamic error is raised if the supplied argument is not one of the supported operators ([TODO: error code]).
The function is useful in contexts where an arity2 callback function needs to be supplied, and a standard operator meets the requirement.
For example, the XSLT xsl:map
instruction
has an onduplicates
attribute that expects such a function. Specifying
onduplicates="op(',')"
is equivalent to specifying
onduplicates="function($x, $y) { $x, $y }
The function is also useful in cases where the choice of operator to apply is made dynamically.
Determines whether two atomic values are equal, under the rules used for comparing keys in a map.
The function fn:atomicequal
is used to compare two atomic values for equality. This function
has the following properties (which do not all apply to the eq
operator):
Any two atomic values can be compared, regardless of their type.
No dynamic error is ever raised (the result is either true
or false
).
The result of the comparison never depends on the static or dynamic context.
Every value (including NaN
) is equal to itself.
The comparison is symmetric: if A equals B, then B equals A.
The comparison is transitive: if A equals B and B equals C, then A equals C.
The function returns true
if and only if one of the following conditions is true:
All of the following conditions are true:
$value1
is an instance of xs:string
, xs:anyURI
, or xs:untypedAtomic
$value2
is an instance of xs:string
, xs:anyURI
, or xs:untypedAtomic
fn:codepointequal($value1, $value2)
Strings are compared without any dependency on collations.
All of the following conditions are true:
$value1
is an instance of xs:decimal
, xs:double
, or xs:float
$value2
is an instance of xs:decimal
, xs:double
, or xs:float
One of the following conditions is true:
Both $value1
and $value2
are NaN
xs:double('NaN')
is the same key as xs:float('NaN')
Both $value1
and $value2
are positive infinity
xs:double('INF')
is the same key as xs:float('INF')
Both $value1
and $value2
are negative infinity
xs:double('INF')
is the same key as xs:float('INF')
$value1
and $value2
when converted to decimal numbers with no rounding or loss of precision
are mathematically equal.
Every instance of xs:double
, xs:float
, and xs:decimal
can be represented
exactly as a decimal number provided enough digits are available both before and after the decimal point. Unlike the eq
relation, which converts both operands to xs:double
values, possibly losing precision in the process, this
comparison is transitive.
Positive and negative zero compare equal.
All of the following conditions are true:
$value1
is an instance of xs:date
, xs:time
, xs:dateTime
,
xs:gYear
, xs:gYearMonth
, xs:gMonth
, xs:gMonthDay
, or xs:gDay
$value2
is an instance of xs:date
, xs:time
, xs:dateTime
,
xs:gYear
, xs:gYearMonth
, xs:gMonth
, xs:gMonthDay
, or xs:gDay
One of the following conditions is true:
Both $value1
and $value2
have a timezone
Neither $value1
nor $value2
has a timezone
fn:deepequal($value1, $value2)
The use of deepequal
rather than eq
ensures that comparing values of different
types yields false
rather than an error.
All of the following conditions are true:
$value1
is an instance of xs:boolean
, xs:hexBinary
, xs:base64Binary
,
xs:duration
, xs:QName
, or xs:NOTATION
$value2
is an instance of xs:boolean
, xs:hexBinary
, xs:base64Binary
,
xs:duration
, xs:QName
, or xs:NOTATION
fn:deepequal($value1, $value2)
The use of deepequal
rather than eq
ensures that comparing values of different
types yields false
rather than an error.
The internal function op:samekey
was introduced in an earlier version of this specification
for comparing keys within a map.
In this version of the specification, the functionality is unchanged, but the function is exposed so that it
is available directly to applications.
The function is used to assess whether two atomic
values are considered to be duplicates when used as keys in a map. A map cannot
contain two separate entries whose keys are map:get
and map:remove
.
The rules for comparing keys in a map are chosen to ensure that the comparison is:
true
or false
, never an error
Two atomic values may be distinguishable even though they are equal under this comparison. For example: they may have
different type annotations; dates and times may have different timezones; xs:QName
values may have different
prefixes.
As always, any algorithm that delivers the right result is acceptable. For example, when testing whether an xs:double
value D is the same key as an xs:decimal
value that has N significant digits, it is not
necessary to know all the digits in the decimal expansion of D to establish the result: computing the first N+1
significant digits (or indeed, simply knowing that there are more than N significant digits) is sufficient.
op:samekey
function in 3.1Returns a map that combines the entries from a number of existing maps.
The function map:merge
$maps
argument.
Informally, the supplied maps are combined as follows:
There is one entry in the returned map for each distinct key present in the union
of the input maps, where two keys are distinct if they are not the
If there are duplicate keys, that is, if two or more maps contain entries having the
$options
) argument.
The definitive specification is as follows.
The effect of calling the singleargument function is the same as the effect of
calling the twoargument function with an empty map as the value of $options
.
The $options
argument can be used to control the way in which duplicate keys are handled.
The
The entries that may appear in the $options
map are as follows:
$maps
contain entries with key values
K1 and K2 where K1 and K2 are the
$maps
argument.
$maps
argument.
$maps
argument.
The key value in the result map that corresponds to such a set of duplicates must
be the xs:byte(1)
and xs:short(1)
, the key in the result could legitimately be xs:long(1)
.
The result of the function call map:merge($MAPS, $OPTIONS)
is defined to be consistent with the result of the expression:
By way of explanation, $combinemaps
is a function that combines
two maps by iterating over the keys of the second map, adding each key and its corresponding
value to the first map as it proceeds. The second call of fn:foldleft
in the return
clause then iterates over the maps supplied in the call
to map:merge
, accumulating a single map that absorbs successive maps
in the input sequence by calling $combinemaps
.
This algorithm processes the supplied maps in a defined order, but processes the keys within each map in implementationdependent order.
The use of fn:randomnumbergenerator
represents one possible conformant
implementation for "duplicates":"useany"
, but it is not the only conformant
implementation and is not intended to be a realistic implementation. The purpose of this
option is to allow the implementation to use whatever strategy is most efficient; for example,
if the input maps are processed in parallel, then specifying "duplicates":"useany"
means that the implementation does not need to keep track of the original order of the sequence of input
maps.
An error is raised $options
indicates that duplicates are to be rejected, and a duplicate key is encountered.
An error is raised $options
includes an entry whose key is defined
in this specification, and whose value is not a permitted value for that key.
If the input is an empty sequence, the result is an empty map.
If the input is a sequence of length one, the result map is
There is no requirement that the supplied input maps should have the same or compatible
types. The type of a map (for example map(xs:integer, xs:string)
) is
descriptive of the entries it currently contains, but is not a constraint on how the map
may be combined with other maps.
$week
, supplemented with an additional
entry.$week
, with one entry replaced by a
new entry. Both input maps contain an entry with the key 6
; the
one used in the result is the one that comes last in the input
sequence.$week
, with one entry replaced by a
new entry. Both input maps contain an entry with the key 6
; the
one used in the result is the one that comes first in the input
sequence.$week
, with one entry replaced by a
new entry. Both input maps contain an entry with the key 6
; the
entry that appears in the result is the sequenceconcatenation of the entries
in the input maps, retaining order.Returns a map that combines data from a sequence of
The function map:ofpairs
$keyvaluepairs
argument.
The optional $combine
argument can be used to define how
duplicate keys should be handled. The default is to form the sequence concatenation
of the corresponding values, retaining their order in the input sequence.
The effect of the function is equivalent to the expression:
The function can be made to fail with a dynamic error in the event that
duplicate keys are present in the input sequence by supplying a $combine
function that invokes the fn:error
function.
If the input is an empty sequence, the result is an empty map.
There is no requirement that the supplied keyvalue pairs should have the same or compatible
types. The type of a map (for example map(xs:integer, xs:string)
) is
descriptive of the entries it currently contains, but is not a constraint on how the map
may be combined with other maps.
map:ofpairs
is the inverse of
map:pairs
.$week
, supplemented with an additional
entry.$week
, with one entry replaced by a
new entry. Both input maps contain an entry with the key 6
; the
one used in the result combines the two supplied values into a single sequence.$week
, with one entry replaced by a
new entry. Both input maps contain an entry with the key 6
; the
supplied $combine
function ensures that the one used in the result
is the one that comes last in the input sequence.6
is obtained by concatenating the values
from the two input maps, with a separator character.Returns a sequence containing keys present in a map
The function map:keys
takes any $map
argument. The $predicate
function, if
supplied, takes the value of the corresponding map entry as an argument, and the
result is a sequence containing the keys of those entries for which the function
returns true
in
The function is
More formally, the function returns the result of the following expression:
Returns a sequence containing all the values present in a map, in unpredictable order.
The function map:values
takes any $map
argument and returns the values that are present in the map as
a sequence, in
The function is
The effect of the function is equivalent to map:foreach($map, fn($k, $v) { $v })
.
Returns a sequence containing all the keyvalue pairs present in a map, each represented
as a
The function map:entries
takes any $map
argument and returns the keyvalue pairs that are present in the map as
a sequence of
The function is
The effect of the function is equivalent to the expression:
Returns a sequence containing all the keyvalue pairs present in a map, each represented
as a
The function map:pairs
takes any $map
argument and returns the keys that are present in the map as
a sequence of
A keyvalue pair map is an instance of type record(key as xs:anyAtomicType, value as item()*)
:
that is a map with two entries, one (with key "key"
) holding the key,
and the other (with key "value"
) holding the value.
The function is
The effect of the function is equivalent to the expression:
Tests whether a supplied map contains an entry for a given key
The function map:contains
returns true
if the $map
contains an entry with the $key
; otherwise it returns false
.
Returns the value associated with a supplied key in a given map.
The function map:get
attempts to find an entry within the $map
that has
the $key
. If there is such an entry, it returns the associated value;
$fallback
function, supplying
the requested $key
value as the argument, and returns the result of this call.
The default $fallback
function always returns an empty sequence.
A return value of ()
from map:get
could indicate that
the key is present in the map with an associated value of ()
, or it could
indicate that the key is not present in the map. The two cases can be distinguished by
calling map:contains
$fallback
function to return a value known never to appear in the map
The $fallback
function can be used in a number of ways:
It might return a conventional value such as NaN
to indicate that no matching
key was found.
It might raise a dynamic error, by means of a call on fn:error
.
It might compute a result algorithmically. For example, if the map holds a table of
abbreviations, such as map{'CA':'Canada', 'UK':'United Kingdom', 'US':'United States'}
,
then specifying fallback := fn:identity#1
has the effect that the key value is returned
unchanged if it is not found in the map.
Invoking the get
$fallback
function$map
is a map, the expression
$map($K)
is equivalent to map:get($map, $K)
. Similarly, the
expression map:get(map:get(map:get($map, 'employee'), 'name'), 'first')
can
be written as $map('employee')('name')('first')
.
Searches the supplied input sequence and any contained maps and arrays for a map entry with the supplied key, and returns the corresponding values.
The function map:find
searches the sequence supplied as $input
looking for map entries whose key is the $key
. The associated value in any such map entry (each being in general a sequence)
is returned as a member of the result array.
The search processes the $input
sequence using the following recursively defined rules
(any equivalent algorithm may be used provided it delivers
the same result, respecting those rules that constrain the order of the result):
To process a sequence, process each of its items in order.
To process an item that is an array, process each of its members in order (each member is, in general, a sequence).
To process an item that is a map, then for each keyvalue entry (K, V)
in the map (in
If K is the $key
,
then add V as a new member to the end of the result array.
Process V (which is, in general, a sequence).
To process an item that is neither a map nor an array, do nothing. (Such items are ignored).
If $input
is an empty sequence, map, or array, or if the requested $key
is not found,
the result will be a zerolength array.
Returns a map containing all the contents of the supplied map, but with an additional entry, which replaces any existing entry for the same key.
The function map:put
returns $map
,
with the exception of any entry whose key is the $key
, together with a new
entry whose key is $key
and whose associated value is $value
.
The effect of the function call map:put($MAP, $KEY, $VALUE)
is equivalent
to the result of the following steps:
let $MAP2 := map:remove($MAP, $KEY)
This returns a map in which all entries with the same key as $KEY
have been removed.
Construct and return a map containing:
All the entries (key/value pairs) in $MAP2
, and
The entry map:entry($KEY, $VALUE)
There is no requirement that the type of $key
and $value
be consistent with the types
of any existing keys and values in the supplied map.
The function map:entry
returns a $key
, and its associated value is $value
.
The function call map:entry(K, V)
produces the same result as the
expression map{K : V}
.
The function map:entry
is intended primarily for use in conjunction with
the function map:merge
. For example, a map containing seven entries may be
constructed like this:
The map:merge
function can be used to construct
a map with a variable number of entries, for example:
The function map:pair
returns a "key"
)
containing $key
and the other (with the key "value"
)
containing $value
.
The function call map:pair(K, V)
produces the same result as the
expression map { "key": K, "value": V }
.
The function map:pair
is intended primarily for use in conjunction with
the function map:ofpairs
. A map may be constructed like this:
The map:ofpairs
function can be used to construct
a map with a variable number of entries, for example:
Returns a map containing all the entries from a supplied map, except
The function map:remove
returns a $map
except for any entry whose key is
the $keys
.
No failure occurs $keys
does not correspond to any entry in $map
;
that key value is simply ignored
The effect of the function call map:remove($MAP, $KEY)
can be described more formally as the result of the expression below:
Applies a supplied function to every entry in a map, returning the concatenation of the results.
The function map:foreach
takes any $map
argument and applies the supplied function
to each entry in the map, in
The function is
The function supplied as $action
takes two arguments. It is called
supplying the key of the map entry as the first argument, and the associated value as
the second argument.
map:keys
. The
result is in implementationdependent order.This XQuery example converts the entries in a map to attributes on a newly constructed element node:
The result is the element <box height="3" width="4"
depth="5"/>
.
Selects entries from a map, returning a new map.
The function map:filter
takes any $map
argument and applies the supplied function
to each entry in the map; the result is a new map containing those entries for which
the function returns true
.
The function supplied as $predicate
takes two arguments. It is called
supplying the key of the map entry as the first argument, and the associated value as
the second argument.
array:filter
.Returns a map based on the contents of an existing map, computing a new value to be associated with a supplied key.
If the supplied $map
contains an existing entry for the supplied $key
,
then the returned map contains an entry for that $key
whose value is obtained by applying
the supplied $action
to the existing value associated with that key.
Otherwise, the returned map contains an entry for the supplied $key
whose value is
obtained by applying the supplied $action
to an empty sequence.
The effect of the function call map:replace($MAP, $KEY, $VALUE)
is equivalent
to the result of the expression:
Applies a supplied function to every entry in a map, returning a map whose entries have the same keys as the input, but (potentially) different associated values.
The function map:substitute
takes any $map
argument and applies the supplied function
to each entry in the map; the result is a map that associates the original set of key
values with the results of these function calls.
The function supplied as $action
takes two arguments. It is called
supplying the key of the map entry as the first argument, and the associated value as
the second argument.
The function call map:substitute($m, $f)
returns the same result as
map:merge(map:foreach($m, fn($k, $v) { map:entry($k, $f($k, $v)) }))
.
Returns a map that typically contains one entry for each item in a supplied input sequence.
Informally, the function processes each item in $input
in order. It calls the $key
function on
that item to obtain a key value, and the $value
function to obtain an associated value.
If the key is nonempty, then:
If the key is not already present in the target map, the processor adds a new keyvalue pair to the map, with that key and that value.
If the key is already present, the processor calls the $combine
function to combine the existing value
for the key with the new value, and replaces the entry with this combined value.
More formally, the result of the function is the result of the following expression:
Although defined to process the input sequence in order, this is only relevant when combining the entries for duplicate keys.
The default function for both $key
and $value
is the identity function.
Although it is permitted to default both, this serves little purpose: usually at least one of these arguments
will be supplied.
The default action for combining entries with duplicate keys is to perform a sequenceconcatenation of the corresponding values,
equivalent to the duplicates: combine
option on map:merge
. Other potentially useful
functions for combining duplicates include:
fn($a, $b) { $a }
Use the first value and discard the remainder
fn($a, $b) { $b }
Use the last value and discard the remainder
fn:concat(?, ",", ?)
Form the stringconcatenation of the values, commaseparated
fn:op('+')
Compute the sum of the values
. mod 3
. The
function to compute the value is the identity function, and duplicates are combined by
sequence concatenation.fn:formatinteger
.The following expression creates a map whose keys are employee @ssn
values, and whose
corresponding values are the employee nodes:
The following expression creates a map whose keys are employee @location
values, and whose
corresponding values represent the number of employees at each distinct location. Any employees that
lack an @location
attribute will be excluded from the result.
The following expression creates a map whose keys are employee @location
values, and whose
corresponding values contain the employee node for the highestpaid employee at each distinct location:
The following expression creates a map allowing efficient access to every element in a document by means
of its fn:generateid
value:
Returns the number of entries in the supplied map.
The function map:size
takes any $map
argument and returns the number of entries that are present
in the map.
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.
Calling the oneargument version of this function is equivalent to calling the twoargument version supplying the default collation as the second argument.
The function returns an $K1
and $K2
:
collationkey($K1, $C) eq collationkey($K2, $C)
if and only if
compare($K1, $K2, $C) eq 0
collationkey($K1, $C) lt collationkey($K2, $C)
if and only if
compare($K1, $K2, $C) lt 0
The collation used by this function is determined according to the rules in xs:base64Binary
values
to ensure unambiguous and contextfree comparison semantics.
An implementation is free to generate a collation key in any convenient way provided
that it always generates the same collation key for two strings that are equal under the
collation, and different collation keys for strings that are not equal. This holds only
within a single
It is possible to define collations that do not have the ability to generate collation
keys. Supplying such a collation will cause the function to fail. The ability to
generate collation keys is an
An error is raised
The function is provided primarily for use with maps. If a map is required where
codepoint equality is inappropriate for comparing keys, then a common technique is to
normalize the key so that equality matching becomes feasible. There are many ways
keys can be normalized, for example by use of functions such as
fn:uppercase
, fn:lowercase
,
fn:normalizespace
, or fn:normalizeunicode
, but this
function provides a way of normalizing them according to the rules of a specified
collation. For example, if the collation ignores accents, then the function will
generate the same collation key for two input strings that differ only in their use of
accents.
The result of the function is defined to be an xs:base64Binary
value. Binary values
are chosen because they have unambiguous and contextfree comparison semantics, because the value space
is unbounded, and because the ordering rules are such that between any two values in the ordered value space, an
arbitrary number of further values can be interpolated. The choice between xs:base64Binary
and xs:hexBinary
is arbitrary; the only operation that behaves differently between the two binary
data types is conversion to/from a string, and this operation is not one that is normally required for
effective use of collation keys.
For collations based on the Unicode Collation Algorithm, an algorithm for computing
collation keys is provided in
The fact that collation keys are ordered can be exploited in XQuery, whose order by
clause does not allow the collation to be selected dynamically. This restriction can be circumvented
by rewriting the clause order by $e/@key collation "URI"
as order by fn:collationkey($e/@key, $collation)
,
where $collation
allows the collation to be chosen dynamically.
Note that xs:base64Binary
becomes an ordered type
in XPath 3.1, making binary collation keys possible.
"A"
and "a"
have the same collation key under this
collation.As the above examples illustrate, it is important that when the
collationkey
function is used to add entries to a map, then it must
also be used when retrieving entries from the map. This process can be made less
errorprone by encapsulating the map within a function: function($k)
{$M(collationkey($k, $collation)}
.
Parses a string supplied in the form of a JSON text, returning the results in the form
of an XML
The effect of the oneargument form of this function is the same as calling the
twoargument form with an empty map as the value of the $options
argument.
The first argument is a JSONtext as defined in
If $value
is an empty sequence, the function returns the empty sequence.
The $options
argument can be used to control the way in which the parsing
takes place. The
The entries that may appear in the $options
map are as follows:
JSONtext
in escape
option is set to true
validate
is true
then reject
, otherwise retain
.validate=true
liberal
option has the value true
.
fallback
function
as described below; in the absence of a fallback function, they are replaced by
the Unicode REPLACEMENT CHARACTER
(xFFFD
)escaped
and escapedkey
will not be present in the XDM output.
all codepoints in the range x00
to x1F
or x7F
to x9F
;
all codepoints that do not represent characters that are valid in the version of XML supported by the processor, including codepoints representing unpaired surrogates;
the backslash character itself (x5C
).
\t
), or a sixcharacter escape sequence otherwise
(for example \uDEAD
). Characters other than these will not be escaped in the result,
even if they were escaped in the input. In the result:
Any string
element whose string value contains a
backslash character must have the attribute value escaped="true"
.
Any element that contains a key
attribute whose string value
contains a backslash character must have the attribute
escapedkey="true"
.
The values of the escaped
and
escapedkey
attributes are immaterial when there is no backslash
present, and it is never necessary to include either attribute when its value
is false
.
fallback
option if the escape
option is present
with the value true
.
function($s) { "�" }
: that is,
a function that replaces the escape sequence with the Unicode REPLACEMENT CHARACTER
.liberal:true()
is specified): for example
\b
or \uFFFF
or \uDEAD
. The function is \x0A
).
The function returns a string
which is inserted into the result in place of the invalid character. The
function also has the option of raising a dynamic error by calling fn:error
.
The various structures that can occur in JSON are transformed recursively to XDM values
according to the rules given in
The function returns a document node, whose only child is the element node representing the outermost construct in the JSON text.
The function is
The base URI of the returned document node is taken from the static base URI of the function call.
The choice of namespace prefix (or absence of a prefix) in the names of constructed
nodes is
The XDM tree returned by the function does not contain any
unnecessary (albeit valid) nodes such as whitespace text nodes, comments, or processing instructions.
It does not include any whitespace in the value of number
or boolean
element nodes, escaped
or escapedkey
attribute nodes.
If the result is typed, every element named string
will have an attribute named
escaped
whose value is either true
or false
, and every element having
an attribute named key
will also have an attribute named escapedkey
whose value is either
true
or false
.
If the result is untyped, the attributes escaped
and escapedkey
will
either be present with the value true
, or will be absent. They will never be present with the value false
.
An error is raised $value
does not conform to the JSON grammar as defined
by "liberal":true()
is present and
the processor chooses to accept the deviation.
An error is raised validate
option is true
and the processor does not support
schema validation or typed data.
An error is raised $options
includes an entry whose key is defined in this specification,
and whose value is not a permitted value for that key.
To read a JSON file, this function can be used in conjunction with the
fn:unparsedtext
function.
Many JSON implementations allow commas to be used after the last item in an object or
array, although the specification does not permit it. The option
spec="liberal"
is provided to allow such deviations from the
specification to be accepted. Some JSON implementations also allow constructors such as
new Date("20001213")
to appear as values: specifying
spec="liberal"
allows such extensions to be accepted, but does not
guarantee it. If such extensions are accepted, the resulting value is
implementationdefined, and will not necessarily conform to the schema at
If the input starts with a byte order mark, this function ignores it. The byte order mark may have been added to the data stream in order to facilitate decoding of an octet stream to a character string, but since this function takes a character string as input, the byte order mark serves no useful purpose.
The possibility of the input containing characters that are not valid in XML (for example, unpaired surrogates)
arises only when such characters are expressed using JSON escape sequences. The is because the input to the function
is an instance of xs:string
, which by definition can only contain characters that are valid in XML.
escaped
attribute
on the second string
element.The following example illustrates use of the fallback
function to
handle characters that are invalid in XML.
Converts an XML tree, whose format corresponds to the XML representation of JSON defined in this specification, into a string conforming to the JSON grammar.
The effect of the oneargument form of this function is the same as calling the
twoargument form with an empty map as the value of the $options
argument.
The first argument $node
is a node; the subtree rooted at this node will typically be
the XML representation of a JSON document as defined in
If $node
is the empty sequence, the function returns the empty sequence.
The $options
argument can be used to control the way in which the conversion
takes place. The
The entries that may appear in the $options
map are as follows:
fn:number
elements in the input. For example, setting the value to fn:identity#1
causes the value to be output unchanged. There is no requirement that the result should
be valid JSON.
fn:number
element to an xs:double
, and then converting
the result to a string using the casting rules. Note that this will result in exponential
notation being used for values outside the range
1e6
to 1e+6
. A dynamic error occurs for values
such as infinity and NaN
where the resulting JSON would be invalid.
The node supplied as $node
must be one of the following:
An element node whose name matches the name of a global element declaration in the schema given in
If the type annotation of the element matches the type of the relevant element declaration in the schema (indicating that the element has been validated against the schema), then the element is considered valid.
Otherwise, the processor
Otherwise (if the processor does not attempt validation using the schema),
the processor http://www.w3.org/2005/xpathfunctions
, is such that validation
against the schema would have an outcome of
The process described here is not precisely equivalent to schema validation.
For example, schema validation will fail if there is an invalid xsi:type
or xsi:nil
attribute, whereas this process will ignore such attributes.
An element node E having a key
attribute and/or an escapedkey
attribute
provided that E would satisfy one of the above
conditions if the key
and/or escapedkey
attributes were removed.
A document node having exactly one element child and no text node children, where the element child satisfies one of the conditions above.
Furthermore, $node
must satisfy the following constraint
(which cannot be conveniently expressed in the schema). Every element M that is a descendantorself of
$node
and has local name map
and namespace URI http://www.w3.org/2005/xpathfunctions
must satisfy the following rule: there must not be two distinct children of M (say C/1 and C/2)
such that the normalized key of C/1 is equal to the normalized key of C/2. The normalized key
of an element C is as follows:
If C has the attribute value escapedkey="true"
, then the value of the
key
attribute of C, with all JSON escape sequences replaced by the corresponding Unicode characters
according to the JSON escaping rules.
Otherwise (the escapedkey
attribute of C is absent or set to false
),
the value of the key
attribute of C.
Nodes in the input tree are handled by applying the following rules, recursively. In these rules the term
“an element named N” means "an element node whose local name is N and whose namespace URI is
http://www.w3.org/2005/xpathfunctions
".
A document node having a single element node child is processed by processing that child.
An element named null
results in the output null
.
An element $E
named boolean
results in the output true
or false
depending on the result of xs:boolean(fn:string($E))
An element $E
named number
is processed as follows:
If the numberformatter
option is present and nonempty,
the supplied function is called, with the string value of $E
as its argument,
and the result is output (whether or not it is valid JSON).
Otherwise, the result of the expression xs:string(xs:double(fn:string($E)))
is output.
The default formatting results in exponential format being used for numbers whose
absolute value is outside the range 1e6
to 1e+6
;
although this is valid according to the JSON specification, some receiving
applications may be unable to process it. Possible reasons for using
a numberformatter
might be:
To avoid use of exponential notation in the output.
To avoid loss of precision when the numbers to be output have
greater precision than an xs:double
.
To improve the human readability of the output, for example by calling fn:formatnumber
to limit the number of decimal places in the result.
To avoid errors when dealing with values that JSON cannot handle, such as Infinity and NaN
(for example, by emitting these as strings within quotation marks).
An element named string
results in the output of the string value of the element, enclosed in
quotation marks, with any special characters in the string escaped as described below.
An element named array
results in the output of the children of the array
element,
each processed by applying these rules recursively: the items in the resulting list are enclosed between square brackets,
and separated by commas.
An element named map
results in the output of a sequence of map entries corresponding to
the children of the map
element, enclosed between curly braces and separated by commas.
Each entry comprises the value of the key
attribute of the child element, enclosed in quotation marks
and escaped as described below, followed by a colon, followed by the result of processing the child element
by applying these rules recursively.
Comments, processing instructions, and whitespace text node children of map
and array
are ignored.
Strings are escaped as follows:
If the attribute escaped="true"
is present for a string value, or escapedkey="true"
for a key value, then:
any valid JSON escape sequence present in the string is copied unchanged to the output;
any invalid JSON escape sequence results in a dynamic error
any un