This document is a working draft developed and maintained by a W3C Community Group,
the
The community group welcomes comments on the specification. Comments are best submitted
as issues on the group's
The community group maintains two extensive test suites,
one oriented to XQuery and XPath, the other to XSLT.
These can be found at
The publications of this community group
This document defines constructor functions, operators, and functions on the datatypes defined in
A summary of changes since version 3.1 is provided at
The purpose of this document is to define functions and operators for inclusion in
XPath 4.0, XQuery 4.0, and XSLT 4.0.
The exact syntax used to call these
functions and operators is specified in
This document defines three classes of functions:
General purpose functions, available for direct use in user-written queries, stylesheets, and XPath expressions,
whose arguments and results are values defined by the
Constructor functions, used for creating instances of a datatype from values of (in general) a different datatype. These functions are also available for general use; they are named after the datatype that they return, and they always take a single argument.
Functions that specify the semantics of operators defined in
xs:dateTimeStamp, and it
incorporates as built-in types the two types xs:yearMonthDuration and xs:dayTimeDuration
which were previously XDM additions to the type system. In addition, XSD 1.1 clarifies and updates many
aspects of the definitions of the existing datatypes: for example, it extends the value space of
xs:double to allow both positive and negative zero, and extends the lexical space to allow +INF;
it modifies the value space of xs:Name
to permit additional Unicode characters; it allows year zero and disallows leap seconds in xs:dateTime
values; and it allows any character string to appear as the value of an xs:anyURI item.
Implementations of this specification
References to specific sections of some of the above documents are indicated by
cross-document links in this document. Each such link consists of a pointer to a
specific section followed a superscript specifying the linked document. The
superscripts have the following meanings: XQ
Despite its title, this document does not attempt to define the semantics of all the operators available
in the
The remaining operators that are described in this publication are the arithmetic operators,
where the semantics of the operator
depend on the types of the arguments. For these operators, the language specification describes rules for selecting
an internal function defined in this specification to underpin the operator. For example, when the operator x+y
is applied to two operands of type xs:double, the function op:numeric-add is selected.
Previous versions of this specification also defined the value comparison operators such as
eq, lt, and gt in terms of functions such as
op:date-greater-than. These have been dropped; for most data types the semantics
of the value comparison operators are defined by reference to the
This recommendation contains a set of function specifications. It defines conformance at the level of individual functions. An implementation of a function conforms to a function specification in this recommendation if all the following conditions are satisfied:
For all combinations of valid inputs to the function (both explicit arguments and implicit context dependencies), the result of the function meets the mandatory requirements of this specification.
For all invalid inputs to the function, the implementation raises (in some way appropriate to the calling environment) a dynamic error.
For a sequence of calls within the same
Other recommendations (“host languages”) that reference this document may dictate:
Subsets or supersets of this set of functions to be available in particular environments;
Mechanisms for invoking functions, supplying arguments, initializing the static and dynamic context, receiving results, and handling errors;
A concrete realization of concepts such as
Which versions of other specifications referenced herein (for example, XML, XSD, or Unicode) are to be used.
Any behavior that is discretionary (implementation-defined or implementation-dependent) in this specification may be constrained by a host language.
Adding such constraints in a host language, however, is discouraged because it makes it difficult to reuse implementations of the function library across host languages.
This specification allows flexibility in the choice of versions of specifications on which it depends:
It is
It is
It is
The XML Schema 1.1 recommendation
introduces one new concrete datatype: xs:dateTimeStamp; it also incorporates
the types xs:dayTimeDuration, xs:yearMonthDuration,
and xs:anyAtomicType which were previously defined in earlier versions of xs:NCName
based on the rules in XML 1.1 rather than 1.0.
The
In this document, text labeled as an example or as a note is provided for explanatory purposes and is not normative.
The functions and operators defined in this document are contained in one of
several namespaces (see xs:QName.
This document uses conventional prefixes to refer to these namespaces. User-written
applications can choose a different prefix to refer to the namespace, so long as it is
bound to the correct URI. The host language may also define a default namespace for
function calls, in which case function names in that namespace need not be prefixed
at all. In many cases the default namespace will be
http://www.w3.org/2005/xpath-functions, allowing a call on the name() rather than fn:name();
in this document, however, all example function calls are explicitly prefixed.
The URIs of the namespaces and the conventional prefixes associated with them are:
http://www.w3.org/2001/XMLSchema for constructors —
associated with xs.
The section http://www.w3.org/2001/XMLSchema,
and are named in this document using the xs prefix.
http://www.w3.org/2005/xpath-functions
for functions — associated with fn.
The namespace
prefix used in this document for most functions that are available to users is
fn.
http://www.w3.org/2005/xpath-functions/math
for functions — associated with math.
This namespace is used for some mathematical functions. The namespace
prefix used in this document for these functions is math.
These functions are available to users in exactly the same way as those in the
fn namespace.
http://www.w3.org/2005/xpath-functions/map
for functions — associated with map.
This namespace is used for some functions that manipulate maps (see
map.
These functions are available to users in exactly the same way as those in the
fn namespace.
http://www.w3.org/2005/xpath-functions/array
for functions — associated with array.
This namespace is used for some functions that manipulate maps (see
array.
These functions are available to users in exactly the same way as those in the
fn namespace.
http://www.w3.org/2005/xqt-errors — associated with
err.
There are no functions in this namespace; it is used for error codes.
This document uses the prefix err to represent the namespace URI
http://www.w3.org/2005/xqt-errors, which is the namespace for all XPath
and XQuery error codes and messages. This namespace prefix is not predeclared and
its use in this document is not normative.
http://www.w3.org/2010/xslt-xquery-serialization — associated with
output.
There are no functions in this namespace: it is
used for serialization parameters, as described in
Functions defined with the op prefix are described here to
underpin the definitions of the operators in op prefix. For example, multiplication is generally
associated with the * operator, but it is described as a function
in this document:
Sometimes there is a need to use an operator as a function.
To meet this requirement, the function fn:for-each-pair($seq1, $seq2, op("+"))
performs a pairwise addition of the values in two input sequences.
The above namespace URIs are not expected to change from one version of this document to another. The contents of these namespaces may be extended to allow additional functions (and errors, and serialization parameters) to be defined.
A function is uniquely defined by its name and arity (number of arguments); it is therefore
not possible to have two different functions that have the same name and arity, but different
types in their signature. That is, function overloading in this sense of the term is not permitted.
Consequently, functions such as item()?
which accepts any single item; supplying an inappropriate item (such as a function item) causes
a dynamic error.
Some functions on numeric types include the type xs:numeric in their signature
as an argument or result type. In this version of the specification, xs:numeric
has been redefined as a built-in union type representing the union of
xs:decimal, xs:float, xs:double (and thus automatically
accepting types derived from these, including xs:integer).
Operators such as + may be overloaded: they map to different underlying functions depending
on the dynamic types of the supplied operands.
It is possible for two functions to have the same name provided they have different arity (number of arguments). For the functions defined in this specification, where two functions have the same name and different arity, they also have closely related behavior, so they are defined in the same section of this document.
Each function (or group of functions having the same name) is defined in this specification using a standard proforma. This has the following sections:
The function name is a QName as defined in math:sin and
math:cos for sine and cosine). If a
function name contains a
The first section in the proforma is a short summary of what the function does. This is intended to be informative rather than normative.
Each function is then defined by specifying its signature(s), which define the types of the parameters and of the result value.
Where functions take a variable number of arguments, two conventions are used:
Wherever possible, a single function signature is used giving default values for those parameters that can be omitted.
If this is not possible, because the effect of omitting a parameter cannot be specified by giving a default value, multiple signatures are given for the function.
Each function signature is presented in a form like this:
In this notation, http://www.w3.org/2005/xpath-functions:
this is one of the conventional prefixes listed in (); otherwise, the name is followed by a parenthesized list of
parameter declarations. Each parameter declaration includes:
The name of the parameter (which in 4.0 is significant because it can be used as a keyword in a function call)
The static type of the parameter (in italics)
If the parameter is optional, then an expression giving the default value
(preceded by the symbol :=).
The default value expression is evaluated using the static and
dynamic context of the function caller (or of a named function reference). For example,
if the default value is given as ., then it evaluates to the context value
from the dynamic context of the function caller; if it is given as default-collation,
then its value is the default collation from the static context of the function caller;
if it is given as deep-equal#2, then the third argument supplied to deep-equal
is the default collation from the static context of the caller.
If no argument is supplied for a parameter that has a default value, the default
value is used. If the parameter is marked (:default-on-empty:),
the default value is also used when the supplied argument is the empty sequence.
Otherwise, the empty sequence is treated according to the function-specific rules.
The marker is only used on parameters that have default values.
If there are two or more parameter declarations, they are separated by a comma.
The return-type
The next section in the proforma defines the semantics of the function as a set of rules.
The order in which the rules appear is significant; they are to be applied in the order in which
they are written. Error conditions, however, are generally listed in a separate section that follows
the main rules, and take precedence over non-error rules except where otherwise stated. The principles outlined
in
Some functions supplement the prose rules with a more formal specification that describes the effect of the function in terms of an equivalent XPath or XQuery implementation. This is intended to take precedence over the prose rules in the event of any conflict; however, both sections are intended to be complete and not to rely on each other.
In writing the formal equivalents, a number of guidelines have been followed:
Where the equivalent code calls other functions, these should either be primitives
defined in the data model specification (see
There should be minimal reliance on XPath or XQuery language features. Although no attempt has been made to precisely define a core set of language constructs, the specifications try to avoid relying on features other than function calls and a few basic operators including the comma operator, equality testing, and simple integer arithmetic.
There is no suggestion that the formal equivalent is a practical implementation; in many cases it might have very poor performance.
In some cases the formal equivalent does not attempt to replicate correct behavior in error cases; if so, this is always clearly stated.
The formal equivalent will always produce a conformant result for the function, but in some cases this will not be the only possible conformant result.
There is no attempt to write formal equivalents for functions that have complex logic
(such as
Where the proforma includes a section headed
Where the proforma includes a section headed
Many of the examples are given in structured form, showing example expressions and their expected results.
These published examples are derived from executable test cases, so they follow a standard format. In general,
the actual result of the expression is expected to be deep-equal to the presented result, under the
rules of the
For more complex functions, examples may be given using informal narrative prose.
Rules for evaluating the operands of operators are described in the relevant sections
of xs:untypedAtomic and the empty sequence are specified in this section.
For function calls, the required type of an argument is defined in the function
signature of each function, and the way in which a supplied value is converted to the
required type (or rejected if it cannot be converted) is defined by the
Some functions accept a single value or the empty sequence as an argument and
some may return a single value or the empty sequence. This is indicated in the
function signature by following the parameter or return type name with a
question mark: ?, indicating that either a single value or the
empty sequence must appear. See below.
Note that this function signature is different from a signature in which the
parameter is omitted. See, for example, the two signatures
for ..
In the second signature, the argument must be present but may be the empty
sequence, written as ().
Some functions accept a sequence of zero or more values as an argument. This is
indicated by following the name of the type of the items in the sequence with
*. The sequence may contain zero or more items of the named type.
For example, the function below accepts a sequence of xs:double and
returns a xs:double or the empty sequence.
In XPath 4.0, the arguments in a function call can be supplied by
keyword as an alternative to supplying them positionally. For example the call
resolve-uri(@href, static-base-uri()) can now be written
resolve-uri(base := static-base-uri(), href := @href). The order in which
arguments are supplied can therefore differ from the order in which they are declared.
The specification, however, continues to use phrases such as “the second argument” as a
convenient shorthand for "the value of the argument that is bound to the second parameter
declaration".
As a matter of convention, a number of functions defined in this document take a parameter whose value is a map, defining options controlling the detail of how the function is evaluated. Maps are a new datatype introduced in XPath 3.1.
For example, the function
Where a function adopts the
The value of the relevant argument must be a map. The entries in the map are
referred to as options: the key of the entry is called the option name, and the
associated value is the option value. Option names defined in this specification
are always strings (single xs:string values). Option values may
be of any type.
The type of the options parameter in the function signature is always
given as map(*).
Although option names are described above as strings, the actual key may be
any value that is the xs:untypedAtomic
or xs:anyURI are equally acceptable.
This means that the implementation of the function can check for the
presence and value of particular options using the functions
Implementations xs:QName as the option
names, using an appropriate namespace.
If an option is present whose key is not described in the specification,
then a type error xs:QName with a non-absent namespace.
All entries in the options map are optional, and supplying the empty map has the same effect as omitting the relevant argument in the function call, assuming this is permitted.
The ordering of the options map is immaterial.
For each named option, the function
specification defines a required type for the option value. The value that is actually
supplied in the map is converted to this required type using the
It is the responsibility of each function implementation to invoke this conversion; it does not happen automatically as a consequence of the function-calling rules.
In cases where the value of an option is itself a map, the specification of the particular function must indicate whether or not these rules apply recursively to the contents of that map.
The diagrams in this section show how nodes, functions, primitive simple types, and user defined types fit together into a type system. This type system comprises two distinct subsystems that both include the primitive atomic types. In the diagrams, connecting lines represent relationships between derived types and the types from which they are derived; the former are always below and to the right of the latter.
The xs:IDREFS, xs:NMTOKENS,
xs:ENTITIES types, and xs:numeric and both the
user-defined list types and
user-defined union types
are special types in that these types are lists or unions
rather than types derived by extension or restriction.
The first diagram illustrates the relationship of various item types.
Item types are used to characterize the various types of item that can appear in a sequence (nodes, atomic items, and functions), and they are therefore used in declaring the types of variables or the argument types and result types of functions.
In XDM, item types include node types,
function types, and built-in atomic types.
Item types form a directed graph, rather than a
hierarchy or lattice: in the relationship defined by the
derived-from(A, B) function, some types are derived from
more than one other type. Examples include functions
(function(xs:string) as xs:int is substitutable for
function(xs:NCName) as xs:int and also for
function(xs:string) as xs:decimal), and choice types
(A is substitutable for the choice type (A | B) and also
for (A | C). Record types provide an alternative way of categorizing
maps: the instances of record(longitude, latitude) overlap with
the instances of map(xs:string, xs:double). The diagram, which shows
only hierarchic relationships, is therefore a simplification of the
full model.
The next diagram illustrate the schema type subsystem, in which
all types are derived from xs:anyType.
Schema types include built-in types defined in the XML Schema specification, and user-defined types defined using mechanisms described in the XML Schema specification. Schema types define the permitted contents of nodes. The main categories are complex types, which define the permitted content of elements, and simple types, which can be used to constrain the values of both elements and attributes.
The final diagram shows all of the atomic types, including the primitive simple types and the
built-in types derived from the primitive simple types.
This includes all the built-in datatypes defined in
Atomic types are both item types and schema types, so the root type xs:anyAtomicType may be found
in both the previous diagrams.
The terminology used to describe the functions and operators on types defined in
Following in the tradition of
The following definitions are adopted from
xs:untypedAtomic
defined in
xs:untypedAtomic), and these have non-overlapping value spaces, so each
datum belongs to exactly one primitive atomic type.
The term
This document uses the terms string, character, and codepoint
with meanings that are normatively defined in
This
definition excludes Unicode characters in the surrogate blocks as well as
xs:string datatype.
The set of codepoints is thus wider than the set of characters.
This specification spells “codepoint” as one word; the Unicode specification spells
it as “code point”.
Equivalent terms found in other specifications are
“character number” or “code position”. See
Because these terms appear so frequently, they are hyperlinked to the definition only when there is a particular desire to draw the reader’s attention to the definition; the absence of a hyperlink does not mean that the term is being used in some other sense.
It is
This specification adopts the Unicode notation U+xxxx to refer to a codepoint
by its hexadecimal value (always four to six hexadecimal digits). This is followed where appropriate
by the official Unicode character name and its graphical representation: for example
Unless explicitly stated, the functions in this document do not ensure that any
returned xs:string values are normalized in the sense of
In functions that involve character counting such
as
Wherever encoding names (such as UTF-8 and UTF-16) are used in this specification,
they are compared without regard to case: the strings "UTF-8" and "utf-8" both
refer to the same encoding.
This document uses the phrase “namespace URI” to identify the concept identified
in
It also uses the term expanded-QName
defined below.
xs:QName datatype as defined in the XDM data model
(see
The term URI is used as follows:
xs:anyURI datatype
as defined in
This means, in practice, that where this
specification requires a “URI Reference”, an IRI as defined in xs:anyURI is a wider definition than the definition in
In this specification:
The auxiliary verb
When the sentence relates to an implementation of a function (for example "All implementations
When the sentence relates to the result of a function (for example "The result $arg") then the implementation is not conformant unless it delivers a result as stated.
When the sentence relates to the arguments to a function (for example "The value of $arg
The auxiliary verb
The auxiliary verb
Where this specification states that something is implementation-defined or implementation-dependent, it is open to host languages to place further constraints on the behavior.
This section is concerned with the question of whether two calls on a function, with the same arguments, may produce different results.
In this section the term
use-when attributes, are in a separate execution scope).
The following definition explains more precisely what it means for two function calls to return the same result:
$V1 and $V2 are
defined to be
Both items are atomic items, of precisely the same type, and the values are equal as defined using the eq operator,
using the Unicode codepoint collation when comparing strings.
Both items are nodes, and represent the same node.
Both items are maps, both maps have the same number of entries,
and for every entry E1 in the first map there is an entry E2 in the second map such
that the keys of E1 and E2 are
Both items are arrays, both arrays have the same number of members, and the members
are pairwise
Both items are function items,
neither item is a map or array, and the two function items have the same function identity.
The concept of function identity is explained in
Some functions produce results that depend not only on their explicit arguments, but also on the static and dynamic context.
The main categories of context-dependent functions are:
Functions that explicitly deliver the value of a component of the static or dynamic context,
for example
Functions with an optional parameter whose default value is taken from the static
or dynamic context of the caller, usually either the context value (for example,
Functions that use the static context of the caller to expand or disambiguate
the values of supplied arguments: for example xs:QName expands its first argument
using the in-scope namespaces of the caller.
Some functions depend on aspects of the dynamic context that remain invariant
within an
User-defined functions in XQuery and XSLT may depend on the static context of the function definition (for example, the in-scope namespaces) and also in a limited way on the dynamic context (for example, the values of global variables). However, the only way they can depend on the static or dynamic context of the caller — which is what concerns us here — is by defining optional parameters whose default values are context-dependent.
Because the focus is a specific part of the dynamic context, all
A
The result of a dynamic call to a function item never depends on the static or dynamic context of the dynamic function call, only (where relevant) on the captured context held within the function item itself.
The
All functions defined in this specification are
Some functions (such as is
operator). However, if non-identical nodes are returned, their content will be the
same in the sense of the
Some functions (such as "stable":false() that makes
them nondeterministic as a user option, and implementations
Where the results of a function are described as being (to a greater or lesser
extent)
A sequence is an ordered collection of zero or more items.
An item is a node, an atomic item, or a function, such as a map or an array. The terms
sequence and item are defined formally in
The following functions are defined on sequences. These functions work on any sequence, without performing any operations that are sensitive to the individual items in the sequence.
| Function | Meaning |
|---|---|
fn:empty | Returns true if the argument is the empty sequence. |
fn:exists | Returns true if the argument is a non-empty sequence. |
fn:foot | Returns the last item in a sequence. |
fn:head | Returns the first item in a sequence. |
fn:identity | Returns its argument value. |
fn:insert-before | Returns a sequence constructed by inserting an item or a sequence of items at a given position within an existing sequence. |
fn:insert-separator | Inserts a separator between adjacent items in a sequence. |
fn:items-at | Returns a sequence containing the items from $input
at positions defined by $at, in the order specified. |
fn:remove | Returns a new sequence containing all the items of $input |
fn:replicate | Produces multiple copies of a sequence. |
fn:reverse | Reverses the order of items in a sequence. |
fn:slice | Returns a sequence containing selected items from a supplied input sequence based on their position. |
fn:subsequence | 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. |
fn:tail | Returns all but the first item in a sequence. |
fn:trunk | Returns all but the last item in a sequence. |
fn:unordered | Returns the items of $input in an |
fn:void | Absorbs the argument. |
As in the previous section, for the illustrative examples below, assume an XQuery
or transformation operating on a non-empty Purchase Order document containing a
number of line-item elements. The variable $seq is bound to the
sequence of line-item nodes in document order. The variables
$item1, $item2, etc. are bound to separate, individual
line-item nodes in the sequence.
Returns true if the argument is the empty sequence.
This function is
If $input is the empty sequence, the function returns
true; otherwise, the function returns false.
The effect of the function is equivalent to the result of the following XPath expression.
| Expression | Result |
|---|---|
empty((1, 2, 3)[10]) |
|
empty(remove(("hello", "world"), 1)) |
|
empty([]) |
|
empty({}) |
|
empty("") |
|
Assuming | |
The result is | |
Returns true if the argument is a non-empty sequence.
This function is
If $input is a non-empty sequence, the function returns
true; otherwise, the function returns false.
The effect of the function is equivalent to the result of the following XPath expression.
| Expression | Result |
|---|---|
exists(remove(("hello"), 1)) |
|
exists(remove(("hello", "world"), 1)) |
|
exists([]) |
|
exists({}) |
|
exists("") |
|
Assuming | |
The result is | |
Returns the last item in a sequence.
This function is
The function returns the value of the expression $input[last()]
The effect of the function is equivalent to the result of the following XPath expression.
If $input is the empty sequence, the empty sequence is returned.
| Expression | Result |
|---|---|
foot(1 to 5) |
|
foot(()) |
|
Returns the first item in a sequence.
This function is
The function returns the first item in $input; if $input
is empty, it returns the empty sequence.
The effect of the function is equivalent to the result of the following XPath expression.
| Expression | Result |
|---|---|
head(1 to 5) |
|
head(("a", "b", "c")) |
|
head(()) |
|
head([ 1, 2, 3 ]) |
|
Returns its argument value.
This function is
The function returns $input.
The effect of the function is equivalent to the result of the following XPath expression.
The function is useful in contexts where a function must be supplied, but no processing is required.
| Expression | Result |
|---|---|
identity(0) |
|
identity(1 to 10) |
|
parse-xml('<a/>') ! (identity(/) is /) |
|
identity(()) |
|
Returns a sequence constructed by inserting an item or a sequence of items at a given position within an existing sequence.
This function is
The value returned by the function consists of all items of $input whose
1-based position is less than $position, followed by all items of
$insert, followed by the remaining elements of $input, in
that order.
The effect of the function is equivalent to the result of the following XPath expression.
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.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
insert-before($abc, 0, "z") |
|
insert-before($abc, 1, "z") |
|
insert-before($abc, 2, "z") |
|
insert-before($abc, 3, "z") |
|
insert-before($abc, 4, "z") |
|
Inserts a separator between adjacent items in a sequence.
This function is
The function inserts a separator between adjacent items in a sequence.
The input is returned unchanged if $separator is the empty sequence
or if $input contains less than two items.
The effect of the function is equivalent to the result of the following XPath expression.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
Insert an empty | |
Returns a sequence containing the items from $input
at positions defined by $at, in the order specified.
This function is
Returns the items in $input at the positions listed
in $at, in order of the integers in the $at argument.
The effect of the function is equivalent to the result of the following XPath expression.
In the simplest case where $at is a single integer,
fn:items-at($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
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 the empty sequence, the result is the empty sequence.
If $at contains duplicate integers, the result also contains duplicates. No de-duplication
occurs. If the input sequence contains nodes, these are not copied: instead, the result
sequence contains multiple references to the same node.
| Expression | Result |
|---|---|
items-at(11 to 20, 4) |
|
items-at(11 to 20, 4 to 6) |
|
items-at(11 to 20, (7, 3)) |
|
items-at(11 to 20, index-of(("a", "b", "c"), "b")) |
|
items-at(characters("quintessential"), (4, 8, 3)) |
|
items-at(characters("quintessential"), (4, 8, 1, 1)) |
|
items-at((), 832) |
|
items-at((), ()) |
|
Returns a new sequence containing all the items of $input
This function is
The function returns a sequence consisting of all items of $input $positions.
The effect of the function is equivalent to the result of the following XPath expression.
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 the empty sequence, the input sequence $input is returned unchanged.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
remove($abc, 0) |
|
remove($abc, 1) |
|
remove($abc, 6) |
|
remove((), 3) |
|
remove($abc, 2 to 3) |
|
remove($abc, ()) |
|
Produces multiple copies of a sequence.
This function is
The function returns the value of (1 to $count) ! $input.
The effect of the function is equivalent to the result of the following XPath expression.
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
| Expression | Result |
|---|---|
replicate(0, 6) |
|
replicate(("A", "B", "C"), 3) |
|
replicate((), 5) |
|
replicate(("A", "B", "C"), 1) |
|
replicate(("A", "B", "C"), 0) |
|
Reverses the order of items in a sequence.
This function is
The function returns a sequence containing the items in $input in reverse
order.
The effect of the function is equivalent to the result of the following XPath expression.
If $input is the empty sequence, the empty sequence is returned.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
reverse($abc) |
|
reverse(("hello")) |
|
reverse(()) |
|
reverse([ 1, 2, 3 ]) |
|
reverse(([ 1, 2, 3 ], [ 4, 5, 6 ])) |
|
Returns a sequence containing selected items from a supplied input sequence based on their position.
This function is
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 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 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 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 1-based 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].
This function can be used to enhance the RangeExpression, defined
in
| Variables | |
|---|---|
| Expression | Result |
|---|---|
slice($in, start := 2, end := 4) |
|
slice($in, start := 2) |
|
slice($in, end := 2) |
|
slice($in, start := 3, end := 3) |
|
slice($in, start := 4, end := 3) |
|
slice($in, start := 2, end := 5, step := 2) |
|
slice($in, start := 5, end := 2, step := -2) |
|
slice($in, start := 2, end := 5, step := -2) |
|
slice($in, start := 5, end := 2, step := 2) |
|
slice($in) |
|
slice($in, start := -1) |
|
slice($in, start := -3) |
|
slice($in, end := -2) |
|
slice($in, start := 2, end := -2) |
|
slice($in, start := -2, end := 2) |
|
slice($in, start := -4, end := -2) |
|
slice($in, start := -2, end := -4) |
|
slice($in, start := -4, end := -2, step := 2) |
|
slice($in, start := -2, end := -4, step := -2) |
|
slice(("a", "b", "c", "d"), 0) |
|
slice((1 to 5), step := 2) |
|
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.
This function is
If the third argument is the empty sequence, the function returns:
Otherwise, the function returns:
The effect of the function is equivalent to the result of the following XPath expression.
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 two-argument case, the function returns a sequence comprising those items of
$input whose 1-based position
is greater than or equal to $start (rounded to an integer).
No error occurs if $start is zero or negative.
In the three-argument case, The function returns a sequence comprising those items of
$input whose 1-based 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 the 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 floating-point
computations.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
subsequence($seq, 4) |
|
subsequence($seq, 3, 2) |
|
Returns all but the first item in a sequence.
This function is
The function all items in $input except the first, retaining order.
The effect of the function is equivalent to the result of the following XPath expression.
If $input is the empty sequence, or a sequence containing a single item, then
the empty sequence is returned.
| Expression | Result |
|---|---|
tail(1 to 5) |
|
tail(("a", "b", "c")) |
|
tail("a") |
|
tail(()) |
|
tail([ 1, 2, 3 ]) |
|
Returns all but the last item in a sequence.
This function is
The function returns all items in $input except the last, retaining order.
The effect of the function is equivalent to the result of the following XPath expression.
If $input is the empty sequence, or a sequence containing a single item, then
the empty sequence is returned.
| Expression | Result |
|---|---|
trunk(1 to 5) |
|
trunk(("a", "b", "c")) |
|
trunk("a") |
|
trunk(()) |
|
trunk([ 1, 2, 3 ]) |
|
Returns the items of $input in an
This function is
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.
This function does not guarantee that the resulting sequence will be in an order different from the input sequence. Many times the two sequences will be identical.
| Expression | Result |
|---|---|
unordered((1, 2, 3, 4, 5)) |
(or some permutation thereof) |
Absorbs the argument.
This function is
The function absorbs the supplied $input argument and
returns the empty sequence.
The function can be used to discard unneeded output of expressions (functions, third-party libraries, etc.).
It can also be used to discard results during development.
It is
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: |
The functions in this section perform comparisons between the items in one or more sequences.
Many of these functions require atomic items to be compared for equality.
fn:compare(A, B)
returns zero when evaluated with a specified or context-determined collation
and implicit timezone.
Except where explicitly stated otherwise, an appeal to
NaN is treated as equal to NaN.
| Function | Meaning |
|---|---|
fn:atomic-equal | Determines whether two atomic items are equal, under the rules used for comparing keys in a map. |
fn:compare | Returns -1, 0, or 1, depending on whether
the first value is less than, equal to, or greater than the second value. |
fn:contains-subsequence | Determines whether one sequence contains another as a contiguous subsequence, using a supplied callback function to compare items. |
fn:deep-equal | This function assesses whether two sequences are deep-equal to each other. To be
deep-equal, they must contain items that are pairwise deep-equal; and for two items to
be deep-equal, they must either be atomic items that compare equal, or nodes of the
same kind, with the same name, whose children are deep-equal |
fn:distinct-values | Returns the values that appear in a sequence, with duplicates eliminated. |
fn:duplicate-values | Returns the values that appear in a sequence more than once. |
fn:ends-with-subsequence | Determines whether one sequence ends with another, using a supplied callback function to compare items. |
fn:index-of | Returns a sequence of positive integers giving the positions within the sequence
$input of items that are $target. |
fn:starts-with-subsequence | Determines whether one sequence starts with another, using a supplied callback function to compare items. |
op:same-key
function in 3.1xs:hexBinary
and xs:base64Binary are now mutually comparable. In rare cases, where an
application uses both types and assumes they are distinct, this can represent a backwards
incompatibility.Determines whether two atomic items are equal, under the rules used for comparing keys in a map.
This function is
The function eq operator):
Any two atomic items 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:codepoint-equal($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
fn:compare($value1, $value2) returns zero.
NaN is equal to NaN, INF
is equal to INF, -INF is equal to -INF,
positive zero equals negative zero. This applies both to xs:double
amd xs:float values, including comparisons across these two types.
Ordinary values (numeric values other than the special values mentioned above)
are compared according to their mathematical magnitude.
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.
This comparison is therefore transitive.
All of the following conditions are true:
One of the following conditions is true:
$value1 and $value2 are both instances of xs:date.
$value1 and $value2 are both instances of xs:time.
$value1 and $value2 are both instances of xs:dateTime.
$value1 and $value2 are both instances of xs:gYear.
$value1 and $value2 are both instances of xs:gYearMonth.
$value1 and $value2 are both instances of xs:gMonth.
$value1 and $value2 are both instances of xs:gMonthDay.
$value1 and $value2 are both instances of xs:gDay.
One of the following conditions is true:
Both $value1 and $value2 have a timezone
Neither $value1 nor $value2 has a timezone
fn:compare($value1, $value2) returns zero.
Values having a timezone are never equal to values without one. The implicit timezone is not used.
All of the following conditions are true:
$value1 is an instance of xs:hexBinary or xs:base64Binary
$value2 is an instance of xs:hexBinary or xs:base64Binary
fn:compare($value1, $value2) returns zero.
All of the following conditions are true:
One of the following conditions is true:
$value1 and $value2 are both instances of xs:boolean.
$value1 and $value2 are both instances of xs:QName.
$value1 and $value2 are both instances of xs:NOTATION.
$value1 and $value2 are both instances of xs:duration.
fn:compare($value1, $value2) returns zero.
The internal function op:same-key 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
items are considered to be duplicates when used as keys in a map. A map cannot
contain two separate entries whose keys are
The rules for comparing keys in a map are chosen to ensure that the comparison is:
true or false, never an error
Two atomic items 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.
Unlike previous versions of this specification, xs:hexBinary and
xs:base64Binary values are mutually comparable. This decision affects backwards
compatibility: it is no longer possible to construct certain maps that
could be validly constructed using earlier versions of the specification. This may also cause problems
passing data from a 3.1 processor to a 4.0 processor.
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.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
Returns -1, 0, or 1, depending on whether
the first value is less than, equal to, or greater than the second value.
The two-argument form of this function is
The three-argument form of this function is
The function compares two atomic items $value1 and $value2 for order, and
returns the integer value -1, 0, or +1,
depending on whether $value1 is less than, equal to, or greater than
$value2, respectively.
This function is transitive and symmetric. For example:
If compare(A, B) returns zero, then compare(B, A)
returns zero.
If compare(A, B) returns -1, then compare(B, A)
returns +1.
If compare(A, B) and compare(B, C) both
return -1, then compare(A, C) also returns -1.
If either $value1 or $value2 is the empty sequence,
the function returns the empty sequence.
Otherwise, the result is determined as follows:
If $value1 is an instance of xs:string,
xs:anyURI or xs:untypedAtomic, and if
$value2 is an instance of xs:string, xs:anyURI
or xs:untypedAtomic, the values are compared as strings, and the
result reflects the order according to the rules of the collation that is used.
The collation is determined according to the rules in
Using the default collation may be inappropriate for some strings,
for example URIs or manufacturing part numbers. In such cases it is safest
to supply "http://www.w3.org/2005/xpath-functions/collation/codepoint"
explicitly as the third argument.
If both $value1 and $value2 are instances of
xs:numeric, the function relies on a total order, which is
defined as follows:
A value $f of type xs:float is in all cases equal
to the value xs:double($f). The remaining rules therefore only consider
instances of xs:double and xs:decimal.
NaN is equal to itself and less than any other value.
Negative infinity is equal to itself and less than any other
value except NaN.
Positive infinity is equal to itself and greater than any other value.
Negative zero is equal to positive zero.
Other xs:double and xs:decimal values (that is,
values other than the infinities, NaN, and negative zero) are ordered
according to their mathematical magnitude, the comparison being done without any
rounding or loss of precision. This effect can be achieved by converting
xs:double values to xs:decimal using an implementation
of xs:decimal that imposes no limits on precision or scale, or an
implementation whose limits are such that all xs:double values can
be represented precisely.
Every xs:double other than NaN and ±INF,
has a mathematical value of the form m × 2^e,
where m is an integer whose absolute value is less than 2^53,
and e is an integer between -1075 and 970, inclusive. This is the value
that is used in comparisons.
Practical difficulties arise because the typical string representations of
an xs:double, such as 3.1, cannot be precisely
represented by values of the form m × 2^e, but are instead converted
to the best available approximation, which will often not be exactly equal
to an xs:decimal expressed using the same lexical form.
If both $value1 and $value2 are instances of
xs:boolean, the result is
fn:compare(xs:integer($value1), xs:integer($value2))
This means that false is
treated as less than true.
If $value1 is an instance of xs:hexBinary or
xs:base64Binary, and if $value2 is an instance of
xs:hexBinary or xs:base64Binary, then:
Let $A be the sequence of integers, in the range (0 to 255), representing
the octets of $value1, in order; and let $B similarly
be the sequence of integers representing the octets of $value2.
If $A is empty and $B is empty return zero.
If $A is empty and $B is not empty return -1.
Let $C be the value of fn:compare(fn:head($A), fn:head($B)).
If $C is non-zero, then return $C.
Otherwise, return the result of applying these rules recursively
to fn:tail($A) and fn:tail($B)
If both $value1 and $value2 are instances of
the same primitive type T, where T is one of the
types xs:dateTime, xs:date, xs:time,
xs:gYear, xs:gYearMonth, xs:gMonth,
gMonthDay, or gDay, then:
Each of the values is converted to an xs:dateTime
value as follows:
The value is considered as a tuple with seven fields
(year, month, day, hours, minutes, seconds, timezone) as defined by
the functions
Any absent components, other than the timezone, are substituted
with the corresponding components of the
xs:dateTime value 1972-01-01T00:00:00
to produce an xs:dateTime value.
If the timezone component is absent, it is substituted with the implicit timezone from the dynamic context.
The xs:dateTime 1972-01-01T00:00:00
is arbitrary. The only constraint is that the year must be a leap year
(so that the xs:gYearMonth value --02-29 expands to a valid date).
XSD originally chose this as the being historically the first date on which there was a leap second,
but this is irrelevant as leap seconds are not supported in XDM.
The result of the function is then the result of comparing the
xs:dateTime
values according to the algorithm defined in section 3.2.7.4 of Order relation on dateTime
for xs:dateTime values with
timezones).
If both $value1 and $value2 are instances of
xs:duration, then:
Let $M1 and $M2
be the months components of the two durations, and let $S1
and $S2 be the seconds components of the two durations.
Let $C be fn:compare($M1, $M2).
If $C is non-zero, return $C.
Otherwise, return fn:compare($S1, $S2).
The result matches the real-world semantics of durations in many cases, for example:
When both values are zero-length durations.
When both values are have an equal months component (in particular when both have a zero months component).
When both values are have an equal seconds component (in particular when both have a zero seconds component).
When both values have a seconds component that is less than the number of seconds in the shortest month.
In other cases the result is well defined and well behaved (for example it
is symmetric and transitive) but may be counter-intuitive. For example,
one month (PT1M) is considered greater than one hundred days
(PT100D).
Previous versions of this specification allowed durations to be compared
only if both were instances of xs:dateTimeDuration or
xs:yearMonthDuration. This requirement has been relaxed in the
interests of allowing all atomic items to be sorted; in some applications the actual sort
order matters little, so long as it is consistent.
If both $value1 and $value2 are instances of
xs:QName, then:
Let $N1 and $N2
be the result of applying the function $L1
and $L2 be the result of applying the function
Let $CPC be "http://www.w3.org/2005/xpath-functions/collation/codepoint".
Let $C be fn:compare($N1, $N2, $CPC).
If $C is non-zero, return $C.
Otherwise, return fn:compare($L1, $L2, $CPC).
If both $value1 and $value2 are instances of
xs:NOTATION, return fn:compare(xs:QName($value1), xs:QName($value2)).
For any other combination of types, a type error
For numeric values, consider the xs:double value written as
0.1e0 and the xs:decimal value written as 0.1:
The mathematical magnitude of this xs:double value is
0.1000000000000000055511151231257827021181583404541015625.
Therefore, compare(0.1e0, 0.1) returns +1. By contrast,
0.1e0 lt 0.1 is false and 0.1e0 eq 0.1
is true, because those expressions convert the xs:decimal value
0.1 to the xs:double value 0.1e0
before the comparison.
Although operations such as sorting and the NaN differently.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
Determines whether one sequence contains another as a contiguous subsequence, using a supplied callback function to compare items.
The two-argument form of this function is
The three-argument form of this function is
Informally, the function returns true if $input contains a consecutive subsequence matching $subsequence,
when items are compared using the $compare function.
The effect of the function is equivalent to the result of the following XPath expression.
There is no requirement that the $compare function should have the traditional qualities
of equality comparison. The result is well-defined, for example, even if $compare is not transitive
or not symmetric.
A return value of () from the function is treated as false.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
|
$options parameter has been added,
absorbing the $collation parameter.xs:hexBinary
and xs:base64Binary are now mutually comparable. In rare cases, where an
application uses both types and assumes they are distinct, this can represent a backwards
incompatibility. This function assesses whether two sequences are deep-equal to each other. To be
deep-equal, they must contain items that are pairwise deep-equal; and for two items to
be deep-equal, they must either be atomic items that compare equal, or nodes of the
same kind, with the same name, whose children are deep-equal
The two-argument form of this function is
The three-argument form of this function is
The $options argument defines additional parameters controlling
how the comparison is done. If it is supplied as a map, then the
For backwards compatibility reasons, the $options argument can also be set
to a string containing a collation name. Supplying a string $S for this argument is equivalent
to supplying the map { 'collation': $S }.
If the two sequences ($input1 and $input2)
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 comparison is controlled by the
ordered option:
By default, the option is true: The function returns
true if and only if every item in the sequence $input1 is
deep-equal to the item at the same position in the sequence $input2.
If the option is set to false, the function returns
false if and only if every item in the sequence $input1
is deep-equal to an item at some position in the sequence $input2,
and vice versa.
The rules for deciding whether two items are deep-equal 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.
| Key | Meaning |
|---|---|
| Determines whether the base-uri of a node is significant.
|
| 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
|
| Determines whether comments are significant.
|
| Requests diagnostics in the case where the function returns false.
When this option is set and the two inputs are found to be not equal, the implementation
|
| Determines whether the id property of elements and attributes is significant.
|
| Determines whether the idrefs property of elements and attributes is significant.
|
| Determines whether the in-scope namespaces of elements are significant.
|
| A user-supplied function to test whether two items
are considered equal. The function can return true
or false to indicate that two items are or are not
equal, overriding the normal rules that would apply to those items;
or it can return the empty sequence, to indicate that the normal
rules should be followed. Note that returning ()
is false.
|
| Determines whether the order of entries in maps is significant.
|
| Determines whether namespace prefixes in xs:QName values (particularly
the names of elements and attributes) are significant.
|
| Determines whether the nilled property of elements and attributes is significant.
|
| If present, indicates that text and attributes are converted to the specified
Unicode normalization form prior to comparison. The value is as for the corresponding
argument of
|
| Controls whether the top-level order of the items of the input sequences
is considered.
|
| Determines whether processing instructions are significant.
|
| Determines whether timezones in date/time values are significant.
|
| Determines whether type annotations are significant.
|
| Determines whether the variety of the type annotation of an element
(whether it has complex content or simple content) is significant.
|
| Determines whether nodes are compared using their typed values rather than
their string values.
|
| A list of QNames of elements considered to be unordered: that is, their child
elements may appear in any order.
|
| 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 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 $options as the original call.
The rules reference a function equal-strings which compares two xs:string
or xs:anyURI values as follows:
If the whitespace option is set to normalize, then each string is processed
by calling the
If the normalization-form option is present, each string is then normalized
by calling the
The two strings are then compared for equality under the requested collation.
More formally, the equal-strings function is equivalent to the following
implementation in XQuery:
The rules for deciding whether two items $i1 and $i2 are deep-equal
are as follows.
The two items are first compared using the function supplied in the items-equal
option. If this returns true then the items are deep-equal. If it returns
false then the items are not deep-equal. If it returns the empty sequence
(which is always the case if the option is not explicitly specified)
then the two items are deep-equal if one or more of the following conditions are true:
All of the following conditions are true:
$i1 is an atomic item.
$i2 is an atomic item.
Either the type-annotations option is false, or both atomic items have
the same type annotation.
One of the following conditions is true:
If both $i1 and $i2 are instances of
xs:string, xs:untypedAtomic, or xs:anyURI,
equal-strings($i1, $i2, $collation, $options)
returns true.
Otherwise, fn:compare($i1, $i2)
returns zero.
If $i1 and $i2 are not comparable, that is,
if the expression compare($i1, $i2) raises an error, then the function
returns false; it does not report an error.
One of the following conditions is true:
Option namespace-prefixes 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
Either map-order is false, or the entries in both maps appear in the same order,
that is, the Nth key in the first map is the
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 deep-equal to each other: that is,
every $p in 1 to array:size($i1) satisfies deep-equal($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 (specifically, an XNode).
$i2 is a node (specifically, an XNode).
Both nodes have the same node kind.
Either the base-uri option is false, or both nodes have the same value
for their base URI property, or both nodes have an absent base URI.
Let significant-children($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 processing-instructions is false.
Adjacent text nodes are merged.
Whitespace-only text nodes are discarded if both the following conditions are true:
The option whitespace is set to strip
or normalize; and
The text node is not within the scope
of an element that has the attribute xml:space="preserve".
Whitespace text nodes will already have been discarded if
$parent is a schema-validated element node whose type annotation
is a complex type with an element-only or empty content model.
One of the following conditions is true.
Both nodes are document nodes, and the sequence significant-children($i1)
is deep-equal to the sequence significant-children($i2).
Both nodes are element nodes, and all the following conditions are true:
The two nodes have the same name, that is (node-name($i1) eq
node-name($i2)).
Either the option namespace-prefixes is false, or both element
names have the same prefix.
Either the option in-scope-namespaces is false, or both element
nodes have the same in-scope namespace bindings.
Either the option type-annotations is false, or both
element nodes have the same type annotation.
Either the option id-property is false, or both element
nodes have the same value for their is-id property.
Either the option idrefs-property is false, or both element
nodes have the same value for their is-idrefs property.
Either the option nilled-property is false, or both element
nodes have the same value for their nilled property.
One of the following conditions is true:
The option type-variety 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 deep-equal 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 node-name($a1) eq node-name($a2)
and $a1 and $a2 are deep-equal.
Attributes, like other items, may be compared using the supplied items-equal
function. However, this function will not be called to compare two attribute nodes unless
they have the same name.
One of the following conditions holds:
Both element nodes are annotated as having simple content (as defined
above), the typed-values option is true,
and the typed value of $i1 is deep-equal
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 typed-values option is false,
and the equal-strings 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
element-only, mixed, or empty content,
the (common) element name is not present in the unordered-elements option,
and the sequence significant-children($i1) is
deep-equal to the sequence significant-children($i2).
Both element nodes have a type annotation that is a complex type with
element-only, mixed, or empty content,
the (common) element name is present in the unordered-elements option,
and the sequence significant-children($i1) is
deep-equal to some permutation of the sequence significant-children($i2).
Elements annotated as xs:untyped fall into this category.
Including an element name in the unordered-elements list is unlikely
to be useful except when the relevant elements have element-only 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 (node-name($i1) eq
node-name($i2)).
Either the option namespace-prefixes is false, or both
attribute names have the same prefix.
Either the option type-annotations is false, or both
attribute nodes have the same type annotation.
Either the option id-property is false, or both attribute nodes
have the same value for their is-id property.
Either the option idrefs-property is false, or both attribute nodes
have the same value for their is-idrefs property.
Let T be true if the option typed-value is true
and both attributes $i1 and $i2 have a type
annotation other than xs:untypedAtomic.
Then either T is true and the typed value of $i1
is deep-equal to the typed value of $i2, or T is false
and the equal-strings 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 (node-name($i1) eq
node-name($i2)).
The equal-strings 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:deep-equal(node-name($i1), node-name($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 top-level sequences
passed explicitly to the
Both nodes are comment nodes, and the equal-strings function
returns true when applied to their string values.
Both nodes are text nodes, and the equal-strings function
returns true when applied to their string values.
All the following conditions are true:
$i1 is a JNode.
$i2 is a JNode.
The $i1
is deep-equal to the $i2.
The other properties of the two JNodes, such as
In all other cases the result is false.
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 attributes is considered significant. There are various ways whitespace differences can be ignored:
If nodes have been schema-validated, setting the typed-values
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 in-scope namespaces. They may also differ in their parent,
their base URI, and the values returned by the is-id and
is-idrefs 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.
Comparing items of different kind (for example, comparing an atomic
item 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:deep-equal(1, current-dateTime()) is false.
The items-equal callback function may be used to override the default rules
for comparing individual items. For example, it might return true unconditionally
when comparing two @timestamp attributes, if there is no expectation that the
two trees will have identical timestamps. Given two nodes $n1 and $n2,
it might compare them using the is operator, so that instead of comparing the
descendants of the two nodes, the function simply checks whether they are the same node.
Given two function items $f1 and $f2 it might return true unconditionally,
knowing that there is no effective way to test if the functions are equivalent. Given
two numeric values, it might return true if they are equal to six decimal places.
It is good practice for the items-equal callback function to be reflexive,
symmetric, and transitive; if it is not, then the NaN)
should be equal to itself; items-equal(A, B)
should return the same result as items-equal(B, A), and items-equal(A, B) and items-equal(B, C) should
imply items-equal(A, C).
Setting the ordered option to false or supplying the
unordered-elements option may result in poor performance when comparing
long sequences, especially if the items-equal callback function is supplied.
| Variables | |
|---|---|
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
|
| Expression: | |
| Result: |
|
| Expression: | |
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
xs:hexBinary
and xs:base64Binary are now mutually comparable. In rare cases, where an
application uses both types and assumes they are distinct, this can represent a backwards
incompatibility.Returns the values that appear in a sequence, with duplicates eliminated.
The one-argument form of this function is
The two-argument form of this function is
The function returns the sequence that results from removing from $values all
but one of a set of values that are
The ordering of the result is as follows:
For any set of values that compare equal, the one that is
returned is the one that appears first in $values.
The items that are returned appear in the order of their first
appearance within $values.
The effect of the function is equivalent to the result of the following XPath expression.
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 numeric values, the rules are the same as NaN is treated
as equal to NaN, and values of different numeric types are converted
to unlimited-precision decimals for comparison purposes.
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.
| Expression | Result |
|---|---|
distinct-values((1, 2.0, 3, 2)) |
|
Returns the values that appear in a sequence more than once.
The one-argument form of this function is
The two-argument form of this function is
The items of $values are compared against each other, according to the
rules of $collation 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.
Specifically, the function returns those items in $values that are
This means that the ordering of the result is as follows:
For any set of values that compare equal, the one that is
returned is the one that appears second in $values.
The items that are returned appear in the order of their second
appearance within $values.
The effect of the function is equivalent to the result of the following XPath expression.
The comparison rules are exactly the same as the
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
Raise an error for duplicates in an ID sequence: | |
Determines whether one sequence ends with another, using a supplied callback function to compare items.
The two-argument form of this function is
The three-argument form of this function is
Informally, the function returns true if $input ends with $subsequence,
when items are compared using the $compare function.
The effect of the function is equivalent to the result of the following XPath expression.
There is no requirement that the $compare function should have the traditional qualities
of equality comparison. The result is well-defined, for example, even if $compare is not transitive
or not symmetric.
A return value of () from the function is treated as false.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
NaN is now considered equal to NaN.Returns a sequence of positive integers giving the positions within the sequence
$input of items that are $target.
The two-argument form of this function is
The three-argument form of this function is
The function returns a sequence of positive integers giving the 1-based positions within the
sequence $input of items that are $target.
The collation used by this function is determined according to the rules in
The result sequence is in ascending numeric order.
If $input is the empty sequence, or if no item in
$input matches $target, then the function returns the empty
sequence.
No error occurs if non-comparable values are encountered. So when comparing two atomic
items, the effective boolean value of fn:index-of($a, $b) is true if
$a and $b are equal, false if they are not equal or not
comparable.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
If | |
Determines whether one sequence starts with another, using a supplied callback function to compare items.
The two-argument form of this function is
The three-argument form of this function is
Informally, the function returns true if $input starts with $subsequence,
when items are compared using the $compare function.
The effect of the function is equivalent to the result of the following XPath expression.
There is no requirement that the $compare function should have the traditional qualities
of equality comparison. The result is well-defined, for example, even if $compare is not transitive
or not symmetric. A return value of () from the function is treated as false.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
|
The following functions assert the cardinality of their sequence arguments.
| Function | Meaning |
|---|---|
fn:exactly-one | Returns $input if it contains exactly one item. Otherwise, raises an error.
|
fn:one-or-more | Returns $input if it contains one or more items. Otherwise, raises an error.
|
fn:zero-or-one | Returns input if it contains zero or one items. Otherwise, raises an
error. |
The functions fn:remove($seq, fn:index-of($seq2, 'abc'))
requires the result of the call on fn:remove($seq, fn:exactly-one(fn:index-of($seq2, 'abc')))
would provide a suitable static type at query analysis time, and ensure that the length of the sequence is
correct with a dynamic check at query execution time.
The 4.0 specifications no longer define strict static typing as an option, so the utility of these functions has declined. They may still serve a purpose, however, as assertions signaling expected preconditions both to the processor and to anyone reading the code.
The type signatures for these functions deliberately declare the argument type as
item()*, permitting a sequence of any length. A more restrictive
signature would defeat the purpose of the function, which is to defer
cardinality checking until query execution time.
Returns $input if it contains exactly one item. Otherwise, raises an error.
This function is
Except in error cases, the function returns $input unchanged.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
A dynamic error is raised $input is an
empty sequence or a sequence containing more than one item.
Returns $input if it contains one or more items. Otherwise, raises an error.
This function is
Except in error cases, the function returns $input unchanged.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
A dynamic error is raised $input is an
empty sequence.
Returns input if it contains zero or one items. Otherwise, raises an
error.
This function is
Except in error cases, the function returns $input unchanged.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
A dynamic error is raised $input
contains more than one item.
Aggregate functions take a sequence as argument and return a single value
computed from values in the sequence. Except for xs:untypedAtomic values are permitted in the
input sequence and handled by special conversion rules. The type of the items in
the sequence must also support certain operations.
| Function | Meaning |
|---|---|
fn:count | Returns the number of items in a sequence. |
fn:all-equal | Returns true if all items in a supplied sequence (after atomization) are
|
fn:all-different | Returns true if no two items in a supplied sequence are
|
fn:avg | Returns the average of the values in the input sequence $values, that is, the
sum of the values divided by the number of values. |
fn:max | Returns a value that is greater than or equal to every other value appearing in the input sequence. |
fn:min | Returns a value that is less than or equal to every other value appearing in the input sequence. |
fn:sum | Returns a value obtained by adding together the values in $values. |
Returns the number of items in a sequence.
This function is
The function returns the number of items in $input.
The function is defined as follows, making use of primitive constructors and accessors defined
in
The function returns 0 if $input is the empty sequence.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
count($tree//chap/p) |
|
count($seq3) |
|
count($seq2) |
|
count($seq2[. > 100]) |
|
count([]) |
|
count([ 1, 2, 3 ]) |
|
fn:uniformReturns true if all items in a supplied sequence (after atomization) are
This function is
The collation used by this function is determined according to the rules in
The result of the function fn:all-equal($values, $collation) is true if and only if the result
of fn:count(fn:distinct-values($values, $collation)) le 1 is true (that is, if the sequence
is empty, or if all the items in the sequence are equal under the rules of the
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: |
|
| Result: | Returns |
| Expression: |
|
| Result: | Returns |
fn:uniqueReturns true if no two items in a supplied sequence are
This function is
The collation used by this function is determined according to the rules in
The result of the function fn:all-different($values, $collation) is true if and only if the result
of fn:count(fn:distinct-values($values, $collation)) eq fn:count($values) is true
(that is, if the sequence
is empty, or if all the items in the sequence are
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: |
|
| Result: | Returns |
| Expression: |
|
| Result: | Returns |
Returns the average of the values in the input sequence $values, that is, the
sum of the values divided by the number of values.
This function is
If $values is the empty sequence, the empty sequence is returned.
Any item in $values that is an instance of xs:untypedAtomic
is cast to xs:double.
After this conversion, one of the following conditions must be true:
Every item in $values is an instance of xs:yearMonthDuration.
Every item in $values is an instance of xs:dayTimeDuration.
Every item in $values is an instance of xs:numeric.
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. Note that the
A type error is raised
| Variables | |
|---|---|
| Expression | Result |
|---|---|
avg($seq3) |
|
avg(($d1, $d2)) |
|
avg(()) |
|
avg((xs:float('INF'), xs:float('-INF'))) |
|
avg(($seq3, xs:float('NaN'))) |
|
fn:avg(($d1, $seq3)) | Raises error FORG0006. |
xs:integer or xs:decimal values, the result is an xs:integer or
xs:decimal, rather than the result of converting this to an xs:float
or xs:double.Returns a value that is greater than or equal to every other value appearing in the input sequence.
The one-argument form of this function is
The two-argument form of this function is
Any item in $values that is an instance of xs:untypedAtomic
is first cast to xs:double. The resulting sequence is referred to as the
converted sequence.
All pairs of values in the converted sequence must be mutually comparable. Two values A
and B are mutually
comparable if fn:compare(A, B) raises no error.
If the converted sequence is empty, the function returns the empty sequence.
If the converted sequence contains the value NaN, the value
NaN is returned
xs:float or xs:double as appropriate)
Two items A
and B from the converted sequence are compared
by calling fn:compare(A, B, $collation),
where $collation
is determined by the rules in
The result of the function is a value from the converted sequence that is greater than
or equal to every other value under the above rules. If there is more than one such value, then it is
A type error is raised
If there are two or 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 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.
In version 4.0, if $values is a sequence of xs:decimal values
(including the case where it is a sequence of xs:integer values), then
the result will be one of these xs:decimal or xs:integer values.
In earlier versions it would
be the result of converting this xs:decimal to xs:float or xs:double.
| Expression | Result |
|---|---|
max((3, 2, 1)) |
|
max([ 3, 2, 1 ]) |
|
max((
xs:integer(5),
xs:float(5),
xs:double(0)
)) |
|
max((
xs:float(0.0E0),
xs:float(-0.0E0)
)) |
|
max((
current-date(),
xs:date("2100-01-01")
)) |
|
max(("a", "b", "c")) |
|
max((3, 4, "Zero")) | Raises error FORG0006. |
xs:integer or xs:decimal values, the result is an xs:integer or
xs:decimal, rather than the result of converting this to an xs:float or
xs:double.Returns a value that is less than or equal to every other value appearing in the input sequence.
The one-argument form of this function is
The two-argument form of this function is
Any item in $values that is an instance of xs:untypedAtomic
is first cast to xs:double. The resulting sequence is referred to as the
converted sequence.
All pairs of values in the converted sequence must be mutually comparable. Two values A
and B are mutually
comparable if fn:compare(A, B) raises no error.
If the converted sequence is empty, the function returns the empty sequence.
If the converted sequence contains the value NaN, the value
NaN is returned
xs:float or xs:double as appropriate)
Two items A
and B from the converted sequence are compared
by calling fn:compare(A, B, $collation),
where $collation
is determined by the rules in
The result of the function is a value from the converted sequence that is less than
or equal to every other value under the above rules. If there is more than one such value, then it is
A type error is raised
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 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.
In version 4.0, if $values is a sequence of xs:decimal values
(including the case where it is a sequence of xs:integer values), then
the result will be one of these xs:decimal or xs:integer values.
In earlier versions it would
be the result of converting this xs:decimal to xs:float
or xs:double.
| Expression | Result |
|---|---|
min((3, 4, 5)) |
|
min([ 3, 4, 5 ]) |
|
min((
xs:integer(5),
xs:float(5),
xs:double(10)
)) |
|
min((
xs:float(0.0E0),
xs:float(-0.0E0)
)) |
|
min((
current-date(),
xs:date("1900-01-01")
)) |
|
min(("a", "b", "c")) |
|
min((3, 4, "Zero")) | Raises error FORG0006. |
Returns a value obtained by adding together the values in $values.
This function is
Any value of type xs:untypedAtomic in $values is 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.
In other cases the items in the converted sequence are added pairwise according
the rules of the + operator.
Specifically, the result of the function is the value of the expression:
where $c is the converted sequence.
This has the effect that a type error will occur unless one of the following conditions is satisfied:
Every item in $values is an instance of xs:yearMonthDuration.
Every item in $values is an instance of xs:dayTimeDuration.
Every item in $values is an instance of xs:numeric.
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 zero-length 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 non-empty sequence sums to zero. For example, sum((-1, +1), xs:double('NaN'))
returns the xs:integer value 0, not NaN.
The sum of a sequence of integers will be an integer, while the
sum of a numeric sequence that includes at least one xs:double will be an
xs:double.
If the converted sequence contains exactly one value then that value is returned.
If the converted sequence contains the value NaN, NaN is
returned.
In edge cases the fact that the input sequence may be reordered makes the result
slightly unpredictable. For example, if the input contains two xs:decimal
values and an xs:float, then the decimal values might be added using
decimal arithmetic, or they might both be converted to xs:float
(potentially losing precision) before any arithmetic is performed.
| Variables | |
|---|---|
| Expression: |
|
|---|---|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: | Raises error FORG0006. |
The following functions take function items as an argument.
| Function | Meaning |
|---|---|
fn:apply | Makes a dynamic call on a function with an argument list supplied in the form of an array. |
fn:do-until | Processes a supplied value repeatedly, continuing when some condition is false, and returning the value that satisfies the condition. |
fn:every | Returns true if every item in the input sequence matches a supplied predicate. |
fn:filter | Returns those items from the sequence $input for which the supplied function
$predicate returns true. |
fn:fold-left | Processes the supplied sequence from left to right, applying the supplied function repeatedly to each item in turn, together with an accumulated result value. |
fn:fold-right | Processes the supplied sequence from right to left, applying the supplied function repeatedly to each item in turn, together with an accumulated result value. |
fn:for-each | Applies the function item $action to every item from the sequence $input
in turn, returning the concatenation of the resulting sequences in order. |
fn:for-each-pair | 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. |
fn:highest | Returns a value that is greater than or equal to every other value appearing in the input sequence. |
fn:index-where | Returns the positions in an input sequence of items that match a supplied predicate. |
fn:lowest | Returns those items from a supplied sequence that have the lowest value of a sort key, where the sort key can be computed using a caller-supplied function. |
fn:partial-apply | Performs partial application of a function item by binding values to selected arguments. |
fn:partition | Partitions a sequence of items into a sequence of non-empty arrays containing the same items, starting a new partition when a supplied condition is true. |
fn:scan-left | Produces the sequence of successive partial results from
the evaluation of |
fn:scan-right | Produces the sequence of successive partial results from
the evaluation of |
fn:some | Returns true if at least one item in the input sequence matches a supplied predicate. |
fn:sort | Sorts a supplied sequence, based on the value of a sort key supplied as a function. |
fn:sort-by | Sorts a supplied sequence, based on the value of a number of sort keys supplied as functions. |
fn:sort-with | Sorts a supplied sequence, according to the order induced by the supplied comparator functions. |
fn:subsequence-where | Returns a contiguous sequence of items from $input, with the start and end
points located by applying predicates. |
fn:take-while | Returns items from the input sequence prior to the first one that fails to match a supplied predicate. |
fn:transitive-closure | Returns all the GNodes reachable from a given start GNode by applying a supplied function repeatedly. |
fn:while-do | Processes a supplied value repeatedly, continuing while some condition remains true, and returning the first value that does not satisfy the condition. |
With all these functions, if the caller-supplied function fails with a dynamic error, this error is propagated as an error from the higher-order function itself.
Makes a dynamic call on a function with an argument list supplied in the form of an array.
This function is
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 $arguments, and so on.
The arity of the supplied function $function must be less than or equal to the size
of the array $arguments.
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 coercion rules are applied to the supplied arguments
in the usual way. Among other things this means that excess arguments are ignored.
A dynamic error is raised if the arity of the function $function is greater than the size of the
array $arguments (
The function is useful where the arity of a function item is not known statically.
| Expression | Result |
|---|---|
apply(concat#3, [ "a", "b", "c" ]) |
|
The expression | |
$predicate callback function may return the empty sequence (meaning false).Processes a supplied value repeatedly, continuing when some condition is false, and returning the value that satisfies the condition.
This function is
Informally, the function behaves as follows:
$pos is initially set to 1.
$action($input, $pos) is evaluated, and the resulting value
is used as a new $input.
$predicate($input, $pos) is evaluated. If the result is
true, the function returns the value of $input.
Otherwise, the process repeats from step 2 with $pos incremented by
1.
When the predicate returns the empty sequence, this is treated as false.
The function delivers the same result as the following XQuery implementation.
Do-until loops are very common in procedural programming languages, and this function provides a way to write functionally clean and interruptible iterations without side-effects. A new value is computed and tested until a given condition fails. Depending on the use case, the value can be a simple atomic item or an arbitrarily complex data structure.
The function
Note that, just as when writing recursive functions, it is easy to construct infinite loops.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: |
$predicate callback function may return the empty sequence (meaning false).Returns true if every item in the input sequence matches a supplied predicate.
This function is
The function returns true if $input is empty, or if $predicate($item, $pos)
returns true for every item $item at position $pos (1-based) in $input.
The effect of the function is equivalent to the result of the following XPath expression.
An error is raised if the $predicate function raises an error. In particular,
when the default predicate fn:boolean#1 is used, an error is raised if an
item has no effective boolean value.
It is possible for the supplied $predicate to be a function whose arity is less than two.
The coercion rules mean that the additional parameters are effectively ignored. Frequently a predicate
function will only consider the item itself, and disregard its position in the sequence.
The predicate is required to return either true, false, or the empty
sequence (which is treated as false). A predicate such as fn { self::h1 }
results in a type error because it returns a node, not a boolean.
The implementation false; it is not required to evaluate the predicate for every item,
nor is it required to examine items sequentially from left to right.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: |
$predicate callback function accepts an optional position argument.$predicate callback function may return the empty sequence (meaning false).Returns those items from the sequence $input for which the supplied function
$predicate returns true.
This function is
The function returns a sequence containing those items from $input
for which $predicate($item, $pos) returns true, where $item
is the item in question, and $pos is its 1-based ordinal position within $input.
The effect of the function is equivalent to the result of the following XPath expression.
As a consequence of the function signature and the function calling rules, a type error
occurs if the supplied $predicate function returns anything other than a single
xs:boolean item or the empty sequence; there is no conversion to an effective boolean
value, but the empty sequence is interpreted as false.
If $predicate is an arity-1 function,
the function call fn:filter($input, $predicate) has a very similar effect to the
expression $input[$predicate(.)]. There are some differences, however. In the case of
$F is required to return an optional boolean;
there is no special treatment for numeric predicate values, and no conversion to an
effective boolean value. Also, with a filter expression $input[$predicate(.)],
the focus within the predicate is different from that outside; this means that the use of a
context-sensitive function such as fn:lang#1 will give different results in
the two cases.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: | |
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: |
Processes the supplied sequence from left to right, applying the supplied function repeatedly to each item in turn, together with an accumulated result value.
This function is
If $input is empty, the function returns $init.
If $input contains at least one item, the function calls
$action($init, $input[1]), returning a value A1.
If $input contains a second item, the function then calls
$action(A1, $input[2]), returning A2; to process the nth
item it calls $action(A/n-1, $input[N]).
This continues in the same way until the end of the $input sequence; the final result is
the result of the last call on $action.
The function delivers the same result as the following XQuery implementation.
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 $init 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 typically 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 $init argument, which is conventionally a
value (such as zero in the case of addition, one in the case of multiplication, or a
zero-length string in the case of string concatenation) that causes the function to
return the value of the other argument unchanged.
Unlike other functions that apply a user-supplied callback function to successive
items in a sequence, this function does not supply the current position to the callback function
as an optional argument. If positional information is required, this can be achieved by
first forming the sequence $input ! { 'position': position(), 'item': . }
and then applying the
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
|
| Expression: | |
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Processes the supplied sequence from right to left, applying the supplied function repeatedly to each item in turn, together with an accumulated result value.
This function is
If $input is empty, the function returns $init.
Let I/n be the last item in $input, and let A/n be $init.
The function starts by calling $action(I/n, $init), producing
a result A/n-1.
If there is a previous item, I/n-1,
the function then calls $action(I/n-1, A/n-1), producing
the result A/n-2.
This continues in the same way until the start of the $input sequence is reached; the final result is
the value A/0.
The function delivers the same result as the following XQuery implementation.
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 $init 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 $init
argument, which is conventionally a value (such as zero in the case of addition, one in
the case of multiplication, or a zero-length 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),
Unlike other functions that apply a user-supplied callback function to successive
items in a sequence, this function does not supply the current position to the callback function
as an optional argument. If positional information is required, this can be achieved by
first forming the sequence $input ! { 'position': position(), 'item': . }
and then applying the
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
$action callback function accepts an optional position argument.Applies the function item $action to every item from the sequence $input
in turn, returning the concatenation of the resulting sequences in order.
This function is
The function calls $action($item, $pos) for each item in $input,
where $item is the item in question and $pos is its 1-based
ordinal position in $input. The final result is the sequence concatenation
of the result of these calls, preserving order.
The function is defined as follows, making use of primitive constructors and accessors defined
in
| Expression: |
|
|---|---|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: |
$action callback function accepts an optional position argument.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.
This function is
The function returns the value of the expression:
If one sequence is longer than the other, excess items in the longer sequence are ignored.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns a value that is greater than or equal to every other value appearing in the input sequence.
This function is
The second argument, $collation, defaults to ().
Supplying an empty
sequence as $collation is equivalent to supplying
fn:default-collation(). For more
information on collations see
The third argument, $key, defaults to the function data#1.
Let $modified-key be the function:
That is, the supplied function for computing key values is wrapped in a function that
converts any xs:untypedAtomic values in its result to xs:double. This makes
the function consistent with the behavior of
The result of the function is obtained as follows:
If the input is an empty sequence, the result is an empty sequence.
The input sequence is sorted, by applying the function
fn:sort($input, $collation, $modified-key).
Let $C be the selected collation, or the default collation where applicable.
Let $B be the last item in the sorted sequence.
The function returns those items $A from the input sequence
that are $B,
retaining their order.
If the set of computed keys contains xs:untypedAtomic values that are not
castable to xs:double then the
operation will fail with a dynamic error (
If the set of computed keys contains values that are not comparable using
the lt operator then the sort
operation will fail with a type error (
| Variables | |
|---|---|
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: | The employees having the highest salary. |
$predicate callback function may return the empty sequence (meaning false).Returns the positions in an input sequence of items that match a supplied predicate.
This function is
The result of the function is a sequence of integers, in monotonic ascending order, representing
the 1-based positions in the input sequence of those items for which the supplied predicate function
returns true. A return value of () from the predicate function
is treated as false.
The effect of the function is equivalent to the result of the following XPath expression.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns those items from a supplied sequence that have the lowest value of a sort key, where the sort key can be computed using a caller-supplied function.
This function is
The collation used by this function is determined according to the rules in
Let $modified-key be the function:
That is, the supplied function for computing key values is wrapped in a function that
converts any xs:untypedAtomic values in its result to xs:double. This makes
the function consistent with the behavior of
The result of the function is obtained as follows:
If the input is the empty sequence, the result is the empty sequence.
The input sequence is sorted, by applying the function
fn:sort($input, $collation, $modified-key).
Let $C be the selected collation, or the default collation where applicable.
Let $B be the first item in the sorted sequence.
The function returns those items $A from the input sequence
that are $B,
retaining their order.
If the set of computed keys contains xs:untypedAtomic values that are not
castable to xs:double then the
operation will fail with a dynamic error (
If the set of computed keys contains values that are not comparable using
the lt operator then the sort
operation will fail with a type error (
| Variables | |
|---|---|
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: | The employees having the lowest salary. |
Performs partial application of a function item by binding values to selected arguments.
This function is
The result is a function obtained by binding values to selected arguments of
the function item $function. The arguments to be bound are represented
by entries in the $arguments map: an entry with key $i
and value $v causes the argument at position $i (1-based)
to be bound to $v.
Any entries in $arguments whose keys are greater than the arity of
$function are ignored.
If $arguments is the empty map then the function returns $function
unchanged.
For example, the effect of calling fn:partial-apply($f, { 2: $x })
is the same as the effect of the partial
appplication $f(?, $x, ?, ?, ....).
The coercion rules are applied to the supplied arguments
in the usual way.
Unlike a partial application using place-holder arguments:
The arity of $function need not be statically known.
It is possible to bind all the arguments of $function: the effect
is to return a zero-arity function.
The result is a
See also
$function minus the
number of parameters in $function that map to supplied
arguments in $arguments.
$function
that do not map to supplied
arguments in $arguments.
$function
that do not map to supplied
arguments in $arguments,
retaining order. The result type of the returned function
is the same as the result type of $function.
An implementation that can determine a more specific signature (for example, through use of type analysis) is permitted to do so.
$function.
$function, augmented,
for each supplied argument, with
a binding of the converted argument value
to the corresponding parameter name.
A type error is raised if any of the supplied arguments, after applying the coercion rules, does not match the required type of the corresponding function parameter.
In addition, a dynamic error may be raised if any of the supplied arguments does not match other constraints on the value of that argument (for example, if the value supplied for a parameter expecting a regular expression is not a valid regular expression); or if the processor is able to establish that evaluation of the resulting function will fail for any other reason (for example, if an error is raised while evaluating a subexpression in the function body that depends only on explicitly supplied and defaulted parameters).
See also
The function is useful where the arity of a function item is not known statically, or where all arguments in a function are to be bound, returning a zero-arity function.
| Expression: | |
|---|---|
| Result: |
Partitions a sequence of items into a sequence of non-empty arrays containing the same items, starting a new partition when a supplied condition is true.
This function is
Informally, the function starts by creating a partition containing the first item in the input sequence,
if any. For each remaining item J in the input sequence,
other than the first, it calls the supplied $split-when function with three
arguments: the contents of the current partition, the item J, and the current
position in the input sequence.
Each partition is a sequence of items; the function result wraps each partition as an array, and returns the sequence of arrays.
If the $split-when function returns true, the current partition is wrapped as an array and added to the result,
and a new current partition is created, initially containing the item J only. If the $split-when
function returns false or (), the item J is added to the current partition.
The effect of the function is equivalent to the result of the following XPath expression.
The function enables a variety of positional grouping problems to be solved. For example:
partition($input, fn($a, $b) { count($a) eq 3 }
partitions a sequence into fixed size groups of length 3.
partition($input, fn($a, $b) { boolean($b/self::h1) }
starts a new group whenever an h1 element is encountered.
partition($input, fn($a, $b) { $b lt foot($a) }
starts a new group whenever an item is encountered whose value is less than
the value of the previous item.
The callback function is not called to process the first item in the input sequence, because this will always start a new partition. The first argument to the callback function (the current partition) is always a non-empty sequence.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Produces the sequence of successive partial results from
the evaluation of
This function is
The function returns a sequence of N+1
$input. For values of $n in the range 0 to N,
the value of the single member of array $n+1 in the result sequence is the value of the expression
fold-left( subsequence($input, 1, $n), $init, $action ).
The effect of the function is equivalent to the result of the following XPath expression.
A practical implementation is likely to compute each array in the result sequence based on the value of the previous item, rather than computing each item independently as implied by the specification.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Produces the sequence of successive partial results from
the evaluation of
This function is
The function returns a sequence of N+1
$input. For values of $n in the range 0 to N,
the value of the single member of array $n+1 in the result sequence is the value of the expression
fold-right( subsequence($input, count($input)-$n+1), $init, $action ).
The effect of the function is equivalent to the result of the following XPath expression.
A practical implementation is likely to compute each array in the result sequence based on the value of the previous item, rather than computing each item independently as implied by the specification.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
$predicate callback function may return the empty sequence (meaning false).Returns true if at least one item in the input sequence matches a supplied predicate.
This function is
The function returns true if (and only if) there is an item $item at position $pos
in the input sequence such that $predicate($item, $pos) returns true.
The effect of the function is equivalent to the result of the following XPath expression.
An error is raised if the $predicate function raises an error. In particular,
when the default predicate fn:boolean#1 is used, an error is raised if an
item has no effective boolean value.
It is possible for the supplied $predicate to be a function whose arity is less than two.
The coercion rules mean that the additional parameters are effectively ignored. Frequently a predicate
function will only consider the item itself, and disregard its position in the sequence.
The predicate is required to return either true, false, or the empty
sequence (which is treated as false). A predicate such as fn { self::h1 }
results in a type error because it returns a node, not a boolean.
The implementation true; it is not required to evaluate the predicate for every item,
nor is it required to examine items sequentially from left to right.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
Sorts a supplied sequence, based on the value of a sort key supplied as a function.
This function is
This function is retained for compatibility from version 3.1 of this specification. Version 4.0
introduces two more powerful functions,
The function call fn:sort($input, $collation, $key) is defined to have the same effect as the
call fn:sort-by($input, { 'key': $key, 'collation': $collation, 'order': 'ascending'}).
See
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 the supplied sort key definitions.
The effect of the function is equivalent to the result of the following XPath expression.
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 (
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | The names in |
| Expression: | |
| Result: | A sorted sequence of employees by last name as the major sort key and first name as the minor sort key, using the default collation. |
Sorts a supplied sequence, based on the value of a number of sort keys supplied as functions.
This function is
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 the supplied
A
key: A fn:data#1,
which atomizes the item.
collation: A xs:string or xs:untypedAtomic. If no collation is supplied, the default
collation from the static context is used.
When comparing values of types other than xs:string or xs:untypedAtomic,
the collation is ignored (but an error
order: An "ascending" or
"descending". The default is "ascending".
The number of sort key definitions is determined by the number of records supplied
in the $keys argument. If the argument is absent or empty, the default is
a single sort key definition using the function data#1, using the default collation
from the static context, and with order ascending.
The result of the fn:sort-by 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 major-to-minor 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 items.
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:lexicographic-compare($key($A), $key($B), $C)
where op:lexicographic-compare($a, $b, $C) is defined as follows:
Here op:simple-compare($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 non-ordered
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 (
The function is a generalization of the
If the sort key for an item evaluates to the empty sequence, the effect of the rules is that this item
precedes any value for which the key is non-empty. This is equivalent to the effect of the XQuery option
empty least. The effect of the option empty greatest can be achieved by adding an
extra sort key definition with { 'key': fn { empty(K(.) } }: when comparing boolean sort keys,
false precedes true.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | The names in |
| Expression: | |
| Result: | Sorts a sequence of employees by last name as the major sort key and first name as the minor sort key, using the default collation |
| Expression: | |
| Result: | Sorts a sequence of employees first by increasing last name (using Swedish collation order) and then by decreasing salary |
Sorts a supplied sequence, according to the order induced by the supplied comparator functions.
This function is
Informally, the items of the supplied $input are sorted into an
order based on the result of evaluating the supplied $comparators.
The result is a sorted sequence.
Each comparator function takes two items and returns an xs:integer that
defines the relationship between these items, following the conventions of the
$c is used to compare two items $a and $b,
it must return a negative integer if $a is to be sorted before $b,
zero if they are considered equal, and a positive integer if $a is
to be sorted after $b.
There may be more than one comparator, representing sort keys in major to minor order.
To determine the relative position of two items $a and $b:
The first comparator is called: $comparators[1]($a, $b). If
the result is non-zero, this determines the relative position of $a
and $b in the result sequence, and any further comparators
can be ignored.
If the Nth comparator returns zero, then:
If this is the last comparator, then the two items are considered
equal, and their relative position in the result sequence will be the same
as their relative position in the input sequence (that is, the sort is
Otherwise, the next comparator is evaluated, and so on, until the last comparator is reached or the result of a comparator is non-zero.
To ensure that the sorting algorithm produces predictable results (indeed, to ensure that it terminates), it is necessary for the comparators to have certain properties. Specifically, for every comparator C:
C must be deterministic (if called twice with the same arguments, it must deliver the same result).
Every item must be equal to itself: C($a, $a) must be zero.
The ordering must be consistent: if C($a, $b) < 0,
then C($b, $a) > 0, and vice versa, and similarly,
if C($a, $b) = 0,
then C($b, $a) = 0.
The ordering must be transitive: if C($a, $b) < 0
and C($b, $c) < 0, then C($a, $c) < 0.
If a comparator function raises an error when processing any pair of items from the input sequence
(for example, if the comparator function is fn:compare#2 and the two items are of
non-comparable types), then the evaluation of
In general it is unpredictable which pairs of items from the input sequence
will actually be compared using each comparator function. However, a comparator function
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns a contiguous sequence of items from $input, with the start and end
points located by applying predicates.
This function is
Informally, the function returns the subsequence of $input starting with the
first item that matches the $from predicate, and ending with the first subsequent
item that matches the $to predicate. If $from is true#0,
it matches for the first item; if $to is false#0, it accepts all
remaining items. If $from does not match any items in $input,
the result is the empty sequence; if $to does not match any items, all items up
to the last are included in the result.
The effect of the function is equivalent to the result of the following XPath expression.
The result includes both the item that matches the $from condition
and the item that matches the $to condition. To select a subsequence that
starts after the $from item, apply the $to item,
apply the
The predicate functions supplied to the $from and $to
parameters can include an integer position argument as well as the item itself.
This position will always be 1-based, relative to the start of $input.
This means it is possible to select items based on their absolute position in the
$input sequence, but there is no mechanism to select an end position
relative to the start position. If this is needed, the function can be combined with others:
for example, to select a subsequence of four items starting with "Barbara",
use $input => subsequence-where(fn { . eq "Barbara" }) => slice(end := 4).
If the requirement is to select all elements stopping before the first h2
element if it exists, or up to the end of the sequence otherwise, the simplest
solution is perhaps to write:
A return value of () from the $from or $to
predicate is treated as false.
| Variables | |
|---|---|
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
$predicate callback function may return the empty sequence (meaning false).Returns items from the input sequence prior to the first one that fails to match a supplied predicate.
This function is
The function returns all items in the sequence prior to the first one where the result of
calling the supplied $predicate function, with the current item and its position
as arguments, returns the value false or ().
If every item in the sequence satisfies the predicate, then $input is returned
in its entirety.
The effect of the function is equivalent to the result of the following XQuery expression.
There is no analogous drop-while or skip-while function,
as found in some functional programming languages. The effect of
drop-while($input, $predicate) can be achieved by calling
fn:subsequence-where($input, fn { not($predicate(.)) }).
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns all the GNodes reachable from a given start GNode by applying a supplied function repeatedly.
This function is
The function works with both XNodes and JNodes.
The value of $node is a node from which navigation starts. If $node is an
empty sequence, the function returns the empty sequence.
The value of $step is a function that takes a single GNode as input, and returns a set of GNodes as its result.
The result of the $node by applying the $step function one or more times.
Although $step may return any sequence of GNodes, the result is treated as a set: the order of GNodes
in the sequence is ignored, and duplicates are ignored. The result of of the
transitive-closure function will always be a sequence of GNodes in document order with no duplicates.
The function delivers the same result as the following XQuery implementation.
Cycles in the data are not a problem; the function stops searching when it finds no new GNodes.
The function may fail to terminate if the supplied $step function constructs and returns
new GNodes. A processor
The $node GNodes is not included in the result, unless it is reachable by applying
the $step function one or more times. If a result is required that does include $node,
it can be readily added to the result using the union operator:
$node | transitive-closure($node, $step).
| Variables | |
|---|---|
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
The following example, given | |
This example uses the XSLT-defined | |
$predicate callback function may return the empty sequence (meaning false).Processes a supplied value repeatedly, continuing while some condition remains true, and returning the first value that does not satisfy the condition.
This function is
Informally, the function behaves as follows:
$pos is initially set to 1.
$predicate($input, $pos) is evaluated. If the result is
false or (), the function returns the value of $input.
Otherwise, $action($input, $pos) is evaluated, the resulting value is
used as a new $input, and the process repeats from step 2 with
$pos incremented by 1.
The function delivers the same result as the following XQuery implementation.
While-do loops are very common in procedural programming languages, and this function provides a way to write functionally clean and interruptible iterations without side-effects. As long as a given condition is met, an new value is computed and tested again. Depending on the use case, the value can be a simple atomic item or an arbitrarily complex data structure.
The function
Note that, just as when writing recursive functions, it is easy to construct infinite loops.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
The following example generates random doubles. It is interrupted once a number exceeds a given limit: | |
This section defines functions and operators on the xs:boolean datatype.
Since no literals are defined in XPath to reference the constant boolean values true and false,
two functions are provided for the purpose.
| Function | Meaning |
|---|---|
fn:true | Returns the xs:boolean value true. |
fn:false | Returns the xs:boolean value false. |
Returns the xs:boolean value true.
This function is
The result is equivalent to xs:boolean("1").
| Expression | Result |
|---|---|
true() |
|
Returns the xs:boolean value false.
This function is
The result is equivalent to xs:boolean("0").
| Expression | Result |
|---|---|
false() |
|
The following functions are defined on boolean values:
| Function | Meaning |
|---|---|
fn:boolean | Computes the effective boolean value of the sequence $input. |
fn:not | Returns true if the effective boolean value of $input is
false, or false if it is true. |
Computes the effective boolean value of the sequence $input.
The function computes the effective boolean value of a sequence, defined according to
the following rules. See also
If $input is the empty sequence, false.
If $input is a sequence whose first item is a true.
If $input is a singleton value of type xs:boolean or of a type
derived from xs:boolean, $input.
If $input is a singleton value of type xs:untypedAtomic,
xs:string, xs:anyURI, or a type derived from xs:string
or xs:anyURI, 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, 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,
The result of this function is not necessarily the same as $input cast as
xs:boolean. For example, fn:boolean("false") returns the value
true whereas "false" cast as xs:boolean (which can also be
written xs:boolean("false")) returns false.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
boolean($abc[1]) |
|
boolean($abc[0]) |
|
boolean($abc[3]) |
|
fn:boolean($abc) | Raises error FORG0006. |
fn:boolean([]) | Raises error FORG0006. |
Returns true if the effective boolean value of $input is
false, or false if it is true.
This function is
The value of $input is first reduced to an effective boolean value by
applying the fn:boolean() function. The function returns true
if the effective boolean value is false, or false if the
effective boolean value is true.
| Expression | Result |
|---|---|
not(true()) |
|
not(()) |
|
not("false") |
|
fn:not(1 to 10) | Raises error FORG0006. |
This section specifies arithmetic operators on the numeric datatypes defined in
The operators described in this section are defined on the following atomic types.
They also apply to types derived by restriction from the above types.
The type xs:numeric is defined as a union type whose member types are
(in order) xs:double, xs:float, and xs:decimal. This type is implicitly imported
into the static context, so it can also be used in defining the signature of user-written functions. Apart from the fact that
it is implicitly imported, it behaves exactly like a user-defined type with the same definition. This means, for example:
If the expected type of a function parameter is given as xs:numeric, the actual value supplied
can be an instance of any of these three types, or any type derived from these three by restriction (this includes the built-in
type xs:integer, which is derived from xs:decimal).
If the expected type of a function parameter is given as xs:numeric, and the actual value supplied
is xs:untypedAtomic (or a node whose atomized value is xs:untypedAtomic), then it will
be cast to the union type xs:numeric using the rules in xs:double subsumes the lexical space of the other member types, and
xs:double is listed first, the effect is that if the untyped atomic item is in the lexical space of
xs:double, it will be converted to an xs:double, and if not, a dynamic error occurs.
When the return type of a function is given as xs:numeric, the actual value returned will be
an instance of one of the three member types (and perhaps also of types derived from these by restriction). The rules
for the particular function will specify how the type of the result depends on the values supplied as arguments.
In many cases, for the functions in this specification, the result is defined to be the same type as the first
argument.
This specification uses xs:float and xs:double values.
One consequence of this is that some operations result in the value NaN (not a number), which
has the unusual property that it is not equal to itself. Another consequence is that some operations return the value negative zero.
This differs from NaN as being equal to itself and defines only a single zero in the value space.
The text accompanying several functions defines behavior for both positive and negative zero inputs and outputs
in the interest of alignment with -0.0e0 (which is actually a unary minus operator
applied to an xs:double value) will always return negative zero: see -0 xs:float or xs:double,
but casting from xs:string
to xs:float or xs:double will always produce negative zero.
XML Schema 1.1 introduces support for positive and negative zero as distinct values, and also uses the NaN.
The following functions define the semantics of arithmetic operators defined in
| Operator | Meaning |
|---|---|
op:numeric-add
| Addition |
op:numeric-subtract
| Subtraction |
op:numeric-multiply
| Multiplication |
op:numeric-divide
| Division |
op:numeric-integer-divide
| Integer division |
op:numeric-mod
| Modulus |
op:numeric-unary-plus
| Unary plus |
op:numeric-unary-minus
| Unary minus (negation) |
The parameters and return types for the above operators are in most cases declared to be of type
xs:numeric, which permits the basic numeric
types: xs:integer, xs:decimal, xs:float
and xs:double, and types derived from them.
In general the two-argument functions require that both arguments are of the same primitive type,
and they return a value of this same type.
The exceptions are op:numeric-divide, which returns
an xs:decimal if called with two xs:integer operands,
and op:numeric-integer-divide which always returns an xs:integer.
If the two operands of an arithmetic expression are not of the same type, they
may be converted to a common type as described in
The result type of operations depends on their argument datatypes and is defined in the following table:
| Operator | Returns |
|---|---|
op:operation(xs:integer, xs:integer)
|
xs:integer (except for op:numeric-divide(integer,
integer), which returns xs:decimal) |
op:operation(xs:decimal, xs:decimal)
|
xs:decimal
|
op:operation(xs:float, xs:float)
|
xs:float
|
op:operation(xs:double, xs:double)
|
xs:double
|
op:operation(xs:integer)
|
xs:integer
|
op:operation(xs:decimal)
|
xs:decimal
|
op:operation(xs:float)
|
xs:float
|
op:operation(xs:double)
|
xs:double
|
The basic rules for addition, subtraction, and multiplication
of ordinary numbers are not set out in this specification; they are taken as given. In the case of xs:double
and xs:float the rules are as defined in NaN,
and exception conditions such as overflow and underflow, are described more explicitly since they are not necessarily obvious.
On overflow and underflow situations during arithmetic operations, conforming
implementations
For xs:float and xs:double operations, overflow
behavior
Raising a dynamic error
Returning INF or -INF.
Returning the largest (positive or negative) non-infinite number.
For xs:float and xs:double operations,
underflow behavior
Raising a dynamic error
Returning 0.0E0 or +/- 2**Emin or a
denormalized value; where Emin is the smallest
possible xs:float or xs:double exponent.
For xs:decimal operations, overflow behavior 0.0 must be returned.
For xs:integer operations, implementations that support
limited-precision integer operations
They
They
The functions op:numeric-add, op:numeric-subtract,
op:numeric-multiply, op:numeric-divide,
op:numeric-integer-divide and op:numeric-mod are each
defined for pairs of numeric operands, each of which has the same
type:xs:integer, xs:decimal, xs:float, or
xs:double. The functions op:numeric-unary-plus and
op:numeric-unary-minus are defined for a single operand whose type
is one of those same numeric types.
For xs:float and xs:double arguments, if either
argument is NaN, the result is NaN.
For xs:decimal values, let N be the number of digits
of precision supported by the implementation, and let M (M <= N) be the minimum limit on the number of digits
required for conformance (18 digits for XSD 1.0, 16 digits for XSD 1.1). Then for addition, subtraction, and multiplication
operations, the returned result
This specification does not determine whether xs:decimal operations are fixed point or floating point.
In an implementation using floating point it is possible for very simple operations to require more digits of precision than
are available; for example, adding 1e100 to 1e-100 requires 200 digits of precision for an
accurate representation of the result.
The divideByZero and invalidOperation. The
IEEE divideByZero exception is raised not only by a direct attempt to divide by zero, but also by
operations such as log(0). The IEEE invalidOperation exception is raised by
attempts to call a function with an argument that is outside the function’s domain (for example,
sqrt(-1) or log(-1)).
Although IEEE defines these as exceptions, it also defines “default non-stop exception handling” in
which the operation returns a defined result, typically positive or negative infinity, or NaN. With this
function library,
these IEEE exceptions do not cause a dynamic error
at the application level; rather they result in the relevant function or operator returning
the defined non-error result.
The underlying IEEE exception -INF, +INF, or NaN) with no error.
The NaN values:
a quiet NaN and a signaling NaN. These two values are not distinguishable in the XDM model:
the value spaces of xs:float and xs:double each include only a single
NaN value. This does not prevent the implementation distinguishing them internally,
and triggering different
Although comparison of numeric values across heterogeneous types has changed
to convert both values to xs:decimal, arithmetic operations continue
to use xs:double as the common type.
Returns the arithmetic sum of its operands: ($arg1 + $arg2).
Defines the semantics of the + operator when
applied to two numeric values
General rules: see
For xs:float or xs:double values, if one of the operands is a
zero or a finite number and the other is INF or -INF,
INF or -INF is returned. If both operands are
INF, INF is returned. If both operands are
-INF, -INF is returned. If one of the operands is
INF and the other is -INF, NaN is
returned.
Returns the arithmetic difference of its operands: ($arg1 - $arg2).
Defines the semantics of the - operator when
applied to two numeric values.
General rules: see
For xs:float or xs:double values, if one of the operands is a
zero or a finite number and the other is INF or -INF, an
infinity of the appropriate sign is returned. If both operands are INF or
-INF, NaN is returned. If one of the operands is
INF and the other is -INF, an infinity of the appropriate
sign is returned.
Returns the arithmetic product of its operands: ($arg1 * $arg2).
Defines the semantics of the * operator when
applied to two numeric values.
General rules: see
For xs:float or xs:double values, if one of the operands is a
zero and the other is an infinity, NaN is returned. If one of the operands
is a non-zero number and the other is an infinity, an infinity with the appropriate sign
is returned.
Returns the arithmetic quotient of its operands: ($arg1 div $arg2).
Defines the semantics of the div operator when
applied to two numeric values.
General rules: see
As a special case, if the types of both $arg1 and $arg2 are
xs:integer, then the return type is xs:decimal.
A dynamic error is raised xs:decimal
and xs:integer operands, if the divisor is (positive or negative) zero.
For xs:float and xs:double operands, floating point division
is performed as specified in INF. A negative number divided by positive zero
returns -INF. Division by negative zero returns -INF and
INF, respectively. Positive or negative zero divided by positive or
negative zero returns NaN. Also, INF or -INF
divided by INF or -INF returns NaN.
Performs an integer division.
Defines the semantics of the idiv operator when
applied to two numeric values.
General rules: see
If $arg2 is INF or -INF, and $arg1
is not INF or -INF, then the result is zero.
Otherwise, subject to limits of precision and overflow/underflow conditions, the result
is the largest (furthest from zero) xs:integer value $N such
that the following expression is true:
The second term in this condition ensures that the result has the correct sign.
The implementation may adopt a different algorithm provided that it is equivalent to
this formulation in all cases where xs:decimal
division.
A dynamic error is raised
A dynamic error is raised NaN or if $arg1 is INF or
-INF.
Except in situations involving errors, loss of precision, or overflow/underflow, the
result of $a idiv $b is the same as ($a div $b) cast as
xs:integer.
The semantics of this function are different from integer division as defined in programming languages such as Java and C++.
| Expression | Result |
|---|---|
op:numeric-integer-divide(10, 3) |
|
op:numeric-integer-divide(3, -2) |
|
op:numeric-integer-divide(-3, 2) |
|
op:numeric-integer-divide(-3, -2) |
|
op:numeric-integer-divide(9.0, 3) |
|
op:numeric-integer-divide(-3.5, 3) |
|
op:numeric-integer-divide(3.0, 4) |
|
op:numeric-integer-divide(3.1E1, 6) |
|
op:numeric-integer-divide(3.1E1, 7) |
|
Returns the remainder resulting from dividing $arg1, the dividend, by
$arg2, the divisor.
Defines the semantics of the mod operator when
applied to two numeric values.
General rules: see
The operation a mod b for operands that are xs:integer or
xs:decimal, or types derived from them, produces a result such that
(a idiv b) * b + (a mod b) is equal to a and the magnitude of
the result is always less than the magnitude of b. This identity holds even
in the special case that the dividend is the negative integer of largest possible
magnitude for its type and the divisor is -1 (the remainder is 0). It follows from this
rule that the sign of the result is the sign of the dividend.
For xs:float and xs:double operands the following rules
apply:
If either operand is NaN, the result is NaN.
If the dividend is positive or negative infinity, or the divisor is positive or
negative zero (0), or both, the result is NaN.
If the dividend is finite and the divisor is an infinity, the result equals the dividend.
If the dividend is positive or negative zero and the divisor is finite, the result is the same as the dividend.
In the remaining cases, where neither positive or negative infinity, nor positive
or negative zero, nor NaN is involved, the result obeys (a idiv
b)*b+(a mod b) = a.
Division is truncating division, analogous to integer division, not
A dynamic error is raised xs:integer
and xs:decimal operands, if $arg2 is zero.
| Expression | Result |
|---|---|
op:numeric-mod(10, 3) |
|
op:numeric-mod(6, -2) |
|
op:numeric-mod(4.5, 1.2) |
|
op:numeric-mod(1.23E2, 0.6E1) |
|
Returns its operand with the sign unchanged: (+ $arg).
Defines the semantics of the unary + operator
applied to a numeric value.
General rules: see
The returned value is equal to $arg, and is an instance of
xs:integer, xs:decimal, xs:double, or
xs:float depending on the type of $arg.
Because coercion rules are applied in the normal way, the unary
+ operator can be used to force conversion of an untyped node to a
number: the result of +@price is the same as xs:double(@price)
if the type of @price is xs:untypedAtomic.
Returns its operand with the sign reversed: -$arg.
Defines the semantics of the unary - operator when
applied to a numeric value.
General rules: see
The returned value is an instance of xs:integer, xs:decimal,
xs:double, or xs:float depending on the type of
$arg.
For xs:integer and xs:decimal arguments, 0 and
0.0 return 0 and 0.0, respectively. For
xs:float and xs:double arguments, NaN returns
NaN, 0.0E0 returns -0.0E0 and vice versa.
INF returns -INF. -INF returns
INF.
xs:double
and xs:decimal) now generally converts both values to xs:decimal.Numeric values can be compared using the function
This function underpins the six value comparison operators eq, ne, lt,
le, gt, and ge and the six general comparison
operators =, !=, <, <=,
>, and >=, which are all defined in terms of
the
For a description of the different ways of comparing numeric
values using the operators = and eq and functions
such as
The following functions are defined on numeric types. Each function returns a value of the same type as the type of its argument.
If the argument is the empty sequence, the empty sequence is returned.
For xs:float and xs:double arguments, if the
argument is NaN, NaN is returned.
With the exception of xs:float and xs:double that are positive or
negative infinity return positive or negative infinity.
| Function | Meaning |
|---|---|
fn:abs | Returns the absolute value of $value. |
fn:ceiling | Rounds $value upwards to a whole number. |
fn:divide-decimals | Divides one xs:decimal by another to a defined precision, returning
both the quotient and the remainder. |
fn:floor | Rounds $value downwards to a whole number. |
fn:is-NaN | Returns true if the argument is the xs:float or xs:double value NaN. |
fn:round | Rounds a value to a specified number of decimal places, with control over how the rounding takes place. |
fn:round-half-to-even | Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near. |
The
Returns the absolute value of $value.
This function is
General rules: see
If $value is negative the function returns -$value, otherwise it
returns $value.
For the four types xs:float,
xs:double, xs:decimal and xs:integer, it is
guaranteed that if the type of $value is an instance of type T then
the result will also be an instance of T. The result $value is an instance of xs:positiveInteger then the value of
$value
For xs:float and xs:double arguments, if the argument is
positive zero or negative zero, then positive zero is returned. If the argument is
positive or negative infinity, positive infinity is returned.
| Expression | Result |
|---|---|
abs(10.5) |
|
abs(-10.5) |
|
abs(-math:log(0)) |
|
Rounds $value upwards to a whole number.
This function is
General rules: see
The function returns the smallest (closest to negative infinity) number with no
fractional part that is not less than $value.
For the four types xs:float,
xs:double, xs:decimal and xs:integer, it is
guaranteed that if the type of $value is an instance of type T then
the result will also be an instance of T. The result $value is an instance of xs:decimal then the result xs:integer.
For xs:float and xs:double arguments, if the argument is
positive zero, then positive zero is returned. If the argument is negative zero, then
negative zero is returned. If the argument is less than zero and greater than -1,
negative zero is returned. If the argument is positive or negative infinity,
the value of the argument is returned.
| Expression | Result |
|---|---|
ceiling(10.5) |
|
ceiling(-10.5) |
|
ceiling(math:log(0)) |
|
Divides one xs:decimal by another to a defined precision, returning
both the quotient and the remainder.
This function is
The function returns a record with two fields:
quotient is the xs:decimal value
furthest from zero such that:
quotient is an exact multiple of ten to the power
of minus $precision;
the absolute value of quotient
multipled by $divisor is less than or equal to the absolute
value of $value;
the sign of quotient is the same as the sign
of op:numeric-divide($value, $divisor).
remainder is the exact result of subtracting quotient
multiplied by $divisor from $value.
There may be $precision is outside this range, it should
be adjusted to the nearest value supported by the implementation.
A dynamic error is raised $divisor is zero.
| Expression | Result |
|---|---|
divide-decimals(120.6, 60.3, 4) |
|
divide-decimals(10, 3) |
|
divide-decimals(10, -3) |
|
divide-decimals(-10, 3) |
|
divide-decimals(-10, -3) |
|
divide-decimals(10, 3, 6) |
|
divide-decimals(100, 30) |
|
divide-decimals(150_862, 7, -3) |
|
Rounds $value downwards to a whole number.
This function is
General rules: see
The function returns the largest (closest to positive infinity) number with no
fractional part that is not greater than $value.
For the four types xs:float,
xs:double, xs:decimal and xs:integer, it is
guaranteed that if the type of $value is an instance of type T then
the result will also be an instance of T. The result $value is an instance of xs:decimal then the result xs:integer.
For xs:float and xs:double arguments, if the argument is
positive zero, then positive zero is returned. If the argument is negative zero, then
negative zero is returned. If the argument is positive or negative infinity,
the value of the argument is returned.
| Expression | Result |
|---|---|
floor(10.5) |
|
floor(-10.5) |
|
math:log(0) => floor() |
|
Returns true if the argument is the xs:float or xs:double value NaN.
This function is
The function returns true if $value is the xs:float or xs:double value NaN;
otherwise it returns false.
| Expression | Result |
|---|---|
is-NaN(23) |
|
is-NaN("NaN") |
|
is-NaN(number("twenty-three")) |
|
is-NaN(math:sqrt(-1)) |
|
$precision
are implementation-defined.Rounds a value to a specified number of decimal places, with control over how the rounding takes place.
This function is
General rules: see
The function returns a value that is close to $value
and that is a multiple of ten to the power of minus
$precision. The default value of $precision
is zero, in which case the function returns a whole number (but not necessarily
an xs:integer).
The detailed way in which rounding is performed depends on the value of
$mode, as follows. Here L
means the highest multiple of ten to the power
of minus $precision that is less than or equal to $value,
U means the lowest multiple of ten to the power
of minus $precision that is greater than or equal to $value,
N means the multiple of ten to the power
of minus $precision that is numerically closest to $value,
and $value is equal to the arithmetic
mean of L and U.
| Rounding Mode | Meaning |
|---|---|
| Returns L. |
| Returns U. |
| Returns L if |
| Returns U if |
| Returns N, unless midway, in which case L. |
| Returns N, unless midway, in which case U. This is the default. |
| Returns N, unless midway, in which case it
returns L if |
| Returns N, unless midway, in which case it
returns U if |
| Returns N, unless midway, in which case it returns whichever of L and U has a last significant digit that is even. |
For the four types xs:float,
xs:double, xs:decimal and xs:integer, it is
guaranteed that if the type of $value is an instance of type T then
the result will also be an instance of T. The result $value is an instance of xs:decimal and $precision is
less than one, then the result xs:integer.
If the second argument is omitted or is the empty sequence,
the function produces the same result as when
$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.
There may be $precision is outside this range, it should
be adjusted to the nearest value supported by the implementation.
This function is typically used with a non-zero $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
counter-intuitive. 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.
The call round($v, 0, "floor") is equivalent to floor($v).
The call round($v, 0, "ceiling") is equivalent to ceiling($v).
The call round($v, $p, "half-to-even") is equivalent to round-half-to-even($v, $p).
| Expression | Result |
|---|---|
round(2.5) |
|
round(2.4999) |
|
round(-2.5) |
|
round(1.125, 2) |
|
round(8452, -2) |
|
round(3.1415e0, 2) |
|
math:log(0) => round() |
|
round(1.7, 0, "floor") |
|
round(-1.7, 0, "floor") |
|
round(1.7, 0, "ceiling") |
|
round(-1.7, 0, "ceiling") |
|
round(1.7, 0, "toward-zero") |
|
round(-1.7, 0, "toward-zero") |
|
round(1.7, 0, "away-from-zero") |
|
round(-1.7, 0, "away-from-zero") |
|
round(1.125, 2, "half-to-floor") |
|
round(-1.125, 2, "half-to-floor") |
|
round(1.125, 2, "half-to-ceiling") |
|
round(-1.125, 2, "half-to-ceiling") |
|
round(1.125, 2, "half-toward-zero") |
|
round(-1.125, 2, "half-toward-zero") |
|
round(1.125, 2, "half-away-from-zero") |
|
round(-1.125, 2, "half-away-from-zero") |
|
round(1.125, 2, "half-to-even") |
|
round(-1.125, 2, "half-to-even") |
|
$precision
are implementation-defined.Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near.
This function is
General rules: see
The function returns the nearest (that is, numerically closest) value to
$value that is a multiple of ten to the power of minus
$precision. If two such values are equally near (e.g. if the fractional
part in $value is exactly .500...), the function returns the one whose least
significant digit is even.
For the four types xs:float,
xs:double, xs:decimal and xs:integer, it is
guaranteed that if the type of $value is an instance of type T then
the result will also be an instance of T. The result $value is an instance of xs:decimal and $precision
is less than one, then the result xs:integer.
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.
There may be $precision is outside this range, it should
be adjusted to the nearest value supported by the implementation.
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 counter-intuitive. For example, consider
round-half-to-even(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.
From 4.0, the effect of this function can also be achieved by
calling "half-to-even".
| Expression | Result |
|---|---|
round-half-to-even(0.5) |
|
round-half-to-even(1.5) |
|
round-half-to-even(2.5) |
|
round-half-to-even(3.567812e+3, 2) |
|
round-half-to-even(4.7564e-3, 2) |
|
round-half-to-even(35612.25, -2) |
|
math:log(0) => round-half-to-even() |
|
It is possible to convert strings to values of type xs:integer,
xs:float, xs:decimal, or xs:double
using the constructor functions described in cast expressions as described in
In addition the xs:double. It differs from the xs:double
constructor function in that any value outside the lexical space of the xs:double
datatype is converted to the xs:double value NaN.
| Function | Meaning |
|---|---|
fn:number | Returns the value indicated by $value or, if $value is not
specified, the context value after atomization, converted to an xs:double.
|
fn:parse-integer | Converts a string to an integer, recognizing any radix in the range 2 to 36. |
Returns the value indicated by $value or, if $value is not
specified, the context value after atomization, converted to an xs:double.
The zero-argument form of this function is
The one-argument form of this function is
If $value is the empty sequence or if $value cannot be converted
to an xs:double, the xs:double value NaN is
returned.
Otherwise, $value is converted to an xs:double following the
rules of xs:double
fails, the xs:double value NaN is returned.
A type error is raised $value is omitted and the context value is
As a consequence of the rules given above, a type error is raised
The string +INF is permitted as a representation of positive infinity,
whether or not XSD 1.1 is supported. Similarly, -0 and 0
produce negative zero and positive zero respectively.
Generally NaN rather than raising a dynamic
error if the argument cannot be converted to xs:double. However, a type
error is raised in the usual way if the supplied argument cannot be atomized or if the
result of atomization does not match the required argument type.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
number(12) |
|
number('12') |
|
number('INF') |
|
number('NaN') |
|
number('non-numeric') |
|
number($e/@price) |
|
number($e/@discount) |
|
number($e/@misspelt) |
|
("10", "11", "12") ! number() |
|
Converts a string to an integer, recognizing any radix in the range 2 to 36.
This function is
If $value is the empty sequence, the result is the empty sequence.
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; upper-case alphabetics
A-Z may be used in place of their lower-case equivalents.
The value of a generalized digit corresponds to its position in this alphabet.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
A dynamic error is raised $radix is not in the range 2 to 36.
A dynamic error is raised $value is a zero-length string,
or if it contains a character
that is not among the first $radix characters in the
alphabet 0123456789abcdefghijklmnopqrstuvwxyz, or the
upper-case 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
If other characters may legitimately appear in the input, for example
a leading 0x, then this must first be removed by pre-processing the input.
If the input uses a different family of digits, then the value should first
be converted to the required digits using
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() => parse-integer(16)
can be used to convert the Base 64 value 1DE= to the integer 54321, via the
hexadecimal string D431.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
Alphabetic base-26 numbering systems (hexavigesimal) can be parsed via translation. Note, enumerating systems that do not assign a symbol to zero (e.g., spreadsheet columns) must be preprocessed in a different fashion. | |
| Expression: | |
| Result: | |
Digit-based numeration systems comparable to the Arabic numbers 0 through 9 can be parsed via translation. | |
| Expression: | |
| Result: | |
| Function | Meaning |
|---|---|
fn:format-integer | Formats an integer according to a given picture string, using the conventions of a given natural language if specified. |
Formats an integer according to a given picture string, using the conventions of a given natural language if specified.
The two-argument form of this function is
The three-argument form of this function is
If $value is the empty sequence, the function returns a zero-length
string.
In all other cases, the $picture argument describes the format in which
$value is output.
The rules that follow describe how non-negative 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 (0-9) without any leading zero;
A circumflex (^), which is present if the radix is present, and absent otherwise.
A circumflex is recognized as marking the presence of a radix only
if (a) it is immediately preceded by an integer
in the range 2 to 36, and (b) it is
followed (somewhere within the primary format token) by an "X"
or "x". In other cases, the circumflex is treated as a grouping separator.
For example, the picture 9^000 outputs the number
2345 as "2^345", whereas 9^XXX outputs "3185".
This rule is to ensure backwards compatibility.
A primary format token. This is always present and
An optional format modifier.
If the string contains one or more semicolons then the last semicolon is taken as terminating the primary format token, and everything that follows is taken as the format modifier; if the string contains no semicolon then the format modifier is taken to be absent (which is equivalent to supplying a zero-length string).
If a radix is present, then the primary format token must follow the rules for a digit-pattern.
The primary format token is classified as one of the following:
A digit-pattern made up of optional-digit-signs, mandatory-digit-signs, and grouping-separator-signs.
The optional-digit-sign is the character #.
0 through 9.
Within the format token, these digits are
interchangeable: a three-digit 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 mandatory-digit-sign is upper-case "X", then all
mandatory-digit-signs must be upper-case "X". The digit family
used in the output comprises the first R characters of the
alphabet 0123456789abcdefghijklmnopqrstuvwxyz, but using upper-case
letters in place of lower-case if an upper-case "X" is used
as the mandatory-digit-sign.
In this case the primary format token ^(([Xx#]|[^\p{N}\p{L}])+?)$
a grouping-separator-sign is a non-alphanumeric 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 mandatory-digit-signs 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 ١ 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 grouping-separator-signs 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 grouping-separator-sign 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 optional-digit-signs and mandatory-digit-signs 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 the 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 mandatory-digit-signs in the primary format token.
Let S/3 be the result of replacing all decimal digits (0-9) 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 right-hand 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 lower-case
words, for example in English, one two three four ...
The format token W, which generates numbers written as upper-case
words, for example in English, ONE TWO THREE FOUR ...
The format token Ww, which generates numbers written as title-case
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
For all format tokens other than a digit-pattern, there
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 language-sensitive. 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 $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 the 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 digit-pattern is used:
If grouping-separator-signs
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 optional-digit-signs is to mark the position of
grouping-separator-signs. 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
mandatory-digit-signs in the format token requires insignificant
leading zeros to be present.
Grouping separators are (365)123-9876. 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 digit-pattern
01, the number three hundred will be output as 300,
despite the absence of any optional-digit-sign.
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
open-source ICU localization library o(%spellout-ordinal-masculine), or c(%spellout-cardinal-year).
The following notes apply when the primary format token is neither a digit-pattern 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
format-integer(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 format-integer(19, "α;a") might expect the nineteenth Greek
letter, format-integer(18, "Α;a") might expect the eighteenth Greek capital letter,
| Expression | Result |
|---|---|
format-integer(123, '0000') |
|
format-integer(123, 'w') | Depending on the default language, the expression might return
the string |
format-integer(21, '1;o', 'en') |
|
format-integer(14, 'Ww;o(-e)', 'de') | If supported, might return the string |
(1 to 10) ! format-integer(., "1;o(-º)", language:="it") | This requests ordinal numbering in Italian: if supported,
this should produce the sequence: |
(1 to 10) ! format-integer(., "Ww;o", language:="it") | This requests ordinal numbering in Italian, spelled out
as words: if supported,
this should produce the sequence: |
format-integer(7, 'a') |
|
format-integer(27, 'a') |
|
format-integer(57, 'I') |
|
format-integer(1234, '#;##0;') |
|
format-integer(1234, '16^xxxx') |
|
format-integer(1234, '16^X') |
|
format-integer(12345678, '16^xxxx_xxxx') |
|
format-integer(12345678, '16^#_xxxx') |
|
format-integer(255, '2^xxxx xxxx') |
|
format-integer(1023, '32^XXXX') |
|
format-integer(1023, '10^XXXX') |
|
format-integer(1023, '10^00') |
|
format-integer(-5, '001') |
|
format-integer(-5, 'a') |
|
format-integer(-12, '16^XX') |
|
This section defines a function for formatting decimal and floating point numbers.
| Function | Meaning |
|---|---|
fn:format-number | Returns a string containing a number formatted according to a given picture string and decimal format. |
This function can be used to format any numeric quantity, including an integer. For integers, however,
the
Decimal formats are defined in the static context, and the way they are defined is therefore outside the scope of this specification. XSLT and XQuery both provide custom syntax for creating a decimal format.
The static context provides a set of decimal formats. One of the decimal formats is unnamed, the others (if any)
are identified by a QName. There is always an unnamed decimal format available, but its contents are
Each decimal format provides a set of named properties.
A phrase such as "The
For any decimal format, the properties
representing characters used in a
xs:QName,
as an alternative to supplying a lexical QName as an instance of xs:string.percent and exponent-separator,
it is now possible to specify a single-character marker to be used in the picture string,
together with a multi-character rendition to be used in the formatted output.Returns a string containing a number formatted according to a given picture string and decimal format.
The two-argument form of this function is
The three-argument form of this function is
The function formats $value as a string using the $picture argument and a decimal format.
The $value argument may be of any numeric data type
(xs:double, xs:float, xs:decimal, or their
subtypes including xs:integer). Note that if an xs:decimal is
supplied, it is not automatically converted to an xs:double, as such
conversion can involve a loss of precision.
If the supplied value of the $value argument is the empty sequence, the
function behaves as if the supplied value were the xs:double value
NaN.
If $options is the empty map, then the number is
formatted using the properties of the unnamed decimal format in the static context.
For backwards compatibility reasons, the decimal format can be supplied as
an instance of xs:string. If the value of the $options
argument is an xs:string, then its value
EQName
as defined in the XPath 4.0 grammar, that is one of the following:
A lexical QName, which is expanded using the statically known namespaces. The default namespace is not used (no prefix means no namespace).
A URIQualifiedName using the syntax Q{uri}local,
where the URI can be zero-length to indicate a name in no namespace.
The effective value of the $options argument is then the map
{ 'format-name': $FN } where $FN is the
xs:QName result of expanding this EQName.
The entries that may appear in the $options map are as follows.
The
In the table, the type xs:string (: matching '.' :)
represents a single-character string, that is, a restriction of xs:string
with the facet pattern=".", while the type
xs:string (: matching '.|.:.*' :) indicates a string
that is either a single character, or a single character followed by
The default value for absent options (other than
format-name) is taken from a decimal format in the static context; the default
values shown in the table are the values used if no specific value is assigned in the
static context.
| Key | Meaning |
|---|---|
|
The name of a decimal format in the static context; if absent, the unnamed
decimal format in the static context is used. An xs:NCName
represents the local part of an xs:QName in no namespace.
|
| The
|
| The
|
| The
|
| The string used to represent the value positive or negative infinity
in the formatted number.
|
| The string used as a minus sign in the formatted number if
there is no subpicture for formatting negative numbers.
|
| The string used to represent the value NaN
in the formatted number.
|
| The
|
|
|
| Defines the characters used in the picture string to represent a mandatory digit:
for example, if the zero-digit is 0 then any of the
digits 0 to 9 may be used (interchangeably)
in the picture string to represent a mandatory digit,
and in the formatted number the characters 0 to 9
will be used to represent the digits zero to nine. The value must be
a character in Unicode category Nd with decimal digit value 0 (zero).
|
| The character used in the picture string to represent
an optional digit.
|
| The character used in the picture string to separate the positive
and negative subpictures.
|
A base decimal format is established as follows:
If the format-name option is present, then
the decimal format in the static context identified by this name.
Otherwise, the unnamed decimal format in the static context.
The base decimal format is then modified using the other entries in the
supplied $options map.
The evaluation of the
The analysis phase takes as its inputs the
The result of the function is the formatted string representation of the supplied number.
A dynamic error is raised $options argument is supplied as an xs:string
that isURIQualifiedName, or if it uses a prefix that is not found in the
statically known namespaces; or if the static context does not contain a declaration of
a decimal format with a matching expanded QName; or if $options?format-name
is present and the static context does
not contain a declaration of a decimal format whose name matches $options?format-name.
If the processor is able to detect the
error statically (for example, when the argument is supplied as a string literal), then
the processor
A dynamic error is raised $format is not valid for the associated property, or if the properties
of the decimal format resulting from a supplied $options
map do not have distinct values.
A string is an ordered sequence of characters, and this specification uses terms such as “left” and “right”, “preceding” and “following” in relation to this ordering, irrespective of the position of the characters when visually rendered on some output medium. Both in the picture string and in the result string, digits with higher significance (that is, representing higher powers of ten) always precede digits with lower significance, even when the rendered text flow is from right to left.
In previous versions of XSLT and XQuery, decimal formats were typically defined in the
static context using custom declarations (<xsl:decimal-format> in XSLT,
declare decimal-format in XQuery) and then selected by name in a call on
$options argument of the
Alternative ways to format an xs:double as a string include:
Direct casting to string, for example using the constructor function xs:string($number)
JSON serialization, for example fn:serialize($number, {'method':'json', 'canonical':true()})
In general these will produce different results, for example in the amount of precision that is retained, and in the use of exponential (scientific) notation.
The following examples assume a default decimal format in which the chosen digits are
the ASCII digits 0-9, the decimal separator is | |
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
The following examples assume the existence of a decimal format named
| |
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
The following examples assume that the exponent separator
in decimal format | |
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
This differs from the format-number function previously defined in XSLT 2.0 in that
any digit can be used in the picture string to represent a mandatory digit: for example the picture
strings "000", "001", and "999" are equivalent.
The digits will all be from the same decimal digit family,
specifically, the sequence of ten consecutive digits starting with the digit assigned to the zero-digit property.
This change is to align format-number
(which previously used "000") with format-dateTime (which used 001).
A dynamic error is raised
A picture-string consists either of a sub-picture, or of
two sub-pictures separated by the
A sub-picture
A sub-picture
The mantissa part of a
sub-picture (defined below)
A sub-picture
A sub-picture
A sub-picture
The integer part of a sub-picture (defined below)
A character that matches the
A sub-picture that contains a
If a sub-picture contains a character treated as an
exponent-separator-sign then this
The mantissa part of the sub-picture is defined as the part that appears to the left of the exponent-separator-sign if there is one, or the entire sub-picture otherwise. The exponent part of the subpicture is defined as the part that appears to the right of the exponent-separator-sign; if there is no exponent-separator-sign then the exponent part is absent.
The integer part of the sub-picture is defined as the part that
appears to the left of the
The fractional part of the sub-picture is defined as that
part of the mantissa part that
appears to the right of the
This phase of the algorithm analyzes
the
Several variables are associated with each sub-picture. If there are two sub-pictures, then these rules are applied to one sub-picture to obtain the values that apply to positive and unsigned zero numbers, and to the other to obtain the values that apply to negative numbers. If there is only one sub-picture, then the values for both cases are derived from this sub-picture.
The variables are as follows:
The integer-part-grouping-positions is a sequence of integers
representing the positions of grouping separators within the integer part of the
sub-picture. For each
The grouping is defined to be
There is an least one grouping-separator in the integer part of the sub-picture.
There is a positive integer G (the grouping size) such that the position of every grouping-separator in the integer part of the sub-picture is a positive integer multiple of G.
Every position in the integer part of the sub-picture that is a positive integer multiple of G is occupied by a grouping-separator.
If the grouping is regular, then the integer-part-grouping-positions sequence contains all integer multiples of G as far as necessary to accommodate the largest possible number.
The minimum-integer-part-size is an integer indicating the minimum number of digits that will
appear to the left of the decimal-separator character. It is initially set to
the number of
There is no maximum integer part size. All significant digits in the integer part of the
number will be displayed, even if this exceeds the number of
The scaling factor is a non-negative integer used to determine the scaling of the mantissa
in exponential notation. It is set to the number of
The prefix is set to contain all passive characters
in the sub-picture to the left of the leftmost active character.
If the picture string contains only one sub-picture,
the prefix
for the negative sub-picture is set by concatenating the
The fractional-part-grouping-positions is a sequence of integers
representing the positions of grouping separators within the fractional part of the
sub-picture. For each
There is no need to extrapolate grouping positions on the fractional side,
because the number of digits in the output will never exceed the number of
The minimum-fractional-part-size is set to the number of
The maximum-fractional-part-size is set to the total number of
If the effect of the above rules is that minimum-integer-part-size and maximum-fractional-part-size are both zero, then an adjustment is applied as follows:
If an exponent separator is present then:
minimum-fractional-part-size is changed to 1 (one).
maximum-fractional-part-size is changed to 1 (one).
This has the effect that with the picture #.e9, the value 0.123 is formatted as 0.1e0
Otherwise:
minimum-integer-part-size is changed to 1 (one).
This has the effect that with the picture #, the value 0.23 is formatted
as 0
If all the following conditions are true:
An exponent separator is present
The minimum-integer-part-size is zero
There is at least one
then the minimum-integer-part-size is changed to 1 (one).
This has the effect that with the picture .9e9, the value 0.1 is formatted
as .1e0, while with the picture #.9e9, it is formatted as 0.1e0
If (after making the above adjustments) the minimum-integer-part-size and the minimum-fractional-part-size are both zero, then the minimum-fractional-part-size is set to 1 (one).
The minimum-exponent-size is set to the number of
The rules for the syntax of the picture string ensure that if an exponent separator is present, then the minimum-exponent-size will always be greater than zero.
The suffix is set to contain all passive characters to the right of the rightmost active character in the sub-picture.
If there is only one sub-picture, then all variables
for positive numbers and negative numbers will be the same, except for
prefix: the prefix for negative numbers will
be preceded by the
This section describes the second phase of processing of the
The algorithm for this second stage of processing is as follows:
If the input number is NaN (not a number), the result is the
value of the
In the rules below, the positive sub-picture and its associated variables are used
if the input number is positive, and the negative sub-picture and its associated
variables are used if it is negative. For xs:double and xs:float,
negative zero is taken as negative, positive zero as positive. For xs:decimal
and xs:integer, the positive sub-picture is used for zero.
The adjusted number is determined as follows:
If the sub-picture contains a
If the sub-picture contains a
Otherwise, the adjusted number is the input number.
If the multiplication causes numeric overflow, no error occurs, and the adjusted number is positive or negative infinity as appropriate.
If the adjusted number is positive or negative infinity, the result is the
concatenation of the appropriate prefix, the value of the
If the minimum exponent size is non-zero,
The primitive type of M is the same as the primitive type of the adjusted number (integer, decimal, float, or double).
The value of M multiplied by ten to the power of E is equal to the adjusted number.
The value of M (unless it is zero) is less than 10N, and at least 10N-1, where N is the scaling factor.
If the minimum exponent size is zero, then M is the adjusted number and there is no exponent.
If the minimum exponent size is non-zero and the adjusted number is zero, then M is the adjusted number and E is zero.
The mantissa M is converted (if necessary) to
an xs:decimal value M/D,
using an implementation of xs:decimal that imposes no limits on the
totalDigits or fractionDigits facets.
The value of M/D is chosen such that:
If the type of M is xs:decimal (including xs:integer),
then M/D is M.
Otherwise:
The result of converting M/D to the primitive type of M
is equal to M under the rules of the
Of all the possible values of M/D, the value that is
chosen
For example, 1.0 is preferred to 0.9999999999, and 100000000 is preferred to 100000001.
This value is then
rounded so that it uses no more than maximum-fractional-part-size digits in
its fractional part. The rounded number is defined to be the result of
calling the function maximum-fractional-part-size as the second
argument, again with no limits on the totalDigits or fractionDigits in the
result.
The absolute value of the rounded number is converted to a string in decimal notation,
using the digits in the
If the number of digits to the left of the
If the number of digits to the right of the
For each integer N in the integer-part-grouping-positions list,
a
For each integer N in the fractional-part-grouping-positions list,
a
If there is no
If an exponent exists, then the string
produced from the mantissa as described above is extended with
the following, in order:
(a) the
The result of the function is the concatenation of the appropriate prefix, the string conversion of the number as obtained above, and the appropriate suffix.
The functions in this section perform trigonometric and other mathematical calculations on xs:double values. They
are provided primarily for use in applications performing geometrical computation, for example when generating
SVG graphics.
Functions are provided to support the six most commonly used trigonometric calculations: sine, cosine, and tangent, and their inverses arc sine, arc cosine, and arc tangent. Other functions such as secant, cosecant, and cotangent are not provided because they are easily computed in terms of these six.
The functions in this section (with the exception of math:pi)
are specified by reference to xs:double values. The IEEE specification
applies with the following caveats:
IEEE states that the preferred quantum is language-defined. In this
specification, it is
IEEE states that certain functions should raise the inexact exception if the result is inexact. In this specification, this exception if it occurs does not result in an error. Any diagnostic information is outside the scope of this specification.
IEEE defines various rounding algorithms for inexact results, and states
that the choice of rounding direction, and the mechanisms for influencing this choice,
are language-defined. In this specification, the rounding direction and any mechanisms for
influencing it are
Certain operations (such as taking the square root of a negative number)
are defined in IEEE to signal the invalid operation exception and return a
quiet NaN. In this specification, such operations return NaN
and do not raise an error. The same policy applies to operations (such as taking
the logarithm of zero) that raise a divide-by-zero exception. Any diagnostic
information is outside the scope of this specification.
Operations whose mathematical result is greater than the largest finite xs:double
value are defined in IEEE to signal the overflow exception; operations whose mathematical
result is closer to zero than the smallest non-zero xs:double value are similarly
defined in IEEE to signal the underflow exception. The treatment of these exceptions in
this specification is defined in
| Function | Meaning |
|---|---|
math:pi | Returns an approximation to the mathematical constant π. |
math:e | Returns an approximation to the mathematical constant e. |
math:acos | Returns the arc cosine of the argument. |
math:asin | Returns the arc sine of the argument. |
math:atan | Returns the arc tangent of the argument. |
math:atan2 | Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive x-axis. |
math:cos | Returns the cosine of the argument. The argument is an angle in radians. |
math:cosh | Returns the hyperbolic cosine of the argument. |
math:exp | Returns the value of ex where x is the argument value. |
math:exp10 | Returns the value of 10x, where x is the supplied argument value. |
math:log | Returns the natural logarithm of the argument. |
math:log10 | Returns the base-ten logarithm of the argument. |
math:pow | Returns the result of raising the first argument to the power of the second. |
math:sin | Returns the sine of the argument. The argument is an angle in radians. |
math:sinh | Returns the hyperbolic sine of the argument. |
math:sqrt | Returns the non-negative square root of the argument. |
math:tan | Returns the tangent of the argument. The argument is an angle in radians. |
math:tanh | Returns the hyperbolic tangent of the argument. |
Returns an approximation to the mathematical constant π.
This function is
This function returns the xs:double value whose lexical representation is
3.141592653589793e0
| Expression | Result |
|---|---|
2 * math:pi() |
|
60 * (math:pi() div 180) | Converts an angle of 60 degrees to radians. |
Returns an approximation to the mathematical constant e.
This function is
This function returns the xs:double value whose lexical representation is
2.718281828459045e0
| Expression | Result |
|---|---|
math:pow(math:e(), 0.05 * 3) |
(approximately) |
Returns the arc cosine of the argument.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise the result is the arc cosine of $value, as defined in the acos function applied to 64-bit 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 <= θ <=
math:pi().
| Expression | Result |
|---|---|
math:acos(()) |
|
math:acos(0) |
(approximately) |
math:acos(-0.0e0) |
(approximately) |
math:acos(1.0e0) |
|
math:acos(-1.0e0) |
(approximately) |
math:acos(2.0e0) |
|
math:acos(xs:double('NaN')) |
|
math:acos(xs:double('INF')) |
|
math:acos(xs:double('-INF')) |
|
Returns the arc sine of the argument.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise the result is the arc sine of $value as defined in the asin function applied to 64-bit 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 -math:pi() div 2 <=
θ <= math:pi() div 2.
| Expression | Result |
|---|---|
math:asin(()) |
|
math:asin(0) |
|
math:asin(-0.0e0) |
|
math:asin(1.0e0) |
(approximately) |
math:asin(-1.0e0) |
(approximately) |
math:asin(2.0e0) |
|
math:asin(xs:double('NaN')) |
|
math:asin(xs:double('INF')) |
|
math:asin(xs:double('-INF')) |
|
Returns the arc tangent of the argument.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise the result is the arc tangent of $value, as defined
in the atan function applied to 64-bit 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 -math:pi() div 2 <=
θ <= math:pi() div 2.
| Expression | Result |
|---|---|
math:atan(()) |
|
math:atan(0) |
|
math:atan(-0.0e0) |
|
math:atan(1.0e0) |
(approximately) |
math:atan(-1.0e0) |
(approximately) |
math:atan(xs:double('NaN')) |
|
math:atan(xs:double('INF')) |
(approximately) |
math:atan(xs:double('-INF')) |
(approximately) |
Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive x-axis.
This function is
The result is the value of atan2(y, x) as defined in the atan2 function applied to
64-bit binary floating point values. The result is in the range -π
to +π radians.
The treatment of the underflow exception is defined in
If either argument is NaN then the result is NaN.
If $x is positive, then the value of
atan2($y, $x) is atan($y div $x).
If $x is negative, then:
If $y is positive, then the value of atan2($y, $x) is
atan($y div $x) + π.
If $y is negative, then the value of atan2($y, $x) is
atan($y div $x) - π.
Some results for special values of the arguments are shown in the examples below.
| Expression | Result |
|---|---|
math:atan2(+0.0e0, 0.0e0) |
|
math:atan2(-0.0e0, 0.0e0) |
|
math:atan2(+0.0e0, -0.0e0) |
|
math:atan2(-0.0e0, -0.0e0) |
|
math:atan2(-1, 0.0e0) |
|
math:atan2(+1, 0.0e0) |
|
math:atan2(-0.0e0, -1) |
|
math:atan2(+0.0e0, -1) |
|
math:atan2(-0.0e0, +1) |
|
math:atan2(+0.0e0, +1) |
|
Returns the cosine of the argument. The argument is an angle in radians.
This function is
If $radians is the empty sequence, the function returns the empty
sequence.
If $radians is positive or negative infinity, or NaN,
then the result is NaN.
Otherwise the result is the cosine of $radians (which is treated as an angle in
radians) as defined in the cos function applied to 64-bit 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 $radiansis positive or negative infinity, or NaN,
then the result is NaN.
Otherwise the result is always in the range -1.0e0 to +1.0e0
| Expression | Result |
|---|---|
math:cos(()) |
|
math:cos(0) |
|
math:cos(-0.0e0) |
|
math:cos(math:pi() div 2) |
(approximately) |
math:cos(-math:pi() div 2) |
(approximately) |
math:cos(math:pi()) |
(approximately) |
math:cos(xs:double('NaN')) |
|
math:cos(xs:double('INF')) |
|
math:cos(xs:double('-INF')) |
|
Returns the hyperbolic cosine of the argument.
This function is
If $value is the empty sequence, the function returns the empty
sequence.
Otherwise the result is the hyperbolic cosine of $value as defined in the
cosh function applied
to 64-bit binary floating point values.
The treatment of the overflow exception
is defined in
If $value is positive or negative zero, the result is
1.
If $value is positive or negative infinity,
the result is INF.
If $value is NaN,
the result is NaN.
In other cases, the result is an xs:double in the range
+1.0 to INF.
| Expression | Result |
|---|---|
math:cosh(0) |
|
math:cosh(math:pi()) |
(approximately) |
Returns the value of ex where x is the argument value.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise the result is the mathematical constant e raised to the power of
$value, as defined in the exp function applied to 64-bit binary floating point values.
The treatment of overflow and underflow is defined in
| Expression | Result |
|---|---|
math:exp(()) |
|
math:exp(0) |
|
math:exp(1) |
(approximately) |
math:exp(2) |
|
math:exp(-1) |
|
math:exp(math:pi()) |
|
math:exp(xs:double('NaN')) |
|
math:exp(xs:double('INF')) |
|
math:exp(xs:double('-INF')) |
|
Returns the value of 10x, where x is the supplied argument value.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise the result is ten raised to the power of $value, as defined in the
exp10 function applied
to 64-bit binary floating point values.
The treatment of overflow and underflow is defined in
| Expression | Result |
|---|---|
math:exp10(()) |
|
math:exp10(0) |
|
math:exp10(1) |
|
math:exp10(0.5) |
|
math:exp10(-1) |
|
math:exp10(xs:double('NaN')) |
|
math:exp10(xs:double('INF')) |
|
math:exp10(xs:double('-INF')) |
|
Returns the natural logarithm of the argument.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise the result is the natural logarithm of $value, as defined in the
log function applied
to 64-bit binary floating point values.
The treatment of divideByZero and invalidOperation exceptions
is defined in -INF, and if it is negative, the result is NaN
| Expression | Result |
|---|---|
math:log(()) |
|
math:log(0) |
|
math:log(math:exp(1)) |
|
math:log(1.0e-3) |
|
math:log(2) |
|
math:log(-1) |
|
math:log(xs:double('NaN')) |
|
math:log(xs:double('INF')) |
|
math:log(xs:double('-INF')) |
|
Returns the base-ten logarithm of the argument.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise the result is the base-10 logarithm of $value, as defined in the
log10 function applied
to 64-bit binary floating point values.
The treatment of divideByZero and invalidOperation exceptions
is defined in -INF, and if it is negative, the result is NaN
| Expression | Result |
|---|---|
math:log10(()) |
|
math:log10(0) |
|
math:log10(1.0e3) |
|
math:log10(1.0e-3) |
|
math:log10(2) |
|
math:log10(-1) |
|
math:log10(xs:double('NaN')) |
|
math:log10(xs:double('INF')) |
|
math:log10(xs:double('-INF')) |
|
Returns the result of raising the first argument to the power of the second.
This function is
If $x is the empty sequence, the function returns the empty sequence.
If $y is an instance of xs:integer, the result is
$x raised to the power of $y as defined in the pown function applied to a
64-bit binary floating point value and an integer.
Otherwise $y is cast to an xs:double,
and the result is $x raised to the power of
$y as defined in the pow function applied to two 64-bit binary floating point values.
The treatment of the divideByZero and invalidOperation
exceptions is defined in
| Expression | Result |
|---|---|
math:pow((), 93.7) |
|
math:pow(2, 3) |
|
math:pow(-2, 3) |
|
math:pow(2, -3) |
|
math:pow(-2, -3) |
|
math:pow(2, 0) |
|
math:pow(0, 0) |
|
math:pow(xs:double('INF'), 0) |
|
math:pow(xs:double('NaN'), 0) |
|
math:pow(-math:pi(), 0) |
|
math:pow(0e0, 3) |
|
math:pow(0e0, 4) |
|
math:pow(-0e0, 3) |
|
math:pow(0, 4) |
|
math:pow(0e0, -3) |
|
math:pow(0e0, -4) |
|
math:pow(-0e0, -3) |
|
math:pow(0, -4) |
|
math:pow(16, 0.5e0) |
|
math:pow(16, 0.25e0) |
|
math:pow(0e0, -3.0e0) |
|
math:pow(-0e0, -3.0e0) |
|
math:pow(0e0, -3.1e0) |
|
math:pow(-0e0, -3.1e0) |
|
math:pow(0e0, 3.0e0) |
|
math:pow(-0e0, 3.0e0) |
|
math:pow(0e0, 3.1e0) |
|
math:pow(-0e0, 3.1e0) |
|
math:pow(-1, xs:double('INF')) |
|
math:pow(-1, xs:double('-INF')) |
|
math:pow(1, xs:double('INF')) |
|
math:pow(1, xs:double('-INF')) |
|
math:pow(1, xs:double('NaN')) |
|
math:pow(-2.5e0, 2.0e0) |
|
math:pow(-2.5e0, 2.00000001e0) |
|
Returns the sine of the argument. The argument is an angle in radians.
This function is
If $radians is the empty sequence, the function returns the empty
sequence.
Otherwise the result is the sine of $radians (which is treated as an angle in
radians) as defined in the sin function applied to 64-bit binary floating point values.
The treatment of the invalidOperation and underflow exceptions
is defined in
If $radians is positive or negative zero, the result is
$radians.
If $radians is positive or negative infinity, or NaN,
then the result is NaN.
Otherwise the result is always in the range -1.0e0 to +1.0e0
| Expression | Result |
|---|---|
math:sin(()) |
|
math:sin(0) |
|
math:sin(-0.0e0) |
|
math:sin(math:pi() div 2) |
(approximately) |
math:sin(-math:pi() div 2) |
(approximately) |
math:sin(math:pi()) |
(approximately) |
math:sin(xs:double('NaN')) |
|
math:sin(xs:double('INF')) |
|
math:sin(xs:double('-INF')) |
|
Returns the hyperbolic sine of the argument.
This function is
If $value is the empty sequence, the function returns the empty
sequence.
Otherwise the result is the hyperbolic sine of $value as defined in the
sinh function applied
to 64-bit binary floating point values.
The treatment of the overflow and underflow exceptions
is defined in
If $value is positive or negative zero, the result is
$value.
If $value is positive or negative infinity, or NaN,
the result is NaN.
| Expression | Result |
|---|---|
math:sinh(1) |
(approximately) |
math:sinh(math:pi()) |
(approximately) |
Returns the non-negative square root of the argument.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise the result is the mathematical non-negative square root of $value
as defined in the squareRoot function applied to 64-bit binary floating point values.
The treatment of the invalidOperation exception is defined in NaN.
If $value is positive or negative zero, positive infinity, or
NaN, then the result is $value. (Negative zero is the only
case where the result can have negative sign)
| Expression | Result |
|---|---|
math:sqrt(()) |
|
math:sqrt(0.0e0) |
|
math:sqrt(-0.0e0) |
|
math:sqrt(1.0e6) |
|
math:sqrt(2.0e0) |
|
math:sqrt(-2.0e0) |
|
math:sqrt(xs:double('NaN')) |
|
math:sqrt(xs:double('INF')) |
|
math:sqrt(xs:double('-INF')) |
|
Returns the tangent of the argument. The argument is an angle in radians.
This function is
If $radians is the empty sequence, the function returns the empty
sequence.
Otherwise the result is the tangent of $radians (which is treated as an angle
in radians) as defined in the tan function applied to 64-bit binary floating point values.
The treatment of the invalidOperation and underflow exceptions
is defined in
If $radians is positive or negative infinity, or NaN,
then the result is NaN.
| Expression | Result |
|---|---|
math:tan(()) |
|
math:tan(0) |
|
math:tan(-0.0e0) |
|
math:tan(math:pi() div 4) |
(approximately) |
math:tan(-math:pi() div 4) |
(approximately) |
1 div math:tan(math:pi() div 2) |
(approximately)
|
1 div math:tan(-math:pi() div 2) |
(approximately)
|
math:tan(math:pi()) |
(approximately) |
math:tan(xs:double('NaN')) |
|
math:tan(xs:double('INF')) |
|
math:tan(xs:double('-INF')) |
|
Returns the hyperbolic tangent of the argument.
This function is
If $value is the empty sequence, the function returns the empty
sequence.
Otherwise the result is the hyperbolic tangent of $value as defined in the
tanh function applied
to 64-bit binary floating point values.
The treatment of the underflow exception
is defined in
If $value is positive or negative zero, the result is
$value.
If $value is positive infinity, the result is +1.0.
If $value is negative infinity, the result is -1.0.
In other cases, the result is an xs:double in the range
-1.0 to +1.0.
| Expression | Result |
|---|---|
math:tanh(1) |
(approximately) |
math:tanh(math:pi()) |
(approximately) |
| Function | Meaning |
|---|---|
fn:random-number-generator | Returns a random number generator, which can be used to generate sequences of random numbers. |
The function makes use of the record structure defined in the next section.
This record type is used to represent the result of a call on
the
| Name | Meaning |
|---|---|
| An
|
|
A zero-arity function that can be called to return another random number generator. The properties of this function are as follows: name: absent parameter names: () signature: non-local variable bindings: none implementation: implementation-dependent
|
|
A function with arity 1 (one), which takes an arbitrary sequence as its argument, and returns a random permutation of that sequence. The properties of this function are as follows: name: absent parameter names: signature: non-local variable bindings: none body: implementation-dependent
|
xs:double values between 0.01 and 0.1 as there are between
0.1 and 1.0).Returns a random number generator, which can be used to generate sequences of random numbers.
This function is
The function returns a random number generator. A random number generator is represented as a value of type
random-number-generator-record, defined in
Calling the $seed is equivalent to calling the single-argument
form of the function with an implementation-dependent seed.
If a $seed is supplied, it may be an atomic item of any type.
Both forms of the function are
The value of the number entry xs:double
values are equally likely to be chosen
The function returned in the permute entry
The map returned by the
It is not meaningful to ask whether the functions returned in the next and permute
functions resulting from two separate calls with the same seed are “the same function”, but the functions must be equivalent in the sense
that calling them produces the same sequence of random numbers.
The repeatability of the results of function calls in different execution scopes is outside the scope of this
specification. It is fn:current-dateTime() as a seed.)
The specification does not place strong conformance requirements on the actual randomness of the result; this is left to the implementation. It is desirable, for example, when generating a sequence of random numbers that the sequence should not get into a repeating loop; but the specification does not attempt to dictate this.
| Expression: |
|
|---|---|
| Result: | A random permutation of the integers in the range
|
| Expression: |
|
| Result: | A 10% sample of the items in an input sequence |
The following XQuery code produces a random sequence of 200 | |
An equivalent result can be achieved with | |
This section specifies functions and operators on the xs:string datatype and the datatypes derived from it.
The operators described in this section are defined on the following types.
They also apply to user-defined types derived by restriction from the above types.
| Function | Meaning |
|---|---|
fn:codepoints-to-string | Returns an xs:string whose characters have supplied |
fn:string-to-codepoints | Returns the sequence of xs:string value. |
Returns an xs:string whose characters have supplied
This function is
The function returns the string made up from the $values. This will be the zero-length string if $values
is the empty sequence.
A dynamic error is raised $values is not a
| Expression | Result |
|---|---|
codepoints-to-string((66, 65, 67, 72)) |
|
codepoints-to-string((2309, 2358, 2378, 2325)) |
|
codepoints-to-string(()) |
|
codepoints-to-string(0) | Raises error FOCH0001. |
Returns the sequence of xs:string value.
This function is
The function returns a sequence of integers, each integer being the Unicode $value.
If $value is a zero-length string or the empty sequence, the function returns
the empty sequence.
| Expression | Result |
|---|---|
string-to-codepoints("Thérèse") |
|
| Function | Meaning |
|---|---|
fn:codepoint-equal | Returns true if two strings are equal, considered codepoint-by-codepoint. |
fn:collation | Constructs a collation URI with requested properties. |
fn:collation-available | Asks whether a collation URI is recognized by the implementation. |
fn:collation-key | Given a string value and a collation, generates an internal value called a collation key, with the property that the matching and ordering of collation keys reflects the matching and ordering of strings under the specified collation. |
fn:contains-token | Determines whether or not any of the supplied strings, when tokenized at whitespace boundaries, contains the supplied token, under the rules of the supplied collation. |
The
Collations can indicate that two different codepoints are to be considered equal for comparison purposes (for example, “v” and “w” are considered equivalent in some Swedish collations). Strings can be compared codepoint-by-codepoint or in a linguistically appropriate manner.
Some sources, for example
This specification defines some collation URIs that provide interoperable sorting behavior across applications. Other collation URIs are defined only partially (leaving some aspects implementation-defined). Implementations may define further collation URIs, or may allow users or third parties to define them.
The
Collations may or may not perform Unicode normalization on strings before comparing them.
This specification allows a collation
name to be provided as an argument to many string functions. Although
collations are defined to be URIs, they are supplied as instances of
xs:string.
The XQuery/XPath static context supplies a default collation
for use when the collation argument is not specified.
(see
If the collation is specified using a relative URI reference,
it is resolved relative to an
Previous versions of this specification stated that it must
be resolved against the
This specification does not define whether or not the collation URI is
dereferenced. The collation URI may be an abstract identifier, or it may
refer to an actual resource describing the collation. If it refers to a
resource, this specification does not define the nature of that resource.
One possible candidate is that the resource is a locale description
expressed using the Locale Data Markup Language: see
The ability to access external resources depends on whether the
calling code is
XML allows elements to specify the xml:lang attribute to
indicate the language associated with the content of such an element.
This specification does not use xml:lang to identify the
default collation because using
xml:lang does not produce desired effects when the two
strings to be compared have different xml:lang values or
when a string is multilingual.
All collations support the ability to compare two strings to decide whether they are equal, and if not, which one should sort first. This must always define a total ordering, which implies that the comparison is transitive.
A collation may (or may not) support the ability to derive a
Furthermore, a collation may (or may not) support the ability to determine whether
one string is a substring of another under that collation. The use of collations
in substring matching is described in
The capabilities of a collation may be determined using the
http://www.w3.org/2005/xpath-functions/collation/codepoint identifies
a collation which must be recognized by every implementation: it is referred to as
the
The Unicode codepoint collation does not perform any normalization on the supplied strings.
The collation is defined as follows. Each of the two strings is
converted to a sequence of integers using the $A and $B are then compared as follows:
If both sequences are empty, the strings are equal.
If one sequence is empty and the other is not, then the string corresponding to the empty sequence is less than the other string.
If the first integer in $A is less than the first integer in $B, then
the string corresponding to $A is less than the string corresponding to
$B.
If the first integer in $A is greater than the first integer in $B, then
the string corresponding to $A is greater than the string corresponding to
$B.
Otherwise (the first pair of integers are equal), the result is obtained
by applying the same rules recursively to fn:tail($A) and
fn:tail($B)
While the Unicode codepoint collation does not produce results suitable for quality publishing of printed indexes or directories, it is adequate for many purposes where a restricted alphabet is used, such as sorting of vehicle registrations.
The Unicode codepoint collation differs from the default sort order used in programming languages that sort strings based on UTF-16 code units, which may include surrogate pairs.
This specification defines a family of collation URIs representing tailorings of the Unicode Collation
Algorithm (UCA) as defined in
This family of URIs use the scheme and path http://www.w3.org/2013/collation/UCA
followed by an optional query part. The query part, if present, consists of a question mark followed
by a sequence of zero or more semicolon-separated parameters. Each parameter is a keyword-value pair, the
keyword and value being separated by an equals sign.
All implementations must recognize URIs in this family in the collation argument of functions that
take a collation argument.
If the fallback parameter is
present with the value no, then the implementation fallback parameter
is omitted or takes the value yes, and if the collation URI is well-formed according to the rules in this section,
then the implementation http://www.w3.org/2013/collation/UCA?lang=se;fallback=yes and the implementation does not include a fully
conformant version of the UCA tailored for Swedish, then it
If two query parameters use the same keyword then the last one wins. If a query parameter uses a keyword or value which is not
defined in this specification then the meaning is fallback parameter is present with the value no it should reject
the collation as unsupported, otherwise it should ignore the unrecognized parameter.
The following query parameters are defined. If any parameter is absent, the default is
| Keyword | Values | Meaning |
|---|---|---|
| fallback | yes | no (default yes) | Determines whether the processor uses a fallback collation if a conformant collation is not available. |
| lang | language code: a string in the lexical space of xs:language. | The language whose collation conventions are to be used. |
| version | string | The version number of the UCA to be used. |
| strength | primary | secondary | tertiary | quaternary | identical, or 1|2|3|4|5 as synonyms (default tertiary / 3) | The collation strength as defined in UCA. Primary
strength takes only the base form of the character into account (so A=a=Ä=ä); secondary strength ignores case but considers accents
and diacritics as significant (so A=a and Ä=ä but ä≠a); tertiary considers case as significant (A≠a≠Ä≠ä); quaternary strength always considers as significant spaces and punctuation
(data-base≠database; if maxVariable is punct or higher and
alternate is not non-ignorable, lower strengths will treat data-base=database). |
| maxVariable | space | punct | symbol | currency (default punct) |
Given the sequence space, punct, symbol, currency,
all characters in the specified group and earlier groups are treated as “noise” characters
to be handled as defined by the alternate parameter. For example, maxVariable=punct indicates
that characters classified as whitespace or punctuation get this treatment. |
| alternate | non-ignorable | shifted | blanked (default non-ignorable) | Controls the handling of characters such as spaces and hyphens;
specifically, the "noise" characters in the groups selected by the maxVariable parameter. The value non-ignorable
indicates that such characters are treated as distinct at the primary level (so data base sorts before database);
shifted indicates that they are used to differentiate two strings only at the quaternary level,
and blanked indicates that they are taken into account only at the identical level. |
| backwards | yes | no (default no) | The value backwards=yes indicates that the last accent in the
string is the most significant. |
| normalization | yes | no (default no) | Indicates whether strings are converted to normalization form D. |
| caseLevel | yes | no (default no) | When used with primary strength, setting caseLevel=yes has the effect of ignoring accents
while taking account of case. |
| caseFirst | upper | lower (default lower) | Indicates whether upper-case precedes lower-case or vice versa. |
| numeric | yes | no (default no) | When numeric=yes is specified, a sequence of consecutive digits is interpreted as a number,
for example chap2 sorts before chap12. |
| reorder | a comma-separated sequence of reorder codes, where a reorder code is one of space, punct,
symbol, currency, digit, or a four-letter script code defined in | Determines the relative ordering of text in different scripts; for example the value digit,Grek,Latn indicates
that digits precede Greek letters, which precede Latin letters. |
This list excludes parameters that are inconvenient to express in a URI, or that are applicable only to substring matching.
UCA collation URIs can be conveniently generated using the
The collation URI http://www.w3.org/2005/xpath-functions/collation/unicode-case-insensitive must be recognized
by every implementation.
The collation is defined as follows:
Let $UCI be the collation URI
"http://www.w3.org/2005/xpath-functions/collation/unicode-case-insensitive".
Let $UCC be the Unicode Codepoint Collation URI
http://www.w3.org/2005/xpath-functions/collation/codepoint.
For any two strings $A and $B, the result
of the comparison fn:compare($A, $B, $UCI) is defined to be the same as
the result of fn:compare(lower-case($A), lower-case($B), $UCC).
The collation supports collation units and can therefore
be used with functions such as
The collation URI http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive must be recognized
by every implementation. It is class attribute values.
The collation is defined as follows:
Let $HACI be the collation URI
"http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive".
Let $UCC be the Unicode Codepoint Collation URI
http://www.w3.org/2005/xpath-functions/collation/codepoint.
Let $lc be the function
fn:translate(?, "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "abcdefghijklmnopqrstuvwxyz").
Then for any two strings $A and $B, the result
of the comparison fn:compare($A, $B, $HACI) is defined to be the same as
the result of fn:compare($lc($A), $lc($B), $UCC).
HTML5 defines the semantics of equality matching using this collation;
The corresponding HTML5 definition is: A string A is an ASCII case-insensitive match for a string B, if the ASCII lowercase of A is the ASCII lowercase of B.
Many functions have a signature that includes a $collation
argument, which is generally optional and takes default-collation()
as its default value.
The collation to use for these functions is determined by the following rules:
If the function specifies an explicit collation, CollationA (e.g., if
the optional collation argument is specified in a call of the
If CollationA is supported by the implementation, then CollationA is used.
Otherwise, a dynamic error is raised
If no collation is explicitly specified for the function
$collation argument is omitted or is set to an
empty sequence)
If CollationB is supported by the implementation, then CollationB is used.
Otherwise, a dynamic error is raised
Because the set of collations that are supported is
If the value of the collation argument is a relative URI reference, it is resolved against the base-URI from the
static context. If it is a relative URI reference and cannot be resolved, perhaps because the base-URI property in the static context
is absent, a dynamic error is raised
There is no explicit requirement that the string used as a collation URI be a valid URI.
Implementations will in many cases reject such strings on the grounds that do not identify a supported collation; they
may also cause an error if they cannot be resolved against the
Returns true if two strings are equal, considered codepoint-by-codepoint.
This function is
If either argument is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns true or false depending on
whether $value1 is equal to
$value2, according to the Unicode codepoint collation
(http://www.w3.org/2005/xpath-functions/collation/codepoint).
This function allows xs:anyURI values to be compared without having to
specify the Unicode codepoint collation.
| Expression | Result |
|---|---|
codepoint-equal("abcd", "abcd") |
|
codepoint-equal("abcd", "abcd ") |
|
codepoint-equal("", "") |
|
codepoint-equal("", ()) |
|
codepoint-equal((), ()) |
|
Constructs a collation URI with requested properties.
This function is
The function is supplied with a map defining the properties required of the collation, and returns a collation URI with these properties.
Specifically, it returns a string in the form of a URI with the scheme and path
http://www.w3.org/2013/collation/UCA followed by an optional
query part. The query part is absent if options is empty.
Otherwise it consists of a question mark followed
by a sequence of one or more semicolon-separated parameters. Each parameter
is a keyword-value pair, the keyword and value being separated by an equals sign.
There is one keyword-value pair for each entry in the options map:
the keyword is the same as the string value of the key in the map, and the value
is the string value of the corresponding value, except where the value is of
type xs:boolean, in which case true and false
are translated to yes and no.
The function does not check whether the implementation actually recognizes
the resulting collation URI: that can be achieved using the
The properties available are as defined for the Unicode Collation Algorithm
(see
The
If the option key is of type xs:string, xs:anyURI,
or xs:untypedAtomic then it is converted to a string, and produces
a URI query parameter which is handled as described in
If the option key is of any other type then the function fails with a
type error
The following options are defined:
| Key | Meaning |
|---|---|
| See
|
| See
|
| See
|
| See
|
| See
|
| See
|
| See
|
| See
|
| See
|
| See
|
| See
|
| See
|
A type error is raised options includes an entry whose key is not of
type xs:string, xs:anyURI,
or xs:untypedAtomic, or whose corresponding value
is not castable to xs:string.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: | A collation suitable for the default language in the dynamic context. |
Asks whether a collation URI is recognized by the implementation.
This function is
The supplied argument is a candidate collation URI.
The function returns true if and only if the implementation recognizes the candidate collation URI.
If the candidate collation is a UCA collation specifying fallback=yes,
then this function will always return true: implementations are required to recognize
such a collation and use fallback behavior if there is no direct equivalent available.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
Given a string value and a collation, generates an internal value called a collation key, with the property that the matching and ordering of collation keys reflects the matching and ordering of strings under the specified collation.
This function is
Calling the one-argument version of this function is equivalent to calling the two-argument version supplying the default collation as the second argument.
The function returns an $K1 and $K2:
collation-key($K1, $C) eq collation-key($K2, $C) if and only if
compare($K1, $K2, $C) eq 0
collation-key($K1, $C) lt collation-key($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 context-free 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
The result of the function is defined to be an xs:base64Binary value. Binary values
are chosen because they have unambiguous and context-free 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:collation-key($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.
The
| Variables | |
|---|---|
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: |
|
As the above examples illustrate, it is important that when the
| |
Determines whether or not any of the supplied strings, when tokenized at whitespace boundaries, contains the supplied token, under the rules of the supplied collation.
The two-argument form of this function is
The three-argument form of this function is
If $value is the empty sequence, the function returns false.
Leading and trailing whitespace is trimmed from $token.
If the trimmed value of $token
is a zero-length 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.
The effect of the function is equivalent to the result of the following XPath 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 space-separated 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 space-separated 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 case-insensitive collation
should be used: see
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: |
The following functions are defined on values of type xs:string and
types derived from it.
| Function | Meaning |
|---|---|
fn:char | Returns a string containing a particular character or glyph. |
fn:characters | Splits the supplied string into a sequence of single-character strings. |
fn:graphemes | Splits the supplied string into a sequence of single-grapheme strings. |
fn:concat | Returns the concatenation of the arguments, treated as sequences of strings. |
fn:string-join | Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items. |
fn:substring | Returns the part of $value beginning at the position
indicated by $start and continuing for the number of $length. |
fn:string-length | Returns the number of |
fn:normalize-space | Returns $value with leading and trailing whitespace removed, and
sequences of internal whitespace reduced to a single space character. |
fn:normalize-unicode | Returns $value after applying Unicode normalization. |
fn:upper-case | Converts a string to upper case. |
fn:lower-case | Converts a string to lower case. |
fn:translate | Returns $value modified by replacing or removing individual
characters. |
fn:hash | Returns the results of a specified hash, checksum, or cyclic redundancy check function applied to the input. |
When the above operators and functions are applied to datatypes derived from
xs:string, they are guaranteed to return values that are instances of
xs:string, but the value might or might not be an instance of the
particular subtype of xs:string to which they were applied.
The strings returned by
Returns a string containing a particular character or glyph.
This function is
The function returns a string, generally containing a single $value.
The supplied value of $value must be one of the following:
A Unicode codepoint, supplied as an integer. For example fn:char(9)
returns the tab character.
An HTML5 character reference name (often referred to as an entity name) as defined
at fn:char("pi") represents the character
fn:char("nbsp") returns
A processor
In the event that the HTML5 character reference name identifies a string comprising multiple codepoints, that string is returned.
[TODO: add a proper bibliographic reference.]
A backslash-escape sequence from the set \n (\r (\t (
The result must consist of
fn:char(0xDEAD) is invalid because it is in the surrogate range.
The function fails with a dynamic error $value is not a valid
representation of a
Although all Unicode characters can appear in string literals (the delimiting quotation marks can be escaped by doubling them), some characters are not visually distinctive, so representing them by name may make code more readable. In addition, there may be contexts where it is necessary or prudent to write XPath expressions using ASCII characters only, for example where an expression is used in the query part of a URI.
A few HTML5 character reference names identify glyphs whose Unicode
representation uses multiple codepoints. For example, the name
NotEqualTilde refers to the glyph ≂̸ which is expressed
using the two codepoints
| Expression | Result |
|---|---|
char("aacute") |
|
char("eth") |
|
char(9) |
|
char("\t") |
|
char(0x20) |
|
char(0x1D1CA) |
|
char("NotEqualTilde") |
|
Splits the supplied string into a sequence of single-character strings.
This function is
The function returns a sequence of strings, each string having length 1, containing
the corresponding $value.
If $value is a zero-length string or the empty sequence, the function returns
the empty sequence.
The effect of the function is equivalent to the result of the following XPath expression.
| Expression | Result |
|---|---|
characters("Thérèse") |
|
characters("") |
|
characters(()) |
|
characters("Banana") => index-of("a") |
|
characters("stretch") => string-join("-") |
|
Splits the supplied string into a sequence of single-grapheme strings.
This function is
The function returns a sequence of strings. Each string in the sequence contains one or
more
If $value is a zero-length string or the empty sequence, the function returns
the empty sequence.
The resultant sequence of strings are extended graphemes, not legacy graphemes (see
| Expression | Result |
|---|---|
graphemes("a" || char(0x308) || "b") |
|
graphemes("") |
|
graphemes(()) |
|
graphemes(char('\r') || char('\n')) |
|
graphemes(char(0x1F476) || char(0x200D) || char(0x1F6D1)) |
|
graphemes("कत") |
|
graphemes("क" || char(0x93C) || char(0x200D) || char(0x94D) || "त") |
|
Returns the concatenation of the arguments, treated as sequences of strings.
The two-argument form of
this function defines the semantics of the || operator.
This function is
Unlike all other functions, this function is defined to be variadic, as indicated by the ellipsis in the function signature. Conceptually, there is an infinite set of functions with different numbers of arguments (minimum arity zero, maximum arity unbounded):
concat() returns a zero-length string, "".
concat("a") returns "a".
concat("a", "b") returns "ab".
concat("a", "b", "c") returns "abc".
concat("a", "b", "c", "d") returns "abcd".
and so on.
It is equally possible to supply a single argument containing a sequence of strings:
concat(()) returns a zero-length string, "".
concat(("a")) returns "a".
concat(("a", "b")) returns "ab".
concat(("a", "b", "c")) returns "abc".
concat(("a", "b", "c", "d")) returns "abcd".
and so on.
More generally, any argument can be a sequence of strings:
concat(("a", "b"), "c") returns "abc".
concat(("a", "b"), (), ("c", "d")) returns "abcd".
A static call on the
Each of the parameters has the required type
xs:anyAtomicType*. The coercion rules ensure that each supplied argument is first converted to
a sequence of atomic items by applying atomization. These sequences are then combined (by
If XPath 1.0 compatibility mode is set to true in the static context of a
static function call to $v is first reduced to a single
string, the result of the expression xs:string($v[1]). This rule applies only to
static function calls.
A named function reference can be used to create a function item with any arity: for example
concat#3 returns a function item that takes three arguments, which it concatenates.
Similarly partial function application can be used to construct a function that concatenates fixed and
variable values: for example concat('[', ?, ']') returns a function item that takes a single
argument and wraps the string value of this argument in square brackets. Similarly,
concat(?, '-', ?) returns a function item of arity two; it returns the string values of
the two arguments separated by a hyphen.
As mentioned in xs:string
returned by
where the ? represents either the actual Unicode character ̈, will return:
"I plan to go to Mu?nchen in September"
where the ? again represents either the actual Unicode character ̈.
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 ̈, will return:
"I plan to go to München in September"
This returned result is normalized in NFC.
Alternatives to the || (for example $x || '-' || $y), the use of string templates
(for example `{ $x }-{ $y }`), and the
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items.
This function is
The coercion rules ensure that the supplied $values argument is first converted to
a sequence of atomic items by applying atomization.
The function then returns an xs:string created by casting each item
in the atomized sequence to an xs:string,
and then concatenating the result strings in order,
using the value of $separator as a
separator between adjacent strings. If $separator is the zero-length
string, then the items in $values are concatenated without a separator.
If $values is the empty sequence, the function returns the
zero-length string.
| Variables | |
|---|---|
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns the part of $value beginning at the position
indicated by $start and continuing for the number of $length.
This function is
If $value is the empty sequence, the function returns
the zero-length 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 non-empty) less than the sum of
$start and $length (both rounded to integers).
The characters returned do not extend beyond $value. If
$start is zero or negative, only those characters in positions greater
than zero are returned.
More specifically, the three argument version of the function returns the characters in
$value whose position $p satisfies:
fn:round($start) <= $p and $p < fn:round($start) + fn:round($length)
The two argument version of the function assumes that $length is infinite
and thus returns the $value whose position $p satisfies:
fn:round($start) <= $p
In the above computations, the operators such as <= and +
are evaluated according to the rules of the XPath 4.0 specification.
The first character of a string is located at position 1, not position 0.
The second and third arguments allow xs:double values (rather than
requiring xs:integer) in order to achieve compatibility with XPath 1.0.
A surrogate pair counts as one character, not two.
The consequences of supplying values such as NaN or positive or negative
infinity for the $start or $length arguments follow from the
above rules, and are not always intuitive.
| Expression | Result |
|---|---|
substring("motor car", 6) |
|
substring("metadata", 4, 3) |
|
substring("12345", 1.5, 2.6) |
|
substring("12345", 0, 3) |
|
substring("12345", 5, -3) |
|
substring("12345", -3, 5) |
|
substring("12345", 0 div 0E0, 3) |
|
substring("12345", 1, 0 div 0E0) |
|
substring((), 1, 3) |
|
substring("12345", -42, 1 div 0E0) |
|
substring("12345", -1 div 0E0, 1 div 0E0) |
|
$value
has been generalized to xs:anyAtomicType?.Returns the number of
The zero-argument form of this function is
The one-argument form of this function is
If $value is the empty sequence, the function returns the
xs:integer value 0.
Otherwise, the value is cast to an xs:string, and an xs:integer
is returned that reflects the number of
If $value is not specified and the context value is
As a consequence of the rules given above, a type error is raised
Unlike some programming languages, a
There are situations where fn:string-length() has a different effect
from fn:string-length(.). These situations all involve nodes with
non-trivial type annotations. For example:
If the context value
is an attribute node typed as an xs:integer with the string value 000001,
then fn:string-length() returns 6
(the length of the string value of the node), while
fn:string-length(.) returns 1 (the length of the string that results from converting
the typed value (1) to a string). In earlier versions of this specification this call would have
failed with a type error.
If the context value is the element node <e> NN </e>, and has the
type annotation xs:NCName, then fn:string-length() returns
4 (the length of the string value of the element node), while fn:string-length(.)
returns 2 (the length of the typed value of the element node).
If the context value is the attribute node ref="A B C", and has the
type annotation xs:IDREFS, then fn:string-length() returns
5 (the length of the string value of the attribute node), while fn:string-length(.)
raises an error, because the atomized value of the attribute is a sequence of strings,
and calling the fn:string function on a sequence of strings fails.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
$value
has been generalized to xs:anyAtomicType?.Returns $value with leading and trailing whitespace removed, and
sequences of internal whitespace reduced to a single space character.
The zero-argument form of this function is
The one-argument form of this function is
If $value is the empty sequence, the function returns a zero-length string.
Otherwise, the value is cast to an xs:string, and a new string is
constructed by stripping leading and trailing whitespace from the string, and by
replacing sequences of one or more adjacent whitespace characters with a single space,
The whitespace characters are defined in the metasymbol S (Production 3) of
If no argument is supplied and the context value is
As a consequence of the rules given above, a type error is raised
The definition of whitespace is unchanged in
S ::= (#x20 | #x9 | #xD | #xA)+
There are situations where fn:normalize-space() has a different effect
from fn:normalize-space(.). These situations all involve nodes with
non-trivial type annotations. For example:
If the context value
is an attribute node typed as an xs:integer with the string value 000001,
then fn:normalize-space() returns "000001"
(the string value of the node, whitespace-normalized), while
fn:normalize-space(.) returns "1" (the typed value of the node,
converted to a string and then normalized).
If the context value is the attribute node ref=" A B C ", and has the
type annotation xs:IDREFS, then fn:normalize-space() returns
"A B C" (the string value of the attribute node, whitespace-normalized),
while fn:normalize-space(.)
raises an error, because the typed value of the attribute is a sequence of strings,
and calling the
The effect of fn:normalize-space is exactly the same as the effect of
the whitespace=collapse facet in XSD. Since this facet is implicit for most
XSD data types (with the notable exception of xs:string itself), nodes that are
validated against types other than xs:string will tend to be implicitly
in the form that xs:normalizedString uses the facet whitespace=replace,
which does
| Expression: | |
|---|---|
| Result: | |
| Expression: |
|
| Result: |
|
Returns $value after applying Unicode normalization.
This function is
If $value is the empty sequence, the function returns the
zero-length string.
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:upper-case(fn:normalize-space($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
FULLY-NORMALIZED
, then the function returns
$value converted to fully normalized form.
If the effective value of $form is the zero-length
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 FULLY-NORMALIZED 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 non-zero canonical combining class (as defined in
A string is converted to FULLY-NORMALIZED 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
FULLY-NORMALIZED. They
It is
A $form argument is not one of the values
supported by the implementation.
Converts a string to upper case.
This function is
If $value is the empty sequence, the zero-length string is
returned.
Otherwise, the function returns $value after translating every
Case mappings may change the length of a string. In general, the
fn:lower-case(fn:upper-case($s)) is not guaranteed to
return $s, nor is fn:upper-case(fn:lower-case($s)). The
character
These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.
Because the function is not sensitive to locale, results will not always match user
expectations. In Quebec, for example, the standard uppercase equivalent of è is È,
while in metropolitan France it is more commonly E; only one of these is supported by
the functions as defined.
Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.
| Expression | Result |
|---|---|
upper-case("abCd0") |
|
Converts a string to lower case.
This function is
If t$value is the empty sequence, the zero-length string is
returned.
Otherwise, the function returns $value after translating every
Case mappings may change the length of a string. In general, the
fn:lower-case(fn:upper-case($s)) is not guaranteed to
return $s, nor is fn:upper-case(fn:lower-case($s)). The
character
These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.
Because the function is not sensitive to locale, results will not always match user
expectations. In Quebec, for example, the standard uppercase equivalent of è is È,
while in metropolitan France it is more commonly E; only one of these is supported by
the functions as defined.
Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.
| Expression | Result |
|---|---|
lower-case("ABc!D") |
|
Returns $value modified by replacing or removing individual
characters.
This function is
If $value is the empty sequence, the function returns the
zero-length 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 zero-length string then the function returns
$value unchanged.
If a character occurs more than once in $replace, then the first
occurrence determines the action taken.
If $with is longer than $replace, the excess
characters are ignored.
| Expression | Result |
|---|---|
translate("bar", "abc", "ABC") |
|
translate("--aaa--", "abc-", "ABC") |
|
translate("abcdabc", "abc", "AB") |
|
Returns the results of a specified hash, checksum, or cyclic redundancy check function applied to the input.
This function is
If $value is the empty sequence, the function returns the empty sequence.
If $value is an instance of xs:string, it is converted to a sequence
of octets on the basis of UTF-8 encoding. If $value is an instance of
xs:base64Binary or xs:hexBinary, it is converted to a sequence of
octets.
The $algorithm argument determines the algorithm to be used to
calculate a checksum, hash, or cyclic redundancy check. The effective value of the
algorithm is determined by passing the value through
fn:upper-case(fn:normalize-space()).
Conforming implementations
MD5: the MD5 Message-Digest algorithm, defined by
SHA-1: the SHA-1 algorithm, defined by
SHA-256: the SHA-256 algorithm, defined by
BLAKE3: the BLAKE3 algorithm defined by
CRC-32: the CRC-32 algorithm, defined by xs:hexBinary value representing this integer in
big-endian order (that is, most significant byte first).
Some libraries, notably System.IO.Hashing.Crc32 in .NET, return
the result in little-endian order.
Conforming implementations $options argument, if present, defines additional parameters
controlling how the process is conducted.
The function returns as xs:hexBinary the octets returned by passing
$value as an octet sequence through the selected algorithm.
The process is followed even if the input octet sequence is empty.
A dynamic error is raised algorithm is not one of the values supported by the implementation.
It is common for secure algorithms to be cryptographically broken, as has happened to
the algorithms MD5, SHA-1, and SHA-256.
And the CRC-32 algorithm is not intended for cryptographic purposes.
Developers are responsible for ensuring that the algorithm chosen meets any expected
security protocols, if relevant.
The BLAKE3 algorithm is included in the list of hashing algorithms
because at the time of writing it appears to be a promising candidate as a secure and
fast algorithm that shows signs of gaining widespread support.
However, this is a fast moving field and the community group recognizes that this
decision might eventually not stand the test of time.
As the technology evolves in the future, implementations are free to drop support
for this algorithm and substitute another that appears to better meet requirements.
Additional security practices, such as salting, may be applied as a preprocessing step,
or fn:hash() can be incorporated into more complex functions.
In most cases, the xs:hexBinary output of the function will be sought in
string form. Because of serialization rules, casting to a string renders the hash in
uppercase, and rendering in lowercase (as adopted by
| Variables | |
|---|---|
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: |
|
| Result: | Raises error FOHA0001. |
The functions described in this section examine a string $arg1 to see
whether it contains another string $arg2 as a substring. The result
depends on whether $arg2 is a substring of $arg1, and
if so, on the range of $arg1 which $arg2 matches.
When the $arg1 contains a
contiguous sequence of characters whose $arg2.
When a collation is specified, the rules are more complex.
All collations support the capability of deciding whether two
The string
Q is then considered to contain P as a
substring if the sequence of collation units corresponding to P
is a subsequence of the sequence of collation units corresponding to
Q. The characters in P that match are the
characters corresponding to these collation units.
This rule may occasionally lead to surprises. For example, consider a collation
that treats "Jaeger" and "Jäger"
as equal. It might do this by treating "ä" as representing
two collation units, in which case the
expression fn:contains("Jäger", "eg") will return
true. Alternatively, a collation might treat "ae" as a single
collation unit, in which case the expression fn:contains("Jaeger",
"eg") will return false. The results of these functions thus
depend strongly on the properties of the collation that is used.
In addition,
collations may specify that some collation units should be ignored during matching. If hyphen is an ignored
collation unit, then fn:contains("code-point", "codepoint") will be true,
and fn:contains("codepoint", "-") will also be true.
In the rules for the functions defined in this section, we use the following terms
taken from
In the definitions in
C is the collation; that is, the value of the $collation
argument if specified, otherwise the default collation.
P is the (candidate) substring, the value of the $substring
argument to the function.
Q is the (candidate) containing string, the value of the $value
argument to the function.
The boundary condition B is satisfied at the start and end of a
string, and between any two characters that belong to different collation units
(“collation elements” in the language of
It is possible to define collations that do not have the ability to decompose a
string into units suitable for substring matching. An argument to a function
defined in this section may be a URI that identifies a collation that is able to
compare two strings, but that does not have the capability to split the string
into collation units. Such a collation may cause the function to fail, or to
give unexpected results, or it may be rejected as an unsuitable argument. The
ability to decompose strings into collation units is an
| Function | Meaning |
|---|---|
fn:contains | Returns true if the string $value contains $substring as a
substring, taking collations into account. |
fn:starts-with | Returns true if the string $value contains $substring as a leading
substring, taking collations into account. |
fn:ends-with | Returns true if the string $value contains $substring as a trailing
substring, taking collations into account. |
fn:substring-before | Returns the part of $value that precedes the first occurrence of
$substring, taking collations into account. |
fn:substring-after | Returns the part of $value that follows the first occurrence of
$substring, taking collations into account. |
Returns true if the string $value contains $substring as a
substring, taking collations into account.
The two-argument form of this function is
The three-argument form of this function is
If $value or $substring is the empty sequence, or
contains only ignorable collation units, it is interpreted as the zero-length
string.
If $substring is the zero-length string, then the function returns
true.
If $value is the zero-length string, the function returns
false.
The collation used by this function is determined according to the rules in
The function returns an xs:boolean indicating whether or not
$value contains (at the beginning, at the end, or anywhere within) at
least one sequence of collation units that provides a $substring, according to the collation that is
used.
A
| Variables | |
|---|---|
| Expression | Result |
|---|---|
The collation used in some of these examples, | |
“Ignorable collation unit” is equivalent to “ignorable collation element” in | |
contains("tattoo", "t") |
|
contains("tattoo", "ttt") |
|
contains("", ()) |
|
Returns true if the string $value contains $substring as a leading
substring, taking collations into account.
The two-argument form of this function is
The three-argument form of this function is
If $value or $substring is the empty sequence, or
contains only ignorable collation units, it is interpreted as the zero-length
string.
If $substring is the zero-length string, then the function returns
true. If $value is the zero-length string and
$substring is not the zero-length string, then the function returns
false.
The collation used by this function is determined according to the rules in
The function returns an xs:boolean indicating whether or not
$value starts with a sequence of collation units that provides a
$substring according to the
collation that is used.
A
| Variables | |
|---|---|
| Expression | Result |
|---|---|
The collation used in some of these examples, | |
“Ignorable collation unit” is equivalent to “ignorable collation element” in | |
starts-with("tattoo", "tat") |
|
starts-with("tattoo", "att") |
|
starts-with((), ()) |
|
Returns true if the string $value contains $substring as a trailing
substring, taking collations into account.
The two-argument form of this function is
The three-argument form of this function is
If $value or $substring is the empty sequence, or
contains only ignorable collation units, it is interpreted as the zero-length
string.
If $substring is the zero-length string, then the function returns
true. If $value is the zero-length string and
the value of $substring is not the zero-length string, then the function returns
false.
The collation used by this function is determined according to the rules in
The function returns an xs:boolean indicating whether or not
$value ends with a sequence of collation units that provides a
$substring according to the
collation that is used.
A
| Variables | |
|---|---|
| Expression | Result |
|---|---|
The collation used in some of these examples, | |
“Ignorable collation unit” is equivalent to “ignorable collation element” in | |
ends-with("tattoo", "tattoo") |
|
ends-with("tattoo", "atto") |
|
ends-with((), ()) |
|
Returns the part of $value that precedes the first occurrence of
$substring, taking collations into account.
The two-argument form of this function is
The three-argument form of this function is
If $value or $substring is the empty sequence, or
contains only ignorable collation units, it is interpreted as the zero-length
string.
If $substring is the zero-length string, then the function returns
the zero-length string.
If $value does not contain a string that is equal to
$substring, then the function returns the zero-length string.
The collation used by this function is determined according to the rules in
The function returns the substring of $value that precedes in
$value the first occurrence of a sequence of collation units
that provides a $substring
according to the collation that is used.
A
| Variables | |
|---|---|
| Expression | Result |
|---|---|
The collation used in some of these examples, | |
“Ignorable collation unit” is equivalent to “ignorable collation element” in | |
substring-before("tattoo", "attoo") |
|
substring-before("tattoo", "tatto") |
|
substring-before((), ()) |
|
Returns the part of $value that follows the first occurrence of
$substring, taking collations into account.
The two-argument form of this function is
The three-argument form of this function is
If $value or $substring is the empty sequence, or
contains only ignorable collation units, it is interpreted as the zero-length
string.
If $substring is the zero-length 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 zero-length string.
The collation used by this function is determined according to the rules in
The function returns the substring of $value that follows in
$value the first occurrence of a sequence of collation units
that provides a $substring
according to the collation that is used.
A dynamic error
| Variables | |
|---|---|
| Expression | Result |
|---|---|
The collation used in some of these examples, | |
“Ignorable collation unit” is equivalent to “ignorable collation element” in | |
substring-after("tattoo", "tat") |
|
substring-after("tattoo", "tattoo") |
|
substring-after((), ()) |
|
The functions described in this section make use of a regular expression syntax for pattern matching. The syntax and semantics of regular expressions are defined in this section.
#)
if the c flag is set.
^ and $) can no longer be followed
by a quantifier.
The regular expression syntax used by these functions is defined in terms of
the regular expression syntax specified in XSD 1.1 (see
Implementers should consult
The regular expression syntax and semantics are identical to those
defined in
In
XSD 1.1 is therefore used as the specification baseline, even for processors that only support XSD 1.0.
As well as extending the XSD 1.1 syntax for regular expressions, this specification also extends the processing model.
In XSD, a regular expression is defined to denote a set of strings, and the only functionality offered is to test whether a string matches a regular expression: that is, whether it is a member of the set of strings denoted by the regular expression.
In this specification, matching a string S against a regular expression delivers a more complex outcome.
First some terminology:
The operation of matching a string S against a regular expression delivers:
A set of matching
For each matching
The semantics of particular constructs in a regular expression are affected by
a set of flags. The available flags and their effect are defined in
The different functions available, such as fn:tokenize, are defined in terms of this outcome. For example:
The function
The function
The function
In principle the set of segments that match a regular expression can be determined by enumerating all the segments of the input string and examining each one independently to establish whether it matches. In practice, however:
If several matching segments have the same starting position, then only one of them is returned. This is chosen as follows:
In the case of a choice (operator "|") the first matching
branch is chosen.
In the case of a repetition with a greedy quantifier (for example "+"
or "*") the longest matching segment is chosen.
In the case of a repetition with a reluctant quantifier (for example "+?"
or "*?") the shortest matching segment is chosen.
A matching segment is not included in the result if it overlaps an earlier matching
segment: specifically, a segment with start position S1 is excluded if there
is a segment that has start position S0 and length L0, where
S0 < S1 < S0+L0.
Two segments can be adjacent: that is, the start position of one a*(?=x) has two non-overlapping matches against
the string aaax, one at position 1 and the other at position 4.
The semantics of a regular expression are thus defined by stating which segments of an input string it matches, and what the captured groups corresponding to this match are. This is defined recursively for each construct that may appear within a regular expression, in terms of the outcome of applying its subexpressions.
For constructs defined in XSD 1.1 (branch, piece,
NormalChar, charClass), XSD defines a set of strings
denoted by the construct. The corresponding semantics for this specification
are that the segments matched by such a construct are the segments whose string value
is contained in this set.
For constructs added to the XSD 1.1 baseline by this specification, the semantics are defined in the sections that follow.
Comments are enabled in regular expressions if the c flag is present.
A comment starts with a # character that is not escaped with an immediately
preceding backslash, and that is not contained in a CharClassExpr (that is,
in square brackets). It ends with the following # character, or with the
end of the string containing the regular expression.
Whether or not the c flag is present, the production for
SingleCharEsc allows the # character
to be escaped.
The grammar for regular expressions is summarized here. Rules that
differ from their definition in XSD 1.1 are marked with the character §
against their names.
In these rules the notation【abc】matches
any of the characters 'a', 'b', or 'c',
while 【0➜9】 matches any character whose Unicode codepoint is within a given range,
and ¬【abc】 matches any character other than 'a', 'b', or 'c'.
These symbols are used in place of the more conventional notation to allow special characters
such as square brackets and hyphens to appear directly without escaping. Within
the lenticular brackets, all characters other than ➜ (including hyphen and backslash)
represent themselves.
This grammar applies to the regular expression after removal of whitespace and comments
if enabled by the x and c flags respectively: see
XSD 1.1 defines additional rules to disambiguate this grammar.
?
following a quantifier. Specifically:
X?? matches X, once or not at all
X*? matches X, zero or more times
X+? matches X, one or more times
X{n}? matches X, exactly n times
X{n,}? matches X, at least n times
X{n,m}? matches X, at least n times, but
not more than m times
Quantifiers that are not
When a quantifier appears at the outermost level of a regular expression, the distinction between greedy and reluctant quantifiers affects the set of matching segments delivered by the matching operation. With a greedy quantifier, the longest matching segment at a given start position is returned; with a reluctant quantifier, the shortest matching segment at a given start position is returned.
When a quantifier appears within a subexpression, the quantified subexpression
matches the
Reluctant quantifiers have no effect on the results of the
boolean
The regular expression syntax defined by
? or * (see below),
is not within a character group (square brackets),
and is not escaped with a backslash. The sub-expression enclosed by a capturing left
parenthesis and its matching right parenthesis is referred to as a
More specifically, the
For example, in the regular expression A(BC(?:D(EF(GH[()])))), the
subexpression BC(?:D(EF(GH[()]))) is capturing subexpression 1, the string
subexpression EF(GH[()]) is capturing subexpression 2, and the subexpression
GH[()] is capturing subexpression 3.
When, in the course of evaluating a regular expression, a particular
When a (a*)+ and the input string "aaaa", an implementation
might legitimately capture either "aaaa" or a zero length string as the content
of the captured subgroup.
Parentheses that are required to group terms within the regular expression, but which are
not required for capturing of substrings, can be represented using
the syntax (?:xxxx).
In the absence of back-references (see below),
the presence of the optional ?: has no effect on the set of strings
that match the regular expression, but causes the left parenthesis not to be counted
by operations (such as
Back-references are allowed
outside a character class expression.
A back-reference is an additional kind of atom.
The construct \N where
N is a single digit is always recognized as a
back-reference; if this is followed by further digits, these
digits are taken to be part of the back-reference if and only if
the resulting number NN is such that
the back-reference is preceded by the opening parenthesis of the NNth
capturing left parenthesis.
The regular expression is invalid if a back-reference refers to a
capturing sub-expression that does not exist or whose
closing right parenthesis occurs after the back-reference.
A back-reference with number N matches a string that is the same as
the value of the Nth captured substring.
For example, the regular expression
('|").*\1 matches a sequence of characters
delimited either by an apostrophe at the start and end, or by a
quotation mark at the start and end.
If no string has been matched by the Nth capturing
sub-expression, the back-reference is interpreted as matching
a zero-length string.
Within a character class expression,
\ followed by a digit is invalid.
Some other regular expression languages interpret this as an octal character reference.
A regular expression that uses a Unicode block name that is not defined in the version(s) of Unicode
supported by the processor (for example \p{IsBadBlockName}) is deemed to be invalid
XSD 1.0 does not say how this situation should be handled; XSD 1.1 says that it should be handled by treating all characters as matching.
Assertions (sometimes called
Assertions fall into the following categories:
The startOfString assertion ^ tests whether the current
position is at the start of the string.
The endOfString assertion $ tests whether the current position
is at the end of the string.
The boundary assertions \b and \B test
whether the current position is at the start or end of a word.
The positive and negative lookahead assertions test whether there is (or is not) a substring starting at the current position that matches a given regular expression.
The positive and negative lookbehind assertions test whether there is (or is not) a substring ending at the current position that matches a given regular expression.
An assertion
Previous versions of this specification allowed a quantifier to follow the
startOfString and endOfString assertions, though this
served no practical purpose. Processors
Two meta-characters, ^ and $ are
added. By default, the meta-character ^ matches if the current position is the
start of the entire string, while $ matches if the current position is the end
of the entire string. In multi-line mode, ^ matches
the start of any line (that is, the start of the entire string,
and the position immediately after a newline character), while
$ matches the end of any line (that is, the end of
the entire string, and the position immediately before a newline
character). Newline here means the character
Single character escapes are extended to allow the
$ character to be escaped.
The assertion \b matches at any position where one of the following conditions is true:
The current position is the start of the string, the string is not empty, and the first
character in the string matches \w.
The current position is the end of the string, the string is not empty, and the
last character in the string matches \w.
The character before the current position matches \w and the character
after the current position matches \W.
The character before the current position matches \W and the character
after the current position matches \w.
Informally, \b matches if the current position is the start or end
of a word, where a word is defined as a sequence of consecutive characters other than
codepoints in Unicode groups P (punctuation), Z (separator),
or C (other).
The assertion \B matches at any position where \b does not match.
There are two equivalent ways of writing a positive lookahead assertion:
(?=xyz)
(*positive_lookahead:xyz)
In both cases, the assertion matches at a particular position in the input string only if there is a substring starting at that position that matches the regular expression xyz.
As with all assertions, evaluation of the assertion does not cause the current position to advance.
For example, Chapter(?=\s+[1-9]) will match "Chapter" only if
followed by a number, with intervening whitespace.
A parenthesized expression within a lookahead assertion can capture a substring in the normal way. There are some minor complications, however:
Substrings captured while evaluating a lookahead assertion are represented
differently in the result of the
If an assertion is satisfied, then any substrings that are captured are based on the first evaluation of the assertion that matches; alternative evaluations of the assertion that also match, but which capture different substrings, are not considered.
A positive lookahead assertion that matches a zero-length string is permitted but pointless, since it will always match, and thus cause the assertion to succeed.
There are two equivalent ways of writing a negative lookahead assertion:
(?!xyz)
(*negative_lookahead:xyz)
In both cases, the assertion matches at a particular position in the input string only if there is no substring starting at that position that matches the regular expression xyz.
As with all assertions, evaluation of the assertion does not cause the current position to advance.
For example, Chapter(?!\s*[1-9]) will match "Chapter" only if
it is not followed by a number, with optional intervening whitespace.
Any capturing parentheses within a negative lookahead assertion are counted for the purpose of numbering captured groups, but they cannot capture any result because the pattern in the assertion must fail to match.
A negative lookahead assertion that matches a zero-length string is permitted but pointless, since it will always match, and thus cause the assertion to fail.
There are two equivalent ways of writing a positive lookbehind assertion:
(?<=xyz)
(*positive_lookbehind:xyz)
The second form may be more convenient when the expression appears within an XML-based host language such as XSLT, where the angle bracket would need to be escaped.
In both cases, the assertion matches at a particular position in the input string only if there is a substring ending at that position that matches the regular expression xyz.
For efficiency and ease of implementation, the regular expression contained
within a lookbehind assertion is constrained. It must consist of one or more
alternatives separated by "|", and each alternative must be fixed-length,
consisting only of the following constructs, each of which matches a single character:
NormalChar (for example "A", "3")
SingleCharEsc (for example "\(", "\[")
charClassEsc (for example "\s", "\p{Lu}")
charClassExpr (for example "[a-z]")
WildcardEsc (".")
As with all assertions, evaluation of the assertion does not cause the current position to advance.
Parenthesized expressions cannot appear within lookbehind assertions.
For example, (?<=\[)[0-9+](?=\]) matches a sequence of digits immediately
preceded by an opening square bracket and followed by a closing square bracket, without
matching the brackets.
There are two equivalent ways of writing a negative lookbehind assertion:
(?<!xyz)
(*negative_lookbehind:xyz)
The second form may be more convenient when the expression appears within an XML-based host language such as XSLT, where the angle bracket would need to be escaped.
In both cases, the assertion matches at a particular position in the input string only if there is no substring ending at that position that matches the regular expression xyz.
The regular expression within a negative lookbehind assertion is subject to the
same restrictions as for a positive lookbehind assertion: see
For example, (?<!\$)[0-9]+ matches any sequence of digits that
is not immediately preceded by a dollar sign.
#)
if the c flag is set.
All these functions provide an optional parameter, $flags,
to set options for the interpretation of the regular expression. The
parameter accepts a xs:string, in which individual letters
are used to set options. The presence of a letter within the string
indicates that the option is on; its absence indicates that the option
is off. Letters may appear in any order and may be repeated. They are case-sensitive. If there
are characters present that are not defined here as flags, then a dynamic error
is raised
The following options are defined:
s: If present, the match operates in “dot-all”
mode. (Perl calls this the single-line mode.) If the
s flag is not specified, the meta-character
. matches any character except a newline
(#x0A) or carriage return (#x0D)
character. In dot-all mode, the
meta-character . matches any character whatsoever.
Suppose the input contains the strings "hello" and
"world" on two lines.
This will not be matched by the regular expression
"hello.*world" unless dot-all mode is enabled.
m: If present, the match operates in multi-line
mode. By default, the meta-character ^ matches the
start of the entire string, while $ matches the end of the
entire string. In multi-line mode, ^ matches the
start of any line (that is, the start of the entire string, and
the position immediately after a newline character
other than a newline
that appears as the last character in the string), while
$ matches the end of any line
(that is, the position immediately
before a newline character, and the end of the entire string if there is no
newline character at the end of the string).
Newline here means the character #x0A only.
i: If present, the match operates in
case-insensitive mode. The detailed rules are as follows.
In these
rules, a character C2 is considered to be a true when the two characters
are considered as strings of length one, and the
fn:lower-case(C1) eq fn:lower-case(C2) or
fn:upper-case(C1) eq fn:upper-case(C2)
Note that the case-variants of a character under this definition are always single characters.
When a normal character (Char) is used as an atom,
it represents
the set containing that character and all its case-variants.
For example, the regular expression "z" will
match both "z" and "Z".
A character range (productions charRange and singleChar
in the XSD 1.1 grammar) represents the set
containing all the characters that it would match in the absence
of the i flag, together with their case-variants.
For example,
the regular expression "[A-Z]" will match all
the letters A to Z and all the letters
a to z. It will also match
certain other characters such as #x212A (KELVIN SIGN), since
fn:lower-case("#x212A") is k.
This rule applies also to a character range used in a character
class subtraction (charClassSub): thus [A-Z-[IO]] will match
characters such as A, B, a, and b, but will not match
I, O, i, or o.
The rule also applies to a character range used as part of a
negative character group: thus "[^Q]" will match every character
except Q and q (these being the only case-variants of Q in
Unicode).
A back-reference is compared using case-blind comparison:
that is, each character must either be the same as the
corresponding character of the previously matched string, or must
be a case-variant of that character. For example, the strings
"Mum", "mom", "Dad",
and "DUD" all match the regular
expression "([md])[aeiou]\1" when the i flag is used.
All other constructs are unaffected by the i flag.
For example,
"\p{Lu}" continues to match upper-case letters only.
x: If present, whitespace characters
(that is, charClassExpr) are not removed. This flag can be used,
for example, to break up long regular expressions into readable lines.
Examples:
fn:matches("helloworld", "hello world", "x") returns true()
fn:matches("helloworld", "hello[ ]world", "x") returns false()
fn:matches("hello world", "hello\ sworld", "x") returns true()
fn:matches("hello world", "hello world", "x") returns false()
Whitespace is treated as a lexical construct to be removed before the regular expression is parsed; it is therefore not explicit in the regular expression grammar.
q: if present, all characters in the regular expression
are treated as representing themselves, not as metacharacters. In effect, every
character that would normally have a special meaning in a regular expression is implicitly escaped
by preceding it with a backslash.
Furthermore, when this flag is present, the characters $ and
\ have no special significance when used in the replacement string
supplied to the
This flag can be used in conjunction with the i flag. If it is used
together with the m, s, x,
c
Examples:
tokenize("12.3.5.6", ".", "q") returns ("12", "3", "5", "6")
replace("a\b\c", "\", "\\", "q") returns "a\\b\\c"
replace("a/b/c", "/", "$", "q") returns "a$b$c"
matches("abcd", ".*", "q") returns false()
matches("Mr. B. Obama", "B. OBAMA", "iq") returns true()
c: if present, comments are enabled
in the regular expression. This flag has no effect if the q flag is
present. A comment is recognized by the presence of a # character that
is not escaped by a backslash or contained in a character class expression
(charClassExpr), and it is terminated by the following #
character or by the end of the regular expression string.
For example:
replace("03/24/2025", "(..#month#)/(..#day#)/(....#year#)", "$3-$1-$2", "c")
Comments are treated as a lexical construct to be removed before the regular expression is parsed; they are therefore not explicit in the regular expression grammar.
| Function | Meaning |
|---|---|
fn:matches | Returns true if the supplied string matches a given regular expression. |
fn:replace | Returns a string produced from the input string by replacing any segments that match a given regular expression with a supplied replacement string, provided either literally, or by invoking a supplied function. |
fn:tokenize | Returns a sequence of strings constructed by splitting the input wherever a separator is found; the separator is any substring that matches a given regular expression. |
fn:analyze-string | 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. |
Returns true if the supplied string matches a given regular expression.
This function is
If $value is the empty sequence, it is interpreted as the zero-length
string.
Flags are defined in
The function returns true if the set of $value against the regular expression $pattern,
with the associated $flags, is non-empty. 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 multi-line mode).
This is different from the behavior of patterns in
Regular expression matching is defined on the basis of Unicode codepoints; it takes no account of collations.
It is valid for the regular expression to match a zero-length segment of $value.
For example, the result of the expression matches($s, "") is always true, regardless
of the value of $s.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
matches("abracadabra", "bra") |
|
matches("abracadabra", "^a.*a$") |
|
matches("abracadabra", "^bra") |
|
matches($poem, "Kaum.*krähen") |
|
matches($poem, "Kaum.*krähen", "s") |
|
matches($poem, "^Kaum.*gesehen,$", "m") |
|
matches($poem, "^Kaum.*gesehen,$") |
|
matches($poem, "kiki", "i") |
|
$replacement argument can now be a function
that computes the replacement strings.Returns a string produced from the input string by replacing any segments that match a given regular expression with a supplied replacement string, provided either literally, or by invoking a supplied function.
This function is
If the $flags argument is omitted or if it is the empty sequence,
the effect is the same as setting $flags to a zero-length string.
Flags are defined in
The string $value is matched against the regular expression $pattern,
using the supplied $flags, to obtain a set of $replacement argument, by applying the first
of the following rules that applies:
If $replacement is a function item F, then
R is obtained by calling F, and then applying the
function
The first argument to F is the string to be replaced,
provided as xs:untypedAtomic.
The second argument to F provides the captured
groups as an xs:untypedAtomic sequence.
The Nth item in this sequence is the string value of the segment captured by
the Nth capturing subexpression. If the
Nth capturing subexpression was not matched, the Nth item
will be the zero-length string.
Note that the rules for function coercion mean that the function actually supplied for F may be an arity-1 function: the second argument does not need to be declared if it is not used.
If $replacement is a string and the
q flag is present, R is the value
of $replacement.
Otherwise, the value of $replacement is processed as follows.
Within the supplied $replacement string, a variable marker $N (where
N is an unsigned integer) may
be used to refer to the Nth captured group associated with M.
The replacement string R is obtained by replacing each of these variable markers
with the string value of the relevant captured group.
The variable marker $0 refers to the substring captured by the regular expression as a
whole.
A literal $ character within the
replacement string must be written as \$, and a literal \
character must be written as \\.
More specifically, the rules are as follows, where S is the number of
capturing subexpressions in the regular expression, and N is the
decimal number formed by taking all the digits that consecutively follow the
$ character in $replacement:
If N=0, then the variable is replaced by the string value of M.
If 1<=N<=S, then the variable marker is
replaced by the string value of the Nth captured group associated
with M. If the
Nth parenthesized sub-expression was not matched, then the
variable marker is replaced by the zero-length string.
If S<N<=9, then the variable marker is
replaced by the zero-length 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 capturing subexpression, followed by the digit
3.
The function returns the xs:string that is obtained by replacing each
of the $value with
the corresponding value of R.
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
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 0-9 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 the 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.
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 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:
The rules for .*
will typically produce two matches: one matching segment containing all the characters in the
input string, and a second zero-length matching seqment at the end position of the string.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns a sequence of strings constructed by splitting the input wherever a separator is found; the separator is any substring that matches a given regular expression.
This function is
The following rules apply when the $pattern
argument is the empty sequence:
The function splits the supplied string at whitespace boundaries.
More specifically, calling fn:tokenize($value) fn:tokenize($value, ())fn:tokenize(fn:normalize-space($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:
Flags are defined in
If $value is the empty sequence, or if $value is the
zero-length 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.
More specifically:
Let M0 be the sequence of $value against $pattern in the presence
of $flags.
Unless the first segment in M0 is zero-length and starts at the first $value, prepend a zero-length segment that starts at the start of $value:
call the result M1.
Unless the last segment in M1 is zero-length and starts at the last $value (that is, the character position after the last character), append a zero-length
segment that starts at the last character position of $value. Call the result M2.
For each pair of adjacent segments in M2 (say, S/n and S/n+1),
construct a string (possibly zero-length) that is the substring of $value containing all characters
that follow S/n and that precede S/n+1. Return this sequence of strings, in order.
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
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.
For the one-argument form of the function:
The function has a similar effect to
the two-argument form with \s+ as the separator pattern, except that the one-argument
form strips leading and trailing whitespace, whereas the two-argument form delivers an extra
zero-length token if leading or trailing whitespace is present.
The separator used is any sequence
of tab (
For the two-argument form of the function:
The function returns no information about the separators that were found
in the string. If this information is required, the (?<=,) will start a new token after every comma,
including the comma as part of the previous token.
If a separator occurs at the start of $value, and is not zero-length, the result
sequence will start with a zero-length string. Similarly, zero-length strings will also occur in
the result sequence if a non-zero-length separator occurs at the end of $value,
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:
The pattern may match zero-length segments of the input string. For example, the
expression tokenize("Do not eat", "\b") returns the sequence
"Do", " ", "not", " ", "eat".
A string may be split into individual characters (producing the same effect as the
tokenize("xyz", ""),
or any other regular expression such as .?? that matches every zero-length string, regardless
of position.
Unlike the split method in some other popular languages, however,
not every regular expression that matches a zero-length string produces this
behavior: for example the regular expression \b splits the string
before and after every word.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: |
Analyzes a string using a regular expression, returning an XML structure that identifies which parts of the input string matched or failed to match the regular expression, and in the case of matched substrings, which substrings matched each capturing group in the regular expression.
This function is
Flags are defined in
If $value is the empty sequence, the function behaves as if
$value were the zero-length string.
The function returns an element node whose local name is
analyze-string-result. This element and all its descendant elements have
the namespace URI http://www.w3.org/2005/xpath-functions. The namespace
prefix is fn:match and fn:non-match 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 an
fn:match element, and any intervening substring as the content of an
fn:non-match element.
More specifically, the function starts by matching the regular expression against the string,
using the supplied $flags, to obtain the fn:match child, whose string value is
the string value of the segment. Before, between, or after these fn:match
elements, as required to ensure that the string value of the fn:analyze-string-result
element is the same as $value, it inserts fn:non-match elements.
The content of an fn:non-match element is always a single (non-empty) text node,
and two fn:non-match elements never appear as adjacent siblings.
The captured groups for each fn:group or fn:lookahead-group
children of the corresponding fn:match element. Groups captured by a subexpression within
a lookahead assertion are referred to as lookahead groups; those not within a lookahead
assertion are called ordinary groups.
The content of an fn:match element is in general:
A sequence of text nodes and fn:group element children,
whose string-values when concatenated comprise the string value of the matching segment,
followed by
A sequence of zero or more fn:lookahead-group elements,
representing the lookahead groups
The string value of an fn:match element may be empty.
An fn:group element
with a nr attribute having the integer value N identifies
the substring captured by an ordinary group, specifically the string value of the Nth captured group.
For each ordinary capturing subexpression there will be at most one corresponding
fn:group element in each fn:match element in the
result.
By contrast, lookahead groups are represented by fn:lookahead-group elements,
which (if they appear at all) must follow all text node and fn:group element children
of the fn:match element. These groups may overlap the matching and non-matching substrings, and
indeed may overlap each other. They must appear in ascending numerical order of group number.
The attributes of the fn:lookahead-group element are as follows:
nr: the group number, based on the position of the capturing subexpression
that captured the group;
value: the string value of the segment that was captured;
position: the one-based start position of the segment within the input string.
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
It is
The declarations and definitions in the schema are not automatically available in
the static context of the
The schema defines the outermost element, analyze-string-result, in such
a way that mixed content is permitted. In fact the element will only have element nodes (match
and non-match) as its children, never text nodes. Although this might have originally been an
oversight, defining the analyze-string-result 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.
The rules for .*
will typically produce two matches: one matching segment containing all the characters in the
input string, and a second zero-length matching seqment at the end position of the string.
In the following examples, the result document is shown in serialized form, with whitespace between the element nodes. This whitespace is not actually present in the result. | |
| Expression: |
|
|---|---|
| Result: | (with whitespace added for legibility) |
| Expression: | |
| Result: | (with whitespace added for legibility) |
| Expression: | |
| Result: | (with whitespace added for legibility) |
| Expression: | |
| Result: | (with whitespace added for legibility) |
| Expression: | |
| Result: | (with whitespace added for legibility) |
This section specifies functions that manipulate URI values, either as instances
of xs:anyURI or as strings.
| Function | Meaning |
|---|---|
fn:decode-from-uri | Decodes URI-escaped characters in a string. |
fn:encode-for-uri | Encodes reserved characters in a string that is intended to be used in the path segment of a URI. |
fn:escape-html-uri | Escapes a URI in the same way that HTML user agents handle attribute values expected to contain URIs. |
fn:iri-to-uri | Converts a string containing an IRI into a URI according to the rules of |
fn:resolve-uri | Resolves a relative IRI reference against an absolute IRI. |
Decodes URI-escaped characters in a string.
This function is
This function returns the original representation of a URI-escaped string.
If $value is the empty sequence, the function returns the zero-length
string.
Otherwise, the value is first converted to a sequence of octets. Each plus sign
(+) is replaced with the octet representing a space character
(x20), and any substring that matches the regular expression
%[a-fA-F0-9][a-fA-F0-9] is replaced with an octet for the two-digit
hexadecimal number that follows the percent sign. Characters that are not part of
such a substring are replaced with the octets of their UTF-8 encoding.
For example, "A%42+C" results in the octets x41,
x42, x20, x43, and "💡" yields
xF0, x9F, x92, and xA1.
If % is followed by up to two characters that are not hexadecimal digits,
these characters are replaced by octets xEF, xBF,
and xBD, that is, the UTF-8 encoding of the Unicode replacement character
("%", "%X", "%AX", and "%XA" are all
replaced with these octets. For the string "%1X!", the octets xEF,
xBF, xBD, and x21 are returned.
Next, the resulting octets are interpreted as UTF-8. For example,
x41, x42, x20, and x43
becomes "AB C", and xF0, x9F,
x92, and xA1 becomes "💡".
If an invalid UTF-8 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 UTF-8 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 UTF-8 sequence.
Similarly, a UTF-8 octet sequence that represents a codepoint that is not a
valid XML character is replaced with a Unicode replacement character.
For example, x00 becomes "�".
| Expression | Result |
|---|---|
decode-from-uri("http://example.com/") |
|
decode-from-uri("~b%C3%A9b%C3%A9?a=b+c") |
|
decode-from-uri("%00-%XX-%F0%9F%92%41-%F0%F0%9F%92%A1") |
|
Encodes reserved characters in a string that is intended to be used in the path segment of a URI.
This function is
If $value is the empty sequence, the function returns the zero-length
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 percent-encoded form as described in
Since
All characters are escaped except those identified as “unreserved” by A to Z,
the digits 0 to 9, HYPHEN-MINUS (-),
LOW LINE (_), FULL STOP (.), and TILDE (~).
This function escapes URI delimiters and therefore cannot be used indiscriminately to encode “invalid” characters in a path segment.
This function is invertible but not idempotent. This is because a string containing a
percent character will be modified by applying the function: for example
100% becomes 100%25, while 100%25 becomes
100%2525.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Escapes a URI in the same way that HTML user agents handle attribute values expected to contain URIs.
This function is
If $value is the empty sequence, the function returns the zero-length
string.
Otherwise, the function escapes all $value to be escaped is replaced by an escape sequence, which is
formed by encoding the character as a sequence of octets in UTF-8, 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 upper-case
letters A-F.
The behavior of this function corresponds to the recommended handling of non-ASCII
characters in URI attribute values as described in
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: |
Converts a string containing an IRI into a URI according to the rules of
This function is
If $value is the empty sequence, the function returns the zero-length
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 percent-encoded 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 percent-encoded. In addition, characters outside the range
Since this function does not escape the character % to a URI should manually escape %
by replacing it with %25.
| Expression: | |
|---|---|
| Result: | |
| Expression: |
|
| Result: |
|
Resolves a relative IRI reference against an absolute IRI.
This function is
The function is defined to operate on IRI references as defined in
The following rules apply in order:
If $href is the empty sequence, the function returns the empty
sequence.
If $href is an absolute IRI (as defined above), then it is returned
unchanged.
If the $base argument is the empty sequence, then:
If the $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
base-uri 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
implementation-defined 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
implementation-defined 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
This section specifies functions that parse strings as URIs, to identify their structure, and construct URI strings from their structured representation.
Some URI schemes are hierarchical and some are non-hierarchical.
Implementations must treat the following schemes as non-hierarchical:
jar, mailto, news, tag,
tel, and urn. Whether additional schemes
are known to be non-hierarchical
| Function | Meaning |
|---|---|
fn:parse-uri | Parses the URI provided and returns a map of its parts. |
fn:build-uri | Constructs a URI from the parts provided. |
Both functions use a structured representation of a URI as defined in the next section.
This record type represents the components of a URI.
| Name | Meaning |
|---|---|
|
The original URI. This element is returned by
|
|
The URI scheme (e.g., “https” or “file”).
|
|
The URI is an absolute URI.
|
|
Whether the URI is hierarchical or not.
|
|
The authority portion of the URI (e.g., “example.com:8080”).
|
| Any userinfo that was passed as part of the authority.
|
| The host passed as part of the authority (e.g., “example.com”).
|
| The port passed as part of the authority (e.g., “8080”).
|
| The path portion of the URI.
|
| Any query string.
|
| Any fragment identifier.
|
| Parsed and unescaped path segments.
|
| Parsed and unescaped query key-value pairs.
|
| The path of the URI, treated as a filepath.
|
The segmented forms of the path and query parameters provide convenient access to commonly used information.
The path, if there is one, is tokenized on “/” characters and
each segment is unescaped (as per the http://example.com/path/to/a%2fb.
The path portion has to be returned as /path/to/a%2fb because
decoding the %2f would change the nature of the path.
The unescaped form is easily accessible from path-segments:
Note that the presence or absence of a leading slash on the path will affect whether or not the sequence begins with a zero-length string.
The query parameters are decoded into a map. Consider the URI:
http://example.com/path?a=1&b=2%264&a=3.
The decoded form in the query-parameters is the following map:
Note that both keys and values are unescaped. If a key
is repeated in the query string, the map will contain a
sequence of values for that key, as seen for a
in this example.
Parses the URI provided and returns a map of its parts.
This function is
If $value is the empty sequence, the result is the empty sequence.
The function parses the $value provided,
returning a map containing its constituent parts: scheme,
authority components, path, etc.
In addition to parsing URIs as defined by
The following options are available:
| Key | Meaning |
|---|---|
| Indicates that deprecated URI
features should be returned
|
| Indicates that a port number that is the same as
the default port for a given scheme should be omitted.
|
| Indicates that an input URI that begins
with two or more leading slashes should be interprted
as a Windows Universal Naming Convention
Path. (Specifically: that it has the file: scheme.)
|
This function is described as a series of transformations
over the input string to identify the parts of a URI that are
present. Some portions of the URI are identified by matching
with a regular expression. This approach is designed to make
the description clear and unambiguous; it is not implementation
advice. Comparison of
Processing begins with a $value. If the \), replace them with forward
slashes (/).
Strip off the fragment identifier and any query:
If the ^(.*?)#(.*)$, the
If the ^(.*?)\?(.*)$,
the
Attempt to identify the scheme:
If the ^([a-zA-Z][A-Za-z0-9\+\-\.]+):(.*)$:
the
the
Otherwise, the
If the
If file:
If the ^/*([a-zA-Z][:|].*)$:
the file and
the / followed
by the first match group with the
second character changed to :, if necessary.
Otherwise, if true:
the file and
the
Finally, if neither of the preceding cases apply:
the
the
Now that the scheme, if there is one, has been identified, determine if the URI is hierarchical:
If the true if / and
false otherwise.
If the URI is not
Identify the remaining components according to the scheme and whether or not the URI is hierarchical.
If the scheme is file:
The
If ^/*(//[^/].*)$: then
If the ^//*[A-Za-z]:/ then
all but one leading slash is removed from
Otherwise, the
If the scheme is hierarchical:
If the ^//([^/]+)$, the
If the ^//([^/]*)(/.*)$, the
Otherwise,
the
If the scheme is not hierarchical:
The
If the ^(([^@]*)@)(.*)(:([^:]*))?$,
then the allow-deprecated-features option is true.
When parsing the example.com), an IPv4 address (e.g., 127.0.0.1),
an IPv6 (or IPvFuture) address (e.g., [::1]), or an error
if there is an open square bracket ([) not matched by a
close square bracket (]). In a properly
constructed RFC 3986 URI, the only place where square
brackets may occur is around the IPv6/IPvFuture IP address.
If the ^(([^@]*)@)?(\[[^\]]*\])(:([^:]*))?$,
then the
If the ^(([^@]*)@)?\[.*$
then
If the ^(([^@]*)@)?([^:]+)(:([^:]*))?$,
then the
the
This function does not attempt to decode the components of the
Similar care must be taken to match the port because an IPv6/IPvFuture address may contain a colon.
If the ^(([^@]*)@)?(\[[^\]]*\])(:([^:]*))?$,
then the
Otherwise, if the ^(([^@]*)@)?([^:]+)(:([^:]*))?$,
then the
Otherwise, the
If the omit-default-ports option is true, the port
is discarded and set to the empty sequence if the port number is the same
as the default port for the given scheme. Implementations http (80), https (443),
ftp (21), and ssh (22). Exactly which ports are
recognized
is
If the
A / (solidus) and applying
The
Consider /path%2Fsegment. An application may want to decode that,
using /path/segment in a database query, for example. At the same
time, an application may wish to modify the URI and then reconstruct it.
In the string form, decoding %2F to / is
not reversible. In the ("", "path/segment"). In this format, the
decoding is reversible: escape the non-syntactic delimiters before
reconstructing the path with the syntactic ones.
A consequence of constructing the /,
if the path begins with a
/, after the last
/, if the path ends with a
/, and between consecutive
/ characters. (If the path consists of a single /,
that / counts as /,
producing a segment list containing two empty strings.)
The
empty strings may seem unnecessary at first glance, but they assure
that the path can be reconstructed by joining the segments together
again without having to handle the presence or absence of a leading or
trailing / as special cases.
Applying
The & (ampersand). For each token, identify
the =), the
If the
A
Implementations may implement additional or different rules for URIs that
have a scheme or pattern that they recognize. An implementation might choose
to parse jar: URIs with special rules, for example, since they extend the
syntax in ways not defined by
A dynamic error is raised
Like
Unlike
In the examples that follow, keys with values that are null or the empty sequence
are elided for editorial clarity. String literals that include an ampersand character
are written as string templates (for example | |
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
This example uses the algorithm described above, not an algorithm that is
specifically aware of the | |
| Expression: | |
| Result: | |
This example demonstrates that parsing the URI treats non-URI characters in
lexical IRIs as “unreserved characters”. The rationale for this is given in the
description of | |
| Expression: | |
| Result: | |
This example demonstrates the use of | |
| Expression: | |
| Result: | |
This example demonstrates the use of | |
| Expression: | |
| Result: | |
Constructs a URI from the parts provided.
This function is
A URI is composed from a scheme, authority, path, query, and fragment.
The following options are available:
| Key | Meaning |
|---|---|
| Indicates that deprecated URI
features should be returned
|
| Indicates that a port number that is the same as
the default port for a given scheme should be omitted.
|
| Indicates that the URI represents
a Windows Universal Naming Convention
Path.
|
The components are derived from the contents of the
$parts map. To simplify the description below, a
value is considered to be present in the map if the relevant
field exists and is non-empty.
If the scheme key is present in the map,
the URI begins with the value of that key. A URI is considered to be
non-hierarchical if either the hierarchical key
is present in the $parts map with the value
false or if the scheme is known to be
non-hierarchical. (In other words, schemes are hierarchical by
default.)
If the scheme is
known to be non-hierarchical, it is delimited by a trailing
:.
Otherwise, if the scheme is file and the unc-path
option is true, the scheme is delimited by a trailing :////.
Otherwise, the scheme is delimited by
a trailing ://.
For simplicity of exposition, we take the
userinfo, host, and
port values from the map and imagine they are
stored in variables with the same name. If the key is not
present in the map, the value of the variable is set to the
empty sequence.
If $userinfo is non-empty and contains a
non-empty password, then $userinfo is set to the
empty sequence unless the
allow-deprecated-features option is true.
If the omit-default-ports option is true
then the $port is set to the empty sequence if
the port number is the same as the default port for the given
scheme. Implementations http (80),
https (443), ftp (21), and
ssh (22). Exactly which ports are recognized is
If any of $userinfo, $host, or $port
exist, the following authority is added to the URI under construction:
If none of userinfo, host, or port
is present, and authority is present, the value of the
authority key is added to the URI. (In this case, no attempt
is made to determine if a password or standard port are present,
the authority value is simply added to the string.)
The path-segments, query-parameters, and
fragment properties. That’s often the most
convenient behavior but, in order to reconstruct a URI from them,
special escaping rules apply. These rules protect delimiters
without encoding additional characters unnecessarily.
The rules for path-segments,
query-parameters, and fragment are
slightly different because the URI encoding conventions are
slightly different in each case.
An application with more stringent requirements can
construct a path or query that
satisfies the requirements and leave the
path-segments and/or
query-parameters keys out of the map.
If the path-segments key exists in
the map, then the path is constructed from the segments. To
construct the path, the possibly encoded segments are
concatentated together, separated by
The rules for encoding the path segments are different
for hierarchical and non-hierarchical URIs. If the URI is
non-hierarchical, no
encoding is performed on the segments. Otherwise,
each segment is encoded by replacing any control characters (codepoints less than 0x20)
and exclusively the following characters with their
percent-escaped forms: [#0-#20%/\?\#\+\[\]]”.
Encoding is performed unless the URI is known to be non-hierarchical;
in other words, encoding is the default. This heuristic improves the
reliability of using fn:build-uri() on the output of
fn:parse-uri(). (For example,
fn:parse-uri('a+b/c') => fn:build-uri() will return
a+b/c.)
It is necessary to avoid encoding non-hierarchical schemes because there is more
variation in them (for example, the tel: scheme
uses a “+” that must not be encoded). Users working with
non-hierarchical schemes may need to address the encoding issue directly
bearing in mind the encoding requirements of the particular schemes in use.
Otherwise the value of the path key is used.
If neither are present, a zero-length string is used for the path.
The path is added to the URI.
If the query-parameters key exists in the map, its value
must be a map. A sequence of strings is constructed from the values in the map.
To construct the string, each [#0-#20%=&\#\+\[\]]”.
(This differs from the path encoding in that it excludes
If the
Otherwise, the string constructed is the value of the
The query is constructed by joining the resulting
strings into a single string, separated by & (ampersand) characters.
If the query-parameters key does not exist in the map, but
the query key does, then the query is the value of the
query key.
If there is a query, it is added to the URI with
a preceding
If the fragment key exists in the map, then
the value of that key is encoded and added to the URI with a
preceding [#0-#20%\#\+\[\]]”.
(This differs from the path encoding in that it excludes
The resulting URI is returned.
| Expression: | |
|---|---|
| Result: |
Operators are defined on the following type:
xs:duration
and on the two defined subtypes (see
xs:yearMonthDuration
xs:dayTimeDuration
Arithmetic on durations is defined only on these subtypes: this is because the results of some operations (for example one month minus one day) have no representation in the value space.
Two xs:duration values may however be compared.
A value of type xs:duration is considered to comprise two parts:
The total number of months, represented as a signed integer.
The total number of seconds, represented as a signed decimal number.
If one of these values is negative (less than zero), the other must not be positive (greater than zero).
In effect this means that operations on durations (including equality comparison,
casting to string, and extraction of components)
all treat the duration as normalized. The duration PT1M30S (one minute and
thirty seconds), for example,
is precisely equivalent to the duration PT90S (ninety seconds); these are
different representations of the same value, and the result of any operation will be
the same regardless which representation is used. For example, the function
The information content of an xs:duration
value can be reduced to an xs:integer number of months, and an xs:decimal
number of seconds. For the two defined subtypes this is further simplified so that one of these two
components is fixed at zero. Operations such as comparison of durations and arithmetic on durations
can be expressed in terms of numeric operations applied to these two components.
Two subtypes of xs:duration, namely xs:yearMonthDuration
and xs:dayTimeDuration, are defined in
The significance of these subtypes is that arithmetic and ordering become well defined; this is not the
case for xs:duration values in general, because of the variable number of days in a month. For this reason, many of the functions
and operators on durations require the arguments/operands to belong to these two subtypes.
In an xs:yearMonthDuration, the seconds component is always zero.
In an xs:dayTimeDuration, the months component is always zero.
All conforming processors
The total number of months can be represented as a signed xs:int value;
The total number of seconds can be represented as a signed xs:decimal
value with facets totalDigits=18 and fractionalDigits=3. That is,
durations must be supported to millisecond precision.
Processors
A processor that limits the range or precision of duration values
may encounter overflow and underflow conditions when it
tries to evaluate operations on durations. In
these situations, the processor
Similarly, a processor may be unable accurately to represent the result of dividing a duration
by 2, or multiplying a duration by 0.5. A processor that limits the precision of the seconds component
of duration values
Duration values may be compared using the
In this version of the specification, all xs:duration values
are mutually comparable: comparison operations are no longer restricted
to the two subtypes xs:yearMonthDuration and xs:dayTimeDuration.
However, although a total ordering is defined over all durations, the result
is not always meaningful: while it makes sense that P1Y1D (one year and a day)
is greater than P1Y (one year), it makes little sense that P32D
(thirty-two days) is less than P1M (one month).
Durations are treated as tuples with two components, the months and seconds components, and they are compared by treating the months as the primary key and the seconds as the primary key.
The duration datatype may be considered to be a composite datatype
in that it contains distinct properties or components. The extraction functions specified
below extract a single component from a duration value.
For xs:duration and its subtypes, including the two subtypes xs:yearMonthDuration and
xs:dayTimeDuration, the components are normalized: this means that the seconds and minutes
components will always be less than 60, the hours component less than 24, and the months component less than 12.
| Function | Meaning |
|---|---|
fn:years-from-duration | Returns the number of years in a duration. |
fn:months-from-duration | Returns the number of months in a duration. |
fn:days-from-duration | Returns the number of days in a duration. |
fn:hours-from-duration | Returns the number of hours in a duration. |
fn:minutes-from-duration | Returns the number of minutes in a duration. |
fn:seconds-from-duration | Returns the number of seconds in a duration. |
Returns the number of years in a duration.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer representing the years
component in $value. Given that a duration
is a ($months, $seconds) tuple, the result is the value of ($months idiv 12).
If $value is a negative duration then the result will be negative.
If $value is an xs:dayTimeDuration the function
returns 0.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
|
Returns the number of months in a duration.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer representing the months
component in $value. Given that a duration
is a ($months, $seconds) tuple, the result is the value of ($months mod 12).
If $value is a negative duration then the result will be negative.
If $value is an xs:dayTimeDuration the function
returns 0.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
|
Returns the number of days in a duration.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer representing the days
component in $value. Given that a duration
is a ($months, $seconds) tuple, the result is ($seconds idiv 86400).
If $value is a negative duration then the result will be negative.
If $value is an xs:yearMonthDuration the function returns 0.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
|
Returns the number of hours in a duration.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer representing the hours
component in $value. ($months, $seconds) tuple, the result is the value of ($seconds mod 86400) idiv 3600
If $value is a negative duration then the result will be negative.
If $value is an xs:yearMonthDuration the function returns 0.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
|
Returns the number of minutes in a duration.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer representing the minutes
component in $value. Given that a duration
is a ($months, $seconds) tuple, the result is the value of ($seconds mod 3600) idiv 60.
If $value is a negative duration then the result will be negative.
If $value is an xs:yearMonthDuration the function returns 0.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
|
Returns the number of seconds in a duration.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:decimal representing the seconds
component in $value. Given that a duration
is a ($months, $seconds) tuple, the result is the value of ($seconds mod 60)
as an xs:decimal.
If $value is a negative duration then the result will be negative.
If $value is an xs:yearMonthDuration the function returns 0.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
|
| Expression: | |
| Result: |
|
This section decribes the xs:dayTimeDuration value representing a decimal number of seconds.
| Function | Meaning |
|---|---|
fn:seconds | Returns an xs:dayTimeDuration whose length is a given number of seconds. |
Returns an xs:dayTimeDuration whose length is a given number of seconds.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:dayTimeDuration value whose length
in seconds is equal to $value.
If $value is negative then the result will be a negative duration.
For handling of overflow and underflow, see
The result of seconds($n) is approximately equal to the result of
the expression xs:dayTimeDuration('PT1S') * $n. The equivalence is only
approximate, because seconds($n) uses the exact xs:decimal
value supplied, whereas multiplying a duration by a number first converts the number
to an xs:double value, which may lose precision.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
|
| Expression: | |
| Result: |
|
| Function | Meaning |
|---|---|
op:add-yearMonthDurations | Returns the result of adding two xs:yearMonthDuration values. |
op:subtract-yearMonthDurations | Returns the result of subtracting one xs:yearMonthDuration value from
another. |
op:multiply-yearMonthDuration | Returns the result of multiplying $arg1 by $arg2.
The result is rounded to the nearest month. |
op:divide-yearMonthDuration | Returns the result of dividing $arg1 by $arg2.
The result is rounded to the nearest month. |
op:divide-yearMonthDuration-by-yearMonthDuration | Returns the ratio of two xs:yearMonthDuration values. |
op:add-dayTimeDurations | Returns the sum of two xs:dayTimeDuration values. |
op:subtract-dayTimeDurations | Returns the result of subtracting one xs:dayTimeDuration from another. |
op:multiply-dayTimeDuration | Returns the result of multiplying a xs:dayTimeDuration by a number. |
op:divide-dayTimeDuration | Returns the result of multiplying a xs:dayTimeDuration by a number. |
op:divide-dayTimeDuration-by-dayTimeDuration | Returns the ratio of two xs:dayTimeDuration values, as a decimal
number. |
For operators that combine a duration and a date/time value, see
Returns the result of adding two xs:yearMonthDuration values.
Defines the semantics of the
+ operator when applied to two xs:yearMonthDuration values.
The function returns the result of adding $arg1 to $arg2.
The result will be an xs:yearMonthDuration whose
length in months is equal to the length in months of $arg1 plus the length
in months of $arg2.
For handling of overflow, see
Either duration (and therefore the result) may be negative.
| Expression: | |
|---|---|
| Result: |
Returns the result of subtracting one xs:yearMonthDuration value from
another.
Defines the semantics of the
- operator when applied to two xs:yearMonthDuration values.
The function returns the result of subtracting $arg2 from
$arg1. The result will be an xs:yearMonthDuration
whose length in months is equal to the length in months of $arg1 minus the
length in months of $arg2.
For handling of overflow, see
Either duration (and therefore the result) may be negative.
| Expression: | |
|---|---|
| Result: |
Returns the result of multiplying $arg1 by $arg2.
The result is rounded to the nearest month.
Defines the semantics of the
* operator when applied to an xs:yearMonthDuration and a numeric
value.
The result is the xs:yearMonthDuration whose length in months is equal to
the result of applying the $arg1 by the value of
$arg2.
If $arg2 is positive or negative zero, the result is a zero-length
duration. If $arg2 is positive or negative infinity, the result overflows
and is handled as described in
For handling of overflow, underflow, and rounding, see
A dynamic error is raised $arg2 is
NaN.
Either duration (and therefore the result) may be negative.
| Expression: | |
|---|---|
| Result: |
Returns the result of dividing $arg1 by $arg2.
The result is rounded to the nearest month.
Defines the semantics of the
div operator when applied to an xs:yearMonthDuration and a numeric
value.
The result is the xs:yearMonthDuration whose length in months is equal to
the result of applying the $arg1 by the value of
$arg2.
If $arg2 is positive or negative infinity, the result is a zero-length
duration. If $arg2 is positive or negative zero, the result overflows and
is handled as described in
For handling of overflow, underflow, and rounding,
see
A dynamic error is raised $arg2 is
NaN.
Either operand (and therefore the result) may be negative.
| Expression: | |
|---|---|
| Result: |
Returns the ratio of two xs:yearMonthDuration values.
Defines the semantics of the
div operator when applied to two xs:yearMonthDuration values.
The function returns the result of dividing the length in months of $arg1
by the length in months of $arg2, according to the rules of the
op:numeric-divide function for integer operands.
For handling of overflow, underflow, and rounding,
see
Either duration (and therefore the result) may be negative.
| Expression: | |
|---|---|
| Result: | |
The following example demonstrates how to calculate the length of an
| |
| Expression: | |
| Result: | |
Returns the sum of two xs:dayTimeDuration values.
Defines the semantics of the +
operator when applied to two xs:dayTimeDuration values.
The function returns the result of adding $arg1 to
$arg2. The result is the xs:dayTimeDuration whose length in
seconds is equal to the sum of the length in seconds of the two input durations.
For handling of overflow, see
Either duration (and therefore the result) may be negative.
| Expression: | |
|---|---|
| Result: |
Returns the result of subtracting one xs:dayTimeDuration from another.
Defines the semantics of the -
operator when applied to two xs:dayTimeDuration values.
The function returns the result of subtracting $arg2 from
$arg1. The result is the xs:dayTimeDuration whose
length in seconds is equal to the length in seconds of $arg1 minus the
length in seconds of $arg2.
For handling of overflow, see
Either duration (and therefore the result) may be negative.
| Expression: | |
|---|---|
| Result: |
Returns the result of multiplying a xs:dayTimeDuration by a number.
Defines the semantics of the *
operator when applied to an xs:dayTimeDuration and a numeric
value.
The function returns the result of multiplying $arg1 by
$arg2. The result is the xs:dayTimeDuration whose length in
seconds is equal to the length in seconds of $arg1 multiplied by the
numeric value $arg2.
If $arg2 is positive or negative zero, the result is a zero-length
duration. If $arg2 is positive or negative infinity, the result overflows
and is handled as described in
For handling of overflow, underflow, and rounding, see
A dynamic error is raised $arg2 is
NaN.
Either operand (and therefore the result) may be negative.
| Expression: | |
|---|---|
| Result: |
Returns the result of multiplying a xs:dayTimeDuration by a number.
Defines the semantics of the
div operator when applied to two xs:dayTimeDuration values.
The function returns the result of dividing $arg1 by
$arg2. The result is the xs:dayTimeDuration whose length in
seconds is equal to the length in seconds of $arg1 divided by the numeric
value $arg2.
If $arg2 is positive or negative infinity, the result is a zero-length
duration. If $arg2 is positive or negative zero, the result overflows and
is handled as described in
For handling of overflow, underflow, and rounding, see
A dynamic error is raised $arg2 is
NaN.
Either operand (and therefore the result) may be negative.
| Expression: | |
|---|---|
| Result: |
Returns the ratio of two xs:dayTimeDuration values, as a decimal
number.
Defines the semantics of the
div operator when applied to two xs:dayTimeDuration values.
The function returns the result of dividing $arg1 by
$arg2. The result is the xs:dayTimeDuration whose length in
seconds is equal to the length in seconds of $arg1 divided by the length in
seconds of $arg2. The calculation is performed by applying
op:numeric-divide to the two xs:decimal operands.
For handling of overflow, underflow, and rounding,
see
Either operand (and therefore the result) may be negative.
| Expression: | |
|---|---|
| Result: | |
This examples shows how to determine the number of seconds in a duration. | |
| Expression: | |
| Result: | |
This section defines operations on the
See
xs:dateTime, xs:date, xs:time, xs:gYearMonth,
xs:gYear, xs:gMonthDay, xs:gMonth, xs:gDay
are referred to collectively as the
This section describes operations on atomic items of these types.
Values of these types are modeled as comprising one or more of the seven components year, month, day, hour, minute, second, and timezone.
The only operations defined on
xs:gYearMonth, xs:gYear,
xs:gMonthDay, xs:gMonth, and xs:gDay values are
equality comparison, ordering, and component extraction.
For other types, further operations are provided, including
arithmetic, formatted display, and timezone
adjustment.
All conforming processors
s.sss). However, processors
All conforming processors
In XSD 1.0, dates can include a negative year, but cannot include the year zero.
In the 4.0 version of this specification, the value space includes values with year zero,
and casting from xs:string accepts year zero in the lexical representation.
If an XSD 1.0 processor is used to validate source documents containing dates with negative
years, then it is -0001 translates to year zero or year -1 in the value space.
A processor that limits the number of digits in date and time datatype
representations may encounter overflow and underflow conditions when it
tries to execute the functions in
Similarly, a processor that limits the precision of the seconds component
of date and time or duration values may need to deliver a rounded result for arithmetic operations.
Such a processor
As defined in xs:dateTime,
xs:date, xs:time, xs:gYearMonth, xs:gYear,
xs:gMonthDay, xs:gMonth, xs:gDay values,
referred to collectively as year, month, day, hours, minutes,
seconds and timezone. The first five components are
xs:integer values. The value of the seconds component is an xs:decimal
and the value of the timezone component is an xs:dayTimeDuration.
For all the primitive date/time datatypes, the timezone property is optional and may or may not
be present. Depending on the datatype, some of the remaining six properties must be present and
some must be
For xs:time, 00:00:00 and 24:00:00 are alternate lexical forms
for the same value, whose canonical representation is 00:00:00. For xs:dateTime,
a time component 24:00:00 translates to 00:00:00 of the following day.
An xs:dateTime with lexical
representation 1999-05-31T05:00:00
is represented in the datamodel by { 1999, 5, 31, 5, 0, 0.0, () }.
An xs:dateTime with lexical
representation 1999-05-31T13:20:00-05:00
is represented by { 1999, 5, 31, 13, 20, 0.0, xs:dayTimeDuration("-PT5H") }.
An xs:dateTime with lexical
representation 1999-12-31T24:00:00
is represented by { 2000, 1, 1, 0, 0, 0.0, () }.
An xs:date with lexical
representation 2005-02-28+8:00
is represented by { 2005, 2, 28, (), (), (), xs:dayTimeDuration("PT8H") }.
An xs:time with lexical
representation 24:00:00
is represented by { (), (), (), 0, 0, 0, () }.
This record type is used to represent the components of a value of type xs:dateTime,
xs:date, xs:time, xs:gYear, xs:gYearMonth,
xs:gMonth, xs:gMonthDay, or xs:gDay.
| Name | Meaning |
|---|---|
|
The value of the
|
|
The value of the
|
|
The value of the
|
|
The value of the
|
|
The value of the
|
|
The value of the
|
|
The timezone offset, if the value has a timezone. A valid value corresponds to an integral number of minutes between -840 and +840 inclusive.
|
Not every instance of the type fn:dateTime-record represents
a valid
{"month": 0} (the value is out of range)
{"month": 4, "day": 31} (April has only 30 days)
{"hours": 24, "minutes": 0, "seconds": 0} (midnight is
represented with hours=0)
{"year": 1900, "day": 1} (year and day,
with no month, is not a valid combination)
{"year": 1900, "timezone": xs:dayTimeDuration("PT24H") (timezones
must be an integral number of minutes between -840 and +840 inclusive)
It is possible to construct an instance of fn:dateTime-record that does
not satisfy these constraints, but it will be rejected if used as an argument to
| Function | Meaning |
|---|---|
fn:dateTime | Returns an xs:dateTime value created by combining an xs:date
and an xs:time. |
fn:build-dateTime | Constructs a |
fn:unix-dateTime | Returns a dateTime value for a Unix time. |
Returns an xs:dateTime value created by combining an xs:date
and an xs:time.
This function is
If either $date or $time is the empty sequence, the function
returns the empty sequence.
Otherwise, the function returns an xs:dateTime whose date component is
equal to $date and whose time component is equal to $time.
The timezone of the result is computed as follows:
If neither argument has a timezone, the result has no timezone.
If exactly one of the arguments has a timezone, or if both arguments have the same timezone, the result has this timezone.
A dynamic error is raised
| Expression | Result |
|---|---|
|
Constructs a
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns a $R such that
deep-equal( $significant(parts-of-dateTime($R)), $significant($value) ),
where $significant is the function map:filter(?, fn($K, $V){$K eq "timezone" or exists($V)}),
that is, a function that discards entries in a map whose value is the empty sequence, other than the entry
with key "timezone".
If all seven components are present (year, month, day, hours, minutes, seconds, and timezone)
then the result will be of type xs:dateTimeStamp.
The range of years supported is
A dynamic error is raised $value is not one of the sets:
year, month, day, hours, minutes, seconds, and optional timezone (delivering an xs:dateTime)
year, month, day, and optional timezone (delivering an xs:date)
year, and optional timezone (delivering an xs:gYear)
year, month, and optional timezone (delivering an xs:gYearMonth)
month, and optional timezone (delivering an xs:gMonth)
month, day, and optional timezone (delivering an xs:gMonthDay)
day, and optional timezone (delivering an xs:gDay)
hours, minutes, seconds, and optional timezone (delivering an xs:time)
A dynamic error is raised $value is outside the permitted range
(for example if the value of the minutes component is less than zero or
greater than 59, or if the timezone is outside the range -PT14H to PT14H),
or if the combination of fields is not a valid date/time (for example,
if month is 4 and day is 31).
Components that are present in $value but with an empty value are treated
as if they were absent.
The timezone, if present, must correspond to an integral number of minutes in the range -840 to +840.
Midnight must be expressed with the hours value set to zero, not 24.
The standard xs:double values, and the timezone may be
supplied as an xs:duration.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns a dateTime value for a Unix time.
This function is
The function returns a dateTime value in UTC timezone for the Unix time specified
by $value in milliseconds.
The Unix time is defined in
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 effect of the function is equivalent to the result of the following XPath expression.
By calling this convenience function, it can be ensured that the correct timezone is used for computing the Unix time.
Note that Unix time does not account for leap seconds. It assumes that every day has 86,400 seconds.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
Calculate the Unix time associated with a | |
Date and time values can be compared using the function
An xs:dateTime can be considered to consist of seven components:
year, month, day, hour, minute,
second and timezone. For xs:dateTime six components (year,
month, day, hour, minute and second) are required
and timezone is optional. For other date/time values, of the first six components, some are required
and others must be Timezone is always optional. For example, for xs:date,
the year, month and day components are required and hour,
minute and second components must be absent; for xs:time the hour,
minute and second components are required and year, month and
day are missing; for xs:gDay, day is required and year,
month, hour, minute and second are missing.
In explicitTimezone facet is available with values
optional, required, or prohibited to
enable the timezone to be defined as mandatory or disallowed.
Values of the date/time datatypes xs:time, xs:gMonthDay, xs:gMonth,
and xs:gDay, can be considered to represent a sequence of recurring time instants or time periods.
An xs:time occurs every day. An xs:gMonth occurs every year. Comparison operators
on these datatypes compare the starting instants of equivalent occurrences in the recurring series.
These xs:dateTime values are calculated as described below.
Comparison operators on xs:date, xs:gYearMonth and xs:gYear compare
their starting instants. These xs:dateTime values are calculated as described below.
The starting instant of an occurrence of a date/time value is an xs:dateTime
calculated by filling
in the missing components of the local value from a reference xs:dateTime. An example of a suitable
reference xs:dateTime is 1972-01-01T00:00:00. Then, for example, the starting
instant corresponding to the xs:date value 2009-03-12 is
2009-03-12T00:00:00; the starting instant corresponding to the xs:time value
13:30:02 is 1972-01-01T13:30:02; and the starting instant corresponding to the
gMonthDay value --02-29 is 1972-02-29T00:00:00 (which explains
why a leap year was chosen for the reference).
In the previous version of this specification, the reference date/time chosen was
1972-12-31T00:00:00. While this gives the same results, it produces a "starting instant" for
a gMonth or gMonthDay that bears no
relation to the ordinary meaning of the term, and it also required special handling of short months.
The original choice was made to allow for leap seconds; but since leap seconds are not recognized
in date/time arithmetic, this is not actually necessary.
If the xs:time value written as
24:00:00 is to be compared, filling in the missing components gives 1972-01-01T00:00:00,
because 24:00:00 is an alternative representation of 00:00:00 (the lexical value
"24:00:00" is
converted to the time components { 0, 0, 0 } before the missing components are filled
in). This has the consequence that when ordering xs:time values,
24:00:00 is
considered to be earlier than 23:59:59. However, when ordering
xs:dateTime
values, a time component of 24:00:00 is considered equivalent to 00:00:00 on the
following day.
Note that the reference xs:dateTime does not have a timezone. The timezone component
is never filled in from the reference xs:dateTime. In some cases, if the date/time value does not
have a timezone, the implicit timezone from the dynamic context is used as the timezone.
This specification uses the reference xs:dateTime 1972-01-01T00:00:00 in the description of the
comparison operators. Implementations may use other reference xs:dateTime values
as long as they yield the same results. The reference xs:dateTime used must meet the following
constraints: when it is used to supply components into xs:gMonthDay values, the year must allow
for February 29 and so must be a leap year; when it is used to supply missing components into xs:gDay
values, the month must allow for 31 days. Different reference xs:dateTime values may be used for
different operators.
The date and time datatypes may be considered to be composite datatypes in that they contain distinct properties or components. The extraction functions specified below extract a single component from a date or time value. In all cases the local value (that is, the original value as written, without any timezone adjustment) is used.
A time written as 24:00:00 is treated as 00:00:00 on the
following day.
| Function | Meaning |
|---|---|
fn:year-from-dateTime | Returns the year component of a |
fn:month-from-dateTime | Returns the month component of a |
fn:day-from-dateTime | Returns the day component of a |
fn:hours-from-dateTime | Returns the hours component of a |
fn:minutes-from-dateTime | Returns the minute component of a |
fn:seconds-from-dateTime | Returns the seconds component of a |
fn:timezone-from-dateTime | Returns the timezone component of a |
fn:year-from-date | Returns the year component of an xs:date. |
fn:month-from-date | Returns the month component of an xs:date. |
fn:day-from-date | Returns the day component of an xs:date. |
fn:timezone-from-date | Returns the timezone component of an xs:date. |
fn:hours-from-time | Returns the hours component of an xs:time. |
fn:minutes-from-time | Returns the minutes component of an xs:time. |
fn:seconds-from-time | Returns the seconds component of an xs:time. |
fn:timezone-from-time | Returns the timezone component of an xs:time. |
fn:parts-of-dateTime | Returns all the components of a |
xs:gYearMonth.Returns the year component of a
This function is
If $value is the empty sequence, or if the year component is absent,
the function returns the empty sequence.
Otherwise, the function returns an xs:integer representing the year
component in $value. The result may be negative.
The value space for xs:dateTime allows year zero. XSD 1.0, however, does not
allow year zero, so if a date earlier that 0001 CE was produced by validating
an XML document using an XSD 1.0 processor, the results may be unpredictable.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
xs:gYearMonth.Returns the month component of a
This function is
If $value is the empty sequence, or if it contains no month component,
the function returns the empty sequence.
Otherwise, the function returns an xs:integer between 1 and
12, both inclusive, representing the month component in
$value.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
xs:gMonthDay.Returns the day component of a
This function is
If $value is the empty sequence, or if it contains no day component,
the function returns the empty sequence.
Otherwise, the function returns an xs:integer between 1 and
31, both inclusive, representing the day component in the
local value of $value.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
xs:time.Returns the hours component of a
This function is
If $value is the empty sequence, or if it contains no hours
component, the function returns the empty sequence.
Otherwise, the function returns an xs:integer between 0 and
23, both inclusive, representing the hours component in $value.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
xs:time.Returns the minute component of a
This function is
If $value is the empty sequence, or if it contains no minutes
component, the function returns the empty sequence.
Otherwise, the function returns an xs:integer value between 0
and 59, both inclusive, representing the minute component in the local value of
$value.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns the seconds component of a
This function is
If $value is the empty sequence, or if it contains no seconds
component, 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 $value.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
xs:gYearMonth.Returns the timezone component of a
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns the timezone component of $value, if any. If
$value has a timezone component, then the result is an
xs:dayTimeDuration that indicates deviation from UTC; its value may
range from +14:00 to -14:00 hours, both inclusive. If $value has no timezone
component, the result is the empty sequence.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns the year component of an xs:date.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer representing the year in the
local value of $value. The value may be negative.
The value space for xs:date allows year zero. XSD 1.0, however, does not
allow year zero, so if a date earlier that 0001 CE was produced by validating
an XML document using an XSD 1.0 processor, the results may be unpredictable.
| Expression | Result |
|---|---|
Returns the month component of an xs:date.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer between
1 and 12, both
inclusive, representing the month component in the local value of $value.
| Expression | Result |
|---|---|
Returns the day component of an xs:date.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer between
1 and 31, both
inclusive, representing the day component in the localized value of
$value.
| Expression | Result |
|---|---|
Returns the timezone component of an xs:date.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns the timezone component of $value, if any. If
$value has a timezone component, then the result is an
xs:dayTimeDuration that indicates deviation from UTC; its value may
range from +14:00 to -14:00 hours, both inclusive. If $value has no timezone
component, the result is the empty sequence.
| Expression | Result |
|---|---|
Returns the hours component of an xs:time.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer between
0 and 23, both
inclusive, representing the value of the hours component in the local value of
$value.
| Expression | Result |
|---|---|
Assume that the dynamic context provides an implicit timezone value of
| |
hours-from-time(xs:time("11:23:00")) |
|
hours-from-time(xs:time("21:23:00")) |
|
hours-from-time(xs:time("01:23:00+05:00")) |
|
hours-from-time(xs:time("24:00:00")) |
|
Returns the minutes component of an xs:time.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer value between 0
and 59, both inclusive, representing the value of the minutes component
in the local value of $value.
| Expression | Result |
|---|---|
minutes-from-time(xs:time("13:00:00Z")) |
|
Returns the seconds component of an xs:time.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:decimal value greater than or equal
to zero and less than 60, representing the seconds and fractional seconds in the local
value of $value.
| Expression | Result |
|---|---|
seconds-from-time(xs:time("13:20:10.5")) |
|
Returns the timezone component of an xs:time.
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns the timezone component of $value, if any. If
$value has a timezone component, then the result is an
xs:dayTimeDuration that indicates deviation from UTC; its value may
range from +14:00 to -14:00 hours, both inclusive. If $value has no timezone
component, the result is the empty sequence.
| Expression | Result |
|---|---|
timezone-from-time(xs:time("13:20:00-05:00")) |
|
timezone-from-time(xs:time("13:20:00")) |
|
Returns all the components of a
This function is
If $value is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns a record whose fields are as follows. All entries will be present, even when the value is an empty sequence.
| Key | Value |
|---|---|
year | Generally, the value of fn:year-from-dateTime($value): but
see the notes below regarding negative years. |
month | The value of fn:month-from-dateTime($value) |
day | The value of fn:day-from-dateTime($value) |
hours | The value of fn:hours-from-dateTime($value) |
minutes | The value of fn:minutes-from-dateTime($value) |
seconds | The value of fn:seconds-from-dateTime($value) |
timezone | The value of fn:timezone-from-dateTime($value) |
The range of years supported is
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
| Function | Meaning |
|---|---|
fn:adjust-dateTime-to-timezone | Adjusts an xs:dateTime value to a specific timezone, or to no timezone at
all. |
fn:adjust-date-to-timezone | Adjusts an xs:date value to a specific timezone, or to no timezone at all;
the result is the date in the target timezone that contains the starting instant of the
supplied date. |
fn:adjust-time-to-timezone | Adjusts an xs:time value to a specific timezone, or to no timezone at
all. |
fn:civil-timezone | Returns the timezone offset from UTC that is in conventional use at a given place and time. |
These functions adjust the timezone component of an xs:dateTime, xs:date or
xs:time value. The $timezone argument to these functions is defined as an
xs:dayTimeDuration but must be a valid timezone value.
Adjusts an xs:dateTime value to a specific timezone, or to no timezone at
all.
The one-argument form of this function is
The two-argument form of this function is
If $value is the empty sequence, then the function returns the empty
sequence.
If $value does not have a timezone component and $timezone is
the empty sequence, then the result is $value.
If $value does not have a timezone component and $timezone is
not the empty sequence, then the result is $value with $timezone
as the timezone component.
If $value has a timezone component and $timezone is the empty
sequence, then the result is the local value of $value without its timezone
component.
If $value has a timezone component and $timezone is not the
empty sequence, then the result is the xs:dateTime value that is equal to
$value and that has a timezone component equal to
$timezone.
A dynamic error is raised $timezone
is less than -PT14H or greater than PT14H or is not an
integral number of minutes.
| Variables | |
|---|---|
Assume the dynamic context provides an implicit timezone of | |
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
Adjusts an xs:date value to a specific timezone, or to no timezone at all;
the result is the date in the target timezone that contains the starting instant of the
supplied date.
The one-argument form of this function is
The two-argument form of this function is
If $value is the empty sequence, then the function returns the empty
sequence.
If $value does not have a timezone component and $timezone is
the empty sequence, then the result is $value.
If $value does not have a timezone component and $timezone is
not the empty sequence, then the result is $value with $timezone
as the timezone component.
If $value has a timezone component and $timezone is the empty
sequence, then the result is the local value of $value without its timezone
component.
If $value has a timezone component and $timezone is not the
empty sequence, then:
Let $dt be the value of fn:dateTime($arg,
xs:time('00:00:00')).
Let $adt be the value of fn:adjust-dateTime-to-timezone($dt,
$timezone)
The function returns the value of xs:date($adt)
A dynamic error is raised $timezone
is less than -PT14H or greater than PT14H or is not an
integral number of minutes.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
Assume the dynamic context provides an implicit timezone of | |
| |
| |
Adjusts an xs:time value to a specific timezone, or to no timezone at
all.
The one-argument form of this function is
The two-argument form of this function is
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('1972-12-31'), $value).
Let $adt be the value of fn:adjust-dateTime-to-timezone($dt,
$timezone)
The function returns the xs:time value
xs:time($adt).
A dynamic error is raised $timezone
is less than -PT14H or greater than PT14H or if does not
contain an integral number of minutes.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
Assume the dynamic context provides an implicit timezone of | |
Returns the timezone offset from UTC that is in conventional use at a given place and time.
The one-argument form of this function is
The two-argument form of this function is
This function uses a database of civil timezones (including daylight savings time) to return
the timezone offset for a given date/time and place. For example, the timezone offset for New York
on 31 December 2024 would be -PT5H.
If the $place argument is empty then the
If the supplied $value has no timezone then the implicit timezone from the dynamic
context is used. This is unrelated to the timezone applicable to the requested $place.
The intended use of the $place argument is to identify
the place where an event
represented by the $value argument took place or will take place.
The value must be an IANA timezone name as defined in the IANA timezone database "America/New_York" and "Europe/Rome".
The result of the function is the civil timezone offset applicable to the given date/time and place, as determined by the IANA timezone database or an alternative authoritative source.
A dynamic error is raised
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | The current civil date and time in New York. |
| Expression: |
|
| Result: | If the default place is a location in the same timezone
as (say) Paris, then |
These functions support adding or subtracting a duration value to or from an
xs:dateTime, an xs:date or an xs:time
value. Appendix E of
| Function | Meaning |
|---|---|
op:subtract-dateTimes | Returns an xs:dayTimeDuration representing the amount of elapsed time
between the instants arg2 and arg1. |
op:subtract-dates | Returns the xs:dayTimeDuration that corresponds to the elapsed time between
the starting instant of $arg2 and the starting instant of
$arg2. |
op:subtract-times | Returns the xs:dayTimeDuration that corresponds to the elapsed time between
the values of $arg2 and $arg1 treated as times on the same
date. |
op:add-yearMonthDuration-to-dateTime | Returns the xs:dateTime that is a given duration after a specified
xs:dateTime (or before, if the duration is negative). |
op:add-dayTimeDuration-to-dateTime | Returns the xs:dateTime that is a given duration after a specified
xs:dateTime (or before, if the duration is negative). |
op:subtract-yearMonthDuration-from-dateTime | Returns the xs:dateTime that is a given duration before a specified
xs:dateTime (or after, if the duration is negative). |
op:subtract-dayTimeDuration-from-dateTime | Returns the xs:dateTime that is a given duration before a specified
xs:dateTime (or after, if the duration is negative). |
op:add-yearMonthDuration-to-date | Returns the xs:date that is a given duration after a specified
xs:date (or before, if the duration is negative). |
op:add-dayTimeDuration-to-date | Returns the xs:date that is a given duration after a specified
xs:date (or before, if the duration is negative). |
op:subtract-yearMonthDuration-from-date | Returns the xs:date that is a given duration before a specified
xs:date (or after, if the duration is negative). |
op:subtract-dayTimeDuration-from-date | Returns the xs:date that is a given duration before a specified
xs:date (or after, if the duration is negative). |
op:add-dayTimeDuration-to-time | Returns the xs:time value that is a given duration after a specified
xs:time (or before, if the duration is negative or causes wrap-around
past midnight) |
op:subtract-dayTimeDuration-from-time | Returns the xs:time value that is a given duration before a specified
xs:time (or after, if the duration is negative or causes wrap-around
past midnight) |
A processor that limits the number of digits in date and time datatype
representations may encounter overflow and underflow conditions when it
tries to execute the functions in this section. In
these situations, the processor
The value spaces of the two totally ordered subtypes of
xs:duration described in xs:integer months for xs:yearMonthDuration
and xs:decimal seconds for xs:dayTimeDuration. If
a processor limits the number of digits allowed in the representation of
xs:integer and xs:decimal then overflow and
underflow situations can arise when it tries to execute the functions in
Returns an xs:dayTimeDuration representing the amount of elapsed time
between the instants arg2 and arg1.
Defines the semantics of the -
operator when applied to two xs:dateTime values.
This function is
If either $arg1 or $arg2 do not contain an explicit timezone
then, for the purpose of the operation, the implicit timezone provided by the dynamic
context (See
The function returns the elapsed time between the date/time instant arg2
and the date/time instant arg1, computed according to the algorithm given
in Appendix E of xs:dayTimeDuration.
If the normalized value of $arg1 precedes in time the normalized value of
$arg2, then the returned value is a negative duration.
Assume that the dynamic context provides an implicit timezone value of
| |
| Expression: | |
|---|---|
| Result: | |
Returns the xs:dayTimeDuration that corresponds to the elapsed time between
the starting instant of $arg2 and the starting instant of
$arg2.
Defines the semantics of the - operator
when applied to two xs:date values.
This function is
If either $arg1 or $arg2 do not contain an explicit timezone
then, for the purpose of the operation, the implicit timezone provided by the dynamic
context (See
The starting instant of an xs:date is the xs:dateTime at
00:00:00 on that date.
The function returns the result of subtracting the two starting instants using
op:subtract-dateTimes.
If the starting instant of $arg1 precedes in time the starting instant of
$arg2, then the returned value is a negative duration.
| Expression | Result |
|---|---|
Assume that the dynamic context provides an implicit timezone value of
| |
| |
Now assume that the dynamic context provides an implicit timezone value of
| |
| |
Returns the xs:dayTimeDuration that corresponds to the elapsed time between
the values of $arg2 and $arg1 treated as times on the same
date.
Defines the semantics of the - operator
when applied to two xs:time values.
This function is
The function returns the result of the expression:
Any other reference date would work equally well.
| Expression | Result |
|---|---|
Assume that the dynamic context provides an implicit timezone value of
| |
| |
| |
| |
| |
Returns the xs:dateTime that is a given duration after a specified
xs:dateTime (or before, if the duration is negative).
Defines the
semantics of the + operator when applied to an xs:dateTime and an
xs:yearMonthDuration value.
This function is
The function returns the result of adding $arg2 to the value of
$arg1 using the algorithm described in Appendix E of $arg2
is negative, then the result xs:dateTime precedes $arg1.
The result has the same timezone as $arg1. If $arg1 has no
timezone, the result has no timezone.
| Expression: | |
|---|---|
| Result: |
Returns the xs:dateTime that is a given duration after a specified
xs:dateTime (or before, if the duration is negative).
Defines the semantics
of the + operator when applied to an xs:dateTime and an
xs:dayTimeDuration value.
This function is
The function returns the result of adding $arg2 to the value of
$arg1 using the algorithm described in Appendix E of $arg2
is negative, then the result xs:dateTime precedes $arg1.
The result has the same timezone as $arg1. If $arg1 has no
timezone, the result has no timezone.
| Expression: | |
|---|---|
| Result: |
Returns the xs:dateTime that is a given duration before a specified
xs:dateTime (or after, if the duration is negative).
Defines the
semantics of the - operator when applied to an xs:dateTime and an
xs:yearMonthDuration value.
This function is
The function returns the xs:dateTime computed by negating
$arg2 and adding the result to $arg1 using the
function op:add-yearMonthDuration-to-dateTime.
| Expression: | |
|---|---|
| Result: |
Returns the xs:dateTime that is a given duration before a specified
xs:dateTime (or after, if the duration is negative).
Defines the semantics
of the - operator when applied to an xs:dateTime an and
xs:dayTimeDuration values
The function returns the xs:dateTime computed by negating
$arg2 and adding the result to $arg1 using the
function op:add-dayTimeDuration-to-dateTime.
| Expression: | |
|---|---|
| Result: |
Returns the xs:date that is a given duration after a specified
xs:date (or before, if the duration is negative).
Defines the semantics
of the + operator when applied to an xs:date and an
xs:yearMonthDuration value.
This function is
The function returns the result of casting $arg1 to an
xs:dateTime, adding $arg2 using the function
op:add-yearMonthDuration-to-dateTime, and casting the result back to an
xs:date.
| Expression: | |
|---|---|
| Result: |
Returns the xs:date that is a given duration after a specified
xs:date (or before, if the duration is negative).
Defines the semantics of
the + operator when applied to an xs:date and an
xs:dayTimeDuration value.
This function is
The function returns the result of casting $arg1 to an
xs:dateTime, adding $arg2 using the function
op:add-dayTimeDuration-to-dateTime, and casting the result back to an
xs:date.
| Expression: | |
|---|---|
| Result: |
|
Returns the xs:date that is a given duration before a specified
xs:date (or after, if the duration is negative).
Defines the semantics
of the - operator when applied to an xs:date and an
xs:yearMonthDuration value.
This function is
Returns the xs:date computed by negating $arg2 and adding the
result to $arg1 using the function
op:add-yearMonthDuration-to-date.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns the xs:date that is a given duration before a specified
xs:date (or after, if the duration is negative).
Defines the semantics of
the - operator when applied to an xs:date and an
xs:dayTimeDuration.
This function is
Returns the xs:date computed by negating $arg2 and adding the
result to $arg1 using the function
op:add-dayTimeDuration-to-date.
| Expression: | |
|---|---|
| Result: |
Returns the xs:time value that is a given duration after a specified
xs:time (or before, if the duration is negative or causes wrap-around
past midnight)
Defines the semantics of
the + operator when applied to an xs:time and an
xs:dayTimeDuration value.
First, the days component in the canonical lexical representation of $arg2
is set to zero (0) and the value of the resulting xs:dayTimeDuration is
calculated. Alternatively, the value of $arg2 modulus 86,400 is used as the
second argument. This value is added to the value of $arg1 converted to an
xs:dateTime using a reference date such as 1972-12-31, and
the time component of the result is returned. Note that the xs:time
returned may occur in a following or preceding day and may be less than
$arg1.
The result has the same timezone as $arg1. If $arg1 has no
timezone, the result has no timezone.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: |
|
Returns the xs:time value that is a given duration before a specified
xs:time (or after, if the duration is negative or causes wrap-around
past midnight)
Defines the semantics of
the - operator when applied to an xs:time and an
xs:dayTimeDuration value.
This function is
The function returns the result of negating $arg2 and adding the result to
$arg1 using the function op:add-dayTimeDuration-to-time.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: |
| Function | Meaning |
|---|---|
fn:format-dateTime | Returns a string containing an xs:dateTime value formatted for display. |
fn:format-date | Returns a string containing an xs:date value formatted for display. |
fn:format-time | Returns a string containing an xs:time value formatted for display. |
Three functions are provided to represent dates and times as a string, using the conventions of a selected calendar,
language, and country. The functions are presented in their customary fashion,
except for the rules and examples, which are described en bloc at
Returns a string containing an xs:dateTime value formatted for display.
This function is
See
Returns a string containing an xs:date value formatted for display.
This function is
See
Returns a string containing an xs:time value formatted for display.
This function is
See
The $value as a string using
the picture string specified by the $picture argument,
the calendar specified by the $calendar argument,
the language specified by the $language argument,
and the country or other place name specified by the $place argument.
The result of the function is the formatted string representation of the supplied
xs:dateTime, xs:date, or xs:time value.
If $value is the empty sequence, the function returns the empty sequence.
Calling the two-argument form of each of the three functions is equivalent to calling the five-argument form with each of the last three arguments set to the empty sequence.
For details of the $language, $calendar, and
$place arguments, see
In general, the use of an invalid $picture,
$language, $calendar, or
$place argument results in a dynamic error
The picture consists of a sequence of variable markers and literal substrings.
A substring enclosed in square brackets is interpreted as a variable marker; substrings
not enclosed in square brackets are taken as literal substrings.
The literal substrings are optional and if present are rendered unchanged, including any whitespace.
If an opening or closing square bracket
is required within a literal substring, it
A variable marker consists of a component specifier followed optionally by one or two presentation modifiers and/or optionally by a width modifier. Whitespace within a variable marker is ignored.
The variable marker may be separated into its components by applying the following rules:
The component specifier is always present and is always a single letter.
The width modifier may be recognized by the presence of a comma.
The substring between the component specifier and the comma (if present) or the end of the string (if there is no comma) contains the first and second presentation modifiers, both of which are optional. If this substring contains a single character, this is interpreted as the first presentation modifier. If it contains more than one character, the last character is examined: if it is valid as a second presentation modifier then it is treated as such, and the preceding part of the substring constitutes the first presentation modifier. Otherwise, the second presentation modifier is presumed absent and the whole substring is interpreted as the first presentation modifier.
The
| Specifier | Meaning | Default Presentation Modifier |
|---|---|---|
| Y | year (absolute value) | 1 |
| M | month in year | 1 |
| D | day in month | 1 |
| d | day in year | 1 |
| F | day of week | n |
| W | week in year | 1 |
| w | week in month | 1 |
| H | hour in day (24 hours) | 1 |
| h | hour in half-day (12 hours) | 1 |
| P | am/pm marker | n |
| m | minute in hour | 01 |
| s | second in minute | 01 |
| f | fractional seconds | 1 |
| Z | timezone | 01:01 |
| z | timezone (Same as Z, but modified where appropriate to include a prefix
as a time offset using GMT, for example GMT+1 or GMT-05:00. For this component there is a fixed
prefix of GMT, or a localized
variation thereof for the chosen language, and the remainder of the value is formatted as for specifier Z.)
| 01:01 |
| C | calendar: the name or abbreviation of a calendar name | n |
| E | era: the name of a baseline for the numbering of years, for example the reign of a monarch | n |
A dynamic error is reported
A dynamic error is reported $value,
for example if the picture supplied to the
It is not an error to include a timezone component when the supplied value has no timezone. In these circumstances the timezone component will be ignored.
The first
any format token permitted as a primary format token in the second argument
of the 1, 01, i, I, w, W,
or Ww) or
the format token n, N,
or Nn, indicating that the value of the component is to be output by name,
in lower-case, upper-case, or title-case respectively. Components that can be output by name
include (but are not limited to) months, days of the week, timezones, and eras.
If the processor cannot output these components by name for the chosen calendar and language
then it must use an
If a comma is to be used as a grouping separator within the format token, then there must be a width
specifier. More specifically: if a variable marker
contains one or more commas, then the last comma is treated as introducing the width modifier, and all others
are treated as grouping separators. So [Y9,999,*] will output the year as 2,008.
It is not possible to use a closing square bracket as a grouping separator within the format token.
If the implementation does not support the use of the requested format token, it
If the first presentation modifier is present, then it may optionally be followed by a second presentation modifier as follows:
| Modifier | Meaning |
|---|---|
either a or t | indicates alphabetic or traditional numbering respectively,
the default being |
either c or o | indicates cardinal or ordinal numbering respectively, for example
7 or seven for a cardinal number, or 7th,
seventh, or 7º
for an ordinal number.
This has the same meaning as
in the second argument of |
Although the formatting rules are expressed in terms of the rules
for format tokens in primo) for the first day of the month, and cardinal numbers
(due, tre, quattro ...) for the remaining days. A processor may therefore use
this convention to number days of the month, ignoring the presence or absence of the ordinal
presentation modifier.
Whether or not a presentation modifier is included, a width modifier may be supplied. This indicates the number of characters to be included in the representation of the value.
The width modifier, if present, is introduced by a comma. It takes the form:
"," min-width ("-" max-width)?
where min-width is either an unsigned integer indicating the minimum number of characters to
be output, or * indicating that there is no explicit minimum, and
max-width is either an unsigned integer indicating the maximum number of characters to
be output, or * indicating that there is no explicit maximum; if max-width
is omitted then * is assumed.
A dynamic error (min-width is present and less than one, or if
max-width is present and less than one or less than min-width.
A format token containing more than one digit, such as 001 or 9999, sets the
minimum and maximum width to the number of digits appearing in the format token; if a width
modifier is also present, then the width modifier takes precedence.
The rules in this section apply to the majority of integer-valued components: specifically M D d F W w H h m s.
In the rules below, the term
If the first presentation modifier takes the form of a
If there is no width modifier, then the value is formatted according to
the rules of the format-integer function.
If there is a width modifier, then the first presentation modifier is adjusted as follows:
If the decimal digit pattern includes a grouping separator, the output is implementation-defined (but this is not an error).
Use of a width modifier together with grouping separators is inadvisable for this reason. It is never necessary to use a width modifier with a decimal digit pattern, since the same effect can be achieved by use of optional digit signs.
Otherwise, the number of mandatory-digit-sign characters in the presentation modifier is increased if necessary. This is done first by replacing optional-digit-signs with mandatory-digit-signs, starting from the right, and then prepending mandatory-digit-signs to the presentation modifier, until the number of mandatory-digit-signs is equal to the minimum width. Any mandatory-digit-signs that are added by this process must use the same decimal digit family as existing mandatory-digit-signs in the presentation modifier if there are any, or ASCII digits otherwise.
The maximum width, if specified, is ignored.
The output is then as defined using the format-integer function with this adjusted decimal digit pattern.
If the first presentation modifiers is one of N, n, or Nn:
Let FN be the full name of the component, that is, the form of the name that would be used in the absence of any width modifier.
If FN is shorter than the minimum width, then it is padded by appending spaces to the end of the name.
If FN is longer than the maximum width, then it is abbreviated, either by choosing a conventional abbreviation that fits within the maximum width (for example, “Wednesday” might be abbreviated to “Weds”), or by removing characters from the end of FN until it fits within the maximum width.
For other presentation modifiers:
Any adjustment of the value to fit within the requested width range is implementation-defined.
The value should not be truncated if this results in output that will not be meaningful to users (for example, there is no sensible way to truncate Roman numerals).
If shorter than the minimum width, the value should be padded to the minimum width, either by appending spaces, or in some other way appropriate to the numbering scheme.
The rules for the year component (Y) are the same as those in
If the width modifier is present and defines a finite maximum width, then that maximum width.
Otherwise, if the first presentation modifier takes the form of a decimal-digit-pattern, then:
Let W be the number of optional-digit-signs and mandatory-digit-signs in that decimal-digit-pattern.
If W is 2 or more, then W.
Otherwise, N is infinity (that is, the year is output in full).
The output for the fractional seconds component (f) is equivalent to the result of the following algorithm:
If the first presentation modifier contains no Unicode digit, then the output is implementation-defined.
Otherwise, the value of the fractional seconds is output as follows:
If there is no width modifier and the first presentation modifier comprises in its
entirety a single mandatory-digit-sign (for example the default 1), then
the presentation modifier is extended on the right with as many optional-digit-signs as
are needed to accommodate the actual fractional seconds precision encountered in the
value to be formatted.
If there is a width modifier, then the first presentation modifier is adjusted as follows:
If a minimum width is specified, and if this exceeds the number of mandatory-digit-sign characters in the first presentation modifier, then the first presentation modifier is adjusted. This is done first by replacing optional-digit-signs with mandatory-digit-signs, starting from the left, and then appending mandatory-digit-signs to the presentation modifier, until the number of mandatory-digit-signs is equal to the minimum width. Any mandatory-digit-signs that are added by this process must use the same decimal digit family as existing mandatory-digit-signs in the presentation modifier.
If a maximum width is specified, the first presentation modifier is extended on the right with as many optional-digit-signs as are needed to ensure that the number of mandatory-digit-signs and optional-digit-signs is at least equal to the maximum width.
The sequence of characters in the (adjusted) first presentation modifier is reversed (for example,
999'### becomes ###'999).
If the result is not a valid
The sequence of digits in the conventional decimal representation of the fractional seconds component
is reversed, with insignificant zeroes removed, and the result is treated as an integer. For example, if the
seconds value is 25.8235, the reversed fractional seconds value is 5328.
The reversed fractional seconds value is formatted using the reversed decimal digit pattern according to the
rules of the 5'328
The resulting string is reversed. In our example, the result is 823'5.
If the result contains more digits than the number of mandatory-digit-signs and optional-digit-signs in the decimal digit pattern, then excess digits are removed from the right hand end (that is, the value is truncated towards zero rather than being rounded). Any grouping separator that immediately precedes a removed digit is also removed.
The reason for presenting the algorithm in this way is that it enables maximum reuse of the rules defined for
A format token consisting of a single digit,
such as 1, does not constrain the number of digits in the output.
In the case of fractional seconds in particular, [f001] requests three decimal digits,
[f01] requests two digits, but [f1] will retain all digits in the
supplied date/time value (the maximum number of digits is implementation-defined).
If exactly one digit is required, this can be achieved using the component specifier
[f1,1-1].
Special rules apply to the formatting of timezones. When the component specifiers Z
or z are used, the rules in this section override any rules given elsewhere in the case of
discrepancies.
If the date/time value to be formatted does not include a timezone offset, then the timezone component
specifier is generally ignored (results in no output). The exception is where military timezones are used
(format ZZ) in which case the string "J" is output, indicating local time.
When the component specifier is z, the output is the same as for component specifier
Z, except that it is prefixed by the characters GMT or some localized
equivalent. The prefix is omitted, however, in cases where the timezone is identified by name rather than by
a numeric offset from UTC.
If the first presentation modifier is numeric and comprises one or two digits
with no grouping-separator (for example 1
or 01), then the timezone is formatted as a displacement from UTC in hours, preceded by a plus or minus
sign: for example -5 or +03. If the actual timezone offset is not an integral number of hours,
then the minutes part of the offset is appended, separated by a colon: for example +10:30 or
-1:15.
If the first presentation modifier is numeric with a grouping-separator (for example 1:01
or 01.01), then the timezone offset is output in hours and minutes, separated by the grouping separator,
even if the number of minutes is zero: for example +5:00 or +10.30.
If the first presentation modifier is numeric and comprises three or four digits with no
grouping-separator, for example 001 or 0001, then the timezone offset
is shown in hours and minutes with no separator, for example -0500 or +1030.
If the first presentation modifier is numeric, in any of the above formats, and the second
presentation modifier is t, then a zero timezone offset (that is, UTC) is output as Z instead
of a signed numeric value. In this presentation modifier is absent or if the timezone offset is non-zero,
then the displayed timezone offset is preceded by a - sign for negative offsets
or a + sign for non-negative offsets.
If the first presentation modifier is Z, then the timezone is formatted
as a military timezone letter, using the convention Z = +00:00, A = +01:00, B = +02:00, ..., M = +12:00,
N = -01:00, O = -02:00, ... Y = -12:00. The letter J (meaning local time) is used in the case of a
value that does not specify a timezone offset. Timezone offsets that have no representation in this system
(for example Indian Standard Time, +05:30) are output as if the format 01:01 had been requested.
If the first presentation modifier is N, then the timezone is output
(where possible) as a timezone name, for example EST or CET. The same timezone
offset has different names in different places; it is therefore $place argument.
In the absence of this information, the implementation may apply a default, for example by using the timezone
names that are conventional in North America. If no timezone name can be identified, the timezone offset is
output using the fallback format 01:01
The following examples illustrate options for timezone formatting.
| Variable marker | $place | Timezone offsets (with time = 12:00:00) | ||||
|---|---|---|---|---|---|---|
| -10:00 | -05:00 | +00:00 | +05:30 | +13:00 | ||
| [Z] | () | -10:00 | -05:00 | +00:00 | +05:30 | +13:00 |
| [Z0] | () | -10 | -5 | +0 | +5:30 | +13 |
| [Z0:00] | () | -10:00 | -5:00 | +0:00 | +5:30 | +13:00 |
| [Z00:00] | () | -10:00 | -05:00 | +00:00 | +05:30 | +13:00 |
| [Z0000] | () | -1000 | -0500 | +0000 | +0530 | +1300 |
| [Z00:00t] | () | -10:00 | -05:00 | Z | +05:30 | +13:00 |
| [z] | () | GMT‑10:00 | GMT‑05:00 | GMT+00:00 | GMT+05:30 | GMT+13:00 |
| [ZZ] | () | W | R | Z | +05:30 | +13:00 |
| [ZN] | "us" | HST | EST | GMT | IST | +13:00 |
| [H00]:[M00] [ZN] | "America/New_York" | 06:00 EST | 12:00 EST | 07:00 EST | 01:30 EST | 18:00 EST |
If a width specifier is present when formatting a timezone, then the representation as defined in this section is padded to the minimum
width as described in
This section applies to the remaining components: P (am/pm marker), C (calendar),
and E (era).
The output for these components is entirely n, indicating that they are output as names (or
conventional abbreviations), and the chosen names will in many cases depend on the chosen language: see
The set of languages, calendars, and places that are supported in the
If the fallback representation uses a different calendar from that requested,
the output string [Calendar: X] (where X is the calendar actually used),
localized as appropriate to the
requested language. If the fallback representation uses a different language
from that requested, the output string [Language: Y] (where Y is the language
actually used) localized in an
implementation-dependent way. If a particular component of the value cannot be output in
the requested format, it
The $language argument specifies the language to be used for the result string
of the function. The value of the argument xml:lang attribute (see
If the $language
argument is omitted or is set to the empty sequence, or if it is set to an invalid value or a
value that the implementation does not recognize,
then the processor uses the default language defined in the dynamic context.
The language is used to select the appropriate language-dependent forms of:
names (for example, of months)
numbers expressed as words or as ordinals (twenty, 20th, twentieth)
hour convention (0-23 vs 1-24, 0-11 vs 1-12)
first day of week, first week of year
Where appropriate this choice may also take into account the value of the
$place argument, though this language
argument.
The choice of the names and abbreviations used in any given language is
Jul while another uses Jly. In German,
one implementation might represent Saturday as Samstag while another
uses Sonnabend. Implementations
Where ordinal numbers are used, the selection of the correct representation of the
ordinal (for example, the grammatical gender)
The calendar attribute specifies that the dateTime, date,
or time supplied in the $value argument
The calendar value if present EQName
(dynamic error: QName then it is expanded into an expanded QName
using the statically known namespaces; if it has no prefix then it represents an expanded-QName in no namespace.
If the expanded QName is in no namespace,
then it
If the $calendar argument is omitted or is set to the empty sequence
then the default calendar defined in the dynamic context is used.
The calendars listed below were known to be in use during the last hundred years. Many other calendars have been used in the past.
This specification does not define any of these calendars, nor the way that they
map to the value space of the xs:date datatype in $place and/or $language arguments, with the
$place
argument taking precedence.
Information about some of these calendars, and algorithms for converting between them, may
be found in
| Designator | Calendar |
|---|---|
| AD | Anno Domini (Christian Era) |
| AH | Anno Hegirae (Islamic Era) |
| AME | Mauludi Era (solar years since Muhammad’s birth) |
| AM | Anno Mundi (Jewish Calendar) |
| AP | Anno Persici |
| AS | Aji Saka Era (Java) |
| BE | Buddhist Era |
| CB | Cooch Behar Era |
| CE | Common Era |
| CL | Chinese Lunar Era |
| CS | Chula Sakarat Era |
| EE | Ethiopian Era |
| FE | Fasli Era |
| ISO | ISO 8601 calendar |
| JE | Japanese Calendar |
| KE | Khalsa Era (Sikh calendar) |
| KY | Kali Yuga |
| ME | Malabar Era |
| MS | Monarchic Solar Era |
| NS | Nepal Samwat Era |
| OS | Old Style (Julian Calendar) |
| RS | Rattanakosin (Bangkok) Era |
| SE | Saka Era |
| SH | Solar Hijri (Islamic Era, used in Iran and Afghanistan) |
| SS | Saka Samvat |
| TE | Tripurabda Era |
| VE | Vikrama Era |
| VS | Vikrama Samvat Era |
At least one of the above calendars
The ISO 8601 calendar (ISO,
is very similar to the Gregorian calendar designated AD, but it
differs in several ways. The ISO calendar
is intended to ensure that date and time formats can be read
easily by other software, as well as being legible for human
users. The ISO calendar
prescribes the use of particular numbering conventions as defined in
ISO 8601, rather than allowing these to be localized on a per-language basis.
In particular it
provides a numeric “week date” format which identifies dates by
year, week of the year, and day in the week;
in the ISO calendar the days of the week are numbered from 1 (Monday) to 7 (Sunday), and
week 1 in any calendar year is the week (from Monday to Sunday) that includes the first Thursday
of that year. The numeric values of the components year, month, day, hour, minute, and second
are the same in the ISO calendar as the values used in the lexical representation of the date and
time as defined in E component)
with this calendar is either a minus sign (for negative years) or a zero-length string (for positive years).
For dates before 1 January, AD 1, year numbers in
the ISO and AD calendars are off by one from each other: ISO year
0000 is 1 BC, -0001 is 2 BC, etc.
ISO 8601 does not define a numbering for weeks within a month. When the w
component is used, the convention to be adopted is that each Monday-to-Sunday week is considered to
fall within a particular month if its Thursday occurs in that month; the weeks that fall in a particular
month under this definition are numbered starting from 1. Thus, for example,
29 January 2013 falls in week 5 because the Thursday of the week (31 January 2013) is the fifth Thursday
in January, and 1 February 2013 is also in week 5 for the same reason.
The value space of the date and time datatypes, as defined in XML Schema, is based on
absolute points in time. The lexical space of these datatypes defines a
representation of these absolute points in time using the proleptic Gregorian calendar,
that is, the modern Western calendar extrapolated into the past and the future; but the value space
is calendar-neutral. The
1502-01-11
(the day on which Pope Gregory XIII was born) might be
formatted using the Old Style (Julian) calendar as 1 January 1502. This reflects the fact
that there was at that time a ten-day difference between the two calendars. It would be
incorrect, and would produce incorrect results, to represent this date in an element or attribute
of type xs:date as 1502-01-01, even though this might reflect the way
the date was recorded in contemporary documents.
When referring to years occurring in antiquity, modern historians generally
use a numbering system in which there is no year zero (the year before 1 CE
is thus 1 BCE). This is the convention that xs:date and xs:dateTime
does not include a year zero: however, XSD 1.1 endorses the ISO 8601 convention. This means that the date on
which Julius Caesar was assassinated has the ISO 8601 lexical representation
-0043-03-13, but will be formatted as 15 March 44 BCE in the Julian calendar
or 13 March 44 BCE in the Gregorian calendar (dependent on the chosen
localization of the names of months and eras).
The intended use of the $place argument is to identify
the place where an event
represented by the dateTime, date,
or time supplied in the $value argument took place or will take place.
If the $place argument is omitted or is set
to the empty sequence, then the default place defined in the dynamic context is used.
If the value is supplied, and is not the empty sequence, then it
Country codes are defined in "de" for Germany
and "jp" for Japan. Implementations
IANA timezone names are defined in the IANA timezone database "America/New_York" and "Europe/Rome".
This argument is not intended to identify the location of the user
for whom the date or time is being formatted;
that should be done by means of the $language attribute.
This information
The geographical area identified by a country code is defined by the boundaries as they existed at the time of the date to be formatted, or the present-day boundaries for dates in the future.
If the $place argument is supplied in the form
of an IANA timezone name that is recognized by the implementation, then the date or
time being formatted is adjusted to the timezone offset applicable in that timezone.
For example, if the xs:dateTime value 2010-02-15T12:00:00Z
is formatted with the $place argument set to
America/New_York, then the output will be as if the value
2010-02-15T07:00:00-05:00 had been supplied. This adjustment takes daylight
savings time into account where possible; if the date in question falls during
daylight savings time in New York, then it is adjusted to timezone offset -PT4H
rather than -PT5H. Adjustment using daylight savings time is only possible
where the value includes a date, and where the date is within the range covered
by the timezone database.
The following examples show a selection of dates and times and the way they might be formatted. These examples assume the use of the Gregorian calendar as the default calendar.
| Required Output | Expression |
|---|---|
2002-12-31
|
format-date($d, "[Y0001]-[M01]-[D01]")
|
12-31-2002
|
format-date($d, "[M]-[D]-[Y]")
|
31-12-2002
|
format-date($d, "[D]-[M]-[Y]")
|
31 XII 2002
|
format-date($d, "[D1] [MI] [Y]")
|
31st December, 2002
|
format-date($d, "[D1o] [MNn], [Y]", "en", (), ())
|
31 DEC 2002
|
format-date($d, "[D01] [MN,*-3] [Y0001]", "en", (), ())
|
December 31, 2002
|
format-date($d, "[MNn] [D], [Y]", "en", (), ())
|
31 Dezember, 2002
|
format-date($d, "[D] [MNn], [Y]", "de", (), ())
|
Tisdag 31 December 2002
|
format-date($d, "[FNn] [D] [MNn] [Y]", "sv", (), ())
|
[2002-12-31]
|
format-date($d, "[[[Y0001]-[M01]-[D01]]]")
|
Two Thousand and Three
|
format-date($d, "[YWw]", "en", (), ())
|
einunddreißigste Dezember
|
format-date($d, "[Dwo] [MNn]", "de", (), ())
|
3:58 PM
|
format-time($t, "[h]:[m01] [PN]", "en", (), ())
|
3:58:45 pm
|
format-time($t, "[h]:[m01]:[s01] [Pn]", "en", (), ())
|
3:58:45 PM PDT
|
format-time($t, "[h]:[m01]:[s01] [PN] [ZN,*-3]", "en", (), ())
|
3:58:45 o'clock PM PDT
|
format-time($t, "[h]:[m01]:[s01] o'clock [PN] [ZN,*-3]", "en", (), ())
|
15:58
|
format-time($t, "[H01]:[m01]")
|
15:58:45.762
|
format-time($t, "[H01]:[m01]:[s01].[f001]")
|
15:58:45 GMT+02:00
|
format-time($t, "[H01]:[m01]:[s01] [z,6-6]", "en", (), ())
|
15.58 Uhr GMT+2
|
format-time($t, "[H01]:[m01] Uhr [z]", "de", (), ())
|
3.58pm on Tuesday, 31st December
|
format-dateTime($dt, "[h].[m01][Pn] on [FNn], [D1o] [MNn]")
|
12/31/2002 at 15:58:45
|
format-dateTime($dt, "[M01]/[D01]/[Y0001] at [H01]:[m01]:[s01]")
|
The following examples use calendars other than the Gregorian calendar.
| Description | Request | Result |
|---|---|---|
| Islamic |
format-date($d, "[D١] [Mn] [Y١]", "ar", "AH", ())
| ٢٦ ﺸﻭّﺍﻝ ١٤٢٣ |
| Jewish (with Western numbering) |
format-date($d, "[D] [Mn] [Y]", "he", "AM", ())
| 26 טבת 5763 |
| Jewish (with traditional numbering) |
format-date($d, "[Dאt] [Mn] [Yאt]", "he", "AM", ())
| כ״ו טבת תשס״ג |
| Julian (Old Style) |
format-date($d, "[D] [MNn] [Y]", "en", "OS", ())
| 18 December 2002 |
| Thai |
format-date($d, "[D๑] [Mn] [Y๑]", "th", "BE", ())
| ๓๑ ธันวาคม ๒๕๔๕ |
| Function | Meaning |
|---|---|
fn:parse-ietf-date | Parses a string containing the date and time in IETF format, returning the corresponding
xs:dateTime value. |
A function is provided to parse dates and times expressed using syntax that is commonly encountered in internet protocols.
Parses a string containing the date and time in IETF format, returning the corresponding
xs:dateTime value.
This function is
The function accepts a string matching the production input in the
following grammar:
input
|
::=
|
S? (dayname ","? S)? ((datespec S time) | asctime) S?
|
dayname
|
::=
|
"Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat" | "Sun" | "Monday | "Tuesday"
| "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday"
|
datespec
|
::=
|
daynum dsep monthname dsep year
|
asctime
|
::=
|
monthname dsep daynum S time S year
|
dsep
|
::=
|
S | (S? "-" S?)
|
daynum
|
::=
|
digit digit?
|
year
|
::=
|
digit digit (digit digit)?
|
digit
|
::=
|
[0-9]
|
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 case-insensitive: upper-case and lower-case distinctions in the above grammar show the conventional usage, but otherwise have no significance.
If the input is the empty sequence, the result is the 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 two-digit 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 parse-ietf-date 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 single-digit value where appropriate in place of a two-digit 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 "[FNn3], [D01] [MNn3] [Y04] [H01]:[m01]:[s01] [Z0000]".
| Expression | Result |
|---|---|
parse-ietf-date("Wed, 06 Jun 1994 07:29:35 GMT") |
|
parse-ietf-date("Wed, 6 Jun 94 07:29:35 GMT") |
|
parse-ietf-date("Wed Jun 06 11:54:45 EST 2013") |
|
parse-ietf-date("Sunday, 06-Nov-94 08:49:37 GMT") |
|
parse-ietf-date("Wed, 6 Jun 94 07:29:35 +0500") |
|
In XPath 4.0, statically-known QNames can be expressed using a QName literal such as
#xml:space. Where the QName is not known statically,
the xs:QName constructor function can be used.
In addition to the xs:QName constructor function, QName values can
be constructed by combining a namespace URI, prefix, and local name, or by resolving
a lexical QName against the in-scope namespaces of an element node. This section
defines functions that perform these operations.
Leading and trailing whitespace, if present, is stripped from
string arguments before the result is constructed.
| Function | Meaning |
|---|---|
fn:QName | Returns an xs:QName value formed using a supplied namespace URI and lexical QName. |
fn:parse-QName | Returns an xs:QName value formed by parsing an EQName. |
fn:resolve-QName | Returns an xs:QName value (that is, an expanded-QName) by taking an
xs:string that has the lexical form of an xs:QName (a
string in the form "prefix:local-name" or "local-name")
and resolving it using the in-scope namespaces for a given element. |
Returns an xs:QName value formed using a supplied namespace URI and lexical QName.
This function is
The namespace URI in the returned QName is taken from $uri. If
$uri is the zero-length 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 zero-length 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).
| Expression | Result |
|---|---|
QName("http://www.example.com/example", "person") |
|
QName("http://www.example.com/example", "ht:person") |
|
Returns an xs:QName value formed by parsing an EQName.
This function is
If $value is the empty sequence, the result is the empty sequence.
Otherwise, leading and trailing whitespace in $value is stripped:
call the result V
If V is castable to xs:NCName,
the result is fn:QName("", $value): that is, a QName in no namespace.
If V 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 in-scope prefixes in the static context, and may result in
various error conditions.
If V takes the form of a
XPath Q{uri}local, where the uri part may be zero-length,
or Q{uri}prefix:local),
then the result is fn:QName(uri, local) or fn:QName(uri, prefix:local)
respectively.
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 URIQualifiedName in which the namespace prefix
is present but the namespace URI is absent.
A dynamic error is raised $value, after whitespace normalization,
is in the form prefix:local (with a non-absent prefix), and
the prefix cannot be resolved to a namespace URI using the in-scope namespace
bindings from the static context.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: |
Returns an xs:QName value (that is, an expanded-QName) by taking an
xs:string that has the lexical form of an xs:QName (a
string in the form "prefix:local-name" or "local-name")
and resolving it using the in-scope namespaces for a given element.
This function is
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 zero-length
string if it has no prefix, and returns an expanded-QName 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 expanded-QName has no namespace part.
The prefix (or absence of a prefix) in the supplied $value argument is
retained in the returned expanded-QName, 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.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
fn:resolve-QName("hello", $element) |
|
fn:resolve-QName("eg:myFunc", $element) |
|
This section specifies functions on QNames as defined in
| Function | Meaning |
|---|---|
fn:prefix-from-QName | Returns the prefix component of the supplied QName. |
fn:local-name-from-QName | Returns the local part of the supplied QName. |
fn:namespace-uri-from-QName | Returns the namespace URI part of the supplied QName. |
fn:expanded-QName | Returns a string representation of an xs:QName in the format Q{uri}local. |
Returns the prefix component of the supplied QName.
This function is
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.
This function is
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.
| Expression: | |
|---|---|
| Result: |
Returns the namespace URI part of the supplied QName.
This function is
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 zero-length
xs:anyURI.
| Expression: | |
|---|---|
| Result: |
Returns a string representation of an xs:QName in the format Q{uri}local.
This function is
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:namespace-uri-from-QName($value))
(which will be a zero-length string if the QName is in no namespace), and
local is the result of
fn:local-name-from-QName($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
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: |
There are no functions designed explicitly to process xs:NOTATION items.
However, some generic functions such as fn:compare can be used on xs:NOTATION items.
Binary data is represented using the data types xs:hexBinary and
xs:base64Binary. Both types have the same value space: a sequence of octets,
which can be considered as integers in the range 0 to 255.
The coercion rules of XPath 4.0 ensure that the two types are interoperable; a function
that declares an argument of type xs:hexBinary will always accept a value of
type xs:base64Binary, and vice versa.
There are no functions defined in this document provided exclusively for processing binary data. A number of generic functions are available:
Functions such as fn:deep-equal, and
Functions such as
The function
The constructor functions xs:string, xs:hexBinary,
and xs:base64Binary can be used to convert binary values to and from their
string representation.
The function xs:base64Binary value.
A library of functions specific to processing of binary data can be found in
Accessors and their semantics are described in
Each of these functions has an arity-zero signature which is equivalent to the arity-one
form, with the context value supplied as the implicit first argument. In addition, each of the
arity-one functions accepts the empty sequence as the argument, in which case it generally delivers
the empty sequence as the result: the exception is
| Function | Accessor | Accepts | Returns |
|---|---|---|---|
|
|
node-name
| node (optional) | xs:QName (optional)
|
|
|
nilled
| node (optional) | xs:boolean (optional)
|
|
|
string-value
| item (optional) |
xs:string
|
|
|
typed-value
| zero or more items | a sequence of atomic items |
|
|
base-uri
| node (optional) | xs:anyURI (optional)
|
|
|
document-uri
| node (optional) | xs:anyURI (optional)
|
| Function | Meaning |
|---|---|
fn:base-uri | Returns the base URI of a node. |
fn:document-uri | Returns the URI of a resource where a document can be found, if available. |
fn:nilled | Returns true for an element that is |
fn:node-name | Returns the name of a node, as an xs:QName. |
fn:string | Returns the value of $value represented as an xs:string. |
fn:data | Returns the result of atomizing a sequence. This process flattens arrays, and replaces nodes by their typed values. |
Returns the base URI of a node.
The zero-argument form of this function is
The one-argument form of this function is
If $node is the empty sequence, the function returns the empty
sequence.
Otherwise, the function returns the value of the dm:base-uri 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 processing-instruction nodes have a base-uri property which may be empty. The base-uri property for all other node kinds is the empty sequence. The dm:base-uri accessor returns the base-uri property of a node if it exists and is non-empty; otherwise it returns the result of applying the dm:base-uri 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 base-uri property is empty, the empty sequence is returned. In the case of namespace nodes, however, the result is always the empty sequence — it does not depend on the base URI of the parent element.
See also
The following errors may be raised when $node is omitted:
If the context value is
If the context value is not an instance of the sequence type node()?, type error
A dynamic error
Returns the URI of a resource where a document can be found, if available.
The zero-argument form of this function is
The one-argument form of this function is
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 document-uri accessor
applied to $node, as defined in
The following errors may be raised when $node is omitted:
If the context value is
If the context value is not an instance of the sequence type node()?, type error
In the 3.1 version of this specification, it was mandated that two distinct documents could
not have the same document-uri property: more specifically, it was guaranteed that for any document node
$D, either document-uri($D) would be absent, or doc(document-uri($D))
would return $D.
For various reasons, this constraint has proved impractical. Different parts of an application
may read the same external resource in different ways, for example with or without validation or
whitespace stripping, leading to different document nodes derived from the same external
resource having the same document-uri property. In addition, the specification
explicitly allows implementations, at user request, to relax the requirements for determinism
of resource access functions, which makes it possible for multiple calls of functions such as
Although the uniqueness of the document-uri property is no longer
an absolute constraint, it is still desirable that implementations should where possible
respect the principle that URIs are usable as identifiers for resources.
In the case of a document node $D returned by the fn:document-uri($D) returns a URI $U
such that a call on fn:doc($U) in the same dynamic context will return the same document
node $D. The URI $U will not necessarily be the same URI that was originally
passed to the
It is
Returns true for an element that is
The zero-argument form of this function is
The one-argument form of this function is
If $node is the empty sequence, the function returns the empty sequence.
Otherwise the function returns the result of the dm:nilled accessor as
defined in
The following errors may be raised when $node is omitted:
If the context value is
If the context value is not an instance of the sequence type 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 name of a node, as an xs:QName.
The zero-argument form of this function is
The one-argument form of this function is
If $node is the empty sequence, the empty sequence is returned.
Otherwise, the function returns the result of the dm:node-name accessor as
defined in
The following errors may be raised when $node is omitted:
If the context value is
If the context value is not an instance of the sequence type 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 the empty sequence if the node represents the
default namespace; otherwise it returns an xs:QName in which prefix and
namespace URI are
For all other kinds of node, the function returns the empty sequence.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
node-name($e//*[@id = 'alpha']) |
|
node-name($e//*[@id = 'gamma']) |
|
node-name($e//*[@id = 'delta']) |
|
node-name($e//processing-instruction()) |
|
node-name($e//*[@id = 'alpha']/text()) |
|
node-name($e//*[@id = 'alpha']/@id) |
|
node-name($e//*[@id = 'alpha']/@xml:id) |
|
Returns the value of $value represented as an xs:string.
The zero-argument form of this function is
The one-argument form of this function is
If $value is the empty sequence, the function returns the zero-length
string.
If $value is an dm:string-value accessor defined in
If $value is a string(jvalue($value)).
This will fail in the case where jvalue($value) is a map or an array.
If $value is an atomic item, the function returns the result of the expression $value cast
as xs:string (see
In all other cases, a dynamic error occurs (see below).
The following errors may be raised when $value is omitted:
If the context value is
If the context value is not an instance of the sequence type item()?, type error
A type error is raised $value is a function item (this includes maps and arrays).
Every node has a string value, even an element with element-only
content (which has no typed value). Moreover, casting an atomic item to a string always
succeeds. Functions, maps, and arrays have no string value, so these
satisfy the type signature but cause failure. Applying the
| Variables | |
|---|---|
| Expression | Result |
|---|---|
string(23) |
|
string(false()) |
|
string("Paris") |
|
string((1, 2, 3)) | Raises error XPTY0004. |
string([ [ 1, 2 ], [ 3, 4 ] ]) | Raises error FOTY0014. |
string(abs#1) | Raises error FOTY0014. |
string({ "x": [10, 20, 30] }/x/*[3]) |
|
string($para) |
|
Returns the result of atomizing a sequence. This process flattens arrays, and replaces nodes by their typed values.
The zero-argument form of this function is
The one-argument form of this function is
The result of $input:
If the item is an atomic item, it is appended to the result sequence.
If the item is an dm:typed-value accessor as defined in
If the item is a
If the item is an array, the result of applying
A type error is raised $input is a node that does not have a typed value.
A type error is raised $input is a function item other than
an array.
A type error is raised $input is omitted and the context value is
The process of applying the
The result of atomizing the empty sequence is the empty sequence.
The result of atomizing the empty array is the empty sequence.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
data(123) |
|
data((123, 456)) |
|
data([ [ 1, 2 ], [ 3, 4 ] ]) |
|
data($para) |
|
data($para/term/@author) |
|
data(abs#1) | Raises error FOTY0013. |
This section specifies further functions that return properties of nodes.
Nodes are formally defined in
| Function | Meaning |
|---|---|
fn:has-children | Returns true if the supplied GNode has one or more child nodes (of any kind). |
fn:in-scope-namespaces | Returns the in-scope namespaces of an element node, as a map. |
fn:in-scope-prefixes | Returns the prefixes of the in-scope namespaces for an element node. |
fn:lang | This function tests whether the language of $node, or the context value 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. |
fn:local-name | Returns the local part of the name of $node as an xs:string
that is either the zero-length string, or has the lexical form of an
xs:NCName. |
fn:name | Returns the name of a node, as an xs:string that is either the zero-length
string, or has the lexical form of an xs:QName. |
fn:namespace-uri | Returns the namespace URI part of the name of $node, as an
xs:anyURI value. |
fn:namespace-uri-for-prefix | Returns the namespace URI of one of the in-scope namespaces for $element,
identified by its namespace prefix. |
fn:path | Returns a path expression that can be used to select the supplied node relative to the root of its containing document. |
fn:root | Returns the root of the tree to which $node belongs. The
function can be applied both to |
fn:siblings | Returns the supplied GNode together with its siblings, in document order. |
Returns true if the supplied GNode has one or more child nodes (of any kind).
The zero-argument form of this function is
The one-argument form of this function is
Provided that the supplied argument $node matches the expected type
gnode()?, the result of the function call
fn:has-children($node) is defined to be the same as the result of the
expression fn:exists($node/child::gnode()).
The following errors may be raised when $node is omitted:
If the context value is
If the context value is not an instance of the sequence type gnode()?, type error
If $node is the 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 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.
If the supplied argument is a map or an array, it will automatically be coerced to a JNode.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
has-children($e) |
|
has-children($e//p[1]) |
|
has-children($e//p[2]) |
|
has-children($e//p[3]) |
|
has-children($e//processing-instruction()) |
|
has-children($e//p[1]/text()) |
|
has-children($e//p[1]/@id) |
|
jtree([1,2,3]) => has-children() |
|
jtree([]) => has-children() |
|
Returns the in-scope namespaces of an element node, as a map.
This function is
The function returns a map representing the prefixes of the in-scope
namespaces for $element. The map contains one entry
for each in-scope namespace: the key of the entry is the namespace
prefix or a zero-length 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 zero-length string as an instance of xs:string.
The order of entries in the returned map is
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.
| Variables | |
|---|---|
| Expression: |
|
|---|---|
| Result: |
Returns the prefixes of the in-scope namespaces for an element node.
This function is
The function returns the result of the expression
map:keys(fn:in-scope-namespaces($element)) (but in no defined order).
The XML namespace is in scope for every element, so the result will always include the string "xml".
This function tests whether the language of $node, or the context value 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 one-argument form of this function is
The two-argument form of this function is
The language of the argument $node 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 zero-length
string.
The relevant xml:lang attribute is determined by the value of the XPath
expression:
If this expression returns the 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 string-value of the relevant
xml:lang attribute, or
$language is equal to some substring of the string-value of the
relevant xml:lang attribute that starts at the start of the
string-value and ends immediately before a hyphen, -
(HYPHEN-MINUS, #x002D).
The following errors may be raised when $node is omitted:
If the context value is
If the context value is not a single node, type error
| Expression | Result |
|---|---|
<para xml:lang="en"/> -> fn:lang("en") |
|
<div xml:lang="en"><para>And now, and
forever!</para></div> -> fn:lang("en") |
|
<para xml:lang="EN"/> -> fn:lang("en") |
|
<para xml:lang="en-us"/> -> fn:lang("en") |
|
<para xml:lang="EN"/> -> fn:lang("fr") |
|
<para xml:lang="en-us"/> -> fn:lang("en-GB") |
|
Returns the local part of the name of $node as an xs:string
that is either the zero-length string, or has the lexical form of an
xs:NCName.
The zero-argument form of this function is
The one-argument form of this function is
If $node is the empty sequence, the function returns the zero-length 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 zero-length string.
Otherwise, the function returns the local part of the expanded-QName of the node
identified by $node, as determined by the dm:node-name 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 value is
If the context value is not a single node, type error
| Variables | |
|---|---|
| Expression | Result |
|---|---|
local-name($e//*[@id = 'alpha']) |
|
local-name($e//*[@id = 'gamma']) |
|
local-name($e//*[@id = 'delta']) |
|
local-name($e//processing-instruction()) |
|
local-name($e//*[@id = 'alpha']/text()) |
|
local-name($e//*[@id = 'alpha']/@id) |
|
local-name($e//*[@id = 'alpha']/@xml:id) |
|
Returns the name of a node, as an xs:string that is either the zero-length
string, or has the lexical form of an xs:QName.
The zero-argument form of this function is
The one-argument form of this function is
If $node is the empty sequence, the function returns the zero-length 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 zero-length string.
Otherwise, the function returns the value of the expression
fn:string(fn:node-name($node)).
The following errors may be raised when $node is omitted:
If the context value is
If the context value is not an instance of the sequence type 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).
| Variables | |
|---|---|
| Expression | Result |
|---|---|
name($e//*[@id = 'alpha']) |
|
name($e//*[@id = 'gamma']) |
|
name($e//*[@id = 'delta']) |
|
name($e//processing-instruction()) |
|
name($e//*[@id = 'alpha']/text()) |
|
name($e//*[@id = 'alpha']/@id) |
|
name($e//*[@id = 'alpha']/@xml:id) |
|
Returns the namespace URI part of the name of $node, as an
xs:anyURI value.
The zero-argument form of this function is
The one-argument form of this function is
If $node is the empty sequence, if the node identified by is neither an
element nor an attribute node, or if it is an element or attribute node whose
expanded-QName (as determined by the dm:node-name accessor in the
xs:anyURI value.
Otherwise, the result will be the namespace URI part of the expanded-QName of the node
identified by $node, as determined by the dm:node-name accessor
defined in xs:anyURI value.
The following errors may be raised when $node is omitted:
If the context value is
If the context value is not an instance of the sequence type node()?, type error
| Variables | |
|---|---|
| Expression | Result |
|---|---|
namespace-uri($e//*[@id = 'alpha']) |
|
namespace-uri($e//*[@id = 'gamma']) |
|
namespace-uri($e//*[@id = 'delta']) |
|
namespace-uri($e//processing-instruction()) |
|
namespace-uri($e//*[@id = 'alpha']/text()) |
|
namespace-uri($e//*[@id = 'alpha']/@id) |
|
namespace-uri($e//*[@id = 'alpha']/@xml:id) |
|
Returns the namespace URI of one of the in-scope namespaces for $element,
identified by its namespace prefix.
This function is
The function returns the result of the expression map:get(fn:in-scope-namespaces($element), string($value)).
| Variables | |
|---|---|
| Expression | Result |
|---|---|
namespace-uri-for-prefix("z", $e) |
|
namespace-uri-for-prefix("", $e) |
|
namespace-uri-for-prefix((), $e) |
|
namespace-uri-for-prefix("xml", $e) |
|
Returns a path expression that can be used to select the supplied node relative to the root of its containing document.
The zero-argument form of this function is
The one-argument form of this function is
The two-argument form of this function is
If $node is the empty sequence, the function returns the empty sequence.
The $options argument defines additional parameters controlling
how the output is formatted. The
| Key | Meaning |
|---|---|
| A GNode, which must be an ancestor of $node. If present,
the returned path will be a relative path that selects $node
starting from the supplied origin node, rather than from the root of the
containing tree.
|
| If true, the names of element nodes in the path are represented by the
result of a call on the
|
| A map from namespace prefixes to namespace URIs, such as might be returned
by the function Q{uri}local notation.
|
| If true, the returned path includes the index positions of nodes. If
false, only the node names are included.
|
Let R be the GNode supplied in the origin option,
or the root GNode of the tree containing $node otherwise.
If $node is a document node, or a JNode with no parent,
the function returns the string "/".
Otherwise, the function returns a string that consists of a sequence of steps, one
for each ancestor-or-self of $node that is not an ancestor-or-self
of R.
If R is an XNode other than a document node and the origin option
is absent or empty, then this string is preceded by
a string notionally representing a call to the fn:root function,
expressed as follows:
If the lexical option is present with the value true,
then the string "fn:root()".
If the namespaces option is present and defines a mapping from a
non empty prefix P
to the namespace URI http://www.w3.org/2005/xpath-functions, then
"P:root()"
If the namespaces option is present and defines a mapping from the empty string
to the namespace URI http://www.w3.org/2005/xpath-functions, then
"root()"
Otherwise, "Q{http://www.w3.org/2005/xpath-functions}root()".
Each step is the concatenation of:
The character "/", which is omitted for the first step
if the origin option is present;
A string whose form depends on the kind of node selected by that step, as follows:
For an element node, the concatenation of:
A representation of the element name, chosen as follows:
If the lexical option is present with the value
true, then the result of applying the
Otherwise, if the namespaces option is present
and the element is in a namespace U and the namespaces option
includes a mapping from a prefix P to the namespace U,
then the string P:L, where L
is the local part of the element name.
If there is more than one such prefix, then one of them is chosen arbitrarily.
Otherwise, if the namespaces option is present
and the element is in a namespace U and the namespaces option
includes a mapping from the zero-length string to the namespace U,
then the local part of the element name.
Otherwise, if the namespaces option is present
and the element is in no namespace and the namespaces option
includes no mapping from the zero-length string to any namespace,
then the local part of the element name.
Otherwise, the string Q{U}L,
where U is the namespace URI of the element name or the
empty string if the element is in no namespace, and L is
the local part of the element name.
Unless the indexes option is present
with the value false,
a string in the form [position] where position is an
integer representing the one-based position of the selected node among its like-named
siblings.
For an attribute node, the concatenation of:
The character "@"
If the lexical option is present with the value
true, then the result of applying the
Otherwise, if the attribute node is in no namespace, the local part of the attribute name.
Otherwise, if the namespaces option is present, and if it includes a mapping
from a non-empty namespace prefix P to the namespace URI of the attribute, then
a string in the form P:L, where L
is the local part of the attribute name.
If there is more than one such prefix, then one of them is chosen arbitrarily.
Otherwise, the string Q{U}L,
where U is the namespace URI of the attribute name, and L is
the local part of the attribute name.
For a text node: text()[position] where
position is an integer representing the position
of the selected node among its text node siblings.
The suffix [position] is omitted if the indexes
option is present with the value false.
For a comment node: comment()[position] where
The suffix [position] is omitted if the indexes
option is present with the value false.
For a processing-instruction node:
processing-instruction(local)[position]
where
The suffix [position] is omitted if the indexes
option is present with the value false.
For a namespace node:
If the namespace node has a name:
namespace::, where
If the namespace node has no name (that is, if it represents the default
namespace):
namespace::*[Ulocal-name() = ""]
Here Ulocal-name() represents a call on the function
fn:local-name and is formatted using the same
conventions as the call on fn:root described earlier.
For a JNode where the ·jvalue· property of the parent
is an array, then as the string *[N] where N
is the value of the ·jkey· property.
For any other JNode (including the case where the ·jvalue· property of the parent is a map):
If the value is an xs:string, xs:untypedAtomic,
or xs:anyURI that is castable to xs:NCName, then
the result of casting the value to xs:NCName.
If the value is an xs:string, xs:untypedAtomic,
or xs:anyURI that is not castable to xs:NCName, then
then as the string get("S")
where S is the string value.
If the value is numeric, then as the string get(N)
where N is the result of casting the numeric value to
xs:string.
If the value is an xs:QName, then as the string
get(#Q{uri}local) where uri
and local are the namespace URI and local name parts of the QName.
If the value is an xs:boolean, then as the string
get(true()) or get(false()).
If the value is of any other type, then as the string
get(xs:T("S")) where T is the
local part of the most specific built-in atomic type of which the value
is an instance, and S is the result of casting the value to
xs:string.
TODO: Better handling of the case where the parent is neither a map nor an array, for example where it is a sequence of several maps or several arrays. It's hard to provide a better path for these when there is no AxisStep for selecting within such values.
The following errors may be raised when $node is omitted:
If the context value is
If the context value is not an instance of the sequence type node()?, type error
If the value of the origin option is a node that is not an ancestor
of $node (or in the absence of $node, the context value),
dynamic error
Using the namespaces option to shorten the generated path is often convenient,
but the resulting path may be unusable if the input tree contains multiple bindings for the same prefix.
Similarly, using the lexical option is convenient if there is no need for precise
namespace information: it is especially suitable when the containing node tree declares no namespaces.
If the supplied argument is a map or an array, it will automatically be coerced to a JNode. This
however is not useful, because this will be a root JNode, yielding the path /.
| Variables | |
|---|---|
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns the root of the tree to which $node belongs. The
function can be applied both to
The zero-argument form of this function is
The one-argument form of this function is
The function returns the value of the expression
$node/ancestor-or-self::gnode()[last()].
The following errors may be raised when $node is omitted:
If the context value is
If the context value is not an instance of the sequence type
gnode()?, type error
These examples use some variables which could be defined in | |
Or they could be defined in | |
| |
| |
| |
| |
The final three examples could be made type-safe by wrapping their operands with
|
Returns the supplied GNode together with its siblings, in document order.
The zero-argument form of this function is
The one-argument form of this function is
If the value of $node is the empty sequence, the function returns the empty sequence.
If $node is a child of some parent GNode P, the function returns all the
children of P (including $node), in document order, as determined
by the value of $node/child::gnode().
Otherwise (specifically, if $node is parentless, or if it is an attribute or namespace node),
the function returns $node.
The effect of the function is equivalent to the result of the following XPath expression.
The following errors may be raised when $node is omitted:
If the context value is
If the context value is not an instance of the sequence type node()?, type error
The result of siblings($n) (except in error cases) is the same as
the result of $n/(preceding-sibling::node() | following-sibling-or-self::node()).
It is also the same as $n/(preceding-sibling-or-self::node() | following-sibling::node())
As with names such as parent and child, the word
| Variables | |
|---|---|
| Expression | Result |
|---|---|
siblings($e//a) ! string() |
|
siblings($e//processing-instruction('pi')) ! string() |
|
siblings($e//@x) ! string() |
|
This section specifies functions on sequences of nodes.
| Function | Meaning |
|---|---|
fn:distinct-ordered-nodes | Removes duplicate GNodes and sorts the input into document order. |
fn:innermost | Returns every GNode within the input sequence that is not an ancestor of another member of the input sequence; the GNodes are returned in document order with duplicates eliminated. |
fn:outermost | Returns every GNode 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. |
Removes duplicate GNodes and sorts the input into document order.
This function is
Any duplicate GNodes (that is, XNodes or JNodes) in the input
(based on node identity) are discarded. The remaining GNodes
are returned in
Document order is
| Expression: | |
|---|---|
| Result: |
|
| Expression: | |
| Result: |
Returns every GNode within the input sequence that is not an ancestor of another member of the input sequence; the GNodes are returned in document order with duplicates eliminated.
This function is
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 GNodes, and returns every GNode within the sequence that is not an ancestor of another GNode within the sequence; the GNodes are returned in document order with duplicates eliminated.
If the supplied argument includes a map or an array, it will automatically be coerced to a JNode.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: |
Returns every GNode 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.
This function is
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 GNodes, and returns every GNode within the sequence that does not have another GNode within the sequence as an ancestor; the GNodes 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 supplied argument includes a map or an array, it will automatically be coerced to a JNode.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: |
This section defines a number of functions used to find elements by ID or IDREF value,
or to generate identifiers.
| Function | Meaning |
|---|---|
fn:id | 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. |
fn:element-with-id | 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. |
fn:idref | 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. |
fn:generate-id | This function returns a string that uniquely identifies a given GNode. |
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 one-argument form of this function is
The two-argument form of this function is
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.
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 is-id 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/xpath-functions/collation/codepoint).
The element has an attribute node whose is-id 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/xpath-functions/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 whitespace-separated sequence of
tokens, each acting as an IDREF. These tokens are then included
in the list of candidate IDREFs. 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 value 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 value is
If the context value is not a single node, type error
The effect of this function is anomalous in respect of element nodes with the
is-id property. For legacy reasons, this function returns the element
that has the is-id 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
If the data model is constructed from an Infoset, an attribute will have the
is-id 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
is-id property if its typed value is a single atomic item 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
is-idrefs 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 well-formed 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 well-formed but invalid document to have an element or
attribute that has the is-id 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.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
| |
|
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 one-argument form of this function is
The two-argument form of this function is
The effect of this function is identical to is-id property. However, it
behaves differently in respect of element nodes with the is-id property.
Whereas the is-id property, this function returns the element identified by the ID,
which is the parent of the element having the is-id 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.
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 is-id
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/xpath-functions/collation/codepoint).
The element has an attribute node whose is-id 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/xpath-functions/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 whitespace-separated sequence of
tokens, each acting as an IDREF. These tokens are then included
in the list of candidate IDREFs. 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 value 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 value is
If the context value is not a single node, type error
This function is equivalent to the
If the data model is constructed from an Infoset, an attribute will have the
is-id 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
is-id property if its typed value is a single atomic item 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
is-idrefs 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 well-formed 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 well-formed but invalid document to have an element or
attribute that has the is-id 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.
| Variables | |
|---|---|
| Expression: | |
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
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 one-argument form of this function is
The two-argument form of this function is
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.
$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 is-idrefs 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/xpath-functions/collation/codepoint).
Each xs:string in $values is parsed as if it were of
lexically of type xs:ID. These xs:strings are then
included in the list of candidate xs:IDs. 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 value 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 value is
If the context value is not a single node, type error
An element or attribute typically acquires the is-idrefs 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 well-formed but invalid document to have a node whose
is-idrefs 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
ill-formed candidate ID values and ill-formed IDREF values are
ignored.
If the data model is constructed from a PSVI, the typed value of a node that has the
is-idrefs property will contain at least one atomic item of type
xs:IDREF (or a type derived by restriction from xs:IDREF).
It may also contain atomic items of other types. These atomic items 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.
| Variables | |
|---|---|
| Expression: | |
|---|---|
| Result: |
|
| Expression: | |
| Result: |
|
This function returns a string that uniquely identifies a given GNode.
The zero-argument form of this function is
The one-argument form of this function is
If $node is the empty sequence, the result is the zero-length string.
In other cases, the function returns a string that uniquely identifies a given node.
fn:codepoint-equal(fn:generate-id($N), fn:generate-id($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 value is
If the context value is not an instance of the sequence type
gnode()?, 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 GNode and that different identifiers are always generated from different GNodes. 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 GNode with
a given generated ID. Of course, it is possible to search a given sequence of GNodes
using an expression such as $nodes[generate-id()=$id].
It is advisable, but not required, for implementations to generate IDs that are distinct even when compared using a case-blind collation.
The primary use case for this function is to generate hyperlinks. For example, when
generating HTML, an anchor for a given section | |
| |
and a link to that section can then be produced with code such as: | |
| |
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 items, it is possible to use generated IDs
as surrogates for nodes when constructing a map. For example, in some implementations,
testing whether a node | |
| |
and then testing for membership of the node-set using: | |
|
The functions included in this section operate on function items, that is, values referring to a function.
Some functions such as
| Function | Meaning |
|---|---|
fn:function-lookup | Returns |
fn:function-name | Returns the name of the function identified by a function item. |
fn:function-arity | Returns the arity of the function identified by a function item. |
fn:function-identity | Returns a string representing the identity of a function item. |
fn:function-annotations | Returns the annotations of the function item. |
Returns
This function is
A call to $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 the 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
If the arguments to
An error is raised if the identified function depends on
components of the static or dynamic context that are not present, or that have
unsuitable values. For example function-lookup( #fn:name, 0 )
if the context value is absent, and function-lookup( #fn:id, 1 ) if the
context value is not a single node in a tree that is rooted at a document node.
The error that is raised is the same as the error that would be raised by the
corresponding function if called with the same static and dynamic context.
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
If the function that is retrieved by
However, the static and dynamic context of the call to
User-defined XSLT or XQuery functions should be accessible to
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
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
| Expression: |
|
|---|---|
| Result: |
|
| Expression: | |
| Result: | An
|
| Expression: | |
| Result: | The result of
calling |
Returns the name of the function identified by a function item.
This function is
If $function refers to a named function, fn:function-name($func)
returns the name of that function.
Otherwise ($function refers to an anonymous function),
fn:function-name($function) returns the empty sequence.
The prefix part of the returned QName is
| Expression: |
|
|---|---|
| Result: | |
| Expression: |
|
| Result: |
|
Returns the arity of the function identified by a function item.
This function is
The $function.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: |
Returns a string representing the identity of a function item.
This function is
The $function.
The returned string has the property that fn:function-identity($f1)
and fn:function-identity($f2) are codepoint-equal if and only if $f1
and $f2 have the same function identity. Apart from this property, the
result is
In the case of maps and arrays, the result follows the following rule:
If $X and $Y are both maps or arrays then fn:function-identity($X)
fn:function-identity($Y) unless
$X and $Y are indistinguishable, that is unless every operator or function applied
to $X returns the same result as for $Y. Even in this case, however, the
result of the comparison fn:function-identity($X) eq fn:function-identity($Y)
is
This function enables applications to test whether two expressions or variables reference the same function item. This may be useful, for example, to allow caching of function results to avoid repeated evaluation. The results of previous function invocations might be held in a map whose key is the function identity.
The function identity, by definition, is generated upon the creation of a function item.
Specific expressions that create function items have their own rules for the identity
of the returned functions: for example, it is guaranteed that evaluation of a function
reference to a system function with no captured context (such as fn:abs#1)
will always return the same function item.
It is not meaningful to store or compare the result of calling
The result of an expression such as function-identity(abs#1) eq function-identity(abs(?))
may be either true or false, because it is abs#1 and abs(?) return the same function item.
Similarly, function-identity({ 1:() }) eq function-identity(map:entry(1, ()))
may be either true or false.
| Expression | Result |
|---|---|
function-identity(abs#1) eq function-identity(abs#1) |
|
function-identity(abs#1) eq function-identity(round#1) |
|
function-identity({ 1: 0 }) eq function-identity({ 1: 1 }) |
|
function-identity([ 0 ]) eq function-identity([ 1 ]) |
|
Returns the annotations of the function item.
This function is
The fn:function-annotations function returns the annotations of
$function as a sequence of
The result is a sequence of map(xs:QName, xs:anyAtomicType*).
If a function (for example, a built-in function) has no annotations,
the result of the function is the empty sequence.
For each annotation, a map is returned, with a single entry. The
key of the map entry is the name of the annotation as an xs:QName.
The value of the entry is the value of the annotation as a sequence of atomic items.
If the annotation has no values, the associated value is the empty sequence.
In the common case where the annotation names are all unique,
the result of the function can readily be converted into single map by applying the function
map:merge.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Maps were introduced as a new datatype in XDM 3.1. This section describes functions that operate on maps.
A map is a kind of item.
K1 and K2 are the fn:atomic-equal($K1, $K2)true.
It is not necessary that all the keys in a map should be of the same type (for example, they can include a mixture of integers and strings).
Maps are immutable, and have no identity separate from their content.
For example, the
A map can also be viewed as a function from keys to associated values. To achieve this, a map is also a
function item. The function corresponding to the map has the signature
function($key as xs:anyAtomicValue) as item()*. Calling the function has the same effect as calling
the $map($key) returns the same result as get($map, $key). For example, if $books-by-isbn
is a map whose keys are ISBNs and whose assocated values are book elements, then the expression
$books-by-isbn("0470192747") returns the book element with the given ISBN.
The fact that a map is a function item allows it to be passed as an argument to higher-order functions
that expect a function item as one of their arguments.
In 4.0, the entries in a map are ordered. The
The entry order of the entries in a map is defined by the function or expression
that creates the map, and affects the result of functions and expressions
that process multiple entries in a map, for example the function for key $k value $v return EXPR. The ordering
is also reflected in the output
of the json and adaptive serialization methods.
Order is maintained in maps for two main reasons:
To make the representation of a map (such as its JSON serialization) easier for human readers to process: for example when visually inspecting the result of a JSON transformation;
To make the result of different implementations interoperable.
Although it is possible to use the ordering of a map to capture
semantic information, the design of functions such as
It is often useful to decompose a map into a sequence of entries, or key-value pairs (in which the key is an atomic item and the value is an arbitrary sequence). Subsequently it may be necessary to reconstruct a map from these components, typically after modification.
There are two conventional ways of representing a map as a sequence of key-value pairs, each with its own advantages and disadvantages. These are described below:
A map can be represented as a sequence of single-entry maps.
It is possible to decompose any map into a sequence of
For example the map
{ "x": 1, "y": 2 } can be decomposed to the sequence ({ "x": 1 }, { "y": 2 }).
A map can be represented as a sequence of JNodes.
A JNode holds the map key in its
The following table summarizes the way in which these two representations can be used to compose and decompose maps:
| Operation | Single-Entry Maps | JNodes |
|---|---|---|
Decompose a map |
|
|
Compose a map |
|
|
Create a single entry |
|
|
Extract the key part of a single entry |
|
|
Extract the value part of a single entry |
|
|
It is also possible to decompose a map using:
The function
The expression for key $k value $v in $map return ....
The examples below show several ways of constructing a map with the same entries as an input map, but with the entries sorted by key.
Using map:entries and map:merge:
Using JNodes:
Using map:for-each:
Using an XQuery FLWOR expression:
The XDM data model (
dm:empty-map constructs the empty map.
dm:map-put adds or replaces an entry in a map.
dm:iterate-map applies a supplied function to every entry in a map.
The functions in this section are all specified by means of equivalent expressions that either call these primitives directly, or invoke other functions that rely on these primitives. The specifications avoid relying on XPath language constructs that manipulate maps, such as map constructor syntax, lookup expressions, or FLWOR expressions. This is done to allow these language constructs to be specified by reference to this function library, without risk of circularity.
There is one exception to this rule: for convenience, the notation {} is used to represent
the empty map, in preference to a call on dm:empty-map().
The formal equivalents are not intended to provide a realistic way of implementating the
functions (in particular, any real implementation might be expected to implement
map:find().The functions defined in this section use a conventional namespace prefix map, which
is assumed to be bound to the namespace URI http://www.w3.org/2005/xpath-functions/map.
The function call map:get($map, $key) can be used to retrieve the value associated with a given key.
There is no operation to atomize a map or convert it to a string. The function
Note that when the required type of an argument to a function such as
| Function | Meaning |
|---|---|
map:build | Returns a map that typically contains one entry for each item in a supplied input sequence. |
map:contains | Tests whether a supplied map contains an entry for a given key. |
map:empty | Returns true if the supplied map contains no entries. |
map:entries | Returns a sequence containing all the key-value pairs present in a map, each represented
as a |
map:entry | |
map:filter | Selects entries from a map, returning a new map. |
map:find | Searches the supplied input sequence and any contained maps and arrays for a map entry with the supplied key, and returns the corresponding values. |
map:for-each | Applies a supplied function to every entry in a map, returning the
|
map:get | Returns the value associated with a supplied key in a given map. |
map:items | Returns a sequence containing all the values present in a map, in order. |
map:keys | Returns a sequence containing all the keys present in a map. |
map:keys-where | Returns a sequence containing selected keys present in a map. |
map:merge | Returns a map that combines the entries from a number of existing maps. |
map:put | 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. |
map:remove | Returns a map containing all the entries from a supplied map, except |
map:size | Returns the number of entries in the supplied map. |
Returns a map that typically contains one entry for each item in a supplied input sequence.
This function is
Informally, the function processes each item in $input in order.
It calls the $key function on that item to obtain a sequence of key values,
and the $value function to obtain an associated value.
Then, for each key value:
If the key is not already present in the target map, the processor adds a new key-value pair to the map, with that key and that value.
If the key is already present, the processor combines the new value for the key
with the existing value; the way they are combined is determined by the
duplicates option.
By default, when two duplicate entries occur:
A single combined entry will be present in the result.
This entry will contain the
The position of the combined entry in the
The key of the combined entry
will correspond to the key of one of the duplicates: it is
xs:dateTime values in different timezones.)
The $options argument can be used to control the
way in which duplicate keys are handled.
The $options map are as follows:
| Key | Value | Meaning |
|---|---|---|
| Determines the policy for handling duplicate keys: specifically, the action to be
taken if two entries in the input sequence have key values
K1 and K2 where K1 and K2 are the
| |
"reject" | Equivalent to supplying a function that raises a dynamic error with error code "FOJS0003". The effect is that duplicate keys result in an error. | |
"use-first" | Equivalent to supplying the function fn($a, $b){ $a }.
The effect is that the first of the duplicates is chosen.
| |
"use-last" | Equivalent to supplying the function fn($a, $b){ $b }.
The effect is that the last of the duplicates is chosen.
| |
"use-any" | Equivalent to supplying the function fn($a, $b){ one-of($a, $b) }
where one-of chooses either $a or $b in
an | |
"combine" | Equivalent to supplying the function fn($a, $b){ $a, $b }
(or equivalently, the function op(",")).
The effect is that the result contains the | |
function(*) |
A function with signature fn(item()*, item()*) as item()*.
The function is called for any entry in the input sequence that has the
X => F(Y) => F(Z).
| |
The effect of the function is equivalent to the result of the following XPath expression.
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.
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.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | A map whose keys are employee |
| Expression: | |
| Result: | A map whose keys are employee |
| Expression: | |
| Result: | A map whose keys are employee |
| Expression: | |
| Result: | A map allowing efficient access to every element in a document by means
of its |
| Expression: | |
| Result: |
Tests whether a supplied map contains an entry for a given key.
This function is
The function true if the $map contains an entry with the $key; otherwise it returns false.
The effect of the function is equivalent to the result of the following XPath expression.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
map:contains($week, 2) |
|
map:contains($week, 9) |
|
map:contains({}, "xyz") |
|
map:contains({ "xyz": 23 }, "xyz") |
|
map:contains({ "abc": 23, "xyz": () }, "xyz") |
|
Returns true if the supplied map contains no entries.
This function is
The function returns true if and only if $map contains no
entries, that is, if map:size($map) eq 0.
The effect of the function is equivalent to the result of the following XPath expression.
| Expression | Result |
|---|---|
map:empty({}) |
|
map:empty({ 1: () }) |
|
Returns a sequence containing all the key-value pairs present in a map, each represented
as a
This function is
The function $map argument and returns the key-value pairs that are present in the map as
a sequence of
The effect of the function is equivalent to the result of the following XPath expression.
| Expression | Result |
|---|---|
This function is
The function $key, and its associated value is $value.
The effect of the function is equivalent to the result of the following XPath expression.
The function
The
| Expression | Result |
|---|---|
map:entry("M", "Monday") |
|
$predicate callback function may return the empty sequence (meaning false).$action callback function now accepts an optional position argument.Selects entries from a map, returning a new map.
This function is
The function $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. A return value of () from the
predicate is treated as false.
The function supplied as $predicate takes three arguments. It is called
supplying the key of the map entry as the first argument, the associated value as
the second argument, and the 1-based integer position as the third argument.
The relative $map.
The effect of the function is equivalent to the result of the following XPath expression.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Searches the supplied input sequence and any contained maps and arrays for a map entry with the supplied key, and returns the corresponding values.
This function is
The function $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 key-value 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 the empty sequence, map, or array, or if the requested $key is not found,
the result will be a zero-length array.
| Variables | |
|---|---|
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
$action callback function now accepts an optional position argument.Applies a supplied function to every entry in a map, returning the
This function is
The function $map argument and applies the supplied function
to each entry in the map, in
The function supplied as $action takes three arguments. It is called
supplying the key of the map entry as the first argument, the associated value as
the second argument, and the 1-based integer position as the third argument.
The function is defined as follows, making use of primitive constructors and accessors defined
in
| Expression: | |
|---|---|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
This XQuery example converts the entries in a map to attributes on a newly constructed element node: | |
The result is the element | |
| Expression: | |
| Result: | |
Returns the value associated with a supplied key in a given map.
This function is
The function $map that has
the $key. If there is such an entry, it returns the associated value;
if not, it returns the supplied $default value.
The function is defined as follows, making use of primitive constructors and accessors defined
in
A return value of () from (), or it could
indicate that the key is not present in the map. The two cases can be distinguished by
either by calling $default value to return a value known never to appear in the map.
Invoking the get with no $default
argument: that is, when $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').
| Variables | |
|---|---|
| Expression | Result |
|---|---|
map:get($week, 4) |
|
map:get($week, 9) |
|
map:get(map:entry(7,()), 7) |
|
map:get($week, 7, "n/a") |
|
Returns a sequence containing all the values present in a map, in order.
This function is
The function $map argument and returns the values that are present in the map as
a sequence, in
The effect of the function is equivalent to $map?*.
The effect of the function is equivalent to the result of the following XPath expression.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: |
Returns a sequence containing all the keys present in a map.
This function is
Informally, the function $map argument and returns
the keys that are present in the map as a sequence of atomic items,
in
The effect of the function is equivalent to the result of the following XPath expression.
The number of items in the result will be the same as the number of entries in the map, and the result sequence will contain no duplicate values.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: | |
| Result: |
$predicate callback function may return the empty sequence (meaning false).Returns a sequence containing selected keys present in a map.
This function is
Informally, the function $map argument. The
$predicate function takes the key and 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 predicate function returns true, in
A return value of () from the predicate function is
treated as false.
The effect of the function is equivalent to the result of the following XPath expression.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
duplicates option.Returns a map that combines the entries from a number of existing maps.
This function is
The function $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.
The $options argument takes the same values (with the same meanings)
as the map:merge, the default for duplicate keys is use-first.
The difference is for backwards compatibility reasons.
With the default options, when duplicate entries occur:
There will be a single entry in the result corresponding to a set of duplicate entries in the input.
The value of that entry will be taken from the first of the duplicates.
The position of that entry in the
The key of the combined entry
will correspond to the key of one of the duplicates: it is
xs:dateTime
values in different timezones.)
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 the empty sequence, the result is the empty map.
If the input is a sequence of length one, the result map is indistinguishable from the input map.
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.
The XSLT 3.0 recommendation included a specification of this function that incorrectly used
the option value { 'duplicates': 'unspecified' } in place of
{ 'duplicates': 'use-any' }. XSLT implementations wishing to
preserve backwards compatibility
| Variables | |
|---|---|
| Expression: |
|
|---|---|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
|
| Expression: | |
| Result: |
|
| Expression: | |
| Result: |
|
| Expression: | |
| Result: |
|
| Expression: | |
| Result: |
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.
This function is
If $map contains an entry whose key is the $key, the function returns
a map in which that entry is replaced (at the same relative position)
with a new entry whose value is $value. It is
$key.
All other entries in the map are unchanged, and retain their relative order.
Otherwise, when $map contains no such entry, the function
returns a map containing all entries from the supplied $map
(retaining their relative position) followed by a new entry whose key
is $key and whose associated value is $value.
The function is defined as follows, making use of primitive constructors and accessors defined
in
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.
It is possible to force the new entry to go at the end of the sequence by calling
map:remove before calling map:put.
It can happen that the supplied $key is the $map, but nevertheless
differs from the existing key in some way:
for example, it might have a different type annotation, or it might be an xs:dateTime
value in a different timezone. In this situation it is
$key or the existing key.
| Variables | |
|---|---|
| Expression: |
|
|---|---|
| Result: | |
| Expression: |
|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns a map containing all the entries from a supplied map, except
This function is
The function $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 relative position of retained entries in the result map
is the same as their relative position in $map.
The effect of the function is equivalent to the result of the following XPath expression.
| Variables | |
|---|---|
| Expression: |
|
|---|---|
| Result: | |
| Expression: |
|
| Result: | |
| Expression: |
|
| Result: | |
| Expression: |
|
| Result: |
Returns the number of entries in the supplied map.
This function is
The function $map argument and returns the number of entries that are present
in the map.
The effect of the function is equivalent to the result of the following XPath expression.
| Expression | Result |
|---|---|
map:size({}) |
|
map:size({ "true": 1, "false": 0 }) |
|
The
This section describes the mappings used by this function.
This mapping is designed with three objectives:
It should be possible to represent any XML element as a map suitable for JSON serialization.
The resulting JSON should be intuitive and easy to use.
The JSON should be consistent and stable: small variations in the input should not result in large variations in the output.
Achieving all three objectives requires design compromises. It also requires sacrificing some other desiderata. In consequence:
The conversion is not lossless (see
The conversion is not streamable.
The results are not necessarily compatible with those produced by other popular libraries.
The requirement for consistency and stability is particularly challenging. An element such as
<name>John</name> maps naturally to the map { "name": "John" };
but adding an attribute (so it becomes <name role="first">John</name>)
then requires an incompatible change in the JSON representation. The format could be made extensible
by converting <name>John</name> to { "name": {"#content":"John"} }
and <name role="first">John</name> to
{ "name": { "@role":"first", "#content":"John" } },
but this imposes unwanted complexity on the simplest cases. The solution adopted is threefold:
It is possible to analyze a corpus of XML documents to develop a conversion plan, which can then be applied consistently to individual input documents, whether or not these documents were present in the corpus. The conversion plan can be serialized and subsequently reused, so that it can be applied to input documents that might not have existed at the time the conversion plan was formulated.
Alternatively, the function can make use of schema information where available, so it considers not just the structure of an individual element instance, but the rules governing the element type.
It is possible to override the choices made by the system, and explicitly specify the format to be used for elements or attributes having a given name.
The key challenge in mapping XML to JSON is in deciding how element content is to be represented. To illustrate the variety of mappings that are possible, the following table lists some examples of typical XML elements and their JSON equivalents:
| XML element | JSON equivalent |
|---|---|
This specification defines a
number of named mappings, called
The layout to be used for a specific elements can be explicitly selected by
supplying a conversion plan as input
to the
It is possible to construct a conversion plan by analyzing a corpus of documents
using the
It is also possible to construct a conversion plan manually, or to modify
the conversion plan produced by the
In the absence of an explicit conversion plan, if the data has been schema-validated, the layout is inferred from the content model for the element type as defined in the schema.
When the data is untyped and no specific layout has been selected, a default layout is chosen based on the properties of the individual element instance.
The advantage of using schema information is that it gives a consistent representation for all elements of a particular type, even if they vary in content: for example if an element type allows optional attributes, the JSON representation will be consistent between those elements that have attributes and those without. In the absence of a schema, consistency can be achieved by supplying a conversion plan that applies uniformly to multiple documents.
The different layouts available are defined in the following sections. For each layout there is a table showing:
$elements argument; when used to convert
a descendant element, the corresponding key-value pair may appear as part of a larger map, depending
on the layout chosen for its parent element..
The
xsi:nil="true". These rules only apply if the
element has been schema-validated.
empty layout cannot be used for
an element that is not empty. In such a situation the recovery action is as follows, in order:
Attributes are dropped, and if this is sufficient to enable the layout to be used, then the element is converted without its attributes.
If the type of an element or attribute in the conversion
plan is given as boolean or numeric, but the actual
value of the element or attribute is not castable to xs:boolean
or xs:numeric respectively, then the node is output ignoring
the type property, that is, as an instance of xs:untypedAtomic.
If the conversion plan supplies a fallback layout (an entry with key
"*"), then the fallback layout is used.
The
The rules for selecting the layout for a particular element are given later,
in
Note that it is possible to request any layout for any element. If an inappropriate layout
is chosen for a particular element (for example, empty layout for an element
that is not empty), then the rules for that layout specify what happens.
It is possible to specify a fallback layout for use when the selected layout fails: this will typically
be a layout such as xml or mixed that can handle any element.
Acknowledgements for this categorization: see
| Layout name |
|
|---|---|
| Usage | Intended for XML elements that have no content and no attributes. |
| Example input | |
| Example output | |
| Mapping rules | The content is represented by the zero-length |
| Mapping for nilled elements | The content is represented by the QName
|
| Errors | Attributes are discarded, along with child comment nodes, processing instructions, and whitespace-only text nodes. If any other child nodes are present, this layout fails. |
| Layout name |
|
|---|---|
| Usage | Intended for XML elements that have no content but may have attributes. |
| Example input | |
| Example output | |
| Mapping rules | The content is represented by a map containing one entry for each
attribute in the XML element; if there are no attributes, the content
is represented as the empty map.
The rules for attribute names are
defined in |
| Mapping for nilled elements | An additional key-value pair |
| Errors | Child comment nodes, processing instructions, and whitespace-only text nodes are discarded. If any other child nodes are present, this layout fails. |
| Layout name |
|
|---|---|
| Usage | Intended for XML elements that have simple content and no attributes. |
| Example input | |
| Example output | |
| Mapping rules | The element is atomized and the resulting atomized value is handled
as described in If the element is untyped, the atomized value will always
appear in the result as an instance of |
| Mapping for nilled elements | The content is represented by the value |
| Errors | Attributes are discarded, along with child comment nodes and processing instructions; whitespace is retained. If any child elements are present, this layout fails. |
| Layout name |
|
|---|---|
| Usage | Intended for XML elements that have simple content and (optionally) attributes. |
| Example input | |
| Example output | |
| Mapping rules | The element is represented by a map containing one entry for each
of its attributes, plus an entry with key The rules for attribute names are
defined in If the element is untyped, the value of each attribute, and of If the element has been schema-validated, the types of the items in the atomized value are retained. |
| Mapping for nilled elements | The |
| Errors | Child comment nodes and processing instructions are discarded; whitespace is retained. If any child elements are present, this layout fails. |
| Layout name |
|
|---|---|
| Usage | Intended for XML elements that act as wrappers for a list of child elements, all having the same element name; neither the element itself nor any of its children should have any attributes. The expected child element name may be present in the conversion plan. The names of the child elements are not retained in the output. |
| Example input (1) | |
| Example output (1) | |
| Example input (2) | |
| Example output (2) | |
| Mapping rules | The content is represented by an array, whose members correspond one-to-one with the children of the element. Each child element is converted to a map as if it were a top-level element: the resulting map contains a single key-value pair. The key part is discarded, and the value part is used as a member in the resulting array. If there are no children then the content is represented by the empty array. |
| Mapping for nilled elements | The array is replaced by the value |
| Errors | Attributes are discarded for both the element itself, and its children. Comments, processing instructions, and whitespace text nodes in the content are discarded. This layout fails if any child element is present with a name that differs from the expected child element name, or if there are non-whitespace text node children. |
| Layout name |
|
|---|---|
| Usage | Intended for XML elements that act as wrappers for a list of child elements, all having the same element name. The wrapper element may have attributes, but the children should not. and the name of the child elements is retained in the output. |
| Example input (1) | |
| Example output (1) | |
| Example input (2) | |
| Example output (2) | |
| Mapping rules |
The content is represented by a map containing one entry for each
attribute in the XML element, plus a property named after the
child elements (the If there are no children and the element is untyped (which can occur when
this layout is chosen explicitly via the options to |
| Mapping for nilled elements | The array-valued entry in the result is replaced by the entry
|
| Errors | Any attributes on the element's children are discarded. Comments, processing instructions, and whitespace text nodes in the content are discarded. This layout fails if any child element is present with a name that differs from the expected child element name, or if there are non-whitespace text node children. |
| Layout name |
|
|---|---|
| Usage | Intended primarily for XML elements that contain multiple child elements, with different names, where the order of the child elements is not significant. Also used for elements whose content is a single element node child. The element may or may not have attributes. |
| Example input (1) | |
| Example output (1) | |
| Example input (2) | |
| Example output (2) | |
| Mapping rules |
The content is represented by a map containing one entry for each attribute in the XML element, plus one entry for each child element, whose value is formatted according to the rules for that element. If two or more child elements have the same name, or names that are represented by
the same string (taking into account the chosen The |
| Mapping for nilled elements | Alongside any attributes, the value includes the additional entry
|
| Errors | Although this layout is intended primarily for elements whose children are unordered and uniquely named, it is also viable to use it in cases where elements can repeat, so long as order relative to other elements is not significant. Comments, processing instructions, and whitespace text nodes in the content are discarded. This layout fails if there are non-whitespace text node children. |
| layout name |
|
|---|---|
| Usage | Intended for XML elements that contain a sequence of element node children, whose order is significant. The element may or may not have attributes. |
| Example input | |
| Example output | |
| Mapping rules | The mapping rules are identical to the rules for the |
| Mapping for nilled elements | A nilled element is indicated by including an additional map
|
| Errors | This layout fails if there are non-whitespace text node children. |
| Layout name |
|
|---|---|
| Usage | Intended for XML elements that contain mixed content (that is, elements that contain both child elements and child text nodes, intermingled). The element may or may not have attributes. |
| Example input | |
| Example output | |
| Mapping rules | The content is represented by an XDM array containing one entry for each attribute in the XML element, and one entry for each child node, in order. Each attribute node is represented within this array by a single-entry
map: the rules for attribute names are
defined in Child nodes are represented within the array as follows: A text node child is represented as an atomic item of type
An element node child is represented as a map containing a single entry, with the key representing the element name and the value representing the element's content, formatted according to the chosen layout for that element. A comment node is represented as a map containing a single
entry whose key is the string A processing instruction node is represented as a map containing
a single entry whose key is the string Whitespace text nodes are retained. |
| Mapping for nilled elements | A nilled element is indicated by including an additional map
|
| Errors | All children are retained, including comments, processing instructions, and text nodes, whether or not they are whitespace-only. This layout never fails. |
Serialized layout allows an element node to be represented as lexical XML, contained within a map.
| Layout name |
|
|---|---|
| Usage | This layout is useful when the input contains a mix of structured data and marked-up textual content. It allows the textual content to be output as serialized XML. It is also used as a fallback representation when the selected element layout is inappropriate for a particular element. |
| Example input | |
| Example output | |
| Mapping rules | The element node is serialized as if by the The serialization parameter The serialization parameter The serialization parameter Other serialization parameters take their default values. The outermost element name will typically be repeated, for example
|
| Mapping for nilled elements | A nilled element is represented using its normal XML serialization,
that is, the output serialization includes the attribute |
| Errors | This layout never fails. |
It is possible to create a conversion plan by analyzing a collection of sample input documents.
The function
The output of this function (the conversion plan) holds information about how elements and attributes (identified by name) should be converted.
For elements, the information is primarily a mapping from element names
(xs:QName instances) to layout names. In some cases additional information beyond
the layout name is also included. The conversion plan is represented as an XDM map, whose structure
is defined in this specification. A conversion plan can be constructed directly, or the plan
produced by calling
The
Let $EE be
the set of all elements named N, specifically
$input/descendant-or-self::*[node-name(.) eq N].
If empty($EE/(* | text()) (that is, if there
are no child elements or text nodes) then:
If empty($EE/@*) (that is, if there
are no attributes),
then the layout is empty: see
Otherwise, the layout is empty-plus: see
If empty($EE/*) (that is, if there are no child elements) then:
If empty($EE/@*) (that is, if there
are no attributes)
then the layout is simple: see
Otherwise, simple-plus: see
The plan also includes the property type. If all the elements
in $EE are castable as xs:boolean, then the type is boolean;
otherwise, if all the elements in $EE as castable as xs:numeric,
then the type is numeric; otherwise, the type is string.
If empty($EE/text()[normalize-space()]) (that is, there are no text node
children other than whitespace), then:
If all-equal($EE/*/node-name()) and exists($EE/*[2])
(that is, if all child elements have the same name, and at least one element has multiple child
elements), then:
If empty($EE/@*) (that is, if there
are no attributes)
then list: see
Otherwise, list-plus: see
If every $e in $EE satisfies all-different($e/*/node-name())
(that is, the child elements are uniquely named among their siblings),
then record: see
Otherwise, sequence: see
Otherwise, mixed: see
For elements with simple content (more specifically, elements where the chosen layout is
simple or simple-plus) the conversion plan also includes an entry indicating
whether the content should be represented as a boolean, a number, or a string. If every instance of
the element name has content that is castable to xs:boolean, the plan indicates
"type": "boolean". If every instance of
the element name has content that is castable to xs:numeric, the plan indicates
"type": "numeric". In other cases, the plan indicates "type": "string"; however,
this may be omitted because it is the default.
For attributes, the conversion plan identifies whether attributes (with a given name)
should be represented as booleans, numbers, or strings; alternatively, it may indicate
that attributes with a given name should be discarded. For every distinct attribute name present
in the input, an entry is output associating the attribute name with one of the types
boolean or numeric; the entry is generally omitted when the values are to
be represented as strings, though the type can also be given explicitly as string.
An entry with type boolean
is generated for an attribute name if all the attributes with that name are castable as xs:boolean.
Similarly, an entry with type numeric is generated for an attribute name if all the
attributes with that name are castable as xs:numeric. In other case, the attributes are
treated as being of type string. Entries with type
string may be omitted, since that is the default.
The entry for an attribute may also specify "type": "skip"
to indicate that the attribute should be discarded.
A plan that is produced by analyzing a corpus of input documents can then be customized by the user if required. For example:
If simple layout is chosen for a particular element name, but
it is known that some documents might be encountered in which that element
has attributes, then simple might be changed to simple-plus.
If record layout is chosen for a particular element name, but
it is known that some documents might be encountered in which child elements
can be repeated, then record might be changed to sequence.
If a generated plan determines that phone numbers should be represented as numbers, it might be modified to treat them as strings.
The conversion plan is a map of type map(xs:string, record(*)).
The key is an element or attribute name, representing element names in the form Q{uri}local,
and attributes in the form @Q{uri}localnotation: in both cases the Q{uri}
part xs:QName instances to allow the plan to be serialized
in JSON format.
A more detailed definition of the structure is given in
A small example might be (in its JSON serialization):
xsi namespaceThis section defines modifications to the above rules that apply to elements having
attributes in the xsi namespace (that is,
http://www.w3.org/2001/XMLSchema-instance).
When analyzing a corpus using xsi:nil="true" are ignored. If all
elements with a given name have this attribute, allocate the layout mixed.
When deciding whether an element has any attributes (for example to decide
between the layouts empty and empty-plus),
all attributes in the xsi namespace are ignored.
When converting an individual element to a map,
all attributes in the xsi namespace are ignored.
Notwithstanding the above, elements having the nilled property
(which essentially means they are schema-validated and have the attribute xsi:nil="true"),
are treated specially by each of the possible element layouts.
This section provides a definition of the structure of the
conversion plan that is output by the
The structure is defined by the following item type:
This makes use of two built-in record definitions defined below.
The rules relating to this structure are as follows:
The keys of the map entries are strings of the form:
local-name representing the name of an element in no namespace.
Q{uri}local-name representing the name of an element in a namespace.
* representing a fallback rule for use with elements where either
(a) there is no more specific rule, or (b) processing using the selected layout
fails.
@local-name representing the name of an attribute in no namespace.
@Q{uri}local-name representing the name of an attribute in a namespace.
Any entries whose keys are not in this format will be ignored.
If the key starts with @, the corresponding value must be
of type fn:attribute-conversion-plan-record; otherwise, it
must be of type fn:element-conversion-plan-record.
In an
The layout entry is always present.
The child entry is present if and only if the value of layout is
list or list-plus. It represents an element name in the format
local-name for a name in no namespace, or Q{uri}local-name for a
name in a namespace.
The type entry is present if and only if the
layout is simple or simple-plus.
In an
The type entry is always present.
If additional entries (beyond those described above) are present in any of the maps, they are ignored, provided that the map is coercible to the given type definition.
The fallback rule (with key "*") is used to process elements whose name has no
specific entry, and also for elements where normal processing fails (for example when the
selected layout is "empty", but the element has children). If no fallback rule
is present then "error" is assumed: this causes processing to fail with a dynamic
error. The fallback rule will typically set the layout property to one of the following:
error: this causes the function to fail with a dynamic error.
deep-skip: this causes the element and its content (recursively)
to be omitted from the output.
mixed: this causes the element to be output using layout mixed
xml: this outputs the element to be output using layout xml,
which represents the content as a string containing serialized XML.
However, any layout may be used as the fallback; if it fails, the error is unrecoverable.
This record type represents a plan for converting elements
to maps during evaluation of
| Name | Meaning |
|---|---|
|
Defines the overall strategy for converting the element content.
|
|
For list layouts, defines the name of the child element type contained in the list.
|
|
For elements with simple content, defines whether they should be represented as numbers or booleans instead of the default representation as strings.
|
This record type represents a plan for converting attributes
to atomic items during evaluation of
| Name | Meaning |
|---|---|
|
Defines whether attributes should be represented as numbers or booleans instead of the default representation as strings; alternatively, indicates that the attribute should be omitted.
|
As an alternative to constructing a conversion plan by analyzing a corpus of specimen documents, conversion may be controlled using type annotations derived from schema validation.
If the function xs:anyType or xs:untyped, then
the following rules apply:
This section uses the notation {prop} to refer to properties
of schema components, as defined in {open content} will inevitably be absent.
Let zeroLength(ST) be true for a simple type ST
if any of the following conditions is true:
ST.{variety} = list, and ST.{facets} includes
a length or maxLength facet whose value is 0 (zero).
ST.{variety} = atomic, and ST.{facets} includes
a length or maxLength facet whose value is 0 (zero).
ST.{variety} = atomic, and ST.{facets} includes
an enumeration facet constraining the value to be zero-length.
ST.{variety} = atomic, and ST.{facets} includes
a pattern facet with the value "" (a zero-length string).
If T is a simple type:
If zeroLength(T), then the selected layout is empty
(see
Otherwise,
the selected layout is simple (see boolean if T is derived from
xs:boolean; numeric if T is derived from
xs:decimal, xs:double, or xs:float;
or string otherwise.
Otherwise (if T is a complex type):
Let $noAttributes be true if
T.{attribute uses} is empty and T.{attribute wildcard}
is absent.
If T.{content type}.{variety} = empty, then:
If $noAttributes and if empty layout is not disabled,
then the selected layout is empty (see
Otherwise, the selected layout is empty-plus (see
If T.{content type}.{variety} = simple
(a complex type with simple content), then:
Let ST be T.{content type}.{simple type definition}
(the corresponding simple type).
If zeroLength(ST), then:
If $noAttributes, the selected layout is empty
(see
Otherwise, the selected layout is empty-plus
(see
Otherwise:
If $noAttributes, the selected layout is
simple (see
Otherwise the selected layout is simple-plus
(see
In both cases the selected type is one of boolean
numeric, or string, chosen in the same way
as for elements having a simple type.
If T.{content type}.{variety} = element-only (a complex type with
an element-only content model):
Let $noWildcards be true if T.{content type}.{open content}
is absent, and T.{content type}.{particle}, expanded recursively, contains
no wildcard term.
Let $childCardinalities be a set of (xs:QName,
xs:double) pairs
representing the expanded names of the element declaration terms within
T.{content type}.{particle},
expanded recursively, and for each one, the maximum number of occurrences of elements
with that name, computed
using the value of the {maxOccurs} property of the particles at each level, taking the value
unbounded as positive infinity.
If $noWildcards is true, and if $childCardinalities
contains a single entry, and that entry has a cardinality greater than one, then:
If $noAttributes then
the selected layout is list (see
Otherwise, the selected layout is list-plus
(see
If $noWildcards is true, and if every entry in $childCardinalities
has a cardinality of one, then the selected layout is
record (see
Otherwise, the selected layout is sequence (see
Otherwise (that is, when T.{content type}.{variety} = mixed, the
selected layout is mixed (see
For attribute nodes, the selected type is boolean if the type annotation is derived from
xs:boolean; numeric if the type annotation is derived from
xs:decimal, xs:double, or xs:float;
and string otherwise.
The various layouts available for elements are described in
If an explicit layout is given for the element name of E in the
conversion plan supplied to the deep-skip,
then no output is produced for that element. If the selected layout is error,
then the function fails with a dynamic error.
If the selected layout fails for the element instance, then
the fallback layout (identified with the key "*" in the conversion plan)
is used; in the absence of a fallback layout, the function fails with a dynamic error.
Otherwise (when no explicit layout is given for E), if the
type annotation of the element is something other than xs:untyped
or xs:anyType, then a schema-determined layout is used as defined
in
Otherwise, if the conversion plan supplies a fallback layout
(identified with the key "*"), then the fallback layout is used.
If the above rules do not provide a layout for E, then
a conversion plan for E is determined by applying the rules in
The name-format option gives control over how element and attribute names are formatted.
There are four options:
The default option (which may be explicitly requested by specifying "name-format": "default")
retains the namespace URI for any element that is either (a) the top-level element of a tree being
converted, or (b) has a name that is in a different namespace from its parent element. In such cases
the format "Q{uri}local" is used. For other elements, the name is output using the
local part of the element name alone. For attributes, the form "Q{uri}local" is used
for an attribute in a namespace, and the local name alone is used for a no-namespace name.
Namespace prefixes are not retained.
The option eqname uses the format "Q{uri}local" for all
element and attribute names that are in a namespace, or the local name alone for all names
that are not in a namespace.
The option local discards all namespace information: all elements and attributes
are output using the local name alone.
The option lexical outputs element and attribute names in the form
obtained by calling the function
Regardless of the chosen name-format, and regardless of the above rules,
attributes in the xml namespace (http://www.w3.org/XML/1998/namespace)
are output using a lexical QName, with the prefix xml.
Attribute names in the output are typically prefixed with the character "@".
The option attribute-marker allows this to be changed to a different
prefix or none.
Whichever format of names is chosen, if the rules for the selected layout would result in an output
map having two entries with the same key, the conflict is resolved by combining these
entries into an array. For example if name-format is set to local
then the element <data x:val="3" y:val="4"/> becomes either
{ "data": { "@val": ["3", "4"] } } or (because attribute order is unpredictable)
{ "data": { "@val": ["4", "3"] } }.
The conversion plan may indicate that element content is to be output
as type string, numeric, or boolean: the default
is string. In the case of untyped elements and attributes, the value is
output as an instance of a string, numeric, or boolean type, according to this
prescription. Specifically:
If the prescribed type is boolean and the value is castable
as xs:boolean, then it is output as an instance of xs:boolean.
If the prescribed type is numeric and the value is castable
as xs:numeric, then it is output as an instance of xs:integer,
xs:decimal, or xs:double depending on the lexical form of the
value, following the same rules as for XPath numeric literals. For example, "-1"
becomes an xs:integer, 12.00 becomes an xs:decimal,
and 1e-3 becomes an xs:double. The special xs:double
values NaN and INF (which cannot be used as numeric literals)
are also recognized.
In all other cases the value is output as an instance of xs:untypedAtomic,
retaining its original lexical form.
Where the element or attribute is schema-validated, however:
If an element has the nilled property (that is, xsi:nil="true"),
then the mapping for nilled elements with the chosen layout is used.
Let AV be the typed value of the node (that is, the result of atomization).
If, however, an element is annotated with a type that does not allow atomization
(specifically, a complex type with element-only content) then let AV be the string value
of the element, as an atomic item of type xs:untypedAtomic.
If an attribute is annotated as having a simple type of {variety} list,
or if an element using layout simple or simple-plus
is annotated as having either a simple type of {variety} list
or a complex type with simple content of {variety} list
then the atomized value AV is represented in the result as the array
represented by the XPath expression array{AV}. This applies whether or not the
atomized value actually contains multiple atomic items. The individual atomic items in the array retain their type,
for example items of type xs:date remain items of type xs:date
in the result.
In all other cases AV will be a single atomic item, and this value
is used
Atomic items in the result of the
This section is non-normative. Its purpose is to explain what information available
in the XDM nodes supplied as input to the
name-format is default or eqname,
then local names and namespace URIs of elements and attributes are retained,
but namespace prefixes are lost. If the chosen name-format is
lexical, then prefixes are retained but namespace URIs are lost.
If the chosen name-format is local then only
local names are retained; namespace URIs and prefixes are lost.
In addition, element names are lost when the parent element is mapped
using list layout: see
sequence, mixed or xml layouts.
empty,
empty-plus, list, list-plus, record,
or sequence layouts. Non-whitespace text nodes are never discarded.
is-id,
is-idref, and is-nilled properties of a node are lost.
record layout is used and the element has multiple children with the same name.
xsi namespace (for example,
xsi:type and xsi:nil) are not represented in the result. .
The following examples show the effect of transforming some simple XML documents with default options,
and then serializing the result as JSON with indent is set to true.
The actual indentation is implementation dependent.
| XDM element | JSON serialization of result |
|---|---|
The following more complex example demonstrates a case where the default conversion is inadequate (for example, it wrongly assumes that for the third production, the order of child elements is immaterial). A better result, shown below, can be achieved by using a schema-aware conversion.
| XDM element | JSON serialization of result |
|---|---|
In the above example, the schema used to validate the source document was simplified to eliminate
options that do not actually arise in this input instance (such as the g:string
element having attributes). This is a legitimate technique that may be useful when trying to obtain
the simplest possible JSON representation.
Further improvements to the usability of the JSON output could be achieved by doing some
simple transformation of the XML prior to conversion. For example, the name
attribute of various productions could be converted to a child element, and
<ref name="x"/> could be transformed to <ref>x</ref>.
Analyzes sample data to generate a conversion plan suitable for use by the
This function is
The function takes as input a collection of document and element nodes and analyzes the trees rooted at these
nodes to determine a conversion plan for converting elements in these trees to maps, suitable for serialization
in JSON format. The conversion plan can be used
The rules followed by the function, and the detailed format of the conversion plan, are described
in
The effect of the function is equivalent to the result of the following XQuery expression.
The conversion plan is organized by element and attribute name, so its effectiveness depends on the
$input collection being homogenous in its structure, and representative of the documents
that will subsequently be converted using the
This function is separate from the
The collection of documents that need to be analyzed to establish an effective conversion plan might be much smaller than the set of documents actually being converted.
Conversely, it might be that only a small number of documents need to be converted at a particular time, but the conversion plan used needs to take into account variations that might exist within a larger corpus.
If JSON output is required in a particular format, it might be necessary to fine-tune the automatically generated conversion plan to take account of these requirements.
It might be necessary to devise a conversion plan that can be used to convert individual documents as they arrive over a period of time, and to ensure that the same conversion rules are applied to each document even though documents might exhibit variations in structure.
The conversion plan is human-readable, which can help in understanding why the
output of
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Converts an element node into a map that is suitable for JSON serialization.
This function is
This function returns a map derived from
the element node supplied in $element. The map is in a form
that is suitable for JSON serialization, thus providing a mechanism for conversion
of arbitrary XML to JSON.
The map that is returned will always be a
The entries that may appear in the $options map are as follows.
The
| Key | Value | Meaning |
|---|---|---|
| A conversion plan, supplied as a map whose keys represent element
and attribute names. The plan might be generated using the function
| |
| A string that is prepended to any key value in the output that represents
an XDM attribute node in the input. The string may be empty. If, after applying the requested
prefix (or no prefix) there is a conflict between the names of attributes and child elements,
then the requested prefix (or lack thereof) is ignored and the default prefix "@"
is used.
| |
| Indicates how the names of element and attribute nodes are handled.
| |
lexical | Names are output in the form produced by the | |
local | Names are output in the form produced by the | |
eqname | Names in a namespace are output in the form "Q{uri}local".
Names in no namespace are output using the local name alone. | |
default | An element name is output as a local name alone if either (a) it is
a top-level element and is in no namespace, or (b) it is in the same namespace as its
parent element. An attribute name is output as a local name alone if it is in no namespace.
All other names are output in the format "Q{uri}local" if in a namespace,
or "Q{}local" if in no namespace. "Top-level" here means that the element
is one that appears explicitly in the sequence of elements passed in the $elements argument,
as distinct from a descendant of such an element. | |
If $element is the empty sequence, the result is the empty sequence.
The principles for conversion from elements to maps are described
in
In general, every descendant element within the tree rooted at the supplied
$element maps to a key-value pair in which the key represents the element name, and the
corresponding value represents the attributes and children of the element. This key-value pair will be added
to the content representing its parent element, in a way that depends on the parent element's layout.
The representation of a node of any other kind depends on the layout chosen for its parent element.
A dynamic error
Any error in the conversion plan is treated as a type error
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Because a map is a function item, functions that apply to functions also apply
to maps. A map is an anonymous function, so 1.
Maps may be compared using the
There is no function or operator to atomize a map or convert it to a string (other than
XPath 4.0 defines a number of syntactic constructs that operate on maps. These all have equivalents in the function library:
The expression {} creates the empty map
(see dm:empty-map(). Using user-visible functions
the same can be achieved by calling
The map constructor { K1 : V1, K2 : V2,
... , K/n : V/n } is equivalent to
map:merge((map:entry(K1, V1), map:entry(K1, V1), ..., map:entry(K/n, V/n)), { "duplicates": "reject" })
The lookup expression $map?*
(see map:items($map).
The lookup expression $map?K, where K is a key value, is equivalent to
map:get($map, K)
The expression for key $k value $v in $map return EXPR
(see map:for-each($map, fn($k, $v) { EXPR }).
Maps can be filtered using the construct $map?[predicate]
(see
Arrays were introduced as a new datatype in XDM 3.1. This section describes functions that operate on arrays.
An array is an additional kind of item. An array of size N is a mapping from the integers (1 to N) to a set of values, called the members of the array, each of which is an arbitrary sequence. Because an array is an item, and therefore a sequence, arrays can be nested.
An array acts as a function from integer positions to associated values, so the
function call $array($index) can be used to retrieve the array member at a given position.
The function corresponding to the array has the signature
function($index as xs:integer) as item()*.
The fact that an array is a function item allows it to be passed as an argument to higher-order functions
that expect a function item as one of their arguments.
The XDM data model (
dm:empty-array constructs the empty array.
dm:array-append adds a member to an array.
dm:iterate-array applies a supplied function to every member of an array, in order.
The functions in this section are all specified by means of equivalent expressions that either call these primitives directly, or invoke other functions that rely on these primitives. The specifications avoid relying on XPath language constructs that manipulate arrays, such as array constructor syntax, lookup expressions, or FLWOR expressions. This is done to allow these language constructs to be specified by reference to this function library, without risk of circularity.
There is one exception to this rule: for convenience, the notation [] is used to represent
the empty array, in preference to a call on dm:empty-array().
The formal equivalents are not intended to provide a realistic way of implementating the functions. They do, however, provide a framework that allows the correctness of a practical implementation to be verified.
The functions defined in this section use a conventional namespace prefix array, which
is assumed to be bound to the namespace URI http://www.w3.org/2005/xpath-functions/array.
As with all other values, arrays are treated as immutable.
For example, the
All functionality on arrays is defined in terms of two primitives:
The function
The function
A record(value as item()*), that is, a map containing a single
entry whose key is the string "value" and whose value is the encapsulated sequence.
Note that when the required type of an argument to a function such as
| Function | Meaning |
|---|---|
array:append | Returns an array containing all the members of a supplied array, plus one additional member at the end. |
array:build | Returns an array obtained by evaluating the supplied function once for each item in the input sequence. |
array:empty | Returns true if the supplied array contains no members. |
array:filter | Returns an array containing those members of the $array for which
$predicate returns true. A return value of ()
is treated as false. |
array:flatten | Replaces any array appearing in a supplied sequence with the members of the array, recursively. |
array:fold-left | Evaluates the supplied function cumulatively on successive members of the supplied array. |
array:fold-right | Evaluates the supplied function cumulatively on successive values of the supplied array. |
array:foot | Returns the last member of an array. |
array:for-each | Returns an array whose size is the same as array:size($array), in which
each member is computed by applying $action to the corresponding member of
$array. |
array:for-each-pair | Returns an array obtained by evaluating the supplied function once for each pair of members at the same position in the two supplied arrays. |
array:get | Returns the value at the specified position in the supplied array (counting from 1). |
array:head | Returns the first member of an array, that is $array(1). |
array:index-of | Returns a sequence of positive integers giving the positions within the array
$array of members that are equal to $target. |
array:index-where | Returns the positions in an input array of members that match a supplied predicate. |
array:insert-before | Returns an array containing all the members of the supplied array, with one additional member at a specified position. |
array:items | Returns the sequence concatenation of the members of an array. |
array:join | Concatenates the contents of several arrays into a single array. |
array:members | Delivers the contents of an array as a sequence of |
array:of-members | Constructs an array from the contents of a sequence of |
array:put | Returns an array containing all the members of a supplied array, except for one member which is replaced with a new value. |
array:remove | Returns an array containing all the members of the supplied array, except for the members at specified positions. |
array:reverse | Returns an array containing all the members of a supplied array, but in reverse order. |
array:size | Returns the number of members in the supplied array. |
array:slice | Returns an array containing selected members of a supplied input array based on their position. |
array:sort | Sorts a supplied array, based on the value of a sort key supplied as a function. |
array:sort-by | Sorts a supplied array, based on the value of a number of sort keys supplied as functions. |
array:sort-with | Sorts a supplied array, according to the order induced by the supplied comparator functions. |
array:split | Delivers the contents of an array as a sequence of single-member arrays. |
array:subarray | Returns an array containing all members from a supplied array starting at a supplied position, up to a specified length. |
array:tail | Returns an array containing all members except the first from a supplied array. |
array:trunk | Returns an array containing all members except the last from a supplied array. |
Returns an array containing all the members of a supplied array, plus one additional member at the end.
This function is
Informally, the result is an array whose size is array:size($array) + 1, in which all
members in positions 1 to array:size($array) are the same as the members in the corresponding position
of $array, and the member in position array:size($array) + 1 is $member.
The function is defined as follows, making use of primitive constructors and accessors defined
in
| Expression | Result |
|---|---|
array:append([ "a", "b", "c" ], "d") |
|
array:append([ "a", "b", "c" ], ("d", "e")) |
|
array:append([ "a", "b", "c" ], [ "d", "e" ]) |
|
Returns an array obtained by evaluating the supplied function once for each item in the input sequence.
This function is
Informally, the function applies the function to each item in the input sequence, and the resulting sequence becomes one member of the returned array.
The effect of the function is equivalent to the result of the following XPath expression.
The single-argument function array:build($input) is equivalent to the XPath
expression array { $input }, but it is useful to have this available as a function.
The two-argument form facilitates the construction of arrays whose members are arbitrary sequences.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns true if the supplied array contains no members.
This function is
The function returns true if and only if $array contains no members.
The effect of the function is equivalent to the result of the following XPath expression.
The test for emptiness is not the same as the test used by the
xsl:on-empty instruction in XSLT. For example, an array
is not considered empty by this function if it contains a single
member that is itself the empty array.
| Expression | Result |
|---|---|
array:empty([ "a", "b", "c" ]) |
|
array:empty([]) |
|
array:empty([ [] ]) |
|
array:empty([ () ]) |
|
$predicate callback function now accepts an optional position argument.$predicate callback function may return the empty sequence (meaning false).Returns an array containing those members of the $array for which
$predicate returns true. A return value of ()
is treated as false.
This function is
Informally, the function returns an array containing those members of the input array that satisfy the supplied predicate.
The effect of the function is equivalent to the result of the following XQuery expression.
As a consequence of the function signature and the function calling rules, a type error occurs if the supplied
function $function returns anything other than a single xs:boolean item
or the empty sequence; there is no conversion to an effective boolean value.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: |
Replaces any array appearing in a supplied sequence with the members of the array, recursively.
This function is
The function processes the items in the supplied sequence $input as follows:
An item that is an array is replaced by its members, retaining order.
Any other item is retained unchanged.
The process is then repeated so long as the sequence contains an array among its items.
The function delivers the same result as the following XQuery implementation.
The argument to the function will often be a single array item, but this is not essential.
Unlike atomization, this function retains any nodes contained in the array.
| Expression | Result |
|---|---|
array:flatten([ 1, 4, 6, 5, 3 ]) |
|
array:flatten(([ 1, 2 ], [ [ 10, 11 ], 12 ], [], 13)) |
|
array:flatten([ (1, 0), (1, 1), (0, 1), (0, 0) ]) |
|
Evaluates the supplied function cumulatively on successive members of the supplied array.
This function is
The function is defined formally below, in terms of the equivalent
The effect of the function is equivalent to the result of the following XPath expression.
If the supplied array is empty, the function returns $init.
If the supplied array contains a single member $m, the function returns $init => $action($m).
If the supplied array contains two members $m and $n, the function returns
$init => $action($m) => $action($n); and similarly for an input array with more than two members.
| Expression | Result |
|---|---|
| |
| |
Evaluates the supplied function cumulatively on successive values of the supplied array.
This function is
The function is defined formally below, in terms of the equivalent
The effect of the function is equivalent to the result of the following XPath expression.
If the supplied array is empty, the function returns $init.
If the supplied array contains a single member $m, the function returns $action($m, $init).
If the supplied array contains two members $m and $n, the function returns
$action($m, $action($n, $init)); and similarly for an input array with more than two members.
| Expression | Result |
|---|---|
| |
| |
Returns the last member of an array.
This function is
The function returns the last member of $array.
The effect of the function is equivalent to the result of the following XPath expression.
A dynamic error occurs $array is empty.
| Expression | Result |
|---|---|
array:foot([ 5, 6, 7, 8 ]) |
|
array:foot([ [ "a", "b" ], [ "c", "d" ] ]) |
|
array:foot([ ("a", "b"), ("c", "d") ]) |
|
$action callback function now accepts an optional position argument.Returns an array whose size is the same as array:size($array), in which
each member is computed by applying $action to the corresponding member of
$array.
This function is
Informally, the function returns an array whose members are obtained by applying
the supplied $action function to each member of the input array in turn.
The $action function is called with two arguments: the first is the
array member (which in general is an arbitrary sequence), and the second is the 1-based
integer position.
The effect of the function is equivalent to the result of the following XPath expression.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
$action callback function now accepts an optional position argument.Returns an array obtained by evaluating the supplied function once for each pair of members at the same position in the two supplied arrays.
This function is
Informally, the function applies $action to each pair of values in corresponding positions
within $array1 and $array2, ignoring any excess values if one array is longer
than the other. The results are then assembed into a new array whose size is equal to the shorter of the
two input arrays.
The effect of the function is equivalent to the result of the following XPath expression.
If the arrays have different size, excess members in the longer array are ignored.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns the value at the specified position in the supplied array (counting from 1).
This function is
Informally, the function returns the member at a specified position in the array.
If $position is out of bounds (that is, if
it is less than one or greater than array:size($array)), then the effect
depends on the number of arguments:
When there are two arguments, an error is raised (
When there are three arguments, the value of $default is returned.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
In the absence of a $default argument,
a dynamic error occurs $position is not in the range 1 to
array:size($array) inclusive.
| Expression | Result |
|---|---|
[ "a", "b", "c" ] => array:get(2) |
|
[ "a", [ "b", "c" ] ] => array:get(2) |
|
[ "a" ] => array:get(1, ()) |
|
[ "a" ] => array:get(2, ()) |
|
Returns the first member of an array, that is $array(1).
This function is
The function returns first member of $array.
The effect of the function is equivalent to the result of the following XPath expression.
A dynamic error occurs $array is empty.
| Expression | Result |
|---|---|
array:head([ 5, 6, 7, 8 ]) |
|
array:head([ [ "a", "b" ], [ "c", "d" ] ]) |
|
array:head([ ("a", "b"), ("c", "d") ]) |
|
Returns a sequence of positive integers giving the positions within the array
$array of members that are equal to $target.
The two-argument form of this function is
The three-argument form of this function is
Informally, all members of $array are compared with $target.
An array member is compared to the target value using the rules of the
The collation used by this function is determined according to the rules in
The first member in an array is at position 1, not position 0.
The result sequence is in ascending numeric order.
The effect of the function is equivalent to the result of the following XPath expression.
If $array is the empty array, or if no member in
$array matches $target, then the function returns the empty
sequence.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
$predicate callback function may return the empty sequence (meaning false).Returns the positions in an input array of members that match a supplied predicate.
This function is
The result of the function is a sequence of integers, in monotonic ascending order, representing
the 1-based positions in the input array of those members for which the supplied predicate function
returns true. A return value of () is treated as false.
The effect of the function is equivalent to the result of the following XPath expression.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns an array containing all the members of the supplied array, with one additional member at a specified position.
This function is
Informally, the function returns an array of size array:size($array) + 1
containing all members from $array
whose position is less than $position, then a new member given by $member, and
then all members from $array whose position is greater than or equal to $position.
Positions are counted from 1.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
A dynamic error occurs $position is not in the range 1 to
array:size($array) + 1 inclusive.
Setting $position to 1 has the effect of prepending the new member at the start of the array. Setting $position
to the value array:size($array) + 1 delivers the same result as array:append($array, $member).
| Expression | Result |
|---|---|
Returns the sequence concatenation of the members of an array.
This function is
The function returns the $array, retaining order.
The effect of the function is equivalent to the result of the following XPath expression.
Unlike
If $A is a single array item, then array:items($A)
returns the same result as $A?*.
| Expression | Result |
|---|---|
array:items(["one", "two", "three"]) |
|
array:items(["one", ("two", "three")]) |
|
array:items(["one", ("two", "three"), ()]) |
|
array:items(["one", ["two", "three"]]) |
|
array:items([ (), 1, (2 to 4), [ 5 ] ]) |
|
Concatenates the contents of several arrays into a single array.
This function is
The function concatenates the members of several arrays into a single array.
The effect of the function is equivalent to the result of the following XPath expression.
| Expression | Result |
|---|---|
array:join(()) |
|
array:join([ 1, 2, 3 ]) |
|
array:join(([ "a", "b" ], [ "c" ])) |
|
array:join(([ "a", "b" ], [ "c" ], [])) |
|
array:join(([ "a", "b" ], [ [ "c" ] ])) |
|
Delivers the contents of an array as a sequence of
This function is
The members of the array are delivered as a sequence of $S: specifically
it is a map comprising a single entry whose key is the xs:string value
"value" and whose corresponding value is $S. The content encapsulated
by a value record $V can be obtained using the expression $V?value.
The function is defined as follows, making use of primitive constructors and accessors defined
in
This function is the inverse of
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Constructs an array from the contents of a sequence of
This function is
The input items must be $S: specifically
it is a map comprising a single entry whose key is the xs:string value
"value" and whose corresponding value is $S. The content encapsulated
by a value record $V can be obtained using the expression $V?value.
The effect of the function is equivalent to the result of the following XQuery expression.
This function is the inverse of
| Expression | Result |
|---|---|
array:of-members(()) |
|
array:of-members({ 'value': (1 to 5) }) |
|
array:of-members((1 to 5) ! { 'value': . }) |
|
array:of-members((1 to 3) ! { 'value': (., . * .) }) |
|
Returns an array containing all the members of a supplied array, except for one member which is replaced with a new value.
This function is
Informally, the result is an array whose size is array:size($array), in which all
members in positions other than $position are the same as the members in the corresponding position
of $array, and the member in position $position is $member.
The effect of the function is equivalent to the result of the following XPath expression.
A dynamic error occurs $position is not in the range 1 to
array:size($array) inclusive.
This error will always occur if $array is empty.
| Expression | Result |
|---|---|
array:put([ "a", "b", "c" ], 2, "d") |
|
array:put([ "a", "b", "c" ], 2, ("d", "e")) |
|
array:put([ "a" ], 1, [ "d", "e" ]) |
|
Returns an array containing all the members of the supplied array, except for the members at specified positions.
This function is
Informally, the function returns an array of size array:size($array) - fn:count(fn:distinct-values($positions))$array
except the members whose position (counting from 1) is present in the sequence $positions.
The order of the remaining members is preserved.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
A dynamic error is raised $positions is not in the range 1 to
array:size($array) inclusive. By implication, an error occurs if $array is empty, unless $positions
is also empty.
| Expression | Result |
|---|---|
array:remove([ "a", "b", "c", "d" ], 1) |
|
array:remove([ "a", "b", "c", "d" ], 2) |
|
array:remove([ "a" ], 1) |
|
array:remove([ "a", "b", "c", "d" ], 1 to 3) |
|
array:remove([ "a", "b", "c", "d" ], ()) |
|
Returns an array containing all the members of a supplied array, but in reverse order.
This function is
The function returns an array with the same number of members
as $array, but in reverse order.
The effect of the function is equivalent to the result of the following XPath expression.
| Expression | Result |
|---|---|
array:reverse([ "a", "b", "c", "d" ]) |
|
array:reverse([ ("a", "b"), ("c", "d") ]) |
|
array:reverse([ 1 to 5 ]) |
|
array:reverse([]) |
|
Returns the number of members in the supplied array.
This function is
The function returns the number of members in the array.
The effect of the function is equivalent to the result of the following XPath expression.
Note that because an array is an item, the 1.
| Expression | Result |
|---|---|
array:size([ "a", "b", "c" ]) |
|
array:size([ "a", [ "b", "c" ] ]) |
|
array:size([]) |
|
array:size([ [] ]) |
|
Returns an array containing selected members of a supplied input array based on their position.
This function is
Informally, the array is converted to a sequence, the function
The effect of the function is equivalent to the result of the following XPath expression.
Note that unlike other operations on arrays, there are no out-of-bounds errors for inappropriate
values of $start, $end, or $step.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
array:slice($in, start := 2, end := 4) |
|
array:slice($in, start := 2) |
|
array:slice($in, end := 2) |
|
array:slice($in, start := 3, end := 3) |
|
array:slice($in, start := 4, end := 3) |
|
array:slice($in, start := 2, end := 5, step := 2) |
|
array:slice($in, start := 5, end := 2, step := -2) |
|
array:slice($in, start := 2, end := 5, step := -2) |
|
array:slice($in, start := 5, end := 2, step := 2) |
|
array:slice($in) |
|
array:slice($in, start := -1) |
|
array:slice($in, start := -3) |
|
array:slice($in, end := -2) |
|
array:slice($in, start := 2, end := -2) |
|
array:slice($in, start := -2, end := 2) |
|
array:slice($in, start := -4, end := -2) |
|
array:slice($in, start := -2, end := -4) |
|
array:slice($in, start := -4, end := -2, step := 2) |
|
array:slice($in, start := -2, end := -4, step := -2) |
|
array:slice([ "a", "b", "c", "d" ], 0) |
|
Sorts a supplied array, based on the value of a sort key supplied as a function.
This function is
This function is retained for compatibility from version 3.1 of this specification. Version 4.0
introduces a more powerful functions,
The function call array:sort($array, $collation, $key) is defined to have the same effect as the
call array:sort-by($array, { 'key': $key, 'collation': $collation, 'order': 'ascending'}).
See
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 the supplied sort key definitions.
The effect of the function is equivalent to the result of the following XPath expression.
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 (
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
Sorts a supplied array, based on the value of a number of sort keys supplied as functions.
This function is
The result of the function is an array that contains the same members as $array,
typically in a different order, the order being defined by the supplied
A
key: A fn:data#1,
which atomizes the value of the array member.
collation: A xs:string or xs:untypedAtomic. If no collation is supplied, the default
collation from the static context is used.
When comparing values of types other than xs:string or xs:untypedAtomic,
the collation is ignored (but an error
order: An "ascending" or
"descending". The default is "ascending".
The number of sort key definitions is determined by the number of records supplied
in the $keys argument. If the argument is absent or empty, the default is
a single sort key definition using the function data#1, using the default collation
from the static context, and with order ascending.
The result of the array:sort-by function is obtained as follows:
The result array contains the same members as $array,
but generally in a different order.
The sort key definitions are established as described above.
The sort key definitions are in major-to-minor order. That is, the position of two
values $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 array member is obtained by applying the sort key
function of the corresponding sort key definition to that member. The result
of this function is in the general case a sequence of atomic items.
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:lexicographic-compare($key($A), $key($B), $C)
where op:lexicographic-compare($a, $b, $C) is defined as follows:
Here op:simple-compare($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 non-ordered
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
The effect of the function is equivalent to the result of the following XPath expression.
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 (
The function is a generalization of the
If the sort key for an item evaluates to the empty sequence, the effect of the rules is that this item
precedes any value for which the key is non-empty. This is equivalent to the effect of the XQuery option
empty least. The effect of the option empty greatest can be achieved by adding an
extra sort key definition with {'key': fn{empty(K(.)}}: when comparing boolean sort keys,
false precedes true.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
Sorts a supplied array, according to the order induced by the supplied comparator functions.
This function is
Informally, the members of the supplied $array are sorted into an
order based on the result of evaluating the supplied $comparators.
The result is a sorted array.
Each comparator function takes two values and returns an xs:integer that
defines the relationship between these values, following the conventions of the
$c is used to compare two values $a and $b,
it must return a negative integer if $a is to be sorted before $b,
zero if they are considered equal, and a positive integer if $a is
to be sorted after $b.
There may be more than one comparator, representing sort keys in major to minor order.
To determine the relative position of two members $a and $b:
The first comparator is called: $comparators[1]($a, $b). If
the result is non-zero, this determines the relative position of $a
and $b in the result array, and any further comparators
can be ignored.
If the Nth comparator returns zero, then:
If this is the last comparator, then the two members are considered
equal, and their relative position in the result sequence will be the same
as their relative position in the input sequence (that is, the sort is
Otherwise, the next comparator is evaluated, and so on, until the last comparator is reached or the result of a comparator is non-zero.
To ensure that the sorting algorithm produces predictable results (indeed, to ensure that it terminates), it is necessary for the comparators to have certain properties. Specifically, for every comparator C:
C must be deterministic (if called twice with the same arguments, it must deliver the same result).
Every value must be equal to itself: C($a, $a) must be zero.
The ordering must be consistent: if C($a, $b) < 0,
then C($b, $a) > 0, and vice versa, and similarly,
if C($a, $b) = 0,
then C($b, $a) = 0.
The ordering must be transitive: if C($a, $b) < 0
and C($b, $c) < 0, then C($a, $c) < 0.
If a comparator function raises an error when processing any pair of members from the input array
(for example, if the comparator function is fn:compare#2 and one of the members
is not coercible to xs:anyAtomicType), then the evaluation of
In general it is unpredictable which pairs of members from the input array
will actually be compared using each comparator function. However, a comparator function
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: |
Delivers the contents of an array as a sequence of single-member arrays.
This function is
The members of the array are delivered as a sequence of
$array.
The effect of the function is equivalent to the result of the following XPath expression.
The function call array:split($array) produces the same result as the
expression for member $m in $array return [ $m ].
The expression $A => array:split() => array:join(), applied to any array
$A, returns the original array $A.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns an array containing all members from a supplied array starting at a supplied position, up to a specified length.
This function is
Except in error cases,
the two-argument version of the function returns the same result as the three-argument
version when called with $length equal to the value of
array:size($array) - $start + 1.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
A dynamic error is raised $start is less than one
array:size($array) + 1
For the three-argument version of the function:
A dynamic error is raised $length is less than zero.
A dynamic error is raised $start + $length is greater than array:size($array) + 1.
The value of $start can be equal to array:size($array) + 1 provided that $length
is either equal to zero or omitted. In this case the result will be the empty array.
| Expression | Result |
|---|---|
array:subarray([ "a", "b", "c", "d" ], 2) |
|
array:subarray([ "a", "b", "c", "d" ], 5) |
|
array:subarray([ "a", "b", "c", "d" ], 2, 0) |
|
array:subarray([ "a", "b", "c", "d" ], 2, 1) |
|
array:subarray([ "a", "b", "c", "d" ], 2, 2) |
|
array:subarray([ "a", "b", "c", "d" ], 5, 0) |
|
array:subarray([], 1, 0) |
|
Returns an array containing all members except the first from a supplied array.
This function is
The function returns an array containing all members of the supplied array except the first.
The effect of the function is equivalent to the result of the following XPath expression.
A dynamic error occurs $array is empty.
If the supplied array contains exactly one member, the result will be the empty array.
| Expression | Result |
|---|---|
array:tail([ 5, 6, 7, 8 ]) |
|
array:tail([ 5 ]) |
|
Returns an array containing all members except the last from a supplied array.
This function is
The function returns an array containing all members of the supplied array except the last.
The effect of the function is equivalent to the result of the following XPath expression.
A dynamic error occurs $array is empty.
If the supplied array contains exactly one member, the result will be the empty array.
| Expression | Result |
|---|---|
array:trunk([ 5, 6, 7, 8 ]) |
|
array:trunk([ 5 ]) |
|
Arrays may be compared using the
The XPath language provides explicit syntax for certain operations on arrays. These constructs can all be specified in terms of function primitives:
The empty array can be constructed using either of the expressions
[] or array{}. The effect is the same as the data model primitive
dm:empty-array(()) (see array:build(()) or array:of-members(()).
The expression array { $sequence } constructs an array whose members
are the items in $sequence. Every member of this array will
be a singleton item. The effect is the same as
array:build($sequence).
The expression [E1, E2, E3, ..., E/n] constructs an array in which
E1 is the first member, E2 is the second member,
and so on. The result is equivalent to the expression
[] => array:append(E1) => array:append(E2) => ... => array:append(E/n))).
The lookup expression $array?* returns the
array:fold-left($array, (), fn($result, $next){ $result, $next }).
The lookup expression $array?$N, where $N
is an integer within the bounds of the array, is equivalent to
array:get($array, $N).
Similarly, applying the array as a function, $array($N),
is also equivalent to array:get($array, [$N])
The expression for member $m in $array return EXPR
is equivalent to array:for-each($array, fn($m){ EXPR })
(see
Arrays can be filtered using the construct $array?[predicate]
(see
A $jnode/descendant::title, as described
at
In addition to the functions defined in this section, functions that operate on JNodes include:
Delivers a root
This function is
The function creates a $input, and whose
This has the effect that lookup expressions starting from this JNode retain information for subsequent navigation.
A JNode has unique identity. If two maps or arrays M1 and
M2 have the same function identity, as determined by the
jtree(M1) is jtree(M2)
It is to some extent $m is bound to a map or array,
calling jtree($m) more than once (with the same variable reference)
will deliver the same JNode each time.
The effect of the coercion rules is technically that if an existing JNode is supplied as $input,
the wrapped value will be extracted, and then rewrapped as a JNode: in practice,
this can be short-circuited by returning the supplied JNode unchanged.
Although $map/child::*. Specifically,
if the left-hand operand of the / operator is a map or array,
then the supplied map or array is implicitly wrapped in a JNode.
The effect of applying json-doc($source)//name.
This expression returns a set of JNodes representing all entries in the JTree having the key "name";
each of these JNodes contains not only the value of the relevant "name" entry,
but also the key (which in this simple example is always "name"
and the containing map. This means, for example, if $result
is the result of the expression json-doc($source)//name, then:
$result/../ssn locates the map that contained each
name, and returns the value of the ssn entry in that map.
$result/ancestor::course returns any
course entries in containing maps.
$result/ancestor::* => jkey() returns a sequence of map keys and array index
values representing the location of the found entries within the JSON structure.
An alternative way of wrapping a map or array, rather than calling jtree($X),
is to use the path expression $X/..
There are two situations where a map or array is implicitly wrapped in a JNode:
When the value of the left-hand operand of the / operator
includes a map or array;
When the context value for evaluation of an AxisStep
includes a map or array.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: |
Returns the
This function is
If $input is the empty sequence, the function returns the empty sequence.
If $input is a root JNode (one in which the
Otherwise, the function returns the $input.
In the case where the parent JNode wraps a map, this will be the key of the relevant entry
within that map; in the case where the parent JNode wraps an array, it will be the 1-based
index of the relevant member of the array.
The following errors may be raised when $node is omitted:
If the context value is
If the context value is not an instance of the sequence type jnode()?,
type error
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns the
This function is
If $input is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns the $input.
The following errors may be raised when $node is omitted:
If the context value is
If the context value is not an instance of the sequence type jnode()?,
type error
In many cases it is unnecessary to make an explicit call on jvalue, because
the coercion rules will take care of this automatically. For example, in an expression
such as $X / descendant::name [matches(., '^J')], the call on
Other examples where the
Any context where the required type is an atomic value, for example arithmetic operations, value comparisons and general comparisons, and calls on functions that expect an atomic value.
Any context where the required type is a map or array, for example
the first argument of functions such as array:size, a free-standing expression within a map
constructor such as map{ $jnode }, the constructs
for member and for key/value, the left-hand
operand of the lookup operator ? (or the context value
in the case of a unary lookup operator), and the operand of a map/array
filter expression $jnode?[predicate].
Notable places where the
When computing the effective boolean
value. As with XNodes, writing if ($array/child::*[1]) ... tests for the existence
of a child, it does not test its value. To test its value, write
if (jvalue($array/child::*[1])) ...,
or equivalently if (xs:boolean($array/child::*[1])) ....
When calling functions that accept arbitrary sequences, such as
It is possible (though probably unwise) to construct a JNode whose jtree([jtree([]), jtree([])]) creates a JNode whose child axis to this JNode will
return a sequence of two JNodes that themselves have further JNodes as their content.
The
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns the
This function is
If $input is the empty sequence, the function returns the empty sequence.
If $input is a root JNode (one in which the
Otherwise, the function returns the $input.
The value of this property will be 1 (one) except in cases where
the value of an entry in a map, or a member in an array, is a sequence that contains
multiple items including maps and/or arrays; in such cases
the position will be the 1-based position of the relevant map or array.
The following errors may be raised when $node is omitted:
If the context value is
If the context value is not an instance of the sequence type jnode()?,
type error
This function is relevant only when there are maps whose entries are multi-item sequences that include maps and arrays, or arrays whose members include such multi-item sequences. Such structures are uncommon, and never arise from parsing of JSON source text. It is generally best to avoid such structures by using arrays rather than sequences within array and map content; apart from other considerations, this allows the data to be serialized in JSON format.
If an entry within a map, or a member of an array, contains a sequence of items
that mixes arrays and maps with other content (for example the array
[1, 2, ([1,2], [3,4], 5)), then a lookup using the
child axis will only construct JNodes in respect of those items that are
non-empty maps or arrays. This may leave gaps in the position numbering sequence,
as illustrated in the examples below.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: |
These functions in this section access resources external to a query or stylesheet, and convert between external file formats and their XPath and XQuery data model representation.
The functions in this section provide access to resources (such as files) in the external environment.
| Function | Meaning |
|---|---|
fn:doc | Retrieves a document using a URI supplied as an xs:string, and returns the
corresponding document node. |
fn:doc-available | The function returns true if and only if the function call fn:doc($source, $options)
would return a document node. |
fn:collection | Returns a sequence of items identified by a collection URI; or a default collection if no URI is supplied. |
fn:uri-collection | Returns a sequence of xs:anyURI values representing the URIs in a URI
collection. |
fn:unparsed-text | The |
fn:unparsed-text-lines | The |
fn:unparsed-text-available | Allows an application to determine
whether a call on |
fn:unparsed-binary | The fn:unparsed-binary function reads an external resource (for example, a
file) and returns its contents in binary. |
fn:environment-variable | Returns the value of a system environment variable, if it exists. |
fn:available-environment-variables | Returns a list of environment variable names that are suitable for passing to
|
$options parameter is added. Note that the rules for the $options parameter
control aspects of processing that were implementation-defined in earlier versions of this
specification. An implementation may provide configuration options designed to retain backwards-compatible
behavior when no explicit options are supplied.Retrieves a document using a URI supplied as an xs:string, and returns the
corresponding document node.
This function is
If $source is the empty sequence, the result is the empty sequence.
If $source is a relative URI reference, it is resolved relative to the value
of the xs:string.
The way in which an absolute URI is dereferenced to obtain an external resource is
described in
The ability to access external resources depends on whether the
calling code is
The URI may include a fragment identifier.
The $options argument defines the detailed behavior of the function.
The
| Key | Value | Meaning |
|---|---|---|
| Indicates whether processing the document may cause other
external resources to be fetched (including, for example, external entities, an external DTD,
or documents referenced using xsi:schemaLocation or
XInclude elements).
| |
true | The document may include references to other external resources. | |
false | The document must not include references to other external resources unless access to these resources has been explicitly enabled. | |
| Determines whether DTD validation takes place.
| |
true | The input is parsed using a validating XML parser.
The input must contain a DOCTYPE declaration to identify
the DTD to be used for validation. The DTD may be internal or external.
| |
false | DTD validation does not take place. However, if a
DOCTYPE declaration is present, then it is read, for example
to perform entity expansion.
| |
| Determines whether two calls on the true, but this may be overridden
by implementation-defined configuration options.
| |
true | Given the same explicit and implicit arguments, multiple
calls return the same document node: that is, the function is | |
false | Multiple calls with the same explicit and implicit arguments may return the same document node or different document nodes at the discretion of the implementation. | |
| Determines whether whitespace-only text nodes are removed
from the resulting document. The default is defined by the host language
or by the implementation. (Note: in XSLT, the xsl:strip-space
and xsl:preserve-space declarations provide detailed control
based on the parent element name.)
| |
true | All whitespace-only text nodes are stripped,
unless either (a) they are within the scope of the attribute xml:space="preserve",
or (b) XSD validation identifies that the parent element has a simple type or a complex
type with simple content.
| |
false | All whitespace-only text nodes are preserved, unless either (a) DTD validation marks them as ignorable, or (b) XSD validation recognizes the containing element as having element-only or empty content. | |
| Determines whether any xi:include elements in the input
are to be processed using an XInclude processor.
| |
true | Any xi:include elements are expanded. If there are
xi:include elements and no XInclude processor is available then
a dynamic error is raised.
| |
false | Any xi:include elements are handled as
ordinary elements without expansion.
| |
| Determines whether XSD validation takes place, using the
schema definitions present in the static context. The effect of requesting
validation is the same as invoking the validate expression to the result,
with corresponding options.
| |
strict | Strict XSD validation takes place | |
lax | Lax XSD validation takes place | |
skip | No XSD validation takes place | |
type Q{uri}local | XSD validation takes place against the schema-defined type, present in the static context, that has the given URI and local name. | |
| When XSD validation takes place, determines whether
schema components referenced using xsi:schemaLocation or xsi:noNamespaceSchemaLocation
attributes within the source document are to be used. The option is ignored
if XSD validation does not take place.
| |
true | XSD validation uses the schema components referenced
using xsi:schemaLocation or xsi:noNamespaceSchemaLocation
attributes in addition to the schema components present in the static context;
these components must be compatible as described in | |
false | Any xsi:schemaLocation and xsi:noNamespaceSchemaLocation
attributes in the document are ignored. | |
By default, this function is true:
This equivalence applies only because the two calls on
the
The requirement to deliver a deterministic result has performance implications,
and for this reason 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
If the $source URI is obtained 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
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 string-to-document-node
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 run-time environment in which the expression is evaluated. This run-time
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 implementation-defined. Implementations may allow the mapping of URIs to resources to be configured by the user, using mechanisms such as catalogs or user-written URI handlers.
The handling of non-XML media types is implementation-defined. Implementations may allow instances of the data model to be constructed from non-XML resources, under user control.
It is
Implementations may provide user-defined 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 the 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 $source 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
$options parameter is added. Note that the rules for the $options parameter
control aspects of processing that were implementation-defined in earlier versions of this
specification. An implementation may provide configuration options designed to retain backwards-compatible
behavior when no explicit options are supplied.The function returns true if and only if the function call fn:doc($source, $options)
would return a document node.
This function is
If $source is the empty sequence, this function returns false.
If a call on fn:doc($source, $options) would return a document node, this function
returns true.
In all other cases this function returns false.
The recognized values for $options are the same as for the stable
option is set to true, then a result of true from this function guarantees
that a call on false from this function guarantees that the corresponding call on stable option is set to false, then the result of this
function provides no guarantees regarding the outcome of a call on
Like any other function, $options. However, it returns false
rather than raising an error if the first argument is invalid as a URI.
The function also returns false (rather than raising an error) if the document is unavailable because of processor limitations, for example if schema validation is requested and the processor is not schema-aware.
Returns a sequence of items identified by a collection URI; or a default collection if no URI is supplied.
This function is
This function takes an xs:string as argument and returns a sequence of
$source as an xs:anyURI and
resolving it according to the mapping specified in
If
If $source is the empty sequence, the function returns the sequence of
If $source is a relative URI reference, it is resolved relative to the value
of the xs:string.
By default, this function is
There is no requirement that
The ability to access external resources depends on whether the
calling code is
A dynamic error is raised
A dynamic error is raised
A dynamic error is raised
A dynamic error $source is not
a valid xs:anyURI.
In earlier versions of this specification, the primary use for the 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.
This function is
If $source is the empty sequence, the function returns the URIs in the
If $source is a relative URI reference, it is resolved relative to the value
of the xs:string.
The single-argument 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.
The ability to access external resources depends on whether the
calling code is
A dynamic error is raised
A dynamic error is raised
A dynamic error is raised
A dynamic error $source is not
a valid xs:anyURI.
In some implementations, there might be a close relationship between
In the case where
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
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
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
$options parameter has been added.The
This function is
The $source argument
If $source is a relative URI reference, it is resolved relative to the value
of the xs:string.
The $options argument, for backwards compatibility reasons, may be supplied
either as a map, or as a string. Supplying a value $S that is not a map
is equivalent to supplying the map { "encoding": $S }.
After that substitution, the
The entries that may appear in the $options map are as follows:
| Key | Value | Meaning |
|---|---|---|
| Defines the encoding of the resource, as described below.
| |
| Determines whether CR and CRLF character sequences
are treated as equivalent to NL characters.
| |
false | No normalization of line endings takes place. | |
true | The character | |
|
If $fallback is true, any character that
cannot be decoded or that is not a
| |
The way in which an absolute URI is dereferenced to obtain an external resource is
described in
The ability to access external resources depends on whether the
calling code is
If the $source argument is the empty sequence, the function
returns the empty sequence.
The encoding option, if non-empty, is the name of an encoding.
The values for this option follow the same rules as for the encoding attribute
in an XML declaration. The values which an implementation is UTF-8, UTF-16, UTF-16LE,
and UTF-16BE (in any upper/lower case combination).
The effective encoding is chosen as follows:
external encoding information if available; otherwise
the encoding recognized as specified in text/xml or application/xml
(see text/*+xml or application/*+xml
(see
the value of the encoding option if present; otherwise
the encoding inferred from the initial octets of the resource,
or from
Encoding names are compared without regard to case.
If the input (as decoded using the effective encoding) starts with a byte order mark, then the byte order mark is not included in the result.
The result of the function is a string containing the string representation of the resource retrieved using the URI, decoded according to the effective encoding.
A dynamic error is raised $source argument
contains a fragment identifier,
A dynamic error is raised encoding option 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 option
is absent and the processor cannot infer the
encoding using external information and the actual encoding is not UTF-8.
If it is appropriate to use a base URI other than the
There is no essential relationship between the sets of URIs accepted by the two
functions
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 implementation-defined. Implementations may allow the mapping of URIs to resources to be configured by the user, using mechanisms such as catalogs or user-written URI handlers.
The handling of media types is implementation-defined.
Implementations may provide user options that relax the requirement for the function to return deterministic results.
Implementations may provide user-defined 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.
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 disable-output-escaping
attribute of the xsl:value-of 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: | |
$options parameter has been added.The
This function is
The unparsed-text-lines function reads an external resource (for example, a
file) and returns its string representation as a sequence of strings, separated at
newline boundaries.
The $options argument, for backwards compatibility reasons, may be supplied
either as a map, or as a string. Supplying a value $S that is not a map
is equivalent to supplying the map { "encoding": $S }.
After that substitution, the
The entries that may appear in the $options map are as follows:
| Key | Meaning |
|---|---|
| Defines the encoding of the resource, following the rules of
|
|
If $fallback is true, any character that
cannot be decoded or that is not a
|
The result of the function is the same as the result of the expression:
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 may be delimited by
any of the character sequences
The ability to access external resources depends on whether the
calling code is
Error conditions are the same as for the
See the notes for
$options parameter has been added.Allows an application to determine
whether a call on
This function is
The
If the first argument is the empty sequence, the function returns false.
In other cases, the function returns true if a call on
false if a call on
The functions unparsed-text with the same arguments.
The ability to access external resources depends on whether the
calling code is
This function was introduced before XQuery and XSLT allowed errors to be caught;
with current versions of these host languages, catching an error from
The specification requires that the if (unparsed-text-available(A)) then unparsed-text(A) else ... to
generate a single call internally.
Since the function
The fn:unparsed-binary function reads an external resource (for example, a
file) and returns its contents in binary.
This function is
The $source argument
If $source is a relative URI reference, it is resolved relative to the value
of the xs:string.
The mapping of URIs to the binary representation of a resource is the mapping defined in
the
If the $source argument is the empty sequence, the function
returns the empty sequence.
The result of the function is an atomic item of type xs:base64Binary
containing the binary representation of the
resource retrieved using the URI.
The ability to access external resources depends on whether the
calling code is
A dynamic error is raised $source argument
contains a fragment identifier,
If it is appropriate to use a base URI other than the
fn:resolve-uri
function before passing it to the fn:unparsed-text function.
There is no essential relationship between the sets of URIs accepted by the
function fn:unparsed-binary and other functions such as
fn:doc and fn:unparsed-text (a URI accepted by one
may or may not be accepted by the others), and if a URI is accepted by more than
one of these functions then 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 implementation-defined. Implementations may allow the mapping of URIs to resources to be configured by the user, using mechanisms such as catalogs or user-written URI handlers.
The handling of media types is implementation-defined.
Implementations may provide user options that relax the requirement for the function to return deterministic results.
Implementations may provide user-defined 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.
There is no function (analogous to fn:doc-available or fn:unparsed-text-available)
to determine whether a suitable resource is available. In XQuery and XSLT, try/catch
constructs are available to catch the error.
The choice of xs:base64Binary rather than xs:hexBinary for the
result is arbitrary. The two types have the same value space and are interchangeable for nearly
all purposes, the notable exception being conversion to xs:string.
A comprehensive set of functions for manipulating binary data is available in the
EXPath binary module: see file:read-binary with similar functionality to
fn:unparsed-binary, the notable differences being (a) that it takes
a file name rather than a URI, and (b) that it is defined to be nondeterministic.
The following XQuery, adapted from an example in the EXPath binary module | |
The example assumes that the functions in the EXPath binary module are available. |
Returns the value of a system environment variable, if it exists.
This function is
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 implementation-dependent 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:
Returns a list of environment variable names that are suitable for passing to
This function is
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
See also the note on security under the definition of the
These functions convert between the lexical representation of XML and the tree representation.
(The
| Function | Meaning |
|---|---|
fn:parse-xml | This function takes as input an XML document, and returns the document node at the root of an XDM tree representing the parsed document. |
fn:parse-xml-fragment | 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. |
fn:serialize | This function serializes the supplied input sequence $input as described in
|
fn:xsd-validator | Given an XSD schema, delivers a function item that can be invoked to validate a document, element, or attribute node against this schema. |
$options parameter has been added.This function takes as input an XML document, and returns the document node at the root of an XDM tree representing the parsed document.
This function is
If $value is the empty sequence, the function returns the empty sequence.
In other cases, $value is expected to contain an XML document supplied
either as a string or a binary value. If it is supplied as a binary value, an optional
byte order mark or XML declaration may contain the input encoding, and the input will be
processed like a resource retrieved by the
The $options argument defines the detailed behavior of the
function. The
| Key | Value | Meaning |
|---|---|---|
| Determines the base URI. This 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. It defaults
to the static base URI of the function call.
| |
| Determines whether DTD validation takes place.
| |
true | The input is parsed using a validating XML parser.
The input must contain a DOCTYPE declaration to identify
the DTD to be used for validation. The DTD may be internal or external.
| |
false | DTD validation does not take place. However, if a
DOCTYPE declaration is present, then it is read, for example
to perform entity expansion.
| |
| Determines whether whitespace-only text nodes are removed
from the resulting document. (Note: in XSLT, the xsl:strip-space
and xsl:preserve-space declarations are ignored.)
| |
true | All whitespace-only text nodes are stripped,
unless either (a) they are within the scope of the attribute xml:space="preserve",
or (b) XSD validation identifies that the parent element has a simple type or a complex
type with simple content.
| |
false | All whitespace-only text nodes are preserved, unless either (a) DTD validation marks them as ignorable, or (b) XSD validation recognizes the containing element as having element-only or empty content. | |
| Indicates whether processing the supplied document may cause
external resources to be fetched (including, for example, external entities, an external DTD,
or documents referenced using xsi:schemaLocation or
XInclude elements).
| |
true | The document may include references to external resources. | |
false | The document must not include references to external resources unless access to these resources has been explicitly enabled. | |
| Determines whether any xi:include elements in the input
are to be processed using an XInclude processor.
| |
true | Any xi:include elements are expanded. If there are
xi:include elements and no XInclude processor is available then
a dynamic error is raised.
| |
false | Any xi:include elements are handled as
ordinary elements without expansion.
| |
| Determines whether XSD validation takes place, using the
schema definitions present in the static context. The effect of requesting
validation is the same as invoking the validate expression to the result,
with corresponding options.
| |
strict | Strict XSD validation takes place | |
lax | Lax XSD validation takes place | |
skip | No XSD validation takes place | |
type Q{uri}local | XSD validation takes place against the schema-defined type, present in the static context, that has the given URI and local name. | |
| When XSD validation takes place, determines whether
schema components referenced using xsi:schemaLocation or xsi:noNamespaceSchemaLocation
attributes within the source document are to be used. The option is ignored
if XSD validation does not take place.
| |
true | XSD validation uses the schema components referenced
using xsi:schemaLocation or xsi:noNamespaceSchemaLocation
attributes in addition to the schema components present in the static context;
these components must be compatible as described in | |
false | Any xsi:schemaLocation and xsi:noNamespaceSchemaLocation
attributes in the document are ignored. | |
Except to the extent defined by these options, the precise process used
to construct the XDM instance is
The document URI of the returned node is
The function is
Options set in $options may be supplemented or modified based on
configuration options defined externally using
A dynamic error is raised $value is not a well-formed and namespace-well-formed XML document.
A dynamic error is raised $value is not valid against the relevant DTD.
A dynamic error is raised xsd-validation option is not one of the
permitted values (for example, if the string that follows "type"
is not a valid EQName, or if it does not identify a type that is present in the
static context).
A dynamic error is raised xsd-validation option is set to anything
other than skip when the processor is not schema-aware. (XSLT 4.0
and XQuery 4.0 define schema-awareness as an optional feature; other host languages
may set their own rules.)
A dynamic error is raised
A dynamic error is raised $value is not valid against the relevant XSD schema.
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.
A common 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 is
exposed as text, the receiving query or stylesheet may pass this text to the
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
| Expression | Result |
|---|---|
fn:parse-xml("<alpha>abcd</alpha>") | A newly
created document node, having an |
fn:parse-xml("<alpha><beta> </beta></alpha>", { "strip-space": true() }) | A newly
created document node, having an |
$options parameter has been added.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.
This function is
If $value is the empty sequence, the function returns the empty sequence.
If the input is supplied as a binary value, the function detects the encoding using the
same rules as the text/xml and application/xml may be skipped.
Otherwise, if the input is a string, any byte order mark as well as the encoding specified
in an optional XML declaration
The input must be a namespace-well-formed external general parsed entity. More
specifically, it must conform to the production rule
The input 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.
The $options argument defines the detailed behavior of the
function. The
| Key | Value | Meaning |
|---|---|---|
| Determines the base URI. This is used
as the base URI of the document node that is returned. It defaults
to the static base URI of the function call.
| |
| Determines whether whitespace-only text nodes are removed
from the resulting document.
| |
true | All whitespace-only text nodes are stripped,
unless they are within the scope of the attribute xml:space="preserve".
| |
false | All whitespace-only text nodes are preserved. | |
DTD validation is DOCTYPE declaration.
Schema validation is
XInclude processing is
Except as explicitly defined, the precise process used to construct the XDM instance is
The document URI of the returned node is
The function is
A dynamic error is raised $value is not a well-formed external general parsed entity, if it contains
entity references other than references to predefined entities, or if a document that
incorporates this well-formed parsed entity would not be namespace-well-formed.
See also the notes for the
The main differences between
Note that all whitespace outside the strip-space
option is set.
One use case for this function is to handle XML fragments stored in databases, which
frequently allow zero-or-more top level element nodes. Another use case is to parse the
contents of a CDATA section embedded within another XML document.
| Expression | Result |
|---|---|
parse-xml-fragment("<alpha>abcd</alpha><beta>abcd</beta>") | A newly created document node, having two elements named |
parse-xml-fragment("He was <i>so</i> kind") | A newly created document node having three children: a text node whose string
value is |
parse-xml-fragment("") | A document node having no children. |
parse-xml-fragment(" ") | A document node whose children comprise a single text node whose string value is a single space. |
parse-xml-fragment(" ", { "strip-space": true() }) | A document node having no children. |
parse-xml-fragment('<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><a/>') | Raises error FODC0006.
|
canonical is available to give control
over serialization of XML, XHTML, and JSON.This function serializes the supplied input sequence $input as described in
This function is
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 provides serialization parameters.
These may be supplied in either of two forms:
As an output:serialization-parameters
element, having the format described in element(output:serialization-parameters).
As a map. In this case the type of the supplied argument must match the required type map(*)
The single-argument version of this function has the same effect as the two-argument
version called with $options set to the empty sequence. This in turn is the
same as the effect of passing an output:serialization-parameters 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:serialization-parameters
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 non-absent namespace) in the case of implementation-defined 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 |
|---|---|---|---|
allow-duplicate-names
|
xs:boolean?
| true means "yes", false means "no" |
no
|
byte-order-mark
|
xs:boolean?
| true means "yes", false means "no" |
no
|
canonical
|
xs:boolean?
| true() means "yes", false() means "no" |
no
|
cdata-section-elements
|
xs:QName*
|
()
| |
doctype-public
|
xs:string?
| Zero-length string and () both represent "absent" | absent |
doctype-system
|
xs:string?
| Zero-length string and () both represent "absent" | absent |
encoding
|
xs:string?
|
UTF-8
| |
escape-solidus
|
xs:boolean?
| true means "yes", false means "no" |
yes
|
escape-uri-attributes
|
xs:boolean?
| true means "yes", false means "no" |
yes
|
html-version
|
xs:decimal?
|
5
| |
include-content-type
|
xs:boolean?
| true means "yes", false means "no" |
yes
|
indent
|
xs:boolean?
| true means "yes", false means "no" |
no
|
item-delimiter
|
xs:string?
| absent | |
json-lines
|
xs:boolean?
| true means "yes", false means "no" |
no
|
json-node-output-method
|
(xs:string | xs:QName)?
| See Notes 1, 2 |
xml
|
media-type
|
xs:string?
| (a media type suitable for the chosen method) | |
method
|
(xs:string | xs:QName)?
| See Notes 1, 2 |
xml
|
normalization-form
|
xs:string?
|
none
| |
omit-xml-declaration
|
xs:boolean?
| true means "yes", false means "no" |
yes
|
standalone
|
xs:boolean?
| true means "yes", false means "no", () means "omit" |
omit
|
suppress-indentation
|
xs:QName*
|
()
| |
undeclare-prefixes
|
xs:boolean?
| true means "yes", false means "no" |
no
|
use-character-maps
|
map(xs:string, xs:string)?
| See Note 3 |
{}
|
version
|
xs:string?
|
1.0
|
Notes to the table:
The notation (A | B) represents a union type whose member types are A
and B.
If an xs:QName is supplied method or json-node-output-method
options,xml and json
are defined as strings, not as xs:QName values.
use-character-maps 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:serialization-parameters)?
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 use-character-maps 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
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
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:serialization-parameters, allows for serializing any valid
XDM instance without raising a serialization error.
There are also use cases where the application wants to post-process 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:serialization-parameters
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
implementation-defined when an output:serialization-parameters
element is used (or when the argument is omitted), but are fixed by this specification in the
case where a map (including the empty map) is supplied for the argument.
| Variables | |
|---|---|
Given the variables: | |
The following call might produce the output shown: | |
| Expression: |
|
|---|---|
| Result: |
|
The following call would also produce the output shown (though the second argument could equally well be supplied
as the empty map ( | |
| Expression: | |
| Result: | |
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
This section describes a process called
The validation process takes the following inputs:
A schema to be used for validation,
called the
A boolean indicating whether any xsi:schemaLocation
or xsi:noNamespaceSchemaLocation attributes are to be taken
into consideration.
A document, element, or attribute node to be validated;
this is called the
A validation mode, which is one of strict
lax, or by-type.
XSLT also allows the value strip, but
this does not invoke validation (instead, it invokes stripping
of existing type annotations, and re-annotation of nodes as
xs:untyped.)
If the validation mode is by-type, then
a schema type to be used for validating the operand node.
This may be any simple or complex type present in the effective
schema: it must not be xs:untyped or xs:untypedAtomic.
An XQuery ValidateExpr allows the type to be
specified as xs:untyped or xs:untypedAtomic,
but this does not invoke validation (instead, it invokes stripping of
existing type annotations and re-annotation of nodes as untyped.)
The output of the validation process comprises one or more of the following:
A boolean indicating whether the operand node was found to be valid.
If the operand node was found to be valid, a deep copy of
the operand node augmented with
This creates a new node with its own identity and with no parent.
The base URI property of every node in the resulting XDM tree is the same as the base URI property of the corresponding node in the input tree.
If the operand node was not found to be valid, then optionally, a set of error diagnostics in implementation-defined format.
The operand node must be one of:
An element node
An attribute node
A well-formed document node, that is, a document node having among its children exactly one element node and zero or more comment and processing instruction nodes.
The term
Note that a
The result of the validation process is defined by the following rules.
The invoking application determines whether the validity assessment
process takes account of any xsi:schemaLocation or xsi:noNamespaceSchemaLocation
attributes in the tree being validated. If it does so, then it
Any schema loaded using these attributes must be
Any schema loaded using these attributes must not override or redefine any schema components in the effective schema.
Any schema components loaded using this mechanism must be used for this validity assessment only, and must not affect the outcome of any subsequent validity assessments of other documents.
A processor may choose to cache such schema components but the existence of such a cache should only affect performance, not the validation outcome.
A consequence of validating a document using schema components that are not
in the static context is that nodes may be annotated with types
that are not in the static context. But the rules for
If the instance being validated contains any xml:id attributes,
such attributes are validated against the type
xs:ID, making the containing element
eligible as a target for the xs:ID,
however, is carried out only if the operand node is a document node.
If the operand node is a document node:
The children of the document node
The element node child is validated, as described below.
The validation rule Validation Root Valid (ID/IDREF)
is
applied to the single element node child of the document node. This means
that validation will fail if there are non-unique ID values or dangling
IDREF values in the document tree.
This rule is
There is no check that the tree contains unparsed entities whose names match
the values of nodes of type xs:ENTITY or
xs:ENTITIES. This is because it is not possible
(either in XSLT or XQuery) to construct a tree containing
unparsed entities. It is possible to
add unparsed entity declarations to the result document by referencing a
suitable DOCTYPE during serialization.
All other children of the document node (comments and processing instructions) are copied unchanged, and the results become the children of a new document node, which is returned as the validation result.
If the operand node is an element node, then:
For specification purposes, because the XSD specifications
require the input document to be expressed as an XML Information Set
(
Validity assessment is carried out on the root element information item of the resulting Infoset, using the supplied schema. The process of validation applies recursively to contained elements and attributes to the extent required by the supplied schema.
A practical implementation is unlikely to perform any physical conversion, but the process is defined this way in order to align with the XSD specification.
If the validation mode is by-type, then
Schema-validity assessment is
carried out according to the rules defined in processor-stipulated type definition
for validation.
If validation mode is strict, then
strict validation is carried out as described in
have a name that matches a top-level element declaration in the effective schema, or
have an xsi:type attribute
whose value matches the name of a top-level type definition
in the effective schema
If there is no such element declaration or type definition, the element is assessed as invalid.
If validation mode is lax, then schema-validity
assessment is carried out in accordance with
If validation mode is lax and the root element
information item has neither a top-level element
declaration nor an xsi:type attribute, XSD 1.0
and XSD 1.1 define the recursive checking of children
and attributes as optional. This specification prescribes that this
recursive checking is required.
This means, for example, that when an instance document is structured as having an envelope in one namespace wrapping a payload in a different namespaces, and when schema definitions are available for the payload but not for the envelope, lax validation of the envelope may trigger validation of the payload.
If the operand node is an element node, the validation rules named “Validation Root Valid (ID/IDREF)” are not applied. This means that document-level constraints relating to uniqueness and referential integrity are not enforced.
There is no check that the document contains unparsed entities whose names match the
values of nodes of type xs:ENTITY or xs:ENTITIES.
If the operand node is an attribute node, in particular when it is a parentless attribute node, then validation cannot be defined directly in terms of the XSD-defined validation process. Instead, conceptually, a copy of the attribute is first added to an element node that is created for the purpose, and namespace fixup is performed on this element node to ensure that it has an in-scope namespace binding for the prefix and namespace of the attribute name. The name of this element is of no consequence, but it must be the same as the name of a synthesized element declaration of the form:
where A is the name of the attribute being validated.
This synthetic element is then validated using the procedure given above for
validating elements, and if it is found to be valid, a copy of the validated
attribute is made, retaining its
The XDM data model does not permit an attribute node with no parent to have a
typed value that includes a namespace-qualified name, that is, a value whose
type is derived from xs:QName or xs:NOTATION. This
restriction is imposed because these types rely on the in-scope namespaces of a
containing element to resolve namespace prefixes. Therefore,
a parentless attribute is considered to be invalid against such a type.
The outcome of the validation expression depends on the
validity property of the root element information item in the PSVI that results
from the XSD validation process.
If the validity property of the root element
information item is valid,
or if validation mode is
lax and the validity property of the root
element information item is notKnown,
the PSVI is converted back into a data model instance
as described in validate
expression.
Otherwise, the operand node is deemed invalid.
During conversion of the PSVI into an XDM instance
after validation, any element information items whose validity property is notKnown are
converted into element nodes with xs:anyType, and any attribute information items whose validity property is
notKnown are converted into attribute nodes with xs:untypedAtomic, as described in
Given an XSD schema, delivers a function item that can be invoked to validate a document, element, or attribute node against this schema.
This function is
The
The details of how the schema is assembled, and the way it is used, are defined by the supplied $options.
If the $options argument is empty, the effect is to use the schema components from the
static context of the call on
The static context of the function call
Explicitly supplied schema documents
Schema components referenced in xsi:schemaLocation and xsi:noNamespaceSchemaLocation
attributes within the instance document being validated.
More details of schema assembly appear below. Taken together, the assembled components must constitute a valid schema.
The function is designed to separate the process of assembling a schema from the process of performing instance
validation. However, if the schema is to include components identified in
xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes, then the process of
assembling the schema cannot be completed until the instance document is available.
The options recognized are as follows. The
| Key | Value | Meaning |
|---|---|---|
| Indicates whether the validation process may cause
external resources to be fetched (including, for example, documents
referenced using the schema-location
property, or xsi:schemaLocation attributes within
the document being validated).
| |
true | The validation process may retrieve external resources. | |
false | The validation process must not retrieve any external resources unless access to these resources has been explicitly enabled. | |
| If true, the schema to be used for validation includes the schema components
available in the static context of the function call. If false, these components
are not used.
| |
| A list of XDM nodes containing XSD schema documents to be used
for validation.
| |
| A list of target namespaces identifying schema components to be used for
validation. The way in which the processor locates schema components for the specified
target namespaces is
| |
| A list of locations of XSD schema documents to be used to assemble a schema.
Any relative URIs are resolved relative to the base URI of the function call.
Access to the schema documents at these locations is allowed regardless of the value
of the trusted option; access to indirectly referenced schema documents
(for example, using xs:include is allowed only if the trusted
option is set to true.
| |
| If true, the schema to be used for validation includes any schema documents
referenced by xsi:schemaLocation or xsi:noNamespaceSchemaLocation
attributes in the instance document being validated. If false, these attributes are ignored.
| |
| Set to the decimal value 1.0 or 1.1 to indicate which version of XSD is to be used.
The default is
| |
| The validation mode.
| |
strict | Validates the input using the element or attribute declaration for the
operand node. This element or attribute declaration must exist. This is the default
when the type option is absent. | |
lax | Validates the input using the element or attribute declaration for the operand node, if it exists. | |
by-type | Validates the input using the supplied governing type. This is the
default when the type option is present. | |
| Establishes the governing type for validation. The type must be present
in the assembled schema.
| |
| If true, the result of the generated validation function, when validation
is successful, includes the property typed-node which contains a copy of the
target node augmented with type annotations and expanded default values. If false, the typed
node is not included in the result. If a node containing type annotations is to be returned,
then the schema used for validation must be compatible with all other schemas used within
the same query or stylesheet, as described in
| |
| If true, the result of the generated validation function, when validation
is unsuccessful, includes detailed information about the nature of the validity errors
that were found. If false, the result only includes an indication that the document
was invalid. Note that setting the value to false means that validation can complete
as soon as the first error is found.
| |
The first task of the function is to assemble a schema (that is, a collection of schema components). Schema components can come from a number of sources, and a schema can be assembled from more than one source, provided that the total collection of components comprises a valid schema: the main thing that will prevent this is if two sources contain conflicting definitions of the same named component.
The default is to use the in-scope schema components from the static context of the function call.
Instead, or in addition, schema components may be loaded explictly for this validator. Supplementary schema components may be requested in a number of ways:
The schema-location option can specify one or more URIs that
are interpreted as locations for source XSD schema documents, which are then
assembled into a schema as described in the XSD specifications.
The schema option can be used to identify one or more
xs:schema element nodes holding source schema documents. This allows
a schema to be constructed dynamically by the application, or to be held as
a global variable in the source code of a query or stylesheet module.
The target-namespace option can be used to supply
the target namespaces of additional schema components that are known to the
system or that are made available using some external mechanism. For example,
the system might have built-in schemas for common namespaces such as
the xml, fn, or xlink namespaces,
or it might have a mechanism allowing schemas for a particular namespace
to be registered using an external API or configuration mechanism.
The use-xsi-schema-location also allows the application
to request that schema documents referenced from xsi:schemaLocation
or xsi:noNamespaceSchemaLocation attributes should be included
in the schema. By default these attributes are ignored.
It is acceptable to assemble a schema from more than one of these
sources. In addition, any of these sources can bring in additional components
by the use of the XSD directives xsl:include and xsl:import.
The important constraint is that the result should be a valid schema. This will only
be the case if the sources used to assemble the schema are
The XSD specification allows a schema to be used for validation even when
it contains unresolved
references to absent schema components. It is
Having assembled a schema, the next task is to validate a supplied node (and the subtree rooted at that node).
This description is a deliberate simplification. If the use-xsi-schema-location
option is true, then assembly of the schema is not completed until the instance document
is available, and in practice overlaps with the validation process.
The
V has an arity of one. Call the value of the supplied argument
$target. The required type of $target
is (document-node(*) | element() | attribute())?:
that is, it accepts either a well-formed
document node, or an element node, or an attribute node, or the empty sequence.
If the argument is the empty sequence then the result of V is also the empty sequence.
In other cases, the result of a call on V is a record containing the following fields:
is-valid as xs:boolean. This field is always present, and indicates
whether the supplied $target node was found to be valid against the schema.
The value is true if either (a) the validation outcome was valid, or
(b) lax validation was requested and the validation outcome was notKnown.
In other cases it is false.
typed-node as (document-node(*) | element() | attribute()).
This field is present
only when (a) the option return-typed-node was set (explicitly or implicitly)
to true, and (b) the value of the is-valid field is true.
It represents the root of a tree that is a deep copy of the input tree,
augmented with type annotations and default values.
error-details as map(*)*. This field is present only when (a) the option
return-error-details was set
to true, and (b) the supplied document was found to be invalid. The value is a sequence
of maps, each containing details of one invalidity that was found. The precise details of the
invalidities are
message. A string containing the text of an error message, intended
for a human reader.
rule. A reference to the rule in the XSD specification that was violated.
This is a string comprising four parts separated by the character
"1.0" or "1.1" indicating whether the reference is to the XSD 1.0 or 1.1 specification.
"1" or "2" indicating whether the reference is to part 1 or part 2 of the specification.
The name of the validation rule (for example "Datatype Valid").
The clause number within that validation rule (for example "2.3").
For example, if an attribute is declared to be of type xs:integer, but the
actual value is not in the lexical space of xs:integer, the value of rule
might be "1.1|2|Datatype Valid|2.1".
node. The node that was found to be invalid. Note that when a containing element
C is invalid because a child element D is not allowed by its content
model, the invalid node is C, not D.
error-node. The node whose presence led to detection of the invalidity. In the
above example, this would be D.
error-uri. The URI of the XML entity in which the error was detected.
line-number. The line number where the error was detected, within its external entity.
column-number. The column number where the error was detected, within the error line number.
The validation is performed as described in $target as the operand node.
If the use-xsi-schema-location option is true and a failure
occurs processing an xsi:schemaLocation or xsi:noNamespaceSchemaLocation
attribute (for example, because a schema document cannot be retrieved, or because the referenced
schema document is invalid, or because it is incompatible with other schema components)
this is treated as an invalidity, not as a dynamic error:
V returns successfully with is-valid set to false.
The function V may fail with a dynamic error if it is not possible to determine whether or not the instance document is valid. This may happen, for example, if processor-defined limits are exceeded.
A dynamic error is raised
A dynamic error is raised
Both XQuery and XSLT provide capabilities for XSD-based schema validation in earlier versions of the specifications, and those are retained in 4.0. This function provides additional capability:
It is possible to control validation more precisely, through a wider range of options;
It is possible to validate different instance documents against different schemas;
Information about any invalidities is made available to the application, rather than simply causing a dynamic error;
The capability is provided by means of a function rather than custom syntax, making it easier to integrate into an application.
The capability is available through XPath alone, and therefore with host languages other than XQuery and XSLT.
Three possible ways of using the function include:
To simply test whether or not a document is valid against a schema, set the options
return-typed-node and return-error-details to false,
and simply test the value of the is-valid field returned when the validation function
is called.
To obtain a typed XDM tree from an input document that is expected to be valid, set the
option return-typed-node to true. On return from the validation function, test the
value of the is-valid field; call typed-node property of the result. The main benefit of using a typed
XDM tree is that it allows static type checking of path expressions: this benefit only applies
when the schema used for validation is the imported schema used in the static context. However, there
are cases where validation against a different schema is appropriate, for example when validating the
result of one query or transformation that is to be used as input to another.
To validate an input document and provide feedback to the document author about any validity
problems that were found, set return-error-details to true. If the result
of the validation function has is-valid = false(), process the returned error-details.
The information available for this part of the processing may not be 100% interoperable, though with care it
should be possible to write the query in such a way that it works with different processors.
The function has no effect on the static context. Schemas loaded using this function, either directly or
via the effect of xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes, are not
added to the static context and have no effect on any other validation episodes. A processor may cache schema
components to reduce the cost of processing the same schema repeatedly, but this has no observable effect other than
on performance.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: |
This function converts between the lexical representation of HTML and the XDM tree representation.
| Function | Meaning |
|---|---|
fn:parse-html | This function takes as input an HTML document, and returns the document node at the root of an XDM tree representing the parsed document. |
fn:html-doc | Reads an external resource containing HTML, and returns the result of parsing the resource as HTML. |
The
The lexical HTML (supplied as a string) is parsed into an HTML DOM
as defined by the HTML5 specification: see
The resulting DOM is converted to an XDM tree as described in this
section. This is described by defining the actions of the accessor functions
defined in
Because the
An implementation must match the semantics of the mapping described in this section, but
the specific way it achieves that is
Some possible implementation strategies are:
Parse the HTML to an HTML DOM and then convert the HTML DOM to an XDM node tree.
Parse the HTML to an HTML DOM and then implement a wrapper or facade that presents an XDM interface to the HTML DOM.
Parse the lexical HTML directly to an XDM node tree, bypassing the HTML DOM.
The http://www.w3.org/1999/xhtml and the content type
application/xhtml+xml, and is popularly referred to as XHTML.
The HTML parsing algorithm constructs
an HTML DOM HTMLDocument document object for the HTML document. The XHTML parsing
algorithm constructs an HTML DOM XMLDocument object for the HTML document, following
XML parsing rules. This mapping supports both of these document types.
The
The HTML DOM Document interface maps to
The HTML DOM Element interface maps to template element.
The HTML DOM Attr interface maps to
Any HTML DOM Attr instances in an HTML DOM HTMLDocument that represent
namespace declarations will have been filtered out: see
The HTML DOM ProcessingInstruction interface maps to
The HTML parsing algorithm does not generate processing instruction nodes. If encountered
they are parsed as comment nodes. The HTML DOM ProcessingInstruction
interface is relevant only when the XHTML parsing algorithm is used.
The HTML DOM Comment interface maps to
The HTML DOM Text interface maps to Text nodes are combined into a single
The HTML DOM CDATASection interface is an instance of HTML DOM
Text, so CDATA sections also map to
The use of CDATA sections can result in the HTML DOM containing adjacent text nodes, which the mapping to XDM will merge into a single node.
An HTML template element is mapped to an XDM template
element with children corresponding to the children of the HTML DOM DocumentFragment
that is the value of the template element.
Given source HTML such as <template><p>Lorem ipsum</p></template>,
the HTML DOM represents the element <p>Lorem ipsum</p>
not as a child of the template element, but as the child of a free-standing
document fragment which is accessible (in the DOM API) as the value of the
template.content property of the element node. The XDM representation produced
by the <p>Lorem ipsum</p> appears as an ordinary child node of the
template element.
The HTML DOM DocumentFragment interface is not supported as an XML node.
There are two places in the HTML DOM where this is used:
The HTML DOM ShadowRoot interface is not present in the main HTML DOM
tree. It is only accessible via JavaScript.
The template element’s content property contains
the child nodes of the template element. The behaviour of this
is described above.
If an implementation allows these nodes to be passed in via an API or similar mechanism,
their behaviour is
The result of the dm:attributes($node) for an HTML DOM Node is as follows:
If the node is an instance of HTML DOM Element then the result
is the value of the Element.attributes property mapped to a
sequence as described below;
Otherwise, the result is the empty sequence.
An HTML DOM NamedNodeMap is mapped to a sequence as follows:
NamedNodeMap.length is the length of the sequence, where a length
of 0 results in the empty sequence;
NamedNodeMap.item(n) is the nth element of the sequence.
That sequence is then filtered as follows:
If the Attr.namespaceURI property is
"http://www.w3.org/2000/xmlns/", the attribute is not included in
this sequence;
If the Attr.localName property is "xmlns", the attribute
is not included in this sequence;
If the Attr.localName property starts with "xmlns:",
the attribute is not included in this sequence;
Otherwise, the attribute is included in this sequence using the XDM mapping rules described in this section.
The HTML DOM Element.attributes property includes namespace and non-namespace
attributes in the list when the HTML or XML parser is used. As such, the namespace attributes
have to be filtered from the resulting XDM attribute sequence.
When the resulting document is an HTML DOM HTMLDocument, the
Attr.localName and Attr.name properties of HTML DOM
Attr nodes are both set to the qualified name. This includes
namespace declarations which are filtered out by the logic in this section.
The Attr.localName property will be ASCII lowercase. The
The result of the dm:base-uri($node) for an HTML DOM Node is the value of the
Node.baseURI property mapped as follows:
If the value is null or the zero-length string, then the result is the empty sequence;
Otherwise, the string value is cast to an xs:anyURI.
The result of the dm:children($node) for an HTML DOM Node is as follows:
If the node is an instance of HTML DOM Document then the result
is the value of the Node.childNodes property mapped to a sequence;
If the node is an instance of HTML DOM HTMLTemplateElement then the
result is the HTML DOM DocumentFragment’s Node.childNodes
property, mapped to a sequence;
If the node is an instance of HTML DOM Element then the result the
value of the Node.childNodes property mapped to a sequence;
Otherwise, the result is the empty sequence.
An HTML DOM NodeList is mapped to a sequence as follows:
NodeList.length is the length of the sequence, where a length
of 0 results in the empty sequence;
NodeList.item(n) is the nth element of the sequence.
That sequence is then filtered as follows:
If the child is an instance of HTML DOM DocumentType, that child
is not included in this sequence;
A sequence of consecutive HTML DOM Text nodes is combined into a
single XDM text node;
Otherwise, the HTML DOM Node nodes are mapped to XDM according to
the rules in this section.
The result of the dm:document-uri($node) for an HTML DOM Node is as follows:
If the node is an instance of HTML DOM Document then the value
of the Document.documentURI property mapped as follows:
If the value is null or the zero-length string, then the result is the empty sequence;
Otherwise, the string value is cast to an xs:anyURI.
Otherwise, the result is the empty sequence.
The result of the dm:is-id($node) for an HTML DOM Node is as follows:
If the node is an instance of HTML DOM Attr then:
If the Attr.name property (its qualified name) is
"id", then:
If the Attr.value is castable to an xs:NCName,
the result is true;
Otherwise, the result is false;
Otherwise, the result is false;
Otherwise, the result is false.
In id attribute is defined as being unique in the element’s tree,
containing at least one character, and not having any ASCII whitespace
characters. This means that an HTML id attribute may not
conform to an xs:NCName.
If an HTML id is not a valid xs:NCName then that
attribute is not an XML ID.
The result of the dm:is-idrefs($node) for an HTML DOM Node is the empty sequence.
The result of the dm:namespace-nodes($node) for an HTML DOM Node is as follows:
If the node is an instance of HTML DOM Element then an
Otherwise, the result is the empty sequence.
For the XHTML parsing algorithm, this will be equivalent to constructing the namespace nodes from an XML infoset, PSVI, or similar mapping.
For the HTML parsing algorithm, the
Section 2.1.3 http://www.w3.org/1999/xhtml.
Section 4.8.15 http://www.w3.org/1998/Math/MathML).
The default element namespace for these elements is the MathML namespace.
Section 4.8.16 http://www.w3.org/2000/svg).
The default element namespace for these elements is the SVG namespace.
Section 13.1.2.3
The supported namespace prefixes are:
xlink in the http://www.w3.org/1999/xlink namespace;
xml in the http://www.w3.org/XML/1998/namespace namespace; and
xmlns in the http://www.w3.org/2000/xmlns/ namespace.
No other namespaces are supported by the HTML parser.
Section number references to
The result of the dm:nilled($node) for an HTML DOM Node is false().
The result of the dm:node-kind($node) for an HTML DOM Node is as follows:
If the node is an instance of HTML DOM Document then the result is
"document".
If the node is an instance of HTML DOM Element then the result is
"element".
If the node is an instance of HTML DOM Attr then the result is
"attribute".
If the node is an instance of HTML DOM ProcessingInstruction then
the result is "processing-instruction".
If the node is an instance of HTML DOM Comment then the result is
"comment".
If the node is an instance of HTML DOM Text then the result is
"text".
The result of the dm:node-name($node) for an HTML DOM Node is as follows:
If the node is an instance of HTML DOM Element then the result is
determined as follows:
The Element.localName property. This is derived as follows:
The local name is initially set to the ASCII lowercase tag name. The
If the local name is an SVG element name, the case-sensitive name is used.
If the local name contains a character that is not a valid XML
NameStartChar or NameChar, then an
NCName.
Unnnnnn escape sequence. That would map :
to U00003A.
This local name escaping applies only to the HTML parsing algorithm.
If the XHTML parsing algorithm is used, the localName and
prefix will be correctly set for QName-based
node names.
The Element.prefix property, or empty if the value is null;
The Element.namespaceURI property, or empty if the value
is null.
If the element is an HTML element, the namespace URI is
"http://www.w3.org/1999/xhtml".
If the element is an SVG element, the namespace URI is
"http://www.w3.org/2000/svg".
If the element is a MathML element, the namespace URI is
"http://www.w3.org/1998/Math/MathML".
If the node is an instance of HTML DOM Attr then the result is
determined as follows:
The
The Attr.localName property. This is derived as follows:
The local name is initially set to the
If the local name is an SVG or MathML attribute name, the case-sensitive name
is used.
If the local name is an allowed xlink, xml, or
xmlns attribute name the local name is the value of the local name
column of the attribute name mapping table in
If the local name contains a character that is not a valid XML
NameStartChar or NameChar, then an
NCName.
Unnnnnn escape sequence. That would map :
to U00003A.
This local name escaping applies only to the HTML parsing algorithm.
If the XHTML parsing algorithm is used, the localName and
prefix will be correctly set for QName-based
node names.
The Attr.prefix property, or empty if the value is null.
If the attribute name is an allowed xlink, xml, or
xmlns attribute name the namespace prefix is the value of the
prefix column of the attribute name mapping table in
The Attr.namespaceURI property, or empty if the value is null;
If the attribute name is an allowed xlink, xml, or
xmlns attribute name the namespace URI is the value of the
namespace column of the attribute name mapping table in
If the node is an instance of HTML DOM ProcessingInstruction then
the result is an xs:QName constructed as follows:
The ProcessingInstruction.target property;
The
The
Otherwise, the result is the empty sequence.
When the resulting document is an HTML DOM HTMLDocument, the
Element.localName and Element.name properties of
HTML DOM Element nodes are both set to the qualified name.
When the resulting document is an HTML DOM HTMLDocument, the
Attr.localName and Attr.name properties of HTML DOM
Attr nodes are both set to the qualified name.
The result of the dm:parent($node) for an HTML DOM Node is as follows:
Let $parent be the Node.parentNode property of the
node;
If $parent is an instance of HTML DOM DocumentFragment,
then for each HTML DOM HTMLTemplateElement $template in
the parsed DOM tree:
Let $content be the value of the
HTMLTemplateElement.content property of $template;
If $content is the same node as $parent, then the
result is $template using the XDM mapping rules described in
this section;
If there are no more $template nodes, then the result is an
empty sequence;
If $parent is null, then the result is the empty sequence;
Otherwise, the result is $parent using the XDM mapping rules
described in this section.
The current node can have a HTML DOM DocumentFragment parent node only
if the include-template-content key of the html-parser-options
is true().
The HTML DOM DocumentFragment’s Node.parentNode property
is null, and a DocumentFragment attached to HTMLTemplateElement.content
property does not have a host property connecting the fragment back to
the template element.
If a future version of DocumentFragment.host
property that references the node’s template element, or the implementation
has access to that internal property, the implementation may choose to use that
instead of traversing the parsed HTML tree.
The result of the dm:string-value($node) for an HTML DOM Node is as follows:
If the node is an instance of HTML DOM Document, then use the
algorithm described in
If the node is an instance of HTML DOM Element, then use the
algorithm described in
If the node is an instance of HTML DOM Text, then use the
algorithm described in
Otherwise, the result is the value of the Node.nodeValue property.
The following algorithm is used to construct the concatenated string value of a node in the HTML DOM tree:
Let $text be the string value "";
For each descendant node $node in document order:
If $node is not an instance of HTML DOM
Text, process the next node in document order;
Append the value of the Node.nodeValue property for
$node to $text;
The result is $text.
The following algorithm is used to construct the maximal sequence of adjacent
Let $text be the string value "";
Append the value of the Node.nodeValue property for
$node to $text;
Let $next be the value of Node.nextSibling;
Let $next is null, or not an instance of HTML DOM
Text, the result is $text;
Otherwise, repeat from step 2 using $next as $node.
Adjacent text nodes in the HTML DOM are treated as a single XDM text node by only including the first text node and providing logic to ensure that the text content is merged into a single text block.
The result of the dm:type-name($node) for an HTML DOM Node is as follows:
If the node is an instance of HTML DOM Element then the result is
xs:untyped.
If the node is an instance of HTML DOM Attr then the result is
xs:untypedAtomic.
If the node is an instance of HTML DOM Text then the result is
xs:untypedAtomic.
Otherwise, the result is the empty sequence.
The result of the dm:typed-value($node) for an HTML DOM Node is as follows:
Let $string-value be the
If the node is an instance of HTML DOM Document then the result is
$string-value as an xs:untypedAtomic;
If the node is an instance of HTML DOM Element then the result is
$string-value as an xs:untypedAtomic;
If the node is an instance of HTML DOM Attr then the result is
$string-value as an xs:untypedAtomic;
If the node is an instance of HTML DOM Text then the result is
$string-value as an xs:untypedAtomic;
Otherwise, the result is $string-value.
The result of the dm:unparsed-entity-public-id($node) for an HTML DOM Node
is the empty sequence.
The result of the dm:unparsed-entity-system-id($node) for an HTML DOM Node
is the empty sequence.
This function takes as input an HTML document, and returns the document node at the root of an XDM tree representing the parsed document.
This function is
If $value is the empty sequence, the function returns the empty sequence.
In other cases, $value is expected to contain an HTML document supplied
either as a string or a binary value.
The entries that may appear in the $options map are as follows:
| Key | Value | Meaning |
|---|---|---|
|
The character encoding to use to decode a sequence of octets that represents an HTML document. Note that encoding names are case-insensitive.
| |
|
Indicates whether the function should fail with a dynamic error if the input is not syntactically valid.
| |
false |
Parsing errors should be handled as described in
| |
true | A parsing error should result in the function failing with a dynamic error. | |
The
If $value is not the empty sequence, an input byte stream is constructed as follows:
If $value is an xs:string, then in principle no decoding is needed.
Conceptually, however, the HTML parsing algorithm always starts by decoding an octet
stream. The string is therefore first encoded using UTF-8, and the resulting octet
stream is then passed to the HTML parser with a
If the first codepoint of the string is
If the type of $value is a sequence of octets (xs:hexBinary or
xs:base64Binary) the encoding of the input byte stream is determined in a
way consistent with
The encoding key of $options is interpreted in step 2 of
If the encoding key of $options is not specified, step 2
of
Tokenizing the byte stream according to the HTML parsing algorithm as described in
Constructing a HTMLDocument object for HTML documents, or an
XMLDocument for XML/XHTML documents as described in
Building an XDM representation of the HTMLDocument or XMLDocument
according to the rules in
The implementation
The implementation
The function is
A dynamic error is raised $value is not a well-formed HTML document. This includes the case
where $value cannot be decoded using the specified encoding.
If the HTML parser accepts a string as the input then that may be used directly when
$value is an xs:string instead of converting the string to
a sequence of octets in an
The WHATWG Encoding specification defines the ISO 8859-1 (latin1) and ASCII encodings as aliases of the windows-1252 encoding.
The expression | |
The expression | |
The expression |
Reads an external resource containing HTML, and returns the result of parsing the resource as HTML.
This function is
The effect of the two-argument function call fn:html-doc($H, $M)is equivalent to the function composition
fn:unparsed-binary($H) => fn:parse-html($M).
If $source is the empty sequence, the function returns the empty sequence.
The ability to access external resources depends on whether the
calling code is
The function may raise any error defined for the
The functions listed in this section parse or serialize JSON data.
JSON is a popular format for exchange of structured data on the web: it is specified in
This specification describes two ways of representing JSON data losslessly using XDM constructs. The first method uses XDM maps to represent JSON objects, and XDM arrays to represent JSON arrays. The second method represents all JSON constructs using XDM element and attribute nodes.
| Function | Meaning |
|---|---|
fn:parse-json | Parses input supplied in the form of a JSON text, returning the results typically in the form of a map or array. |
fn:json-doc | Reads an external resource containing JSON, and returns the result of parsing the resource as JSON. |
fn:json-to-xml | Parses a string supplied in the form of a JSON text, returning the results in the form
of an XML |
fn:xml-to-json | 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. |
Note also:
The function
The function
This section defines a mapping from JSON data to XDM maps and arrays. Two functions are available
to support this mapping:
The conversion is lossless if recommended JSON good practice is followed. Information may however be lost if (a) JSON numbers are not exactly representable as double-precision floating point, or (b) duplicate key values appear within a JSON object.
The representation of JSON data produced by the { "Sun": 1, "Mon": 2, "Tue": 3, ... } produces a simple map, so if the result
of parsing is held in $weekdays, the number for a given weekday can be extracted
using an expression such as $weekdays?Tue. Similarly, a simple array such as
[ "Sun", "Mon", "Tue", ... ] produces an array that can be addressed as, for example,
$weekdays(3). A more deeply nested structure can be addressed in a similar way:
for example if the JSON text is an array of person objects, each of which has a property named
phones which is an array of strings containing phone numbers, then the first phone number of
each person in the data can be addressed as $data?phones(1).
This section defines a mapping from JSON data to XML (specifically, to XDM element and attribute nodes). A
function
The XML representation is designed to be capable of representing any valid JSON text including one that uses characters which are not valid in XML. The transformation is normally lossless: that is, distinct JSON texts convert to distinct XML representations. When converting JSON to XML, options are provided to reject unsupported characters, to replace them with a substitute character, or to leave them in backslash-escaped form.
The conversion is lossless if recommended JSON good practice is followed. Information may however be lost if (a) JSON numbers are not exactly representable as double-precision floating point, or (b) duplicate key values appear within a JSON object.
The following example demonstrates the correspondence of a JSON text and the corresponding XML representation.
Consider the following JSON text:
The XML representation of this text is as follows. Whitespace is included in the XML representation for purposes of illustration,
but it will not necessarily be present in the output of the
An XSD 1.0 schema for the XML representation is provided in http://www.w3.org/2005/xpath-functions, then:
Unless the host language specifies otherwise, the processor (if it is schema-aware)
If a schema location is provided, then the schema document at that location
The rules governing the mapping from JSON to XML are as follows. In these rules, the phrase
“an element named N” is to be interpreted as meaning “an element node whose local name is N and whose
namespace URI is http://www.w3.org/2005/xpath-functions”.
The JSON value null is represented by an element named null, with empty content.
The JSON values true and false are represented by an element named boolean,
with content conforming to the type xs:boolean. When the element is created by the
true or false.
The xs:boolean,
for example 1 and 0. Leading and trailing whitespace is accepted.
A JSON number is represented by an element named number,
with content conforming to the type xs:double, with the additional restriction that the value
must not be positive or negative infinity, nor NaN. The
xs:double and then casting the result to xs:string.
Leading and trailing whitespace is accepted.
Since JSON does not impose limits on the range or precision
of numbers, these rules mean that conversion from JSON to XML will always succeed, and will retain full precision
in the lexical representation unless the data model implementation is one that reconstructs the string value from
the typed value. In the reverse direction, conversion from XML to JSON may fail if the value is infinity or NaN,
or if the string value is such that casting to xs:double produces positive or negative infinity.
A JSON string is represented by an element named string, with
content conforming to the type xs:string. The string element has two
alternative representations: escaped form, and unescaped form.
A JSON array is represented by an element named array. The content is a sequence of
child elements representing the members of the array in order, each such element being the representation
of the array member obtained by applying these rules recursively.
A JSON object is represented by an element named map. The content is a sequence
of child elements each of which represents one of the name/value pairs in the object. The representation of the
name/value pair N:V is obtained by taking the element that represents the value V (by applying these
rules recursively) and adding an attribute with name key (in no namespace), whose
value is N as an instance of xs:string. The functions
The attribute escaped="true" may be specified on a string element to indicate
that the string value contains backslash-escaped characters that are to be interpreted according to the JSON
rules. The attribute escaped-key="true" may be specified on any element with a key attribute to indicate
that the key contains backslash-escaped characters that are to be interpreted according to the JSON
rules. Both attributes have the default value false, signifying that the relevant value is in unescaped form.
In unescaped form, the backslash character has no special significance (it represents itself).
The JSON grammar for number is a subset of the lexical space of
the XSD type xs:double. The mapping from JSON number values to xs:double
values is defined by the XPath rules for casting from xs:string to xs:double. Note that
these rules will never generate an error for out-of-range values; instead very large or very small values will be
converted to +INF or -INF. Since JSON does not impose limits on the range or precision
of numbers, the conversion is not guaranteed to retain full precision.
Although the order of entries in a JSON object is generally considered to have no significance, the functions
json-to-xml and xml-to-json both retain order.
The XDM representation of a JSON value may either be untyped (all elements annotated as xs:untyped, attributes
as xs:untypedAtomic), or it may be typed. If it is typed, then it http://www.w3.org/2005/xpath-functions
are ignored, including attributes such as xsi:type and xsi:nil that would normally influence the process
of schema validation.
The namespace prefix associated with the namespace http://www.w3.org/2005/xpath-functions (if any) is immaterial.
The effect of the
The set of characters that may appear in JSON texts is not the same as the set of characters allowed in XML. Specifically:
As plain unescaped characters, JSON allows any codepoint in the
numeric range 0x20 to 0x10FFFF, with the exception of
As a backslash-escaped character, JSON allows any codepoint in the numeric range 0x00 to 0xFFFF.
Whether escaped or not, the JSON grammar allows codepoints in the surrogate range to appear, and does not explicitly require that they be properly paired. However, the JSON specifications recognize that unpaired surrogates are likely to lead to interoperability problems.
Ignoring unpaired surrogates, this means that JSON allows codepoints that are not allowed by XML:
Not allowed by XML 1.0: 0x00 to 0x1F (other than 0x09, 0x0A, and 0x0D); 0xFFFE; 0xFFFF.
Not allowed by XML 1.1: 0x00; 0xFFFE; 0xFFFF.
The XDM data model (see xs:string data type in such a way that any
Unicode codepoint assigned to a character (which excludes surrogates)
is allowed. However, this
is not required: a conformant implementation
In consequence, parsing of conformant JSON texts may fail if they contain codepoints that the implementation does not support. However, if such codepoints are represented in the input using JSON escape sequences, these specifications define mechanisms for dealing with them, for example by substituting a replacement character.
null value should be handled.xs:double values should translate
to positive or negative infinity.escape option has been changed to false. The 3.1
specification gave the default value as true, but this appears to have been an error,
since it was inconsistent with examples given in the specification and with tests in the test suite.Parses input supplied in the form of a JSON text, returning the results typically in the form of a map or array.
This function is
The first argument is a JSON text as defined in
If $value is the empty sequence, the function returns the empty sequence.
If the input is "null", the result will also be 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:
| Key | Value | Meaning |
|---|---|---|
| Determines whether deviations from the syntax of RFC7159 are permitted.
| |
false |
The input JSON-text in | |
true |
The input | |
| Determines the policy for handling duplicate keys in a JSON object.
To determine whether keys are duplicates, they are compared using the Unicode codepoint collation, after expanding escape
sequences, unless the escape option is set to true
| |
reject |
An error is raised | |
use-first | If duplicate keys are present in a JSON object, all but the first of a set of duplicates are ignored. | |
use-last | If duplicate keys are present in a JSON object, all but the last of a set of duplicates are ignored. | |
| Determines whether special characters are represented in the XDM output in backslash-escaped form.
| |
false |
Any fallback function
as described below; in the absence of a fallback function, it is replaced by
| |
true |
JSON escape sequences are used in the result to represent special characters in the JSON input, as defined below,
whether or not they were represented using JSON escape sequences in the input.
The characters that are considered “special” for this purpose are:
all codepoints in the range all codepoints that do not represent
the character \t), or a six-character escape sequence otherwise
(for example \uDEAD). Characters other than these are not escaped in the result, even if they
were escaped in the input.
| |
|
Provides a function which is called when the input contains an escape sequence
that represents a character that is not a fallback option if the escape
option is present with the value true.
| |
User-supplied function |
The function is called when the JSON input contains character that
is not a liberal:true() is specified):
for example \b or \uFFFF or \uDEAD.
By default, the escape sequence is replaced with the Unicode
| |
| Determines how the JSON null value should be represented.
| |
Value |
The supplied XDM value is used to represent the JSON null value.
The default representation of null is the empty sequence, which works
well in cases where setting a property of an object to null has the
same meaning as omitting the property. It works less well in cases where null
is used with some other meaning, because expressions such as the lookup operator
? flatten the result to a single sequence of items,
which means that any entries whose value is the empty sequence effectively disappear.
The property can be set to any XDM value; a suggested value is the xs:QName
value fn:QName("http://www.w3.org/2005/xpath-functions", "null"),
which is recognized by the JSON serialization method as representing the JSON value
null.
| |
| Determines how numeric values should be processed.
| |
User-supplied function |
The supplied function is called to process the string value of any JSON number
in the input. By default, numbers are processed by
converting to xs:double using the XPath casting rules.
Supplying the value xs:decimal#1 will instead convert to xs:decimal
(which potentially retains more precision, but disallows exponential notation), while
supplying a function that casts to (xs:decimal | xs:double) will treat
the value as xs:decimal if there is no exponent, or as xs:double
otherwise. Supplying the value fn:identity#1 causes the value to be retained
unchanged as an xs:untypedAtomic.
If the liberal option is false (the default), then
the supplied number-parser is called if and only if the value conforms
to the JSON grammar for numbers (for example,
a leading plus sign and redundant leading zeroes are not allowed). If the liberal
option is true then it is also called if the value conforms to an
| |
The various structures that can occur in JSON are transformed recursively to XDM values as follows:
A JSON xs:string; the
associated value may be of any type, and is the result of converting the JSON
value by recursive application of these rules. For example, the JSON text
{ "x": 2, "y": 5 } is transformed to the value
{ "x": 2, "y": 5 }.
If duplicate keys are encountered in a JSON duplicates option defined above.
The order of entries is retained.
A JSON [ "a", "b", null ] is transformed (by default) to the value
[ "a", "b", () ].
A JSON xs:string value.
escape and fallback options, as described in the table above.
A JSON number-parser option; by default it isxs:double value using
the rules for casting from xs:string to xs:double.
The casting rules leave implementations some flexibility as to how values should be handled when they
are too large to represent as an xs:double. It is 1e9999
or -1e9999 respectively.
Round-tripping of NaN can be achieved by setting the option "null": number("NaN")
The JSON true and false are
converted to the corresponding xs:boolean values.
The JSON value null option, which defaults to an
empty sequence.
A dynamic error $value does not conform to the JSON grammar, unless the option
"liberal":true() is present and the processor chooses to accept the deviation.
A dynamic error "duplicates": "reject" is present and the value of
$value contains a JSON object with duplicate keys.
A dynamic error $options
map contains an entry whose key is defined in this specification and whose value is not valid for that key,
or if it contains an entry with the key fallback when the option "escape":true()
is also present.
The result of the function will be an instance of one of the following types. An
instance of test (or in XQuery, typeswitch) can be used to
distinguish them:
map(xs:string, item()?) for a JSON object
array(item()?) for a JSON array
xs:string for a JSON string
xs:double for a JSON number
xs:boolean for a JSON boolean
empty-sequence() for a JSON null (or for empty input)
If the source of the JSON input is a resource accessible by URI, then it may be preferable
to use the xs:hexBinary
or xs:base64Binary) then this can first be decoded as a string using the functions
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. This is because the input to the function
is an instance of xs:string, which by definition (see
The serializer provides an option to output data in unparsed-text-lines($uri) =!> parse-json().
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Reads an external resource containing JSON, and returns the result of parsing the resource as JSON.
This function is
The effect of the two-argument function call fn:json-doc($H, $M)is equivalent to the function composition
fn:unparsed-text($H) => fn:parse-json($M), except that:
The function may accept a resource in any encoding. [RFC 7159] requires UTF-8, UTF-16, or UTF-32 to be accepted, but it is not an error if a different encoding is used. Unless external encoding information is available, the function must assume that the encoding is one of UTF-8, UTF-16, or UTF-32, and must distinguish these cases by examination of the initial octets of the resource.
Having established the encoding, the function must accept any codepoint that can validly occur in a JSON text, with the exception of unpaired surrogates.
If $source is the empty sequence, the function returns the empty sequence.
The ability to access external resources depends on whether the
calling code is
The function may raise any error defined for the
An initial byte order mark is dropped, as with the
If the input cannot be decoded (that is, converted into a sequence of Unicode codepoints, which may or may not represent characters),
then a dynamic error occurs as with the
If the input can be decoded,
then the possibility still arises that the resulting sequence of codepoints includes codepoints that are
not \uFFFF),
and the JSON escape sequence is then passed to the fallback function specified in the $options argument, which in turn
defaults to a function that returns
The function text/xml
and application/xml may be skipped.
Parses a string supplied in the form of a JSON text, returning the results in the form
of an XML
This function is
The first argument is a JSON text as defined in
If $value is the 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:
| Key | Value | Meaning |
|---|---|---|
| Determines whether deviations from the syntax of RFC7159 are permitted.
| |
false |
The input JSON-text in | |
true |
The input | |
| Determines the policy for handling duplicate keys in a JSON object.
To determine whether keys are duplicates, they are compared using the Unicode codepoint collation, after expanding escape
sequences, unless the escape option is set to true
| |
reject |
An error is raised | |
use-first | If duplicate keys are present in a JSON object, all but the first of a set of duplicates are ignored. | |
retain |
If duplicate keys are present in a JSON object, the XML result of the function will also contain duplicates (making
it invalid against the schema). This value is therefore incompatible with the option validate=true
| |
| Determines whether the generated XML tree is schema-validated.
| |
true |
Indicates that the resulting XDM instance must be typed; that is, the element
and attribute nodes must carry the type annotations that result from validation
against the schema given at liberal option has the value true.
| |
false | Indicates that the resulting XDM instance must be untyped. | |
| Determines whether special characters are represented in the XDM output
in backslash-escaped form.
| |
false |
All characters in the input that are valid
in the version of XML supported by the implementation, whether or not they are represented
in the input by means of an escape sequence, are represented as unescaped characters in the result. Any
characters or codepoints that are not valid XML characters
(for example, unpaired surrogates) fallback function
as described below; in the absence of a fallback function, they are replaced by
the character escaped and escaped-key will not be present in the XDM output.
| |
true |
JSON escape sequences are used in the result to represent special characters in the JSON input, as defined below,
whether or not they were represented using JSON escape sequences in the input.
The characters that are considered “special” for this purpose are:
all codepoints in the range 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 ( \t), or a six-character 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 Any element that contains a The values of the | |
|
Provides a function which is called when the input contains an escape sequence
that represents a character that is not valid in the version of XML
supported by the implementation.
It is an error to supply the fallback option if the escape
option is present with the value true.
| |
User-supplied function |
The function is called when the JSON input contains an escape sequence
that is valid according to the JSON grammar, but which does not represent a
character that is valid in the version of XML supported by the processor.
In the case of surrogates, it is called once for any six-character escape sequence
that is not properly paired with another surrogate. The untyped atomic item
supplied as the argument will always be a two- or six-character escape
sequence, starting with a backslash, that conforms to the rules in the JSON grammar
(as extended by the implementation if liberal:true() is specified):
for example \b or \uFFFF or \uDEAD.
By default, the escape sequence is replaced with the Unicode
| |
| Determines how numeric values should be processed.
| |
User-supplied function |
The supplied function is called to process the string value of any JSON number
in the input. The string value of the number element generated in
the result will be the value obtained by calling the supplied function, and
then converting its result to a string by calling fn:string#1.
By default, numbers are represented in the XML output exactly as they
were written in the input.
Supplying the value | |
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
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, nor in the value of escaped or escaped-key
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 escaped-key whose value is either
true or false.
If the result is untyped, the attributes escaped and escaped-key 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
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("2000-12-13") 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
implementation-defined, 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. This is the only possibility because the input to the function
is an instance of xs:string, which by definition can contain only those characters that are valid in XML.
| Expression: | |
|---|---|
| Result: | (with whitespace added for legibility) |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | (with whitespace added for legibility) |
| Expression: | |
| Result: | (with whitespace added for legibility)
|
The following example illustrates use of the | |
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.
This function is
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:
| Key | Value | Meaning |
|---|---|---|
| Determines whether the character \/. By default the character is escaped, but this is only necessary
when the resulting JSON is embedded in HTML.
| |
false |
The character | |
true |
The character | |
| Determines whether additional whitespace should be added to the output to improve readability.
| |
false | The processor must not insert any insignificant whitespace between JSON tokens. | |
true |
The processor | |
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/xpath-functions, 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 escaped-key attribute
provided that E would satisfy one of the above
conditions if the key and/or escaped-key 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 descendant-or-self of
$node and has local name map and namespace URI http://www.w3.org/2005/xpath-functions
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 escaped-key="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 escaped-key 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 phrase
“an element named N” means “an element node whose local name is N and whose namespace URI is
http://www.w3.org/2005/xpath-functions”.
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.
The input is required to conform to the XSD rules defining a valid instance of xs:double
(excluding infinity and NaN), while the output is required to conform to the
JSON rules defining a valid JSON number. These rules are slightly different.
Specifically, the XSD rules require the value (after removing leading and trailing whitespace) to match the regular expression:
while the JSON rules require:
If the input value does not match the required JSON format, it must therefore be adjusted by applying the following steps:
Remove leading and trailing whitespace.
Remove any leading plus sign.
Remove any leading zero digits in the integer part, while ensuring that at least one digit remains.
If there is a decimal point that is not preceded by a digit, add a zero digit before the decimal point.
If there is a decimal point that is not followed by a digit, add a zero digit after the decimal point.
The output uses exponential notation if and only if the input uses exponential notation.
The rules have changed since version 3.1 of this specification. In previous versions, the supplied
number was cast to an xs:double, and then serialized using the rules of the
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. The order of properties in the output JSON representation retains the order
of the children of the map element.
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 escaped-key="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 unescaped occurrence of escape-solidus option) \", \b, \f, \n, \r, \t, \/
any other codepoint in the range 1-31 or 127-159 is replaced by an escape in the form \uHHHH where HHHH is the upper-case hexadecimal representation of the codepoint value.
Otherwise (that is, in the absence of the attribute escaped="true" for a string value,
or escaped-key="true" for a key value):
any occurrence of backslash is replaced by \\
any occurrence of
\", \b, \f, \n,
\r, or \t respectively;
any other codepoint in the range 1-31 or 127-159 is replaced by an escape in
the form \uHHHH where HHHH is the upper-case hexadecimal representation of the codepoint value.
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.
A dynamic error is raised $node is not a document or element node or is not valid according to the schema for the XML representation of
JSONmap element has two children whose normalized key values are the same.
A dynamic error is raised $node includes a string labeled with escaped="true", or
a key labeled with escaped-key="true", where the content of the string or key
contains an invalid JSON escape sequence: specifically, where it contains a backslash (\) that is not followed by one
of the characters ", \, /, b, f, n,
r, t, or u, or where it contains the characters \u
not followed by four hexadecimal digits (that is [0-9A-Fa-f]{4}).
The rule requiring schema validity has a number of consequences, including the following:
The input cannot contain no-namespace attributes, or attributes in the namespace http://www.w3.org/2005/xpath-functions,
except where explicitly allowed by the schema. Attributes in other namespaces, however, are ignored.
Nodes that do not affect schema validity, such as comments, processing instructions, namespace nodes, and whitespace text node
children of map and array, are ignored.
Numeric values are restricted to those that are valid in JSON:
the schema disallows positive and negative infinity and NaN.
Duplicate key values are not permitted. \n and \u000A are treated as duplicates even though
the rules in the schema do not treat them as such.
The rule allowing the top-level element to have a key attribute (which is ignored)
allows any element in the output of the key attribute, and then convert this subtree
back to JSON, perhaps after a transformation. The rule means that an element with the appropriate name will be
accepted if it has been validated against one of the
types mapWithinMapType, arrayWithinMapType, stringWithinMapType,
numberWithinMapType, booleanWithinMapType, or nullWithinMapType.
The input | |
The input | |
The input |
This section describes functions that parse CSV data.
A CSV is a 2-dimensional tabular data structure consisting of multiple
CSV has developed informally for decades, and many variations are found.
This specification refers to
This specification uses the term
Line endings are normalized: specifically, the character sequences
Row delimiters other than newline are recognized.
Field delimiters other than
Quote characters other than
Non-ASCII characters are recognized.
This specification defines a mapping from this extended grammar to constructs in the XDM model, and provides illustrative examples of how these constructs can be combined with other language features to process CSV data.
| Function | Meaning |
|---|---|
fn:csv-to-arrays | Parses CSV data supplied as a string, returning the results in the form of a sequence of arrays of strings. |
fn:parse-csv | Parses CSV data, returning the results in the form of a record containing information about the names in the header, as well as the data itself. |
fn:csv-doc | Reads an external resource containing CSV, and returns the results as a record containing information about the names in the header, as well as the data itself. |
fn:csv-to-xml | Parses CSV data supplied as a string, returning the results as an XML document, as described by
|
The most basic function for parsing CSV is xs:string.
The other two functions recognize column names, and make it easier to address
individual fields using these names. The parse-csv function
delivers this capability using XDM maps and functions, while csv-to-xml
function represents the information using XDM element nodes.
The delimiters used for rows, columns, and quoting are configurable. An error
is raised if the same delimiter string is used in multiple roles
Rows in CSV files are typically delimited with CRLF (
The last row in the file may or may not be followed by a row delimiter. the empty file is treated as containing zero rows, while a file consisting solely of a row delimiter is treated as containing one empty row. In all other cases, a file that does not end with a row delimiter is treated as if a row delimiter were added at the end.
Fields in CSV are frequently delimited with a comma. Other field
delimiters are useful, for
example when numeric data uses comma as a decimal separator. The
chosen field delimiter is then often
The column delimiter thus defaults to column-delimiter option is set to a multi-character string.
CSVs, as specified in
If a field is to contain the quote character, the character must be escaped by doubling it,
as with escaping of quotes in XPath string literals (see
The quotes surrounding quoted fields are not included in the result. The following input string, when parsed, produces a sequence of strings, as shown below:
The quote character defaults to
No space is allowed between the column delimiter and a quote. An error is raised
The following example is therefore invalid and parsing it will raise an error.
The result of xs:string values.
The first row of the CSV is returned in the same way as all the other rows.
For example, given the input:
the
It is common practice for all rows in a CSV to have the same number of columns, but this is not required.
produces
Parses CSV data supplied as a string, returning the results in the form of a sequence of arrays of strings.
This function is
The $value argument is CSV data, as defined in xs:string value. The function parses this string,
after normalizing newlines so that array(xs:string)*; each array represents one row of the CSV input.
If $value is the empty sequence or a zero-length string, 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:
| Key | Value | Meaning |
|---|---|---|
| The character used to delimit fields within a record. An instance of
xs:string whose length is exactly one.
| |
| The character used to delimit rows within
the CSV string. An instance of
xs:string whose length is exactly one.
Defaults to a single newline character (
| |
| The character used to quote fields within the CSV string. An instance of
xs:string whose length is exactly one.
| |
| Determines whether leading and trailing whitespace
is removed from the content of unquoted fields.
| |
false | Unquoted fields will be returned with any leading or trailing whitespace intact. | |
true | Unquoted fields will be returned with leading or trailing whitespace removed, and all other whitespace preserved. | |
An empty field is represented by a zero-length string. An empty field is deemed to exist
when a field delimiter immediately follows either another field delimiter, or
a row delimiter, or the start of $value; or when a row delimiter or the
end of $value immediately follows a field delimiter.
A blank row is represented as the empty array (not as an
array containing a single empty field). A blank row is deemed to exist when a
row delimiter immediately follows either another row delimiter or the start of $value,
after trimming of whitespace if the trim-whitespace option is true.
No blank row occurs after the final row delimiter.
If $value is a zero-length string, the CSV is considered to
contain no rows; while if $value consists of a single row delimiter,
it is considered to contain a single blank row. The presence or
absence of a final row delimiter generally has no effect on the result,
except when it appears at the start of the input, in which case it causes a
single blank row to exist.
A dynamic error $csv does not conform to the required grammar.
A dynamic error field-delimiter, row-delimiter, or
quote-character option is not a single character.
A dynamic error field-delimiter, row-delimiter, and
quote-character.
The default row delimiter is a single newline character CR and CRLF will already have been normalized to a single
newline.
All fields are returned as xs:string values.
Quoted fields in the input are returned without the quotes.
The first row is not treated specially.
For more discussion of the returned data, see
Handling trivial input: | |
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
Using newline separators: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
Quote handling: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
Non-default record- and field-delimiters: | |
| Expression: | |
| Result: | |
Non-default quote character: | |
| Expression: | |
| Result: | |
Trimming whitespace in fields: | |
| Expression: | |
| Result: | |
While options parameter.
This record type is used to hold the result of the
| Name | Meaning |
|---|---|
|
This entry holds a sequence of strings containing column names.
The content depends on the setting of the With With If the value of the The order of names is
|
|
This entry holds a map from column names (as strings) to
column positions (as 1-based positive integers).
The content depends on the setting of the With With If the If the value of the The allocation of column numbers is
|
| This entry is a sequence of arrays of strings, holding the parsed
rows of the CSV data. The format is the same as the result of the
|
| A function providing ready access to a given field in a given
row. The The function takes two arguments: the first is an integer giving the row number (1-based), the second identifies a column either by its name or by its 1-based position. Except in error cases (described below),
the function call The properties of the function are as follows: Absent
None As described in the specification above A dynamic error The function returns a field in the result. The first argument The second argument If If
|
Parses CSV data, returning the results in the form of a record containing information about the names in the header, as well as the data itself.
This function is
If $value is the empty sequence, the function returns the empty sequence.
The input supplied in $value is CSV data, as defined
in
If the input is the a zero-length string, the function
returns a parsed-csv-structure-record whose
rows entry is 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:
| Key | Value | Meaning |
|---|---|---|
| The character used to delimit fields within a record. An instance of
xs:string whose length is exactly one.
| |
| The character used to delimit rows within
the CSV string. An instance of
xs:string whose length is exactly one.
Defaults to a single newline character (
| |
| The character used to quote fields within the CSV string. An instance of
xs:string whose length is exactly one.
| |
| Determines whether leading and trailing whitespace
is removed from the content of unquoted fields.
| |
false | Unquoted fields will be returned with any leading or trailing whitespace intact. | |
true | Unquoted fields will be returned with leading or trailing whitespace removed, and all other whitespace preserved. | |
| Determines whether the first row of the CSV should be treated as a list
of column names, or whether column names are being supplied by the caller.
The value must either be a single boolean, or a sequence of zero or more strings.
| |
true | Column names are taken from the first row of the CSV data. | |
false | Column names are not available; all references to columns are by ordinal position. | |
xs:string* | Supplies explicit names for the columns. The Nth name in the list applies to the Nth column after any filtering or rearrangement. A zero-length string can be used when there is a column that requires no name. | |
| A sequence of integers indicating which columns to include and in which order. If this
option is absent or empty, all columns are returned in their original
order. For example, the value 1 to 4 indicates that the output
contains the first, second, third, and fourth columns from the input, in order,
while (1, 5, 4) indicates that the output
contains three columns, taken from the first, fifth, and fourth columns of the input,
in that order. An integer in the sequence is treated as the 1-based
index of the column to include. Any other columns are dropped.
If a particular row includes no field at the specified index,
the empty field is included at the relevant position in the result. If an integer appears
more than once then the result will include duplicated columns.
| |
| Determines whether all rows should be adjusted to
contain the same number of fields. This option is ignored if
select-columns is specified.
| |
false | No padding or trimming of rows takes place,
unless requested using the select-columns option. | |
true | The number of fields in the first row (whether this be a header or a data row) determines the number of fields in every subsequent row; to achieve this, excess fields are removed, or additional zero-length fields are added. | |
The result of the function is a parsed-csv-structure-record, as
defined in
A dynamic error $csv does not conform to the required grammar.
A dynamic error field-delimiter, row-delimiter, or quote-character
is not a single character.
A dynamic error field-delimiter, row-delimiter, and
quote-character.
The default row delimiter is a single newline character CR and CRLF will already have been normalized to a single
newline.
All fields are returned as xs:string values.
Quoted fields in the input are returned without the quotes.
For more discussion of the returned data, see
If the source of the CSV input is a resource accessible by URI, then it may be preferable
to use the xs:hexBinary
or xs:base64Binary) then this can first be decoded as a string using the functions
| Variables | |
|---|---|
Default delimiters, no column headers: | |
| Expression: | |
|---|---|
| Result: | |
Default delimiters, column headers: | |
| Expression: | |
| Result: | |
Custom delimiters, no column headers: | |
| Expression: | |
| Result: | |
Supplied column names: | |
| Expression: | |
| Result: | |
Filtering columns, with ragged input and | |
| Expression: | |
| Result: | |
Filtering columns, with supplied column map | |
| Expression: | |
| Result: | |
Specifying the number of columns explicitly, with | |
| Expression: | |
| Result: | |
Specifying the number of columns with a number and | |
| Expression: | |
| Result: | |
Reads an external resource containing CSV, and returns the results as a record containing information about the names in the header, as well as the data itself.
This function is
The effect of the two-argument function call fn:csv-doc($H, $M) is
equivalent to the function composition
fn:unparsed-binary($H) => fn:parse-csv($M).
If $source is the empty sequence, the function returns the empty sequence.
The ability to access external resources depends on whether the
calling code is
The function may raise any error defined for the
The
If no non-empty column names are available, then the columns
element and all column attributes are absent.
If non-empty column names are available for some columns but not for others,
then (a) the empty column element is included
within the columns element if and only if there is a subsequent
column with a non-empty name, and (b) the column attribute
for the corresponding field elements is absent.
For example (when no column names are available):
An XSD 1.0 schema for the XML representation is provided in
Parses CSV data supplied as a string, returning the results as an XML document, as described by
This function is
The arguments have the same meaning, and are subject to the same constraints, as
the arguments of
If $value is the empty sequence, the function returns the empty sequence.
In other cases, the effect of the function is equivalent to the result of the
following XQuery expression
(where $options is the empty map if the argument is not supplied):
The elements in the returned XML are in the namespace
http://www.w3.org/2005/xpath-functions;
the namespace prefix that is used (or its absence) is
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 document: see
The result of the function will always be such that validation against this schema would succeed.
However, it is
See
| Variables | |
|---|---|
An empty CSV with default column extraction (false): | |
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | (with whitespace added for legibility) |
| Expression: | |
| Result: | (with whitespace added for legibility) |
An empty CSV with header extraction: | |
| Expression: | |
| Result: | (with whitespace added for legibility) |
An empty CSV with explicit column names: | |
| Expression: | |
| Result: | (with whitespace added for legibility) |
With defaults for delimiters and quotes, recognizing headers: | |
| Expression: | |
| Result: | (with whitespace added for legibility) |
Filtering columns | |
| Expression: | |
| Result: | (with whitespace added for legibility) |
Ragged rows | |
| Expression: | |
| Result: | (with whitespace added for legibility) |
Trimming rows to constant width | |
| Expression: | |
| Result: | (with whitespace added for legibility) |
Specifying a fixed number of columns | |
| Expression: | |
| Result: | (with whitespace added for legibility) |
The following examples illustrate more complex applications making use of CSV parsing functions.
A variable $crlf is assumed to be in scope representing the CRLF string:
Direct conversion is a matter of iterating across the records and fields to
generate <tr> and <td> elements.
Using XQuery:
Using XSLT:
The
And in XSLT:
This section describes functions that support
Invisible XML defines a BNF-like language for specifying grammars, together with
a mapping from sentences in that grammar to an XML representation. By defining an
Invisible XML grammar, a great variety of non-XML data formats can be manipulated
as if they were XML. The function
Creates an Invisible XML parser for a grammar.
This function is
Conceptually, an
If the function is called twice with the same arguments, it is
For example, the following grammar describes a date as consisting of a year, a month, and a day. Each are a sequence of digits and they are separated by hyphens:
Using this grammar to parse “2023-10-31” will produce:
Using this grammar to parse “2023-10-32” will produce something like this:
The exact format of the error output will vary between implementations.
The only required part of the output is the ixml:state attribute
that contains the value failed.
Careful readers will observe that the example grammar will parse “2023-00-00” as a date. The grammar could easily be extended to exclude the “00” forms for month and day, but this is only intended to be an illustrative example.
The
The provided grammar must be a string conforming to the Invisible XML specification grammar or an XML representation of such a grammar.
The following options are available. The
| Key | Meaning |
|---|---|
| Raise an error if the parse function fails
|
Additional,
If $grammar is the empty sequence, a parser is returned
for the Invisible XML specification grammar. This $grammar is not
empty, it err:FOIX0001.
The parsing function that is returned behaves as follows:
It takes a string as input and returns an item as its result, usually an
XML document containing the result of the parse. (The return type is item()
to allow implementations to provide other sorts of results.)
It is
If the fail-on-error option is
true, the parsing function will raise
err:FOIX0002 if the input provided cannot be
parsed successfully. Otherwise, it returns an XML representation of the
error (rooted at a document node) as described by the
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | Raises error FOIX0002. |
The following functions allow dynamic loading and evaluation of XQuery queries, XSLT stylesheets, and XPath binary operators.
| Function | Meaning |
|---|---|
fn:load-xquery-module | Provides access to the public functions and global variables of a dynamically loaded XQuery library module. |
fn:transform | Invokes a transformation using a dynamically loaded XSLT stylesheet. |
fn:op | Returns a function whose effect is to apply a supplied binary operator to two arguments. |
This record type is used to hold the result of the
| Name | Meaning |
|---|---|
|
global variable declared in the library module. The key of the
This map (V ) contains one entry for each public
entry is the name of the variable, as an
|
|
This map (F ) contains one entry for each distinct QName
Q that represents the name of a public and non-external
function declared in the library module. The key of the entry is
Q, as an
|
Provides access to the public functions and global variables of a dynamically loaded XQuery library module.
This function is
The function loads an implementation-defined set of modules having the target namespace $module-uri.
The $options argument can be used to control the way in which the function operates.
The
If the query module is retrieved as an external resource, this is subject to
the trusted
option.
Versions of XQuery prior to 4.0 do not define any constraints on access to
external resources. Many XQuery implementations, however, provide such
mechanisms. An implementation of fn:load-xquery-module that allows
execution of an
| Key | Value | Meaning |
|---|---|---|
| The minimum level of the XQuery language that the
processor must support.
| |
| Indicates whether the returned query module is
trusted to access external resources. This applies both to resources
statically referenced in the query module (such as imported schemas and
imported library modules), and to resources accessed dynamically by
invoking functions in the retrieved module, for example by use of the
| |
true | The loaded query has the same level of trust as the caller, and may therefore access all external resources available to the caller. | |
false | The functions and variables in the returned
XQuery module are | |
| A sequence of URIs (in the form of xs:string values) which may be used or ignored in an
| |
| The content of the query module as a string. When this option is used, the
location-hints option is ignored. The static base URI of the dynamically loaded
module is the same as the
| |
| The item to be used as the initial context item when evaluating global variables in the library module. Supplying
the empty sequence is equivalent to omitting the entry from the map, and indicates the absence of a context item.
If the library module specifies a required type for the context item, then the supplied value
| |
| Values for external variables defined in the library module. Values
| |
| Values for vendor-defined configuration options for the XQuery processor used to process the request. The key is the
name of an option, expressed as a QName: the namespace URI of the QName
| |
The result of the function is a map
R with two entries, as defined in
The static and dynamic context of the library module are established according to the rules in
It is
The library module that is loaded may import other modules using an import module declaration. The result of
options map supplied in the function call
The library module that is loaded may import schema declarations using an import schema declaration. It is
Where nodes are passed to or from the dynamically loaded module, for example as an argument or result of a function,
they
If $module-uri is a zero length string, a dynamic error is raised
If the implementation is not able to find a library module with the specified target namespace,
an error is raised
If a static error (including a statically detected type error) is encountered when processing the library module,
a dynamic error is raised
If a value is supplied for the initial context item or for an external variable and the value does not conform to the required
type declared in the dynamically loaded module, a dynamic error is raised
If no suitable XQuery processor is available, a dynamic error is raised
No XQuery processor is available;
Use of the function has been disabled;
No XQuery processor supporting the requested version of XQuery is available;
No XQuery processor supporting the optional Module Feature is available.
If a dynamic error (including a dynamically detected type error) is encountered when processing the module
(for example, when evaluating its global variables), the dynamic error is returned
If a function declaration F in the loaded module declares (say) four parameters of which one is optional,
its arity range will be from 3 to 4, so the result will include two function items corresponding to F#3
and F#4. In the lower-arity function item, F#3, the fourth parameter will take its
default value. If the expression that initializes the default value is context sensitive, the static and dynamic
context for its evaluation are the static and dynamic contexts of the
As with all other functions in this specification, conformance requirements depend on the host language. For example, a host language might specify that provision of this function is optional, or that it is excluded entirely, or that implementations are required to support XQuery modules using a specified version of XQuery.
Even where support for this function is mandatory, it is
The load-xquery-module function does not modify the static or dynamic context.
Functions and variables from the loaded module become available within the result returned by the function, but they
are not added to the static or dynamic context of the caller. This means, for example, that function-lookup
will not locate functions from the loaded module.
| Expression: | |
|---|---|
| Result: |
Invokes a transformation using a dynamically loaded XSLT stylesheet.
This function is
This function loads an XSLT stylesheet and invokes it to perform a transformation.
The inputs to the transformation are supplied in the form of a map.
The
The function first identifies the
If the xslt-version
option is present, the requested XSLT version is the value of that option.
Otherwise, the requested XSLT version
is the value of the [xsl:]version attribute of the outermost element in the supplied stylesheet or package.
The function then attempts to locate an XSLT processor that implements the requested XSLT version.
If a processor that implements the requested XSLT version is available, then it is used.
Otherwise, if a processor that implements a version later than the requested version is available, then it is used.
Otherwise, the function fails indicating that no suitable XSLT processor is available.
The phrase
If more than one XSLT processor is available under the above rules, then the one that is chosen may be selected according to the availability of requested features: see below.
Once an XSLT processor has been selected that implements a given version of XSLT, the processor
follows the rules of that version of the XSLT specification. This includes any decision to operate in backwards or forwards
compatibility mode. For example, if an XSLT 2.0 processor is selected, and the stylesheet specifies version="1.0",
then the processor will operate in backwards compatibility mode; if the same processor is selected and the stylesheet
specifies version="3.0", the processor will operate in forwards compatibility mode.
If the stylesheet to be executed is retrieved as an external resource, this is subject to
the trusted
option.
Versions of XSLT prior to 4.0 do not define any constraints on access to
external resources. Many XSLT implementations, however, provide such
mechanisms. An implementation of fn:transform that allows
an XSLT processor to execute an
The combinations of options that are relevant to each version of XSLT, other than xslt-version
itself, are listed below. This is followed by a table giving the meaning of each option.
For invocation of an XSLT 1.0 processor (see
The stylesheet, provided by supplying exactly one of the following:
stylesheet-location
stylesheet-node
stylesheet-text
The source tree, provided as the value of the source-node option.
Zero or more of the following additional options:
stylesheet-base-uri
stylesheet-params (defaults to the empty map)initial-mode (defaults to the stylesheet’s default mode)delivery-format (defaults to document)serialization-params (defaults to the empty map)enable-messages (default is implementation-defined)requested-properties (default is the empty map)trusted (default is false)vendor-options (defaults to the empty map)cache (default is implementation-defined)For invocation of an XSLT 2.0 processor (see
The stylesheet, provided by supplying exactly one of the following:
stylesheet-location
stylesheet-node
stylesheet-text
Invocation details, as exactly one of the following:
For apply-templates invocation, all of the following:
source-node
Optionally, initial-mode (defaults to the stylesheet’s default mode)
For call-template invocation, all of the following:
initial-template
Optionally, source-node
Zero or more of the following additional options:
stylesheet-base-uri
stylesheet-params (defaults to the empty map)base-output-uri (defaults to absent)delivery-format (defaults to document)serialization-params (defaults to the empty map)enable-messages (default is implementation-defined)enable-trace (default is implementation-defined)requested-properties (default is the empty map)trusted (default is false)vendor-options (defaults to the empty map)cache (default is implementation-defined)For invocation of an XSLT 3.0 or XSLT 4.0 processor (see
The stylesheet, provided either by supplying exactly one of the following:
stylesheet-location
stylesheet-node
stylesheet-text
Or by supplying exactly one of the following:
package-location
package-node
package-text
package-name plus optionally package-versionInvocation details, as exactly one of the following combinations:
For apply-templates invocation, all of the following:
Exactly one of source-node, source-location,
or initial-match-selection
Optionally, initial-mode
Optionally, template-params
Optionally, tunnel-params
For call-template invocation using an explicit template name, all of the following:
initial-template
Optionally, template-params
Optionally, tunnel-params
Optionally, source-node
For call-template invocation using the defaulted template name xsl:initial-template, all of the following:
Optionally, template-params
Optionally, tunnel-params
If the source-node or source-locationoption
is present and initial-template is absent,
then apply-templates invocation will be used. To use call-template invocation on the template
named xsl:initial-template while also supplying a context item for use when evaluating
global variables, either (a) supply the context item using the global-context-item option,
or (b) supply source-node, and set the initial-template option explicitly to the
QName xsl:initial-template
For call-function invocation, all of the following:
initial-function
function-params
The invocation method can be determined as the first of the following which applies:
If initial-function is present, then call-function invocation.
If initial-template is present, then call-template invocation.
If source-node or source-location
or initial-match-selection
is present, then apply-templates invocation.
Otherwise, call-template invocation using
the default entry point xsl:initial-template.
Zero or more of the following additional options:
stylesheet-base-uri
static-params (defaults to the empty map)stylesheet-params (defaults to the empty map)global-context-item (defaults to absent)base-output-uri (defaults to absent)delivery-format
serialization-params (defaults to the empty map)enable-assertions (default is false)enable-messages (default is implementation-defined)enable-trace (default is implementation-defined)requested-properties (default is the empty map)trusted (default is false)vendor-options (defaults to the empty map)cache (default is implementation-defined)The meanings of each option are defined in the table below.
| Key | Applies to | Value | Meaning |
|---|---|---|---|
| 1.0, 2.0, 3.0, 4.0 | The URI of the principal result document; also used as the base URI for
resolving relative URIs of secondary result documents. If the value is a relative
reference, it is resolved against the
fn:transform
function call.
| |
| 1.0, 2.0, 3.0, 4.0 | This option has no effect on the result of the transformation but may affect
efficiency. The value true indicates an expectation that the same
stylesheet is likely to be used for more than one transformation; the value
false indicates an expectation that the stylesheet will be used once
only.
| |
| 1.0, 2.0, 3.0, 4.0 | The manner in which the transformation results should be delivered. Applies both to the
principal result document and to secondary result documents created using
xsl:result-document.
If the relevant
| |
document | The result is delivered as a document node. | ||
serialized | The result is delivered as
a string, representing the results of serialization. Note that (as with the
| ||
raw | The result of the initial template or function is returned as an arbitrary XDM value (after conversion to the declared type, but without wrapping in a document node, and without serialization): when this option is chosen, the returned map contains the raw result. | ||
file | The serialized result is written to persistent storage. This means that the
fn:transform function has side-effects and becomes nondeterministic,
so the option should be used with care, and the precise behavior may
be base-output-uri and the URIs of any
secondary result documents must be writable locations. | ||
| 3.0, 4.0 | Indicates whether any xsl:assert instructions in the stylesheet
are to be evaluated.
| |
| 1.0, 2.0, 3.0, 4.0 | Indicates whether any xsl:message instructions in the stylesheet
are to be evaluated. The destination and formatting of any such messages is
| |
| 2.0, 3.0, 4.0 | Indicates whether any
| |
| 3.0, 4.0 | An array of values to be used as the arguments to the initial function call.
The value is converted to the required type of the declared parameter using the function
conversion rules.
| |
| 3.0, 4.0 | The value of the global context item, as defined in XSLT 3.0
| |
| 3.0, 4.0 | The name of the initial function to be called for call-function invocation. The
arity of the function is inferred from the length of
function-params.
| |
| 3.0, 4.0 | The value of the initial match selection, as defined in XSLT 3.0
| |
| 1.0, 2.0, 3.0, 4.0 | The name of the initial processing mode.
| |
| 2.0, 3.0, 4.0 | The name of a named template in the stylesheet to act as the initial entry
point.
| |
| 3.0, 4.0 | The name of the top-level stylesheet package to be invoked (an absolute
URI)
| |
| 3.0, 4.0 | The location of the top-level stylesheet package, as a relative or absolute
URI
| |
| 3.0, 4.0 | A document or element node containing the top-level stylesheet
package
| |
| 3.0, 4.0 | The top-level stylesheet package in the form of unparsed lexical
XML.
| |
| 3.0, 4.0 | The version of the top-level stylesheet package to be invoked.
| |
| 1.0, 2.0, 3.0, 4.0 | A function that is used to post-process each result document of
the transformation (both the principal result and secondary results), in whatever
form it would otherwise be delivered (document, serialized, or raw). The first
argument of the function is the key used to identify the result in the map return
by the If the implementation provides a way of writing or invoking functions
with side-effects, this post-processing function might be used to save
a copy of the result document to persistent storage. For example, if the
implementation provides access to the EXPath File library If the primary purpose of the post-processing function is achieved by
means of such side-effects, and if the actual results are not needed by
the caller of the Calls to
| |
| 1.0, 2.0, 3.0, 4.0 | The keys in the map are QNames that could legitimately be supplied in a call to
the XSLT system-property function; the values in the map are the requested
settings of the corresponding property. The boolean values true and
false are equivalent to the string values yes and
no. As a special case, setting a value for xsl:version has
no effect, because of the potential for conflict with other options. For example: Setting Setting Setting Setting xsl:supports-dynamic-evaluation
to false is interpreted as an explicit request for a processor in which
the value of the property is false. The effect if the requests cannot be precisely met
is implementation-defined. In some cases it may be appropriate to ignore the request or
to provide an alternative (for example, a later version of the product than the one
requested); in other cases it may be more appropriate to raise an error
| |
| 1.0, 2.0, 3.0, 4.0 | Serialization parameters for the principal result document. The supplied map
follows the same rules that apply to a map supplied as the second argument of
When a parameter is supplied, the corresponding value overrides or augments
the value specified in the unnamed When a parameter is supplied and the corresponding value is the empty
sequence (for example, When a parameter is not supplied in
| |
| 1.0, 2.0, 3.0, 4.0 | When source-location is supplied then
it is expected to be an absolute or relative URI identifying an
unparsed XML document. If relative, it
is resolved against the static base URI of the fn:transform function call.
The document at this location is parsed,
and the document node acts as the
initial-match-selection, that is, stylesheet execution starts by
applying templates to this node. If the initial mode is streamable
and a streaming XSLT 3.0 or XSLT 4.0 processor is used,
then the supplied document is processed in streaming mode.
| |
| 1.0, 2.0, 3.0, 4.0 | When source-node is supplied then the
global-context-item (the context item for evaluating global variables)
is the root of the tree containing the supplied node. In addition, for apply-templates
invocation, the source-node acts as the
initial-match-selection, that is, stylesheet execution starts by
applying templates to this node.
| |
| 3.0, 4.0 | The values of static parameters defined in the stylesheet; the keys are the
names of the parameters, and the associated values are their values. The value is
converted to the required type of the declared parameter using the coercion
rules.
| |
| 1.0, 2.0, 3.0, 4.0 | A string intended to be used as the static base URI of the principal stylesheet
module. This value stylesheet-node or
stylesheet-location) then it is fn:transform function call.
| |
| 1.0, 2.0, 3.0, 4.0 | URI that can be used to locate the principal stylesheet module. If relative, it
is resolved against the fn:transform function call.
The value also acts as the default for stylesheet-base-uri.
| |
| 1.0, 2.0, 3.0, 4.0 | Root of the tree containing the principal stylesheet module, as a document or
element node. The base URI of the node acts as the default for
stylesheet-base-uri.
| |
| 1.0, 2.0, 3.0, 4.0 | A map holding values to be supplied for stylesheet parameters. The keys are the
parameter names; the values are the corresponding parameter values. The values are
converted if necessary to the required type using the coercion rules. The
default is the empty map.
| |
| 1.0, 2.0, 3.0, 4.0 | The principal stylesheet module in the form of unparsed lexical
XML.
| |
| 3.0, 4.0 | The values of non-tunnel parameters to be supplied to the initial template,
used with both apply-templates and call-template invocation. Each value is converted to
the required type of the declared parameter using the coercion
rules.
| |
| 3.0, 4.0 | The values of tunnel parameters to be supplied to the initial template, used
with both apply-templates and call-template invocation. Each value is converted to the
required type of the declared parameter using the coercion
rules.
| |
| Indicates whether the target stylesheet is
trusted to access external resources. This applies both to resources
statically referenced by the stylesheet (for example using
xsl:include, xsl:import, xsl:use-package,
or xsl:import-schema), and to resources accessed dynamically by
executing the retrieved stylesheet, for example by use of the
| ||
true | The loaded stylesheet has the same level of trust as the caller, and may therefore access all external resources available to the caller. | ||
false | The loaded stylesheet is | ||
| 1.0, 2.0, 3.0, 4.0 | Values for vendor-defined configuration options for the XSLT processor used to
process the request. The key is the name of an option, expressed as a QName: the
namespace URI of the QName
| |
| 1.0, 2.0, 3.0, 4.0 | The minimum level of the XSLT language that the processor must support.
| |
The result of the transformation is returned as a map. There is one entry in the map for the principal result document, and one
for each secondary result document. The key is a URI in the form of an xs:string value. The key for the principal
result document is the base output URI if specified, or the string "output" otherwise. The key for secondary
result documents is the URI of the document, as an absolute URI. The associated value in each entry depends on the requested
delivery format. If the delivery format is document, the value is a document node. If the delivery format is
serialized, the value is a string containing the serialized result.
Where nodes are passed to or from the transformation, for example as the value of a stylesheet parameter or the result of a function,
they
It is
The function is xsl:source-document change between
one invocation and the next.
A dynamic error is raised
No XSLT processor is available;
No XSLT processor supporting the requested version of XSLT is available;
The XSLT processor API does not support some requested feature (for example, the ability to supply tunnel parameters externally);
A dynamic error is raised
If a static or dynamic error is reported by the XSLT processor, this function fails with a dynamic error, retaining the XSLT error code.
A dynamic error is raised
XSLT 1.0 does not define any error codes, so this is the likely outcome with an XSLT 1.0 processor. XSLT 2.0 and 3.0 do
define error codes, but some APIs do not expose them. If multiple errors are signaled by the transformation (which is most likely
to happen with static errors) then the error code should where possible be that of one of these errors, chosen arbitrarily; the processor
may make details of additional errors available to the application in an
A dynamic error is raised
A dynamic error is raised
Recursive use of the
As with all other functions in this specification, conformance requirements depend on the host language.
For example, a host language might specify that provision of this function is optional, or that it is excluded entirely,
or that implementations are required to support a particular set of values for the xslt-version
parameter.
Even where support for this function is mandatory, it is
The following example loads a stylesheet from the location | |
Returns a function whose effect is to apply a supplied binary operator to two arguments.
This function is
The supplied operator must be one of:
",", "and", "or", "+",
"-", "*", "div", "idiv",
"mod", "=", "<", "<=",
">", ">=", "!=", "eq",
"lt", "le", "gt", "ge",
"ne", "<<", ">>",
"precedes", "follows", "precedes-or-is", "follows-or-is",
"is", "is-not", "||", "|", "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:
fn($x, $y) { $x ⊙ $y }
For example, op("+") returns fn($x, $y) { $x + $y }.
A type error is raised
The function is useful in contexts where an arity-2 callback function needs to be supplied, and a standard operator meets the requirement.
For example, the XSLT xsl:map instruction
has an on-duplicates attribute that expects such a function. Specifying
on-duplicates="op(',')" is equivalent to specifying
on-duplicates="fn($x, $y) { $x, $y }
The function is also useful in cases where the choice of operator to apply is made dynamically.
Some operators (such as and, or, and otherwise)
have custom error handling semantics, with the effect that evaluating one of the operands cannot
cause an error unless the other operand has a particular value
(see op('and')(X, Y)
will have the normal semantics of a dynamic function call, where the arguments are evaluated in any order,
and a failure evaluating any argument may cause the function call as a whole to fail.
| Expression | Result |
|---|---|
for-each-pair(21 to 25, 1 to 5, op("+")) |
|
for-each-pair(21 to 25, 1 to 5, op("-")) |
|
The functions in this section deliver information about schema types (including simple types and complex
types). These may represent built-in types (such as xs:dateTime),
user-defined types found in the static context (typically because they appear in an imported schema),
or types used as type annotations on schema-validated nodes.
For more information on schema types, see
The structured representation of a schema type is described in
Simple properties of a schema type that can be expressed as strings or booleans are
represented in this record structure directly as atomic field values, while complex properties
whose values are themselves types (for example, base-type and primitive-type)
are represented as functions. This is done partly to make it easier for implementations to compute
complex properties on demand rather than in advance, and partly to ensure that the overall
structure is always acyclic. For example, the primitive type of xs:decimal is itself
xs:decimal, and if this were represented as a field value without a guarding function,
serialization of the map using the JSON output method would not terminate.
| Function | Meaning |
|---|---|
fn:schema-type | Returns a record containing information about a named schema type in the static context. |
fn:type-of | Returns information about the type of a value, as a string. |
fn:atomic-type-annotation | Returns a record containing information about the type annotation of an atomic value. |
fn:node-type-annotation | Returns a record containing information about the type annotation of an element or attribute node. |
This record type represents the properties of a simple or complex type in a schema.
| Name | Meaning |
|---|---|
|
The name of the type. Empty in the case of an anonymous type. Corresponds to
|
|
True for a simple type, false for a complex type.
|
|
Function item returning the base type (the type from which this type is derived by restriction
or extension). The function is always present, and returns the empty sequence
in the case of the type
|
|
For an atomic type, a function item returning the primitive type from which this
type is ultimately derived. Corresponds to the
|
|
For a simple type, one of
|
|
For a simple type with variety
|
|
For a complex type with variety
|
|
For a
|
|
For a simple type, a function item that can be used to construct instances of this type. In the case of a named
type that is present in the dynamic context, the result is the same function as returned by
|
Returns a record containing information about a named schema type in the static context.
This function is
If the static context (specifically, the $name,
the function returns a
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
Returns information about the type of a value, as a string.
This function is
The function returns a string, whose lexical form will always match
the grammar of $value.
If $value is the empty sequence, the function returns the string "empty-sequence()".
Otherwise, the returned string is the concatenation of:
A string representing the distinct item types that are present in $value,
formed as follows:
For each item in $value, construct a string representing its item type
as described below.
Eliminate duplicate strings from this list by applying the
If $ss contains only one string, use that string.
Otherwise, return the result of the expression `({ fn:string-join($ss, "|") })`.
An occurrence indicator: absent if $value contains exactly one item, or
"+" if it contains more than one item.
The string representing the type of an individual item J is constructed as follows:
If J is an
"document-node()""element()""attribute()""text()""processing-instruction()""comment()""namespace-node()"
If J is a "jnode()".
If J is an atomic item, the result is a string chosen as follows:
Let T be the type denoted by the type annotation of J.
If T is an anonymous type, set T to the base type of T, and repeat until a type is reached that is not anonymous.
If the name of T is in the namespace http://www.w3.org/2001/XMLSchema,
return the string "xs:local" where local is the local part of the
name of T.
Otherwise, return the name of T in the form of a
"Q{uri}local",
or "Q{}local" if the name is in no namespace).
If J is a function item:
If J is an array, return "array(*)".
If J is a map, return "map(*)".
Otherwise, return "fn(*)".
If the $value argument is omitted and the context value is
In general, an item matches more than one type, and there are cases where there is no single matching type that is more specific than all the others. This is especially true with functions, maps, and arrays. This function therefore selects one of the types that matches the item, which is not necessarily the most specific type.
This function should not be used as a substitute for an instance of test. The precise type annotation
of the result of an expression is not always predictable, because processors are free to deliver a more specific type
than is mandated by the specification. For example, if $n is of type xs:positiveInteger,
then the result of abs($n) is guaranteed to be an instance of xs:integer, but an
implementation might reasonably return the supplied value unchanged: that is, a value whose actual type
annotation is xs:positiveInteger. Similarly the type annotation of the value returned by
position() might be xs:long rather than xs:integer.
Implementations xs:string.
| Variables | |
|---|---|
| Expression | Result |
|---|---|
type-of($e//*[@id = 'alpha']) |
|
type-of($e//*) |
|
type-of($e//@id[. = 'gamma']) |
|
type-of($e//node()[. = '3.14159']) |
|
type-of($e//no-such-node) |
|
type-of($e/child::node()) |
|
type-of(1) |
|
type-of(1 to 5) |
|
type-of((1, 1.2, 2)) |
|
type-of([ 1, 2, 3 ]) |
|
type-of({ 'a': 1 }) |
|
type-of(type-of#1) |
|
type-of(jtree([])) |
|
Returns a record containing information about the type annotation of an atomic value.
This function is
Given an atomic value, the function returns a
The result will always have ?is-simple = true() and ?variety = "atomic". In a non-schema-aware
environment the type will always be a built-in atomic type in the xs namespace: see
Note that under the function coercion rules, it is possible to supply a node as the argument, which
will then be atomized. In simple cases the type annotation on the atomized value will be the same as
the type annotation on the node. But this is not always true: for example the type annotation on
the node might be a complex type with simple content, while the type annotation on its atomized
value is the corresponding simple content type. To get the type annotation on the node, use the function
This function should not be used as a substitute for an instance of test. The precise type annotation
of the result of an expression is not always predictable, because processors are free to deliver a more specific type
than is mandated by the specification. For example, if $n is of type xs:positiveInteger,
then the result of abs($n) is guaranteed to be an instance of xs:integer, but an
implementation might reasonably return the supplied value unchanged: that is, a value whose actual type
annotation is xs:positiveInteger. Similarly the type annotation of the value returned by
position() might be xs:long rather than xs:integer.
Implementations xs:string.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
Returns a record containing information about the type annotation of an element or attribute node.
This function is
Given an element or attribute node, the function returns a
For an element that has not been schema-validated, the type annotation is always xs:untyped.
For an attribute that has not been schema-validated, the type annotation is always xs:untypedAtomic.
The type annotation of an attribute node is always a simple type; the type annotation of an element node may be simple or complex.
| Expression: | |
|---|---|
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: | |
| Expression: | |
| Result: |
The following functions are defined to obtain information from the static or dynamic context.
| Function | Meaning |
|---|---|
fn:current-date | Returns the current date. |
fn:current-dateTime | Returns the current date and time (with timezone). |
fn:current-time | Returns the current time. |
fn:default-collation | Returns the value of the default collation property from the |
fn:default-language | Returns the value of the default language property from the dynamic context. |
fn:implicit-timezone | Returns the value of the implicit timezone property from the dynamic context. |
fn:last | Returns the context size from the dynamic context. |
fn:position | Returns the context position from the dynamic context. |
fn:static-base-uri | This function returns the value of the |
Returns the current date.
This function is
Returns xs:date(fn:current-dateTime()). This is an xs:date
(with timezone) that is current at some time during the evaluation of a query or
transformation in which
This function is
The returned date will always have an associated timezone, which will always be the same as the implicit timezone in the dynamic context
| Expression | Result |
|---|---|
current-date() | An |
Returns the current date and time (with timezone).
This function is
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
This function is fn:current-dateTime() 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
| Expression | Result |
|---|---|
current-dateTime() | An |
Returns the current time.
This function is
Returns xs:time(fn:current-dateTime()). This is an xs:time
(with timezone) that is current at some time during the evaluation of a query or
transformation in which
This function is fn:current-time() is
The returned time will always have an associated timezone, which will always be the same as the implicit timezone in the dynamic context
| Expression | Result |
|---|---|
current-time() | An |
Returns the value of the default collation property from the
This function is
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/xpath-functions/collation/codepoint) is
used.
In most cases, the default collation is known statically,
and a call on this function can therefore be pre-evaluated during static analysis. The only
notable exception is when a call on default-collation() is used to define
the default value of a parameter to a user-defined 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.
This function is
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
Returns the value of the implicit timezone property from the dynamic context.
This function is
Returns the value of the implicit timezone property from the dynamic context. Components
of the dynamic context are described in
Returns the context size from the dynamic context.
This function is
Returns the context size from the dynamic context. (See
A type error is raised
Under most circumstances, the context size is absent only if the context value is absent. However, XSLT 3.0 with streaming defines situations in which the context value and context position are known, but the context size is unknown.
| Expression | Result |
|---|---|
(1 to 20)[last() - 1] |
|
Returns the context position from the dynamic context.
This function is
Returns the context position from the dynamic context. (See
A type error is raised
This function returns the value of the
This function is
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 compile-time
and run-time 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
If a call on the
In this document, as well as in an error is raised
is used. Raising an error is equivalent to calling the fn:string(fn:abs#1). Host languages may allow type errors
to be reported statically if they are discovered during static analysis.
When function specifications indicate that an error is to be raised, the notation
[
is used to specify an error code. Each error defined
in this document is identified by an xs:QName that is in the
http://www.w3.org/2005/xqt-errors namespace, represented in this document by the err prefix. It is this
xs:QName that is actually passed as an argument to the
The xs:QName argument.
$description was supplied, it could not be empty.Calling the
This function is
This function never returns a value. Instead it always raises an error. The effect of the error is identical to the effect of dynamic errors raised implicitly, for example when an incorrect argument is supplied to a function.
The parameters to the
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/xqt-errors 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 $code is the empty sequence, the effective value of the error code
is fn:QName('http://www.w3.org/2005/xqt-errors', 'err:FOER0000').
The $description is a natural-language description of the error
condition.
If the value is the empty sequence, then the effective value of the description is
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 the value supplied is the empty sequence, then the effective value of the
error object is
This function always raises a dynamic error. By default, it raises
The value of the $description parameter may need to be localized.
Since the function never returns a value, the declared return type of item()*
is a convenient fiction. It is relevant insofar as a function item such as error#1
may (as a consequence of function coercion) be supplied in contexts where a function with a more specific
return type is required.
Any QName may be used as an error code; there are no reserved names or namespaces. The error is always classified as a dynamic error, even if the error code used is one that is normally used for static errors or type errors.
| Expression: |
|
|---|---|
| Result: | Raises error FOER0000.
|
| Expression: | |
| Result: | Raises error myerr:toohighsal.
|
$label argument can now be set
to the empty sequence. Previously if $label was supplied, it could not be empty.Provides an execution trace intended to be used in debugging queries.
This function is
The function returns $input, unchanged.
In addition, the values of $input, typically serialized and converted
to an xs:string, and $label (if non-empty)
Any serialization of the implementation’s trace output
The format of the trace output and its order are
If the trace information is unrelated to a specific value,
| Expression: | |
|---|---|
| Result: | The function returns the |
| Expression: | |
| Result: | The result of the expression is the same as the result of
|
Outputs trace information and discards the result.
This function is
Similar to $input,
typically serialized and converted to an xs:string, and $label
(if non-empty)
In contrast to
Any serialization of the implementation’s log output
The format of the log output and its order are
The function can be used for debugging. It can also be helpful in productive environments, e.g. to store dynamic input and evaluations to log files.
| Expression: | |
|---|---|
| Result: | The result of the expression is the same as the result of
|
Constructor functions are used to convert a supplied value to a given type, and the name of the function is the same as the name of the target type. This section describes constructor functions corresponding to the following types:
Simple types (atomic types, union types, and list types as
defined in
These constructor functions always take a single argument.
Record types defined as
These take one argument for each named field of the record type.
Constructor functions for record types are defined in
Constructor functions are defined for all user-defined named simple types, and for most built-in atomic, list,
and union types. The only named simple types that have no constructor function are those that have no instances
other than instances of their derived types: specifically, xs:anySimpleType, xs:anyAtomicType,
and xs:NOTATION.
Every built-in atomic
type that is defined in xs:anyAtomicType and xs:NOTATION, has an
associated constructor function. The type xs:untypedAtomic, defined
in xs:yearMonthDuration and xs:dayTimeDuration defined
in xs:dateTimeStamp introduced in
A constructor function is not defined for xs:anyAtomicType as there are no atomic items with type annotation xs:anyAtomicType at runtime, although this can be a statically inferred type.
A constructor function is not defined for xs:NOTATION since it is defined as an abstract type in xs:NOTATION then a constructor function is defined for it.
See
The form of the constructor function for an atomic type
If $arg is the empty sequence, the empty sequence is returned. For
example, the signature of the constructor function corresponding to the
xs:unsignedInt type defined in
Calling the constructor function xs:unsignedInt(12) returns
the xs:unsignedInt value 12. Another call of that constructor
function that returns the same xs:unsignedInt value is
xs:unsignedInt("12").
The same result would also be returned if the
constructor function were to be called with a node that had a typed value equal
to the xs:unsignedInt 12.
Because the declared parameter type for the argument is xs:anyAtomicType?,
the coercion rules will atomize the supplied argument
(see
If the value passed to a constructor function, after atomization, is not in the lexical space
of the datatype to be constructed,
and cannot be converted to a value in the value space of the datatype under the rules in
The semantics of the constructor function
xs:TYPE(arg)
are identical to the semantics of
arg cast as xs:TYPE?
. See
If the argument to a constructor function is a literal, the result of the
function
Special rules apply to constructor functions for xs:QName and types derived from xs:QName and xs:NOTATION. See
The argument is optional, and defaults to the context value (which will be atomized if necessary).
The following constructor functions for the built-in atomic types are supported:
Implementations xs:float("-0.0E0").
But because
Implementations xs:double("-0.0E0").
But because
See
See xs:ENTITY and types derived from it.
Special rules apply to constructor functions for the types xs:QName and xs:NOTATION, for two reasons:
Values cannot belong directly to the type xs:NOTATION, only to its subtypes.
The lexical representation of these types uses namespace prefixes, whose meaning is context-dependent.
These constraints result in the following rules:
There is no constructor function for xs:NOTATION. Constructors are defined, however, for xs:QName,
for types derived or constructed from xs:QName, and for types
derived or constructed from xs:NOTATION.
When converting from an xs:string, the prefix within the lexical
xs:QName supplied
as the argument is resolved to a namespace URI using the statically known
namespaces from the static context. If the lexical xs:QName
has no prefix, the
namespace URI of the resulting expanded-QName is the default namespace for elements and types,
taken from the static context. Components of the static context are
defined in
When a constructor function for a namespace-sensitive type is used as a literal function item
or in a partial function application (for example, xs:QName#1 or xs:QName(?)) the namespace
bindings that are relevant are those from the static context of the literal function item or partial function application.
When a constructor function for a namespace-sensitive type is obtained by means of the
When the supplied argument to the xs:QName constructor
function is a node, the node is atomized in the usual way, and if the result is xs:untypedAtomic it is then
converted as if a string had been supplied. The effect might not be what is desired.
For example, given the attribute xsi:type="my:type", the expression
xs:QName(@xsi:type) might fail on the grounds that the prefix my
is undeclared. This is because the namespace bindings are taken from the static context
(that is, from the query or stylesheet), and not from the source document containing the
@xsi:type attribute. The solution to this problem is to use the function call
resolve-QName(@xsi:type, .) instead.
Each of the three built-in list
types defined in xs:NMTOKENS, xs:ENTITIES, and xs:IDREFS, has an
associated constructor function.
The function signatures are as follows:
The semantics are equivalent to casting to the corresponding types from xs:string.
All three of these types have the facet minLength = 1 meaning that there must
always be at least one item in the list. The return type, however, allows for the fact that when the argument to
the function is the empty sequence, the result is the empty sequence.
In the case of atomic types, it is possible to use an expression such as
xs:date(@date-of-birth) to convert an attribute value to an instance of xs:date,
knowing that this will work both in the case where the attribute is already annotated as xs:date,
and also in the case where it is xs:untypedAtomic. This approach does not work with list types,
because it is not permitted to use a value of type xs:NMTOKEN* as input to the constructor
function xs:NMTOKENS. Instead, it is necessary to use conditional logic that performs the conversion
only in the case where the input is untyped:
if (@x instance of attribute(*, xs:untypedAtomic)) then xs:NMTOKENS(@x) else data(@x)
There is a constructor function for the union type xs:numeric
defined in
The semantics are determined by the rules in
If the argument is an instance of xs:double, xs:float, or xs:decimal,
then the result is an instance of the same primitive type, with the same value;
If the argument is an instance of xs:boolean, the result is the xs:double value
0.0e0 or 1.0e0;
If the argument is an instance of xs:string or xs:untypedAtomic, then:
If the value is in the lexical space of xs:double, the result will be the
corresponding xs:double value;
Otherwise, a dynamic error
The result will never be an instance of xs:float, xs:decimal,
or xs:integer. This is because xs:double appears first in the list of member
types of xs:numeric, and its lexical space subsumes the lexical space of the other numeric
types. Thus, unlike XPath numeric literals, the result does not depend on the lexical form of the supplied
value. The reason for this design choice is to retain compatibility with the function conversion rules:
functions such as xs:numeric as their first or only argument, and compatibility with the function conversion
rules defined in earlier versions of these specifications demands that when an untyped atomic item
(or untyped node) is supplied as the argument, it is converted to an xs:double value
even if its lexical form is that (say) of an integer.
In all other cases, a dynamic error
In the case of an implementation that supports XSD 1.1, there is a constructor function
associated with the built-in union type xs:error.
The function signature is as follows:
The semantics are equivalent to casting to the corresponding union type (see
Because xs:error has no member types, and therefore has an empty value space, casting
will always fail with a dynamic error except in the case where the supplied argument is the empty
sequence, in which case the result is also the empty sequence.
For every
For named atomic types, the rules
are the same as the rules for constructing built-in derived atomic types defined in T,
the signature of the function takes the form T($value as xs:anyAtomicType? := .) as T?,
and the semantics are the same as casting to derived types: see
For named union types, the rules
follow the same principles as the rules for constructing built-in union types defined in U,
the signature of the function takes the form U($value as xs:anyAtomicType? := .) as U?,
and the semantics are the same as casting to union types: see
For named list types, the rules
follow the same principles as the rules for constructing built-in list types defined in L,
where the item type of L is I,
the signature of the function takes the form L($value as xs:string? := .) as I*,
and the semantics are the same as casting to list types: see
Constructor functions are available both for named types defined in an imported schema (that is,
named simple types in the xs:string, and named local union types follow the same rules as
union types defined in a schema.
Special rules apply to constructor functions for namespace-sensitive types, that is,
atomic types derived from xs:QName and xs:NOTATION, list types that have
a namespace-sensitive item type, and union types that have a namespace-sensitive member type. See
Consider a situation where the static context contains an atomic type
called hatSize defined in a schema whose target namespace is bound
to the prefix eg. In such a case the following constructor function is available to users:
The resulting function may be used in an expression such as eg:hatSize("10½").
In the case of an atomic type A, the return type of the function is A?, reflecting
the fact that the result will be the empty sequence if the input is the empty sequence. For a union or list type,
the return type of the function is specified only as xs:anyAtomicType*. Implementations performing
static type checking will often be able to compute a more specific result type. For example, if the target type
is a list type whose item type is the atomic type A, the result will always be an instance of A*;
if the target type is a pure union type U then the result will always be an instance of U?.
In general, however, applications needing interoperable behavior on implementations that do strict static type
checking will need to use a treat as expression to assert the specific type of the result.
To construct an instance of a user-defined type
that is not in a namespace, it is possible to use an
EQName (for example Q{}hatsize(17)). Alternatives are
to use a cast expression (17 cast as hatsize) or (if the host language allows it)
to undeclare the default function namespace.
Both XQuery 4.0 and XSLT 4.0 provide syntax to declare named record types;
such a declaration implicitly adds a constructor function for values of that
type to the (See
For example, if there is a named item type with the XQuery definition:
then there will be a function definition equivalent to:
Equivalently using XSLT syntax, if there is a named item type with the XSLT definition:
then there will be a function definition equivalent to:
The rules defining the relationship of the function definition to the
record type are given for XQuery 4.0 in
Constructor functions and cast expressions accept an expression and return a value of a given type. They both convert a source value SV, of a source type, ST to a target value TV, of the given target type TT.
Constructor functions and cast expressions have identical semantics
but different syntax. The name of the
constructor function is the same as the name of the built-in xs:date("2003-01-01")
means exactly the same as
"2003-01-01" cast as xs:date?.
The cast expression takes a type name to indicate the target type of the conversion.
See
Where the argument to a cast is a literal, the result of the function
The general rules for casting from primitive types to primitive types are defined in
xs:string (and xs:untypedAtomic)
follow in
Casting is not supported to or from xs:anySimpleType.
Casting to xs:anySimpleType is not permitted and raises a static error:
Similarly, casting is not supported to or from xs:anyAtomicType and will raise
a static error: xs:anyAtomicType, although this can be a
statically inferred type.
xs:untypedAtomic. The three types xs:integer,
xs:dayTimeDuration, and xs:yearMonthDuration, which have custom
casting rules but are not strictly-speaking primitive, are now handled in other subsections.
This section defines casting between xs:untypedAtomic.
The type conversions
that are supported between primitive atomic types are indicated in the table below;
casts between other (non-primitive) types are defined in terms of these primitives.
Where the target type TT is a primitive type, the result TV will always
be an instance of TT. The result xs:NCName SV
to xs:string
In this table, there is a
row for each
Y indicates that a conversion from values of the type to which
the row applies to the type to which the column applies is supported;
N indicates that there are no supported conversions from values
of the type to which the row applies to the type to which the column applies;
M indicates that a conversion from values of the type to
which the row applies to the type to which the column applies may succeed for
some values in the value space and fail for others.
There is no row or column for xs:untypedAtomic because the casting rules are exactly the same
as for xs:string. When casting from xs:string or xs:untypedAtomic
the semantics in
xs:NOTATION as an abstract type.
Thus, casting to xs:NOTATION from any other type including xs:NOTATION
is not permitted and raises a static error xs:NOTATION to another subtype of
xs:NOTATION is permitted.
Casting is not supported to or from xs:anySimpleType. Thus, there is no row
or column for this type in the table below. For any node that has not been validated or
has been validated as xs:anySimpleType, the typed value of the node is an
atomic item of type xs:untypedAtomic. There are no atomic items with the
type annotation xs:anySimpleType at runtime.
Casting to
xs:anySimpleType is not permitted and raises a static error:
Similarly, casting is not supported to or from xs:anyAtomicType and will raise
a static error: xs:anyAtomicType at runtime, although this can be a
statically inferred type.
If casting is attempted from an
In the following table, the columns and rows are identified by short codes that identify simple types as follows:
In the following table, the notation S\T
indicates that the source
(S
) of the conversion is indicated in the column below the
notation and that the target (T
) is indicated in the row to the
right of the notation.
| S\T | str | flt | dbl | dec | dur | dT | tim | dat | gYM | gYr | gMD | gDay | gMon | bool | b64 | hxB | aURI | QN | NOT |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| str | Y | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M |
| flt | Y | Y | Y | M | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N |
| dbl | Y | Y | Y | M | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N |
| dec | Y | Y | Y | Y | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N |
| dur | Y | N | N | N | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N |
| dT | Y | N | N | N | N | Y | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N |
| tim | Y | N | N | N | N | N | Y | N | N | N | N | N | N | N | N | N | N | N | N |
| dat | Y | N | N | N | N | Y | N | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N |
| gYM | Y | N | N | N | N | N | N | N | Y | N | N | N | N | N | N | N | N | N | N |
| gYr | Y | N | N | N | N | N | N | N | N | Y | N | N | N | N | N | N | N | N | N |
| gMD | Y | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N | N | N | N |
| gDay | Y | N | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N | N | N |
| gMon | Y | N | N | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N | N |
| bool | Y | Y | Y | Y | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N |
| b64 | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | Y | N | N | N |
| hxB | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | Y | N | N | N |
| aURI | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | N | N |
| QN | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | M |
| NOT | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | M |
xs:untypedAtomicAny atomic item SV can be cast to xs:untypedAtomic.
The effect is the same as casting to xs:string (see xs:untypedAtomic value comprising the same sequence of
characters.
xs:stringAny atomic item SV can be cast to xs:string.
The resulting xs:string value TV depends on
the source type ST as follows.
If SV is an instance of xs:string,
TV is an instance of xs:string comprising
the same sequence of characters as SV.
The implementation is free to return SV unchanged, including its original type annotation.
If SV is an instance of xs:anyURI, the result TV is an instance
of xs:string comprising the same sequence of characters
as SV, but with a type annotation of xs:anyURI.
No escaping of special characters takes place.
If SV is an instance of xs:QName or xs:NOTATION:
if the qualified name has a prefix, then TV is the concatenation of the prefix of SV, a single colon (:), and the local name of SV.
otherwise TV is the local name of SV.
If SV is an instance of xs:numeric,
the rules in
If SV is an instance of xs:dateTime, xs:date
or xs:time, the rules in
If ST is xs:duration, or any subtype thereof including
xs:yearMonthDuration and xs:dayTimeDuration, then the rules
in
In all other cases, TV is the
To cast as xs:untypedAtomic the value is cast as
xs:string, as described above, and the type annotation changed
to xs:untypedAtomic.
xs:stringThe following rules apply when the source type ST is xs:decimal,
xs:double, or xs:float, or any subtype of these including
xs:integer.
If SV is an instance of xs:decimal,
then the canonical representation of
SV is returned, as defined in
Unlike previous versions of this specification, no special
rule is given for the case where SV is an instance of
xs:integer. This is because the general rule for
xs:decimal gives the same result. The result
in this case will be a sequence of decimal digits in the range
42, -1, 0, or 1000000000.
An xs:decimal that is equal to an integer is converted
to a string as if it were first cast to an xs:integer.
Specifically, there will be no decimal point and no fractional part.
If the value is not equal to an integer, then there will be a decimal
point and a fractional part, which will be a sequence of decimal digits
with no trailing zeroes. For example: 42.3, -1.5,
or 0.00001.
If SV is an instance of xs:float or
xs:double, then:
TV will be an xs:string in the lexical space
of xs:double or xs:float that when
converted to an xs:double or xs:float under
the rules of NaN
if SV is NaN.
In addition, TV must satisfy the constraints in the
following sub-bullets.
If SV has an absolute value that is
greater than or equal to 0.000001 (one millionth)
and less than 1000000 (one million), then the value
is converted to an xs:decimal and the
resulting xs:decimal is converted to an
xs:string according to the rules above, as though using an
implementation of xs:decimal that imposes no limits on the
totalDigits or
fractionDigits facets.
If SV has the value positive or negative zero, TV
is "0" or "-0" respectively.
If SV is positive or negative infinity,
TV is the string "INF" or "-INF" respectively.
In other cases, the result consists of a mantissa, which has the lexical form
of an xs:decimal, followed by the letter "E", followed by an exponent which has
the lexical form of an xs:integer. Leading zeroes and "+" signs are prohibited
in the exponent. For the mantissa, there must be a decimal point, and there must
be exactly one digit before the decimal point, which must be non-zero. The "+"
sign is prohibited. There must be at least one digit after the decimal point.
Apart from this mandatory digit, trailing zero digits are prohibited.
The above rules allow more than one representation of the same value.
For example, the xs:float value whose exact decimal representation is 1.26743223E15
might be represented by any of the strings "1.26743223E15",
"1.26743222E15" or "1.26743224E15" (inter alia).
It is implementation-dependent which of these representations is chosen.
The string representations of numeric values are backwards compatible
with XPath 1.0 except for the special values positive and negative
infinity, negative zero and values outside the range 1.0e-6 to 1.0e+6.
xs:stringIf SV is an instance of xs:dateTime,
xs:date, xs:time, xs:gYear,
xs:gYearMonth, xs:gMonth, xs:gMonthDay, or xs:gDay,
then TV is the
canonical representation of SV as defined in
The result TV includes the original timezone if a timezone is present.
All these data types contain different combinations of the components year, month, day, hour, minute, second, and timezone; all the components relevant to the data type (with the exception of the timezone) are output, and the results are concatenated together with suitable punctuation. Specifically:
The year component is
represented as a xs:string of four digits, or more if needed. A leading minus
sign is present for BCE years.
The month, day, hour and minute
components are represented as two digits (with a leading zero if needed).
For example, February is represented as 02.
The hours component will never be "24": midnight
is always represented as "00:00:00".
The second component is output using as a two-digit integer
if it is a whole number (for example, 30, 05, or 00),
or if it is fractional, as two digits followed by a decimal point followed by as many digits as
are necessary, with no trailing zeroes (for example 30.5 or 00.001).
The timezone component, if present, is
cast to xs:string by applying the function eg:convertTZtoString
given in Z, +01:00,
-05:00, or +05:30.
.
xs:duration values to xs:stringIf SV is an instance of xs:duration (including its subtypes
xs:yearMonthDuration and xs:dayTimeDuration), then TV is the
canonical representation of SV as defined in
The rules have the effect of normalizing the value so that the number of months is always
less than 12, the number of hours less than 24, and the number of minutes and seconds less
than 60. Zero-valued components are omitted. Fractional seconds follow the same rules
as xs:decimal. For example, the duration P15MT30H
is represented as P1Y3M1DT6H. A zero-length duration is output as PT0S.
At the time of writing, the published XSD 1.1 recommendation contains
cut-and-paste errors in the definition
of the dayTimeDuration canonical mapping. The binding of variable s
should be to dt's ·seconds· (not ·months·) component, and the return
expression given as sgn & 'P' & ·duYearMonthCanonicalFragmentMap·(|s|)
should read sgn & 'P' & ·duDayTimeCanonicalFragmentMap·(|s|)
In reading these XSD formulations, be aware that a & b represents
string concatenation, while |s| computes the absolute value of a number.
This section defines the rules for casting to the primitive numeric types xs:float,
xs:double, and xs:decimal. Rules for casting to the derived type
xs:integer are given in
When a value of any simple type is cast as xs:float, the xs:float
TV is derived from the ST and the
SV as follows:
If ST is xs:float, then TV
is SV and the conversion is complete.
If ST is xs:double, then
TV is obtained as follows:
if SV is the xs:double value
INF, -INF, NaN,
positive zero, or negative zero, then TV is
the xs:float value INF,
-INF, NaN, positive zero, or
negative zero respectively.
otherwise, SV can be expressed in the form
m × 2^e where the mantissa
m and exponent e are signed
xs:integers whose value range is defined in
if m (the mantissa of
SV) is outside the permitted range
for the mantissa of an xs:float
value (-2^24-1 to +2^24-1), then it
is divided by 2^N where
N is the lowest positive
xs:integer that brings the result
of the division within the permitted range, and
the exponent e is increased by
N. This is integer division (in
effect, the binary value of the mantissa is
truncated on the right). Let M be
the mantissa and E the exponent
after this adjustment.
if E exceeds 104 (the
maximum exponent value in the value space of
xs:float) then TV is
the xs:float value INF
or -INF depending on the sign of M.
if E is less than -149
(the minimum exponent value in the value space
of xs:float) then TV is
the xs:float value positive or
negative zero depending on the sign of M
otherwise, TV is the
xs:float value M × 2^E.
If ST is xs:decimal, or
xs:integer, then TV is xs:float(
SV
cast as xs:string) and the conversion is complete.
If ST is xs:boolean, SV is
converted to 1.0E0 if SV is
true and to 0.0E0 if SV
is false and the conversion is complete.
If ST is xs:untypedAtomic
or xs:string, see
XSD 1.1 adds the value +INF to the lexical space,
as an alternative to INF. XSD 1.1 also adds negative zero
to the value space.
Implementations xs:float("-0.0E0").
But because
When a value of any simple type is cast as xs:double, the
xs:double value TV is derived from the
ST and the SV as follows:
If ST is xs:double, then
TV is SV and the conversion is complete.
If ST is xs:float or a type derived
from xs:float, then TV is obtained as follows:
if SV is the xs:float value
INF, -INF, NaN,
positive zero, or negative zero, then TV is
the xs:double value INF,
-INF, NaN, positive zero, or
negative zero respectively.
otherwise, SV can be expressed in the form
m × 2^e where the
mantissa m and exponent e are
signed xs:integer values whose value range
is defined in xs:double value
m × 2^e.
If ST is xs:decimal or
xs:integer, then TV is xs:double(
SV
cast as xs:string) and the conversion is complete.
If ST is xs:boolean, SV is
converted to 1.0E0 if SV is
true and to 0.0E0 if SV
is false and the conversion is complete.
If ST is xs:untypedAtomic
or xs:string, see
XSD 1.1 adds the value +INF to the lexical space,
as an alternative to INF. XSD 1.1 also adds negative zero
to the value space.
Implementations xs:double("-0.0E0").
But because
This section defines the rules for casting to the primitive type xs:decimal.
The rules are also invoked implicitly as part of the process of converting to types
derived from xs:decimal. There are special rules, however, if the
target type TT is xs:integer, or a type derived from
xs:integer: those rules are given in
When the target type TT is xs:decimal, the
resulting xs:decimal value TV is derived from
ST and SV as follows:
If ST is xs:decimal or a subtype thereof
(including xs:integer), then
the result TV has the same xs:decimal or any
subtype of xs:decimal for which this is a valid instance, including
the original type ST.
If ST is xs:float or
xs:double, then TV is the
xs:decimal value, within the set of
xs:decimal values that the implementation is
capable of representing, that is numerically closest to
SV. If two values are equally close, then the one
that is closest to zero is chosen. If SV is too
large to be accommodated as an xs:decimal, (see
xs:float or xs:double values
NaN, INF, or -INF, a dynamic
error is raised
If ST is xs:boolean, the result TV is
1.0 if SV is
1 or true and to 0.0 if
SV is 0 or false.
The type annotation of the result may be any subtype of xs:decimal
whose value space includes the integer values 0 and 1.
If ST is xs:untypedAtomic
or xs:string, see
This section defines the rules for casting to the primitive duration type xs:duration.
Rules for casting to the derived types
xs:yearMonthDuration and xs:dayTimeDuration
are given in
If the source value SV is an instance of xs:duration
(including instances of subtypes such as xs:yearMonthDuration
and xs:dayTimeDuration, then the datum of the result
TV is the same as the datum of SV, and the
type annotation is xs:duration or any subtype thereof that
includes this datum in its value space (in particular, it
If ST is xs:untypedAtomic
or xs:string, see
In several situations, casting to date and time types requires the extraction
of a component from SV or from the result of
xs:string. These conversions must follow certain rules. For
example, converting an xs:integer year value requires
converting to an xs:string with four or more characters, preceded
by a minus sign if the value is negative.
This document defines four functions to perform these conversions. These functions are for illustrative purposes only and make no recommendations as to style or efficiency. References to these functions from the following text are not normative.
The arguments to these functions come from functions defined in this document. Thus, the functions below assume that they are correct and do no range checking on them.
Conversion from
When a value of any primitive type is cast as
xs:dateTime, the xs:dateTime value
TV is derived from ST and SV
as follows:
If ST is xs:dateTime, then
TV is SV.
If ST is xs:date, then let
eg:convertYearToString( year-from-date(
SV
)), let eg:convertTo2CharString( month-from-date(
SV
)), let eg:convertTo2CharString( day-from-date(
SV
)) and let eg:convertTZtoString( timezone-from-date(
SV
)); TV is xs:dateTime( concat(
, '-',
, '-',
, 'T00:00:00 ', ) ).
If ST is xs:untypedAtomic or
xs:string, see
When a value of any primitive type is cast as xs:time,
the xs:time value TV is derived from
ST and SV as follows:
If ST is xs:time, then
TV is SV.
If ST is xs:dateTime, then
TV is xs:time( concat(
eg:convertTo2CharString( hours-from-dateTime(
SV
)), ':', eg:convertTo2CharString( minutes-from-dateTime(
SV
)), ':', eg:convertSecondsToString( seconds-from-dateTime(
SV
)), eg:convertTZtoString( timezone-from-dateTime(
SV
)) )).
If ST is xs:untypedAtomic
or xs:string, see
When a value of any primitive type is cast as xs:date,
the xs:date value TV is derived from
ST and SV as follows:
If ST is xs:date, then
TV is SV.
If ST is xs:dateTime, then let
eg:convertYearToString( year-from-dateTime(
SV
)), let eg:convertTo2CharString( month-from-dateTime(
SV
)), let eg:convertTo2CharString( day-from-dateTime(
SV
)) and let eg:convertTZtoString(timezone-from-dateTime(
SV
)); TV is xs:date( concat(
, '-',
, '-',
) ).
If ST is xs:untypedAtomic
or xs:string, see
When a value of any primitive type is cast as
xs:gYearMonth, the xs:gYearMonth value
TV is derived from ST and SV
as follows:
If ST is xs:gYearMonth, then
TV is SV.
If ST is xs:dateTime, then let
eg:convertYearToString( year-from-dateTime(
SV
)), let eg:convertTo2CharString( month-from-dateTime(
SV
)) and let eg:convertTZtoString( timezone-from-dateTime(
SV
)); TV is xs:gYearMonth( concat(
, '-',
) ).
If ST is xs:date, then let
eg:convertYearToString( year-from-date(
SV
)), let eg:convertTo2CharString( month-from-date(
SV
)) and let eg:convertTZtoString( timezone-from-date(
SV
)); TV is xs:gYearMonth( concat(
, '-',
) ).
If ST is xs:untypedAtomic
or xs:string, see
When a value of any primitive type is cast as xs:gYear,
the xs:gYear value TV is derived from
ST and SV as follows:
If ST is xs:gYear, then
TV is SV.
If ST is xs:dateTime, let
eg:convertYearToString( year-from-dateTime(
SV
)) and let eg:convertTZtoString( timezone-from-dateTime(
SV
)); TV is xs:gYear(concat(
)).
If ST is xs:date, let
eg:convertYearToString( year-from-date(
SV
)); and let eg:convertTZtoString( timezone-from-date(
SV
)); TV is xs:gYear(concat(
)).
If ST is xs:untypedAtomic
or xs:string, see
When a value of any primitive type is cast as
xs:gMonthDay, the xs:gMonthDay value
TV is derived from ST and SV
as follows:
If ST is xs:gMonthDay, then
TV is SV.
If ST is xs:dateTime, then let
eg:convertTo2CharString( month-from-dateTime(
SV
)), let eg:convertTo2CharString( day-from-dateTime(
SV
)) and let eg:convertTZtoString( timezone-from-dateTime(
SV
)); TV is xs:gYearMonth( concat(
'--',
'-',
) ).
If ST is xs:date, then let
eg:convertTo2CharString( month-from-date(
SV
)), let eg:convertTo2CharString( day-from-date(
SV
)) and let eg:convertTZtoString( timezone-from-date(
SV
)); TV is xs:gYearMonth( concat(
'--',
, '-',
) ).
If ST is xs:untypedAtomic
or xs:string, see
When a value of any primitive type is cast as xs:gDay,
the xs:gDay value TV is derived from
ST and SV as follows:
If ST is xs:gDay, then
TV is SV.
If ST is xs:dateTime, then let
eg:convertTo2CharString( day-from-dateTime(
SV
)) and let eg:convertTZtoString( timezone-from-dateTime(
SV
)); TV is xs:gDay(
concat( '---', )).
If ST is xs:date, then let
eg:convertTo2CharString( day-from-date(
SV
)) and let eg:convertTZtoString( timezone-from-date(
SV
)); TV is xs:gDay(
concat( '---', )).
If ST is xs:untypedAtomic
or xs:string, see
When a value of any primitive type is cast as xs:gMonth,
the xs:gMonth value TV is derived from
ST and SV as follows:
If ST is xs:gMonth, then
TV is SV.
If ST is xs:dateTime, then let
eg:convertTo2CharString( month-from-dateTime(
SV
)) and let eg:convertTZtoString( timezone-from-dateTime(
SV
)); TV is xs:gMonth(
concat( '--' , )).
If ST is xs:date, then let
eg:convertTo2CharString( month-from-date(
SV
)) and let eg:convertTZtoString( timezone-from-date(
SV
)); TV is xs:gMonth(
concat( '--', )).
If ST is xs:untypedAtomic
or xs:string, see
xs:booleanWhen the target type TT is xs:boolean, the
resulting xs:boolean value TV is derived from
the source value SV as follows:
If SV is an instance of xs:boolean, then TV
is SV.
If SV is an instance of xs:numeric and
SV is 0, +0, -0,
0.0, 0.0E0 or NaN, then
TV is false.
If ST is is an instance of xs:numeric and
SV is not one of the above values, then TV
is true.
If ST is xs:untypedAtomic
or xs:string, see
xs:base64Binary and xs:hexBinaryValues of type xs:base64Binary can be cast as
xs:hexBinary and vice versa, since the two types have the same
value space. Casting to xs:base64Binary and
xs:hexBinary is also supported from the same type and from
xs:untypedAtomic, xs:string and subtypes of
xs:string using
Casting to xs:anyURI is supported only from the same type,
xs:untypedAtomic or xs:string.
When a value of any xs:anyURI, the
xs:anyURI value TV is derived from the
ST and SV as follows:
If ST is xs:untypedAtomic or xs:string see
Casting from xs:string or xs:untypedAtomic to
xs:QName or xs:NOTATION is described in
It is also possible to cast from xs:NOTATION to xs:QName,
or from xs:QName to
any type derived by restriction from xs:NOTATION. (Casting to xs:NOTATION
itself is not allowed, because xs:NOTATION is an abstract type.) The resulting
xs:QName or xs:NOTATION has the same prefix, local name, and namespace URI
parts as the supplied value.
See
The
value space of ENTITY is the set of all strings that match the
NCName production ... and have been
declared as an unparsed entity in a document type definition.
However,
xs:ENTITY match declared unparsed entities. Thus, this rule is relaxed in this specification and, in casting to xs:ENTITY and types derived from it, no check is made that the values correspond to declared unparsed entities.
This section applies when the supplied value SV
is an instance of xs:string or xs:untypedAtomic,
including types derived from these by restriction. If the value is
xs:untypedAtomic, it is treated in exactly the same way as a
string containing the same sequence of characters.
The supplied string is mapped to a typed value of the target type as defined in whiteSpace facet for the datatype. The resulting whitespace-normalized string
must be a valid lexical form for the datatype. The semantics of casting follow the rules of
XSD 1.1 validation (even for processors where validation would follow XSD 1.0 rules).
For example, "13" cast as xs:unsignedInt returns
the xs:unsignedInt typed
value 13. This could also be written xs:unsignedInt("13").
In the 4.0 version of this specification, casting from xs:string
is defined to follow XSD 1.1. This means that some lexical forms not permitted by
XSD 1.0 must be accepted: for example dates with the year zero, and +INF
as a representation of positive infinity. Casting to xs:anyURI will
never fail, because XSD 1.1 allows any sequence of characters in an xs:anyURI
value.
The target type can be any simple type other than an abstract type. Specifically, it can be a type whose variety is atomic, union, or list. In each case the effect of casting to the target type is the same as constructing an element with the supplied value as its content, validating the element using the target type as the governing type, and atomizing the element to obtain its typed value.
When the target type is a derived type that is restricted by a pattern facet, the
lexical form is first checked against the pattern before further casting
is attempted (See
For example, consider a user-defined type my:boolean which is derived by
restriction from xs:boolean and specifies the pattern facet value="0|1".
The expression "true" cast as my:boolean would fail with a dynamic
error
Facets other than pattern are checked my:height
defined as a restriction of xs:integer with the facet <maxInclusive value="84"/>,
then the expression "100" cast as my:height would fail with a dynamic
error
Casting to the types xs:NOTATION, xs:anySimpleType,
or xs:anyAtomicType is not permitted because these types are abstract (they have
no immediate instances).
Special rules apply when casting to namespace-sensitive types. The types xs:QName
and xs:NOTATION are namespace-sensitive. Any type derived by restriction from
a namespace-sensitive type is itself namespace-sensitive, as is any union type having a
namespace-sensitive type among its members, and any list type having a namespace-sensitive type
as its item type. For details, see
Since version 3.0 of this specification, casting has been allowed between xs:QName
and xs:NOTATION in either direction; this was not permitted in previous Recommendations. Version 3.0 also removed
the rule that only a string literal (rather than a dynamic string) may be cast to an xs:QName
When casting to a numeric type:
If the value is too large or too small to be accurately represented by the implementation,
it is handled as an overflow or underflow as defined in
If the target type is xs:float or xs:double, the string -0 (and equivalents
such as -0.0 or -000)
In casting to xs:decimal or to a type derived from xs:decimal,
if the value is not too large or too small but nevertheless cannot be represented accurately
with the number of decimal digits available to the implementation, the implementation may round
to the nearest representable value or may raise a dynamic error
When casting to xs:duration, xs:dateTime, or xs:time,
if the seconds component has more fractional digits than are supported by the implementation,
excess digits xs:dateTime('2023-12-31T23:59:59.999999999')
is guaranteed to deliver an xs:dateTime value whose year component is 2023 rather than 2024.
Implementations are required to support millisecond precision or greater.
In casting to xs:date, xs:dateTime, xs:gYear,
or xs:gYearMonth
(or types derived from these), if the value is too large or too
small to be represented by the implementation, a dynamic error
In casting to a duration value, if the value is too large or too small to be represented by the
implementation, a dynamic error
If the cast fails for any other reason, a dynamic error
Casting from xs:string and xs:untypedAtomic to any other type
(primitive or non-primitive) has been described in
Casting a value to a derived type can be separated into a number of cases. In these rules:
The types xs:integer, xs:yearMonthDuration,
and xs:dayTimeDuration are treated as quasi-primitive types
(alongside the 20 truly
For any atomic type T, let P(T) denote the most specific primitive or quasi-primitive type
such that itemType-subtype(T, P(T)) is true.
The rules are then:
When the source type ST is the same type as the target type TT: this case always succeeds, returning the source value SV unchanged.
When itemType-subtype(ST, TT) is true:
see
When TT is the quasi-primitive type xs:integer
and SV is an instance of xs:numeric:
see
When TT is the quasi-primitive type xs:yearMonthDuration
or xs:dayTimeDuration and SV is an instance of xs:duration:
see
When P(ST) is the same type as P(TT):
see
Otherwise (P(ST) is not the same type as P(TT)):
see
When an atomic item SV is cast as xs:integer, the
resulting xs:integer value TV is obtained as follows:
If ST is
xs:decimal, xs:float or
xs:double, then TV is SV
with the fractional part discarded and the value converted to
xs:integer. Thus, casting 3.1456
returns 3 while -17.89 returns
-17. Casting 3.124E1
returns 31. If SV is too large to be
accommodated as an integer, (see xs:float or
xs:double values NaN,
INF, or -INF, a dynamic error is raised
In all other cases, the general rules of
When casting to a subtype of xs:integer (for example, xs:long), the
rules in xs:integer as a quasi-primitive type.
xs:yearMonthDuration and xs:dayTimeDurationWhen the source value SV is an instance of xs:duration (including
any subtype of xs:duration), then:
If the target type TT is xs:yearMonthDuration, the result
is an instance of xs:yearMonthDuration whose months component
is equal to the months component of SV. The seconds
component of SV is ignored.
If the target type TT is xs:dayTimeDuration, the result
is an instance of xs:dayTimeDuration whose seconds component
is equal to the seconds component of SV. The months
component of SV is ignored.
In all other cases, the general rules of
In general, casting to xs:yearMonthDuration or xs:dayTimeDuration
loses information.
When casting to a subtype of xs:dayTimeDuration or
xs:yearMonthDuration, the
rules in xs:dayTimeDuration and xs:yearMonthDuration as quasi-primitive types.
It is always possible to cast an atomic item A to a type T
if the relation A instance of T is true, provided that T
is not an abstract type.
For example, it is
possible to cast an xs:unsignedShort to an
xs:unsignedInt, to an xs:integer, to an
xs:decimal, or to a union type
whose member types are xs:integer and xs:double.
Since the value space of the original type is a subset of the value space of the target type, such a cast is always successful.
For the expression A instance of T to be true, T must be
either an atomic type, or a union type that has no constraining facets. It cannot
be a list type, nor a union type derived by restriction from another union type, nor
a union type that has a list type among its member types.
The result will have the same value as the original, but will have a new type annotation:
If T is an atomic type, then the type annotation of the result is T.
If T is a union type, then the type of the result is an atomic type M
such that M is one of the atomic types in the transitive membership of
the union type T and A instance of M is true; if there is more
than one type M that satisfies these conditions (which could happen, for example,
if T is the union of two overlapping types such as xs:int
and xs:positiveInteger) then the first one is used, taking the member types
in the order in which they appear within the definition of the union type.
It is possible to cast an SV to a TT if the type of the
SV and the TT type are both derived by restriction
(directly or indirectly) from the same xs:byte can be cast as
xs:unsignedShort, provided the value is not negative.
If the value does not conform to the facets defined for the target type, then a dynamic
error is raised xs:string, in the case of types that have no canonical
representation defined for them).
Note that this will cause casts to fail if the pattern excludes the canonical
lexical representation of the source type. For example, if the type
my:distance is defined as a restriction of xs:decimal
with a pattern that requires two digits after the decimal point, casting of an
xs:integer to my:distance will always fail, because
the canonical representation of an xs:integer does not conform to
this pattern.
In some cases, casting from a parent type to a derived type requires special
rules. See xs:yearMonthDuration and xs:dayTimeDuration. See xs:ENTITY and types derived from it.
When the ST and the TT are derived, directly or
indirectly, from different
Cast the SV, up the hierarchy, to the
If SV is an instance of xs:string or xs:untypedAtomic, check its value against the
pattern facet of TT, and raise a dynamic error
Let P(TT) be the most specific primitive or quasi-primitive type of which TT
is a subtype, as described in
Cast the value to P(TT), as described in
If TT is derived from xs:NOTATION, assume for the
purposes of this rule that casting to xs:NOTATION succeeds.
Cast the value down to the target type TT, as described in
If the target type of a cast expression (or a constructor function) is a type with variety union, the supplied value must be one of the following:
A value of type xs:string or xs:untypedAtomic.
This case follows the general rules for casting from strings, and has already been
described in
If the union type has a pattern facet, the pattern is tested against the supplied
value after whitespace normalization, using the whiteSpace
normalization rules of the member datatype against which validation succeeds.
A value that is an instance of one of the atomic types in the transitive
membership of the union type, and of the union type itself. This case has already been described in
This situation only applies when the value is an instance of the union type, which means it will never apply when the union is derived by facet-based restriction from another union type.
A value that is castable to one or more of the atomic types in the transitive membership
of the union type (in the sense that the castable as operator returns true).
In this case the supplied value is cast to each atomic type in the transitive membership
of the union type in turn (in the order in which the member types appear in the declaration)
until one of these casts is successful; if none of them is successful, a dynamic error occurs
If the union type has a pattern facet, the pattern is tested against the canonical representation of the result value.
Only the atomic types in the transitive membership of the union type are considered. The
union type may have list types in its transitive membership, but (unless the supplied value
is of type xs:string or xs:untypedAtomic, in which case the
rules in
If more than one of these conditions applies, then the casting is done according to the rules for the first condition that applies.
If none of these conditions applies, the cast fails with a dynamic error
Example: consider a type U whose member types are xs:integer
and xs:date.
The expression "123" cast as U returns the
xs:integer value 123.
The expression current-date() cast as U returns
the current date as an instance of xs:date.
The expression 23.1 cast as U returns the xs:integer
value 23.
Example: consider a type V whose member types are xs:short
and xs:negativeInteger.
The expression "-123" cast as V returns the
xs:short value -123.
The expression "-100000" cast as V returns the
xs:negativeInteger value -100000.
The expression 93.7 cast as V returns the
xs:short value 93.
The expression "93.7" cast as V raises
a dynamic error "93.7" is not in the lexical space of the union type.
Example: consider a type W that is derived from the above type V
by restriction, with a pattern facet of -?\d\d.
The expression "12" cast as V returns the
xs:short value 12.
The expression "123" cast as V raises
an dynamic error "123" does not match the pattern facet.
If the target type of a cast expression (or a constructor function) is a
type with variety list, the supplied value must be of type xs:string or
xs:untypedAtomic. The rules follow the general principle for
all casts from xs:string outlined in
If the supplied value is not of type xs:string or
xs:untypedAtomic, a type error is raised
The semantics of the operation are consistent with validation: that is, the effect of casting a string S to a list type L is the same as constructing an element or attribute node whose string value is S, validating it using L as the governing type, and atomizing the resulting node. The result will always be either failure, or a sequence of zero or more atomic items each of which is an instance of the item type of L (or if the item type of L is a union type, an instance of one of the atomic types in its transitive membership).
If the item type of the list type is namespace-sensitive, then the
namespace bindings in the static context will be used to
resolve any namespace prefix, in the same way as when the target type is
xs:QName.
If the list type has a pattern facet, the pattern must match
the supplied value after collapsing whitespace (an operation equivalent to the
use of the
For example, the expression cast "A B C D" as xs:NMTOKENS
produces a sequence of four xs:NMTOKEN values,
("A", "B", "C", "D").
For example, given a user-defined type my:coordinates defined
as a list of xs:integer with the facet <xs:length value="2"/>,
the expression my:coordinates("2 -1") will return a sequence of two
xs:integer values (2, -1), while the expression my:coordinates("1 2 3")
will result in a dynamic error because the length of the list does not conform to the
length facet. The expression my:coordinates("1.0 3.0")
will also fail because the strings 1.0 and 3.0
are not in the lexical space of xs:integer.
The error text provided with these errors is non-normative.
Error code used by
Raised when
This error is raised whenever an attempt is made to divide by zero.
This error is raised whenever numeric operations result in an overflow or underflow.
This error is raised when an integer used to select a member of an array is outside the range of values for that array.
This error is raised when the $length argument to
Raised when casting to xs:decimal if the supplied value exceeds the
implementation-defined limits for the datatype.
Raised by NaN or Infinity.
Raised when casting to xs:integer if the supplied value exceeds the
implementation-defined limits for the datatype.
Raised when multiplying or dividing a duration by a number, if the number supplied is NaN.
Raised when casting a string to xs:decimal if the string has more digits of precision
than the implementation can represent (the implementation also has the option of rounding).
Raised by
Raised by any function that uses a collation if the requested collation is not recognized.
Raised by
Raised by functions such as
Raised by
Raised when parsing CSV input if a syntax error in the input CSV is found.
Raised when parsing CSV input if the field-separator,
record-separator, or quote-character option is set to
an invalid value.
Raised when parsing CSV input if the same delimiter character is assigned to more than one role.
Raised by the function from the get entry of
csv-columns-record, if its $key argument is an
xs:string and is not one of the known column names.
Raised by
Raised by
Raised by
Raised by xs:anyURI.
Raised (optionally) by xs:anyURI.
Raised by
Raised by
Raised when the xsd-validation option to type Q{U}NNN
is used, and Q{U}NNN does not identify a type in the static context.
Raised when the xsd-validation option to skip, if the processor is not schema-aware.
Raised when
Raised by
Raised when the dtd-validation option to dtd-validation option, but there
may be environments (such as web browsers) where this is not practically feasible.
Raised by
Raised by
This error is raised if the decimal format name supplied to
This error is raised if a decimal format value supplied to
This error is raised if the picture string supplied to
Raised when casting to date/time datatypes, or performing arithmetic with date/time values, if arithmetic overflow or underflow occurs.
Raised when casting to duration datatypes, or performing arithmetic with duration values, if arithmetic overflow or underflow occurs.
Raised by adjust-date-to-timezone and related functions if the supplied timezone is invalid.
Raised by civil-timezone if no timezone data is available for the given date/time and place.
Raised by build-dateTime if the set of fields supplied does not correspond to those present in one of the
Raised by build-dateTime if one of the fields supplied has a value that is outside the
supported range.
This error is raised if the picture string or calendar supplied to
This error is raised if the picture string supplied to
Raised by
Raised by functions such as
Raised by functions such as
Raised by
Raised by functions such as $options map contains an invalid entry.
Raised by
Raised by escaped="true" or escaped-key="true", and the corresponding string
or key contains an invalid JSON escape sequence.
Raised by
Raised by
Raised by
Raised by origin
option is not an ancestor of the $node whose relative path is required.
Raised by
Raised by
Raised by
Raised by
Raised by
A general-purpose error raised when casting, if a cast between two datatypes is allowed in principle,
but the supplied value cannot be converted: for example when attempting to cast the string "nine" to an integer.
Raised when either argument to
Raised by
Raised by
Raised by
Raised by functions such as
Raised by
A catch-all error for
Raised when the input to
Raised when the radix supplied to
Raised when the digits in the string supplied to
Raised by regular expression functions such as i, m, q, s, or x.
Raised by regular expression functions such as
Raised by
Raised by $replacement
and $action arguments are supplied.
Raised by
Raised by
Raised by
Raised by $source argument contains a fragment identifier,
or if it cannot be resolved to an absolute URI (for example, because the
base-URI property in the static context is absent), or if it cannot be used to
retrieve the string representation of a resource.
Raised by $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
Raised by $encoding argument is absent and the processor
cannot infer the encoding using external information and the
encoding is not UTF-8.
A dynamic error is raised if the authority component of a URI contains an open square bracket but no corresponding close square bracket.
A dynamic error is raised if no XSLT processor suitable for evaluating a call on
A dynamic error is raised if the parameters supplied to initial-template does not exist in the stylesheet), that error code should
be used in preference.
A dynamic error is raised if an XSLT transformation invoked using
A dynamic error is raised if the
A dynamic error is raised if the result of the
This appendix lists the named record types that are used in function signatures in this function library, and that are available in the static context of every application.
These definitions are all in the standard function namespace http://www.w3.org/2005/xpath-functions,
which is normally bound to the prefix fn. Because this will not usually be the default namespace for
types, the names will usually be written with the prefix fn.
Record
Record
Record
Record
Record
Record
Record
Record
fn namespace.
Two functions in this specification, http://www.w3.org/2005/xpath-functions, which is therefore the target namespace
of the relevant schema.
A processor xs:redefine or xs:override, adding members to substitution
groups, or defining derived types. Processors are not xsi:schemaLocation or
xsi:type attributes in the instance being validated.
The schema for this namespace is organized as three schema documents. The first is a simple
umbrella document that includes the other two. A copy can be found at
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
targetNamespace="http://www.w3.org/2005/xpath-functions">
<!--
* This is a schema for the namespace http://www.w3.org/2005/xpath-functions
*
* The schema is made available under the terms of the W3C software notice and license
* at http://www.w3.org/Consortium/Legal/copyright-software-19980720
*
* The schema includes two schema documents, containing definitions of the structure
* of the results of the fn:analyze-string and fn:json-to-xml functions respectively.
*
-->
<xs:include schemaLocation="analyze-string.xsd"/>
<xs:include schemaLocation="schema-for-json.xsd"/>
<xs:include schemaLocation="schema-for-csv.xsd"/>
</xs:schema>
This schema describes the output of the function
The schema is reproduced below, and can also be found in
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.w3.org/2005/xpath-functions"
xmlns:fn="http://www.w3.org/2005/xpath-functions"
elementFormDefault="qualified">
<!--
* This is a schema for the XML representation of JSON used as the target for the
* function fn:analyze-string()
*
* The schema is made available under the terms of the W3C software notice and license
* at http://www.w3.org/Consortium/Legal/copyright-software-19980720
*
-->
<xs:element name="analyze-string-result" type="fn:analyze-string-result-type"/>
<xs:element name="match" type="fn:match-type"/>
<xs:element name="non-match" type="xs:string"/>
<xs:element name="group" type="fn:group-type"/>
<xs:element name="lookahead-group" type="fn:lookahead-group-type"/>
<xs:complexType name="analyze-string-result-type" mixed="true">
<xs:sequence>
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element ref="fn:match"/>
<xs:element ref="fn:non-match"/>
</xs:choice>
</xs:sequence>
</xs:complexType>
<xs:complexType name="match-type" mixed="true">
<xs:sequence>
<xs:element ref="fn:group" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="fn:lookahead-group" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="group-type" mixed="true">
<xs:sequence>
<xs:element ref="fn:group" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="nr" type="xs:positiveInteger"/>
</xs:complexType>
<xs:complexType name="lookahead-group-type">
<xs:attribute name="nr" type="xs:positiveInteger"/>
<xs:attribute name="value" type="xs:string"/>
<xs:attribute name="position" type="xs:positiveInteger"/>
</xs:complexType>
</xs:schema>
This schema describes the output of the function
The schema is reproduced below, and can also be found in
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
targetNamespace="http://www.w3.org/2005/xpath-functions"
xmlns:j="http://www.w3.org/2005/xpath-functions">
<!--
* This is a schema for the XML representation of JSON used as the target for the
* function fn:json-to-xml()
*
* The schema is made available under the terms of the W3C software notice and license
* at http://www.w3.org/Consortium/Legal/copyright-software-19980720
*
-->
<xs:element name="map" type="j:mapType">
<xs:unique name="unique-key">
<xs:selector xpath="*"/>
<xs:field xpath="@key"/>
<xs:field xpath="@escaped-key"/>
</xs:unique>
</xs:element>
<xs:element name="array" type="j:arrayType"/>
<xs:element name="string" type="j:stringType"/>
<xs:element name="number" type="j:numberType"/>
<xs:element name="boolean" type="j:booleanType"/>
<xs:element name="null" type="j:nullType"/>
<xs:complexType name="nullType">
<xs:sequence/>
<xs:anyAttribute processContents="skip" namespace="##other"/>
</xs:complexType>
<xs:complexType name="booleanType">
<xs:simpleContent>
<xs:extension base="xs:boolean">
<xs:anyAttribute processContents="skip" namespace="##other"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="stringType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="escaped" type="xs:boolean" use="optional" default="false"/>
<xs:anyAttribute processContents="skip" namespace="##other"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:simpleType name="finiteNumberType">
<xs:restriction base="xs:double">
<!-- exclude positive and negative infinity, and NaN -->
<xs:minExclusive value="-INF"/>
<xs:maxExclusive value="INF"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="numberType">
<xs:simpleContent>
<xs:extension base="j:finiteNumberType">
<xs:anyAttribute processContents="skip" namespace="##other"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="arrayType">
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element ref="j:map"/>
<xs:element ref="j:array"/>
<xs:element ref="j:string"/>
<xs:element ref="j:number"/>
<xs:element ref="j:boolean"/>
<xs:element ref="j:null"/>
</xs:choice>
<xs:anyAttribute processContents="skip" namespace="##other"/>
</xs:complexType>
<xs:complexType name="mapWithinMapType">
<xs:complexContent>
<xs:extension base="j:mapType">
<xs:attributeGroup ref="j:key-group"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="arrayWithinMapType">
<xs:complexContent>
<xs:extension base="j:arrayType">
<xs:attributeGroup ref="j:key-group"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="stringWithinMapType">
<xs:simpleContent>
<xs:extension base="j:stringType">
<xs:attributeGroup ref="j:key-group"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="numberWithinMapType">
<xs:simpleContent>
<xs:extension base="j:numberType">
<xs:attributeGroup ref="j:key-group"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="booleanWithinMapType">
<xs:simpleContent>
<xs:extension base="j:booleanType">
<xs:attributeGroup ref="j:key-group"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="nullWithinMapType">
<xs:attributeGroup ref="j:key-group"/>
</xs:complexType>
<xs:complexType name="mapType">
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element name="map" type="j:mapWithinMapType">
<xs:unique name="unique-key-2">
<xs:selector xpath="*"/>
<xs:field xpath="@key"/>
</xs:unique>
</xs:element>
<xs:element name="array" type="j:arrayWithinMapType"/>
<xs:element name="string" type="j:stringWithinMapType"/>
<xs:element name="number" type="j:numberWithinMapType"/>
<xs:element name="boolean" type="j:booleanWithinMapType"/>
<xs:element name="null" type="j:nullWithinMapType"/>
</xs:choice>
<xs:anyAttribute processContents="skip" namespace="##other"/>
</xs:complexType>
<xs:attributeGroup name="key-group">
<xs:attribute name="key" type="xs:string" use="required"/>
<xs:attribute name="escaped-key" type="xs:boolean" use="optional" default="false"/>
</xs:attributeGroup>
</xs:schema>
This schema describes the output of the function
The schema is reproduced below, and can also be found in
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
targetNamespace="http://www.w3.org/2005/xpath-functions"
xmlns:csv="http://www.w3.org/2005/xpath-functions">
<!--
* This is a schema for the XML representation of CSV used as the target for the
* function fn:csv-to-xml()
*
* The schema is made available under the terms of the W3C software notice and license
* at http://www.w3.org/Consortium/Legal/copyright-software-19980720
*
-->
<xs:element name="csv" type="csv:csvType"/>
<xs:element name="columns" type="csv:columnsType"/>
<xs:element name="rows" type="csv:rowsType"/>
<xs:element name="column" type="csv:columnFieldType"/>
<xs:element name="row" type="csv:rowType"/>
<xs:element name="field" type="csv:fieldType"/>
<xs:complexType name="csvType">
<xs:sequence>
<xs:element ref="csv:columns" minOccurs="0" maxOccurs="1"/>
<xs:element ref="csv:rows" minOccurs="1" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="columnsType">
<xs:sequence>
<xs:element ref="csv:column" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="rowsType">
<xs:sequence>
<xs:element ref="csv:row" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="rowType">
<xs:sequence>
<xs:element ref="csv:field" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="columnFieldType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:anyAttribute processContents="skip" namespace="##other"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="fieldType">
<xs:simpleContent>
<xs:extension base="csv:columnFieldType">
<xs:attribute name="column" type="xs:string" use="optional"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:schema>
This Appendix describes some sources of functions that fall outside the scope of the function library defined in this specification. It includes both function specifications and function implementations. Inclusion of a function in this appendix does not constitute any kind of recommendation or endorsement; neither is omission from this appendix to be construed negatively. This Appendix does not attempt to give any information about licensing arrangements for these function specifications or implementations.
A number of W3C Recommendations make use of XPath, and in some cases such Recommmendations define additional functions to be made available when XPath is used in a specific host language.
The various versions of XSLT have all included additional functions intended to be available only when XPath is used within XSLT, and not in other host language environments. Some of these functions were originally defined in XSLT, and subsequently migrated into the core function library defined in this specification.
Generally, the reason that functions have been defined in XSLT rather than in the core library has been that they required additional static or dynamic context information.
XSLT-defined functions share the core namespace http://www.w3.org/2005/xpath-functions (but in XPath 1.0
and XSLT 1.0, no namespace was defined for these functions).
The following table lists all functions that have been defined in XSLT, and summarizes their current status.
| Function name | Availability |
|---|---|
| fn:accumulator-after | XSLT 3.0 and later |
| fn:accumulator-before | XSLT 3.0 and later |
| fn:apply-templates | XSLT 4.0 |
| fn:available-system-properties | XSLT 3.0 and later |
| fn:character-map | XSLT 4.0 |
| fn:collation-key | Originally XSLT 3.0, then XPath 3.1 and later |
| fn:copy-of | XSLT 3.0 and later |
| fn:current | XSLT 1.0 and later |
| fn:current-group | XSLT 2.0 and later |
| fn:current-grouping-key | XSLT 2.0 and later |
| fn:current-merge-group | XSLT 3.0 and later |
| fn:current-merge-key | XSLT 3.0 and later |
| fn:current-merge-key-array | XSLT 4.0 |
| fn:current-output-uri | XSLT 3.0 and later |
| fn:document | XSLT 1.0 and later |
| fn:element-available | XSLT 1.0 and later |
| fn:format-date | Originally XSLT 2.0, then XPath 3.0 and later |
| fn:format-dateTime | Originally XSLT 2.0, then XPath 3.0 and later |
| fn:format-number | Originally XSLT 1.0 and 2.0; then XPath 3.0 and later |
| fn:format-time | Originally XSLT 2.0; then XPath 3.0 and later |
| fn:function-available | XSLT 1.0 and later |
| fn:generate-id | Originally XSLT 1.0 and 2.0; then XPath 3.0 and later |
| fn:json-to-xml | Originally XSLT 3.0, then XPath 3.1 and later |
| fn:key | XSLT 1.0 and later |
| fn:map-for-key | XSLT 4.0 |
| fn:regex-group | XSLT 2.0 and later |
| fn:regex-groups | XSLT 4.0 |
| fn:snapshot | XSLT 3.0 and later |
| fn:stream-available | XSLT 3.0 and later |
| fn:system-property | XSLT 1.0 and later |
| fn:type-available | XSLT 2.0 and later |
| fn:unparsed-entity-public-id | XSLT 2.0 and later |
| fn:unparsed-entity-uri | XSLT 1.0 and later |
| fn:unparsed-text | Originally XSLT 2.0; then XPath 3.0 and later |
| fn:unparsed-text-available | Originally XSLT 2.0; then XPath 3.0 and later |
| fn:xml-to-json | Originally XSLT 3.0, then XPath 3.1 and later |
| map:contains | Originally XSLT 3.0, then XPath 3.1 and later |
| map:entry | Originally XSLT 3.0, then XPath 3.1 and later |
| map:find | Originally XSLT 3.0, then XPath 3.1 and later |
| map:for-each | Originally XSLT 3.0, then XPath 3.1 and later |
| map:get | Originally XSLT 3.0, then XPath 3.1 and later |
| map:keys | Originally XSLT 3.0, then XPath 3.1 and later |
| map:merge | Originally XSLT 3.0, then XPath 3.1 and later |
| map:put | Originally XSLT 3.0, then XPath 3.1 and later |
| map:remove | Originally XSLT 3.0, then XPath 3.1 and later |
| map:size | Originally XSLT 3.0, then XPath 3.1 and later |
XSLT 3.0 was well advanced when work started on XPath 3.1, but XPath 3.1 appeared as a Recommendation before XSLT 3.0 reached that status.
XForms 1.1 is based on XPath 1.0. It adds the following functions to the set defined in XPath 1.0, using the same namespace:
boolean-from-string, is-card-number, avg, min, max,
count-non-empty, index, power, random, compare,
if, property,
digest, hmac, local-date, local-dateTime, now,
days-from-date, days-to-date, seconds-from-dateTime, seconds-to-dateTime,
adjust-dateTime-to-timezone, seconds, months, instance,
current, id, context, choose, event.
XForms 2.0 was first published as a W3C Working Draft, and subsequently as a W3C Community Group specification. These draft specifications do not include any additional functions beyond those in the core XPath specification.
The XQuery Update 1.0 specification defines one additional function in the core namespace
http://www.w3.org/2005/xpath-functions, namely fn:put. This function can be used
to write a document to external storage. It is thus unusual in that it has side-effects; the XQuery Update 1.0
specification defines semantics for updating expressions including this function.
Although XQuery Update 1.0 is defined as an extension of XQuery 1.0, a number of implementers have adapted it, in a fairly intuitive way, to work with later versions of XQuery. At the time of this publication, later versions of the XQuery Update specification remain at Working Draft status.
A number of community groups, with varying levels of formal organization, have defined specifications for additional function libraries to augment the core functions defined in this specification. Many of the resulting function specifications have implementations available for popular XPath, XQuery, and XSLT processors, though the level of support is highly variable.
The first such group was EXSLT. This activity was primarily concerned with augmenting the capability of XSLT 1.0, and many of its specifications were overtaken by core functions that became available in XPath 2.0. EXSLT defined a number of function modules covering:
node-set function)max, min, abs, and trigonometric functions)Specifications from the EXSLT group can be found at
A renewed attempt to define additional function libraries using XPath 2.0 as its baseline formed under the name EXPath. Again, the specifications are in various states of maturity and stability, and implementation across popular processors is patchy. At the time of this publication the function libraries that exist in stable published form include:
The EXPath community has also been engaged in other related projects, such as defining packaging
standards for distribution of XSLT/XQuery components, and tools for unit testing. Its specifications
can be found at
A third activity has operated under the name EXQuery, which as the name suggests has focused
on extensions to XQuery. EXQuery has published a single specification, RestXQ, which is primarily a
system of function annotations allowing XQuery functions to act as endpoints for RESTful services.
It also includes some simple functions to assist with the creation of such services. The RestXQ specification
can be found at
Many useful functions can be written in XSLT or XQuery, and in this case the function implementations themselves can be portable across different XSLT and XQuery processors. This section describes one such library.
FunctX is an open-source library of general-purpose functions, supplied in the form of XQuery 1.0 and XSLT 2.0 implementations. It contains over a hundred functions. Typical examples of these functions are:
The FunctX library can be found at
The keyword for the argument has changed from arg to value.
The argument is now optional, and defaults to the context value (which is atomized if necessary).
This change aligns constructor functions such as xs:string, xs:boolean,
and xs:numeric with
The semantics of the HTML case-insensitive collation
"http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive"
are now defined normatively in this specification rather than by reference to the
living HTML5 specification (which has changed since 3.1); and the rules now make ordering explicit rather than leaving
it implementation-defined.
An option in an
These changes are not highlighted in the change-marked version of the specification.
The value comparison operators such as eq, lt, and gt
are now defined in op:XX-equal,
op:XX-less-than, and op:XX-greater-than
have therefore been dropped.
The names of parameters appearing in function signatures have been changed. This is to reflect the introduction of keyword arguments in XPath 4.0; the names chosen for parameters are now more consistent across the function library.
In 3.1 and earlier versions, the keywords used in the specification were for documentation purposes only, so these changes do not affect backwards compatibility.
Where appropriate, the phrase "the value of $x" has been replaced
by the simpler $x. No change in meaning is intended.
For functions that take a variable number of arguments, wherever possible the specification now gives a single function signature indicating default values for arguments that may be omitted, rather than multiple signatures.
The formal specifications of array functions have been rewritten to use two new
primitives: array:members which converts an array to a sequence of value records,
and array:of-members which does the inverse. This has enabled many of the
functions to be specified more concisely, and with less duplication between similar functions
for sequences and arrays.
The appendix containing illustrative user-written functions has been dropped; many of these functions are no longer needed.
This section summarizes the extent to which this specification is compatible with previous versions.
Version 4.0 of this function library is fully backwards compatible with version 3.1, except as noted below:
In xs:double and xs:decimal) have changed.
In previous versions of the specification, xs:decimal values were converted
to xs:double, leading to a possible loss of precision. This could make
comparisons non-transitive, leading to problems when grouping,
and potentially (depending on the sort algorithm) with sorting. The problem has been fixed by requiring
comparisons to be performed based on the exact mathematical value without any loss of precision.
This means, for example, that deep-equal(0.2, 0.2e0) is now false, whereas in previous
versions it was true. The two values are not mathematically equal, because the exact decimal equivalent
of the xs:double value written as 0.2e0 is
0.200000000000000011102230246251565404236316680908203125.
The corresponding change has not been made to the = and eq operators,
because it was found to be too disruptive. For example, if the context node is the element
<e price="10.0" discount="0.2"/>, there is an expectation that the expression
@price - @discount = 9.8 should return true. But (assuming untyped data), the result of
the subtraction is an xs:double whose precise value is
9.800000000000000710542735760100185871124267578125, so comparing the two values as
decimals would return false.
In previous versions, unrecognized options supplied to the $options
parameter of functions such as
In version 4.0, omitting the $value of
In version 3.1, the <a>abc<!--note1-->def</code>
and <a>abcde<!--note2-->f</code> were considered non-equal. In version 4.0,
the text nodes are now merged prior to comparison, so these two elements compare equal.
In version 3.1, the atomic types xs:hexBinary and xs:base64Binary
were not mutually comparable under the eq operator, and always compared not equal
as map keys or under operations such as fn:distinct-values and fn:deep-equal.
In version 4.0, instances of xs:hexBinary and xs:base64Binary are
equal if they represent the same octet sequence. This means, for example, that the zero-length
values xs:hexBinary("") and xs:base64Binary("") can no longer co-exist
as keys in the same map.
The format of numeric values in the output of xs:double and then serialized
using the casting rules, resulting in an input value of 10000000 being output as 1e7.
In version 4.0, the value is output
In version 4.0, the function signature of xs:NCName or a zero-length string (the new coercion rules
mean that any string in the form of an xs:NCName is acceptable). If a string is supplied
that does not meet these requirements, a type error will be raised. In version 3.1, this was not an error:
it came under the rule that when no namespace binding existed for the supplied prefix, the function
would return the empty sequence.
Furthermore, because the expected type of this parameter is no longer xs:string, the
special coercion rules for xs:string parameters in XPath 1.0 compatibility mode no longer apply.
For example, supplying xs:duration('PT1H') as the first argument will now raise a
type error, rather than looking for a namespace binding for the prefix PT1H.
Version 4.0 makes it clear that the casting of a value other than xs:string
or xs:untypedAtomic to a list type (whether using a cast expression or a
constructor function) is a type error xs:string?.
The way that xs:integer or xs:decimal values, the result is an xs:integer or
xs:decimal, rather than the result of converting this to an xs:double.
The type of the third argument of xs:string to (xs:string | xs:QName).
Because the expected type of this parameter is no longer xs:string, the
special coercion rules for xs:string parameters no longer apply.
For example, it is no
longer possible to supply an instance of xs:anyURI or (when XPath 1.0 compatibility
mode is in force) an instance of xs:boolean or xs:duration.
When
In regular expressions, the assertions ^ and $ can no longer be
followed by a quantifier. This is because (a) a quantifier that allows zero occurrences means
that the assertion will always match, and (b) a quantifier that allows multiple occurrences
has no effect. Processors may provide an option that allows such regular expressions to be
accepted for compatibility reasons.
The NaN as equal to NaN.
For compatibility issues regarding earlier versions, see the 3.1 version of this specification.