Please check the errata for any errors or issues reported since publication.
See also translations.
This document is also available in these non-normative formats: Specification in XML format using HTML5 vocabulary, XML function catalog, and HTML with change markings relative to version 3.0.
Copyright © 2000 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
This document defines constructor functions, operators, and functions on the datatypes defined in [XML Schema Part 2: Datatypes Second Edition] and the datatypes defined in [XQuery and XPath Data Model (XDM) 3.1]. It also defines functions and operators on nodes and node sequences as defined in the [XQuery and XPath Data Model (XDM) 3.1]. These functions and operators are defined for use in [XML Path Language (XPath) 4.0] and [XQuery 4.1: An XML Query Language] and [XSL Transformations (XSLT) Version 4.0] and other related XML standards. The signatures and summaries of functions defined in this document are available at: http://www.w3.org/2005/xpath-functions/.
A summary of changes since version 3.1 is provided at F Changes since version 3.1.
This version of the specification is work in progress. It is produced by the QT4 Working Group, officially the W3C XSLT 4.0 Extensions Community Group. Individual functions specified in the document may be at different stages of review, reflected in their History notes. Comments are invited, in the form of GitHub issues at https://github.com/qt4cg/qtspecs.
The purpose of this document is to define functions and operators for inclusion in XPath 4.0, XQuery 4.0, and XSLT 4.0. The exact syntax used to call these functions and operators is specified in [XML Path Language (XPath) 4.0], [XQuery 4.1: An XML Query Language] and [XSL Transformations (XSLT) Version 4.0].
This document defines three classes of functions:
General purpose functions, available for direct use in user-written queries, stylesheets, and XPath expressions, whose arguments and results are values defined by the [XQuery and XPath Data Model (XDM) 3.1].
Constructor functions, used for creating instances of a datatype from values of (in general) a different datatype. These functions are also available for general use; they are named after the datatype that they return, and they always take a single argument.
Functions that specify the semantics of operators defined in [XML Path Language (XPath) 4.0] and [XQuery 4.1: An XML Query Language]. These exist for specification purposes only, and are not intended for direct calling from user-written code.
[XML Schema Part 2: Datatypes Second Edition] defines a number of primitive and derived datatypes, collectively known as built-in datatypes. This document defines functions and operations on these datatypes as well as the other types (for example, nodes and sequences of nodes) defined in Section 2.7 Schema Information DM31 of the [XQuery and XPath Data Model (XDM) 3.1]. These functions and operations are available for use in [XML Path Language (XPath) 4.0], [XQuery 4.1: An XML Query Language] and any other host language that chooses to reference them. In particular, they may be referenced in future versions of XSLT and related XML standards.
[Schema 1.1 Part 2] adds to the datatypes defined
in [XML Schema Part 2: Datatypes Second Edition]. It introduces a new derived type xs:dateTimeStamp
, and it
incorporates as 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 may support either XSD 1.0 or XSD 1.1 or both.
References to specific sections of some of the above documents are indicated by 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 [XQuery 4.1: An XML Query Language], XT [XSL Transformations (XSLT) Version 4.0], XP [XML Path Language (XPath) 4.0], and DM [XQuery and XPath Data Model (XDM) 3.1].
Despite its title, this document does not attempt to define the semantics of all the operators available
in the [XML Path Language (XPath) 4.0] language; indeed, in the interests of avoiding duplication, the majority of
operators (including all higher-order operators such as x/y
, x!y
, and x[y]
,
as well simple operators such as x,y
, x and y
, x or y
,
x<<y
, x>>y
, x is y
, x||y
, x|y
,
x union y
, x except y
, x intersect y
, x to y
and x otherwise y
) are now defined entirely within [XML Path Language (XPath) 4.0].
The remaining operators that are described in this publication are those where the semantics of the operator
depend on the types of the arguments. For these operators, the language specification describes rules for selecting
an internal function defined in this specification to underpin the operator. For example, when the operator x+y
is applied to two operands of type xs:double
, the function op:numeric-add
is selected.
XPath defines a range of comparison operators x=y
, x!=y
, x<y
,
x>y
, x<=y
, x>=y
, x eq y
, x ne y
, x lt y
,
x gt y
, x le y
, x ge y
, which apply to a variety of operand types including
for example numeric values, strings, dates and times, and durations. For each relevant data type, two functions
are defined in this specification, for example op:date-equal
and op:date-less-than
.
These define the semantics of the eq
and lt
operators applied to operands of that data type. The operators
x ne y
, x gt y
, x le y
, and x ge y
are defined by reference to
these two; and the general comparison operators =
, !=
, <
,
>
, <=
, and >=
are defined by reference to
eq
, ne
, lt
,
gt
, le
, and ge
respectively.
Note:
Previous versions of this specification also defined a third comparison function of the form
op:date-greater-than
. This has been dropped, as it is always the inverse of the -less-than
form.
This recommendation contains a set of function specifications. It defines conformance at the level of individual functions. An implementation of a function conforms to a function specification in this recommendation if all the following conditions are satisfied:
For all combinations of valid inputs to the function (both explicit arguments and implicit context dependencies), the result of the function meets the mandatory requirements of this specification.
For all invalid inputs to the function, the implementation signals (in some way appropriate to the calling environment) that a dynamic error has occurred.
For a sequence of calls within the same ·execution scope·, the requirements of this recommendation regarding the ·determinism· of results are satisfied (see 1.8.4 Properties of functions).
Other recommendations (“host languages”) that reference this document may dictate:
Subsets or supersets of this set of functions to be available in particular environments;
Mechanisms for invoking functions, supplying arguments, initializing the static and dynamic context, receiving results, and handling errors;
A concrete realization of concepts such as ·execution scope·;
Which versions of other specifications referenced herein (for example, XML, XSD, or Unicode) are to be used.
Any behavior that is discretionary (implementation-defined or implementation-dependent) in this specification may be constrained by a host language.
Note:
Adding such constraints in a host language, however, is discouraged because it makes it difficult to re-use implementations of the function library across host languages.
This specification allows flexibility in the choice of versions of specifications on which it depends:
It is ·implementation-defined· which version of Unicode is supported, but it is recommended that the most recent version of Unicode be used.
It is ·implementation-defined· whether the type system is based on XML Schema 1.0 or XML Schema 1.1.
It is ·implementation-defined· whether definitions that rely on XML (for example, the set of valid XML characters) should use the definitions in XML 1.0 or XML 1.1.
Note:
The XML Schema 1.1 recommendation
introduces one new concrete datatype: xs:dateTimeStamp
; it also incorporates
the types xs:dayTimeDuration
, xs:yearMonthDuration
,
and xs:anyAtomicType
which were previously defined in earlier versions of [XQuery and XPath Data Model (XDM) 3.1].
Furthermore, XSD 1.1
includes the option of supporting revised definitions of types such as xs:NCName
based on the rules in XML 1.1 rather than 1.0.
The [XQuery and XPath Data Model (XDM) 4.0] allows flexibility in the repertoire of characters permitted during processing that goes beyond even what version of XML is supported. A processor may allow the user to construct nodes and atomic values that contain characters not allowed by any version of XML. [Definition] A permitted character is one within the repertoire accepted by the implementation.
In this document, text labeled as an example or as a note is provided for explanatory purposes and is not normative.
The functions and operators defined in this document are contained in one of
several namespaces (see [Namespaces in XML]) and referenced using an
xs:QName
.
This document uses conventional prefixes to refer to these namespaces. User-written
applications can choose a different prefix to refer to the namespace, so long as it is
bound to the correct URI. The host language may also define a default namespace for
function calls, in which case function names in that namespace need not be prefixed
at all. In many cases the default namespace will be
http://www.w3.org/2005/xpath-functions
, allowing a call on the fn:name
function (for example) to be written as name()
rather than fn:name()
;
in this document, however, all example function calls are explicitly prefixed.
The URIs of the namespaces and the conventional prefixes associated with them are:
http://www.w3.org/2001/XMLSchema
for constructors —
associated with xs
.
The section 20 Constructor functions defines
constructor functions for the built-in datatypes defined
in [XML Schema Part 2: Datatypes Second Edition] and in Section
2.7 Schema Information
DM31
of [XQuery and XPath Data Model (XDM) 3.1]. These datatypes and the corresponding constructor functions
are in the XML Schema namespace, http://www.w3.org/2001/XMLSchema
,
and are named in this document using the xs
prefix.
http://www.w3.org/2005/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
18.2 Functions that Operate on Maps). The namespace
prefix used in this document for these functions is map
.
These functions are available to users in exactly the same way as those in the
fn
namespace.
http://www.w3.org/2005/xpath-functions/array
for functions — associated with array
.
This namespace is used for some functions that manipulate maps (see
19.1 Functions that Operate on Arrays). The namespace
prefix used in this document for these functions is array
.
These functions are available to users in exactly the same way as those in the
fn
namespace.
http://www.w3.org/2005/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 [XSLT and XQuery Serialization 3.1]
Functions defined with the op
prefix are described here to
underpin the definitions of the operators in [XML Path Language (XPath) 4.0], [XQuery 4.1: An XML Query Language]
and [XSL Transformations (XSLT) Version 4.0]. These functions are not available
directly to users, and there is no requirement that implementations should
actually provide these functions. For this reason, no namespace is associated
with the op
prefix. For example, multiplication is generally
associated with the *
operator, but it is described as a function
in this document:
op:numeric-multiply ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
Sometimes there is a need to use an operator as a function.
To meet this requirement, the function fn:op
takes any simple binary operator as its argument,
and returns a corresponding function. So for example fn:for-each-pair($seq1, $seq2, op("+"))
performs a pairwise addition of the values in two input sequences.
Note:
The above namespace URIs are not expected to change from one version of this document to another. The contents of these namespaces may be extended to allow additional functions (and errors, and serialization parameters) to be defined.
A function is uniquely defined by its name and arity (number of arguments); it is therefore
not possible to have two different functions that have the same name and arity, but different
types in their signature. That is, function overloading in this sense of the term is not permitted.
Consequently, functions such as fn:string
which accept arguments of many different
types have a signature that defines a very general argument type, in this case item()?
which accepts any single item; supplying an inappropriate item (such as a function item) causes
a dynamic error.
Some functions on numeric types include the type xs:numeric
in their signature
as an argument or result type. In this version of the specification, xs:numeric
has been redefined as a built-in union type representing the union of
xs:decimal
, xs:float
, xs:double
(and thus automatically
accepting types derived from these, including xs:integer
).
Operators such as +
may be overloaded: they map to different underlying functions depending
on the dynamic types of the supplied operands.
It is possible for two functions to have the same name provided they have different arity (number of arguments). For the functions defined in this specification, where two functions have the same name and different arity, they also have closely related behavior, so they are defined in the same section of this document.
Each function (or group of functions having the same name) is defined in this specification using a standard proforma.
The function name is a QName
as defined in [XML Schema Part 2: Datatypes Second Edition]
and must adhere to its syntactic conventions. Following the precedent set by [XML Path Language (XPath) Version 1.0],
function names are generally composed of English words separated by hyphens (-
). Abbreviations are
used only where there is a strong precedent in other programming languages (as with math:sin
and
math:cos
for sine and cosine). If a
function name contains a [XML Schema Part 2: Datatypes Second Edition] datatype name, it may have
intercapitalized spelling and is used in the function name as such. An example is fn:timezone-from-dateTime
.
The first section in the proforma is a short summary of what the function does. This is intended to be informative rather than normative.
Each function is then defined by specifying its signature(s), which define the types of the parameters and of the result value.
Where functions take a variable number of arguments, two conventions are used:
Wherever possible, a single function signature is used giving default values for those parameters that can be omitted.
If this is not possible, because the effect of omitting a parameter cannot be specified by giving a default value, multiple signatures are given for the function.
Each function signature is presented in a form like this:
fn:function-name ( |
||
$parameter-name |
as , |
|
$... |
as
|
|
) as
|
In this notation, function-name, in bold-face, is the
local name of the
function whose signature is being specified. The prefix fn
indicates that the function is in the namespace http://www.w3.org/2005/xpath-functions
:
this is one of the conventional prefixes listed in 1.3 Namespaces and prefixes.
If the function takes no
parameters, then the name is followed by an empty parameter list:
()
; otherwise, the name is followed by a parenthesized list of
parameter declarations. Each parameter declaration includes:
The name of the parameter (which in 4.0 is significant because it can be used as a keyword in a function call)
The static type of the parameter (in italics)
If the parameter is optional, then an expression giving the default value
(preceded by the symbol :=
).
If there are two or more parameter declarations, they are separated by a comma.
The return-type
, also in italics, specifies the static type of the value returned by the
function. The dynamic type of the value returned by the function is the same as its static
type or derived from the static type. All parameter types and return types are
specified using the SequenceType notation defined in Section
2.5.4 SequenceType Syntax
XP31.
One function, fn:concat
, has a variable number of arguments (zero or more).
More strictly, there is an infinite set of functions having the name fn:concat
, with arity
ranging from 0 to infinity. For this special case, a single function signature is given, with an ellipsis
indicating an indefinite number of arguments.
The next section in the proforma defines the semantics of the function as a set of rules. The order in which the rules appear is significant; they are to be applied in the order in which they are written. Error conditions, however, are generally listed in a separate section that follows the main rules, and take precedence over non-error rules except where otherwise stated. The principles outlined in Section 2.3.4 Errors and Optimization XP31 apply by default: to paraphrase, if the result of the function can be determined without evaluating all its arguments, then it is not necessary to evaluate the remaining arguments merely in order to determine whether any error conditions apply.
Where the proforma includes sections headed Notes or Examples, these are non-normative.
Rules for passing parameters to operators are described in the relevant sections
of [XQuery 4.1: An XML Query Language] and [XML Path Language (XPath) 4.0]. For example, the rules for
passing parameters to arithmetic operators are described in Section
3.5 Arithmetic Expressions
XP31. Specifically, rules for parameters of
type xs:untypedAtomic
and the empty sequence are specified in this section.
As is customary, the parameter type name indicates that the function or operator
accepts arguments of that type, or types derived from it, in that position. This
is called subtype substitution (See Section
2.5.5 SequenceType Matching
XP31). In addition, numeric type instances and
instances of type xs:anyURI
can be promoted to produce an argument
of the required type. (See Section
B.1 Type Promotion
XP31).
Subtype Substitution: A derived type may substitute for
its base type. In particular, xs:integer
may be used
where xs:decimal
is expected.
Numeric Type Promotion: xs:decimal
may be
promoted to xs:float
or xs:double
.
Promotion to xs:double
should be done directly, not via
xs:float
, to avoid loss of precision.
anyURI Type Promotion: A value of
type xs:anyURI
can be promoted to the
type xs:string
.
Some functions accept a single value or the empty sequence as an argument and
some may return a single value or the empty sequence. This is indicated in the
function signature by following the parameter or return type name with a
question mark: ?
, indicating that either a single value or the
empty sequence must appear. See below.
fn:function-name ( |
||
$parameter-name |
as
|
|
) as
|
Note that this function signature is different from a signature in which the
parameter is omitted. See, for example, the two signatures
for fn:string
. In the first signature, the parameter is omitted
and the argument defaults to the context item, referred to as .
.
In the second signature, the argument must be present but may be the empty
sequence, written as ()
.
Some functions accept a sequence of zero or more values as an argument. This is
indicated by following the name of the type of the items in the sequence with
*
. The sequence may contain zero or more items of the named type.
For example, the function below accepts a sequence of xs:double
and
returns a xs:double
or the empty sequence.
fn:median ( |
||
$arg |
as
|
|
) as
|
In XPath 4.0, the arguments in a function call can be supplied by
keyword as an alternative to supplying them positionally. For example the call
resolve-uri(@href, static-base-uri())
can now be written
resolve-uri(base: static-base-uri(), relative: @href)
. The order in which
arguments are supplied can therefore differ from the order in which they are declared.
The specification, however, continues to use phrases such as “the second argument” as a
convenient shorthand for "the value of the argument that is bound to the second parameter
declaration".
As a matter of convention, a number of functions defined in this document take a parameter whose value is a map, defining options controlling the detail of how the function is evaluated. Maps are a new datatype introduced in XPath 3.1.
For example, the function fn:xml-to-json
has an options parameter
allowing specification of whether the output is to be indented. A call might be written:
xml-to-json($input, map{'indent':true()})
[Definition] Functions that take an options parameter adopt common conventions on how the options are used. These are referred to as the option parameter conventions. These rules apply only to functions that explicitly refer to them.
Where a function adopts the ·option parameter conventions·, the following rules apply:
The value of the relevant argument must be a map. The entries in the map are
referred to as options: the key of the entry is called the option name, and the
associated value is the option value. Option names defined in this specification
are always strings (single xs:string
values). Option values may
be of any type.
The type of the options parameter in the function signature is always
given as map(*)
.
Although option names are described above as strings, the actual key may be
any value that compares equal to the required string (using the eq
operator
with Unicode codepoint collation; or equivalently, the fn:atomic-equal
relation).
For example, instances of xs:untypedAtomic
or xs:anyURI
are equally acceptable.
Note:
This means that the implementation of the function can check for the
presence and value of particular options using the functions map:contains
and/or map:get
.
It is not an error if the options map contains options with names other than those
described in this specification. Implementations may attach an
·implementation-defined· meaning to such entries,
and may define errors that arise if such entries are present with invalid values.
Implementations must ignore such entries unless they have a specific
·implementation-defined· meaning.
Implementations that define additional options in this way should
use values of type xs:QName
as the option names, using an appropriate namespace.
All entries in the options map are optional, and supplying an empty map has the same effect as omitting the relevant argument in the function call, assuming this is permitted.
For each named option, the function specification defines a required type for the option value. The value that is actually supplied in the map is converted to this required type using the function conversion rulesXP31. This will result in an error (typically [err:XPTY0004]XP or [err:FORG0001]FO) if conversion of the supplied value to the required type is not possible. A type error also occurs if this conversion delivers a coerced function whose invocation fails with a type error. A dynamic error occurs if the supplied value after conversion is not one of the permitted values for the option in question: the error codes for this error are defined in the specification of each function.
Note:
It is the responsibility of each function implementation to invoke this conversion; it does not happen automatically as a consequence of the function-calling rules.
In cases where an option is list-valued, by convention the value may be supplied
either as a sequence or as an array. Accepting a sequence is convenient if the
value is generated programmatically using an XPath expression; while accepting an array
allows the options to be held in an external file in JSON format, to be read using
a call on the fn:json-doc
function.
In cases where the value of an option is itself a map, the specification of the particular function must indicate whether or not these rules apply recursively to the contents of that map.
The diagrams in this section show how nodes, functions, primitive simple types, and user defined types fit together into a type system. This type system comprises two distinct subsystems that both include the primitive atomic types. In the diagrams, connecting lines represent relationships between derived types and the types from which they are derived; the 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 values, and functions), and they are therefore used in declaring the types of variables or the argument types and result types of functions.
Item types in the data model form a directed graph, rather than a
hierarchy or lattice: in the relationship defined by the
derived-from(A, B)
function, some types are derived from
more than one other type. Examples include functions
(function(xs:string) as xs:int
is substitutable for
function(xs:NCName) as xs:int
and also for
function(xs:string) as xs:decimal
), and union types
(A
is substitutable for union(A, B)
and also
for union(A, C)
. In XDM, item types include node types,
function types, and built-in atomic types. The diagram, which shows
only hierarchic relationships, is therefore a simplification of the
full model.
item (abstract)
anyAtomicType (built-in atomic)
node (node)
attribute (node)
user-defined attribute types (user-defined)
document (node)
user-defined document types (user-defined)
element (node)
user-defined element types (user-defined)
text (node)
comment (node)
processing-instruction (node)
namespace (node)
function(*) (function item)
array(*) (function item)
map(*) (function item)
Legend:
Supertype
subtype
Abstract types (abstract)
Built-in atomic types (built-in atomic)
Node types (node)
Function item types (function item)
User-defined types (user-defined)
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.
XML Schema types (abstract)
anyType (built-in complex)
Simple types (abstract)
anySimpleType (built-inlist)
Atomic types (abstract)
anyAtomicType (built-in atomic)
list types (abstract)
ENTITIES (built-in list)
IDREFS (built-in list)
NMTOKENS (built-in list)
user-defined list types (user-defined)
union types (abstract)
numeric (built-in complex)
user-defined union types (user-defined)
complex types (complex)
untyped (built-in complex)
user-defined complex types (user-defined)
Legend:
Supertype
subtype
Abstract types (abstract)
Built-in atomic types (built-in atomic)
Built-in complex types (built-in complex)
Built-in list types (built-in list)
User-defined types (user-defined)
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 [XML Schema Part 2: Datatypes Second Edition].
Atomic types are both item types and schema types, so the root type xs:anyAtomicType
may be found
in both the previous diagrams.
anyAtomicType
anyURI
base64Binary
boolean
date
dateTime
dateTimeStamp
decimal
integer
long
int
short
byte
nonNegativeInteger
positiveInteger
unsignedLong
unsignedInt
unsignedShort
unsignedByte
nonPositiveInteger
negativeInteger
double
duration
dayTimeDuration
yearMonthDuration
float
gDay
gMonth
gMonthDay
gYear
gYearMonth
hexBinary
NOTATION
QName
string
normalizedString
token
NMTOKEN
Name
NCName
ENTITY
ID
IDREF
language
time
Legend:
Supertype
subtype
Built-in atomic types
The terminology used to describe the functions and operators on types defined in [XML Schema Part 2: Datatypes Second Edition] is defined in the body of this specification. The terms defined in this section are used in building those definitions.
Note:
Following in the tradition of [XML Schema Part 2: Datatypes Second Edition], the terms type and datatype are used interchangeably.
This document uses the terms string
, character
, and codepoint
with meanings that are normatively defined in [XQuery and XPath Data Model (XDM) 3.1], and which are paraphrased here
for ease of reference:
[Definition] A character is an instance of the CharXML production of [Extensible Markup Language (XML) 1.0 (Fifth Edition)].
Note:
This definition excludes Unicode characters in the surrogate blocks as well as xFFFE and xFFFF, while including characters with codepoints greater than xFFFF which some programming languages treat as two characters. The valid characters are defined by their codepoints, and include some whose codepoints have not been assigned by the Unicode consortium to any character.
[Definition] A string is a sequence of zero or more
·characters·, or equivalently,
a value in the value space of the xs:string
datatype.
[Definition] A codepoint is an integer assigned to a ·character· by the Unicode consortium, or reserved for future assignment to a character.
Note:
The set of codepoints is thus wider than the set of characters.
This specification spells “codepoint” as one word; the Unicode specification spells it as “code point”. Equivalent terms found in other specifications are “character number” or “code position”. See [Character Model for the World Wide Web 1.0: Fundamentals]
Because these terms appear so frequently, they are hyperlinked to the definition only when there is a particular desire to draw the reader’s attention to the definition; the absence of a hyperlink does not mean that the term is being used in some other sense.
It is ·implementation-defined· which version of [The Unicode Standard] is supported, but it is recommended that the most recent version of Unicode be used.
Unless explicitly stated, the functions in this document do not ensure that any
returned xs:string
values are normalized in the sense of [Character Model for the World Wide Web 1.0: Fundamentals].
Note:
In functions that involve character counting such
as fn:substring
, fn:string-length
and
fn:translate
, what is counted is the number of XML ·characters·
in the string (or equivalently, the number of Unicode codepoints). Some
implementations may represent a codepoint above xFFFF using two 16-bit
values known as a surrogate pair. A surrogate pair counts as one character, not two.
This document uses the phrase “namespace URI” to identify the concept identified in [Namespaces in XML] as “namespace name”, and the phrase “local name” to identify the concept identified in [Namespaces in XML] as “local part”.
It also uses the term “expanded-QName” defined below.
[Definition] An expanded-QName
is a value in the value space of the xs:QName
datatype as defined in the XDM data model
(see [XQuery and XPath Data Model (XDM) 3.1]): that is, a triple containing namespace prefix (optional), namespace URI (optional),
and local name. Two expanded QNames are equal if the namespace URIs are the same (or both absent)
and the local names are the same. The prefix plays no part in the comparison, but is used only
if the expanded QName needs to be converted back to a string.
The term URI is used as follows:
[Definition] Within this specification, the term URI refers to Universal Resource Identifiers as
defined in [RFC 3986] and extended in [RFC 3987] with a new name IRI. The term URI
Reference, unless otherwise stated, refers to a string in the lexical space of the xs:anyURI
datatype
as defined in [XML Schema Part 2: Datatypes Second Edition].
Note:
This means, in practice, that where this
specification requires a “URI Reference”, an IRI as defined in [RFC 3987] will be
accepted, provided that other relevant specifications also permit an IRI. The term URI has been
retained in preference to IRI to avoid introducing new names for concepts such as “Base URI” that
are defined or referenced across the whole family of XML specifications. Note also that the
definition of xs:anyURI
is a wider definition than the definition in [RFC 3987];
for example it does not require non-ASCII characters to be escaped.
In this specification:
The auxiliary verb must, when rendered in small capitals, indicates a precondition for conformance.
When the sentence relates to an implementation of a function (for example "All implementations must recognize URIs of the form ...") then an implementation is not conformant unless it behaves as stated.
When the sentence relates to the result of a function (for example "The result must have the same type as
$arg
") then the implementation is not conformant unless it delivers a result as stated.
When the sentence relates to the arguments to a function (for example "The value of $arg
must
be a valid regular expression") then the implementation is not conformant unless it enforces the condition by raising a dynamic error
whenever the condition is not satisfied.
The auxiliary verb may, when rendered in small capitals, indicates optional or discretionary behavior. The statement “An implementation may do X” implies that it is implementation-dependent whether or not it does X.
The auxiliary verb should, when rendered in small capitals, indicates desirable or recommended behavior. The statement “An implementation should do X” implies that it is desirable to do X, but implementations may choose to do otherwise if this is judged appropriate.
[Definition] Where behavior is described as implementation-defined, variations between processors are permitted, but a conformant implementation must document the choices it has made.
[Definition] Where behavior is described as implementation-dependent, variations between processors are permitted, and conformant implementations are not required to document the choices they have made.
Note:
Where this specification states that something is 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 function, unless otherwise specified, applies equally to function definitionsXP40 (which can be the target of a static function call) and function itemsDM40 (which can be the target of a dynamic function call).
[Definition] An execution scope is a sequence of
calls to the function library during which certain aspects of the state are required to remain invariant.
For example, two calls to fn:current-dateTime
within the same execution scope will return the same result.
The execution scope is defined by the host language that invokes the function library.
In XSLT, for example, any two function calls executed during
the same transformation are in the same execution scope (except that static expressions, such as those used in
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:
[Definition] Two values $V1
and $V2
are
defined to be identical if they contain the same number of items and the items are pairwise identical. Two items are identical
if and only if one of the following conditions applies:
Both items are atomic values, of precisely the same type, and the values are equal as defined using the eq
operator,
using the Unicode codepoint collation when comparing strings.
Both items are nodes, and represent the same node.
Both items are maps, both maps have the same number of entries, and for every entry E1 in the first map there is an entry E2 in the second map such that the keys of E1 and E2 are ·the same key·, and the corresponding values V1 and V2 are ·identical·.
Both items are arrays, both arrays have the same number of members, and the members are pairwise ·identical·.
Both items are function items, neither item is a map or array, and the two function items have the same function identity. The concept of function identity is explained in Section 2.9.1 Function ItemsDM40.
Some functions produce results that depend not only on their explicit arguments, but also on the static and dynamic context.
[Definition] A
function definitionXP40
may have the property of being context-dependent: the result of such a
function depends on the values of properties in the static and dynamic
evaluation context of the caller
as well as on the actual supplied arguments (if any). A function definition may
be context-dependent for some arities in its arity range, and context-independent
for others: for example fn:name#0
is context-dependent
while fn:name#1
is context-independent.
[Definition] A function definitionXP40 that is not ·context-dependent· is called context-independent.
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 fn:static-base-uri
, fn:default-collation
,
fn:position
, or fn:last
.
Functions with an optional parameter whose default value is taken from the static
or dynamic context of the caller, usually either the context item (for example, fn:node-name
)
or the default collation (for example, fn:index-of
).
Functions that use the static context of the caller to expand or disambiguate
the values of supplied arguments: for example fn:doc
expands its first
argument using the static base URI of the caller, and xs:QName
expands its first argument
using the in-scope namespaces of the caller.
[Definition] A function is focus-dependent if its result depends on the focusXP31 (that is, the context item, position, or size) of the caller.
[Definition] A function that is not ·focus-dependent· is called focus-independent.
Notes:
Note:
Some functions depend on aspects of the dynamic context that remain invariant within an ·execution scope·, such as the implicit timezone. Formally this is treated in the same way as any other context dependency, but internally, the implementation may be able to take advantage of the fact that the value is invariant.
Note:
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.
Note:
Because the focus is a specific part of the dynamic context, all ·focus-dependent· functions are also ·context-dependent·. A ·context-dependent· function, however, may be either ·focus-dependent· or ·focus-independent·.
A function definition that is context-dependent
can be used as the target of a named
function reference, can be partially applied, and can be found using fn:function-lookup
.
The principle in such cases is that the static context used for the function evaluation
is taken from the static context of the named function reference, partial function application, or the call
on fn:function-lookup
; and the dynamic context for the function evaluation is taken from the dynamic
context of the evaluation of the named function reference, partial function application, or the call
of fn:function-lookup
. These constructs all deliver a
function itemDM40
having a captured context based on the static and dynamic
context of the construct that created the function item. This captured context forms
part of the closure of the function item.
The result of a dynamic call to a function item never depends on the static or dynamic context of the dynamic function call, only (where relevant) on the the captured context held within the function item itself.
The fn:function-lookup
function is a special case because it is
potentially dependent on everything in the static and dynamic context. This is because the static and dynamic
context of the call to fn:function-lookup
form the captured context of the
function item that fn:function-lookup
returns.
[Definition] A function that is guaranteed to produce ·identical· results from repeated calls within a single ·execution scope· if the explicit and ·implicit· arguments are identical is referred to as deterministic.
[Definition] A function that is not ·deterministic· is referred to as nondeterministic.
All functions defined in this specification are ·deterministic· unless otherwise stated. Exceptions include the following:
[Definition] Some
functions (such as fn:distinct-values
, fn:unordered
, map:keys
,
and map:for-each
) produce results in an
·implementation-defined· or
·implementation-dependent· order.
In such cases two calls with the same arguments are not guaranteed to produce the results in the same order. These functions are
said to be nondeterministic with respect to ordering.
Some functions (such as fn:analyze-string
,
fn:parse-xml
, fn:parse-xml-fragment
, and fn:json-to-xml
)
construct a tree of nodes to
represent their results. There is no guarantee that repeated calls with the same
arguments will return the same identical node (in the sense of the is
operator). However, if non-identical nodes are returned, their content will be the
same in the sense of the fn:deep-equal
function. Such a function is said
to be non-deterministic with respect to node identity.
Some functions (such as fn:doc
and fn:collection
) create new nodes by reading external
documents. Such functions are guaranteed to be ·deterministic· with the exception that
an implementation is allowed to make them non-deterministic as a user option.
Where the results of a function are described as being (to a greater or lesser extent) ·implementation-defined· or ·implementation-dependent·, this does not by itself remove the requirement that the results should be deterministic: that is, that repeated calls with the same explicit and implicit arguments must return identical results.
Accessors and their semantics are described in [XQuery and XPath Data Model (XDM) 3.1]. Some of these accessors are exposed to the user through the functions described below.
Each of these functions has an arity-zero signature which is equivalent to the arity-one
form, with the context item supplied as the implicit first argument. In addition, each of the
arity-one functions accepts an empty sequence as the argument, in which case it generally delivers
an empty sequence as the result: the exception is fn:string
, which delivers
a zero-length string.
Function | Accessor | Accepts | Returns |
---|---|---|---|
fn:node-name
|
node-name
|
node (optional) | xs:QName (optional)
|
fn:nilled
|
nilled
|
node (optional) | xs:boolean (optional)
|
fn:string
|
string-value
|
item (optional) |
xs:string
|
fn:data
|
typed-value
|
zero or more items | a sequence of atomic values |
fn:base-uri
|
base-uri
|
node (optional) | xs:anyURI (optional)
|
fn:document-uri
|
document-uri
|
node (optional) | xs:anyURI (optional)
|
Returns the name of a node, as an xs:QName
.
fn:node-name ( |
||
$node |
as
|
:= . |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the argument is omitted, it defaults to the context item (.
).
If $node
is the empty sequence, the empty sequence is returned.
Otherwise, the function returns the result of the dm:node-name
accessor as
defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 4.10 node-name AccessorDM40).
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
For element and attribute nodes, the name of the node is returned as an
xs:QName
, retaining the prefix, namespace URI, and local part.
For processing instructions, the name of the node is returned as an
xs:QName
in which the prefix and namespace URI are absentDM40.
For a namespace node, the function returns an empty sequence if the node represents the
default namespace; otherwise it returns an xs:QName
in which prefix and
namespace URI are absentDM40 and the local
part is the namespace prefix being bound.
For all other kinds of node, the function returns the empty sequence.
Returns true
for an element that is nilled.
fn:nilled ( |
||
$node |
as
|
:= . |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the argument is omitted, it defaults to the context item (.
).
If $node
is the empty sequence, the function returns the empty sequence.
Otherwise the function returns the result of the dm:nilled
accessor as
defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 4.8 nilled AccessorDM40).
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
If $node
is not an element node, the function returns the empty
sequence.
If $node
is an untyped element node, the function returns false
.
In practice, the function returns true
only for an element node that has
the attribute xsi:nil="true"
and that is successfully validated against a
schema that defines the element to be nillable; the detailed rules, however, are defined
in [XQuery and XPath Data Model (XDM) 3.1].
Returns the value of $value
represented as an xs:string
.
fn:string ( |
||
$value |
as
|
:= . |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
In the zero-argument version of the function, $value
defaults to the context
item. That is, calling fn:string()
is equivalent to calling
fn:string(.)
.
If $value
is the empty sequence, the function returns the zero-length
string.
If $value
is a node, the function returns the string value of the node, as obtained using the
dm:string-value
accessor defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 4.12 string-value AccessorDM40).
If $value
is an atomic value, the function returns the result of the expression $value cast
as xs:string
(see 21 Casting).
In all other cases, a dynamic error occurs (see below).
A dynamic error is raised [err:XPDY0002]XP by the zero-argument version of the function if the context item is absentDM40.
A type error is raised [err:FOTY0014] if
$value
is a function item (this includes maps and arrays).
Every node has a string value, even an element with element-only content (which has no typed value). Moreover, casting an atomic value to a string always succeeds. Functions, maps, and arrays have no string value, so these are the only arguments that satisfy the type signature but cause failure.
Expression | Result |
---|---|
|
|
|
|
|
|
|
Raises error XPTY0004. |
|
Raises error FOTY0014. |
|
Raises error FOTY0014. |
let $para := <para>In a hole in the ground there lived a <term author="Tolkien">hobbit</term>.</para> |
|
|
|
Returns the result of atomizing a sequence. This process flattens arrays, and replaces nodes by their typed values.
fn:data ( |
||
$input |
as
|
:= . |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the argument is omitted, it defaults to the context item (.
).
The result of fn:data
is the sequence of atomic values produced by
applying the following rules to each item in $input
:
If the item is an atomic value, it is appended to the result sequence.
If the item is a node, the typed value of the node is appended to the result
sequence. The typed value is a sequence of zero or more atomic values:
specifically, the result of the dm:typed-value
accessor as defined in
[XQuery and XPath Data Model (XDM) 3.1] (See Section 4.14 typed-value AccessorDM40).
If the item is an array, the result of applying fn:data
to
each member of the array, in order, is appended to the result sequence.
A type error is raised [err:FOTY0012] if an item in the
sequence $input
is a node that does not have a typed value.
A type error is raised [err:FOTY0013] if an item in
the sequence $input
is a function item other than
an array.
A dynamic error is raised if $input
is omitted and the context item is
absentDM40.
The process of applying the fn:data
function to a sequence is referred to
as atomization
. In many cases an explicit call on fn:data
is
not required, because atomization is invoked implicitly when a node or sequence of nodes
is supplied in a context where an atomic value or sequence of atomic values is
required.
The result of atomizing an empty sequence is an empty sequence.
The result of atomizing an empty array is an empty sequence.
Expression | Result |
---|---|
|
|
|
|
|
|
let $para := <para>In a hole in the ground there lived a <term author="Tolkien">hobbit</term>.</para> |
|
|
|
|
|
|
Raises error FOTY0013. |
Returns the base URI of a node.
fn:base-uri ( |
||
$node |
as
|
:= . |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The zero-argument version of the function returns the base URI of the context node: it
is equivalent to calling fn:base-uri(.)
.
The single-argument version of the function behaves as follows:
If $node
is the empty sequence, the function returns the empty
sequence.
Otherwise, the function returns the value of the dm:base-uri
accessor
applied to the node $node
. This accessor is defined, for each kind of
node, in the XDM specification (See Section 4.2 base-uri AccessorDM40).
Note:
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 an empty sequence — it does not depend on the base URI of the parent element.
See also fn:static-base-uri
.
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
Returns the URI of a resource where a document can be found, if available.
fn:document-uri ( |
||
$node |
as
|
:= . |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the argument is omitted, it defaults to the context item (.
).
If $node
is the empty sequence, the function returns the empty sequence.
If $node
is not a document node, the function returns the empty
sequence.
Otherwise, the function returns the value of the document-uri
accessor
applied to $node
, as defined in [XQuery and XPath Data Model (XDM) 3.1] (See
Section 5.1.2 AccessorsDM40).
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
In the case of a document node $D
returned by the fn:doc
function, or a document node at the root of a tree containing a node returned by the
fn:collection
function, it will always be true that either
fn:document-uri($D)
returns the empty sequence, or that the following
expression is true
: fn:doc(fn:document-uri($D))
is $D
. It is
·implementation-defined· whether this guarantee also holds for
document nodes obtained by other means, for example a document node passed as the
initial context node of a query or transformation.
A consequence of these rules is that it is not possible (within the
execution scope of a transformation) for two different documents to have the same
value for their document-uri
property. This means that in situations where
URI stability is not guaranteed (for example, with streamed input documents in XSLT,
or for documents returned by fn:collection
if document stability has been
disabled), the document-uri
property should be absent, and
fn:document-uri
should return an empty sequence.
In this document, as well as in [XQuery 4.1: An XML Query Language] and [XML Path Language (XPath) 4.0],
the phrase “an error is raised”
is used. Raising an error is equivalent to calling the fn:error
function defined in this section with the provided error code. Except where otherwise
specified, errors defined in this specification are dynamic errors. Some errors,
however, are classified as type errors. Type errors are typically used where the presence
of the error can be inferred from knowledge of the type of the actual arguments to a function, for
example with a call such as fn:string(fn:abs#1)
. Host languages may allow type errors
to be reported statically if they are discovered during static analysis.
When function specifications indicate that an error is to be raised, the notation
“[error code ]” is used to specify an error code. Each error defined
in this document is identified by an xs:QName
that is in the
http://www.w3.org/2005/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
fn:error
function. Calling this function raises an error. For a
more detailed treatment of error handing, see Section
2.3.3 Handling Dynamic Errors
XP31.
The fn:error
function is a general function that may be called as above
but may also be called from [XQuery 4.1: An XML Query Language] or [XML Path Language (XPath) 4.0]
applications with, for example, an xs:QName
argument.
Calling the fn:error
function raises an application-defined error.
fn:error ( |
||
$code |
as
|
:= () , |
$description |
as
|
:= () , |
$value |
as
|
:= . |
) as
|
This function is ·nondeterministic·, ·context-independent·, and ·focus-independent·.
This function never returns a value. Instead it always raises an error. The effect of the error is identical to the effect of dynamic errors raised implicitly, for example when an incorrect argument is supplied to a function.
The parameters to the fn:error
function supply information that is
associated with the error condition and that is made available to a caller that asks for
information about the error. The error may be caught either by the host language (using
a try/catch construct in XSLT or XQuery, for example), or by the calling application or
external processing environment. The way in which error information is returned to the
external processing environment is ·implementation-dependent·.
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 no value is supplied for the $code
argument, or if the value supplied
is an empty sequence,
the effective value of the error code is fn:QName('http://www.w3.org/2005/xqt-errors', 'err:FOER0000')
.
The $description
is a natural-language description of the error
condition.
If no value is supplied for the $description
argument, or if the value supplied
is an empty sequence, then the
effective value of the description is ·implementation-dependent·.
The $value
is an arbitrary value used to convey additional
information about the error, and may be used in any way the application
chooses.
If no value is supplied for the $value
argument or if the value supplied
is an empty sequence, then the
effective value of the error object is ·implementation-dependent·.
This function always raises a dynamic error. By default, it raises [err:FOER0000]
The value of the $description
parameter may need to be localized.
The type “none” is a special type defined in [XQuery 1.0 and XPath 2.0 Formal Semantics] and is not available to the user. It indicates that the function never returns and ensures that it has the correct static type.
Any QName may be used as an error code; there are no reserved names or namespaces. The error is always classified as a dynamic error, even if the error code used is one that is normally used for static errors or type errors.
|
Raises error FOER0000. (This returns the URI
|
error( QName( 'http://www.example.com/HR', 'myerr:toohighsal' ), 'Salary is too high' ) |
Raises error myerr:toohighsal. (This returns |
All three arguments are now optional, and each argument can be set
to an empty sequence. Previously if $description
was supplied, it could not be empty.
Provides an execution trace intended to be used in debugging queries.
fn:trace ( |
||
$input |
as , |
|
$label |
as
|
:= () |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns $input
, unchanged.
In addition, the values of $input
, typically serialized and converted
to an xs:string
, and $label
(if supplied
and non-empty) may
be output to an ·implementation-defined· destination.
The serialization of the trace output must not raise an error. This can be achieved (for example) by using a serialization method that can handle arbitrary input, such as the adaptive output method (see Section 10 Adaptive Output Method SER31).
The format of the trace output and its order are ·implementation-dependent·. Therefore, the order in which the output appears is not predictable. This also means that if dynamic errors occur (whether or not they are caught using try/catch), it may be unpredictable whether any output is logged before the error occurs.
If the trace information is unrelated to a specific value,
fn:log
can be used instead.
Consider a situation in which a user wants to investigate the actual value passed to
a function. Assume that in a particular execution, |
The $label
argument can now be set
to an empty sequence. Previously if $label
was supplied, it could not be empty.
Outputs trace information and discards the result.
fn:log ( |
||
$input |
as , |
|
$label |
as
|
:= () |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Similar to fn:trace
, the values of $input
,
typically serialized and converted to an xs:string
, and $label
(if supplied and non-empty) may be output to an
·implementation-defined· destination.
In contrast to fn:trace
, the function returns an empty sequence.
The serialization of the log output must not raise an error. This can e.g. be achieved by using a serialization method that can handle arbitrary input, such as the Section 10 Adaptive Output Method SER31.
The format of the trace output and its order are ·implementation-dependent·. Therefore, the order in which the output appears is not predictable. This also means that if dynamic errors occur (whether or not they are caught using try/catch), it may be unpredictable whether any output is logged before the error occurs.
The function can be used for debugging. It can also be helpful in productive environments, e.g. to store dynamic input and evaluations to log files.
New function.
Returns implementation-dependent information about the current state of execution.
fn:stack-trace () as xs:string |
This function is ·nondeterministic·, ·context-independent·, and ·focus-independent·.
The result of the function is an ·implementation-dependent· string containing diagnostic information about the current state of execution.
The function is non-deterministic: multiple calls will typically produce different results.
The function will typically be called to assist in diagnosing dynamic errors.
This section specifies arithmetic operators on the numeric datatypes defined in [XML Schema Part 2: Datatypes Second Edition].
The operators described in this section are defined on the following atomic types.
decimal
integer
double
float
Legend:
Supertype
subtype
Built-in 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 21.3.5 Casting to union types.
Because the lexical space of xs:double
subsumes the lexical space of the other member types, and
xs:double
is listed first, the effect is that if the untyped atomic value is in the lexical space of
xs:double
, it will be converted to an xs:double
, and if not, a dynamic error occurs.
When the return type of a function is given as xs:numeric
, the actual value returned will be
an instance of one of the three member types (and perhaps also of types derived from these by restriction). The rules
for the particular function will specify how the type of the result depends on the values supplied as arguments.
In many cases, for the functions in this specification, the result is defined to be the same type as the first
argument.
Note:
This specification uses [IEEE 754-2008] arithmetic for xs:float
and xs:double
values.
One consequence of this is that some operations result in the value NaN
(not a number), which
has the unusual property that it is not equal to itself. Another consequence is that some operations return the value negative zero.
This differs from [XML Schema Part 2: Datatypes Second Edition], which defines
NaN
as being equal to itself and defines only a single zero in the value space.
The text accompanying several functions defines behavior for both positive and negative zero inputs and outputs
in the interest of alignment with [IEEE 754-2008]. A conformant implementation must
respect these semantics. In consequence, the expression -0.0e0
(which is actually a unary minus operator
applied to an xs:double
value) will always return negative zero: see 4.2.8 op:numeric-unary-minus.
As a concession to implementations that rely on implementations of XSD 1.0, however, when casting from string to double
the lexical form -0
may be converted to positive zero, though negative zero
is recommended.
XML Schema 1.1 introduces support for positive and negative zero as distinct values, and also uses the [IEEE 754-2008]
semantics for comparisons involving NaN
.
The following functions define the semantics of arithmetic operators defined in [XQuery 4.1: An XML Query Language] and [XML Path Language (XPath) 4.0] on these numeric types.
Operator | Meaning |
---|---|
op: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, subtype substitution and numeric type promotion are used to obtain two operands of the same type. Section B.1 Type Promotion XP31 and Section B.2 Operator Mapping XP31 describe the semantics of these operations in detail.
The result type of operations depends on their argument datatypes and is defined in the following table:
Operator | Returns |
---|---|
op:operation(xs:integer, xs:integer)
|
xs:integer (except for op: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
|
These rules define any operation on any pair of arithmetic types. Consider the following example:
op:operation(xs:int, xs:double) => op:operation(xs:double, xs:double)
For this operation, xs:int
must be converted to
xs:double
. This can be done, since by the rules above:
xs:int
can be substituted for xs:integer
,
xs:integer
can be substituted for xs:decimal
,
xs:decimal
can be promoted to xs:double
. As far as possible, the promotions should be done in a
single step. Specifically, when an xs:decimal
is promoted to an
xs:double
, it should not be converted to an xs:float
and then to xs:double
, as this risks loss of precision.
As another example, a user may define height
as a derived type of
xs:integer
with a minimum value of 20 and a maximum value of 100.
They may then derive fenceHeight
using an enumeration to restrict the
permitted set of values to, say, 36, 48 and 60.
op:operation(fenceHeight, xs:integer) => op:operation(xs:integer, xs:integer)
fenceHeight
can be substituted for its base type
height
and height
can be substituted for its base type
xs:integer
.
The basic rules for addition, subtraction, and multiplication
of ordinary numbers are not set out in this specification; they are taken as given. In the case of xs:double
and xs:float
the rules are as defined in [IEEE 754-2008]. The rules for handling
division and modulus operations, as well as the rules for handling special values such as infinity and NaN
,
and exception conditions such as overflow and underflow, are described more explicitly since they are not necessarily obvious.
On overflow and underflow situations during arithmetic operations, conforming implementations must behave as follows:
For xs:float
and xs:double
operations, overflow
behavior must be conformant with [IEEE 754-2008]. This specification allows the following options:
Raising a dynamic error [err:FOAR0002] via an overflow trap.
Returning INF
or -INF
.
Returning the largest (positive or negative) non-infinite number.
For xs:float
and xs:double
operations,
underflow behavior must be conformant with [IEEE 754-2008]. This specification allows the following options:
Raising a dynamic error [err:FOAR0002] via an underflow trap.
Returning 0.0E0
or +/- 2**Emin
or a
denormalized value; where Emin
is the smallest
possible xs:float
or xs:double
exponent.
For xs:decimal
operations, overflow behavior must
raise a dynamic error [err:FOAR0002]. On
underflow, 0.0
must be returned.
For xs:integer
operations, implementations that support
limited-precision integer operations must select from
the following options:
They may choose to always raise a dynamic error [err:FOAR0002].
They may provide an ·implementation-defined· mechanism that allows users to choose between raising an error and returning a result that is modulo the largest representable integer value. See [ISO 10967].
The functions op: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 should be accurate to N digits of precision, and for division and modulus operations,
the returned result should be accurate to at least M digits of precision.
The actual precision is ·implementation-defined·. If the number
of digits in the mathematical result exceeds the number of digits that the implementation
retains for that operation, the result is truncated or rounded in an ·implementation-defined· manner.
Note:
This specification does not determine whether xs:decimal
operations are fixed point or floating point.
In an implementation using floating point it is possible for very simple operations to require more digits of precision than
are available; for example, adding 1e100
to 1e-100
requires 200 digits of precision for an
accurate representation of the result.
The [IEEE 754-2008] specification also describes handling of
two exception conditions called divideByZero
and invalidOperation
. The
IEEE divideByZero
exception is raised not only by a direct attempt to divide by zero, but also by
operations such as log(0)
. The IEEE invalidOperation
exception is raised by
attempts to call a function with an argument that is outside the function’s domain (for example,
sqrt(-1)
or log(-1)
).
Although IEEE defines these as exceptions, it also defines “default 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 may be notified to the application
or to the user by some ·implementation-defined·
warning condition, but the observable effect on an application
using the functions and operators defined in this specification is simply to return
the defined result (typically -INF
, +INF
, or NaN
) with no error.
The [IEEE 754-2008] specification distinguishes two NaN
values:
a quiet NaN
and a signaling NaN
. These two values are not distinguishable in the XDM model:
the value spaces of xs:float
and xs:double
each include only a single
NaN
value. This does not prevent the implementation distinguishing them internally,
and triggering different ·implementation-defined·
warning conditions, but such distinctions do not affect the observable behavior of an application
using the functions and operators defined in this specification.
Returns the arithmetic sum of its operands: ($arg1 + $arg2
).
Defines the semantics of the +
operator when
applied to two numeric values
op:numeric-add ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
General rules: see 4.2 Arithmetic operators on numeric values.
For xs:float
or xs:double
values, if one of the operands is a
zero or a finite number and the other is INF
or -INF
,
INF
or -INF
is returned. If both operands are
INF
, INF
is returned. If both operands are
-INF
, -INF
is returned. If one of the operands is
INF
and the other is -INF
, NaN
is
returned.
Returns the arithmetic difference of its operands: ($arg1 - $arg2
).
Defines the semantics of the -
operator when
applied to two numeric values.
op:numeric-subtract ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
General rules: see 4.2 Arithmetic operators on numeric values.
For xs:float
or xs:double
values, if one of the operands is a
zero or a finite number and the other is INF
or -INF
, an
infinity of the appropriate sign is returned. If both operands are INF
or
-INF
, NaN
is returned. If one of the operands is
INF
and the other is -INF
, an infinity of the appropriate
sign is returned.
Returns the arithmetic product of its operands: ($arg1 * $arg2
).
Defines the semantics of the *
operator when
applied to two numeric values.
op:numeric-multiply ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
General rules: see 4.2 Arithmetic operators on numeric values.
For xs:float
or xs:double
values, if one of the operands is a
zero and the other is an infinity, NaN
is returned. If one of the operands
is a 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.
op:numeric-divide ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
General rules: see 4.2 Arithmetic operators on numeric values.
As a special case, if the types of both $arg1
and $arg2
are
xs:integer
, then the return type is xs:decimal
.
A dynamic error is raised [err:FOAR0001] for xs:decimal
and xs:integer
operands, if the divisor is (positive or negative) zero.
For xs:float
and xs:double
operands, floating point division
is performed as specified in [IEEE 754-2008]. A positive number divided by
positive zero returns INF
. A negative number divided by positive zero
returns -INF
. Division by negative zero returns -INF
and
INF
, respectively. Positive or negative zero divided by positive or
negative zero returns NaN
. Also, INF
or -INF
divided by INF
or -INF
returns NaN
.
Performs an integer division.
Defines the semantics of the idiv
operator when
applied to two numeric values.
op:numeric-integer-divide ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
General rules: see 4.2 Arithmetic operators on numeric values.
If $arg2
is INF
or -INF
, and $arg1
is not INF
or -INF
, then the result is zero.
Otherwise, subject to limits of precision and overflow/underflow conditions, the result
is the largest (furthest from zero) xs:integer
value $N
such
that the following expression is true
:
abs($N * $arg2) le abs($arg1) and compare($N * $arg2, 0) eq compare($arg1, 0).
Note:
The second term in this condition ensures that the result has the correct sign.
The implementation may adopt a different algorithm provided that it is equivalent to
this formulation in all cases where ·implementation-dependent· or ·implementation-defined· behavior does not affect the outcome, for example,
the implementation-defined precision of the result of xs:decimal
division.
A dynamic error is raised [err:FOAR0001] if the divisor is (positive or negative) zero.
A dynamic error is raised [err:FOAR0002] if either operand is
NaN
or if $arg1
is INF
or
-INF
.
Except in situations involving errors, loss of precision, or overflow/underflow, the
result of $a idiv $b
is the same as ($a div $b) cast as
xs:integer
.
The semantics of this function are different from integer division as defined in programming languages such as Java and C++.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Returns the remainder resulting from dividing $arg1
, the dividend, by
$arg2
, the divisor.
Defines the semantics of the mod
operator when
applied to two numeric values.
op:numeric-mod ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
General rules: see 4.2 Arithmetic operators on numeric values.
The operation a mod b
for operands that are xs:integer
or
xs:decimal
, or types derived from them, produces a result such that
(a idiv b)*b+(a mod b)
is equal to a
and the magnitude of
the result is always less than the magnitude of b
. This identity holds even
in the special case that the dividend is the negative integer of largest possible
magnitude for its type and the divisor is -1 (the remainder is 0). It follows from this
rule that the sign of the result is the sign of the dividend.
For xs:float
and xs:double
operands the following rules
apply:
If either operand is NaN
, the result is NaN
.
If the dividend is positive or negative infinity, or the divisor is positive or
negative zero (0), or both, the result is NaN
.
If the dividend is finite and the divisor is an infinity, the result equals the dividend.
If the dividend is positive or negative zero and the divisor is finite, the result is the same as the dividend.
In the remaining cases, where neither positive or negative infinity, nor positive
or negative zero, nor NaN
is involved, the result obeys (a idiv
b)*b+(a mod b)
= a
.
Division is truncating division, analogous to integer division, not [IEEE 754-2008] rounding division i.e. additional digits are truncated,
not rounded to the required precision.
A dynamic error is raised [err:FOAR0001] for xs:integer
and xs:decimal
operands, if $arg2
is zero.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
Returns its operand with the sign unchanged: (+ $arg
).
Defines the semantics of the unary +
operator
applied to a numeric value.
op:numeric-unary-plus ( |
||
$arg |
as
|
|
) as
|
General rules: see 4.2 Arithmetic operators on numeric values.
The returned value is equal to $arg
, and is an instance of
xs:integer
, xs:decimal
, xs:double
, or
xs:float
depending on the type of $arg
.
Because function conversion rules are applied in the normal way, the unary
+
operator can be used to force conversion of an untyped node to a
number: the result of +@price
is the same as xs:double(@price)
if the type of @price
is xs:untypedAtomic
.
Returns its operand with the sign reversed: (- $arg
).
Defines the semantics of the unary -
operator when
applied to a numeric value.
op:numeric-unary-minus ( |
||
$arg |
as
|
|
) as
|
General rules: see 4.2 Arithmetic operators on numeric values.
The returned value is an instance of xs:integer
, xs:decimal
,
xs:double
, or xs:float
depending on the type of
$arg
.
For xs:integer
and xs:decimal
arguments, 0
and
0.0
return 0
and 0.0
, respectively. For
xs:float
and xs:double
arguments, NaN
returns
NaN
, 0.0E0
returns -0.0E0
and vice versa.
INF
returns -INF
. -INF
returns
INF
.
The six value comparison operators eq
, ne
, lt
,
le
, gt
, and ge
are defined in terms of two
underlying functions: op:numeric-equal
and op:numeric-less-than
.
These functions are defined to operate on values of the same type.
If the arguments are of different types, one argument is promoted to the type of the other
as described above in 4.2 Arithmetic operators on numeric values. Each comparison operator returns a
boolean value. If either, or both, operands are NaN
,
false
is returned.
Function | Meaning |
---|---|
op:numeric-equal |
Returns true if and only if the value of $arg1 is equal to the value of
$arg2 . |
op:numeric-less-than |
Returns true if and only if $arg1 is numerically less than
$arg2 . |
Returns true
if and only if the value of $arg1
is equal to the value of
$arg2
.
Defines the semantics of
the eq
operator when applied to two numeric values, and is also used in defining the
semantics of ne
, le
and ge
.
op:numeric-equal ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
General rules: see 4.2 Arithmetic operators on numeric values and 4.3 Comparison operators on numeric values.
For xs:float
and xs:double
values, positive zero and negative
zero compare equal. INF
equals INF
and -INF
equals -INF
. If $arg1
or $arg2
is
NaN
, the function returns false
.
Returns true
if and only if $arg1
is numerically less than
$arg2
.
Defines the semantics of the
lt
operator when applied to two numeric values, and is also used in defining the
semantics of le
, gt
, and ge
.
op:numeric-less-than ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
General rules: see 4.2 Arithmetic operators on numeric values and 4.3 Comparison operators on numeric values.
For xs:float
and xs:double
values, positive infinity is
greater than all other non-NaN
values; negative infinity is less than all
other non-NaN
values. Positive and negative zero compare equal.
If $arg1
or $arg2
is
NaN
, the function returns false
.
The following functions are defined on numeric types. Each function returns a value of the same type as the type of its argument.
If the argument is the empty sequence, the empty sequence is returned.
For xs:float
and xs:double
arguments, if the
argument is NaN
, NaN
is returned.
With the exception of fn:abs
, functions with arguments of
type xs:float
and xs:double
that are positive or
negative infinity return positive or negative infinity.
Function | Meaning |
---|---|
fn:abs |
Returns the absolute value of $value . |
fn:ceiling |
Rounds $value upwards to a whole number. |
fn:floor |
Rounds $value downwards to a whole number. |
fn:round |
Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near. |
fn: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. |
fn:is-NaN |
Returns true if the argument is the xs:float or xs:double value NaN . |
Note:
fn:round
and fn:round-half-to-even
produce the same result in all cases
except when the argument is exactly midway between two values with the required precision.
Other ways of rounding midway values can be achieved as follows:
Towards negative infinity: -fn:round(-$x)
Away from zero: fn:round(fn:abs($x))*fn:compare($x,0)
Towards zero: fn:abs(fn:round(-$x))*-fn:compare($x,0)
Returns the absolute value of $value
.
fn:abs ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
General rules: see 4.4 Functions on numeric values.
If $value
is negative the function returns -$value
, otherwise it
returns $value
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example, if
$value
is an instance of xs:positiveInteger
then the value of
$value
may be returned unchanged.
For xs:float
and xs:double
arguments, if the argument is
positive zero or negative zero, then positive zero is returned. If the argument is
positive or negative infinity, positive infinity is returned.
Expression | Result |
---|---|
|
|
|
|
|
|
Rounds $value
upwards to a whole number.
fn:ceiling ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
General rules: see 4.4 Functions on numeric values.
The function returns the smallest (closest to negative infinity) number with no
fractional part that is not less than $value
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example, if
$value
is an instance of xs:decimal
then the result may
be an instance of xs:integer
.
For xs:float
and xs:double
arguments, if the argument is
positive zero, then positive zero is returned. If the argument is negative zero, then
negative zero is returned. If the argument is less than zero and greater than -1,
negative zero is returned. If the argument is positive or negative infinity,
the value of the argument is returned.
Expression | Result |
---|---|
|
|
|
|
|
|
Rounds $value
downwards to a whole number.
fn:floor ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
General rules: see 4.4 Functions on numeric values.
The function returns the largest (closest to positive infinity) number with no
fractional part that is not greater than $value
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example, if
$value
is an instance of xs:decimal
then the result may
be an instance of xs:integer
.
For xs:float
and xs:double
arguments, if the argument is
positive zero, then positive zero is returned. If the argument is negative zero, then
negative zero is returned. If the argument is positive or negative infinity,
the value of the argument is returned.
Expression | Result |
---|---|
|
|
|
|
|
|
Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near.
fn:round ( |
||
$value |
as , |
|
$precision |
as
|
:= 0 |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
General rules: see 4.4 Functions on numeric values.
The function returns the nearest (that is, numerically closest) value to
$value
that is a multiple of ten to the power of minus
$precision
. If two such values are equally near (for example, if the
fractional part in $value
is exactly .5), the function returns the one that
is closest to positive infinity.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example, if
$value
is an instance of xs:decimal
and $precision
is
less than one, then the result may
be an instance of xs:integer
.
The single-argument version of this function produces the same result as the
two-argument version with $precision=0
(that is, it rounds to a whole
number).
When $value
is of type xs:float
and xs:double
:
If $value
is NaN
, positive or negative zero, or positive or negative
infinity, then the result is the same as the argument.
For other values, the argument is cast to xs:decimal
using an
implementation of xs:decimal
that imposes no limits on the number of
digits that can be represented. The function is applied to this
xs:decimal
value, and the resulting xs:decimal
is
cast back to xs:float
or xs:double
as appropriate to
form the function result. If the resulting xs:decimal
value is zero,
then positive or negative zero is returned according to the sign of
$value
.
This function is typically used with a 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
.
Expression | Result |
---|---|
|
|
|
|
|
(Not the possible alternative, |
|
|
|
|
|
|
|
|
Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near.
fn:round-half-to-even ( |
||
$value |
as , |
|
$precision |
as
|
:= 0 |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
General rules: see 4.4 Functions on numeric values.
The function returns the nearest (that is, numerically closest) value to
$value
that is a multiple of ten to the power of minus
$precision
. If two such values are equally near (e.g. if the fractional
part in $value
is exactly .500...), the function returns the one whose least
significant digit is even.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example, if
$value
is an instance of xs:decimal
and $precision
is less than one, then the result may
be an instance of xs:integer
.
The one-argument form of this function produces the same result as the two-argument form
with $precision=0
.
For arguments of type xs:float
and xs:double
:
If the argument is NaN
, positive or negative zero, or positive or
negative infinity, then the result is the same as the argument.
In all other cases, the argument is cast to xs:decimal
using an
implementation of xs:decimal
that imposes no limits on the number of digits that
can be represented. The function is applied to this xs:decimal
value,
and the resulting xs:decimal
is cast back to xs:float
or
xs:double
as appropriate to form the function result. If the
resulting xs:decimal
value is zero, then positive or negative zero is
returned according to the sign of the original argument.
This function is typically used in financial applications where the argument is of type
xs:decimal
. For arguments of type xs:float
and
xs:double
the results may be 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
.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Returns true
if the argument is the xs:float
or xs:double
value NaN
.
fn:is-NaN ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns true
if the argument is the xs:float
or xs:double
value NaN
;
otherwise it returns false
.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
New in 4.0. Accepted 2022-09-20.
It is possible to convert strings to values of type xs:integer
,
xs:float
, xs:decimal
, or xs:double
using the constructor functions described in 20 Constructor functions
or using cast
expressions as described in 21 Casting.
In addition the fn:number
function is available to convert strings
to values of type xs:double
. It differs from the xs:double
constructor function in that any value outside the lexical space of the xs:double
datatype is converted to the xs:double
value NaN
.
Function | Meaning |
---|---|
fn:number |
Returns the value indicated by $value or, if $value is not
specified, the context item 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 item after atomization, converted to an xs:double
.
fn:number ( |
||
$value |
as
|
:= . |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Calling the zero-argument version of the function is defined to give the same result as
calling the single-argument version with the context item (.
). That is,
fn:number()
is equivalent to fn:number(.)
, as defined by
the rules that follow.
If $value
is the empty sequence or if $value
cannot be converted
to an xs:double
, the xs:double
value NaN
is
returned.
Otherwise, $value
is converted to an xs:double
following the
rules of 21.1.2.2 Casting to xs:double. If the conversion to xs:double
fails, the xs:double
value NaN
is returned.
A dynamic error is raised [err:XPDY0002]XP
if $value
is omitted and the context item is absentDM40.
As a consequence of the rules given above, a type error occurs if the context item cannot be atomized, or if the result of atomizing the context item is a sequence containing more than one atomic value.
XSD 1.1 allows the string +INF
as a representation of positive infinity;
XSD 1.0 does not. It is ·implementation-defined· whether XSD 1.1 is
supported.
Generally fn:number
returns NaN
rather than raising a dynamic
error if the argument cannot be converted to xs:double
. However, a type
error is raised in the usual way if the supplied argument cannot be atomized or if the
result of atomization does not match the required argument type.
Expression | Result |
---|---|
|
|
|
|
Assume that the context item is the |
Converts a string to an integer, recognizing any radix in the range 2 to 36.
fn:parse-integer ( |
||
$value |
as , |
|
$radix |
as
|
:= 10 |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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. More formally, in non-error cases the result of the function is given by the XQuery expression:
let $alphabet := characters("0123456789abcdefghijklmnopqrstuvwxyz") let $preprocessed-value := translate($value, "_ 	

", "") let $digits := translate($preprocessed-value, "+-", "") let $abs := sum( for $char at $p in reverse(characters($digits)) return (index-of($alphabet, $char) - 1) * xs:integer(math:pow($radix, $p - 1))) return if (starts-with($preprocessed-value, "-")) then -$abs else +$abs
A dynamic error is raised [err:FORG0011]
if $radix
is not in the range 2 to 36.
A dynamic error is raised [err:FORG0012]
if, after stripping whitespace and underscores and the optional leading sign,
$value
is a 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 [err:FOCA0003]
if the value of the resulting integer exceeds the implementation-dependent
limit on the size of an xs:integer
.
When $radix
takes its default value of 10
,
the function delivers the same result as casting $value
(after removal of whitespace and underscores) to xs:integer
.
If underscores or whitespace in the input need to be rejected, then
the string should first be validated, perhaps using fn:matches
.
If other characters may legitimately appear in the input, for example
a leading 0x
, then this must first be removed by 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 fn:translate
.
A string in the lexical space of xs:hexBinary
will always
be an acceptable input, provided it is not too long. So, for example, the expression
"1DE=" => xs:base64Binary() => xs:hexBinary() => xs:string() => parse-integer(16)
can be used to convert the Base 64 value 1DE=
to the integer 54321, via the
hexadecimal string D431
.
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. |
|
lower-case("AAB") => translate("abcdefghijklmnopqrstuvwxyz", "0123456789abcdefghijklmnop") => parse-integer(26) |
|
Digit-based numeration systems comparable to the Arabic numbers 0 through 9 can be parsed via translation. |
|
translate('٢٠٢٣', '٠١٢٣٤٥٦٧٨٩', '0123456789') => parse-integer() |
|
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.
fn:format-integer ( |
||
$value |
as , |
|
$picture |
as , |
|
$language |
as
|
:= () |
) as
|
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default language.
The three-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is an 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 "4451"
.
This rule is to ensure backwards compatibility.
A primary format token. This is always present and must not be zero-length.
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 #
.
If the radix is absent, then
a mandatory-digit-sign is a ·character· in Unicode category Nd. All
mandatory-digit-signs within the format token
must be from the same digit family, where a digit
family is a sequence of ten consecutive characters in Unicode category Nd,
having digit values 0
through 9
.
Within the format token, these digits are
interchangeable: a 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 must match the
regular expression ^((\p{Nd}|#|[^\p{N}\p{L}])+?)$
. If it contains a
digit but does not match this pattern, a dynamic error is raised [err:FODF1310].
If the radix (call it R) is
present (including the case where an explicit radix of 10 is used), then
the character used as the mandatory-digit-sign is either "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 must match the
regular expression ^(([Xx#]|[^\p{N}\p{L}])+?)$
a grouping-separator-sign is a non-alphanumeric character, that is a ·character· whose Unicode category is other than Nd, Nl, No, Lu, Ll, Lt, Lm or Lo.
Note:
If a semicolon is to be used as a grouping separator, then the primary format token as a whole must be followed by another semicolon, to ensure that the grouping separator is not mistaken as a separator between the primary format token and the format modifier.
There must be at least one mandatory-digit-sign. There may be zero or more optional-digit-signs, and (if present) these must precede all mandatory-digit-signs. There may be zero or more grouping-separator-signs. A grouping-separator-sign must not appear at the start or end of the digit-pattern, nor adjacent to another grouping-separator-sign.
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 ١
(Arabic-Indic digit one) generates the sequence ١
then ٢
then ٣
...
A format token of 16^xx
generates the sequence 00 01 02 03
... 08 09 0a 0b 0c 0d 0e 0f 10 11 ...
A format token of 16^X
generates the sequence 0 1 2 3
... 8 9 A B C D E F 10 11 ...
The 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 position of a grouping separator is the number of optional-digit-signs and mandatory-digit-signs appearing between the grouping separator and the right-hand end of the primary format token.
Grouping separators are defined to be regular if the following conditions apply:
There is at least one grouping separator.
Every grouping separator is the same character (call it C).
There is a positive integer G (the grouping size) such that:
The position of every grouping separator is an integer multiple of G, and
Every positive integer multiple of G that is less than the number of optional-digit-signs and mandatory-digit-signs in the primary format token is the position of a grouping separator.
The grouping separator template is a (possibly infinite) set of (position, character) pairs.
If grouping separators are regular, then the grouping separator template contains one pair of the form (n×G, C)
for every positive integer n where G is the grouping size and C is the grouping character.
Otherwise (when grouping separators are not regular), the grouping separator template contains one pair of the form
(P, C)
for every grouping separator found in the primary formatting token, where C is the grouping
separator character and P is its position.
Note:
If there are no grouping separators, then the grouping separator template is an empty set.
The number is formatted as follows:
Let S1 be the result of formatting the supplied number
in the appropriate radix:
for radix 10 this will be the value obtained by casting
it to xs:string
.
Let S2 be the result of padding S1 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 S3 be the result of replacing all decimal digits (0-9) in S2 with the corresponding digits from the selected digit family. (This has no effect when the selected digit family uses ASCII digits (0-9), which will always be the case if a radix is specified.)
Let S4 be the result of inserting grouping separators into S3: for every (position P, character C) pair in the grouping separator template where P is less than the number of digits in S3, insert character C into S3 at position P, counting from the right-hand end.
Let S5 be the result of converting S4 into ordinal form, if an ordinal modifier is present, as described below.
The result of the function is then S5.
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 ·implementation-defined· which
numbering sequences, additional to those listed above, are supported. If an
implementation does not support a numbering sequence represented by the given
token, it must use a format token of 1
.
Note:
In some traditional numbering sequences additional signs are added to denote that the letters should be interpreted as numbers, for example, in ancient Greek the dexia keraia (x0374, ʹ) and sometimes the aristeri keraia (x0375, ͵). These should not be included in the format token.
For all format tokens other than a digit-pattern, there
may be ·implementation-defined· lower and upper bounds on the range of numbers that
can be formatted using this format token; indeed, for some numbering sequences there may
be intrinsic limits. For example, the format token ①
(circled
digit one, ①) has a range imposed by the Unicode character repertoire — zero to 20
in Unicode versions prior to 3.2, or zero to 50 in subsequent versions. For the numbering
sequences described above any upper bound imposed by the implementation must
not be less than 1000 (one thousand) and any lower bound must not be
greater than 1. Numbers that fall outside this range must be
formatted using the format token 1
.
The above expansions of numbering sequences for format tokens such as a
and
i
are indicative but not prescriptive. There are various conventions in
use for how alphabetic sequences continue when the alphabet is exhausted, and differing
conventions for how roman numerals are written (for example, IV
versus
IIII
as the representation of the number 4). Sometimes alphabetic
sequences are used that omit letters such as i
and o
. This
specification does not prescribe the detail of any sequence other than those sequences
consisting entirely of decimal digits.
Many numbering sequences are 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 #x410 (Cyrillic
capital letter A). In such cases, the $language
argument specifies which
language conventions are to be used. If the argument is specified, the value
should be either an empty sequence or a value that would be valid
for the xml:lang
attribute (see [Extensible Markup Language (XML) 1.0 (Fifth Edition)]). Note that this
permits the identification of sublanguages based on country codes (from ISO 3166-1) as
well as identification of dialects and regions within a country.
The set of languages for which numbering is supported is ·implementation-defined·. If the $language
argument is absent, or is
set to an empty sequence, or is invalid, or is not a language supported by the
implementation, then the number is formatted using the default language from the dynamic
context.
The format modifier must be a string that matches the regular
expression ^([co](\(.+\))?)?[at]?$
. That is, if it is present it must
consist of one or more of the following, in order:
either c
or o
, optionally followed by a sequence of
characters enclosed between parentheses, to indicate cardinal or ordinal numbering
respectively, the default being cardinal numbering
either a
or t
, to indicate alphabetic or traditional
numbering respectively, the default being ·implementation-defined·.
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 ·implementation-defined·. No error occurs if the implementation does not define any interpretation for the defined string.
It is ·implementation-defined· what combinations of values of the format token, the language, and the cardinal/ordinal modifier are supported. If ordinal numbering is not supported for the combination of the format token, the language, and the string appearing in parentheses, the request is ignored and cardinal numbers are generated instead.
The use of the a
or t
modifier disambiguates between numbering
sequences that use letters. In many languages there are two commonly used numbering
sequences that use letters. One numbering sequence assigns numeric values to letters in
alphabetic sequence, and the other assigns numeric values to each letter in some other
manner traditional in that language. In English, these would correspond to the numbering
sequences specified by the format tokens a
and i
. In some
languages, the first member of each sequence is the same, and so the format token alone
would be ambiguous. In the absence of the a
or t
modifier, the
default is ·implementation-defined·.
A dynamic error is raised [err:FODF1310] if the format token is invalid, that is, if it violates any mandatory rules (indicated by an emphasized must or required keyword in the above rules). For example, the error is raised if the primary format token contains a digit but does not match the required regular expression.
Note the careful distinction between conditions that are errors and conditions where fallback occurs. The principle is that an error in the syntax of the format picture will be reported by all processors, while a construct that is recognized by some implementations but not others will never result in an error, but will instead cause a fallback representation of the integer to be used.
The following notes apply when a 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 not designed for effects such as
formatting a US telephone number as (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 [ICU], or any other library making use of the
Unicode Common Locale Data Repository [Unicode CLDR], is to allow the value in parentheses
to be the name of a registered numbering rule set for the language in question,
conventionally prefixed with a percent sign: for example,
o(%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, #x3C4 τ
, but the implementation might return the eighteenth one,
#x3C3 σ
, because the latter is the nineteenth item in the sequence of
lowercase Greek letters in Unicode (the sequence is interrupted because of the final
form of the sigma, #x3C2 ς). Because Greek never had a final capital sigma,
Unicode has marked #x3A2, the eighteenth codepoint in the sequence of Greek capital
letters, as reserved, to ensure that every Greek uppercase letter is always 32 codepoints
less than its lowercase counterpart. Therefore, someone writing
format-integer(18, "Α;a")
might expect the eighteenth Greek capital letter,
#x3A3 Σ
, but an implementation might return #x3a2, the eighteenth position
in the sequence of Greek capital letters, but unassigned to any character.
Expression | Result |
---|---|
|
|
|
|
Ordinal numbering in Italian: The specification |
|
1º 2º 3º 4º ... |
|
The specification |
|
Primo Secondo Terzo Quarto Quinto ... |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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, taking account of decimal formats specified in the static context. |
Note:
This function can be used to format any numeric quantity, including an integer. For integers, however,
the fn:format-integer
function offers additional possibilities. Note also that the picture
strings used by the two functions are not 100% compatible, though they share some options in common.
Decimal formats are defined in the static context, and the way they are defined is therefore outside the scope of this specification. XSLT and XQuery both provide custom syntax for creating a decimal format.
The static context provides a set of decimal formats. One of the decimal formats is unnamed, the others (if any) are identified by a QName. There is always an unnamed decimal format available, but its contents are ·implementation-defined·.
Each decimal format provides a set of named properties, described in the following table:
Name | Type | Usage (non-normative) |
---|---|---|
decimal-separator |
A single ·character· | Defines the character used to represent the decimal point (typically . ) both in the picture string and in the formatted number. |
grouping-separator |
A single ·character· | Defines the character used to separate groups of digits (typically , ) both in the picture string and in the formatted number. |
exponent-separator |
A single ·character· | Defines the character used to separate the mantissa from the exponent
in scientific notation (typically e ) both in the picture string and in the formatted number. |
infinity |
A ·string· | Defines the string used to represent the value positive or negative infinity in the
formatted number (typically Infinity ) |
minus-sign |
A single ·character· | Defines the character used as a minus sign in the formatted number if there is no
subpicture for formatting negative numbers (typically - , x2D) |
NaN |
A ·string· | Defines the string used to represent the value NaN in the formatted number |
percent |
A single ·character· | Defines the character used as a percent sign (typically % ) both in the picture string and in the formatted number |
per-mille |
A single ·character· | Defines the character used as a per-mille sign (typically ‰ , x2030) both in the picture string and in the formatted number |
zero-digit |
A single ·character·, which must be a character in Unicode category Nd with decimal digit value 0 (zero) | 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. |
digit |
A single ·character· | Defines the character used in the picture string to represent an optional digit (typically
# ) |
pattern-separator |
A single ·character· | Defines the character used in the picture string to separate the positive and negative
subpictures (typically ; ) |
Note:
A phrase such as "The minus-signXP31 character" is to be read as “the character assigned to the minus-signXP31 property in the relevant decimal format within the static context”.
[Definition] The decimal digit family of a decimal format is the sequence of ten digits with consecutive Unicode ·codepoints· starting with the character that is the value of the zero-digitXP31 property.
[Definition] The optional digit character is the character that is the value of the digitXP31 property.
For any named or unnamed decimal format, the properties representing characters used in a ·picture string· must have distinct values. These properties are decimal-separatorXP31 , grouping-separatorXP31, exponent-separatorXP31, percentXP31, per-milleXP31, digitXP31, and pattern-separatorXP31. Furthermore, none of these properties may be equal to any ·character· in the ·decimal digit family·.
Returns a string containing a number formatted according to a given picture string, taking account of decimal formats specified in the static context.
fn:format-number ( |
||
$value |
as , |
|
$picture |
as , |
|
$decimal-format-name |
as
|
:= () |
) as
|
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on decimal formats, and namespaces.
The effect of the two-argument form of the function is equivalent to calling the three-argument form with an empty sequence as the value of the third argument.
The function formats $value
as a string using the ·picture string· specified by the
$picture
argument and the decimal-format named by the
$decimal-format-name
argument, or the unnamed decimal-format, if there
is no $decimal-format-name
argument. The syntax of the picture string is
described in 4.7.3 Syntax of the picture string.
The $value
argument may be of any numeric data type
(xs:double
, xs:float
, xs:decimal
, or their
subtypes including xs:integer
). Note that if an xs:decimal
is
supplied, it is not automatically promoted to an xs:double
, as such
promotion can involve a loss of precision.
If the supplied value of the $value
argument is an empty sequence, the
function behaves as if the supplied value were the xs:double
value
NaN
.
The value of $decimal-format-name
, if present and non-empty,
must be either an xs:QName
,
or a string which after removal of leading and trailing
whitespace is in the form of an EQName
as defined in the XPath 4.0
grammar, that is one of the following:
A lexical QName, which is expanded using the statically known namespaces. The default namespace is not used (no prefix means no namespace).
A URIQualifiedName
using the syntax Q{uri}local
, where
the URI can be zero-length to indicate a name in no namespace.
The decimal format that is used is the decimal format in the static context whose name
matches $decimal-format-name
if supplied, or the unnamed decimal format in
the static context otherwise.
The evaluation of the fn:format-number
function takes place in two
phases, an analysis phase described in 4.7.4 Analyzing the picture string and a
formatting phase described in 4.7.5 Formatting the number.
The analysis phase takes as its inputs the ·picture string· and the variables derived from the relevant decimal format in the static context, and produces as its output a number of variables with defined values. The formatting phase takes as its inputs the number to be formatted and the variables produced by the analysis phase, and produces as its output a string containing a formatted representation of the number.
The result of the function is the formatted string representation of the supplied number.
A dynamic error is raised [err:FODF1280]
if
the $decimal-format-name
argument is supplied as an xs:string
that is neither a valid lexical QName nor a
valid URIQualifiedName
, or if it uses a prefix that is not found in the
statically known namespaces, or if the static context does not contain a declaration of
a decimal-format with a matching expanded QName. If the processor is able to detect the
error statically (for example, when the argument is supplied as a string literal), then
the processor may optionally signal this as a static error.
A 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.
Expression | Result |
---|---|
The following examples assume a default decimal format in which the chosen digits are
the ASCII digits 0-9, the decimal separator is |
|
|
|
|
|
|
|
|
|
|
|
The following example assumes the existence of a decimal format named |
|
format-number( 1234.5678, '#ʹ##0·00', 'ch' ) |
|
The following examples assume that the exponent separator is
in decimal format |
|
|
|
|
|
|
|
|
|
The decimal format name can now be supplied as a value of type xs:QName
,
as an alternative to supplying a lexical QName as an instance of xs:string
.
Note:
This differs from the 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
).
[Definition] The formatting of a number is controlled by a picture string. The picture string is a sequence of ·characters·, in which the characters assigned to the properties decimal-separatorXP31 , exponent-separatorXP31, grouping-separatorXP31, and digitXP31, and pattern-separatorXP31 and the members of the ·decimal digit family·, are classified as active characters, and all other characters (including the values of the properties percentXP31 and per-milleXP31) are classified as passive characters.
A dynamic error is raised [err:FODF1310] if the ·picture string· does not conform to the following rules. Note that in these rules the words "preceded" and "followed" refer to characters anywhere in the string, they are not to be read as "immediately preceded" and "immediately followed".
A picture-string consists either of a sub-picture, or of two sub-pictures separated by the pattern-separatorXP31 character. A picture-string must not contain more than one instance of the pattern-separatorXP31 character. If the picture-string contains two sub-pictures, the first is used for positive and unsigned zero values and the second for negative values.
A sub-picture must not contain more than one instance of the decimal-separatorXP31 character.
A sub-picture must not contain more than one instance of the percentXP31 or per-milleXP31 characters, and it must not contain one of each.
The mantissa part of a sub-picture (defined below) must contain at least one character that is either an ·optional digit character· or a member of the ·decimal digit family·.
A sub-picture must not contain a passive character that is preceded by an active character and that is followed by another active character.
A sub-picture must not contain a grouping-separatorXP31 character that appears adjacent to a decimal-separatorXP31 character, or in the absence of a decimal-separatorXP31 character, at the end of the integer part.
A sub-picture must not contain two adjacent instances of the grouping-separatorXP31 character.
The integer part of a sub-picture (defined below) must not contain a member of the ·decimal digit family· that is followed by an instance of the ·optional digit character·. The fractional part of a sub-picture (defined below) must not contain an instance of the ·optional digit character· that is followed by a member of the ·decimal digit family·.
A character that matches the exponent-separatorXP31 property is treated as an exponent-separator-sign if it is both preceded and followed within the sub-picture by an active character. Otherwise, it is treated as a passive character. A sub-picture must not contain more than one character that is treated as an exponent-separator-sign.
A sub-picture that contains a percentXP31 or per-milleXP31 character must not contain a character treated as an exponent-separator-sign.
If a sub-picture contains a character treated as an exponent-separator-sign then this must be followed by one or more characters that are members of the ·decimal digit family·, and it must not be followed by any active character that is not a member of the ·decimal digit family·.
The mantissa part of the 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 decimal-separatorXP31 character if there is one, or the entire mantissa part otherwise.
The fractional part of the sub-picture is defined as that part of the mantissa part that appears to the right of the decimal-separatorXP31 character if there is one, or the part that appears to the right of the rightmost active character otherwise. The fractional part may be zero-length.
This phase of the algorithm analyzes the ·picture string· and the properties from the selected decimal format in the static context, and it has the effect of setting the values of various variables, which are used in the subsequent formatting phase. These variables are listed below. Each is shown with its initial setting and its datatype.
Several variables are associated with each 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 grouping-separatorXP31 character that appears within the integer part of the sub-picture, this sequence contains an integer that is equal to the total number of ·optional digit character· and ·decimal digit family· characters that appear within the integer part of the sub-picture and to the right of the grouping-separatorXP31 character.
The grouping is defined to be regular if the following conditions apply:
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 ·decimal digit family· characters found in the integer part of the sub-picture, but may be adjusted as described below.
Note:
There is no maximum integer part size. All significant digits in the integer part of the number will be displayed, even if this exceeds the number of ·optional digit character· and ·decimal digit family· characters in the subpicture.
The scaling factor is a non-negative integer used to determine the scaling of the mantissa in exponential notation. It is set to the number of ·decimal digit family· characters found in the integer part of the sub-picture.
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 minus-signXP31 character and the prefix for the positive sub-picture (if any), in that order.
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 grouping-separatorXP31 character that appears within the fractional part of the sub-picture, this sequence contains an integer that is equal to the total number of ·optional digit character· and ·decimal digit family· characters that appear within the fractional part of the sub-picture and to the left of the grouping-separatorXP31 character.
Note:
There is no need to extrapolate grouping positions on the fractional side, because the number of digits in the output will never exceed the number of ·optional digit character· and ·decimal digit family· characters in the fractional part of the sub-picture.
The minimum-fractional-part-size is set to the number of ·decimal digit family· characters found in the fractional part of the sub-picture.
The maximum-fractional-part-size is set to the total number of ·optional digit character· and ·decimal digit family· characters found in the fractional part of the sub-picture.
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).
Note:
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).
Note:
This has the effect that with the picture #
, the value 0.23
is formatted
as 0
If all the following conditions are true:
An exponent separator is present
The minimum-integer-part-size is zero
There is at least one ·optional digit character· in the integer part of the sub-picture
then the minimum-integer-part-size is changed to 1 (one).
Note:
This has the effect that with the picture .9e9
, the value 0.1
is formatted
as .1e0
, while with the picture #.9e9
, it is formatted as 0.1e0
If (after making the above adjustments) the 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 ·decimal digit family· characters found in the exponent part of the sub-picture if present, or zero otherwise.
Note:
The rules for the syntax of the picture string ensure that if an exponent separator is present, then the 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.
Note:
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 minus-signXP31 character.
This section describes the second phase of processing of the
fn:format-number
function. This phase takes as input a number to be formatted
(referred to as the input number), and the variables set up by
analyzing the decimal format in the static context and the
·picture string·, as described above.
The result of this phase is a string, which forms the return value of
the fn:format-number
function.
The algorithm for this second stage of processing is as follows:
If the input number is NaN
(not a number), the result is the
value of the pattern separatorXP31 property (with no
prefix or suffix).
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 percentXP31 character, the adjusted number is the input number multiplied by 100.
If the sub-picture contains a per-milleXP31 character, the adjusted number is the input number multiplied by 1000.
Otherwise, the adjusted number is the input number.
If the multiplication causes numeric overflow, no error occurs, and the adjusted number is positive or negative infinity as appropriate.
If the adjusted number is positive or negative infinity, the result is the concatenation of the appropriate prefix, the value of the infinityXP31 property, and the appropriate suffix.
If the minimum exponent size is non-zero, and the adjusted number is non-zero, then the adjusted number is scaled to establish a mantissa and an integer exponent. The mantissa and exponent are chosen such that all the following conditions are true:
The primitive type of the mantissa is the same as the primitive type of the adjusted number (integer, decimal, float, or double).
The mantissa multiplied by ten to the power of the exponent is equal to the adjusted number.
The mantissa (unless it is zero) is less than 10N, and at least 10N-1, where N is the scaling factor.
If the minimum exponent size is zero, then the mantissa is the adjusted number and there is no exponent.
If the minimum exponent size is non-zero and the adjusted number is zero, then the mantissa is the adjusted number and the exponent is zero.
The mantissa is converted (if necessary) to
an xs:decimal
value,
using an implementation of xs:decimal
that imposes no limits on the
totalDigits
or fractionDigits
facets. If there are several
such values that
are numerically equal to the mantissa (bearing in mind that if the
mantissa is an xs:double
or xs:float
, the comparison will be done by
converting the decimal value back to an xs:double
or xs:float
), the one that
is chosen should be one with the smallest possible number of digits
not counting leading or trailing zeroes (whether significant or insignificant).
For example, 1.0 is preferred to
0.9999999999, and 100000000 is preferred to 100000001. This value is then
rounded so that it uses no more than maximum-fractional-part-size
digits in
its fractional part. The rounded number is defined to be the result of
converting the mantissa to an xs:decimal
value, as described above,
and then calling the function fn:round-half-to-even
with this converted number
as the first argument and the 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 ·decimal digit family· to represent the ten decimal digits, and the decimal-separatorXP31 character to separate the integer part and the fractional part. This string must always contain a decimal-separatorXP31, and it must contain no leading zeroes and no trailing zeroes. The value zero will at this stage be represented by a decimal-separatorXP31 on its own.
If the number of digits to the left of the decimal-separatorXP31 character is less than minimum-integer-part-size, leading zero digitXP31 characters are added to pad out to that size.
If the number of digits to the right of the decimal-separatorXP31 character is less than minimum-fractional-part-size, trailing zero digitXP31 characters are added to pad out to that size.
For each integer N in the integer-part-grouping-positions list, a grouping-separatorXP31 character is inserted into the string immediately after that digit that appears in the integer part of the number and has N digits between it and the decimal-separatorXP31 character, if there is such a digit.
For each integer N in the fractional-part-grouping-positions list, a grouping-separatorXP31 character is inserted into the string immediately before that digit that appears in the fractional part of the number and has N digits between it and the decimal-separatorXP31 character, if there is such a digit.
If there is no decimal-separatorXP31 character in the sub-picture, or if there are no digits to the right of the decimal-separator character in the string, then the decimal-separator character is removed from the string (it will be the rightmost character in the string).
If an exponent exists, then the string produced from the mantissa as described above is extended with the following, in order: (a) the exponent-separatorXP31 character; (b) if the exponent is negative, the minus-signXP31 character; (c) the value of the exponent represented as a decimal integer, extended if necessary with leading zeroes to make it up to the minimum exponent size, using digits taken from the ·decimal digit family·.
The result of the function is the concatenation of the appropriate prefix, the string conversion of the number as obtained above, and the appropriate suffix.
The functions in this section perform trigonometric and other mathematical calculations on xs:double
values. They
are provided primarily for use in applications performing geometrical computation, for example when generating
SVG graphics.
Functions are provided to support the six most commonly used trigonometric calculations: sine, cosine and tangent, and their inverses arc sine, arc cosine, and arc tangent. Other functions such as secant, cosecant, and cotangent are not provided because they are easily computed in terms of these six.
The functions in this section (with the exception of math:pi
)
are specified by reference to [IEEE 754-2008], where
they appear as Recommended operations in section 9. IEEE defines
these functions for a variety of floating point formats; this specification
defines them only for xs:double
values. The IEEE specification
applies with the following caveats:
IEEE states that the preferred quantum is language-defined. In this specification, it is ·implementation-defined·.
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 ·implementation-defined·.
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 4.2 Arithmetic operators on numeric values.
Function | Meaning |
---|---|
math:pi |
Returns an approximation to the mathematical constant π. |
math:exp |
Returns the value of ex where x is the argument value. |
math:exp10 |
Returns the value of 10 x, where x is the supplied argument value. |
math:log |
Returns the natural logarithm of the argument. |
math:log10 |
Returns the base-ten logarithm of the argument. |
math:pow |
Returns the result of raising the first argument to the power of the second. |
math:sqrt |
Returns the non-negative square root of the argument. |
math:sin |
Returns the sine of the argument. The argument is an angle in radians. |
math:cos |
Returns the cosine of the argument. The argument is an angle in radians. |
math:tan |
Returns the tangent of the argument. The argument is an angle in radians. |
math:asin |
Returns the arc sine of the argument. |
math:acos |
Returns the arc cosine of the argument. |
math:atan |
Returns the arc tangent of the argument. |
math:atan2 |
Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive x-axis. |
Returns an approximation to the mathematical constant π.
math:pi () as xs:double |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
This function returns the xs:double
value whose lexical representation is
3.141592653589793e0
Expression | Result |
---|---|
|
|
The expression |
Returns the value of ex where x is the argument value.
math:exp ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the mathematical constant e raised to the power of
$value
, as defined in the [IEEE 754-2008] specification of
the exp
function applied to 64-bit binary floating point values.
The treatment of overflow and underflow is defined in 4.2 Arithmetic operators on numeric values.
Expression | Result |
---|---|
|
|
|
|
|
(approximately) |
|
|
|
|
|
|
|
|
|
|
|
|
Returns the value of 10
x, where x is the supplied argument value.
math:exp10 ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is ten raised to the power of $value
, as defined in the
[IEEE 754-2008] specification of the exp10
function applied
to 64-bit binary floating point values.
The treatment of overflow and underflow is defined in 4.2 Arithmetic operators on numeric values.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Returns the natural logarithm of the argument.
math:log ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the natural logarithm of $value
, as defined in the
[IEEE 754-2008] specification of the log
function applied
to 64-bit binary floating point values.
The treatment of divideByZero
and invalidOperation
exceptions
is defined in 4.2 Arithmetic operators on numeric values. The effect is that if the argument is
zero, the result is -INF
, and if it is negative, the result is NaN
.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Returns the base-ten logarithm of the argument.
math:log10 ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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
[IEEE 754-2008] specification of the log10
function applied
to 64-bit binary floating point values.
The treatment of divideByZero
and invalidOperation
exceptions
is defined in 4.2 Arithmetic operators on numeric values. The effect is that if the argument is
zero, the result is -INF
, and if it is negative, the result is NaN
.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Returns the result of raising the first argument to the power of the second.
math:pow ( |
||
$x |
as , |
|
$y |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $x
is the empty sequence, the function returns the empty sequence.
If $y
is an instance of xs:integer
, the result is
$x
raised to the power of $y
as defined in the [IEEE 754-2008] specification of the pown
function applied to a
64-bit binary floating point value and an integer.
Otherwise $y
is converted to an xs:double
by numeric
promotion, and the result is $x
raised to the power of
$y
as defined in the [IEEE 754-2008] specification of the
pow
function applied to two 64-bit binary floating point values.
The treatment of the divideByZero
and invalidOperation
exceptions is defined in 4.2 Arithmetic operators on numeric values. Some of the consequences are
illustrated in the examples below.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(Odd-valued whole numbers are treated specially). |
|
|
|
|
|
|
|
(Odd-valued whole numbers are treated specially). |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Returns the non-negative square root of the argument.
math:sqrt ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 [IEEE 754-2008] specification of the
squareRoot
function applied to 64-bit binary floating point values.
The treatment of the invalidOperation
exception is defined in 4.2 Arithmetic operators on numeric values. The effect is that if the argument is less than zero, the result
is NaN
.
If $value
is positive or negative zero, positive infinity, or
NaN
, then the result is $value
. (Negative zero is the only
case where the result can have negative sign)
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Returns the sine of the argument. The argument is an angle in radians.
math:sin ( |
||
$radians |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $radians
is the empty sequence, the function returns the empty
sequence.
Otherwise the result is the sine of $radians
(which is treated as an angle in
radians) as defined in the [IEEE 754-2008] specification of the
sin
function applied to 64-bit binary floating point values.
The treatment of the invalidOperation
and underflow
exceptions
is defined in 4.2 Arithmetic operators on numeric values.
If $radians
is positive or negative zero, the result is
$radians
.
If $radians
is positive or negative infinity, or NaN
,
then the result is NaN
.
Otherwise the result is always in the range -1.0e0 to +1.0e0
Expression | Result |
---|---|
|
|
|
|
|
|
|
(approximately) |
|
(approximately) |
|
(approximately) |
|
|
|
|
|
|
Returns the cosine of the argument. The argument is an angle in radians.
math:cos ( |
||
$radians |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $radians
is the empty sequence, the function returns the empty
sequence.
If $radians
is positive or negative infinity, or NaN
,
then the result is NaN
.
Otherwise the result is the cosine of $
θ (which is treated as an angle in
radians) as defined in the [IEEE 754-2008] specification of the
cos
function applied to 64-bit binary floating point values.
The treatment of the invalidOperation
exception is defined in 4.2 Arithmetic operators on numeric values.
If $radians
is positive or negative zero, the result is
$radians
.
If $radians
is positive or negative infinity, or NaN
,
then the result is NaN
.
Otherwise the result is always in the range -1.0e0 to +1.0e0
Expression | Result |
---|---|
|
|
|
|
|
|
|
(approximately) |
|
(approximately) |
|
(approximately) |
|
|
|
|
|
|
Returns the tangent of the argument. The argument is an angle in radians.
math:tan ( |
||
$radians |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $radians
is the empty sequence, the function returns the empty
sequence.
Otherwise the result is the tangent of $radians
(which is treated as an angle
in radians) as defined in the [IEEE 754-2008] specification of the
tan
function applied to 64-bit binary floating point values.
The treatment of the invalidOperation
and underflow
exceptions
is defined in 4.2 Arithmetic operators on numeric values.
If $radians
is positive or negative infinity, or NaN
,
then the result is NaN
.
Expression | Result |
---|---|
|
|
|
|
|
|
|
(approximately) |
|
(approximately) |
|
(approximately) (Mathematically, tan(π/2) is positive infinity. But because |
|
(approximately) (Mathematically, tan(-π/2) is negative infinity. But because |
|
(approximately) |
|
|
|
|
|
|
Returns the arc sine of the argument.
math:asin ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the arc sine of $value
as defined in the [IEEE 754-2008] specification of 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 4.2 Arithmetic operators on numeric values.
If $value
is positive or negative zero, the result is $value
.
If $value
is NaN
, or if its absolute value is greater than one,
then the result is NaN
.
In other cases the result is an xs:double
value representing an angle
θ in radians in the range -π/2 <=
θ <= +
π/2
.
Expression | Result |
---|---|
|
|
|
|
|
|
|
(approximately) |
|
(approximately) |
|
|
|
|
|
|
|
|
Returns the arc cosine of the argument.
math:acos ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the arc cosine of $value
, as defined in the [IEEE 754-2008] specification of 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 4.2 Arithmetic operators on numeric values.
If $value
is NaN
, or if its absolute value is greater than one,
then the result is NaN
.
In other cases the result is an xs:double
value representing an angle
θ in radians in the range 0 <=
θ <=
+
π.
Expression | Result |
---|---|
|
|
|
(approximately) |
|
(approximately) |
|
|
|
(approximately) |
|
|
|
|
|
|
|
|
Returns the arc tangent of the argument.
math:atan ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the arc tangent of $value
, as defined
in the [IEEE 754-2008] specification of 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 4.2 Arithmetic operators on numeric values.
If $value
is positive or negative zero, the result is $value
.
If $value
is NaN
then the result is NaN
.
In other cases the result is an xs:double
value representing an angle
θ in radians in the range -π/2 <=
θ <= +
π/2
.
Expression | Result |
---|---|
|
|
|
|
|
|
|
(approximately) |
|
(approximately) |
|
|
|
(approximately) |
|
(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.
math:atan2 ( |
||
$y |
as , |
|
$x |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The result is the value of atan2(y, x)
as defined in the [IEEE 754-2008] specification of 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 4.2 Arithmetic operators on numeric values. The following rules apply when the values are finite and non-zero,
(subject to rules for overflow, underflow and approximation).
If either argument is NaN
then the result is NaN
.
If $x
is positive, then the value of atan2($y,
$x)
is atan($y div $x)
.
If $x
is negative, then:
If $y
is positive, then the value of atan2($y, $x)
is
atan($y div $x) +
π.
If $y
is negative, then the value of atan2($y, $x)
is
atan($y div $x) -
π.
Some results for special values of the arguments are shown in the examples below.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Function | Meaning |
---|---|
fn:random-number-generator |
Returns a random number generator, which can be used to generate sequences of random numbers. |
Returns a random number generator, which can be used to generate sequences of random numbers.
fn:random-number-generator ( |
||
$seed |
as
|
:= () |
) as random-number-generator-record |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns a random number generator. A random number generator is represented as a value of type
random-number-generator-record
, defined as follows:
random-number-generator-record : |
|
record( |
|
number |
as xs:double , |
next |
as function() as #random-number-generator-record , |
permute |
as function(item()*) as item()* , |
* |
|
) |
Note:
This type is self-referential in a way that the
current syntax for record type declarations does not allow. The
use of the type #random-number-generator-record
as the return type of the next
function is purely for expository purposes; an approximation allowed by the grammar would be
next as (function() as record(number, next, permute, *))
.
That is, the result of the function is a map containing three entries. The keys of each entry are strings:
The entry with key "number"
holds a random number; it is an xs:double
greater than or equal
to zero (0.0e0), and less than one (1.0e0).
The entry with key "next"
is a 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: () => map(xs:string, item())
non-local variable bindings: none
implementation: implementation-dependent
The entry with key "permute"
is a function with arity 1 (one), which takes an arbitrary sequence
as its argument, and returns a random permutation of that sequence.
The properties of this function are as follows:
name: absent
parameter names: "arg"
signature: (item()*) => item()*
non-local variable bindings: none
implementation: implementation-dependent
Calling the fn:random-number-generator
function with no arguments is equivalent to calling the single-argument
form of the function with an implementation-dependent seed.
Calling the fn:random-number-generator
function with an empty sequence as $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 value of any type.
Both forms of the function are ·deterministic·: calling the function twice with the same arguments, within a single ·execution scope·, produces the same results.
The value of the number
entry should be such that the distribution of numbers is uniform: for example, the probability of the
number being in the range 0.1e0 to 0.2e0 is the same as the probability of its being in the range 0.8e0 to 0.9e0.
The function returned in the permute
entry should be such that all permutations
of the supplied sequence are equally likely to be chosen.
The map returned by the fn:random-number-generator
function may contain additional entries beyond
those specified here, but it must match the type
item-type(rng)
defined above. The meaning of any additional entries
is ·implementation-defined·. To avoid conflict with any future version of this specification, the keys of any
such entries should start with an underscore character.
It is not meaningful to ask whether the functions returned in the next
and permute
functions resulting from two separate calls with the same seed are “the same function”, but the functions must be equivalent in the sense
that calling them produces the same sequence of random numbers.
The repeatability of the results of function calls in different execution scopes is outside the scope of this
specification. It is recommended that when the same seed is provided explicitly, the same random number sequence
should be delivered even in different execution scopes; while if no seed is provided, the processor should choose a seed
that is likely to be different from one execution scope to another. (The same effect can be achieved explicitly by using
fn: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.
The following example returns a random permutation of the integers in the range
|
|
The following example returns a 10% sample of the items in an input sequence |
|
The following code defines a function that can be called to produce a random sequence of |
|
declare %public function r:random-sequence($length as xs:integer) as xs:double* { r:random-sequence($length, random-number-generator()) }; declare %private function r:random-sequence($length as xs:integer, $G as record(number as xs:double, next as function(*), *)) { if ($length eq 0) then () else ($G?number, r:random-sequence($length - 1, $G?next())) }; r:random-sequence(200); |
This section specifies functions and operators on the [XML Schema Part 2: Datatypes Second Edition]
xs:string
datatype and the datatypes derived from it.
The operators described in this section are defined on the following types.
string
normalizedString
token
language
NMTOKEN
Name
NCName
ENTITY
ID
IDREF
Legend:
Supertype
subtype
Built-in atomic 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 ·codepoints·. |
fn:string-to-codepoints |
Returns the sequence of ·codepoints· that constitute an
xs:string value. |
Returns an xs:string
whose characters have supplied ·codepoints·.
fn:codepoints-to-string ( |
||
$values |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the string made up from the ·characters· whose Unicode ·codepoints· are
supplied in $values
. This will be the zero-length string if $values
is the empty sequence.
A dynamic error is raised [err:FOCH0001] if any of the codepoints in
$values
is not a
·permitted character·.
Expression | Result |
---|---|
|
|
|
|
|
|
|
Raises error FOCH0001. |
Returns the sequence of ·codepoints· that constitute an
xs:string
value.
fn:string-to-codepoints ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns a sequence of integers, each integer being the Unicode ·codepoint· of the corresponding ·character· in $value
.
If $value
is a zero-length string or the empty sequence, the function returns
the empty sequence.
Expression | Result |
---|---|
|
|
Function | Meaning |
---|---|
fn:compare |
Returns -1 , 0 , or 1 ,
depending on whether $value1 collates before,
equal to, or after $value2 according to the rules of a selected
collation. |
fn:codepoint-equal |
Returns true if two strings are equal, considered codepoint-by-codepoint. |
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. |
A collation is a specification of the manner in which ·strings· are
compared and, by extension, ordered. When values whose type is
xs:string
or a type derived from xs:string
are
compared (or, equivalently, sorted), the comparisons are inherently
performed according to some collation (even if that collation is defined
entirely on codepoint values). The [Character Model for the World Wide Web 1.0: Fundamentals] observes that
some applications may require different comparison and ordering behaviors
than other applications. Similarly, some users having particular linguistic
expectations may require different behaviors than other users. Consequently,
the collation must be taken into account when comparing strings in any
context. Several functions in this and the following section make use of a
collation.
Collations can indicate that two different codepoints are, in fact, equal for comparison purposes (e.g., “v” and “w” are considered equivalent in some Swedish collations). Strings can be compared codepoint-by-codepoint or in a linguistically appropriate manner, as defined by the collation.
Some collations, especially those based on the Unicode Collation Algorithm (see [UTS #10]) can be “tailored” for various purposes. This document does not discuss such tailoring, nor does it provide a mechanism to perform tailoring. Instead, it assumes that the collation argument to the various functions below is a tailored and named collation.
The ·Unicode codepoint collation· is a collation available in every implementation, which sorts based on codepoint values. For further details see 5.3.2 The Unicode Codepoint Collation.
Collations may or may not perform Unicode normalization on strings before comparing them.
This specification assumes that collations are named and that the collation
name may be provided as an argument to string functions. Functions that
allow specification of a collation do so with an argument whose type is
xs:string
but whose lexical form must conform to an
xs:anyURI
.
This specification also defines the manner in which a
default collation is determined if the collation argument is not specified
in calls of functions that use a collation but allow it to be omitted.
If the collation is specified using a relative URI reference, it is resolved relative to an ·implementation-defined· base URI.
Note:
Previous versions of this specification stated that it must be resolved against the Static Base URIXP40, but this is not always operationally convenient. It is recommended that processors should provide a means of setting the base URI for resolving collation URIs independently of the Static Base URIXP40, though for backwards compatibility, the static Base URIXP40 or executable Base URIXP40 should be used as a default.
This specification does not define whether or not the collation URI is dereferenced. The collation URI may be an abstract identifier, or it may refer to an actual resource describing the collation. If it refers to a resource, this specification does not define the nature of that resource. One possible candidate is that the resource is a locale description expressed using the Locale Data Markup Language: see [UTS #35].
Functions such as fn:compare
and fn:max
that
compare xs:string
values use a single collation URI to identify
all aspects of the collation rules. This means that any parameters such as
the strength of the collation must be specified as part of the collation
URI. For example, suppose there is a collation
http://www.example.com/collations/French
that refers to a French collation that compares on the basis of
base characters. Collations that use the same basic rules, but with higher
strengths, for example, base characters and accents, or base characters,
accents and case, would need to be given different names, say
http://www.example.com/collations/French1
and
http://www.example.com/collations/French2
.
Note that some specifications use the term collation to refer to
an algorithm that can be parameterized, but in this specification, each
possible parameterization is considered to be a distinct collation.
The XQuery/XPath static context includes a provision for a default collation that can be used for string comparisons and ordering operations. See the description of the static context in Section 2.1.1 Static Context XP31. If the default collation is not specified by the user or the system, the default collation is the ·Unicode codepoint collation·.
Note:
XML allows elements to specify the xml:lang
attribute to
indicate the language associated with the content of such an element.
This specification does not use xml:lang
to identify the
default collation because using
xml:lang
does not produce desired effects when the two
strings to be compared have different xml:lang
values or
when a string is multilingual.
[Definition] The collation URI
http://www.w3.org/2005/xpath-functions/collation/codepoint
identifies
a collation which must be recognized by every implementation: it is referred to as
the Unicode codepoint collation (not to be confused with the Unicode collation algorithm).
The Unicode codepoint collation does not perform any normalization on the supplied strings.
The collation is defined as follows. Each of the two strings is
converted to a sequence of integers using the fn:string-to-codepoints
function. These two sequences $A
and $B
are then compared as follows:
If both sequences are empty, the strings are equal.
If one sequence is empty and the other is not, then the string corresponding to the empty sequence is less than the other string.
If the first integer in $A
is less than the first integer in $B
, then
the string corresponding to $A
is less than the string corresponding to
$B
.
If the first integer in $A
is greater than the first integer in $B
, then
the string corresponding to $A
is greater than the string corresponding to
$B
.
Otherwise (the first pair of integers are equal), the result is obtained
by applying the same rules recursively to fn:tail($A)
and
fn:tail($B)
Note:
While the Unicode codepoint collation does not produce results suitable for quality publishing of printed indexes or directories, it is adequate for many purposes where a restricted alphabet is used, such as sorting of vehicle registrations.
This specification defines a family of collation URIs representing tailorings of the Unicode Collation Algorithm (UCA) as defined in [UTS #10]. The parameters used for tailoring the UCA are based on the parameters defined in the Locale Data Markup Language (LDML), defined in [UTS #35].
This family of URIs use the scheme and path http://www.w3.org/2013/collation/UCA
followed by an optional query part. The query part, if present, consists of a question mark followed
by a sequence of zero or more 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 must either use a collation that conforms with
the rules in the Unicode specifications for the requested tailoring, or fail with a static or dynamic error indicating that it
does not provide the collation (the error code should be the same as if the collation URI were not recognized).
If the fallback
parameter
is omitted or takes the value yes
, and if the collation URI is well-formed according to the rules in this section,
then the implementation must accept the collation URI, and should use the available
collation that most closely reflects the user’s intentions. For example, if the collation URI requested is
http://www.w3.org/2013/collation/UCA?lang=se;fallback=yes
and the implementation does not include a fully
conformant version of the UCA tailored for Swedish, then it may choose to use a Swedish collation that is known to differ
from the UCA definition, or one whose conformance has not been established. It might even, as a last resort, fall back to using
codepoint collation.
If two query parameters use the same keyword then the last one wins. If a query parameter uses a keyword or value which is not
defined in this specification then the meaning is ·implementation-defined·. If the implementation recognizes
the meaning of the keyword and value then it should interpret it accordingly; if it does not recognize
the keyword or value then if the fallback
parameter is present with the value no
it should reject
the collation as unsupported, otherwise it should ignore the unrecognized parameter.
The following query parameters are defined. If any parameter is absent, the default is ·implementation-defined· except where otherwise stated. The meaning given for each parameter is non-normative; the normative specification is found in [UTS #35].
Keyword | Values | Meaning |
---|---|---|
fallback | yes | no (default yes) | Determines whether the processor uses a fallback collation if a conformant collation is not available. |
lang | language code: a string in the lexical space of xs:language . |
The language whose collation conventions are to be used. |
version | string | The version number of the UCA to be used. |
strength (default tertiary) | primary | secondary | tertiary | quaternary | identical, or 1|2|3|4|5 as synonyms | 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 considers
spaces and punctuation that would otherwise be ignored (for example data-base =database ). |
maxVariable | space | punct | symbol | currency (default punct) |
Indicates that 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 datatype );
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 | 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 [ISO 15924 Register], the register
of scripts maintained by the Unicode Consortium in its capacity as registration authority
for [ISO 15924]. |
Determines the relative ordering of text in different scripts; for example the value
digit,Grek,Latn indicates
that digits precede Greek letters, which precede Latin letters. |
Note:
This list excludes parameters that are inconvenient to express in a URI, or that are applicable only to substring matching.
The collation URI http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive
must be recognized
by every implementation. It is designed to be compatible with
the HTML ASCII case-insensitive collation as defined in [HTML: Living Standard] (section 4.6, Strings),
which is used, for example, when matching HTML class
attribute values.
The collation is defined as follows:
Let $HACI
be the collation URI
"http://www.w3.org/2005/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)
.
Note:
HTML5 defines the semantics of equality matching using this collation; this
specification additionally defines ordering rules.
The collation supports collation units and can therefore
be used with functions such as fn:contains
; each Unicode codepoint is a single collation unit.
The corresponding HTML5 definition is: A string A is an ASCII 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
fn:compare
function), then:
If CollationA is supported by the implementation, then CollationA is used.
Otherwise, a dynamic error is raised [err:FOCH0002].
If no collation is explicitly specified for the function
(that is,
if the $collation
argument is omitted or is set to an
empty sequence), and the
default collation in the XQuery/XPath static context is CollationB, then:
If CollationB is supported by the implementation, then CollationB is used.
Otherwise, a dynamic error is raised [err:FOCH0002].
Note:
Because the set of collations that are supported is ·implementation-defined·, an implementation has the option to support all collation URIs, in which case it will never raise this error.
If the value of the collation argument is a relative URI reference, it is resolved against the 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 [err:FOCH0002].
Note:
There is no explicit requirement that the string used as a collation URI be a valid URI. Implementations will in many cases reject such strings on the grounds that do not identify a supported collation; they may also cause an error if they cannot be resolved against the relevant base URI.
Returns -1
, 0
, or 1
,
depending on whether $value1
collates before,
equal to, or after $value2
according to the rules of a selected
collation.
fn:compare ( |
||
$value1 |
as , |
|
$value2 |
as , |
|
$collation |
as
|
:= fn:default-collation() |
) as
|
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI.
Returns -1
, 0
, or 1
,
depending on whether $value1
is
respectively less than, equal to, or greater than $value2
,
according to the rules of the collation that is used.
The collation used by this function is determined according to the rules in 5.3.5 Choosing a collation.
If either $value1
or $value2
is the empty sequence,
the function returns the empty sequence.
This function, when used with the default collation, defines the semantics of the eq
, ne
,
gt
, lt
, le
and ge
operators on xs:string
values.
Expression | Result |
---|---|
|
|
|
(Assuming the default collation includes provisions that equate “ss” and the (German) character “ß” (“sharp-s”). Otherwise, the returned value depends on the semantics of the default collation.) |
compare( 'Strasse', 'Straße', 'http://www.w3.org/2013/collation/UCA?lang=de;strength=primary' ) |
(The specified collation equates “ss” and the (German) character “ß” (“sharp-s”).) |
|
(Assuming the default collation includes provisions that treat differences between “ss” and the (German) character “ß” (“sharp-s”) with less strength than the differences between the base characters, such as the final “n”. ). |
Returns true
if two strings are equal, considered codepoint-by-codepoint.
fn:codepoint-equal ( |
||
$value1 |
as , |
|
$value2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
|
|
|
|
|
|
|
|
|
|
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:collation-key ( |
||
$value |
as , |
|
$collation |
as
|
:= fn:default-collation() |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
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 ·implementation-dependent·
value with the property that,
for any two strings $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 5.3.5 Choosing a collation. Collation keys are defined as 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 ·execution scope·; an implementation is under no obligation to generate the same collation keys during a subsequent unrelated query or transformation.
It is possible to define collations that do not have the ability to generate collation keys. Supplying such a collation will cause the function to fail. The ability to generate collation keys is an ·implementation-defined· property of the collation.
An error is raised [err:FOCH0004] if the specified collation does not support the generation of collation keys.
The function is provided primarily for use with maps. If a map is required where
codepoint equality is inappropriate for comparing keys, then a common technique is to
normalize the key so that equality matching becomes feasible. There are many ways
keys can be normalized, for example by use of functions such as
fn:upper-case
, fn:lower-case
,
fn:normalize-space
, or fn:normalize-unicode
, but this
function provides a way of normalizing them according to the rules of a specified
collation. For example, if the collation ignores accents, then the function will
generate the same collation key for two input strings that differ only in their use of
accents.
The result of the function is defined to be an xs:base64Binary
value. Binary values
are chosen because they have unambiguous and 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 [UTS #10]. Implementations are not required to use this algorithm.
The fact that collation keys are ordered can be exploited in XQuery, whose order by
clause does not allow the collation to be selected dynamically. This restriction can be circumvented
by rewriting the clause order by $e/@key collation "URI"
as order by fn: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.
Expression | Result |
---|---|
let $C := 'http://www.w3.org/2013/collation/UCA?strength=primary' |
|
map:merge( (map { collation-key("A", $C): 1 }, map { collation-key("a", $C): 2 }), map { "duplicates": "use-last" } )(collation-key("A", $C)) |
(Given that the keys of the two entries are equal under the rules of the chosen collation, only one of the entries can appear in the result; the one that is chosen is the one from the last map in the input sequence.) |
let $M := map { collation-key("A", $C): 1, collation-key("B", $C): 2 } return $M(collation-key("a", $C)) |
(The strings |
As the above examples illustrate, it is important that when the
|
Determines whether or not any of the supplied strings, when tokenized at whitespace boundaries, contains the supplied token, under the rules of the supplied collation.
fn:contains-token ( |
||
$value |
as , |
|
$token |
as , |
|
$collation |
as
|
:= fn:default-collation() |
) as
|
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI.
If $value
is the empty sequence, the function returns false
.
Leading and trailing whitespace is trimmed from $token
.
If the trimmed value of $token
is a zero-length string, the function returns false
.
The collation used by this function is determined according to the rules in 5.3.5 Choosing a collation.
The function returns true
if and only if there is string in $value
which,
after tokenizing at whitespace boundaries, contains a token
that is equal to the trimmed value of $token
under
the rules of the selected collation.
That is, the function returns the value of the expression:
some $t in $input!tokenize(.) satisfies compare($t, replace($token, '^\s*|\s*$', ''), $collation) eq 0)
Interior whitespace within $token
will cause the function to return false
,
unless such whitespace is ignored by the selected collation.
This function can be used for processing 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 5.3.4 The HTML ASCII Case-Insensitive Collation.
Expression | Result |
---|---|
|
|
|
|
|
|
contains-token( "red green blue", "RED", "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) |
|
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 named character or glyph. |
fn:characters |
Splits the supplied string into a sequence of single-character strings. |
fn:concat |
Returns the concatenation of the string values of the arguments. |
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 ·characters· indicated by $length . |
fn:string-length |
Returns the number of ·characters· in a string. |
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. |
Notes:
When the above operators and functions are applied to datatypes derived from
xs:string
, they are guaranteed to return values that are instances of
xs:string
, but the value might or might not be an instance of the
particular subtype of xs:string
to which they were applied.
The strings returned by fn:concat
and fn:string-join
are not guaranteed to be normalized.
But see note in fn:concat
.
Returns a string containing a named character or glyph.
fn:char ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns a string, generally containing a single ·character· or glyph, identified by $value
.
For example, fn:char("nbsp")
returns a string containing the
non-breaking space character, xA0
.
The supplied value of $value
must be one of the following:
An HTML5 character reference name (often referred to as an entity name) as defined
at [https://html.spec.whatwg.org/multipage/named-characters.html]. The name is
written with no leading ampersand and no trailing semicolon.
For example fn:char("pi")
represents the character
π
(x3C0
).
A processor may recognize additional character reference names defined in other versions of HTML. Character reference names are case-sensitive.
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
(newline, x0A),
\r
(carriage return, 0xD
),
or \t
(tab, 0x09
).
A decimal codepoint value in the form #[0-9]+
, for example
fn:char("#10")
represents a newline character. Leading zeroes are optional.
A hexadecimal codepoint value in the form #x[0-9a-fA-F]+
, for example
fn:char("#x0A")
represents a newline character. Leading zeroes are optional, and the
letters A-F may be in either upper or lower case.
The result must consist of
·permitted characters·.
For example fn:char("#xDEAD")
is invalid because it is in the surrogate range.
The function fails with a dynamic error [err:FOCH0005] if $value
is not a valid
representation of a valid character or sequence of characters.
Although all Unicode characters can appear in string literals (the delimiting quotation marks can be escaped by doubling them), some characters are not visually distinctive, so representing them by name may make code more readable. In addition, there may be contexts where it is necessary or prudent to write XPath expressions using ASCII characters only, for example where an expression is used in the query part of a URI.
A few HTML5 character reference names identify glyphs whose Unicode
representation uses multiple codepoints. For example, the name
NotEqualTilde
refers to the glyph ≂̸
which is expressed
using the two codepoints #x2242 #x0338
. In such cases the string length of
the result of the function will exceed one.
Expression | Result |
---|---|
|
|
|
|
|
(The character tab). |
|
(The character Tempus Imperfectum Cum Prolatione Perfecta). |
|
|
|
|
|
(This HTML5 character reference name expands to multiple codepoints.) |
Accepted for 4.0 on 2023-01-10; with actions on the editor for revision. See issue #121.
Splits the supplied string into a sequence of single-character strings.
fn:characters ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns a sequence of strings, each string having length 1, containing
the corresponding ·character· in $value
.
If $value
is a zero-length string or the empty sequence, the function returns
the empty sequence.
More formally, the function returns the result of the expression fn:string-to-codepoints($value) ! fn:codepoints-to-string(.)
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
"Banana" => characters() => reverse() => string-join() |
|
New in 4.0. Accepted 2022-09-20, subject to improving the description.
Returns the concatenation of the string values of the arguments.
The two-argument form of
this function defines the semantics of the ||
operator.
fn:concat ( |
||
$... |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
This function accepts zero or more arguments, each declared with the required type
xs:anyAtomicType*
. The value $v
supplied for each argument
is first reduced to a single string as follows:
If XPath 1.0 compatibility mode is set to true in the static context of the
function call, then the result of xs:string($v[1])
.
Otherwise, the result of fn:string-join($v)
.
The resulting sequence of strings (one for each supplied argument) is then reduced
to a single string by applying fn:string-join#1
to the sequence.
The fn:concat
function is specified to allow zero or more arguments, which
are concatenated together. This is the only function specified in this document that
allows a variable number of arguments. This capability is retained for compatibility
with [XML Path Language (XPath) Version 1.0].
As mentioned in 5.1 String types Unicode normalization is not automatically
applied to the result of fn:concat
. If a normalized result is required,
fn:normalize-unicode
can be applied to the xs:string
returned by fn:concat
. The following XQuery:
let $v1 := "I plan to go to Mu" let $v2 := "?nchen in September" return concat($v1, $v2)
where the ?
represents either the actual Unicode character COMBINING DIARESIS
(Unicode codepoint U+0308
) or ̈
, will return:
"I plan to go to Mu?nchen in September"
where the ?
represents either the actual Unicode character COMBINING DIARESIS
(Unicode codepoint U+0308
) or ̈
.
It is worth noting that the returned value is not normalized in NFC; however, it is normalized in NFD.
However, the following XQuery:
let $v1 := "I plan to go to Mu" let $v2 := "?nchen in September" return normalize-unicode(concat($v1, $v2))
where ?
represents either the actual Unicode character COMBINING DIARESIS
(Unicode codepoint U+0308
) or ̈
, will return:
"I plan to go to München in September"
This returned result is normalized in NFC.
Expression | Result |
---|---|
|
|
concat( 'Thy ', (), 'old ', "groans", "", ' ring', ' yet', ' in', ' my', ' ancient',' ears.' ) |
|
|
|
concat('Ingratitude, ', 'thou ', ('marble-hearted', ' fiend!')) |
|
|
|
|
|
|
|
Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items.
fn:string-join ( |
||
$values |
as , |
|
$separator |
as
|
:= "" |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of calling the single-argument version of this function is the same as
calling the two-argument version with $separator
set to a zero-length
string.
The function returns an xs:string
created by casting each item
in the sequence $values
to an xs:string
,
and then concatenating the result strings in order,
using the value of $separator
as a
separator between adjacent strings. If $separator
is the 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.
Expression | Result |
---|---|
|
|
|
|
string-join( ('Blow, ', 'blow, ', 'thou ', 'winter ', 'wind!'), '' ) |
|
|
|
|
|
let $doc := <doc> <chap> <section xml:id="xyz"/> </chap> </doc> |
|
$doc//@xml:id ! string-join((node-name(), '="', ., '"')) |
|
$doc//section ! string-join(ancestor-or-self::*/name(), '/') |
|
Returns the part of $value
beginning at the position
indicated by $start
and continuing for the number of ·characters· indicated by $length
.
fn:substring ( |
||
$value |
as , |
|
$start |
as , |
|
$length |
as
|
:= () |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns
the zero-length string.
Otherwise, the function returns a string comprising those ·characters· of $value
whose index position (counting
from one) is greater than or equal to $start
(rounded to an
integer), and (if $length
is specified
and 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 ·characters· in
$value
whose position $p
satisfies:
fn:round($start) <= $p
In the above computations, the rules for op:numeric-less-than
apply.
The first character of a string is located at position 1, not position 0.
The second and third arguments allow xs:double
values (rather than
requiring xs:integer
) in order to achieve compatibility with XPath 1.0.
A surrogate pair counts as one character, not two.
The consequences of supplying values such as NaN
or positive or negative
infinity for the $start
or $length
arguments follow from the
above rules, and are not always intuitive.
Expression | Result |
---|---|
|
(Characters starting at position 6 to the end of
|
|
(Characters at positions greater than or equal to 4 and less than 7 are selected.) |
|
(Characters at positions greater than or equal to 2 and less than 5 are selected.) |
|
(Characters at positions greater than or equal to 0 and less than 3 are selected. Since the first position is 1, these are the characters at positions 1 and 2.) |
|
(Characters at positions greater than or equal to 5 and less than 2 are selected.) |
|
(Characters at positions greater than or equal to -3 and less than 2 are selected. Since the first position is 1, this is the character at position 1.) |
|
(Since |
|
(As above.) |
|
|
|
(Characters at positions greater than or equal to -42 and less than
|
|
(Since the value of |
The third argument can now be supplied as an empty sequence.
Returns the number of ·characters· in a string.
fn:string-length ( |
||
$value |
as
|
:= fn:string(.) |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns an xs:integer
equal to the length in ·characters· of $value
.
Calling the zero-argument version of the function is equivalent to calling
fn:string-length(fn:string(.))
.
If $value
is the empty sequence, the function returns the
xs:integer
value 0
.
If $value
is not specified and the context item is absentDM40, a dynamic error is raised: [err:XPDY0002]XP.
Unlike some programming languages, a ·codepoint· greater than 65535 counts as one character, not two.
There are situations where fn:string-length()
has a different effect
from fn:string-length(.)
. For example, if the context item
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(.)
raises a type error (because the result of atomization
is not an xs:string
).
Expression | Result |
---|---|
string-length( "Harp not on that string, madam; that is past." ) |
|
|
|
Returns $value
with leading and trailing whitespace removed, and
sequences of internal whitespace reduced to a single space character.
fn:normalize-space ( |
||
$value |
as
|
:= fn:string(.) |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the
zero-length string.
The function returns a string constructed by stripping leading and trailing whitespace
from $value
, and replacing sequences of one or more adjacent
whitespace characters with a single space, #x20
.
The whitespace characters are defined in the metasymbol S (Production 3) of [Extensible Markup Language (XML) 1.0 (Fifth Edition)].
If no argument is supplied, then $value
defaults to the string value
(calculated using fn:string
) of the context item (.
).
If no argument is supplied and the context item is absentDM40 then a dynamic error is raised: [err:XPDY0002]XP.
The definition of whitespace is unchanged in [Extensible Markup Language (XML) 1.1 Recommendation]. It is repeated here for convenience:
S ::= (#x20 | #x9 | #xD | #xA)+
Expression | Result |
---|---|
normalize-space(" The wealthy curled darlings of our nation. ") |
|
|
|
Returns $value
after applying Unicode normalization.
fn:normalize-unicode ( |
||
$value |
as , |
|
$form |
as
|
:= "NFC" |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the
zero-length string.
If the single-argument version of the function is used, the result is the same as
calling the two-argument version with $form
set to the string
"NFC"
.
Otherwise, the function returns $value
normalized according to
the rules of the normalization form identified by the value of
$form
.
The effective value of $form
is the value of the expression
fn: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 [UAX #15].
The motivation for normalization form FULLY-NORMALIZED is explained in [Character Model for the World Wide Web 1.0: Normalization]. However, as that specification did not progress beyond working draft status, the normative specification is as follows:
A string is fully-normalized if (a) it is in normalization form NFC as defined in [UAX #15], and (b) it does not start with a composing character.
A composing character is a character that is one or both of the following:
the second character in the canonical decomposition mapping of some character that is not listed in the Composition Exclusion Table defined in [UAX #15];
of non-zero canonical combining class (as defined in [The Unicode Standard]).
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 must support normalization form NFC
and
may support normalization forms NFD
, NFKC
, NFKD
, and
FULLY-NORMALIZED
. They may also support other normalization forms
with ·implementation-defined· semantics.
It is ·implementation-defined· which
version of Unicode (and therefore, of the normalization algorithms and their underlying
data) is supported by the implementation. See [UAX #15] for
details of the stability policy regarding changes to the normalization rules in future
versions of Unicode. If the input string contains codepoints that are unassigned in the
relevant version of Unicode, or for which no normalization rules are defined, the
fn:normalize-unicode
function leaves such codepoints unchanged. If the
implementation supports the requested normalization form then it must
be able to handle every input string without raising an error.
A dynamic error is raised [err:FOCH0003] if the
effective value of the $form
argument is not one of the values
supported by the implementation.
Converts a string to upper case.
fn:upper-case ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the zero-length string is
returned.
Otherwise, the function returns $value
after translating every
·character· to its upper-case correspondent as
defined in the appropriate case mappings section in the Unicode standard [The Unicode Standard]. For versions of Unicode beginning with the 2.1.8 update, only
locale-insensitive case mappings should be applied. Beginning with version 3.2.0 (and
likely future versions) of Unicode, precise mappings are described in default case
operations, which are full case mappings in the absence of tailoring for particular
languages and environments. Every lower-case character that does not have an upper-case
correspondent, as well as every upper-case character, is included in the returned value
in its original form.
Case mappings may change the length of a string. In general, the
fn:upper-case
and fn:lower-case
functions are not inverses
of each other: fn:lower-case(fn:upper-case($s))
is not guaranteed to
return $s
, nor is fn:upper-case(fn:lower-case($s))
. The
Latin small letter dotless i (ı, U+0131, used in Turkish) is perhaps the most prominent
lower-case letter which will not round-trip. The Latin capital letter i with dot above (İ, U+0130)
is the most prominent upper-case letter which will not round trip; there are others,
such as Latin capital letter sharp S (ẞ, U+1E9E), which was introduced in Unicode 5.1.
These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.
Because the function is not sensitive to locale, results will not always match user
expectations. In Quebec, for example, the standard uppercase equivalent of è
is È
,
while in metropolitan France it is more commonly E
; only one of these is supported by
the functions as defined.
Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.
Expression | Result |
---|---|
|
|
Converts a string to lower case.
fn:lower-case ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If t$value
is the empty sequence, the zero-length string is
returned.
Otherwise, the function returns $value
after translating every
·character· to its lower-case correspondent as
defined in the appropriate case mappings section in the Unicode standard [The Unicode Standard]. For versions of Unicode beginning with the 2.1.8 update, only
locale-insensitive case mappings should be applied. Beginning with version 3.2.0 (and
likely future versions) of Unicode, precise mappings are described in default case
operations, which are full case mappings in the absence of tailoring for particular
languages and environments. Every upper-case character that does not have a lower-case
correspondent, as well as every lower-case character, is included in the returned value
in its original form.
Case mappings may change the length of a string. In general, the
fn:upper-case
and fn:lower-case
functions are not inverses
of each other: fn:lower-case(fn:upper-case($s))
is not guaranteed to
return $s
, nor is fn:upper-case(fn:lower-case($s))
. The
Latin small letter dotless i (ı, U+0131, used in Turkish) is perhaps the most prominent
lower-case letter which will not round-trip. The Latin capital letter i with dot above (İ, U+0130)
is the most prominent upper-case letter which will not round trip; there are others,
such as Latin capital letter sharp S (ẞ, U+1E9E), which was introduced in Unicode 5.1.
These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.
Because the function is not sensitive to locale, results will not always match user
expectations. In Quebec, for example, the standard uppercase equivalent of è
is È
,
while in metropolitan France it is more commonly E
; only one of these is supported by
the functions as defined.
Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.
Expression | Result |
---|---|
|
|
Returns $value
modified by replacing or removing individual
characters.
fn:translate ( |
||
$value |
as , |
|
$replace |
as , |
|
$with |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the
zero-length string.
Otherwise, the function returns a result string constructed by processing each ·character· in $value
, in order,
according to the following rules:
If the character does not appear in $replace
then it
is added to the result string unchanged.
If the character first appears in $replace
at some
position M, where the value of $with
is
M or more characters in length, then the character at position
M in $with
is added to the result string.
If the character first appears in $replace
at some
position M, where $with
is less than
M characters in length, then the character is omitted from the
result string.
If $replace
is the 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 |
---|---|
|
|
|
|
|
|
The functions described in the section examine a string $arg1
to see
whether it contains another string $arg2
as a substring. The result
depends on whether $arg2
is a substring of $arg1
, and
if so, on the range of ·characters· in $arg1
which $arg2
matches.
When the ·Unicode codepoint collation·
is used, this simply involves determining whether $arg1
contains a
contiguous sequence of characters whose ·codepoints· are the same, one for one,
with the codepoints of the characters in $arg2
.
When a collation is specified, the rules are more complex.
All collations support the capability of deciding whether two ·strings· are
considered equal, and if not, which of the strings should be regarded as
preceding the other. For functions such as fn:compare
, this is
all that is required. For other functions, such as fn:contains
,
the collation needs to support an additional property: it must be able to
decompose the string into a sequence of collation units, each unit consisting of
one or more characters, such that two strings can be compared by pairwise
comparison of these units. (“collation unit” is equivalent to "collation
element" as defined in [UTS #10].) The string
$arg1
is then considered to contain $arg2
as a
substring if the sequence of collation units corresponding to $arg2
is a subsequence of the sequence of the collation units corresponding to
$arg1
. The characters in $arg1
that match are the
characters corresponding to these collation units.
This rule may occasionally lead to surprises. For example, consider a collation
that treats "Jaeger"
and "Jäger"
as equal. It might do this by treating "ä"
as representing
two collation units, in which case the
expression fn:contains("Jäger", "eg")
will return
true
. Alternatively, a collation might treat "ae" as a single
collation unit, in which case the expression fn:contains("Jaeger",
"eg")
will return false
. The results of these functions thus
depend strongly on the properties of the collation that is used.
In addition,
collations may specify that some collation units should be ignored during matching. If hyphen is an ignored
collation unit, then fn:contains("code-point", "codepoint")
will be true
,
and fn:contains("codepoint", "-")
will also be true
.
In the definitions below, we refer to the terms match and minimal match as defined in definitions DS2 and DS4 of [UTS #10]. In applying these definitions:
C is the collation; that is, the value of the $collation
argument if specified, otherwise the default collation.
P is the (candidate) substring $arg2
Q is the (candidate) containing string $arg1
The boundary condition B is satisfied at the start and end of a string, and between any two characters that belong to different collation units (“collation elements” in the language of [UTS #10]). It is not satisfied between two characters that belong to the same collation unit.
It is possible to define collations that do not have the ability to decompose a string into units suitable for substring matching. An argument to a function defined in this section may be a URI that identifies a collation that is able to compare two strings, but that does not have the capability to split the string into collation units. Such a collation may cause the function to fail, or to give unexpected results or it may be rejected as an unsuitable argument. The ability to decompose strings into collation units is an ·implementation-defined· property of the collation.
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.
fn:contains ( |
||
$value |
as , |
|
$substring |
as , |
|
$collation |
as
|
:= fn:default-collation() |
) as
|
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI.
If $value
or $substring
is the empty sequence, or
contains only ignorable collation units, it is interpreted as the 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 5.3.5 Choosing a collation.
The function returns an xs:boolean
indicating whether or not
$value
contains (at the beginning, at the end, or anywhere within) at
least one sequence of collation units that provides a minimal match to the
collation units in $substring
, according to the collation that is
used.
Note:
Minimal match is defined in [UTS #10].
A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.
Expression | Result |
---|---|
The collation used in these examples, |
|
“Ignorable collation unit” is equivalent to “ignorable collation element” in [UTS #10]. |
|
|
|
|
|
|
(The first rule is applied, followed by the second rule.) |
contains( "abcdefghi", "-d-e-f-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
contains( "a*b*c*d*e*f*g*h*i*", "d-ef-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
contains( "abcd***e---f*--*ghi", "def", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
contains( (), "--***-*---", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
(The second argument contains only ignorable collation units and is equivalent to the zero-length string.) |
Returns true
if the string $value
contains $substring
as a leading
substring, taking collations into account.
fn:starts-with ( |
||
$value |
as , |
|
$substring |
as , |
|
$collation |
as
|
:= fn:default-collation() |
) as
|
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI.
If $value
or $substring
is the empty sequence, or
contains only ignorable collation units, it is interpreted as the 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 5.3.5 Choosing a collation.
The function returns an xs:boolean
indicating whether or not
$value
starts with a sequence of collation units that provides a
match to the collation units of $substring
according to the
collation that is used.
Note:
Match is defined in [UTS #10].
A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.
Expression | Result |
---|---|
The collation used in these examples, |
|
“Ignorable collation unit” is equivalent to “ignorable collation element” in [UTS #10]. |
|
|
|
|
|
|
|
starts-with( "abcdefghi", "-a-b-c-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
starts-with( "a*b*c*d*e*f*g*h*i*", "a-bc-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
starts-with( "abcd***e---f*--*ghi", "abcdef", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
starts-with( (), "--***-*---", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
(The second argument contains only ignorable collation units and is equivalent to the zero-length string.) |
starts-with( "-abcdefghi", "-abc", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
Returns true
if the string $value
contains $substring
as a trailing
substring, taking collations into account.
fn:ends-with ( |
||
$value |
as , |
|
$substring |
as , |
|
$collation |
as
|
:= fn:default-collation() |
) as
|
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI.
If $value
or $substring
is the empty sequence, or
contains only ignorable collation units, it is interpreted as the 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 5.3.5 Choosing a collation.
The function returns an xs:boolean
indicating whether or not
$value
ends with a sequence of collation units that provides a
match to the collation units of $substring
according to the
collation that is used.
Note:
Match is defined in [UTS #10].
A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.
Expression | Result |
---|---|
The collation used in these examples, |
|
“Ignorable collation unit” is equivalent to “ignorable collation element” in [UTS #10]. |
|
|
|
|
|
|
|
ends-with( "abcdefghi", "-g-h-i-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
ends-with( "abcd***e---f*--*ghi", "defghi", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
ends-with( "abcd***e---f*--*ghi", "defghi", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
ends-with( (), "--***-*---", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
(The second argument contains only ignorable collation units and is equivalent to the zero-length string.) |
ends-with( "abcdefghi", "ghi-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
Returns the part of $value
that precedes the first occurrence of
$substring
, taking collations into account.
fn:substring-before ( |
||
$value |
as , |
|
$substring |
as , |
|
$collation |
as
|
:= fn:default-collation() |
) as
|
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI.
If $value
or $substring
is the empty sequence, or
contains only ignorable collation units, it is interpreted as the 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 5.3.5 Choosing a collation.
The function returns the substring of $value
that precedes in
$value
the first occurrence of a sequence of collation units
that provides a minimal match to the collation units of $substring
according to the collation that is used.
Note:
Minimal match is defined in [UTS #10].
A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.
Expression | Result |
---|---|
The collation used in these examples, |
|
“Ignorable collation unit” is equivalent to “ignorable collation element” in [UTS #10]. |
|
|
|
|
|
|
|
substring-before( "abcdefghi", "--d-e-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
substring-before( "abc--d-e-fghi", "--d-e-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
substring-before( "a*b*c*d*e*f*g*h*i*", "***cde", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
substring-before( "Eureka!", "--***-*---", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
(The second argument contains only ignorable collation units and is equivalent to the zero-length string.) |
Returns the part of $value
that follows the first occurrence of
$substring
, taking collations into account.
fn:substring-after ( |
||
$value |
as , |
|
$substring |
as , |
|
$collation |
as
|
:= fn:default-collation() |
) as
|
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI.
If $value
or $substring
is the empty sequence, or
contains only ignorable collation units, it is interpreted as the 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 5.3.5 Choosing a collation.
The function returns the substring of $value
that follows in
$value
the first occurrence of a sequence of collation units
that provides a minimal match to the collation units of $substring
according to the collation that is used.
Note:
Minimal match is defined in [UTS #10].
A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.
Expression | Result |
---|---|
The collation used in these examples, |
|
“Ignorable collation unit” is equivalent to “ignorable collation element” in [UTS #10]. |
|
|
|
|
|
|
|
substring-after( "abcdefghi", "--d-e-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
substring-after( "abc--d-e-fghi", "--d-e-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
substring-after( "a*b*c*d*e*f*g*h*i*", "***cde***", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
|
substring-after( "Eureka!", "--***-*---", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" ) |
(The second argument contains only ignorable collation units and is equivalent to the zero-length string.) |
The three functions described in this section make use of a regular expression syntax for pattern matching. This is described below.
Function | Meaning |
---|---|
fn:matches |
Returns true if the supplied string matches a given regular expression. |
fn:replace |
Returns a string produced from the input string by replacing any substrings that match a given regular expression with a supplied replacement string, 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. |
The regular expression syntax used by these functions is defined in terms of the regular expression syntax specified in XML Schema (see [XML Schema Part 2: Datatypes Second Edition]), which in turn is based on the established conventions of languages such as Perl. However, because XML Schema uses regular expressions only for validity checking, it omits some facilities that are widely used with languages such as Perl. This section, therefore, describes extensions to the XML Schema regular expressions syntax that reinstate these capabilities.
Note:
It is recommended that implementers consult [UTS #18] for information on using regular expression processing on Unicode characters.
The regular expression syntax and semantics are identical to those defined in [XML Schema Part 2: Datatypes Second Edition] with the additions described in the following sub-sections.
Note:
In [Schema 1.1 Part 2] there are no substantive technical changes to the syntax or semantics of regular expressions relative to XSD 1.0, but a number of errors and ambiguities have been resolved. For example, the rules for the interpretation of hyphens within square brackets in a regular expression have been clarified; and the semantics of regular expressions are no longer tied to a specific version of Unicode.
Implementers, even in cases where XSD 1.1 is not supported, are advised to consult the XSD 1.1 regular expression specification for guidance on how to handle cases where the XSD 1.0 specification is unclear or inconsistent.
Two meta-characters, ^
and $
are
added. 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), while
$
matches the end of any line (that is, the end of
the entire string, and the position immediately before a newline
character). Newline here means the character #x0A
only.
This means that the production in [XML Schema Part 2: Datatypes Second Edition]:
[10] Char ::= [^.\?*+()|#x5B#x5D]
is modified to read:
[10] Char ::= [^.\?*+{}()|^$#x5B#x5D]
The XSD 1.1 grammar for regular expressions uses the same
production rule, but renumbered and renamed [73] NormalChar
; it
is affected in the same way.
The characters #x5B
and #x5D
correspond
to [
and ]
respectively.
Note:
The definition of Char (production [10]) in [XML Schema Part 2: Datatypes Second Edition] has a known error in which it omits the left brace ({
) and right brace (}
). That error is corrected here.
The following production:
[11] charClass ::= charClassEsc | charClassExpr | WildCardEsc
is modified to read:
[11] charClass ::= charClassEsc | charClassExpr |
WildCardEsc | "^" | "$"
Using XSD 1.1 as the baseline the equivalent is to change the production:
[74] charClass ::= SingleCharEsc | charClassEsc | charClassExpr | WildCardEsc
to read:
[74] charClass ::= SingleCharEsc | charClassEsc | charClassExpr |
WildCardEsc | "^" | "$"
Single character escapes are extended to allow the
$
character to be escaped. The following production
is changed:
[24]SingleCharEsc ::= '\' [nrt\|.?*+(){}#x2D#x5B#x5D#x5E]
to
[24]SingleCharEsc ::= '\' [nrt\|.?*+(){}$#x2D#x5B#x5D#x5E]
(In the XSD 1.1 version of the regular expression grammar, the production rule
for SingleCharEsc
is unchanged, but is renumbered [84])
Reluctant quantifiers are supported. They are
indicated by a
?
following a quantifier. Specifically:
X??
matches X, once or not at all
X*?
matches X, zero or more times
X+?
matches X, one or more times
X{n}?
matches X, exactly n times
X{n,}?
matches X, at least n times
X{n,m}?
matches X, at least n times, but
not more than m times
The effect of these quantifiers is that the regular expression
matches the shortest possible substring consistent
with the match as a whole succeeding. Without the
?
, the regular expression matches the
longest possible substring.
To achieve this, the production in [XML Schema Part 2: Datatypes Second Edition]:
[4] quantifier ::= [?*+] | ( '{' quantity '}' )
is changed to:
[4] quantifier ::= ( [?*+] | ( '{' quantity '}' ) ) '?'?
(In the XSD 1.1 version of the regular expression grammar, this rule is unchanged, but is renumbered [67])
Note:
Reluctant quantifiers have no effect on the results of the
boolean fn:matches
function, since this
function is only interested in discovering whether a match
exists, and not where it exists.
Sub-expressions (groups) within the regular expression are
recognized. The regular expression syntax defined by [XML Schema Part 2: Datatypes Second Edition]
allows a regular expression to contain parenthesized sub-expressions, but attaches no special
significance to them. Some operations associated with regular expressions (for example,
back-references, and the fn:replace
function) allow access to the parts of the
input string that matched a sub-expression (called captured substrings).
[Definition] A
left parenthesis is recognized as a capturing left parenthesis provided
it is not immediately followed by ?:
(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 capturing sub-expression.
More specifically, the ·capturing sub-expression· enclosed by the Nth capturing left parenthesis within the regular expression (determined by its character position in left-to-right order, and counting from one) is referred to as the Nth capturing sub-expression.
For example, in the regular expression A(BC(?:D(EF(GH[()]))))
, the string matched
by the sub-expression BC(?:D(EF(GH[()])))
is capturing sub-expression 1, the string
matched by EF(GH[()])
is capturing sub-expression 2, and the string matched by
GH[()]
is capturing sub-expression 3.
When, in the course of evaluating a regular expression, a particular substring of the input matches a capturing sub-expression, that substring becomes available as a captured substring. The string matched by the Nth capturing sub-expression is referred to as the Nth captured substring. By convention, the substring captured by the entire regular expression is treated as captured substring 0 (zero).
When a ·capturing sub-expression· is matched
more than once (because it is within a construct that allows repetition), then
only the last substring that it matched will be captured. Note that this rule
is not sufficient in all cases to ensure an unambiguous result, especially in
cases where (a) the regular expression contains nested repeating constructs,
and/or (b) the repeating construct matches a zero-length string. In such cases
it is implementation-dependent which substring is captured. For example given
the regular expression (a*)+
and the input string "aaaa"
, an implementation
might legitimately capture either "aaaa"
or a zero length string as the content
of the captured subgroup.
Parentheses that are required to group terms within the regular expression, but which are
not required for capturing of substrings, can be represented using
the syntax (?:xxxx)
. To achieve this, the production rule for atom
in [XML Schema Part 2: Datatypes Second Edition] is changed to replace the alternative:
( '(' regExp ')' )
with:
( '(' '?:'? regExp ')' )
(For the new versions of the XSD 1.0 and XSD 1.1 production rules for
atom
, see below.)
In the absence of 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 fn:replace
and back-references) that number the capturing sub-expressions
within a regular expression.
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 N
th captured substring.
For example, the regular expression
('|").*\1
matches a sequence of characters
delimited either by an apostrophe at the start and end, or by a
quotation mark at the start and end.
If no string has been matched by the N
th capturing
sub-expression, the back-reference is interpreted as matching
a zero-length string.
Combining this change with the introduction of non-capturing groups (see above), back-references change the following production:
[9] atom ::= Char | charClass | ( '(' regExp ')' )
to
[9] atom ::= Char | charClass | ( '(' '?:'? regExp ')' ) | backReference
[9a] backReference ::= "\" [1-9][0-9]*
With respect to the XSD 1.1 version of the regular expression grammar, the effect is to change:
[72] atom ::= NormalChar | charClass | ( '(' regExp ')' )
to
[72] atom ::= NormalChar | charClass | ( '(' '?:'? regExp ')' ) | backReference
[72a] backReference ::= "\" [1-9][0-9]*
Note:
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
[err:FORX0002].
Note:
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.
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. If there
are characters present that are not defined here as flags, then a dynamic error
is raised [err:FORX0001].
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 case-variant of
another character C1 if the following XPath expression returns
true
when the two characters
are considered as strings of length one, and the
·Unicode codepoint collation· is used:
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 (production charRange
in the XSD 1.0 grammar, replaced by productions charRange
and singleChar
in XSD 1.1) represents the set
containing all the characters that it would match in the absence
of the i
flag, together with their 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
(#x9
, #xA
, #xD
and #x20
)
in the regular expression are removed prior to matching with one exception:
whitespace characters within character class expressions
(charClassExpr
) are not removed. This flag can be used,
for example, to break up long regular expressions into readable lines.
Examples:
fn:matches("helloworld", "hello world", "x")
returns true()
fn:matches("helloworld", "hello[ ]world", "x")
returns false()
fn:matches("hello world", "hello\ sworld", "x")
returns true()
fn:matches("hello world", "hello world", "x")
returns false()
q
: if present, all characters in the regular expression
are treated as representing themselves, not as metacharacters. In effect, every
character that would normally have a special meaning in a regular expression is implicitly escaped
by preceding it with a backslash.
Furthermore, when this flag is present, the characters $
and
\
have no special significance when used in the replacement string
supplied to the fn:replace
function.
This flag can be used in conjunction with the i
flag. If it is used
together with the m
, s
, or x
flag, that flag
has no effect.
Examples:
fn:tokenize("12.3.5.6", ".", "q")
returns ("12", "3", "5", "6")
fn:replace("a\b\c", "\", "\\", "q")
returns "a\\b\\c"
fn:replace("a/b/c", "/", "$", "q")
returns "a$b$c"
fn:matches("abcd", ".*", "q")
returns false()
fn:matches("Mr. B. Obama", "B. OBAMA", "iq")
returns true()
Returns true
if the supplied string matches a given regular expression.
fn:matches ( |
||
$value |
as , |
|
$pattern |
as , |
|
$flags |
as
|
:= "" |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, it is interpreted as the zero-length
string.
If the $flags
argument is omitted or if it is an empty sequence,
the effect is the same as setting $flags
to a zero-length string.
Flags are defined in 5.6.2 Flags.
The function returns true
if $value
or some substring of
$value
matches the regular expression supplied as $pattern
,
and the associated $flags
. Otherwise, the function returns false
.
A dynamic error is raised [err:FORX0002] if
$pattern
is invalid according to the rules described in 5.6.1 Regular expression syntax.
A dynamic error is raised [err:FORX0001] if
$flags
is invalid according to the rules described in 5.6.2 Flags.
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 [XML Schema Part 2: Datatypes Second Edition], where regular expressions are implicitly anchored.
Regular expression matching is defined on the basis of Unicode code points; it takes no account of collations.
Expression | Result |
---|---|
|
|
|
|
|
|
Given the source document: |
|
let $poem := <poem author="Wilhelm Busch"> Kaum hat dies der Hahn gesehen, Fängt er auch schon an zu krähen: Kikeriki! Kikikerikih!! Tak, tak, tak! - da kommen sie. </poem> |
|
the following function calls produce the following results, with the
|
|
|
|
|
|
|
|
|
|
|
|
Returns a string produced from the input string by replacing any substrings that match a given regular expression with a supplied replacement string, provided either literally, or by invoking a supplied function.
fn:replace ( |
||
$value |
as , |
|
$pattern |
as , |
|
$replacement |
as
|
:= () , |
$flags |
as
|
:= '' , |
$action |
as
|
:= () |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, it is interpreted as the zero-length
string.
The replacement string is determined by the values of the
$replacement
and/or $action
arguments:
If the $action
argument is present and is not an empty sequence,
the string is obtained by calling the $action
function.
The first argument to the $action
function is the string to be replaced,
provided as xs:untypedAtomic
.
The second argument to the $action
function provides the captured
substrings as an xs:untypedAtomic
sequence.
The Nth
item in this sequence is the substring captured by
the Nth
parenthesized sub-expression. If the
Nth
parenthesized sub-expression 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 the $action
parameter may be an arity-1 function: the
second argument does not need to be declared if it is not used.
The replacement string is obtained by invoking fn:string
for the result of the function call.
Otherwise, if the $replacement
argument is present and is not
an empty sequence, the replacement string is the value of $replacement
.
Otherwise, the replacement string is the zero-length string.
If the $flags
argument is omitted or if it is an empty sequence,
the effect is the same as setting $flags
to a zero-length string.
Flags are defined in 5.6.2 Flags.
The function returns the xs:string
that is obtained by replacing each
non-overlapping substring of $value
that matches the given
$pattern
with a replacement string.
If two overlapping substrings of $value
both match the
$pattern
, then only the first one (that is, the one whose first ·character· comes first in the $value
string) is
replaced.
If the q
flag is present, or if the replacement string was obtained
by calling the $action
function, then the replacement string is used
as is.
Otherwise, within the replacement string, a variable $N
may
be used to refer to the substring captured by the Nth parenthesized sub-expression in
the regular expression. For each match of the pattern, these variables are assigned the
value of the content matched by the relevant sub-expression, and the modified
replacement string is then substituted for the ·characters· in $value
that matched the pattern.
$0
refers to the substring captured by the regular expression as a
whole.
More specifically, the rules are as follows, where S
is the number of
parenthesized sub-expressions in the regular expression, and N
is the
decimal number formed by taking all the digits that consecutively follow the
$
character:
If N
=0
, then the variable is replaced by the substring
matched by the regular expression as a whole.
If 1
<=N
<=S
, then the variable is
replaced by the substring captured by the Nth parenthesized sub-expression. If the
Nth
parenthesized sub-expression was not matched, then the
variable is replaced by the zero-length string.
If S
<N
<=9
, then the variable 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 sub-expression, followed by the digit
3
.
Unless the q
flag is used, a literal $
character within the
replacement string must be written as \$
, and a literal \
character must be written as \\
.
If two alternatives within the pattern both match at the same position in the
$input
, then the match that is chosen is the one matched by the first
alternative. For example:
replace("abcd", "(ab)|(a)", "[1=$1][2=$2]") returns "[1=ab][2=]cd"
A dynamic error is raised [err:FORX0002] if the value of
$pattern
is invalid according to the rules described in section 5.6.1 Regular expression syntax.
A dynamic error is raised [err:FORX0001] if the value of
$flags
is invalid according to the rules described in section 5.6.2 Flags.
A dynamic error is raised [err:FORX0003] if the pattern matches a
zero-length string, that is, if the expression fn:matches("", $pattern,
$flags)
returns true
. It is not an error, however, if a captured
substring is zero-length.
In the absence of the q
flag,
a dynamic error is raised [err:FORX0004] if the value of
$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 [err:FORX0004] if the value of
$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 [err:FORX0005] if both the $replacement
and $action
arguments are supplied, and neither is an empty sequence.
If the input string contains no substring that matches the regular expression, the result of the function is a single string identical to the input string.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(The first |
replace( "abracadabra", "bra", action := function { "*" } ) |
|
replace( "abracadabra", "bra", action := upper-case#1 ) |
|
replace( "Chapter 9", "[0-9]+", action := function { string(number(.) + 1) } ) |
|
replace( "LHR to LAX", "[A-Z]{3}", action := map {'LAX': 'Los Angeles', 'LHR': 'London' } ) |
|
replace( "57°43′30″", "([0-9]+)°([0-9]+)′([0-9]+)″", action := function($s, $groups) { string(number($groups[1]) + number($groups[2]) ÷ 60 + number($groups[3]) ÷ 3600) || '°' } ) |
|
The expression |
The addition of the $action
argument as proposed here has
not been reviewed by the working group.
Returns a sequence of strings constructed by splitting the input wherever a separator is found; the separator is any substring that matches a given regular expression.
fn:tokenize ( |
||
$value |
as , |
|
$pattern |
as
|
:= () , |
$flags |
as
|
:= "" |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The following rules apply when the $pattern
argument is omitted,
or is set to an empty sequence:
The function splits the supplied string at whitespace boundaries.
More specifically, calling fn:tokenize($value)
or fn:tokenize($value, ())
is equivalent to calling 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:
If the $flags
argument is omitted or if it is an empty sequence,
the effect is the same as setting $flags
to a zero-length string.
Flags are defined in 5.6.2 Flags.
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.
If a separator occurs at the start of the $value
string, the result
sequence will start with a zero-length string. Similarly, zero-length strings will also occur in
the result sequence if a separator occurs at the end of the $value
string,
or if two adjacent substrings match the supplied $pattern
.
If two alternatives within the supplied $pattern
both match at the same
position in the $value
string, then the match that is chosen is the first.
For example:
tokenize("abracadabra", "(ab)|(a)") returns ("", "r", "c", "d", "r", "")
A dynamic error is raised [err:FORX0002] if the value of
$pattern
is invalid according to the rules described in section 5.6.1 Regular expression syntax.
A dynamic error is raised [err:FORX0001] if the value of
$flags
is invalid according to the rules described in section 5.6.2 Flags.
A dynamic error is raised [err:FORX0003] if the supplied
$pattern
matches a zero-length string, that is, if fn:matches("",
$pattern, $flags)
returns true
.
If the input string is not zero length, and no separators are found in the input string, the result of the function is a single string identical to the input string.
The one-argument form of 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 function returns no information about the separators that were found
in the string. If this information is required, the fn:analyze-string
function
can be used instead.
The separator used by the one-argument form of the function is any sequence
of tab (x09
), newline (x0A
), carriage return
(x0D
) or space (x20
) characters. This is the same as the
separator recognized by list-valued attributes as defined in XSD.
It is not the same as the separator recognized by list-valued attributes in HTML5,
which also treats form-feed (x0C
) as whitespace. If it is necessary
to treat form-feed as a separator, an explicit separator pattern should be used.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
tokenize( "Some unparsed <br> HTML <BR> text", "\s*<br>\s*", "i" ) |
|
Changed for 4.0: allow the second argument to be an empty sequence.
Analyzes a string using a regular expression, returning an XML structure that identifies which parts of the input string matched or failed to match the regular expression, and in the case of matched substrings, which substrings matched each capturing group in the regular expression.
fn:analyze-string ( |
||
$value |
as , |
|
$pattern |
as , |
|
$flags |
as
|
:= "" |
) as
|
This function is ·nondeterministic·, ·context-independent·, and ·focus-independent·.
If the $flags
argument is omitted or if it is an empty sequence,
the effect is the same as setting $flags
to a zero-length string.
Flags are defined in 5.6.2 Flags.
If $value
is the empty sequence the function behaves as if
$value
were the zero-length string. In this situation the result will be
an element node with no children.
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 ·implementation-dependent·. The children of this element are a
sequence of 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 a
match
element, and any intervening substring as the content of a
non-match
element.
More specifically, the function starts at the beginning of the input string and attempts
to find the first substring that matches the regular expression. If there are several
matches, the first match is defined to be the one whose starting position comes first in
the string. If several alternatives within the regular expression both match at the same
position in the input string, then the match that is chosen is the first alternative
that matches. For example, if the input string is The quick brown fox jumps
and the regular expression is jump|jumps
, then the match that is chosen is
jump
.
Having found the first match, the instruction proceeds to find the second and subsequent matches by repeating the search, starting at the first ·character· that was not included in the previous match.
The input string is thus partitioned into a sequence of substrings, some of which match
the regular expression, others which do not match it. Each substring will contain at
least one character. This sequence is represented in the result by the sequence of
fn:match
and fn:non-match
children of the returned element
node; the string value of the fn:match
or fn:non-match
element
will be the corresponding substring of $input
, and the string value of the
returned element node will therefore be the same as $input
.
The content of an fn:non-match
element is always a single text node.
The content of a fn:match
element, however, is in general a sequence of
text nodes and fn:group
element children. An fn:group
element
with a nr
attribute having the integer value N identifies the
substring captured by the Nth parenthesized sub-expression in the regular
expression. For each capturing subexpression there will be at most one corresponding
fn:group
element in each fn:match
element in the
result.
If the function is called twice with the same arguments, it is ·implementation-dependent· whether the two calls return the same element node or distinct (but deep equal) element nodes. In this respect it is ·non-deterministic with respect to node identity·.
The base URI of the element nodes in the result is ·implementation-dependent·.
A schema is defined for the structure of the returned element: see C.1 Schema for the result of fn:analyze-string.
The result of the function will always be such that validation against this schema would succeed. However, it is ·implementation-defined· whether the result is typed or untyped, that is, whether the elements and attributes in the returned tree have type annotations that reflect the result of validating against this schema.
A dynamic error is raised [err:FORX0002] if the value of
$pattern
is invalid according to the rules described in section 5.6.1 Regular expression syntax.
A dynamic error is raised [err:FORX0001] if the value of
$flags
is invalid according to the rules described in section 5.6.2 Flags.
A dynamic error is raised [err:FORX0003] if the supplied
$pattern
matches a zero-length string, that is, if fn:matches("",
$pattern, $flags)
returns true
.
It is recommended that a processor that implements schema awareness should return typed nodes. The concept of “schema awareness”, however, is a matter for host languages to define and is outside the scope of the function library specification.
The declarations and definitions in the schema are not automatically available in
the static context of the fn:analyze-string
call (or of any other
expression). The contents of the static context are host-language defined, and in some
host languages are implementation-defined.
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.
Expression | Result |
---|---|
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. |
|
|
<analyze-string-result xmlns="http://www.w3.org/2005/xpath-functions"> <match>The</match> <non-match> </non-match> <match>cat</match> <non-match> </non-match> <match>sat</match> <non-match> </non-match> <match>on</match> <non-match> </non-match> <match>the</match> <non-match> </non-match> <match>mat</match> <non-match>.</non-match> </analyze-string-result> (with whitespace added for legibility) |
analyze-string( "2008-12-03", "^(\d+)\-(\d+)\-(\d+)$" ) |
<analyze-string-result xmlns="http://www.w3.org/2005/xpath-functions"> <match><group nr="1">2008</group>-<group nr="2" >12</group>-<group nr="3">03</group></match> </analyze-string-result> (with whitespace added for legibility) |
analyze-string( "A1,C15,,D24, X50,", "([A-Z])([0-9]+)" ) |
<analyze-string-result xmlns="http://www.w3.org/2005/xpath-functions"> <match><group nr="1">A</group><group nr="2">1</group></match> <non-match>,</non-match> <match><group nr="1">C</group><group nr="2">15</group></match> <non-match>,,</non-match> <match><group nr="1">D</group><group nr="2">24</group></match> <non-match>, </non-match> <match><group nr="1">X</group><group nr="2">50</group></match> <non-match>,</non-match> </analyze-string-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:resolve-uri |
Resolves a relative IRI reference against an absolute IRI. |
fn:encode-for-uri |
Encodes reserved characters in a string that is intended to be used in the path segment of a URI. |
fn:decode-from-uri |
Decodes URI-escaped characters in a string. |
fn:iri-to-uri |
Converts a string containing an IRI into a URI according to the rules of [RFC 3987]. |
fn:escape-html-uri |
Escapes a URI in the same way that HTML user agents handle attribute values expected to contain URIs. |
Resolves a relative IRI reference against an absolute IRI.
fn:resolve-uri ( |
||
$href |
as , |
|
$base |
as
|
:= () |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.
The function is defined to operate on IRI references as defined in [RFC 3987], and the implementation must permit all arguments that are valid according to that specification. In addition, the implementation may accept some or all strings that conform to the rules for (absolute or relative) Legacy Extended IRI references as defined in [Legacy extended IRIs for XML resource identification]. For the purposes of this section, the terms IRI and IRI reference include these extensions, insofar as the implementation chooses to support them.
The following rules apply in order:
If $href
is the empty sequence, the function returns the empty
sequence.
If $href
is an absolute IRI (as defined above), then it is returned
unchanged.
If the $base
argument is not supplied,
or is supplied as an empty sequence then:
If the static base URI in the static context is not absent, it is used as the effective
value of $base
.
Otherwise, a dynamic error is raised: [err:FONS0005].
The function resolves the relative IRI reference $href
against the base IRI $base
using the algorithm defined in [RFC 3986], adapted by treating any ·character·
that would not be valid in an RFC3986 URI or relative reference in the same way that
RFC3986 treats unreserved characters. No percent-encoding takes place.
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 [err:FONS0005] if the base-uri property is not initialized in the static
context.
A dynamic error is raised [err:FORG0002] if $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 [err:FORG0002] if $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 or if it is a non-hierarchic URI). In XPath 4.0, attempting
to resolve against an absolute URI that includes a fragment identifier is no longer
an error, the fragment identifier is simply ignored. A narrow reading of RFC 3986
might seem to forbid this, but in practice the interpretation is non-controversial
and the practice is widely supported.
A dynamic error is raised [err:FORG0009] if the chosen resolution algorithm fails for any other reason.
Resolving a URI does not dereference it. This is merely a syntactic operation on two ·strings·.
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 should not be done by converting the LEIRI to a URI, and should not involve percent-encoding. This specification fills this gap by defining resolution for LEIRIs in the same way that RFC3987 defines resolution for IRIs, that is by specifying that additional characters are handled as unreserved characters.
The optional second argument can now be supplied as an empty sequence.
Encodes reserved characters in a string that is intended to be used in the path segment of a URI.
fn:encode-for-uri ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 [RFC 3986] to the 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 [RFC 3986].
Since [RFC 3986] recommends that, for consistency, URI producers and normalizers should use uppercase hexadecimal digits for all percent-encodings, this function must always generate hexadecimal values using the upper-case letters A-F.
All characters are escaped except those identified as “unreserved” by [RFC 3986], that is the upper- and lower-case letters 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 |
---|---|
encode-for-uri( "http://example.com/00/Weather/CA/Los%20Angeles#ocean" ) |
(This is probably not what the user intended because all of the delimiters have been encoded.) |
concat( "http://example.com/", encode-for-uri("~bébé") ) |
|
concat( "http://example.com/", encode-for-uri("100% organic") ) |
|
Decodes URI-escaped characters in a string.
fn:decode-from-uri ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 an sequence of octets. Each plus sign
(+
) is replaced with the octet representing a space character
(x20
), and any substring that matches the regular expression
%[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 no hexadecimal digits,
these characters are replaced by octets xEF
, xBF
,
and xBD
, that is, the UTF-8 encoding of the Unicode replacement character
(0xFFFD
). For example, the incomplete or invalid percent-encoded strings
"%"
, "%X"
, and "%AX"
are all replaced with
these octets. For the string "%1X!"
, the octets xEF
,
xBF
, xBD
, and x21
are returned.
Next, the resulting octets are interpreted as 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 |
---|---|
|
|
|
|
|
|
Converts a string containing an IRI into a URI according to the rules of [RFC 3987].
fn:iri-to-uri ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 [RFC 3987] by percent-encoding characters
that are allowed in an IRI but not in a URI. If $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 [RFC 3986] before the conversion is performed.
Since [RFC 3986] recommends that, for consistency, URI producers and normalizers should use uppercase hexadecimal digits for all percent-encodings, this function must always generate hexadecimal values using the upper-case letters A-F.
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 ·string· and operates on the ·characters· in the string.
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 x20-x7E will be
percent-encoded because they are invalid in a URI.
Since this function does not escape the PERCENT SIGN %
and this character is not
allowed in data within a URI, users wishing to convert character strings (such as file
names) that include %
to a URI should manually escape %
by replacing it with %25
.
Expression | Result |
---|---|
iri-to-uri( "http://www.example.com/00/Weather/CA/Los%20Angeles#ocean" ) |
|
|
|
Escapes a URI in the same way that HTML user agents handle attribute values expected to contain URIs.
fn:escape-html-uri ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the zero-length
string.
Otherwise, the function escapes all ·characters· except
printable characters of the US-ASCII coded character set, specifically the ·codepoints· between 32 and 126 (decimal) inclusive. Each
character in $uri
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 [HTML 4.0] Appendix B.2.1.
Expression | Result |
---|---|
escape-html-uri( "http://www.example.com/00/Weather/CA/Los Angeles#ocean" ) |
|
escape-html-uri( "javascript:if (navigator.browserLanguage == 'fr') window.open('http://www.example.com/~bébé');" ) |
|
This section specifies functions that parse strings as URIs, to identify their structure, and construct URI strings from their structured representation.
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. |
The structured representation of a URI is described by the
uri-structure-record
:
uri-structure-record : |
|
record( |
|
uri? |
as xs:string , |
scheme? |
as xs:string , |
authority? |
as xs:string , |
userinfo? |
as xs:string , |
host? |
as xs:string , |
port? |
as xs:string , |
path? |
as xs:string , |
query? |
as xs:string , |
fragment? |
as xs:string , |
path-segments? |
as array(xs:string) , |
query-parameters? |
as array(record(key? as xs:string, value? as xs:string, *)) , |
* |
|
) |
The parts of this structure are:
uri | The original URI. This element is returned by fn:parse-uri ,
but ignored by fn:build-uri . |
scheme | The URI scheme (e.g., “https” or “file”). |
authority | The authority portion of the URI (e.g., “example.com:8080”). |
userinfo | Any userinfo that was passed as part of the authority. |
host | The host passed as part of the authority (e.g., “example.com”). |
port | The port passed as part of the authority (e.g., “8080”). |
path | The path portion of the URI. |
query | Any query string. |
fragment | Any fragment identifier. |
path-segments | Parsed and unescaped path segments. |
query-segments | Parsed and unescaped query terms |
* | Additional, information defined structures are allowed. |
The segmented forms of the path and query parameters provide convenient access to commonly used information. They’re represented in the map as arrays, instead of sequences, just for the convenience of serializing the structure.
The path, if there is one, is tokenized on “/” characters and
each segment is unesaped. Consider the URI http://example.com/path/to/a%2fb
. The path portion has to be returned as /path/to/a%2fb
because
decoding the %2f
would change the nature of the path.
The unescaped form is easily accessible from the path-segments array:
[ "", "path", "to", "a/b" ]
Note that the presence or absence of a leading slash on the path will effect whether or not the array begins with an empty string.
The query parameters are similarly decoded. Consider the URI:
http://example.com/path?a=1&b=2%264&a=3
.
Here the decoded form in the query-segments gives quick access to
the parameter values:
[ { "key": "a", "value": "1" }, { "key": "b", "value": "2&4" }, { "key": "a", "value": "3" } ]
Note that both keys and values are unescaped and that it’s an array
of maps because key values can be repeated, as seen for a
in this example.
Parses the URI provided and returns a map of its parts.
fn:parse-uri ( |
||
$uri |
as , |
|
$options |
as
|
:= map{} |
) as uri-structure-record |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function parses the $uri
provided,
returning a map containing its constituent parts: scheme,
authority components, path, etc.
In addition to parsing URIs as defined by [RFC 3986]
(and [RFC 3987]), this function also attempts to
account for strings that are not valid URIs but that often appear
in URI-adjacent spaces, such as file names. Not all such strings
can be successfully parsed as URIs.
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.
The following options are available:
Key | Meaning |
---|---|
path-separator |
Identifies the path separator
|
query-separator |
Identifies the query separator
|
allow-deprecated-features |
Indicates that deprecated URI
features should be returned
|
omit-default-ports |
Indicates that a port number that is the same as
the default port for a given scheme should be omitted.
|
unc-path |
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.)
|
Processing begins with a string that is equal
to the $uri
. If the string contains
any backlashes (\
), replace them with forward
slashes (/
).
If the string matches ^(.*)#([^#]*)$
,
the string is the first match group and the
fragment is the second match group. Otherwise,
the string is unchanged and the fragment is the empty
sequence.
If the string matches ^(.*)\?([^\?]*)$
,
the string is the first match group and the
query is the second match group. Otherwise,
the string is unchanged and the query is the empty
sequence.
If the string matches ^[a-zA-Z][:|].*$
:
the scheme is file
;
if the second character in the string is |
, it is changed to :
;
the filepath is the string; and
a leading slash /
is added to the string.
Otherwise, if the string matches
^([a-zA-Z][A-Za-z0-9\+\-\.]*):(.*)$
:
the scheme is the first match group,
the string is the second match group, and
the filepath is the empty sequence.
Finally, if the string does not match either expression:
the scheme is the empty sequence,
the string is unchanged, and
the filepath is the empty sequence.
If the scheme is the empty sequence, the
unc-path
option is true
, and the string
matches ^//[^/].*$
, then the scheme is file
and the filepath is the string.
If the scheme is known to be hierarchical, or known
not to be hierarchical, then hierarchical is set accordingly.
Exactly which schemes are known to be hierarchical or
non-hierarchical is
·implementation-defined·.
If the implementation does not know if a scheme is or is not
hierarchical, the hierarchical setting depends on the
string. If the string is the empty string,
hierarchical is the empty sequence (i.e. not known),
otherwise hierarchical is
true
if string begins with /
and false
otherwise.
If the scheme is not known or is known to be file
and
the string matches ^//*([a-zA-Z]:.*)$
,
the authority is empty and the string is
the first match group. Otherwise, if the string
matches ^///*([^/]+)(/.*)?$
then the authority
is the first match group and the string is the second
match group. If the string does not match either
regular expression, the authority is the empty sequence
and the string is unchanged.
If the string matches ^//*([a-zA-Z]:.*)$
,
the authority is empty and the string is
the first match group. Otherwise, if the string
matches ^///*([^/]+)(/.*)?$
then the authority
is the first match group and the string is the second
match group. If the string does not match either
regular expression, the authority is the empty sequence
and the string is unchanged.
If the authority matches
^(([^@]*)@)(.*)(:([^:]*))?$
,
then the userinfo is match group 2, otherwise
userinfo is the empty sequence. If
userinfo is present and contains a non-empty password, then
userinfo is discarded and set to the empty sequence
unless the allow-deprecated-features
option is true
.
When parsing the authority to find the host,
there are four possibilities: the host can be a registered name (e.g.,
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 authority matches
^(([^@]*)@)?(\[[^\]]*\])(:([^:]*))?$
,
then the host is match group 3, otherwise
If the authority matches
^(([^@]*)@)?\[.*$
then [err:FOUR0001] is raised, otherwise
If the authority matches
^(([^@]*)@)?([^:]+)(:([^:]*))?$
,
then the host is match group 3, otherwise
the host is the empty sequence.
This function does not attempt to decode the components of the host.
Similar care must be taken to match the port because an IPv6/IPvFuture address may contain a colon.
If the authority matches
^(([^@]*)@)?(\[[^\]]*\])(:([^:]*))?$
,
then the port is match group 5, otherwise
If the authority matches
^(([^@]*)@)?([^:]+)(:([^:]*))?$
,
then the port is match group 5, otherwise
the port is the empty sequence.
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 should
recognize the default ports for http
(80), https
(443),
ftp
(21), and ssh
(22). Exactly which ports are
recognized
is ·implementation-defined·.
If the string is the empty string, then
path is the empty sequence, otherwise path
is the whole string. If the scheme is
file
or the empty sequence, and filepath is
the empty sequence, filepath is also the whole string.
The path separator is the value of the
path-separator
option. A
path-segments sequence is constructed by
tokenizing the string on the path
separator and applying uri decoding on each
token.
Applying uri decoding replaces all occurrences of
plus (+
) with spaces and all occurrences of
%[a-fA-F0-9][a-fA-F0-9]
with a single character with the
codepoint represented by the two digit hexadecimal number that
follows the %
character. In other words, "A%42C"
becomes
"ABC"
If there are any occurrences of %
followed
by up to two characters that are not hexadecimal digits, they are
replaced by the character sequence 0xef
, 0xbf
, 0xbd
(that is, 0xfffd
, the Unicode replacement character, in UTF-8).
After replacing all of the percent-escaped characters, the character sequence is
interpreted as UTF-8 to get the string. In other words "A%XYC%Z%F0%9F%92%A9"
becomes
"A�C�💩"
. If the character sequence is
not a valid sequence of UTF-8 characters, any invalid characters are replaced with the
0xfffd
.
The query separator is the value of the
query-separator
option.
A query-parameters value is constructed as follows.
Start with an empty map. Tokenize the query on
the query separator. For each token, identify
the key and the value. If the token
contains an equal sign (=
), the key
is the string that precedes the first equal sign, uri
decoded, and the value is the remainder
of the token, after the first equal sign, uri decoded. If the
token does not contain an equal sign, key is the
empty string and the value is equal to the
token, uri decoded. Add the key/value pair
to the map. If the key already exists in the map, add the value
to a list of values associated with that key. The resulting map, when all
tokens have been processed, is the query-parameters map.
If the filepath is not the empty sequence, it is uri decoded. On a Windows system, any forward slashes in the path may be replaced with backslashes.
The following map is returned:
{ "uri": $uri, "scheme": scheme, "hierarchical": hierarchical, "authority": authority, "userinfo": userinfo, "host": host, "port": port, "path": path, "query": query, "fragment": fragment, "path-segments": path-segments, "query-parameters": query-parameters, "filepath": filepath }
The map should only be populated with keys that have a non-empty value (keys whose value is the empty sequence should be omitted).
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 [RFC 3986]. Implementations may add
additional keys to the map. The meaning of those keys is implementation-defined.
A dynamic error is raised [err:FOUR0001] if the URI contains an open square bracket in the authority component that is not followed by a close square bracket.
Like fn:resolve-uri
, this function handles the additional characters
allowed in [RFC 3987] IRIs in the same way that other unreserved
characters are handled.
Unlike fn:resolve-uri
, this function is not attempting to resolve
one URI against another and consequently, the errors that can arise under those
circumstances do not apply here. The fn:parse-uri
function will
accept strings that would raise errors if resolution was attempted,
see fn:build-uri
.
In the examples that follow, keys with values that are null or an empty sequence
are elided for editorial clarity. String literals that include an ampersand character
are written as string templates (for example |
|
Expression: |
parse-uri( "http://qt4cg.org/specifications/xpath-functions-40/Overview.html#parse-uri" ) |
---|---|
Result: |
map { "uri": "http://qt4cg.org/specifications/xpath-functions-40/Overview.html#parse-uri", "scheme": "http", "hierarchical": true(), "authority": "qt4cg.org", "host": "qt4cg.org", "path": "/specifications/xpath-functions-40/Overview.html", "fragment": "parse-uri", "path-segments": ("", "specifications", "xpath-functions-40", "Overview.html") } |
Expression: |
|
Result: |
map { "uri": "http://www.ietf.org/rfc/rfc2396.txt", "scheme": "http", "hierarchical": true(), "authority": "www.ietf.org", "host": "www.ietf.org", "path": "/rfc/rfc2396.txt", "path-segments": ("", "rfc", "rfc2396.txt") } |
Expression: |
|
Result: |
map { "uri": "https://example.com/path/to/file", "scheme": "https", "hierarchical": true(), "authority": "example.com", "host": "example.com", "path": "/path/to/file", "path-segments": ("", "path", "to", "file") } |
Expression: |
parse-uri( `https://example.com:8080/path?s=%22hello world%22&sort=relevance` ) |
Result: |
map { "uri": `https://example.com:8080/path?s=%22hello world%22&sort=relevance`, "scheme": "https", "hierarchical": true(), "authority": "example.com:8080", "host": "example.com", "port": "8080", "path": "/path", "query": `s=%22hello world%22&sort=relevance`, "query-parameters": map { "s": '"hello world"', "sort": "relevance" }, "path-segments": ("", "path") } |
Expression: |
|
Result: |
map { "uri": "https://user@example.com/path/to/file", "scheme": "https", "hierarchical": true(), "authority": "user@example.com", "userinfo": "user", "host": "example.com", "path": "/path/to/file", "path-segments": ("", "path", "to", "file") } |
Expression: |
|
Result: |
map { "uri": "ftp://ftp.is.co.za/rfc/rfc1808.txt", "scheme": "ftp", "hierarchical": true(), "authority": "ftp.is.co.za", "host": "ftp.is.co.za", "path": "/rfc/rfc1808.txt", "path-segments": ("", "rfc", "rfc1808.txt") } |
Expression: |
|
Result: |
map { "uri": "file:////uncname/path/to/file", "scheme": "file", "hierarchical": true(), "authority": "uncname", "host": "uncname", "path": "/path/to/file", "filepath": "/path/to/file", "path-segments": ("", "path", "to", "file") } |
Expression: |
|
Result: |
map { "uri": "file:///c:/path/to/file", "scheme": "file", "hierarchical": true(), "path": "/c:/path/to/file", "filepath": "c:/path/to/file", "path-segments": ("", "c: ", "path", "to", "file") } |
Expression: |
|
Result: |
map { "uri": "file:/C:/Program%20Files/test.jar", "scheme": "file", "hierarchical": true(), "path": "/C:/Program%20Files/test.jar", "filepath": "C:/Program Files/test.jar", "path-segments": ("", "C: ", "Program Files", "test.jar") } |
Expression: |
|
Result: |
map { "uri": "file:\\c:\path\to\file", "scheme": "file", "hierarchical": true(), "path": "/c:/path/to/file", "filepath": "c:/path/to/file", "path-segments": ("", "c: ", "path", "to", "file") } |
Expression: |
|
Result: |
map { "uri": "file:\c:\path\to\file", "scheme": "file", "hierarchical": true(), "path": "/c:/path/to/file", "filepath": "c:/path/to/file", "path-segments": ("", "c: ", "path", "to", "file") } |
Expression: |
|
Result: |
map { "uri": "c:\path\to\file", "scheme": "file", "hierarchical": true(), "path": "/c:/path/to/file", "filepath": "c:/path/to/file", "path-segments": ("", "c: ", "path", "to", "file") } |
Expression: |
|
Result: |
map { "uri": "/path/to/file", "hierarchical": true(), "path": "/path/to/file", "filepath": "/path/to/file", "path-segments": ("", "path", "to", "file") } |
Expression: |
|
Result: |
map { "uri": "#testing", "fragment": "testing" } |
Expression: |
|
Result: |
map { "uri": "?q=1", "query": "q=1", "query-parameters": map { "q": "1" } } |
Expression: |
|
Result: |
map { "uri": "ldap://[2001:db8::7]/c=GB?objectClass?one", "scheme": "ldap", "hierarchical": true(), "authority": "[2001:db8::7]", "host": "[2001:db8::7]", "path": "/c=GB", "query": "objectClass?one", "query-parameters": map { "": "objectClass?one" }, "path-segments": ("", "c=GB") } |
Expression: |
|
Result: |
map { "uri": "mailto:John.Doe@example.com", "scheme": "mailto", "hierarchical": false(), "path": "John.Doe@example.com", "path-segments": ("John.Doe@example.com") } |
Expression: |
|
Result: |
map { "uri": "news:comp.infosystems.www.servers.unix", "scheme": "news", "hierarchical": false(), "path": "comp.infosystems.www.servers.unix", "path-segments": ("comp.infosystems.www.servers.unix") } |
Expression: |
|
Result: |
map { "uri": "tel:+1-816-555-1212", "scheme": "tel", "hierarchical": false(), "path": "+1-816-555-1212", "path-segments": (" 1-816-555-1212") } |
Expression: |
|
Result: |
map { "uri": "telnet://192.0.2.16:80/", "scheme": "telnet", "hierarchical": true(), "authority": "192.0.2.16:80", "host": "192.0.2.16", "port": "80", "path": "/", "path-segments": ("", "") } |
Expression: |
parse-uri( "urn:oasis:names:specification:docbook:dtd:xml:4.1.2" ) |
Result: |
map { "uri": "urn:oasis:names:specification:docbook:dtd:xml:4.1.2", "scheme": "urn", "hierarchical": false(), "path": "oasis:names:specification:docbook:dtd:xml:4.1.2", "path-segments": "oasis:names:specification:docbook:dtd:xml:4.1.2" } |
Expression: |
|
Result: |
map { "uri": "tag:textalign.net,2015:ns", "scheme": "tag", "hierarchical": false(), "path": "textalign.net,2015:ns", "path-segments": "textalign.net,2015:ns" } |
Expression: |
|
Result: |
map { "uri": "tag:jan@example.com,1999-01-31:my-uri", "scheme": "tag", "hierarchical": false(), "path": "jan@example.com,1999-01-31:my-uri", "path-segments": "jan@example.com,1999-01-31:my-uri" } |
This example uses the algorithm described above, not an algorithm that is
specifically aware of the |
|
Expression: |
parse-uri( "jar:file:/C:/Program%20Files/test.jar!/foo/bar" ) |
Result: |
map { "uri": "jar:file:/C:/Program%20Files/test.jar!/foo/bar", "scheme": "jar", "hierarchical": false(), "path": "file:/C:/Program%20Files/test.jar!/foo/bar", "path-segments": ("file:", "C:", "Program Files", "test.jar!", "foo", "bar") } |
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: |
map { "uri": "http://www.example.org/Dürst", "scheme": "http", "hierarchical": true(), "authority": "www.example.org", "host": "www.example.org", "path": "/Dürst", "path-segments": ("", "Dürst") } |
This example demonstrates a non-standard query separator. |
|
Expression: |
parse-uri( "https://example.com:8080/path?s=%22hello world%22;sort=relevance", map { "query-separator": ";" } ) |
Result: |
map { "uri": "https://example.com:8080/path?s=%22hello world%22;sort=relevance", "scheme": "https", "hierarchical": true(), "authority": "example.com:8080", "host": "example.com", "port": "8080", "path": "/path", "query": "s=%22hello world%22;sort=relevance", "query-parameters": map { "s": '"hello world"', "sort": "relevance" }, "path-segments": ("", "path") } |
This example uses an invalid query separator so raises an error. |
|
Expression: |
parse-uri( "https://example.com:8080/path?s=%22hello world%22;;sort=relevance", map { "query-separator": ";;" } ) |
Result: |
Raises error FOXX0000. |
This example demonstrates the use of |
|
Expression: |
|
Result: |
map { "uri": "c|/path/to/file", "scheme": "file", "hierarchical": true(), "path": "/c:/path/to/file", "filepath": "c:/path/to/file", "path-segments": ("", "c:", "path", "to", "file") } |
This example demonstrates the use of |
|
Expression: |
|
Result: |
map { "uri": "file://c|/path/to/file", "scheme": "file", "hierarchical": true(), "path": "/c:/path/to/file", "filepath": "c:/path/to/file", "path-segments": ("", "c:", "path", "to", "file") } |
Proposed on 17 Oct 2022 to resolve issue #72. Accepted in principle on 15 Nov 2022, with some details still to be resolved. Updated in response to issue #389 and issue #390. Further updated on 13 September 2023 in response to comments from review in meeting 042.
Constructs a URI from the parts provided.
fn:build-uri ( |
||
$parts |
as uri-structure-record , |
|
$options |
as
|
:= map{} |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·.
A URI is composed from a scheme, authority, path, query, and fragment.
The following options are available:
Key | Meaning |
---|---|
path-separator |
Identifies the path separator
|
query-separator |
Identifies the query separator
|
allow-deprecated-features |
Indicates that deprecated URI
features should be returned
|
omit-default-ports |
Indicates that a port number that is the same as
the default port for a given scheme should be omitted.
|
unc-path |
Indicates that the URI represents
a Windows Universal Naming Convention
Path.
|
The components are derived from the contents of the $parts
map in the following way:
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 file
and the unc-path
option is true
, the scheme is delimited by a trailing :////
,
otherwise, if the URI is non-hierarchical, the scheme is delimited by
a trailing :
. For all other schemes, it is delimited by
a trailing ://
. Exactly which schemes are known to be
non-hierarchical is
·implementation-defined·.
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 should recognize
the default ports for http
(80),
https
(443), ftp
(21), and
ssh
(22). Exactly which ports are recognized is
·implementation-defined·.
If any of $userinfo
, $host
, or $port
exist, the following authority is added to the URI
under construction:
concat((if (exists($userinfo)) then $userinfo || "@" else ""), $host, (if (exists($port)) then ":" || $port else ""))
If none of userinfo
, host
, or port
is present, and authority
is present, the value of the
authority
key is added to the URI. (In this case, no attempt
is made to determine if a password or standard port are present,
the authority
value is simply added to the string.)
If the path-segments
key exists in the map, then the
path is constructed from the parts, with non-URI characters encoded:
string-join($parts?path-segments ! encode-for-uri(.), $options?path-separator)
,
otherwise the value of the path
key is used.
If the path
value is the empty sequence,
the empty string is used for the path. The path is added to the URI.
If the 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.
For each key and each value associated with
that key in turn:
If the key is the empty string, the string constructed
is the value encoded with encode-for-uri
.
Otherwise, the string constructed is the value of the
key, encoded, followed by an equal sign (=
),
followed by the value, encoded.
The query is constructed by joining the resulting
strings into a single string, separated by $options?query-separator
).
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 question mark (?
).
If the fragment
key exists in the map, then
the value of that key is added to the URI with
a preceding hash mark (#
).
The resulting URI is returned.
Expression: |
build-uri(map { "scheme": "https", "host": "qt4cg.org", "port": (), "path": "/specifications/index.html" }) |
---|---|
Result: |
|
Proposed on 17 Oct 2022 to resolve issue #72. Accepted in principle on 15 Nov 2022, with some details still to be resolved. Updated in response to issue #389 and issue #390. Further updated on 13 September 2023 in response to comments from review in meeting 042.
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
.
fn:true () as xs:boolean |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The result is equivalent to xs:boolean("1")
.
Expression | Result |
---|---|
|
|
Returns the xs:boolean
value false
.
fn:false () as xs:boolean |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The result is equivalent to xs:boolean("0")
.
Expression | Result |
---|---|
|
|
The following functions define the semantics of operators on boolean values in [XQuery 4.1: An XML Query Language] and [XML Path Language (XPath) 4.0]:
Function | Meaning |
---|---|
op:boolean-equal |
Returns true if the two arguments are the same boolean value. |
op:boolean-less-than |
Returns true if the first argument is false and the second is true . |
The ordering operator op:boolean-less-than
is provided for application purposes
and for compatibility with [XML Path Language (XPath) Version 1.0]. The [XML Schema Part 2: Datatypes Second Edition]
datatype xs:boolean
is not ordered.
Returns true
if the two arguments are the same boolean value.
Defines the semantics of the eq
operator when applied to two xs:boolean
values.
op:boolean-equal ( |
||
$value1 |
as , |
|
$value2 |
as
|
|
) as
|
The function returns true
if both arguments are true
or if
both arguments are false
. It returns false
if one of the
arguments is true
and the other argument is false
.
Returns true
if the first argument is false
and the second is true
.
Defines the
semantics of the lt
operator when applied to two xs:boolean
values. Also
used in the definition of the ge
operator.
op:boolean-less-than ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
The function returns true
if $arg1
is false
and
$arg2
is true
. Otherwise, it returns
false
.
The following functions are defined on boolean values:
Function | Meaning |
---|---|
fn:boolean |
Computes the effective boolean value of the sequence $input . |
fn:not |
Returns true if the effective boolean value of $input is
false , or false if it is true . |
Computes the effective boolean value of the sequence $input
.
fn:boolean ( |
||
$input |
as
|
|
) as
|
The function computes the effective boolean value of a sequence, defined according to the following rules. See also Section 2.4.3 Effective Boolean Value XP31.
If $input
is the empty sequence, fn:boolean
returns
false
.
If $input
is a sequence whose first item is a node,
fn:boolean
returns true
.
If $input
is a singleton value of type xs:boolean
or a
derived from xs:boolean
, fn:boolean
returns
$input
.
If $input
is a singleton value of type xs:string
or a type
derived from xs:string
, xs:anyURI
or a type derived from
xs:anyURI
, or xs:untypedAtomic
,
fn:boolean
returns false
if the operand value has
zero length; otherwise it returns true
.
If $input
is a singleton value of any numeric type or a type derived
from a numeric type, fn:boolean
returns false
if the
operand value is NaN
or is numerically equal to zero; otherwise it
returns true
.
In all cases other than those listed above, fn:boolean
raises a type error [err:FORG0006].
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
.
Expression | Result |
---|---|
let $abc := ("a", "b", "") |
|
|
|
|
|
|
|
|
|
|
Returns true
if the effective boolean value of $input
is
false
, or false
if it is true
.
fn:not ( |
||
$input |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
|
|
|
|
|
|
|
Operators are defined on the following type:
xs:duration
and on the two defined subtypes (see 8.1 Two totally ordered subtypes of duration):
xs:yearMonthDuration
xs:dayTimeDuration
No ordering relation is defined on xs:duration
values.
Two xs:duration
values may however be compared for equality.
Operations on durations (including equality comparison, casting to string, and extraction of components) all treat the duration as 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. Thus, for example, a duration of 120 seconds always gives the same result as a duration of two minutes.
Conditions such as underflow and overflow may occur with arithmetic on durations: see 9.7.1 Limits and precision
Note:
This means that in practice, 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 [Schema 1.1 Part 2]. These types must
be available in the data model whether or not the implementation supports other aspects of XSD 1.1.
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.
Function | Meaning |
---|---|
op:yearMonthDuration-less-than |
Returns true if $arg1 is a shorter duration than $arg2 . |
op:dayTimeDuration-less-than |
Returns true if $arg1 is a shorter duration than $arg2 . |
op:duration-equal |
Returns true if $arg1 and $arg2 are durations of the same
length. |
The following comparison operators are defined on the [XML Schema Part 2: Datatypes Second Edition]
duration datatypes. Each operator takes two operands of the same
type and returns an xs:boolean
result. As discussed in [XML Schema Part 2: Datatypes Second Edition], the
order relation on xs:duration
is a partial order rather than
a total order. For this reason, only equality is defined on xs:duration
.
A full complement of comparison and
arithmetic functions are defined on the two subtypes of duration described in
8.1 Two totally ordered subtypes of duration which do have a total order.
Returns true
if $arg1
is a shorter duration than $arg2
.
Defines
the semantics of the lt
operator when applied to two xs:yearMonthDuration
values. Also used in the definition of the ge
operator.
op:yearMonthDuration-less-than ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
If the number of months in $arg1
is numerically less than the
number of months in $arg2
, the function returns true
.
Otherwise, the function returns false
.
Either or both durations may be negative.
Returns true
if $arg1
is a shorter duration than $arg2
.
Defines the
semantics of the lt
operator when applied to two xs:dayTimeDuration
values.
Also used in the definition of the ge
operator.
op:dayTimeDuration-less-than ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
If the number of seconds in $arg1
is numerically less than the
number of seconds in $arg2
, the function returns true
.
Otherwise, the function returns false
.
Either or both durations may be negative
Returns true
if $arg1
and $arg2
are durations of the same
length.
Defines the
semantics of the eq
operators when applied to two xs:duration
values. Also
used in the definition of the ne
operator.
op:duration-equal ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
If the xs:yearMonthDuration
components of $arg1
and
$arg2
are equal and the xs:dayTimeDuration
components of
$arg1
and $arg2
are equal, the function returns
true
.
Otherwise, the function returns false
.
The semantics of this function are:
xs:yearMonthDuration($arg1) div xs:yearMonthDuration('P1M') eq xs:yearMonthDuration($arg2) div xs:yearMonthDuration('P1M') and xs:dayTimeDuration($arg1) div xs:dayTimeDuration('PT1S') eq xs:dayTimeDuration($arg2) div xs:dayTimeDuration('PT1S')
that is, the function returns true
if the months and seconds values of the
two durations are equal.
Note that this function, like any other, may be applied to arguments that are derived
from the types given in the function signature, including the two subtypes
xs:dayTimeDuration
and xs:yearMonthDuration
. With the
exception of the zero-length duration, no instance of xs:dayTimeDuration
can ever be equal to an instance of xs:yearMonthDuration
.
Expression | Result |
---|---|
op:duration-equal( xs:duration("P1Y"), xs:duration("P12M") ) |
|
op:duration-equal( xs:duration("PT24H"), xs:duration("P1D") ) |
|
op:duration-equal( xs:duration("P1Y"), xs:duration("P365D") ) |
|
op:duration-equal( xs:yearMonthDuration("P0Y"), xs:dayTimeDuration("P0D") ) |
|
op:duration-equal( xs:yearMonthDuration("P1Y"), xs:dayTimeDuration("P365D") ) |
|
op:duration-equal( xs:yearMonthDuration("P2Y"), xs:yearMonthDuration("P24M") ) |
|
op:duration-equal( xs:dayTimeDuration("P10D"), xs:dayTimeDuration("PT240H") ) |
|
op:duration-equal( xs:duration("P2Y0M0DT0H0M0S"), xs:yearMonthDuration("P24M") ) |
|
op:duration-equal( xs:duration("P0Y0M10D"), xs:dayTimeDuration("PT240H") ) |
|
The duration datatype may be considered to be a composite datatypes
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.
fn:years-from-duration ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
years-from-duration( xs:yearMonthDuration("P20Y15M") ) |
|
years-from-duration( xs:yearMonthDuration("-P15M") ) |
|
years-from-duration( xs:dayTimeDuration("-P2DT15H") ) |
|
Returns the number of months in a duration.
fn:months-from-duration ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
months-from-duration( xs:yearMonthDuration("P20Y15M") ) |
|
months-from-duration( xs:yearMonthDuration("-P20Y18M") ) |
|
months-from-duration( xs:dayTimeDuration("-P2DT15H0M0S") ) |
|
Returns the number of days in a duration.
fn:days-from-duration ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
days-from-duration( xs:dayTimeDuration("P3DT10H") ) |
|
days-from-duration( xs:dayTimeDuration("P3DT55H") ) |
|
days-from-duration( xs:yearMonthDuration("P3Y5M") ) |
|
Returns the number of hours in a duration.
fn:hours-from-duration ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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
. Given that a duration
is a ($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 |
---|---|
hours-from-duration( xs:dayTimeDuration("P3DT10H") ) |
|
hours-from-duration( xs:dayTimeDuration("P3DT12H32M12S") ) |
|
hours-from-duration( xs:dayTimeDuration("PT123H") ) |
|
hours-from-duration( xs:dayTimeDuration("-P3DT10H") ) |
|
Returns the number of minutes in a duration.
fn:minutes-from-duration ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
minutes-from-duration( xs:dayTimeDuration("P3DT10H") ) |
|
minutes-from-duration( xs:dayTimeDuration("-P5DT12H30M") ) |
|
Returns the number of seconds in a duration.
fn:seconds-from-duration ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
seconds-from-duration( xs:dayTimeDuration("P3DT10H12.5S") ) |
|
seconds-from-duration( xs:dayTimeDuration("-PT256S") ) |
|
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 9.7 Arithmetic operators on durations, dates and times.
Returns the result of adding two xs:yearMonthDuration
values.
Defines the semantics of the
+
operator when applied to two xs:yearMonthDuration
values.
op:add-yearMonthDurations ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
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 9.7.1 Limits and precision.
Either duration (and therefore the result) may be negative.
Expression | Result |
---|---|
op:add-yearMonthDurations( xs:yearMonthDuration("P2Y11M"), xs:yearMonthDuration("P3Y3M") ) |
|
Returns the result of subtracting one xs:yearMonthDuration
value from
another.
Defines the semantics of the
-
operator when applied to two xs:yearMonthDuration
values.
op:subtract-yearMonthDurations ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
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 9.7.1 Limits and precision.
Either duration (and therefore the result) may be negative.
Expression | Result |
---|---|
op:subtract-yearMonthDurations( xs:yearMonthDuration("P2Y11M"), xs:yearMonthDuration("P3Y3M") ) |
|
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.
op:multiply-yearMonthDuration ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
The result is the xs:yearMonthDuration
whose length in months is equal to
the result of applying the fn:round
function to the value obtained by
multiplying the length in months of $arg1
by the value of
$arg2
.
If $arg2
is positive or negative zero, the result is a zero-length
duration. If $arg2
is positive or negative infinity, the result overflows
and is handled as described in 9.7.1 Limits and precision.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
A dynamic error is raised [err:FOCA0005] if $arg2
is
NaN
.
Either duration (and therefore the result) may be negative.
Expression | Result |
---|---|
op:multiply-yearMonthDuration( xs:yearMonthDuration("P2Y11M"), 2.3 ) |
|
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.
op:divide-yearMonthDuration ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
The result is the xs:yearMonthDuration
whose length in months is equal to
the result of applying the fn:round
function to the value obtained by
dividing the length in months of $arg1
by the value of
$arg2
.
If $arg2
is positive or negative infinity, the result is a zero-length
duration. If $arg2
is positive or negative zero, the result overflows and
is handled as described in 9.7.1 Limits and precision.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
A dynamic error is raised [err:FOCA0005] if $arg2
is
NaN
.
Either operand (and therefore the result) may be negative.
Expression | Result |
---|---|
op:divide-yearMonthDuration( xs:yearMonthDuration("P2Y11M"), 1.5 ) |
|
Returns the ratio of two xs:yearMonthDuration
values.
Defines the semantics of the
div
operator when applied to two xs:yearMonthDuration
values.
op:divide-yearMonthDuration-by-yearMonthDuration ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
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 and underflow, see 9.7.1 Limits and precision.
Either duration (and therefore the result) may be negative.
Expression | Result |
---|---|
op:divide-yearMonthDuration-by-yearMonthDuration( xs:yearMonthDuration("P3Y4M"), xs:yearMonthDuration("-P1Y4M") ) |
|
The following example demonstrates how to calculate the length of an
|
|
op:divide-yearMonthDuration-by-yearMonthDuration( xs:yearMonthDuration("P3Y4M"), xs:yearMonthDuration("P1M") ) |
|
Returns the sum of two xs:dayTimeDuration
values.
Defines the semantics of the +
operator when applied to two xs:dayTimeDuration
values.
op:add-dayTimeDurations ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
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 9.7.1 Limits and precision.
Either duration (and therefore the result) may be negative.
Expression | Result |
---|---|
op:add-dayTimeDurations( xs:dayTimeDuration("P2DT12H5M"), xs:dayTimeDuration("P5DT12H") ) |
|
Returns the result of subtracting one xs:dayTimeDuration
from another.
Defines the semantics of the -
operator when applied to two xs:dayTimeDuration
values.
op:subtract-dayTimeDurations ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
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 9.7.1 Limits and precision.
Either duration (and therefore the result) may be negative.
Expression | Result |
---|---|
op:subtract-dayTimeDurations( xs:dayTimeDuration("P2DT12H"), xs:dayTimeDuration("P1DT10H30M") ) |
|
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.
op:multiply-dayTimeDuration ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
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 9.1.1 Limits and precision.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
A dynamic error is raised [err:FOCA0005] if $arg2
is
NaN
.
Either operand (and therefore the result) may be negative.
Expression | Result |
---|---|
op:multiply-dayTimeDuration( xs:dayTimeDuration("PT2H10M"), 2.1 ) |
|
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.
op:divide-dayTimeDuration ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
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 9.1.1 Limits and precision.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
A dynamic error is raised [err:FOCA0005] if $arg2
is
NaN
.
Either operand (and therefore the result) may be negative.
Expression | Result |
---|---|
op:divide-dayTimeDuration( xs:dayTimeDuration("P1DT2H30M10.5S"), 1.5 ) |
|
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.
op:divide-dayTimeDuration-by-dayTimeDuration ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
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 and underflow, see 9.7.1 Limits and precision.
Either operand (and therefore the result) may be negative.
Expression | Result |
---|---|
round-half-to-even( op:divide-dayTimeDuration-by-dayTimeDuration( xs:dayTimeDuration("P2DT53M11S"), xs:dayTimeDuration("P1DT10H") ), 4 ) |
|
This examples shows how to determine the number of seconds in a duration. |
|
op:divide-dayTimeDuration-by-dayTimeDuration( xs:dayTimeDuration("P2DT53M11S"), xs:dayTimeDuration("PT1S") ) |
|
This section defines operations on the [XML Schema Part 2: Datatypes Second Edition] date and time types.
See [Working With Timezones] for a disquisition on working with date and time values with and without timezones.
The operators described in this section are defined on the following date and time types:
xs:dateTime
xs:date
xs:time
xs:gYearMonth
xs:gYear
xs:gMonthDay
xs:gMonth
xs:gDay
The only operation defined on
xs:gYearMonth
, xs:gYear
,
xs:gMonthDay
, xs:gMonth
and xs:gDay
values is
equality comparison.
For other types, further operations are provided, including component extraction,
order comparisons, arithmetic, formatted display, and timezone
adjustment.
All minimally conforming processors must support positive year values with a minimum of 4 digits (i.e., YYYY) and a minimum fractional second precision of 1 millisecond or three digits (i.e., s.sss). However, conforming processors may set larger ·implementation-defined· limits on the maximum number of digits they support in these two situations. Processors may also choose to support the year 0000 and years with negative values. The results of operations on dates that cross the year 0000 are ·implementation-defined·.
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 9.7 Arithmetic operators on durations, dates and times. In these situations, the processor must return 00:00:00 in case of time underflow. It must raise a dynamic error [err:FODT0001] in case of overflow.
As defined in Section
3.3.2 Dates and Times
DM31, xs:dateTime
,
xs:date
, xs:time
, xs:gYearMonth
, xs:gYear
,
xs:gMonthDay
, xs:gMonth
, xs:gDay
values,
referred to collectively as date/time values, are represented as seven components or properties:
year
, month
, day
, hour
, minute
,
second
and timezone
. The first five components are
xs:integer
values. The value of the second
component is an xs:decimal
and the value of the timezone
component is an xs:dayTimeDuration
.
For all the primitive date/time datatypes, the timezone
property is optional and may or may not
be present. Depending on the datatype, some of the remaining six properties must be present and
some must be absentDM31.
Absent, or missing, properties are represented by the empty sequence.
This value is referred to as the local value in that the value retains its original timezone.
Before comparing or subtracting xs:dateTime
values, this local value must
be translated or normalized to UTC.
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, -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, (), (), (), PT8H}
.
An xs:time
with lexical
representation 24:00:00
is represented by {(), (), (), 0, 0, 0, ()}
.
A function is provided for constructing a
xs:dateTime
value from a xs:date
value and a
xs:time
value.
Function | Meaning |
---|---|
fn:dateTime |
Returns an xs:dateTime value created by combining an xs:date
and an xs:time . |
Returns an xs:dateTime
value created by combining an xs:date
and an xs:time
.
fn:dateTime ( |
||
$date |
as , |
|
$time |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 [err:FORG0008] if the two arguments both have timezones and the timezones are different.
Expression | Result |
---|---|
dateTime( xs:date("1999-12-31"), xs:time("12:00:00") ) |
|
dateTime( xs:date("1999-12-31"), xs:time("24:00:00") ) |
(This is because |
Function | Meaning |
---|---|
op:dateTime-equal |
Returns true if the two supplied xs:dateTime values refer to the same
instant in time. |
op:dateTime-less-than |
Returns true if the first argument represents an earlier instant in time
than the second argument. |
op:date-equal |
Returns true if and only if the starting instants of the two supplied
xs:date values are the same. |
op:date-less-than |
Returns true if and only if the starting instant of $arg1 is
less than the starting instant of $arg2 . Returns false
otherwise. |
op:time-equal |
Returns true if the two xs:time values represent the same
instant in time, when treated as being times on the same date, before adjusting the
timezone. |
op:time-less-than |
Returns true if the first xs:time value represents an earlier
instant in time than the second, when both are treated as being times on the same
date,
before adjusting the timezone. |
op:gYearMonth-equal |
Returns true if the two xs:gYearMonth values have the same starting
instant. |
op:gYear-equal |
Returns true if the two xs:gYear values have the same starting instant. |
op:gMonthDay-equal |
Returns true if the two xs:gMonthDay values have the same starting instant,
when considered as days in the same year. |
op:gMonth-equal |
Returns true if the two xs:gMonth values have the same starting instant,
when considered as months in the same year. |
op:gDay-equal |
Returns true if the two xs:gDay values have the same starting instant, when
considered as days in the same month of the same year. |
The following comparison operators are defined on the [XML Schema Part 2: Datatypes Second Edition]
date/time datatypes. Each operator takes two operands of the same
type and returns an xs:boolean
result.
[XML Schema Part 2: Datatypes Second Edition] also states that the order relation on date and time datatypes is not a total order but a partial order because these datatypes may or may not have a timezone. This is handled as follows. If either operand to a comparison function on date or time values does not have an (explicit) timezone then, for the purpose of the operation, an implicit timezone, provided by the dynamic context Section C.2 Dynamic Context Components XP31, is assumed to be present as part of the value. This creates a total order for all date and time values.
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 absentDM31.
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.
Note:
In [Schema 1.1 Part 2], a new 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).
Note:
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.
Note:
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.
Returns true
if the two supplied xs:dateTime
values refer to the same
instant in time.
Defines the
semantics of the eq
operator when applied to two xs:dateTime
values. Also
used in the definition of the ne
, le
and ge
operators.
op:dateTime-equal ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
If either $arg1
or $arg2
has no timezone component, the
effective value of the argument is obtained by substituting the implicit timezone from
the dynamic evaluation context.
The function then returns true
if and only if the effective value of
$arg1
is equal to the effective value of $arg2
according to
the algorithm defined in section 3.2.7.4 of [XML Schema Part 2: Datatypes Second Edition]
“Order relation on dateTime” for xs:dateTime
values with
timezones. Otherwise the function returns false
.
Expression | Result |
---|---|
Assume that the dynamic context provides an implicit timezone value of
|
|
op:dateTime-equal( xs:dateTime("2002-04-02T12:00:00-01:00"), xs:dateTime("2002-04-02T17:00:00+04:00") ) |
|
op:dateTime-equal( xs:dateTime("2002-04-02T12:00:00"), xs:dateTime("2002-04-02T23:00:00+06:00") ) |
|
op:dateTime-equal( xs:dateTime("2002-04-02T12:00:00"), xs:dateTime("2002-04-02T17:00:00") ) |
|
op:dateTime-equal( xs:dateTime("2002-04-02T12:00:00"), xs:dateTime("2002-04-02T12:00:00") ) |
|
op:dateTime-equal( xs:dateTime("2002-04-02T23:00:00-04:00"), xs:dateTime("2002-04-03T02:00:00-01:00") ) |
|
op:dateTime-equal( xs:dateTime("1999-12-31T24:00:00"), xs:dateTime("2000-01-01T00:00:00") ) |
|
op:dateTime-equal( xs:dateTime("2005-04-04T24:00:00"), xs:dateTime("2005-04-04T00:00:00") ) |
|
Returns true
if the first argument represents an earlier instant in time
than the second argument.
Defines the
semantics of the lt
operator when applied to two xs:dateTime
values. Also
used in the definition of the ge
operator.
op:dateTime-less-than ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
If either $arg1
or $arg2
has no timezone component, the
effective value of the argument is obtained by substituting the implicit timezone from
the dynamic evaluation context.
The function then returns true
if and only if the effective value of
$arg1
is less than the effective value of $arg2
according
to the algorithm defined in section 3.2.7.4 of [XML Schema Part 2: Datatypes Second Edition]
“Order relation on dateTime” for xs:dateTime
values with
timezones. Otherwise the function returns false
.
Returns true
if and only if the starting instants of the two supplied
xs:date
values are the same.
Defines the
semantics of the eq
operator when applied to two xs:date
values. Also used
in the definition of the ne
, le
and ge
operators.
op:date-equal ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The starting instant of an xs:date
is the xs:dateTime
at time
00:00:00
on that date.
The function returns the result of the expression:
op:dateTime-equal(xs:dateTime($arg1), xs:dateTime($arg2))
Expression | Result |
---|---|
op:date-equal( xs:date("2004-12-25Z"), xs:date("2004-12-25+07:00") ) |
(The starting instants are
|
op:date-equal( xs:date("2004-12-25-12:00"), xs:date("2004-12-26+12:00") ) |
|
Returns true
if and only if the starting instant of $arg1
is
less than the starting instant of $arg2
. Returns false
otherwise.
Defines the semantics
of the lt
operator when applied to two xs:date
values. Also used in the
definition of the ge
operator.
op:date-less-than ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
The starting instant of an xs:date
is the xs:dateTime
at time
00:00:00
on that date.
The function returns the result of the expression:
op:dateTime-less-than(xs:dateTime($arg1), xs:dateTime($arg2))
Expression | Result |
---|---|
op:date-less-than( xs:date("2004-12-25Z"), xs:date("2004-12-25-05:00") ) |
|
op:date-less-than( xs:date("2004-12-25-12:00"), xs:date("2004-12-26+12:00") ) |
|
Returns true
if the two xs:time
values represent the same
instant in time, when treated as being times on the same date, before adjusting the
timezone.
Defines the
semantics of the eq
operator when applied to two xs:time
values. Also used
in the definition of the ne
, le
and ge
operators.
op:time-equal ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
Each of the supplied xs:time
values is expanded to an
xs:dateTime
value by associating the time with an arbitrary date. The
function returns the result of comparing these two xs:dateTime
values using
op:dateTime-equal
.
The result of the function is thus the same as the value of the expression:
op:dateTime-equal( dateTime(xs:date('1972-12-31'), $arg1), dateTime(xs:date('1972-12-31'), $arg2))
Expression | Result |
---|---|
Assume that the date components from the reference |
|
op:time-equal( xs:time("08:00:00+09:00"), xs:time("17:00:00-06:00") ) |
(The |
op:time-equal( xs:time("21:30:00+10:30"), xs:time("06:00:00-05:00") ) |
|
op:time-equal( xs:time("24:00:00+01:00"), xs:time("00:00:00+01:00") ) |
(This not the result one might expect. For |
Returns true
if the first xs:time
value represents an earlier
instant in time than the second, when both are treated as being times on the same date,
before adjusting the timezone.
Defines the semantics
of the lt
operator when applied to two xs:time
values. Also used in the
definition of the ge
operator.
op:time-less-than ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
Each of the supplied xs:time
values is expanded to an
xs:dateTime
value by associating the time with an arbitrary date. The
function returns the result of comparing these two xs:dateTime
values using
op:dateTime-less-than
.
The result of the function is thus the same as the value of the expression:
op:dateTime-less-than( dateTime(xs:date('1972-12-31'), $arg1), dateTime(xs:date('1972-12-31'), $arg2))
Expression | Result |
---|---|
Assume that the dynamic context provides an implicit timezone value of
|
|
op:time-less-than( xs:time("12:00:00"), xs:time("23:00:00+06:00") ) |
|
op:time-less-than( xs:time("11:00:00"), xs:time("17:00:00Z") ) |
|
op:time-less-than( xs:time("23:59:59"), xs:time("24:00:00") ) |
|
Returns true
if the two xs:gYearMonth
values have the same starting
instant.
Defines the
semantics of the eq
operator when applied to two xs:gYearMonth
values. Also
used in the definition of the ne
operator.
op:gYearMonth-equal ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template xxxx-xx-01T00:00:00
. The function
returns the result of comparing these two starting instants using
op:dateTime-equal
.
Assume that the dynamic context provides an implicit timezone value of
|
|
|
|
|
Returns true
if the two xs:gYear
values have the same starting instant.
Defines the semantics
of the eq
operator when applied to two xs:gYear
values. Also used in the
definition of the ne
operator.
op:gYear-equal ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template xxxx-01-01T00:00:00
. The function
returns the result of comparing these two starting instants using
op:dateTime-equal
.
Expression | Result |
---|---|
Assume that the dynamic context provides an implicit timezone value of
|
|
|
|
op:gYear-equal( xs:gYear("1976-05:00"), xs:gYear("1976") ) |
|
Returns true
if the two xs:gMonthDay
values have the same starting instant,
when considered as days in the same year.
Defines the
semantics of the eq
operator when applied to two xs:gMonthDay
values. Also
used in the definition of the ne
operator.
op:gMonthDay-equal ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template 1972-xx-xxT00:00:00
or an equivalent.
The function returns the result of comparing these two starting instants using
op:dateTime-equal
.
Expression | Result |
---|---|
Assume that the dynamic context provides an implicit timezone value of
|
|
op:gMonthDay-equal( xs:gMonthDay("--12-25-14:00"), xs:gMonthDay("--12-26+10:00") ) |
( The starting instants are |
op:gMonthDay-equal( xs:gMonthDay("--12-25"), xs:gMonthDay("--12-26Z") ) |
|
Returns true
if the two xs:gMonth
values have the same starting instant,
when considered as months in the same year.
Defines the
semantics of the eq
operator when applied to two xs:gMonth
values. Also used
in the definition of the ne
operator.
op:gMonth-equal ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template 1972-xx-01T00:00:00
or an equivalent.
The function returns the result of comparing these two starting instants using
op:dateTime-equal
.
Expression | Result |
---|---|
Assume that the dynamic context provides an implicit timezone value of
|
|
op:gMonth-equal( xs:gMonth("--12-14:00"), xs:gMonth("--12+10:00") ) |
( The starting instants are |
op:gMonth-equal( xs:gMonth("--12"), xs:gMonth("--12Z") ) |
|
Returns true
if the two xs:gDay
values have the same starting instant, when
considered as days in the same month of the same year.
Defines the semantics
of the eq
operator when applied to two xs:gDay
values. Also used in the
definition of the ne
operator.
op:gDay-equal ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template 1972-12-xxT00:00:00
or an equivalent.
The function returns the result of comparing these two starting instants using
op:dateTime-equal
.
Expression | Result |
---|---|
Assume that the dynamic context provides an implicit timezone value of
|
|
op:gDay-equal( xs:gDay("---25-14:00"), xs:gDay("---25+10:00") ) |
( The starting instants are |
|
|
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.
Note:
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 an xs:dateTime . |
fn:month-from-dateTime |
Returns the month component of an xs:dateTime . |
fn:day-from-dateTime |
Returns the day component of an xs:dateTime . |
fn:hours-from-dateTime |
Returns the hours component of an xs:dateTime . |
fn:minutes-from-dateTime |
Returns the minute component of an xs:dateTime . |
fn:seconds-from-dateTime |
Returns the seconds component of an xs:dateTime . |
fn:timezone-from-dateTime |
Returns the timezone component of an xs:dateTime . |
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 . |
Returns the year component of an xs:dateTime
.
fn:year-from-dateTime ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the year
component in the local value of $value
. The result may be negative.
Ignoring complications that arise with midnight on the last day of the year, the year returned is the same numeric value that appears in the lexical representation, which for negative years means the meaning may vary depending on whether XSD 1.0 or XSD 1.1 conventions are in use.
Expression | Result |
---|---|
year-from-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") ) |
|
year-from-dateTime( xs:dateTime("1999-05-31T21:30:00-05:00") ) |
|
year-from-dateTime( xs:dateTime("1999-12-31T19:20:00") ) |
|
year-from-dateTime( xs:dateTime("1999-12-31T24:00:00") ) |
|
year-from-dateTime( xs:dateTime("-0002-06-06T00:00:00") ) |
(The result is the same whether XSD 1.0 or 1.1 is in use, despite the absence of a year 0 in the XSD 1.0 value space.) |
Returns the month component of an xs:dateTime
.
fn:month-from-dateTime ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
month-from-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") ) |
|
month-from-dateTime( xs:dateTime("1999-12-31T19:20:00-05:00") ) |
|
month-from-dateTime( adjust-dateTime-to-timezone( xs:dateTime("1999-12-31T19:20:00-05:00"), xs:dayTimeDuration("PT0S") ) ) |
|
Returns the day component of an xs:dateTime
.
fn:day-from-dateTime ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between 1
and
31
, both inclusive, representing the day component in the
local value of $value
.
Expression | Result |
---|---|
day-from-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") ) |
|
day-from-dateTime( xs:dateTime("1999-12-31T20:00:00-05:00") ) |
|
day-from-dateTime( adjust-dateTime-to-timezone( xs:dateTime("1999-12-31T19:20:00-05:00"), xs:dayTimeDuration("PT0S") ) ) |
|
Returns the hours component of an xs:dateTime
.
fn:hours-from-dateTime ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between 0
and
23
, both inclusive, representing the hours component in the local value
of $value
.
Expression | Result |
---|---|
hours-from-dateTime( xs:dateTime("1999-05-31T08:20:00-05:00") ) |
|
hours-from-dateTime( xs:dateTime("1999-12-31T21:20:00-05:00") ) |
|
hours-from-dateTime( adjust-dateTime-to-timezone( xs:dateTime("1999-12-31T21:20:00-05:00"), xs:dayTimeDuration("PT0S") ) ) |
|
hours-from-dateTime( xs:dateTime("1999-12-31T12:00:00") ) |
|
hours-from-dateTime( xs:dateTime("1999-12-31T24:00:00") ) |
|
Returns the minute component of an xs:dateTime
.
fn:minutes-from-dateTime ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
value between 0
and 59
, both inclusive, representing the minute component in the local value of
$value
.
Expression | Result |
---|---|
minutes-from-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") ) |
|
minutes-from-dateTime( xs:dateTime("1999-05-31T13:30:00+05:30") ) |
|
Returns the seconds component of an xs:dateTime
.
fn:seconds-from-dateTime ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") ) |
|
Returns the timezone component of an xs:dateTime
.
fn:timezone-from-dateTime ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") ) |
|
timezone-from-dateTime( xs:dateTime("2000-06-12T13:20:00Z") ) |
|
timezone-from-dateTime( xs:dateTime("2004-08-27T00:00:00") ) |
|
Returns the year component of an xs:date
.
fn:year-from-date ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the year in the
local value of $value
. The value may be negative.
The year returned is the same numeric value that appears in the lexical representation, which for negative years means the meaning may vary depending on whether XSD 1.0 or XSD 1.1 conventions are in use.
Expression | Result |
---|---|
year-from-date( xs:date("1999-05-31") ) |
|
year-from-date( xs:date("2000-01-01+05:00") ) |
|
year-from-date( xs:date("-0002-06-01") ) |
(The result is the same whether XSD 1.0 or 1.1 is in use, despite the absence of a year 0 in the XSD 1.0 value space.) |
Returns the month component of an xs:date
.
fn:month-from-date ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
month-from-date( xs:date("1999-05-31-05:00") ) |
|
month-from-date( xs:date("2000-01-01+05:00") ) |
|
Returns the day component of an xs:date
.
fn:day-from-date ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
day-from-date( xs:date("1999-05-31-05:00") ) |
|
day-from-date( xs:date("2000-01-01+05:00") ) |
|
Returns the timezone component of an xs:date
.
fn:timezone-from-date ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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-date( xs:date("1999-05-31-05:00") ) |
|
timezone-from-date( xs:date("2000-06-12Z") ) |
|
Returns the hours component of an xs:time
.
fn:hours-from-time ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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( adjust-time-to-timezone( xs:time("01:23:00+05:00"), xs:dayTimeDuration("PT0S") ) ) |
|
|
|
Returns the minutes component of an xs:time
.
fn:minutes-from-time ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
|
|
Returns the seconds component of an xs:time
.
fn:seconds-from-time ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:decimal
value greater than or equal
to zero and less than 60, representing the seconds and fractional seconds in the local
value of $value
.
Expression | Result |
---|---|
|
|
Returns the timezone component of an xs:time
.
fn:timezone-from-time ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
|
|
|
|
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. |
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.
fn:adjust-dateTime-to-timezone ( |
||
$value |
as , |
|
$timezone |
as
|
:= fn:implicit-timezone() |
) as
|
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $timezone
is not specified, then the effective value of
$timezone
is the value of the implicit timezone in the dynamic
context.
If $value
is the empty sequence, then the function returns the empty
sequence.
If $value
does not have a timezone component and $timezone
is
the empty sequence, then the result is $value
.
If $value
does not have a timezone component and $timezone
is
not the empty sequence, then the result is $value
with $timezone
as the timezone component.
If $value
has a timezone component and $timezone
is the empty
sequence, then the result is the local value of $value
without its timezone
component.
If $value
has a timezone component and $timezone
is not the
empty sequence, then the result is the xs:dateTime
value that is equal to
$value
and that has a timezone component equal to
$timezone
.
A dynamic error is raised [err:FODT0003] if $timezone
is less than -PT14H
or greater than PT14H
or is not an
integral number of minutes.
Expression | Result |
---|---|
Assume the dynamic context provides an implicit timezone of |
|
let $tz-10 := xs:dayTimeDuration("-PT10H") |
|
adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00') ) |
|
adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00-07:00') ) |
|
adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00'), $tz-10 ) |
|
adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00-07:00'), $tz-10 ) |
|
adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00-07:00'), xs:dayTimeDuration("PT10H") ) |
|
adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T00:00:00+01:00'), xs:dayTimeDuration("-PT8H") ) |
|
adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00'), () ) |
|
adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00-07:00'), () ) |
|
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-date-to-timezone ( |
||
$value |
as , |
|
$timezone |
as
|
:= fn:implicit-timezone() |
) as
|
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $timezone
is not specified, then the effective value of
$timezone
is the value of the implicit timezone in the dynamic
context.
If $value
is the empty sequence, then the function returns the empty
sequence.
If $value
does not have a timezone component and $timezone
is
the empty sequence, then the result is $value
.
If $value
does not have a timezone component and $timezone
is
not the empty sequence, then the result is $value
with $timezone
as the timezone component.
If $value
has a timezone component and $timezone
is the empty
sequence, then the result is the local value of $value
without its timezone
component.
If $value
has a timezone component and $timezone
is not the
empty sequence, then the function returns the value of the expression:
Let $dt
be the value of fn:dateTime($arg,
xs:time('00:00:00'))
.
Let $adt
be the value of fn:adjust-dateTime-to-timezone($dt,
$timezone)
The function returns the value of xs:date($adt)
A dynamic error is raised [err:FODT0003] if $timezone
is less than -PT14H
or greater than PT14H
or is not an
integral number of minutes.
Expression | Result |
---|---|
Assume the dynamic context provides an implicit timezone of |
|
let $tz-10 := xs:dayTimeDuration("-PT10H") |
|
adjust-date-to-timezone( xs:date("2002-03-07") ) |
|
adjust-date-to-timezone( xs:date("2002-03-07-07:00") ) |
( |
adjust-date-to-timezone( xs:date("2002-03-07"), $tz-10 ) |
|
adjust-date-to-timezone( xs:date("2002-03-07-07:00"), $tz-10 ) |
( |
adjust-date-to-timezone( xs:date("2002-03-07"), () ) |
|
adjust-date-to-timezone( xs:date("2002-03-07-07:00"), () ) |
|
Adjusts an xs:time
value to a specific timezone, or to no timezone at
all.
fn:adjust-time-to-timezone ( |
||
$value |
as , |
|
$timezone |
as
|
:= fn:implicit-timezone() |
) as
|
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $timezone
is not specified, then the effective value of
$timezone
is the value of the implicit timezone in the dynamic
context.
If $value
is the empty sequence, then the function returns the empty
sequence.
If $value
does not have a timezone component and $timezone
is
the empty sequence, then the result is $value
.
If $value
does not have a timezone component and $timezone
is
not the empty sequence, then the result is $value
with $timezone
as the timezone component.
If $value
has a timezone component and $timezone
is the empty
sequence, then the result is the localized value of $value
without its
timezone component.
If $value
has a timezone component and $timezone
is not the
empty sequence, then:
Let $dt
be the xs:dateTime
value
fn:dateTime(xs:date('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 [err:FODT0003] if $timezone
is less than -PT14H
or greater than PT14H
or if does not
contain an integral number of minutes.
Expression | Result |
---|---|
Assume the dynamic context provides an implicit timezone of |
|
let $tz-10 := xs:dayTimeDuration("-PT10H") |
|
adjust-time-to-timezone( xs:time("10:00:00") ) |
|
adjust-time-to-timezone( xs:time("10:00:00-07:00") ) |
|
adjust-time-to-timezone( xs:time("10:00:00"), $tz-10 ) |
|
adjust-time-to-timezone( xs:time("10:00:00-07:00"), $tz-10 ) |
|
adjust-time-to-timezone( xs:time("10:00:00"), () ) |
|
adjust-time-to-timezone( xs:time("10:00:00-07:00"), () ) |
|
adjust-time-to-timezone( xs:time("10:00:00-07:00"), xs:dayTimeDuration("PT10H") ) |
|
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 [XML Schema Part 2: Datatypes Second Edition] describes an algorithm for
performing such operations.
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 must return P0M or PT0S in case of duration underflow and 00:00:00 in case of time underflow. It must raise a dynamic error [err:FODT0001] in case of overflow.
The value spaces of the two totally ordered subtypes of
xs:duration
described in 8.1 Two totally ordered subtypes of duration are
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
8.4 Arithmetic operators on durations. In these situations the processor
must return zero in case of numeric underflow and P0M
or PT0S in case of duration underflow. It must raise a
dynamic error [err:FODT0002] in case of overflow.
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.
op:subtract-dateTimes ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
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 Section
C.2 Dynamic Context Components
XP31.) is
assumed to be present as part of the value.
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 [XML Schema Part 2: Datatypes Second Edition], and expressed as a
xs:dayTimeDuration
.
If the normalized value of $arg1
precedes in time the normalized value of
$arg2
, then the returned value is a negative duration.
Expression | Result |
---|---|
Assume that the dynamic context provides an implicit timezone value of
|
|
op:subtract-dateTimes( xs:dateTime("2000-10-30T06:12:00"), xs:dateTime("1999-11-28T09:00:00Z") ) |
|
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.
op:subtract-dates ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
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 Section
C.2 Dynamic Context Components
XP31.) is
assumed to be present as part of the value.
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
|
|
op:subtract-dates( xs:date("2000-10-30"), xs:date("1999-11-28") ) |
(The normalized values of the two starting instants are |
Now assume that the dynamic context provides an implicit timezone value of
|
|
op:subtract-dates( xs:date("2000-10-30"), xs:date("1999-11-28Z") ) |
( The normalized values of the two starting instants are |
op:subtract-dates( xs:date("2000-10-15-05:00"), xs:date("2000-10-10+02:00") ) |
|
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.
op:subtract-times ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The function returns the result of the expression:
op-subtract-dateTimes( dateTime(xs:date('1972-12-31'), $arg1), dateTime(xs:date('1972-12-31'), $arg2))
Any other reference date would work equally well.
Expression | Result |
---|---|
Assume that the dynamic context provides an implicit timezone value of
|
|
op:subtract-times( xs:time("11:12:00Z"), xs:time("04:00:00") ) |
(This is obtained by subtracting from the |
op:subtract-times( xs:time("11:00:00-05:00"), xs:time("21:30:00+05:30") ) |
(The two |
op:subtract-times( xs:time("17:00:00-06:00"), xs:time("08:00:00+09:00") ) |
(The two normalized |
op:subtract-times( xs:time("24:00:00"), xs:time("23:59:59") ) |
(The two normalized |
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.
op:add-yearMonthDuration-to-dateTime ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the result of adding $arg2
to the value of
$arg1
using the algorithm described in Appendix E of [XML Schema Part 2: Datatypes Second Edition], disregarding the rule about leap seconds. If $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 |
---|---|
op:add-yearMonthDuration-to-dateTime( xs:dateTime("2000-10-30T11:12:00"), xs:yearMonthDuration("P1Y2M") ) |
|
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.
op:add-dayTimeDuration-to-dateTime ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the result of adding $arg2
to the value of
$arg1
using the algorithm described in Appendix E of [XML Schema Part 2: Datatypes Second Edition], disregarding the rule about leap seconds. If $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 |
---|---|
op:add-dayTimeDuration-to-dateTime( xs:dateTime("2000-10-30T11:12:00"), xs:dayTimeDuration("P3DT1H15M") ) |
|
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.
op:subtract-yearMonthDuration-from-dateTime ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
op:subtract-yearMonthDuration-from-dateTime( xs:dateTime("2000-10-30T11:12:00"), xs:yearMonthDuration("P1Y2M") ) |
|
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
op:subtract-dayTimeDuration-from-dateTime ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
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 |
---|---|
op:subtract-dayTimeDuration-from-dateTime( xs:dateTime("2000-10-30T11:12:00"), xs:dayTimeDuration("P3DT1H15M") ) |
|
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.
op:add-yearMonthDuration-to-date ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
op:add-yearMonthDuration-to-date( xs:date("2000-10-30"), xs:yearMonthDuration("P1Y2M") ) |
|
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.
op:add-dayTimeDuration-to-date ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
op:add-dayTimeDuration-to-date( xs:date("2004-10-30Z"), xs:dayTimeDuration("P2DT2H30M0S") ) |
( The starting instant of the first argument is the
|
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.
op:subtract-yearMonthDuration-from-date ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Returns the xs:date
computed by negating $arg2
and adding the
result to $arg1
using the function
op:add-yearMonthDuration-to-date
.
Expression | Result |
---|---|
op:subtract-yearMonthDuration-from-date( xs:date("2000-10-30"), xs:yearMonthDuration("P1Y2M") ) |
|
op:subtract-yearMonthDuration-from-date( xs:date("2000-02-29Z"), xs:yearMonthDuration("P1Y") ) |
|
op:subtract-yearMonthDuration-from-date( xs:date("2000-10-31-05:00"), xs:yearMonthDuration("P1Y1M") ) |
|
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
.
op:subtract-dayTimeDuration-from-date ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Returns the xs:date
computed by negating $arg2
and adding the
result to $arg1
using the function
op:add-dayTimeDuration-to-date
.
Expression | Result |
---|---|
op:subtract-dayTimeDuration-from-date( xs:date("2000-10-30"), xs:dayTimeDuration("P3DT1H15M") ) |
|
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.
op:add-dayTimeDuration-to-time ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
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 |
---|---|
op:add-dayTimeDuration-to-time( xs:time("11:12:00"), xs:dayTimeDuration("P3DT1H15M") ) |
|
op:add-dayTimeDuration-to-time( xs:time("23:12:00+03:00"), xs:dayTimeDuration("P1DT3H15M") ) |
(That is, |
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.
op:subtract-dayTimeDuration-from-time ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the result of negating $arg2
and adding the result to
$arg1
using the function op:add-dayTimeDuration-to-time
.
Expression | Result |
---|---|
op:subtract-dayTimeDuration-from-time( xs:time("11:12:00"), xs:dayTimeDuration("P3DT1H15M") ) |
|
op:subtract-dayTimeDuration-from-time( xs:time("08:20:00-05:00"), xs:dayTimeDuration("P23DT10H10M") ) |
|
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 signatures are presented first, followed by the rules which apply to each of the functions.
Returns a string containing an xs:dateTime
value formatted for display.
fn:format-dateTime ( |
||
$value |
as , |
|
$picture |
as , |
|
$language |
as
|
:= () , |
$calendar |
as
|
:= () , |
$place |
as
|
:= () |
) as
|
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default calendar, and default language, and default place, and implicit timezone.
The five-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone, and namespaces.
The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.
Returns a string containing an xs:date
value formatted for display.
fn:format-date ( |
||
$value |
as , |
|
$picture |
as , |
|
$language |
as
|
:= () , |
$calendar |
as
|
:= () , |
$place |
as
|
:= () |
) as
|
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default calendar, and default language, and default place, and implicit timezone.
The five-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone, and namespaces.
The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.
Returns a string containing an xs:time
value formatted for display.
fn:format-time ( |
||
$value |
as , |
|
$picture |
as , |
|
$language |
as
|
:= () , |
$calendar |
as
|
:= () , |
$place |
as
|
:= () |
) as
|
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default calendar, and default language, and default place, and implicit timezone.
The five-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone, and namespaces.
The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.
The fn:format-dateTime
, fn:format-date
,
and fn:format-time
functions format $value
as a string using
the picture string specified by the $picture
argument,
the calendar specified by the $calendar
argument,
the language specified by the $language
argument,
and the country or other place name specified by the $place
argument.
The result of the function is the formatted string representation of the supplied
xs:dateTime
, xs:date
, or xs:time
value.
[Definition] The three
functions fn:format-dateTime
, fn:format-date
,
and fn:format-time
are referred to collectively as the
date formatting functions.
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 an empty sequence.
For details of the $language
, $calendar
, and
$place
arguments, see 9.8.4.8 The language, calendar, and place arguments.
In general, the use of an invalid $picture
,
$language
, $calendar
, or
$place
argument results in a dynamic error [err:FOFD1340]. By contrast,
use of an option in any of these arguments that is valid but not supported by the implementation is
not an error, and in these cases the implementation is required to output the value in a fallback
representation. More detailed rules are given below.
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 must be doubled. The variable markers are replaced in the result by strings representing aspects of the date and/or time to be formatted. These are described in detail below.
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 component specifier indicates the component of the date or time that is required, and takes the following values:
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 [err:FOFD1340] if the syntax of the picture is incorrect.
A dynamic error is reported [err:FOFD1350]
if a component specifier within the picture
refers to components that are not available in the given type of $value
,
for example if the picture supplied to the fn:format-time
refers
to the year, month, or day component.
It is not an error to include a timezone component when the supplied value has no timezone. In these circumstances the timezone component will be ignored.
The first presentation modifier indicates the style in which the value of a component is to be represented. Its value may be either:
any format token permitted as a primary format token in the second argument
of the fn:format-integer
function, indicating
that the value of the component is to be output numerically using the specified number format (for example,
1
, 01
, i
, I
, w
, W
,
or Ww
) or
the format token n
, N
,
or Nn
, indicating that the value of the component is to be output by name,
in 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 ·implementation-defined· fallback representation.
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 must use the default presentation modifier for that component.
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 ·implementation-defined·.
This has the same meaning as in the second argument of fn:format-integer . |
either c or o |
indicates cardinal or ordinal numbering respectively, for example
7 or seven for a cardinal number, or 7th ,
seventh , or 7º
for an ordinal number.
This has the same meaning as
in the second argument of fn:format-integer .
The actual representation of the ordinal form of a number
may depend not only on the language, but also on the grammatical context (for example,
in some languages it must agree in gender). |
Note:
Although the formatting rules are expressed in terms of the rules
for format tokens in fn:format-integer
, the formats actually used may be specialized
to the numbering of date components where appropriate. For example, in Italian, it is conventional to
use an ordinal number (primo
) for the first day of the month, and cardinal numbers
(due, tre, quattro ...
) for the remaining days. A processor may therefore use
this convention to number days of the month, ignoring the presence or absence of the ordinal
presentation modifier.
Whether or not a presentation modifier is included, a width modifier may be supplied. This indicates the number of characters to be included in the representation of the value.
The width modifier, if present, is introduced by a comma. It takes the form:
"," 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 ([err:FOFD1340]) is raised if
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 decimal digit pattern has the meaning given in 4.6.1 fn:format-integer.
If the first presentation modifier takes the form of a decimal digit pattern:
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).
Note:
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 9.8.4.3 Formatting Integer-Valued Date/Time Components, except that the value of the year as output is the value of the year component of the supplied value modulo ten to the power N where N is determined as follows:
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 decimal digit pattern, then the output is
·implementation-defined·.
The sequence of digits in the conventional decimal representation of the fractional seconds component
is reversed, with insignificant zeroes removed, and the result is treated as an integer. For example, if the
seconds value is 25.8235
, the reversed fractional seconds value is 5328
.
The reversed fractional seconds value is formatted using the reversed decimal digit pattern according to the
rules of the fn:format-integer
function. Given the examples above, the result is 5'328
The resulting string is reversed. In our example, the result is 823'5
.
If the result contains more digits than the number of 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.
Note:
The reason for presenting the algorithm in this way is that it enables maximum re-use of the rules defined for
fn:format-integer
. Since the fractional seconds value is not properly an integer, the rules do not
work if used directly: for example, the positions of grouping separators need to be counted from the left rather
than from the right. Implementations, as always, are free to use a different algorithm that yields the same result.
Note:
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 recommended that this option
should be used only if a country code (see [ISO 3166-1]) or IANA timezone name (see [IANA Timezone Database]) is supplied in the $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 9.8.4.2 The Width Modifier, but it is never shortened.
This section applies to the remaining components: P
(am/pm marker), C
(calendar),
and E
(era).
The output for these components is entirely ·implementation-defined·.
The default presentation modifier for these components is 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 9.8.4.8 The language, calendar, and place arguments.
The set of languages, calendars, and places that are supported in the ·date formatting functions· is ·implementation-defined·. When any of these arguments is omitted or is an empty sequence, an ·implementation-defined· default value is used.
If the fallback representation uses a different calendar from that requested,
the output string must identify the calendar actually used, for example by
prefixing the string with [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 must identify the language actually
used, for example by prefixing the string with [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 should be output in the default format for
that component.
The $language
argument specifies the language to be used for the result string
of the function. The value of the argument should be either the empty sequence
or a value that would be valid for the xml:lang
attribute (see [XML]).
Note that this permits the identification of sublanguages
based on country codes (from [ISO 3166-1]) as well as identification of dialects
and of regions within a country.
If the $language
argument is omitted or is set to an empty sequence, or if it is set to an invalid value or a
value that the implementation does not recognize,
then the processor uses the default language defined in the dynamic context.
The language is used to select the appropriate 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 should not be used to override the
language or any sublanguage that is specified as part of the language
argument.
The choice of the names and abbreviations used in any given language is
·implementation-defined·. For example,
one implementation might abbreviate July as Jul
while another uses Jly
. In German,
one implementation might represent Saturday as Samstag
while another
uses Sonnabend
. Implementations may provide mechanisms allowing users to
control such choices.
Where ordinal numbers are used, the selection of the correct representation of the ordinal (for example, the linguistic gender) may depend on the component being formatted and on its textual context in the picture string.
The calendar
attribute specifies that the dateTime
, date
,
or time
supplied in the $value
argument must be
converted to a value in the specified calendar and then converted to a string using the
conventions of that calendar.
The calendar value if present must be a valid EQName
(dynamic error: [err:FOFD1340]).
If it is a lexical 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 must identify a calendar with a designator specified below
(dynamic error: [err:FOFD1340]).
If the expanded QName is in a namespace then it identifies the calendar in an ·implementation-defined· way.
If the $calendar
argument is omitted or is set to an empty sequence
then the default calendar defined in the dynamic context is used.
Note:
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 [XML Schema Part 2: Datatypes Second Edition].
There may be ambiguities when dates are recorded using different calendars.
For example, the start of a new day is not simultaneous in different calendars,
and may also vary geographically (for example, based on the time of sunrise or sunset).
Translation of dates is therefore more reliable when the time of day is also known, and
when the geographic location is known.
When translating dates between
one calendar and another, the processor may take account of the values
of the $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 [Calendrical Calculations].
Designator | Calendar |
---|---|
AD | Anno Domini (Christian Era) |
AH | Anno Hegirae (Muhammedan Era) |
AME | Mauludi Era (solar years since Mohammed’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 | Mohammedan Solar Era (Iran) |
SS | Saka Samvat |
TE | Tripurabda Era |
VE | Vikrama Era |
VS | Vikrama Samvat Era |
At least one of the above calendars must be supported. It is ·implementation-defined· which calendars are supported.
The ISO 8601 calendar ([ISO 8601]),
which is included in the above list and designated 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 [XML Schema Part 2: Datatypes Second Edition]. The era (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.
Note:
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
·date formatting functions· produce a representation
of this absolute point in time, but denoted in a possibly different calendar. So,
for example, the date whose lexical representation in XML Schema is 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 should be used when the
requested calendar is OS (Julian) or AD (Gregorian). When the requested
calendar is ISO, however, the conventions of ISO 8601 should be followed:
here the year before +0001 is numbered zero. In [XML Schema Part 2: Datatypes Second Edition] (version 1.0),
the value space for 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 an empty sequence, then the default place defined in the dynamic context is used.
If the value is supplied, and is not the empty sequence, then it should
either be a country code or an IANA timezone name.
If the value does not take this form, or if its value is not recognized
by the implementation, then the default place defined in the dynamic context is used.
Country codes are defined in [ISO 3166-1]. Examples are "de"
for Germany
and "jp"
for Japan. Implementations may also allow the use
of codes representing subdivisions of a country from ISO 3166-2, or codes representing formerly used names of
countries from ISO 3166-3
IANA timezone names are defined in the IANA timezone database [IANA Timezone Database].
Examples are "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
may be used to provide additional information when converting dates between
calendars or when deciding how individual components of the date and time are to be formatted.
For example, different countries using the Old Style (Julian) calendar started the new year on different
days, and some countries used variants of the calendar that were out of synchronization as a result of
differences in calculating leap years.
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.
fn:parse-ietf-date ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 an empty sequence, the result is an empty sequence.
The dayname
, if present, is ignored.
The daynum
, monthname
, and year
supply the day,
month, and year of the resulting xs:dateTime
value. A two-digit year
must have 1900 added to it. A year such as 0070 is to be treated
as given; negative years are not permitted.
The hours
, minutes
, and seconds
(including
fractional seconds) values supply the corresponding components of the resulting
xs:dateTime
value; if the seconds
value
or the fractional seconds value is absent then zero
is assumed.
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 [err:FORG0010] if the input does
not match the grammar, or if the resulting date/time value is invalid
(for example, "31 February"
).
The parse-ietf-date
function attempts to interpret its input as a date
in any of the three formats specified by HTTP [RFC 2616].
These formats are used widely on the Internet to represent timestamps, and were specified in:
[RFC 822] (electronic mail), extended in [RFC 1123] to allow four-digit years;
[RFC 850] (Usenet Messages), obsoleted by [RFC 1036];
POSIX asctime()
format
[RFC 2616] (HTTP) officially uses a subset of those three formats restricted to GMT.
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"
,
and the timezone offset "-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 [RFC 3339] which is based on a profile of ISO 8601 similar to that already used in XPath and XSD, but the “approximate” [RFC 822] format described here is very widely used.
An [RFC 1123] date can be generated approximately using fn:format-dateTime
with a picture
string of "[FNn3], [D01] [MNn3] [Y04] [H01]:[m01]:[s01] [Z0000]"
.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
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 these functions.
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.
fn:QName ( |
||
$uri |
as , |
|
$qname |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 [err:FOCA0002] if $qname
does not have the correct lexical form for an instance of xs:QName
.
A dynamic error is raised [err:FOCA0002] if $uri
is the zero-length string or the empty sequence, and the value of
$qname
contains a colon (:
).
A dynamic error may be raised [err:FOCA0002] if
$uri
is not a valid URI (XML Namespaces 1.0) or IRI (XML Namespaces
1.1).
|
|
|
Returns an xs:QName
value formed by parsing an EQName.
fn:parse-QName ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on namespaces.
Leading and trailing whitespace in $value
is stripped.
If the resulting $value
is castable to xs:NCName
,
the result is fn:QName("", $value)
: that is, a QName in no namespace.
Otherwise, if the resulting $value
is in the lexical space of xs:QName
(that is, if it is in the form prefix:local
), the result is xs:QName($value)
.
Note that this result depends on the in-scope prefixes in the static context, and may result in
various error conditions.
Otherwise, if the resulting $value
takes the form of an
XPath BracedURILiteralXP40
(that is, Q{uri}local
, where the uri
part may be zero-length),
then the result is fn:QName(uri, local)
.
The rules used for parsing a BracedURILiteralXP40 within a
URIQualifiedNameXP40 are the XPath rules,
not the XQuery rules (the XQuery rules require special characters such as <
and &
to be escaped).
A dynamic error is raised [err:FOCA0002]
if the supplied value of $value
, after whitespace normalization,
does not match the XPath production EQNameXP40
A dynamic error is raised [err:FONS0004] if
the supplied value of $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.
|
|
|
|
|
|
|
New function, accepted 2022-11-18
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.
fn:resolve-QName ( |
||
$value |
as , |
|
$element |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 Section 2.1 TerminologyDM40.
A dynamic error is raised [err:FOCA0002] if $value
does
not have the correct lexical form for an instance of xs:QName
.
A dynamic error is raised [err:FONS0004] if $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 (contains($value, ":")) then resolve-QName($value, $element) else QName("", $value)
If the requirement is to construct an xs:QName
using the namespaces in the
static context, then the xs:QName
constructor should be used.
Assume that the element bound to |
|
|
|
|
This section specifies functions on QNames as defined in [XML Schema Part 2: Datatypes Second Edition].
Function | Meaning |
---|---|
op:QName-equal |
Returns true if two supplied QNames have the same namespace URI and the
same local part. |
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 . |
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:namespace-uri-for-prefix |
Returns the namespace URI of one of the in-scope namespaces for $element ,
identified by its namespace prefix. |
Returns true
if two supplied QNames have the same namespace URI and the
same local part.
Defines the semantics
of the eq
and ne
operators when applied to two values of type xs:QName
.
op:QName-equal ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns true
if the namespace URIs of $arg1
and
$arg2
are equal and the local names of $arg1
and
$arg2
are equal.
Otherwise, the function returns false
.
The namespace URI parts are considered equal if they are both absentDM40, or if they are both present and equal under the rules
of the fn:codepoint-equal
function.
The local parts are also compared under the rules of the fn:codepoint-equal
function.
The prefix parts of $arg1
and $arg2
, if any, are ignored.
Returns the prefix component of the supplied QName.
fn:prefix-from-QName ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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.
fn:local-name-from-QName ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
local-name-from-QName( QName("http://www.example.com/example", "person") ) |
|
Returns the namespace URI part of the supplied QName.
fn:namespace-uri-from-QName ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 |
---|---|
namespace-uri-from-QName( QName("http://www.example.com/example", "person") ) |
|
Returns a string representation of an xs:QName
in the format Q{uri}local
.
fn:expanded-QName ( |
||
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 BracedURILiteralXP40.
Expression | Result |
---|---|
QName("http:/example.com", "person") => expanded-QName() |
|
QName("", "person") => expanded-QName() |
|
New function, accepted 2022-11-15.
Returns the in-scope namespaces of an element node, as a map.
fn:in-scope-namespaces ( |
||
$element |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 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
.
Expression | Result |
---|---|
let $e := <z:a xmlns="http://example.org/one" xmlns:z="http://example.org/two"> <b xmlns=""/> </z:a> |
|
|
map{"": "http://example.org/one", "z": "http://example.org/two", "xml": "http://www.w3.org/XML/1998/namespace"} |
New in 4.0. Accepted 2022-09-20. Note that the function signature uses notation that is not yet accepted.
Returns the prefixes of the in-scope namespaces for an element node.
fn:in-scope-prefixes ( |
||
$element |
as
|
|
) as
|
This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.
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"
.
Reformulated in 4.0, so it is now defined in terms of the new
fn:in-scope-namespaces
function; the semantics are unchanged.
Returns the namespace URI of one of the in-scope namespaces for $element
,
identified by its namespace prefix.
fn:namespace-uri-for-prefix ( |
||
$value |
as , |
|
$element |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the result of the expression map:get(fn:in-scope-namespaces($element), string($value))
.
Expression | Result |
---|---|
let $e := <z:a xmlns="http://example.org/one" xmlns:z="http://example.org/two"> <b xmlns=""/> </z:a> |
|
|
|
|
|
|
|
|
|
Reformulated in 4.0, so it is now defined in terms of the new
fn:in-scope-namespaces
function; the semantics are unchanged.
The following comparison operators on xs:base64Binary
and
xs:hexBinary
values are defined. Comparisons take two operands of
the same type; that is, both operands must be xs:base64Binary
or
both operands may be xs:hexBinary
. Each returns a boolean value.
A value of type xs:hexBinary
can be compared with a value of type
xs:base64Binary
by casting one value to the other type. See
21.1.6 Casting to xs:base64Binary and xs:hexBinary.
Function | Meaning |
---|---|
op:hexBinary-equal |
Returns true if two xs:hexBinary values contain the same octet
sequence. |
op:hexBinary-less-than |
Returns true if the first argument is less than the second. |
op:base64Binary-equal |
Returns true if two xs:base64Binary values contain the same octet
sequence. |
op:base64Binary-less-than |
Returns true if the first argument is less than the second. |
Returns true
if two xs:hexBinary
values contain the same octet
sequence.
Defines the semantics of
the eq
and ne
operators when applied to two xs:hexBinary
values.
op:hexBinary-equal ( |
||
$value1 |
as , |
|
$value2 |
as
|
|
) as
|
The function returns true
if $value1
and $value2
are of the same length, measured in binary octets, and contain the same octets in the
same order. Otherwise, it returns false
.
Returns true
if the first argument is less than the second.
Defines the semantics of
the lt
operator when applied to two xs:hexBinary
values. Also used in the
definition of the ge
operator.
op:hexBinary-less-than ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
The function returns true
if any of the following conditions is true
:
$arg1
is zero-length (contains no octets) and $arg2
is
not zero-length.
Neither argument is zero-length, and the first octet of $arg1
is less
than the first octet of $arg2
, treating the value of the octet as an
unsigned integer in the range 0 to 255.
Neither argument is zero-length, the first octet of $arg1
is equal to
the first octet of $arg2
, and the xs:hexBinary
value
formed by taking all octets of arg1
after the first is less than the
xs:hexBinary
value formed by taking all octets of
arg2
after the first.
Otherwise, the function returns false
.
Returns true
if two xs:base64Binary
values contain the same octet
sequence.
Defines the semantics
of the eq
and ne
operators when applied to two xs:base64Binary
values.
op:base64Binary-equal ( |
||
$value1 |
as , |
|
$value2 |
as
|
|
) as
|
The function returns true
if $value1
and $value2
are of the same length, measured in binary octets, and contain the same octets in the
same order. Otherwise, it returns false
.
Returns true
if the first argument is less than the second.
Defines the semantics
of the lt
operator when applied to two xs:base64Binary
values. Also used in
the definition of the ge
operator.
op:base64Binary-less-than ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
The function returns true
if any of the following conditions is true
:
$arg1
is zero-length (contains no octets) and $arg2
is
not zero-length.
Neither argument is zero-length, and the first octet of $arg1
is less
than the first octet of $arg2
, treating the value of the octet as an
unsigned integer in the range 0 to 255.
Neither argument is zero-length, the first octet of $arg1
is equal to
the first octet of $arg2
, and the xs:base64Binary
value
formed by taking all octets of arg1
after the first is less than the
xs:base64Binary
value formed by taking all octets of
arg2
after the first.
Otherwise, the function returns false
.
This section specifies operators that take xs:NOTATION
values as arguments.
Function | Meaning |
---|---|
op:NOTATION-equal |
Returns true if the two xs:NOTATION values have the same
namespace URI and the same local part. |
Returns true
if the two xs:NOTATION
values have the same
namespace URI and the same local part.
Defines the
semantics of the eq
and ne
operators when applied to two values of type
xs:NOTATION
.
op:NOTATION-equal ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
The function returns true
if the namespace URIs of $arg1
and
$arg2
are equal and the local names of $arg1
and
$arg2
are equal.
Otherwise, the function returns false
.
The namespace URI parts are considered equal if they are both absentDM40, or if they are both present and equal under the rules
of the fn:codepoint-equal
function.
The local parts are also compared under the rules of the fn:codepoint-equal
function.
The prefix parts of $arg1
and $arg2
, if any, are ignored.
This section specifies functions and operators on nodes. Nodes are formally defined in Section 6 Nodes DM31.
Function | Meaning |
---|---|
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: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:namespace-uri |
Returns the namespace URI part of the name of $node , as an
xs:anyURI value. |
fn:lang |
This function tests whether the language of $node , or the context item if
the second argument is omitted, as specified by xml:lang attributes is the
same as, or is a sublanguage of, the language specified by $language . |
fn:root |
Returns the root of the tree to which $node belongs. This will usually, but
not necessarily, be a document node. |
fn:path |
Returns a path expression that can be used to select the supplied node relative to the root of its containing document. |
fn:has-children |
Returns true if the supplied node has one or more child nodes (of any kind). |
fn:innermost |
Returns every node within the input sequence that is not an ancestor of another member of the input sequence; the nodes are returned in document order with duplicates eliminated. |
fn:outermost |
Returns every node within the input sequence that has no ancestor that is itself a member of the input sequence; the nodes are returned in document order with duplicates eliminated. |
For the illustrative examples below assume an XQuery or transformation operating on a
PurchaseOrder
document containing a number of line-item
elements. Each line-item has
child elements called description
, price
, quantity
, etc. whose content is different
for each line-item
. Quantity has simple content of type xs:decimal
.
Further assume that variables $item1
, $item2
, etc. are
each bound to single line-item element nodes in the document in sequence and that
the value of the quantity child of the first line-item is 5.0
.
let $po := <PurchaseOrder> <line-item> <description>Large widget</description> <price>8.95</price> <quantity>5.0</quantity> </line-item> <line-item> <description>Small widget</description> <price>3.99</price> <quantity>2.0</quantity> </line-item> <line-item> <description>Tiny widget</description> <price>1.49</price> <quantity>805</quantity> </line-item> </PurchaseOrder>
let $item1 := $po/line-item[1]
let $item2 := $po/line-item[2]
let $item3 := $po/line-item[3]
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:name ( |
||
$node |
as
|
:= . |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the argument is omitted, it defaults to the context item (.
).
If the argument is supplied and is the empty sequence, the function returns the 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 item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
Because the result depends on the choice of namespace prefixes in the source document,
it is not good practice to use the result of this function for anything other than display
purposes. For example, the test name(.) = 'my:profile'
will fail if the source
document uses an unexpected namespace prefix. Such a test (assuming it relates to an element node)
is better written as boolean(self::my:profile)
.
Returns the local part of the name of $node
as an xs:string
that is either the zero-length string, or has the lexical form of an
xs:NCName
.
fn:local-name ( |
||
$node |
as
|
:= . |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the argument is omitted, it defaults to the context item (.
).
If the argument is supplied and is the empty sequence, the function returns the 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 Section 4.10 node-name AccessorDM40). This will be an
xs:string
whose lexical form is an xs:NCName
.
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
Returns the namespace URI part of the name of $node
, as an
xs:anyURI
value.
fn:namespace-uri ( |
||
$node |
as
|
:= . |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the argument is omitted, it defaults to the context node (.
).
If the node identified by $node
is neither an element nor an attribute node,
or if it is an element or attribute node whose expanded-QName (as determined by the
dm:node-name
accessor in the Section 4.10 node-name AccessorDM40)
is in no namespace, then the function returns the zero-length 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 Section 4.10 node-name AccessorDM40), returned as an
xs:anyURI
value.
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
This function tests whether the language of $node
, or the context item if
the second argument is omitted, as specified by xml:lang
attributes is the
same as, or is a sublanguage of, the language specified by $language
.
fn:lang ( |
||
$language |
as , |
|
$node |
as
|
:= . |
) as
|
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The behavior of the function if the second argument is omitted is exactly the same as if
the context item (.
) had been passed as the second argument.
The language of the argument $node
, or the context item if the second
argument is omitted, is determined by the value of the xml:lang
attribute
on the node, or, if the node has no such attribute, by the value of the
xml:lang
attribute on the nearest ancestor of the node that has an
xml:lang
attribute. If there is no such ancestor, then the function
returns false
.
If $language
is the empty sequence it is interpreted as the zero-length
string.
The relevant xml:lang
attribute is determined by the value of the XPath
expression:
(ancestor-or-self::*/@xml:lang)[last()]
If this expression returns an empty sequence, the function returns false
.
Otherwise, the function returns true
if and only if, based on a caseless
default match as specified in section 3.13 of [The Unicode Standard], either:
$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 item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
The expression |
|
|
|
The expression |
Returns the root of the tree to which $node
belongs. This will usually, but
not necessarily, be a document node.
fn:root ( |
||
$node |
as
|
:= . |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the function is called without an argument, the context item (.
) is used
as the default argument.
The function returns the value of the expression
($arg/ancestor-or-self::node())[1]
.
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
These examples use some variables which could be defined in [XQuery 4.1: An XML Query Language] as: |
|
let $i := <tool>wrench</tool> let $o := <order> {$i} <quantity>5</quantity> </order> let $odoc := document {$o} let $newi := $o/tool |
|
Or they could be defined in [XSL Transformations (XSLT) Version 4.0] as: |
|
<xsl:variable name="i" as="element()"> <tool>wrench</tool> </xsl:variable> <xsl:variable name="o" as="element()"> <order> <xsl:copy-of select="$i"/> <quantity>5</quantity> </order> </xsl:variable> <xsl:variable name="odoc"> <xsl:copy-of select="$o"/> </xsl:variable> <xsl:variable name="newi" select="$o/tool"/> |
|
|
|
|
|
|
|
|
|
The final three examples could be made type-safe by wrapping their operands with
|
Returns a path expression that can be used to select the supplied node relative to the root of its containing document.
fn:path ( |
||
$node |
as
|
:= . |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The behavior of the function if the argument is omitted is exactly the same as if the
context item (.
) had been passed as the argument.
If $node
is the empty sequence, the function returns the empty sequence.
If $node
is a document node, the function returns the string
"/"
.
Otherwise, the function returns a string that consists of a sequence of steps, one
for each ancestor-or-self of $node
other than the root node. This string is
prefixed by "Q{http://www.w3.org/2005/xpath-functions}root()"
if the root
node is not a document node. Each step consists of the character "/"
followed by a string whose form depends on the kind of node selected by that step, as
follows:
For an element node,
Q{uri}local[position]
,
where uri
is the namespace URI of the node name or the
empty string if the node is in no namespace, local
is
the local part of the node name, and position
is an
integer representing the position of the selected node among its like-named
siblings.
For an attribute node:
if the node is in no namespace, @local
, where
local
is the local part of the node name
otherwise, @Q{uri}local
, where
uri
is the namespace URI of the node name,
and local
is the local part of the node name
For a text node: text()[position]
where
position
is an integer representing the position
of the selected node among its text node siblings
For a comment node: comment()[position]
where
position
is an integer representing the position
of the selected node among its comment node siblings
For a processing-instruction node:
processing-instruction(local)[position]
where local
is the name of the processing instruction
node and position
is an integer representing the
position of the selected node among its like-named processing-instruction node
siblings
For a namespace node:
If the namespace node has a name:
namespace::prefix
, where
prefix
is the local part of the name of the
namespace node (which represents the namespace prefix).
If the namespace node has no name (that is, it represents the default
namespace):
namespace::*[Q{http://www.w3.org/2005/xpath-functions}local-name()=""]
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
Expression | Result |
---|---|
let $e := document { <p xmlns="http://example.com/one" xml:lang="de" author="Friedrich von Schiller"> Freude, schöner Götterfunken,<br/> Tochter aus Elysium,<br/> Wir betreten feuertrunken,<br/> Himmlische, dein Heiligtum.</p>} |
|
|
|
|
|
|
|
|
|
|
|
path( $e//text()[ starts-with(normalize-space(), 'Tochter') ] ) |
|
let $emp := <employee xml:id="ID21256"> <empnr>E21256</empnr> <first>John</first> <last>Brown</last> </employee> |
|
|
|
|
|
|
|
Returns true
if the supplied node has one or more child nodes (of any kind).
fn:has-children ( |
||
$node |
as
|
:= . |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the argument is omitted, it defaults to the context item (.
).
Provided that the supplied argument $node
matches the expected type
node()?
, the result of the function call
fn:has-children($node)
is defined to be the same as the result of the
expression fn:exists($node/child::node())
.
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
If $node
is an empty sequence the result is false
.
The motivation for this function is to support streamed evaluation. According to the streaming rules in [XSL Transformations (XSLT) Version 4.0], the following construct is not streamable:
<xsl:if test="exists(row)"> <ulist> <xsl:for-each select="row"> <item><xsl:value-of select="."/></item> </xsl:for-each> </ulist> </xsl:if>
This is because it makes two downward selections to read the child row
elements. The use of fn:has-children
in the xsl:if
conditional
is intended to circumvent this restriction.
Although the function was introduced to support streaming use cases, it has general utility as a convenience function.
Returns every node within the input sequence that is not an ancestor of another member of the input sequence; the nodes are returned in document order with duplicates eliminated.
fn:innermost ( |
||
$nodes |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the function call fn:innermost($nodes)
is defined to be
equivalent to the result of the expression:
$nodes except $nodes/ancestor::node()
That is, the function takes as input a sequence of nodes, and returns every node within the sequence that is not an ancestor of another node within the sequence; the nodes are returned in document order with duplicates eliminated.
If the source document contains nested sections represented by |
Returns every node within the input sequence that has no ancestor that is itself a member of the input sequence; the nodes are returned in document order with duplicates eliminated.
fn:outermost ( |
||
$nodes |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the function call fn:outermost($nodes)
is defined to be
equivalent to the result of the expression:
$nodes[not(ancestor::node() intersect $nodes)]/.
That is, the function takes as input a sequence of nodes, and returns every node within the sequence that does not have another node within the sequence as an ancestor; the nodes are returned in document order with duplicates eliminated.
The formulation $nodes except $nodes/descendant::node()
might appear to be
simpler, but does not correctly account for attribute nodes, as these are not
descendants of their parent element.
The motivation for the function was based on XSLT streaming use cases. There are cases
where the [XSL Transformations (XSLT) Version 4.0] streaming rules allow the construct
outermost(//section)
but do not allow //section
; the
function can therefore be useful in cases where it is known that sections will not be
nested, as well as cases where the application actually wishes to process all sections
except those that are nested within another.
If the source document contains nested sections represented by |
A sequence
is an ordered collection of zero or more items
.
An item
is either a node or an atomic value. The terms
sequence
and item
are defined formally in [XQuery 4.1: An XML Query Language] and [XML Path Language (XPath) 4.0].
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:intersperse |
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 except those
at specified positions. |
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 ·implementation-dependent· order. |
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.
fn:empty ( |
||
$input |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $input
is the empty sequence, the function returns
true
; otherwise, the function returns false
.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
Assuming |
|
let $break := <br/> return empty($break) |
|
The result is |
Returns true
if the argument is a non-empty sequence.
fn:exists ( |
||
$input |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $input
is a non-empty sequence, the function returns
true
; otherwise, the function returns false
.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
Assuming |
|
let $break := <br/> return exists($break) |
|
The result is |
Returns the last item in a sequence.
fn:foot ( |
||
$input |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the value of the expression $input[position() = last()]
If $input
is the empty sequence the empty sequence is returned.
Expression | Result |
---|---|
|
|
|
|
New in 4.0.
Returns the first item in a sequence.
fn:head ( |
||
$input |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the value of the expression $input[1]
If $input
is the empty sequence, the empty sequence is returned. Otherwise
the first item in the sequence is returned.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
Returns its argument value.
fn:identity ( |
||
$input |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns $input
.
The function is useful in contexts where a function must be supplied, but no processing is required.
Expression | Result |
---|---|
|
|
|
|
|
(If the argument is a node, the function returns the identical node, not a copy). |
|
|
New in 4.0. Accepted 2022-09-20.
Returns a sequence constructed by inserting an item or a sequence of items at a given position within an existing sequence.
fn:insert-before ( |
||
$input |
as , |
|
$position |
as , |
|
$insert |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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.
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.
Expression | Result |
---|---|
let $abc := ("a", "b", "c") |
|
|
|
|
|
|
|
|
|
|
|
Inserts a separator between adjacent items in a sequence.
fn:intersperse ( |
||
$input |
as , |
|
$separator |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the value of head($input), tail($input) ! ($separator, .)
.
If $input
contains less than two items then it is returned unchanged.
If $separator
is the empty sequence then $input
is returned unchanged.
For example, in XQuery, fn:intersperse(para, <hr/>)
would insert
an empty hr
element between adjacent paragraphs.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
New in 4.0. Accepted 2022-09-27.
Returns a sequence containing the items from $input
at positions defined by $at
, in the order specified.
fn:items-at ( |
||
$input |
as , |
|
$at |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Returns the value of $at ! fn:subsequence($input, ., 1)
The effect of the function is to return those items from $items
at the positions given by the integers in $at
, in the order
represented by the integers in $at
.
In the simplest case where $at
is a single integer,
fn: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 fn:subsequence
,
these do not need to be contiguous.
The $at
expression can depend on the focus.
The order of the returned items can differ from their order in the $input
sequence.
If any integer in $at
is outside the range 1 to count($input)
, that integer
is effectively ignored: no error occurs.
If either of the arguments is an empty sequence, the result is an empty sequence.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
New in 4.0 (see issue 213)
Returns a new sequence containing all the items of $input
except those
at specified positions.
fn:remove ( |
||
$input |
as , |
|
$positions |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns a sequence consisting of all items of $input
whose
1-based position is not equal to any of the integers in $positions
.
More formally, the function returns the result of the expression $input[not(position() = $positions)]
.
Any integer in $positions
that is less than 1 or greater than the number of items in
$input
is effectively ignored.
If $input
is the empty sequence, the empty sequence is returned.
If $positions
is an empty sequence, the input sequence $input
is returned unchanged.
Expression | Result |
---|---|
let $abc := ("a", "b", "c") |
|
|
|
|
|
|
|
|
|
|
|
|
|
Changed in 4.0: the second argument can now be a sequence of integers.
Produces multiple copies of a sequence.
fn:replicate ( |
||
$input |
as , |
|
$count |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the value of (1 to $count) ! $input
.
If $input
is the empty sequence, the empty sequence is returned.
The $count
argument is declared as xs:nonNegativeInteger
,
which means that a type error occurs if it is called with a negative value.
If the input sequence contains nodes, these are not copied: instead, the result sequence contains
multiple references to the same node. So, for example, fn:count(fn:replicate(/, 6)|())
returns 1
, because the fn:replicate
call creates duplicates, and the
union operation eliminates them.
[TODO: the use of type xs:nonNegativeInteger
for the second argument
assumes we will accept the proposal to allow downcasting in the coercion rules for
function arguments. MHK 2022-10-04.]
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
New in 4.0. Accepted 2022-10-04.
Reverses the order of items in a sequence.
fn:reverse ( |
||
$input |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns a sequence containing the items in $input
in reverse
order.
If $input
is the empty sequence, the empty sequence is returned.
Expression | Result |
---|---|
let $abc := ("a", "b", "c") |
|
|
|
|
|
|
|
|
(The input is a sequence containing a single item (the array)). |
|
|
Returns a sequence containing selected items from a supplied input sequence based on their position.
fn:slice ( |
||
$input |
as , |
|
$start |
as
|
:= () , |
$end |
as
|
:= () , |
$step |
as
|
:= () |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $input
is the empty sequence, the function returns the empty sequence.
Let $S
be the first of the following that applies:
If $start
is absent, empty, or zero, then 1.
If $start
is negative, then fn:count($input) + $start + 1
.
Otherwise, $start
.
Let $E
be the first of the following that applies:
If $end
is absent, empty, or zero, then fn:count($input)
.
If $end
is negative, then fn:count($input) + $end + 1
.
Otherwise, $end
.
Let $STEP
be the first of the following that applies:
If $step
is absent, empty, or zero, then:
If $E ge $S
, then +1
Otherwise -1
Otherwise, $step
.
If $STEP
is negative, the function returns
$input => fn:reverse() => fn:slice(-$S, -$E, -$STEP)
.
Otherwise the function returns the result of the expression:
$input[position() ge $S and position() le $E and (position() - $S) mod $STEP eq 0]
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]
.
Expression | Result |
---|---|
let $in := ('a', 'b', 'c', 'd', 'e') |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Proposed for 4.0; not yet reviewed.
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:subsequence ( |
||
$input |
as , |
|
$start |
as , |
|
$length |
as
|
:= () |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
In the two-argument case (or where the third argument is an empty sequence), the function returns:
$input[round($start) le position()]
In the three-argument case, the function returns:
$input[round($start) le position() and position() lt round($start) + round($length)]
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 an empty sequence.
The reason the function accepts arguments of type xs:double
is that many
computations on untyped data return an xs:double
result; and the reason for
the rounding rules is to compensate for any imprecision in these floating-point
computations.
Expression | Result |
---|---|
let $seq := ("item1", "item2", "item3", "item4", "item5") |
|
|
|
|
|
Returns all but the first item in a sequence.
fn:tail ( |
||
$input |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the value of the expression subsequence($input, 2)
If $input
is the empty sequence, or a sequence containing a single item, then
the empty sequence is returned.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
Returns all but the last item in a sequence.
fn:trunk ( |
||
$input |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the value of the expression fn:remove($input, count($input))
If $input
is the empty sequence, or a sequence containing a single item, then
the empty sequence is returned.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
New in 4.0.
Returns the items of $input
in an ·implementation-dependent· order.
fn:unordered ( |
||
$input |
as
|
|
) as
|
This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.
The function returns the items of $input
in an ·implementation-dependent· order.
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.
Expression | Result |
---|---|
|
(or some permutation thereof) |
Absorbs the argument.
fn:void ( |
||
$input |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function absorbs the supplied $input
argument and
returns an 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.
The function is utilized by built-in functions such as map:get
to return an empty sequence for arbitrary input.
It is ·implementation-dependent· whether the supplied argument is evaluated or ignored. An implementation may decide to evaluate ·nondeterministic· expressions and ignore deterministic ones.
Expression | Result |
---|---|
|
|
|
(Without the third argument, an error would be raised). |
|
|
New in 4.0. Approved.
The functions in this section rely on comparisons between the items in one or more sequences.
Function | Meaning |
---|---|
fn:starts-with-sequence |
Determines whether one sequence starts with another, using a supplied callback function to compare items. |
fn:ends-with-sequence |
Determines whether one sequence ends with another, using a supplied callback function to compare items. |
fn:contains-sequence |
Determines whether one sequence contains another as a contiguous subsequence, using a supplied callback function to compare items. |
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:index-of |
Returns a sequence of positive integers giving the positions within the sequence
$input of items that are equal to $search . |
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 values that compare equal, or nodes of the same kind, with the same name, whose children are deep-equal, or maps with matching entries, or arrays with matching members. |
Determines whether one sequence starts with another, using a supplied callback function to compare items.
fn:starts-with-sequence ( |
||
$input |
as , |
|
$subsequence |
as , |
|
$compare |
as
|
:= fn:deep-equal#2 |
) as
|
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.
The three-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Informally, the function returns true
if $input
starts with $subsequence
,
when items are compared using the supplied (or default) $compare
function.
More formally, the function returns the value of the expression:
count($input) ge count($subsequence) and all(for-each-pair($input, $subsequence, $compare))
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.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
starts-with-sequence( 1 to 10, 101 to 105, function($x, $y) { $x mod 100 = $y mod 100 } ) |
|
starts-with-sequence( ("A", "B", "C"), ("a", "b"), function($x, $y) { compare( $x, $y, "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) eq 0 } ) |
|
let $p := parse-xml("<doc><chap><p/><p/></chap></doc>")//p[2] return starts-with-sequence( $p/ancestor::*[1], $p/parent::*, op("is") ) |
|
|
|
starts-with-sequence( ("Alpha", "Beta", "Gamma"), ("A", "B"), starts-with#2 ) |
|
starts-with-sequence( ("Alpha", "Beta", "Gamma", "Delta"), 1 to 3, function($x, $y) { ends-with($x, 'a' ) } ) |
(True because the first three items in the input sequence end with |
New in 4.0. Accepted 2022-11-01
Determines whether one sequence ends with another, using a supplied callback function to compare items.
fn:ends-with-sequence ( |
||
$input |
as , |
|
$subsequence |
as , |
|
$compare |
as
|
:= fn:deep-equal#2 |
) as
|
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.
The three-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Informally, the function returns true
if $input
ends with $subsequence
,
when items are compared using the supplied (or default) $compare
function.
More formally, the function returns the value of the expression:
starts-with-sequence(reverse($input), reverse($subsequence), $compare)
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.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
ends-with-sequence( 1 to 10, 108 to 110, function($x, $y) { $x mod 100 = $y mod 100 } ) |
|
ends-with-sequence( ("A", "B", "C"), ("b", "c"), function($x, $y) { compare( $x, $y, "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) eq 0 } ) |
|
let $p := parse-xml("<doc><chap><p/><p/></chap></doc>")//p[2] return ends-with-sequence( $p/ancestor::node()[last()], $p/root(), op("is") ) |
|
|
|
ends-with-sequence( ("Alpha", "Beta", "Gamma"), ("B", "G"), starts-with#2 ) |
|
ends-with-sequence( ("Alpha", "Beta", "Gamma", "Delta"), 1 to 2, function($x, $y) { string-length($x) eq 5 } ) |
(True because the last two items in the input sequence have a string length of 5.) |
New in 4.0. Accepted 2022-11-01
Determines whether one sequence contains another as a contiguous subsequence, using a supplied callback function to compare items.
fn:contains-sequence ( |
||
$input |
as , |
|
$subsequence |
as , |
|
$compare |
as
|
:= fn:deep-equal#2 |
) as
|
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.
The three-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Informally, the function returns true
if $input
contains a consecutive subsequence matching $subsequence
,
when items are compared using the supplied (or default) $compare
function.
More formally, the function returns the value of the expression:
if (starts-with-sequence($input, $subsequence, $compare)) then true() else if (empty($input)) then false() else contains-sequence(tail($input, $subsequence, $compare))
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.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
contains-sequence( 1 to 10, 103 to 105, function($x, $y) { $x mod 100 = $y mod 100 } ) |
|
contains-sequence( ("A", "B", "C", "D"), ("b", "c"), function($x, $y) { compare( $x, $y, "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) eq 0 } ) |
|
let $chap := parse-xml("<doc><chap><h1/><p/><p/><footnote/></chap></doc>")//chap return contains-sequence( $chap ! child::*, $chap ! child::p, op("is") ) |
(True because the |
|
|
contains-sequence( ("Alpha", "Beta", "Gamma", "Delta"), ("B", "G"), starts-with#2 ) |
|
contains-sequence( ("Zero", "Alpha", "Beta", "Gamma", "Delta", "Epsilon"), 1 to 4, function($x, $y) { ends-with($x, 'a') } ) |
(True because there is a run of 4 consecutive items ending in |
New in 4.0. Accepted 2022-11-01
Returns the values that appear in a sequence, with duplicates eliminated.
fn:distinct-values ( |
||
$values |
as , |
|
$collation |
as
|
:= fn:default-collation() |
) as
|
The one-argument form of this function is ·nondeterministic-wrt-ordering·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.
The function returns the sequence that results from removing from $values
all
but one of a set of values that are considered equal to one another.
Two items $J and $K in the input sequence
(after atomization, as required by the function signature)
are considered equal if fn:deep-equal($J, $K, $coll)
is true
,
where $coll
is the collation selected according to the rules in 5.3.5 Choosing a collation. This collation is used when string comparison is
required.
The order in which the sequence of values is returned is ·implementation-dependent·.
Which value of a set of values that compare equal is returned is ·implementation-dependent·.
If $values
is the empty sequence, the function returns the empty sequence.
Values of type xs:untypedAtomic
are compared as if they were of type
xs:string
.
Values that cannot be compared, because the eq
operator is not defined for
their types, are considered to be distinct.
For xs:float
and xs:double
values, positive zero is equal to
negative zero and, although NaN
does not equal itself, if $values
contains multiple NaN
values a single NaN
is returned.
If xs:dateTime
, xs:date
or xs:time
values do not
have a timezone, they are considered to have the implicit timezone provided by the
dynamic context for the purpose of comparison. Note that xs:dateTime
,
xs:date
or xs:time
values can compare equal even if their
timezones are different.
Expression | Result |
---|---|
|
(or some permutation thereof) (The result may include either the |
distinct-values(( xs:untypedAtomic("cherry"), xs:untypedAtomic("plum"), xs:untypedAtomic("plum") )) |
(xs:untypedAtomic("cherry"), xs:untypedAtomic("plum")) (or some permutation thereof) |
Returns the values that appear in a sequence more than once.
fn:duplicate-values ( |
||
$values |
as , |
|
$collation |
as
|
:= fn:default-collation() |
) as
|
The one-argument form of this function is ·nondeterministic-wrt-ordering·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.
The items of $values
are compared against each other, according to the
rules of fn:distinct-values
and with $coll
as the collation
selected according to the rules in 5.3.5 Choosing a collation.
From each resulting set of values that are considered equal, one value will be returned if the set contains more than one value.
The order in which the sequence of values is returned is ·implementation-dependent·.
Which value of a set of values that compare equal is returned is ·implementation-dependent·.
The effect of the function is equivalent to the following XSLT expression:
<xsl:for-each-group select="$values" group-by="." collation="{$collation}"> <xsl:sequence select="current-group()[2]"/> </xsl:for-each>
The following XQuery expression is equivalent if no collation is specified
(group by
requires collation URIs to be static):
for $group in $values group by $value := $group where count($group) > 1 return $value
Expression | Result |
---|---|
|
(The result may be the |
|
|
|
(The string |
Raise an error for duplicates in an ID sequence: |
|
let $ids := duplicate-values(//@id) where exists($ids) return error((), 'Duplicate IDs found: ' || string-join($ids, ', ')) |
Returns a sequence of positive integers giving the positions within the sequence
$input
of items that are equal to $search
.
fn:index-of ( |
||
$input |
as , |
|
$search |
as , |
|
$collation |
as
|
:= fn:default-collation() |
) as
|
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.
The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.
The function returns a sequence of positive integers giving the positions within the
sequence $input
of items that are equal to $search
.
The collation used by this function is determined according to the rules in 5.3.5 Choosing a collation. This collation is used when string comparison is required.
The items in the sequence $input
are compared with $search
under
the rules for the eq
operator. Values of type xs:untypedAtomic
are compared as if they were of type xs:string
. Values that cannot be
compared, because the eq
operator is not defined for their types, are
considered to be distinct. If an item compares equal, then the position of that item in
the sequence $input
is included in the result.
The first item in a sequence is at position 1, not position 0.
The result sequence is in ascending numeric order.
If $input
is the empty sequence, or if no item in
$input
matches $search
, then the function returns the empty
sequence.
No error occurs if non-comparable values are encountered. So when comparing two atomic
values, 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 |
---|---|
|
|
|
|
index-of( ("a", "sport", "and", "a", "pastime"), "a" ) |
|
|
|
|
(The array is atomized to a sequence of five integers). |
If |
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 values that compare equal, or nodes of the same kind, with the same name, whose children are deep-equal, or maps with matching entries, or arrays with matching members.
fn:deep-equal ( |
||
$input1 |
as , |
|
$input2 |
as , |
|
$collation |
as
|
:= fn:default-collation() , |
$options |
as
|
:= map{} |
) as
|
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.
The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.
The four-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.
The $collation
argument identifies a collation which is used at all levels
of recursion when strings are compared (but not when names are compared), according to
the rules in 5.3.5 Choosing a collation. If the argument is not supplied,
or if it is empty, then the default collation from the
dynamic context of the caller is used.
The $options
argument, if present, defines additional parameters controlling
how the comparison is done. The ·option parameter conventions· apply.
If the two sequences are both empty, the function returns true
.
If the two sequences are of different lengths, the function returns
false
.
If the two sequences are of the same length, the function returns true
if
and only if every item in the sequence $input1
is deep-equal to the
item at the same position in the sequence $input2
. 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 |
---|---|
base-uri |
Determines whether the base-uri of a node is significant.
|
comments |
Determines whether comments are significant.
|
debug |
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
should output messages (in an implementation-dependent format and to
an implementation-dependent destination) indicating the nature of the differences
that
were found.
|
false-on-error |
If true , then in the event of a dynamic error occurring in the course of
the comparison, the function will return false rather than throwing the error. (This option does
not affect the handling of errors in the supplied values of the $collation
and $options arguments.)
|
id-property |
Determines whether the id property of elements and attributes is significant.
|
idrefs-property |
Determines whether the idrefs property of elements and attributes is significant.
|
in-scope-namespaces |
Determines whether the in-scope namespaces of elements are significant.
|
namespace-prefixes |
Determines whether namespace prefixes in xs:QName values (particularly
the names of elements and attributes) are significant.
|
nilled-property |
Determines whether the nilled property of elements and attributes is significant.
|
normalization-form |
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 fn:normalize-unicode .
|
processing-instructions |
Determines whether processing instructions are significant.
|
timezones |
Determines whether timezones in date/time values are significant.
|
type-annotations |
Determines whether type annotations are significant.
|
type-variety |
Determines whether the variety of the type annotation of an element
(whether it has complex content or simple content) is significant.
|
typed-values |
Determines whether nodes are compared using their typed values rather than
their string values.
|
unordered-elements |
A list of QNames of elements considered to be unordered: that is, their child
elements may appear in any order.
|
whitespace |
Determines the extent to which whitespace
is treated as significant. The value
preserve retains all whitespace. The value strip ignores text nodes
consisting entirely of whitespace.
The value normalize ignores whitespace text nodes in the same way as
the strip option, and additionally compares text and attribute nodes after
normalizing whitespace in accordance with the rules of the fn:normalize-space
function. The detailed rules, given below, also take into account type annotations
and
xml:space attributes.
|
Note:
As a general rule for boolean options (but not invariably), the value true
indicates
that the comparison is more strict.
In the following rules, where a recursive call on fn:deep-equal
is made, this is assumed
to use the same values of $collation
and $options
as the original call.
The rules reference a function equal-strings
which compares two strings as follows:
If the whitespace
option is set to normalize
, then each string is processed
by calling the fn:normalize-space
function.
If the normalization-form
option is present, each string is then normalized
by calling the fn:normalize-unicode
function, supplying the specified normalization
form.
The two strings are then compared for equality under the requested $collation
.
More formally, the equal-strings
function can be expressed as follows:
function($s1 as xs:string, $s2 as xs:string, $collation as xs:string, $options as map(*) ) as xs:boolean { let $n1 := if ($options?whitespace = "normalize")) then normalize-unicode(?, $options?normalization-form) else identity#1, $n2 := if ($options?normalize-space) then normalize-space#1 else identity#1 } return compare($n1($n2($s1)), $n1($n2($s2)), $collation) eq 0 }
The rules for deciding whether two items $i1
and $i2
are deep-equal
are as follows. 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 value.
$i2
is an atomic value.
Either the type-annotations
option is false
, or both atomic values have
the same type annotation.
One of the following conditions is true:
If both $i1
and $i2
are instances of
xs:string
or xs:untypedAtomic
,
equal-strings($i1, $i2, $collation, $options)
returns true
.
If both $i1
and $i2
are instances of
xs:date
, xs:time
or xs:dateTime
,
$i1 eq $i2
returns true
.
Otherwise, fn:atomic-equal($i1, $i2)
returns true
.
Note:
If $i1
and $i2
are not comparable, that is,
if the expression ($i1 eq $i2)
would raise an error, then the function
returns false
; it does not report an error.
One of the following conditions is true:
Option 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 ·same key· (note that the collation is not used when comparing keys), and
has the same associated value (compared using the fn:deep-equal
function, recursively).
All the following conditions are true:
$i1
is an array.
$i2
is an array.
Both arrays have the same number of members (array:size($i1) eq
array:size($i2)
).
Members in the same position of both arrays are 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 Section 2.9.1 Function ItemsDM40.
All the following conditions are true:
$i1
is a node.
$i2
is a node.
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:
Either:
The option whitespace
is set to strip
or normalize
; or
$parent
is a schema-validated element node whose type annotation
is a complex type with an element-only or empty content model.
The text node is not within the scope
of an element that has the attribute xml:space="preserve"
.
One of the following conditions is true.
Both nodes are document nodes, and the sequence 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 simple content means either a simple type or a complex type with simple content.
Both nodes are annotated as having complex content. For this purpose complex content means a complex type whose variety is mixed, element-only, or empty.
Note:
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 $a1
and
$a2
are deep-equal.
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
.
Note:
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)
.
Note:
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.
Either the option typed-value
is false
, or
the typed value of $i1
is deep-equal to the typed value of
$i2
.
Either the option typed-value
is true
, or
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.
Note:
Namespace nodes are not considered directly unless they appear in the top-level sequences
passed explicitly to the fn:deep-equal
function.
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.
In all other cases the result is false
.
A type error is raised [err:FOTY0015] if either input sequence contains a function item that is not a map or array.
However, the above error is not raised if the false-on-error
option is
true
; in this case, the function returns false
rather than raising an error.
A type error is raised [err:XPTY0004]XP if the value of
$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 [err:FOJS0005] if the value of
$options
includes an entry whose key is defined
in this specification, and whose value is not a permitted value for that key.
By default, whitespace in text nodes and attribute is considered significant. There are various ways whitespace differences can be ignored:
If nodes have been 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 Section 4.5 is-id AccessorDM40 and
Section 4.6 is-idrefs AccessorDM40). The order of children is significant,
but the order of attributes is insignificant.
By default, the contents of comments and processing instructions are significant only if these nodes appear directly as items in the two sequences being compared. The content of a comment or processing instruction that appears as a descendant of an item in one of the sequences being compared does not affect the result. However, the presence of a comment or processing instruction, if it causes a text node to be split into two text nodes, may affect the result.
Comparing items of different kind (for example, comparing an atomic
value to a node, or a map to an array, or an integer to an xs:date
) returns false
,
it does not return an error. So
the result of fn:deep-equal(1, current-dateTime())
is false
.
Comparing a function (other than a map or array) to any other value raises a type error,
unless the error is suppressed using the false-on-error
option.
Expression | Result |
---|---|
let $at := <attendees> <name last="Parker" first="Peter"/> <name last="Barker" first="Bob"/> <name last="Parker" first="Peter"/> </attendees> |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
deep-equal( parse-xml("<a xmlns='AA'/>"), parse-xml("<p:a xmlns:p='AA'/>")) |
(By default, namespace prefixes are ignored). |
deep-equal( parse-xml("<a xmlns='AA'/>"), parse-xml("<p:a xmlns:p='AA'/>"), options := map{'namespace-prefixes':true()}) |
(False because the namespace prefixes differ). |
deep-equal( parse-xml("<a xmlns='AA'/>"), parse-xml("<p:a xmlns:p='AA'/>"), options := map{'in-scope-namespaces':true()}) |
(False because the in-scope namespace bindings differ). |
deep-equal( parse-xml("<a><b/><c/></a>"), parse-xml("<a><c/><b/></a>")) |
(By default, order of elements is significant). |
deep-equal( parse-xml("<a><b/><c/></a>"), parse-xml("<a><c/><b/></a>"), options := map{'unordered-elements': parse-QName('a')}) |
(The |
deep-equal( parse-xml( "<para style='bold'><span>x</span></para>"), parse-xml( "<para style=' bold'> <span>x</span></para>")) |
(By default, both the leading whitespace in the |
deep-equal( parse-xml( "<para style='bold'><span>x</span></para>"), parse-xml( "<para style=' bold'> <span>x</span></para>"), options := map{'whitespace': 'normalize'}) |
(The |
Options parameter added. Approved in principle on 2023-01-31, subject to further review.
The following functions test the cardinality of their sequence arguments.
Function | Meaning |
---|---|
fn:zero-or-one |
Returns input if it contains zero or one items. Otherwise, raises an
error. |
fn:one-or-more |
Returns $input if it contains one or more items. Otherwise, raises an error.
|
fn:exactly-one |
Returns $input if it contains exactly one item. Otherwise, raises an error.
|
The functions fn:zero-or-one
, fn:one-or-more
, and
fn:exactly-one
defined in this section, check that the cardinality
of a sequence is in the expected range. They are particularly useful with regard
to static typing. For example, the function call fn:remove($seq, fn:index-of($seq2, 'abc'))
requires the result of the call on fn:index-of
to be a singleton integer,
but the static type system cannot infer this; writing the expression as
fn:remove($seq, fn:exactly-one(fn:index-of($seq2, 'abc')))
will provide a suitable static type at query analysis time, and ensures that the length of the sequence is
correct with a dynamic check at query execution time.
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 zero or one items. Otherwise, raises an
error.
fn:zero-or-one ( |
||
$input |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Except in error cases, the function returns $input
unchanged.
A dynamic error is raised [err:FORG0003] if $input
contains more than one item.
Returns $input
if it contains one or more items. Otherwise, raises an error.
fn:one-or-more ( |
||
$input |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Except in error cases, the function returns $input
unchanged.
A dynamic error is raised [err:FORG0004] if $input
is an
empty sequence.
Returns $input
if it contains exactly one item. Otherwise, raises an error.
fn:exactly-one ( |
||
$input |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Except in error cases, the function returns $input
unchanged.
A dynamic error is raised [err:FORG0005] if $input
is an
empty sequence or a sequence containing more than one item.
Aggregate functions take a sequence as argument and return a single value
computed from values in the sequence. Except for fn:count
, the
sequence must consist of values of a single type or one if its subtypes, or they
must be numeric. 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: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 equal to the highest value appearing in the input sequence. |
fn:min |
Returns a value that is equal to the lowest value appearing in the input sequence. |
fn:sum |
Returns a value obtained by adding together the values in $values . |
fn:all-equal |
Returns true if all items in a supplied sequence (after atomization) are equal. |
fn:all-different |
Returns true if no two items in a supplied sequence are equal. |
Returns the number of items in a sequence.
fn:count ( |
||
$input |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the number of items in $input
.
returns 0
.if $input
is the empty sequence.
Expression | Result |
---|---|
let $seq1 := ($item1, $item2) |
|
let $seq2 := (98.5, 98.3, 98.9) |
|
let $seq3 := () |
|
|
|
|
|
|
|
|
|
|
|
|
|
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:avg ( |
||
$values |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $values
is the empty sequence, the empty sequence is returned.
If $values
contains values of type xs:untypedAtomic
they are cast
to xs:double
.
Duration values must either all be xs:yearMonthDuration
values or must all
be xs:dayTimeDuration
values. For numeric values, the numeric promotion
rules defined in 4.2 Arithmetic operators on numeric values are used to promote all values to a single
common type. After these operations, $values
must satisfy the following condition:
There must be a type T such that:
every item in $values
is an instance of T.
T is one of xs:double
, xs:float
,
xs:decimal
, xs:yearMonthDuration
, or
xs:dayTimeDuration
.
The function returns the average of the values as sum($values) div
count($values)
; but the implementation may use an otherwise equivalent algorithm
that avoids arithmetic overflow.
A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.
Expression | Result |
---|---|
let $d1 := xs:yearMonthDuration("P20Y") |
|
let $d2 := xs:yearMonthDuration("P10M") |
|
let $seq3 := (3, 4, 5) |
|
|
(The result is of type |
|
|
|
|
|
|
|
|
|
Returns a value that is equal to the highest value appearing in the input sequence.
fn:max ( |
||
$values |
as , |
|
$collation |
as
|
:= fn:default-collation() |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.
The following conversions are applied to the input sequence $values
, in order:
Values of type xs:untypedAtomic
in $values
are cast to
xs:double
.
If the resulting sequence contains values that are instances of more than one primitive type (meaning the 19 primitive types defined in [Schema 1.1 Part 2]), then:
If each value is an instance of one of the types xs:string
or xs:anyURI
,
then all the values are cast to type xs:string
.
If each value is an instance of one of the types xs:decimal
or xs:float
,
then all the values are cast to type xs:float
.
If each value is an instance of one of the types xs:decimal
, xs:float
,
or xs:double
, then all the values are cast to type xs:double
.
Otherwise, a type error is raised [err:FORG0006].
Note:
The primitive type of an xs:integer
value for this purpose is xs:decimal
.
The items in the resulting sequence may be reordered in an arbitrary order. The resulting sequence is referred to below as the converted sequence. The function returns an item from the converted sequence rather than the input sequence.
If the converted sequence is empty, the function returns the empty sequence.
All items in the converted sequence must be derived from a single base type for which
the le
operator is defined. In addition, the values in the sequence must
have a total order. If date/time values do not have a timezone, they are considered to
have the implicit timezone provided by the dynamic context for the purpose of
comparison. Duration values must either all be xs:yearMonthDuration
values
or must all be xs:dayTimeDuration
values.
If the converted sequence contains the value NaN
, the value
NaN
is returned
(as an xs:float
or xs:double
as appropriate).
If the items in the converted sequence are of type xs:string
or types
derived by restriction from xs:string
, then the determination of the item
with the smallest value is made according to the collation that is used. If the type of
the items in the converted sequence is not xs:string
and
$collation
is specified, the collation is ignored.
The collation used by this function is determined according to the rules in 5.3.5 Choosing a collation.
The function returns the result of the expression:
if (every $v in $c satisfies $c[1] ge $v) then $c[1] else max(tail($c))
evaluated with $collation
as the default collation if specified, and with
$c
as the converted sequence.
A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.
Because the rules allow the sequence to be reordered, if there are two or more items that are
“equal highest”, the specific item whose value is returned is ·implementation-dependent·. This can arise for example if two different strings
compare equal under the selected collation, or if two different xs:dateTime
values compare equal despite being in different timezones.
If the converted sequence contains exactly one value then that value is returned.
The default type when the fn:max
function is applied to
xs:untypedAtomic
values is xs:double
. This differs from the
default type for operators such as gt
, and for sorting in XQuery and XSLT,
which is xs:string
.
The rules for the dynamic type of the result are stricter in version 3.1 of the specification than
in earlier versions. For example, if all the values in the input sequence belong to types derived from
xs:integer
, version 3.0 required only that the result be an instance
of the least common supertype of the types present in the input sequence; Version 3.1
requires that the returned value retains its original type. This does not apply, however, where type promotion
is needed to convert all the values to a common primitive type.
Expression | Result |
---|---|
|
|
|
(Arrays are atomized). |
|
|
|
(Assuming that the current date is during the 21st century.) |
|
(Assuming a typical default collation.) |
|
Returns a value that is equal to the lowest value appearing in the input sequence.
fn:min ( |
||
$values |
as , |
|
$collation |
as
|
:= fn:default-collation() |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.
The following rules are applied to the input sequence:
Values of type xs:untypedAtomic
in $values
are cast to
xs:double
.
If the resulting sequence contains values that are instances of more than one primitive type (meaning the 19 primitive types defined in [Schema 1.1 Part 2]), then:
If each value is an instance of one of the types xs:string
or xs:anyURI
,
then all the values are cast to type xs:string
.
If each value is an instance of one of the types xs:decimal
or xs:float
,
then all the values are cast to type xs:float
.
If each value is an instance of one of the types xs:decimal
, xs:float
,
or xs:double
, then all the values are cast to type xs:double
.
Otherwise, a type error is raised [err:FORG0006].
Note:
The primitive type of an xs:integer
value for this purpose is xs:decimal
.
The items in the resulting sequence may be reordered in an arbitrary order. The resulting sequence is referred to below as the converted sequence. The function returns an item from the converted sequence rather than the input sequence.
If the converted sequence is empty, the empty sequence is returned.
All items in the converted sequence must be derived from a single base type for which
the le
operator is defined. In addition, the values in the sequence must
have a total order. If date/time values do not have a timezone, they are considered to
have the implicit timezone provided by the dynamic context for the purpose of
comparison. Duration values must either all be xs:yearMonthDuration
values
or must all be xs:dayTimeDuration
values.
If the converted sequence contains the value NaN
, the value
NaN
is returned
(as an xs:float
or xs:double
as appropriate).
If the items in the converted sequence are of type xs:string
or types
derived by restriction from xs:string
, then the determination of the item
with the smallest value is made according to the collation that is used. If the type of
the items in the converted sequence is not xs:string
and
$collation
is specified, the collation is ignored.
The collation used by this function is determined according to the rules in 5.3.5 Choosing a collation.
The function returns the result of the expression:
if (every $v in $c satisfies $c[1] le $v) then $c[1] else min(tail($c))
evaluated with $collation
as the default collation if specified, and with
$c
as the converted sequence.
A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.
Because the rules allow the sequence to be reordered, if there are two or items that are
“equal lowest”, the specific item whose value is returned is ·implementation-dependent·. This can arise for example if two different strings
compare equal under the selected collation, or if two different xs:dateTime
values compare equal despite being in different timezones.
If the converted sequence contains exactly one value then that value is returned.
The default type when the fn:min
function is applied to
xs:untypedAtomic
values is xs:double
. This differs from the
default type for operators such as lt
, and for sorting in XQuery and XSLT,
which is xs:string
.
The rules for the dynamic type of the result are stricter in version 3.1 of the specification than
in earlier versions. For example, if all the values in the input sequence belong to types derived from
xs:integer
, version 3.0 required only that the result be an instance
of the least common supertype of the types present in the input sequence; Version 3.1
requires that the returned value retains its original type. This does not apply, however, where type promotion
is needed to convert all the values to a common primitive type.
Expression | Result |
---|---|
|
|
|
(Arrays are atomized). |
|
|
|
|
|
(Assuming that the current date is set to a reasonable value.) |
|
(Assuming a typical default collation.) |
|
Returns a value obtained by adding together the values in $values
.
fn:sum ( |
||
$values |
as , |
|
$zero |
as
|
:= 0 |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Any values of type xs:untypedAtomic
in $values
are cast to
xs:double
. The items in the resulting sequence may be reordered in an
arbitrary order. The resulting sequence is referred to below as the converted
sequence.
If the converted sequence is empty, then the function returns
the value of the argument $zero
, which defaults to
the xs:integer
value 0
.
If the converted sequence contains the value NaN
, NaN
is
returned.
All items in $values
must be numeric or derived from a single base type. In
addition, the type must support addition. Duration values must either all be
xs:yearMonthDuration
values or must all be
xs:dayTimeDuration
values. For numeric values, the numeric promotion
rules defined in 4.2 Arithmetic operators on numeric values are used to promote all values to a single
common type. The sum of a sequence of integers will therefore be an integer, while the
sum of a numeric sequence that includes at least one xs:double
will be an
xs:double
.
The result of the function is the value of the expression:
if (count($c) eq 0) then $zero else if (count($c) eq 1) then $c[1] else $c[1] + sum(subsequence($c, 2))
where $c
is the converted sequence.
The result of the function when a single argument is supplied is the result of the expression:
fn:sum($arg, 0)
.
A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.
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
.
If the converted sequence contains exactly one value then that value is returned.
Expression | Result |
---|---|
let $d1 := xs:yearMonthDuration("P20Y") |
|
let $d2 := xs:yearMonthDuration("P10M") |
|
let $seq1 := ($d1, $d2) |
|
let $seq3 := (3, 4, 5) |
|
|
|
sum( $seq1[. lt xs:yearMonthDuration('P3M')], xs:yearMonthDuration('P0M') ) |
|
|
|
|
|
|
|
|
|
|
(There is no requirement that the |
|
(Atomizing an array returns the sequence obtained by atomizing its members.) |
|
(Atomizing an array returns the sequence obtained by atomizing its members.) |
|
Returns true
if all items in a supplied sequence (after atomization) are equal.
fn:all-equal ( |
||
$values |
as , |
|
$collation |
as
|
:= fn:default-collation() |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
Omitting the second argument, $collation
, is equivalent to supplying
fn:default-collation()
. For more
information on collations see 5.3.5 Choosing a collation.
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
fn:distinct-values
function).
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
all-equal( ("ABC", "abc"), "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) |
|
The expression |
|
The expression |
Originally proposed for 4.0 under the name fn:uniform
.
Accepted 2022-09-20 with a change of name.
Returns true
if no two items in a supplied sequence are equal.
fn:all-different ( |
||
$values |
as , |
|
$collation |
as
|
:= fn:default-collation() |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
Omitting the second argument, $collation
, is equivalent to supplying
fn:default-collation()
. For more
information on collations see 5.3.5 Choosing a collation.
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 distinct under the rules of the
fn:distinct-values
function).
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
all-different( ("ABC", "abc"), "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) |
|
The expression |
|
The expression |
Originally proposed for 4.0 under the name fn:unique
.
Accepted 2022-09-20 with a change of name and with clarifications to the description.
This section defines a number of functions used to find elements by ID
or IDREF
value,
or to generate IDs.
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 node. |
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:id ( |
||
$values |
as , |
|
$node |
as
|
:= . |
) as
|
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns a sequence, in document order with duplicates eliminated,
containing every element node E
that satisfies all the following
conditions:
E
is in the target document. The target document is the document
containing $node
, or the document containing the context item
(.
) if the second argument is omitted. The behavior of the
function if $node
is omitted is exactly the same as if the context
item had been passed as $node
.
E
has an ID
value equal to one of the candidate
IDREF
values, where:
An element has an ID
value equal to V
if either
or both of the following conditions are true:
The is-id
property (See Section 4.5 is-id AccessorDM40.) of the element node is 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 Section 4.5 is-id AccessorDM40.) is 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 IDREF
s. If any of the tokens is not a
lexically valid IDREF
(that is, if it is not lexically an
xs:NCName
), it is ignored. Formally, the candidate
IDREF
values are the strings in the sequence given by the
expression:
for $s in $values return tokenize(normalize-space($s), ' ')[. castable as xs:IDREF]
If several elements have the same ID
value, then E
is
the one that is first in document order.
A dynamic error is raised [err:FODC0001] if
$node
, or the context item if the second argument is absent, is a node
in a tree whose root is not a document node.
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
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
fn:element-with-id
has been introduced with the desired
behavior.
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 value of type
xs:ID
or a type derived by restriction from xs:ID
.
No error is raised in respect of a candidate IDREF
value that does not
match the ID
of any element in the document. If no candidate
IDREF
value matches the ID
value of any element, the
function returns the empty sequence.
It is not necessary that the supplied argument should have type xs:IDREF
or xs:IDREFS
, or that it should be derived from a node with the
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.
Expression | Result |
---|---|
let $emp := validate lax{ document{ <employee xml:id="ID21256" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <empnr xsi:type="xs:ID">E21256</empnr> <first>John</first> <last>Brown</last> </employee> } } |
|
|
(The |
|
(Assuming the |
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 ( |
||
$values |
as , |
|
$node |
as
|
:= . |
) as
|
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Note:
The effect of this function is identical to fn:id
in respect of
elements that have an attribute with the is-id
property. However, it
behaves differently in respect of element nodes with the is-id
property.
Whereas the fn:id
function, for legacy reasons, returns the element that has 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
, or the document containing the context item
(.
) if the second argument is omitted. The behavior of the
function if $node
is omitted is exactly the same as if the context
item had been passed as $node
.
E
has an ID
value equal to one of the candidate
IDREF
values, where:
An element has an ID
value equal to V
if either
or both of the following conditions are true:
The element has an child element node whose is-id
property (See Section 4.5 is-id AccessorDM40.) is 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 Section 4.5 is-id AccessorDM40.) is 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 IDREF
s. If any of the tokens is not a
lexically valid IDREF
(that is, if it is not lexically an
xs:NCName
), it is ignored. Formally, the candidate
IDREF
values are the strings in the sequence given by the
expression:
for $s in $arg return tokenize(normalize-space($s), ' ')[. castable as xs:IDREF]
If several elements have the same ID
value, then E
is
the one that is first in document order.
A dynamic error is raised [err:FODC0001] if $node
, or the context item if the second argument is omitted, is a node
in a tree whose root is not a document node.
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
This function is equivalent to the fn:id
function except when dealing with
ID-valued element nodes. Whereas the fn:id
function selects the element
containing the identifier, this function selects its parent.
If the data model is constructed from an Infoset, an attribute will have the
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 value of type
xs:ID
or a type derived by restriction from xs:ID
.
No error is raised in respect of a candidate IDREF
value that does not
match the ID
of any element in the document. If no candidate
IDREF
value matches the ID
value of any element, the
function returns the empty sequence.
It is not necessary that the supplied argument should have type xs:IDREF
or xs:IDREFS
, or that it should be derived from a node with the
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.
Expression | Result |
---|---|
let $emp := validate lax{ document{ <employee xml:id="ID21256" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <empnr xsi:type="xs:ID">E21256</empnr> <first>John</first> <last>Brown</last> </employee> } } |
|
|
(The |
|
(Assuming the |
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:idref ( |
||
$values |
as , |
|
$node |
as
|
:= . |
) as
|
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns a sequence, in document order with duplicates eliminated,
containing every element or attribute node $N
that satisfies all the
following conditions:
$N
is in the target document. The target document is the document
containing $node
or the document containing the context item
(.
) if the second argument is omitted. The behavior of the
function if $node
is omitted is exactly the same as if the context
item had been passed as $node
.
$N
has an IDREF
value equal to one of the candidate
ID
values, where:
A node $N
has an IDREF
value equal to
V
if both of the following conditions are true:
The is-idrefs
property (see Section 4.6 is-idrefs AccessorDM40) of $N
is true
.
The sequence
tokenize(normalize-space(string($N)), ' ')
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:string
s are then
included in the list of candidate xs:ID
s. If any of the strings
in $values
is not a lexically valid xs:ID
(that is,
if it is not lexically an xs:NCName
), it is ignored. More
formally, the candidate ID
values are the strings in the
sequence:
$values[. castable as xs:NCName]
A dynamic error is raised [err:FODC0001] if
$node
, or the context item if the second argument is omitted, is a node
in a tree whose root is not a document node.
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
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 value of type
xs:IDREF
(or a type derived by restriction from xs:IDREF
).
It may also contain atomic values of other types. These atomic values are treated as
candidate ID
values if two conditions are met: their lexical form must be valid as an
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.
Expression | Result |
---|---|
let $emp := validate lax { document { <employees xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <employee xml:id="ID21256"> <empnr xsi:type="xs:ID">E21256</empnr> <first>Anil</first> <last>Singh</last> <deputy xsi:type="xs:IDREF">E30561</deputy> </employee> <employee xml:id="ID30561"> <empnr xsi:type="xs:ID">E30561</empnr> <first>John</first> <last>Brown</last> <manager xsi:type="xs:IDREF">ID21256</manager> </employee> </employees> } } |
|
$emp/( element-with-id('ID21256')/@xml:id => idref() )/ancestor::employee/last => string() |
(Assuming that |
$emp/( element-with-id('E30561')/empnr => idref() )/ancestor::employee/last => string() |
(Assuming that |
This function returns a string that uniquely identifies a given node.
fn:generate-id ( |
||
$node |
as
|
:= . |
) as
|
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the argument is omitted, it defaults to the context item (.
).
If the argument 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.
More formally, it is guaranteed that within a single
·execution scope·,
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 must consist of ASCII alphanumeric characters and must start with an alphabetic character. Thus, the string is syntactically an XML name.
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
An implementation is free to generate an identifier in any convenient way provided that it always generates the same identifier for the same node and that different identifiers are always generated from different nodes. An implementation is under no obligation to generate the same identifiers each time a document is transformed or queried.
There is no guarantee that a generated unique identifier will be distinct from any unique IDs specified in the source document.
There is no inverse to this function; it is not directly possible to find the node with
a given generated ID. Of course, it is possible to search a given sequence of nodes
using an expression such as $nodes[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 values, it is possible to use generated IDs
as surrogates for nodes when constructing a map. For example, in some implementations,
testing whether a node |
|
|
|
and then testing for membership of the node-set using: |
|
|
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($href)
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 function reads an external resource (for example, a
file) and returns a string representation of the resource. |
fn:unparsed-text-lines |
The fn:unparsed-text-lines function reads an external resource (for
example, a file) and returns its contents as a sequence of strings, one for each line
of
text in the string representation of the resource. |
fn:unparsed-text-available |
Because errors in evaluating the fn:unparsed-text function are
non-recoverable, these two functions are provided to allow an application to determine
whether a call with particular arguments would succeed. |
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
fn:environment-variable , as a (possibly empty) sequence of strings. |
Retrieves a document using a URI supplied as an xs:string
, and returns the
corresponding document node.
fn:doc ( |
||
$href |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on available documents, and static base URI.
If $href
is the empty sequence, the result is an empty sequence.
If $href
is a relative URI reference, it is resolved relative to the value
of the static base URI property from the static context. The resulting absolute URI is
promoted to an xs:string
.
If the available documents described in Section 2.1.2 Dynamic Context XP31 provides a mapping from this string to a document node, the function returns that document node.
The URI may include a fragment identifier.
By default, this function is ·deterministic·. Two
calls on this function return the same document node if the same URI Reference (after
resolution to an absolute URI Reference) is supplied to both calls. Thus, the following
expression (if it does not raise an error) will always return true
:
doc("foo.xml") is doc("foo.xml")
However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is implementation-defined. If the user has not selected such an option, a call of the function must either return a deterministic result or must raise a dynamic error [err:FODC0003].
Note:
If $href
is read from a source document, it is generally appropriate to
resolve it relative to the base URI property of the relevant node in the source
document. This can be achieved by calling the fn:resolve-uri
function,
and passing the resulting absolute URI as an argument to the fn:doc
function.
If two calls to this function supply different absolute URI References as arguments, the same document node may be returned if the implementation can determine that the two arguments refer to the same resource.
By defining the semantics of this function in terms of a 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 ·implementation-dependent·.
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 [err:FODC0002]. The data resulting from the retrieval
action is then parsed as an XML document and a tree is constructed in accordance with
the [XQuery and XPath Data Model (XDM) 3.0]. If the top-level media type is known and is
"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 [err:FODC0002]. Otherwise, the result of the function is the document node
at the root of the resulting tree. This tree is then optionally validated against a
schema.
Various aspects of this processing are ·implementation-defined·. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:
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 ·implementation-defined· whether DTD validation and/or schema validation is applied to the source document.
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 an empty sequence, or a fallback document provided by the error handler.
Implementations may provide user options that relax the requirement for the function to return deterministic results.
The effect of a fragment identifier in the supplied URI is ·implementation-defined·. One possible interpretation is to treat the fragment identifier as an ID attribute value, and to return a document node having the element with the selected ID value as its only child.
A dynamic error may be raised [err:FODC0005] if
$href
is not a valid URI reference.
A dynamic error is raised [err:FODC0002] if a relative URI reference is supplied, and the base-URI property in the static context is absent.
A dynamic error is raised [err:FODC0002] if the available documents provides no mapping for the absolutized URI.
A dynamic error is raised [err:FODC0002] if the resource cannot be retrieved or cannot be parsed successfully as XML.
A dynamic error is raised [err:FODC0003] if the implementation is not able to guarantee that the result of the function will be deterministic, and the user has not indicated that an unstable result is acceptable.
The function returns true
if and only if the function call fn:doc($href)
would return a document node.
fn:doc-available ( |
||
$href |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on available documents, and static base URI.
If $href
is an empty sequence, this function returns false
.
If a call on fn:doc($href)
would return a document node, this function
returns true
.
In all other cases this function returns false
. This
includes the case where an invalid URI is supplied, and also the case where
a valid relative URI reference is supplied, and cannot be resolved,
for example because the static base URI is absent.
If this function returns true
, then calling fn:doc($href)
within the same ·execution scope· must return a document node. However,
if nondeterministic processing has been selected for the fn:doc
function,
this guarantee is lost.
Returns a sequence of items identified by a collection URI; or a default collection if no URI is supplied.
fn:collection ( |
||
$uri |
as
|
:= () |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on available collections, and static base URI.
This function takes an xs:string
as argument and returns a sequence of
items obtained by interpreting $uri
as an xs:anyURI
and
resolving it according to the mapping specified in available
collections described in Section
C.2 Dynamic Context Components
XP31.
If available collections provides a mapping from this string to a sequence of items, the function returns that sequence. If available collections maps the string to an empty sequence, then the function returns an empty sequence.
If $uri
is not specified, the function returns the sequence of items in
the default collection in the dynamic context. See Section
C.2 Dynamic Context Components
XP31.
If $uri
is a relative xs:anyURI
, it is resolved
against the value of the base-URI property from the static context.
If $uri
is the empty sequence, the function behaves as if it had been
called without an argument. See above.
By default, this function is ·deterministic·. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is ·implementation-defined·. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error [err:FODC0003].
There is no requirement that any nodes in the result should be in document order, nor is there a requirement that the result should contain no duplicates.
A dynamic error is raised [err:FODC0002] if no URI is supplied and the value of the default collection is absentDM40.
A dynamic error is raised [err:FODC0002] if a relative URI reference is supplied, and the base-URI property in the static context is absent.
A dynamic error is raised [err:FODC0002] if available node collections provides no mapping for the absolutized URI.
A dynamic error may be raised [err:FODC0004] if $uri
is not
a valid xs:anyURI
.
In earlier versions of this specification, the primary use for the fn:collection
function
was to retrieve a collection of XML documents, perhaps held as lexical XML in operating
system filestore, or perhaps held in an XML database. In this release the concept has
been generalised to allow other resources to be retrieved: for example JSON documents might
be returned as arrays or maps, non-XML text files might be returned as strings, and binary
files might be returned as instances of xs:base64Binary
.
The abstract concept of a collection might be realized in different ways by different implementations, and the ways in which URIs map to collections can be equally variable. Specifying resources using URIs is useful because URIs are dynamic, can be parameterized, and do not rely on an external environment.
Returns a sequence of xs:anyURI
values representing the URIs in a URI
collection.
fn:uri-collection ( |
||
$uri |
as
|
:= () |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on available URI collections, and static base URI.
The zero-argument form of the function returns the URIs in the default URI collection described in Section C.2 Dynamic Context Components XP31.
If $uri
is a relative xs:anyURI
, it is resolved
against the value of the base-URI property from the static context.
If $uri
is the empty sequence, the function behaves as if it had been
called without an argument. See above.
The single-argument form of the function returns the sequence of URIs corresponding to the supplied URI in the available URI collections described in Section C.2 Dynamic Context Components XP31.
By default, this function is ·deterministic·. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is ·implementation-defined·. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error [err:FODC0003].
There is no requirement that the URIs returned by this function should all be distinct, and no assumptions can be made about the order of URIs in the sequence, unless the implementation defines otherwise.
A dynamic error is raised [err:FODC0002] if no URI is supplied (that is, if the function is called with no arguments, or with a single argument that evaluates to an empty sequence), and the value of the default resource collection is absentDM40.
A dynamic error is raised [err:FODC0002] if a relative URI reference is supplied, and the base-URI property in the static context is absent.
A dynamic error is raised [err:FODC0002] if available resource collections provides no mapping for the absolutized URI.
A dynamic error may be raised [err:FODC0004] if $uri
is not
a valid xs:anyURI
.
In some implementations, there might be a close relationship between collections (as retrieved
by the fn:collection
function), and URI collections (as retrieved by this function).
For example, a collection might return XML documents, and the corresponding URI collection might return
the URIs of those documents. However, this specification does not impose such a close relationship. For example, there
may be collection URIs accepted by one of the two functions and not by the other; a collection might contain
items that do not have any URI; or a URI collection might contain URIs that cannot be dereferenced to return any
resource.
Thus, some implementations might ensure that calling fn:uri-collection
and then
applying fn:doc
to each of the returned URIs delivers the same result as
calling fn:collection
with the same argument; however, this is not
guaranteed.
In the case where fn:uri-collection
returns the URIs of resources that
could also be retrieved directly using fn:collection
, there are several reasons why it
might be appropriate to use this function in preference
to the fn:collection
function. For example:
It allows different URIs for different kinds of resource to be dereferenced in
different ways: for
example, the returned URIs might be referenced using the
fn:unparsed-text
function rather than the fn:doc
function.
In XSLT 3.0 it allows the documents in a collection to be processed in streaming mode using the
xsl:stream
instruction.
It allows recovery from failures to read, parse, or validate individual documents,
by calling the fn:doc
(or other dereferencing) function within the scope of try/catch.
It allows selection of which documents to read based on their URI, for example
they can be filtered to select those whose URIs end in .xml
, or those
that use the https
scheme.
An application might choose to limit the number of URIs processed in a single run, for example it might process only the first 50 URIs in the collection; or it might present the URIs to the user and allow the user to select which of them need to be further processed.
It allows the URIs to be modified before they are dereferenced, for example by adding or removing query parameters, or by redirecting the request to a local cache or to a mirror site.
For some of these use cases, this assumes that the cost of calling
fn:collection
might be significant (for example, it might involving
retrieving all the documents in the collection over the network and parsing them). This
will not necessarily be true of all implementations.
The fn:unparsed-text
function reads an external resource (for example, a
file) and returns a string representation of the resource.
fn:unparsed-text ( |
||
$href |
as , |
|
$encoding |
as
|
:= () |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.
The $href
argument must be a string in the form of a URI
reference, which must contain no fragment identifier, and
must identify a resource for which a string representation is
available. If the URI is a relative URI reference, then it is resolved relative to the
static base URI property from the static context.
The mapping of URIs to the string representation of a resource is the mapping defined in the available text resourcesXP31 component of the dynamic context.
If the $href
argument is an empty sequence, the function
returns an empty sequence.
The $encoding
argument, if present
and non-empty, is the name of an encoding. The values
for this attribute follow the same rules as for the encoding
attribute in
an XML declaration. The only values which every
implementation is required to recognize are
utf-8
and utf-16
.
The encoding of the external resource is determined as follows:
external encoding information is used if available, otherwise
if the media type of the resource is text/xml
or
application/xml
(see [RFC 2376]), or if it matches
the conventions text/*+xml
or application/*+xml
(see
[RFC 7303] and/or its successors), then the encoding is recognized
as specified in [Extensible Markup Language (XML) 1.0 (Fifth Edition)], otherwise
the $encoding
argument is used if present, otherwise
the processor may use ·implementation-defined· heuristics to determine the likely encoding, otherwise
UTF-8 is assumed.
The result of the function is a string containing the string representation of the resource retrieved using the URI.
A dynamic error is raised [err:FOUT1170] if the $href
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.
A dynamic error is raised [err:FOUT1190] if the value of the
$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 ·characters· using the specified
encoding, or if the resulting characters are not
·permitted character·.
A dynamic error is raised [err:FOUT1200] if $encoding
is absent and the processor cannot infer the
encoding using external information and the encoding is not UTF-8.
If it is appropriate to use a base URI other than the dynamic base URI (for example,
when resolving a relative URI reference read from a source document) then it is
advisable to resolve the relative URI reference using the fn: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 two
functions fn:unparsed-text
and fn:doc
(a URI accepted by one
may or may not be accepted by the other), and if a URI is accepted by both there is no
essential relationship between the results (different resource representations are
permitted by the architecture of the web).
There are no constraints on the MIME type of the resource.
The fact that the resolution of URIs is defined by a mapping in the dynamic context means that in effect, various aspects of the behavior of this function are ·implementation-defined·. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:
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-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.
Implementations may provide user options that relax the requirement for the function to return deterministic results.
The rules for determining the encoding are chosen for consistency with [XML Inclusions (XInclude) Version 1.0 (Second Edition)]. Files with an XML media type are treated specially because there are use cases for this function where the retrieved text is to be included as unparsed XML within a CDATA section of a containing document, and because processors are likely to be able to reuse the code that performs encoding detection for XML external entities.
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: |
|
<xsl:output method="html"/> <xsl:template match="/"> <xsl:value-of select="unparsed-text('header.html', 'iso-8859-1')" disable-output-escaping="yes"/> <xsl:apply-templates/> <xsl:value-of select="unparsed-text('footer.html', 'iso-8859-1')" disable-output-escaping="yes"/> </xsl:template> |
The fn:unparsed-text-lines
function reads an external resource (for
example, a file) and returns its contents as a sequence of strings, one for each line of
text in the string representation of the resource.
fn:unparsed-text-lines ( |
||
$href |
as , |
|
$encoding |
as
|
:= () |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.
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 result of the single-argument function is the same as the result of the expression
fn:tokenize(fn:unparsed-text($href), '\r\n|\r|\n')[not(position()=last() and
.='')]
. The result of the two-argument function is the same as the result of
the expression fn:tokenize(fn:unparsed-text($href, $encoding),
'\r\n|\r|\n')[not(position()=last() and .='')]
.
The result is thus a sequence of strings containing the text of the resource retrieved using the URI, each string representing one line of text. Lines are separated by one of the sequences x0A, x0D, or x0Dx0A. The characters representing the newline are not included in the returned strings. If there are two adjacent newline sequences, a zero-length string will be returned to represent the empty line; but if the external resource ends with the sequence x0A, x0D, or x0Dx0A, the result will be as if this final line ending were not present.
Error conditions are the same as for the fn:unparsed-text
function.
See the notes for fn:unparsed-text
.
Because errors in evaluating the fn:unparsed-text
function are
non-recoverable, these two functions are provided to allow an application to determine
whether a call with particular arguments would succeed.
fn:unparsed-text-available ( |
||
$href |
as , |
|
$encoding |
as
|
:= () |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.
The fn:unparsed-text-available
function determines whether a call
on the fn:unparsed-text
function with identical arguments would
return a string.
If the first argument is an empty sequence, the function returns false
.
In other cases, the function returns true
if a call on
fn:unparsed-text
with the same arguments would succeed, and
false
if a call on fn:unparsed-text
with the same arguments would
fail with a non-recoverable dynamic error.
The functions fn:unparsed-text
and
fn:unparsed-text-available
have the same requirement for
·determinism· as the functions
fn:doc
and fn:doc-available
. This means that unless the
user has explicitly stated a requirement for a reduced level of determinism, either of
these functions if called twice with the same arguments during the course of a
transformation must return the same results each time; moreover, the
results of a call on fn:unparsed-text-available
must be consistent with the results of a subsequent call on
unparsed-text
with the same arguments.
This requires that the fn:unparsed-text-available
function should
actually attempt to read the resource identified by the URI, and check that it is
correctly encoded and contains no characters that are invalid in XML. Implementations
may avoid the cost of repeating these checks for example by caching the validated
contents of the resource, to anticipate a subsequent call on the
fn:unparsed-text
or fn:unparsed-text-lines
function. Alternatively, implementations may be able to rewrite an expression such as
if (unparsed-text-available(A)) then unparsed-text(A) else ...
to
generate a single call internally.
Since the function fn:unparsed-text-lines
succeeds or fails under
exactly the same circumstances as fn:unparsed-text
, the
fn:unparsed-text-available
function may equally be used to test
whether a call on fn:unparsed-text-lines
would succeed.
Returns the value of a system environment variable, if it exists.
fn:environment-variable ( |
||
$name |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on environment variables.
The set of available environment variablesXP31 is a set of (name, value) pairs forming part of the dynamic context, in which the name is unique within the set of pairs. The name and value are arbitrary strings.
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 ·implementation-defined·, but must be the same as the collation used to ensure that the names of all environment variables are unique.
The function is ·deterministic·, which means that if it is called several times within the same ·execution scope·, with the same arguments, it must return the same result.
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 [POSIX.1-2008] (Chapter 8, Environment Variables). Implementations may use prefixes or other naming conventions to disambiguate the names.
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 may choose to provide access to the environment variables associated with the process in which the query or stylesheet processing was initiated.
Security advice: Queries from untrusted sources should not be permitted unrestricted
access to environment variables. For example, the name of the account under which the
query is running may be useful information to a would-be intruder. An implementation may
therefore choose to restrict access to the environment, or may provide a facility to
make fn:environment-variable
always return the empty sequence.
Returns a list of environment variable names that are suitable for passing to
fn:environment-variable
, as a (possibly empty) sequence of strings.
fn:available-environment-variables () as xs:string* |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on environment variables.
The function returns a sequence of strings, being the names of the environment variables in the dynamic context in some ·implementation-dependent· order.
The function is ·deterministic·: that is, the set of available environment variables does not vary during evaluation.
The function returns a list of strings, containing no duplicates.
It is intended that the strings in this list should be suitable for passing to
fn:environment-variable
.
See also the note on security under the definition of the
fn:environment-variable
function. If access to environment variables has
been disabled, fn:available-environment-variables
always returns the empty
sequence.
These functions convert between the lexical representation and XPath and XQuery data model representation of various file formats.
These functions convert between the lexical representation of XML and the tree representation.
Function | Meaning |
---|---|
fn:parse-xml |
This function takes as input an XML document represented as a string, and returns the document node at the root of an XDM tree representing the parsed document. |
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
[XSLT and XQuery Serialization 3.1], returning the serialized representation
of the sequence as a string. |
This function takes as input an XML document represented as a string, and returns the document node at the root of an XDM tree representing the parsed document.
fn:parse-xml ( |
||
$value |
as
|
|
) as
|
This function is ·nondeterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.
If $value
is the empty sequence, the function returns the empty sequence.
The precise process used to construct the XDM instance is ·implementation-defined·. In particular, it is implementation-defined whether DTD and/or schema validation is invoked, and it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used.
The static base URI property from the static context of the fn:parse-xml
function call is used both as the base URI used by the XML parser to resolve relative
entity references within the document, and as the base URI of the document node that is
returned.
The document URI of the returned node is absentDM40.
The function is not ·deterministic·: that is, if the function is called twice with the same arguments, it is ·implementation-dependent· whether the same node is returned on both occasions.
A dynamic error is raised [err:FODC0006] if the content of
$value
is not a well-formed and namespace-well-formed XML document.
A dynamic error is raised [err:FODC0006] if DTD-based validation is
carried out and the content of $value
is not valid against its DTD.
Since the XML document is presented to the parser as a string, rather than as a sequence of octets, the encoding specified within the XML declaration has no meaning. If the XML parser accepts input only in the form of a sequence of octets, then the processor must ensure that the string is encoded as octets in a way that is consistent with rules used by the XML parser to detect the encoding.
The primary use case for this function is to handle input documents that contain nested
XML documents embedded within CDATA sections. Since the content of the CDATA section are
exposed as text, the receiving query or stylesheet may pass this text to the
fn:parse-xml
function to create a tree representation of the nested
document.
Similarly, nested XML within comments is sometimes encountered, and lexical XML is sometimes returned by extension functions, for example, functions that access web services or read from databases.
A use case arises in XSLT where there is a need to preprocess an input document before
parsing. For example, an application might wish to edit the document to remove its
DOCTYPE declaration. This can be done by reading the raw text using the
fn:unparsed-text
function, editing the resulting string, and then
passing it to the fn:parse-xml
function.
The expression |
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:parse-xml-fragment ( |
||
$value |
as
|
|
) as
|
This function is ·nondeterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.
If $value
is the empty sequence, the function returns the empty sequence.
The input must be a namespace-well-formed external general parsed entity. More specifically, it must be a string conforming to the production rule extParsedEntXML in [Extensible Markup Language (XML) 1.0 (Fifth Edition)], it must contain no entity references other than references to predefined entities, and it must satisfy all the rules of [Namespaces in XML] for namespace-well-formed documents with the exception that the rule requiring it to be a well-formed document is replaced by the rule requiring it to be a well-formed external general parsed entity.
The string is parsed to form a sequence of nodes which become children of the new document node, in the same way as the content of any element is converted into a sequence of children for the resulting element node.
Schema validation is not invoked, which means that the nodes in the returned document will all be untyped.
The precise process used to construct the XDM instance is ·implementation-defined·. In particular, it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used.
The static base URI from the static context of the fn:parse-xml-fragment
function call is used as the base URI of the document node that is returned.
The document URI of the returned node is absentDM40.
The function is not ·deterministic·: that is, if the function is called twice with the same arguments, it is ·implementation-dependent· whether the same node is returned on both occasions.
A dynamic error is raised [err:FODC0006] if the content of
$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 fn:parse-xml
function.
The main differences between fn:parse-xml
and
fn:parse-xml-fragment
are that for fn:parse-xml
, the
children of the resulting document node must contain exactly one element node and no
text nodes, wheras for fn:parse-xml-fragment
, the resulting document node
can have any number (including zero) of element and text nodes among its children. An
additional difference is that the text declaration at the start of an
external entity has slightly different syntax from the XML declaration at
the start of a well-formed document.
Note that all whitespace outside the text declaration is significant, including whitespace that precedes the first element node.
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.
The expression
|
|
The expression |
|
The expression |
|
The expression |
|
The expression |
This function serializes the supplied input sequence $input
as described in
[XSLT and XQuery Serialization 3.1], returning the serialized representation
of the sequence as a string.
fn:serialize ( |
||
$input |
as , |
|
$options |
as
|
:= () |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The value of the first argument $input
acts as the input sequence to the serialization process,
which starts with sequence normalization.
The second argument $options
, if present, provides serialization parameters. These may be supplied in either
of two forms:
As an output:serialization-parameters
element, having the format described in Section
3.1 Setting Serialization Parameters by Means of a Data Model Instance
SER31. In this case the type of the supplied
argument must match the required type 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 an 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 ·implementation-defined·,
and may depend on the context.
If the second argument is supplied as a map, then the ·option parameter conventions· apply. In this case:
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
|
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-separator
|
xs:string?
|
absent | |
json-node-output-method
|
union(xs:string, xs:QName)?
|
See Notes 1, 2 |
xml
|
media-type
|
xs:string?
|
(a media type suitable for the chosen method ) |
|
method
|
union(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 |
map{}
|
version
|
xs:string?
|
1.0
|
Notes to the table:
The notation union(A, B)
is used to represent a union type whose member types are A
and B
.
If an xs:QName
is supplied for the method
or json-node-output-method
options, then it must have a non-absent namespace URI. This
means that system-defined serialization methods such as xml
and json
are defined as strings, not as xs:QName
values.
For the use-character-maps
option, the value is a map, whose keys
are the characters to be mapped (as xs:string
instances),
and whose corresponding values are the strings to be substituted for these characters.
A type error [err:XPTY0004]XP occurs if the $options
argument
is present and does not match either of the types element(output:serialization-parameters)?
or map(*)
.
Note:
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 [err:FODC0010] is raised.
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 ·option parameter conventions·,
a type error [err:XPTY0004]XP is raised.
If the value is of the correct type, but does not satisfy the rules for that
parameter defined in [XSLT and XQuery Serialization 3.1], then a dynamic error
[err:SEPM0016]SER31 is raised. (For example, this occurs if the map supplied to
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 fn:serialize
call failing with
a dynamic error.
One use case for this function arises when there is a need to construct an XML document
containing nested XML documents within a CDATA section (or on occasions within a
comment). See fn:parse-xml
for further details.
Another use case arises when there is a need to call an extension function that expects a lexical XML document as input.
Another use case for this function is serializing instances of the data model into a human
readable format for the purposes of debugging. Using the Section
10 Adaptive Output Method
SER31 by specifying it as the output method defined in the second argument via
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 an empty map) is supplied for the argument.
Expression | Result |
---|---|
Given the variables: |
|
let $params := <output:serialization-parameters xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization"> <output:omit-xml-declaration value="yes"/> </output:serialization-parameters> |
|
let $data := <a b="3"/> |
|
The following call might produce the output shown: |
|
|
|
The following call would also produce the output shown (though the second argument could equally well be supplied
as an empty map ( |
|
serialize( $data, map { "method": "xml", "omit-xml-declaration": true() } ) |
|
The expression |
|
The expression |
The functions listed parse or serialize JSON data.
Function | Meaning |
---|---|
fn:parse-json |
Parses a string 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 document node. |
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. |
fn:items-to-json |
|
fn:elements-to-maps |
Converts a sequence of element nodes to a sequence of maps, suitable for serialization as JSON. |
Note also that the function fn:serialize
has an option to act as the inverse function to fn:parse-json
.
Parses a string supplied in the form of a JSON text, returning the results typically in the form of a map or array.
fn:parse-json ( |
||
$value |
as , |
|
$options |
as
|
:= map{} |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the one-argument form of this function is the same as calling the
two-argument form with an empty map as the value of the $options
argument.
The first argument is a JSON text as defined in [RFC 7159], in the form of a string. The function parses this string to return an XDM value.
If $value
is the empty sequence, the function returns the empty sequence.
Note:
The result will also be an empty sequence if $value
is the string "null"
.
The $options
argument can be used to control the way in which the parsing
takes place. The ·option parameter conventions· apply.
The entries that may appear in the $options
map are as follows:
Key | Value | Meaning |
---|---|---|
liberal |
Determines whether deviations from the syntax of RFC7159 are permitted.
|
|
false |
The input must consist of an optional byte order mark (which is ignored) followed by a string
that conforms to the grammar of JSON-text in [RFC 7159]. An error must be raised
[err:FOJS0001] if the input does not conform to the grammar.
|
|
true |
The input may contain deviations from the grammar of [RFC 7159], which are handled in an ·implementation-defined· way. (Note: some popular extensions include allowing quotes on keys to be omitted, allowing a comma to appear after the last item in an array, allowing leading zeroes in numbers, and allowing control characters such as tab and newline to be present in unescaped form.) Since the extensions accepted are implementation-defined, an error may be raised [err:FOJS0001] if the input does not conform to the grammar. | |
duplicates |
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 , in which
case keys are compared in escaped form.
|
|
reject |
An error is raised [err:FOJS0003] if duplicate keys are encountered. | |
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. | |
escape |
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) are passed to the fallback function
as described below; in the absence of a fallback function, they are replaced by
the Unicode REPLACEMENT CHARACTER (xFFFD ).
|
|
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:
\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.
|
|
fallback |
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 a special character (as defined
under
the escape option) that is valid according to the JSON
grammar, whether the special character is represented in the input directly or as
an escape sequence.
The function is called once for any surrogate
that is not properly paired with another surrogate. The string 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 . The function is not
called for an escape sequence that is invalid against the grammar (for example \x0A ). The function returns a string
which is inserted into the result in place of the invalid character. The
function also has the option of raising a dynamic error by calling fn:error .
|
|
number-parser |
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 union(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:string . Before calling the supplied number-parser ,
the value is first checked to ensure that it conforms to the JSON grammar (for example,
a leading plus sign and redundant leading zeroes are not allowed); these checks are
disabled
if the liberal option is set to true .
|
|
() |
If no function is supplied, numbers are processed by casting the supplied value to
xs:double .
|
The various structures that can occur in JSON are transformed recursively to XDM values as follows:
A JSON object is converted to a map.
The entries in the map correspond to the key/value
pairs in the JSON object. The key is always of type 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
map{"x":2, "y":5}
.
If duplicate keys are encountered in a JSON object, they are handled
as determined by the duplicates
option defined above.
A JSON array is transformed to an array whose members are the result of converting
the corresponding member of the array by recursive application of these rules. For
example, the JSON text ["a", "b", null]
is transformed to the value
["a", "b", ()]
.
A JSON string is converted to an xs:string
value.
The handling of special characters depends on the
escape
and fallback
options, as described in the table above.
A JSON number is processed using the function supplied
in the number-parser
option; by default it is converted to an xs:double
value using
the rules for casting from xs:string
to xs:double
.
The JSON boolean values true
and false
are
converted to the corresponding xs:boolean
values.
The JSON value null is converted to the empty sequence.
A dynamic error [err:FOJS0001] occurs if the value of
$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 [err:FOJS0003] occurs if the option
"duplicates":"reject"
is present and the value of
$value
contains a JSON object with duplicate keys.
A dynamic error [err:FOJS0005] occurs if the $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 input starts with a byte order mark, this function ignores it. The byte order mark may have been added to the data stream in order to facilitate decoding of an octet stream to a character string, but since this function takes a character string as input, the byte order mark serves no useful purpose.
The possibility of the input containing characters that are not valid in XML (for example, unpaired surrogates)
arises only when such characters are expressed using JSON escape sequences. The is because the input to the function
is an instance of xs:string
, which by definition can only contain characters that are valid in XML.
Expression | Result |
---|---|
|
|
|
|
|
|
parse-json( '{"x":"\\", "y":"\u0025"}', map { 'escape': true() } ) |
|
parse-json( '{"x":"\\", "y":"\u0000"}' ) |
|
parse-json( '{"x":"\\", "y":"\u0000"}', map { 'escape': true() } ) |
|
parse-json( '{"x":"\\", "y":"\u0000"}', map { 'fallback': function($s) { '['||$s||']' } } ) |
|
Reads an external resource containing JSON, and returns the result of parsing the resource as JSON.
fn:json-doc ( |
||
$href |
as , |
|
$options |
as
|
:= map{} |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.
The effect of the single-argument call fn:json-doc($H)
is the same as the effect of the two-argument call
fn:json-doc($H, map{})
where an empty map is supplied as the second argument.
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.
If the resource contains characters that are not
·permitted characters·,
then rather than raising an error as fn:unparsed-text#1
does, the function replaces such characters by the equivalent
JSON escape sequence prior to parsing.
Note:
Equivalently, the implementation can use some other internal representation of strings that allows non-XML characters to be manipulated.
If $href
is the empty sequence, the function returns the empty sequence.
The function may raise any error defined for the fn:unparsed-text
or fn:parse-json
functions.
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 fn:unparsed-text
function.
If the input can be decoded,
then the possibility still arises that the resulting sequence of codepoints includes codepoints that do not represent characters that are valid in the
version of XML that the processor supports. Such codepoints are translated into JSON escape sequences (for example, \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 Unicode REPLACEMENT CHARACTER
(xFFFD
).
Parses a string supplied in the form of a JSON text, returning the results in the form of an XML document node.
fn:json-to-xml ( |
||
$value |
as , |
|
$options |
as
|
:= map{} |
) as
|
This function is ·nondeterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.
The effect of the one-argument form of this function is the same as calling the
two-argument form with an empty map as the value of the $options
argument.
The first argument is a JSON-text as defined in [RFC 7159], in the form of a string. The function parses this string to return an XDM node.
If $value
is an empty sequence, the function returns the empty sequence.
The $options
argument can be used to control the way in which the parsing
takes place. The ·option parameter conventions· apply.
The entries that may appear in the $options
map are as follows:
Key | Value | Meaning |
---|---|---|
liberal |
Determines whether deviations from the syntax of RFC7159 are permitted.
|
|
false |
The input must consist of an optional byte order mark (which is ignored) followed by a string
that conforms to the grammar of JSON-text in [RFC 7159]. An error must be raised
(see below) if the input does not conform to the grammar.
|
|
true |
The input may contain deviations from the grammar of [RFC 7159], which are handled in an ·implementation-defined· way. (Note: some popular extensions include allowing quotes on keys to be omitted, allowing a comma to appear after the last item in an array, allowing leading zeroes in numbers, and allowing control characters such as tab and newline to be present in unescaped form.) Since the extensions accepted are implementation-defined, an error may be raised (see below) if the input does not conform to the grammar. | |
duplicates |
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 , in which
case keys are compared in escaped form.
|
|
reject |
An error is raised [err:FOJS0003] if duplicate keys are encountered. | |
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
[err:FOJS0005]
|
|
validate |
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 C.2 Schema for the result of fn:json-to-xml, or against an
·implementation-defined· schema
if the liberal option has the value true .
|
|
false |
Indicates that the resulting XDM instance must be untyped. | |
escape |
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) are passed to the fallback function
as described below; in the absence of a fallback function, they are replaced by
the Unicode REPLACEMENT CHARACTER (xFFFD ).
The attributes 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:
\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:
|
|
fallback |
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, the function is called once for any six-character
escape sequence
that is not properly paired with another surrogate. The string 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 . The function is not
called for an escape sequence that is invalid against the grammar (for example \x0A ).
The function returns a string
which is inserted into the result in place of the invalid character. The
function also has the option of raising a dynamic error by calling fn:error .
|
The various structures that can occur in JSON are transformed recursively to XDM values according to the rules given in 15.5.2 XML Representation of JSON.
The function returns a document node, whose only child is the element node representing the outermost construct in the JSON text.
The function is ·non-deterministic with respect to node identity·: that is, if the function is called twice with the same arguments, it is ·implementation-dependent· whether the same node is returned on both occasions.
The base URI of the returned document node is taken from the static base URI of the function call.
The choice of namespace prefix (or absence of a prefix) in the names of constructed nodes is ·implementation-dependent·.
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, or 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 [err:FOJS0001] if the value of
$value
does not conform to the JSON grammar as defined
by [RFC 7159], unless the option "liberal":true()
is present and
the processor chooses to accept the deviation.
An error is raised [err:FOJS0004] if the value of
the validate
option is true
and the processor does not support
schema validation or typed data.
An error is raised [err:FOJS0005] if the value of
$options
includes an entry whose key is defined in this specification,
and whose value is not a permitted value for that key.
To read a JSON file, this function can be used in conjunction with the
fn:unparsed-text
function.
Many JSON implementations allow commas to be used after the last item in an object or
array, although the specification does not permit it. The option
spec="liberal"
is provided to allow such deviations from the
specification to be accepted. Some JSON implementations also allow constructors such as
new Date("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 C.2 Schema for the result of fn:json-to-xml.
If the input starts with a byte order mark, this function ignores it. The byte order mark may have been added to the data stream in order to facilitate decoding of an octet stream to a character string, but since this function takes a character string as input, the byte order mark serves no useful purpose.
The possibility of the input containing characters that are not valid in XML (for example, unpaired surrogates)
arises only when such characters are expressed using JSON escape sequences. The is because the input to the function
is an instance of xs:string
, which by definition can only contain characters that are valid in XML.
Expression | Result |
---|---|
json-to-xml( '{"x": 1, "y": [3,4,5]}', map { "validate": false() } ) |
<map xmlns="http://www.w3.org/2005/xpath-functions"> <number key="x">1</number> <array key="y"> <number>3</number> <number>4</number> <number>5</number> </array> </map> (with whitespace added for legibility) |
json-to-xml( '"abcd"', map { 'liberal': false() } ) |
|
json-to-xml( '{"x": "\\", "y": "\u0025"}', map { "validate": false() } ) |
<map xmlns="http://www.w3.org/2005/xpath-functions"> <string key="x">\</string> <string key="y">%</string> </map> (with whitespace added for legibility) |
json-to-xml( '{"x": "\\", "y": "\u0025"}', map { 'escape': true(), "validate": false() } ) |
<map xmlns="http://www.w3.org/2005/xpath-functions"> <string escaped="true" key="x">\\</string> <string key="y">%</string> </map> (with whitespace added for legibility) (But see the detailed rules for alternative values of the |
The following example illustrates use of the |
|
let $jsonstr := unparsed-text('http://example.com/endpoint'), $options := map { 'liberal': true(), 'fallback': function($char as xs:string) as xs:string { let $c0chars := map { '\u0000':'[NUL]', '\u0001':'[SOH]', '\u0002':'[STX]', ... '\u001E':'[RS]', '\u001F':'[US]' }, $replacement := $c0chars($char) return if (exists($replacement)) then $replacement else error(xs:QName('err:invalid-char'), 'Error: ' || $char || ' is not a C0 control character.') } } return json-to-xml($jsonstr, $options) |
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.
fn:xml-to-json ( |
||
$node |
as , |
|
$options |
as
|
:= map{} |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the one-argument form of this function is the same as calling the
two-argument form with an empty map as the value of the $options
argument.
The first argument $node
is a node; the subtree rooted at this node will typically be
the XML representation of a JSON document as defined in 15.5.2 XML Representation of JSON.
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 ·option parameter conventions· apply.
The entries that may appear in the $options
map are as follows:
Key | Value | Meaning |
---|---|---|
indent |
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 may insert whitespace between JSON tokens in order to improve readability. The specification imposes no constraints on how this is done. | |
number-formatter |
Determines how numeric values should be formatted.
|
|
User-supplied function |
The supplied function is called to process the string value of all fn:number
elements in the input. For example, setting the value to fn:identity#1
causes the value to be output unchanged. There is no requirement that the result should
be valid JSON.
|
|
() |
If no function is supplied, numbers are formatted by converting the string value of
the fn:number element to an xs:double , and then converting
the result to a string using the casting rules. Note that this will result in exponential
notation being used for values outside the range
1e-6 to 1e+6 . A dynamic error occurs for values
such as infinity and NaN where the resulting JSON would be invalid.
|
The node supplied as $node
must be one of the following: [err:FOJS0006]
An element node whose name matches the name of a global element declaration in the schema given in C.2 Schema for the result of fn:json-to-xml (“the schema”) and that is valid as defined below:
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 may attempt to validate the element against the schema, in which case it is treated as valid if and only if the outcome of validation is valid.
Otherwise (if the processor does not attempt validation using the schema),
the processor must ensure that the content of the element,
after stripping all attributes (at any depth) in namespaces other than
http://www.w3.org/2005/xpath-functions
, is such that validation
against the schema would have an outcome of valid.
Note:
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 C1 and C2)
such that the normalized key of C1 is equal to the normalized key of C2. 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 term
“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:
If the number-formatter
option is present and non-empty,
the supplied function is called, with the string value of $E
as its argument,
and the result is output (whether or not it is valid JSON).
Otherwise, the result of the expression xs:string(xs:double(fn:string($E)))
is output.
Note:
The default formatting results in exponential format being used for numbers whose
absolute value is outside the range 1e-6
to 1e+6
;
although this is valid according to the JSON specification, some receiving
applications may be unable to process it. Possible reasons for using
a number-formatter
might be:
To avoid use of exponential notation in the output.
To avoid loss of precision when the numbers to be output have
greater precision than an xs:double
.
To improve the human readability of the output, for example by calling fn:format-number
to limit the number of decimal places in the result.
To avoid errors when dealing with values that JSON cannot handle, such as Infinity and NaN
(for example, by emitting these as strings within quotation marks).
An element named string
results in the output of the string value of the element, enclosed in
quotation marks, with any special characters in the string escaped as described below.
An element named array
results in the output of the children of the array
element,
each processed by applying these rules recursively: the items in the resulting list are enclosed between square brackets,
and separated by commas.
An element named map
results in the output of a sequence of map entries corresponding to
the children of the map
element, enclosed between curly braces and separated by commas.
Each entry comprises the value of the key
attribute of the child element, enclosed in quotation marks
and escaped as described below, followed by a colon, followed by the result of processing the child element
by applying these rules recursively.
Comments, processing instructions, and whitespace text node children of map
and array
are ignored.
Strings are escaped as follows:
If the attribute escaped="true"
is present for a string value, or 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 [err:FOJS0007];
any unescaped occurrence of quotation mark, backspace, form-feed, newline, carriage return, tab, or solidus is replaced by
\"
, \b
, \f
, \n
, \r
, \t
, or \/
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.
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 quotation mark, backspace, form-feed, newline, carriage return, or tab is
replaced by \"
, \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 [err:FOJS0005] if the value of
$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 [err:FOJS0006] if the value of
$node
is not a document or element node or is not valid according to the schema for the XML representation of
JSON, or if a map
element has two children whose normalized key values are the same.
A dynamic error is raised [err:FOJS0007] if the value of
$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. Most cases of duplicate keys are prevented by the rules in the schema;
additional cases (where the keys are equal only after expanding JSON escape sequences) are prevented by the prose rules
of this function. For example, the key values \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 fn:json-to-xml
function
to be processed: for example, it is possible to take a JSON document, convert it to XML, select
a subtree based on the value of a 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 |
Converts a sequence of element nodes to a sequence of maps, suitable for serialization as JSON.
fn:elements-to-maps ( |
||
$elements |
as , |
|
$options |
as
|
:= map{} |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function converts the supplied element nodes to maps. The conversion is one-to-one and retains order: for each element node in the input, there will be a corresponding map in the output. The form of the generated maps is designed to be suitable for serialization as JSON using the JSON output method.
The conversion can process any element nodes whatsoever, but it is not lossless. For example, information about base URIs and unused in-scope namespaces is lost.
The element nodes actually present in the $elements
argument are refered to as top-level
elements; their descendant elements are refered to as descendant elements.
The entries that may appear in the $options
map are as follows:
Key | Value | Meaning |
---|---|---|
uniform |
Indicates that all elements with the same name (except where schema type information
is available)
should use the same JSON layout. Setting this option requires the processor to analyze
the entire input
before deciding what layout to use for each element; but by ensuring consistency across
elements, it may
make the resulting JSON easier to process.
|
|
false |
The layout for each element node is decided independently, based on its individual content. | |
true |
In the absence of schema type information, and of an explicit entry in the layouts
property, the layout chosen for a given element node must be the same as that for
all other
elements of the same name.
|
|
layouts |
A mapping from element names to layout names, used to override the default
formatting rules for a particular element name.
|
A top-level element node is output as a map comprising a single key-value pair, where the key is a string derived from the element name as described below, and the content follows the rules of a specific layout appropriate to that element.
The name of a top-level element is represented as follows:
If the element name is in no namespace, as a string containing the local part of the element name.
If the element name is in a namespace, as a string in the format
Q{uri}local
, where uri
is the namespace, and local
is the local part of the element name.
For a descendant element, the name is represented as follows:
If the element name is in the same namespace as its parent, or if both are in no namespace, then as a string containing the local part of the element name.
Otherwise, as a string in the format
Q{uri}local
, where uri
is the namespace (or the empty string
to represent no namespace), and local
is the local part of the element name.
Note that prefixes used in element names are not retained; neither are the prefix-to-uri mappings represented by namespace nodes in the XDM tree.
Note:
Where an element appears as a child of an element formatted using record layout
(see 15.6.1.7 Record Layout), its name is when necessary suffixed by an index such as "[1]"
or "[2]"
to make it unique.
The available layouts are described in 15.6 Converting Elements to Maps. A layout is selected for each element node E by applying the following rules in order:
If the name of E is listed as the key of an entry in the layouts
option, then the corresponding named layout is used.
If E has a type annotation T other than xs:untyped
or xs:anyType
, then the layout appropriate to its schema type
is used. Specifically, taking the layouts in the order presented in
15.6.1 Element Layouts, the first layout whose XSD conditions
are satisfied by T is chosen.
If the option uniform
is set to false (which is its default value),
then the chosen layout is the first layout, in the order they are listed in
15.6.1 Element Layouts, whose match pattern
matches E.
If the option uniform
is set to true, then let S
be the set of all element nodes in the input having the same name as E,
with type annotation xs:untyped
or xs:anyType
,
including both top-level element nodes and descendant element nodes.
The chosen layout is then the first layout, in the order they are listed in
15.6.1 Element Layouts, whose match pattern matches
every element node in S.
A dynamic error is raised if the selected layout rules require atomization of an element that does not have a typed value (typically because it has been validated against an element-only content model): [err:FOTY0012].
The namespace URI and local name of all elements and attributes is available in the JSON output. Prefixes are not retained, and namespaces that are declared but not used are not retained.
The distinction between different atomic types is lost, except for the boolean/number/string distinction present in JSON.
Expression | Result |
---|---|
elements-to-maps(<a x="2">banana</a>) |
map{"a": map{"@x":"2", "#content":"banana"} } |
elements-to-maps(<a><b/><c>2</c></a>) |
map{"a": map{"b":"", "c":"2"} } |
elements-to-maps(<a>A <i>nice</i> one!</a>) |
map{"a": ["A ", map{"i":"nice"}, " one!"] } |
elements-to-maps(<a>A <i>nice</i> one!</a>, map{'layouts':map{QName('', 'a'): 'xml'}}) |
[map{"a": "<a>A <i>nice</i> one!</a>" } |
Proposed for 4.0.
These functions convert between the lexical representation of HTML and the tree representation.
Function | Meaning |
---|---|
fn:parse-html |
This function takes as input an HTML document represented as a string, and returns the document node at the root of an XDM tree representing the parsed document. |
parse-html-options : |
|
record( |
|
method |
as union(enum("html", "xhtml"), xs:string) , |
html-version |
as union(enum("LS"), xs:decimal) , |
encoding? |
as xs:string? , |
include-template-content? |
as xs:boolean? , |
* |
|
) |
The keys of this record type are:
method |
The approach used to parse the HTML document into XDM nodes. Note: An implementation may use this to specify a specific algorithm, tool, or
library that is used, such as An implementation may also use this to specify a non-standard variant of
HTML to support, such as |
html-version |
The version of HTML to support when parsing HTML strings or sequences of octets. Valid values an implementation must support for the
Valid values an implementation must support for the
Any other |
encoding | The character encoding to use to decode a sequence of octets that represents an HTML document. |
include-template-content |
Defines how to handle elements in the If this option is If this option is The default behaviour is ·implementation-defined·. Note: This allows an implementation to support the behaviour defined in
[HTML: Living Standard] section 4.12.3.1, Interaction of
|
* |
Additional ·implementation-defined· parser options. |
This function takes as input an HTML document represented as a string, and returns the document node at the root of an XDM tree representing the parsed document.
fn:parse-html ( |
||
$html |
as , |
|
$options |
as parse-html-options |
:= map{ "method":"html",
"html-version":"5", "encoding":"utf-8"
} |
) as
|
This function is ·nondeterministic·, ·context-independent·, and ·focus-independent·.
If $html
is the empty sequence, the function returns the empty sequence.
The method
key of $options
specifies the parsing algorithm,
application, or library to use to construct the XDM nodes from the parsed HTML document.
If the type of $html
is an xs:string
, the encoding is determined
in a way consistent with [HTML: Living Standard] section 13.2.3.1, Parsing with a
known character encoding. The specific character encoding is
·implementation-dependent·.
Note:
The HTML specification uses this for when the encoding of the input byte stream is known for certain, such as when the byte stream has already been decoded.
This means that an implementation should set the encoding to the encoding of the underlying string representation. For example, a Java program could specify the encoding as UTF-16. If the implementation supports passing native string values then that can be used instead of using a byte stream and encoding.
Be aware that the WHATWG Encoding specification defines the ISO 8859-1 (latin1) and ASCII encodings as aliases of the windows-1252 encoding.
If the type of $html
is a sequence of octets (xs:hexBinary
or
xs:base64Binary
), the encoding is determined in a way consistent with
[HTML: Living Standard] section 13.2.3.2, Determining the character encoding.
The encoding
key of $options
is used in step 2 as the user
instructing the user agent to override the document’s character encoding with the
specified encoding.
For any given method
key of $options
the implementation must
use a parser and validator consistent with the html-version
key of
$options
.
method | html-version | Description |
---|---|---|
html | 3, 3.2, 4, 4.01 | An ·implementation-dependent· parsing algorithm, tree construction, and validation consistent with the specified HTML version. |
html | 5, 5.0, 5.1, 5.2 | An HTML5 conformant parsing algorithm, tree construction, and validation consistent
with the specified HTML version. An implementation may choose to use LS
for all these HTML versions. |
html | LS | A parsing algorithm, tree construction, and validation consistent with the [HTML: Living Standard]. |
xhtml | 1.0, 1.1 |
An implementation may choose to use an XML parser to directly construct the XDM nodes, and then use an ·implementation-dependent· validation mechanism (such as DTD or XMLSchema) to validate the XHTML DOM tree. An implementation may also choose to use [HTML: Living Standard] for all these XHTML versions, or some other HTML parser capable of processing XHTML documents. |
* | * |
An ·implementation-defined· parsing algorithm, tree construction, and validation consistent with the specified HTML version. This allows an implementation to provide their own method, html-version
combinations. For example, an implementation could use the values
|
The 15.7 XDM Mapping from HTML DOM Nodes section defines a mapping between the constructed HTML DOM tree and an XDM tree. It is ·implementation-dependent· how this mapping occurs.
The function is not ·deterministic·: that is, if the function is called twice with the same arguments, it is ·implementation-dependent· whether the same node is returned on both occasions.
A dynamic error is raised [err:FODC0011] if the content of
$html
is not a well-formed HTML document.
A dynamic error is raised [err:FODC0012] if the method
key of $options
is not supported by the implementation.
A dynamic error is raised [err:FODC0012] if a key passed to
$options
, or the value of that key, is not supported by the implementation.
If the HTML parser accepts a string as the input then that may be used directly when
$html
is an xs:string
instead of converting the string to
a sequence of octets in an ·implementation-dependent· encoding. The HTML
parser must not perform character encoding processing on that input, treating the HTML
string as being in a known character encoding that matches the encoding of the string.
The mapping from the HTML document to the XDM nodes can be done in several ways:
An implementation could construct the XDM nodes directly in the HTML tree construction step of the HTML parsing algorithm.
An implementation could take the DOM tree and interfaces generated by the HTML parser and adapt those to the XDM accessors. The 15.7 XDM Mapping from HTML DOM Nodes section defines this for the [DOM: Living Standard] specification.
An implementation could traverse the HTML document returned by the parsing algorithm and create the corresponding XDM nodes.
The expression |
|
The expression |
|
The expression |
|
The expression |
|
The expression |
|
[TODO: The examples depend on keyword arguments.] |
New in 4.0. Accepted 2023-01-10.
The functions listed parse CSV data.
Function | Meaning |
---|---|
fn:parse-csv |
Parses CSV data supplied as a string, returning the results in the form of a sequence of arrays of strings. |
fn:csv-to-xdm |
Parses CSV data supplied as a string, returning the results in the form of a
parsed-csv-structure-record record containing information about the
column structure of the data, as well as the data itself as a sequence of
csv-row-record records. |
fn:csv-to-xml |
Parses CSV data supplied as a string, returning the results as an XML document, as described by 15.8.6 Representing CSV data as XML. |
fn:csv-fetch-field-by-column |
Fetches a field from a parsed CSV row by name or position. |
The structured representation of a parsed CSV is described by the
parsed-csv-structure-record
, see 15.8.5 Mapping CSV data to XDM in fn:csv-to-xdm.
Parses CSV data supplied as a string, returning the results in the form of a sequence of arrays of strings.
fn:parse-csv ( |
||
$csv |
as , |
|
$options |
as parse-csv-options |
:= map{} |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the one-argument form of this function is the same as calling the
two-argument form with an empty map as the value of the $options
argument.
The first argument is CSV data, as defined in [RFC 4180], in the form of a
sequence of xs:string
values. The function parses this sequence to return
an XDM value.
If $csv
is the empty sequence, implementations must
return the empty sequence as the value of the body
field of the returned
map.
The $options
argument can be used to control the way in which the parsing
takes place. The ·option parameter conventions· apply.
Implementations must treat any of CRLF, CR, or LF as a single line
separator, as with fn:unparsed-text-lines
.
Fields are regarded as simple xs:string
values. Implementations
must leave whitespace within a field untouched, without
normalizing or otherwise altering it, unless whitespace trimming is explicitly requested
by the user using the trim-whitespace
option.
When whitespace trimming is requested, implementations must only
strip leading and trailing whitespace, this is not equivalent to calling
fn:normalize-space()
.
The entries that may appear in the $options
map are as follows:
Key | Value | Meaning |
---|---|---|
field-delimiter |
The character used to delimit fields within a record. An instance of
xs:string whose length is exactly one.
|
|
record-delimiter |
The characters used to delimit records within the CSV string, if the
default use of line separator as record separator is to be overridden.
|
|
quote-character |
The character used to quote fields within the CSV string. An instance of
xs:string whose length is exactly one.
|
|
trim-whitespace |
Determines whether fields should have leading and trailing whitespace
removed before being returned.
|
|
false |
Fields will be returned with any leading or trailing whitespace intact. Implementations must preserve whitespace as it occurred in the CSV string. | |
true |
Fields will be returned with leading or trailing whitespace removed, and all non-leading or -trailing whitespace preserved. |
The result of the function is a sequence of arrays-of-strings
array(xs:string)*
.
A blank row is represented as an empty array.
An empty field is represented by the empty string.
A dynamic error [err:FOCV0001] occurs if the value of
$csv
does not conform to the [RFC 4180] grammar for quoted
fields.
A dynamic error [err:FOCV0002] occurs if one or more of the values
for field-separator
, record-separator
,
quote-character
are specified and are not a single character.
A dynamic error [err:FOCV0003] occurs if any of the values for
field-separator
, record-separator
,
quote-character
are equal.
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 15.8 Conversion from CSV.
Expression | Result |
---|---|
let $lf := char('x0A') |
|
let $cr := char('x0D') |
|
let $crlf := char('x0D')||char('x0A') |
|
Handling any of the default record separators: |
|
|
( ["name", "city"] ["Bob", "Berlin"], ["Alice", "Aachen"] ) |
|
( ["name", "city"] ["Bob", "Berlin"], ["Alice", "Aachen"] ) |
|
( ["name", "city"] ["Bob", "Berlin"], ["Alice", "Aachen"] ) |
Quote handling: |
|
|
( ["name", "city"] ["Bob", "Berlin"], ["Alice", "Aachen"] ) |
|
( ["name", "city"] ['Bob "The Exemplar" Mustermann', "Berlin"], ["Alice", "Aachen"] ) |
Non-default record- and field-separators: |
|
|
( ["name", "city"] ["Bob", "Berlin"], ["Alice", "Aachen"] ) |
Non-default quote character: |
|
|
( ["name", "city"] ["Bob", "Berlin"], ["Alice", "Aachen"] ) |
Trimming whitespace in fields: |
|
|
( ["name", "city"] ["Bob", "Berlin"], ["Alice", "Aachen"] ) |
Parses CSV data supplied as a string, returning the results in the form of a
parsed-csv-structure-record
record containing information about the
column structure of the data, as well as the data itself as a sequence of
csv-row-record
records.
fn:csv-to-xdm ( |
||
$csv |
as , |
|
$options |
as
|
:= map{} |
) as parsed-csv-structure-record |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the one-argument form of this function is the same as calling the
two-argument form with an empty map as the value of the $options
argument.
The first argument is CSV data, as defined in [RFC 4180], in the form of a
sequence of xs:string
values. The function parses this sequence using
fn:parse-csv
, and then processes its result to return an XDM value.
If $csv
is the empty sequence, implementations must
return a parsed-csv-structure-record
whose rows
entry is the empty sequence.
If $csv
is the empty sequence, but column name extraction has been
requested, or explicit column names have been supplied, then the
parsed-csv-structure-record
returned by implementations
must have a rows
entry whose value is the empty
sequence.
The $options
argument can be used to control the way in which the parsing
takes place. The ·option parameter conventions· apply.
Handling of delimiters, and whitespace trimming, are handled using
fn:parse-csv
, and the options controlling their use are defined
there.
If the headers
option is true, implementations must
exclude the first record from the returned map’s body
key, and return it as
the value of the returned map’s headers-record
key.
The entries that may appear in the $options
map are as follows:
Key | Value | Meaning |
---|---|---|
field-delimiter |
The character used to delimit fields within a record. An instance of
xs:string whose length is exactly one.
|
|
record-delimiter |
The characters used to delimit records within the CSV string, if the
default use of line separator as record separator is to be overridden.
|
|
quote-character |
The character used to quote fields within the CSV string. An instance of
xs:string whose length is exactly one.
|
|
trim-whitespace |
Determines whether fields should have leading and trailing whitespace
removed before being returned.
|
|
false |
Fields will be returned with any leading or trailing whitespace intact. Implementations must preserve whitespace as it occurred in the CSV string. | |
true |
Fields will be returned with leading or trailing whitespace removed, and all non-leading or -trailing whitespace preserved. | |
column-names |
Determines whether the first row of the CSV should be treated as a list
of column names and returned as a csv-columns-record in the
columns entry of the returned map.
|
|
true |
A csv-columns-record is constructed using the
first row of the CSV data and returned as the header entry of the
parsed-csv-structure-record . The row’s fields are transformed
into a map of the form { "Column name": column-number } for the
names entry of the csv-columns-record , and the
fields of the row are returned as a sequence of strings
(xs:string* ) for the fields entry. Implmentations
must exclude the first row from the rows
entry of the returned parsed-csv-structure-record . |
|
false |
Implementations must return an empty
csv-columns-record , equivalent to the literal map map {
names: map {}, fields: () } , in the columns entry of
the returned parsed-csv-structure-record . Implementations
must not exclude the first row from the rows
entry of the parsed-csv-structure-record . |
|
map(xs:integer, xs:string) |
A csv-columns-record is
constructed using the supplied map and returned as the header
entry of the parsed-csv-structure-record . The supplied map is used
as the names entry, and a sequence of strings for the
fields is constructed, filling in blank columns with the empty
string. and the fields of the row are returned as the fields
entry. Implementations must not exclude the first row from
the rows entry of the parsed-csv-structure-record .
|
|
number-of-columns |
Specifies how many columns to return.
|
|
'all' |
All fields from all rows must be returned, without being padded or truncated, regardless of whether rows have varying numbers of fields, or of how many fields they have. | |
'first-row' |
The number of fields in the first row is counted, and processing proceeds as if that integer had been supplied as the value for this option. | |
xs:integer |
The number of columns is set to this value. Rows
with more fields than the supplied value are truncated by discarding the extra
fields. as if calling fn:subsequence(R, 1, I) , given the row’s
sequence of fields in R, and the supplied value in I. If
a row has fewer fields than the supplied value it is padded by appending empty
string values until it contains the specified number of fields. |
If column names were extracted from the first row of the CSV, when there are duplicate
column names, implementations must include only the first occurrence
in the names
entry of the csv-columns-record
, ignoring
subsequent entries. Any fields in the first record whose value is the empty string
must also be omitted.
The result of the function is a parsed-csv-structure-record
, a map with
string keys containing two entries, columns
, and rows
.
The entry with key "columns"
holds a csv-columns-record
record. If column names have been extracted, or supplied, then the record will
have a names
entry whose value is a map of column-name to
column-number, map(xs:integer, xs:string)
. The record’s
fields
entry will contains the column names as a sequence of
strings, xs:string*
, replicating the row they were taken from.
If column names were not extracted or supplied, then the
csv-columns-record
will contain a names
entry whose
value is an empty map, and a fields
entry whose value is the empty
sequence.
The entry with key "rows"
holds the records of the CSV as a sequence
of row records, csv-row-record*
. If there is no data in the CSV, this
will be the empty sequence.
Each record in the rows
sequence contains a fields
entry, containing the row’s fields as a sequence of strings,
xs:string*
, and a field
entry containing an arity-one
function. The function takes a string or integer key K as input, and
returns the field in fields that corresponds to the position
K, if K is an xs:integer
, or the position
obtained by looking up K in the names
map if K
is an xs:string
.
The properties of this function are as follows:
name: absent
parameter names: ($key)
signature: (union(xs:integer, xs:string)) => xs:string?
non-local variable bindings: none
implementation: implementation-dependent
errors: A dynamic error [err:FOCV0004] occurs if the supplied $key is a string and does not occur in the map of column names.
This function behaves identically to fn:csv-fetch-field-by-column
would had the header
entry of the containing
parsed-csv-structure-record
and the fields
entry of
this csv-row-record
been supplied as its first two arguments, and
$key as its last. See the definition of
fn:csv-fetch-field-by-column
for more details
A dynamic error [err:FOCV0001] occurs if the value of
$csv
does not conform to the [RFC 4180] grammar for quoted
fields.
A dynamic error [err:FOCV0002] occurs if one or more of the values
for field-separator
, record-separator
,
quote-character
are specified and are not a single character.
A dynamic error [err:FOCV0003] occurs if any of the values for
field-separator
, record-separator
,
quote-character
are equal.
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 15.8 Conversion from CSV.
Expression | Result |
---|---|
let $crlf := char('x0D')||char('x0A') |
|
let $csv-string := `name,city{$crlf}Bob,Berlin{$crlf}Alice,Aachen{$crlf}` |
|
let $options := map { "record-separator": "§", "field-separator": ";", "quote-character": "|" } |
|
let $non-std-csv := `|name|;|city|§|Bob|;|Berlin|§|Alice|;|Aachen|` |
|
let $trim-opts := map { "trim-whitespace": true() } |
|
With defaults for delimiters and quotes, and default column extraction (false): |
|
|
|
|
map { "names": map {}, "fields": (), } |
|
|
|
Raises error CV. |
|
|
With defaults for delimiters and quotes, and |
|
|
map { "names": map { "name": 1, "city": 2 }, "fields": ("name", "city"), } |
|
|
|
|
|
|
|
|
Non-default record- and field-delimiters, non-default quotes: |
|
|
|
|
map { "names": map {}, "fields": (), } |
|
|
|
|
Trimming whitespace in fields: |
|
|
|
let $csv-uneven-cols := `date,name,city,amount,currency,original amount,note{$crlf}2023-07-19,Bob,Berlin,10.00,USD,13.99{$crlf}2023-07-20,Alice,Aachen,15.00{$crlf}2023-07-20,Charlie,Celle,15.00,GBP,11.99,cake,not a lie{$crlf}` |
|
Filtering columns |
|
|
|
|
( ["Bob","2023-07-19","10.00"], ["Alice","2023-07-20","15.00"], ["Charlie","2023-07-20","15.00"] ) |
Specifying the number of columns, using |
|
|
|
|
( ["2023-07-19","Bob","Berlin","10.00","USD","13.99"], ["2023-07-20","Alice","Aachen","15.00"], ["2023-07-20","Charlie","Celle","15.00","GBP","11.99","cake","not a lie"] ) |
Specifying the number of columns using |
|
|
|
|
( ["2023-07-19","Bob","Berlin","10.00","USD","13.99",""], ["2023-07-20","Alice","Aachen","15.00","","",""], ["2023-07-20","Charlie","Celle","15.00","GBP","11.99","cake"] ) |
Specifying the number of columns with a number |
|
|
|
|
( ["2023-07-19","Bob","Berlin","10.00","USD","13.99"], ["2023-07-20","Alice","Aachen","15.00","",""], ["2023-07-20","Charlie","Celle","15.00","GBP","11.99"] ) |
Parses CSV data supplied as a string, returning the results as an XML document, as described by 15.8.6 Representing CSV data as XML.
fn:csv-to-xml ( |
||
$csv |
as , |
|
$options |
as
|
:= map{} |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.
The effect of the one-argument form of this function is the same as calling the
two-argument form with an empty map as the value of the $options
argument.
The first argument is CSV data, as defined in [RFC 4180], in the form of a
sequence of xs:string
values. The function parses this sequence using
fn:parse-csv
, and then processes its result to return an XML document.
If $csv
is the empty sequence, implementations must
return a <fn:csv>
whose <fn:rows>
element
is empty.
If $csv
is the empty sequence, but column name extraction has been
requested, but explicit column names have not been supplied, then the implementation
must return a <fn:csv>
element whose
<fn:header>
element is empty.
If $csv
is the empty sequence, but explicit column names have been
supplied, then the implementation must return a
<fn:csv>
element whose <fn:header>
element contains the appropriate <fn:column>
elements.
The $options
argument can be used to control the way in which the parsing
takes place. The ·option parameter conventions· apply.
Handling of delimiters, and whitespace trimming, are handled using
fn:parse-csv
, and the options controlling their use are defined
there.
The entries that may appear in the $options
map are as follows:
Key | Value | Meaning |
---|---|---|
field-delimiter |
The character used to delimit fields within a record. An instance of
xs:string whose length is exactly one.
|
|
record-delimiter |
The characters used to delimit records within the CSV string, if the
default use of line separator as record separator is to be overridden.
|
|
quote-character |
The character used to quote fields within the CSV string. An instance of
xs:string whose length is exactly one.
|
|
trim-whitespace |
Determines whether fields should have leading and trailing whitespace
removed before being returned.
|
|
false |
Fields will be returned with any leading or trailing whitespace intact. Implementations must preserve whitespace as it occurred in the CSV string. | |
true |
Fields will be returned with leading or trailing whitespace removed, and all non-leading or -trailing whitespace preserved. | |
column-names |
Determines whether the first row of the CSV should be treated as a list
of column headers and returned as a csv-columns-record in the
header entry of the returned map.
|
|
true |
The <header> element is populated
with <column> elements constructed using the values
from the first row of the CSV data. Implmentations must
exclude the first row from the <rows>
element. |
|
false |
Implementations must not include a
<header> element in the output. |
|
map(xs:integer, xs:string) |
The supplied map is used to
construct a sequence of <column> elements to populate
the <header> element. The xs:integer
denotes the column number, and the xs:string the column name. Gaps
in the integer sequence of column numbers are filled with empty
<column> elements. Implementations must
not exclude the first row from the <rows>
element. |
|
filter-columns |
A sequence indicating which fields to return and in which order. If this
option is missing or the empty sequence, all fields are returned in their natural
order. Items in the sequence are treated as the index of the column to return. In
the returned data, only fields from the specified columnms are returned, and in
the order specified.
|
|
number-of-columns |
Specifies how many columns to return.
|
|
'all' |
All fields from all rows must be returned, without being padded or truncated, regardless of whether rows have varying numbers of fields, or of how many fields they have. | |
'first-row' |
The number of fields in the first row is counted, and processing proceeds as if that integer had been supplied as the value for this option. | |
xs:integer |
The number of columns is set to this value. Rows
with more fields than the supplied value are truncated by discarding the extra
fields. as if calling fn:subsequence(R, 1, I) , given the row’s
sequence of fields in R, and the supplied value in I. If
a row has fewer fields than the supplied value it is padded by appending empty
string values until it contains the specified number of fields. |
A dynamic error [err:FOCV0001] occurs if the value of
$csv
does not conform to the [RFC 4180] grammar for quoted
fields.
A dynamic error [err:FOCV0002] occurs if one or more of the values
for field-separator
, record-separator
,
quote-character
are specified and are not a single character.
A dynamic error [err:FOCV0003] occurs if any of the values for
field-separator
, record-separator
,
quote-character
are equal.
Expression | Result |
---|---|
let $crlf := char('x0D')||char('x0A') |
|
let $csv-string := `name,city{$crlf}Bob,Berlin{$crlf}Alice,Aachen{$crlf}` |
|
An empty CSV with default column extraction (false): |
|
|
<fn:csv> <fn:rows/> </fn:csv> |
An empty CSV with column extraction: |
|
|
<fn:csv> <fn:header/> <fn:rows/> </fn:csv> |
An empty CSV with explicit column names: |
|
|
<fn:csv> <fn:header> <fn:column>name</fn:field> <fn:column/> <fn:column>city</fn:field> </fn:header> <fn:rows/> </fn:csv> |
With defaults for delimiters and quotes, and column extraction: |
|
|
<fn:csv> <fn:header> <fn:column>name</fn:field> <fn:column>city</fn:field> </fn:header> <fn:rows> <fn:row> <fn:field column="name">Bob</fn:field> <fn:field column="city">Berlin</fn:field> </fn:row> <fn:row> <fn:field column="name">Alice</fn:field> <fn:field column="city">Aachen</fn:field> </fn:row> </fn:rows> </fn:csv> |
With defaults for delimiters and quotes, and column extraction: |
|
|
<fn:csv> <fn:header> <fn:field>name</fn:field> <fn:field>city</fn:field> </fn:header> <fn:rows> <fn:row> <fn:field column="name">Bob</fn:field> <fn:field column="city">Berlin</fn:field> </fn:row> <fn:row> <fn:field column="name">Alice</fn:field> <fn:field column="city">Aachen</fn:field> </fn:row> </fn:rows> </fn:csv> |
let $csv-uneven-cols := `date,name,city,amount,currency,original amount,note{$crlf}2023-07-19,Bob,Berlin,10.00,USD,13.99{$crlf}2023-07-20,Alice,Aachen,15.00{$crlf}2023-07-20,Charlie,Celle,15.00,GBP,11.99,cake,not a lie{$crlf}` |
|
Filtering columns |
|
|
<fn:csv> <fn:header> <fn:field>name</fn:field> <fn:field>date</fn:field> <fn:field>amount</fn:field> </fn:header> <fn:rows> <fn:row> <fn:field column="name">Bob</fn:field> <fn:field column="date">2023-07-19</fn:field> <fn:field column="amount">10.00</fn:field> </fn:row> <fn:row> <fn:field column="name">Alice</fn:field> <fn:field column="date">2023-07-20</fn:field> <fn:field column="amount">15.00</fn:field> </fn:row> <fn:row> <fn:field column="name">Charlie</fn:field> <fn:field column="date">2023-07-20</fn:field> <fn:field column="amount">15.00</fn:field> </fn:row> </fn:rows> </fn:csv> |
Specifying the number of columns, using "all" (the default) |
|
|
<fn:csv> <fn:header> <fn:field>date</fn:field> <fn:field>name</fn:field> <fn:field>city</fn:field> <fn:field>amount</fn:field> <fn:field>currency</fn:field> <fn:field>original amount</fn:field> <fn:field>note</fn:field> </fn:header> <fn:rows> <fn:row> <fn:field column="date">2023-07-19</fn:field> <fn:field column="name">Bob</fn:field> <fn:field column="city">Berlin</fn:field> <fn:field column="amount">10.00</fn:field> <fn:field column="currency">USD</fn:field> <fn:field column="original amount">13.99</fn:field> </fn:row> <fn:row> <fn:field column="date">2023-07-20</fn:field> <fn:field column="name">Alice</fn:field> <fn:field column="city">Aachen</fn:field> <fn:field column="amount">15.00</fn:field> </fn:row> <fn:row> <fn:field column="date">2023-07-20</fn:field> <fn:field column="name">Charlie</fn:field> <fn:field column="city">Celle</fn:field> <fn:field column="amount">15.00</fn:field> <fn:field column="currency">GBP</fn:field> <fn:field column="original amount">11.99</fn:field> <fn:field column="note">cake</fn:field> <fn:field>not a lie</fn:field> </fn:row> </fn:rows> </fn:csv> |
Specifying the number of columns using |
|
|
<fn:csv> <fn:header> <fn:field>date</fn:field> <fn:field>name</fn:field> <fn:field>city</fn:field> <fn:field>amount</fn:field> <fn:field>currency</fn:field> <fn:field>original amount</fn:field> <fn:field>note</fn:field> </fn:header> <fn:rows> <fn:row> <fn:field column="date">2023-07-19</fn:field> <fn:field column="name">Bob</fn:field> <fn:field column="city">Berlin</fn:field> <fn:field column="amount">10.00</fn:field> <fn:field column="currency">USD</fn:field> <fn:field column="original amount">13.99</fn:field> <fn:field column="note"/> </fn:row> <fn:row> <fn:field column="date">2023-07-20</fn:field> <fn:field column="name">Alice</fn:field> <fn:field column="city">Aachen</fn:field> <fn:field column="amount">15.00</fn:field> <fn:field column="currency"/> <fn:field column="original amount"/> <fn:field column="note"/> </fn:row> <fn:row> <fn:field column="date">2023-07-20</fn:field> <fn:field column="name">Charlie</fn:field> <fn:field column="city">Celle</fn:field> <fn:field column="amount">15.00</fn:field> <fn:field column="currency">GBP</fn:field> <fn:field column="original amount">11.99</fn:field> <fn:field column="note">cake</fn:field> </fn:row> </fn:rows> </fn:csv> |
Specifying the number of columns with a number |
|
|
<fn:csv> <fn:header> <fn:field>date</fn:field> <fn:field>name</fn:field> <fn:field>city</fn:field> <fn:field>amount</fn:field> <fn:field>currency</fn:field> <fn:field>original amount</fn:field> </fn:header> <fn:rows> <fn:row> <fn:field column="date">2023-07-19</fn:field> <fn:field column="name">Bob</fn:field> <fn:field column="city">Berlin</fn:field> <fn:field column="amount">10.00</fn:field> <fn:field column="currency">USD</fn:field> <fn:field column="original amount">13.99</fn:field> </fn:row> <fn:row> <fn:field column="date">2023-07-20</fn:field> <fn:field column="name">Alice</fn:field> <fn:field column="city">Aachen</fn:field> <fn:field column="amount">15.00</fn:field> <fn:field column="currency"/> <fn:field column="original amount"/> </fn:row> <fn:row> <fn:field column="date">2023-07-20</fn:field> <fn:field column="name">Charlie</fn:field> <fn:field column="city">Celle</fn:field> <fn:field column="amount">15.00</fn:field> <fn:field column="currency">GBP</fn:field> <fn:field column="original amount">11.99</fn:field> </fn:row> </fn:rows> </fn:csv> |
Fetches a field from a parsed CSV row by name or position.
fn:csv-fetch-field-by-column ( |
||
$columns |
as csv-columns-record , |
|
$fields |
as , |
|
$key |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The first argument is a csv-columns-record
, as provided in the
header
entry of the parsed-csv-structure-record
returned by
fn:csv-to-xdm
.
The second argument is the row whose fields are being fetched, represented as a sequence
of strings as would be provided by the fields
entry of a
csv-row-record
returned by fn:csv-to-xdm
.
The final argument is the key to use for the lookup, supplied as either an
xs:string
(the column name) or xs:integer
(the column
position).
When the argument is a string, if the string is missing from the keys of the map
contained in the names
entry of the $columns
argument’s
csv-columns-record
, then implementations must raise
an [err:FOCV0004].
When the argument is an integer, if the integer position is outside the bounds of the
$fields
sequence (i.e. is greater than the size of the sequence), then
implementations must return the empty string.
The function returns the field in the sequence $fields
at the position in
the sequence either explicitly provided (when $key
is an
xs:integer
), or looked up from the map of name to position in the
csv-columns-record
provided in $columns
.
A dynamic error [err:FOCV0004] occurs if the value of
$key
is an xs:string
but is not a member of the keys of the
map contained in the names
entry of the csv-columns-record
in
$header
. fields.
Expression | Result |
---|---|
let $columns := map { "names": map { "name": 1, "city": 2 }, "fields: ("name", "city") } |
|
let $fields := ("Bob", "Berlin") |
|
With a string key: |
|
|
|
|
Raises error FOCV0004. |
With an integer key |
|
|
|
|
|
JSON is a popular format for exchange of structured data on the web: it is specified in [RFC 7159]. This section describes facilities allowing JSON data to be converted to and from XDM values.
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.
This section defines a mapping from JSON data to XDM maps and arrays. Two functions are available
to support this mapping: fn:parse-json
and fn:serialize
(with options
selecting JSON as the output method).
The fn:parse-json
function will accept any JSON text as input, and converts it
to XDM data values. The fn:serialize
function (with JSON as the output method) will accept any XDM
value produced using fn:parse-json
and convert it back to the original JSON text
(subject to insignificant variations such as reordering the properties in a JSON object).
Note:
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 fn:parse-json
function
has been chosen with ease of manipulation as a design aim. For example, a simple JSON object
such as {"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 fn:json-to-xml
is provided to take a JSON string as input and convert it
to the XML representation, and a second function fn:xml-to-json
performs the reverse operation.
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.
Note:
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:
{ "desc" : "Distances between several cities, in kilometers.", "updated" : "2014-02-04T18:50:45", "uptodate": true, "author" : null, "cities" : { "Brussels": [ {"to": "London", "distance": 322}, {"to": "Paris", "distance": 265}, {"to": "Amsterdam", "distance": 173} ], "London": [ {"to": "Brussels", "distance": 322}, {"to": "Paris", "distance": 344}, {"to": "Amsterdam", "distance": 358} ], "Paris": [ {"to": "Brussels", "distance": 265}, {"to": "London", "distance": 344}, {"to": "Amsterdam", "distance": 431} ], "Amsterdam": [ {"to": "Brussels", "distance": 173}, {"to": "London", "distance": 358}, {"to": "Paris", "distance": 431} ] } }
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
json-to-xml
function.
<map xmlns="http://www.w3.org/2005/xpath-functions"> <string key='desc'>Distances between several cities, in kilometers.</string> <string key='updated'>2014-02-04T18:50:45</string> <boolean key="uptodate">true</boolean> <null key="author"/> <map key='cities'> <array key="Brussels"> <map> <string key="to">London</string> <number key="distance">322</number> </map> <map> <string key="to">Paris</string> <number key="distance">265</number> </map> <map> <string key="to">Amsterdam</string> <number key="distance">173</number> </map> </array> <array key="London"> <map> <string key="to">Brussels</string> <number key="distance">322</number> </map> <map> <string key="to">Paris</string> <number key="distance">344</number> </map> <map> <string key="to">Amsterdam</string> <number key="distance">358</number> </map> </array> <array key="Paris"> <map> <string key="to">Brussels</string> <number key="distance">265</number> </map> <map> <string key="to">London</string> <number key="distance">344</number> </map> <map> <string key="to">Amsterdam</string> <number key="distance">431</number> </map> </array> <array key="Amsterdam"> <map> <string key="to">Brussels</string> <number key="distance">173</number> </map> <map> <string key="to">London</string> <number key="distance">358</number> </map> <map> <string key="to">Paris</string> <number key="distance">431</number> </map> </array> </map> </map>
An XSD 1.0 schema for the XML representation is provided in C.2 Schema for the result of fn:json-to-xml.
It is not necessary to import this schema into the static context unless the stylesheet or query
makes explicit reference to the components defined in the schema. If the stylesheet or query does import a schema
for the namespace http://www.w3.org/2005/xpath-functions
, then:
Unless the host language specifies otherwise, the processor (if it is schema-aware) must recognize an import declaration for this namespace, whether or not a schema location is supplied.
If a schema location is provided, then the schema document at that location must be equivalent to the schema document at C.2 Schema for the result of fn:json-to-xml; the effect if it is not equivalent is ·implementation-dependent·
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
fn:json-to-xml
function, the string value of the element will be true
or false
.
The fn:xml-to-json
function also recognizes other strings that validate as 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
fn:json-to-xml
function creates an element whose string value is lexically the same as the JSON representation
of the number. The fn:xml-to-json
function generates a JSON representation that is the result of casting the
(typed or untyped) value of the node to 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 fn:json-to-xml
and
fn:xml-to-json
both retain the order of entries, subject to rules about how duplicate keys are handled. The
key may be represented in escaped or unescaped form.
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 json-to-xml
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 must have the type
annotations obtained by validating the untyped representation against the schema given in C.2 Schema for the result of fn:json-to-xml.
If it is untyped, then it must be an XDM instance such that validation against this schema would succeed;
with the proviso that all attributes other than those in no namespace or in namespace 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 fn:xml-to-json
function does not depend on the choice of prefix, and the prefix (if any) generated by the
fn:json-to-xml
function is ·implementation-dependent·.
The elements-to-maps
function converts XML element nodes to maps, in a form
suitable for serialization as JSON. 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 changes in the input should not result in large changes in the output.
Achieving all three objectives requires design compromises. It also requires sacrificing some other desiderata. In consequence:
The conversion is not lossless.
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 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 can be made extensible
by converting <name>John</name>
to map{"name":{"#content":"John"}}
and <name role="first">John</name>
to map{"name":{"@role":"first", "#content":"John"}}
,
but this imposes unwanted complexity on the simplest cases. The solution is to provide some user
control over the mappings that are chosen.
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 |
---|---|
<hr/> |
"hr": "" |
<date-of-birth>2023-05-18</age> |
"date-of-birth": 2023-05-18 |
<box width="5" height="10"/> |
"box": {"@width":5, "@height":10} |
<label id="t41">Warning!</label> |
"label": {"@id": "t41", "#content":"Warning!"} |
<box> <width>5</width> <height>10</height> </box> |
"box": { "width":5, "height":10 } |
<polygon> <point x="0" y="0"/> <point x="1" y="0"/> <point x="1" y="1"/> <point x="0" y="1"/> </polygon> |
"polygon": [ {"x":0, "y":0}, {"x":1, "y":0}, {"x":1, "y":1}, {"x":0, "y":1} ] |
This specification defines a number of named mappings, called layouts, and allows the layout to be selected in three different ways:
The layout to be used for a specific element name can be explicitly selected in the options
to the fn:elements-to-maps
function.
In the absence of an explicit selection, if the data has been schema-validated, the layout is inferred from the content model for the element type as defined in the schema.
Otherwise (that is, 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.
If the uniform
option is set to true
, then the same layout
must be used for all elements with a given name. This means that all elements must be
examined before any element is processed. The layout chosen is the first one (in the order of
presentation in the following sections) whose match pattern matches every element with
the relevant name.
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 either by using the uniform
option, or by selecting a layout explicitly in the layouts
option.
The different layouts available are defined in the following sections. For each layout there is a table showing:
Layout name: the name to be used to select this layout in
the options parameter of the fn:items-to-json
function.
Usage: the situations for which this layout is designed.
XML example: an example of a typical XML element for which this layout is appropriate.
JSON equivalent: the JSON representation of this example. The JSON equivalent is always shown as a key-value pair suitable for use within a JSON object; the way this is used depends on the context in which the element appears.
Note:
The elements-to-maps
function produces a map as its result, but it is convenient
to demonstrate the form of the map by showing the effect of serializing the map as JSON.
XSD conditions: the properties of the XSD type definition that cause this layout to be selected. The first layout that meets these conditions will be chosen.
Match pattern: an XSLT 4.0 pattern defining the elements for which this layout will be selected. The first layout whose pattern matches will be chosen.
Mapping rules: The rules for mapping the XML element to an XDM map representation.
Mapping for nilled elements: special rules that apply to an
element having the attribute xsi:nil="true"
. These rules only apply if the
element has been schema-validated.
Notes: General observations, especially concerning what information is retained by this mapping and what information is lost.
Note that it is possible to use any layout for any element. Use of an inappropriate layout may result in information being discarded; but in some cases, discarding information may be the desired outcome.
Note:
Acknowledgements for this categorization: see [Goessner]. Although Goessner's categories have been used, the actual mappings vary from his proposal.
Layout name |
|
---|---|
Usage |
Intended for XML elements that have no content and no attributes. |
XML example |
<hr/> |
JSON equivalent |
{"hr":""} |
XSD conditions |
The element has a complex type with variety empty, or a simple type with
variety list and |
Match pattern |
|
Mapping rules |
The content is represented by the string |
Mapping for nilled elements |
The content is represented by an empty sequence, which is serialized as the JSON value
|
Notes |
If any child nodes or attributes are present, they are discarded. (This can happen when this layout is explicitly selected for elements that are not actually empty.) |
Layout name |
|
---|---|
Usage |
Intended for XML elements that have no content but may have attributes. |
XML example |
<hr class="ccc" id="zzz"/> |
JSON equivalent |
{"hr":{"@class":"ccc", "@id":"zzz"}} |
XSD conditions |
The element has a complex type with variety empty, or a simple type with
variety list and |
Match pattern |
|
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 an empty map. The mapping rules for attributes are defined in 15.6.2 Representing Attributes. |
Mapping for nilled elements |
An additional key-value pair |
Notes |
If any child nodes are present in the element, they are discarded. (This can happen when this layout is explicitly selected for elements that are not actually empty.) |
Layout name |
|
---|---|
Usage |
Intended for XML elements that have simple content and no attributes. |
XML example |
<date>2023-05-30</date> |
JSON equivalent |
{"date":"2023-05-30"} |
XSD conditions |
The element has a simple type. |
Match pattern |
|
Mapping rules |
The element is atomized and the resulting atomized value is adjusted as follows, to ensure that it can be successfully serialized as JSON:
Note: If the element is untyped, the result will always be a JSON string. |
Mapping for nilled elements |
The content is represented by an empty sequence, which is serialized as the JSON value
|
Notes |
If any attributes are present, they are discarded. If the element has a type annotation that is a complex type with element-only content, atomization will fail and a dynamic error occurs. In the case of mixed content, if child elements are present, atomization means that they will not appear in the result. Comments and processing instructions in the content are discarded. Whitespace is retained. |
Layout name |
|
---|---|
Usage |
Intended for XML elements that have simple content and (optionally) attributes. |
XML example |
<price currency="USD">23.50</date> |
JSON equivalent |
"date":{"@currency":"USD", "#content":23.50} |
XSD conditions |
The element has a complex type with simple content. |
Match pattern |
|
Mapping rules |
The content is represented by a map containing one entry for each
attribute in the XML element, plus an entry named The atomized value is adjusted as described in 15.6.1.3 Simple Layout. The mapping rules for attributes are defined in 15.6.2 Representing Attributes. Note: If the element is untyped, the value of each attribute, and of If the element has been schema-validated, the values of each property may instead be a number, a boolean, or an array. |
Mapping for nilled elements |
The |
Notes |
In the case of mixed content, if child elements are present, atomization means that they will not appear in the result. Comments and processing instructions in the content are discarded. Whitespace is retained. |
Layout name |
|
---|---|
Usage |
Intended for XML elements that act as wrappers for a list of child elements, all having the same element name. Any attributes on either the wrapper element or the wrapped elements will be discarded. The name of the child elements is not retained in the JSON output. |
XML example |
<dates> <date>2023-03-20</date> <date>2023-04-12</date> <date>2023-05-30</date> </dates> |
JSON equivalent |
"dates": ["2023-03-20", "2023-04-12", "2023-05-30"] |
XSD conditions |
The element has a complex type with element-only content, containing a single
element particle, whose |
Match pattern |
That is, there are at least two child elements; all child elements have the same name; there are no text node children other than whitespace-only text nodes; and there are no attributes on the wrapper element. |
Mapping rules |
If the element has element children with names that are not all equal, or if it has non-whitespace text node children, then it is output as if mixed layout were chosen. This is fallback behavior for use when this layout is chosen inappropriately. In other cases, the content is represented by a XDM array containing the results of formatting the content of each child element according to the rules for that element. If there are no children then the content is represented by an empty array. |
Mapping for nilled elements |
The array is replaced by an empty sequence, corresponding to the JSON value
|
Notes |
Comments and processing instructions in the content are discarded. |
Consider the following XML:
<items> <item nr="n1"><p>One</p></item> <item nr="n2"><p>Two</p></item> </items>
When this is converted using list layout and serialized as JSON, the result is:
{"items":[ {"@nr":"n1", "p":"One"}, {"@nr":"n2", "p":"Two"} ]}
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, and the name of the child elements is retained in the JSON output. |
XML example |
<dates id="x"> <date>2023-03-20</date> <date>2023-04-12</date> <date>2023-05-30</date> </dates> |
JSON equivalent |
"dates": {"@id":"x", "date": ["2023-03-20", "2023-04-12", "2023-05-30"]} |
XSD conditions |
The element has a complex type with element-only content, containing a single
element particle, whose |
Match pattern |
That is, there are at least two child elements; all child elements have the same name; and there are no text node children other than whitespace-only text nodes. |
Mapping rules |
If the element has element children with names that are not all equal, or if it has non-whitespace text node children, then it is output as if mixed layout were chosen. This is fallback behavior for use when this layout is chosen inappropriately. In other cases, 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 content property), whose value is an array containing the results of formatting the content of each child element according to the rules for that element. 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 is replaced by an empty sequence, corresponding to the JSON value |
Notes |
Comments and processing instructions in the content are discarded. |
Consider the following XML:
<items format="bullets"> <item nr="1"><p>One</p></item> <item nr="2"><p>Two</p></item> </items>
When this is converted using list layout, the result is:
"items": {"@format":"bullets", "item": [ {"@nr":"1, "p":"One"}, {"@nr":"2, "p":"Two"} ]
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. |
XML example |
<employee id="x"> <date-of-birth>1984-03-20</date> <location>Germany</location> <position>Janitor</position> </employee> |
JSON equivalent |
{"employee": {"@id":"x", "date-of-birth":"1984-03-20", "location":"Germany", "position":"Janitor"}} |
XSD conditions |
The element has a complex type with element-only content, and either:
|
Match pattern |
That is, there is at least one child element; all child elements have different names; and there are no text node children other than whitespace-only text nodes. |
Mapping rules |
If the element has non-whitespace text node children, then it is output as if mixed layout were chosen. This is fallback behavior for use when this layout is chosen inappropriately. In other cases, 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. The properties representing child elements have names based on the child element name
in the normal way, except
that if the multiple child elements have the same name,
then each is made unique by adding a suffix in the form Because the child elements are converted to a map, their order is not retained. |
Mapping for nilled elements |
Alongside any attributes, the value includes the additional entry
|
Notes |
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. Indeed,
with XSD 1.1, a complex type defined using
Comments and processing instructions in the content are discarded. |
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. |
XML example |
<section id="x"> <head>Introduction</head> <p>Lorem ipsum.</p> <p>Dolor sit amet.</p> </section> |
JSON equivalent |
{"section": [ {"@id":"x"}, {"head":"Introduction"}, {"p":"Lorem ipsum"}, {"p":"Dolor sit amet"} ]} |
XSD conditions |
The element has a complex type with element-only content that does not meet the criteria for list or record layout. |
Match pattern |
That is, the element has no text node children other than whitespace nodes. |
Mapping rules |
The mapping rules are identical to the rules for mixed layout (see 15.6.1.9 Mixed Layout) except that whitespace-only text nodes are discarded. |
Mapping for nilled elements |
A nilled element is indicated by a property value of |
Notes |
Because whitespace text nodes are stripped, this layout should not normally be used with mixed content. |
Layout name |
|
---|---|
Usage |
Intended for XML elements that contain mixed content. The element may or may not have attributes. |
XML example |
<para id="x">This is a <i>fine</i> mess!</para> |
JSON equivalent |
{"para": [ {"@id":"x"}, "This is a ", {"i":"fine"}, "mess!" ]} |
XSD conditions |
The element has a complex type that does not satisfy the criteria for any other layout to be used. |
Match pattern |
|
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, with the key representing the attribute name and the value representing the attribute value, formatted as described in 15.6.2 Representing Attributes. Child nodes are represented within the array as follows:
Whitespace text nodes are retained. |
Mapping for nilled elements |
A nilled element is indicated by a property value of |
Notes |
This is the only layout that retains information about all child nodes, including text nodes (both whitespace and non-whitespace), elements, comments, and processing instructions. |
Serialized layout allows an element node to be represented as lexical XML, HTML, or XHTML, contained within a map.
Layout names |
|
---|---|
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 XML, HTML, or XHTML markup within a JSON framework. |
XML example |
<p>That was <i>awesome</i></p> |
JSON equivalent |
"p":"<p>That was <i>awesome</i></p>" |
XSD conditions |
Not applicable. Serialized layout will only be used if
explicitly selected in the |
Match pattern |
Not applicable. Serialized layout will only be used if
explicitly selected in the |
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. Note: The outermost element name will typically be repeated, for example
|
Mapping for nilled elements |
Nilled elements are handled according to the standard serialization rules. |
Attributes are generally converted to key-value pairs within a map. The key is always a string:
For an attribute in no namespace, the key is "@"
followed by the local
name of the attribute.
For an attribute in the XML namespace, the key is "@xml:"
followed by the local
name of the attribute.
For an attribute in any other namespace, the key takes the form "@Q{uri}local"
where
uri
is the namespace and local
is the local part of the attribute name.
The corresponding value is obtained by atomizing the atomized value of the attribute node as follows, to ensure that error-free JSON serialization is possible:
Numeric values that have no JSON serialization (specifically, infinity and NaN) are
converted to strings by applying the string
function. For example, NaN
becomes "NaN"
.
A sequence of two or more items is converted to an array of two or more singleton members.
For example, (1, 2, 3)
becomes [1, 2, 3]
.
Note:
No adjustment is needed when the attribute is untyped; the typed value in that case is always a simple string.
TODO: Issue 641 may make these adjustments unnecessary.
Attributes in the xsi
namespace (http://www.w3.org/2001/XMLSchema-instance
)
are discarded.
Note:
This is because these attributes can appear even when the schema does not allow the element to have attributes, which means that a layout might be chosen that does not accommodate attributes.
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 equivalent |
---|---|
<a x='1' b='2'/> |
{ "a":{ "@x": "1", "@b": "2" } } |
<a><x>1</x><y>2</y></a> |
{ "a":{ "x": "1", "y": "2" } } |
<polygon> <point x='0' y='0'/> <point x='0' y='1'/> <point x='1' y='1'/> <point x='1' y='0'/> </polygon> |
{ "polygon":[ {"@x": "0", "@y": "0"}, {"@x": "0", "@y": "1"}, {"@x": "1", "@y": "1"}, {"@x": "1", "@y": "0"} ] ] } |
<cities> <city id="LDN"> <name>London</name> <size>18.2</size> </city> <city id="PRS"> <name>Paris</name> <size>19.1</size> </city> <city id="BLN"> <name>Berlin</name> <size>14.6</size> </city> </cities> |
{ "cities":[ { "@id": "LDN", "name": "London", "size": "18.2" }, { "@id": "PRS", "name": "Paris", "size": "19.1" }, { "@id": "BLN", "name": "Berlin", "size": "14.6" } ] } |
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 equivalent |
---|---|
<g:grammar language="xquery" xmlns:g="http://www.w3.org/XPath/grammar"> <g:production name="FunctionBody"> <g:ref name="EnclosedExpr"/> <g:ref name="Block"/> </g:production> <g:production name="EnclosedExpr"> <g:ref name="Lbrace"/> <g:ref name="Expr"/> <g:optional> <g:ref name="Expr"/> </g:optional> <g:ref name="Rbrace"/> </g:production> <g:production name="SimpleReturnClause"> <g:string>return</g:string> <g:ref name="ExprSingle"/> </g:production> </g:grammar> |
[{ "Q{http://www.w3.org/XPath/grammar}grammar":[ { "@language":"xquery" }, { "production":[ { "@name":"FunctionBody" }, { "ref":{"@name": "EnclosedExpr"} }, { "ref":{"@name": "Block"} } ] }, { "production":[ { "@name":"EnclosedExpr" }, { "ref":{"@name": "Lbrace"} }, { "ref":{"@name": "Expr"} }, { "optional":[ { "ref":{"@name": "Expr"} } ] }, { "ref":{"@name": "Rbrace"} } ] }, { "production":[ { "@name":"SimpleReturnClause" }, { "string":"return" }, { "ref":{"@name": "ExprSingle"} } ] } ] }] |
Note:
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>
.
The HTML5 format is specified in [HTML: Living Standard]. This section describes facilities allowing HTML5 documents as defined by [DOM: Living Standard] HTML DOM nodes to be mapped to XDM accessors/nodes.
An implementation must match the semantics of the mapping described in this section, but the specific way it achieves that is ·implementation-dependent·.
Note:
An implementation may use the HTML DOM directly, using XDM accessor bindings for the HTML DOM nodes.
The [DOM: Living Standard] defines two parsing algorithms. The HTML parsing algorithm constructs
a HTML DOM HTMLDocument
document object for the HTML document. The XHTML parsing
algorithm constructs a HTML DOM XMLDocument
object for the HTML document, following
XML parsing rules. This mapping supports both of these document types.
The [DOM: Living Standard] specification defines HTML DOM nodes that are mapped to XDM nodes as follows:
The HTML DOM Document
interface maps to Section 5.1 Document nodesDM40.
The HTML DOM Element
interface maps to Section 5.2 Element nodesDM40.
The HTML DOM Attr
interface maps to Section 5.3 Attribute nodesDM40.
Note:
HTML DOM Attr
instances in an HTML DOM HTMLDocument
that are
namespace declarations are not supported; they are filtered out by this mapping. The
XHTML parsing algorithm does not generate Attr
nodes for namespace
declarations.
If an implementation allows these nodes to be passed in via an API or similar mechanism, their behaviour is ·implementation-defined·.
The HTML DOM ProcessingInstruction
interface maps to
Section 5.5 Processing instruction nodesDM40.
Note:
The HTML parsing algorithm does not support processing instructions. If encountered
they are parsed as comment nodes. The HTML DOM ProcessingInstruction
interface is for when the XHTML parsing algorithm is used, where the document is a
valid XML document.
The HTML DOM Comment
interface maps to Section 5.6 Comment nodesDM40.
The HTML DOM Text
interface maps to Section 5.7 Text nodesDM40.
Note:
The HTML DOM CDATASection
interface is an instance of HTML DOM
Text
, so CDATA sections also map to Section 5.7 Text nodesDM40.
Note:
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 defined by the include-template-content
key in the
15.3.1 HTML parser options map.
If an implementation allows these nodes to be passed in via an API or similar mechanism, their behaviour is ·implementation-defined·.
The result of the Section 4.1 attributes AccessorDM40
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 an empty sequence.
The resulting 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 an 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.
Note:
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.
Note:
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.
Note:
The Attr.localName
property will be ASCII lowercase. The
[HTML: Living Standard] section 13.2.5.33, Attribute name state specifies that
ASCII upper alpha characters are appended to the attribute’s name in lowercase.
The result of the Section 4.2 base-uri AccessorDM40
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 an empty string, then the result is an empty sequence;
Otherwise, the string value is cast to an xs:anyURI
.
The result of the Section 4.3 children AccessorDM40
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 determined as follows:
If the include-template-content
key of the
parse-html-options
map is false()
, the result is
an empty sequence;
Select the HTML DOM DocumentFragment
from the
HTMLTemplateElement.content
property;
The HTML DOM DocumentFragment
’s Node.childNodes
property is 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 an empty sequence.
The resulting 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 an 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;
If the child is an instance of HTML DOM Text
, and the
Node.previousSibling
property value is also an instance of HTML DOM
Text
, that child is not included in this sequence;
Otherwise, the HTML DOM Node
nodes are mapped to XDM according to
the rules in this section.
Note:
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 Section 4.4 document-uri AccessorDM40
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 an empty string, then the result is an empty sequence;
Otherwise, the string value is cast to an xs:anyURI
.
Otherwise, the result is an empty sequence.
The result of the Section 4.5 is-id AccessorDM40
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
.
Note:
In [HTML: Living Standard] section 3.2.5, Global attributes, the
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 Section 4.6 is-idrefs AccessorDM40
dm:is-idrefs($node)
for an HTML DOM Node
is an empty sequence.
The result of the Section 4.7 namespace-nodes AccessorDM40
dm:namespace-nodes($node)
for an HTML DOM Node
is an
empty sequence.
The result of the Section 4.8 nilled AccessorDM40
dm:nilled($node)
for an HTML DOM Node
is false()
.
The result of the Section 4.9 node-kind AccessorDM40
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 Section 4.10 node-name AccessorDM40
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 local name is the value of the
Element.localName
property;
Note:
If the local name contains a character that is not a valid XML
NameStartChar
or NameChar
, then an
·implementation-defined·
replacement character is used. The result must be a valid
NCName
.
For example, in [DOM: Living Standard] section 13.2.9
Coercing an HTML DOM into an infoset, it uses a
Unnnnnn
escape sequence. That would map :
to U00003A
.
This local name escaping only applies for 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 namespace prefix is the value of the
Element.prefix
property, or empty if the value is null;
The namespace URI is the value of the
Element.namespaceURI
property, or empty if the value
is null;
If the node is an instance of HTML DOM Attr
then the result is
determined as follows:
The local name is the value of the
Attr.localName
property;
Note:
If the local name contains a character that is not a valid XML
NameStartChar
or NameChar
, then an
·implementation-defined·
replacement character is used. The result must be a valid
NCName
.
For example, in [DOM: Living Standard] section 13.2.9
Coercing an HTML DOM into an infoset, it uses a
Unnnnnn
escape sequence. That would map :
to U00003A
.
This local name escaping only applies for 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 namespace prefix is the value of the
Attr.prefix
property, or empty if the value is null;
The namespace URI is the value of the
Attr.namespaceURI
property, or empty if the value is null;
If the node is an instance of HTML DOM ProcessingInstruction
then
the result is an xs:QName
constructed as follows:
The local name is the value of the
ProcessingInstruction.target
property;
The namespace prefix is empty;
The namespace URI is empty;
Otherwise, the result is an empty sequence.
Note:
The HTML parser will set the Element.namespaceURI
property
of an HTML DOM Element
according to the element type.
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"
.
Note:
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.
Note:
The Element.localName
property will be ASCII lowercase. The
[HTML: Living Standard] section 13.2.5.8, Tag name state specifies that
ASCII upper alpha characters are appended to the attribute’s name in lowercase.
This is used when processing the Tag open state and
End tag open state HTML parser states for open and close tags
respectively.
Note:
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.
Note:
The Attr.localName
property will be ASCII lowercase. The
[HTML: Living Standard] section 13.2.5.33, Attribute name state specifies that
ASCII upper alpha characters are appended to the attribute’s name in lowercase.
The result of the Section 4.11 parent AccessorDM40
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 an empty sequence;
Otherwise, the result is $parent
using the XDM mapping rules
described in this section.
Note:
The current node can only have a HTML DOM DocumentFragment
parent node
if the include-template-content
key of the html-parser-options
is true()
.
Note:
The HTML DOM DocumentFragment
’s Node.parentNode
property
is null, and document fragment attached to HTMLTemplateElement.content
property do not have a host
property connecting the fragment back to
the template element.
If a future version of [DOM: Living Standard] adds a 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 Section 4.12 string-value AccessorDM40
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 15.7.12.1 Tree string construction;
If the node is an instance of HTML DOM Element
, then use the
algorithm described in 15.7.12.1 Tree string construction;
If the node is an instance of HTML DOM Text
, then use the
algorithm described in 15.7.12.2 Text node string construction;
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 character information items for text node children of an element:
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
.
Note:
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 Section 4.13 type-name AccessorDM40
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 an empty sequence.
The result of the Section 4.14 typed-value AccessorDM40
dm:typed-value($node)
for an HTML DOM Node
is as follows:
Let $string-value
be the 15.7.12 string-value Accessor
for the node;
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 Section 4.15 unparsed-entity-public-id AccessorDM40
dm:unparsed-entity-public-id($node)
for an HTML DOM Node
is an empty sequence.
The result of the Section 4.16 unparsed-entity-system-id AccessorDM40
dm:unparsed-entity-system-id($node)
for an HTML DOM Node
is an empty sequence.
Comma separated values (CSV) refers to a wide variety of plain-text tabular data with fields and records separated by standard character delimiters. CSV has developed informally for decades, and this implementation refers to [RFC 4180], which provides a standardized grammar. This section defines a mapping from RFC 4180 to constructs in the XDM model, and provides illustrative examples of how these constructs can be used in conjunction with existing language features to provide rich processing of CSV data.
A CSV is a 2-dimensional tabular data structure consisting of multiple rows. Each row contains multiple fields. Each field’s position in the row is organised by column located in a column Fields across records are members of a column, identified by position and possibly name. Each field contains a single string value. Column names can be assigned within a CSV using an optional header row.
The rows and fields from this specification map directly to the record and field structures defined in RFC 4180, which has no explicit structure to represent columns.
A row can be thought of as analogous to both a sequence of fields and a map of fields (when columns are named). Fields are ordered left-to-right and thus have a position, as with an array. Named columns allow fields to be retrieved by name, as with a map.
Fields are simple strings. A field that contains reserved characters (one of the delimiters) must be quoted, and the quote character must be escaped if it occurs within a field. (See 15.8.3 Field quoting.)
The functions for processing CSV-formatted data are built on
fn:parse-csv
, which provides a simple representation of a parsed CSV
as a sequence of arrays-of-strings, array(xs:string)*
, handling row and
column delimiters, and quoting.
The fn:csv-to-xml
and fn:csv-to-xdm
functions provide more
sophisticated processing.
All three functions: fn:parse-csv
, fn:csv-to-xml
, and
fn:csv-to-xdm
, take options to control basic parsing, consisting
of specifying the various delimiters. These core delimiter options are used by the
functions that generate CSV data:
common-csv-options : |
|
record( |
|
row-delimiter? |
as xs:string , |
column-delimiter? |
as xs:string , |
quote-character? |
as xs:string |
) |
Additionally, the parsing functions share an additional option to control whether leading and trailing whitespace should be stripped or not.
parse-csv-options : |
|
record( |
|
row-delimiter? |
as xs:string , |
column-delimiter? |
as xs:string , |
quote-character? |
as xs:string , |
trim-whitespace? |
as xs:boolean |
) |
Rows in CSV are typically delimited with CRLF, LF, or CR line endings, although field quoting means that there is not always a one-to-one mapping between line and row in a file.
The row delimiter defaults to matching any of CRLF (

),
LF (

), or CR (
). Valid values for the row
delimiter are a single unicode character, or one of CRLF, LF, or CR, that has
not been marked for use as the column delimiter. Implementations
must raise [err:FOCV0002] if the
row-delimiter
option is set to a mutli-character string other
than CRLF (

), and [err:FOCV0003]
if the same string has been set for row or column delimiter, or quote
character.
Fields in CSV are typically delimited with a comma. Files with other field delimiters are common, especially when the comma has data significance, for example with the use of the decimal comma in much of the world (there the delimiter is usually the semicolon).
The column delimiter defaults to the comma ","
. Valid values for
the column delimiter are a single unicode character, that has not been marked
for use as the row delimiter. Implementations must raise
[err:FOCV0002] if the column-delimiter
option is set to a mutli-character string, and [err:FOCV0003] if the same string has been set for row or column delimiter, or quote
character.
CSVs, per RFC 4180, require that fields be wrapped with a quote character if they contain either the row or column delimiter. This is achieved by wrapping the field with the quote character:
"A single field, with a comma","another field containing CRLF within it"
If a field is to contain the quote character, it must be escaped by preceding it with itself, as with escaping double quotes in XPath (see Section 4.3.1 LiteralsXP40). Implementations must raise [err:FOCV0001] if a quote character appears within a field incorrectly escaped.
incorrectly escaped " quote character
The quotes surrounding quoted fields are not included in their content. The following input string, when parsed, would produce a sequence of strings, as shown below:
'"Field 1","Field 2","Field ""with quotes"" 3"'
('Field 1', 'Field 2', 'Field "with quotes" 3')
The quote character defaults to the double quote "
.
No space is allowed between the column delimiter and a quote. Implementations must raise [err:FOCV0001] if whitespace or other characters occur between a quote character and the nearest column delimiter.
The following example is illegal and parsing it should raise an error.
'"Field 1", "Field 2", "Field 3"'
The basic output from fn:parse-csv
returns a sequence of rows, where
each row is simply mapped to an array of xs:string
values.
The first row of the CSV is returned as with all the other rows.
fn:parse-csv
does not distinguish between a header row and data
rows, and returns all of them.
'Column 1,Column 2,Column 3 Field 1A,Field 1B,Field 1C Field 2A,Field 2B,Field 2C'
Produces
( ["Column 1", "Column 2", "Column 3"], ["Field 1A", "Field 1B", "Field 1C"], ["Field 2A", "Field 2B", "Field 2C"] )
There is an expectation that, in the general case, all rows in a given CSV will have the same number of columns, but there is no guarantee of this.
'Column 1,Column 2,Column 3 Field 1A,Field 1B,Field 1C Field 2A,Field 2B,Field 2C,Field 2D'
Produces
( ["Column 1", "Column 2", "Column 3"], ["Field 1A", "Field 1B", "Field 1C"], ["Field 2A", "Field 2B", "Field 2C", "Field 2D] )
[RFC 4180] states that CSVs should contain the
same number of fields in each row, so that there are a uniform number of columns.
However, the reality is that CSVs can, and sometimes do, contain a variable number
of fields in a row. As a result, implementations of this function must
not truncate or pad the number of fields in each row for any reason.
The fn:csv-to-xml
and fn:csv-to-xdm
functions provide
facilities to deal with enforcing uniformity and an expected number of
columns.
fn:csv-to-xdm
The fn:csv-to-xdm
function returns a
parsed-csv-structure-record
:
parsed-csv-structure-record : |
|
record( |
|
columns |
as csv-columns-record , |
rows |
as csv-row-record* |
) |
header
entryThe columns
entry describes how columns map to names, as well as
providing all the fields in the header row that was used to generate the column
names.
csv-columns-record : |
|
record( |
|
names |
as map(xs:string, xs:integer) , |
fields |
as xs:string* |
) |
It’s required. If column names were not extracted, then implementations
must return a csv-columns-record
whose
names
entry is an empty map, and whose fields
entry is the empty sequence.
rows
entryThe rows
entry returns the rows themselves. It is a sequence of
csv-row
records. If the CSV was empty of rows, implementations
must return a rows
entry consisting of the
empty sequence.
csv-row
recordcsv-row-record : |
|
record( |
|
fields |
as xs:string* , |
field |
as function(union(xs:integer, xs:string)) as xs:string? |
) |
The csv-row
record represents a single row. The
fields
entry is a sequence containing the fields as
xs:string
.
The field
entry contains a function, as described below:
field
functionThe function returned in the field
entry is an arity 1 (one)
function which takes either a string or an integer as its argument
$key
, and returns a field from the csv-row
’s
fields
sequence by either column position (when passed an
xs:integer
) or column name (when passed an
xs:string
).
This function is, effectively, a partial application of
fn:csv-fetch-field-by-column
where its $columns
argument is bound to the columns
entry of the
parsed-csv-structure-record
, and its $row
argument
is bound to array{csv-row?fields}
. This is described in more
detail below:
Given a string, $csv-string
containing CSV data, implementations
must return a function that will return identical results
to fn:csv-fetch-field-by-column
called with the same
csv-columns
and an array()
containing the same
items as the fields
sequence:
let $csv-record := fn:csv-to-xdm($csv-string), $csv-columns := $csv-record?columns, $csv-row := head($csv-record?rows) return if (empty($csv-row?field(1))) then empty(fn:csv-fetch-field-by-column($csv-columns, array{$csv-row}, 1)) else $csv-row?field(1) = fn:csv-fetch-field-by-column($csv-columns, array{$csv-row}, 1) (: must return true :)
The fn:csv-to-xml
function returns XML representing the CSV data.
Following is a CSV text and its XML representation.
Name,Date,Amount Alice,2023-07-14,1.23 Bob,2023-07-14,2.34
<csv xmlns="http://www.w3.org/2005/xpath-functions"> <columns> <column>Name</column> <column>Date</column> <column>Amount</column> </columns> <rows> <row> <field column="Name">Alice</field> <field column="Date">2023-07-14</field> <field column="Amount">1.23</field> </row> <row> <field column="Name">Bob</field> <field column="Date">2023-07-14</field> <field column="Amount">2.34</field> </row> </rows> </csv>
If column names were not extracted, then implementations should
not include the <header>
element, and
<field>
elements should not have
the column
attribute:
<csv xmlns="http://www.w3.org/2005/xpath-functions"> <rows> <row> <field>Name</field> <field>Date</field> <field>Amount</field> </row> <row> <field>Alice</field> <field>2023-07-14</field> <field>1.23</field> </row> <row> <field>Bob</field> <field>2023-07-14</field> <field>2.34</field> </row> </rows> </csv>
An XSD 1.0 schema for the XML representation is provided in C.3 Schema for the result of fn:csv-to-xml.
The following examples illustrate how an application can build more complex processing of the output of fn:parse-csv
.
A variable, $crlf
is assumed to be in scope containing the CR and LF characters
let $crlf := fn:char('x0D')||fn:char('x0A')
fn:csv-to-xdm
Direct conversion is a matter of iterating across the records and fields to
generate <tr>
and <td>
elements.
Using XQuery:
let $csv := fn:csv-to-xdm(`name,city{$crlf}Bob,Berlin`), $headers := $parsed-csv?headers-record return <table> <thead>{ for $column in $csv?columns?fields return <th>{ $column }</th> }</thead> <tbody>{ for $row in $csv?rows return <tr> { for $field in $row?fields return <td>{ $field }</td> } </tr> }</tbody> </table>
Using XSLT:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:eg="http://example.org/eg" xmlns:array="http://www.w3.org/2005/xpath-functions/array" exclude-result-prefixes="eg array" version="4.0"> <xsl:output method="xml" indent="true"/> <xsl:template match="." mode="csv-th" expand-text="true"> <th>{.}</th> </xsl:template> <xsl:template match="." mode="csv-td" expand-text="true"> <td>{.}</td> </xsl:template> <xsl:template match="." mode="csv-tr"> <tr> <xsl:apply-templates select=".?fields" mode="csv-td"/> </tr> </xsl:function> <xsl:template name="xsl:initial-template"> <xsl:variable name="csv" select="csv-to-xdm(`name,city{$crlf}Bob,Berlin`)"/> <table> <thead> <tr> <xsl:apply-templates select="$csv?columns?fields" mode="csv-th"/> </tr> </thead> <tbody> <xsl:apply-templates select="$csv?rows" mode="csv-tr"/> </tbody> </table> </xsl:template> </xsl:stylesheet>
fn:csv-to-xml
The fn:csv-to-xml
function makes these kinds of
conversion-to-XML-table tasks simpler by providing a simple XML represenation of the data. Here, in XQuery:
let $csv := fn:csv-to-xml(`name,city{$crlf}Bob,Berlin`) return <table> <thead>{ for $column in $csv/csv/columns/column return <th>{ $column }</th> }</thead> <tbody>{ for $row in $csv/csv/rows/row return <tr>{ for $field in $row/field return <td>{ $field }</td> }</tr> } }</tbody> </table>
And in XSLT:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fn="http://www.w3.org/2005/xpath-functions" exclude-result-prefixes="fn" version="4.0"> <xsl:output method="xml" indent="true"/> <xsl:template match="fn:column" expand-text="true"> <th>{.}</th> </xsl:template> <xsl:template match="fn:field" expand-text="true"> <td>{.}</td> </xsl:template> <xsl:template match="fn:row"> <tr> <xsl:apply-templates/> </tr> </xsl:function> <xsl:template match="fn:columns"> <thead> <tr> <xsl:apply-templates/> </tr> </thead> </xsl:function> <xsl:template match="fn:rows"> <tbody> <xsl:apply-templates/> </tbody> </xsl:function> <xsl:template match="fn:csv"> <table> <xsl:apply-templates/> </table> </xsl:template> <xsl:template name="xsl:initial-template"> <xsl:apply-templates select="fn:csv-to-xml(`name,city{$crlf}Bob,Berlin`)"/> </xsl:template> </xsl:stylesheet>
The following functions are defined to obtain information from the static or dynamic context.
Function | Meaning |
---|---|
fn:position |
Returns the context position from the dynamic context. |
fn:last |
Returns the context size from the dynamic context. |
fn:current-dateTime |
Returns the current date and time (with timezone). |
fn:current-date |
Returns the current date. |
fn:current-time |
Returns the current time. |
fn:implicit-timezone |
Returns the value of the implicit timezone property from the dynamic context. |
fn:default-collation |
Returns the value of the default collation property from the dynamic context. |
fn:default-language |
Returns the value of the default language property from the dynamic context. |
fn:static-base-uri |
This function returns the value of the executable base URI property from the dynamic context. |
Returns the context position from the dynamic context.
fn:position () as xs:integer |
This function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
Returns the context position from the dynamic context. (See Section C.2 Dynamic Context Components XP31.)
A dynamic error is raised [err:XPDY0002]XP if the context item is absentDM40.
Returns the context size from the dynamic context.
fn:last () as xs:integer |
This function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
Returns the context size from the dynamic context. (See Section C.2 Dynamic Context Components XP31.)
A dynamic error is raised [err:XPDY0002]XP if the context size is absentDM40.
Under most circumstances, the context size is absent only if the context item is absent. However, XSLT 3.0 with streaming defines situations in which the context item and context position are known, but the context size is unknown.
Expression | Result |
---|---|
|
|
Returns the current date and time (with timezone).
fn:current-dateTime () as xs:dateTimeStamp |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
Returns the current dateTime (with timezone) from the dynamic context. (See Section
C.2 Dynamic Context Components
XP31.) This is an
xs:dateTime
that is current at some time during the evaluation of a
query or transformation in which fn:current-dateTime
is executed.
This function is ·deterministic·. The precise instant during the query
or transformation represented by the value of fn:current-dateTime()
is
·implementation-dependent·.
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
|
Returns the current date.
fn:current-date () as xs:date |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
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 fn:current-date
is executed.
This function is ·deterministic·. The precise instant during the query
or transformation represented by the value of fn:current-date
is ·implementation-dependent·.
The returned date will always have an associated timezone, which will always be the same as the implicit timezone in the dynamic context
|
Returns the current time.
fn:current-time () as xs:time |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
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 fn:current-time
is executed.
This function is ·deterministic·. The precise instant during the query
or transformation represented by the value of fn:current-time()
is ·implementation-dependent·.
The returned time will always have an associated timezone, which will always be the same as the implicit timezone in the dynamic context
|
Returns the value of the implicit timezone property from the dynamic context.
fn:implicit-timezone () as xs:dayTimeDuration |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
Returns the value of the implicit timezone property from the dynamic context. Components of the dynamic context are described in Section C.2 Dynamic Context Components XP31.
Returns the value of the default collation property from the dynamic context.
fn:default-collation () as xs:string |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
Returns the value of the default collation property from the dynamic context context. Components of the dynamic context are described in [TITLE OF XP31 SPEC, TITLE OF id-xp-dynamic-context-components SECTION]XP31.
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.
fn:default-language () as xs:language |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default language.
Returns the value of the default language property from the dynamic context. Components of the dynamic context are described in Section 2.1.2 Dynamic Context XP31.
The default language property can never be absent. The functions fn:format-integer
,
fn:format-date
, fn:format-time
, and fn:format-dateTime
are defined to use the default language if no explicit language is supplied. The default language
may play a role in selection of a default collation, but this is not a requirement.
This function returns the value of the executable base URI property from the dynamic context.
fn:static-base-uri () as xs:anyURI? |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.
The function (despite its name) returns the value of the executable base URI property from the dynamic context. If the property is absent, the empty sequence is returned.
Components of the dynamic context are described in [TITLE OF XP31 SPEC, TITLE OF dynamic_context SECTION]XP31 .
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
fn:static-base-uri
function should return a URI suitable for locating
resources needed during dynamic evaluation.
If a call on the fn:static-base-uri
function appears within the expression used
to define the value of an optional parameter to a user-defined function, then the value supplied
to the function (if the argument is omitted) will be the executable base URI from the dynamic
context of the function caller. This allows such a function to resolve relative URIs supplied
in other parameters to the same function.
The functions included in this section operate on function items, that is, values referring to a function.
[Definition] Functions that accept functions among their arguments, or that return functions in their result, are described in this specification as higher-order functions.
Note:
Some functions such as fn:parse-json
allow the option of supplying a callback function
for example to define exception behavior. Where this is not essential to the use of the function,
the function has not been classified as higher-order for this purpose; in applications where function items
cannot be created, these particular options will not be available.
Function | Meaning |
---|---|
fn:function-lookup |
Returns a function item having a given name and arity, if there is one. |
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-annotations |
Returns the annotations of the function identified by a function item. |
Returns a function item having a given name and arity, if there is one.
fn:function-lookup ( |
||
$name |
as , |
|
$arity |
as
|
|
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
A call to fn:function-lookup
starts by looking for a
function definitionXP40
in the named functions component of the dynamic context
(specifically, the dynamic context of the call to fn:function-lookup
),
using the expanded QName supplied as $name
and the arity supplied as
$arity
. There can be at most one such function definition.
If no function definition can be identified (by name and arity), then an empty sequence is returned.
If a function definition is identified, then a function item is obtained from the function
definition using the same rules as for evaluation of a named function reference
(see Section 4.6.2.4 Named Function ReferencesXP40). The captured context of
the returned function item (if it is context dependent) is the static and dynamic context of
the call on fn:function-lookup
.
If the arguments to fn:function-lookup
identify a function that is present
in the static context of the function call, the function will always return the same
function that a static reference to this function would bind to. If there is no such
function in the static context, then the results depend on what is present in the
dynamic context, which is ·implementation-defined·.
This function can be useful where there is a need to make a dynamic decision on which of several statically known functions to call. It can thus be used as a substitute for polymorphism, in the case where the application has been designed so several functions implement the same interface.
The function can also be useful in cases where a query or stylesheet module is written
to work with alternative versions of a library module. In such cases the author of the
main module might wish to test whether an imported library module contains or does not
contain a particular function, and to call a function in that module only if it is
available in the version that was imported. A static call would cause a static error if
the function is not available, whereas getting the function using
fn:function-lookup
allows the caller to take fallback action in this
situation.
If the function that is retrieved by fn:function-lookup
is ·context-dependent·, that is, if it has
dependencies on the static or dynamic context of its caller, the context that applies is
the static and/or dynamic context of the call to the fn:function-lookup
function itself. The context thus effectively forms part of the closure of the returned
function. In practice this applies only where the target of
fn:function-lookup
is a built-in function, because user-defined
functions never depend on the static or dynamic context of the function call. The rule
applies recursively, since fn:function-lookup
is itself a context-dependent
built-in function.
However, the static and dynamic context of the call to fn:function-lookup
may play a role even when the selected function definition is not itself context dependent,
if the expressions used to establish default parameter values are context dependent.
The function identity is determined in the same way as for
a named function reference. Specifically, if there is no context dependency, two calls
on fn:function-lookup
with the same name and arity must return the same function.
These specifications do not define any circumstances in which the dynamic context will contain functions that are not present in the static context, but neither do they rule this out. For example an API may provide the ability to add functions to the dynamic context. Equally, these specifications do not define any mechanism for creating context-dependent functions other than the built-in context-dependent functions, but neither do they rule out the existence of such functions.
The mere fact that a function exists and has a name does not of itself mean that the
function is present in the dynamic context. For example, functions obtained through
use of the fn:load-xquery-module
function are not added to the dynamic context.
Expression | Result |
---|---|
|
|
The expression |
|
The expression let $f := function-lookup(xs:QName('zip:binary-entry'), 2) return if (exists($f)) then $f($href, $entry) else () zip:binary-entry($href, $entry) if the function is available, or
an empty sequence otherwise.
|
Returns the name of the function identified by a function item.
fn:function-name ( |
||
$function |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 an empty sequence.
The prefix part of the returned QName is ·implementation-dependent·.
Expression | Result |
---|---|
|
(The namespace prefix of the returned QName is not predictable.) |
|
|
Returns the arity of the function identified by a function item.
fn:function-arity ( |
||
$function |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The fn:function-arity
function returns the arity (number of arguments) of
the function identified by $function
.
Expression | Result |
---|---|
|
|
|
|
let $initial := substring(?, 1, 1) return function-arity($initial) |
|
Returns the annotations of the function identified by a function item.
fn:function-annotations ( |
||
$function |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The fn:function-annotations
function returns the annotations of
the function identified by $function
as a map.
For each annotation, a map entry is returned: The key is the name of the annotation.
The value is a sequence comprising the annotation values, or an empty sequence
if the annotation has no values.
If a function (for example, a built-in function) has no annotations,
an empty map is returned.
Expression | Result |
---|---|
declare %private function local:inc($c) { $c + 1 }; function-annotations(local:inc#1) |
|
let $old := %local:deprecated('0.1', '0.2') function() {} let $ann := function-annotations($old) return map:keys($ann) || ': ' || string-join(map:values($ann), ', ') |
|
|
|
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: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 those items from a supplied sequence that have the highest value of a sort key, where the sort key can be computed using a caller-supplied function. |
fn:index-where |
Returns the position in an input sequence of items that match a supplied predicate. |
fn:items-after |
Returns the items from the input sequence that follow the first item to match a supplied predicate. |
fn:items-before |
Returns the items from the input sequence that precede the first item to match a supplied predicate. |
fn:items-starting-where |
Returns the items from the input sequence starting from the first item to match a supplied predicate. |
fn:items-ending-where |
Returns the items from the input sequence ending with the first item to match a supplied predicate. |
fn:iterate-while |
Processes a supplied value repeatedly, continuing while some condition remains true, and returning the first value that does not satisfy the condition. |
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: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: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 one or more supplied sort keys supplied as functions. |
fn:transitive-closure |
Given a function F that navigates from one node to other nodes, returns a function that applies F repeatedly. |
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.
fn:apply ( |
||
$function |
as , |
|
$arguments |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The result of the function is obtained by invoking the supplied function $function
with arguments
taken from the members of the supplied array $arguments
. The first argument of the function call is the first
member of $arguments
, the second argument is the second member of $array
, and so on.
The arity of the supplied function $function
must be the same as the size of the array $array
.
The effect of calling fn:apply($f, [$a, $b, $c, ...])
is the same as the effect of the dynamic function call
$f($a, $b, $c, ....)
. For example, the function conversion rules are applied to the supplied arguments
in the usual way.
A dynamic error is raised if the arity of the function $function
is not the same as the size of the
array $array
([err:FOAP0001]).
The function is useful where the arity of a function item is not known statically.
Expression | Result |
---|---|
|
|
The expression |
Returns true
if every item in the input sequence matches a supplied predicate.
fn:every ( |
||
$input |
as , |
|
$predicate |
as
|
:= fn:identity#1 |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the function is equivalent to the following implementation in XQuery:
declare function fn:every( $input as item()*, $predicate as function(item()) as xs:boolean) as xs:boolean { every $i in $input satisfies $predicate($i) };
or its equivalent in XSLT:
<xsl:function name="fn:every" as="xs:boolean"> <xsl:param name="input" as="item()*"/> <xsl:param name="predicate" as="function(item()) as xs:boolean"/> <xsl:sequence select="every $i in $input satisfies $predicate($i)"/> </xsl:function>
If the second argument is omitted, the first argument must be a sequence of
xs:boolean
values.
The implementation may deliver a result as soon as one item is found for which the predicate
returns false
; it is not required to evaluate the predicate for every item.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
every( ("January", "February", "March", "April", "September", "October", "November", "December"), contains(?, "r") ) |
|
every( ("January", "February", "March", "April", "September", "October", "November", "December") =!> contains("r") ) |
|
New in 4.0. Accepted 2022-09-13.
Returns those items from the sequence $input
for which the supplied function
$predicate
returns true
.
fn:filter ( |
||
$input |
as , |
|
$predicate |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the function is equivalent to the following implementation in XQuery:
declare function filter( $input as item()*, $predicate as function(item()) as xs:boolean) as item()* { if (empty($input)) then () else (head($input)[$predicate(.) eq true()], filter(tail($input), $predicate) ) };
or its equivalent in XSLT:
<xsl:function name="filter" as="item()*"> <xsl:param name="input" as="item()*"/> <xsl:param name="predicate" as="function(item()) as xs:boolean"/> <xsl:if test="exists($input)"> <xsl:sequence select="head($input)[$f(.) eq true()], filter(tail($input), $f)"/> </xsl:if> </xsl:function>
As a consequence of the function signature and the function calling rules, a type error
occurs if the supplied function $predicate
returns anything other than a single
xs:boolean
item; there is no conversion to an effective boolean
value.
The function call fn:filter($SEQ, $F)
has a very similar effect to the
expression $SEQ[$F(.)]
. There are some differences, however. In the case of
fn:filter
, the function $F
is required to return a boolean;
there is no special treatment for numeric predicate values, and no conversion to an
effective boolean value. Also, with a filter expression $SEQ[$F(.)]
, the
focus within the predicate is different from that outside; this means that the use of a
context-sensitive function such as fn:lang#1
will give different results in
the two cases.
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.
fn:fold-left ( |
||
$input |
as , |
|
$zero |
as , |
|
$action |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the function is equivalent to the following implementation in XQuery:
declare function fold-left( $input as item()*, $zero as item()*, $action as function(item()*, item()) as item()*) as item()* { if (empty($input)) then $zero else fold-left(tail($input), $action($zero, head($input)), $action) };
or its equivalent in XSLT:
<xsl:function name="fold-left" as="item()*"> <xsl:param name="input" as="item()*"/> <xsl:param name="zero" as="item()*"/> <xsl:param name="action" as="function(item()*, item()) as item()*"/> <xsl:choose> <xsl:when test="empty($input)"> <xsl:sequence select="$zero"/> </xsl:when> <xsl:otherwise> <xsl:sequence select="fold-left(tail($input), $action($zero, head($input)), $action)"/> </xsl:otherwise> </xsl:choose> </xsl:function>
As a consequence of the function signature and the function calling rules, a type error
occurs if the supplied function $action
cannot be applied to two arguments, where
the first argument is either the value of $zero
or the result of a previous
application of $action
, and the second
is any single item from the sequence $input
.
This operation is often referred to in the functional programming literature as
“folding” or “reducing” a sequence. It takes a function that operates on a pair of
values, and applies it repeatedly, with an accumulated result as the first argument, and
the next item in the sequence as the second argument. The accumulated result is
initially set to the value of the $zero
argument, which is conventionally a
value (such as zero in the case of addition, one in the case of multiplication, or a
zero-length string in the case of string concatenation) that causes the function to
return the value of the other argument unchanged.
Expression | Result |
---|---|
fold-left( 1 to 5, 0, function($a, $b) { $a + $b } ) |
(This returns the sum of the items in the sequence). |
fold-left( (2,3,5,7), 1, function($a, $b) { $a * $b } ) |
(This returns the product of the items in the sequence). |
fold-left( (true(), false(), false()), false(), function($a, $b) { $a or $b } ) |
(This returns |
fold-left( (true(), false(), false()), false(), function($a, $b) { $a and $b } ) |
(This returns |
fold-left( 1 to 5, (), function($a, $b) { $b, $a } ) |
(This reverses the order of the items in a sequence). |
fold-left( 1 to 5, "", concat(?, ".", ?) ) |
|
fold-left( 1 to 5, "$zero", concat("$f(", ?, ", ", ?, ")") ) |
|
fold-left( 1 to 5, map { }, function($map, $n) { map:put($map, $n, $n * 2) } ) |
|
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:fold-right ( |
||
$input |
as , |
|
$zero |
as , |
|
$action |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the function is equivalent to the following implementation in XQuery:
declare function fold-right( $input as item()*, $zero as item()*, $action as function(item(), item()*) as item()*) as item()* { if (empty($input)) then $zero else $action(head($input), fold-right(tail($input), $zero, $action)) };
or its equivalent in XSLT:
<xsl:function name="fold-right" as="item()*"> <xsl:param name="input" as="item()*"/> <xsl:param name="zero" as="item()*"/> <xsl:param name="action" as="function(item(), item()*) as item()*"/> <xsl:choose> <xsl:when test="empty($input)"> <xsl:sequence select="$zero"/> </xsl:when> <xsl:otherwise> <xsl:sequence select="$action(head($input), fold-right(tail($input), $zero, $action))"/> </xsl:otherwise> </xsl:choose> </xsl:function>
As a consequence of the function signature and the function calling rules, a type error
occurs if the supplied function $action
cannot be applied to two arguments, where
the first argument is any item in the sequence $input
, and the second is either
the value of $zero
or the result of a previous application of
$action
.
This operation is often referred to in the functional programming literature as
“folding” or “reducing” a sequence. It takes a function that operates on a pair of
values, and applies it repeatedly, with the next item in the sequence as the first
argument, and the result of processing the remainder of the sequence as the second
argument. The accumulated result is initially set to the value of the $zero
argument, which is conventionally a value (such as zero in the case of addition, one in
the case of multiplication, or a 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), fn:fold-right
produces the same result as
fn:fold-left
.
Expression | Result |
---|---|
fold-right( 1 to 5, 0, function($a, $b) { $a + $b } ) |
(This returns the sum of the items in the sequence). |
fold-right( 1 to 5, "", concat(?, ".", ?) ) |
|
fold-right( 1 to 5, "$zero", concat("$f(", ?, ", ", ?, ")") ) |
|
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 ( |
||
$input |
as , |
|
$action |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the function is equivalent to the following implementation in XQuery:
declare function for-each($input, $action) { if (empty($input)) then () else ($action(head($input)), for-each(tail($input), $action)) };
or its equivalent in XSLT:
<xsl:function name="for-each"> <xsl:param name="iinput"/> <xsl:param name="action"/> <xsl:if test="exists($input)"> <xsl:sequence select="$action(head($input)), for-each(tail($input), $action)"/> </xsl:if> </xsl:function>
The function call fn:for-each($SEQ, $F)
is equivalent to the expression
for $i in $SEQ return $F($i)
, assuming that ordering mode is
ordered
.
See also array:build
, which provides similar functionality for the
case where the input is a sequence rather than an array.
Expression | Result |
---|---|
|
|
for-each( ("john", "jane"), string-to-codepoints#1 ) |
|
|
|
First introduced in 3.1.Functionality unchanged in 4.0, but the specification has been formalized.
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:for-each-pair ( |
||
$input1 |
as , |
|
$input2 |
as , |
|
$action |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the function is equivalent to the following implementation in XQuery:
declare function fn:for-each-pair($input1, $input2, $action) { if(fn:exists($input1) and fn:exists($input2)) then ( $action(fn:head($input1), fn:head($input2)), fn:for-each-pair(fn:tail($input1), fn:tail($input2), $action) ) else () };
or its equivalent in XSLT:
<xsl:function name="fn:for-each-pair"> <xsl:param name="input1"/> <xsl:param name="input2"/> <xsl:param name="action"/> <xsl:if test="fn:exists($input1) and fn:exists($input2)"> <xsl:sequence select="$action(fn:head($input1), fn:head($input2))"/> <xsl:sequence select="fn:for-each-pair(fn:tail($input1), fn:tail($input2), $action)"/> </xsl:if> </xsl:function>
If one sequence is longer than the other, excess items in the longer sequence are ignored.
Expression | Result |
---|---|
for-each-pair( ("a", "b", "c"), ("x", "y", "z"), concat#2 ) |
|
for-each-pair( 1 to 5, 1 to 5, function($a, $b) { 10 * $a + $b } ) |
|
let $s := 1 to 8 return for-each-pair($s, tail($s), function($a, $b) { $a * $b }) |
|
Returns those items from a supplied sequence that have the highest value of a sort key, where the sort key can be computed using a caller-supplied function.
fn:highest ( |
||
$input |
as , |
|
$collation |
as
|
:= fn:default-collation() , |
$key |
as
|
:= fn:data#1 |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
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 5.3.5 Choosing a collation.
The third argument defaults to the function data#1
.
Let $modified-key
be the function:
function($item) { $key($item) => data() ! ( if (. instance of xs:untypedAtomic) then xs:double(.) else .) }
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 fn:min
and fn:max
,
but inconsistent with fn:sort
, which treats untyped values as strings.
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 such that
(fn:deep-equal($key($A), $key($B), $C)
, retaining their order.
If the set of computed keys contains xs:untypedAtomic
values that are not
castable to xs:double
then
operation will fail with a dynamic error ([err:FORG0001]FO).
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 ([err:XPTY0004]XP).
Expression | Result |
---|---|
let $e := <a x="10" y="5" z="2"/> |
|
|
(By default, untyped values are compared as numbers.) |
|
(Here, the attribute values are compared as strings.) |
|
|
highest( ("red", "green", "blue"), (), map { "red" : xs:hexBinary('FF0000'), "green": xs:hexBinary('008000'), "blue" : xs:hexBinary('0000FF') } ) |
|
highest( ("red", "orange", "yellow", "green", "blue", "indigo", "violet"), (), string-length#1 ) |
|
|
|
To find employees having the highest salary: |
|
highest($employees, (), function { xs:decimal(salary) }) |
New in 4.0. Accepted 2022-09-20.
Returns the position in an input sequence of items that match a supplied predicate.
fn:index-where ( |
||
$input |
as , |
|
$predicate |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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
.
More formally, the function returns the result of the expression:
index-of($input!$predicate(.), true())
Expression | Result |
---|---|
|
|
|
|
|
|
index-where( ("January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"), contains(?, "r") ) |
|
New in 4.0. Accepted 2022-09-20.
Returns the items from the input sequence that follow the first item to match a supplied predicate.
fn:items-after ( |
||
$input |
as , |
|
$predicate |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The supplied $predicate
function is called for each item in the input sequence $input
,
to return a boolean value. Let $P
be the 1-based position of the first item to match the predicate,
or -1 if no item matches the predicate.
The function then returns if ($P lt 0) then () else fn:subsequence($input, $P + 1)
.
To retain the first matching item, use fn:items-starting-where
.
Expression | Result |
---|---|
|
|
items-after( ("January", "February", "March", "April", "May"), starts-with(?, "A") ) |
|
|
|
|
|
parse-xml("<doc><p/><p/><h2/><img/></doc>")//doc/* => items-after(function { boolean(self::h2) }) |
|
New in 4.0. Accepted 2022-10-25.
Returns the items from the input sequence that precede the first item to match a supplied predicate.
fn:items-before ( |
||
$input |
as , |
|
$predicate |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The supplied $predicate
function is called for each item in the input sequence $input
,
to return a boolean value. Let $P
be the 1-based position of the first item to match the predicate,
or -1 if no item matches the predicate.
The function then returns if ($P lt 0) then $input else fn:subsequence($input, 1, $P - 1)
.
To retain the first matching item, use fn:items-ending-where
.
Expression | Result |
---|---|
|
|
items-before( ("January", "February", "March", "April", "May"), starts-with(?, "A") ) |
|
|
|
|
|
parse-xml("<doc><p/><p/><h2/><img/></doc>")//doc/* => items-before(function { boolean(self::img) }) =!> name() |
|
("Aardvark", "Antelope", "Bison", "Buffalo", "Camel", "Dingo") => items-starting-where(starts-with(?, "B")) => items-before(starts-with(?, "D")) |
|
New in 4.0. Accepted 2022-10-25.
Returns the items from the input sequence starting from the first item to match a supplied predicate.
fn:items-starting-where ( |
||
$input |
as , |
|
$predicate |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The supplied $predicate
function is called for each item in the input sequence $input
,
to return a boolean value. Let $P
be the 1-based position of the first item to match the predicate,
or -1 if no item matches the predicate.
The function then returns if ($P lt 0) then () else fn:subsequence($input, $P)
.
To exclude the first item, use fn:items-after
.
Expression | Result |
---|---|
|
|
items-starting-where( ("January", "February", "March", "April", "May"), starts-with(?, "A") ) |
|
|
|
|
|
parse-xml("<doc><p/><p/><h2/><img/></doc>")//doc/* => items-starting-where(function { boolean(self::h2) }) =!> name() |
|
New in 4.0. Accepted 2022-10-25.
Returns the items from the input sequence ending with the first item to match a supplied predicate.
fn:items-ending-where ( |
||
$input |
as , |
|
$predicate |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The supplied $predicate
function is called for each item in the input sequence $input
,
to return a boolean value. Let $P
be the 1-based position of the first item to match the predicate,
or -1 if no item matches the predicate.
The function then returns if ($P lt 0) then $input else fn:subsequence($input, 1, $P)
.
To exclude the last item, use fn:items-before
.
Expression | Result |
---|---|
|
|
items-ending-where( ("January", "February", "March", "April", "May"), starts-with(?, "A") ) |
|
|
|
|
|
parse-xml("<doc><p/><p/><h2/><img/></doc>")//doc/* => items-ending-where(function { boolean(self::h2) }) =!> name() |
|
New in 4.0. Accepted 2022-10-25.
Processes a supplied value repeatedly, continuing while some condition remains true, and returning the first value that does not satisfy the condition.
fn:iterate-while ( |
||
$input |
as , |
|
$predicate |
as , |
|
$action |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Informally, the function behaves as follows:
The supplied $input
value is tested against the supplied
$predicate
.
If the result of the predicate is true
, $action($input)
is evaluated, the resulting value is used as a new $input
, and the
process repeats from step 1.
If the result of the predicate is false
, the function returns the
value of $input
.
More formally, the function is equivalent to the following implementation in XQuery:
declare function fn:iterate-while( $input as item()*, $predicate as function(item()*) as xs:boolean, $action as function(item()*) as item()* ) as item()* { if ($predicate($input)) then ( fn:iterate-while($action($input), $predicate, $action) ) else ( $input ) };
While-loops are very common in procedural programming languages, and this function provides a way to write functionally clean and interruptible iterations without side-effects. An initial value is tested and replaced by new values until it matches a given condition. Depending on the use case, the value can be a simple atomic item or an arbitrarily complex data structure.
Note that, just as when writing recursive functions, it is easy to construct infinite loops.
Expression | Result |
---|---|
iterate-while( 2, function { . < 100 }, function { . * . } ) |
|
let $input := (0 to 4, 6 to 10) return iterate-while( 0, function($n) { $n = $input }, function($n) { $n + 1 } ) |
(This returns the first positive number missing in a sequence.) |
iterate-while( 1 to 9, function($seq) { head($seq) < 5 }, function($seq) { tail($seq) } ) |
(The first number of a sequence is removed as long as it is smaller than 5.) |
let $input := 3936256 return iterate-while( $input, function($result) { abs($result * $result - $input) >= 0.0000000001 }, function($guess) { ($guess + $input div $guess) div 2 } ) => round(5) |
(This computes the square root of a number.) |
The following example generates random doubles. It is interrupted once a number exceeds a given limit: |
|
let $r := random-number-generator() let $map := iterate-while( $r, function($r) { $r?number < 0.8 }, function($r) { map:put($r?next(), 'numbers', ($r?numbers, $r?number)) } ) return $map?numbers |
New in 4.0. Approved.
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:lowest ( |
||
$input |
as , |
|
$collation |
as
|
:= fn:default-collation() , |
$key |
as
|
:= fn:data#1 |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
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 5.3.5 Choosing a collation.
The third argument defaults to the function data#1
.
Let $modified-key
be the function:
function($item) { $key($item) => data() ! ( if (. instance of xs:untypedAtomic) then xs:double(.) else . ) }
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 fn:min
and fn:max
,
but inconsistent with fn:sort
, which treats untyped values as strings.
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 first item in the sorted sequence.
The function returns those items $A from the input sequence such that
(fn:deep-equal($key($A), $key($B), $C)
, retaining their order.
If the set of computed keys contains xs:untypedAtomic
values that are not
castable to xs:double
then
operation will fail with a dynamic error ([err:FORG0001]FO).
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 ([err:XPTY0004]XP).
Expression | Result |
---|---|
let $e := <a x="10" y="5" z="2"/> |
|
|
(By default, untyped values are compared as numbers.) |
|
(Here, the attribute values are compared as strings.) |
|
|
lowest( ("red", "green", "blue"), (), map { "red" : xs:hexBinary('FF0000'), "green": xs:hexBinary('008000'), "blue" : xs:hexBinary('0000FF') } ) |
|
lowest( ("April", "June", "July", "August"), (), string-length#1 ) |
|
|
|
To find employees having the lowest salary: |
|
lowest($employees, (), function { xs:decimal(salary) }) |
New in 4.0. Accepted 2022-09-20.
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:partition ( |
||
$input |
as , |
|
$break-when |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 $break-when
function with two
arguments: the contents of the current partition, and the item J.
Each partition is a sequence of items; the function result wraps each partition as an array, and returns the sequence of arrays.
If the $break-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 $break-when
function returns false
, the item J is added to the current partition.
More formally, the function returns the result of the expression:
fold-left($input, (), function($partitions, $next) { if (empty($partitions) or $break-when(foot($partitions)?*, $next)) then ($partitions, [$next]) else (trunk($partitions), array{foot($partitions)?*, $next}) })
The function enables a variety of positional grouping problems to be solved. For example:
partition($input, function($a, $b) { count($a) eq 3 }
partitions a sequence into fixed size groups of length 3.
partition($input, function($a, $b) { boolean($b/self::h1) }
starts a new group whenever an h1
element is encountered.
partition($input, function($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 |
---|---|
partition( ("Anita", "Anne", "Barbara", "Catherine", "Christine"), function($partition, $next) { substring(head($partition),1,1) ne substring($next,1,1) } ) |
|
partition( (1, 2, 3, 4, 5, 6, 7), function($partition, $next) { count($partition) eq 2 } ) |
|
partition( (1, 4, 6, 3, 1, 1), function($partition, $next) { sum($partition) ge 5 } ) |
|
partition( tokenize("In the beginning was the word"), function($partition, $next) { sum(($partition, $next) ! string-length()) gt 10 } ) |
|
partition( (1, 2, 3, 6, 7, 9, 10), function($partition, $next) { $next != foot($partition) + 1 } ) |
|
Proposed for 4.0
Returns true
if at least one item in the input sequence matches a supplied predicate.
fn:some ( |
||
$input |
as , |
|
$predicate |
as
|
:= fn:identity#1 |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the function is equivalent to the following implementation in XQuery:
declare function fn:some( $input as item()*, $predicate as function(item()) as xs:boolean) as xs:boolean { some $i in $input satisfies $predicate($i) };
or its equivalent in XSLT:
<xsl:function name="fn:some" as="xs:boolean"> <xsl:param name="input" as="item()*"/> <xsl:param name="predicate" as="function(item()) as xs:boolean"/> <xsl:sequence select="some $i in $input satisfies $predicate($i)"/> </xsl:function>
If the second argument is omitted, the first argument must be a sequence of xs:boolean
values.
The implementation may deliver a result as soon as one item is found for which the predicate
returns true
; it is not required to evaluate the predicate for every item.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
some( ("January", "February", "March", "April", "September", "October", "November", "December"), contains(?, "z") ) |
|
some( ("January", "February", "March", "April", "September", "October", "November", "December") =!> contains("r") ) |
|
New in 4.0. Accepted 2022-09-13.
Sorts a supplied sequence, based on the value of one or more supplied sort keys supplied as functions.
fn:sort ( |
||
$input |
as , |
|
$collation |
as
|
:= fn:default-collation() , |
$key |
as
|
:= fn:data#1 , |
$order |
as
|
:= 'ascending' |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
The result of the function is a sequence that contains all the items from $input
,
typically in a different order, the order being defined by one or more sort key definitions.
A sort key definition has three parts:
A sort key function, which is applied to each item in the input sequence to determine a sort key value.
A collation, which is used when comparing sort key values
that are of type xs:string
or xs:untypedAtomic
.
An order direction, which is ascending
or
descending
.
The number of sort key definitions is determined by the number of function items supplied
in the $key
argument. If the argument is absent or empty, the default is
a single sort key definition using the function data#1
.
The $n
'th sort key definition (where $n
counts from one (1))
is established as follows:
The sort key function is $key[$n] otherwise data#1
.
The collation is $collation[$n] otherwise $collation[last()]
otherwise default-collation()
.
That is, it is the collation supplied in the corresponding item of the supplied
$collation
argument; or in its absence, the last entry in
$collation
; or if $collation
is absent or empty, the
default collation from the static context of the caller.
The order direction is
$order[$n] otherwise $order[last()] otherwise "ascending"
.
That is, it is "ascending"
or "descending"
according
to the value of the corresponding item in the supplied $order
argument; or in its absence, the last entry in $order
; or
if $order
is absent or empty, then "ascending"
.
When comparing values of types other than xs:string
or xs:untypedAtomic
,
the corresponding collation is ignored, and no error is reported if the supplied value is
not a known or valid collation name. If it is necessary to supply such an ignored value
(for example, in the case where a non-string sort key is followed by another sort key
that requires a collation) the empty string can be supplied.
The result of the function is obtained as follows:
The result sequence contains the same items as the input sequence $input
,
but generally in a different order.
The sort key definitions are established as described above.
The sort key definitions are in 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 sort key function in the
first sort key definition.
If those two sort key values are equal, then the position is determined by the relative magnitude
of their secondary sort key values, computed by evaluating the
sort key function in the second sort key definition, and so on.
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 order direction in the corresponding sort key definition
is "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.
Note:
That is, the sort is stable.
Each sort key value for a given item is obtained by applying the sort key
function of the corresponding sort key definition to that item. The result
of this function is in the general case a sequence of atomic values.
Two sort key values $a
and $b
are compared as follows:
Let $C be the collation in the corresponding sort key definition.
Let $REL
be the result of evaluating op:lexicographic-compare($key($A), $key($B), $C)
where op:lexicographic-compare($a, $b, $C)
is defined as follows:
if (empty($a) and empty($b)) then 0 else if (empty($a)) then -1 else if (empty($b)) then +1 else let $rel = op:simple-compare(head($a), head($b), $C) return if ($rel eq 0) then op:lexicographic-compare(tail($a), tail($b), $C) else $rel
Here op:simple-compare($k1, $k2)
is defined as follows:
if ($k1 instance of union(xs:string, xs:anyURI, xs:untypedAtomic) and $k2 instance of union(xs:string, xs:anyURI, xs:untypedAtomic)) then compare($k1, $k2, $C) else if ($k1 eq $k2 or (is-NaN($k1) and is-NaN($k2))) then 0 else if (is-NaN($k1) or $k2 lt $k2) then -1 else +1
Note:
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 ([err:XPTY0004]XP).
XSLT and XQuery both provide native sorting capability, but earlier releases of XPath provided no sorting functionality for use in standalone environments.
In addition there are cases where this function may be more flexible than the built-in sorting capability for XQuery or XSLT, for example when the sort key or collation is chosen dynamically, or when the sort key is a sequence of items rather than a single item.
The results are compatible with the results of XSLT sorting (using xsl:sort
) in the case where the sort key evaluates to a sequence of
length zero or one, given the options stable="yes"
.
The results are compatible with the results of XQuery sorting (using the order by
clause) in the case where the sort key evaluates to a sequence of
length zero or one, given the options stable
, ascending
, and empty least
.
The function has been enhanced in 4.0 to allow multiple sort keys to be defined, each potentially with a different collation, and to allow sorting in descending order.
The effect of the XQuery option empty least|greatest
, which controls
whether the empty sequence is sorted before or after all other values, can be achieved by adding an
extra sort key definition that evaluates whether or not the actual sort key is empty (when sorting
boolean values, false
precedes true
).
Supplying too many items in the $collation
and/or $order
arguments
is not an error; the excess values are ignored except for type-checking against the function
signature.
Expression | Result |
---|---|
|
|
|
|
|
|
To sort a set of strings |
|
let $SWEDISH := "http://www.w3.org/2013/collation/UCA?lang=se" return sort($in, $SWEDISH) |
|
To sort a sequence of employees by last name as the major sort key and first name as the minor sort key, using the default collation: |
|
sort($employees, (), fn{name ! (last, first)}) |
|
To sort a sequence of employees first by increasing last name (using Swedish collation order) and then by decreasing salary: |
|
let $SWEDISH := "http://www.w3.org/2013/collation/UCA?lang=se" return sort($employees, $SWEDISH, (fn{name/last}, fn{xs:decimal(salary)}), ("ascending", "descending")) |
Substantially revised in 4.0 to allow multiple sort key definitions.
Given a function F that navigates from one node to other nodes, returns a function that applies F repeatedly.
fn:transitive-closure ( |
||
$step |
as , |
|
$min |
as
|
:= 1 , |
$max |
as
|
:= () |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The argument is a function $step
that takes a single node as input, and returns a set of nodes as its result.
The result of the fn:transitive-closure
function is a function TC that takes a
single node N as input, and returns all nodes that can be reached from
N by applying $step
repeatedly between $min
and $max
times (inclusive).
Although $step
may return any sequence of nodes, the result is treated as a set: the order of nodes
in the sequence is ignored, and duplicates are ignored. The result of calling TC will always be
a sequence of nodes in document order with no duplicates.
The default value of $min
, if the argument is not supplied or is set to an empty sequence,
is 1 (one). If $min
is zero, the result of calling TC will include the argument node
N. If $min
is greater than zero, the result will include N only if
N is reachable by a cyclic path involving between $min
and $max
steps.
The default value of $max
, if the argument is not supplied or is set to an empty sequence,
is unbounded. In this situation the function TC continues execution until no further nodes
are added to the result set. Note that if the $step
function constructs new nodes, this
can lead to non-termination. Specifying an explicit value for $max
guarantees termination.
Cycles in the data are not a problem, even if $max
is unbounded;
the function stops searching when it finds no new nodes.
Expression | Result |
---|---|
let $data := document{<doc> <person id="0"/> <person id="1" manager="0"/> <person id="2" manager="0"/> <person id="3" manager="2"/> <person id="4" manager="2"/> <person id="5" manager="1"/> <person id="6" manager="3"/> <person id="7" manager="6"/> <person id="8" manager="6"/> </doc>} |
|
let $direct-reports := function($p as element(person)) as element(person)* { $p/../person[@manager=$p/@id] } |
|
let $tc := transitive-closure($direct-reports) return $tc($data//person[@id="2"])/string(@id) |
|
let $tc := transitive-closure($direct-reports, min:=0) return $tc($data//person[@id="2"])/string(@id) |
|
let $tc := transitive-closure($direct-reports, max:=2) return $tc($data//person[@id="2"])/string(@id) |
|
let $tc := transitive-closure(function { child::* }) return $tc($data)/@id/string() |
(The transitive closure of the child axis is the ancestor axis
if |
The following example, given |
|
let $tc := transitive-closure(function { document(//(xsl:import|xsl:include)/@href) }) return $tc($root) =!> document-uri() |
|
This example uses the XSLT-defined |
|
The following example, given |
|
let $tc := transitive-closure(function { child::section }, min:=2, max:=3) return $tc($doc/article)/head |
The following functions allow dynamic loading and execution of XQuery queries and XSLT stylesheets, or XPath 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. |
Provides access to the public functions and global variables of a dynamically loaded XQuery library module.
fn:load-xquery-module ( |
||
$module-uri |
as , |
|
$options |
as
|
:= map{} |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The function loads an implementation-defined set of modules having the target namespace $module-uri
.
Calling the one-argument version of the function has the same effect as calling the two-argument version with an empty map as the second argument.
The $options
argument can be used to control the way in which the function operates.
The ·option parameter conventions· apply.
Key | Meaning |
---|---|
xquery-version |
The minimum level of the XQuery language that the
processor must support.
|
location-hints |
A sequence of URIs (in the form of xs:string values) which may be used or ignored in an
·implementation-defined· way.
|
context-item |
The item to be used as the initial context item when evaluating global variables in
the library module. Supplying
an 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 must conform to
this type, without conversion.
|
variables |
Values for external variables defined in the library module. Values must be supplied
for external variables that have no default value, and may be supplied for external variables
that do have a default value. The supplied value must conform to the required type of the variable, without conversion.
The map contains one entry for each external variable: the key is the variable’s name,
and the associated value is
the variable’s value. The ·option parameter conventions· do not apply
to this contained map.
|
vendor-options |
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 should be a URI controlled
by the vendor of the XQuery processor. The meaning of the associated value is ·implementation-defined·.
Implementations should ignore options whose names are in an unrecognized namespace.
The ·option parameter conventions· do not apply
to this contained map.
|
The result of the function is a map R with two entries:
There is an entry whose key is the xs:string
value "variables"
and whose associated value
is a map V. This map (V) contains one entry for each public global variable declared in the library module.
The key of the
entry is the name of the variable, as an xs:QName
value; the associated value is the value of the variable.
There is an entry whose key is the xs:string
value "functions"
and whose associated value
is a map F. 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 xs:QName
value; the associated value is a map A.
This map (A) contains one entry for each arity N within the arity range of any of the function declarations
with the given name; its key is N,
as an xs:integer
value, and its associated value is a function item obtained as if by evaluating
a named function reference Q#N
, using the static and dynamic context of the call on
fn:load-xquery-module
. The function item
can be invoked using the rules for dynamic function invocation.
The static and dynamic context of the library module are established according to the rules in Section C Context Components XQ31.
It is ·implementation-defined· whether constructs in the library module are evaluated in the same ·execution scope· as the calling module.
The library module that is loaded may import other modules using an import module
declaration. The result of
fn:load-xquery-module
does not include global variables or functions declared in such a transitively imported module.
However, the options
map supplied in the function call may
(and if no default is defined, must)
supply values for external variables declared in transitively loaded library modules.
The library module that is loaded may import schema declarations using an import schema
declaration. It is
·implementation-defined· whether schema components in the in-scope
schema definitions of the calling module
are automatically added to the in-scope schema definitions of the dynamically loaded module. The in-scope schema definitions
of the calling and called modules must be consistent, according to the rules defined in
Section
2.2.5 Consistency Constraints
XQ31.
Where nodes are passed to or from the dynamically loaded module, for example as an argument or result of a function, they should if possible retain their node identity, their base URI, their type annotations, and their relationships to all other nodes in the containing tree (including ancestors and siblings). If this is not possible, for example because the only way of passing nodes to the chosen XQuery implementation is by serializing and re-parsing, then a node may be passed in the form of a deep copy, which may lose information about the identity of the node, about its ancestors and siblings, about its base URI, about its type annotations, and about its relationships to other nodes passed across the interface.
If $module-uri
is a zero length string, a dynamic error is raised [err:FOQM0001].
If the implementation is not able to find a library module with the specified target namespace, an error is raised [err:FOQM0002].
If a static error (including a statically detected type error) is encountered when processing the library module, a dynamic error is raised [err:FOQM0003].
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 [err:FOQM0005].
If no suitable XQuery processor is available, a dynamic error is raised [err:FOQM0006]. This includes (but is not limited to) the following cases:
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 as is.
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 fn:load-xquery-module
function call itself.
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 recommended for security reasons that implementations should provide a user option to disable its use, or to disable aspects of its functionality.
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.
Invokes a transformation using a dynamically loaded XSLT stylesheet.
fn:transform ( |
||
$options |
as
|
|
) as
|
This function is ·nondeterministic·, ·context-dependent·, and ·focus-independent·.
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 ·option parameter conventions· apply to this map; they do not apply to any nested map unless otherwise specified.
The function first identifies the requested XSLT version, as follows:
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.
Note:
The phrase locate an XSLT processor includes the possibility of locating a software product and configuring it to act as an XSLT processor that implements the requested XSLT version.
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.
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 [XSL Transformations (XSLT) Version 1.0]), the supplied options must include all of the following (if anything else is present, it is ignored):
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 an empty map)initial-mode
(defaults to the stylesheet’s default mode)delivery-format
(defaults todocument
)serialization-params
(defaults to an empty map)enable-messages
(default is implementation-defined)requested-properties
(default is an empty map)vendor-options
(defaults to an empty map)cache
(default is implementation-defined)
For invocation of an XSLT 2.0 processor (see [XSL Transformations (XSLT) Version 2.0]), the supplied options must include all of the following (if anything else is present, it is ignored):
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 an empty map)base-output-uri
(defaults to absent)delivery-format
(defaults todocument
)serialization-params
(defaults to an empty map)enable-messages
(default is implementation-defined)enable-trace
(default is implementation-defined)requested-properties
(default is an empty map)vendor-options
(defaults to an empty map)cache
(default is implementation-defined)
For invocation of an XSLT 3.0 processor (see [XSL Transformations (XSLT) Version 4.0]), the supplied options must include all of the following (if anything else is present, it is ignored):
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 optionallypackage-version
Invocation details, as exactly one of the following combinations:
For apply-templates invocation, all of the following:
Exactly one of source-node
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
Note:
If the source-node
option 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
Note:
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 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 an empty map)stylesheet-params
(defaults to an empty map)global-context-item
(defaults to absent)base-output-uri
(defaults to absent)
delivery-format
serialization-params
(defaults to an empty map)enable-assertions
(default isfalse
)enable-messages
(default is implementation-defined)enable-trace
(default is implementation-defined)requested-properties
(default is an empty map)vendor-options
(defaults to an empty map)cache
(default is implementation-defined)
The meanings of each option are defined in the table below.
Key | Applies to | Value | Meaning |
---|---|---|---|
base-output-uri |
1.0, 2.0, 3.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 static base URI of the fn:transform
function call.
|
|
cache |
1.0, 2.0, 3.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.
|
|
delivery-format |
1.0, 2.0, 3.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 .
|
|
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
fn:serialize function) the final encoding stage of
serialization (which turns a sequence of characters into a sequence of
octets) is either skipped, or reversed by decoding the octet stream back
into a character stream. |
||
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. | ||
enable-assertions |
3.0 | Indicates whether any xsl:assert instructions in the stylesheet
are to be evaluated.
|
|
enable-messages |
1.0, 2.0, 3.0 | Indicates whether any xsl:message instructions in the stylesheet
are to be evaluated. The destination and formatting of any such messages is
implementation-defined.
|
|
enable-trace |
2.0, 3.0 | Indicates whether any fn:trace functions in the stylesheet are to
generate diagnostic messages. The destination and formatting of any such messages
is
implementation-defined.
|
|
function-params |
3.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.
|
|
global-context-item |
3.0 | The value of the global context item, as defined in XSLT 3.0
|
|
initial-function |
3.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 .
|
|
initial-match-selection |
3.0 | The value of the initial match selection, as defined in XSLT 3.0
|
|
initial-mode |
1.0, 2.0, 3.0 | The name of the initial processing mode.
|
|
initial-template |
2.0, 3.0 | The name of a named template in the stylesheet to act as the initial entry
point.
|
|
package-name |
3.0 | The name of the top-level stylesheet package to be invoked (an absolute
URI)
|
|
package-location |
3.0 | The location of the top-level stylesheet package, as a relative or absolute
URI
|
|
package-node |
3.0 | A document or element node containing the top-level stylesheet
package
|
|
package-text |
3.0 | The top-level stylesheet package in the form of unparsed lexical
XML.
|
|
package-version |
3.0 | The version of the top-level stylesheet package to be invoked.
|
|
post-process |
1.0 2.0 3.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 fn:transform function (for example, this will be the supplied
base output URI in the case of the principal result, or the string “output” if no
base output URI was supplied). The second argument is the
actual value. The value that is returned in the result of the fn:transform
function is the result of applying this post-processing.
Note: 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 [EXPath],
then a serialized document might be written to filestore by calling the
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
|
|
requested-properties |
1.0, 2.0, 3.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:
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 [err:FOXT0001] indicating that no suitable XSLT processor
is available.
|
|
serialization-params |
1.0, 2.0, 3.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
fn:serialize .
|
|
source-node |
1.0, 2.0, 3.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.
|
|
static-params |
3.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 function conversion
rules.
|
|
stylesheet-base-uri |
1.0, 2.0, 3.0 | A string intended to be used as the static base URI of the principal stylesheet
module. This value must be used if no other static base URI is
available. If the supplied stylesheet already has a base URI (which will generally
be
the case if the stylesheet is supplied using stylesheet-node or
stylesheet-location ) then it is ·implementation-defined· whether this
parameter has any effect. If the value is a relative reference, it is resolved against
the static base URI of the fn:transform function call.
|
|
stylesheet-location |
1.0, 2.0, 3.0 | URI that can be used to locate the principal stylesheet module. If relative, it
is resolved against the static base URI of the fn:transform function call.
The value also acts as the default for stylesheet-base-uri.
|
|
stylesheet-node |
1.0, 2.0, 3.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.
|
|
stylesheet-params |
1.0, 2.0, 3.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 function conversion rules. The
default is an empty map.
|
|
stylesheet-text |
1.0, 2.0, 3.0 | The principal stylesheet module in the form of unparsed lexical
XML.
|
|
template-params |
3.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 function conversion
rules.
|
|
tunnel-params |
3.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 function conversion
rules.
|
|
vendor-options |
1.0, 2.0, 3.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 should be a URI controlled by the vendor
of the XSLT processor. The meaning of the associated value is ·implementation-defined·. Implementations
should ignore options whose names are in an unrecognized
namespace. Default is an empty map.
|
|
xslt-version |
1.0, 2.0, 3.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 should if possible retain their node identity, their base URI, their type annotations, and their relationships to all other nodes in the containing tree (including ancestors and siblings). If this is not possible, for example because the only way of passing nodes to the chosen XSLT implementation is by serializing and re-parsing, then a node may be passed in the form of a deep copy, which may lose information about the identity of the node, about its ancestors and siblings, about its base URI, about its type annotation, and about its relationships to other nodes passed across the interface.
It is ·implementation-defined· whether the XSLT transformation is executed within the same ·execution scope· as the calling code.
The function is ·nondeterministic· in that it is
·implementation-dependent· whether running the function twice against the same
inputs produces identical results. The results of two invocations may differ in the identity of any returned nodes; they may also
differ in other respects, for example because the value of fn:current-dateTime
is different for the two invocations,
or because the contents of external documents accessed using fn:doc
or xsl:source-document
change between
one invocation and the next.
A dynamic error is raised [err:FOXT0001] if the transformation cannot be invoked because no suitable XSLT processor is available. This includes (but is not limited to) the following cases:
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 [err:FOXT0002] if an error is detected in the supplied parameters (for example if two mutually exclusive parameters are supplied).
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 [err:FOXT0003] if the XSLT transformation invoked by a call on
fn:transform
fails with a static or dynamic error, and no more specific error code is available.
Note:
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 ·implementation-defined· way.
A dynamic error is raised [err:FOXT0004] if the use of this function (or of selected options) has been externally disabled, for example for security reasons.
A dynamic error is raised [err:FOXT0006] if the transformation produces output containing characters available only in XML 1.1, and the calling processor cannot handle such characters.
Recursive use of the fn:transform
function may lead to catastrophic failures such as
non-termination or stack overflow. No error code is assigned to such conditions, since they cannot necessarily
be detected by the processor.
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 recommended for security reasons that implementations should provide a user option to disable its use, or to disable aspects of its functionality such as the ability to write to persistent resources.
The following example loads a stylesheet from the location |
|
let $result := transform( map { "stylesheet-location" : "render.xsl", "source-node" : doc('test.xml') }) return $result?output//body |
Returns a function whose effect is to apply a supplied binary operator to two arguments.
fn:op ( |
||
$operator |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The supplied operator must be one of:
","
, "and"
, "or"
, "+"
,
"-"
, "*"
, "div"
, "idiv"
,
"mod"
, "="
, "<"
, "<="
,
">"
, ">="
, "!="
, "eq"
,
"lt"
, "le"
, "gt"
, "ge"
,
"ne"
, "<<"
, ">>"
,
"is"
, "||"
, "|"
, "union"
,
"except"
, "intersect"
, "to"
,
"otherwise"
The result of calling fn:op("⊙")
, where ⊙
is one of the above operators, is
the function represented by the XPath expression:
function($x, $y) { $x ⊙ $y }
For example, op("+")
returns function($x, $y) { $x + $y }
.
A dynamic error is raised if the supplied argument is not one of the supported operators ([TODO: error code]).
The function is useful in contexts where an 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="function($x, $y) { $x, $y }
The function is also useful in cases where the choice of operator to apply is made dynamically.
Expression | Result |
---|---|
|
|
|
|
New in 4.0. Accepted 2022-10-11.
Maps were introduced as a new datatype in XDM 3.1. This section describes functions that operate on maps.
A map is an additional kind of item.
[Definition] A map consists of a set of entries, also known as key-value pairs. Each entry comprises a key which is an arbitrary atomic value, and an arbitrary sequence called the associated value.
[Definition] Within a map, no two entries have the same key.
Two atomic values K1
and K2
are the same key
for this purpose if the function call fn:atomic-equal($K1, $K2)
returns 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 map:remove
function returns a map that differs
from the supplied map by the omission (typically) of one entry, but the supplied map is not changed by the operation.
Two calls on map:remove
with the same arguments return maps that are
indistinguishable from each other; there is no way of asking whether these are “the same map”.
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 get
function: the expression
$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.
It is often useful to decompose a map into a sequence of entries, or key-value pairs (in which the key is an atomic value 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 key-value pairs, each with its own advantages and disadvantages. Both approaches are supported by functions in this library. These are described below:
[Definition] A singleton map is a map containing a single entry.
It is possible to decompose any map into a sequence of ·singleton maps·, and to construct a map from a sequence of singleton maps.
For example the map
map{"x":1, "y":2}
can be decomposed to the sequence (map{"x":1}, map{"y":2})
.
[Definition] A key-value pair map is a map containing two
entries, one (with the key "key"
) containing the key part of a key value pair, the other (with the key "value"
)
containing the value part of a key value pair.
For example
the map map{"x":1, "y":2}
can be decomposed as
(map{"key":"x", "value":1}, map{"key":"y", "value":2})
A ·key-value pair map· is an instance of the type
record(key as xs:anyAtomicType, value as item()*)
.
The following table summarizes the way in which these two representations can be used to compose and decompose maps:
Operation | Singleton Maps | Key-Value Pair Maps |
---|---|---|
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 |
|
|
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 fn:serialize
can in some cases
be used to produce a JSON representation of a map.
Function | Meaning |
---|---|
fn:atomic-equal |
Determines whether two atomic values are equal, under the rules used for comparing keys in a map. |
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:entries |
Returns a sequence containing all the key-value pairs present in a map, each represented as a ·singleton map·. |
map:entry |
Returns a ·singleton map· that represents a single key-value pair. |
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 concatenation of the results. |
map:get |
Returns the value associated with a supplied key in a given map. |
map:keys |
Returns a sequence containing keys present in a map |
map:merge |
Returns a map that combines the entries from a number of existing maps. |
map:of-pairs |
Returns a map that combines data from a sequence of ·key-value pair maps·. |
map:pair |
Returns a ·key-value pair map· that represents a single key-value pair. |
map:pairs |
Returns a sequence containing all the key-value pairs present in a map, each represented as a ·key-value pair map·. |
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 those having a specified key. |
map:replace |
Returns a map based on the contents of an existing map, computing a new value to be associated with a supplied key. |
map:size |
Returns the number of entries in the supplied map. |
map:substitute |
Applies a supplied function to every entry in a map, returning a map whose entries have the same keys as the input, but (potentially) different associated values. |
map:values |
Returns a sequence containing all the values present in a map, in unpredictable order. |
Determines whether two atomic values are equal, under the rules used for comparing keys in a map.
fn:atomic-equal ( |
||
$value1 |
as , |
|
$value2 |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function fn:atomic-equal
is used to compare two atomic values for equality. This function
has the following properties (which do not all apply to the eq
operator):
Any two atomic values can be compared, regardless of their type.
No dynamic error is ever raised (the result is either true
or false
).
The result of the comparison never depends on the static or dynamic context.
Every value (including NaN
) is equal to itself.
The comparison is symmetric: if A equals B, then B equals A.
The comparison is transitive: if A equals B and B equals C, then A equals C.
The function returns true
if and only if one of the following conditions is true:
All of the following conditions are true:
$value1
is an instance of xs:string
, xs:anyURI
, or xs:untypedAtomic
$value2
is an instance of xs:string
, xs:anyURI
, or xs:untypedAtomic
fn:codepoint-equal($value1, $value2)
Note:
Strings are compared without any dependency on collations.
All of the following conditions are true:
$value1
is an instance of xs:decimal
, xs:double
, or xs:float
$value2
is an instance of xs:decimal
, xs:double
, or xs:float
One of the following conditions is true:
Both $value1
and $value2
are NaN
Note:
xs:double('NaN')
is the same key as xs:float('NaN')
Both $value1
and $value2
are positive infinity
Note:
xs:double('INF')
is the same key as xs:float('INF')
Both $value1
and $value2
are negative infinity
Note:
xs:double('-INF')
is the same key as xs:float('-INF')
$value1
and $value2
when converted to decimal numbers with no rounding or loss of precision
are mathematically equal.
Note:
Every instance of xs:double
, xs:float
, and xs:decimal
can be represented
exactly as a decimal number provided enough digits are available both before and after the decimal point. Unlike the eq
relation, which converts both operands to xs:double
values, possibly losing precision in the process, this
comparison is transitive.
Note:
Positive and negative zero compare equal.
All of the following conditions are true:
$value1
is an instance of xs:date
, xs:time
, xs:dateTime
,
xs:gYear
, xs:gYearMonth
, xs:gMonth
, xs:gMonthDay
, or xs:gDay
$value2
is an instance of xs:date
, xs:time
, xs:dateTime
,
xs:gYear
, xs:gYearMonth
, xs:gMonth
, xs:gMonthDay
, or xs:gDay
One of the following conditions is true:
Both $value1
and $value2
have a timezone
Neither $value1
nor $value2
has a timezone
fn:deep-equal($value1, $value2)
Note:
The use of deep-equal
rather than eq
ensures that comparing values of different
types yields false
rather than an error.
All of the following conditions are true:
$value1
is an instance of xs:boolean
, xs:hexBinary
, xs:base64Binary
,
xs:duration
, xs:QName
, or xs:NOTATION
$value2
is an instance of xs:boolean
, xs:hexBinary
, xs:base64Binary
,
xs:duration
, xs:QName
, or xs:NOTATION
fn:deep-equal($value1, $value2)
Note:
The use of deep-equal
rather than eq
ensures that comparing values of different
types yields false
rather than an error.
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
values are considered to be duplicates when used as keys in a map. A map cannot
contain two separate entries whose keys are the same as defined by this function.
The function is also used when matching keys in functions such as map:get
and map:remove
.
The rules for comparing keys in a map are chosen to ensure that the comparison is:
Context-free: there is no dependency on the static or dynamic context
Error-free: any two atomic values can be compared, and the result is either true
or false
, never an error
Transitive: if A is the same key as B, and B is the same key as C, then A is the same key as C.
Two atomic values may be distinguishable even though they are equal under this comparison. For example: they may have
different type annotations; dates and times may have different timezones; xs:QName
values may have different
prefixes.
As always, any algorithm that delivers the right result is acceptable. For example, when testing whether an xs:double
value D is the same key as an xs:decimal
value that has N significant digits, it is not
necessary to know all the digits in the decimal expansion of D to establish the result: computing the first N+1
significant digits (or indeed, simply knowing that there are more than N significant digits) is sufficient.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
atomic-equal( "https://www.w3.org/", xs:anyURI("https://www.w3.org/") ) |
|
|
|
Proposed for 4.0; the function is identical to the internal op:same-key
function in 3.1
Returns a map that typically contains one entry for each item in a supplied input sequence.
map:build ( |
||
$input |
as , |
|
$key |
as
|
:= fn:identity#1 , |
$value |
as
|
:= fn:identity#1 , |
$combine |
as
|
:= fn:op(',') |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Informally, the function processes each item in $input
in order. It calls the $key
function on
that item to obtain a key value, and the $value
function to obtain an associated value.
If the key is non-empty, then:
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 calls the $combine
function to combine the existing value
for the key with the new value, and replaces the entry with this combined value.
More formally, the result of the function is the result of the following expression:
fold-left($input, map{}, fn($map, $next) { let $nextKey := $key($next) let $nextValue := $value($next) return if (fn:exists($nextKey)) then if (map:contains($map, $nextKey)) then map:put($map, $nextKey, $combine($map($nextKey), $nextValue)) else map:put($map, $nextKey, $nextValue) else $map })
Although defined to process the input sequence in order, this is only relevant when combining the entries for duplicate keys.
The default function for both $key
and $value
is the identity function.
Although it is permitted to default both, this serves little purpose: usually at least one of these arguments
will be supplied.
The default action for combining entries with duplicate keys is to perform a sequence-concatenation of the corresponding values,
equivalent to the duplicates: combine
option on map:merge
. Other potentially useful
functions for combining duplicates include:
fn($a, $b) { $a }
Use the first value and discard the remainder
fn($a, $b) { $b }
Use the last value and discard the remainder
fn:concat(?, ",", ?)
Form the string-concatenation of the values, comma-separated
fn:op('+')
Compute the sum of the values
Expression | Result |
---|---|
|
|
|
(Returns a map with one entry for each distinct value of |
map:build( 1 to 5, value := format-integer(?, "w") ) |
(Returns a map with five entries. The function to compute the key is an identity function, the
function to compute the value invokes |
map:build( ("January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"), substring(?, 1, 1) ) |
map{"A": ("April", "August"), "D": ("December"), "F": ("February"), "J": ("January", "June", "July"), "M": ("March", "May"), "N": ("November"), "O": ("October"), "S": ("September")} |
map:build( ("apple", "apricot", "banana", "blueberry", "cherry"), substring(?, 1, 1), string-length#1, op("+") ) |
(Constructs a map where the key is the first character of an input item, and where the corresponding value is the total string-length of the items starting with that character.) |
The following expression creates a map whose keys are employee |
|
map:build(//employee, fn { @ssn }) |
|
The following expression creates a map whose keys are employee |
|
map:build(//employee, fn { @location }, fn { 1 }, op("+")) |
|
The following expression creates a map whose keys are employee |
|
map:build(//employee, function { @location }, combine := fn($a, $b) { highest(($a, $b), fn { xs:decimal(@salary) }) }) |
|
The following expression creates a map allowing efficient access to every element in a document by means
of its |
|
map:build(//*, generate-id#1) |
Accepted for version 4.0 2022-10-18
Tests whether a supplied map contains an entry for a given key
map:contains ( |
||
$map |
as , |
|
$key |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function map:contains
returns true
if the ·map· supplied as $map
contains an entry with the ·same key· as $key
; otherwise it returns false
.
Expression | Result |
---|---|
let $week := map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:"Samstag"} |
|
|
|
|
|
|
|
|
|
|
|
Returns a sequence containing all the key-value pairs present in a map, each represented as a ·singleton map·.
map:entries ( |
||
$map |
as
|
|
) as
|
This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.
The function map:entries
takes any ·map·
as its $map
argument and returns the key-value pairs that are present in the map as
a sequence of ·singleton maps·, in ·implementation-dependent· order.
The function is non-deterministic with respect to ordering (see 1.8.4 Properties of functions). This means that two calls with the same argument are not guaranteed to produce the results in the same order.
The effect of the function is equivalent to the expression:
map:for-each($map, fn($k, $v) { map { $k: $v } })
Expression | Result |
---|---|
map:entries( map { 1: "yes", 2: "no" } ) |
(or some permutation thereof) (The result sequence is in ·implementation-dependent· order.) |
Returns a ·singleton map· that represents a single key-value pair.
map:entry ( |
||
$key |
as , |
|
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function map:entry
returns a ·map· which contains a single
entry. The key of the entry in the new map is
$key
, and its associated value is $value
.
The function call map:entry(K, V)
produces the same result as the
expression map{K : V}
.
The function map:entry
is intended primarily for use in conjunction with
the function map:merge
. For example, a map containing seven entries may be
constructed like this:
map:merge(( map:entry("Su", "Sunday"), map:entry("Mo", "Monday"), map:entry("Tu", "Tuesday"), map:entry("We", "Wednesday"), map:entry("Th", "Thursday"), map:entry("Fr", "Friday"), map:entry("Sa", "Saturday") ))
The map:merge
function can be used to construct
a map with a variable number of entries, for example:
map:merge(for $b in //book return map:entry($b/isbn, $b))
Expression | Result |
---|---|
|
|
Selects entries from a map, returning a new map.
map:filter ( |
||
$map |
as , |
|
$predicate |
as
|
|
) as
|
This function is ·context-independent·, and ·focus-independent·.
The function map:filter
takes any ·map· as its $map
argument and applies the supplied function
to each entry in the map; the result is a new map containing those entries for which
the function returns true
.
The function supplied as $predicate
takes two arguments. It is called
supplying the key of the map entry as the first argument, and the associated value as
the second argument.
Expression | Result |
---|---|
map:filter( map { 1: "Sunday", 2: "Monday", 3: "Tuesday", 4:"Wednesday", 5: "Thursday", 6: "Friday", 7: "Saturday" }, function($k, $v) { $k = (1, 7) } ) |
|
map:filter( map { 1: "Sunday", 2: "Monday", 3: "Tuesday", 4: "Wednesday", 5: "Thursday", 6:"Friday", 7:"Saturday" }, function($k, $v) { $v = ("Saturday", "Sunday") } ) |
|
Proposed for 4.0.
Discussed 2022-09-20; decided to defer acceptance pending ideas for alignment with array:filter
.
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:find ( |
||
$input |
as , |
|
$key |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function map:find
searches the sequence supplied as $input
looking for map entries whose key is the ·same key·
as $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 ·implementation-dependent· order) perform both of the following steps, in order:
If K is the ·same key· as $key
,
then add V as a new member to the end of the result array.
Process V (which is, in general, a sequence).
To process an item that is neither a map nor an array, do nothing. (Such items are ignored).
If $input
is an empty sequence, map, or array, or if the requested $key
is not found,
the result will be a zero-length array.
Expression | Result |
---|---|
let $responses := [map{0:'no', 1:'yes'}, map{0:'non', 1:'oui'}, map{0:'nein', 1:('ja', 'doch')}] |
|
|
|
|
|
|
|
let $inventory := map{"name":"car", "id":"QZ123", "parts": [map{"name":"engine", "id":"YW678", "parts":[]}]} |
|
|
|
Applies a supplied function to every entry in a map, returning the concatenation of the results.
map:for-each ( |
||
$map |
as , |
|
$action |
as
|
|
) as
|
This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.
The function map:for-each
takes any ·map· as its $map
argument and applies the supplied function
to each entry in the map, in ·implementation-dependent· order; the result is the sequence obtained by
concatenating the results of these function calls.
The function is non-deterministic with respect to ordering (see 1.8.4 Properties of functions). This means that two calls with the same arguments are not guaranteed to process the map entries in the same order.
The function supplied as $action
takes two arguments. It is called
supplying the key of the map entry as the first argument, and the associated value as
the second argument.
Expression | Result |
---|---|
map:for-each( map { 1: "yes", 2: "no" }, function($k, $v) { $k } ) |
(or some permutation thereof) (This function call is equivalent to calling |
distinct-values( map:for-each( map { 1: "yes", 2: "no" }, function($k, $v) { $v } ) ) |
(or some permutation thereof) (This function call returns the distinct values present in the map, in implementation-dependent order.) |
map:merge( map:for-each( map { "a": 1, "b": 2 }, function($k, $v) { map:entry($k, $v + 1) } ) ) |
(This function call returns a map with the same keys as the input map, with the value of each entry increased by one.) |
This XQuery example converts the entries in a map to attributes on a newly constructed element node: |
|
let $dimensions := map{'height': 3, 'width': 4, 'depth': 5}; return <box>{ map:for-each($dimensions, function($k, $v) { attribute { $k } { $v } }) }</box> |
|
The result is the element |
Returns the value associated with a supplied key in a given map.
map:get ( |
||
$map |
as , |
|
$key |
as , |
|
$fallback |
as
|
:= void#1 |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function map:get
attempts to find an entry within the ·map· supplied as $map
that has
the ·same key· as $key
. If there is such an entry, it returns the associated value;
if not, it invokes the supplied $fallback
function, supplying
the requested $key
value as the argument, and returns the result of this call.
The default $fallback
function always returns an empty sequence.
A return value of ()
from map:get
could indicate that
the key is present in the map with an associated value of ()
, or it could
indicate that the key is not present in the map. The two cases can be distinguished by
calling map:contains
, or by using
a $fallback
function to return a value known never to appear in the map.
The $fallback
function can be used in a number of ways:
It might return a conventional value such as NaN
to indicate that no matching
key was found.
It might raise a dynamic error, by means of a call on fn:error
.
It might compute a result algorithmically. For example, if the map holds a table of
abbreviations, such as map{'CA':'Canada', 'UK':'United Kingdom', 'US':'United States'}
,
then specifying fallback := fn:identity#1
has the effect that the key value is returned
unchanged if it is not found in the map.
Invoking the ·map· as a function item has the same effect
as calling get
with no $fallback
function: 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')
.
Expression | Result |
---|---|
let $week := map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:"Samstag"} |
|
|
|
|
(When the key is not present, the function returns an empty sequence.) |
|
(An empty sequence as the result can also signify that the key is present and the associated value is an empty sequence.) |
map { 1: "single", 2: "double", 3: "triple" } => map:get(10, function { . || "-fold" }) |
(The map holds special cases; the fallback function handles other cases.) |
Returns a sequence containing keys present in a map
map:keys ( |
||
$map |
as , |
|
$predicate |
as
|
:= true#0 |
) as
|
This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.
The function map:keys
takes any ·map·
as its $map
argument. The $predicate
function, if
supplied, takes the value of the corresponding map entry as an argument, and the
result is a sequence containing the keys of those entries for which the function
returns true
in ·implementation-dependent· order.
The function is non-deterministic with respect to ordering (see 1.8.4 Properties of functions). This means that two calls with the same argument are not guaranteed to produce the results in the same order.
More formally, the function returns the result of the following expression:
map:for-each( $map, function($key, $value) { if($predicate($value)) { $key } } )
Expression | Result |
---|---|
|
(or some permutation thereof) (The result is in ·implementation-dependent· order.) |
let $numbers := map { 0: 'zero', 1: 'one', 2: 'two', 3: 'three' } return map:keys($numbers, function { . = ('two', 'three') }) |
|
let $square := map:merge( (1 to 5) ! map:entry(., . * .) ) return map:keys($square, function { . > 5 and . < 20 }) |
|
let $birthdays := map { 'jack': xs:date('1980-12-31'), 'joel': xs:date('1969-11-10'), 'john': xs:date('2001-05-05') } return map:keys($birthdays, function($date) { year-from-date($date) = 1969 }) |
|
Returns a map that combines the entries from a number of existing maps.
map:merge ( |
||
$maps |
as , |
|
$options |
as
|
:= map{} |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function map:merge
returns a map that
is formed by combining the contents of the maps supplied in the $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 ·same key·.
If there are duplicate keys, that is, if two or more maps contain entries having the
·same key·, then the way this is handled is
controlled by the second ($options
) argument.
The definitive specification is as follows.
The effect of calling the single-argument function is the same as the effect of
calling the two-argument function with an empty map as the value of $options
.
The $options
argument can be used to control the way in which duplicate keys are handled.
The ·option parameter conventions· apply.
The entries that may appear in the $options
map are as follows:
Key | Value | Meaning |
---|---|---|
duplicates |
Determines the policy for handling duplicate keys: specifically, the action to be
taken if two maps in the input sequence $maps contain entries with key values
K1 and K2 where K1 and K2 are the
·same key·.
|
|
reject |
An error is raised [err:FOJS0003] if duplicate keys are encountered. | |
use-first |
If duplicate keys are present, all but the first of a set of duplicates are ignored,
where the ordering is based on the order of maps in the $maps argument.
|
|
use-last |
If duplicate keys are present, all but the last of a set of duplicates are ignored,
where the ordering is based on the order of maps in the $maps argument.
|
|
use-any |
If duplicate keys are present, all but one of a set of duplicates are ignored, and it is ·implementation-dependent· which one is retained. | |
combine |
If duplicate keys are present, the result map includes an entry for the key whose
associated value is the sequence-concatenation of all the values associated with the
key,
retaining order based on the order of maps in the $maps argument.
The key value in the result map that corresponds to such a set of duplicates must
be the ·same key· as each of the duplicates, but it is
otherwise unconstrained: for example if the duplicate keys are xs:byte(1)
and xs:short(1) , the key in the result could legitimately be xs:long(1) .
|
The result of the function call map:merge($MAPS, $OPTIONS)
is defined to be consistent with the result of the expression:
let $FOJS0003 := QName("http://www.w3.org/2005/xqt-errors", "FOJS0003"), $duplicates-handler := map { "use-first": function($a, $b) {$a}, "use-last": function($a, $b) {$b}, "combine": function($a, $b) {$a, $b}, "reject": function($a, $b) {fn:error($FOJS0003)}, "use-any": function($a, $b) {fn:random-number-generator()?permute(($a, $b))[1]} }, $combine-maps := function($A as map(*), $B as map(*), $deduplicator as function(*)) { fold-left(map:keys($B), $A, function($z, $k) { if (map:contains($z, $k)) then map:put($z, $k, $deduplicator($z($k), $B($k))) else map:put($z, $k, $B($k)) }) } return fold-left($MAPS, map{}, $combine-maps(?, ?, $duplicates-handler(($OPTIONS?duplicates, "use-first")[1]))
Note:
By way of explanation, $combine-maps
is a function that combines
two maps by iterating over the keys of the second map, adding each key and its corresponding
value to the first map as it proceeds. The second call of fn:fold-left
in the return
clause then iterates over the maps supplied in the call
to map:merge
, accumulating a single map that absorbs successive maps
in the input sequence by calling $combine-maps
.
This algorithm processes the supplied maps in a defined order, but processes the keys within each map in implementation-dependent order.
The use of fn:random-number-generator
represents one possible conformant
implementation for "duplicates":"use-any"
, but it is not the only conformant
implementation and is not intended to be a realistic implementation. The purpose of this
option is to allow the implementation to use whatever strategy is most efficient; for example,
if the input maps are processed in parallel, then specifying "duplicates":"use-any"
means that the implementation does not need to keep track of the original order of the sequence of input
maps.
An error is raised [err:FOJS0003] if the value of
$options
indicates that duplicates are to be rejected, and a duplicate key is encountered.
An error is raised [err:FOJS0005] if the value of
$options
includes an entry whose key is defined
in this specification, and whose value is not a permitted value for that key.
If the input is an empty sequence, the result is an empty map.
If the input is a sequence of length one, the result map is indistinguishable from the supplied 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.
Expression | Result |
---|---|
let $week := map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:"Samstag"} |
|
|
(Returns an empty map). |
map:merge(( map:entry(0, "no"), map:entry(1, "yes") )) |
(Returns a map with two entries). |
map:merge(( ($week, map { 7: "Unbekannt" }) ) |
map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:"Samstag", 7:"Unbekannt"} (The value of the existing map is unchanged; the returned map
contains all the entries from |
map:merge( ($week, map { 6: "Sonnabend" }), map { "duplicates": "use-last" } ) |
map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:"Sonnabend"} (The value of the existing map is unchanged; the returned map
contains all the entries from |
map:merge( ($week, map { 6: "Sonnabend" }), map { "duplicates": "use-first" } ) |
map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:"Samstag"} (The value of the existing map is unchanged; the returned map
contains all the entries from |
map:merge( ($week, map { 6: "Sonnabend" }), map { "duplicates": "combine" } ) |
map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:("Samstag", "Sonnabend")} (The value of the existing map is unchanged; the returned map
contains all the entries from |
Returns a map that combines data from a sequence of ·key-value pair maps·.
map:of-pairs ( |
||
$pairs |
as , |
|
$combine |
as
|
:= fn:op(',') |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function map:of-pairs
returns a map that
is formed by combining ·key-value pair maps· supplied in the
$key-value-pairs
argument.
The optional $combine
argument can be used to define how
duplicate keys should be handled. The default is to form the sequence concatenation
of the corresponding values, retaining their order in the input sequence.
The effect of the function is equivalent to the expression:
map:build($key-value-pairs, fn($kvp) { $kvp?key }, fn($kvp) { $kvp?value }, $combine)
The function can be made to fail with a dynamic error in the event that
duplicate keys are present in the input sequence by supplying a $combine
function that invokes the fn:error
function.
If the input is an empty sequence, the result is an empty map.
There is no requirement that the supplied key-value pairs should have the same or compatible
types. The type of a map (for example map(xs:integer, xs:string)
) is
descriptive of the entries it currently contains, but is not a constraint on how the map
may be combined with other maps.
Expression | Result |
---|---|
let $week := map { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6 :"Samstag" } |
|
|
(Returns an empty map). |
|
(The function |
map:of-pairs(( map { "key": 0, "value": "no" }, map { "key": 1, "value": "yes" } )) |
(Returns a map with two entries). |
map:of-pairs(( map:pairs($week), map { "key": 7, "value": "Unbekannt" } )) |
map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:"Samstag", 7:"Unbekannt"} (The value of the existing map is unchanged; the returned map
contains all the entries from |
map:of-pairs(( map:pairs($week), map { "key": 6, "value": "Sonnabend" } )) |
map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:("Samstag", "Sonnabend")} (The value of the existing map is unchanged; the returned map
contains all the entries from |
map:of-pairs( (map:pairs($week), map { "key": 6, "value": "Sonnabend" }), function($old, $new) { $new } ) |
map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:"Sonnabend"} (The value of the existing map is unchanged; the returned map
contains all the entries from |
map:of-pairs( (map:pairs($week), map { "key": 6, "value": "Sonnabend" }), function($old, $new) { `{$old}|{$new}` } ) |
map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:"Samstag|Sonnabend"} (In the result map, the value for key |
Returns a ·key-value pair map· that represents a single key-value pair.
map:pair ( |
||
$key |
as , |
|
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function map:pair
returns a ·map· which contains two entries, one (with the key "key"
)
containing $key
and the other (with the key "value"
)
containing $value
.
The function call map:pair(K, V)
produces the same result as the
expression map { "key": K, "value": V }
.
The function map:pair
is intended primarily for use in conjunction with
the function map:of-pairs
. A map may be constructed like this:
map:of-pairs(( map:pair("Su", "Sunday"), map:pair("Mo", "Monday"), map:pair("Tu", "Tuesday"), map:pair("We", "Wednesday"), map:pair("Th", "Thursday"), map:pair("Fr", "Friday"), map:pair("Sa", "Saturday") ))
The map:of-pairs
function can be used to construct
a map with a variable number of entries, for example:
map:of-pairs(//book ! map:pair(./isbn, .))
Expression | Result |
---|---|
|
|
Returns a sequence containing all the key-value pairs present in a map, each represented as a ·key-value pair map·.
map:pairs ( |
||
$map |
as
|
|
) as
|
This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.
The function map:pairs
takes any ·map·
as its $map
argument and returns the keys that are present in the map as
a sequence of ·key-value pair maps·, in ·implementation-dependent· order.
A key-value pair map is an instance of type record(key as xs:anyAtomicType, value as item()*)
:
that is a map with two entries, one (with key "key"
) holding the key,
and the other (with key "value"
) holding the value.
The function is non-deterministic with respect to ordering (see 1.8.4 Properties of functions). This means that two calls with the same argument are not guaranteed to produce the results in the same order.
The effect of the function is equivalent to the expression:
map:for-each($map, fn($k, $v) { map { "key": $k, "value": $v } })
Expression | Result |
---|---|
map:pairs( map { 1: "yes", 2: "no" } ) |
(or some permutation thereof) (The result is in ·implementation-dependent· order.) |
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:put ( |
||
$map |
as , |
|
$key |
as , |
|
$value |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function map:put
returns a ·map· that contains all entries from the supplied $map
,
with the exception of any entry whose key is the ·same key· as $key
, together with a new
entry whose key is $key
and whose associated value is $value
.
The effect of the function call map:put($MAP, $KEY, $VALUE)
is equivalent
to the result of the following steps:
let $MAP2 := map:remove($MAP, $KEY)
This returns a map in which all entries with the same key as $KEY
have been removed.
Construct and return a map containing:
All the entries (key/value pairs) in $MAP2
, and
The entry map:entry($KEY, $VALUE)
There is no requirement that the type of $key
and $value
be consistent with the types
of any existing keys and values in the supplied map.
Expression | Result |
---|---|
let $week := map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:"Samstag"} |
|
|
map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:"Sonnabend"} |
|
map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:"Samstag", -1:"Unbekannt"} |
Returns a map containing all the entries from a supplied map, except those having a specified key.
map:remove ( |
||
$map |
as , |
|
$keys |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function map:remove
returns a ·map· containing all the entries in $map
except for any entry whose key is
the ·same key· as an item in
$keys
.
No failure occurs if an item in $keys
does not correspond to any entry in $map
;
that key value is simply ignored.
The effect of the function call map:remove($MAP, $KEY)
can be described more formally as the result of the expression below:
map:merge( map:for-each($MAP, fn($k, $v) { if (some $key in $KEY satisfies fn:atomic-equal($k, $key)) then () else map:entry($k, $v) }) )
Expression | Result |
---|---|
let $week := map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:"Samstag"} |
|
|
map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 5:"Freitag", 6:"Samstag"} |
|
map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:"Samstag"} |
|
|
|
map{0:"Sonntag", 1:"Montag", 2:"Dienstag", 3:"Mittwoch", 4:"Donnerstag", 5:"Freitag", 6:"Samstag"} |
Returns a map based on the contents of an existing map, computing a new value to be associated with a supplied key.
map:replace ( |
||
$map |
as , |
|
$key |
as , |
|
$action |
as
|
|
) as
|
This function is ·context-independent·, and ·focus-independent·.
If the supplied $map
contains an existing entry for the supplied $key
,
then the returned map contains an entry for that $key
whose value is obtained by applying
the supplied $action
to the existing value associated with that key.
Otherwise, the returned map contains an entry for the supplied $key
whose value is
obtained by applying the supplied $action
to an empty sequence.
The effect of the function call map:replace($MAP, $KEY, $VALUE)
is equivalent
to the result of the expression:
if (map:contains($MAP, $KEY)) then map:put($MAP, $KEY, $ACTION(map:get($MAP, $KEY))) else map:put($MAP, $KEY, $ACTION(())
Expression | Result |
---|---|
|
|
|
|
fold-left( ("a", "b", "c", "a"), map { }, function($map, $key) { map:replace($map, $key, function($val) { ($val otherwise 0) + 1 }) } ) |
|
Returns the number of entries in the supplied map.
map:size ( |
||
$map |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function map:size
takes any ·map·
as its $map
argument and returns the number of entries that are present
in the map.
Expression | Result |
---|---|
|
|
|
|
First introduced in 3.1.Functionality unchanged in 4.0, but the specification has been formalized.
Applies a supplied function to every entry in a map, returning a map whose entries have the same keys as the input, but (potentially) different associated values.
map:substitute ( |
||
$map |
as , |
|
$action |
as
|
|
) as
|
This function is ·context-independent·, and ·focus-independent·.
The function map:substitute
takes any ·map· as its $map
argument and applies the supplied function
to each entry in the map; the result is a map that associates the original set of key
values with the results of these function calls.
The function supplied as $action
takes two arguments. It is called
supplying the key of the map entry as the first argument, and the associated value as
the second argument.
The function call map:substitute($m, $f)
returns the same result as
map:merge(map:for-each($m, fn($k, $v) { map:entry($k, $f($k, $v)) }))
.
Expression | Result |
---|---|
map:substitute( map { 1: true(), 2: false() }, function($k, $v) { not($v) } ) |
|
map:substitute( map { 1: "yes", 2: "no" }, function($k, $v) { $v || ' (' || $k || ')' } ) |
|
Returns a sequence containing all the values present in a map, in unpredictable order.
map:values ( |
||
$map |
as
|
|
) as
|
This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.
The function map:values
takes any ·map·
as its $map
argument and returns the values that are present in the map as
a sequence, in ·implementation-dependent· order.
The function is non-deterministic with respect to ordering (see 1.8.4 Properties of functions). This means that two calls with the same argument are not guaranteed to produce the results in the same order.
The effect of the function is equivalent to map:for-each($map, fn($k, $v) { $v })
.
Expression | Result |
---|---|
map:values( map{ 1: "yes", 2: "no" } ) |
(or some permutation thereof) (The result is in ·implementation-dependent· order.) |
map:values( map { 1: ("red", "green"), 2: ("blue", "yellow"), 3:() } ) |
(or some permutation thereof) (The result is in ·implementation-dependent· order.) |
Because a map is a function item, functions that apply to functions also apply
to maps. A map is an anonymous function, so fn:function-name
returns the empty
sequence; fn:function-arity
always returns 1
.
Maps may be compared using the fn:deep-equal
function.
There is no function or operator to atomize a map or convert it to a string (other than fn:serialize
,
which can be used to serialize some maps as JSON texts).
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 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 array:reverse
function returns an array that differs from the supplied
array in the order of its members, but the supplied array is not changed by the operation. Two calls
on array:reverse
with the same argument will return arrays that are indistinguishable from
each other; there is no way of asking whether these are “the same array”. Like sequences, arrays have no identity.
All functionality on arrays is defined in terms of two primitives:
The function array:members
decomposes an array to a sequence of
value records.
The function array:of-members
composes an array from a sequence of
value records.
A value record here is an item that encapsulates an arbitrary value; the representation
chosen for a value record is 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.
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:exists |
Returns true if the supplied array contains one or more members. |
array:filter |
Returns an array containing those members of the $array for which
$predicate returns true . |
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, that is $array(array:size($array)) . |
array:for-each |
Returns an array whose size is the same as array:size($array) , in which
each member is computed by applying $function 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-where |
Returns the position 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:join |
Concatenates the contents of several arrays into a single array. |
array:members |
Delivers the contents of an array as a sequence of value records. |
array:of-members |
Constructs an array from the contents of a sequence of value records. |
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:replace |
Returns an array containing all the members of a supplied array, except for one member which is replaced with a new value, the new value being computed from the previous value. |
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 |
Returns an array containing all the members of the supplied array, sorted according to the value of a sort key supplied as a function. |
array:split |
Delivers the contents of an array as a sequence of singleton 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. |
array:values |
Returns a sequence with the members of an array. |
Returns an array containing all the members of a supplied array, plus one additional member at the end.
array:append ( |
||
$array |
as , |
|
$member |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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
.
More formally, the result is the value of the expression
array:of-members((array:members($array), map{'value':$member}))
.
Expression | Result |
---|---|
|
|
|
|
|
|
First introduced in 3.1.Functionality unchanged in 4.0, but the specification has been formalized
Returns an array obtained by evaluating the supplied function once for each item in the input sequence.
array:build ( |
||
$input |
as , |
|
$action |
as
|
:= fn:identity#1 |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the function is called with one argument, the effect is the same as calling the two-argument
function with fn:identity#1
as the second argument.
Informally, array:build#2
applies the supplied function to each item
in the input sequence, and the resulting sequence becomes one member of the returned array.
More formally, array:build#2
returns the result of the expression:
array:of-members($input ! map{'value':$action(.)})
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.
See also array:for-each
, which provides similar functionality for the
case where the input is an array rather than a sequence.
Expression | Result |
---|---|
|
|
array:build( 1 to 5, function { 2 * . } ) |
|
array:build( 1 to 5, function { 1 to . } ) |
|
array:build( ("red", "green", "blue"), characters#1 ) |
|
array:build( 1 to 5, function { array { 1 to . } } ) |
|
Proposed for 4.0.
Returns true
if the supplied array contains no members.
array:empty ( |
||
$array |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns true
if and only if $array
contains no members, that is,
if array:size($array) eq 0
.
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 an empty array.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
Proposed for 4.0, see issue 229
Returns true
if the supplied array contains one or more members.
array:exists ( |
||
$array |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns true
if and only if $array
contains one or more members, that is,
if array:size($array) gt 0
.
The function name is chosen by analogy with fn:exists
. Note that the function tests whether
any array members exist, not whether the array itself exists. A function such as:
function($a as array(*)?) as xs:boolean { return array:exists($a) }
will raise a type error (rather than returning false
) if the argument $a
is
an empty sequence, because array:exists
does not allow the argument to be
an empty sequence.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
Proposed for 4.0, see issue 229
Returns an array containing those members of the $array
for which
$predicate
returns true
.
array:filter ( |
||
$array |
as , |
|
$predicate |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Informally, the function returns an array containing those members of the input array that satisfy the supplied predicate.
More formally, the function returns the result of the expression
array:of-members(array:members($array) => fn:filter(function($m) { $predicate($m?value) })
.
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; there is no conversion
to an effective boolean value.
Expression | Result |
---|---|
array:filter( ["A", "B", 1, 2], function($x) { $x instance of xs:integer } ) |
|
array:filter( ["the cat", "sat", "on the mat"], function { count(tokenize(.)) > 1 } ) |
|
|
|
First introduced in 3.1.Functionality unchanged in 4.0, but the specification has been formalized.
Replaces any array appearing in a supplied sequence with the members of the array, recursively.
array:flatten ( |
||
$input |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 is equivalent to the following XQuery implementation (assuming static typing is not in force):
declare function flatten ($S as item()*) { for $s in $S return ( typeswitch($s) case $a as array(*) return flatten($a?*) default return $s )}
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 |
---|---|
|
|
|
|
|
|
First introduced in 3.1.Retained unchanged.
Evaluates the supplied function cumulatively on successive members of the supplied array.
array:fold-left ( |
||
$array |
as , |
|
$zero |
as , |
|
$action |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The result of the function is the value of the expression
array:members($array) => fn:fold-left($zero, function($a, $b) { $action($a, $b?value })
If the supplied array is empty, the function returns $zero
.
If the supplied array contains a single member $m
, the function returns $zero => $action($m)
.
If the supplied array contains two members $m
and $n
, the function returns
$zero => $action($m) => $action($n)
; and similarly for an input array with more than two members.
Expression | Result |
---|---|
array:fold-left( [true(), true(), false()], true(), function($x, $y) { $x and $y } ) |
(Returns true if every member of the input array has an effective boolean value of |
array:fold-left( [true(), true(), false()], false(), function($x, $y) { $x or $y } ) |
(Returns true if at least one member of the input array has an effective boolean value of |
array:fold-left( [ 1, 2, 3 ], [], function($x, $y) { [ $x, $y ] } ) |
|
First introduced in 3.1.Functionality unchanged in 4.0, but the specification has been formalized.
Evaluates the supplied function cumulatively on successive values of the supplied array.
array:fold-right ( |
||
$array |
as , |
|
$zero |
as , |
|
$action |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The result of the function is the value of the expression
array:members($array) => fn:fold-right($zero, function($a, $b) { $action($a, $b?value })
If the supplied array is empty, the function returns $zero
.
If the supplied array contains a single member $m
, the function returns $action($m, $zero)
.
If the supplied array contains two members $m
and $n
, the function returns
$action($m, $action($n, $zero))
; and similarly for an input array with more than two members.
Expression | Result |
---|---|
array:fold-right( [true(), true(), false()], true(), function($x, $y) { $x and $y } ) |
(Returns true if every member of the input array has an effective boolean value of |
array:fold-right( [true(), true(), false()], false(), function($x, $y) { $x or $y } ) |
(Returns true if at least one member of the input array has an effective boolean value of |
array:fold-right( [ 1, 2, 3 ], [], function($x, $y) { [ $x, $y ] } ) |
|
First introduced in 3.1.Functionality unchanged in 4.0, but the specification has been formalized.
Returns the last member of an array, that is $array(array:size($array))
.
array:foot ( |
||
$array |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns last member of $array
, that is the value of array:get($array, array:size($array))
.
A dynamic error occurs [err:FOAY0001] if $array
is empty.
Expression | Result |
---|---|
|
|
|
|
|
|
Proposed and accepted for 4.0, see issue 97
Returns an array whose size is the same as array:size($array)
, in which
each member is computed by applying $function
to the corresponding member of
$array
.
array:for-each ( |
||
$array |
as , |
|
$action |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Informally, the function returns an array whose members are obtained by applying
the supplied $function
to each member of the input array in turn.
More formally, the function returns the result of the expression
array:of-members(array:members($array) ! map { 'value': $action(?value) }
.
Expression | Result |
---|---|
array:for-each( [ "A", "B", 1, 2 ], function($z) { $z instance of xs:integer } ) |
|
array:for-each( [ "the cat", "sat", "on the mat" ], tokenize#1 ) |
|
array:for-each( [ [ "the", "cat" ], [ "sat" ], [ "on", "the", "mat" ] ], array:flatten#1 ) |
|
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:for-each-pair ( |
||
$array1 |
as , |
|
$array2 |
as , |
|
$action |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the result of the expression:
array:of-members(
for-each-pair(array:members($array1),
array:members($array2),
function($m, $n) {map{'value': $action($m?value, $n?value)}}))
If the arrays have different size, excess members in the longer array are ignored.
Expression | Result |
---|---|
array:for-each-pair( ["A", "B", "C"], [1, 2, 3], function($x, $y) { array { $x, $y }} ) |
|
let $array := ["A", "B", "C", "D"] return array:for-each-pair( $array, array:tail($array), concat#2 ) |
|
First introduced in 3.1.Functionality unchanged in 4.0, but the specification has been formalized.
Returns the value at the specified position in the supplied array (counting from 1).
array:get ( |
||
$array |
as , |
|
$position |
as , |
|
$fallback |
as
|
:= fn($i) { fn:error(fn:QName('', 'FOAY0001')) } |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Informally, the function returns the member at a specified position in the array.
If $position
is less than one or greater than array:size($array)
,
then the $fallback
function is called, supplying the value of $position
as the argument value; and the result of this call is returned.
The default $fallback
function raises a dynamic error. The call on fn:error
shown as the default is for illustrative purposes only; apart from the error code (err:FOAY0001
)
the details of the error (such as the error message) are ·implementation-dependent·.
More formally, the function returns the value of:
if ($position = (1 to array:size($array))) then array:members($array)[$position]?value else $fallback($position)
In the absence of a $fallback
function,
a dynamic error occurs [err:FOAY0001] if $position
is not in the range 1 to
array:size($array)
inclusive.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
Returns the first member of an array, that is $array(1)
.
array:head ( |
||
$array |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns first member of $array
,
that is the value of array:get($array, 1)
.
A dynamic error occurs [err:FOAY0001] if $array
is empty.
Expression | Result |
---|---|
|
|
|
|
|
|
First introduced in 3.1.Unchanged in 4.0.
Returns the position in an input array of members that match a supplied predicate.
array:index-where ( |
||
$array |
as , |
|
$predicate |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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
.
More formally, the function returns the result of the expression:
index-of(array:for-each($input, $predicate)?*, true())
Expression | Result |
---|---|
|
|
|
|
array:index-where( array { 1 to 10 }, function {. mod 2 = 0 } ) |
|
array:index-where( [ "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December" ], contains(?, "r") ) |
|
array:index-where( [(1, 2, 3), (4, 5, 6), (7, 8)], function($m) { count($m) = 3 } ) |
|
Approved 2022-12-13 for inclusion in 4.0 - issue #114
Returns an array containing all the members of the supplied array, with one additional member at a specified position.
array:insert-before ( |
||
$array |
as , |
|
$position |
as , |
|
$member |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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.
More formally, except in error cases, the result is the value of the expression
array:of-members(array:members($array) => fn:insert-before($position, map{'value':$member}))
.
A dynamic error occurs [err:FOAY0001] if $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 |
---|---|
array:insert-before( ["a", "b", "c", "d"], 3, ("x", "y") ) |
|
array:insert-before( ["a", "b", "c", "d"], 5, ("x", "y") ) |
|
array:insert-before( ["a", "b", "c", "d"], 3, ["x", "y"] ) |
|
First introduced in 3.1.Functionality unchanged in 4.0, but the specification has been formalized.
Concatenates the contents of several arrays into a single array.
array:join ( |
||
$arrays |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Informally, the function concatenates the members of several arrays into a single array.
More formally, the function returns the result of
array:of-members($arrays ! array:members(.))
.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
First introduced in 3.1.Functionality unchanged in 4.0, but the specification has been formalized.
Delivers the contents of an array as a sequence of value records.
array:members ( |
||
$array |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The members of the array are delivered as a sequence of value records.
A value record is an item that encapsulates an arbitrary sequence $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
.
This function is the inverse of array:of-members
.
Expression | Result |
---|---|
|
|
|
|
array:members([(1,1), (2,4), (3,9), (4,16), (5,25)]) ! sum(?value) |
|
let $array := [ "any array" ] return deep-equal( $array, array:of-members(array:members($array)) ) |
|
Proposed for 4.0, see issues 29, 113, 314.
Constructs an array from the contents of a sequence of value records.
array:of-members ( |
||
$input |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The input items must be value records. A value record is an item that encapsulates
an arbitrary sequence $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
.
This function is the inverse of array:members
.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
Proposed for 4.0, see issues 29, 113, 314.
Returns an array containing all the members of a supplied array, except for one member which is replaced with a new value.
array:put ( |
||
$array |
as , |
|
$position |
as , |
|
$member |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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
.
More formally, the result is the value of the expression
$array => array:remove($position) => array:insert-before($position, $member)
.
A dynamic error occurs [err:FOAY0001] if $position
is not in the range 1 to
array:size($array)
inclusive.
This error will always occur if $array
is empty.
Expression | Result |
---|---|
|
|
|
|
|
|
First introduced in 3.1.Unchanged in 4.0.
Returns an array containing all the members of the supplied array, except for the members at specified positions.
array:remove ( |
||
$array |
as , |
|
$positions |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Informally, the function returns an array of size array:size($array) - fn:count(fn:distinct-values($positions))
containing all members from $array
except the members whose position (counting from 1) is present in the sequence $positions
.
The order of the remaining members is preserved.
More formally, the result of the function, except in error cases, is given by the expression
array:of-members(array:members($array) => fn:remove($positions))
.
A dynamic error is raised [err:FOAY0001] if any integer in $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 |
---|---|
|
|
|
|
|
|
|
|
|
|
First introduced in 3.1.Functionality unchanged in 4.0, but the specification has been formalized.
Returns an array containing all the members of a supplied array, except for one member which is replaced with a new value, the new value being computed from the previous value.
array:replace ( |
||
$array |
as , |
|
$position |
as , |
|
$action |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 the result of applying
the $action
function to the original value in that position.
More formally, the result is the value of the expression
$array => array:remove($position) => array:insert-before($position, $action($array($position)))
.
A dynamic error occurs [err:FOAY0001]
if $position
is not in the range 1 to
array:size($array)
inclusive.
This error will always occur if $array
is empty.
Expression | Result |
---|---|
|
|
|
|
|
|
First introduced in 4.0.
Returns an array containing all the members of a supplied array, but in reverse order.
array:reverse ( |
||
$array |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the result of the expression:
array:of-members(array:members($array) => fn:reverse())
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
First introduced in 3.1.Functionality unchanged in 4.0, but the specification has been formalized.
Returns the number of members in the supplied array.
array:size ( |
||
$array |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Informally, the function returns the number of members in the array.
More formally, the function returns the value of fn:count(array:members($array))
.
Note that because an array is an item, the fn:count
function
when applied to an array always returns 1
.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
Returns an array containing selected members of a supplied input array based on their position.
array:slice ( |
||
$array |
as , |
|
$start |
as
|
:= () , |
$end |
as
|
:= () , |
$step |
as
|
:= () |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Returns the value of array:of-members(array:members($array) => fn:slice($start, $end, $step))
The function is formally defined by converting the array to a sequence, applying
fn:slice
to this sequence, and then converting the resulting sequence
back to an array.
Note that unlike other operations on arrays, there are no out-of-bounds errors for inappropriate
values of $start
, $end
, or $step
.
Expression | Result |
---|---|
let $in := ['a', 'b', 'c', 'd', 'e'] |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Proposed for 4.0; not yet reviewed?.
Returns an array containing all the members of the supplied array, sorted according to the value of a sort key supplied as a function.
array:sort ( |
||
$array |
as , |
|
$collation |
as
|
:= fn:default-collation() , |
$key |
as
|
:= fn:data#1 |
) as
|
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
The three-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Calling the single-argument version of the function is equivalent to calling the two-argument form
with default-collation()
as the second argument: that is, it sorts the members of an array according
to the typed value of the items, using the default collation to compare strings.
Calling the two-argument version of the function is equivalent to calling the three-argument form
with fn:data#1
as the third argument: that is, it sorts the members of an array according
to the typed value of the items, using a specified collation to compare strings.
In the case of both array:sort#2
and array:sort#3
, supplying an empty
sequence as the second argument is equivalent to supplying fn:default-collation()
. For more
information on collations see 5.3.5 Choosing a collation.
The result of array:sort#3
is the value of the expression
array:of-members(array:members($array) => sort($collation, function($x) { $key($x?value) }))
If the set of computed sort keys contains values that are not comparable using the le
operator then the sort
operation will fail with a dynamic error.
Expression | Result |
---|---|
|
|
|
|
|
|
To sort an array of strings |
|
let $SWEDISH := "http://www.w3.org/2013/collation/UCA?lang=se" return array:sort($in, $SWEDISH) |
|
To sort an array of maps representing employees, using last name as the major sort key and first name as the minor sort key, with the default collation: |
|
array:sort($employees, (), function($emp) {$emp?name?last, $emp?name?first}) |
First introduced in 3.1.Functionality unchanged in 4.0, but the specification has been formalized.
Delivers the contents of an array as a sequence of singleton arrays.
array:split ( |
||
$array |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The members of the array are delivered as a sequence of arrays. Each returned array encapsulates the value of a single array member.
The function call array:split($array)
produces the same result as the
expression for member $m in $array return [ $m ]
.
This function is the inverse of array:join
.
Expression | Result |
---|---|
|
|
|
|
|
|
array:split( array { 1 to 5 } ) |
|
array:split( [ (1,1), (2,4), (3,9), (4,16), (5,25) ] ) ! sum(.) |
|
let $array := [ "any array" ] return deep-equal( $array, array:join(array:split($array)) ) |
|
Returns an array containing all members from a supplied array starting at a supplied position, up to a specified length.
array:subarray ( |
||
$array |
as , |
|
$start |
as , |
|
$length |
as
|
:= () |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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
.
Setting the third argument to the empty sequence has the same effect as omitting the argument.
Except in error cases, the result of the three-argument version of the function is the
value of the expression
array:of-members(array:members($array) => fn:subsequence($start, $length))
.
A dynamic error is raised [err:FOAY0001] if $start
is less than one
or greater than array:size($array) + 1
.
For the three-argument version of the function:
A dynamic error is raised [err:FOAY0002]
if $length
is less than zero.
A dynamic error is raised [err:FOAY0001]
if $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 an empty array.
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
First introduced in 3.1.Functionality unchanged in 4.0, but the specification has been formalized.
Returns an array containing all members except the first from a supplied array.
array:tail ( |
||
$array |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns an array containing all members of the supplied array except the first,
that is array:remove($array, 1)
.
A dynamic error occurs [err:FOAY0001] if $array
is empty.
If the supplied array contains exactly one member, the result will be an empty array.
Expression | Result |
---|---|
|
|
|
|
First introduced in 3.1.Unchanged in 4.0.
Returns an array containing all members except the last from a supplied array.
array:trunk ( |
||
$array |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns an array containing all members of the supplied array except the last,
that is array:remove($array, array:size($array))
.
A dynamic error occurs [err:FOAY0001] if $array
is empty.
If the supplied array contains exactly one member, the result will be an empty array.
Expression | Result |
---|---|
|
|
|
|
Proposed and accepted for 4.0, see issue 97
Returns a sequence with the members of an array.
array:values ( |
||
$array |
as
|
|
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function concatenates the members of $array
and returns them as
a sequence. The values are returned in their original order.
Arrays contained within members are returned unchanged.
The effect of the function is equivalent to $array?*
.
Expression | Result |
---|---|
|
|
|
|
This section is non-normative.
The XPath language provides explicit syntax for certain operations on arrays. These constructs can also be specified in terms of functions primitives:
array { $sequence }
constructs an array whose members
are the items in $sequence
. Every member of this array will
be a singleton item. This can be defined as
array:join($sequence ! array { . })
.
[E1, E2, E3, ..., En]
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:join(([ E1 ], [ E2 ], ... [ En ])).
The lookup expression $array?*
is equivalent to
array:split($array)?*
.
The lookup expression $array?$N
, where $N
is an integer within the bounds of the array, is equivalent to
array:split($array)[$N]?*
.
Similarly, applying the array as a function, $array($N)
,
is also equivalent to
array:split($array)[$N]?*
array { $sequence }
constructs an array whose members
are the items in $sequence
. Every member of this array will
be a singleton item. This can be defined as
array:of-members($sequence ! map { 'value': . })
.
[E1, E2, E3, ..., En]
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:of-members((map { 'value': E1 }, map { 'value': E2 },
map { 'value': E3 }, ... map { 'value': En })).
The lookup expression $array?*
is equivalent to
array:members($array) ! ?value
.
The lookup expression $array?$N
, where $N
is an integer within the bounds of the array, is equivalent to
array:members($array)[$N]?value
.
Similarly, applying the array as a function, $array($N)
,
is also equivalent to
array:members($array)[$N]?value
This section describes constructor functions corresponding to simple types defined in [XML Schema Part 2: Datatypes Second Edition]. Constructor functions are used to convert a supplied value to a given type. They always take a single argument, and the name of the function is the same as the name of the target type.
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 [XML Schema Part 2: Datatypes Second Edition],
except xs:anyAtomicType
and xs:NOTATION
, has an
associated constructor function. The type xs:untypedAtomic
, defined
in Section
2.7 Schema Information
DM31 and the two derived types
xs:yearMonthDuration
and xs:dayTimeDuration
defined
in Section
2.7 Schema Information
DM31 also have associated constructor functions.
Implementations may additionally provide
a constructor functions for the new datatype xs:dateTimeStamp
introduced in [Schema 1.1 Part 2].
A constructor function is not defined for xs:anyAtomicType
as there are no atomic values 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 [XML Schema Part 2: Datatypes Second Edition]. If the static context (See Section
2.1.1 Static Context
XP31) contains a type derived from
xs:NOTATION
then a constructor function is defined for it.
See 20.5 Constructor functions for user-defined types.
The form of the constructor function for an atomic type eg:TYPE is:
eg:TYPE ( |
||
$value |
as
|
:= . |
) as
|
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 [XML Schema Part 2: Datatypes Second Edition] is:
xs:unsignedInt ( |
||
$arg |
as
|
:= . |
) as
|
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. The standard features described in
Section
2.4.2 Atomization
XP31 would atomize the node to
extract its typed value and then call the constructor with that value. If the
value passed to a constructor 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 this
specification, then an
dynamic error is raised [err:FORG0001].
The semantics of the constructor function
xs:TYPE(arg)
are identical to the semantics of
arg
cast as xs:TYPE?
. See 21 Casting.
If the argument to a constructor function is a literal, the result of the function may be evaluated statically; if an error is found during such evaluation, it may be reported as a static error.
Special rules apply to constructor functions for xs:QName
and types derived from xs:QName
and xs:NOTATION
. See
20.2 Constructor functions for xs:QName and xs:NOTATION.
The argument is optional, and defaults to the context item (which will be atomized if necessary).
The following constructor functions for the built-in atomic types are supported:
xs:string ( |
||
$value |
as
|
:= . |
) as
|
xs:boolean ( |
||
$value |
as
|
:= . |
) as
|
xs:decimal ( |
||
$value |
as
|
:= . |
) as
|
xs:float ( |
||
$value |
as
|
:= . |
) as
|
Implementations should return negative zero for xs:float("-0.0E0")
.
But because [XML Schema Part 2: Datatypes Second Edition] does not distinguish between the values positive zero and negative zero,
implementations may return positive zero in this case.
xs:double ( |
||
$value |
as
|
:= . |
) as
|
Implementations should return negative zero for xs:double("-0.0E0")
.
But because [XML Schema Part 2: Datatypes Second Edition] does not distinguish between the values positive zero and negative zero,
implementations may return positive zero in this case.
xs:duration ( |
||
$value |
as
|
:= . |
) as
|
xs:dateTime ( |
||
$value |
as
|
:= . |
) as
|
xs:time ( |
||
$value |
as
|
:= . |
) as
|
xs:date ( |
||
$value |
as
|
:= . |
) as
|
xs:gYearMonth ( |
||
$value |
as
|
:= . |
) as
|
xs:gYear ( |
||
$value |
as
|
:= . |
) as
|
xs:gMonthDay ( |
||
$value |
as
|
:= . |
) as
|
xs:gDay ( |
||
$value |
as
|
:= . |
) as
|
xs:gMonth ( |
||
$value |
as
|
:= . |
) as
|
xs:hexBinary ( |
||
$value |
as
|
:= . |
) as
|
xs:base64Binary ( |
||
$value |
as
|
:= . |
) as
|
xs:anyURI ( |
||
$value |
as
|
:= . |
) as
|
xs:QName ( |
||
$value |
as
|
:= . |
) as
|
See 20.2 Constructor functions for xs:QName and xs:NOTATION for special rules.
xs:normalizedString ( |
||
$value |
as
|
:= . |
) as
|
xs:token ( |
||
$value |
as
|
:= . |
) as
|
xs:language ( |
||
$value |
as
|
:= . |
) as
|
xs:NMTOKEN ( |
||
$value |
as
|
:= . |
) as
|
xs:Name ( |
||
$value |
as
|
:= . |
) as
|
xs:NCName ( |
||
$value |
as
|
:= . |
) as
|
xs:ID ( |
||
$value |
as
|
:= . |
) as
|
xs:IDREF ( |
||
$value |
as
|
:= . |
) as
|
xs:ENTITY ( |
||
$value |
as
|
:= . |
) as
|
See 21.1.9 Casting to xs:ENTITY for rules related to constructing values of type xs:ENTITY
and types derived from it.
xs:integer ( |
||
$value |
as
|
:= . |
) as
|
xs:nonPositiveInteger ( |
||
$value |
as
|
:= . |
) as
|
xs:negativeInteger ( |
||
$value |
as
|
:= . |
) as
|
xs:long ( |
||
$value |
as
|
:= . |
) as
|
xs:int ( |
||
$value |
as
|
:= . |
) as
|
xs:short ( |
||
$value |
as
|
:= . |
) as
|
xs:byte ( |
||
$value |
as
|
:= . |
) as
|
xs:nonNegativeInteger ( |
||
$value |
as
|
:= . |
) as
|
xs:unsignedLong ( |
||
$value |
as
|
:= . |
) as
|
xs:unsignedInt ( |
||
$value |
as
|
:= . |
) as
|
xs:unsignedShort ( |
||
$value |
as
|
:= . |
) as
|
xs:unsignedByte ( |
||
$value |
as
|
:= . |
) as
|
xs:positiveInteger ( |
||
$value |
as
|
:= . |
) as
|
xs:yearMonthDuration ( |
||
$value |
as
|
:= . |
) as
|
xs:dayTimeDuration ( |
||
$value |
as
|
:= . |
) as
|
xs:untypedAtomic ( |
||
$value |
as
|
:= . |
) as
|
xs:dateTimeStamp ( |
||
$value |
as
|
:= . |
) as
|
Available only if the implementation supports XSD 1.1.
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 Section
2.1.1 Static Context
XP31. A dynamic error is raised [err:FONS0004]
if the prefix is not bound in the static context. As described in
Section
2.1 Terminology
DM31, the supplied prefix is retained as part of the
expanded-QName value.
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 fn:function-lookup
function, the relevant namespace bindings are those from the static context of the call on fn:function-lookup
.
Note:
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 [XML Schema Part 2: Datatypes Second Edition],
namely xs:NMTOKENS
, xs:ENTITIES
, and xs:IDREFS
, has an
associated constructor function.
The function signatures are as follows:
xs:NMTOKENS ( |
||
$value |
as
|
:= . |
) as
|
xs:ENTITIES ( |
||
$value |
as
|
:= . |
) as
|
xs:IDREFS ( |
||
$value |
as
|
:= . |
) as
|
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 an empty sequence, the result is an empty sequence.
Note:
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 [XQuery and XPath Data Model (XDM) 3.1]. The function signature is:
xs:numeric ( |
||
$value |
as
|
:= . |
) as
|
The semantics are determined by the rules in 21.3.5 Casting to union types. These rules have the effect that:
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 [err:FORG0001] occurs;
Note:
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 fn:abs
and fn:round
are declared to expect an instance
of 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 value
(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 [err:FORG0001] occurs.
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:
xs:error ( |
||
$value |
as
|
:= . |
) as
|
The semantics are equivalent to casting to the corresponding union type (see 21.3.5 Casting to union types).
Note:
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 an empty
sequence, in which case the result is also an empty sequence.
For every named user-defined simple type in the static context (See Section 2.1.1 Static Context XP31), there is a constructor function whose name is the same as the name of the type.
For named atomic types, the rules
are the same as the rules for constructing built-in derived atomic types defined in 20.1 Constructor functions for XML Schema built-in atomic types. For a named atomic type 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 21.3.1 Casting to derived types..
For named union types, the rules
follow the same principles as the rules for constructing built-in union types defined in 20.4 Constructor functions for XML Schema built-in union types. For a named union type 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 21.3.5 Casting to union types.
For named list types, the rules
follow the same principles as the rules for constructing built-in list types defined in 20.3 Constructor functions for XML Schema built-in list types. For a named list type 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 21.3.6 Casting to list types.
Constructor functions are available both for named types defined in an imported schema (that is,
named simple types in the in-scope schema typesXP40),
and for types defined by means of item type aliasesXP40.
Specifically, named enumeration types follow the same rules as schema types derived by
restricting 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 20.2 Constructor functions for xs:QName and xs:NOTATION.
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:
eg:hatSize ( |
||
$value |
as
|
|
) as
|
The resulting function may be used in an expression such as eg:hatSize("10½")
.
Note:
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.
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, with identical semantics and different syntax. The name of the
constructor function is the same as the name of the built-in [XML Schema Part 2: Datatypes Second Edition]
datatype or the datatype defined in Section
2.7 Schema Information
DM31
of [XQuery and XPath Data Model (XDM) 3.1] (see 20.1 Constructor functions for XML Schema built-in atomic types) or the user-derived datatype
(see 20.5 Constructor functions for user-defined types) that is the
target for the conversion, and the semantics are exactly the same as for a cast
expression; for example,
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 Section 3.14.2 Cast XP31. If the type name allows the empty sequence and the expression to be cast is the empty sequence, the empty sequence is returned. If the type name does not allow the empty sequence and the expression to be cast is the empty sequence, a type error is raised [err:XPTY0004]XP.
Where the argument to a cast is a literal, the result of the function may be evaluated statically; if an error is encountered during such evaluation, it may be reported as a static error.
The general rules for casting from primitive types to primitive types are defined in
21.1 Casting from primitive types to primitive types, and subsections describe the rules
for specific target types.
The general rules for casting from xs:string
(and xs:untypedAtomic
)
follow in 21.2 Casting from xs:string and xs:untypedAtomic.
Casting to non-primitive types, including atomic types derived by resctriction,
union types, and list types, is described in 21.3 Casting involving non-primitive types.
Casting from derived types is defined in 21.3.2 Casting from derived types to parent types,
21.3.3 Casting within a branch of the type hierarchy and 21.3.4 Casting across the type hierarchy.
[Definition] Throughout
this section (21 Casting), the term primitive type means either one of
the 19 primitive types defined in [XML Schema Part 2: Datatypes Second Edition], or one of the types
xs:untypedAtomic
, xs:integer
, xs:yearMonthDuration
and xs:dayTimeDuration
; and where the text refers to types derived from a particular
primitive type T, the reference is to types for which T is the nearest
ancestor-or-self primitive type in the type hierarchy.
When casting from xs:string
or xs:untypedAtomic
the semantics in 21.2 Casting from xs:string and xs:untypedAtomic apply, regardless of target type.
This section defines casting between ·primitive types·
(specifically, the 19 primitive types defined in [XML Schema Part 2: Datatypes Second Edition] as well as xs:untypedAtomic
,
xs:integer
and the two derived types of
xs:duration
: xs:yearMonthDuration
and xs:dayTimeDuration
which are treated as primitive types in this section. 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.
In this table, there is a
row for each ·primitive type· acting as the source of the conversion and
there is a column for each ·primitive type· acting as the target of the conversion. The
intersections of rows and columns contain one of three characters:
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;
and 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.
[XML Schema Part 2: Datatypes Second Edition] defines 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 [err:XPST0080]XP.
However, casting from one subtype of 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 value of type xs:untypedAtomic
. There are no atomic values with the
type annotation xs:anySimpleType
at runtime.
Casting to
xs:anySimpleType
is not permitted and raises a static error:
[err:XPST0080]XP.
Similarly, casting is not supported to or from xs:anyAtomicType
and will raise
a static error: [err:XPST0080]XP. There are no atomic values
with the type annotation xs:anyAtomicType
at runtime, although this can be a
statically inferred type.
If casting is attempted from an ST to a TT for which casting is not supported, as defined in the table below, a type error is raised [err:XPTY0004]XP.
In the following table, the columns and rows are identified by short codes that identify simple types as follows:
uA = xs:untypedAtomic
aURI = xs:anyURI
b64 = xs:base64Binary
bool = xs:boolean
dat = xs:date
gDay = xs:gDay
dbl = xs:double
dec = xs:decimal
dT = xs:dateTime
dTD = xs:dayTimeDuration
dur = xs:duration
flt = xs:float
hxB = xs:hexBinary
gMD = xs:gMonthDay
gMon = xs:gMonth
int = xs:integer
NOT = xs:NOTATION
QN = xs:QName
str = xs:string
tim = xs:time
gYM = xs:gYearMonth
yMD = xs:yearMonthDuration
gYr = xs:gYear
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 | uA | str | flt | dbl | dec | int | dur | yMD | dTD | dT | tim | dat | gYM | gYr | gMD | gDay | gMon | bool | b64 | hxB | aURI | QN | NOT |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
uA | Y | Y | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M |
str | Y | Y | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M |
flt | Y | Y | Y | Y | M | M | N | N | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N |
dbl | Y | Y | Y | Y | M | M | N | N | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N |
dec | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N |
int | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N |
dur | Y | Y | N | N | N | N | Y | Y | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N |
yMD | Y | Y | N | N | N | N | Y | Y | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N |
dTD | Y | Y | N | N | N | N | Y | Y | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N |
dT | Y | Y | N | N | N | N | N | N | N | Y | Y | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N |
tim | Y | Y | N | N | N | N | N | N | N | N | Y | N | N | N | N | N | N | N | N | N | N | N | N |
dat | Y | Y | N | N | N | N | N | N | N | Y | N | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N |
gYM | Y | Y | N | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N | N | N | N | N | N |
gYr | Y | Y | N | N | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N | N | N | N | N |
gMD | Y | Y | N | N | N | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N | N | N | N |
gDay | Y | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N | N | N |
gMon | Y | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N | N |
bool | Y | Y | Y | Y | Y | Y | N | N | N | N | N | N | N | N | N | N | N | Y | N | N | N | N | N |
b64 | Y | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | Y | N | N | N |
hxB | Y | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | Y | N | N | N |
aURI | Y | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | N | N |
QN | Y | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | M |
NOT | Y | Y | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | Y | M |
Casting is permitted from any ·primitive type· to the
·primitive types·
xs:string
and xs:untypedAtomic
.
When a value of any simple type is cast as xs:string
, the
derivation of the xs:string
value TV depends on
the ST and on the SV, as follows.
If ST is xs:string
or a type derived from
xs:string
, TV is SV.
If ST is xs:anyURI
, the type conversion is
performed without escaping any characters.
If ST is 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.
If ST is a numeric type, the following rules apply:
If ST is xs:integer
,
TV is the canonical lexical representation of
SV as defined in [XML Schema Part 2: Datatypes Second Edition]. There
is no decimal point.
If ST is xs:decimal
, then:
If SV is in the value space of
xs:integer
, that is, if there are no
significant digits after the decimal point, then the
value is converted from an xs:decimal
to an xs:integer
and the resulting
xs:integer
is converted to an
xs:string
using the rule above.
Otherwise, the canonical lexical representation of SV is returned, as defined in [XML Schema Part 2: Datatypes Second Edition].
If ST is 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 21.2 Casting from xs:string and xs:untypedAtomic produces
a value that is equal to SV, or is 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.
Note:
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.
If ST is xs:dateTime
, xs:date
or xs:time
, TV is the local value.
The components of TV are individually cast to xs:string
using the functions
described in [casting-to-datetimes]
and the results are concatenated together. The year
component is
cast to xs:string
using eg:convertYearToString
.
The month
, day
, hour
and minute
components are cast to xs:string
using eg:convertTo2CharString
.
The second
component is cast to xs:string
using
eg:convertSecondsToString
. The timezone component, if present, is
cast to xs:string
using eg:convertTZtoString
.
Note that the hours component of the resulting string
will never be "24"
. Midnight is always represented as "00:00:00"
.
If ST is xs:yearMonthDuration
or xs:dayTimeDuration
, TV is the
canonical representation of SV as defined in [Schema 1.1 Part 2].
If ST is xs:duration
then let SYM be
SV
cast as xs:yearMonthDuration
, and let SDT be
SV
cast as xs:dayTimeDuration
; Now, let the next intermediate value, TYM,
be
SYM
cast as
TT
, and let TDT be
SDT
cast as
TT
. If TYM is "P0M"
, then TV is
TDT. Otherwise, TYM and TDT are merged according to the following rules:
If TDT is "PT0S"
, then TV is TYM.
Otherwise, TV is the concatenation of all the characters in TYM and all the characters except the first "P" and the optional negative sign in TDT.
In all other cases, TV is the [XML Schema Part 2: Datatypes Second Edition] canonical representation of SV. For datatypes that do not have a canonical lexical representation defined an ·implementation-dependent· canonical representation may be used.
To cast as xs:untypedAtomic
the value is cast as
xs:string
, as described above, and the type annotation changed
to xs:untypedAtomic
.
Note:
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
.
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:integer
s whose value range is defined in
[XML Schema Part 2: Datatypes Second Edition], and the following rules apply:
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
21.2 Casting from xs:string and xs:untypedAtomic.
Note:
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.
Note:
Implementations should return negative zero for xs:float("-0.0E0")
.
But because [XML Schema Part 2: Datatypes Second Edition] does not distinguish between the values positive zero and negative zero.
Implementations may return positive zero in this case.
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 [XML Schema Part 2: Datatypes Second Edition], and
TV is the 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
21.2 Casting from xs:string and xs:untypedAtomic.
Note:
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.
Note:
Implementations should return negative zero for xs:double("-0.0E0")
.
But because [XML Schema Part 2: Datatypes Second Edition] does not distinguish between the values positive zero and negative zero.
Implementations may return positive zero in this case.
When a value of any simple type is cast as xs:decimal
, the
xs:decimal
value TV is derived from
ST and SV as follows:
If ST is xs:decimal
,
xs:integer
or a type derived from them, then
TV is SV, converted to an
xs:decimal
value if need be, and the conversion is complete.
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
[XML Schema Part 2: Datatypes Second Edition] for ·implementation-defined· limits on
numeric values) a dynamic error is raised [err:FOCA0001]. If SV is one of the special
xs:float
or xs:double
values
NaN
, INF
, or -INF
, a dynamic
error is raised [err:FOCA0002].
If ST is xs:boolean
, SV is
converted to 1.0
if SV is
1
or true
and to 0.0
if
SV is 0
or false
and the
conversion is complete.
If ST is xs:untypedAtomic
or xs:string
, see
21.2 Casting from xs:string and xs:untypedAtomic.
When a value of any simple type is cast as xs:integer
, the
xs:integer
value TV is derived from
ST and SV as follows:
If ST is xs:integer
, or a type derived
from xs:integer
, then TV is
SV, converted to an xs:integer
value
if need be, and the conversion is complete.
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
and -17.89
returns
-17
. Casting 3.124E1
returns 31
. If SV is too large to be
accommodated as an integer, (see [XML Schema Part 2: Datatypes Second Edition] for
·implementation-defined· limits on numeric values) a
dynamic error is
raised [err:FOCA0003]. If SV is
one of the special xs:float
or
xs:double
values NaN
,
INF
, or -INF
, a dynamic error is raised
[err:FOCA0002].
If ST is xs:boolean
, SV is
converted to 1
if SV is 1
or true
and to 0
if SV is
0
or false
and the conversion is complete.
If ST is xs:untypedAtomic
or xs:string
, see
21.2 Casting from xs:string and xs:untypedAtomic.
When a value of type xs:untypedAtomic
, xs:string
,
a type derived from xs:string
,
xs:yearMonthDuration
or xs:dayTimeDuration
is
cast as xs:duration
, xs:yearMonthDuration
or
xs:dayTimeDuration
, TV is derived from
ST and SV as follows:
If ST is the same as TT, then TV is SV.
If ST is xs:duration
, or a type derived
from xs:duration
, but not
xs:dayTimeDuration
or a type derived from
xs:dayTimeDuration
, and TT is
xs:yearMonthDuration
, then TV is derived
from SV by removing the day, hour, minute and second
components from SV.
If ST is xs:duration
, or a type derived
from duration
, but not
xs:yearMonthDuration
or a type derived from
xs:yearMonthDuration
, and TT is
xs:dayTimeDuration
, then TV is derived
from SV by removing the year and month components from SV.
If ST is xs:yearMonthDuration
or xs:dayTimeDuration
, and TT is
xs:duration
, then TV is derived from
SV as defined in 21.3.2 Casting from derived types to parent types.
If ST is xs:yearMonthDuration
and TT is
xs:dayTimeDuration
, the cast is permitted and
returns a xs:dayTimeDuration
with value
0.0
seconds.
If ST is xs:dayTimeDuration
and TT is
xs:yearMonthDuration
, the cast is permitted and
returns a xs:yearMonthDuration
with value
0
months.
If ST is xs:untypedAtomic
or xs:string
, see
21.2 Casting from xs:string and xs:untypedAtomic.
Note that casting from xs:duration
to
xs:yearMonthDuration
or xs:dayTimeDuration
loses
information. To avoid this, users can cast the xs:duration
value to both an xs:yearMonthDuration
and an
xs:dayTimeDuration
and work with both values.
In several situations, casting to date and time types requires the extraction
of a component from SV or from the result of
fn:current-dateTime
and converting it to an
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.
declare function eg:convertYearToString($year as xs:integer) as xs:string { let $plusMinus := if ($year >= 0) then "" else "-" let $yearString := abs($year) cast as xs:string let $length := string-length($yearString) return if ($length = 1) then concat($plusMinus, "000", $yearString) else if ($length = 2) then concat($plusMinus, "00", $yearString) else if ($length = 3) then concat($plusMinus, "0", $yearString) else concat($plusMinus, $yearString) }
declare function eg:convertTo2CharString($value as xs:integer) as xs:string { let $string := $value cast as xs:string return if (string-length($string) = 1) then concat("0", $string) else $string }
declare function eg:convertSecondsToString($seconds as xs:decimal) as xs:string { let $string := $seconds cast as xs:string let $intLength := string-length(($seconds cast as xs:integer) cast as xs:string) return if ($intLength = 1) then concat("0", $string) else $string }
declare function eg:convertTZtoString($tz as xs:dayTimeDuration?) as xs:string { if (empty($tz)) then "" else if ($tz eq xs:dayTimeDuration('PT0S')) then "Z" else let $tzh := hours-from-duration($tz) let $tzm := minutes-from-duration($tz) let $plusMinus := if ($tzh >= 0) then "+" else "-" let $tzhString := eg:convertTo2CharString(abs($tzh)) let $tzmString := eg:convertTo2CharString(abs($tzm)) return concat($plusMinus, $tzhString, ":", $tzmString) }
Conversion from ·primitive types· to date and time types follows the rules below.
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
SYR be eg:convertYearToString( year-from-date(
SV
))
, let SMO be
eg:convertTo2CharString( month-from-date(
SV
))
, let SDA be
eg:convertTo2CharString( day-from-date(
SV
))
and let STZ be
eg:convertTZtoString( timezone-from-date(
SV
))
; TV is xs:dateTime( concat(
SYR
, '-',
SMO
, '-',
SDA
, 'T00:00:00 '
, STZ
) )
.
If ST is xs:untypedAtomic
or
xs:string
, see
21.2 Casting from xs:string and xs:untypedAtomic.
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
21.2 Casting from xs:string and xs:untypedAtomic.
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
SYR be eg:convertYearToString( year-from-dateTime(
SV
))
, let SMO be
eg:convertTo2CharString( month-from-dateTime(
SV
))
, let SDA be
eg:convertTo2CharString( day-from-dateTime(
SV
))
and let STZ be eg:convertTZtoString(timezone-from-dateTime(
SV
))
; TV is xs:date( concat(
SYR
, '-',
SMO
, '-',
SDA, STZ
) )
.
If ST is xs:untypedAtomic
or xs:string
, see
21.2 Casting from xs:string and xs:untypedAtomic.
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
SYR be eg:convertYearToString( year-from-dateTime(
SV
))
, let SMO be
eg:convertTo2CharString( month-from-dateTime(
SV
))
and let STZ be
eg:convertTZtoString( timezone-from-dateTime(
SV
))
; TV is xs:gYearMonth( concat(
SYR
, '-',
SMO, STZ
) )
.
If ST is xs:date
, then let
SYR be eg:convertYearToString( year-from-date(
SV
))
, let SMO be
eg:convertTo2CharString( month-from-date(
SV
))
and let STZ be
eg:convertTZtoString( timezone-from-date(
SV
))
; TV is xs:gYearMonth( concat(
SYR
, '-',
SMO, STZ
) )
.
If ST is xs:untypedAtomic
or xs:string
, see
21.2 Casting from xs:string and xs:untypedAtomic.
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
SYR be eg:convertYearToString( year-from-dateTime(
SV
))
and let STZ be
eg:convertTZtoString( timezone-from-dateTime(
SV
))
; TV is xs:gYear(concat(
SYR, STZ
))
.
If ST is xs:date
, let
SYR be eg:convertYearToString( year-from-date(
SV
))
; and let STZ be
eg:convertTZtoString( timezone-from-date(
SV
))
; TV is xs:gYear(concat(
SYR, STZ
))
.
If ST is xs:untypedAtomic
or xs:string
, see
21.2 Casting from xs:string and xs:untypedAtomic.
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
SMO be eg:convertTo2CharString( month-from-dateTime(
SV
))
, let SDA be
eg:convertTo2CharString( day-from-dateTime(
SV
))
and let STZ be
eg:convertTZtoString( timezone-from-dateTime(
SV
))
; TV is xs:gYearMonth( concat(
'--',
SMO
'-',
SDA, STZ
) )
.
If ST is xs:date
, then let
SMO be eg:convertTo2CharString( month-from-date(
SV
))
, let SDA be
eg:convertTo2CharString( day-from-date(
SV
))
and let STZ be
eg:convertTZtoString( timezone-from-date(
SV
))
; TV is xs:gYearMonth( concat(
'--',
SMO
, '-',
SDA, STZ
) )
.
If ST is xs:untypedAtomic
or xs:string
, see
21.2 Casting from xs:string and xs:untypedAtomic.
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
SDA be eg:convertTo2CharString( day-from-dateTime(
SV
))
and let STZ be
eg:convertTZtoString( timezone-from-dateTime(
SV
))
; TV is xs:gDay(
concat( '---'
, SDA, STZ
))
.
If ST is xs:date
, then let
SDA be eg:convertTo2CharString( day-from-date(
SV
))
and let STZ be
eg:convertTZtoString( timezone-from-date(
SV
))
; TV is xs:gDay(
concat( '---'
, SDA, STZ
))
.
If ST is xs:untypedAtomic
or xs:string
, see
21.2 Casting from xs:string and xs:untypedAtomic.
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
SMO be eg:convertTo2CharString( month-from-dateTime(
SV
))
and let STZ be
eg:convertTZtoString( timezone-from-dateTime(
SV
))
; TV is xs:gMonth(
concat( '--'
, SMO, STZ
))
.
If ST is xs:date
, then let
SMO be eg:convertTo2CharString( month-from-date(
SV
))
and let STZ be
eg:convertTZtoString( timezone-from-date(
SV
))
; TV is xs:gMonth(
concat( '--'
, SMO, STZ
))
.
If ST is xs:untypedAtomic
or xs:string
, see
21.2 Casting from xs:string and xs:untypedAtomic.
When a value of any ·primitive type· is cast as xs:boolean
, the
xs:boolean
value TV is derived from
ST and SV as follows:
If ST is xs:boolean
, then TV
is SV.
If ST is xs:float
, xs:double
,
xs:decimal
or xs:integer
and
SV is 0
, +0
, -0
,
0.0
, 0.0E0
or NaN
, then
TV is false
.
If ST is xs:float
, xs:double
,
xs:decimal
or xs:integer
and
SV is not one of the above values, then TV
is true
.
If ST is xs:untypedAtomic
or xs:string
, see
21.2 Casting from xs:string and xs:untypedAtomic.
Values 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 [XML Schema Part 2: Datatypes Second Edition] semantics.
Casting to xs:anyURI
is supported only from the same type,
xs:untypedAtomic
or xs:string
.
When a value of any ·primitive type· is cast as 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
21.2 Casting from xs:string and xs:untypedAtomic.
Casting from xs:string
or xs:untypedAtomic
to
xs:QName
or xs:NOTATION
is described in
21.2 Casting from xs:string and xs:untypedAtomic.
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.
Note:
See 20.2 Constructor functions for xs:QName and xs:NOTATION for a discussion of how the combination of atomization and casting might not produce the desired effect.
[XML Schema Part 2: Datatypes Second Edition] says that “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,
[XSL Transformations (XSLT) Version 4.0] and [XQuery 4.1: An XML Query Language] do not check that constructed values of type 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 [XML Schema Part 2: Datatypes Second Edition].
Whitespace normalization is applied as indicated by the
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
XML Schema validation. For example, "13" cast as xs:unsignedInt
returns
the xs:unsignedInt
typed
value 13
. This could also be written xs:unsignedInt("13")
.
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 21.3.1 Casting to derived types). If the lexical form does not conform to the pattern, a dynamic error [err:FORG0001] is raised.
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 [err:FORG0001].
Facets other than pattern
are checked after the conversion.
For example if there is a user-defined datatype called 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 [err:FORG0001].
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 20.2 Constructor functions for xs:QName and xs:NOTATION.
Note:
This version of the specification allows casting between xs:QName
and xs:NOTATION
in either direction; this was not permitted in the previous Recommendation. This version also removes
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 4.2 Arithmetic operators on numeric values.
If the target type is xs:float
or xs:double
, the string -0
(and equivalents
such as -0.0
or -000
) should be converted to the value negative zero.
However, if the implementation is reliant on an implementation of XML Schema 1.0 in which negative zero
is not part of the value space for these types, these lexical forms may be converted to positive zero.
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 [err:FOCA0006].
The choice of rounding algorithm and the choice between rounding and error behavior and is
·implementation-defined·.
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
[err:FODT0001] is raised.
In casting to a duration value, if the value is too large or too small to be represented by the implementation, a dynamic error [err:FODT0002] is raised.
For xs:anyURI
, the extent to which an implementation validates the
lexical form of xs:anyURI
is ·implementation-dependent·.
If the cast fails for any other reason, a dynamic error [err:FORG0001] is raised.
Casting from xs:string
and xs:untypedAtomic
to any other type
(primitive or non-primitive) has been described in 21.2 Casting from xs:string and xs:untypedAtomic.
This section defines how other casts to non-primitive types operate, including casting
to types derived by restriction, to union types, and to list types.
Note:
A non-primitive type here means any type that is not a ·primitive type· according to the extended definition used in 21 Casting.
Casting a value to a derived type can be separated into four cases. In these rules:
The types xs:untypedAtomic
, xs:integer
, xs:yearMonthDuration
,
and xs:dayTimeDuration
are treated as primitive types (alongside the 19 primitive types defined in XSD).
For any atomic type T, let P(T) denote the most specific primitive type
such that itemType-subtype(T, P(T))
is true
.
The rules are then:
When ST is the same type as TT: this case always succeeds, returning SV unchanged.
When itemType-subtype(ST, TT)
is true
: This case is described in 21.3.2 Casting from derived types to parent types.
When P(ST) is the same type as P(TT): This case is described in 21.3.3 Casting within a branch of the type hierarchy.
Otherwise (P(ST) is not the same type as P(TT)): This case is described in 21.3.4 Casting across the type hierarchy.
It is always possible to cast an atomic value 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 ·primitive type·, provided that the
supplied value conforms to the constraints implied by the facets of the target
type. This includes the case where the target type is derived from the type of the supplied value,
as well as the case where the type of the supplied value is derived from the target type. For example, an instance of 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 [err:FORG0001]. See [XML Schema Part 2: Datatypes Second Edition].
In the case of the pattern facet (which applies to the lexical space rather than
the value space), the pattern is tested against the canonical lexical
representation of the value, as defined for the source type (or the result
of casting the value to an xs:string
, in the case of types that have no canonical
lexical 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 21.1.3 Casting to duration types for rules regarding casting to
xs:yearMonthDuration
and xs:dayTimeDuration
. See 21.1.9 Casting to xs:ENTITY, below, for casting to xs:ENTITY
and types derived from it.
When the ST and the TT are derived, directly or indirectly, from different ·primitive types·, this is called casting across the type hierarchy. Casting across the type hierarchy is logically equivalent to three separate steps performed in order. Errors can occur in either of the latter two steps.
Cast the SV, up the hierarchy, to the ·primitive type· of the source, as described in 21.3.2 Casting from derived types to parent types.
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 [err:FORG0001] if the check fails.
Cast the value to the ·primitive type· of TT, as described in 21.1 Casting from primitive types to primitive types.
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 TT, as described in 21.3.3 Casting within a branch of the type hierarchy
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 21.2 Casting from xs:string and xs:untypedAtomic.
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 21.3.2 Casting from derived types to parent types
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 [err:FORG0001]. If the union type has constraining facets then the resulting value must satisfy these facets, otherwise a dynamic error occurs [err:FORG0001].
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 21.2 Casting from xs:string and xs:untypedAtomic apply), any list types in the membership
are effectively ignored.
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 [err:FORG0001].
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 [err:FORG0001] on the grounds that the string
"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 [err:FORG0001] on the grounds that the string
"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 21.2 Casting from xs:string and xs:untypedAtomic.
If the supplied value is not of type xs:string
or
xs:untypedAtomic
, a type error is raised
[err:XPTY0004]XP.
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 values 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 fn:normalize-space
function).
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.
Raised when fn:apply
is called and the arity of the supplied function is not
the same as the number of members in the supplied array.
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 array:subarray
is negative.
Raised when casting to xs:decimal
if the supplied value exceeds the
implementation-defined limits for the datatype.
Raised by fn:resolve-QName
and fn:QName
when a supplied value does not have the lexical
form of a QName or URI respectively; and when casting to decimal, if the supplied value is 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 fn:codepoints-to-string
if the input contains an integer that is not the codepoint
of a ·permitted character·.
Raised by any function that uses a collation if the requested collation is not recognized.
Raised by fn:normalize-unicode
if the requested normalization form is not
supported by the implementation.
Raised by functions such as fn:contains
if the requested collation does
not operate on a character-by-character basis.
Raised by fn:char
if the supplied character name is not recognized, or
if it represents a codepoint that is not
a ·permitted character·.
Raised by fn:parse-csv
if a syntax error in the quoting of one of the
fields in the input CSV is found.
Raised by fn:parse-csv
if the field-separator
,
record-separator
, or quote-character
option is set to
an illegal value.
Raised by fn:parse-csv
if any of the delimiter characters have been
set to the same value.
Raised by fn:csv-fetch-field-by-column
, and the function from the
field
entry of csv-columns-record
, if its
$key
argument is an xs:string
and is not one of the
known column names.
Raised by fn:id
, fn:idref
, and fn:element-with-id
if the node that identifies the tree to be searched is a node in a tree whose root is not
a document node.
Raised by fn:doc
, fn:collection
, and fn:uri-collection
to indicate that either the supplied URI cannot be dereferenced to obtain a resource, or the resource
that is returned is not parseable as XML.
Raised by fn:doc
, fn:collection
, and fn:uri-collection
to indicate that it is not possible to
return a result that is guaranteed deterministic.
Raised by fn:collection
and fn:uri-collection
if the argument is not a valid xs:anyURI
.
Raised (optionally) by fn:doc
if the argument
is not a valid xs:anyURI
.
Raised by fn:parse-xml
if the supplied string is not a well-formed and namespace-well-formed XML document;
or if DTD validation is requested and the document is not valid against its DTD.
Raised when fn:serialize
is called and the processor does not support serialization,
in cases where the host language makes serialization an optional feature.
Raised by fn:parse-html
if the supplied string is not a well-formed HTML document.
Raised by fn:parse-html
if a key passed to $options
, or its value,
is not supported by the implementation.
This error is raised if the decimal format name supplied to fn:format-number
is not a valid QName,
or if the prefix in the QName is undeclared, or if there is no decimal format in the static context with
a matching name.
This error is raised if the picture string supplied to fn:format-number
or
fn:format-integer
has invalid syntax.
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.
Error code used by fn:error
when no other error code is provided.
This error is raised if the picture string or calendar supplied to fn:format-date
, fn:format-time
,
or fn:format-dateTime
has invalid syntax.
This error is raised if the picture string supplied to fn:format-date
selects a component that is not present in a date, or if the picture string supplied to fn:format-time
selects a component that is not present in a time.
Raised by functions such as fn:json-doc
, fn:parse-json
or fn:json-to-xml
if the string supplied as input does not conform to the JSON grammar (optionally with implementation-defined extensions).
Raised by functions such as map:merge
, fn:json-doc
,
fn:parse-json
or fn:json-to-xml
if the input contains duplicate keys, when the chosen policy is to reject duplicates.
Raised by fn:json-to-xml
if validation
is requested when the processor does not support schema validation or typed nodes.
Raised by functions such as map:merge
, fn:parse-json
,
and fn:xml-to-json
if the $options
map contains an invalid entry.
Raised by fn:xml-to-json
if the XML input does not
conform to the rules for the XML representation of JSON.
Raised by fn:xml-to-json
if the XML input uses the attribute
escaped="true"
or escaped-key="true"
, and the corresponding string
or key contains an invalid JSON escape sequence.
Raised by fn:resolve-QName
and analogous functions if a supplied QName has a
prefix that has no binding to a namespace.
Raised by fn:resolve-uri
if no base URI is available for resolving a relative URI.
Raised by fn:load-xquery-module
if the supplied module URI is zero-length.
Raised by fn:load-xquery-module
if no module can be found with the supplied module URI.
Raised by fn:load-xquery-module
if a static error
(including a statically detected type error) is encountered when processing the library module.
Raised by fn:load-xquery-module
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.
Raised by fn:load-xquery-module
if no XQuery processor is available supporting the requested
XQuery version (or if none is available at all).
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 fn:resolve-uri
is not a valid URI/IRI.
Raised by fn:zero-or-one
if the supplied value contains more than one item.
Raised by fn:one-or-more
if the supplied value is an empty sequence.
Raised by fn:exactly-one
if the supplied value is not a singleton sequence.
Raised by functions such as fn:max
, fn:min
, fn:avg
, fn:sum
if the supplied sequence contains values inappropriate to this function.
Raised by fn:dateTime
if the two arguments both have timezones and the timezones are different.
A catch-all error for fn:resolve-uri
, recognizing that the implementation can choose between a variety
of algorithms and that some of these may fail for a variety of reasons.
Raised when the input to fn:parse-ietf-date
does not match the prescribed
grammar, or when it represents an invalid date/time such as 31 February.
Raised when the radix supplied to fn:parse-integer
is not in the range 2 to 36.
Raised when the digits in the string supplied to fn:parse-integer
are not in the range appropriate
to the chosen radix.
Raised by regular expression functions such as fn:matches
and fn:replace
if the
regular expression flags contain a character other than i
, m
, q
, s
, or x
.
Raised by regular expression functions such as fn:matches
and fn:replace
if the
regular expression is syntactically invalid.
For functions such as fn:replace
and fn:tokenize
, raises an error if
the supplied regular expression is capable of matching a zero length string.
Raised by fn:replace
to report errors in the replacement string.
Raised by fn:replace
if both the $replacement
and $action
arguments are supplied.
Raised by fn:data
, or by implicit atomization, if applied to a node with no typed value,
the main example being an element validated against a complex type that defines it to have element-only content.
Raised by fn:data
, or by implicit atomization, if the sequence to be atomized contains
a function item.
Raised by fn:string
, or by implicit string conversion, if the input sequence contains
a function item.
Raised by fn:deep-equal
if either input sequence contains a
function item.
A dynamic error is raised if the authority component of a URI contains an open square bracket but no corresponding close square bracket.
Raised by fn:unparsed-text
or fn:unparsed-text-lines
if the $href
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 fn:unparsed-text
or fn:unparsed-text-lines
if the $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 ·characters· using the specified
encoding, or if the resulting characters are not
·permitted characters·.
Raised by fn:unparsed-text
or fn:unparsed-text-lines
if the $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 no XSLT processor suitable for evaluating a call on fn:transform
is available.
A dynamic error is raised if the parameters supplied to fn:transform
are invalid, for example
if two mutually exclusive parameters are supplied. If a suitable XSLT error code is available (for example in the
case where the requested 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 fn:transform
fails with a
static or dynamic error. The XSLT error code is used if available; this error code provides a fallback when no XSLT
error code is returned, for example because the processor is an XSLT 1.0 processor.
A dynamic error is raised if the fn:transform
function is invoked when XSLT transformation (or a specific
transformation option) has been disabled for security or other reasons.
A dynamic error is raised if the result of the fn:transform
function contains characters available
only in XML 1.1 and the calling processor cannot handle such characters.
Two functions in this specification, fn:analyze-string
and
fn:json-to-xml
, produce results in the form of an XDM node tree that must conform
to a specified schema. In both cases the elements in the result are in the namespace
http://www.w3.org/2005/xpath-functions
, which is therefore the target namespace
of the relevant schema document.
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 xpath-functions.xsd:
<?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:schema>
fn:analyze-string
This schema describes the output of the function fn:analyze-string
.
The schema is reproduced below, and can also be found in analyze-string.xsd:
<?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:complexType name="analyze-string-result-type" mixed="true"> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element ref="fn:match"/> <xs:element ref="fn:non-match"/> </xs:choice> </xs:complexType> <xs:complexType name="match-type" mixed="true"> <xs:sequence> <xs:element ref="fn: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:schema>
fn:json-to-xml
This schema describes the output of the function fn:json-to-xml
, and the input to the
function fn:xml-to-json
.
The schema is reproduced below, and can also be found in schema-for-json.xsd:
<?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>
fn:csv-to-xml
This schema describes the output of the function fn:csv-to-xml
.
The schema is reproduced below, and can also be found in schema-for-json.xsd:
<?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"/> </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 conformance rules for XSLT 4.0 require implementations to support either XPath 3.0 or XPath 3.1. Some of the new functions in XPath 3.1, however, must be supported by all XSLT 4.0 implementations whether or not they implement other parts of XPath 3.1.
The following table lists all functions that have been defined in XSLT 1.0, 2.0, or 3.0, and summarizes their status.
Function name | Availability |
---|---|
fn:accumulator-after | XSLT 3.0 only |
fn:accumulator-before | XSLT 3.0 only |
fn:available-system-properties | XSLT 3.0 only |
fn:collation-key | Common to XSLT 3.0 and XPath 3.1 |
fn:copy-of | XSLT 3.0 only |
fn:current | XSLT 1.0, 2.0, and 3.0 |
fn:current-group | XSLT 2.0 and 3.0 |
fn:current-grouping-key | XSLT 2.0 and 3.0 |
fn:current-merge-group | XSLT 3.0 only |
fn:current-merge-key | XSLT 3.0 only |
fn:current-output-uri | XSLT 3.0 only |
fn:document | XSLT 1.0, 2.0, and 3.0 |
fn:element-available | XSLT 1.0, 2.0, and 3.0 |
fn:format-date | XSLT 2.0; migrated to XPath 3.0 and 3.1 |
fn:format-dateTime | XSLT 2.0; migrated to XPath 3.0 and 3.1 |
fn:format-number | XSLT 1.0 and 2.0; migrated to XPath 3.0 and 3.1 |
fn:format-time | XSLT 2.0; migrated to XPath 3.0 and 3.1 |
fn:function-available | XSLT 1.0, 2.0, and 3.0 |
fn:generate-id | XSLT 1.0 and 2.0; migrated to XPath 3.0 and 3.1 |
fn:json-to-xml | Common to XSLT 3.0 and XPath 3.1 |
fn:key | XSLT 1.0, 2.0, and 3.0 |
fn:regex-group | XSLT 2.0 and 3.0 |
fn:snapshot | XSLT 3.0 only |
fn:stream-available | XSLT 3.0 only |
fn:system-property | XSLT 1.0, 2.0, and 3.0 |
fn:type-available | XSLT 2.0 and 3.0 |
fn:unparsed-entity-public-id | XSLT 2.0 and 3.0 |
fn:unparsed-entity-uri | XSLT 1.0, 2.0, and 3.0 |
fn:unparsed-text | XSLT 2.0; migrated to XPath 3.0 and 3.1 |
fn:xml-to-json | Common to XSLT 3.0 and XPath 3.1 |
map:contains | Common to XSLT 3.0 and XPath 3.1 |
map:entry | Common to XSLT 3.0 and XPath 3.1 |
map:find | Common to XSLT 3.0 and XPath 3.1 |
map:for-each | Common to XSLT 3.0 and XPath 3.1 |
map:get | Common to XSLT 3.0 and XPath 3.1 |
map:keys | Common to XSLT 3.0 and XPath 3.1 |
map:merge | Common to XSLT 3.0 and XPath 3.1 |
map:put | Common to XSLT 3.0 and XPath 3.1 |
map:remove | Common to XSLT 3.0 and XPath 3.1 |
map:size | Common to XSLT 3.0 and XPath 3.1 |
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 implementors 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:
Dates and Times
Dynamic XPath Evaluation
Common (containing most notably the widely usednode-set
function)
Math (max
,min
,abs
, and trigonometric functions)
Random Number Generation
Regular Expressions
Sets (operations on sets of nodes including set intersection and difference)
String Manipulation (tokenize, replace, join and split, etc.)
Specifications from the EXSLT group can be found at [EXSLT].
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:
Binary (functions for manipulating binary data)
File Handling (reading and writing files)
Geospatial (handling of geographic data)
HTTP Client (sending HTTP requests)
ZIP Facility (reading and creating ZIP files or similar archives)
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 [EXPath].
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 [EXQuery].
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:
Test whether a string is all-whitespace
Trim leading and trailing whitespace
Test whether all the values in a sequence are distinct
Capitalize the first character of a string
Change the namespace of all elements in a tree
Get the number of days in a given month
Get the first or last day in a given month
Get the date of the preceding or following day
Ask whether an element has element-only, mixed, or simple content
Find the position of a node in a sequence
Count words in a string
The FunctX library can be found at [FunctX].
Certain functions that were proposed for inclusion in this function library have been excluded on the basis that it is straightforward for users to implement these functions themselves using XSLT 2.0 or XQuery 1.0.
This Appendix provides sample implementations of some of these functions.
To emphasize that these functions are examples of functions that vendors may write,
their names carry the prefix eg
. Vendors are free to define such functions in any
namespace. A group of vendors may also choose to create a collection of such useful
functions and put them in a common namespace.
In some situations, users may want to provide default values for missing
information that may be signaled by elements that are omitted, have no value or
have the empty sequence as their value. For example, a missing middle initial
may be indicated by omitting the element or a non-existent bonus signaled with
an empty sequence. This section includes examples of functions that provide such
defaults. These functions return xs:anyAtomicType*
. Users may want
to write functions that return more specific types.
eg:if-empty ( |
||
$node |
as , |
|
$value |
as
|
|
) as
|
If the first argument is the empty sequence or an element without simple or
complex content, eg:if-empty()
returns the second argument; otherwise, it
returns the content of the first argument.
XSLT implementation
<xsl:function name="eg:if-empty" as="xs:anyAtomicType*"> <xsl:param name="node" as="node()?"/> <xsl:param name="value" as="xs:anyAtomicType"/> <xsl:sequence select="($node[child::node()], $value)[1]"/> </xsl:function>
XQuery implementation
declare function eg:if-empty ( $node as node()?, $value as xs:anyAtomicType) as xs:anyAtomicType* { ($node[child::node()], $value)[1] }
eg:if-absent ( |
||
$node |
as , |
|
$value |
as
|
|
) as
|
If the first argument is the empty sequence, eg:if-absent()
returns the second
argument; otherwise, it returns the content of the first argument.
XSLT implementation
<xsl:function name="eg:if-absent" as="xs:anyAtomicType*"> <xsl:param name="node" as="node()?"/> <xsl:param name="value" as="xs:anyAtomicType"/> <xsl:sequence select="($node, $value)[1]"/> </xsl:function>
XQuery implementation
declare function eg:if-absent ( $node as node()?, $value as xs:anyAtomicType) as xs:anyAtomicType* { ($node, $value)[1] }
eg:value-union ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function returns a sequence containing all the distinct items in $arg1
and $arg2
, in an arbitrary order.
XSLT implementation
<xsl:function name="eg:value-union" as="xs:anyAtomicType*"> <xsl:param name="arg1" as="xs:anyAtomicType*"/> <xsl:param name="arg2" as="xs:anyAtomicType*"/> <xsl:sequence select="fn:distinct-values(($arg1, $arg2))"/> </xsl:function>
XQuery implementation
declare function eg:value-union ( $arg1 as xs:anyAtomicType*, $arg2 as xs:anyAtomicType*) as xs:anyAtomicType* { fn:distinct-values(($arg1, $arg2)) }
eg:value-intersect ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function returns a sequence containing all the distinct items that
appear in both $arg1
and $arg2
, in an arbitrary order.
XSLT implementation>
<xsl:function name="eg:value-intersect" as="xs:anyAtomicType*"> <xsl:param name="arg1" as="xs:anyAtomicType*"/> <xsl:param name="arg2" as="xs:anyAtomicType*"/> <xsl:sequence select="fn:distinct-values($arg1[.=$arg2])"/> </xsl:function>
XQuery implementation
declare function eg:value-intersect ( $arg1 as xs:anyAtomicType*, $arg2 as xs:anyAtomicType* ) as xs:anyAtomicType* { fn:distinct-values($arg1[.=$arg2]) }
eg:value-except ( |
||
$arg1 |
as , |
|
$arg2 |
as
|
|
) as
|
This function returns a sequence containing all the distinct items that
appear in $arg1
but not in $arg2
, in an arbitrary order.
XSLT implementation
<xsl:function name="eg:value-except" as="xs:anyAtomicType*"> <xsl:param name="arg1" as="xs:anyAtomicType*"/> <xsl:param name="arg2" as="xs:anyAtomicType*"/> <xsl:sequence select="fn:distinct-values($arg1[not(.=$arg2)])"/> </xsl:function>
XQuery implementation
declare function eg:value-except ( $arg1 as xs:anyAtomicType*, $arg2 as xs:anyAtomicType*) as xs:anyAtomicType* { fn:distinct-values($arg1[not(.=$arg2)]) }
eg:index-of-node ( |
||
$seq |
as , |
|
$search |
as
|
|
) as
|
This function returns a sequence of positive integers giving the positions within
the sequence $seq
of nodes that are identical to $search
.
The nodes in the sequence $seq
are compared with
$search
under the rules for the is
operator. If a
node compares identical, then the position of that node in the sequence
$seq
is included in the result.
If the value of $seq
is the empty sequence, or if no node in
$seq
matches $search
, then the empty sequence is returned.
The index is 1-based, not 0-based.
The result sequence is in ascending numeric order.
XSLT implementation
<xsl:function name="eg:index-of-node" as="xs:integer*"> <xsl:param name="seq" as="node()*"/> <xsl:param name="search" as="node()"/> <xsl:sequence select="fn:index-where($seq, fn:op('is')(?, $search))"/> </xsl:function>
XQuery implementation
declare function eg:index-of-node($seq as node()*, $search as node()) as xs:integer* { fn:index-where($seq, fn:op('is')(?, $search)) }
eg:string-pad ( |
||
$padString |
as , |
|
$padCount |
as
|
|
) as
|
Returns a xs:string
consisting of a given number of copies of an
xs:string
argument concatenated together.
XSLT implementation
<xsl:function name="eg:string-pad" as="xs:string"> <xsl:param name="padString" as="xs:string?"/> <xsl:param name="padCount" as="xs:integer"/> <xsl:sequence select=" fn:string-join(fn:replicate($padString, $padCount))"/> </xsl:function>
XQuery implementation
declare function eg:string-pad ( $padString as xs:string?, $padCount as xs:integer) as xs:string { fn:string-join(fn:replicate($padString, $padCount)) }
This returns the zero-length string if $padString
is the empty
sequence, which is consistent with the general principle that if an
xs:string
argument is the empty sequence it is treated as if it
were the zero-length string.
eg:distinct-nodes-stable ( |
||
$arg |
as
|
|
) as
|
This function illustrates one possible implementation of a distinct-nodes function. It removes duplicate nodes by identity, preserving the first occurrence of each node.
XPath
$arg[empty(subsequence($arg, 1, position()-1) intersect .)]
XSLT implementation
<xsl:function name="eg:distinct-nodes-stable" as="node()*"> <xsl:param name="arg" as="node()*"/> <xsl:sequence select="" fn:fold-left( $arg, (), function($foundSoFar as node()*, $this as node()) as node()* { if ($foundSoFar intersect $this) then $foundSoFar else ($foundSoFar, $this) }) "/> </xsl:function>
XQuery implementation
declare function eg:distinct-nodes-stable ($arg as node()*) as node()* { fn:fold-left( $arg, (), function($foundSoFar as node()*, $this as node()) as node()* { if ($foundSoFar intersect $this) then $foundSoFar else ($foundSoFar, $this) }) };
It is ·implementation-defined· which version of Unicode is supported, but it is recommended that the most recent version of Unicode be used. (See Conformance.)
It is ·implementation-defined· whether the type system is based on XML Schema 1.0 or XML Schema 1.1. (See Conformance.)
It is ·implementation-defined· whether definitions that rely on XML (for example, the set of valid XML characters) should use the definitions in XML 1.0 or XML 1.1. (See Conformance.)
It is not an error if the options map contains options with names other than those
described in this specification. Implementations may attach an
·implementation-defined· meaning to such entries,
and may define errors that arise if such entries are present with invalid values.
Implementations must ignore such entries unless they have a specific
·implementation-defined· meaning.
Implementations that define additional options in this way should
use values of type xs:QName
as the option names, using an appropriate namespace.
(See Options.)
It is ·implementation-defined· which version of [The Unicode Standard] is supported, but it is recommended that the most recent version of Unicode be used. (See Strings, characters, and codepoints.)
[Definition] Some
functions (such as fn:distinct-values
, fn:unordered
, map:keys
,
and map:for-each
) produce results in an
·implementation-defined· or
·implementation-dependent· order.
In such cases two calls with the same arguments are not guaranteed to produce the results in the same order. These functions are
said to be nondeterministic with respect to ordering.
(See .)
Where the results of a function are described as being (to a greater or lesser extent) ·implementation-defined· or ·implementation-dependent·, this does not by itself remove the requirement that the results should be deterministic: that is, that repeated calls with the same explicit and implicit arguments must return identical results. (See Properties of functions.)
In the case of a document node $D
returned by the fn:doc
function, or a document node at the root of a tree containing a node returned by the
fn:collection
function, it will always be true that either
fn:document-uri($D)
returns the empty sequence, or that the following
expression is true
: fn:doc(fn:document-uri($D))
is $D
. It is
·implementation-defined· whether this guarantee also holds for
document nodes obtained by other means, for example a document node passed as the
initial context node of a query or transformation.
(See fn:document-uri.)
In addition, the values of $input
, typically serialized and converted
to an xs:string
, and $label
(if supplied
and non-empty) may
be output to an ·implementation-defined· destination.
(See fn:trace.)
Similar to fn:trace
, the values of $input
,
typically serialized and converted to an xs:string
, and $label
(if supplied and non-empty) may be output to an
·implementation-defined· destination.
(See fn:log.)
They may provide an ·implementation-defined· mechanism that allows users to choose between raising an error and returning a result that is modulo the largest representable integer value. See [ISO 10967]. (See Arithmetic operators on numeric values.)
For xs:decimal
values, let N be the number of digits
of precision supported by the implementation, and let M (M <= N
) be the minimum limit on the number of digits
required for conformance (18 digits for XSD 1.0, 16 digits for XSD 1.1). Then for addition, subtraction, and multiplication
operations, the returned result should be accurate to N digits of precision, and for division and modulus operations,
the returned result should be accurate to at least M digits of precision.
The actual precision is ·implementation-defined·. If the number
of digits in the mathematical result exceeds the number of digits that the implementation
retains for that operation, the result is truncated or rounded in an ·implementation-defined· manner.
(See Arithmetic operators on numeric values.)
The [IEEE 754-2008] specification also describes handling of
two exception conditions called divideByZero
and invalidOperation
. The
IEEE divideByZero
exception is raised not only by a direct attempt to divide by zero, but also by
operations such as log(0)
. The IEEE invalidOperation
exception is raised by
attempts to call a function with an argument that is outside the function’s domain (for example,
sqrt(-1)
or log(-1)
).
Although IEEE defines these as exceptions, it also defines “default 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 may be notified to the application
or to the user by some ·implementation-defined·
warning condition, but the observable effect on an application
using the functions and operators defined in this specification is simply to return
the defined result (typically -INF
, +INF
, or NaN
) with no error.
(See Arithmetic operators on numeric values.)
The [IEEE 754-2008] specification distinguishes two NaN
values:
a quiet NaN
and a signaling NaN
. These two values are not distinguishable in the XDM model:
the value spaces of xs:float
and xs:double
each include only a single
NaN
value. This does not prevent the implementation distinguishing them internally,
and triggering different ·implementation-defined·
warning conditions, but such distinctions do not affect the observable behavior of an application
using the functions and operators defined in this specification.
(See Arithmetic operators on numeric values.)
The implementation may adopt a different algorithm provided that it is equivalent to
this formulation in all cases where ·implementation-dependent· or ·implementation-defined· behavior does not affect the outcome, for example,
the implementation-defined precision of the result of xs:decimal
division.
(See op:numeric-integer-divide.)
XSD 1.1 allows the string +INF
as a representation of positive infinity;
XSD 1.0 does not. It is ·implementation-defined· whether XSD 1.1 is
supported.
(See fn:number.)
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 ·implementation-defined· which
numbering sequences, additional to those listed above, are supported. If an
implementation does not support a numbering sequence represented by the given
token, it must use a format token of 1
.
(See fn:format-integer.)
For all format tokens other than a digit-pattern, there
may be ·implementation-defined· lower and upper bounds on the range of numbers that
can be formatted using this format token; indeed, for some numbering sequences there may
be intrinsic limits. For example, the format token ①
(circled
digit one, ①) has a range imposed by the Unicode character repertoire — zero to 20
in Unicode versions prior to 3.2, or zero to 50 in subsequent versions. For the numbering
sequences described above any upper bound imposed by the implementation must
not be less than 1000 (one thousand) and any lower bound must not be
greater than 1. Numbers that fall outside this range must be
formatted using the format token 1
.
(See fn:format-integer.)
The set of languages for which numbering is supported is ·implementation-defined·. If the $language
argument is absent, or is
set to an empty sequence, or is invalid, or is not a language supported by the
implementation, then the number is formatted using the default language from the dynamic
context.
(See fn:format-integer.)
...either a
or t
, to indicate alphabetic or traditional
numbering respectively, the default being ·implementation-defined·.
(See fn:format-integer.)
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 ·implementation-defined·. No error occurs if the implementation does not define any interpretation for the defined string. (See fn:format-integer.)
It is ·implementation-defined· what combinations of values of the format token, the language, and the cardinal/ordinal modifier are supported. If ordinal numbering is not supported for the combination of the format token, the language, and the string appearing in parentheses, the request is ignored and cardinal numbers are generated instead. (See fn:format-integer.)
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 ·implementation-defined·.
(See fn:format-integer.)
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 ·implementation-defined·. (See Defining a decimal format.)
IEEE states that the preferred quantum is language-defined. In this specification, it is ·implementation-defined·. (See Trigonometric and exponential functions.)
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 ·implementation-defined·. (See Trigonometric and exponential functions.)
The map returned by the fn:random-number-generator
function may contain additional entries beyond
those specified here, but it must match the type
item-type(rng)
defined above. The meaning of any additional entries
is ·implementation-defined·. To avoid conflict with any future version of this specification, the keys of any
such entries should start with an underscore character.
(See fn:random-number-generator.)
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 ·implementation-defined·. If the implementation recognizes
the meaning of the keyword and value then it should interpret it accordingly; if it does not recognize
the keyword or value then if the fallback
parameter is present with the value no
it should reject
the collation as unsupported, otherwise it should ignore the unrecognized parameter.
(See The Unicode Collation Algorithm.)
The following query parameters are defined. If any parameter is absent, the default is ·implementation-defined· except where otherwise stated. The meaning given for each parameter is non-normative; the normative specification is found in [UTS #35]. (See The Unicode Collation Algorithm.)
Because the set of collations that are supported is ·implementation-defined·, an implementation has the option to support all collation URIs, in which case it will never raise this error. (See Choosing a collation.)
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 ·implementation-defined· property of the collation. (See fn:collation-key.)
Conforming implementations must support normalization form NFC
and
may support normalization forms NFD
, NFKC
, NFKD
, and
FULLY-NORMALIZED
. They may also support other normalization forms
with ·implementation-defined· semantics.
(See fn:normalize-unicode.)
It is ·implementation-defined· which
version of Unicode (and therefore, of the normalization algorithms and their underlying
data) is supported by the implementation. See [UAX #15] for
details of the stability policy regarding changes to the normalization rules in future
versions of Unicode. If the input string contains codepoints that are unassigned in the
relevant version of Unicode, or for which no normalization rules are defined, the
fn:normalize-unicode
function leaves such codepoints unchanged. If the
implementation supports the requested normalization form then it must
be able to handle every input string without raising an error.
(See fn:normalize-unicode.)
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 ·implementation-defined· property of the collation. (See Functions based on substring matching.)
The result of the function will always be such that validation against this schema would succeed. However, it is ·implementation-defined· whether the result is typed or untyped, that is, whether the elements and attributes in the returned tree have type annotations that reflect the result of validating against this schema. (See fn:analyze-string.)
If the scheme is known to be hierarchical, or known
not to be hierarchical, then hierarchical is set accordingly.
Exactly which schemes are known to be hierarchical or
non-hierarchical is
·implementation-defined·.
If the implementation does not know if a scheme is or is not
hierarchical, the hierarchical setting depends on the
string. If the string is the empty string,
hierarchical is the empty sequence (i.e. not known),
otherwise hierarchical is
true
if string begins with /
and false
otherwise.
(See fn:parse-uri.)
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 should
recognize the default ports for http
(80), https
(443),
ftp
(21), and ssh
(22). Exactly which ports are
recognized
is ·implementation-defined·.
(See fn:parse-uri.)
If the scheme
is file
and the unc-path
option is true
, the scheme is delimited by a trailing :////
,
otherwise, if the URI is non-hierarchical, the scheme is delimited by
a trailing :
. For all other schemes, it is delimited by
a trailing ://
. Exactly which schemes are known to be
non-hierarchical is
·implementation-defined·.
(See fn:build-uri.)
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 should recognize
the default ports for http
(80),
https
(443), ftp
(21), and
ssh
(22). Exactly which ports are recognized is
·implementation-defined·.
(See fn:build-uri.)
All minimally conforming processors must support positive year values with a minimum of 4 digits (i.e., YYYY) and a minimum fractional second precision of 1 millisecond or three digits (i.e., s.sss). However, conforming processors may set larger ·implementation-defined· limits on the maximum number of digits they support in these two situations. Processors may also choose to support the year 0000 and years with negative values. The results of operations on dates that cross the year 0000 are ·implementation-defined·. (See Limits and precision.)
...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 ·implementation-defined· fallback representation.
(See The picture string.)
...indicates alphabetic or traditional numbering respectively,
the default being ·implementation-defined·.
This has the same meaning as in the second argument of fn:format-integer
.
(See The picture string.)
The sequence of characters in the (adjusted) first presentation modifier is reversed (for example,
999'###
becomes ###'999
).
If the result is not a valid decimal digit pattern, then the output is
·implementation-defined·.
(See Formatting Fractional Seconds.)
The output for these components is entirely ·implementation-defined·.
The default presentation modifier for these components is 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 9.8.4.8 The language, calendar, and place arguments.
(See Formatting Other Components.)
The set of languages, calendars, and places that are supported in the ·date formatting functions· is ·implementation-defined·. When any of these arguments is omitted or is an empty sequence, an ·implementation-defined· default value is used. (See The language, calendar, and place arguments.)
The choice of the names and abbreviations used in any given language is
·implementation-defined·. For example,
one implementation might abbreviate July as Jul
while another uses Jly
. In German,
one implementation might represent Saturday as Samstag
while another
uses Sonnabend
. Implementations may provide mechanisms allowing users to
control such choices.
(See The language, calendar, and place arguments.)
The choice of the names and abbreviations used in any given language for calendar units such as days of the week and months of the year is ·implementation-defined·. (See The language, calendar, and place arguments.)
The calendar value if present must be a valid EQName
(dynamic error: [err:FOFD1340]).
If it is a lexical 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 must identify a calendar with a designator specified below
(dynamic error: [err:FOFD1340]).
If the expanded QName is in a namespace then it identifies the calendar in an ·implementation-defined· way.
(See The language, calendar, and place arguments.)
At least one of the above calendars must be supported. It is ·implementation-defined· which calendars are supported. (See The language, calendar, and place arguments.)
Various aspects of this processing are ·implementation-defined·. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:... (See fn:doc.)
It is ·implementation-defined· whether DTD validation and/or schema validation is applied to the source document. (See fn:doc.)
The effect of a fragment identifier in the supplied URI is ·implementation-defined·. One possible interpretation is to treat the fragment identifier as an ID attribute value, and to return a document node having the element with the selected ID value as its only child. (See fn:doc.)
By default, this function is ·deterministic·. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is ·implementation-defined·. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error [err:FODC0003]. (See fn:collection.)
By default, this function is ·deterministic·. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is ·implementation-defined·. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error [err:FODC0003]. (See fn:uri-collection.)
...the processor may use ·implementation-defined· heuristics to determine the likely encoding, otherwise... (See fn:unparsed-text.)
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 ·implementation-defined·. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:... (See fn:unparsed-text.)
The collation used for matching names is ·implementation-defined·, but must be the same as the collation used to ensure that the names of all environment variables are unique. (See fn:environment-variable.)
The precise process used to construct the XDM instance is ·implementation-defined·. In particular, it is implementation-defined whether DTD and/or schema validation is invoked, and it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used. (See fn:parse-xml.)
The precise process used to construct the XDM instance is ·implementation-defined·. In particular, it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used. (See fn:parse-xml-fragment.)
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 ·implementation-defined·,
and may depend on the context.
(See fn:serialize.)
The input may contain deviations from the grammar of [RFC 7159], which are handled in an ·implementation-defined· way. (Note: some popular extensions include allowing quotes on keys to be omitted, allowing a comma to appear after the last item in an array, allowing leading zeroes in numbers, and allowing control characters such as tab and newline to be present in unescaped form.) Since the extensions accepted are implementation-defined, an error may be raised [err:FOJS0001] if the input does not conform to the grammar. (See fn:parse-json.)
The input may contain deviations from the grammar of [RFC 7159], which are handled in an ·implementation-defined· way. (Note: some popular extensions include allowing quotes on keys to be omitted, allowing a comma to appear after the last item in an array, allowing leading zeroes in numbers, and allowing control characters such as tab and newline to be present in unescaped form.) Since the extensions accepted are implementation-defined, an error may be raised (see below) if the input does not conform to the grammar. (See fn:json-to-xml.)
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 C.2 Schema for the result of fn:json-to-xml, or against an
·implementation-defined· schema
if the liberal
option has the value true
.
(See fn:json-to-xml.)
Any other method
and html-version
combinations are
·implementation-defined·.
(See HTML parser options.)
The default behaviour is ·implementation-defined·. (See HTML parser options.)
Additional ·implementation-defined· parser options. (See HTML parser options.)
An ·implementation-defined· parsing algorithm, tree construction, and validation consistent with the specified HTML version. (See fn:parse-html.)
If an implementation allows these nodes to be passed in via an API or similar mechanism, their behaviour is ·implementation-defined·. (See XDM Mapping from HTML DOM Nodes.)
If an implementation allows these nodes to be passed in via an API or similar mechanism, their behaviour is ·implementation-defined·. (See XDM Mapping from HTML DOM Nodes.)
If the local name contains a character that is not a valid XML
NameStartChar
or NameChar
, then an
·implementation-defined·
replacement character is used. The result must be a valid
NCName
.
(See node-name Accessor.)
If the local name contains a character that is not a valid XML
NameStartChar
or NameChar
, then an
·implementation-defined·
replacement character is used. The result must be a valid
NCName
.
(See node-name Accessor.)
If the arguments to fn:function-lookup
identify a function that is present
in the static context of the function call, the function will always return the same
function that a static reference to this function would bind to. If there is no such
function in the static context, then the results depend on what is present in the
dynamic context, which is ·implementation-defined·.
(See fn:function-lookup.)
A sequence of URIs (in the form of xs:string
values) which may be used or ignored in an
·implementation-defined· way....
(See fn:load-xquery-module.)
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 should be a URI controlled by the vendor of the XQuery processor. The meaning of the associated value is ·implementation-defined·. Implementations should ignore options whose names are in an unrecognized namespace. The ·option parameter conventions· do not apply to this contained map.... (See fn:load-xquery-module.)
It is ·implementation-defined· whether constructs in the library module are evaluated in the same ·execution scope· as the calling module. (See fn:load-xquery-module.)
The library module that is loaded may import schema declarations using an import schema
declaration. It is
·implementation-defined· whether schema components in the in-scope
schema definitions of the calling module
are automatically added to the in-scope schema definitions of the dynamically loaded module. The in-scope schema definitions
of the calling and called modules must be consistent, according to the rules defined in
Section
2.2.5 Consistency Constraints
XQ31.
(See fn:load-xquery-module.)
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 [EXPath],
then a serialized document might be written to filestore by calling the
file:write
function. Similar mechanisms might be used to issue
an HTTP POST request that posts the result to an HTTP server, or to send
the document to an email recipient. The semantics of calling functions
with side-effects are entirely ·implementation-defined·.
(See fn:transform.)
Calls to fn:transform
can potentially have side-effects
even in the absence of the post-processing option, because the XSLT
specification allows a stylesheet to invoke extension functions
that have side-effects. The semantics in this case are ·implementation-defined·.
(See fn:transform.)
A string intended to be used as the static base URI of the principal stylesheet
module. This value must be used if no other static base URI is
available. If the supplied stylesheet already has a base URI (which will generally be
the case if the stylesheet is supplied using stylesheet-node
or
stylesheet-location
) then it is ·implementation-defined· whether this
parameter has any effect. If the value is a relative reference, it is resolved against
the static base URI of the fn:transform
function call....
(See fn:transform.)
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 should be a URI controlled by the vendor of the XSLT processor. The meaning of the associated value is ·implementation-defined·. Implementations should ignore options whose names are in an unrecognized namespace. Default is an empty map.... (See fn:transform.)
It is ·implementation-defined· whether the XSLT transformation is executed within the same ·execution scope· as the calling code. (See fn:transform.)
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 ·implementation-defined· way. (See fn:transform.)
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
[XML Schema Part 2: Datatypes Second Edition] for ·implementation-defined· limits on
numeric values) a dynamic error is raised [err:FOCA0001]. If SV is one of the special
xs:float
or xs:double
values
NaN
, INF
, or -INF
, a dynamic
error is raised [err:FOCA0002].
(See Casting to xs:decimal.)
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
and -17.89
returns
-17
. Casting 3.124E1
returns 31
. If SV is too large to be
accommodated as an integer, (see [XML Schema Part 2: Datatypes Second Edition] for
·implementation-defined· limits on numeric values) a
dynamic error is
raised [err:FOCA0003]. If SV is
one of the special xs:float
or
xs:double
values NaN
,
INF
, or -INF
, a dynamic error is raised
[err:FOCA0002].
(See Casting to xs:integer.)
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 [err:FOCA0006].
The choice of rounding algorithm and the choice between rounding and error behavior and is
·implementation-defined·.
(See Casting from xs:string and xs:untypedAtomic.)
The tz timezone database, available at http://www.iana.org/time-zones. It is ·implementation-defined· which version of the database is used. (See IANA Timezone Database.)
Unicode Standard Annex #15: Unicode Normalization Forms. Ed. Mark Davis and Ken Whistler, Unicode Consortium. The current version is 9.0.0, dated 2016-02-24. As with [The Unicode Standard], the version to be used is ·implementation-defined·. Available at: http://www.unicode.org/reports/tr15/. (See UAX #15.)
The Unicode Consortium, Reading, MA, Addison-Wesley, 2016. The Unicode Standard as updated from time to time by the publication of new versions. See http://www.unicode.org/standard/versions/ for the latest version and additional information on versions of the standard and of the Unicode Character Database. The version of Unicode to be used is ·implementation-defined·, but implementations are recommended to use the latest Unicode version; currently, Version 9.0.0. (See The Unicode Standard.)
Unicode Technical Standard #10: Unicode Collation Algorithm. Ed. Mark Davis and Ken Whistler, Unicode Consortium. The current version is 9.0.0, dated 2016-05-18. As with [The Unicode Standard], the version to be used is ·implementation-defined·. Available at: http://www.unicode.org/reports/tr10/. (See UTS #10.)
Unicode Technical Standard #35: Unicode Locale Data Markup Language. Ed Mark Davis et al, Unicode Consortium. The current version is 29, dated 2016-03-15. As with [The Unicode Standard], the version to be used is ·implementation-defined·. Available at: http://www.unicode.org/reports/tr35/. (See UTS #35.)
A number of new functions have been defined:
fn:every
A number of functions are included in the draft specification but have not yet been reviewed or accepted:
The keywords used for parameter names have been changed. Previously these names were
of no significance, but in 4.0 they can be used with keyword := value
argument syntax in function calls.
The fn:deep-equal
function has an options
argument
giving detailed control over how two values are compared.
The fn:format-integer
function can produce output in non-decimal
radices, for example binary and hexadecimal.
The fn:json-doc
function accepts additional options.
The fn:remove
function allows several items to be removed from
a sequence in a single call.
The fn:replace
function has an additional optional argument
allowing the replacement string to be computed from the matched input string.
The following changes are present in this draft, but have not been agreed by the community group:
The third argument of fn:format-number
can now be supplied
as an xs:QName
instead of as a string that can be converted to a QName.
Using a xs:QName
, especially in the (rare) cases when the value is
supplied dynamically, avoids the need to maintain the static namespace context
at execution time.
The function fn:xml-to-json
accepts an additional option:
number-formatter
allows the user to control the formatting of numeric
values, for example by preventing the use of exponential notation for large integers.
In the functions fn:substring
, fn:subsequence
,
fn:unparsed-text
, fn:unparsed-text-available
, fn:unparsed-text-lines
,
and array:subarray
, fn:resolve-uri
, fn:error
, and fn:trace
,
arguments that can be omitted can now also be set to an empty sequence;
the effect of supplying an empty sequence is equivalent to the effect of not supplying the argument.
The keyword for the argument has changed from arg
to value
.
The argument is now optional, and defaults to the context item (which is atomized if necessary).
This change aligns constructor functions such as xs:string
, xs:boolean
,
and xs:numeric
with fn:string
, fn:boolean
,
and fn:number
.
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.
These changes are not highlighted in the change-marked version of the specification.
The operator mapping table has been simplified so all the value comparison operators
are now defined in terms of two functions (for each data type): op:XX-equal
,
and op:XX-less-than
. The entries for op:XX-greater-than
have therefore been removed.
The names of arguments appearing in function signatures have been changed. This is to reflect the introduction of keyword arguments in XPath 4.0; the names chosen for arguments are now more consistent across the function library.
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.
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 edge cases, when comparing values of different numeric types (for example, xs:double
and xs:decimal
) where the values are numerically very close, numeric comparison may give different
results. 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 (for example using fn:distinct-values
,
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.
In version 4.0, omitting the $value
of fn:error
has the same
effect as setting it to an empty sequence. In 3.1, the effects could be different (the effect of omitting
the argument was implementation-defined).
In version 3.1, the fn:deep-equal
function did not merge adjacent text nodes after stripping
comments and processing instructions, so the elements <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 4.0, the function signature of fn:namespace-uri-for-prefix
constrains the
first argument to be either an 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 an 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 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 [err:XPTY0004]XP.
Previously this was defined as an error, but the kind of error and the error code were left unspecified.
Accordingly, the function signatures of the constructor functions for built-in list types
have been changed to use an argument type of xs:string?
.
For compatibility issues regarding earlier versions, see the 3.1 version of this specification.