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 G Changes since version 3.1.
This version of the specification is work in progress. It is produced by the QT4 Working Group, officially the W3C XSLT 4.0 Extensions Community Group. Individual functions specified in the document may be at different stages of review, reflected in their History notes. Comments are invited, in the form of GitHub issues at https://github.com/qt4cg/qtspecs.
Changes in 4.0 ⬇
Use the arrows to browse significant changes since the 3.1 version of this specification.
Sections with significant changes are marked Δ in the table of contents. New functions introduced in this version are marked ➕ in the table of contents.
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.
In some cases, this specification references XSD for the semantics of operations such as the effect of matching using regular expressions, or conversion of atomic items to strings. In most such cases there is no intended technical difference between the XSD 1.0 and XSD 1.1 specifications, but the 1.1 version often provides clearer explanations and sometimes also corrects technical errors. In such cases this specification often chooses to reference the XSD 1.1 specification. This should not be taken as implying that it is necessary to invoke an XSD 1.1 processor.
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 raises (in some way appropriate to the calling environment) a dynamic error.
For a sequence of calls within the same ·execution scope·, the requirements of this recommendation regarding the ·determinism· of results are satisfied (see 1.9.5 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 reuse implementations of the function library across host languages.
This specification allows flexibility in the choice of versions of specifications on which it depends:
It is ·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 items 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 19 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 17.3 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 18.2 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. This has the following sections:
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: specifically U+002D (HYPHEN-MINUS, -
) . 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 this is the last parameter of a ·variadic· function, an ellipsis (...
)
If the parameter is optional, then an expression giving the default value (preceded by the symbol :=
).
The default value expression is evaluated using the static and dynamic context of the function caller (or of a named function reference). For example, if the default value is given as .
, then it evaluates to the context value from the dynamic context of the function caller; if it is given as default-collation
, then its value is the default collation from the static context of the function caller; if it is given as deep-equal#2
, then the third argument supplied to deep-equal
is the default collation from the static context of the caller.
If 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.
If a function is ·variadic·, it has a variable number of arguments (zero or more). More strictly, there is an infinite set of functions having the same name and different arities.
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.
Some functions supplement the prose rules with a formal specification that describes the effect of the function in terms of an equivalent XPath or XQuery implementation. This is intended to take precedence over the prose rules in the event of any conflict; however, both sections are intended to be complete and not to rely on each other.
In writing the formal specifications, a number of guidelines have been followed:
Where the equivalent code calls other functions, these should either be primitives defined in the data model specification (see [XQuery and XPath Data Model (XDM) 3.1]), or functions that themselves have a formal specification; and the dependencies should not be circular.
There should be minimal reliance on XPath or XQuery language features. Although no attempt has been made to precisely define a core set of language constructs, the specifications try to avoid relying on features other than function calls and a few basic operators including the comma operator, equality testing, and simple integer arithmetic.
Editorial note | |
This worthy intent is not yet fully achieved; for example there are formal specifications that invoke fn:atomic-equal. |
There is no attempt to write formal specifications for functions that have complex logic (such as fn:format-number
) or dependencies (such as fn:doc
); the aim of the formal specifications is to define as rigorously as possible a platform of basic functionality that can be used as a solid foundation for more complex features.
Where the proforma includes a section headed Examples, these are non-normative.
Many of the examples are given in structured form, showing example expressions and their expected results. These published examples are derived from executable test cases, so they follow a standard format. In general, the actual result of the expression is expected to be deep-equal to the presented result, under the rules of the fn:deep-equal
function with default options. In some cases the result is qualified to indicate that the order of items in the result is implementation-dependent, or that numeric results are approximate.
For more complex functions, examples may be given using informal narrative prose.
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 value, referred to as .
. In the second signature, the argument must be present but may be the empty sequence, written as ()
.
Some functions accept a sequence of zero or more values as an argument. This is indicated by following the name of the type of the items in the sequence with *
. The sequence may contain zero or more items of the named type. For example, the function below accepts a sequence of xs:double
and returns a xs:double
or the empty sequence.
fn:median ( | ||
$arg | as
| |
) as
|
In XPath 4.0, the arguments in a function call can be supplied by keyword as an alternative to supplying them positionally. For example the call 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, { '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
.
Implementations may attach an ·implementation-defined· meaning to options in the map that are not described in this specification. These options should use values of type xs:QName
as the option names, using an appropriate namespace.
If an option is present whose key is not described in the specification, then a type error [err:XPTY0004]XPmust be raised unless either (a) the key is recognized by the implementation, or (b) the key is a value of type xs:QName
with a non-absent 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 coercion rulesXP40. 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 function should accept either a sequence or an array: but this rule applies only if the specification of the option explicitly accepts either. 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 items, 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 the union type (A | B)
and also for (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.
The following definitions are adopted from [XQuery and XPath Data Model (XDM) 4.0].
[Definition] An atomic item is a pair (T, D) where T (the ·type annotation·) is an atomic type, and D (the ·datum·) is a point in the value space of T.
[Definition] A primitive type is one of the 19 primitive atomic types defined in Section 3.2 Primitive datatypesXS2 of [XML Schema Part 2: Datatypes Second Edition], or the type xs:untypedAtomic
defined in [XQuery and XPath Data Model (XDM) 4.0].
[Definition] The datum of an ·atomic item· is a point in the value space of its type, which is also a point in the value space of the primitive type from which that type is derived. There are 20 primitive atomic types (19 defined in XSD, plus xs:untypedAtomic
), and these have non-overlapping value spaces, so each datum belongs to exactly one primitive atomic type.
[Definition] The type annotation of an atomic item is the most specific atomic type that it is an instance of (it is also an instance of every type from which that type is derived).
Note:
The term value space is defined in [Schema 1.1 Part 2] as a set of values. The term datum is used here in preference to value, because value has a different meaning in this data model.
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 U+FFFE and U+FFFF, while including characters with codepoints greater than U+FFFF 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.
This specification adopts the Unicode notation U+xxxx
to refer to a codepoint by its hexadecimal value (always four to six hexadecimal digits). This is followed where appropriate by the official Unicode character name and its graphical representation: for example U+20AC (EURO SIGN, €
) .
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 U+FFFF 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) 4.0]): 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 items, of precisely the same type, and the values are equal as defined using the eq
operator, using the Unicode codepoint collation when comparing strings.
Both items are nodes, and represent the same node.
Both items are maps, both maps have the same number of entries, and for every entry E1 in the first map there is an entry E2 in the second map such that the keys of E1 and E2 are ·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.4 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 value (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
, fn:parse-html
, 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 nondeterministic with respect to node identity.
Some functions (such as fn:doc
and fn:collection
) create new nodes by reading external documents. Such functions are guaranteed to be ·deterministic· with the exception that an implementation is allowed to make them nondeterministic as a user option.
Where the results of a function are described as being (to a greater or lesser extent) ·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.
[Definition] If a variadic function is called, several arguments in the function call are sequence-concatenated to supply the value of a single parameter in the function definition.
[Definition] The function fn:concat
is defined to be variadic: it accepts any number of arguments. No other function has this property.
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 value 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 items |
fn:base-uri | base-uri | node (optional) | xs:anyURI (optional) |
fn:document-uri | document-uri | node (optional) | xs:anyURI (optional) |
Function | Meaning |
---|---|
fn:node-name | Returns the name of a node, as an xs:QName . |
fn:nilled | Returns true for an element that is nilled. |
fn:string | Returns the value of $value represented as an xs:string . |
fn:data | Returns the result of atomizing a sequence. This process flattens arrays, and replaces nodes by their typed values. |
fn:base-uri | Returns the base URI of a node. |
fn:document-uri | Returns the URI of a resource where a document can be found, if available. |
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 value (.
).
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 value is absentDM40, type error [err:XPDY0002]XP.
If the context value is not a single node, type error [err:XPTY0004]XP.
For element and attribute nodes, the name of the node is returned as an xs:QName
, retaining the prefix, namespace URI, and local part.
For processing instructions, the name of the node is returned as an xs:QName
in which the prefix and namespace URI are 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.
Variables | |
---|---|
let $e := <doc> <p id="alpha" xml:id="beta">One</p> <p id="gamma" xmlns="http://example.com/ns">Two</p> <ex:p id="delta" xmlns:ex="http://example.com/ns">Three</ex:p> <?pi 3.14159?> </doc> |
Expression | Result |
---|---|
| QName("", "p") |
| QName("http://example.com/ns", "p") |
| QName("http://example.com/ns", "ex:p") |
| QName("", "pi") |
| () |
| QName("", "id") |
| xs:QName("xml:id") |
Returns true
for an element that is nilled.
fn:nilled ( | ||
$node | as
| := . |
) as
|
The 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 value (.
).
If $node
is the empty sequence, the function returns the empty sequence.
Otherwise the function returns the result of the dm:nilled
accessor as defined in [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 value is absentDM40, type error [err:XPDY0002]XP
If the context value is not a single node, type error [err:XPTY0004]XP.
If $node
is not an element node, the function returns the empty sequence.
If $node
is an untyped element node, the function returns false
.
In practice, the function returns true
only for an element node that has the attribute xsi:nil="true"
and that is successfully validated against a schema that defines the element to be nillable; the detailed rules, however, are defined in [XQuery and XPath Data Model (XDM) 3.1].
Returns the value of $value
represented as an xs:string
.
fn:string ( | ||
$value | as
| := . |
) as
|
The 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 value. 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 item, the function returns the result of the expression $value cast as xs:string
(see 20 Casting).
In all other cases, a dynamic error occurs (see below).
The following errors may be raised when $value
is omitted:
If the context value is absentDM40, type error [err:XPDY0002]XP.
If the context value is not a single item, type error [err:XPTY0004]XP.
A type error is raised [err:FOTY0014] if $value
is a function item (this includes maps and arrays).
Every node has a string value, even an element with element-only content (which has no typed value). Moreover, casting an atomic item to a string always succeeds. Functions, maps, and arrays have no string value, so these are the only arguments that satisfy the type signature but cause failure.
Variables | |
---|---|
let $para := <para>There lived a <term author="Tolkien">hobbit</term>.</para> |
Expression | Result |
---|---|
| "23" |
| "false" |
| "Paris" |
| Raises error XPTY0004. |
| Raises error FOTY0014. |
| Raises error FOTY0014. |
| "There lived a hobbit." |
Returns the result of atomizing a sequence. This process flattens arrays, and replaces nodes by their typed values.
fn:data ( | ||
$input | as
| := . |
) as
|
The 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 value (.
).
The result of fn:data
is the sequence of atomic items produced by applying the following rules to each item in $input
:
If the item is an atomic item, 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 items: 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 type error is raised [err:XPDY0002]XP if $input
is omitted and the context value 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 item or sequence of atomic items is required.
The result of atomizing an empty sequence is an empty sequence.
The result of atomizing an empty array is an empty sequence.
Variables | |
---|---|
let $para := <para>There lived a <term author="Tolkien">hobbit</term>.</para> |
Expression | Result |
---|---|
| 123 |
| 123, 456 |
| 1, 2, 3, 4 |
| xs:untypedAtomic("There lived a hobbit.") |
| xs:untypedAtomic("Tolkien") |
| Raises error FOTY0013. |
Returns the base URI of a node.
fn: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 value is absentDM40, type error [err:XPDY0002]XP
If the context value is not a single node, type error [err:XPTY0004]XP.
Returns the URI of a resource where a document can be found, if available.
fn: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 value (.
).
If $node
is the empty sequence, the function returns the empty sequence.
If $node
is not a document node, the function returns the empty sequence.
Otherwise, the function returns the value of the 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 value is absentDM40, type error [err:XPDY0002]XP
If the context value is not a single node, type error [err:XPTY0004]XP.
In the 3.1 version of this specification, it was mandated that two distinct documents could not have the same document-uri property: more specifically, it was guaranteed that for any document node $D
, either document-uri($D)
would be absent, or doc(document-uri($D))
would return $D
.
For various reasons, this constraint has proved impractical. Different parts of an application may read the same external resource in different ways, for example with or without validation or whitespace stripping, leading to different document nodes derived from the same external resource having the same document-uri
property. In addition, the specification explicitly allows implementations, at user request, to relax the requirements for determinism of resource access functions, which makes it possible for multiple calls of functions such as fn:doc
, fn:json-doc
, or fn:collection
to return different results for the same supplied URI.
Although the uniqueness of the document-uri
property is no longer an absolute constraint, it is still desirable that implementations should where possible respect the principle that URIs are usable as identifiers for resources.
In the case of a document node $D
returned by the fn:doc
function, it will generally be the case that fn:document-uri($D)
returns a URI $U
such that a call on fn:doc($U)
in the same dynamic context will return the same document node $D
. The URI $U
will not necessarily be the same URI that was originally passed to the fn:doc
function, since several URIs may identify the same resource.
It is recommended that implementations of fn:collection
should ensure that any documents included in the returned collection, if they have a non-empty fn:document-uri
property, should be such that a call on fn:doc
supplying this URI returns the same document node.
This section specifies further functions 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 value if the second argument is omitted, as specified by xml:lang attributes is the same as, or is a sublanguage of, the language specified by $language . |
fn: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). |
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 value (.
).
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 value is absentDM40, type error [err:XPDY0002]XP
If the context value is not a single 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)
.
Variables | |
---|---|
let $e := <doc> <p id="alpha" xml:id="beta">One</p> <p id="gamma" xmlns="http://example.com/ns">Two</p> <ex:p id="delta" xmlns:ex="http://example.com/ns">Three</ex:p> <?pi 3.14159?> </doc> |
Expression | Result |
---|---|
| "p" |
| "p" |
| "ex:p" |
| "pi" |
| "" |
| "id" |
| "xml:id" |
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 value (.
).
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 value is absentDM40, type error [err:XPDY0002]XP
If the context value is not a single node, type error [err:XPTY0004]XP.
Variables | |
---|---|
let $e := <doc> <p id="alpha" xml:id="beta">One</p> <p id="gamma" xmlns="http://example.com/ns">Two</p> <ex:p id="delta" xmlns:ex="http://example.com/ns">Three</ex:p> <?pi 3.14159?> </doc> |
Expression | Result |
---|---|
| "p" |
| "p" |
| "p" |
| "pi" |
| "" |
| "id" |
| "id" |
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 value is absentDM40, type error [err:XPDY0002]XP
If the context value is not a single node, type error [err:XPTY0004]XP.
Variables | |
---|---|
let $e := <doc> <p id="alpha" xml:id="beta">One</p> <p id="gamma" xmlns="http://example.com/ns">Two</p> <ex:p id="delta" xmlns:ex="http://example.com/ns">Three</ex:p> <?pi 3.14159?> </doc> |
Expression | Result |
---|---|
| "" |
| "http://example.com/ns" |
| "http://example.com/ns" |
| "" |
| "" |
| "" |
| "http://www.w3.org/XML/1998/namespace" |
This function tests whether the language of $node
, or the context value if the second argument is omitted, as specified by xml:lang
attributes is the same as, or is a sublanguage of, the language specified by $language
.
fn: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 value (.
) had been passed as the second argument.
The language of the argument $node
, or the context value 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 value is absentDM40, type error [err:XPDY0002]XP
If the context value is not a single 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 value (.
) 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 value is absentDM40, type error [err:XPDY0002]XP
If the context value is not a single 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 value (.
) 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 value is absentDM40, type error [err:XPDY0002]XP
If the context value is not a single node, type error [err:XPTY0004]XP.
Variables | |
---|---|
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>} | |
let $emp := <employee xml:id="ID21256"> <empnr>E21256</empnr> <first>John</first> <last>Brown</last> </employee> |
Expression: |
|
---|---|
Result: | '/' |
Expression: |
|
Result: | '/Q{http://example.com/one}p[1]' |
Expression: |
|
Result: | '/Q{http://example.com/one}p[1]/@Q{http://www.w3.org/XML/1998/namespace}lang' |
Expression: |
|
Result: | '/Q{http://example.com/one}p[1]/@author' |
Expression: |
|
Result: | '/Q{http://example.com/one}p[1]/Q{http://example.com/one}br[2]' |
Expression: | path( $e//text()[ starts-with(normalize-space(), 'Tochter') ] ) |
Result: | '/Q{http://example.com/one}p[1]/text()[2]' |
Expression: |
|
Result: | 'Q{http://www.w3.org/2005/xpath-functions}root()' |
Expression: |
|
Result: | 'Q{http://www.w3.org/2005/xpath-functions}root()/@Q{http://www.w3.org/XML/1998/namespace}id' |
Expression: |
|
Result: | 'Q{http://www.w3.org/2005/xpath-functions}root()/Q{}empnr[1]' |
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 value (.
).
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 value is absentDM40, type error [err:XPDY0002]XP
If the context value is not a single 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.
Variables | |
---|---|
let $e := <doc> <p id="alpha">One</p> <p/> <p>Three</p> <?pi 3.14159?> </doc> |
Expression | Result |
---|---|
| true() |
| true() |
| false() |
| true() |
| false() |
| false() |
| false() |
This section specifies functions on sequences of nodes.
Function | Meaning |
---|---|
fn:distinct-ordered-nodes | Removes duplicate nodes and sorts the input into document order. |
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. |
Removes duplicate nodes and sorts the input into document order.
fn:distinct-ordered-nodes ( | ||
$nodes | as
| |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Any duplicate nodes in the input (based on node identity) are discarded. The remaining nodes are returned in document orderXP40.
Document order is ·implementation-dependent· (but stable) for nodes in different documents. If some node in document A precedes some node in document B, then every node in A precedes every node in B.
Expression: | let $x := parse-xml('<doc><a/><b/><c/><d/><c/><e/></doc>') return distinct-ordered-nodes(($x//c, $x//b, $x//a, $x//b)) ! name() |
---|---|
Result: | "a", "b", "c", "c" (The two |
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 |
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.
Since the function never returns a value, the declared return type of item()*
is a convenient fiction. It is relevant insofar as a function item such as error#1
may (as a consequence of function coercion) be supplied in contexts where a function with a more specific return type is required.
Any QName may be used as an error code; there are no reserved names or namespaces. The error is always classified as a dynamic error, even if the error code used is one that is normally used for static errors or type errors.
Expression: |
|
---|---|
Result: | Raises error FOER0000. (This returns the URI |
Expression: | error( QName('http://www.example.com/HR', 'myerr:toohighsal'), 'Salary is too high' ) |
Result: | Raises error myerr:toohighsal. (This returns |
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.
Any serialization of the implementation's trace output must not raise an error. This can be achieved (for example) by using a serialization method that can handle arbitrary input, such as the adaptive output method (see Section 10 Adaptive Output Method SER31).
The format of the trace output and its order are ·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 reported before the error occurs.
If the trace information is unrelated to a specific value, fn:message
can be used instead.
Consider a situation in which a user wants to investigate the actual value passed to a function. Assume that in a particular execution, | |
The following two XPath expressions are identical, but only the second provides trace feedback to the user: | |
|
Outputs trace information and discards the result.
fn:message ( | ||
$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.
Any serialization of the implementation’s log output must not raise an error. This can e.g. be achieved by using a serialization method that can handle arbitrary input, such as the Section 10 Adaptive Output Method SER31.
The format of the log output and its order are ·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.
The following two XPath expressions are identical, but only the second logs any feedback: | |
|
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 nondeterministic: multiple calls will typically produce different results.
The function will typically be called to assist in diagnosing dynamic errors.
This section specifies arithmetic operators on the numeric datatypes defined in [XML Schema Part 2: Datatypes Second Edition].
The operators described in this section are defined on the following atomic types.
decimal
integer
double
float
Legend:
Supertype
subtype
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 20.3.7 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 item is in the lexical space of xs:double
, it will be converted to an xs:double
, and if not, a dynamic error occurs.
When the return type of a function is given as xs:numeric
, the actual value returned will be an instance of one of the three member types (and perhaps also of types derived from these by restriction). The rules for the particular function will specify how the type of the result depends on the values supplied as arguments. In many cases, for the functions in this specification, the result is defined to be the same type as the first argument.
Note:
This specification uses [IEEE 754-2019] 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-2019]. 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-2019] 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-2019]. 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-2019]. 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-2019]. 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-2019] 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-2019] 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-2019]. 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 |
---|---|
| 3 |
| -1 |
| -1 |
| 1 |
| 3 |
| -1 |
| 0 |
| 5 |
| 4 |
Returns the remainder resulting from dividing $arg1
, the dividend, by $arg2
, the divisor.
Defines the semantics of the mod
operator when applied to two numeric values.
op: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-2019] rounding division i.e. additional digits are truncated, not rounded to the required precision.
A dynamic error is raised [err:FOAR0001] for xs:integer
and xs:decimal
operands, if $arg2
is zero.
Expression | Result |
---|---|
| 1 |
| 0 |
| 0.9 |
| 3.0E0 |
Returns its operand with the sign unchanged: (+ $arg
).
Defines the semantics of the unary +
operator applied to a numeric value.
op: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 coercion rules are applied in the normal way, the unary +
operator can be used to force conversion of an untyped node to a number: the result of +@price
is the same as xs:double(@price)
if the type of @price
is xs:untypedAtomic
.
Returns its operand with the sign reversed: -$arg
.
Defines the semantics of the unary -
operator when applied to a numeric value.
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.
Note:
For a description of the different ways of comparing numeric values using the operators =
and eq
and the functions fn:deep-equal
and fn:atomic-equal
, see Section H Atomic Comparisons: An Overview (Non-Normative)XP40.
Note:
See also the function fn:compare
.
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, with control over how the rounding takes place. |
fn:round-half-to-even | Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near. |
fn:is-NaN | Returns true if the argument is the xs:float or xs:double value NaN . |
Note:
The fn:round
function has been extended with a third argument in version 4.0 of this specification; this means that the fn:ceiling
, fn:floor
, and fn:round-half-to-even
functions are now technically redundant. They are retained, however, both for backwards compatibility and for convenience.
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 |
---|---|
| 10.5 |
| 10.5 |
| xs:double('INF') |
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 |
---|---|
| 11 |
| -10 |
| -xs:double('INF') |
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 |
---|---|
| 10 |
| -11 |
| -xs:double('INF') |
Rounds a value to a specified number of decimal places, with control over how the rounding takes place.
fn:round ( | ||
$value | as , | |
$precision | as
| := 0 , |
$mode | as
| := 'half-to-ceiling' |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
General rules: see 4.4 Functions on numeric values.
The function returns a value that is close to $value
and that is a multiple of ten to the power of minus $precision
. The default value of $precision
is zero, in which case the function returns a whole number (but not necessarily an xs:integer
).
The detailed way in which rounding is performed depends on the value of $mode
, as follows. Here L means the highest multiple of ten to the power of minus $precision
that is less than or equal to $value
, U means the lowest multiple of ten to the power of minus $precision
that is greater than or equal to $value
, N means the multiple of ten to the power of minus $precision
that is numerically closest to $value
, and midway means that $value
is equal to the arithmetic mean of L and U.
Rounding Mode | Meaning |
---|---|
| Returns L. |
| Returns U. |
| Returns L if |
| Returns U if |
| Returns N, unless midway, in which case L. |
| Returns N, unless midway, in which case U. This is the default. |
| Returns N, unless midway, in which case it returns L if |
| Returns N, unless midway, in which case it returns U if |
| Returns N, unless midway, in which case it returns whichever of L and U has a last significant digit that is even. |
For the four types xs:float
, xs:double
, xs:decimal
and xs:integer
, it is guaranteed that if the type of $value
is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $value
is an instance of xs:decimal
and $precision
is less than one, then the result may be an instance of xs:integer
.
If the second argument is omitted or is an empty sequence, the function produces the same result as when $precision = 0
(that is, it rounds to a whole number).
When $value
is of type xs:float
and xs:double
:
If $value
is NaN
, positive or negative zero, or positive or negative infinity, then the result is the same as the argument.
For other values, the argument is cast to xs:decimal
using an implementation of xs:decimal
that imposes no limits on the number of digits that can be represented. The function is applied to this xs:decimal
value, and the resulting xs:decimal
is cast back to xs:float
or xs:double
as appropriate to form the function result. If the resulting xs:decimal
value is zero, then positive or negative zero is returned according to the sign of $value
.
This function is typically used with a non-zero $precision
in financial applications where the argument is of type xs:decimal
. For arguments of type xs:float
and xs:double
the results may be counter-intuitive. For example, consider round(35.425e0, 2)
. The result is not 35.43
, as might be expected, but 35.42
. This is because the xs:double
written as 35.425e0
has an exact value equal to 35.42499999999...
, which is closer to 35.42
than to 35.43
.
The call round($v, 0, "floor")
is equivalent to floor($v)
.
The call round($v, 0, "ceiling")
is equivalent to ceiling($v)
.
The call round($v, $p, "half-to-even")
is equivalent to round-half-to-even($v, $p)
.
Expression | Result |
---|---|
| 3.0 |
| 2.0 |
| -2.0 |
| 1.13 |
| 8500 |
| 3.14e0 |
| -xs:double('INF') |
| 1 |
| -2 |
| 2 |
| -1 |
| 1 |
| -1 |
| 2 |
| -2 |
| 1.12 |
| -1.13 |
| 1.13 |
| -1.12 |
| 1.12 |
| -1.12 |
| 1.13 |
| -1.13 |
| 1.12 |
| -1.12 |
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
.
If the second argument is omitted or an empty sequence, the function produces the same result as the two-argument version with $precision = 0
.
For arguments of type xs:float
and xs:double
:
If the argument is NaN
, positive or negative zero, or positive or negative infinity, then the result is the same as the argument.
In all other cases, the argument is cast to xs:decimal
using an implementation of xs:decimal
that imposes no limits on the number of digits that can be represented. The function is applied to this xs:decimal
value, and the resulting xs:decimal
is cast back to xs:float
or xs:double
as appropriate to form the function result. If the resulting xs:decimal
value is zero, then positive or negative zero is returned according to the sign of the original argument.
This function is typically used in financial applications where the argument is of type xs:decimal
. For arguments of type xs:float
and xs:double
the results may be counter-intuitive. For example, consider round-half-to-even(xs:float(150.015), 2)
. The result is not 150.02
as might be expected, but 150.01
. This is because the conversion of the xs:float
value represented by the literal 150.015
to an xs:decimal
produces the xs:decimal
value 150.014999389...
, which is closer to 150.01
than to 150.02
.
From 4.0, the effect of this function can also be achieved by calling fn:round
with the third argument set to "half-to-even"
.
Expression | Result |
---|---|
| 0.0 |
| 2.0 |
| 2.0 |
| 3567.81e0 |
| 0.0e0 |
| 35600 |
| -xs:double('INF') |
Returns true
if the argument is the xs:float
or xs:double
value NaN
.
fn: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 |
---|---|
| false() |
| false() |
| true() |
| true() |
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 19 Constructor functions or using cast
expressions as described in 20 Casting.
In addition the fn:number
function is available to convert strings to values of type xs:double
. It differs from the xs:double
constructor function in that any value outside the lexical space of the xs:double
datatype is converted to the xs:double
value NaN
.
Function | Meaning |
---|---|
fn:number | Returns the value indicated by $value or, if $value is not specified, the context value after atomization, converted to an xs:double . |
fn:parse-integer | Converts a string to an integer, recognizing any radix in the range 2 to 36. |
Returns the value indicated by $value
or, if $value
is not specified, the context value after atomization, converted to an xs:double
.
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 value (.
). That is, fn:number()
is equivalent to fn:number(.)
, as defined by the rules that follow.
If $value
is the empty sequence or if $value
cannot be converted to an xs:double
, the xs:double
value NaN
is returned.
Otherwise, $value
is converted to an xs:double
following the rules of 20.1.3.2 Casting to xs:double. If the conversion to xs:double
fails, the xs:double
value NaN
is returned.
A type error is raised [err:XPDY0002]XP if $value
is omitted and the context value is absentDM40.
As a consequence of the rules given above, a type error is raised [err:XPTY0004]XP if the context value cannot be atomized, or if the result of atomizing the context value is a sequence containing more than one atomic item.
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.
Variables | |
---|---|
let $e := <e price="12.1" discount="NONE"/> |
Expression | Result |
---|---|
| 1.2e1 |
| 1.2e1 |
| xs:double('INF') |
| xs:double('NaN') |
| xs:double('NaN') |
| 1.21e1 |
| xs:double('NaN') |
| xs:double('NaN') |
| 1.0e1, 1.1e1, 1.2e1 |
Converts a string to an integer, recognizing any radix in the range 2 to 36.
fn:parse-integer ( | ||
$value | as , | |
$radix | as
| := 10 |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is an empty sequence, the result is an empty sequence.
The supplied $radix
must be in the range 2 to 36 inclusive.
The string $value
is preprocessed by stripping all whitespace characters (including internal whitespace) and underscore characters.
After this process, the supplied value must consist of an optional sign (+
or -
) followed by a sequence of one or more generalized digits drawn from the first $radix
characters in the alphabet 0123456789abcdefghijklmnopqrstuvwxyz
; upper-case alphabetics A-Z
may be used in place of their lower-case equivalents.
The value of a generalized digit corresponds to its position in this alphabet.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
let $alphabet := characters("0123456789abcdefghijklmnopqrstuvwxyz") let $preprocessed := translate($value, codepoints-to-string((9, 10, 13, 32, 95)), "") let $digits := translate($preprocessed, "+-", "") let $abs := sum( for $char at $p in reverse(characters(lower-case($digits))) return (index-of($alphabet, $char) - 1) * xs:integer(math:pow($radix, $p - 1))) return if (starts-with($preprocessed, "-")) 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: | 200 |
Expression: |
|
Result: | -20 |
Expression: |
|
Result: | 100 |
Expression: |
|
Result: | 255 |
Expression: |
|
Result: | 4294967295 |
Expression: |
|
Result: | -4294967295 |
Expression: |
|
Result: | 255 |
Expression: |
|
Result: | 5 |
Expression: |
|
Result: | 1023 |
Alphabetic base-26 numbering systems (hexavigesimal) can be parsed via translation. Note, enumerating systems that do not assign a symbol to zero (e.g., spreadsheet columns) must be preprocessed in a different fashion. | |
Expression: | lower-case("AAB") => translate("abcdefghijklmnopqrstuvwxyz", "0123456789abcdefghijklmnop") => parse-integer(26) |
Result: | 1 |
Digit-based numeration systems comparable to the Arabic numbers 0 through 9 can be parsed via translation. | |
Expression: | translate(value := '٢٠٢٣', replace := '٠١٢٣٤٥٦٧٨٩', with := '0123456789') => parse-integer() |
Result: | 2023 |
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 "3185"
. 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-signmust 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 U+0661 (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 U+0374 (DEXIA KERAIA, ʹ
) and sometimes U+0375 (ARISTERI KERAIA, ͵
) . 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 U+2460 (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 U+0410 (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-pattern01
, 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, U+03C4 (GREEK SMALL LETTER TAU, τ
) , but the implementation might return the eighteenth one, U+03C3 (GREEK SMALL LETTER SIGMA, σ
) , 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, U+03C2 (GREEK SMALL LETTER FINAL SIGMA, ς
) ). Because Greek never had a final capital sigma, Unicode has marked U+03A2, 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, U+03A3 (GREEK CAPITAL LETTER SIGMA, Σ
) , but an implementation might return U+03A2, the eighteenth position in the sequence of Greek capital letters, but unassigned to any character.
Expression: |
|
---|---|
Result: | "0123" |
| |
Ordinal numbering in Italian: The specification | |
1º 2º 3º 4º ... | |
The specification | |
Primo Secondo Terzo Quarto Quinto ... | |
Expression: |
|
Result: | "21st" |
| |
Expression: |
|
Result: | "g" |
Expression: |
|
Result: | "aa" |
Expression: |
|
Result: | "LVII" |
Expression: |
|
Result: | "1;234" |
Expression: |
|
Result: | "04d2" |
Expression: |
|
Result: | "4D2" |
Expression: |
|
Result: | "00bc_614e" |
Expression: |
|
Result: | "bc_614e" |
Expression: |
|
Result: | "1111 1111" |
Expression: |
|
Result: | "00VV" |
Expression: |
|
Result: | "1023" |
Expression: |
|
Result: | "10^23" |
This section defines a function for formatting decimal and floating point numbers.
Function | Meaning |
---|---|
fn:format-number | Returns a string containing a number formatted according to a given picture string and decimal format. |
Note:
This function can be used to format any numeric quantity, including an integer. For integers, however, the fn: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.
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”.
[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 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·.
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
.
Decimal format parameters can now be supplied directly as a map in the third argument, rather than referencing a format defined in the static context. [Issues 340 1138 PRs 1049 1151 5 March 2024]
For selected properties including percent
and exponent-separator
, it is now possible to specify a single-character marker to be used in the picture string, together with a multi-character rendition to be used in the formatted output. [Issue 1048 PR 1250 11 June 2024]
Returns a string containing a number formatted according to a given picture string and decimal format.
fn:format-number ( | ||
$value | as , | |
$picture | as , | |
$options | 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 function formats $value
as a string using the ·picture string· specified by the $picture
argument and a decimal format.
The $value
argument may be of any numeric data type (xs:double
, xs:float
, xs:decimal
, or their subtypes including xs:integer
). Note that if an xs:decimal
is supplied, it is not automatically promoted to an xs:double
, as such promotion can involve a loss of precision.
If the supplied value of the $value
argument is an empty sequence, the function behaves as if the supplied value were the xs:double
value NaN
.
If $options
is absent, or if it is supplied as an empty sequence or an empty map, then the number is formatted using the properties of the unnamed decimal format in the static context.
For backwards compatibility reasons, the decimal format can be supplied as an instance of xs:string
. If the value of the $options
argument is an xs:string
, then its value must be a string which after removal of leading and trailing whitespace is in the form of an EQName
as defined in the XPath 4.0 grammar, that is one of the following:
A lexical QName, which is expanded using the statically known namespaces. The default namespace is not used (no prefix means no namespace).
A URIQualifiedName
using the syntax Q{uri}local
, where the URI can be zero-length to indicate a name in no namespace.
The effective value of the $options
argument is then the map {'format-name':$FN}
where $FN
is the xs:QName
result of expanding this EQName
.
The entries that may appear in the $options
map are as follows. The ·option parameter conventions· apply. The detailed rules for the interpretation of each option appear later.
In the table, the type xs:string (: matching '.' :)
represents a single-character string, that is, a restriction of xs:string
with the facet pattern="."
, while the type xs:string (: matching '.|.:.*' :)
indicates a string that is either a single character, or a single character followed by U+003A (COLON, :
) followed by an arbitrary string. Such a property identifies two values: a single character called the marker, which is used to represent the property in the picture string; and an arbitrary string called the rendition which is used to represent in the property in the result string. In the absence of the colon the single character value is used both as the marker and the rendition.
The default value for absent options (other than format-name
) is taken from a decimal format in the static context; the default values shown in the table are the values used if no specific value is assigned in the static context.
record( | |
format-name? | as (xs:NCName | xs:QName)? , |
decimal-separator? | as xs:string (: matching '.|.:.*' :) , |
grouping-separator? | as xs:string (: matching '.|.:.*' :) , |
exponent-separator? | as xs:string (: matching '.|.:.*' :) , |
infinity? | as xs:string , |
minus-sign? | as xs:string , |
NaN? | as xs:string , |
percent? | as xs:string (: matching '.|.:.*' :) , |
per-mille? | as xs:string (: matching '.|.:.*' :) , |
zero-digit? | as xs:string (: matching '.' :) , |
digit? | as xs:string (: matching '.' :) , |
pattern-separator? | as xs:string (: matching '.' :) |
) |
Key | Meaning |
---|---|
| The name of a decimal format in the static context; if absent, the unnamed decimal format in the static context is used. An xs:NCName represents the local part of an xs:QName in no namespace.
|
| The marker used to represent the decimal point in the picture string, and the rendition of the decimal point in the formatted number.
|
| The marker used to separate groups of digits in the picture string, and the rendition of the grouping separator in the formatted number.
|
| The marker used to separate the mantissa from the exponent in scientific notation in the picture string, and the rendition of the exponent separator in the formatted number.
|
| The string used to represent the value positive or negative infinity in the formatted number.
|
| The string used as a minus sign in the formatted number if there is no subpicture for formatting negative numbers.
|
| The string used to represent the value NaN in the formatted number.
|
| The marker used to indicate the presence of a percent sign in the picture string, and the rendition of the percent sign in the formatted number.
|
| marker used to indicate the presence of a per-mille sign in the picture string, and the rendition of the per-mille sign in the formatted number.
|
| Defines the characters used in the picture string to represent a mandatory digit: for example, if the zero-digit is 0 then any of the digits 0 to 9 may be used (interchangeably) in the picture string to represent a mandatory digit, and in the formatted number the characters 0 to 9 will be used to represent the digits zero to nine. The value must be a character in Unicode category Nd with decimal digit value 0 (zero).
|
| The character used in the picture string to represent an optional digit.
|
| The character used in the picture string to separate the positive and negative subpictures.
|
A base decimal format is established as follows:
If the format-name
option is present, then the decimal format in the static context identified by this name.
Otherwise, the unnamed decimal format in the static context.
The base decimal format is then modified using the other entries in the supplied $options
map.
The evaluation of the 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 $options
argument is supplied as an xs:string
that is neither a valid lexical QName nor a valid URIQualifiedName
, or if it uses a prefix that is not found in the statically known namespaces; or if the static context does not contain a declaration of a decimal format with a matching expanded QName; or if $options?format-name
is present and the static context does not contain a declaration of a decimal format whose name matches $options?format-name
. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.
A dynamic error is raised [err:FODF1290] if a value of $format
is not valid for the associated property, or if the properties of the decimal format resulting from a supplied $options
map do not have distinct values.
A string is an ordered sequence of characters, and this specification uses terms such as “left” and “right”, “preceding” and “following” in relation to this ordering, irrespective of the position of the characters when visually rendered on some output medium. Both in the picture string and in the result string, digits with higher significance (that is, representing higher powers of ten) always precede digits with lower significance, even when the rendered text flow is from right to left.
In previous versions of XSLT and XQuery, decimal formats were typically defined in the static context using custom declarations (<xsl:decimal-format>
in XSLT, declare decimal-format
in XQuery) and then selected by name in a call on fn:format-number
. This mechanism remains available, but in 4.0, it may be more convenient to dispense with these declarations, and instead to define a decimal format as a map bound to a global variable, which can be referenced in the $options
argument of the fn:format-number
call.
The following examples assume a default decimal format in which the chosen digits are the ASCII digits 0-9, the decimal separator is | |
Expression: |
|
---|---|
Result: | "12,345.60" |
Expression: |
|
Result: | "12,345,678.90" |
Expression: |
|
Result: | "0124" |
Expression: |
|
Result: | "14%" |
Expression: |
|
Result: | "14pc" |
Expression: | format-number(12345, '0.0###^0', { 'exponent-separator': '^:×10^' }) |
Result: | "1.2345×10^4" |
Expression: |
|
Result: | "-006" |
Expression: | format-number(1234567.8, '0.000,0', { 'grouping-separator': '.', 'decimal-separator': ',' }) |
Result: | "1.234.567,8" |
The following examples assume the existence of a decimal format named | |
Expression: |
|
Result: | "1.234,57" |
Expression: | format-number(12345, '0,###^0', { 'format-name': 'de', 'exponent-separator': '^' }) |
Result: | "1,234^4" |
Expression: | format-number(12345, '0,###^0', { 'format-name': 'de', 'exponent-separator': '^:×10^' }) |
Result: | "1,234×10^4" |
The following examples assume that the exponent separator in decimal format | |
Expression: |
|
Result: | "12.346E2" |
Expression: |
|
Result: | "2.3E-1" |
Expression: |
|
Result: | "0.23E0" |
Expression: |
|
Result: | ".23E0" |
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, 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-2019], 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:e | Returns an approximation to the mathematical constant e. |
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. |
math:sinh | Returns the hyperbolic sine of the argument. |
math:cosh | Returns the hyperbolic cosine of the argument. |
math:tanh | Returns the hyperbolic tangent of the argument. |
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 |
---|---|
| 6.283185307179586e0 |
The expression |
Returns an approximation to the mathematical constant e.
math:e () as xs:double |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
This function returns the xs:double
value whose lexical representation is 2.718281828459045e0
Expression | Result |
---|---|
| 1.161834242728283e0 (approximately) |
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-2019] 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 |
---|---|
| () |
| 1.0e0 |
| 2.7182818284590455e0 (approximately) |
| 7.38905609893065e0 |
| 0.36787944117144233e0 |
| 23.140692632779267e0 |
| xs:double('NaN') |
| xs:double('INF') |
| 0.0e0 |
Returns the value of 10
x, where x is the supplied argument value.
math:exp10 ( | ||
$value | as
| |
) as
|
This function is ·deterministic·, ·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-2019] 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 |
---|---|
| () |
| 1.0e0 |
| 1.0e1 |
| 3.1622776601683795e0 |
| 1.0e-1 |
| xs:double('NaN') |
| xs:double('INF') |
| 0.0e0 |
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-2019] 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 |
---|---|
| () |
| xs:double('-INF') |
| 1.0e0 |
| -6.907755278982137e0 |
| 0.6931471805599453e0 |
| xs:double('NaN') |
| xs:double('NaN') |
| xs:double('INF') |
| xs:double('NaN') |
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-2019] 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 |
---|---|
| () |
| xs:double('-INF') |
| 3.0e0 |
| -3.0e0 |
| 0.3010299956639812e0 |
| xs:double('NaN') |
| xs:double('NaN') |
| xs:double('INF') |
| xs:double('NaN') |
Returns the result of raising the first argument to the power of the second.
math:pow ( | ||
$x | as , | |
$y | as
| |
) as
|
This function is ·deterministic·, ·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-2019] 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-2019] 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 |
---|---|
| () |
| 8.0e0 |
| -8.0e0 |
| 0.125e0 |
| -0.125e0 |
| 1.0e0 |
| 1.0e0 |
| 1.0e0 |
| 1.0e0 |
| 1.0e0 |
| 0.0e0 |
| 0.0e0 |
| -0.0e0 |
| 0.0e0 |
| xs:double('INF') |
| xs:double('INF') |
| xs:double('-INF') |
| xs:double('INF') |
| 4.0e0 |
| 2.0e0 |
| xs:double('INF') |
| xs:double('-INF') (Odd-valued whole numbers are treated specially). |
| xs:double('INF') |
| xs:double('INF') |
| 0.0e0 |
| -0.0e0 (Odd-valued whole numbers are treated specially). |
| 0.0e0 |
| 0.0e0 |
| 1.0e0 |
| 1.0e0 |
| 1.0e0 |
| 1.0e0 |
| 1.0e0 |
| 6.25e0 |
| xs:double('NaN') |
Returns the 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-2019] 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 |
---|---|
| () |
| 0.0e0 |
| -0.0e0 |
| 1.0e3 |
| 1.4142135623730951e0 |
| xs:double('NaN') |
| xs:double('NaN') |
| xs:double('INF') |
| xs:double('NaN') |
Returns the sine of the argument. The argument is an angle in radians.
math:sin ( | ||
$radians | as
| |
) as
|
This function is ·deterministic·, ·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-2019] 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 |
---|---|
| () |
| 0.0e0 |
| -0.0e0 |
| 1.0e0 (approximately) |
| -1.0e0 (approximately) |
| 0.0e0 (approximately) |
| xs:double('NaN') |
| xs:double('NaN') |
| xs:double('NaN') |
Returns the cosine of the argument. The argument is an angle in radians.
math:cos ( | ||
$radians | as
| |
) as
|
This function is ·deterministic·, ·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 $radians
(which is treated as an angle in radians) as defined in the [IEEE 754-2019] 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 |
---|---|
| () |
| 1.0e0 |
| 1.0e0 |
| 0.0e0 (approximately) |
| 0.0e0 (approximately) |
| -1.0e0 (approximately) |
| xs:double('NaN') |
| xs:double('NaN') |
| xs:double('NaN') |
Returns the tangent of the argument. The argument is an angle in radians.
math:tan ( | ||
$radians | as
| |
) as
|
This function is ·deterministic·, ·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-2019] 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 |
---|---|
| () |
| 0.0e0 |
| -0.0e0 |
| 1.0e0 (approximately) |
| -1.0e0 (approximately) |
| 0.0e0 (approximately) (Mathematically, tan(π/2) is positive infinity. But because |
| -0.0e0 (approximately) (Mathematically, tan(-π/2) is negative infinity. But because |
| 0.0e0 (approximately) |
| xs:double('NaN') |
| xs:double('NaN') |
| xs:double('NaN') |
Returns the arc sine of the argument.
math:asin ( | ||
$value | as
| |
) as
|
This function is ·deterministic·, ·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-2019] 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 -math:pi() div 2
<= θ <= math:pi() div 2
.
Expression | Result |
---|---|
| () |
| 0.0e0 |
| -0.0e0 |
| 1.5707963267948966e0 (approximately) |
| -1.5707963267948966e0 (approximately) |
| xs:double('NaN') |
| xs:double('NaN') |
| xs:double('NaN') |
| xs:double('NaN') |
Returns the arc cosine of the argument.
math:acos ( | ||
$value | as
| |
) as
|
This function is ·deterministic·, ·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-2019] 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
<= θ <= math:pi()
.
Expression | Result |
---|---|
| () |
| 1.5707963267948966e0 (approximately) |
| 1.5707963267948966e0 (approximately) |
| 0.0e0 |
| 3.141592653589793e0 (approximately) |
| xs:double('NaN') |
| xs:double('NaN') |
| xs:double('NaN') |
| xs:double('NaN') |
Returns the arc tangent of the argument.
math:atan ( | ||
$value | as
| |
) as
|
This function is ·deterministic·, ·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-2019] 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 -math:pi() div 2
<= θ <= math:pi() div 2
.
Expression | Result |
---|---|
| () |
| 0.0e0 |
| -0.0e0 |
| 0.7853981633974483e0 (approximately) |
| -0.7853981633974483e0 (approximately) |
| xs:double('NaN') |
| 1.5707963267948966e0 (approximately) |
| -1.5707963267948966e0 (approximately) |
Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive 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-2019] 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 |
---|---|
| 0.0e0 |
| -0.0e0 |
| 3.141592653589793e0 |
| -3.141592653589793e0 |
| -1.5707963267948966e0 |
| 1.5707963267948966e0 |
| -3.141592653589793e0 |
| 3.141592653589793e0 |
| -0.0e0 |
| +0.0e0 |
Returns the hyperbolic sine of the argument.
math:sinh ( | ||
$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 hyperbolic sine of $value
as defined in the [IEEE 754-2019] specification of the sinh
function applied to 64-bit binary floating point values.
The treatment of the overflow
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 positive or negative infinity, or NaN
, the result is NaN
.
Expression | Result |
---|---|
| 1.1752011936438014e0 (approximately) |
| 11.548739357257748e0 (approximately) |
Returns the hyperbolic cosine of the argument.
math:cosh ( | ||
$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 hyperbolic cosine of $value
as defined in the [IEEE 754-2019] specification of the cosh
function applied to 64-bit binary floating point values.
The treatment of the overflow
exception is defined in 4.2 Arithmetic operators on numeric values.
If $value
is positive or negative zero, the result is 1
.
If $value
is positive or negative infinity, the result is INF
.
If $value
is NaN
, the result is NaN
.
In other cases, the result is an xs:double
in the range +1.0
to INF
.
Expression | Result |
---|---|
| 1.0e0 |
| 11.591953275521519e0 (approximately) |
Returns the hyperbolic tangent of the argument.
math:tanh ( | ||
$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 hyperbolic tangent of $value
as defined in the [IEEE 754-2019] specification of the tanh
function applied to 64-bit binary floating point values.
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 positive infinity, the result is +1.0
.
If $value
is negative infinity, the result is -1.0
.
In other cases, the result is an xs:double
in the range -1.0
to +1.0
.
Expression | Result |
---|---|
| 0.7615941559557649e0 (approximately) |
| 0.99627207622075e0 (approximately) |
Function | Meaning |
---|---|
fn:random-number-generator | Returns a random number generator, which can be used to generate sequences of random numbers. |
The 3.1 specification suggested that every value in the result range should have the same chance of being chosen. This has been corrected to say that the distribution should be arithmetically uniform (because there are as many xs:double
values between 0.01 and 0.1 as there are between 0.1 and 1.0).
Returns a random number generator, which can be used to generate sequences of random numbers.
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:
Name | Meaning |
---|---|
| An
|
| A zero-arity function that can be called to return another random number generator. The properties of this function are as follows:
|
| 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:
|
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 item 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 record type 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 XQuery code produces a random sequence of 200 | |
declare %public function local:random-sequence($length as xs:integer) as xs:double* { local:random-sequence($length, random-number-generator()) }; declare %private function local:random-sequence( $length as xs:integer, $record as record(number as xs:double, next as fn(*), *) ) as xs:double* { if ($length != 0) { $record?number, local:random-sequence($length - 1, $record?next()) } }; local:random-sequence(200) | |
An equivalent result can be achieved with | |
tail(fold-left( (1 to 200), random-number-generator(), fn($result) { head($result) ! (?next(), ?number), tail($result) } )) |
This section specifies functions and operators on the [XML Schema Part 2: Datatypes Second Edition]xs:string
datatype and the datatypes derived from it.
The operators described in this section are defined on the following types.
string
normalizedString
token
language
NMTOKEN
Name
NCName
ENTITY
ID
IDREF
Legend:
Supertype
subtype
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 |
---|---|
| "BACH" |
| "अशॊक" |
| "" |
| 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 |
---|---|
| (84, 104, 233, 114, 232, 115, 101) |
Function | Meaning |
---|---|
fn:codepoint-equal | Returns true if two strings are equal, considered codepoint-by-codepoint. |
fn:collation | Constructs a collation URI with requested properties. |
fn:collation-available | Asks whether a collation URI is recognized by the implementation. |
fn:collation-key | Given a string value and a collation, generates an internal value called a collation key, with the property that the matching and ordering of collation keys reflects the matching and ordering of strings under the specified collation. |
fn:contains-token | Determines whether or not any of the supplied strings, when tokenized at whitespace boundaries, contains the supplied token, under the rules of the supplied collation. |
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 | primary | secondary | tertiary | quaternary | identical, or 1|2|3|4|5 as synonyms (default tertiary / 3) | The collation strength as defined in UCA. Primary strength takes only the base form of the character into account (so A=a=Ä=ä); secondary strength ignores case but considers accents and diacritics as significant (so A=a and Ä=ä but ä≠a); tertiary considers case as significant (A≠a≠Ä≠ä); quaternary strength always considers as significant spaces and punctuation (data-base≠database; if maxVariable is punct or higher and alternate is not non-ignorable , lower strengths will treat data-base=database). |
maxVariable | space | punct | symbol | currency (default punct) | Given the sequence space , punct , symbol , currency , all characters in the specified group and earlier groups are treated as “noise” characters to be handled as defined by the alternate parameter. For example, maxVariable=punct indicates that characters classified as whitespace or punctuation get this treatment. |
alternate | non-ignorable | shifted | blanked (default non-ignorable) | Controls the handling of characters such as spaces and hyphens; specifically, the "noise" characters in the groups selected by the maxVariable parameter. The value non-ignorable indicates that such characters are treated as distinct at the primary level (so data base sorts before database ); shifted indicates that they are used to differentiate two strings only at the quaternary level, and blanked indicates that they are taken into account only at the identical level. |
backwards | yes | no (default no) | The value backwards=yes indicates that the last accent in the string is the most significant. |
normalization | yes | no (default no) | Indicates whether strings are converted to normalization form D. |
caseLevel | yes | no (default no) | When used with primary strength, setting caseLevel=yes has the effect of ignoring accents while taking account of case. |
caseFirst | upper | lower (default lower) | Indicates whether upper-case precedes lower-case or vice versa. |
numeric | yes | no (default no) | When numeric=yes is specified, a sequence of consecutive digits is interpreted as a number, for example chap2 sorts before chap12 . |
reorder | a comma-separated sequence of reorder codes, where a reorder code is one of space , punct , symbol , currency , digit , or a four-letter script code defined in [ISO 15924 Register], the register of scripts maintained by the Unicode Consortium in its capacity as registration authority for [ISO 15924]. | Determines the relative ordering of text in different scripts; for example the value digit,Grek,Latn indicates that digits precede Greek letters, which precede Latin letters. |
Note:
This list excludes parameters that are inconvenient to express in a URI, or that are applicable only to substring matching.
UCA collation URIs can be conveniently generated using the fn:collation
function.
The collation URI http://www.w3.org/2005/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 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 |
---|---|
| true() |
| false() |
| true() |
| () |
| () |
Constructs a collation URI with requested properties.
fn:collation ( | ||
$options | as
| |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
The function is supplied with a map defining the properties required of the collation, and returns a collation URI with these properties.
Specifically, it returns a string in the form of a URI with the scheme and path http://www.w3.org/2013/collation/UCA
followed by an optional query part. The query part is absent if options
is empty. Otherwise it consists of a question mark followed by a sequence of one or more semicolon-separated parameters. Each parameter is a keyword-value pair, the keyword and value being separated by an equals sign. There is one keyword-value pair for each entry in the options
map: the keyword is the same as the string value of the key in the map, and the value is the string value of the corresponding value, except where the value is of type xs:boolean
, in which case true
and false
are translated to yes
and no
.
The function does not check whether the implementation actually recognizes the resulting collation URI: that can be achieved using the fn:collation-available
function.
The properties available are as defined for the Unicode Collation Algorithm (see 5.3.3 The Unicode Collation Algorithm). Additional ·implementation-defined· properties may be specified as described in the rules for UCA collation URIs.
The ·option parameter conventions· apply, except as regards the handling of options not defined in this specification. Specifically:
If the option key is of type xs:string
, xs:anyURI
, or xs:untypedAtomic
then it is converted to a string, and produces a URI query parameter which is handled as described in 5.3.3 The Unicode Collation Algorithm.
If the option key is of any other type then the function fails with a type error [err:XPTY0004]XP.
The following options are defined:
record( | |
fallback? | as xs:boolean , |
lang? | as xs:language , |
version? | as xs:string , |
strength? | as enum("primary", "secondary", "tertiary", "quaternary", "identical", "1", "2", "3", "4", "5") , |
maxVariable? | as enum("space", "punct", "symbol", "currency") , |
alternate? | as enum("non-ignorable", "shifted", "blanked", "currency") , |
backwards? | as xs:boolean , |
normalization? | as xs:boolean , |
caseLevel? | as xs:boolean , |
caseFirst? | as enum("upper","lower") , |
numeric? | as xs:boolean , |
reorder? | as xs:string |
) |
Key | Meaning |
---|---|
| See 5.3.3 The Unicode Collation Algorithm.
|
| See 5.3.3 The Unicode Collation Algorithm.
|
| See 5.3.3 The Unicode Collation Algorithm.
|
| See 5.3.3 The Unicode Collation Algorithm.
|
| See 5.3.3 The Unicode Collation Algorithm.
|
| See 5.3.3 The Unicode Collation Algorithm.
|
| See 5.3.3 The Unicode Collation Algorithm.
|
| See 5.3.3 The Unicode Collation Algorithm.
|
| See 5.3.3 The Unicode Collation Algorithm.
|
| See 5.3.3 The Unicode Collation Algorithm.
|
| See 5.3.3 The Unicode Collation Algorithm.
|
| See 5.3.3 The Unicode Collation Algorithm.
|
A type error is raised [err:XPTY0004]XP if options
includes an entry whose key is not of type xs:string
, xs:anyURI
, or xs:untypedAtomic
, or whose corresponding value is not castable to xs:string
.
Expression: |
|
---|---|
Result: | "http://www.w3.org/2013/collation/UCA" |
Expression: |
|
Result: | "http://www.w3.org/2013/collation/UCA?lang=de" |
Expression: |
|
Result: | "http://www.w3.org/2013/collation/UCA?lang=de;strength=primary" (The order of query parameters may vary.) |
The expression |
Asks whether a collation URI is recognized by the implementation.
fn:collation-available ( | ||
$collation | as , | |
$usage | as
| := () |
) as
|
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.
The first argument is a candidate collation URI.
The second argument establishes the intended usage of the collation URI. The value is a sequence containing zero or more of the following:
equality
indicates that the intended purpose of the collation URI is to compare strings for equality, for example in functions such as fn:index-of
or fn:deep-equal
.
sort
indicates that the intended purpose of the collation URI is to sort or compare different strings in a collating sequence, for example in functions such as fn:sort
or fn:max
.
substring
indicates that the intended purpose of the collation URI is to establish whether one string is a substring of another, for example in functions such as fn:contains
or fn:starts-with
.
The function returns true if and only if the implementation recognizes the candidate collation URI as one that can be used for each of the purposes listed in the $usage
argument. If the $usage
argument is absent or set to an empty sequence, the function returns true only if the collation is available for all purposes.
If the candidate collation is a UCA collation specifying fallback=yes
, then this function will always return true: implementations are required to recognize such a collation and use fallback behavior if there is no direct equivalent available.
Expression: |
|
---|---|
Result: | true() |
Expression: |
|
Result: | true() |
The expression |
Given a string value and a collation, generates an internal value called a collation key, with the property that the matching and ordering of collation keys reflects the matching and ordering of strings under the specified collation.
fn: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.
Variables | |
---|---|
let $C := collation({'strength':'primary'}) |
Expression: | map:merge( ({ collation-key("A", $C): 1 }, { collation-key("a", $C): 2 }), { "duplicates": "use-last" } )(collation-key("A", $C)) |
---|---|
Result: | 2 (Given that the keys of the two entries are equal under the rules of the chosen collation, only one of the entries can appear in the result; the one that is chosen is the one from the last map in the input sequence.) |
Expression: | let $M := { collation-key("A", $C): 1, collation-key("B", $C): 2 } return $M(collation-key("a", $C)) |
Result: | 1 (The strings |
As the above examples illustrate, it is important that when the |
Determines whether or not any of the supplied strings, when tokenized at whitespace boundaries, contains the supplied token, under the rules of the supplied collation.
fn: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.
The effect of the function is equivalent to the result of the following XPath expression.
some $t in $value ! 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: | true() |
Expression: |
|
Result: | true() |
Expression: |
|
Result: | false() |
Expression: | contains-token( "red green blue", "RED", "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" ) |
Result: | true() |
The following functions are defined on values of type xs:string
and types derived from it.
Function | Meaning |
---|---|
fn:char | Returns a string containing a particular character or glyph. |
fn:characters | Splits the supplied string into a sequence of single-character strings. |
fn:graphemes | Splits the supplied string into a sequence of single-grapheme strings. |
fn:concat | Returns the concatenation of the arguments, treated as sequences of strings. |
fn:string-join | Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items. |
fn:substring | Returns the part of $value beginning at the position indicated by $start and continuing for the number of ·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. |
fn:hash | Returns the results of a specified hash, checksum, or cyclic redundancy check function applied to the input. |
Notes:
When the above operators and functions are applied to datatypes derived from xs:string
, they are guaranteed to return values that are instances of xs:string
, but the value might or might not be an instance of the particular subtype of xs:string
to which they were applied.
The strings returned by fn:concat
and fn:string-join
are not guaranteed to be normalized. But see note in fn:concat
.
Returns a string containing a particular character or glyph.
fn:char ( | ||
$value | as
| |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns a string, generally containing a single ·character· or glyph, identified by $value
.
The supplied value of $value
must be one of the following:
A Unicode codepoint, supplied as an integer. For example fn:char(9)
returns the tab character.
An HTML5 character reference name (often referred to as an entity name) as defined at https://html.spec.whatwg.org/multipage/named-characters.html. The name is written with no leading ampersand and no trailing semicolon. For example fn:char("pi")
represents the character π
(x3C0
) and fn:char("nbsp")
returns the non-breaking space character, xA0
.
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, x0D
), or \t
(tab, x09
).
The result must consist of ·permitted characters·. For example fn:char(0xDEAD)
is invalid because it is in the surrogate range.
The function fails with a dynamic error [err:FOCH0005] if $value
is not a valid representation of a ·permitted character· or sequence of permitted characters.
Although all Unicode characters can appear in string literals (the delimiting quotation marks can be escaped by doubling them), some characters are not visually distinctive, so representing them by name may make code more readable. In addition, there may be contexts where it is necessary or prudent to write XPath expressions using ASCII characters only, for example where an expression is used in the query part of a URI.
A few HTML5 character reference names identify glyphs whose Unicode representation uses multiple codepoints. For example, the name NotEqualTilde
refers to the glyph ≂̸
which is expressed using the two codepoints U+2242 (MINUS TILDE, ≂
) , U+0338 (COMBINING LONG SOLIDUS OVERLAY) . In such cases the string length of the result of the function will exceed one.
Expression | Result |
---|---|
| "á" |
| "ð" |
| codepoints-to-string(9) (The character tab). |
| codepoints-to-string(9) (The character tab). |
| " " |
| "𝇊" (The character MUSICAL SYMBOL TEMPUS IMPERFECTUM CUM PROLATIONE PERFECTA). |
| codepoints-to-string((8770, 824)) (This HTML5 character reference name expands to multiple codepoints.) |
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.
The effect of the function is equivalent to the result of the following XPath expression.
fn:string-to-codepoints($value) ! fn:codepoints-to-string(.)
Expression | Result |
---|---|
| ("T", "h", "é", "r", "è", "s", "e") |
| () |
| () |
| (2, 4, 6) |
| "s-t-r-e-t-c-h" |
"Banana" => characters() => reverse() => string-join() | "ananaB" |
Splits the supplied string into a sequence of single-grapheme strings.
fn:graphemes ( | ||
$value | as
| |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns a sequence of strings. Each string in the sequence contains one or more ·character·s that collectively constitute a single extended grapheme cluster, as defined by [UAX #29].
If $value
is a zero-length string or the empty sequence, the function returns the empty sequence.
The resultant sequence of strings are extended graphemes, not legacy graphemes (see [UAX #29]).
Expression | Result |
---|---|
| ("a" || char(0x308), "b") (a + ◌̈ + b, three characters, two graphemes). |
| () |
| () |
| char('\r') || char('\n') (Carriage return + line feed, two characters, one grapheme). |
| char(0x1F476) || char(0x200D) || char(0x1F6D1) (👶 +ZWJ + 🛑, three characters, one grapheme). |
| ("क", "त") (क + त, two characters, two graphemes). |
| "क" || char(0x93C) || char(0x200D) || char(0x94D) || "त" (क + ◌़ + ZWJ + ◌् + त, five characters, one grapheme). |
Returns the concatenation of the arguments, treated as sequences of strings.
The two-argument form of this function defines the semantics of the ||
operator.
fn:concat ( | ||
$values | as
| := () |
) as
|
This function is ·deterministic·, ·context-independent·, ·focus-independent·, and ·variadic·.
This function is defined to be variadic. It defines a single parameter with the required type xs:anyAtomicType*
, but because the function is variadic, the input sequence may be supplied using multiple arguments. In addition the parameter is declared optional, so a call with no arguments is also permitted.
Unlike all other functions, this function is defined to be variadic, as indicated by the ellipsis in the function signature. Conceptually, there is an infinite set of functions with different numbers of arguments (minimum arity zero, maximum arity unbounded):
concat()
returns a zero-length string, ""
.
concat("a")
returns "a"
.
concat("a", "b")
returns "ab"
.
concat("a", "b", "c")
returns "abc"
.
concat("a", "b", "c", "d")
returns "abcd"
.
and so on.
It is equally possible to supply a single argument containing a sequence of strings:
concat(())
returns a zero-length string, ""
.
concat(("a"))
returns "a"
.
concat(("a", "b"))
returns "ab"
.
concat(("a", "b", "c"))
returns "abc"
.
concat(("a", "b", "c", "d"))
returns "abcd"
.
and so on.
More generally, any argument can be a sequence of strings:
concat(("a", "b"), "c")
returns "abc"
.
concat(("a", "b"), (), ("c", "d"))
returns "abcd"
.
A static call on the concat
function must use positional arguments, it cannot use keywords.
Each of the parameters has the required type xs:anyAtomicType*
. The coercion rules ensure that each supplied $values argument is first converted to a sequence of atomic items by applying atomization. These sequences are then combined (by sequence concatenationXP40) into a single sequence, and each item in the combined sequence is converted to a string using the fn:string
function. The strings are then concatenated with no separator.
The result of the function is then obtained by forming the sequence concatenationXP40 of these atomized values and applying the function fn:string-join#1
to the result. The call on fn:string-join
has the effect of casting each atomic item in the sequence to an xs:string
.
If XPath 1.0 compatibility mode is set to true in the static context of a static function call to fn:concat
, then each supplied argument $v
is first reduced to a single string, the result of the expression xs:string($v[1])
. This is special-case processing for the fn:concat
function, it is not something that follows from the general rules for calling variadic functions. This reflects the fact that fn:concat
had custom behavior in XPath 1.0. This rule applies only to static function calls.
A named function reference can be used to create a function item with any arity: for example concat#3
returns a function item that takes three arguments, which it concatenates. Similarly partial function application can be used to construct a function that concatenates fixed and variable values: for example concat('[', ?, ']')
returns a function item that takes a single argument and wraps the string value of this argument in square brackets. Similarly, concat(?, '-', ?)
returns a function item of arity two; it returns the string values of the two arguments separated by a hyphen.
As mentioned in 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 U+0308 (COMBINING DIAERESIS) or the numeric character reference ̈
, will return:
"I plan to go to Mu?nchen in September"
where the ?
again represents either the actual Unicode character U+0308 (COMBINING DIAERESIS) or the numeric character reference ̈
. 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 U+0308 (COMBINING DIAERESIS) or the numeric character reference ̈
, will return:
"I plan to go to München in September"
This returned result is normalized in NFC.
Alternatives to the fn:concat
function include the concatenation operator ||
(for example $x || '-' || $y
), and the use of string templates (for example `{$x}-{$y}`)
, and the fn:string-join
function.
Expression: |
|
---|---|
Result: | "ungrateful" |
Expression: | concat(
'Thy ', (), 'old ', "groans", "", ' ring',
' yet', ' in', ' my', ' ancient',' ears.'
)
|
Result: | "ungrateful" |
Expression: | concat(
'Thy ', (), 'old ', "groans", "", ' ring',
' yet', ' in', ' my', ' ancient',' ears.'
) |
Result: | "Thy old groans ring yet in my ancient ears." |
Expression: |
|
Result: | "Ciao!" |
Expression: |
|
Result: | "Ingratitude, thou marble-hearted fiend!" |
Expression: |
|
Result: | "1234true" |
Expression: |
|
Result: | "" |
Expression: |
|
Result: | "10/6" |
Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items.
fn:string-join ( | ||
$values | as , | |
$separator | as
| := "" |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the second argument is omitted or an empty sequence, the effect is the same as calling the two-argument version with $separator
set to a zero-length string.
The coercion rules ensure that the supplied $values
argument is first converted to a sequence of atomic items by applying atomization.
The function then returns an xs:string
created by casting each item in the atomized sequence to an xs:string
, and then concatenating the result strings in order, using the value of $separator
as a separator between adjacent strings. If $separator
is the zero-length string, then the items in $values
are concatenated without a separator.
If $values
is the empty sequence, the function returns the zero-length string.
Variables | |
---|---|
let $doc := <doc><chap><section xml:id="xyz"/></chap></doc> |
Expression: |
|
---|---|
Result: | "123456789" |
Expression: |
|
Result: | "Now is the time ..." |
Expression: | string-join( ('Blow, ', 'blow, ', 'thou ', 'winter ', 'wind!'), '' ) |
Result: | "Blow, blow, thou winter wind!" |
Expression: |
|
Result: | "" |
Expression: |
|
Result: | "1, 2, 3, 4, 5" |
Expression: | $doc//@xml:id ! string-join((node-name(), '="', ., '"')) |
Result: | 'xml:id="xyz"' |
Expression: | $doc//section ! string-join(ancestor-or-self::*/name(), '/') |
Result: | "doc/chap/section" |
Returns the part of $value
beginning at the position indicated by $start
and continuing for the number of ·characters· indicated by $length
.
fn:substring ( | ||
$value | as , | |
$start | as , | |
$length | as
| := () |
) as
|
This function is ·deterministic·, ·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 |
---|---|
| " car" (Characters starting at position 6 to the end of |
| "ada" (Characters at positions greater than or equal to 4 and less than 7 are selected.) |
| "234" (Characters at positions greater than or equal to 2 and less than 5 are selected.) |
| "12" (Characters at positions greater than or equal to 0 and less than 3 are selected. Since the first position is 1, these are the characters at positions 1 and 2.) |
| "" (Characters at positions greater than or equal to 5 and less than 2 are selected.) |
| "1" (Characters at positions greater than or equal to -3 and less than 2 are selected. Since the first position is 1, this is the character at position 1.) |
| "" (Since |
| "" (As above.) |
| "" |
| "12345" (Characters at positions greater than or equal to -42 and less than |
| "" (Since the value of |
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 value is absentDM40, a type error is raised: [err:XPDY0002]XP.
As a consequence of the rules given above, a type error is raised [err:XPTY0004]XP if the context value cannot be atomized, or if the result of atomizing the context value is a sequence containing more than one atomic item.
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 value is an attribute node typed as an xs:integer
with the string value 000001
, then fn:string-length()
returns 6
(the length of the string value of the node), while fn:string-length(.)
raises a type error (because the result of atomization is not an xs:string
).
Expression: | string-length( "Harp not on that string, madam; that is past." ) |
---|---|
Result: | 45 |
Expression: | "ᾧ" => string-length() |
Result: | 1 |
Expression: | "ᾧ" => normalize-unicode("NFD") => string-length() |
Result: | 4 (For strings that consist of a base character with combining characters, each combining character is length 1.) |
Expression: |
|
Result: | 0 |
Returns $value
with leading and trailing whitespace removed, and sequences of internal whitespace reduced to a single space character.
fn: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, U+0020 (SPACE) .
The whitespace characters are defined in the metasymbol S (Production 3) of [Extensible Markup Language (XML) 1.0 (Fifth Edition)].
If no argument is supplied, then $value
defaults to the string value (calculated using fn:string
) of the context value (.
).
If no argument is supplied and the context value is absentDM40, a type error is raised [err:XPDY0002]XP.
As a consequence of the rules given above, a type error is raised [err:XPTY0004]XP if the context value cannot be atomized, or if the result of atomizing the context value is a sequence containing more than one atomic item.
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: | normalize-space(" The wealthy curled darlings of our nation. ") |
---|---|
Result: | "The wealthy curled darlings of our nation." |
Expression: |
|
Result: | "" |
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 second argument is omitted or an empty sequence, 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 character U+0131 (LATIN SMALL LETTER DOTLESS I, ı
) (used in Turkish) is perhaps the most prominent lower-case letter which will not round-trip. The character U+0130 (LATIN CAPITAL LETTER I WITH DOT ABOVE, İ
) is the most prominent upper-case letter which will not round trip; there are others, such as U+1E9E (LATIN CAPITAL LETTER SHARP S, ẞ
) , which was introduced in Unicode 5.1.
These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.
Because the function is not sensitive to locale, results will not always match user expectations. In Quebec, for example, the standard uppercase equivalent of è
is È
, while in metropolitan France it is more commonly E
; only one of these is supported by the functions as defined.
Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.
Expression | Result |
---|---|
| "ABCD0" |
Converts a string to lower case.
fn: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 character U+0131 (LATIN SMALL LETTER DOTLESS I, ı
) (used in Turkish) is perhaps the most prominent lower-case letter which will not round-trip. The character U+0130 (LATIN CAPITAL LETTER I WITH DOT ABOVE, İ
) is the most prominent upper-case letter which will not round trip; there are others, such as U+1E9E (LATIN CAPITAL LETTER SHARP S, ẞ
) , which was introduced in Unicode 5.1.
These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.
Because the function is not sensitive to locale, results will not always match user expectations. In Quebec, for example, the standard uppercase equivalent of è
is È
, while in metropolitan France it is more commonly E
; only one of these is supported by the functions as defined.
Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.
Expression | Result |
---|---|
| "abc!d" |
Returns $value
modified by replacing or removing individual characters.
fn:translate ( | ||
$value | as , | |
$replace | as , | |
$with | as
| |
) as
|
This function is ·deterministic·, ·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 |
---|---|
| "BAr" |
| "AAA" |
| "ABdAB" |
Returns the results of a specified hash, checksum, or cyclic redundancy check function applied to the input.
fn:hash ( | ||
$value | as , | |
$algorithm | as
| := "MD5" , |
$options | 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
is an instance of xs:string
, it is converted to a sequence of octets on the basis of UTF-8 encoding. If $value
is an instance of xs:base64Binary
or xs:hexBinary
, it is converted to a sequence of octets.
The $algorithm
argument, if present, determines the algorithm to be used to calculate a checksum, hash, or cyclic redundancy check. If empty or absent, MD5
will be used. The effective value of the algorithm is determined by passing the value through fn:upper-case(fn:normalize-space())
.
Conforming implementations must support the following options and the functions referred to by them:
MD5
: the MD5 Message-Digest algorithm, defined by [RFC 6151] (update to [RFC 1321]).
SHA-1
: the SHA-1 algorithm, defined by [FIPS 180-4].
SHA-256
: the SHA-256 algorithm, defined by [FIPS 180-4].
BLAKE3
: the BLAKE3 algorithm defined by [BLAKE3 Hashing].
CRC-32
: the CRC-32 algorithm, defined by [IEEE 802-3]. It delivers a 32 bit unsigned integer, which this function returns as a 4-octet xs:hexBinary
value representing this integer in big-endian order (that is, most significant byte first).
Note:
Some libraries, notably System.IO.Hashing.Crc32
in .NET, return the result in little-endian order.
Conforming implementations may support other checksum and hash functions with implementation-defined semantics. The $options
argument, if present, defines additional parameters controlling how the process is conducted.
The function returns as xs:hexBinary
the octets returned by passing $value
as an octet sequence through the selected algorithm. The process is followed even if the input octet sequence is empty.
A dynamic error is raised [err:FOHA0001] if the effective value of the option algorithm
is not one of the values supported by the implementation.
It is common for secure algorithms to be cryptographically broken, as has happened to the algorithms MD5
, SHA-1
, and SHA-256
. And the CRC-32
algorithm is not intended for cryptographic purposes. Developers are responsible for ensuring that the algorithm chosen meets any expected security protocols, if relevant.
The BLAKE3
algorithm is included in the list of hashing algorithms because at the time of writing it appears to be a promising candidate as a secure and fast algorithm that shows signs of gaining widespread support. However, this is a fast moving field and the community group recognizes that this decision might eventually not stand the test of time. As the technology evolves in the future, implementations are free to drop support for this algorithm and substitute another that appears to better meet requirements.
Additional security practices, such as salting, may be applied as a preprocessing step, or fn:hash()
can be incorporated into more complex functions.
In most cases, the xs:hexBinary
output of the function will be sought in string form. Because of serialization rules, casting to a string renders the hash in uppercase, and rendering in lowercase (as adopted by [RFC 1321] and [FIPS 180-4]) requires further adjustment.
Variables | |
---|---|
let $doc := <doc>abc</doc> | |
let $salt := "D;%yL9TS:5PalS/d" |
Expression: | hash("abc") |
---|---|
Result: | xs:hexBinary("900150983CD24FB0D6963F7D28E17F72") |
Expression: | hash("ABC") |
Result: | xs:hexBinary("902FBDD2B1DF0C4F70B4A5D23525E932") |
Expression: | hash("") |
Result: | xs:hexBinary("D41D8CD98F00B204E9800998ECF8427E") |
Expression: | hash("ABC", "SHA-1") |
Result: | xs:hexBinary("3C01BDBB26F358BAB27F267924AA2C9A03FCFDB8") |
Expression: | hash("ABC", "BLAKE3") => string() => lower-case() |
Result: | "d1717274597cf0289694f75d96d444b992a096f1afd8e7bbfa6ebb1d360fedfc" |
Expression: | hash("ABC", "BLAKE3") => xs:base64Binary() => string() |
Result: | "0XFydFl88CiWlPddltREuZKglvGv2Oe7+m67HTYP7fw=" |
Expression: | hash("ABC", "sha-256") => string() |
Result: | "B5D4045C3F466FA91FE2CC6ABE79232A1A57CDF104F7A26E716E0A1E2789DF78" |
Expression: | hash("ABC", "sha-256") |
Result: | xs:hexBinary("B5D4045C3F466FA91FE2CC6ABE79232A1A57CDF104F7A26E716E0A1E2789DF78") |
Expression: | hash($doc) |
Result: | xs:hexBinary("900150983CD24FB0D6963F7D28E17F72") |
Expression: | hash(serialize($doc), "sha-1") => xs:base64Binary() => string() |
Result: | "8PzN28NtxQv5RlxQ5/w6DcnrpEU=" |
Expression: | hash("password123" || $salt, "SHA-256") |
Result: | xs:hexBinary("9C9B913EB1B6254F4737CE947EFD16F16E916F9D6EE5C1102A2002E48D4C88BD") |
Expression: | hash("", "CRC-32") |
Result: | xs:hexBinary("00000000") |
Expression: | hash("input", "CRC-32") |
Result: | xs:hexBinary("D82832D7") |
Expression: |
|
Result: | Raises error FOHA0001. |
The functions described in this section examine a string $arg1
to see whether it contains another string $arg2
as a substring. The result depends on whether $arg2
is a substring of $arg1
, and if so, on the range of ·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.
Variables | |
---|---|
let $coll := "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" |
Expression | Result |
---|---|
The collation used in some of these examples, | |
“Ignorable collation unit” is equivalent to “ignorable collation element” in [UTS #10]. | |
| true() |
| false() |
| true() (The first rule is applied, followed by the second rule.) |
contains( "abcdefghi", "-d-e-f-", $coll ) | true() |
contains( "a*b*c*d*e*f*g*h*i*", "d-ef-", $coll ) | true() |
contains( "abcd***e---f*--*ghi", "def", $coll ) | true() |
contains( (), "--***-*---", $coll ) | true() (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.
Variables | |
---|---|
let $coll := "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" |
Expression | Result |
---|---|
The collation used in some of these examples, | |
“Ignorable collation unit” is equivalent to “ignorable collation element” in [UTS #10]. | |
| true() |
| false() |
| true() |
starts-with( "abcdefghi", "-a-b-c-", $coll ) | true() |
starts-with( "a*b*c*d*e*f*g*h*i*", "a-bc-", $coll ) | true() |
starts-with( "abcd***e---f*--*ghi", "abcdef", $coll ) | true() |
starts-with( (), "--***-*---", $coll ) | true() (The second argument contains only ignorable collation units and is equivalent to the zero-length string.) |
starts-with( "-abcdefghi", "-abc", $coll ) | true() |
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.
Variables | |
---|---|
let $coll := "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" |
Expression | Result |
---|---|
The collation used in some of these examples, | |
“Ignorable collation unit” is equivalent to “ignorable collation element” in [UTS #10]. | |
| true() |
| false() |
| true() |
ends-with( "abcdefghi", "-g-h-i-", $coll ) | true() |
ends-with( "abcd***e---f*--*ghi", "defghi", $coll ) | true() |
ends-with( "abcd***e---f*--*ghi", "defghi", $coll ) | true() |
ends-with( (), "--***-*---", $coll ) | true() (The second argument contains only ignorable collation units and is equivalent to the zero-length string.) |
ends-with( "abcdefghi", "ghi-", $coll ) | true() |
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.
Variables | |
---|---|
let $coll := "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" |
Expression | Result |
---|---|
The collation used in some of these examples, | |
“Ignorable collation unit” is equivalent to “ignorable collation element” in [UTS #10]. | |
| "t" |
| "" |
| "" |
substring-before( "abcdefghi", "--d-e-", $coll ) | "abc" |
substring-before( "abc--d-e-fghi", "--d-e-", $coll ) | "abc--" |
substring-before( "a*b*c*d*e*f*g*h*i*", "***cde", $coll ) | "a*b*" |
substring-before( "Eureka!", "--***-*---", $coll ) | "" (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.
Variables | |
---|---|
let $coll := "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary" |
Expression | Result |
---|---|
The collation used in some of these examples, | |
“Ignorable collation unit” is equivalent to “ignorable collation element” in [UTS #10]. | |
| "too" |
| "" |
| "" |
substring-after( "abcdefghi", "--d-e-", $coll ) | "fghi" |
substring-after( "abc--d-e-fghi", "--d-e-", $coll ) | "-fghi" |
substring-after( "a*b*c*d*e*f*g*h*i*", "***cde***", $coll ) | "*f*g*h*i*" |
substring-after( "Eureka!", "--***-*---", $coll ) | "Eureka!" (The second argument contains only ignorable collation units and is equivalent to the zero-length string.) |
The four functions described in this section make use of a regular expression syntax for pattern matching, described below.
Function | Meaning |
---|---|
fn:matches | Returns true if the supplied string matches a given regular expression. |
fn:replace | Returns a string produced from the input string by replacing any substrings that match a given regular expression with a supplied replacement string, 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 subsections.
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. Furthermore, the #
character may be escaped: see 5.6.1.6 Comments. 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 from 1.0, 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 from 1.0, 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.
Comments are enabled in regular expressions if the c
flag is present.
A comment starts with a #
character that is not escaped with an immediately preceding backslash, and that is not contained in a CharClassExpr
(that is, in square brackets). It ends with the following #
character, or with the end of the string containing the regular expression.
Whether or not the c
flag is present, the production for SingleCharEsc
is extended to allow the #
character to be escaped.
All these functions provide an optional parameter, $flags
, to set options for the interpretation of the regular expression. The parameter accepts a xs:string
, in which individual letters are used to set options. The presence of a letter within the string indicates that the option is on; its absence indicates that the option is off. Letters may appear in any order and may be repeated. They are case-sensitive. 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()
Note:
Whitespace is treated as a lexical construct to be removed before the regular expression is parsed; it is therefore not explicit in the regular expression grammar.
q
: if present, all characters in the regular expression are treated as representing themselves, not as metacharacters. In effect, every character that would normally have a special meaning in a regular expression is implicitly escaped by preceding it with a backslash.
Furthermore, when this flag is present, the characters $
and \
have no special significance when used in the replacement string supplied to the fn:replace
function.
This flag can be used in conjunction with the i
flag. If it is used together with the m
, s
, x
, or c
flag, that flag has no effect.
Examples:
tokenize("12.3.5.6", ".", "q")
returns ("12", "3", "5", "6")
replace("a\b\c", "\", "\\", "q")
returns "a\\b\\c"
replace("a/b/c", "/", "$", "q")
returns "a$b$c"
matches("abcd", ".*", "q")
returns false()
matches("Mr. B. Obama", "B. OBAMA", "iq")
returns true()
c
: if present, comments are enabled in the regular expression. This flag has no effect if the q
flag is present. A comment is recognized by the presence of a #
character that is not escaped by a backslash or contained in a character class expression (charClassExpr
), and it is terminated by the following #
character or by the end of the regular expression string.
For example:
replace("03/24/2025", "(..#month#)/(..#day#)/(....#year#)", "$3-$1-$2", "c")
Note:
Comments are treated as a lexical construct to be removed before the regular expression is parsed; they are therefore not explicit in the regular expression grammar.
Returns true
if the supplied string matches a given regular expression.
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 codepoints; it takes no account of collations.
Variables | |
---|---|
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> |
Expression | Result |
---|---|
| true() |
| true() |
| false() |
Given the source document: | |
the following function calls produce the following results, with the | |
| false() |
| true() |
| true() |
| false() |
| true() |
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: | "a*cada*" |
Expression: |
|
Result: | "*" |
Expression: |
|
Result: | "*c*bra" |
Expression: |
|
Result: | "brcdbr" |
Expression: |
|
Result: | "abbraccaddabbra" |
Expression: |
|
Result: | "b" |
Expression: |
|
Result: | "bbbb" |
Expression: |
|
Result: | "carted" (The first |
Expression: | replace("abracadabra", "bra", action := fn { "*" }) |
Result: | "a*cada*" |
Expression: | replace( "abracadabra", "bra", action := upper-case#1 ) |
Result: | "aBRAcadaBRA" |
Expression: | replace("Chapter 9", "[0-9]+", action := fn { . + 1 }) |
Result: | "Chapter 10" |
Expression: | replace( "LHR to LAX", "[A-Z]{3}", action := { 'LAX': 'Los Angeles', 'LHR': 'London' } ) |
Result: | "London to Los Angeles" |
Expression: | replace( "57°43′30″", "([0-9]+)°([0-9]+)′([0-9]+)″", action := fn($s, $groups) { string($groups[1] + $groups[2] ÷ 60 + $groups[3] ÷ 3600) || '°' } ) |
Result: | "57.725°" |
The expression |
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 (U+0009 (TAB) ), newline (U+000A (NEWLINE) ), carriage return (U+000D (CARRIAGE RETURN) ) or space (U+0020 (SPACE) ) 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 (U+000C (FORM FEED) ) as whitespace. If it is necessary to treat form-feed as a separator, an explicit separator pattern should be used.
Expression: |
|
---|---|
Result: | ("red", "green", "blue") |
Expression: |
|
Result: | ("The", "cat", "sat", "on", "the", "mat") |
Expression: |
|
Result: | ("", "red", "green", "blue", "") |
Expression: |
|
Result: | ("1", "15", "24", "50") |
Expression: |
|
Result: | ("1", "15", "", "24", "50", "") |
| |
Expression: | tokenize( "Some unparsed <br> HTML <BR> text", "\s*<br>\s*", "i" ) |
Result: | ("Some unparsed", "HTML", "text") |
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 ·nondeterministic 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.
In the following examples, the result document is shown in serialized form, with whitespace between the element nodes. This whitespace is not actually present in the result. | |
Expression: |
|
---|---|
Result: | <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) |
Expression: | analyze-string("08-12-03", "^(\d+)\-(\d+)\-(\d+)$") |
Result: | <analyze-string-result xmlns="http://www.w3.org/2005/xpath-functions"> <match> <group nr="1">08</group>-<group nr="2">12</group>-<group nr="3">03</group> </match> </analyze-string-result> (with whitespace added for legibility) |
Expression: | analyze-string("A1,C15,,D24, X50,", "([A-Z])([0-9]+)") |
Result: | <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.
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: | encode-for-uri( "http://example.com/00/Weather/CA/Los%20Angeles#ocean" ) |
---|---|
Result: | "http%3A%2F%2Fexample.com%2F00%2FWeather%2FCA%2FLos%2520Angeles%23ocean" (This is probably not what the user intended because all of the delimiters have been encoded.) |
Expression: | concat( "http://example.com/", encode-for-uri("~bébé") ) |
Result: | "http://example.com/~b%C3%A9b%C3%A9" |
Expression: | concat( "http://example.com/", encode-for-uri("100% organic") ) |
Result: | "http://example.com/100%25%20organic" |
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 a sequence of octets. Each plus sign (+
) is replaced with the octet representing a space character (x20
), and any substring that matches the regular expression %[a-fA-F0-9][a-fA-F0-9]
is replaced with an octet for the two-digit hexadecimal number that follows the percent sign. Characters that are not part of such a substring are replaced with the octets of their UTF-8 encoding. For example, "A%42+C"
results in the octets x41
, x42
, x20
, x43
, and "💡"
yields xF0
, x9F
, x92
, and xA1
.
If %
is followed by up to two characters that are not hexadecimal digits, these characters are replaced by octets xEF
, xBF
, and xBD
, that is, the UTF-8 encoding of the Unicode replacement character (U+FFFD (REPLACEMENT CHARACTER, �
) ). For example, the incomplete or invalid percent-encoded strings "%"
, "%X"
, "%AX"
, and "%XA"
are all replaced with these octets. For the string "%1X!"
, the octets xEF
, xBF
, xBD
, and x21
are returned.
Next, the resulting octets are interpreted as 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 |
---|---|
| "http://example.com/" |
| "~bébé?a=b c" |
| "�-�-�A-�💡" |
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 U+0020 (SPACE) to U+007E (TILDE, ~
) will be percent-encoded because they are invalid in a URI.
Since this function does not escape the character U+0025 (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: | iri-to-uri( "http://www.example.com/00/Weather/CA/Los%20Angeles#ocean" ) |
---|---|
Result: | "http://www.example.com/00/Weather/CA/Los%20Angeles#ocean" |
Expression: |
|
Result: | "http://www.example.com/~b%C3%A9b%C3%A9" |
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 $value
to be escaped is replaced by an escape sequence, which is formed by encoding the character as a sequence of octets in UTF-8, and then representing each of these octets in the form %HH, where HH is the hexadecimal representation of the octet. This function must always generate hexadecimal values using the upper-case letters A-F.
The behavior of this function corresponds to the recommended handling of non-ASCII characters in URI attribute values as described in [HTML 4.0] Appendix B.2.1.
Expression: | escape-html-uri( "http://www.example.com/00/Weather/CA/Los Angeles#ocean" ) |
---|---|
Result: | "http://www.example.com/00/Weather/CA/Los Angeles#ocean" |
Expression: | escape-html-uri( "javascript:if (navigator.browserLanguage == 'fr') window.open('http://www.example.com/~bébé');" ) |
Result: | "javascript:if (navigator.browserLanguage == 'fr') window.open('http://www.example.com/~b%C3%A9b%C3%A9');" |
This section specifies functions that parse strings as URIs, to identify their structure, and construct URI strings from their structured representation.
Some URI schemes are hierarchical and some are non-hierarchical. Implementations must treat the following schemes as non-hierarchical: jar
, mailto
, news
, tag
, tel
, and urn
. Whether additional schemes are known to be non-hierarchical ·implementation-defined·. If a scheme is not known to be non-hierarchical, it must be treated as hierarchical.
Function | Meaning |
---|---|
fn:parse-uri | Parses the URI provided and returns a map of its parts. |
fn:build-uri | Constructs a URI from the parts provided. |
The structured representation of a URI is described by the uri-structure-record, whose parts are:
Name | Meaning |
---|---|
| The original URI. This element is returned by
|
| The URI scheme (e.g., “https” or “file”).
|
| The URI is an absolute URI.
|
| Whether the URI is hierarchical or not.
|
| The authority portion of the URI (e.g., “example.com:8080”).
|
| Any userinfo that was passed as part of the authority.
|
| The host passed as part of the authority (e.g., “example.com”).
|
| The port passed as part of the authority (e.g., “8080”).
|
| The path portion of the URI.
|
| Any query string.
|
| Any fragment identifier.
|
| Parsed and unescaped path segments.
|
| Parsed and unescaped query key-value pairs.
|
| The path of the URI, treated as a filepath.
|
The segmented forms of the path and query parameters provide convenient access to commonly used information.
The path, if there is one, is tokenized on “/” characters and each segment is unescaped (as per the fn:decode-from-uri
function). Consider the URI http://example.com/path/to/a%2fb
. The path portion has to be returned as /path/to/a%2fb
because decoding the %2f
would change the nature of the path. The unescaped form is easily accessible from path-segments
:
("", "path", "to", "a/b")
Note that the presence or absence of a leading slash on the path will affect whether or not the sequence begins with an empty string.
The query parameters are decoded into a map. Consider the URI: http://example.com/path?a=1&b=2%264&a=3
. The decoded form in the query-parameters is the following map:
{ "a": ("1", "3"), "b": "2&4" }
Note that both keys and values are unescaped. If a key is repeated in the query string, the map will contain a sequence of values for that key, as seen for a
in this example.
Parses the URI provided and returns a map of its parts.
fn:parse-uri ( | ||
$value | as , | |
$options | as
| := {} |
) as uri-structure-record? |
record uri-structure-record ( uri? as xs:string?, scheme? as xs:string?, absolute? as xs:boolean?, hierarchical? as xs:boolean?, authority? as xs:string?, userinfo? as xs:string?, host? as xs:string?, port? as xs:integer?, path? as xs:string?, query? as xs:string?, fragment? as xs:string?, path-segments? as xs:string*, query-parameters? as map(xs:string, xs:string*)?, filepath? as xs:string? )
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is an empty sequence, the result is an empty sequence.
The function parses the $value
provided, returning a map containing its constituent parts: scheme, authority components, path, etc. In addition to parsing URIs as defined by [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.
The following options are available:
record( | |
allow-deprecated-features? | as xs:boolean , |
omit-default-ports? | as xs:boolean , |
unc-path? | as xs:boolean |
) |
Key | Meaning |
---|---|
| Indicates that deprecated URI features should be returned
|
| Indicates that a port number that is the same as the default port for a given scheme should be omitted.
|
| Indicates that an input URI that begins with two or more leading slashes should be interprted as a Windows Universal Naming Convention Path. (Specifically: that it has the file: scheme.)
|
This function is described as a series of transformations over the input string to identify the parts of a URI that are present. Some portions of the URI are identified by matching with a regular expression. This approach is designed to make the description clear and unambiguous; it is not implementation advice. Comparison of scheme and authority components is case insensitive.
Processing begins with a string that is equal to the $value
. If the string contains any backslashes (\
), replace them with forward slashes (/
).
Strip off the fragment identifier and any query:
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 a fragment is present, it is URI decoded. If the fragment is the empty string, it is discarded 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 query is the empty string, it is discarded and the query is the empty sequence.
Attempt to identify the scheme:
If the string matches ^([a-zA-Z][A-Za-z0-9\+\-\.]+):(.*)$
:
the scheme is the first match group and
the string is the second match group.
Otherwise, the scheme is the empty sequence and the string is unchanged.
If the scheme is not empty and the fragment is empty, absolute is true. Otherwise, absolute is the empty sequence. (But see the discussion of hierarchical URIs, below.)
If scheme is the empty sequence or file
:
If the string matches ^/*([a-zA-Z][:|].*)$
:
the scheme is file
and
the string is a single slash /
followed by the first match group with the second character changed to :
, if necessary.
Otherwise, if unc-path is true
:
the scheme is file
and
the string is unchanged.
Finally, if neither of the preceding cases apply:
the scheme remains the empty sequence and
the string is unchanged.
Now that the scheme, if there is one, has been identified, determine if the URI is hierarchical:
If the scheme is known to be hierarchical, or known not to be hierarchical, then hierarchical is set accordingly. 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 URI is not hierarchical, absolute is the empty sequence.
Identify the remaining components according to the scheme and whether or not the URI is hierarchical.
If the scheme is file
:
The authority is the empty sequence.
If unc-path is true and the string matches ^/*(//[^/].*)$
: then filepath, and string are both the first match group.
If the string begins ^//*[A-Za-z]:/
then all but one leading slash is removed from string and the filepath is the string with all leading slashes removed.
Otherwise, the filepath and string are the string with any sequence of leading slashes replaced by a single slash.
If the scheme is hierarchical
:
If the string matches ^//([^/]+)$
, the authority is the first match group and the string is empty.
If the string matches ^//([^/]*)(/.*)$
, the authority is the first match group and the string is the second match group.
Otherwise, the authority is the empty sequence and the string is unchanged.
If the scheme is not hierarchical
:
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 the empty sequence, filepath is also the whole string.
A path-segments sequence is constructed by tokenizing the string on /
(solidus) and applying uri decoding on each token.
Note:
The path and path-segments properties both contain the path portion of the URI. The different formats only become important when the path contains encoded delimiters.
Consider /path%2Fsegment
. An application may want to decode that, using /path/segment
in a database query, for example. At the same time, an application may wish to modify the URI and then reconstruct it.
In the string form, decoding %2F
to /
is not reversible. In the path-segments form, the path is broken into discrete segments where the syntactic delimiters occur. This means the encoded delimiters can be decoded without introducing ambiguity: ("", "path/segment")
. In this format, the decoding is reversible: escape the non-syntactic delimiters before reconstructing the path with the syntactic ones.
A consequence of constructing the path-segments this way is that an empty string appears before the first /
, if the path begins with a /
, after the last /
, if the path ends with a /
, and between consecutive /
characters. (If the path consists of a single /
, that /
counts as both the first and last /
, producing a segment list containing two empty strings.)
The empty strings may seem unnecessary at first glance, but they assure that the path can be reconstructed by joining the segments together again without having to handle the presence or absence of a leading or trailing /
as special cases.
Applying uri decoding is equivalent to calling fn:decode-from-uri
on the string.
The query-parameters value is constructed as follows. Start with an empty map. Tokenize the query on the &
(ampersand). 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.
A uri-structure-record is returned. The record should be populated with only those 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: | { "authority": "qt4cg.org", "fragment": "parse-uri", "hierarchical": true(), "host": "qt4cg.org", "path": "/specifications/xpath-functions-40/Overview.html", "path-segments": ("", "specifications", "xpath-functions-40", "Overview.html"), "scheme": "http", "uri": "http://qt4cg.org/specifications/xpath-functions-40/Overview.html#parse-uri" } |
Expression: | parse-uri("http://www.ietf.org/rfc/rfc2396.txt") |
Result: | { "authority": "www.ietf.org", "hierarchical": true(), "absolute": true(), "host": "www.ietf.org", "path": "/rfc/rfc2396.txt", "path-segments": ("", "rfc", "rfc2396.txt"), "scheme": "http", "uri": "http://www.ietf.org/rfc/rfc2396.txt" } |
Expression: | parse-uri("https://example.com/path/to/file") |
Result: | { "authority": "example.com", "path": "/path/to/file", "scheme": "https", "path-segments": ("", "path", "to", "file"), "host": "example.com", "hierarchical": true(), "absolute": true(), "uri": "https://example.com/path/to/file" } |
Expression: | parse-uri(`https://example.com:8080/path?s=%22hello world%22&sort=relevance`) |
Result: | { "authority": "example.com:8080", "hierarchical": true(), "absolute": true(), "host": "example.com", "path": "/path", "path-segments": ("", "path"), "port": "8080", "query": "s=%22hello world%22&sort=relevance", "query-parameters": { "s": """hello world""", "sort": "relevance" }, "scheme": "https", "uri": "https://example.com:8080/path?s=%22hello world%22&sort=relevance" } |
Expression: | parse-uri("https://user@example.com/path/to/file") |
Result: | { "authority": "user@example.com", "hierarchical": true(), "absolute": true(), "host": "example.com", "path": "/path/to/file", "path-segments": ("", "path", "to", "file"), "scheme": "https", "uri": "https://user@example.com/path/to/file", "userinfo": "user" } |
Expression: | parse-uri("ftp://ftp.is.co.za/rfc/rfc1808.txt") |
Result: | { "authority": "ftp.is.co.za", "hierarchical": true(), "absolute": true(), "host": "ftp.is.co.za", "path": "/rfc/rfc1808.txt", "path-segments": ("", "rfc", "rfc1808.txt"), "scheme": "ftp", "uri": "ftp://ftp.is.co.za/rfc/rfc1808.txt" } |
Expression: | parse-uri("file:////uncname/path/to/file") |
Result: | { "filepath": "/uncname/path/to/file", "hierarchical": true(), "absolute": true(), "path": "/uncname/path/to/file", "path-segments": ("", "uncname", "path", "to", "file"), "scheme": "file", "uri": "file:////uncname/path/to/file" } |
Expression: | parse-uri("file:///c:/path/to/file") |
Result: | { "filepath": "c:/path/to/file", "hierarchical": true(), "absolute": true(), "path": "/c:/path/to/file", "path-segments": ("", "c:", "path", "to", "file"), "scheme": "file", "uri": "file:///c:/path/to/file" } |
Expression: | parse-uri("file:/C:/Program%20Files/test.jar") |
Result: | { "filepath": "C:/Program Files/test.jar", "hierarchical": true(), "absolute": true(), "path": "/C:/Program%20Files/test.jar", "path-segments": ("", "C:", "Program Files", "test.jar"), "scheme": "file", "uri": "file:/C:/Program%20Files/test.jar" } |
Expression: | parse-uri("file:\\c:\path\to\file") |
Result: | { "filepath": "c:/path/to/file", "hierarchical": true(), "absolute": true(), "path": "/c:/path/to/file", "path-segments": ("", "c:", "path", "to", "file"), "scheme": "file", "uri": "file:\\c:\path\to\file" } |
Expression: | parse-uri("file:\c:\path\to\file") |
Result: | { "filepath": "c:/path/to/file", "hierarchical": true(), "absolute": true(), "path": "/c:/path/to/file", "path-segments": ("", "c:", "path", "to", "file"), "scheme": "file", "uri": "file:\c:\path\to\file" } |
Expression: | parse-uri("c:\path\to\file") |
Result: | { "filepath": "c:/path/to/file", "hierarchical": true(), "path": "/c:/path/to/file", "path-segments": ("", "c:", "path", "to", "file"), "scheme": "file", "uri": "c:\path\to\file" } |
Expression: | parse-uri("/path/to/file") |
Result: | { "filepath": "/path/to/file", "hierarchical": true(), "path": "/path/to/file", "path-segments": ("", "path", "to", "file"), "uri": "/path/to/file" } |
Expression: | parse-uri("#testing") |
Result: | { "fragment": "testing", "uri": "#testing" } |
Expression: | parse-uri("?q=1") |
Result: | { "query": "q=1", "query-parameters":{ "q": "1" }, "uri": "?q=1" } |
Expression: | parse-uri("ldap://[2001:db8::7]/c=GB?objectClass?one") |
Result: | { "authority": "[2001:db8::7]", "hierarchical": true(), "absolute": true(), "host": "[2001:db8::7]", "path": "/c=GB", "path-segments": ("", "c=GB"), "query": "objectClass?one", "query-parameters":{ "": "objectClass?one" }, "scheme": "ldap", "uri": "ldap://[2001:db8::7]/c=GB?objectClass?one" } |
Expression: | parse-uri("mailto:John.Doe@example.com") |
Result: | { "hierarchical": false(), "path": "John.Doe@example.com", "path-segments": "John.Doe@example.com", "scheme": "mailto", "uri": "mailto:John.Doe@example.com" } |
Expression: | parse-uri("news:comp.infosystems.www.servers.unix") |
Result: | { "hierarchical": false(), "path": "comp.infosystems.www.servers.unix", "path-segments": "comp.infosystems.www.servers.unix", "scheme": "news", "uri": "news:comp.infosystems.www.servers.unix" } |
Expression: | parse-uri("tel:+1-816-555-1212") |
Result: | { "hierarchical": false(), "path": "+1-816-555-1212", "path-segments": " 1-816-555-1212", "scheme": "tel", "uri": "tel:+1-816-555-1212" } |
Expression: | parse-uri("telnet://192.0.2.16:80/") |
Result: | { "authority": "192.0.2.16:80", "hierarchical": true(), "absolute": true(), "host": "192.0.2.16", "path": "/", "path-segments": ("", ""), "port": "80", "scheme": "telnet", "uri": "telnet://192.0.2.16:80/" } |
Expression: | parse-uri("urn:oasis:names:specification:docbook:dtd:xml:4.1.2") |
Result: | { "hierarchical": false(), "path": "oasis:names:specification:docbook:dtd:xml:4.1.2", "path-segments": "oasis:names:specification:docbook:dtd:xml:4.1.2", "scheme": "urn", "uri": "urn:oasis:names:specification:docbook:dtd:xml:4.1.2" } |
Expression: | parse-uri("tag:textalign.net,2015:ns") |
Result: | { "hierarchical": false(), "path": "textalign.net,2015:ns", "path-segments": "textalign.net,2015:ns", "scheme": "tag", "uri": "tag:textalign.net,2015:ns" } |
Expression: | parse-uri("tag:jan@example.com,1999-01-31:my-uri") |
Result: | { "hierarchical": false(), "path": "jan@example.com,1999-01-31:my-uri", "path-segments": "jan@example.com,1999-01-31:my-uri", "scheme": "tag", "uri": "tag: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: | { "hierarchical": false(), "path": "file:/C:/Program%20Files/test.jar!/foo/bar", "path-segments": ("file:", "C:", "Program Files", "test.jar!", "foo", "bar"), "scheme": "jar", "uri": "jar:file:/C:/Program%20Files/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: | parse-uri("http://www.example.org/Dürst") |
Result: | { "authority": "www.example.org", "hierarchical": true(), "absolute": true(), "host": "www.example.org", "path": "/Dürst", "path-segments": ("", "Dürst"), "scheme": "http", "uri": "http://www.example.org/Dürst" } |
This example demonstrates the use of | |
Expression: | parse-uri("c|/path/to/file") |
Result: | { "filepath": "c:/path/to/file", "hierarchical": true(), "path": "/c:/path/to/file", "path-segments": ("", "c:", "path", "to", "file"), "scheme": "file", "uri": "c|/path/to/file" } |
This example demonstrates the use of | |
Expression: | parse-uri("file://c|/path/to/file") |
Result: | { "filepath": "c:/path/to/file", "hierarchical": true(), "absolute": true(), "path": "/c:/path/to/file", "path-segments": ("", "c:", "path", "to", "file"), "scheme": "file", "uri": "file://c|/path/to/file" } |
Constructs a URI from the parts provided.
fn:build-uri ( | ||
$parts | as uri-structure-record , | |
$options | as
| := {} |
) as
|
record uri-structure-record ( uri? as xs:string?, scheme? as xs:string?, absolute? as xs:boolean?, hierarchical? as xs:boolean?, authority? as xs:string?, userinfo? as xs:string?, host? as xs:string?, port? as xs:integer?, path? as xs:string?, query? as xs:string?, fragment? as xs:string?, path-segments? as xs:string*, query-parameters? as map(xs:string, xs:string*)?, filepath? as xs:string? )
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:
record( | |
allow-deprecated-features? | as xs:boolean , |
omit-default-ports? | as xs:boolean , |
unc-path? | as xs:boolean |
) |
Key | Meaning |
---|---|
| Indicates that deprecated URI features should be returned
|
| Indicates that a port number that is the same as the default port for a given scheme should be omitted.
|
| Indicates that the URI represents a Windows Universal Naming Convention Path.
|
The components are derived from the contents of the $parts
map. To simplify the description below, a value is considered to be present in the map if the relevant field exists and is non-empty.
If the scheme
key is present in the map, the URI begins with the value of that key. A URI is considered to be non-hierarchical if either the hierarchical
key is present in the $parts
map with the value false()
or if the scheme is known to be non-hierarchical. (In other words, schemes are hierarchical by default.)
If the scheme
is known to be non-hierarchical, it is delimited by a trailing :
.
Otherwise, if the scheme
is file
and the unc-path
option is true
, the scheme is delimited by a trailing :////
.
Otherwise, the scheme is delimited by a trailing ://
.
For simplicity of exposition, we take the userinfo
, host
, and port
values from the map and imagine they are stored in variables with the same name. If the key is not present in the map, the value of the variable is set to the empty sequence.
If $userinfo
is non-empty and contains a non-empty password, then $userinfo
is set to the empty sequence unless the allow-deprecated-features
option is true
.
If the omit-default-ports
option is true
then the $port
is set to the empty sequence if the port number is the same as the default port for the given scheme. Implementations 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.)
The fn:parse-uri
function removes percent-escaping when it constructs the path-segments
, query-parameters
, and fragment
properties. That’s often the most convenient behavior but, in order to reconstruct a URI from them, special escaping rules apply. These rules protect delimiters without encoding additional characters unnecessarily. The rules for path-segments
, query-parameters
, and fragment
are slightly different because the URI encoding conventions are slightly different in each case.
An application with more stringent requirements can construct a path
or query
that satisfies the requirements and leave the path-segments
and/or query-parameters
keys out of the map.
If the path-segments
key exists in the map, then the path is constructed from the segments. To construct the path, the possibly encoded segments are concatentated together, separated by /
(solidus) characters.
The rules for encoding the path segments are different for hierarchical and non-hierarchical URIs. If the URI is non-hierarchical, no encoding is performed on the segments. Otherwise, each segment is encoded by replacing any control characters (codepoints less than 0x20) and exclusively the following characters with their percent-escaped forms: (space)
%
(percent sign), /
(solidus), ?
(question mark), #
(number sign), +
(plus sign), [
(left square bracket), and ]
(right square bracket). That is “[#0-#20%/\?\#\+\[\]]
”.
Note:
Encoding is performed unless the URI is known to be non-hierarchical; in other words, encoding is the default. This heuristic improves the reliability of using fn:build-uri()
on the output of fn:parse-uri()
. (For example, fn:parse-uri('a+b/c') => fn:build-uri()
will return a+b/c
.)
It’s necessary to avoid encoding non-hierarchical schemes because there is more variation in them (for example, the tel:
scheme uses a “+
” that must not be encoded). Users working with non-hierarchical schemes may need to address the encoding issue directly bearing in mind the encoding requirements of the particular schemes in use.
Otherwise the value of the path
key is used.
If neither are present, 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.
To construct the string, each key and value is encoded. The encoding performed replaces any control characters (codepoints less than 0x20) and exclusively the following characters with their percent-escaped forms: (space)
%
(percent sign), =
(equals sign), &
(ampersand), #
(number sign), +
(plus sign), [
(left square bracket), and ]
(right square bracket). That is “[#0-#20%=&\#\+\[\]]
”. (This differs from the path encoding in that it excludes /
and ?
but includes =
and &
.) For each key and each value associated with that key in turn:
If the key is the empty string, the string constructed is the encoded value.
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 &
(ampersand) characters. If the query-parameters
key does not exist in the map, but the query
key does, then the query is the value of the query
key.
If there is a query, it is added to the URI with a preceding ?
(question mark).
If the fragment
key exists in the map, then the value of that key is encoded and added to the URI with a preceding hash mark (#
). The encoding performed replaces any control characters (codepoints less than 0x20) and exclusively the following characters with their percent-escaped forms: (space)
%
(percent sign), #
(number sign), +
(plus sign), [
(left square bracket), and ]
(right square bracket). That is “[#0-#20%\#\+\[\]]
”. (This differs from the path encoding in that it excludes /
and ?
.)
The resulting URI is returned.
Expression: | build-uri({ "scheme": "https", "host": "qt4cg.org", "port": (), "path": "/specifications/index.html" }) |
---|---|
Result: | "https://qt4cg.org/specifications/index.html" |
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 |
---|---|
| xs:boolean(1) |
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 |
---|---|
| xs:boolean(0) |
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:untypedAtomic
, xs:string
, xs:anyURI
, or a type derived from xs:string
or xs:anyURI
, fn:boolean
returns false
if the operand value has zero length; otherwise it returns true
.
If $input
is a singleton value of any numeric type or a type derived from a numeric type, fn:boolean
returns false
if the operand value is NaN
or is numerically equal to zero; otherwise it returns true
.
In all cases other than those listed above, fn:boolean
raises a type error [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
.
Variables | |
---|---|
let $abc := ("a", "b", "") |
Expression | Result |
---|---|
| true() |
| false() |
| false() |
| |
|
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 |
---|---|
| false() |
| true() |
| false() |
|
Operators are defined on the following type:
xs:duration
and on the two defined subtypes (see 8.1.1 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.
A value of type xs:duration
is considered to comprise two parts:
The total number of months, represented as a signed integer.
The total number of seconds, represented as a signed decimal number.
If one of these values is negative (less than zero), the other must not be positive (greater than zero).
In effect this means that operations on durations (including equality comparison, casting to string, and extraction of components) all treat the duration as normalized. The duration PT1M30S
(one minute and thirty seconds), for example, is precisely equivalent to the duration PT90S
(ninety seconds); these are different representations of the same value, and the result of any operation will be the same regardless which representation is used. For example, the function fn:seconds-from-duration
returns 30 in both cases.
Note:
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.
In an xs:yearMonthDuration
, the seconds component is always zero. In an xs:dayTimeDuration
, the months component is always zero.
All conforming processors must support duration values in which:
The total number of months can be represented as a signed xs:int
value;
The total number of seconds can be represented as a signed xs:decimal
value with facets totalDigits=18
and fractionalDigits=3
. That is, durations must be supported to millisecond precision.
Processors may support a greater range and/or precision. The limits are ·implementation-defined·.
A processor that limits the range or precision of duration values may encounter overflow and underflow conditions when it tries to evaluate operations on durations. In these situations, the processor must return a zero-length duration in case of duration underflow, and must raise a dynamic error [err:FODT0001] in case of overflow.
Similarly, a processor may be unable accurately to represent the result of dividing a duration by 2, or multiplying a duration by 0.5. A processor that limits the precision of the seconds component of duration values must deliver a result that is as close as possible to the mathematically precise result, given these limits; if two values are equally close, the one that is chosen is ·implementation-defined·.
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.1 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: | op:duration-equal( xs:duration("P1Y"), xs:duration("P12M") ) |
---|---|
Result: | true() |
Expression: | op:duration-equal( xs:duration("PT24H"), xs:duration("P1D") ) |
Result: | true() |
Expression: | op:duration-equal( xs:duration("P1Y"), xs:duration("P365D") ) |
Result: | false() |
Expression: | op:duration-equal( xs:yearMonthDuration("P0Y"), xs:dayTimeDuration("P0D") ) |
Result: | true() |
Expression: | op:duration-equal( xs:yearMonthDuration("P1Y"), xs:dayTimeDuration("P365D") ) |
Result: | false() |
Expression: | op:duration-equal( xs:yearMonthDuration("P2Y"), xs:yearMonthDuration("P24M") ) |
Result: | true() |
Expression: | op:duration-equal( xs:dayTimeDuration("P10D"), xs:dayTimeDuration("PT240H") ) |
Result: | true() |
Expression: | op:duration-equal( xs:duration("P2Y0M0DT0H0M0S"), xs:yearMonthDuration("P24M") ) |
Result: | true() |
Expression: | op:duration-equal( xs:duration("P0Y0M10D"), xs:dayTimeDuration("PT240H") ) |
Result: | true() |
The duration datatype may be considered to be a composite datatype in that it contains distinct properties or components. The extraction functions specified below extract a single component from a duration value. For xs:duration
and its subtypes, including the two subtypes xs:yearMonthDuration
and xs:dayTimeDuration
, the components are normalized: this means that the seconds and minutes components will always be less than 60, the hours component less than 24, and the months component less than 12.
Function | Meaning |
---|---|
fn:years-from-duration | Returns the number of years in a duration. |
fn:months-from-duration | Returns the number of months in a duration. |
fn:days-from-duration | Returns the number of days in a duration. |
fn:hours-from-duration | Returns the number of hours in a duration. |
fn:minutes-from-duration | Returns the number of minutes in a duration. |
fn:seconds-from-duration | Returns the number of seconds in a duration. |
Returns the number of years in a duration.
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: | years-from-duration( xs:yearMonthDuration("P20Y15M") ) |
---|---|
Result: | 21 |
Expression: | years-from-duration( xs:yearMonthDuration("-P15M") ) |
Result: | -1 |
Expression: | years-from-duration( xs:dayTimeDuration("-P2DT15H") ) |
Result: | 0 |
Expression: | years-from-duration( xs:duration("P1Y1000D") ) |
Result: | 1 (To capture whole portions of years reflected in the |
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: | months-from-duration( xs:yearMonthDuration("P20Y15M") ) |
---|---|
Result: | 3 |
Expression: | months-from-duration( xs:yearMonthDuration("-P20Y18M") ) |
Result: | -6 |
Expression: | months-from-duration( xs:dayTimeDuration("-P2DT15H0M0S") ) |
Result: | 0 |
Expression: | months-from-duration( xs:duration("P1M100D") ) |
Result: | 1 (To capture whole portions of months reflected in the |
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: | days-from-duration( xs:dayTimeDuration("P3DT10H") ) |
---|---|
Result: | 3 |
Expression: | days-from-duration( xs:dayTimeDuration("P3DT55H") ) |
Result: | 5 |
Expression: | days-from-duration( xs:yearMonthDuration("P3Y5M") ) |
Result: | 0 |
Expression: | days-from-duration( xs:duration("P1Y1D") ) |
Result: | 1 (To capture days reflected in the |
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: | hours-from-duration( xs:dayTimeDuration("P3DT10H") ) |
---|---|
Result: | 10 |
Expression: | hours-from-duration( xs:dayTimeDuration("P3DT12H32M12S") ) |
Result: | 12 |
Expression: | hours-from-duration( xs:dayTimeDuration("PT123H") ) |
Result: | 3 |
Expression: | hours-from-duration( xs:dayTimeDuration("-P3DT10H") ) |
Result: | -10 |
Expression: | hours-from-duration( xs:duration("P1YT1H") ) |
Result: | 1 (To capture hours reflected in the |
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: | minutes-from-duration( xs:dayTimeDuration("P3DT10H") ) |
---|---|
Result: | 0 |
Expression: | minutes-from-duration( xs:dayTimeDuration("-P5DT12H30M") ) |
Result: | -30 |
Expression: | minutes-from-duration( xs:duration("P1YT1M") ) |
Result: | 1 (To capture minutes reflected in the |
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: | seconds-from-duration( xs:dayTimeDuration("P3DT10H12.5S") ) |
---|---|
Result: | 12.5 |
Expression: | seconds-from-duration( xs:dayTimeDuration("-PT256S") ) |
Result: | -16.0 |
Expression: | seconds-from-duration( xs:duration("P1YT1S") ) |
Result: | 1 (To capture seconds reflected in the |
Expression: | seconds-from-duration( xs:duration("P1YT1S") ) |
Result: | 1 (To capture seconds reflected in the |
This section decribes the fn:seconds
function, which constructs an xs:dayTimeDuration
value representing a decimal number of seconds.
Function | Meaning |
---|---|
fn:seconds | Returns an xs:dayTimeDuration whose length is a given number of seconds. |
Returns an xs:dayTimeDuration
whose length is a given number of seconds.
fn:seconds ( | ||
$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:dayTimeDuration
value whose length in seconds is equal to $value
.
If $value
is negative then the result will be a negative duration.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
The result of seconds($n)
is approximately equal to the result of the expression xs:dayTimeDuration('PT1S') * $n
. The equivalence is only approximate, because seconds($n)
uses the exact xs:decimal
value supplied, whereas multiplying a duration by a number first promotes the number to an xs:double
value, which may lose precision.
Expression: | seconds(1) |
---|---|
Result: | xs:dayTimeDuration('PT1S') |
Expression: | seconds(0.001) |
Result: | xs:dayTimeDuration('PT0.001S') |
Expression: | seconds(60) |
Result: | xs:dayTimeDuration('PT1M') |
Expression: | seconds(86400) |
Result: | xs:dayTimeDuration('P1D') |
Expression: | seconds(-5400) |
Result: | xs:dayTimeDuration('-PT1H30M') |
Expression: | xs:dateTime('1970-01-01T00:00:00Z') + 1706702400 * seconds(1) |
Result: | xs:dateTime('2024-01-31T12:00:00Z') (The expression converts a Unix timestamp to an |
Expression: | ( xs:dateTime('2024-01-31T12:00:00Z') - xs:dateTime('1970-01-01T00:00:00Z') ) div seconds(1) |
Result: | 1706702400 (The expression converts an |
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 8.1.2 Limits and precision.
Either duration (and therefore the result) may be negative.
Expression: | op:add-yearMonthDurations( xs:yearMonthDuration("P2Y11M"), xs:yearMonthDuration("P3Y3M") ) |
---|---|
Result: | xs:yearMonthDuration("P6Y2M") |
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 8.1.2 Limits and precision.
Either duration (and therefore the result) may be negative.
Expression: | op:subtract-yearMonthDurations( xs:yearMonthDuration("P2Y11M"), xs:yearMonthDuration("P3Y3M") ) |
---|---|
Result: | xs:yearMonthDuration("-P4M") |
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, underflow, and rounding, see 8.1.2 Limits and precision.
A dynamic error is raised [err:FOCA0005] if $arg2
is NaN
.
Either duration (and therefore the result) may be negative.
Expression: | op:multiply-yearMonthDuration( xs:yearMonthDuration("P2Y11M"), 2.3 ) |
---|---|
Result: | xs:yearMonthDuration("P6Y9M") |
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, underflow, and rounding, see 8.1.2 Limits and precision.
A dynamic error is raised [err:FOCA0005] if $arg2
is NaN
.
Either operand (and therefore the result) may be negative.
Expression: | op:divide-yearMonthDuration( xs:yearMonthDuration("P2Y11M"), 1.5 ) |
---|---|
Result: | xs:yearMonthDuration("P1Y11M") |
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, underflow, and rounding, see 8.1.2 Limits and precision.
Either duration (and therefore the result) may be negative.
Expression: | op:divide-yearMonthDuration-by-yearMonthDuration( xs:yearMonthDuration("P3Y4M"), xs:yearMonthDuration("-P1Y4M") ) |
---|---|
Result: | -2.5 |
The following example demonstrates how to calculate the length of an | |
Expression: | op:divide-yearMonthDuration-by-yearMonthDuration( xs:yearMonthDuration("P3Y4M"), xs:yearMonthDuration("P1M") ) |
Result: | 40 |
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 8.1.2 Limits and precision.
Either duration (and therefore the result) may be negative.
Expression: | op:add-dayTimeDurations( xs:dayTimeDuration("P2DT12H5M"), xs:dayTimeDuration("P5DT12H") ) |
---|---|
Result: | xs:dayTimeDuration('P8DT5M') |
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 8.1.2 Limits and precision.
Either duration (and therefore the result) may be negative.
Expression: | op:subtract-dayTimeDurations( xs:dayTimeDuration("P2DT12H"), xs:dayTimeDuration("P1DT10H30M") ) |
---|---|
Result: | xs:dayTimeDuration('P1DT1H30M') |
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 8.1.2 Limits and precision.
For handling of overflow, underflow, and rounding, see 8.1.2 Limits and precision.
A dynamic error is raised [err:FOCA0005] if $arg2
is NaN
.
Either operand (and therefore the result) may be negative.
Expression: | op:multiply-dayTimeDuration( xs:dayTimeDuration("PT2H10M"), 2.1 ) |
---|---|
Result: | xs:dayTimeDuration('PT4H33M') |
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 8.1.2 Limits and precision.
For handling of overflow, underflow, and rounding, see 8.1.2 Limits and precision.
A dynamic error is raised [err:FOCA0005] if $arg2
is NaN
.
Either operand (and therefore the result) may be negative.
Expression: | op:divide-dayTimeDuration( xs:dayTimeDuration("P1DT2H30M10.5S"), 1.5 ) |
---|---|
Result: | xs:duration("PT17H40M7S") |
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, underflow, and rounding, see 8.1.2 Limits and precision.
Either operand (and therefore the result) may be negative.
Expression: | round-half-to-even( op:divide-dayTimeDuration-by-dayTimeDuration( xs:dayTimeDuration("P2DT53M11S"), xs:dayTimeDuration("P1DT10H") ), 4 ) |
---|---|
Result: | 1.4378 |
This examples shows how to determine the number of seconds in a duration. | |
Expression: | op:divide-dayTimeDuration-by-dayTimeDuration( xs:dayTimeDuration("P2DT53M11S"), xs:dayTimeDuration("PT1S") ) |
Result: | 175991.0 |
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.
[Definition] The eight primitive types xs:dateTime
, xs:date
, xs:time
, xs:gYearMonth
, xs:gYear
, xs:gMonthDay
, xs:gMonth
, xs:gDay
are referred to collectively as the Gregorian types.
This section describes operations on atomic items of these types.
Values of these types are modeled as comprising one or more of the seven components year, month, day, hour, minute, second, and timezone.
The only operations defined on xs:gYearMonth
, xs:gYear
, xs:gMonthDay
, xs:gMonth
and xs:gDay
values are equality comparison and component extraction. For other types, further operations are provided, including order comparisons, arithmetic, formatted display, and timezone adjustment.
All conforming processors must support year values in the range 1 to 9999, and a minimum fractional second precision of 1 millisecond or three digits (i.e., s.sss). However, 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 0 and years with negative values. The results of operations on dates that cross the year 0 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.
Similarly, a processor that limits the precision of the seconds component of date and time or duration values may need to deliver a rounded result for arithmetic operations. Such a processor must deliver a result that is as close as possible to the mathematically precise result, given these limits: if two values are equally close, the one that is chosen is ·implementation-defined·.
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, xs:dayTimeDuration("-PT5H") }
.
An xs:dateTime
with lexical representation 1999-12-31T24:00:00
is represented by { 2000, 1, 1, 0, 0, 0.0, () }
.
An xs:date
with lexical representation 2005-02-28+8:00
is represented by { 2005, 2, 28, (), (), (), xs:dayTimeDuration("PT8H") }
.
An xs:time
with lexical representation 24:00:00
is represented by { (), (), (), 0, 0, 0, () }
.
Function | Meaning |
---|---|
fn:dateTime | Returns an xs:dateTime value created by combining an xs:date and an xs:time . |
fn:unix-dateTime | Returns a dateTime value for a Unix time. |
Returns an xs:dateTime
value created by combining an xs:date
and an xs:time
.
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") ) | xs:dateTime("1999-12-31T12:00:00") |
dateTime( xs:date("1999-12-31"), xs:time("24:00:00") ) | xs:dateTime("1999-12-31T00:00:00") (This is because |
Returns a dateTime value for a Unix time.
fn:unix-dateTime ( | ||
$value | as
| := 0 |
) as
|
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns a dateTime value in UTC timezone for the Unix time specified by $value
in milliseconds. If the value is absent or an empty sequence, 0
is used. The Unix time is defined in [IEEE 1003.1-2024].
If the implementation supports data types from XSD 1.1 then the returned value will be an instance of xs:dateTimeStamp
. Otherwise, the only guarantees are that it will be an instance of xs:dateTime
and will have a timezone component.
The effect of the function is equivalent to the result of the following XPath expression.
xs:dateTime('1970-01-01T00:00:00Z') + ($value otherwise 0) * seconds(0.001)
By calling this convenience function, it can be ensured that the correct timezone is used for computing the Unix time.
Note that Unix time does not account for leap seconds. It assumes that every day has 86,400 seconds.
Expression: | unix-dateTime() |
---|---|
Result: | xs:dateTime('1970-01-01T00:00:00Z') |
Expression: | unix-dateTime(1) |
Result: | xs:dateTime('1970-01-01T00:00:00.001Z') |
Expression: | unix-dateTime(86400000) |
Result: | xs:dateTime('1970-01-02T00:00:00Z') |
Calculate the Unix time associated with a | |
let $value := current-dateTime() return ($value - unix-dateTime()) div seconds(0.001) |
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
.
Assume that the dynamic context provides an implicit timezone value of | |
Expression: | op:dateTime-equal( xs:dateTime("2002-04-02T12:00:00-01:00"), xs:dateTime("2002-04-02T17:00:00+04:00") ) |
---|---|
Result: | true() |
Expression: | op:dateTime-equal( xs:dateTime("2002-04-02T12:00:00"), xs:dateTime("2002-04-02T23:00:00+06:00") ) |
Result: | true() |
Expression: | op:dateTime-equal( xs:dateTime("2002-04-02T12:00:00"), xs:dateTime("2002-04-02T17:00:00") ) |
Result: | false() |
Expression: | op:dateTime-equal( xs:dateTime("2002-04-02T12:00:00"), xs:dateTime("2002-04-02T12:00:00") ) |
Result: | true() |
Expression: | op:dateTime-equal( xs:dateTime("2002-04-02T23:00:00-04:00"), xs:dateTime("2002-04-03T02:00:00-01:00") ) |
Result: | true() |
Expression: | op:dateTime-equal( xs:dateTime("1999-12-31T24:00:00"), xs:dateTime("2000-01-01T00:00:00") ) |
Result: | true() |
Expression: | op:dateTime-equal( xs:dateTime("2005-04-04T24:00:00"), xs:dateTime("2005-04-04T00:00:00") ) |
Result: | false() |
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") ) | false() (The starting instants are |
op:date-equal( xs:date("2004-12-25-12:00"), xs:date("2004-12-26+12:00") ) | true() |
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") ) | true() |
op:date-less-than( xs:date("2004-12-25-12:00"), xs:date("2004-12-26+12:00") ) | false() |
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") ) | false() (Using the reference date components the starting instants are |
op:time-equal( xs:time("21:30:00+10:30"), xs:time("06:00:00-05:00") ) | true() |
op:time-equal( xs:time("24:00:00+01:00"), xs:time("00:00:00+01:00") ) | true() (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") ) | false() |
op:time-less-than( xs:time("11:00:00"), xs:time("17:00:00Z") ) | true() |
op:time-less-than( xs:time("23:59:59"), xs:time("24:00:00") ) | false() |
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") ) | true() |
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