The presentation of this document has been augmented to identify changes from the version 3.1 Recommendation published on 21 March 2017. Three kinds of changes are highlighted: new, added text, changed text, and deleted text.


W3C

XPath and XQuery Functions and Operators 4.0

W3C Editor's Draft 22 October 2024

This version:
https://qt4cg.org/pr/1521/xpath-functions-40/
Latest version of XPath and XQuery Functions and Operators 4.0:
https://qt4cg.org/specifications/xpath-functions-40/
Most recent Recommendation of XPath and XQuery Functions and Operators:
https://www.w3.org/TR/2017/REC-xpath-functions-31-20170321/
Editor:
Michael Kay, Saxonica <http://www.saxonica.com/>

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.


Abstract

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.

Status of this Document

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.


1 Introduction

Changes in 4.0 

  1. Use the arrows to browse significant changes since the 3.1 version of this specification.

  2. 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:

[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].

1.1 Operators

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.

1.2 Conformance

Changes in 4.0  

  1. Higher-order functions are no longer an optional feature.  [Issue 205 PR 326 1 February 2023]

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.

1.3 Namespaces and prefixes

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 xs:numeric,
    $arg2 as xs:numeric
    ) as xs:numeric

    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.

1.4 Function overloading

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.

1.5 Function signatures and descriptions

Each function (or group of functions having the same name) is defined in this specification using a standard proforma. This has the following sections:

1.5.1 Function name

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.

1.5.2 Function summary

The first section in the proforma is a short summary of what the function does. This is intended to be informative rather than normative.

1.5.3 Function signature

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 parameter-type,
$... as 
) as return-type

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.

1.5.4 Function rules

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.

1.5.5 Formal Specification

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:

  1. 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.

  2. 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.

1.5.6 Notes

Where the proforma includes a section headed Notes, these are non-normative.

1.5.7 Examples

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.

1.6 Function calls

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).

  1. Subtype Substitution: A derived type may substitute for its base type. In particular, xs:integer may be used where xs:decimal is expected.

  2. 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.

  3. 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 parameter-type
) as return-type?

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 xs:double*
) as xs:double?

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".

1.7 Options

Changes in 4.0  

  1. Use of an option keyword that is not defined in the specification and is not known to the implementation now results in a dynamic error; previously it was ignored.   [Issue 1019 PR 1059 26 March 2024]

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:

  1. 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.

  2. The type of the options parameter in the function signature is always given as map(*).

  3. 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.

  4. 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.

  5. If an option is present whose key is not described in the specification, then a type error [err:XPTY0004]XP must 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.

  6. 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.

  7. 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.

  8. 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.

  9. 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.

1.8 Type System

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.

1.8.1 Item Types

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)

1.8.2 Schema Type Hierarchy

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)

          • 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)

1.8.3 Atomic Type Hierarchy

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

1.9 Terminology

Changes in 4.0  

  1. The term atomic value has been replaced by atomic item.   [Issue 1337 PR 1361 2 August 2024]

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.

1.9.1 Atomic items

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.

1.9.2 Strings, characters, and codepoints

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.

1.9.3 Namespaces and URIs

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.

1.9.4 Conformance terminology

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.

1.9.5 Properties of functions

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:

  1. 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.

  2. Both items are nodes, and represent the same node.

  3. 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·.

  4. Both items are arrays, both arrays have the same number of members, and the members are pairwise ·identical·.

  5. 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.

Context-dependent functions fall into a number of categories:

  1. The functions fn:current-date, fn:current-dateTime, fn:current-time, fn:default-language, fn:implicit-timezone, fn:adjust-date-to-timezone, fn:adjust-dateTime-to-timezone, and fn:adjust-time-to-timezone depend on properties of the dynamic context that are fixed within the ·execution scope·. The same applies to a number of functions in the op: namespace that manipulate dates and times and that make use of the implicit timezone. These functions will return the same result if called repeatedly during a single ·execution scope·.

  2. A number of functions including fn:base-uri#0, fn:data#0, fn:document-uri#0, fn:element-with-id#1, fn:id#1, fn:idref#1, fn:lang#1, fn:last#0, fn:local-name#0, fn:name#0, fn:namespace-uri#0, fn:normalize-space#0, fn:number#0, fn:path#0, fn:position#0, fn:root#0, fn:string#0, and fn:string-length#0 depend on the focusXP31. These functions will in general return different results on different calls if the focus is different.

    A function is focus-dependent if its result depends on the focusXP31 (that is, the context value, position, or size).

    A function that is not ·focus-dependent· is called focus-independent

  3. The function fn:default-collation and many string-handling operators and functions depend on the default collation and the in-scope collations, which are both properties of the static context. If a particular call of one of these functions is evaluated twice with the same arguments then it will return the same result each time (because the static context, by definition, does not change at run time). However, two distinct calls (that is, two calls on the function appearing in different places in the source code) may produce different results even if the explicit arguments are the same.

  4. Functions such as fn:static-base-uri, fn:doc, and fn:collection depend on other aspects of the static context. As with functions that depend on collations, a single call will produce the same results on each call if the explicit arguments are the same, but two calls appearing in different places in the source code may produce different results.

The fn: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] For a ·context-dependent· function, the parts of the context on which it depends are referred to as implicit arguments.

[Definition] A function that is guaranteed to produce ·identical· results from repeated calls within a single ·execution scope· if the explicit and ·implicit· arguments are identical is referred to as deterministic.

[Definition] A function that is not ·deterministic· is referred to as nondeterministic.

All functions defined in this specification are ·deterministic· unless otherwise stated. Exceptions include the following:

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.

2 Functions on nodes and node sequences

2.1 Accessors

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.

2.1.1 fn:node-name

Summary

Returns the name of a node, as an xs:QName.

Signature
fn:node-name(
$node as node()? := .
) as xs:QName?
Properties

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·.

Rules

If the argument is omitted, it defaults to the context value (.). The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

If $node is the empty sequence, the empty sequence is returned.

Otherwise, the function returns the result of the dm:node-name accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 4.10 node-name AccessorDM40).

Error Conditions

The following errors may be raised when $node is omitted:

Notes

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.

Examples
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
node-name($e//*[@id = 'alpha'])
QName("", "p")
node-name($e//*[@id = 'gamma'])
QName("http://example.com/ns", "p")
node-name($e//*[@id = 'delta'])
QName("http://example.com/ns", "ex:p")
node-name($e//processing-instruction())
QName("", "pi")
node-name($e//*[@id = 'alpha']/text())
()
node-name($e//*[@id = 'alpha']/@id)
QName("", "id")
node-name($e//*[@id = 'alpha']/@xml:id)
xs:QName("xml:id")

2.1.2 fn:nilled

Summary

Returns true for an element that is nilled.

Signature
fn:nilled(
$node as node()? := .
) as xs:boolean?
Properties

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·.

Rules

If the argument is omitted, it defaults to the context value (.). The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

If $node is the empty sequence, the function returns the empty sequence.

Otherwise the function returns the result of the dm:nilled accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 4.8 nilled AccessorDM40).

Error Conditions

The following errors may be raised when $node is omitted:

Notes

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].

2.1.3 fn:string

Summary

Returns the value of $value represented as an xs:string.

Signature
fn:string(
$value as item()? := .
) as xs:string
Properties

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·.

Rules

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).

Error Conditions

The following errors may be raised when $value is omitted:

A type error is raised [err:FOTY0014] if $value is a function item (this includes maps and arrays).

Notes

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.

Examples
Variables
let $para := <para>There lived a <term author="Tolkien">hobbit</term>.</para>
Expression Result
string(23)
"23"
string(false())
"false"
string("Paris")
"Paris"
string((1, 2, 3))

Raises error XPTY0004.

string([ [ 1, 2 ], [ 3, 4 ] ])

Raises error FOTY0014.

string(abs#1)

Raises error FOTY0014.

string($para)
"There lived a hobbit."

2.1.4 fn:data

Summary

Returns the result of atomizing a sequence. This process flattens arrays, and replaces nodes by their typed values.

Signature
fn:data(
$input as item()* := .
) as xs:anyAtomicType*
Properties

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·.

Rules

If the argument is omitted, it defaults to the context value (.). The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

The result of fn:data is the sequence of atomic 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.

Error Conditions

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.

Notes

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.

Examples
Variables
let $para := <para>There lived a <term author="Tolkien">hobbit</term>.</para>
Expression Result
data(123)
123
data((123, 456))
123, 456
data([ [ 1, 2 ], [ 3, 4 ] ])
1, 2, 3, 4
data($para)
xs:untypedAtomic("There lived a hobbit.")
data($para/term/@author)
xs:untypedAtomic("Tolkien")
data(abs#1)

Raises error FOTY0013.

2.1.5 fn:base-uri

Summary

Returns the base URI of a node.

Signature
fn:base-uri(
$node as node()? := .
) as xs:anyURI?
Properties

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·.

Rules

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:

  1. If $node is the empty sequence, the function returns the empty sequence.

  2. 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.

Error Conditions

The following errors may be raised when $node is omitted:

2.1.6 fn:document-uri

Changes in 4.0  

  1. The constraints on the result of the function have been relaxed.  [Issues 898 1161 PR 1265 2 July 2024]

Summary

Returns the URI of a resource where a document can be found, if available.

Signature
fn:document-uri(
$node as node()? := .
) as xs:anyURI?
Properties

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·.

Rules

If the argument is omitted, it defaults to the context value (.). The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

If $node is the empty sequence, the function returns the empty sequence.

If $node is not a document node, the function returns the empty sequence.

Otherwise, the function returns the value of the document-uri accessor applied to $node, as defined in [XQuery and XPath Data Model (XDM) 3.1] (See Section 5.1.2 AccessorsDM40).

Error Conditions

The following errors may be raised when $node is omitted:

Notes

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.

2.2 Other functions on nodes

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).

2.2.1 fn:name

Summary

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.

Signature
fn:name(
$node as node()? := .
) as xs:string
Properties

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·.

Rules

If the argument is omitted, it defaults to the context value (.). The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

If 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)).

Error Conditions

The following errors may be raised when $node is omitted:

Notes

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).

Examples
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
name($e//*[@id = 'alpha'])
"p"
name($e//*[@id = 'gamma'])
"p"
name($e//*[@id = 'delta'])
"ex:p"
name($e//processing-instruction())
"pi"
name($e//*[@id = 'alpha']/text())
""
name($e//*[@id = 'alpha']/@id)
"id"
name($e//*[@id = 'alpha']/@xml:id)
"xml:id"

2.2.2 fn:local-name

Summary

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.

Signature
fn:local-name(
$node as node()? := .
) as xs:string
Properties

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·.

Rules

If the argument is omitted, it defaults to the context value (.). The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

If 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.

Error Conditions

The following errors may be raised when $node is omitted:

Examples
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
local-name($e//*[@id = 'alpha'])
"p"
local-name($e//*[@id = 'gamma'])
"p"
local-name($e//*[@id = 'delta'])
"p"
local-name($e//processing-instruction())
"pi"
local-name($e//*[@id = 'alpha']/text())
""
local-name($e//*[@id = 'alpha']/@id)
"id"
local-name($e//*[@id = 'alpha']/@xml:id)
"id"

2.2.3 fn:namespace-uri

Summary

Returns the namespace URI part of the name of $node, as an xs:anyURI value.

Signature
fn:namespace-uri(
$node as node()? := .
) as xs:anyURI
Properties

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·.

Rules

If the argument is omitted, it defaults to the context node (.). 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 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.

Error Conditions

The following errors may be raised when $node is omitted:

Examples
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
namespace-uri($e//*[@id = 'alpha'])
""
namespace-uri($e//*[@id = 'gamma'])
"http://example.com/ns"
namespace-uri($e//*[@id = 'delta'])
"http://example.com/ns"
namespace-uri($e//processing-instruction())
""
namespace-uri($e//*[@id = 'alpha']/text())
""
namespace-uri($e//*[@id = 'alpha']/@id)
""
namespace-uri($e//*[@id = 'alpha']/@xml:id)
"http://www.w3.org/XML/1998/namespace"

2.2.4 fn:lang

Summary

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.

Signature
fn:lang(
$language as xs:string?,
$node as node() := .
) as xs:boolean
Properties

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·.

Rules

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:

  1. $language is equal to the string-value of the relevant xml:lang attribute, or

  2. $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).

Error Conditions

The following errors may be raised when $node is omitted:

Examples

The expression fn:lang("en") would return true if the context node were any of the following four elements:

  • <para xml:lang="en"/>

  • <div xml:lang="en"><para>And now, and forever!</para></div>

  • <para xml:lang="EN"/>

  • <para xml:lang="en-us"/>

The expression fn:lang("fr") would return false if the context node were <para xml:lang="EN"/>

2.2.5 fn:root

Summary

Returns the root of the tree to which $node belongs. This will usually, but not necessarily, be a document node.

Signature
fn:root(
$node as node()? := .
) as node()?
Properties

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·.

Rules

If the function is called without an argument, the context value (.) is used as the default argument. The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

The function returns the value of the expression ($arg/ancestor-or-self::node())[1].

Error Conditions

The following errors may be raised when $node is omitted:

Examples

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"/>

root($i) returns the element node $i

root($o/quantity) returns the element node $o

root($odoc//quantity) returns the document node $odoc

root($newi) returns the element node $o

The final three examples could be made type-safe by wrapping their operands with exactly-one().

2.2.6 fn:path

Summary

Returns a path expression that can be used to select the supplied node relative to the root of its containing document.

Signature
fn:path(
$node as node()? := .
) as xs:string?
Properties

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·.

Rules

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:

  1. 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.

  2. For an attribute node:

    1. if the node is in no namespace, @local, where local is the local part of the node name

    2. otherwise, @Q{uri}local, where uri is the namespace URI of the node name, and local is the local part of the node name

  3. For a text node: text()[position] where position is an integer representing the position of the selected node among its text node siblings

  4. For a comment node: comment()[position] where position is an integer representing the position of the selected node among its comment node siblings

  5. 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

  6. For a namespace node:

    1. 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).

    2. 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() = ""]

Error Conditions

The following errors may be raised when $node is omitted:

Examples
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:

path($e)

Result:
'/'
Expression:

path($e/*:p)

Result:
'/Q{http://example.com/one}p[1]'
Expression:

path($e/*:p/@xml:lang)

Result:
'/Q{http://example.com/one}p[1]/@Q{http://www.w3.org/XML/1998/namespace}lang'
Expression:

path($e/*:p/@author)

Result:
'/Q{http://example.com/one}p[1]/@author'
Expression:

path($e/*:p/*:br[2])

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:

path($emp)

Result:
'Q{http://www.w3.org/2005/xpath-functions}root()'
Expression:

path($emp/@xml:id)

Result:
'Q{http://www.w3.org/2005/xpath-functions}root()/@Q{http://www.w3.org/XML/1998/namespace}id'
Expression:

path($emp/empnr)

Result:
'Q{http://www.w3.org/2005/xpath-functions}root()/Q{}empnr[1]'

2.2.7 fn:has-children

Summary

Returns true if the supplied node has one or more child nodes (of any kind).

Signature
fn:has-children(
$node as node()? := .
) as xs:boolean
Properties

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·.

Rules

If the argument is omitted, it defaults to the context value (.). The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

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()).

Error Conditions

The following errors may be raised when $node is omitted:

Notes

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.

Examples
Variables
let $e := <doc>
  <p id="alpha">One</p>
  <p/>
  <p>Three</p>
  <?pi 3.14159?>
</doc>
Expression Result
has-children($e)
true()
has-children($e//p[1])
true()
has-children($e//p[2])
false()
has-children($e//p[3])
true()
has-children($e//processing-instruction())
false()
has-children($e//p[1]/text())
false()
has-children($e//p[1]/@id)
false()

2.3 Functions on sequences of nodes

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.

2.3.1 fn:distinct-ordered-nodes

Changes in 4.0  

  1. New in 4.0  [Issue 1189 PR 1191 14 May 2024]

Summary

Removes duplicate nodes and sorts the input into document order.

Signature
fn:distinct-ordered-nodes(
$nodes as node()*
) as node()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Any duplicate nodes in the input (based on node identity) are discarded. The remaining nodes are returned in document orderXP40.

Notes

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.

Examples
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 $x//b expressions select the same node; one of these is eliminated as a duplicate. The $x//c expression selects two nodes that have distinct identity, so both are retained.)

2.3.2 fn:innermost

Summary

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.

Signature
fn:innermost(
$nodes as node()*
) as node()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples

If the source document contains nested sections represented by div elements, the expression innermost(//div) returns those div elements that do not contain further div elements.

2.3.3 fn:outermost

Summary

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.

Signature
fn:outermost(
$nodes as node()*
) as node()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples

If the source document contains nested sections represented by div elements, the expression outermost(//div) returns those div elements that are not contained within further div elements.

3 Errors and diagnostics

3.1 Raising errors

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.

3.1.1 fn:error

Changes in 4.0  

  1. All three arguments are now optional, and each argument can be set to an empty sequence. Previously if $description was supplied, it could not be empty.  [Issue 895 PR 901 16 December 2023]

Summary

Calling the fn:error function raises an application-defined error.

Signature
fn:error(
$code as xs:QName? := (),
$description as xs:string? := (),
$value as item()* := .
) as item()*
Properties

This function is ·nondeterministic·, ·context-independent·, and ·focus-independent·.

Rules

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·.

Error Conditions

This function always raises a dynamic error. By default, it raises [err:FOER0000]

Notes

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.

Examples
Expression:

error()

Result:

Raises error FOER0000.

(This returns the URI http://www.w3.org/2005/xqt-errors#FOER0000 (or the corresponding xs:QName) to the external processing environment, unless the error is caught using a try/catch construct in the host language.)

Expression:
error(
  QName('http://www.example.com/HR', 'myerr:toohighsal'),
  'Salary is too high'
)
Result:

Raises error myerr:toohighsal.

(This returns http://www.example.com/HR#toohighsal and the xs:string "Salary is too high" (or the corresponding xs:QName) to the external processing environment, unless the error is caught using a try/catch construct in the host language.)

3.2 Diagnostic tracing

3.2.1 fn:trace

Changes in 4.0  

  1. The $label argument can now be set to an empty sequence. Previously if $label was supplied, it could not be empty.  [Issue 895 PR 901 16 December 2023]

Summary

Provides an execution trace intended to be used in debugging queries.

Signature
fn:trace(
$input as item()*,
$label as xs:string? := ()
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

If the trace information is unrelated to a specific value, fn:message can be used instead.

Examples

Consider a situation in which a user wants to investigate the actual value passed to a function. Assume that in a particular execution, $v is an xs:decimal with value 124.84. Writing fn:trace($v, 'the value of $v is:') will return $v. The processor may output "124.84" and "the value of $v is:" to an ·implementation-defined· destination.

The following two XPath expressions are identical, but only the second provides trace feedback to the user:

  • //book[xs:decimal(@price) gt 100]

  • //book[xs:decimal(@price) gt 100] => trace('books more expensive than €100:')

3.2.2 fn:message

Changes in 4.0  

  1. New in 4.0  [Issues 574 651 PRs 629 803 7 November 2023]

Summary

Outputs trace information and discards the result.

Signature
fn:message(
$input as item()*,
$label as xs:string? := ()
) as empty-sequence()
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples

The following two XPath expressions are identical, but only the second logs any feedback:

  • //book[xs:decimal(@price) lt 1000]

  • //book[if (xs:decimal(@price) lt 1000) then true() else message(@price, @title || ' is unexpectedly expensive: ')]

3.2.3 fn:stack-trace

Changes in 4.0  

  1. New in 4.0  [ PR 1074 26 March 2024]

Summary

Returns implementation-dependent information about the current state of execution.

Signature
fn:stack-trace() as xs:string
Properties

This function is ·nondeterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

The function will typically be called to assist in diagnosing dynamic errors.

4 Functions and operators on numerics

This section specifies arithmetic operators on the numeric datatypes defined in [XML Schema Part 2: Datatypes Second Edition].

4.1 Numeric types

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.

4.2 Arithmetic operators on numeric values

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.

4.2.1 op:numeric-add

Summary

Returns the arithmetic sum of its operands: ($arg1 + $arg2).

Operator Mapping

Defines the semantics of the + operator when applied to two numeric values

Signature
op:numeric-add(
$arg1 as xs:numeric,
$arg2 as xs:numeric
) as xs:numeric
Rules

General rules: see 4.2 Arithmetic operators on numeric values.

Notes

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.

4.2.2 op:numeric-subtract

Summary

Returns the arithmetic difference of its operands: ($arg1 - $arg2).

Operator Mapping

Defines the semantics of the - operator when applied to two numeric values.

Signature
op:numeric-subtract(
$arg1 as xs:numeric,
$arg2 as xs:numeric
) as xs:numeric
Rules

General rules: see 4.2 Arithmetic operators on numeric values.

Notes

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.

4.2.3 op:numeric-multiply

Summary

Returns the arithmetic product of its operands: ($arg1 * $arg2).

Operator Mapping

Defines the semantics of the * operator when applied to two numeric values.

Signature
op:numeric-multiply(
$arg1 as xs:numeric,
$arg2 as xs:numeric
) as xs:numeric
Rules

General rules: see 4.2 Arithmetic operators on numeric values.

Notes

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.

4.2.4 op:numeric-divide

Summary

Returns the arithmetic quotient of its operands: ($arg1 div $arg2).

Operator Mapping

Defines the semantics of the div operator when applied to two numeric values.

Signature
op:numeric-divide(
$arg1 as xs:numeric,
$arg2 as xs:numeric
) as xs:numeric
Rules

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.

Error Conditions

A dynamic error is raised [err:FOAR0001] for xs:decimal and xs:integer operands, if the divisor is (positive or negative) zero.

Notes

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.

4.2.5 op:numeric-integer-divide

Summary

Performs an integer division.

Operator Mapping

Defines the semantics of the idiv operator when applied to two numeric values.

Signature
op:numeric-integer-divide(
$arg1 as xs:numeric,
$arg2 as xs:numeric
) as xs:integer
Rules

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.

Error Conditions

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.

Notes

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++.

Examples
Expression Result
op:numeric-integer-divide(10, 3)
3
op:numeric-integer-divide(3, -2)
-1
op:numeric-integer-divide(-3, 2)
-1
op:numeric-integer-divide(-3, -2)
1
op:numeric-integer-divide(9.0, 3)
3
op:numeric-integer-divide(-3.5, 3)
-1
op:numeric-integer-divide(3.0, 4)
0
op:numeric-integer-divide(3.1E1, 6)
5
op:numeric-integer-divide(3.1E1, 7)
4

4.2.6 op:numeric-mod

Summary

Returns the remainder resulting from dividing $arg1, the dividend, by $arg2, the divisor.

Operator Mapping

Defines the semantics of the mod operator when applied to two numeric values.

Signature
op:numeric-mod(
$arg1 as xs:numeric,
$arg2 as xs:numeric
) as xs:numeric
Rules

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.

Error Conditions

A dynamic error is raised [err:FOAR0001] for xs:integer and xs:decimal operands, if $arg2 is zero.

Examples
Expression Result
op:numeric-mod(10, 3)
1
op:numeric-mod(6, -2)
0
op:numeric-mod(4.5, 1.2)
0.9
op:numeric-mod(1.23E2, 0.6E1)
3.0E0

4.2.7 op:numeric-unary-plus

Summary

Returns its operand with the sign unchanged: (+ $arg).

Operator Mapping

Defines the semantics of the unary + operator applied to a numeric value.

Signature
op:numeric-unary-plus(
$arg as xs:numeric
) as xs:numeric
Rules

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.

Notes

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.

4.2.8 op:numeric-unary-minus

Summary

Returns its operand with the sign reversed: -$arg.

Operator Mapping

Defines the semantics of the unary - operator when applied to a numeric value.

Signature
op:numeric-unary-minus(
$arg as xs:numeric
) as xs:numeric
Rules

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.

4.3 Comparison operators on numeric values

Changes in 4.0  

  1. Deleted an inaccurate statement concerning the behavior of NaN.  [Issue 473 PR 482]

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.

4.3.1 op:numeric-equal

Summary

Returns true if and only if the value of $arg1 is equal to the value of $arg2.

Operator Mapping

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.

Signature
op:numeric-equal(
$arg1 as xs:numeric,
$arg2 as xs:numeric
) as xs:boolean
Rules

General rules: see 4.2 Arithmetic operators on numeric values and 4.3 Comparison operators on numeric values.

Notes

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.

4.3.2 op:numeric-less-than

Summary

Returns true if and only if $arg1 is numerically less than $arg2.

Operator Mapping

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.

Signature
op:numeric-less-than(
$arg1 as xs:numeric,
$arg2 as xs:numeric
) as xs:boolean
Rules

General rules: see 4.2 Arithmetic operators on numeric values and 4.3 Comparison operators on numeric values.

Notes

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.

4.4 Functions on numeric values

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.

4.4.1 fn:abs

Summary

Returns the absolute value of $value.

Signature
fn:abs(
$value as xs:numeric?
) as xs:numeric?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples
Expression Result
abs(10.5)
10.5
abs(-10.5)
10.5
abs(-math:log(0))
xs:double('INF')

4.4.2 fn:ceiling

Summary

Rounds $value upwards to a whole number.

Signature
fn:ceiling(
$value as xs:numeric?
) as xs:numeric?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples
Expression Result
ceiling(10.5)
11
ceiling(-10.5)
-10
ceiling(math:log(0))
-xs:double('INF')

4.4.3 fn:floor

Summary

Rounds $value downwards to a whole number.

Signature
fn:floor(
$value as xs:numeric?
) as xs:numeric?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples
Expression Result
floor(10.5)
10
floor(-10.5)
-11
math:log(0) => floor()
-xs:double('INF')

4.4.4 fn:round

Changes in 4.0  

  1. A third argument has been added, providing control over the rounding mode.  [Issues 1187 1274 PRs 1260 1275 11 June 2024]

Summary

Rounds a value to a specified number of decimal places, with control over how the rounding takes place.

Signature
fn:round(
$value as xs:numeric?,
$precision as xs:integer? := 0,
$mode as enum('floor', 'ceiling', 'toward-zero', 'away-from-zero', 'half-to-floor', 'half-to-ceiling', 'half-toward-zero', 'half-away-from-zero', 'half-to-even')? := 'half-to-ceiling'
) as xs:numeric?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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 Modes
Rounding Mode Meaning

'floor'

Returns L.

'ceiling'

Returns U.

'toward-zero'

Returns L if $value is positive, otherwise U.

'away-from-zero'

Returns U if $value is positive, otherwise L

'half-to-floor'

Returns N, unless midway, in which case L.

'half-to-ceiling'

Returns N, unless midway, in which case U. This is the default.

'half-toward-zero'

Returns N, unless midway, in which case it returns L if $value is positive, otherwise U.

'half-away-from-zero'

Returns N, unless midway, in which case it returns U if $value is positive, otherwise L.

'half-to-even'

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:

  1. If $value is NaN, positive or negative zero, or positive or negative infinity, then the result is the same as the argument.

  2. 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.

Notes

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).

Examples
Expression Result
round(2.5)
3.0
round(2.4999)
2.0
round(-2.5)
-2.0
round(1.125, 2)
1.13
round(8452, -2)
8500
round(3.1415e0, 2)
3.14e0
math:log(0) => round()
-xs:double('INF')
round(1.7, 0, "floor")
1
round(-1.7, 0, "floor")
-2
round(1.7, 0, "ceiling")
2
round(-1.7, 0, "ceiling")
-1
round(1.7, 0, "toward-zero")
1
round(-1.7, 0, "toward-zero")
-1
round(1.7, 0, "away-from-zero")
2
round(-1.7, 0, "away-from-zero")
-2
round(1.125, 2, "half-to-floor")
1.12
round(-1.125, 2, "half-to-floor")
-1.13
round(1.125, 2, "half-to-ceiling")
1.13
round(-1.125, 2, "half-to-ceiling")
-1.12
round(1.125, 2, "half-toward-zero")
1.12
round(-1.125, 2, "half-toward-zero")
-1.12
round(1.125, 2, "half-away-from-zero")
1.13
round(-1.125, 2, "half-away-from-zero")
-1.13
round(1.125, 2, "half-to-even")
1.12
round(-1.125, 2, "half-to-even")
-1.12

4.4.5 fn:round-half-to-even

Summary

Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near.

Signature
fn:round-half-to-even(
$value as xs:numeric?,
$precision as xs:integer? := 0
) as xs:numeric?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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:

  1. If the argument is NaN, positive or negative zero, or positive or negative infinity, then the result is the same as the argument.

  2. 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.

Notes

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".

Examples
Expression Result
round-half-to-even(0.5)
0.0
round-half-to-even(1.5)
2.0
round-half-to-even(2.5)
2.0
round-half-to-even(3.567812e+3, 2)
3567.81e0
round-half-to-even(4.7564e-3, 2)
0.0e0
round-half-to-even(35612.25, -2)
35600
math:log(0) => round-half-to-even()
-xs:double('INF')

4.4.6 fn:is-NaN

Changes in 4.0  

  1. New in 4.0  [  20 September 2022]

Summary

Returns true if the argument is the xs:float or xs:double value NaN.

Signature
fn:is-NaN(
$value as xs:anyAtomicType
) as xs:boolean
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns true if the argument is the xs:float or xs:double value NaN; otherwise it returns false.

Examples
Expression Result
is-NaN(23)
false()
is-NaN("NaN")
false()
is-NaN(number("twenty-three"))
true()
is-NaN(math:sqrt(-1))
true()

4.5 Parsing numbers

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.

4.5.1 fn:number

Summary

Returns the value indicated by $value or, if $value is not specified, the context value after atomization, converted to an xs:double.

Signature
fn:number(
$value as xs:anyAtomicType? := .
) as xs:double
Properties

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·.

Rules

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.

Error Conditions

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.

Notes

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.

Examples
Variables
let $e := <e price="12.1" discount="NONE"/>
Expression Result
number(12)
1.2e1
number('12')
1.2e1
number('INF')
xs:double('INF')
number('NaN')
xs:double('NaN')
number('non-numeric')
xs:double('NaN')
number($e/@price)
1.21e1
number($e/@discount)
xs:double('NaN')
number($e/@misspelt)
xs:double('NaN')
("10", "11", "12") ! number()
1.0e1, 1.1e1, 1.2e1

4.5.2 fn:parse-integer

Changes in 4.0  

  1. New in 4.0  [Issue 241 PR 434 25 April 2023]

Summary

Converts a string to an integer, recognizing any radix in the range 2 to 36.

Signature
fn:parse-integer(
$value as xs:string?,
$radix as xs:integer? := 10
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Formal Specification

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-value := translate($value, "_ 	

", "")
let $digits := translate($preprocessed-value, "+-", "")
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-value, "-")) then -$abs else +$abs
Error Conditions

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.

Notes

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.

Examples
Expression:

parse-integer(" 200 ")

Result:
200
Expression:

parse-integer("-20")

Result:
-20
Expression:

parse-integer(" +100")

Result:
100
Expression:

parse-integer("ff", 16)

Result:
255
Expression:

parse-integer("FFFF FFFF", 16)

Result:
4294967295
Expression:

parse-integer("-FFFF_FFFF", 16)

Result:
-4294967295
Expression:

parse-integer("377", 8)

Result:
255
Expression:

parse-integer("101", 2)

Result:
5
Expression:

parse-integer("vv", 32)

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

4.6 Formatting integers

Function Meaning
fn:format-integer Formats an integer according to a given picture string, using the conventions of a given natural language if specified.

4.6.1 fn:format-integer

Changes in 4.0  

  1. The function has been extended to allow output in a radix other than 10, for example in hexadecimal.  [Issue 241 PR 434 7 April 2023]

Summary

Formats an integer according to a given picture string, using the conventions of a given natural language if specified.

Signature
fn:format-integer(
$value as xs:integer?,
$picture as xs:string,
$language as xs:string? := ()
) as xs:string
Properties

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·.

Rules

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:

  1. An optional radix, which is an integer in the range 2 to 36, written using ASCII digits (0-9) without any leading zero;

  2. 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.

  3. A primary format token. This is always present and must not be zero-length.

  4. 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:

  1. A digit-pattern made up of optional-digit-signs, mandatory-digit-signs, and grouping-separator-signs.

    • The optional-digit-sign is the character #.

    • If the radix is absent, then a mandatory-digit-sign is a ·character· in Unicode category Nd. All mandatory-digit-signs within the format token must be from the same digit family, where a digit family is a sequence of ten consecutive characters in Unicode category Nd, having digit values 0 through 9. Within the format token, these digits are interchangeable: a three-digit number may thus be indicated equivalently by 000, 001, or 999.

      If the primary format token contains at least one Unicode digit, then the primary format token is taken as a decimal digit pattern, and in this case it must match the regular expression ^((\p{Nd}|#|[^\p{N}\p{L}])+?)$. If it contains a digit but does not match this pattern, a dynamic error is raised [err:FODF1310].

    • If the radix (call it R) is present (including the case where an explicit radix of 10 is used), then the character used as the mandatory-digit-sign is either "x" or "X". If any mandatory-digit-sign is upper-case "X", then all mandatory-digit-signs must be upper-case "X". The digit family used in the output comprises the first R characters of the alphabet 0123456789abcdefghijklmnopqrstuvwxyz, but using upper-case letters in place of lower-case if an upper-case "X" is used as the mandatory-digit-sign.

      In this case the primary format token must match the regular expression ^(([Xx#]|[^\p{N}\p{L}])+?)$

    • a grouping-separator-sign is a non-alphanumeric character, that is a ·character· whose Unicode category is other than Nd, Nl, No, Lu, Ll, Lt, Lm or Lo.

    Note:

    If a semicolon is to be used as a grouping separator, then the primary format token as a whole must be followed by another semicolon, to ensure that the grouping separator is not mistaken as a separator between the primary format token and the format modifier.

    There must be at least one mandatory-digit-sign. There may be zero or more optional-digit-signs, and (if present) these must precede all mandatory-digit-signs. There may be zero or more grouping-separator-signs. A grouping-separator-sign must not appear at the start or end of the digit-pattern, nor adjacent to another grouping-separator-sign.

    The corresponding output is a number in the specified radix, using this digit family, with at least as many digits as there are mandatory-digit-signs in the format token. Thus:

    • A format token 1 generates the sequence 0 1 2 ... 10 11 12 ...

    • A format token 01 (or equivalently, 00 or 99) generates the sequence 00 01 02 ... 09 10 11 12 ... 99 100 101

    • A format token of 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:

    1. 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.

    2. 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.

    3. Grouping separators are defined to be regular if the following conditions apply:

      1. There is at least one grouping separator.

      2. Every grouping separator is the same character (call it C).

      3. There is a positive integer G (the grouping size) such that:

        1. The position of every grouping separator is an integer multiple of G, and

        2. 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.

    4. The grouping separator template is a (possibly infinite) set of (position, character) pairs.

    5. 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.

    6. 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.

    7. Note:

      If there are no grouping separators, then the grouping separator template is an empty set.

    The number is formatted as follows:

    1. 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.

    2. 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.

    3. 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.)

    4. 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.

    5. Let S5 be the result of converting S4 into ordinal form, if an ordinal modifier is present, as described below.

    6. The result of the function is then S5.

  2. The format token A, which generates the sequence A B C ... Z AA AB AC....

  3. The format token a, which generates the sequence a b c ... z aa ab ac....

  4. The format token i, which generates the sequence i ii iii iv v vi vii viii ix x ....

  5. The format token I, which generates the sequence I II III IV V VI VII VIII IX X ....

  6. The format token w, which generates numbers written as lower-case words, for example in English, one two three four ...

  7. The format token W, which generates numbers written as upper-case words, for example in English, ONE TWO THREE FOUR ...

  8. The format token Ww, which generates numbers written as title-case words, for example in English, One Two Three Four ...

  9. 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·.

Error Conditions

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.

Notes
  1. 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.

  2. The following notes apply when a digit-pattern is used:

    1. 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.

    2. 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.

    3. 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.

    4. Numbers will never be truncated. Given the digit-pattern 01, the number three hundred will be output as 300, despite the absence of any optional-digit-sign.

  3. 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).

  4. 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.

Examples
Expression:

format-integer(123, '0000')

Result:
"0123"

format-integer(123, 'w') might return "one hundred and twenty-three"

Ordinal numbering in Italian: The specification "1;o(-º)" with $language equal to it, if supported, should produce the sequence:

1º 2º 3º 4º ...

The specification "Ww;o" with $language equal to it, if supported, should produce the sequence:

Primo Secondo Terzo Quarto Quinto ...
Expression:

format-integer(21, '1;o', 'en')

Result:
"21st"

format-integer(14, 'Ww;o(-e)', 'de') might return "Vierzehnte"

Expression:

format-integer(7, 'a')

Result:
"g"
Expression:

format-integer(27, 'a')

Result:
"aa"
Expression:

format-integer(57, 'I')

Result:
"LVII"
Expression:

format-integer(1234, '#;##0;')

Result:
"1;234"
Expression:

format-integer(1234, '16^xxxx')

Result:
"04d2"
Expression:

format-integer(1234, '16^X')

Result:
"4D2"
Expression:

format-integer(12345678, '16^xxxx_xxxx')

Result:
"00bc_614e"
Expression:

format-integer(12345678, '16^#_xxxx')

Result:
"bc_614e"
Expression:

format-integer(255, '2^xxxx xxxx')

Result:
"1111 1111"
Expression:

format-integer(1023, '32^XXXX')

Result:
"00VV"
Expression:

format-integer(1023, '10^XXXX')

Result:
"1023"
Expression:

format-integer(1023, '10^00')

Result:
"10^23"

4.7 Formatting numbers

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.

4.7.1 Defining a decimal format

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·.

4.7.2 fn:format-number

Changes in 4.0  

  1. 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.

  2. 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]

  3. 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]

Summary

Returns a string containing a number formatted according to a given picture string and decimal format.

Signature
fn:format-number(
$value as xs:numeric?,
$picture as xs:string,
$options as (xs:string | map(*))? := ()
) as xs:string
Properties

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.

Rules

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

format-name

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.
  • Type: (xs:NCName | xs:QName)?

  • Default: ()

decimal-separator

The marker used to represent the decimal point in the picture string, and the rendition of the decimal point in the formatted number.
  • Type: xs:string (: matching '.|.:.*' :)

  • Default: "."

grouping-separator

The marker used to separate groups of digits in the picture string, and the rendition of the grouping separator in the formatted number.
  • Type: xs:string (: matching '.|.:.*' :)

  • Default: ","

exponent-separator

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.
  • Type: xs:string (: matching '.|.:.*' :)

  • Default: "e"

infinity

The string used to represent the value positive or negative infinity in the formatted number.
  • Type: xs:string

  • Default: "Infinity"

minus-sign

The string used as a minus sign in the formatted number if there is no subpicture for formatting negative numbers.
  • Type: xs:string

  • Default: "-"

NaN

The string used to represent the value NaN in the formatted number.
  • Type: xs:string

  • Default: "NaN"

percent

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.
  • Type: xs:string (: matching '.|.:.*' :)

  • Default: "%"

per-mille

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.
  • Type: xs:string (: matching '.|.:.*' :)

  • Default: "‰" (0x2030)

zero-digit

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).
  • Type: xs:string (: matching '.' :)

  • Default: "0"

digit

The character used in the picture string to represent an optional digit.
  • Type: xs:string (: matching '.' :)

  • Default: "#"

pattern-separator

The character used in the picture string to separate the positive and negative subpictures.
  • Type: xs:string (: matching '.' :)

  • Default: ";"

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.

Error Conditions

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.

Notes

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.

Examples

The following examples assume a default decimal format in which the chosen digits are the ASCII digits 0-9, the decimal separator is ., the grouping separator is ,, the minus-sign is -, and the percent-sign is %.

Expression:

format-number(12345.6, '#,###.00')

Result:
"12,345.60"
Expression:

format-number(12345678.9, '9,999.99')

Result:
"12,345,678.90"
Expression:

format-number(123.9, '9999')

Result:
"0124"
Expression:

format-number(0.14, '01%')

Result:
"14%"
Expression:
format-number(12345, '0,###^0', {
  'percent': '%:pc'
})
Result:
"14pc"
Expression:

format-number(-6, '000')

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 de in which the grouping separator is . and the decimal separator is ,:

Expression:

format-number(1234.5678, '#.##0,00', {'format-name':'de'})

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 fortran is E:

Expression:

format-number(1234.5678, '00.000E0', 'fortran')

Result:
"12.346E2"
Expression:

format-number(0.234, '0.0E0', 'fortran')

Result:
"2.3E-1"
Expression:

format-number(0.234, '#.00E0', 'fortran')

Result:
"0.23E0"
Expression:

format-number(0.234, '.00E0', 'fortran')

Result:
".23E0"

4.7.3 Syntax of the picture string

Note:

This differs from the format-number function previously defined in XSLT 2.0 in that any digit can be used in the picture string to represent a mandatory digit: for example the picture strings "000", "001", and "999" are equivalent. The digits will all be from the same decimal digit family, specifically, the sequence of ten consecutive digits starting with the digit assigned to the zero-digit property. This change is to align format-number (which previously used "000") with format-dateTime (which used 001).

[Definition] The formatting of a number is controlled by a picture string. The picture string is a sequence of ·characters·, in which the characters assigned to the properties decimal-separatorXP31 , exponent-separatorXP31, grouping-separatorXP31, 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.

4.7.4 Analyzing the picture string

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:

    1. There is an least one grouping-separator in the integer part of the sub-picture.

    2. 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.

    3. 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.

4.7.5 Formatting the number

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:

  1. If the input number is NaN (not a number), the result is the value of the pattern separatorXP31 property (with no prefix or suffix).

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. 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.

  9. 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.

  10. 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.

  11. 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.

  12. 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).

  13. 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·.

  14. 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.

4.8 Trigonometric and exponential functions

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:

  1. IEEE states that the preferred quantum is language-defined. In this specification, it is ·implementation-defined·.

  2. 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.

  3. 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·.

  4. 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.

  5. 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 10x, where x is the supplied argument value.
math:log Returns the natural logarithm of the argument.
math:log10 Returns the base-ten logarithm of the argument.
math:pow Returns the result of raising the first argument to the power of the second.
math: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.

4.8.1 math:pi

Summary

Returns an approximation to the mathematical constant π.

Signature
math:pi() as xs:double
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

This function returns the xs:double value whose lexical representation is 3.141592653589793e0

Examples
Expression Result
2 * math:pi()
6.283185307179586e0

The expression 60 * (math:pi() div 180) converts an angle of 60 degrees to radians.

4.8.2 math:e

Changes in 4.0  

  1. New in 4.0  [Issues 1196 1216 PRs 1205 1230 14 May 2024]

Summary

Returns an approximation to the mathematical constant e.

Signature
math:e() as xs:double
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

This function returns the xs:double value whose lexical representation is 2.718281828459045e0

Examples
Expression Result
math:pow(math:e(), 0.05 * 3)
1.161834242728283e0

(approximately)

4.8.3 math:exp

Summary

Returns the value of ex where x is the argument value.

Signature
math:exp(
$value as xs:double?
) as xs:double?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

The treatment of overflow and underflow is defined in 4.2 Arithmetic operators on numeric values.

Examples
Expression Result
math:exp(())
()
math:exp(0)
1.0e0
math:exp(1)
2.7182818284590455e0

(approximately)

math:exp(2)
7.38905609893065e0
math:exp(-1)
0.36787944117144233e0
math:exp(math:pi())
23.140692632779267e0
math:exp(xs:double('NaN'))
xs:double('NaN')
math:exp(xs:double('INF'))
xs:double('INF')
math:exp(xs:double('-INF'))
0.0e0

4.8.4 math:exp10

Summary

Returns the value of 10x, where x is the supplied argument value.

Signature
math:exp10(
$value as xs:double?
) as xs:double?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

The treatment of overflow and underflow is defined in 4.2 Arithmetic operators on numeric values.

Examples
Expression Result
math:exp10(())
()
math:exp10(0)
1.0e0
math:exp10(1)
1.0e1
math:exp10(0.5)
3.1622776601683795e0
math:exp10(-1)
1.0e-1
math:exp10(xs:double('NaN'))
xs:double('NaN')
math:exp10(xs:double('INF'))
xs:double('INF')
math:exp10(xs:double('-INF'))
0.0e0

4.8.5 math:log

Summary

Returns the natural logarithm of the argument.

Signature
math:log(
$value as xs:double?
) as xs:double?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples
Expression Result
math:log(())
()
math:log(0)
xs:double('-INF')
math:log(math:exp(1))
1.0e0
math:log(1.0e-3)
-6.907755278982137e0
math:log(2)
0.6931471805599453e0
math:log(-1)
xs:double('NaN')
math:log(xs:double('NaN'))
xs:double('NaN')
math:log(xs:double('INF'))
xs:double('INF')
math:log(xs:double('-INF'))
xs:double('NaN')

4.8.6 math:log10

Summary

Returns the base-ten logarithm of the argument.

Signature
math:log10(
$value as xs:double?
) as xs:double?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples
Expression Result
math:log10(())
()
math:log10(0)
xs:double('-INF')
math:log10(1.0e3)
3.0e0
math:log10(1.0e-3)
-3.0e0
math:log10(2)
0.3010299956639812e0
math:log10(-1)
xs:double('NaN')
math:log10(xs:double('NaN'))
xs:double('NaN')
math:log10(xs:double('INF'))
xs:double('INF')
math:log10(xs:double('-INF'))
xs:double('NaN')

4.8.7 math:pow

Summary

Returns the result of raising the first argument to the power of the second.

Signature
math:pow(
$x as xs:double?,
$y as xs:numeric
) as xs:double?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples
Expression Result
math:pow((), 93.7)
()
math:pow(2, 3)
8.0e0
math:pow(-2, 3)
-8.0e0
math:pow(2, -3)
0.125e0
math:pow(-2, -3)
-0.125e0
math:pow(2, 0)
1.0e0
math:pow(0, 0)
1.0e0
math:pow(xs:double('INF'), 0)
1.0e0
math:pow(xs:double('NaN'), 0)
1.0e0
math:pow(-math:pi(), 0)
1.0e0
math:pow(0e0, 3)
0.0e0
math:pow(0e0, 4)
0.0e0
math:pow(-0e0, 3)
-0.0e0
math:pow(0, 4)
0.0e0
math:pow(0e0, -3)
xs:double('INF')
math:pow(0e0, -4)
xs:double('INF')
math:pow(-0e0, -3)
xs:double('-INF')
math:pow(0, -4)
xs:double('INF')
math:pow(16, 0.5e0)
4.0e0
math:pow(16, 0.25e0)
2.0e0
math:pow(0e0, -3.0e0)
xs:double('INF')
math:pow(-0e0, -3.0e0)
xs:double('-INF')

(Odd-valued whole numbers are treated specially).

math:pow(0e0, -3.1e0)
xs:double('INF')
math:pow(-0e0, -3.1e0)
xs:double('INF')
math:pow(0e0, 3.0e0)
0.0e0
math:pow(-0e0, 3.0e0)
-0.0e0

(Odd-valued whole numbers are treated specially).

math:pow(0e0, 3.1e0)
0.0e0
math:pow(-0e0, 3.1e0)
0.0e0
math:pow(-1, xs:double('INF'))
1.0e0
math:pow(-1, xs:double('-INF'))
1.0e0
math:pow(1, xs:double('INF'))
1.0e0
math:pow(1, xs:double('-INF'))
1.0e0
math:pow(1, xs:double('NaN'))
1.0e0
math:pow(-2.5e0, 2.0e0)
6.25e0
math:pow(-2.5e0, 2.00000001e0)
xs:double('NaN')

4.8.8 math:sqrt

Summary

Returns the non-negative square root of the argument.

Signature
math:sqrt(
$value as xs:double?
) as xs:double?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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)

Examples
Expression Result
math:sqrt(())
()
math:sqrt(0.0e0)
0.0e0
math:sqrt(-0.0e0)
-0.0e0
math:sqrt(1.0e6)
1.0e3
math:sqrt(2.0e0)
1.4142135623730951e0
math:sqrt(-2.0e0)
xs:double('NaN')
math:sqrt(xs:double('NaN'))
xs:double('NaN')
math:sqrt(xs:double('INF'))
xs:double('INF')
math:sqrt(xs:double('-INF'))
xs:double('NaN')

4.8.9 math:sin

Summary

Returns the sine of the argument. The argument is an angle in radians.

Signature
math:sin(
$radians as xs:double?
) as xs:double?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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

Examples
Expression Result
math:sin(())
()
math:sin(0)
0.0e0
math:sin(-0.0e0)
-0.0e0
math:sin(math:pi() div 2)
1.0e0

(approximately)

math:sin(-math:pi() div 2)
-1.0e0

(approximately)

math:sin(math:pi())
0.0e0

(approximately)

math:sin(xs:double('NaN'))
xs:double('NaN')
math:sin(xs:double('INF'))
xs:double('NaN')
math:sin(xs:double('-INF'))
xs:double('NaN')

4.8.10 math:cos

Summary

Returns the cosine of the argument. The argument is an angle in radians.

Signature
math:cos(
$radians as xs:double?
) as xs:double?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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 $radiansis positive or negative infinity, or NaN, then the result is NaN.

Otherwise the result is always in the range -1.0e0 to +1.0e0

Examples
Expression Result
math:cos(())
()
math:cos(0)
1.0e0
math:cos(-0.0e0)
1.0e0
math:cos(math:pi() div 2)
0.0e0

(approximately)

math:cos(-math:pi() div 2)
0.0e0

(approximately)

math:cos(math:pi())
-1.0e0

(approximately)

math:cos(xs:double('NaN'))
xs:double('NaN')
math:cos(xs:double('INF'))
xs:double('NaN')
math:cos(xs:double('-INF'))
xs:double('NaN')

4.8.11 math:tan

Summary

Returns the tangent of the argument. The argument is an angle in radians.

Signature
math:tan(
$radians as xs:double?
) as xs:double?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples
Expression Result
math:tan(())
()
math:tan(0)
0.0e0
math:tan(-0.0e0)
-0.0e0
math:tan(math:pi() div 4)
1.0e0

(approximately)

math:tan(-math:pi() div 4)
-1.0e0

(approximately)

1 div math:tan(math:pi() div 2)
0.0e0

(approximately)

(Mathematically, tan(π/2) is positive infinity. But because math:pi() div 2 returns an approximation, the result of math:tan(math:pi() div 2) will be a large but finite number.)

1 div math:tan(-math:pi() div 2)
-0.0e0

(approximately)

(Mathematically, tan(-π/2) is negative infinity. But because -math:pi() div 2 returns an approximation, the result of math:tan(-math:pi() div 2) will be a large but finite negative number.)

math:tan(math:pi())
0.0e0

(approximately)

math:tan(xs:double('NaN'))
xs:double('NaN')
math:tan(xs:double('INF'))
xs:double('NaN')
math:tan(xs:double('-INF'))
xs:double('NaN')

4.8.12 math:asin

Summary

Returns the arc sine of the argument.

Signature
math:asin(
$value as xs:double?
) as xs:double?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples
Expression Result
math:asin(())
()
math:asin(0)
0.0e0
math:asin(-0.0e0)
-0.0e0
math:asin(1.0e0)
1.5707963267948966e0

(approximately)

math:asin(-1.0e0)
-1.5707963267948966e0

(approximately)

math:asin(2.0e0)
xs:double('NaN')
math:asin(xs:double('NaN'))
xs:double('NaN')
math:asin(xs:double('INF'))
xs:double('NaN')
math:asin(xs:double('-INF'))
xs:double('NaN')

4.8.13 math:acos

Summary

Returns the arc cosine of the argument.

Signature
math:acos(
$value as xs:double?
) as xs:double?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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().

Examples
Expression Result
math:acos(())
()
math:acos(0)
1.5707963267948966e0

(approximately)

math:acos(-0.0e0)
1.5707963267948966e0

(approximately)

math:acos(1.0e0)
0.0e0
math:acos(-1.0e0)
3.141592653589793e0

(approximately)

math:acos(2.0e0)
xs:double('NaN')
math:acos(xs:double('NaN'))
xs:double('NaN')
math:acos(xs:double('INF'))
xs:double('NaN')
math:acos(xs:double('-INF'))
xs:double('NaN')

4.8.14 math:atan

Summary

Returns the arc tangent of the argument.

Signature
math:atan(
$value as xs:double?
) as xs:double?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples
Expression Result
math:atan(())
()
math:atan(0)
0.0e0
math:atan(-0.0e0)
-0.0e0
math:atan(1.0e0)
0.7853981633974483e0

(approximately)

math:atan(-1.0e0)
-0.7853981633974483e0

(approximately)

math:atan(xs:double('NaN'))
xs:double('NaN')
math:atan(xs:double('INF'))
1.5707963267948966e0

(approximately)

math:atan(xs:double('-INF'))
-1.5707963267948966e0

(approximately)

4.8.15 math:atan2

Summary

Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive x-axis.

Signature
math:atan2(
$y as xs:double,
$x as xs:double
) as xs:double
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples
Expression Result
math:atan2(+0.0e0, 0.0e0)
0.0e0
math:atan2(-0.0e0, 0.0e0)
-0.0e0
math:atan2(+0.0e0, -0.0e0)
3.141592653589793e0
math:atan2(-0.0e0, -0.0e0)
-3.141592653589793e0
math:atan2(-1, 0.0e0)
-1.5707963267948966e0
math:atan2(+1, 0.0e0)
1.5707963267948966e0
math:atan2(-0.0e0, -1)
-3.141592653589793e0
math:atan2(+0.0e0, -1)
3.141592653589793e0
math:atan2(-0.0e0, +1)
-0.0e0
math:atan2(+0.0e0, +1)
+0.0e0

4.8.16 math:sinh

Changes in 4.0  

  1. New in 4.0  [Issues 1196 1216 PRs 1205 1230 14 May 2024]

Summary

Returns the hyperbolic sine of the argument.

Signature
math:sinh(
$value as xs:double?
) as xs:double?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples
Expression Result
math:sinh(1)
1.1752011936438014e0

(approximately)

math:sinh(math:pi())
11.548739357257748e0

(approximately)

4.8.17 math:cosh

Changes in 4.0  

  1. New in 4.0  [Issues 1196 1216 PRs 1205 1230 14 May 2024]

Summary

Returns the hyperbolic cosine of the argument.

Signature
math:cosh(
$value as xs:double?
) as xs:double?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples
Expression Result
math:cosh(0)
1.0e0
math:cosh(math:pi())
11.591953275521519e0

(approximately)

4.8.18 math:tanh

Changes in 4.0  

  1. New in 4.0  [Issues 1196 1216 PRs 1205 1230 14 May 2024]

Summary

Returns the hyperbolic tangent of the argument.

Signature
math:tanh(
$value as xs:double?
) as xs:double?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples
Expression Result
math:tanh(1)
0.7615941559557649e0

(approximately)

math:tanh(math:pi())
0.99627207622075e0

(approximately)

4.9 Random Numbers

Function Meaning
fn:random-number-generator Returns a random number generator, which can be used to generate sequences of random numbers.

4.9.1 fn:random-number-generator

Changes in 4.0  

  1. 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).

Summary

Returns a random number generator, which can be used to generate sequences of random numbers.

Signature
fn:random-number-generator(
$seed as xs:anyAtomicType? := ()
) as random-number-generator-record
record random-number-generator-record (
   number as xs:double,
   next as fn() as random-number-generator-record,
   permute as function(item()*) as item()*
)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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

number

An xs:double greater than or equal to zero (0.0e0), and less than one (1.0e0).

  • Type: xs:double

next

A zero-arity function that can be called to return another random number generator.

The properties of this function are as follows:

  • name: absent

  • parameter names: ()

  • signature: () => map(xs:string, item())

  • non-local variable bindings: none

  • implementation: implementation-dependent

  • Type: fn() as random-number-generator-record

permute

A function with arity 1 (one), which takes an arbitrary sequence as its argument, and returns a random permutation of that sequence.

The properties of this function are as follows:

  • name: absent

  • parameter names: "arg"

  • signature: (item()*) => item()*

  • non-local variable bindings: none

  • body: implementation-dependent

  • Type: function(item()*) as item()*

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 all eligible xs:double values are equally likely to be chosen the distribution of numbers is uniform: for example, the probability of the number being in the range 0.1e0 to 0.2e0 is the same as the probability of its being in the range 0.8e0 to 0.9e0.

The function returned in the permute entry should be such that all permutations of the supplied sequence are equally likely to be chosen.

The map returned by the fn: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.

Notes

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.

Examples

The following example returns a random permutation of the integers in the range 1 to 100:

random-number-generator()?permute(1 to 100)

The following example returns a 10% sample of the items in an input sequence $seq, chosen at random:

random-number-generator()?permute($seq)[1 to (count($seq) idiv 10)]

The following XQuery code produces a random sequence of 200 xs:double values in the range zero to one:

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 fn:fold-left:

tail(fold-left(
  (1 to 200),
  random-number-generator(),
  fn($result) { head($result) ! (?next(), ?number), tail($result) }
))

5 Functions on strings

This section specifies functions and operators on the [XML Schema Part 2: Datatypes Second Edition] xs:string datatype and the datatypes derived from it.

5.1 String types

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.

5.2 Functions to assemble and disassemble strings

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.

5.2.1 fn:codepoints-to-string

Summary

Returns an xs:string whose characters have supplied ·codepoints·.

Signature
fn:codepoints-to-string(
$values as xs:integer*
) as xs:string
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Error Conditions

A dynamic error is raised [err:FOCH0001] if any of the codepoints in $values is not a ·permitted character·.

Examples
Expression Result
codepoints-to-string((66, 65, 67, 72))
"BACH"
codepoints-to-string((2309, 2358, 2378, 2325))
"अशॊक"
codepoints-to-string(())
""
codepoints-to-string(0)

Raises error FOCH0001.

5.2.2 fn:string-to-codepoints

Summary

Returns the sequence of ·codepoints· that constitute an xs:string value.

Signature
fn:string-to-codepoints(
$value as xs:string?
) as xs:integer*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples
Expression Result
string-to-codepoints("Thérèse")
(84, 104, 233, 114, 232, 115, 101)

5.3 Comparison of strings

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.

5.3.1 Collations

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.

5.3.2 The Unicode Codepoint Collation

[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:

  1. If both sequences are empty, the strings are equal.

  2. If one sequence is empty and the other is not, then the string corresponding to the empty sequence is less than the other string.

  3. 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.

  4. 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.

  5. 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.

5.3.3 The Unicode Collation Algorithm

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.

5.3.4 The HTML ASCII Case-Insensitive Collation

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.

5.3.5 Choosing a collation

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:

  1. 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].

  2. 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.

5.3.6 fn:codepoint-equal

Summary

Returns true if two strings are equal, considered codepoint-by-codepoint.

Signature
fn:codepoint-equal(
$value1 as xs:string?,
$value2 as xs:string?
) as xs:boolean?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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).

Notes

This function allows xs:anyURI values to be compared without having to specify the Unicode codepoint collation.

Examples
Expression Result
codepoint-equal("abcd", "abcd")
true()
codepoint-equal("abcd", "abcd ")
false()
codepoint-equal("", "")
true()
codepoint-equal("", ())
()
codepoint-equal((), ())
()

5.3.7 fn:collation

Changes in 4.0  

  1. New in 4.0  [Issue 1091 PR 1093 9 April 2024]

Summary

Constructs a collation URI with requested properties.

Signature
fn:collation(
$options as map(*)
) as xs:string
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.

Rules

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

fallback

See 5.3.3 The Unicode Collation Algorithm.
  • Type: xs:boolean

  • Default: true()

lang

See 5.3.3 The Unicode Collation Algorithm.
  • Type: xs:language

  • Default: default-language()

version

See 5.3.3 The Unicode Collation Algorithm.
  • Type: xs:string

  • Default: ()

strength

See 5.3.3 The Unicode Collation Algorithm.
  • Type: enum("primary", "secondary", "tertiary", "quaternary", "identical", "1", "2", "3", "4", "5")

  • Default: ()

maxVariable

See 5.3.3 The Unicode Collation Algorithm.
  • Type: enum("space", "punct", "symbol", "currency")

  • Default: "punct"

alternate

See 5.3.3 The Unicode Collation Algorithm.
  • Type: enum("non-ignorable", "shifted", "blanked", "currency")

  • Default: "non-ignorable"

backwards

See 5.3.3 The Unicode Collation Algorithm.
  • Type: xs:boolean

  • Default: false()

normalization

See 5.3.3 The Unicode Collation Algorithm.
  • Type: xs:boolean

  • Default: false()

caseLevel

See 5.3.3 The Unicode Collation Algorithm.
  • Type: xs:boolean

  • Default: false()

caseFirst

See 5.3.3 The Unicode Collation Algorithm.
  • Type: enum("upper","lower")

  • Default: "lower"

numeric

See 5.3.3 The Unicode Collation Algorithm.
  • Type: xs:boolean

  • Default: false()

reorder

See 5.3.3 The Unicode Collation Algorithm.
  • Type: xs:string

  • Default: ""

Error Conditions

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.

Examples
Expression:

collation({})

Result:
"http://www.w3.org/2013/collation/UCA"
Expression:

collation(map{'lang':'de'})

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

collation(map{'lang':'de', 'strength':'primary'})

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

(The order of query parameters may vary.)

The expression collation(map{'lang':default-language()}) returns a collation suitable for the default language in the dynamic context.

5.3.8 fn:collation-available

Changes in 4.0  

  1. New in 4.0  [Issue 1160 PR 1262 9 July 2024]

Summary

Asks whether a collation URI is recognized by the implementation.

Signature
fn:collation-available(
$collation as xs:string,
$usage as enum('equality', 'sort', 'substring')* := ()
) as xs:boolean
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.

Rules

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.

Notes

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.

Examples
Expression:

collation-available("http://www.w3.org/2013/collation/UCA?lang=de")

Result:
true()
Expression:

collation({ 'lang': 'de' }) => collation-available()

Result:
true()

The expression collation({ 'lang': default-language() }) returns a collation suitable for the default language in the dynamic context.

5.3.9 fn:collation-key

Summary

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.

Signature
fn:collation-key(
$value as xs:string,
$collation as xs:string? := fn:default-collation()
) as xs:base64Binary
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.

Rules

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.

Error Conditions

An error is raised [err:FOCH0004] if the specified collation does not support the generation of collation keys.

Notes

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.

Examples
Variables
let $C := collation(map{'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 "A" and "a" have the same collation key under this collation.)

As the above examples illustrate, it is important that when the collation-key function is used to add entries to a map, then it must also be used when retrieving entries from the map. This process can be made less error-prone by encapsulating the map within a function: fn($k) { $M(collation-key($k, $collation) }.

5.3.10 fn:contains-token

Summary

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.

Signature
fn:contains-token(
$value as xs:string*,
$token as xs:string,
$collation as xs:string? := fn:default-collation()
) as xs:boolean
Properties

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.

Rules

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.

Formal Specification

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
Notes

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.

Examples
Expression:

contains-token("red green blue ", "red")

Result:
true()
Expression:

contains-token(("red", "green", "blue"), " red ")

Result:
true()
Expression:

contains-token("red, green, blue", "red")

Result:
false()
Expression:
contains-token(
  "red green blue",
  "RED",
  "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive"
)
Result:
true()

5.4 Functions on string values

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.

5.4.1 fn:char

Changes in 4.0  

  1. New in 4.0  [Issues 121 989 PRs 261 306 993 10 January 2023]

Summary

Returns a string containing a particular character or glyph.

Signature
fn:char(
$value as (xs:string | xs:positiveInteger)
) as xs:string
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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:

  1. A Unicode codepoint, supplied as an integer. For example fn:char(9) returns the tab character.

  2. 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.]

  3. 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.

Error Conditions

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.

Notes

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.

Examples
Expression Result
char("aacute")
"á"
char("eth")
"ð"
char(9)
codepoints-to-string(9)

(The character tab).

char("\t")
codepoints-to-string(9)

(The character tab).

char(0x20)
" "
char(0x1D1CA)
"𝇊"

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

char("NotEqualTilde")
codepoints-to-string((8770, 824))

(This HTML5 character reference name expands to multiple codepoints.)

5.4.2 fn:characters

Changes in 4.0  

  1. New in 4.0  [  20 September 2022]

Summary

Splits the supplied string into a sequence of single-character strings.

Signature
fn:characters(
$value as xs:string?
) as xs:string*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

fn:string-to-codepoints($value) ! fn:codepoints-to-string(.)
Examples
Expression Result
characters("Thérèse")
("T", "h", "é", "r", "è", "s", "e")
characters("")
()
characters(())
()
characters("Banana") => index-of("a")
(2, 4, 6)
characters("stretch") => string-join("-")
"s-t-r-e-t-c-h"
"Banana"
=> characters()
=> reverse()
=> string-join()
"ananaB"

5.4.3 fn:graphemes

Changes in 4.0  

  1. New in 4.0  [Issue 73 PR 1068 15 May 2024]

Summary

Splits the supplied string into a sequence of single-grapheme strings.

Signature
fn:graphemes(
$value as xs:string?
) as xs:string*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

The resultant sequence of strings are extended graphemes, not legacy graphemes (see [UAX #29]).

Examples
Expression Result
graphemes("a" || char(0x308) || "b")
("a" || char(0x308), "b")

(a + ◌̈ + b, three characters, two graphemes).

graphemes("")
()
graphemes(())
()
graphemes(char('\r') || char('\n'))
char('\r') || char('\n')

(Carriage return + line feed, two characters, one grapheme).

graphemes(char(0x1F476) || char(0x200D) || char(0x1F6D1))
char(0x1F476) || char(0x200D) || char(0x1F6D1)

(👶 +ZWJ + 🛑, three characters, one grapheme).

graphemes("कत")
("क", "त")

(क + त, two characters, two graphemes).

graphemes("क" || char(0x93C) || char(0x200D) || char(0x94D) || "त")
"क" || char(0x93C) || char(0x200D) || char(0x94D) || "त"

(क + ◌़ + ZWJ + ◌् + त, five characters, one grapheme).

5.4.4 fn:concat

Changes in 4.0  

  1. The function can now take any number of arguments (previously it had to be two or more), and the arguments can sequences of strings rather than single strings.  [Issue 701 PR 702 19 September 2023]

Summary

Returns the concatenation of the arguments, treated as sequences of strings.

Operator Mapping

The two-argument form of this function defines the semantics of the || operator.

Signature
fn:concat(
$values as xs:anyAtomicType* ... := ()
) as xs:string
Properties

This function is ·deterministic·, ·context-independent·, ·focus-independent·, and ·variadic·.

Rules

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.

The coercion rules ensure that each supplied $values argument is first converted to a sequence of atomic items by applying atomization.

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.

Notes

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 &#x0308;, 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 &#x0308;. 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 &#x0308;, 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}`).

Examples
Expression:

concat('un', 'grateful')

Result:
"ungrateful"
Expression:
concat(
  'Thy ', (), 'old ', "groans", "", ' ring',
  ' yet', ' in', ' my', ' ancient',' ears.'
)
Result:
"Thy old groans ring yet in my ancient ears."
Expression:

concat('Ciao!', ())

Result:
"Ciao!"
Expression:

concat('Ingratitude, ', 'thou ', ('marble-hearted', ' fiend!'))

Result:
"Ingratitude, thou marble-hearted fiend!"
Expression:

concat(01, 02, 03, 04, true())

Result:
"1234true"
Expression:

concat()

Result:
""
Expression:

10 || '/' || 6

Result:
"10/6"

5.4.5 fn:string-join

Summary

Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items.

Signature
fn:string-join(
$values as xs:anyAtomicType*,
$separator as xs:string? := ""
) as xs:string
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

If $values is the empty sequence, the function returns the zero-length string.

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

string-join(1 to 9)

Result:
"123456789"
Expression:

string-join(('Now', 'is', 'the', 'time', '...'), ' ')

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

string-join((), 'separator')

Result:
""
Expression:

string-join(1 to 5, ', ')

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"

5.4.6 fn:substring

Changes in 4.0  

  1. The third argument can now be supplied as an empty sequence.  [Issue 895 PR 901 16 December 2023]

Summary

Returns the part of $value beginning at the position indicated by $start and continuing for the number of ·characters· indicated by $length.

Signature
fn:substring(
$value as xs:string?,
$start as xs:double,
$length as xs:double? := ()
) as xs:string
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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 and op:numeric-greater-than apply.

Notes

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.

Examples
Expression Result
substring("motor car", 6)
" car"

(Characters starting at position 6 to the end of $sourceString are selected.)

substring("metadata", 4, 3)
"ada"

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

substring("12345", 1.5, 2.6)
"234"

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

substring("12345", 0, 3)
"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.)

substring("12345", 5, -3)
""

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

substring("12345", -3, 5)
"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.)

substring("12345", 0 div 0E0, 3)
""

(Since 0 div 0E0 returns NaN, and NaN compared to any other number returns false, no characters are selected.)

substring("12345", 1, 0 div 0E0)
""

(As above.)

substring((), 1, 3)
""
substring("12345", -42, 1 div 0E0)
"12345"

(Characters at positions greater than or equal to -42 and less than INF are selected.)

substring("12345", -1 div 0E0, 1 div 0E0)
""

(Since the value of -INF + INF is NaN, no characters are selected.)

5.4.7 fn:string-length

Summary

Returns the number of ·characters· in a string.

Signature
fn:string-length(
$value as xs:string? := fn:string(.)
) as xs:integer
Properties

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·.

Rules

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.

Error Conditions

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.

Notes

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).

Examples
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:

string-length(())

Result:
0

5.4.8 fn:normalize-space

Summary

Returns $value with leading and trailing whitespace removed, and sequences of internal whitespace reduced to a single space character.

Signature
fn:normalize-space(
$value as xs:string? := fn:string(.)
) as xs:string
Properties

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·.

Rules

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 (.).

Error Conditions

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.

Notes

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)+

Examples
Expression:
normalize-space(" The    wealthy curled darlings
           of    our    nation. ")
Result:
"The wealthy curled darlings of our nation."
Expression:

normalize-space(())

Result:
""

5.4.9 fn:normalize-unicode

Summary

Returns $value after applying Unicode normalization.

Signature
fn:normalize-unicode(
$value as xs:string?,
$form as xs:string? := "NFC"
) as xs:string
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Error Conditions

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.

5.4.10 fn:upper-case

Summary

Converts a string to upper case.

Signature
fn:upper-case(
$value as xs:string?
) as xs:string
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples
Expression Result
upper-case("abCd0")
"ABCD0"

5.4.11 fn:lower-case

Summary

Converts a string to lower case.

Signature
fn:lower-case(
$value as xs:string?
) as xs:string
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples
Expression Result
lower-case("ABc!D")
"abc!d"

5.4.12 fn:translate

Summary

Returns $value modified by replacing or removing individual characters.

Signature
fn:translate(
$value as xs:string?,
$replace as xs:string,
$with as xs:string
) as xs:string
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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:

  1. If the character does not appear in $replace then it is added to the result string unchanged.

  2. 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.

  3. 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.

Notes

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.

Examples
Expression Result
translate("bar", "abc", "ABC")
"BAr"
translate("--aaa--", "abc-", "ABC")
"AAA"
translate("abcdabc", "abc", "AB")
"ABdAB"

5.4.13 fn:hash

Changes in 4.0  

  1. New in 4.0  [Issues 779 1188 1422 1426 PRs 937 995 1190 23 January 2024]

Summary

Returns the results of a specified hash, checksum, or cyclic redundancy check function applied to the input.

Signature
fn:hash(
$value as (xs:string | xs:hexBinary | xs:base64Binary)?,
$algorithm as xs:string? := "MD5",
$options as map(*)? := {}
) as xs:hexBinary?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Error Conditions

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.

Notes

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.

Examples
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:

hash("password123", "sha-unknown")

Result:

Raises error FOHA0001.

5.5 Functions based on substring matching

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.

5.5.1 fn:contains

Summary

Returns true if the string $value contains $substring as a substring, taking collations into account.

Signature
fn:contains(
$value as xs:string?,
$substring as xs:string?,
$collation as xs:string? := fn:default-collation()
) as xs:boolean
Properties

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.

Rules

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].

Error Conditions

A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.

Examples
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, $coll, is a collation in which both - and * are ignorable collation units.

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

contains("tattoo", "t")
true()
contains("tattoo", "ttt")
false()
contains("", ())
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.)

5.5.2 fn:starts-with

Summary

Returns true if the string $value contains $substring as a leading substring, taking collations into account.

Signature
fn:starts-with(
$value as xs:string?,
$substring as xs:string?,
$collation as xs:string? := fn:default-collation()
) as xs:boolean
Properties

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.

Rules

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].

Error Conditions

A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.

Examples
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, $coll, is a collation in which both - and * are ignorable collation units.

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

starts-with("tattoo", "tat")
true()
starts-with("tattoo", "att")
false()
starts-with((), ())
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()

5.5.3 fn:ends-with

Summary

Returns true if the string $value contains $substring as a trailing substring, taking collations into account.

Signature
fn:ends-with(
$value as xs:string?,
$substring as xs:string?,
$collation as xs:string? := fn:default-collation()
) as xs:boolean
Properties

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.

Rules

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].

Error Conditions

A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.

Examples
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, $coll, is a collation in which both - and * are ignorable collation units.

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

ends-with("tattoo", "tattoo")
true()
ends-with("tattoo", "atto")
false()
ends-with((), ())
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()

5.5.4 fn:substring-before

Summary

Returns the part of $value that precedes the first occurrence of $substring, taking collations into account.

Signature
fn:substring-before(
$value as xs:string?,
$substring as xs:string?,
$collation as xs:string? := fn:default-collation()
) as xs:string
Properties

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.

Rules

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].

Error Conditions

A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.

Examples
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, $coll, is a collation in which both - and * are ignorable collation units.

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

substring-before("tattoo", "attoo")
"t"
substring-before("tattoo", "tatto")
""
substring-before((), ())
""
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.)

5.5.5 fn:substring-after

Summary

Returns the part of $value that follows the first occurrence of $substring, taking collations into account.

Signature
fn:substring-after(
$value as xs:string?,
$substring as xs:string?,
$collation as xs:string? := fn:default-collation()
) as xs:string
Properties

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.

Rules

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].

Error Conditions

A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.

Examples
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, $coll, is a collation in which both - and * are ignorable collation units.

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

substring-after("tattoo", "tat")
"too"
substring-after("tattoo", "tattoo")
""
substring-after((), ())
""
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.)

5.6 String functions that use regular expressions

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.

5.6.1 Regular expression syntax

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.

5.6.1.1 Matching the Start and End of the String

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])

5.6.1.2 Reluctant Quantifiers

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.

5.6.1.3 Captured Sub-Expressions

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.

5.6.1.4 Back-References

Back-references are allowed outside a character class expression. A back-reference is an additional kind of atom. The construct \N where N is a single digit is always recognized as a back-reference; if this is followed by further digits, these digits are taken to be part of the back-reference if and only if the resulting number NN is such that the back-reference is preceded by the opening parenthesis of the NNth capturing left parenthesis. The regular expression is invalid if a back-reference refers to a capturing sub-expression that does not exist or whose closing right parenthesis occurs after the back-reference.

A back-reference with number N matches a string that is the same as the value of the Nth captured substring.

For example, the regular expression ('|").*\1 matches a sequence of characters delimited either by an apostrophe at the start and end, or by a quotation mark at the start and end.

If no string has been matched by the Nth capturing sub-expression, the back-reference is interpreted as matching a zero-length string.

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.

5.6.1.5 Unicode Block Names

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.

5.6.1.6 Comments

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.

5.6.2 Flags

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.

    1. 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".

    2. 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).

    3. 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.

    4. 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.

5.6.3 fn:matches

Summary

Returns true if the supplied string matches a given regular expression.

Signature
fn:matches(
$value as xs:string?,
$pattern as xs:string,
$flags as xs:string? := ""
) as xs:boolean
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Error Conditions

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.

Notes

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.

Examples
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
matches("abracadabra", "bra")
true()
matches("abracadabra", "^a.*a$")
true()
matches("abracadabra", "^bra")
false()

Given the source document:

the following function calls produce the following results, with the poem element as the context node:

matches($poem, "Kaum.*krähen")
false()
matches($poem, "Kaum.*krähen", "s")
true()
matches($poem, "^Kaum.*gesehen,$", "m")
true()
matches($poem, "^Kaum.*gesehen,$")
false()
matches($poem, "kiki", "i")
true()

5.6.4 fn:replace

Changes in 4.0  

  1. The $action argument is new in 4.0.  [  18 July 2023]

Summary

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.

Signature
fn:replace(
$value as xs:string?,
$pattern as xs:string,
$replacement as xs:string? := (),
$flags as xs:string? := '',
$action as (fn(xs:untypedAtomic, xs:untypedAtomic*) as item()?)? := ()
) as xs:string
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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:

  1. If N=0, then the variable is replaced by the substring matched by the regular expression as a whole.

  2. 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.

  3. If S<N<=9, then the variable is replaced by the zero-length string.

  4. 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"
Error Conditions

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.

Notes

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.

Examples
Expression:

replace("abracadabra", "bra", "*")

Result:
"a*cada*"
Expression:

replace("abracadabra", "a.*a", "*")

Result:
"*"
Expression:

replace("abracadabra", "a.*?a", "*")

Result:
"*c*bra"
Expression:

replace("abracadabra", "a", "")

Result:
"brcdbr"
Expression:

replace("abracadabra", "a(.)", "a$1$1")

Result:
"abbraccaddabbra"
Expression:

replace("AAAA", "A+", "b")

Result:
"b"
Expression:

replace("AAAA", "A+?", "b")

Result:
"bbbb"
Expression:

replace("darted", "^(.*?)d(.*)$", "$1c$2")

Result:
"carted"

(The first d is replaced.)

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 fn:replace("abracadabra", ".*?", "$1") raises an error, because the pattern matches the zero-length string

5.6.5 fn:tokenize

Changes in 4.0  

  1. The second argument can now be an empty sequence.  [Issue 895 PR 901 16 December 2023]

Summary

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.

Signature
fn:tokenize(
$value as xs:string?,
$pattern as xs:string? := (),
$flags as xs:string? := ""
) as xs:string*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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", "")
Error Conditions

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.

Notes

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.

Examples
Expression:

tokenize(" red green blue ")

Result:
("red", "green", "blue")
Expression:

tokenize("The cat sat on the mat", "\s+")

Result:
("The", "cat", "sat", "on", "the", "mat")
Expression:

tokenize(" red green blue ", "\s+")

Result:
("", "red", "green", "blue", "")
Expression:

tokenize("1, 15, 24, 50", ",\s*")

Result:
("1", "15", "24", "50")
Expression:

tokenize("1,15,,24,50,", ",")

Result:
("1", "15", "", "24", "50", "")

fn:tokenize("abba", ".?") raises the dynamic error [err:FORX0003].

Expression:
tokenize(
  "Some unparsed <br> HTML <BR> text",
  "\s*<br>\s*", "i"
)
Result:
("Some unparsed", "HTML", "text")

5.6.6 fn:analyze-string

Summary

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.

Signature
fn:analyze-string(
$value as xs:string?,
$pattern as xs:string,
$flags as xs:string? := ""
) as element(fn:analyze-string-result)
Properties

This function is ·nondeterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Error Conditions

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.

Notes

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.

Examples

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:

analyze-string("The cat sat on the mat.", "\w+")

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)

6 Functions that manipulate URIs

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.

6.1 fn:resolve-uri

Changes in 4.0  

  1. The optional second argument can now be supplied as an empty sequence.  [Issue 895 PR 901 16 December 2023]

Summary

Resolves a relative IRI reference against an absolute IRI.

Signature
fn:resolve-uri(
$href as xs:string?,
$base as xs:string? := ()
) as xs:anyURI?
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.

Rules

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:

  1. If $href is the empty sequence, the function returns the empty sequence.

  2. If $href is an absolute IRI (as defined above), then it is returned unchanged.

  3. If the $base argument is not supplied, or is supplied as an empty sequence then:

    1. If the static base URI in the static context is not absent, it is used as the effective value of $base.

    2. Otherwise, a dynamic error is raised: [err:FONS0005].

  4. 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.

Error Conditions

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, or if it contains a fragment identifier). 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.

Notes

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.

6.2 fn:encode-for-uri

Summary

Encodes reserved characters in a string that is intended to be used in the path segment of a URI.

Signature
fn:encode-for-uri(
$value as xs:string?
) as xs:string
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples
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"

6.3 fn:decode-from-uri

Changes in 4.0  

  1. New in 4.0  [Issue 600 PR 631 12 September 2023]

Summary

Decodes URI-escaped characters in a string.

Signature
fn:decode-from-uri(
$value as xs:string?
) as xs:string
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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 "�".

Examples
Expression Result
decode-from-uri("http://example.com/")
"http://example.com/"
decode-from-uri("~b%C3%A9b%C3%A9?a=b+c")
"~bébé?a=b c"
decode-from-uri("%00-%XX-%F0%9F%92%41-%F0%F0%9F%92%A1")
"�-�-�A-�💡"

6.4 fn:iri-to-uri

Summary

Converts a string containing an IRI into a URI according to the rules of [RFC 3987].

Signature
fn:iri-to-uri(
$value as xs:string?
) as xs:string
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples
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:

iri-to-uri("http://www.example.com/~bébé")

Result:
"http://www.example.com/~b%C3%A9b%C3%A9"

6.5 fn:escape-html-uri

Summary

Escapes a URI in the same way that HTML user agents handle attribute values expected to contain URIs.

Signature
fn:escape-html-uri(
$value as xs:string?
) as xs:string
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples
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');"

6.6 Parsing and building URIs

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

uri

The original URI. This element is returned by fn:parse-uri, but ignored by fn:build-uri.

  • Type: xs:string?

scheme

The URI scheme (e.g., “https” or “file”).

  • Type: xs:string?

absolute

The URI is an absolute URI.

  • Type: xs:boolean?

hierarchical

Whether the URI is hierarchical or not.

  • Type: xs:boolean?

authority

The authority portion of the URI (e.g., “example.com:8080”).

  • Type: xs:string?

userinfo

Any userinfo that was passed as part of the authority.

  • Type: xs:string?

host

The host passed as part of the authority (e.g., “example.com”).

  • Type: xs:string?

port

The port passed as part of the authority (e.g., “8080”).

  • Type: xs:integer?

path

The path portion of the URI.

  • Type: xs:string?

query

Any query string.

  • Type: xs:string?

fragment

Any fragment identifier.

  • Type: xs:string?

path-segments

Parsed and unescaped path segments.

  • Type: xs:string*

query-parameters

Parsed and unescaped query key-value pairs.

  • Type: map(xs:string, xs:string*)?

filepath

The path of the URI, treated as a filepath.

  • Type: xs:string?

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.

6.6.1 fn:parse-uri

Changes in 4.0  

  1. New in 4.0  [Issues 72 389 390  17 October 2022]

Summary

Parses the URI provided and returns a map of its parts.

Signature
fn:parse-uri(
$value as xs:string?,
$options as map(*)? := {}
) 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?
)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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

allow-deprecated-features

Indicates that deprecated URI features should be returned
  • Type: xs:boolean

  • Default: false()

omit-default-ports

Indicates that a port number that is the same as the default port for a given scheme should be omitted.
  • Type: xs:boolean

  • Default: false()

unc-path

Indicates that an input URI that begins with two or more leading slashes should be interprted as a Windows Universal Naming Convention Path. (Specifically: that it has the file: scheme.)
  • Type: xs:boolean

  • Default: false()

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.

  1. If the authority matches ^(([^@]*)@)?(\[[^\]]*\])(:([^:]*))?$, then the host is match group 3, otherwise

  2. If the authority matches ^(([^@]*)@)?\[.*$ then [err:FOUR0001] is raised, otherwise

  3. If the authority matches ^(([^@]*)@)?([^:]+)(:([^:]*))?$, then the host is match group 3, otherwise

  4. 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.

Error Conditions

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.

Notes

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.

Examples

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 `Barnes&Noble`) to ensure that the examples work in both XPath and XQuery.

Expression:
parse-uri("http://qt4cg.org/specifications/xpath-functions-40/Overview.html#parse-uri")
Result:
map {
  "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:
map {
  "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:
map {
  "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:
map {
  "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": map {
    "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:
map {
  "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:
map {
  "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:
map {
  "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:
map {
  "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:
map {
  "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:
map {
  "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:
map {
  "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:
map {
  "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:
map {
  "filepath": "/path/to/file",
  "hierarchical": true(),
  "path": "/path/to/file",
  "path-segments": ("", "path", "to", "file"),
  "uri": "/path/to/file"
}
Expression:
parse-uri("#testing")
Result:
map {
  "fragment": "testing",
  "uri": "#testing"
}
Expression:
parse-uri("?q=1")
Result:
map {
  "query": "q=1",
  "query-parameters":map {
    "q": "1"
  },
  "uri": "?q=1"
}
Expression:
parse-uri("ldap://[2001:db8::7]/c=GB?objectClass?one")
Result:
map {
  "authority": "[2001:db8::7]",
  "hierarchical": true(),
  "absolute": true(),
  "host": "[2001:db8::7]",
  "path": "/c=GB",
  "path-segments": ("", "c=GB"),
  "query": "objectClass?one",
  "query-parameters":map {
    "": "objectClass?one"
  },
  "scheme": "ldap",
  "uri": "ldap://[2001:db8::7]/c=GB?objectClass?one"
}
Expression:
parse-uri("mailto:John.Doe@example.com")
Result:
map {
  "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:
map {
  "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:
map {
  "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:
map {
  "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:
map {
  "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:
map {
  "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:
map {
  "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 jar: scheme.

Expression:
parse-uri("jar:file:/C:/Program%20Files/test.jar!/foo/bar")
Result:
map {
  "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 fn:resolve-uri.

Expression:
parse-uri("http://www.example.org/Dürst")
Result:
map {
  "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 | instead of : in a Windows path.

Expression:
parse-uri("c|/path/to/file")
Result:
map {
  "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 | instead of : in a Windows path with an explicit file: scheme.

Expression:
parse-uri("file://c|/path/to/file")
Result:
map {
  "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"
}

6.6.2 fn:build-uri

Changes in 4.0  

  1. New in 4.0  [Issues 72 389 390 PRs 1423 1413 17 October 2022]

Summary

Constructs a URI from the parts provided.

Signature
fn:build-uri(
$parts as uri-structure-record,
$options as map(*)? := {}
) as xs:string
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?
)
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·.

Rules

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

allow-deprecated-features

Indicates that deprecated URI features should be returned
  • Type: xs:boolean

  • Default: false()

omit-default-ports

Indicates that a port number that is the same as the default port for a given scheme should be omitted.
  • Type: xs:boolean

  • Default: false()

unc-path

Indicates that the URI represents a Windows Universal Naming Convention Path.
  • Type: xs:boolean

  • Default: false()

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.

Examples
Expression:
build-uri(map {
  "scheme": "https",
  "host": "qt4cg.org",
  "port": (),
  "path": "/specifications/index.html"
})
Result:
"https://qt4cg.org/specifications/index.html"

7 Functions and operators on Boolean values

This section defines functions and operators on the xs:boolean datatype.

7.1 Boolean constant functions

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.

7.1.1 fn:true

Summary

Returns the xs:boolean value true.

Signature
fn:true() as xs:boolean
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The result is equivalent to xs:boolean("1").

Examples
Expression Result
true()
xs:boolean(1)

7.1.2 fn:false

Summary

Returns the xs:boolean value false.

Signature
fn:false() as xs:boolean
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The result is equivalent to xs:boolean("0").

Examples
Expression Result
false()
xs:boolean(0)

7.2 Operators on Boolean values

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.

7.2.1 op:boolean-equal

Summary

Returns true if the two arguments are the same boolean value.

Operator Mapping

Defines the semantics of the eq operator when applied to two xs:boolean values.

Signature
op:boolean-equal(
$value1 as xs:boolean,
$value2 as xs:boolean
) as xs:boolean
Rules

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.

7.2.2 op:boolean-less-than

Summary

Returns true if the first argument is false and the second is true.

Operator Mapping

Defines the semantics of the lt operator when applied to two xs:boolean values. Also used in the definition of the ge operator.

Signature
op:boolean-less-than(
$arg1 as xs:boolean,
$arg2 as xs:boolean
) as xs:boolean
Rules

The function returns true if $arg1 is false and $arg2 is true. Otherwise, it returns false.

7.3 Functions on Boolean values

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.

7.3.1 fn:boolean

Summary

Computes the effective boolean value of the sequence $input.

Signature
fn:boolean(
$input as item()*
) as xs:boolean
Rules

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.

Error Conditions

In all cases other than those listed above, fn:boolean raises a type error [err:FORG0006].

Notes

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.

Examples
Variables
let $abc := ("a", "b", "")
Expression Result
boolean($abc[1])
true()
boolean($abc[0])
false()
boolean($abc[3])
false()

fn:boolean($abc) raises a type error [err:FORG0006].

fn:boolean([]) raises a type error [err:FORG0006].

7.3.2 fn:not

Summary

Returns true if the effective boolean value of $input is false, or false if it is true.

Signature
fn:not(
$input as item()*
) as xs:boolean
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples
Expression Result
not(true())
false()
not(())
true()
not("false")
false()

fn:not(1 to 10) raises a type error [err:FORG0006].

8 Functions and operators on durations

Operators are defined on the following type:

and on the two defined subtypes (see 8.1.1 Subtypes of duration):

No ordering relation is defined on xs:duration values. Two xs:duration values may however be compared for equality.

8.1 Duration data types

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.

8.1.1 Subtypes of duration

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.

8.1.2 Limits and precision

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·.

8.2 Comparison operators on durations

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.

8.2.1 op:yearMonthDuration-less-than

Summary

Returns true if $arg1 is a shorter duration than $arg2.

Operator Mapping

Defines the semantics of the lt operator when applied to two xs:yearMonthDuration values. Also used in the definition of the ge operator.

Signature
op:yearMonthDuration-less-than(
$arg1 as xs:yearMonthDuration,
$arg2 as xs:yearMonthDuration
) as xs:boolean
Rules

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.

Notes

Either or both durations may be negative.

8.2.2 op:dayTimeDuration-less-than

Summary

Returns true if $arg1 is a shorter duration than $arg2.

Operator Mapping

Defines the semantics of the lt operator when applied to two xs:dayTimeDuration values. Also used in the definition of the ge operator.

Signature
op:dayTimeDuration-less-than(
$arg1 as xs:dayTimeDuration,
$arg2 as xs:dayTimeDuration
) as xs:boolean
Rules

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.

Notes

Either or both durations may be negative

8.2.3 op:duration-equal

Summary

Returns true if $arg1 and $arg2 are durations of the same length.

Operator Mapping

Defines the semantics of the eq operators when applied to two xs:duration values. Also used in the definition of the ne operator.

Signature
op:duration-equal(
$arg1 as xs:duration,
$arg2 as xs:duration
) as xs:boolean
Rules

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.

Notes

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.

Examples
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()

8.3 Component extraction functions on durations

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.

8.3.1 fn:years-from-duration

Summary

Returns the number of years in a duration.

Signature
fn:years-from-duration(
$value as xs:duration?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples
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 xs:dayTimeDuration component, it must first be converted to an xs:yearMonthDuration.)

8.3.2 fn:months-from-duration

Summary

Returns the number of months in a duration.

Signature
fn:months-from-duration(
$value as xs:duration?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples
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 xs:dayTimeDuration component, it must first be converted to an xs:yearMonthDuration.)

8.3.3 fn:days-from-duration

Summary

Returns the number of days in a duration.

Signature
fn:days-from-duration(
$value as xs:duration?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples
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 xs:yearMonthDuration component, it must first be converted to an xs:dayTimeDuration.)

8.3.4 fn:hours-from-duration

Summary

Returns the number of hours in a duration.

Signature
fn:hours-from-duration(
$value as xs:duration?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples
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 xs:yearMonthDuration component, it must first be converted to an xs:dayTimeDuration.)

8.3.5 fn:minutes-from-duration

Summary

Returns the number of minutes in a duration.

Signature
fn:minutes-from-duration(
$value as xs:duration?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples
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 xs:yearMonthDuration component, it must first be converted to an xs:dayTimeDuration.)

8.3.6 fn:seconds-from-duration

Summary

Returns the number of seconds in a duration.

Signature
fn:seconds-from-duration(
$value as xs:duration?
) as xs:decimal?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples
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 xs:yearMonthDuration component of an xs:duration, it must first be converted to an xs:dayTimeDuration.)

Expression:
seconds-from-duration(
   xs:duration("P1YT1S")
)
Result:
1

(To capture seconds reflected in the xs:yearMonthDuration component, it must first be converted to an xs:dayTimeDuration.)

8.4 Constructing durations

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.

8.4.1 fn:seconds

Changes in 4.0  

  1. New in 4.0  [Issue 959 PR 984 6 February 2024]

Summary

Returns an xs:dayTimeDuration whose length is a given number of seconds.

Signature
fn:seconds(
$value as xs:decimal?
) as xs:dayTimeDuration?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

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.

Examples
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 xs:dateTime value).

Expression:
(
  xs:dateTime('2024-01-31T12:00:00Z') -
  xs:dateTime('1970-01-01T00:00:00Z')
) div seconds(1)
Result:
1706702400

(The expression converts an xs:dateTime value to a Unix timestamp).

8.5 Arithmetic operators on durations

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.

8.5.1 op:add-yearMonthDurations

Summary

Returns the result of adding two xs:yearMonthDuration values.

Operator Mapping

Defines the semantics of the + operator when applied to two xs:yearMonthDuration values.

Signature
op:add-yearMonthDurations(
$arg1 as xs:yearMonthDuration,
$arg2 as xs:yearMonthDuration
) as xs:yearMonthDuration
Rules

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.

Notes

Either duration (and therefore the result) may be negative.

Examples
Expression:
op:add-yearMonthDurations(
  xs:yearMonthDuration("P2Y11M"),
  xs:yearMonthDuration("P3Y3M")
)
Result:
xs:yearMonthDuration("P6Y2M")

8.5.2 op:subtract-yearMonthDurations

Summary

Returns the result of subtracting one xs:yearMonthDuration value from another.

Operator Mapping

Defines the semantics of the - operator when applied to two xs:yearMonthDuration values.

Signature
op:subtract-yearMonthDurations(
$arg1 as xs:yearMonthDuration,
$arg2 as xs:yearMonthDuration
) as xs:yearMonthDuration
Rules

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.

Notes

Either duration (and therefore the result) may be negative.

Examples
Expression:
op:subtract-yearMonthDurations(
  xs:yearMonthDuration("P2Y11M"),
  xs:yearMonthDuration("P3Y3M")
)
Result:
xs:yearMonthDuration("-P4M")

8.5.3 op:multiply-yearMonthDuration

Summary

Returns the result of multiplying $arg1 by $arg2. The result is rounded to the nearest month.

Operator Mapping

Defines the semantics of the * operator when applied to an xs:yearMonthDuration and a numeric value.

Signature
op:multiply-yearMonthDuration(
$arg1 as xs:yearMonthDuration,
$arg2 as xs:double
) as xs:yearMonthDuration
Rules

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.

Error Conditions

A dynamic error is raised [err:FOCA0005] if $arg2 is NaN.

Notes

Either duration (and therefore the result) may be negative.

Examples
Expression:
op:multiply-yearMonthDuration(
  xs:yearMonthDuration("P2Y11M"),
  2.3
)
Result:
xs:yearMonthDuration("P6Y9M")

8.5.4 op:divide-yearMonthDuration

Summary

Returns the result of dividing $arg1 by $arg2. The result is rounded to the nearest month.

Operator Mapping

Defines the semantics of the div operator when applied to an xs:yearMonthDuration and a numeric value.

Signature
op:divide-yearMonthDuration(
$arg1 as xs:yearMonthDuration,
$arg2 as xs:double
) as xs:yearMonthDuration
Rules

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.

Error Conditions

A dynamic error is raised [err:FOCA0005] if $arg2 is NaN.

Notes

Either operand (and therefore the result) may be negative.

Examples
Expression:
op:divide-yearMonthDuration(
  xs:yearMonthDuration("P2Y11M"),
  1.5
)
Result:
xs:yearMonthDuration("P1Y11M")

8.5.5 op:divide-yearMonthDuration-by-yearMonthDuration

Summary

Returns the ratio of two xs:yearMonthDuration values.

Operator Mapping

Defines the semantics of the div operator when applied to two xs:yearMonthDuration values.

Signature
op:divide-yearMonthDuration-by-yearMonthDuration(
$arg1 as xs:yearMonthDuration,
$arg2 as xs:yearMonthDuration
) as xs:decimal
Rules

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.

Notes

Either duration (and therefore the result) may be negative.

Examples
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 xs:yearMonthDuration value in months:

Expression:
op:divide-yearMonthDuration-by-yearMonthDuration(
  xs:yearMonthDuration("P3Y4M"),
  xs:yearMonthDuration("P1M")
)
Result:
40

8.5.6 op:add-dayTimeDurations

Summary

Returns the sum of two xs:dayTimeDuration values.

Operator Mapping

Defines the semantics of the + operator when applied to two xs:dayTimeDuration values.

Signature
op:add-dayTimeDurations(
$arg1 as xs:dayTimeDuration,
$arg2 as xs:dayTimeDuration
) as xs:dayTimeDuration
Rules

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.

Notes

Either duration (and therefore the result) may be negative.

Examples
Expression:
op:add-dayTimeDurations(
  xs:dayTimeDuration("P2DT12H5M"),
  xs:dayTimeDuration("P5DT12H")
)
Result:
xs:dayTimeDuration('P8DT5M')

8.5.7 op:subtract-dayTimeDurations

Summary

Returns the result of subtracting one xs:dayTimeDuration from another.

Operator Mapping

Defines the semantics of the - operator when applied to two xs:dayTimeDuration values.

Signature
op:subtract-dayTimeDurations(
$arg1 as xs:dayTimeDuration,
$arg2 as xs:dayTimeDuration
) as xs:dayTimeDuration
Rules

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.

Notes

Either duration (and therefore the result) may be negative.

Examples
Expression:
op:subtract-dayTimeDurations(
  xs:dayTimeDuration("P2DT12H"),
  xs:dayTimeDuration("P1DT10H30M")
)
Result:
xs:dayTimeDuration('P1DT1H30M')

8.5.8 op:multiply-dayTimeDuration

Summary

Returns the result of multiplying a xs:dayTimeDuration by a number.

Operator Mapping

Defines the semantics of the * operator when applied to an xs:dayTimeDuration and a numeric value.

Signature
op:multiply-dayTimeDuration(
$arg1 as xs:dayTimeDuration,
$arg2 as xs:double
) as xs:dayTimeDuration
Rules

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.

Error Conditions

A dynamic error is raised [err:FOCA0005] if $arg2 is NaN.

Notes

Either operand (and therefore the result) may be negative.

Examples
Expression:
op:multiply-dayTimeDuration(
  xs:dayTimeDuration("PT2H10M"),
  2.1
)
Result:
xs:dayTimeDuration('PT4H33M')

8.5.9 op:divide-dayTimeDuration

Summary

Returns the result of multiplying a xs:dayTimeDuration by a number.

Operator Mapping

Defines the semantics of the div operator when applied to two xs:dayTimeDuration values.

Signature
op:divide-dayTimeDuration(
$arg1 as xs:dayTimeDuration,
$arg2 as xs:double
) as xs:dayTimeDuration
Rules

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.

Error Conditions

A dynamic error is raised [err:FOCA0005] if $arg2 is NaN.

Notes

Either operand (and therefore the result) may be negative.

Examples
Expression:
op:divide-dayTimeDuration(
  xs:dayTimeDuration("P1DT2H30M10.5S"),
  1.5
)
Result:
xs:duration("PT17H40M7S")

8.5.10 op:divide-dayTimeDuration-by-dayTimeDuration

Summary

Returns the ratio of two xs:dayTimeDuration values, as a decimal number.

Operator Mapping

Defines the semantics of the div operator when applied to two xs:dayTimeDuration values.

Signature
op:divide-dayTimeDuration-by-dayTimeDuration(
$arg1 as xs:dayTimeDuration,
$arg2 as xs:dayTimeDuration
) as xs:decimal
Rules

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.

Notes

Either operand (and therefore the result) may be negative.

Examples
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

9 Functions and operators on dates and times

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.

9.1 Date and time types

[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.

9.1.1 Limits and precision

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·.

9.2 Date/time datatype values

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.

9.2.1 Examples

  • 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, () }.

9.3 Constructing a dateTime

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.

9.3.1 fn:dateTime

Summary

Returns an xs:dateTime value created by combining an xs:date and an xs:time.

Signature
fn:dateTime(
$date as xs:date?,
$time as xs:time?
) as xs:dateTime?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Error Conditions

A dynamic error is raised [err:FORG0008] if the two arguments both have timezones and the timezones are different.

Examples
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 "24:00:00" is an alternate lexical form for "00:00:00").

9.3.2 fn:unix-dateTime

Changes in 4.0  

  1. New in 4.0  [Issue 959  1 August 2024]

Summary

Returns a dateTime value for a Unix time.

Signature
fn:unix-dateTime(
$value as xs:nonNegativeInteger? := 0
) as xs:dateTimeStamp
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Formal Specification

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)
Notes

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.

Examples
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 xs:dateTime value:

let $value := current-dateTime()
return ($value - unix-dateTime()) div seconds(0.001)

9.4 Comparison operators on duration, date and time values

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.

9.4.1 op:dateTime-equal

Summary

Returns true if the two supplied xs:dateTime values refer to the same instant in time.

Operator Mapping

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.

Signature
op:dateTime-equal(
$arg1 as xs:dateTime,
$arg2 as xs:dateTime
) as xs:boolean
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

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.

Examples

Assume that the dynamic context provides an implicit timezone value of -05:00

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()

9.4.2 op:dateTime-less-than

Summary

Returns true if the first argument represents an earlier instant in time than the second argument.

Operator Mapping

Defines the semantics of the lt operator when applied to two xs:dateTime values. Also used in the definition of the ge operator.

Signature
op:dateTime-less-than(
$arg1 as xs:dateTime,
$arg2 as xs:dateTime
) as xs:boolean
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

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.

9.4.3 op:date-equal

Summary

Returns true if and only if the starting instants of the two supplied xs:date values are the same.

Operator Mapping

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.

Signature
op:date-equal(
$arg1 as xs:date,
$arg2 as xs:date
) as xs:boolean
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

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))
Examples
Expression Result
op:date-equal(
  xs:date("2004-12-25Z"),
  xs:date("2004-12-25+07:00")
)
false()

(The starting instants are xs:dateTime("2004-12-25T00:00:00Z") and xs:dateTime("2004-12-25T00:00:00+07:00"). These are normalized to xs:dateTime("2004-12-25T00:00:00Z") and xs:dateTime("2004-12-24T17:00:00Z"). ).

op:date-equal(
  xs:date("2004-12-25-12:00"),
  xs:date("2004-12-26+12:00")
)
true()

9.4.4 op:date-less-than

Summary

Returns true if and only if the starting instant of $arg1 is less than the starting instant of $arg2. Returns false otherwise.

Operator Mapping

Defines the semantics of the lt operator when applied to two xs:date values. Also used in the definition of the ge operator.

Signature
op:date-less-than(
$arg1 as xs:date,
$arg2 as xs:date
) as xs:boolean
Rules

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))
Examples
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()

9.4.5 op:time-equal

Summary

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.

Operator Mapping

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.

Signature
op:time-equal(
$arg1 as xs:time,
$arg2 as xs:time
) as xs:boolean
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

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))
Examples
Expression Result

Assume that the date components from the reference xs:dateTime correspond to 1972-12-31.

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 1972-12-31T08:00:00+09:00 and 1972-12-31T17:00:00-06:00, respectively, and normalize to 1972-12-30T23:00:00Z and 1972-12-31T23:00:00Z. ).

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 xs:dateTime values, a time of 24:00:00 is equivalent to 00:00:00 on the following day. For xs:time, the normalization from 24:00:00 to 00:00:00 happens before the xs:time is converted into an xs:dateTime for the purpose of the equality comparison. For xs:time, any operation on 24:00:00 produces the same result as the same operation on 00:00:00 because these are two different lexical representations of the same value. ).

9.4.6 op:time-less-than

Summary

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.

Operator Mapping

Defines the semantics of the lt operator when applied to two xs:time values. Also used in the definition of the ge operator.

Signature
op:time-less-than(
$arg1 as xs:time,
$arg2 as xs:time
) as xs:boolean
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

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))
Examples
Expression Result

Assume that the dynamic context provides an implicit timezone value of -05:00.

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()

9.4.7 op:gYearMonth-equal

Summary

Returns true if the two xs:gYearMonth values have the same starting instant.

Operator Mapping

Defines the semantics of the eq operator when applied to two xs:gYearMonth values. Also used in the definition of the ne operator.

Signature
op:gYearMonth-equal(
$arg1 as xs:gYearMonth,
$arg2 as xs:gYearMonth
) as xs:boolean
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

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.

Examples

Assume that the dynamic context provides an implicit timezone value of -05:00.

op:gYearMonth-equal(xs:gYearMonth("1986-02"), xs:gYearMonth("1986-03")) returns false(). The starting instants are 1986-02-01T00:00:00-05:00 and 1986-03-01T00:00:00, respectively.

op:gYearMonth-equal(xs:gYearMonth("1978-03"), xs:gYearMonth("1986-03Z")) returns false(). The starting instants are 1978-03-01T00:00:00-05:00 and 1986-03-01T00:00:00Z, respectively.

9.4.8 op:gYear-equal

Summary

Returns true if the two xs:gYear values have the same starting instant.

Operator Mapping

Defines the semantics of the eq operator when applied to two xs:gYear values. Also used in the definition of the ne operator.

Signature
op:gYear-equal(
$arg1 as xs:gYear,
$arg2 as xs:gYear
) as xs:boolean
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

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.

Examples
Expression Result

Assume that the dynamic context provides an implicit timezone value of -05:00. Assume, also, that the xs:dateTime template is xxxx-01-01T00:00:00.

op:gYear-equal(xs:gYear("2005-12:00"), xs:gYear("2005+12:00")) returns false(). The starting instants are 2005-01-01T00:00:00-12:00 and 2005-01-01T00:00:00+12:00, respectively, and normalize to 2005-01-01T12:00:00Z and 2004-12-31T12:00:00Z.

op:gYear-equal(
  xs:gYear("1976-05:00"),
  xs:gYear("1976")
)
true()

9.4.9 op:gMonthDay-equal

Summary

Returns true if the two xs:gMonthDay values have the same starting instant, when considered as days in the same year.

Operator Mapping

Defines the semantics of the eq operator when applied to two xs:gMonthDay values. Also used in the definition of the ne operator.

Signature
op:gMonthDay-equal(
$arg1 as xs:gMonthDay,
$arg2 as xs:gMonthDay
) as xs:boolean
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

The starting instants of $arg1 and $arg2 are calculated by supplying the missing components of $arg1 and $arg2 from the xs:dateTime template 1972-xx-xxT00:00:00 or an equivalent. The function returns the result of comparing these two starting instants using op:dateTime-equal.

Examples

Assume that the dynamic context provides an implicit timezone value of -05:00. Assume for the purposes of illustration that the xs:dateTime template used is 1972-xx-xxT00:00:00 (this does not affect the result).

Expression:
op:gMonthDay-equal(
  xs:gMonthDay("--12-25-14:00"),
  xs:gMonthDay("--12-26+10:00")
)
Result:
true()

( The starting instants are 1972-12-25T00:00:00-14:00 and 1972-12-26T00:00:00+10:00, respectively, and normalize to 1972-12-25T14:00:00Z and 1972-12-25T14:00:00Z. ).

Expression:
op:gMonthDay-equal(
  xs:gMonthDay("--12-25"),
  xs:gMonthDay("--12-26Z")
)
Result:
false()

9.4.10 op:gMonth-equal

Summary

Returns true if the two xs:gMonth values have the same starting instant, when considered as months in the same year.

Operator Mapping

Defines the semantics of the eq operator when applied to two xs:gMonth values. Also used in the definition of the ne operator.

Signature
op:gMonth-equal(
$arg1 as xs:gMonth,
$arg2 as xs:gMonth
) as xs:boolean
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

The starting instants of $arg1 and $arg2 are calculated by supplying the missing components of $arg1 and $arg2 from the xs:dateTime template 1972-xx-01T00:00:00 or an equivalent. The function returns the result of comparing these two starting instants using op:dateTime-equal.

Examples
Expression Result

Assume that the dynamic context provides an implicit timezone value of -05:00. Assume, also, that the xs:dateTime template chosen is 1972-xx-01T00:00:00.

op:gMonth-equal(
  xs:gMonth("--12-14:00"),
  xs:gMonth("--12+10:00")
)
false()

( The starting instants are 1972-12-01T00:00:00-14:00 and 1972-12-01T00:00:00+10:00, respectively, and normalize to 1972-11-30T14:00:00Z and 1972-12-01T14:00:00Z. ).

op:gMonth-equal(
  xs:gMonth("--12"),
  xs:gMonth("--12Z")
)
false()

9.4.11 op:gDay-equal

Summary

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.

Operator Mapping

Defines the semantics of the eq operator when applied to two xs:gDay values. Also used in the definition of the ne operator.

Signature
op:gDay-equal(
$arg1 as xs:gDay,
$arg2 as xs:gDay
) as xs:boolean
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

The starting instants of $arg1 and $arg2 are calculated by supplying the missing components of $arg1 and $arg2 from the xs:dateTime template 1972-12-xxT00:00:00 or an equivalent. The function returns the result of comparing these two starting instants using op:dateTime-equal.

Examples
Expression Result

Assume that the dynamic context provides an implicit timezone value of -05:00. Assume, also, that the xs:dateTime template is 1972-12-xxT00:00:00.

op:gDay-equal(
  xs:gDay("---25-14:00"),
  xs:gDay("---25+10:00")
)
false()

( The starting instants are 1972-12-25T00:00:00-14:00 and 1972-12-25T00:00:00+10:00, respectively, and normalize to 1972-12-25T14:00:00Z and 1972-12-24T14:00:00Z. ).

op:gDay-equal(xs:gDay("---12"), xs:gDay("---12Z"))
false()

9.5 Component extraction functions on dates and times

The date and time datatypes may be considered to be composite datatypes in that they contain distinct properties or components. The extraction functions specified below extract a single component from a date or time value. In all cases the local value (that is, the original value as written, without any timezone adjustment) is used.

Note:

A time written as 24:00:00 is treated as 00:00:00 on the following day.

Function Meaning
fn:year-from-dateTime Returns the year component of a ·Gregorian· value.
fn:month-from-dateTime Returns the month component of a ·Gregorian· value.
fn:day-from-dateTime Returns the day component of a ·Gregorian· value.
fn:hours-from-dateTime Returns the hours component of a ·Gregorian· value.
fn:minutes-from-dateTime Returns the minute component of a ·Gregorian· value.
fn:seconds-from-dateTime Returns the seconds component of a ·Gregorian· value.
fn:timezone-from-dateTime Returns the timezone component of a ·Gregorian· value.
fn:year-from-date Returns the year component of an xs:date.
fn:month-from-date Returns the month component of an xs:date.
fn:day-from-date Returns the day component of an xs:date.
fn:timezone-from-date Returns the timezone component of an xs:date.
fn:hours-from-time Returns the hours component of an xs:time.
fn:minutes-from-time Returns the minutes component of an xs:time.
fn:seconds-from-time Returns the seconds component of an xs:time.
fn:timezone-from-time Returns the timezone component of an xs:time.

9.5.1 fn:year-from-dateTime

Changes in 4.0  

  1. The function has been extended to handle other Gregorian types such as xs:gYearMonth.  [Issue 1448 ]

Summary

Returns the year component of a ·Gregorian· value.

Signature
fn:year-from-dateTime(
$value as (xs:dateTime | xs:date | xs:time | xs:gYear | xs:gYearMonth | xs:gMonth | xs:gMonthDay | xs:gDay)?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, or if the year component is absent, the function returns the empty sequence.

Otherwise, the function returns an xs:integer representing the year component in $value. The result may be negative.

Notes

Ignoring complications that arise with midnight on the last day of the year, the year returned is the same numeric value that appears in the lexical representation, which for negative years means the meaning may vary depending on whether XSD 1.0 or XSD 1.1 conventions are in use.

Examples
Expression:
year-from-dateTime(
  xs:dateTime("1999-05-31T13:20:00-05:00")
)
Result:
1999
Expression:
year-from-dateTime(
  xs:dateTime("1999-05-31T21:30:00-05:00")
)
Result:
1999
Expression:
year-from-dateTime(
  xs:dateTime("1999-12-31T19:20:00")
)
Result:
1999
Expression:
year-from-dateTime(
  xs:dateTime("1999-12-31T24:00:00")
)
Result:
2000
Expression:
year-from-dateTime(
  xs:dateTime("-0002-06-06T00:00:00")
)
Result:
-2

(The result is the same whether XSD 1.0 or 1.1 is in use, despite the absence of a year 0 in the XSD 1.0 value space.)

Expression:
year-from-dateTime(
  xs:gYearMonth("2007-05Z")
)
Result:
2007
Expression:
year-from-dateTime(
  xs:time("12:30:00")
)
Result:
()

9.5.2 fn:month-from-dateTime

Changes in 4.0  

  1. The function has been extended to handle other Gregorian types such as xs:gYearMonth.  [Issue 1448 ]

Summary

Returns the month component of a ·Gregorian· value.

Signature
fn:month-from-dateTime(
$value as (xs:dateTime | xs:date | xs:time | xs:gYear | xs:gYearMonth | xs:gMonth | xs:gMonthDay | xs:gDay)?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, or if it contains no month component, the function returns the empty sequence.

Otherwise, the function returns an xs:integer between 1 and 12, both inclusive, representing the month component in $value.

Examples
Expression:
month-from-dateTime(
  xs:dateTime("1999-05-31T13:20:00-05:00")
)
Result:
5
Expression:
month-from-dateTime(
  xs:dateTime("1999-12-31T19:20:00-05:00")
)
Result:
12
Expression:
month-from-dateTime(
  adjust-dateTime-to-timezone(
    xs:dateTime("1999-12-31T19:20:00-05:00"),
    xs:dayTimeDuration("PT0S")
  )
)
Result:
1
Expression:
month-from-dateTime(
  xs:gYearMonth("2007-05Z")
)
Result:
5
Expression:
month-from-dateTime(
  xs:time("12:30:00")
)
Result:
()

9.5.3 fn:day-from-dateTime

Changes in 4.0  

  1. The function has been extended to handle other Gregorian types such as xs:gMonthDay.  [Issue 1448 ]

Summary

Returns the day component of a ·Gregorian· value.

Signature
fn:day-from-dateTime(
$value as (xs:dateTime | xs:date | xs:time | xs:gYear | xs:gYearMonth | xs:gMonth | xs:gMonthDay | xs:gDay)?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, or if it contains no day component, the function returns the empty sequence.

Otherwise, the function returns an xs:integer between 1 and 31, both inclusive, representing the day component in the local value of $value.

Examples
Expression:
day-from-dateTime(
  xs:dateTime("1999-05-31T13:20:00-05:00")
)
Result:
31
Expression:
day-from-dateTime(
  xs:dateTime("1999-12-31T20:00:00-05:00")
)
Result:
31
Expression:
day-from-dateTime(
  adjust-dateTime-to-timezone(
    xs:dateTime("1999-12-31T19:20:00-05:00"),
    xs:dayTimeDuration("PT0S")
  )
)
Result:
1
Expression:
day-from-dateTime(
  xs:gMonthDay("--05-31Z")
)
Result:
31
Expression:
day-from-dateTime(
  xs:time("12:30:00")
)
Result:
()

9.5.4 fn:hours-from-dateTime

Changes in 4.0  

  1. The function has been extended to handle other types including xs:time.  [Issue 1448 ]

Summary

Returns the hours component of a ·Gregorian· value.

Signature
fn:hours-from-dateTime(
$value as (xs:dateTime | xs:date | xs:time | xs:gYear | xs:gYearMonth | xs:gMonth | xs:gMonthDay | xs:gDay)?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, or if it contains no hours component, the function returns the empty sequence.

Otherwise, the function returns an xs:integer between 0 and 23, both inclusive, representing the hours component in $value.

Examples
Expression:
hours-from-dateTime(
  xs:dateTime("1999-05-31T08:20:00-05:00")
)
Result:
8
Expression:
hours-from-dateTime(
  xs:dateTime("1999-12-31T21:20:00-05:00")
)
Result:
21
Expression:
hours-from-dateTime(
  adjust-dateTime-to-timezone(
    xs:dateTime("1999-12-31T21:20:00-05:00"),
    xs:dayTimeDuration("PT0S")
  )
)
Result:
2
Expression:
hours-from-dateTime(
  xs:dateTime("1999-12-31T12:00:00")
)
Result:
12
Expression:
hours-from-dateTime(
  xs:dateTime("1999-12-31T24:00:00")
)
Result:
0
Expression:
hours-from-dateTime(
  xs:gYearMonth("2007-05Z")
)
Result:
()
Expression:
year-from-dateTime(
  xs:time("12:30:00")
)
Result:
12

9.5.5 fn:minutes-from-dateTime

Changes in 4.0  

  1. The function has been extended to handle other types including xs:time.  [Issue 1448 ]

Summary

Returns the minute component of a ·Gregorian· value.

Signature
fn:minutes-from-dateTime(
$value as (xs:dateTime | xs:date | xs:time | xs:gYear | xs:gYearMonth | xs:gMonth | xs:gMonthDay | xs:gDay)?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, or if it contains no minutes component, the function returns the empty sequence.

Otherwise, the function returns an xs:integer value between 0 and 59, both inclusive, representing the minute component in the local value of $value.

Examples
Expression:
minutes-from-dateTime(
  xs:dateTime("1999-05-31T13:20:00-05:00")
)
Result:
20
Expression:
minutes-from-dateTime(
  xs:dateTime("1999-05-31T13:30:00+05:30")
)
Result:
30
Expression:
minutes-from-dateTime(
  xs:gYearMonth("2007-05Z")
)
Result:
()
Expression:
minutes-from-dateTime(
  xs:time("12:30:00")
)
Result:
30

9.5.6 fn:seconds-from-dateTime

Summary

Returns the seconds component of a ·Gregorian· value.

Signature
fn:seconds-from-dateTime(
$value as (xs:dateTime | xs:date | xs:time | xs:gYear | xs:gYearMonth | xs:gMonth | xs:gMonthDay | xs:gDay)?
) as xs:decimal?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, or if it contains no seconds component, the function returns the empty sequence.

Otherwise, the function returns an xs:decimal value greater than or equal to zero and less than 60, representing the seconds and fractional seconds in $value.

Examples
Expression:
seconds-from-dateTime(
  xs:dateTime("1999-05-31T13:20:00-05:00")
)
Result:
0
Expression:
seconds-from-dateTime(
  xs:gYearMonth("2007-05Z")
)
Result:
()
Expression:
seconds-from-dateTime(
  xs:time("12:30:14.5")
)
Result:
14.5

9.5.7 fn:timezone-from-dateTime

Changes in 4.0  

  1. The function has been extended to handle other types such as xs:gYearMonth.  [Issue 1448 ]

Summary

Returns the timezone component of a ·Gregorian· value.

Signature
fn:timezone-from-dateTime(
$value as (xs:dateTime | xs:date | xs:time | xs:gYear | xs:gYearMonth | xs:gMonth | xs:gMonthDay | xs:gDay)?
) as xs:dayTimeDuration?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, the function returns the empty sequence.

Otherwise, the function returns the timezone component of $value, if any. If $value has a timezone component, then the result is an xs:dayTimeDuration that indicates deviation from UTC; its value may range from +14:00 to -14:00 hours, both inclusive. If $value has no timezone component, the result is the empty sequence.

Examples
Expression:
timezone-from-dateTime(
  xs:dateTime("1999-05-31T13:20:00-05:00")
)
Result:
xs:dayTimeDuration("-PT5H")
Expression:
timezone-from-dateTime(
  xs:dateTime("2000-06-12T13:20:00Z")
)
Result:
xs:dayTimeDuration("PT0S")
Expression:
timezone-from-dateTime(
  xs:dateTime("2004-08-27T00:00:00")
)
Result:
()
Expression:
timezone-from-dateTime(
  xs:gYearMonth("2007-05Z")
)
Result:
xs:dayTimeDuration("PT0S")
Expression:
timezone-from-dateTime(
  xs:time("12:30:00")
)
Result:
()

9.5.8 fn:year-from-date

Summary

Returns the year component of an xs:date.

Signature
fn:year-from-date(
$value as xs:date?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, the function returns the empty sequence.

Otherwise, the function returns an xs:integer representing the year in the local value of $value. The value may be negative.

Notes

The year returned is the same numeric value that appears in the lexical representation, which for negative years means the meaning may vary depending on whether XSD 1.0 or XSD 1.1 conventions are in use.

Examples
Expression Result
year-from-date(
  xs:date("1999-05-31")
)
1999
year-from-date(
  xs:date("2000-01-01+05:00")
)
2000
year-from-date(
  xs:date("-0002-06-01")
)
-2

(The result is the same whether XSD 1.0 or 1.1 is in use, despite the absence of a year 0 in the XSD 1.0 value space.)

9.5.9 fn:month-from-date

Summary

Returns the month component of an xs:date.

Signature
fn:month-from-date(
$value as xs:date?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, the function returns the empty sequence.

Otherwise, the function returns an xs:integer between 1 and 12, both inclusive, representing the month component in the local value of $value.

Examples
Expression Result
month-from-date(
  xs:date("1999-05-31-05:00")
)
5
month-from-date(
  xs:date("2000-01-01+05:00")
)
1

9.5.10 fn:day-from-date

Summary

Returns the day component of an xs:date.

Signature
fn:day-from-date(
$value as xs:date?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, the function returns the empty sequence.

Otherwise, the function returns an xs:integer between 1 and 31, both inclusive, representing the day component in the localized value of $value.

Examples
Expression Result
day-from-date(
  xs:date("1999-05-31-05:00")
)
31
day-from-date(
  xs:date("2000-01-01+05:00")
)
1

9.5.11 fn:timezone-from-date

Summary

Returns the timezone component of an xs:date.

Signature
fn:timezone-from-date(
$value as xs:date?
) as xs:dayTimeDuration?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, the function returns the empty sequence.

Otherwise, the function returns the timezone component of $value, if any. If $value has a timezone component, then the result is an xs:dayTimeDuration that indicates deviation from UTC; its value may range from +14:00 to -14:00 hours, both inclusive. If $value has no timezone component, the result is the empty sequence.

Examples
Expression Result
timezone-from-date(
  xs:date("1999-05-31-05:00")
)
xs:dayTimeDuration("-PT5H")
timezone-from-date(
  xs:date("2000-06-12Z")
)
xs:dayTimeDuration("PT0S")

9.5.12 fn:hours-from-time

Summary

Returns the hours component of an xs:time.

Signature
fn:hours-from-time(
$value as xs:time?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, the function returns the empty sequence.

Otherwise, the function returns an xs:integer between 0 and 23, both inclusive, representing the value of the hours component in the local value of $value.

Examples
Expression Result

Assume that the dynamic context provides an implicit timezone value of -05:00.

hours-from-time(xs:time("11:23:00"))
11
hours-from-time(xs:time("21:23:00"))
21
hours-from-time(xs:time("01:23:00+05:00"))
1
hours-from-time(
  adjust-time-to-timezone(
    xs:time("01:23:00+05:00"),
    xs:dayTimeDuration("PT0S")
  )
)
20
hours-from-time(xs:time("24:00:00"))
0

9.5.13 fn:minutes-from-time

Summary

Returns the minutes component of an xs:time.

Signature
fn:minutes-from-time(
$value as xs:time?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, the function returns the empty sequence.

Otherwise, the function returns an xs:integer value between 0 and 59, both inclusive, representing the value of the minutes component in the local value of $value.

Examples
Expression Result
minutes-from-time(xs:time("13:00:00Z"))
0

9.5.14 fn:seconds-from-time

Summary

Returns the seconds component of an xs:time.

Signature
fn:seconds-from-time(
$value as xs:time?
) as xs:decimal?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, the function returns the empty sequence.

Otherwise, the function returns an xs:decimal value greater than or equal to zero and less than 60, representing the seconds and fractional seconds in the local value of $value.

Examples
Expression Result
seconds-from-time(xs:time("13:20:10.5"))
10.5

9.5.15 fn:timezone-from-time

Summary

Returns the timezone component of an xs:time.

Signature
fn:timezone-from-time(
$value as xs:time?
) as xs:dayTimeDuration?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, the function returns the empty sequence.

Otherwise, the function returns the timezone component of $value, if any. If $value has a timezone component, then the result is an xs:dayTimeDuration that indicates deviation from UTC; its value may range from +14:00 to -14:00 hours, both inclusive. If $value has no timezone component, the result is the empty sequence.

Examples
Expression Result
timezone-from-time(xs:time("13:20:00-05:00"))
xs:dayTimeDuration("-PT5H")
timezone-from-time(xs:time("13:20:00"))
()

9.6 Timezone adjustment functions on dates and time values

Function Meaning
fn:adjust-dateTime-to-timezone Adjusts an xs:dateTime value to a specific timezone, or to no timezone at all.
fn:adjust-date-to-timezone Adjusts an xs:date value to a specific timezone, or to no timezone at all; the result is the date in the target timezone that contains the starting instant of the supplied date.
fn:adjust-time-to-timezone Adjusts an xs:time value to a specific timezone, or to no timezone at all.

These functions adjust the timezone component of an xs:dateTime, xs:date or xs:time value. The $timezone argument to these functions is defined as an xs:dayTimeDuration but must be a valid timezone value.

9.6.1 fn:adjust-dateTime-to-timezone

Summary

Adjusts an xs:dateTime value to a specific timezone, or to no timezone at all.

Signature
fn:adjust-dateTime-to-timezone(
$value as xs:dateTime?,
$timezone as xs:dayTimeDuration? := fn:implicit-timezone()
) as xs:dateTime?
Properties

The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $timezone is not specified, then the effective value of $timezone is the value of the implicit timezone in the dynamic context.

If $value is the empty sequence, then the function returns the empty sequence.

If $value does not have a timezone component and $timezone is the empty sequence, then the result is $value.

If $value does not have a timezone component and $timezone is not the empty sequence, then the result is $value with $timezone as the timezone component.

If $value has a timezone component and $timezone is the empty sequence, then the result is the local value of $value without its timezone component.

If $value has a timezone component and $timezone is not the empty sequence, then the result is the xs:dateTime value that is equal to $value and that has a timezone component equal to $timezone.

Error Conditions

A dynamic error is raised [err:FODT0003] if $timezone is less than -PT14H or greater than PT14H or is not an integral number of minutes.

Examples
Variables
let $tz-10 := xs:dayTimeDuration("-PT10H")

Assume the dynamic context provides an implicit timezone of -05:00 (-PT5H0M).

Expression:
adjust-dateTime-to-timezone(
  xs:dateTime('2002-03-07T10:00:00')
)
Result:
xs:dateTime('2002-03-07T10:00:00-05:00')
Expression:
adjust-dateTime-to-timezone(
  xs:dateTime('2002-03-07T10:00:00-07:00')
)
Result:
xs:dateTime('2002-03-07T12:00:00-05:00')
Expression:
adjust-dateTime-to-timezone(
  xs:dateTime('2002-03-07T10:00:00'),
  $tz-10
)
Result:
xs:dateTime('2002-03-07T10:00:00-10:00')
Expression:
adjust-dateTime-to-timezone(
  xs:dateTime('2002-03-07T10:00:00-07:00'),
  $tz-10
)
Result:
xs:dateTime('2002-03-07T07:00:00-10:00')
Expression:
adjust-dateTime-to-timezone(
  xs:dateTime('2002-03-07T10:00:00-07:00'),
  xs:dayTimeDuration("PT10H")
)
Result:
xs:dateTime('2002-03-08T03:00:00+10:00')
Expression:
adjust-dateTime-to-timezone(
  xs:dateTime('2002-03-07T00:00:00+01:00'),
  xs:dayTimeDuration("-PT8H")
)
Result:
xs:dateTime('2002-03-06T15:00:00-08:00')
Expression:
adjust-dateTime-to-timezone(
  xs:dateTime('2002-03-07T10:00:00'),
  ()
)
Result:
xs:dateTime('2002-03-07T10:00:00')
Expression:
adjust-dateTime-to-timezone(
  xs:dateTime('2002-03-07T10:00:00-07:00'),
  ()
)
Result:
xs:dateTime('2002-03-07T10:00:00')

9.6.2 fn:adjust-date-to-timezone

Summary

Adjusts an xs:date value to a specific timezone, or to no timezone at all; the result is the date in the target timezone that contains the starting instant of the supplied date.

Signature
fn:adjust-date-to-timezone(
$value as xs:date?,
$timezone as xs:dayTimeDuration? := fn:implicit-timezone()
) as xs:date?
Properties

The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $timezone is not specified, then the effective value of $timezone is the value of the implicit timezone in the dynamic context.

If $value is the empty sequence, then the function returns the empty sequence.

If $value does not have a timezone component and $timezone is the empty sequence, then the result is $value.

If $value does not have a timezone component and $timezone is not the empty sequence, then the result is $value with $timezone as the timezone component.

If $value has a timezone component and $timezone is the empty sequence, then the result is the local value of $value without its timezone component.

If $value has a timezone component and $timezone is not the empty sequence, then:

  • Let $dt be the value of fn:dateTime($arg, xs:time('00:00:00')).

  • Let $adt be the value of fn:adjust-dateTime-to-timezone($dt, $timezone)

  • The function returns the value of xs:date($adt)

Error Conditions

A dynamic error is raised [err:FODT0003] if $timezone is less than -PT14H or greater than PT14H or is not an integral number of minutes.

Examples
Variables
let $tz-10 := xs:dayTimeDuration("-PT10H")
Expression Result

Assume the dynamic context provides an implicit timezone of -05:00 (-PT5H0M).

adjust-date-to-timezone(
  xs:date("2002-03-07")
)
xs:date("2002-03-07-05:00")
adjust-date-to-timezone(
  xs:date("2002-03-07-07:00")
)
xs:date("2002-03-07-05:00")

($value is converted to xs:dateTime("2002-03-07T00:00:00-07:00"). This is adjusted to the implicit timezone, giving "2002-03-07T02:00:00-05:00". ).

adjust-date-to-timezone(
  xs:date("2002-03-07"),
  $tz-10
)
xs:date("2002-03-07-10:00")
adjust-date-to-timezone(
  xs:date("2002-03-07-07:00"),
  $tz-10
)
xs:date("2002-03-06-10:00")

($value is converted to xs:dateTime("2002-03-07T00:00:00-07:00"). This is adjusted to the given timezone, giving "2002-03-06T21:00:00-10:00". ).

adjust-date-to-timezone(
  xs:date("2002-03-07"),
  ()
)
xs:date("2002-03-07")
adjust-date-to-timezone(
  xs:date("2002-03-07-07:00"),
  ()
)
xs:date("2002-03-07")

9.6.3 fn:adjust-time-to-timezone

Summary

Adjusts an xs:time value to a specific timezone, or to no timezone at all.

Signature
fn:adjust-time-to-timezone(
$value as xs:time?,
$timezone as xs:dayTimeDuration? := fn:implicit-timezone()
) as xs:time?
Properties

The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $timezone is not specified, then the effective value of $timezone is the value of the implicit timezone in the dynamic context.

If $value is the empty sequence, then the function returns the empty sequence.

If $value does not have a timezone component and $timezone is the empty sequence, then the result is $value.

If $value does not have a timezone component and $timezone is not the empty sequence, then the result is $value with $timezone as the timezone component.

If $value has a timezone component and $timezone is the empty sequence, then the result is the localized value of $value without its timezone component.

If $value has a timezone component and $timezone is not the empty sequence, then:

  • Let $dt be the xs:dateTime value fn:dateTime(xs:date('1972-12-31'), $value).

  • Let $adt be the value of fn:adjust-dateTime-to-timezone($dt, $timezone)

  • The function returns the xs:time value xs:time($adt).

Error Conditions

A dynamic error is raised [err:FODT0003] if $timezone is less than -PT14H or greater than PT14H or if does not contain an integral number of minutes.

Examples
Variables
let $tz-10 := xs:dayTimeDuration("-PT10H")
Expression Result

Assume the dynamic context provides an implicit timezone of -05:00 (-PT5H0M).

adjust-time-to-timezone(
  xs:time("10:00:00")
)
xs:time("10:00:00-05:00")
adjust-time-to-timezone(
  xs:time("10:00:00-07:00")
)
xs:time("12:00:00-05:00")
adjust-time-to-timezone(
  xs:time("10:00:00"),
  $tz-10
)
xs:time("10:00:00-10:00")
adjust-time-to-timezone(
  xs:time("10:00:00-07:00"),
  $tz-10
)
xs:time("07:00:00-10:00")
adjust-time-to-timezone(
  xs:time("10:00:00"),
  ()
)
xs:time("10:00:00")
adjust-time-to-timezone(
  xs:time("10:00:00-07:00"),
  ()
)
xs:time("10:00:00")
adjust-time-to-timezone(
  xs:time("10:00:00-07:00"),
  xs:dayTimeDuration("PT10H")
)
xs:time("03:00:00+10:00")

9.7 Arithmetic operators on durations, dates and times

These functions support adding or subtracting a duration value to or from an xs:dateTime, an xs:date or an xs:time value. Appendix E of [XML Schema Part 2: Datatypes Second Edition] describes an algorithm for performing such operations.

Function Meaning
op:subtract-dateTimes Returns an xs:dayTimeDuration representing the amount of elapsed time between the instants arg2 and arg1.
op:subtract-dates Returns the xs:dayTimeDuration that corresponds to the elapsed time between the starting instant of $arg2 and the starting instant of $arg2.
op:subtract-times Returns the xs:dayTimeDuration that corresponds to the elapsed time between the values of $arg2 and $arg1 treated as times on the same date.
op:add-yearMonthDuration-to-dateTime Returns the xs:dateTime that is a given duration after a specified xs:dateTime (or before, if the duration is negative).
op:add-dayTimeDuration-to-dateTime Returns the xs:dateTime that is a given duration after a specified xs:dateTime (or before, if the duration is negative).
op:subtract-yearMonthDuration-from-dateTime Returns the xs:dateTime that is a given duration before a specified xs:dateTime (or after, if the duration is negative).
op:subtract-dayTimeDuration-from-dateTime Returns the xs:dateTime that is a given duration before a specified xs:dateTime (or after, if the duration is negative).
op:add-yearMonthDuration-to-date Returns the xs:date that is a given duration after a specified xs:date (or before, if the duration is negative).
op:add-dayTimeDuration-to-date Returns the xs:date that is a given duration after a specified xs:date (or before, if the duration is negative).
op:subtract-yearMonthDuration-from-date Returns the xs:date that is a given duration before a specified xs:date (or after, if the duration is negative).
op:subtract-dayTimeDuration-from-date Returns the xs:date that is a given duration before a specified xs:date (or after, if the duration is negative).
op:add-dayTimeDuration-to-time Returns the xs:time value that is a given duration after a specified xs:time (or before, if the duration is negative or causes wrap-around past midnight)
op:subtract-dayTimeDuration-from-time Returns the xs:time value that is a given duration before a specified xs:time (or after, if the duration is negative or causes wrap-around past midnight)

9.7.1 Limits and precision

A processor that limits the number of digits in date and time datatype representations may encounter overflow and underflow conditions when it tries to execute the functions in this section. In these situations, the processor must return P0M or PT0S in case of duration underflow and 00:00:00 in case of time underflow. It must raise a dynamic error [err:FODT0001] in case of overflow.

The value spaces of the two totally ordered subtypes of xs:duration described in 8.1.1 Subtypes of duration are xs:integer months for xs:yearMonthDuration and xs:decimal seconds for xs:dayTimeDuration. If a processor limits the number of digits allowed in the representation of xs:integer and xs:decimal then overflow and underflow situations can arise when it tries to execute the functions in 8.5 Arithmetic operators on durations. In these situations the processor must return zero in case of numeric underflow and P0M or PT0S in case of duration underflow. It must raise a dynamic error [err:FODT0002] in case of overflow.

9.7.2 op:subtract-dateTimes

Summary

Returns an xs:dayTimeDuration representing the amount of elapsed time between the instants arg2 and arg1.

Operator Mapping

Defines the semantics of the - operator when applied to two xs:dateTime values.

Signature
op:subtract-dateTimes(
$arg1 as xs:dateTime,
$arg2 as xs:dateTime
) as xs:dayTimeDuration
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

If either $arg1 or $arg2 do not contain an explicit timezone then, for the purpose of the operation, the implicit timezone provided by the dynamic context (See Section C.2 Dynamic Context Components XP31.) is assumed to be present as part of the value.

The function returns the elapsed time between the date/time instant arg2 and the date/time instant arg1, computed according to the algorithm given in Appendix E of [XML Schema Part 2: Datatypes Second Edition], and expressed as a xs:dayTimeDuration.

If the normalized value of $arg1 precedes in time the normalized value of $arg2, then the returned value is a negative duration.

Examples

Assume that the dynamic context provides an implicit timezone value of -05:00.

Expression:
op:subtract-dateTimes(
  xs:dateTime("2000-10-30T06:12:00"),
  xs:dateTime("1999-11-28T09:00:00Z")
)
Result:
xs:dayTimeDuration("P337DT2H12M")

9.7.3 op:subtract-dates

Summary

Returns the xs:dayTimeDuration that corresponds to the elapsed time between the starting instant of $arg2 and the starting instant of $arg2.

Operator Mapping

Defines the semantics of the - operator when applied to two xs:date values.

Signature
op:subtract-dates(
$arg1 as xs:date,
$arg2 as xs:date
) as xs:dayTimeDuration
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

If either $arg1 or $arg2 do not contain an explicit timezone then, for the purpose of the operation, the implicit timezone provided by the dynamic context (See Section C.2 Dynamic Context Components XP31.) is assumed to be present as part of the value.

The starting instant of an xs:date is the xs:dateTime at 00:00:00 on that date.

The function returns the result of subtracting the two starting instants using op:subtract-dateTimes.

If the starting instant of $arg1 precedes in time the starting instant of $arg2, then the returned value is a negative duration.

Examples
Expression Result

Assume that the dynamic context provides an implicit timezone value of Z.

op:subtract-dates(
  xs:date("2000-10-30"),
  xs:date("1999-11-28")
)
xs:dayTimeDuration("P337D")

(The normalized values of the two starting instants are {2000, 10, 30, 0, 0, 0, xs:dayTimeDuration("PT0S")} and {1999, 11, 28, 0, 0, 0, xs:dayTimeDuration("PT0S")}.)

Now assume that the dynamic context provides an implicit timezone value of +05:00.

op:subtract-dates(
  xs:date("2000-10-30"),
  xs:date("1999-11-28Z")
)
xs:dayTimeDuration("P336DT19H")

( The normalized values of the two starting instants are {2000, 10, 29, 19, 0, 0, xs:dayTimeDuration("PT0S")} and {1999, 11, 28, 0, 0, 0, xs:dayTimeDuration("PT0S")}.)

op:subtract-dates(
  xs:date("2000-10-15-05:00"),
  xs:date("2000-10-10+02:00")
)
xs:dayTimeDuration("P5DT7H")

9.7.4 op:subtract-times

Summary

Returns the xs:dayTimeDuration that corresponds to the elapsed time between the values of $arg2 and $arg1 treated as times on the same date.

Operator Mapping

Defines the semantics of the - operator when applied to two xs:time values.

Signature
op:subtract-times(
$arg1 as xs:time,
$arg2 as xs:time
) as xs:dayTimeDuration
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

The function returns the result of the expression:

op-subtract-dateTimes(
        dateTime(xs:date('1972-12-31'), $arg1),
        dateTime(xs:date('1972-12-31'), $arg2))
Notes

Any other reference date would work equally well.

Examples
Expression Result

Assume that the dynamic context provides an implicit timezone value of -05:00. Assume, also, that the date components of the reference xs:dateTime correspond to "1972-12-31".

op:subtract-times(
  xs:time("11:12:00Z"),
  xs:time("04:00:00")
)
xs:dayTimeDuration("PT2H12M")

(This is obtained by subtracting from the xs:dateTime value {1972, 12, 31, 11, 12, 0, xs:dayTimeDuration("PT0S")} the xs:dateTime value {1972, 12, 31, 9, 0, 0, xs:dayTimeDuration("PT0S")}.)

op:subtract-times(
  xs:time("11:00:00-05:00"),
  xs:time("21:30:00+05:30")
)
xs:dayTimeDuration("PT0S")

(The two xs:dateTime values are {1972, 12, 31, 11, 0, 0, xs:dayTimeDuration("-PT5H")} and {1972, 12, 31, 21, 30, 0, xs:dayTimeDuration("PT5H30M")}. These normalize to {1972, 12, 31, 16, 0, 0, xs:dayTimeDuration("PT0S")} and {1972, 12, 31, 16, 0, 0, xs:dayTimeDuration("PT0S")}. ).

op:subtract-times(
  xs:time("17:00:00-06:00"),
  xs:time("08:00:00+09:00")
)
xs:dayTimeDuration("P1D")

(The two normalized xs:dateTime values are {1972, 12, 31, 23, 0, 0, xs:dayTimeDuration("PT0S")} and {1972, 12, 30, 23, 0, 0, xs:dayTimeDuration("PT0S")}.)

op:subtract-times(
  xs:time("24:00:00"),
  xs:time("23:59:59")
)
xs:dayTimeDuration("-PT23H59M59S")

(The two normalized xs:dateTime values are {1972, 12, 31, 0, 0, 0, ()} and {1972, 12, 31, 23, 59, 59.0, ()}.)

9.7.5 op:add-yearMonthDuration-to-dateTime

Summary

Returns the xs:dateTime that is a given duration after a specified xs:dateTime (or before, if the duration is negative).

Operator Mapping

Defines the semantics of the + operator when applied to an xs:dateTime and an xs:yearMonthDuration value.

Signature
op:add-yearMonthDuration-to-dateTime(
$arg1 as xs:dateTime,
$arg2 as xs:yearMonthDuration
) as xs:dateTime
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the result of adding $arg2 to the value of $arg1 using the algorithm described in Appendix E of [XML Schema Part 2: Datatypes Second Edition], disregarding the rule about leap seconds. If $arg2 is negative, then the result xs:dateTime precedes $arg1.

The result has the same timezone as $arg1. If $arg1 has no timezone, the result has no timezone.

Examples
Expression:
op:add-yearMonthDuration-to-dateTime(
  xs:dateTime("2000-10-30T11:12:00"),
  xs:yearMonthDuration("P1Y2M")
)
Result:
xs:dateTime("2001-12-30T11:12:00")

9.7.6 op:add-dayTimeDuration-to-dateTime

Summary

Returns the xs:dateTime that is a given duration after a specified xs:dateTime (or before, if the duration is negative).

Operator Mapping

Defines the semantics of the + operator when applied to an xs:dateTime and an xs:dayTimeDuration value.

Signature
op:add-dayTimeDuration-to-dateTime(
$arg1 as xs:dateTime,
$arg2 as xs:dayTimeDuration
) as xs:dateTime
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the result of adding $arg2 to the value of $arg1 using the algorithm described in Appendix E of [XML Schema Part 2: Datatypes Second Edition], disregarding the rule about leap seconds. If $arg2 is negative, then the result xs:dateTime precedes $arg1.

The result has the same timezone as $arg1. If $arg1 has no timezone, the result has no timezone.

Examples
Expression:
op:add-dayTimeDuration-to-dateTime(
  xs:dateTime("2000-10-30T11:12:00"),
  xs:dayTimeDuration("P3DT1H15M")
)
Result:
xs:dateTime("2000-11-02T12:27:00")

9.7.7 op:subtract-yearMonthDuration-from-dateTime

Summary

Returns the xs:dateTime that is a given duration before a specified xs:dateTime (or after, if the duration is negative).

Operator Mapping

Defines the semantics of the - operator when applied to an xs:dateTime and an xs:yearMonthDuration value.

Signature
op:subtract-yearMonthDuration-from-dateTime(
$arg1 as xs:dateTime,
$arg2 as xs:yearMonthDuration
) as xs:dateTime
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the xs:dateTime computed by negating $arg2 and adding the result to $arg1 using the function op:add-yearMonthDuration-to-dateTime.

Examples
Expression:
op:subtract-yearMonthDuration-from-dateTime(
  xs:dateTime("2000-10-30T11:12:00"),
  xs:yearMonthDuration("P1Y2M")
)
Result:
xs:dateTime("1999-08-30T11:12:00")

9.7.8 op:subtract-dayTimeDuration-from-dateTime

Summary

Returns the xs:dateTime that is a given duration before a specified xs:dateTime (or after, if the duration is negative).

Operator Mapping

Defines the semantics of the - operator when applied to an xs:dateTime an and xs:dayTimeDuration values

Signature
op:subtract-dayTimeDuration-from-dateTime(
$arg1 as xs:dateTime,
$arg2 as xs:dayTimeDuration
) as xs:dateTime
Rules

The function returns the xs:dateTime computed by negating $arg2 and adding the result to $arg1 using the function op:add-dayTimeDuration-to-dateTime.

Examples
Expression:
op:subtract-dayTimeDuration-from-dateTime(
  xs:dateTime("2000-10-30T11:12:00"),
  xs:dayTimeDuration("P3DT1H15M")
)
Result:
xs:dateTime("2000-10-27T09:57:00")

9.7.9 op:add-yearMonthDuration-to-date

Summary

Returns the xs:date that is a given duration after a specified xs:date (or before, if the duration is negative).

Operator Mapping

Defines the semantics of the + operator when applied to an xs:date and an xs:yearMonthDuration value.

Signature
op:add-yearMonthDuration-to-date(
$arg1 as xs:date,
$arg2 as xs:yearMonthDuration
) as xs:date
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the result of casting $arg1 to an xs:dateTime, adding $arg2 using the function op:add-yearMonthDuration-to-dateTime, and casting the result back to an xs:date.

Examples
Expression:
op:add-yearMonthDuration-to-date(
  xs:date("2000-10-30"),
  xs:yearMonthDuration("P1Y2M")
)
Result:
xs:date("2001-12-30")

9.7.10 op:add-dayTimeDuration-to-date

Summary

Returns the xs:date that is a given duration after a specified xs:date (or before, if the duration is negative).

Operator Mapping

Defines the semantics of the + operator when applied to an xs:date and an xs:dayTimeDuration value.

Signature
op:add-dayTimeDuration-to-date(
$arg1 as xs:date,
$arg2 as xs:dayTimeDuration
) as xs:date
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the result of casting $arg1 to an xs:dateTime, adding $arg2 using the function op:add-dayTimeDuration-to-dateTime, and casting the result back to an xs:date.

Examples
Expression:
op:add-dayTimeDuration-to-date(
  xs:date("2004-10-30Z"),
  xs:dayTimeDuration("P2DT2H30M0S")
)
Result:
xs:date("2004-11-01Z")

( The starting instant of the first argument is the xs:dateTime value {2004, 10, 30, 0, 0, 0, xs:dayTimeDuration("PT0S")}. Adding the second argument to this gives the xs:dateTime value {2004, 11, 1, 2, 30, 0, xs:dayTimeDuration("PT0S")}. The time components are then discarded. ).

9.7.11 op:subtract-yearMonthDuration-from-date

Summary

Returns the xs:date that is a given duration before a specified xs:date (or after, if the duration is negative).

Operator Mapping

Defines the semantics of the - operator when applied to an xs:date and an xs:yearMonthDuration value.

Signature
op:subtract-yearMonthDuration-from-date(
$arg1 as xs:date,
$arg2 as xs:yearMonthDuration
) as xs:date
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Returns the xs:date computed by negating $arg2 and adding the result to $arg1 using the function op:add-yearMonthDuration-to-date.

Examples
Expression:
op:subtract-yearMonthDuration-from-date(
  xs:date("2000-10-30"),
  xs:yearMonthDuration("P1Y2M")
)
Result:
xs:date("1999-08-30")
Expression:
op:subtract-yearMonthDuration-from-date(
  xs:date("2000-02-29Z"),
  xs:yearMonthDuration("P1Y")
)
Result:
xs:date("1999-02-28Z")
Expression:
op:subtract-yearMonthDuration-from-date(
  xs:date("2000-10-31-05:00"),
  xs:yearMonthDuration("P1Y1M")
)
Result:
xs:date("1999-09-30-05:00")

9.7.12 op:subtract-dayTimeDuration-from-date

Summary

Returns the xs:date that is a given duration before a specified xs:date (or after, if the duration is negative).

Operator Mapping

Defines the semantics of the - operator when applied to an xs:date and an xs:dayTimeDuration.

Signature
op:subtract-dayTimeDuration-from-date(
$arg1 as xs:date,
$arg2 as xs:dayTimeDuration
) as xs:date
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Returns the xs:date computed by negating $arg2 and adding the result to $arg1 using the function op:add-dayTimeDuration-to-date.

Examples
Expression:
op:subtract-dayTimeDuration-from-date(
  xs:date("2000-10-30"),
  xs:dayTimeDuration("P3DT1H15M")
)
Result:
xs:date("2000-10-26")

9.7.13 op:add-dayTimeDuration-to-time

Summary

Returns the xs:time value that is a given duration after a specified xs:time (or before, if the duration is negative or causes wrap-around past midnight)

Operator Mapping

Defines the semantics of the + operator when applied to an xs:time and an xs:dayTimeDuration value.

Signature
op:add-dayTimeDuration-to-time(
$arg1 as xs:time,
$arg2 as xs:dayTimeDuration
) as xs:time
Rules

First, the days component in the canonical lexical representation of $arg2 is set to zero (0) and the value of the resulting xs:dayTimeDuration is calculated. Alternatively, the value of $arg2 modulus 86,400 is used as the second argument. This value is added to the value of $arg1 converted to an xs:dateTime using a reference date such as 1972-12-31, and the time component of the result is returned. Note that the xs:time returned may occur in a following or preceding day and may be less than $arg1.

The result has the same timezone as $arg1. If $arg1 has no timezone, the result has no timezone.

Examples
Expression:
op:add-dayTimeDuration-to-time(
  xs:time("11:12:00"),
  xs:dayTimeDuration("P3DT1H15M")
)
Result:
xs:time("12:27:00")
Expression:
op:add-dayTimeDuration-to-time(
  xs:time("23:12:00+03:00"),
  xs:dayTimeDuration("P1DT3H15M")
)
Result:
xs:time("02:27:00+03:00")

(That is, {0, 0, 0, 2, 27, 0, xs:dayTimeDuration("PT3H")}).

9.7.14 op:subtract-dayTimeDuration-from-time

Summary

Returns the xs:time value that is a given duration before a specified xs:time (or after, if the duration is negative or causes wrap-around past midnight)

Operator Mapping

Defines the semantics of the - operator when applied to an xs:time and an xs:dayTimeDuration value.

Signature
op:subtract-dayTimeDuration-from-time(
$arg1 as xs:time,
$arg2 as xs:dayTimeDuration
) as xs:time
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the result of negating $arg2 and adding the result to $arg1 using the function op:add-dayTimeDuration-to-time.

Examples
Expression:
op:subtract-dayTimeDuration-from-time(
  xs:time("11:12:00"),
  xs:dayTimeDuration("P3DT1H15M")
)
Result:
xs:time("09:57:00")
Expression:
op:subtract-dayTimeDuration-from-time(
  xs:time("08:20:00-05:00"),
  xs:dayTimeDuration("P23DT10H10M")
)
Result:
xs:time("22:10:00-05:00")

9.8 Formatting dates and times

Function Meaning
fn:format-dateTime Returns a string containing an xs:dateTime value formatted for display.
fn:format-date Returns a string containing an xs:date value formatted for display.
fn:format-time Returns a string containing an xs:time value formatted for display.

Three functions are provided to represent dates and times as a string, using the conventions of a selected calendar, language, and country. The functions are presented in their customary fashion, except for the rules and examples, which are described en bloc at 9.8.4 The date/time formatting functions and 9.8.5 Examples of date and time formatting.

9.8.1 fn:format-dateTime

Changes in 4.0  

  1. The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.  [Issue 895 PR 901 16 December 2023]

Summary

Returns a string containing an xs:dateTime value formatted for display.

Signature
fn:format-dateTime(
$value as xs:dateTime?,
$picture as xs:string,
$language as xs:string? := (),
$calendar as xs:string? := (),
$place as xs:string? := ()
) as xs:string?
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default calendar, and default language, and default place, and implicit timezone.

Rules

See 9.8.4 The date/time formatting functions.

9.8.2 fn:format-date

Changes in 4.0  

  1. The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.  [Issue 895 PR 901 16 December 2023]

Summary

Returns a string containing an xs:date value formatted for display.

Signature
fn:format-date(
$value as xs:date?,
$picture as xs:string,
$language as xs:string? := (),
$calendar as xs:string? := (),
$place as xs:string? := ()
) as xs:string?
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default calendar, and default language, and default place, and implicit timezone.

Rules

See 9.8.4 The date/time formatting functions.

9.8.3 fn:format-time

Changes in 4.0  

  1. The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.  [Issue 895 PR 901 16 December 2023]

Summary

Returns a string containing an xs:time value formatted for display.

Signature
fn:format-time(
$value as xs:time?,
$picture as xs:string,
$language as xs:string? := (),
$calendar as xs:string? := (),
$place as xs:string? := ()
) as xs:string?
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default calendar, and default language, and default place, and implicit timezone.

Rules

See 9.8.4 The date/time formatting functions.

9.8.4 The date/time formatting functions

The fn:format-dateTime, fn:format-date, and fn:format-time functions format $value as a string using the picture string specified by the $picture argument, the calendar specified by the $calendar argument, the language specified by the $language argument, and the country or other place name specified by the $place argument. The result of the function is the formatted string representation of the supplied xs:dateTime, xs:date, or xs:time value.

[Definition] The three functions fn:format-dateTime, fn:format-date, and fn:format-time are referred to collectively as the date formatting functions.

If $value is the empty sequence, the function returns the empty sequence.

Calling the two-argument form of each of the three functions is equivalent to calling the five-argument form with each of the last three arguments set to an empty sequence.

For details of the $language, $calendar, and $place arguments, see 9.8.4.8 The language, calendar, and place arguments.

In general, the use of an invalid $picture, $language, $calendar, or $place argument results in a dynamic error [err:FOFD1340]. By contrast, use of an option in any of these arguments that is valid but not supported by the implementation is not an error, and in these cases the implementation is required to output the value in a fallback representation. More detailed rules are given below.

9.8.4.1 The picture string

The picture consists of a sequence of variable markers and literal substrings. A substring enclosed in square brackets is interpreted as a variable marker; substrings not enclosed in square brackets are taken as literal substrings. The literal substrings are optional and if present are rendered unchanged, including any whitespace. If an opening or closing square bracket is required within a literal substring, it must be doubled. The variable markers are replaced in the result by strings representing aspects of the date and/or time to be formatted. These are described in detail below.

A variable marker consists of a component specifier followed optionally by one or two presentation modifiers and/or optionally by a width modifier. Whitespace within a variable marker is ignored.

The variable marker may be separated into its components by applying the following rules:

  1. The component specifier is always present and is always a single letter.

  2. The width modifier may be recognized by the presence of a comma.

  3. The substring between the component specifier and the comma (if present) or the end of the string (if there is no comma) contains the first and second presentation modifiers, both of which are optional. If this substring contains a single character, this is interpreted as the first presentation modifier. If it contains more than one character, the last character is examined: if it is valid as a second presentation modifier then it is treated as such, and the preceding part of the substring constitutes the first presentation modifier. Otherwise, the second presentation modifier is presumed absent and the whole substring is interpreted as the first presentation modifier.

The component specifier indicates the component of the date or time that is required, and takes the following values:

Specifier Meaning Default Presentation Modifier
Y year (absolute value) 1
M month in year 1
D day in month 1
d day in year 1
F day of week n
W week in year 1
w week in month 1
H hour in day (24 hours) 1
h hour in half-day (12 hours) 1
P am/pm marker n
m minute in hour 01
s second in minute 01
f fractional seconds 1
Z timezone 01:01
z timezone (Same as Z, but modified where appropriate to include a prefix as a time offset using GMT, for example GMT+1 or GMT-05:00. For this component there is a fixed prefix of GMT, or a localized variation thereof for the chosen language, and the remainder of the value is formatted as for specifier Z.) 01:01
C calendar: the name or abbreviation of a calendar name n
E era: the name of a baseline for the numbering of years, for example the reign of a monarch n

A dynamic error is reported [err:FOFD1340] if the syntax of the picture is incorrect.

A dynamic error is reported [err:FOFD1350] if a component specifier within the picture refers to components that are not available in the given type of $value, for example if the picture supplied to the fn:format-time refers to the year, month, or day component.

It is not an error to include a timezone component when the supplied value has no timezone. In these circumstances the timezone component will be ignored.

The first presentation modifier indicates the style in which the value of a component is to be represented. Its value may be either:

  • any format token permitted as a primary format token in the second argument of the fn:format-integer function, indicating that the value of the component is to be output numerically using the specified number format (for example, 1, 01, i, I, w, W, or Ww) or

  • the format token n, N, or Nn, indicating that the value of the component is to be output by name, in lower-case, upper-case, or title-case respectively. Components that can be output by name include (but are not limited to) months, days of the week, timezones, and eras. If the processor cannot output these components by name for the chosen calendar and language then it must use an ·implementation-defined· fallback representation.

If a comma is to be used as a grouping separator within the format token, then there must be a width specifier. More specifically: if a variable marker contains one or more commas, then the last comma is treated as introducing the width modifier, and all others are treated as grouping separators. So [Y9,999,*] will output the year as 2,008.

It is not possible to use a closing square bracket as a grouping separator within the format token.

If the implementation does not support the use of the requested format token, it must use the default presentation modifier for that component.

If the first presentation modifier is present, then it may optionally be followed by a second presentation modifier as follows:

Modifier Meaning
either a or t indicates alphabetic or traditional numbering respectively, the default being ·implementation-defined·. This has the same meaning as in the second argument of fn:format-integer.
either c or o indicates cardinal or ordinal numbering respectively, for example 7 or seven for a cardinal number, or 7th, seventh, or for an ordinal number. This has the same meaning as in the second argument of fn:format-integer. The actual representation of the ordinal form of a number may depend not only on the language, but also on the grammatical context (for example, in some languages it must agree in gender).

Note:

Although the formatting rules are expressed in terms of the rules for format tokens in fn:format-integer, the formats actually used may be specialized to the numbering of date components where appropriate. For example, in Italian, it is conventional to use an ordinal number (primo) for the first day of the month, and cardinal numbers (due, tre, quattro ...) for the remaining days. A processor may therefore use this convention to number days of the month, ignoring the presence or absence of the ordinal presentation modifier.

9.8.4.2 The Width Modifier

Whether or not a presentation modifier is included, a width modifier may be supplied. This indicates the number of characters to be included in the representation of the value.

The width modifier, if present, is introduced by a comma. It takes the form:

   ","  min-width ("-" max-width)?

where min-width is either an unsigned integer indicating the minimum number of characters to be output, or * indicating that there is no explicit minimum, and max-width is either an unsigned integer indicating the maximum number of characters to be output, or * indicating that there is no explicit maximum; if max-width is omitted then * is assumed.

A dynamic error ([err:FOFD1340]) is raised if min-width is present and less than one, or if max-width is present and less than one or less than min-width.

A format token containing more than one digit, such as 001 or 9999, sets the minimum and maximum width to the number of digits appearing in the format token; if a width modifier is also present, then the width modifier takes precedence.

9.8.4.3 Formatting Integer-Valued Date/Time Components

The rules in this section apply to the majority of integer-valued components: specifically M D d F W w H h m s.

In the rules below, the term decimal digit pattern has the meaning given in 4.6.1 fn:format-integer.

  1. If the first presentation modifier takes the form of a decimal digit pattern:

    1. If there is no width modifier, then the value is formatted according to the rules of the format-integer function.

    2. If there is a width modifier, then the first presentation modifier is adjusted as follows:

      1. If the decimal digit pattern includes a grouping separator, the output is implementation-defined (but this is not an error).

        Note:

        Use of a width modifier together with grouping separators is inadvisable for this reason. It is never necessary to use a width modifier with a decimal digit pattern, since the same effect can be achieved by use of optional digit signs.

      2. Otherwise, the number of mandatory-digit-sign characters in the presentation modifier is increased if necessary. This is done first by replacing optional-digit-signs with mandatory-digit-signs, starting from the right, and then prepending mandatory-digit-signs to the presentation modifier, until the number of mandatory-digit-signs is equal to the minimum width. Any mandatory-digit-signs that are added by this process must use the same decimal digit family as existing mandatory-digit-signs in the presentation modifier if there are any, or ASCII digits otherwise.

      3. The maximum width, if specified, is ignored.

      4. The output is then as defined using the format-integer function with this adjusted decimal digit pattern.

  2. If the first presentation modifiers is one of N, n, or Nn:

    1. Let FN be the full name of the component, that is, the form of the name that would be used in the absence of any width modifier.

    2. If FN is shorter than the minimum width, then it is padded by appending spaces to the end of the name.

    3. If FN is longer than the maximum width, then it is abbreviated, either by choosing a conventional abbreviation that fits within the maximum width (for example, “Wednesday” might be abbreviated to “Weds”), or by removing characters from the end of FN until it fits within the maximum width.

  3. For other presentation modifiers:

    1. Any adjustment of the value to fit within the requested width range is implementation-defined.

    2. The value should not be truncated if this results in output that will not be meaningful to users (for example, there is no sensible way to truncate Roman numerals).

    3. If shorter than the minimum width, the value should be padded to the minimum width, either by appending spaces, or in some other way appropriate to the numbering scheme.

9.8.4.4 Formatting the Year Component

The rules for the year component (Y) are the same as those in 9.8.4.3 Formatting Integer-Valued Date/Time Components, except that the value of the year as output is the value of the year component of the supplied value modulo ten to the power N where N is determined as follows:

  1. If the width modifier is present and defines a finite maximum width, then that maximum width.

  2. Otherwise, if the first presentation modifier takes the form of a decimal-digit-pattern, then:

    1. Let W be the number of optional-digit-signs and mandatory-digit-signs in that decimal-digit-pattern.

    2. If W is 2 or more, then W.

  3. Otherwise, N is infinity (that is, the year is output in full).

9.8.4.5 Formatting Fractional Seconds

The output for the fractional seconds component (f) is equivalent to the result of the following algorithm:

  1. If the first presentation modifier contains no Unicode digit, then the output is implementation-defined.

  2. Otherwise, the value of the fractional seconds is output as follows:

    1. If there is no width modifier and the first presentation modifier comprises in its entirety a single mandatory-digit-sign (for example the default 1), then the presentation modifier is extended on the right with as many optional-digit-signs as are needed to accommodate the actual fractional seconds precision encountered in the value to be formatted.

    2. If there is a width modifier, then the first presentation modifier is adjusted as follows:

      1. If a minimum width is specified, and if this exceeds the number of mandatory-digit-sign characters in the first presentation modifier, then the first presentation modifier is adjusted. This is done first by replacing optional-digit-signs with mandatory-digit-signs, starting from the left, and then appending mandatory-digit-signs to the presentation modifier, until the number of mandatory-digit-signs is equal to the minimum width. Any mandatory-digit-signs that are added by this process must use the same decimal digit family as existing mandatory-digit-signs in the presentation modifier.

      2. If a maximum width is specified, the first presentation modifier is extended on the right with as many optional-digit-signs as are needed to ensure that the number of mandatory-digit-signs and optional-digit-signs is at least equal to the maximum width.

    3. The sequence of characters in the (adjusted) first presentation modifier is reversed (for example, 999'### becomes ###'999). If the result is not a valid decimal digit pattern, then the output is ·implementation-defined·.

    4. The sequence of digits in the conventional decimal representation of the fractional seconds component is reversed, with insignificant zeroes removed, and the result is treated as an integer. For example, if the seconds value is 25.8235, the reversed fractional seconds value is 5328.

    5. The reversed fractional seconds value is formatted using the reversed decimal digit pattern according to the rules of the fn:format-integer function. Given the examples above, the result is 5'328

    6. The resulting string is reversed. In our example, the result is 823'5.

    7. If the result contains more digits than the number of mandatory-digit-signs and optional-digit-signs in the decimal digit pattern, then excess digits are removed from the right hand end (that is, the value is truncated towards zero rather than being rounded). Any grouping separator that immediately precedes a removed digit is also removed.

Note:

The reason for presenting the algorithm in this way is that it enables maximum reuse of the rules defined for fn:format-integer. Since the fractional seconds value is not properly an integer, the rules do not work if used directly: for example, the positions of grouping separators need to be counted from the left rather than from the right. Implementations, as always, are free to use a different algorithm that yields the same result.

Note:

A format token consisting of a single digit, such as 1, does not constrain the number of digits in the output. In the case of fractional seconds in particular, [f001] requests three decimal digits, [f01] requests two digits, but [f1] will retain all digits in the supplied date/time value (the maximum number of digits is implementation-defined). If exactly one digit is required, this can be achieved using the component specifier [f1,1-1].

9.8.4.6 Formatting timezones

Special rules apply to the formatting of timezones. When the component specifiers Z or z are used, the rules in this section override any rules given elsewhere in the case of discrepancies.

If the date/time value to be formatted does not include a timezone offset, then the timezone component specifier is generally ignored (results in no output). The exception is where military timezones are used (format ZZ) in which case the string "J" is output, indicating local time.

  • When the component specifier is z, the output is the same as for component specifier Z, except that it is prefixed by the characters GMT or some localized equivalent. The prefix is omitted, however, in cases where the timezone is identified by name rather than by a numeric offset from UTC.

  • If the first presentation modifier is numeric and comprises one or two digits with no grouping-separator (for example 1 or 01), then the timezone is formatted as a displacement from UTC in hours, preceded by a plus or minus sign: for example -5 or +03. If the actual timezone offset is not an integral number of hours, then the minutes part of the offset is appended, separated by a colon: for example +10:30 or -1:15.

  • If the first presentation modifier is numeric with a grouping-separator (for example 1:01 or 01.01), then the timezone offset is output in hours and minutes, separated by the grouping separator, even if the number of minutes is zero: for example +5:00 or +10.30.

  • If the first presentation modifier is numeric and comprises three or four digits with no grouping-separator, for example 001 or 0001, then the timezone offset is shown in hours and minutes with no separator, for example -0500 or +1030.

  • If the first presentation modifier is numeric, in any of the above formats, and the second presentation modifier is t, then a zero timezone offset (that is, UTC) is output as Z instead of a signed numeric value. In this presentation modifier is absent or if the timezone offset is non-zero, then the displayed timezone offset is preceded by a - sign for negative offsets or a + sign for non-negative offsets.

  • If the first presentation modifier is Z, then the timezone is formatted as a military timezone letter, using the convention Z = +00:00, A = +01:00, B = +02:00, ..., M = +12:00, N = -01:00, O = -02:00, ... Y = -12:00. The letter J (meaning local time) is used in the case of a value that does not specify a timezone offset. Timezone offsets that have no representation in this system (for example Indian Standard Time, +05:30) are output as if the format 01:01 had been requested.

  • If the first presentation modifier is N, then the timezone is output (where possible) as a timezone name, for example EST or CET. The same timezone offset has different names in different places; it is therefore recommended that this option should be used only if a country code (see [ISO 3166-1]) or IANA timezone name (see [IANA Timezone Database]) is supplied in the $place argument. In the absence of this information, the implementation may apply a default, for example by using the timezone names that are conventional in North America. If no timezone name can be identified, the timezone offset is output using the fallback format 01:01.

The following examples illustrate options for timezone formatting.

Variable marker $place Timezone offsets (with time = 12:00:00)
    -10:00 -05:00 +00:00 +05:30 +13:00
[Z] () -10:00 -05:00 +00:00 +05:30 +13:00
[Z0] () -10 -5 +0 +5:30 +13
[Z0:00] () -10:00 -5:00 +0:00 +5:30 +13:00
[Z00:00] () -10:00 -05:00 +00:00 +05:30 +13:00
[Z0000] () -1000 -0500 +0000 +0530 +1300
[Z00:00t] () -10:00 -05:00 Z +05:30 +13:00
[z] () GMT‑10:00 GMT‑05:00 GMT+00:00 GMT+05:30 GMT+13:00
[ZZ] () W R Z +05:30 +13:00
[ZN] "us" HST EST GMT IST +13:00
[H00]:[M00] [ZN] "America/New_York" 06:00 EST 12:00 EST 07:00 EST 01:30 EST 18:00 EST

If a width specifier is present when formatting a timezone, then the representation as defined in this section is padded to the minimum width as described in 9.8.4.2 The Width Modifier, but it is never shortened.

9.8.4.7 Formatting Other Components

This section applies to the remaining components: P (am/pm marker), C (calendar), and E (era).

The output for these components is entirely ·implementation-defined·. The default presentation modifier for these components is n, indicating that they are output as names (or conventional abbreviations), and the chosen names will in many cases depend on the chosen language: see 9.8.4.8 The language, calendar, and place arguments.

9.8.4.8 The language, calendar, and place arguments

The set of languages, calendars, and places that are supported in the ·date formatting functions· is ·implementation-defined·. When any of these arguments is omitted or is an empty sequence, an ·implementation-defined· default value is used.

If the fallback representation uses a different calendar from that requested, the output string must identify the calendar actually used, for example by prefixing the string with [Calendar: X] (where X is the calendar actually used), localized as appropriate to the requested language. If the fallback representation uses a different language from that requested, the output string must identify the language actually used, for example by prefixing the string with [Language: Y] (where Y is the language actually used) localized in an implementation-dependent way. If a particular component of the value cannot be output in the requested format, it should be output in the default format for that component.

The $language argument specifies the language to be used for the result string of the function. The value of the argument should be either the empty sequence or a value that would be valid for the xml:lang attribute (see [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 of regions within a country.

If the $language argument is omitted or is set to an empty sequence, or if it is set to an invalid value or a value that the implementation does not recognize, then the processor uses the default language defined in the dynamic context.

The language is used to select the appropriate language-dependent forms of:

  • names (for example, of months)

  • numbers expressed as words or as ordinals (twenty, 20th, twentieth)

  • hour convention (0-23 vs 1-24, 0-11 vs 1-12)

  • first day of week, first week of year

Where appropriate this choice may also take into account the value of the $place argument, though this should not be used to override the language or any sublanguage that is specified as part of the language argument.

The choice of the names and abbreviations used in any given language is ·implementation-defined·. For example, one implementation might abbreviate July as Jul while another uses Jly. In German, one implementation might represent Saturday as Samstag while another uses Sonnabend. Implementations may provide mechanisms allowing users to control such choices.

Where ordinal numbers are used, the selection of the correct representation of the ordinal (for example, the grammatical gender) may depend on the component being formatted and on its textual context in the picture string.

The calendar attribute specifies that the dateTime, date, or time supplied in the $value argument must be converted to a value in the specified calendar and then converted to a string using the conventions of that calendar.

The calendar value if present must be a valid EQName (dynamic error: [err:FOFD1340]). If it is a lexical QName then it is expanded into an expanded QName using the statically known namespaces; if it has no prefix then it represents an expanded-QName in no namespace. If the expanded QName is in no namespace, then it must identify a calendar with a designator specified below (dynamic error: [err:FOFD1340]). If the expanded QName is in a namespace then it identifies the calendar in an ·implementation-defined· way.

If the $calendar argument is omitted or is set to an empty sequence then the default calendar defined in the dynamic context is used.

Note:

The calendars listed below were known to be in use during the last hundred years. Many other calendars have been used in the past.

This specification does not define any of these calendars, nor the way that they map to the value space of the xs:date datatype in [XML Schema Part 2: Datatypes Second Edition]. There may be ambiguities when dates are recorded using different calendars. For example, the start of a new day is not simultaneous in different calendars, and may also vary geographically (for example, based on the time of sunrise or sunset). Translation of dates is therefore more reliable when the time of day is also known, and when the geographic location is known. When translating dates between one calendar and another, the processor may take account of the values of the $place and/or $language arguments, with the $place argument taking precedence.

Information about some of these calendars, and algorithms for converting between them, may be found in [Calendrical Calculations].

Designator Calendar
AD Anno Domini (Christian Era)
AH Anno Hegirae (Islamic Era)
AME Mauludi Era (solar years since Muhammad’s birth)
AM Anno Mundi (Jewish Calendar)
AP Anno Persici
AS Aji Saka Era (Java)
BE Buddhist Era
CB Cooch Behar Era
CE Common Era
CL Chinese Lunar Era
CS Chula Sakarat Era
EE Ethiopian Era
FE Fasli Era
ISO ISO 8601 calendar
JE Japanese Calendar
KE Khalsa Era (Sikh calendar)
KY Kali Yuga
ME Malabar Era
MS Monarchic Solar Era
NS Nepal Samwat Era
OS Old Style (Julian Calendar)
RS Rattanakosin (Bangkok) Era
SE Saka Era
SH Solar Hijri (Islamic Era, used in Iran and Afghanistan)
SS Saka Samvat
TE Tripurabda Era
VE Vikrama Era
VS Vikrama Samvat Era

At least one of the above calendars must be supported. It is ·implementation-defined· which calendars are supported.

The ISO 8601 calendar ([ISO 8601]), which is included in the above list and designated ISO, is very similar to the Gregorian calendar designated AD, but it differs in several ways. The ISO calendar is intended to ensure that date and time formats can be read easily by other software, as well as being legible for human users. The ISO calendar prescribes the use of particular numbering conventions as defined in ISO 8601, rather than allowing these to be localized on a per-language basis. In particular it provides a numeric “week date” format which identifies dates by year, week of the year, and day in the week; in the ISO calendar the days of the week are numbered from 1 (Monday) to 7 (Sunday), and week 1 in any calendar year is the week (from Monday to Sunday) that includes the first Thursday of that year. The numeric values of the components year, month, day, hour, minute, and second are the same in the ISO calendar as the values used in the lexical representation of the date and time as defined in [XML Schema Part 2: Datatypes Second Edition]. The era (E component) with this calendar is either a minus sign (for negative years) or a zero-length string (for positive years). For dates before 1 January, AD 1, year numbers in the ISO and AD calendars are off by one from each other: ISO year 0000 is 1 BC, -0001 is 2 BC, etc.

ISO 8601 does not define a numbering for weeks within a month. When the w component is used, the convention to be adopted is that each Monday-to-Sunday week is considered to fall within a particular month if its Thursday occurs in that month; the weeks that fall in a particular month under this definition are numbered starting from 1. Thus, for example, 29 January 2013 falls in week 5 because the Thursday of the week (31 January 2013) is the fifth Thursday in January, and 1 February 2013 is also in week 5 for the same reason.

Note:

The value space of the date and time datatypes, as defined in XML Schema, is based on absolute points in time. The lexical space of these datatypes defines a representation of these absolute points in time using the proleptic Gregorian calendar, that is, the modern Western calendar extrapolated into the past and the future; but the value space is calendar-neutral. The ·date formatting functions· produce a representation of this absolute point in time, but denoted in a possibly different calendar. So, for example, the date whose lexical representation in XML Schema is 1502-01-11 (the day on which Pope Gregory XIII was born) might be formatted using the Old Style (Julian) calendar as 1 January 1502. This reflects the fact that there was at that time a ten-day difference between the two calendars. It would be incorrect, and would produce incorrect results, to represent this date in an element or attribute of type xs:date as 1502-01-01, even though this might reflect the way the date was recorded in contemporary documents.

When referring to years occurring in antiquity, modern historians generally use a numbering system in which there is no year zero (the year before 1 CE is thus 1 BCE). This is the convention that should be used when the requested calendar is OS (Julian) or AD (Gregorian). When the requested calendar is ISO, however, the conventions of ISO 8601 should be followed: here the year before +0001 is numbered zero. In [XML Schema Part 2: Datatypes Second Edition] (version 1.0), the value space for xs:date and xs:dateTime does not include a year zero: however, XSD 1.1 endorses the ISO 8601 convention. This means that the date on which Julius Caesar was assassinated has the ISO 8601 lexical representation -0043-03-13, but will be formatted as 15 March 44 BCE in the Julian calendar or 13 March 44 BCE in the Gregorian calendar (dependent on the chosen localization of the names of months and eras).

The intended use of the $place argument is to identify the place where an event represented by the dateTime, date, or time supplied in the $value argument took place or will take place. If the $place argument is omitted or is set to an empty sequence, then the default place defined in the dynamic context is used. If the value is supplied, and is not the empty sequence, then it should either be a country code or an IANA timezone name. If the value does not take this form, or if its value is not recognized by the implementation, then the default place defined in the dynamic context is used.

  • Country codes are defined in [ISO 3166-1]. Examples are "de" for Germany and "jp" for Japan. Implementations may also allow the use of codes representing subdivisions of a country from ISO 3166-2, or codes representing formerly used names of countries from ISO 3166-3

  • IANA timezone names are defined in the IANA timezone database [IANA Timezone Database]. Examples are "America/New_York" and "Europe/Rome".

This argument is not intended to identify the location of the user for whom the date or time is being formatted; that should be done by means of the $language attribute. This information may be used to provide additional information when converting dates between calendars or when deciding how individual components of the date and time are to be formatted. For example, different countries using the Old Style (Julian) calendar started the new year on different days, and some countries used variants of the calendar that were out of synchronization as a result of differences in calculating leap years.

The geographical area identified by a country code is defined by the boundaries as they existed at the time of the date to be formatted, or the present-day boundaries for dates in the future.

If the $place argument is supplied in the form of an IANA timezone name that is recognized by the implementation, then the date or time being formatted is adjusted to the timezone offset applicable in that timezone. For example, if the xs:dateTime value 2010-02-15T12:00:00Z is formatted with the $place argument set to America/New_York, then the output will be as if the value 2010-02-15T07:00:00-05:00 had been supplied. This adjustment takes daylight savings time into account where possible; if the date in question falls during daylight savings time in New York, then it is adjusted to timezone offset -PT4H rather than -PT5H. Adjustment using daylight savings time is only possible where the value includes a date, and where the date is within the range covered by the timezone database.

9.8.5 Examples of date and time formatting

The following examples show a selection of dates and times and the way they might be formatted. These examples assume the use of the Gregorian calendar as the default calendar.

Required Output Expression
2002-12-31 format-date($d, "[Y0001]-[M01]-[D01]")
12-31-2002 format-date($d, "[M]-[D]-[Y]")
31-12-2002 format-date($d, "[D]-[M]-[Y]")
31 XII 2002 format-date($d, "[D1] [MI] [Y]")
31st December, 2002 format-date($d, "[D1o] [MNn], [Y]", "en", (), ())
31 DEC 2002 format-date($d, "[D01] [MN,*-3] [Y0001]", "en", (), ())
December 31, 2002 format-date($d, "[MNn] [D], [Y]", "en", (), ())
31 Dezember, 2002 format-date($d, "[D] [MNn], [Y]", "de", (), ())
Tisdag 31 December 2002 format-date($d, "[FNn] [D] [MNn] [Y]", "sv", (), ())
[2002-12-31] format-date($d, "[[[Y0001]-[M01]-[D01]]]")
Two Thousand and Three format-date($d, "[YWw]", "en", (), ())
einunddreißigste Dezember format-date($d, "[Dwo] [MNn]", "de", (), ())
3:58 PM format-time($t, "[h]:[m01] [PN]", "en", (), ())
3:58:45 pm format-time($t, "[h]:[m01]:[s01] [Pn]", "en", (), ())
3:58:45 PM PDT format-time($t, "[h]:[m01]:[s01] [PN] [ZN,*-3]", "en", (), ())
3:58:45 o'clock PM PDT format-time($t, "[h]:[m01]:[s01] o'clock [PN] [ZN,*-3]", "en", (), ())
15:58 format-time($t, "[H01]:[m01]")
15:58:45.762 format-time($t, "[H01]:[m01]:[s01].[f001]")
15:58:45 GMT+02:00 format-time($t, "[H01]:[m01]:[s01] [z,6-6]", "en", (), ())
15.58 Uhr GMT+2 format-time($t, "[H01]:[m01] Uhr [z]", "de", (), ())
3.58pm on Tuesday, 31st December format-dateTime($dt, "[h].[m01][Pn] on [FNn], [D1o] [MNn]")
12/31/2002 at 15:58:45 format-dateTime($dt, "[M01]/[D01]/[Y0001] at [H01]:[m01]:[s01]")

The following examples use calendars other than the Gregorian calendar.

Description Request Result
Islamic format-date($d, "[D&#x0661;] [Mn] [Y&#x0661;]", "ar", "AH", ()) ٢٦ ﺸﻭّﺍﻝ ١٤٢٣
Jewish (with Western numbering) format-date($d, "[D] [Mn] [Y]", "he", "AM", ()) ‏26 טבת 5763
Jewish (with traditional numbering) format-date($d, "[D&#x05D0;t] [Mn] [Y&#x05D0;t]", "he", "AM", ()) כ״ו טבת תשס״ג
Julian (Old Style) format-date($d, "[D] [MNn] [Y]", "en", "OS", ()) 18 December 2002
Thai format-date($d, "[D&#x0E51;] [Mn] [Y&#x0E51;]", "th", "BE", ()) ๓๑ ธันวาคม ๒๕๔๕

9.9 Parsing dates and times

Function Meaning
fn:parse-ietf-date Parses a string containing the date and time in IETF format, returning the corresponding xs:dateTime value.

A function is provided to parse dates and times expressed using syntax that is commonly encountered in internet protocols.

9.9.1 fn:parse-ietf-date

Summary

Parses a string containing the date and time in IETF format, returning the corresponding xs:dateTime value.

Signature
fn:parse-ietf-date(
$value as xs:string?
) as xs:dateTime?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function accepts a string matching the production input in the following grammar:

input ::= S? (dayname ","? S)? ((datespec S time) | asctime) S?
dayname ::= "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat" | "Sun" | "Monday | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday"
datespec ::= daynum dsep monthname dsep year
asctime ::= monthname dsep daynum S time S year
dsep ::= S | (S? "-" S?)
daynum ::= digit digit?
year ::= digit digit (digit digit)?
digit ::= [0-9]
monthname ::= "Jan" | "Feb" | "Mar" | "Apr" | "May" | "Jun" | "Jul" | "Aug" | "Sep" | "Oct" | "Nov" | "Dec"
time ::= hours ":" minutes (":" seconds)? (S? timezone)?
hours ::= digit digit?
minutes ::= digit digit
seconds ::= digit digit ("." digit+)?
timezone ::= tzname | tzoffset (S? "(" S? tzname S? ")")?
tzname ::= "UT" | "UTC" | "GMT" | "EST" | "EDT" | "CST" | "CDT" | "MST" | "MDT" | "PST" | "PDT"
tzoffset ::= ("+"|"-") hours ":"? minutes?
S ::= (x09 | x0A | x0D | x20)+

The input is case-insensitive: upper-case and lower-case distinctions in the above grammar show the conventional usage, but otherwise have no significance.

If the input is an empty sequence, the result is an empty sequence.

The dayname, if present, is ignored.

The daynum, monthname, and year supply the day, month, and year of the resulting xs:dateTime value. A two-digit year must have 1900 added to it. A year such as 0070 is to be treated as given; negative years are not permitted.

The hours, minutes, and seconds (including fractional seconds) values supply the corresponding components of the resulting xs:dateTime value; if the seconds value or the fractional seconds value is absent then zero is assumed.

If both a tzoffset and a tzname are supplied then the tzname is ignored.

If a tzoffset is supplied then this defines the hours and minutes parts of the timezone offset:

  • If it contains a colon, this separates the hours part from the minutes part.

  • Otherwise, the grammar allows a sequence of from one to four digits. These are interpreted as H, HH, HMM, or HHMM respectively, where H or HH is the hours part, and MM (if present) is the minutes part.

  • If the minutes part is absent it defaults to 00.

If a tzname is supplied with no tzoffset then it is translated to a timezone offset as follows:

tzname Offset
UT, UTC, GMT 00:00
EST -05:00
EDT -04:00
CST -06:00
CDT -05:00
MST -07:00
MDT -06:00
PST -08:00
PDT -07:00

If neither a tzoffset nor tzname is supplied, a timezone offset of 00:00 is assumed.

Error Conditions

A dynamic error is raised [err:FORG0010] if the input does not match the grammar, or if the resulting date/time value is invalid (for example, "31 February").

Notes

The parse-ietf-date function attempts to interpret its input as a date in any of the three formats specified by HTTP [RFC 2616].

These formats are used widely on the Internet to represent timestamps, and were specified in:

[RFC 2616] (HTTP) officially uses a subset of those three formats restricted to GMT.

The grammar for this function is slightly more liberal than the RFCs (reflecting the internet tradition of being liberal in what is accepted). For example the function:

  1. Accepts a single-digit value where appropriate in place of a two-digit value with a leading zero (so "Wed 1 Jun" is acceptable in place of "Wed 01 Jun", and the timezone offset "-5:00" is equivalent to "-05:00")

  2. Accepts one or more whitespace characters (x20, x09, x0A, x0D) wherever a single space is required, and allows whitespace to be omitted where it is not required for parsing

  3. Accepts and ignores whitespace characters (x20, x09, x0A, x0D) at the start or end of the string.

In new protocols IETF recommends the format of [RFC 3339], which is based on a profile of ISO 8601 similar to that already used in XPath and XSD, but the “approximate” [RFC 822] format described here is very widely used.

An [RFC 1123] date can be generated approximately using fn:format-dateTime with a picture string of "[FNn3], [D01] [MNn3] [Y04] [H01]:[m01]:[s01] [Z0000]".

Examples
Expression Result
parse-ietf-date("Wed, 06 Jun 1994 07:29:35 GMT")
xs:dateTime("1994-06-06T07:29:35Z")
parse-ietf-date("Wed, 6 Jun 94 07:29:35 GMT")
xs:dateTime("1994-06-06T07:29:35Z")
parse-ietf-date("Wed Jun 06 11:54:45 EST 2013")
xs:dateTime("2013-06-06T11:54:45-05:00")
parse-ietf-date("Sunday, 06-Nov-94 08:49:37 GMT")
xs:dateTime("1994-11-06T08:49:37Z")
parse-ietf-date("Wed, 6 Jun 94 07:29:35 +0500")
xs:dateTime("1994-06-06T07:29:35+05:00")

10 Functions related to QNames

10.1 Functions to create a QName

In addition to the xs:QName constructor function, QName values can be constructed by combining a namespace URI, prefix, and local name, or by resolving a lexical QName against the in-scope namespaces of an element node. This section defines functions that perform these operations. Leading and trailing whitespace, if present, is stripped from string arguments before the result is constructed.

Function Meaning
fn:QName Returns an xs:QName value formed using a supplied namespace URI and lexical QName.
fn:parse-QName Returns an xs:QName value formed by parsing an EQName.
fn:resolve-QName Returns an xs:QName value (that is, an expanded-QName) by taking an xs:string that has the lexical form of an xs:QName (a string in the form "prefix:local-name" or "local-name") and resolving it using the in-scope namespaces for a given element.

10.1.1 fn:QName

Summary

Returns an xs:QName value formed using a supplied namespace URI and lexical QName.

Signature
fn:QName(
$uri as xs:string?,
$qname as xs:string
) as xs:QName
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The namespace URI in the returned QName is taken from $uri. If $uri is the zero-length string or the empty sequence, it represents “no namespace”.

The prefix (or absence of a prefix) in $qname is retained in the returned xs:QName value.

The local name in the result is taken from the local part of $qname.

Error Conditions

A dynamic error is raised [err:FOCA0002] if $qname does not have the correct lexical form for an instance of xs:QName.

A dynamic error is raised [err:FOCA0002] if $uri is the zero-length string or the empty sequence, and the value of $qname contains a colon (:).

A dynamic error may be raised [err:FOCA0002] if $uri is not a valid URI (XML Namespaces 1.0) or IRI (XML Namespaces 1.1).

Examples

fn:QName("http://www.example.com/example", "person") returns an xs:QName with namespace URI "http://www.example.com/example", local name "person" and prefix "".

fn:QName("http://www.example.com/example", "ht:person") returns an xs:QName with namespace URI "http://www.example.com/example", local name "person" and prefix "ht".

10.1.2 fn:parse-QName

Changes in 4.0  

  1. New in 4.0  [Issue 1 PR 207 15 November 2022]

Summary

Returns an xs:QName value formed by parsing an EQName.

Signature
fn:parse-QName(
$value as xs:string?
) as xs:QName?
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on namespaces.

Rules

If $value is an empty sequence, the result is an empty sequence.

Otherwise, leading and trailing whitespace in $value is stripped.

If the resulting $value is castable to xs:NCName, the result is fn:QName("", $value): that is, a QName in no namespace.

Otherwise, if the resulting $value is in the lexical space of xs:QName (that is, if it is in the form prefix:local), the result is xs:QName($value). Note that this result depends on the in-scope prefixes in the static context, and may result in various error conditions.

Otherwise, if the resulting $value takes the form of an XPath BracedURILiteralXP40 (that is, Q{uri}local, where the uri part may be zero-length), then the result is fn:QName(uri, local).

The rules used for parsing a BracedURILiteralXP40 within a URIQualifiedNameXP40 are the XPath rules, not the XQuery rules (the XQuery rules require special characters such as < and & to be escaped).

Error Conditions

A dynamic error is raised [err:FOCA0002] if the supplied value of $value, after whitespace normalization, does not match the XPath production EQNameXP40

A dynamic error is raised [err:FONS0004] if the supplied value of $value, after whitespace normalization, is in the form prefix:local (with a non-absent prefix), and the prefix cannot be resolved to a namespace URI using the in-scope namespace bindings from the static context.

Examples

fn:parse-QName("Q{http://www.example.com/example}person") returns an xs:QName with namespace URI "http://www.example.com/example", local name "person" and prefix "".

fn:parse-QName("person") returns an xs:QName with absent namespace URI, local name "person" and prefix "".

fn:parse-QName("Q{}person") returns an xs:QName with absent namespace URI, local name "person" and prefix "".

fn:parse-QName("p:person") returns an xs:QName with namespace URI obtained from the static context, local name "person" and prefix "p" (The result is the same as xs:QName("p:person")).

10.1.3 fn:resolve-QName

Summary

Returns an xs:QName value (that is, an expanded-QName) by taking an xs:string that has the lexical form of an xs:QName (a string in the form "prefix:local-name" or "local-name") and resolving it using the in-scope namespaces for a given element.

Signature
fn:resolve-QName(
$value as xs:string?,
$element as element()
) as xs:QName?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, returns the empty sequence.

More specifically, the function searches the namespace bindings of $element for a binding whose name matches the prefix of $value, or the zero-length string if it has no prefix, and returns an expanded-QName whose local name is taken from the supplied $value, and whose namespace URI is taken from the string value of the namespace binding.

If the $value has no prefix, and there is no namespace binding for $element corresponding to the default (unnamed) namespace, then the resulting expanded-QName has no namespace part.

The prefix (or absence of a prefix) in the supplied $value argument is retained in the returned expanded-QName, as described in Section 2.1 TerminologyDM40.

Error Conditions

A dynamic error is raised [err:FOCA0002] if $value does not have the correct lexical form for an instance of xs:QName.

A dynamic error is raised [err:FONS0004] if $value has a prefix and there is no namespace binding for $element that matches this prefix.

Notes

Sometimes the requirement is to construct an xs:QName without using the default namespace. This can be achieved by writing:

if (contains($value, ":"))
then resolve-QName($value, $element)
else QName("", $value)

If the requirement is to construct an xs:QName using the namespaces in the static context, then the xs:QName constructor should be used.

Examples

Assume that the element bound to $element has a single namespace binding bound to the prefix eg.

fn:resolve-QName("hello", $element) returns a QName with local name "hello" that is in no namespace.

fn:resolve-QName("eg:myFunc", $element) returns an xs:QName whose namespace URI is specified by the namespace binding corresponding to the prefix "eg" and whose local name is "myFunc".

10.2 Functions and operators on QNames

This section specifies functions and an operator on QNames as defined in [XML Schema Part 2: Datatypes Second Edition].

Function Meaning
op:QName-equal Returns true if two supplied QNames have the same namespace URI and the same local part.
fn:prefix-from-QName Returns the prefix component of the supplied QName.
fn:local-name-from-QName Returns the local part of the supplied QName.
fn:namespace-uri-from-QName Returns the namespace URI part of the supplied QName.
fn:expanded-QName Returns a string representation of an xs:QName in the format Q{uri}local.
fn:in-scope-namespaces Returns the in-scope namespaces of an element node, as a map.
fn:in-scope-prefixes Returns the prefixes of the in-scope namespaces for an element node.
fn:namespace-uri-for-prefix Returns the namespace URI of one of the in-scope namespaces for $element, identified by its namespace prefix.

10.2.1 op:QName-equal

Summary

Returns true if two supplied QNames have the same namespace URI and the same local part.

Operator Mapping

Defines the semantics of the eq and ne operators when applied to two values of type xs:QName.

Signature
op:QName-equal(
$arg1 as xs:QName,
$arg2 as xs:QName
) as xs:boolean
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns true if the namespace URIs of $arg1 and $arg2 are equal and the local names of $arg1 and $arg2 are equal.

Otherwise, the function returns false.

The namespace URI parts are considered equal if they are both absentDM40, or if they are both present and equal under the rules of the fn:codepoint-equal function.

The local parts are also compared under the rules of the fn:codepoint-equal function.

Notes

The prefix parts of $arg1 and $arg2, if any, are ignored.

10.2.2 fn:prefix-from-QName

Summary

Returns the prefix component of the supplied QName.

Signature
fn:prefix-from-QName(
$value as xs:QName?
) as xs:NCName?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence the function returns the empty sequence.

If $value has no prefix component the function returns the empty sequence.

Otherwise, the function returns an xs:NCName representing the prefix component of $value.

10.2.3 fn:local-name-from-QName

Summary

Returns the local part of the supplied QName.

Signature
fn:local-name-from-QName(
$value as xs:QName?
) as xs:NCName?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence the function returns the empty sequence.

Otherwise, the function returns an xs:NCName representing the local part of $value.

Examples
Expression:
local-name-from-QName(
  QName("http://www.example.com/example", "person")
)
Result:
"person"

10.2.4 fn:namespace-uri-from-QName

Summary

Returns the namespace URI part of the supplied QName.

Signature
fn:namespace-uri-from-QName(
$value as xs:QName?
) as xs:anyURI?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence the function returns the empty sequence.

Otherwise, the function returns an xs:anyURI representing the namespace URI part of $value.

If $value is in no namespace, the function returns the zero-length xs:anyURI.

Examples
Expression:
namespace-uri-from-QName(
  QName("http://www.example.com/example", "person")
)
Result:
xs:anyURI("http://www.example.com/example")

10.2.5 fn:expanded-QName

Changes in 4.0  

  1. New in 4.0  [Issue 1 PR 207 15 November 2022]

Summary

Returns a string representation of an xs:QName in the format Q{uri}local.

Signature
fn:expanded-QName(
$value as xs:QName?
) as xs:string?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence, returns the empty sequence.

The result is a string in the format Q{uri}local, where:

  • uri is the result of fn:string(fn:namespace-uri-from-QName($value)) (which will be a zero-length string if the QName is in no namespace), and

  • local is the result of fn:local-name-from-QName($value).

There is no escaping of special characters in the namespace URI. If the namespace URI contains curly braces, the resulting string will not be a valid BracedURILiteralXP40.

Examples
Expression:
QName("http://example.com/", "person")
=> expanded-QName()
Result:
"Q{http://example.com/}person"
Expression:
QName("", "person")
=> expanded-QName()
Result:
"Q{}person"

10.2.6 fn:in-scope-namespaces

Changes in 4.0  

  1. New in 4.0  [  20 September 2022]

Summary

Returns the in-scope namespaces of an element node, as a map.

Signature
fn:in-scope-namespaces(
$element as element()
) as map((xs:NCName | enum('')), xs:anyURI)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns a map representing the prefixes of the in-scope namespaces for $element. The map contains one entry for each in-scope namespace: the key of the entry is the namespace prefix or a zero-length string, and the corresponding value is the namespace URI.

For namespace bindings that have a prefix, the key represents the prefix as an instance of xs:NCName. For the default namespace, which has no prefix, the key is the zero-length string as an instance of xs:string.

Notes

The XML namespace is in scope for every element, so the result will always include an entry with key "xml" and corresponding value http://www.w3.org/XML/1998/namespace.

Examples
Variables
let $e := 
<z:a xmlns="http://example.org/one" xmlns:z="http://example.org/two">
  <b xmlns=""/>
</z:a>
Expression:

in-scope-namespaces($e)

Result:
{
  "": "http://example.org/one",
  "z": "http://example.org/two",
  "xml": "http://www.w3.org/XML/1998/namespace"
}

10.2.7 fn:in-scope-prefixes

Changes in 4.0  

  1. Reformulated in 4.0 in terms of the new fn:in-scope-namespaces function; the semantics are unchanged.

Summary

Returns the prefixes of the in-scope namespaces for an element node.

Signature
fn:in-scope-prefixes(
$element as element()
) as xs:string*
Properties

This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the result of the expression map:keys(fn:in-scope-namespaces($element)) (but in no defined order).

Notes

The XML namespace is in scope for every element, so the result will always include the string "xml".

10.2.8 fn:namespace-uri-for-prefix

Changes in 4.0  

  1. Reformulated in 4.0 in terms of the new fn:in-scope-namespaces function; the semantics are unchanged.

Summary

Returns the namespace URI of one of the in-scope namespaces for $element, identified by its namespace prefix.

Signature
fn:namespace-uri-for-prefix(
$value as (xs:NCName | enum(''))?,
$element as element()
) as xs:anyURI?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the result of the expression map:get(fn:in-scope-namespaces($element), string($value)).

Examples
Variables
let $e := 
<z:a xmlns="http://example.org/one" xmlns:z="http://example.org/two">
  <b xmlns=""/>
</z:a>
Expression Result
namespace-uri-for-prefix("z", $e)
"http://example.org/two"
namespace-uri-for-prefix("", $e)
"http://example.org/one"
namespace-uri-for-prefix((), $e)
"http://example.org/one"
namespace-uri-for-prefix("xml", $e)
"http://www.w3.org/XML/1998/namespace"

11 Operators on base64Binary and hexBinary

11.1 Comparisons of base64Binary and hexBinary values

The following comparison operators on xs:hexBinary and xs:base64Binary values are defined. Each returns a boolean value.

These functions can be used to compare any xs:hexBinary or xs:base64Binary value with any other xs:hexBinary or xs:base64Binary value: both types have the same value space, namely a sequence of octets which are treated as integers in the range 0 to 255.

Function Meaning
op:binary-equal Returns true if both binary values contain the same octet sequence.
op:binary-less-than Returns true if the first argument is less than the second.

11.1.1 op:binary-equal

Summary

Returns true if both binary values contain the same octet sequence.

Operator Mapping

Defines the semantics of the eq and ne operators when applied to two xs:hexBinary or xs:base64Binary values.

Signature
op:binary-equal(
$value1 as (xs:hexBinary | xs:base64Binary),
$value2 as (xs:hexBinary | xs:base64Binary)
) as xs:boolean
Rules

The function returns true if $value1 and $value2 are of the same length, measured in binary octets, and contain the same octets in the same order. Otherwise, it returns false.

11.1.2 op:binary-less-than

Summary

Returns true if the first argument is less than the second.

Operator Mapping

Defines the semantics of the lt operator when applied to two xs:hexBinary or xs:base64Binaryvalues. Also used in the definition of the ge operator.

Signature
op:binary-less-than(
$arg1 as (xs:hexBinary | xs:base64Binary),
$arg2 as (xs:hexBinary | xs:base64Binary)
) as xs:boolean
Rules

Each of the two arguments are converted to a sequence of octets, $A and $B, and the first octet in each sequence, $a and $b, are compared.

  1. If $a is empty and $b is non-empty return true.

  2. If $b is empty return false.

  3. Otherwise (neither $a nor $b are empty):

    1. If $a and $b are identical the result is obtained by applying these same rules recursively to fn:tail($A) and fn:tail($B).

    2. Otherwise, if $a is less than $b, treating the value of each octet as an unsigned integer in the range 0 to 255, then return true, otherwise return false.

12 Operators on NOTATION

This section specifies operators that take xs:NOTATION values as arguments.

Function Meaning
op:NOTATION-equal Returns true if the two xs:NOTATION values have the same namespace URI and the same local part.

12.1 op:NOTATION-equal

Summary

Returns true if the two xs:NOTATION values have the same namespace URI and the same local part.

Operator Mapping

Defines the semantics of the eq and ne operators when applied to two values of type xs:NOTATION.

Signature
op:NOTATION-equal(
$arg1 as xs:NOTATION,
$arg2 as xs:NOTATION
) as xs:boolean
Rules

The function returns true if the namespace URIs of $arg1 and $arg2 are equal and the local names of $arg1 and $arg2 are equal.

Otherwise, the function returns false.

The namespace URI parts are considered equal if they are both absentDM40, or if they are both present and equal under the rules of the fn:codepoint-equal function.

The local parts are also compared under the rules of the fn:codepoint-equal function.

Notes

The prefix parts of $arg1 and $arg2, if any, are ignored.

13 Functions and operators on sequences

A sequence is an ordered collection of zero or more items. An item is a node, an atomic item, or a function, such as a map or an array. The terms sequence and item are defined formally in [XQuery 4.1: An XML Query Language] and [XML Path Language (XPath) 4.0].

13.1 General functions and operators on sequences

The following functions are defined on sequences. These functions work on any sequence, without performing any operations that are sensitive to the individual items in the sequence.

Function Meaning
fn:empty Returns true if the argument is the empty sequence.
fn:exists Returns true if the argument is a non-empty sequence.
fn:foot Returns the last item in a sequence.
fn:head Returns the first item in a sequence.
fn:identity Returns its argument value.
fn:insert-before Returns a sequence constructed by inserting an item or a sequence of items at a given position within an existing sequence.
fn:intersperse Inserts a separator between adjacent items in a sequence.
fn:items-at Returns a sequence containing the items from $input at positions defined by $at, in the order specified.
fn:remove Returns a new sequence containing all the items of $input except those at specified positions.
fn:replicate Produces multiple copies of a sequence.
fn:reverse Reverses the order of items in a sequence.
fn:slice Returns a sequence containing selected items from a supplied input sequence based on their position.
fn:subsequence Returns the contiguous sequence of items in $input beginning at the position indicated by $start and continuing for the number of items indicated by $length.
fn:tail Returns all but the first item in a sequence.
fn:trunk Returns all but the last item in a sequence.
fn:unordered Returns the items of $input in an ·implementation-dependent· order.
fn:void Absorbs the argument.

As in the previous section, for the illustrative examples below, assume an XQuery or transformation operating on a non-empty Purchase Order document containing a number of line-item elements. The variable $seq is bound to the sequence of line-item nodes in document order. The variables $item1, $item2, etc. are bound to separate, individual line-item nodes in the sequence.

13.1.1 fn:empty

Summary

Returns true if the argument is the empty sequence.

Signature
fn:empty(
$input as item()*
) as xs:boolean
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $input is the empty sequence, the function returns true; otherwise, the function returns false.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

count($input) eq 0
Examples
Expression Result
empty((1, 2, 3)[10])
true()
empty(remove(("hello", "world"), 1))
false()
empty([])
false()
empty({})
false()
empty("")
false()

Assuming $break is an element with no children:

let $break := <br/>
return empty($break)

The result is false().

13.1.2 fn:exists

Summary

Returns true if the argument is a non-empty sequence.

Signature
fn:exists(
$input as item()*
) as xs:boolean
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $input is a non-empty sequence, the function returns true; otherwise, the function returns false.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

count($input) gt 0
Examples
Expression Result
exists(remove(("hello"), 1))
false()
exists(remove(("hello", "world"), 1))
true()
exists([])
true()
exists({})
true()
exists("")
true()

Assuming $break is an element with no children:

let $break := <br/>
return exists($break)

The result is true().

13.1.3 fn:foot

Changes in 4.0  

  1. New in 4.0  [Issue 97 PR 250]

Summary

Returns the last item in a sequence.

Signature
fn:foot(
$input as item()*
) as item()?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the value of the expression $input[last()]

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

filter($input, fn($item, $pos) { $pos eq count($input) })
Notes

If $input is the empty sequence the empty sequence is returned.

Examples
Expression Result
foot(1 to 5)
(5)
foot(())
()

13.1.4 fn:head

Summary

Returns the first item in a sequence.

Signature
fn:head(
$input as item()*
) as item()?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the first item in $input; if $input is empty, it returns an empty sequence.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

filter($input, fn($item, $pos) { $pos eq 1 })
Examples
Expression Result
head(1 to 5)
1
head(("a", "b", "c"))
"a"
head(())
()
head([ 1, 2, 3 ])
[ 1, 2, 3 ]

13.1.5 fn:identity

Changes in 4.0  

  1. New in 4.0  [  20 September 2022]

Summary

Returns its argument value.

Signature
fn:identity(
$input as item()*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns $input.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

$input
Notes

The function is useful in contexts where a function must be supplied, but no processing is required.

Examples
Expression Result
identity(0)
(0)
identity(1 to 10)
(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
parse-xml('<a/>') ! (identity(/) is /)
true()

(If the argument is a node, the function returns the identical node, not a copy).

identity(())
()

13.1.6 fn:insert-before

Summary

Returns a sequence constructed by inserting an item or a sequence of items at a given position within an existing sequence.

Signature
fn:insert-before(
$input as item()*,
$position as xs:integer,
$insert as item()*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The value returned by the function consists of all items of $input whose 1-based position is less than $position, followed by all items of $insert, followed by the remaining elements of $input, in that order.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

filter($input, fn($item, $pos) { $pos lt $position }),
$insert,
filter($input, fn($item, $pos) { $pos ge $position })
Notes

If $input is the empty sequence, $insert is returned. If $insert is the empty sequence, $input is returned.

If $position is less than one (1), the first position, the effective value of $position is one (1). If $position is greater than the number of items in $input, then the effective value of $position is equal to the number of items in $input plus 1.

The value of $input is not affected by the sequence construction.

Examples
Variables
let $abc := ("a", "b", "c")
Expression Result
insert-before($abc, 0, "z")
("z", "a", "b", "c")
insert-before($abc, 1, "z")
("z", "a", "b", "c")
insert-before($abc, 2, "z")
("a", "z", "b", "c")
insert-before($abc, 3, "z")
("a", "b", "z", "c")
insert-before($abc, 4, "z")
("a", "b", "c", "z")

13.1.7 fn:intersperse

Changes in 4.0  

  1. New in 4.0  [Issue 2  27 September 2022]

Summary

Inserts a separator between adjacent items in a sequence.

Signature
fn:intersperse(
$input as item()*,
$separator as item()*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the value of head($input), tail($input) ! ($separator, .).

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

for-each($input, fn($item, $pos) {
   if ($pos eq 1)
   then $item
   else ($separator, $item)
})
Notes

If $input contains less than two items then it is returned unchanged.

If $separator is the empty sequence then $input is returned unchanged.

For example, in XQuery, fn:intersperse(para, <hr/>) would insert an empty hr element between adjacent paragraphs.

Examples
Expression Result
intersperse(1 to 5, "|")
(1, "|", 2, "|" , 3, "|", 4, "|", 5)
intersperse((), "|")
()
intersperse("A", "|")
"A"
intersperse(1 to 5, ())
(1, 2, 3, 4, 5)
intersperse(1 to 3, ("⅓", "⅔"))
(1, "⅓", "⅔", 2, "⅓", "⅔", 3)

13.1.8 fn:items-at

Changes in 4.0  

  1. New in 4.0  [Issue 213 PR 419 22 November 2022]

Summary

Returns a sequence containing the items from $input at positions defined by $at, in the order specified.

Signature
fn:items-at(
$input as item()*,
$at as xs:integer*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Returns the items in $input at the positions listed in $at, in order of the integers in the $at argument.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

for-each($at, fn($index) { subsequence($input, $index, 1) })
Notes

In the simplest case where $at is a single integer, fn:items-at($input, 3) returns the same result as $input[3].

Compared with a simple positional filter expression, the function is useful because:

  1. It can select items at multiple positions, and unlike fn:subsequence, these do not need to be contiguous.

  2. The $at expression can depend on the focus.

  3. The order of the returned items can differ from their order in the $input sequence.

If any integer in $at is outside the range 1 to count($input), that integer is effectively ignored: no error occurs.

If either of the arguments is an empty sequence, the result is an empty sequence.

If $at contains duplicate integers, the result also contains duplicates. No de-duplication occurs. If the input sequence contains nodes, these are not copied: instead, the result sequence contains multiple references to the same node.

Examples
Expression Result
items-at(11 to 20, 4)
14
items-at(11 to 20, 4 to 6)
14, 15, 16
items-at(11 to 20, (7, 3))
17, 13
items-at(11 to 20, index-of(("a", "b", "c"), "b"))
12
items-at(characters("quintessential"), (4, 8, 3))
("n", "s", "i")
items-at(characters("quintessential"), (4, 8, 1, 1))
("n", "s", "q", "q")
items-at((), 832)
()
items-at((), ())
()

13.1.9 fn:remove

Changes in 4.0  

  1. The second argument can now be a sequence of integers.  [Issue 294 PR 313 24 January 2023]

Summary

Returns a new sequence containing all the items of $input except those at specified positions.

Signature
fn:remove(
$input as item()*,
$positions as xs:integer*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns a sequence consisting of all items of $input whose 1-based position is not equal to any of the integers in $positions.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

filter($input, fn($item, $pos) { not($pos eq $positions) })
Notes

Any integer in $positions that is less than 1 or greater than the number of items in $input is effectively ignored.

If $input is the empty sequence, the empty sequence is returned.

If $positions is an empty sequence, the input sequence $input is returned unchanged.

Examples
Variables
let $abc := ("a", "b", "c")
Expression Result
remove($abc, 0)
("a", "b", "c")
remove($abc, 1)
("b", "c")
remove($abc, 6)
("a", "b", "c")
remove((), 3)
()
remove($abc, 2 to 3)
"a"
remove($abc, ())
("a", "b", "c")

13.1.10 fn:replicate

Changes in 4.0  

  1. New in 4.0  [  4 October 2022]

Summary

Produces multiple copies of a sequence.

Signature
fn:replicate(
$input as item()*,
$count as xs:nonNegativeInteger
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the value of (1 to $count) ! $input.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

fold-left(1 to $count, (), fn($result, $next) { $result, $input })
Notes

If $input is the empty sequence, the empty sequence is returned.

The $count argument is declared as xs:nonNegativeInteger, which means that a type error occurs if it is called with a negative value.

If the input sequence contains nodes, these are not copied: instead, the result sequence contains multiple references to the same node. So, for example, fn:count(fn:replicate(/, 6)|()) returns 1, because the fn:replicate call creates duplicates, and the union operation eliminates them.

Examples
Expression Result
replicate(0, 6)
(0, 0, 0, 0, 0, 0)
replicate(("A", "B", "C"), 3)
("A", "B", "C", "A", "B", "C", "A", "B", "C")
replicate((), 5)
()
replicate(("A", "B", "C"), 1)
("A", "B", "C")
replicate(("A", "B", "C"), 0)
()

13.1.11 fn:reverse

Summary

Reverses the order of items in a sequence.

Signature
fn:reverse(
$input as item()*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns a sequence containing the items in $input in reverse order.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

fold-left($input, (), fn($result, $item) {$item, $result})
Notes

If $input is the empty sequence, the empty sequence is returned.

Examples
Variables
let $abc := ("a", "b", "c")
Expression Result
reverse($abc)
("c", "b", "a")
reverse(("hello"))
("hello")
reverse(())
()
reverse([ 1, 2, 3 ])
[ 1, 2, 3 ]

(The input is a sequence containing a single item (the array)).

reverse(([ 1, 2, 3 ], [ 4, 5, 6 ]))
([ 4, 5, 6 ], [ 1, 2, 3 ])

13.1.12 fn:slice

Changes in 4.0  

  1. New in 4.0

Summary

Returns a sequence containing selected items from a supplied input sequence based on their position.

Signature
fn:slice(
$input as item()*,
$start as xs:integer? := (),
$end as xs:integer? := (),
$step as xs:integer? := ()
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $input is the empty sequence, the function returns the empty sequence.

Let $S be the first of the following that applies:

  • If $start is absent, empty, or zero, then 1.

  • If $start is negative, then fn:count($input) + $start + 1.

  • Otherwise, $start.

Let $E be the first of the following that applies:

  • If $end is absent, empty, or zero, then fn:count($input).

  • If $end is negative, then fn:count($input) + $end + 1.

  • Otherwise, $end.

Let $STEP be the first of the following that applies:

  • If $step is absent, empty, or zero, then:

    • If $E ge $S, then +1

    • Otherwise -1

  • Otherwise, $step.

If $STEP is negative, the function returns $input => fn:reverse() => fn:slice(-$S, -$E, -$STEP).

Otherwise the function returns the result of the expression:

$input[position() ge $S and position() le $E and (position() - $S) mod $STEP eq 0]
Editorial note  
TBA: define formal equivalent.
Notes

The function is inspired by the slice operators in Javascript and Python, but it differs in detail to accommodate the tradition of 1-based addressing in XPath. The end position is inclusive rather than exclusive, so that in the simple case where $start and $end are positive and $end > $start, fn:slice($in, $start, $end) returns the same result as $in[position() = $start to $end].

This function can be used to enhance the RangeExpression, defined in Section 4.7.2 Range ExpressionsXP40, to construct a sequence of integers based on steps other than 1.

Examples
Variables
let $in := ('a', 'b', 'c', 'd', 'e')
Expression Result
slice($in, start := 2, end := 4)
("b", "c", "d")
slice($in, start := 2)
("b", "c", "d", "e")
slice($in, end := 2)
("a", "b")
slice($in, start := 3, end := 3)
("c")
slice($in, start := 4, end := 3)
("d", "c")
slice($in, start := 2, end := 5, step := 2)
("b", "d")
slice($in, start := 5, end := 2, step := -2)
("e", "c")
slice($in, start := 2, end := 5, step := -2)
()
slice($in, start := 5, end := 2, step := 2)
()
slice($in)
("a", "b", "c", "d", "e")
slice($in, start := -1)
("e")
slice($in, start := -3)
("c", "d", "e")
slice($in, end := -2)
("a", "b", "c", "d")
slice($in, start := 2, end := -2)
("b", "c", "d")
slice($in, start := -2, end := 2)
("d", "c", "b")
slice($in, start := -4, end := -2)
("b", "c", "d")
slice($in, start := -2, end := -4)
("d", "c", "b")
slice($in, start := -4, end := -2, step := 2)
("b", "d")
slice($in, start := -2, end := -4, step := -2)
("d", "b")
slice(("a", "b", "c", "d"), 0)
("a", "b", "c", "d")
slice((1 to 5), step := 2)
(1, 3, 5)

13.1.13 fn:subsequence

Changes in 4.0  

  1. The optional third argument can now be supplied as an empty sequence.  [Issue 895 PR 901 16 December 2023]

Summary

Returns the contiguous sequence of items in $input beginning at the position indicated by $start and continuing for the number of items indicated by $length.

Signature
fn:subsequence(
$input as item()*,
$start as xs:double,
$length as xs:double? := ()
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

In the two-argument case (or where the third argument is an empty sequence), the function returns:

$input[round($start) le position()]

In the three-argument case, the function returns:

$input[round($start) le position() 
         and position() lt round($start) + round($length)]
Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

filter($input,
       if (empty($length))
       then fn($item, $pos) {
                round($start) le $pos
            }
       else fn($item, $pos) {
                round($start) le $pos and $pos lt round($start) + round($length)
            })
Notes

The first item of a sequence is located at position 1, not position 0.

If $input is the empty sequence, the empty sequence is returned.

In the two-argument case, the function returns a sequence comprising those items of $input whose 1-based position is greater than or equal to $start (rounded to an integer). No error occurs if $start is zero or negative.

In the three-argument case, The function returns a sequence comprising those items of $input whose 1-based position is greater than or equal to $start (rounded to an integer), and less than the sum of $start and $length (both rounded to integers). No error occurs if $start is zero or negative, or if $start plus $length exceeds the number of items in the sequence, or if $length is negative.

As a consequence of the general rules, if $start is -INF and $length is +INF, then fn:round($start) + fn:round($length) is NaN; since position() lt NaN always returns false, the result is an empty sequence.

The reason the function accepts arguments of type xs:double is that many computations on untyped data return an xs:double result; and the reason for the rounding rules is to compensate for any imprecision in these floating-point computations.

Examples
Variables
let $seq := ("item1", "item2", "item3", "item4", "item5")
Expression Result
subsequence($seq, 4)
("item4", "item5")
subsequence($seq, 3, 2)
("item3", "item4")

13.1.14 fn:tail

Summary

Returns all but the first item in a sequence.

Signature
fn:tail(
$input as item()*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function all items in $input except the first, retaining order.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

filter($input, fn($item, $pos) { $pos gt 1 })
Notes

If $input is the empty sequence, or a sequence containing a single item, then the empty sequence is returned.

Examples
Expression Result
tail(1 to 5)
(2, 3, 4, 5)
tail(("a", "b", "c"))
("b", "c")
tail("a")
()
tail(())
()
tail([ 1, 2, 3 ])
()

13.1.15 fn:trunk

Changes in 4.0  

  1. New in 4.0  [Issue 97 PR 250]

Summary

Returns all but the last item in a sequence.

Signature
fn:trunk(
$input as item()*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns all items in $input except the last, retaining order.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

filter($input, fn($item, $pos) { $pos ne count($input) })
Notes

If $input is the empty sequence, or a sequence containing a single item, then the empty sequence is returned.

Examples
Expression Result
trunk(1 to 5)
(1, 2, 3, 4)
trunk(("a", "b", "c"))
("a", "b")
trunk("a")
()
trunk(())
()
trunk([ 1, 2, 3 ])
()

13.1.16 fn:unordered

Summary

Returns the items of $input in an ·implementation-dependent· order.

Signature
fn:unordered(
$input as item()*
) as item()*
Properties

This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the items of $input in an ·implementation-dependent· order.

Notes

Query optimizers may be able to do a better job if the order of the output sequence is not specified. For example, when retrieving prices from a purchase order, if an index exists on prices, it may be more efficient to return the prices in index order rather than in document order.

This function does not guarantee that the resulting sequence will be in an order different from the input sequence. Many times the two sequences will be identical.

Examples
Expression Result
unordered((1, 2, 3, 4, 5))
(1, 2, 3, 4, 5)

(or some permutation thereof)

13.1.17 fn:void

Changes in 4.0  

  1. New in 4.0  [Issue 1029 PR 1032 25 February 2025]

Summary

Absorbs the argument.

Signature
fn:void(
$input as item()* := ()
) as empty-sequence()
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function absorbs the supplied $input argument and returns an empty sequence.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

()
Notes

The function can be used to discard unneeded output of expressions (functions, third-party libraries, etc.).

It can also be used to discard results during development.

The function is utilized by built-in functions such as map:get to return an empty sequence for arbitrary input.

It is ·implementation-dependent· whether the supplied argument is evaluated or ignored. An implementation may decide to evaluate ·nondeterministic· expressions and ignore deterministic ones.

Examples
Expression:

void(1 to 1000000)

Result:
()
Expression:

array:get(array { 1, 2, 3 }, 4, void#1)

Result:
()

(Without the third argument, an error would be raised.)

Expression:

for $f in (identity#1, void#1) return $f(123)

Result:
123
Expression:
let $mapping := () 
return for-each(1 to 10, $mapping otherwise void#0)
Result:
()

(Indicates that if no mapping is supplied, all items are dropped.)

13.2 Comparison functions

The functions in this section perform comparisons between the items in one or more sequences.

Function Meaning
fn:atomic-equal Determines whether two atomic items are equal, under the rules used for comparing keys in a map.
fn:deep-equal This function assesses whether two sequences are deep-equal to each other. To be deep-equal, they must contain items that are pairwise deep-equal; and for two items to be deep-equal, they must either be atomic items that compare equal, or nodes of the same kind, with the same name, whose children are deep-equal, or maps with matching entries, or arrays with matching members.
fn:compare Returns -1, 0, or 1, depending on whether the first value is less than, equal to, or greater than the second value.
fn:distinct-values Returns the values that appear in a sequence, with duplicates eliminated.
fn:duplicate-values Returns the values that appear in a sequence more than once.
fn:index-of Returns a sequence of positive integers giving the positions within the sequence $input of items that are equal to $target.
fn:starts-with-subsequence Determines whether one sequence starts with another, using a supplied callback function to compare items.
fn:ends-with-subsequence Determines whether one sequence ends with another, using a supplied callback function to compare items.
fn:contains-subsequence Determines whether one sequence contains another as a contiguous subsequence, using a supplied callback function to compare items.

13.2.1 fn:atomic-equal

Changes in 4.0  

  1. New in 4.0. The function is identical to the internal op:same-key function in 3.1

Summary

Determines whether two atomic items are equal, under the rules used for comparing keys in a map.

Signature
fn:atomic-equal(
$value1 as xs:anyAtomicType,
$value2 as xs:anyAtomicType
) as xs:boolean
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function fn:atomic-equal is used to compare two atomic items for equality. This function has the following properties (which do not all apply to the eq operator):

  • Any two atomic items can be compared, regardless of their type.

  • No dynamic error is ever raised (the result is either true or false).

  • The result of the comparison never depends on the static or dynamic context.

  • Every value (including NaN) is equal to itself.

  • The comparison is symmetric: if A equals B, then B equals A.

  • The comparison is transitive: if A equals B and B equals C, then A equals C.

The function returns true if and only if one of the following conditions is true:

  1. All of the following conditions are true:

    1. $value1 is an instance of xs:string, xs:anyURI, or xs:untypedAtomic

    2. $value2 is an instance of xs:string, xs:anyURI, or xs:untypedAtomic

    3. fn:codepoint-equal($value1, $value2)

    Note:

    Strings are compared without any dependency on collations.

  2. All of the following conditions are true:

    1. $value1 is an instance of xs:decimal, xs:double, or xs:float

    2. $value2 is an instance of xs:decimal, xs:double, or xs:float

    3. One of the following conditions is true:

      1. Both $value1 and $value2 are NaN

        Note:

        xs:double('NaN') is the same key as xs:float('NaN')

      2. Both $value1 and $value2 are positive infinity

        Note:

        xs:double('INF') is the same key as xs:float('INF')

      3. Both $value1 and $value2 are negative infinity

        Note:

        xs:double('-INF') is the same key as xs:float('-INF')

      4. $value1 and $value2 when converted to decimal numbers with no rounding or loss of precision are mathematically equal.

        Note:

        Every instance of xs:double, xs:float, and xs:decimal can be represented exactly as a decimal number provided enough digits are available both before and after the decimal point. Unlike the eq relation, which converts both operands to xs:double values, possibly losing precision in the process, this comparison is transitive.

        Note:

        Positive and negative zero compare equal.

  3. All of the following conditions are true:

    1. One of the following conditions is true:

      1. $value1 and $value2 are both instances of xs:date.

      2. $value1 and $value2 are both instances of xs:time.

      3. $value1 and $value2 are both instances of xs:dateTime.

      4. $value1 and $value2 are both instances of xs:gYear.

      5. $value1 and $value2 are both instances of xs:gYearMonth.

      6. $value1 and $value2 are both instances of xs:gMonth.

      7. $value1 and $value2 are both instances of xs:gMonthDay.

      8. $value1 and $value2 are both instances of xs:gDay.

    2. One of the following conditions is true:

      1. Both $value1 and $value2 have a timezone

      2. Neither $value1 nor $value2 has a timezone

    3. $value1 eq $value2

    Note:

    Values having a timezone are never equal to values without one. The implicit timezone is not used.

  4. All of the following conditions are true:

    1. One of the following conditions is true:

      1. $value1 and $value2 are both instances of xs:boolean.

      2. $value1 and $value2 are both instances of xs:QName.

      3. $value1 and $value2 are both instances of xs:NOTATION.

      4. $value1 and $value2 are both instances of xs:duration.

      5. $value1 and $value2 are both instances of xs:hexBinary.

      6. $value1 and $value2 are both instances of xs:base64Binary.

    2. $value1 eq $value2

Notes

The internal function op:same-key was introduced in an earlier version of this specification for comparing keys within a map. In this version of the specification, the functionality is unchanged, but the function is exposed so that it is available directly to applications.

The function is used to assess whether two atomic items are considered to be duplicates when used as keys in a map. A map cannot contain two separate entries whose keys are the same as defined by this function. The function is also used when matching keys in functions such as map:get and map:remove.

The rules for comparing keys in a map are chosen to ensure that the comparison is:

  • Context-free: there is no dependency on the static or dynamic context

  • Error-free: any two atomic items can be compared, and the result is either true or false, never an error

  • Transitive: if A is the same key as B, and B is the same key as C, then A is the same key as C.

Two atomic items may be distinguishable even though they are equal under this comparison. For example: they may have different type annotations; dates and times may have different timezones; xs:QName values may have different prefixes.

Unlike the eq operator and the fn:deep-equal function, xs:hexBinary and xs:base64Binary values are considered distinct. This decision was made in order to preserve backwards compatibility: if the values were treated as interchangeable, it would become impossible to construct certain maps that could be validly constructed using earlier versions of the specification, and it would be difficult to make maps fully interoperable between processors supporting different language versions, for example when calling fn:transform.

As always, any algorithm that delivers the right result is acceptable. For example, when testing whether an xs:double value D is the same key as an xs:decimal value that has N significant digits, it is not necessary to know all the digits in the decimal expansion of D to establish the result: computing the first N+1 significant digits (or indeed, simply knowing that there are more than N significant digits) is sufficient.

Examples
Expression:

atomic-equal(3, 3)

Result:
true()
Expression:

atomic-equal(3, 3e0)

Result:
true()
Expression:

atomic-equal(3.1, 3.1e0)

Result:
false()
Expression:

atomic-equal(xs:double('NaN'), xs:float('NaN'))

Result:
true()
Expression:

atomic-equal("a", "a")

Result:
true()
Expression:

atomic-equal("a", "A")

Result:
false()
Expression:

atomic-equal("a", xs:untypedAtomic("a"))

Result:
true()
Expression:
atomic-equal(
  "https://www.w3.org/",
  xs:anyURI("https://www.w3.org/")
)
Result:
true()
Expression:

atomic-equal(12, "12")

Result:
false()

13.2.2 fn:deep-equal

Changes in 4.0  

  1. The $options parameter has been added, absorbing the $collation parameter.  [Issues 934 1167 PR 1191 21 May 2024]

  2. A callback function can be supplied for comparing individual items.  [Issues 99 1142 PRs 1120 1150 9 April 2024]

Summary

This function assesses whether two sequences are deep-equal to each other. To be deep-equal, they must contain items that are pairwise deep-equal; and for two items to be deep-equal, they must either be atomic items that compare equal, or nodes of the same kind, with the same name, whose children are deep-equal, or maps with matching entries, or arrays with matching members.

Signature
fn:deep-equal(
$input1 as item()*,
$input2 as item()*,
$options as (xs:string | map(*))? := {'collation':fn:default-collation()}
) as xs:boolean
Properties

The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.

The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.

Rules

The $options argument, if present, defines additional parameters controlling how the comparison is done. If it is supplied as a map, then he ·option parameter conventions· apply.

For backwards compatibility reasons, the $options argument can also be set to a string containing a collation name. Supplying a string $S for this argument is equivalent to supplying the map {'collation': $S}. Omitting the argument, or supplying the empty sequence, is equivalent to supplying an empty map.

If the two sequences ($input1 and $input2) are both empty, the function returns true.

If the two sequences are of different lengths, the function returns false.

If the two sequences are of the same length, the comparison is controlled by the ordered option:

  • By default, the option is true: The function returns true if and only if every item in the sequence $input1 is deep-equal to the item at the same position in the sequence $input2.

  • If the option is set to false, the function returns false if and only if every item in the sequence $input1 is deep-equal to an item at some position in the sequence $input2, and vice versa.

The rules for deciding whether two items are deep-equal appear below.

The entries that may appear in the $options map are as follows. The detailed rules for the interpretation of each option appear later.

record(
base-uri? as xs:boolean,
collation? as xs:string,
comments? as xs:boolean,
debug? as xs:boolean,
id-property? as xs:boolean,
idrefs-property? as xs:boolean,
in-scope-namespaces? as xs:boolean,
items-equal? as fn(item(), item()) as xs:boolean?,
namespace-prefixes? as xs:boolean,
nilled-property? as xs:boolean,
normalization-form? as xs:string?,
ordered? as xs:boolean,
processing-instructions? as xs:boolean,
timezones? as xs:boolean,
type-annotations? as xs:boolean,
type-variety? as xs:boolean,
typed-values? as xs:boolean,
unordered-elements? as xs:QName*,
whitespace? as enum("preserve", "strip", "normalize")
)
Key Meaning

base-uri

Determines whether the base-uri of a node is significant.
  • Type: xs:boolean

  • Default: false

collation

Identifies a collation which is used at all levels of recursion when strings are compared (but not when names are compared), according to the rules in 5.3.5 Choosing a collation. If the argument is not supplied, or if it is empty, then the default collation from the dynamic context of the caller is used.
  • Type: xs:string

  • Default: fn:default-collation()

comments

Determines whether comments are significant.
  • Type: xs:boolean

  • Default: false

debug

Requests diagnostics in the case where the function returns false. When this option is set and the two inputs are found to be not equal, the implementation should output messages (in an implementation-dependent format and to an implementation-dependent destination) indicating the nature of the differences that were found.
  • Type: xs:boolean

  • Default: false

id-property

Determines whether the id property of elements and attributes is significant.
  • Type: xs:boolean

  • Default: false

idrefs-property

Determines whether the idrefs property of elements and attributes is significant.
  • Type: xs:boolean

  • Default: false

in-scope-namespaces

Determines whether the in-scope namespaces of elements are significant.
  • Type: xs:boolean

  • Default: false

items-equal

A user-supplied function to test whether two items are considered equal. The function can return true or false to indicate that two items are or are not equal, overriding the normal rules that would apply to those items; or it can return an empty sequence, to indicate that the normal rules should be followed. Note that returning () is not equivalent to returning false.
  • Type: fn(item(), item()) as xs:boolean?

  • Default: fn:void#0

namespace-prefixes

Determines whether namespace prefixes in xs:QName values (particularly the names of elements and attributes) are significant.
  • Type: xs:boolean

  • Default: false

nilled-property

Determines whether the nilled property of elements and attributes is significant.
  • Type: xs:boolean

  • Default: false

normalization-form

If present, indicates that text and attributes are converted to the specified Unicode normalization form prior to comparison. The value is as for the corresponding argument of fn:normalize-unicode.
  • Type: xs:string?

  • Default: ()

ordered

Controls whether the top-level order of the items of the input sequences is considered.
  • Type: xs:boolean

  • Default: true

processing-instructions

Determines whether processing instructions are significant.
  • Type: xs:boolean

  • Default: false

timezones

Determines whether timezones in date/time values are significant.
  • Type: xs:boolean

  • Default: false

type-annotations

Determines whether type annotations are significant.
  • Type: xs:boolean

  • Default: false

type-variety

Determines whether the variety of the type annotation of an element (whether it has complex content or simple content) is significant.
  • Type: xs:boolean

  • Default: true

typed-values

Determines whether nodes are compared using their typed values rather than their string values.
  • Type: xs:boolean

  • Default: true

unordered-elements

A list of QNames of elements considered to be unordered: that is, their child elements may appear in any order.
  • Type: xs:QName*

  • Default: ()

whitespace

Determines the extent to which whitespace is treated as significant. The value preserve retains all whitespace. The value strip ignores text nodes consisting entirely of whitespace. The value normalize ignores whitespace text nodes in the same way as the strip option, and additionally compares text and attribute nodes after normalizing whitespace in accordance with the rules of the fn:normalize-space function. The detailed rules, given below, also take into account type annotations and xml:space attributes.
  • Type: enum("preserve", "strip", "normalize")

  • Default: preserve

Note:

As a general rule for boolean options (but not invariably), the value true indicates that the comparison is more strict.

In the following rules, where a recursive call on fn:deep-equal is made, this is assumed to use the same values of $options as the original call.

The rules reference a function equal-strings which compares two xs:string or xs:anyURI values as follows:

  1. If the whitespace option is set to normalize, then each string is processed by calling the fn:normalize-space function.

  2. If the normalization-form option is present, each string is then normalized by calling the fn:normalize-unicode function, supplying the specified normalization form.

  3. The two strings are then compared for equality under the requested collation.

More formally, the equal-strings function is equivalent to the following implementation in XQuery:

declare function equal-strings(
  $string1   as xs:string,
  $string2   as xs:string, 
  $options   as map(*)
) as xs:boolean {
  let $n1 := if ($options?normalization-form)
             then normalize-unicode(?, $options?normalization-form) 
             else identity#1
  let $n2 := if ($options?whitespace = "normalize")
             then normalize-space#1 
             else identity#1               
  return compare($n1($n2($string1)), $n1($n2($string2)), $options?collation) eq 0    
}

The rules for deciding whether two items $i1 and $i2 are deep-equal are as follows.

The two items are first compared using the function supplied in the items-equal option. If this returns true then the items are deep-equal. If it returns false then the items are not deep-equal. If it returns an empty sequence (which is always the case if the option is not explicitly specified) then the two items are deep-equal if one or more of the following conditions are true:

  1. All of the following conditions are true:

    1. $i1 is an atomic item.

    2. $i2 is an atomic item.

    3. Either the type-annotations option is false, or both atomic items have the same type annotation.

    4. One of the following conditions is true:

      1. If both $i1 and $i2 are instances of xs:string, xs:untypedAtomic, or xs:anyURI, equal-strings($i1, $i2, $collation, $options) returns true.

      2. If both $i1 and $i2 are instances of xs:date, xs:time or xs:dateTime, $i1 eq $i2 returns true.

      3. If both $i1 and $i2 are instances of xs:hexBinary or xs:base64Binary, $i1 eq $i2 returns true.

      4. Otherwise, fn:atomic-equal($i1, $i2) returns true.

      Note:

      If $i1 and $i2 are not comparable, that is, if the expression ($i1 eq $i2) would raise an error, then the function returns false; it does not report an error.

    5. One of the following conditions is true:

      1. Option namespace-prefixes is false.

      2. Neither $i1 nor $i2 is of type xs:QName or xs:NOTATION.

      3. $i1 and $i2 are qualified names with the same namespace prefix.

    6. One of the following conditions is true:

      1. Option timezones is false.

      2. Neither $i1 nor $i2 is of type xs:date, xs:time, xs:dateTime, xs:gYear, xs:gYearMonth, xs:gMonth, xs:gMonthDay, or xs:gDay.

      3. Neither $i1 nor $i2 has a timezone component.

      4. Both $i1 and $i2 have a timezone component and the timezone components are equal.

  2. All of the following conditions are true:

    1. $i1 is a map.

    2. $i2 is a map.

    3. Both maps have the same number of entries.

    4. For every entry in the first map, there is an entry in the second map that:

      1. has the ·same key· (note that the collation is not used when comparing keys), and

      2. has the same associated value (compared using the fn:deep-equal function, recursively).

  3. All the following conditions are true:

    1. $i1 is an array.

    2. $i2 is an array.

    3. Both arrays have the same number of members (array:size($i1) eq array:size($i2)).

    4. Members in the same position of both arrays are deep-equal to each other: that is, every $p in 1 to array:size($i1) satisfies deep-equal($i1($p), $i2($p), $collation, $options).

  4. All the following conditions are true:

    1. $i1 is a function item and is not a map or array.

    2. $i2 is a function item and is not a map or array.

    3. $i1 and $i2 have the same function identity. The concept of function identity is explained in Section 2.9.4 Function ItemsDM40.

  5. All the following conditions are true:

    1. $i1 is a node.

    2. $i2 is a node.

    3. Both nodes have the same node kind.

    4. Either the base-uri option is false, or both nodes have the same value for their base URI property, or both nodes have an absent base URI.

    5. Let significant-children($parent) be the sequence of nodes obtained by applying the following steps to the children of $parent, in turn:

      1. Comment nodes are discarded if the option comments is false.

      2. Processing instruction nodes are discarded if the option processing-instructions is false.

      3. Adjacent text nodes are merged.

      4. Whitespace-only text nodes are discarded if both the following conditions are true:

        1. The option whitespace is set to strip or normalize; and

        2. The text node is not within the scope of an element that has the attribute xml:space="preserve".

        Note:

        Whitespace text nodes will already have been discarded if $parent is a schema-validated element node whose type annotation is a complex type with an element-only or empty content model.

    6. One of the following conditions is true.

      1. Both nodes are document nodes, and the sequence significant-children($i1) is deep-equal to the sequence significant-children($i2).

      2. Both nodes are element nodes, and all the following conditions are true:

        1. The two nodes have the same name, that is (node-name($i1) eq node-name($i2)).

        2. Either the option namespace-prefixes is false, or both element names have the same prefix.

        3. Either the option in-scope-namespaces is false, or both element nodes have the same in-scope namespace bindings.

        4. Either the option type-annotations is false, or both element nodes have the same type annotation.

        5. Either the option id-property is false, or both element nodes have the same value for their is-id property.

        6. Either the option idrefs-property is false, or both element nodes have the same value for their is-idrefs property.

        7. Either the option nilled-property is false, or both element nodes have the same value for their nilled property.

        8. One of the following conditions is true:

          1. The option type-variety is false.

          2. Both nodes are annotated as having simple content. For this purpose simple content means either a simple type or a complex type with simple content.

          3. Both nodes are annotated as having complex content. For this purpose complex content means a complex type whose variety is mixed, element-only, or empty.

          Note:

          It is a consequence of this rule that, by default, validating a document D against a schema will usually (but not necessarily) result in a document that is not deep-equal to D. The exception is when the schema allows all elements to have mixed content.

        9. The two nodes have the same number of attributes, and for every attribute $a1 in $i1/@* there exists an attribute $a2 in $i2/@* such that node-name($a1) eq node-name($a2) and $a1 and $a2 are deep-equal.

          Note:

          Attributes, like other items, may be compared using the supplied items-equal function. However, this function will not be called to compare two attribute nodes unless they have the same name.

        10. One of the following conditions holds:

          1. Both element nodes are annotated as having simple content (as defined above), the typed-values option is true, and the typed value of $i1 is deep-equal to the typed value of $i2.

            Note:

            The typed value of an element node is used only when the element has simple content, which means that no error can occur as a result of atomizing a node with no typed value.

          2. Both element nodes are annotated as having simple content (as defined above), the typed-values option is false, and the equal-strings function returns true when applied to the string value of $i1 and the string value of $i2.

          3. Both element nodes have a type annotation that is a complex type with element-only, mixed, or empty content, the (common) element name is not present in the unordered-elements option, and the sequence significant-children($i1) is deep-equal to the sequence significant-children($i2).

          4. Both element nodes have a type annotation that is a complex type with element-only, mixed, or empty content, the (common) element name is present in the unordered-elements option, and the sequence significant-children($i1) is deep-equal to some permutation of the sequence significant-children($i2).

            Note:

            Elements annotated as xs:untyped fall into this category.

            Including an element name in the unordered-elements list is unlikely to be useful except when the relevant elements have element-only content, but this is not a requirement: the rules apply equally to elements with mixed content, or even (trivially) to elements with empty content.

      3. Both nodes are attribute nodes, and all the following conditions are true:

        1. The two attribute nodes have the same name, that is (node-name($i1) eq node-name($i2)).

        2. Either the option namespace-prefixes is false, or both attribute names have the same prefix.

        3. Either the option type-annotations is false, or both attribute nodes have the same type annotation.

        4. Either the option id-property is false, or both attribute nodes have the same value for their is-id property.

        5. Either the option idrefs-property is false, or both attribute nodes have the same value for their is-idrefs property.

        6. Let T be true if the option typed-value is true and both attributes $i1 and $i2 have a type annotation other than xs:untypedAtomic.

          Then either T is true and the typed value of $i1 is deep-equal to the typed value of $i2, or T is false and the equal-strings function returns true when applied to the string value of $i1 and the string value of $i2.

      4. Both nodes are processing instruction nodes, and all the following conditions are true:

        1. The two nodes have the same name, that is (node-name($i1) eq node-name($i2)).

        2. The equal-strings function returns true when applied to the string value of $i1 and the string value of $i2.

      5. Both nodes are namespace nodes, and all the following conditions are true:

        1. The two nodes either have the same name or are both nameless, that is fn:deep-equal(node-name($i1), node-name($i2)).

        2. The string value of $i1 is equal to the string value of $i2 when compared using the Unicode codepoint collation.

        Note:

        Namespace nodes are not considered directly unless they appear in the top-level sequences passed explicitly to the fn:deep-equal function.

      6. Both nodes are comment nodes, and the equal-strings function returns true when applied to their string values.

      7. Both nodes are text nodes, and the equal-strings function returns true when applied to their string values.

In all other cases the result is false.

Error Conditions

A type error is raised [err:XPTY0004]XP if the value of $options includes an entry whose key is defined in this specification, and whose value is not of the permitted type for that key.

A dynamic error is raised [err:FOJS0005] if the value of $options includes an entry whose key is defined in this specification, and whose value is not a permitted value for that key.

Notes

By default, whitespace in text nodes and attributes is considered significant. There are various ways whitespace differences can be ignored:

  • If nodes have been schema-validated, setting the typed-values option to true causes the typed values rather than the string values to be compared. This will typically cause whitespace to be ignored except where the type of the value is xs:string.

  • Setting the whitespace option to normalize causes all text and attribute nodes to have leading and trailing whitespace removed, and intermediate whitespace reduced to a single character.

By default, two nodes are not required to have the same type annotation, and they are not required to have the same in-scope namespaces. They may also differ in their parent, their base URI, and the values returned by the is-id and is-idrefs accessors (see Section 4.5 is-id AccessorDM40 and Section 4.6 is-idrefs AccessorDM40). The order of children is significant, but the order of attributes is insignificant.

By default, the contents of comments and processing instructions are significant only if these nodes appear directly as items in the two sequences being compared. The content of a comment or processing instruction that appears as a descendant of an item in one of the sequences being compared does not affect the result. In previous versions of this specification, the presence of a comment or processing instruction, if it caused text to be split across two text nodes, might affect the result; this has been changed in 4.0 so that adjacent text nodes are merged after comments and processing instructions have been stripped.

Comparing items of different kind (for example, comparing an atomic item to a node, or a map to an array, or an integer to an xs:date) returns false, it does not return an error. So the result of fn:deep-equal(1, current-dateTime()) is false.

The items-equal callback function may be used to override the default rules for comparing individual items. For example, it might return true unconditionally when comparing two @timestamp attributes, if there is no expectation that the two trees will have identical timestamps. Given two nodes $n1 and $n2, it might compare them using the is operator, so that instead of comparing the descendants of the two nodes, the function simply checks whether they are the same node. Given two function items $f1 and $f2 it might return true unconditionally, knowing that there is no effective way to test if the functions are equivalent. Given two numeric values, it might return true if they are equal to six decimal places.

It is good practice for the items-equal callback function to be reflexive, symmetric, and transitive; if it is not, then the fn:deep-equal function itself will lack these qualities. Reflexive means that every item (including NaN) should be equal to itself; symmetric means that items-equal(A, B) should return the same result as items-equal(B, A), and transitive means that items-equal(A, B) and items-equal(B, C) should imply items-equal(A, C).

Setting the ordered option to false or supplying the unordered-elements option may result in poor performance when comparing long sequences, especially if the items-equal callback function is supplied.

Examples
Variables
let $at := <attendees>
  <name last="Parker" first="Peter"/>
  <name last="Barker" first="Bob"/>
  <name last="Parker" first="Peter"/>
</attendees>
Expression:

deep-equal($at, $at/*)

Result:
false()
Expression:

deep-equal($at/name[1], $at/name[2])

Result:
false()
Expression:

deep-equal($at/name[1], $at/name[3])

Result:
true()
Expression:

deep-equal($at/name[1], 'Peter Parker')

Result:
false()
Expression:
deep-equal(
  $at//name[@first="Bob"], 
  $at//name[@last="Barker"],
  options := { 'items-equal': op('is') } 
)
Result:
true()

(Tests whether the two input sequences contain exactly the same nodes.)

Expression:

deep-equal([ 1, 2, 3], [ 1, 2, 3 ])

Result:
true()
Expression:

deep-equal((1, 2, 3), [ 1, 2, 3 ])

Result:
false()
Expression:
deep-equal(
  { 1: 'a', 2: 'b' },
  { 2: 'b', 1: 'a' }
)
Result:
true()
Expression:
deep-equal(
  (1, 2, 3, 4),
  (1, 4, 3, 2),
  options := { 'ordered': false() }
)
Result:
true()
Expression:
deep-equal(
  (1, 1, 2, 3),
  (1, 2, 3, 3),
  options := { 'ordered': false() }
)
Result:
false()
Expression:
deep-equal(
  parse-xml("<a xmlns='AA'/>"),
  parse-xml("<p:a xmlns:p='AA'/>")
)
Result:
true()

(By default, namespace prefixes are ignored).

Expression:
deep-equal(
  parse-xml("<a xmlns='AA'/>"),
  parse-xml("<p:a xmlns:p='AA'/>"),
  options := { 'namespace-prefixes': true() }
)
Result:
false()

(False because the namespace prefixes differ).

Expression:
deep-equal(
  parse-xml("<a xmlns='AA'/>"),
  parse-xml("<p:a xmlns:p='AA'/>"),
  options := { 'in-scope-namespaces': true() }
)
Result:
false()

(False because the in-scope namespace bindings differ).

Expression:
deep-equal(
  parse-xml("<a><b/><c/></a>"),
  parse-xml("<a><c/><b/></a>")
)
Result:
false()

(By default, order of elements is significant).

Expression:
deep-equal(
  parse-xml("<a><b/><c/></a>"),
  parse-xml("<a><c/><b/></a>"),
  options := { 'unordered-elements': xs:QName('a') }
)
Result:
true()

(The unordered-elements option means that the ordering of the children of a is ignored.)

Expression:
deep-equal(
  parse-xml("<para style='bold'><span>x</span></para>"),
  parse-xml("<para style=' bold'> <span>x</span></para>")
)
Result:
false()

(By default, both the leading whitespace in the style attribute and the whitespace text node preceding the span element are significant.)

Expression:
deep-equal(
  parse-xml("<para style='bold'><span>x</span></para>"),
  parse-xml("<para style=' bold'> <span>x</span></para>"),
  options := { 'whitespace': 'normalize' }
)
Result:
true()

(The whitespace option causes both the leading space in the attribute value and the whitespace preceding the span element to be ignored.)

Expression:
deep-equal(
  (1, 2, 3), 
  (1.0007, 1.9998, 3.0005),
  options := { 'items-equal': fn($x, $y) {
                  if (($x, $y) instance of xs:numeric+) {
                      abs($x - $y) lt 0.001
                  }
                }
             }
)
Result:
true()

(For numeric values, the callback function tests whether they are approximately equal. For any other items, it returns an empty sequence, so the normal comparison rules apply.)

Expression:
deep-equal(
  (1,2,3,4,5), 
  (1,2,3,8,5),
  options := { 'items-equal': fn($x, $y) {
                 trace((), `comparing {$x} and {$y}`)
                }
             }
)
Result:
false()

(The callback function traces which items are being compared, without changing the result of the comparison.)

13.2.3 fn:compare

Changes in 4.0  

  1. The function has been expanded in scope to handle comparison of values other than strings.

Summary

Returns -1, 0, or 1, depending on whether the first value is less than, equal to, or greater than the second value.

Signature
fn:compare(
$value1 as xs:anyAtomicType?,
$value2 as xs:anyAtomicType?,
$collation as xs:string? := fn:default-collation()
) as xs:integer?
Properties

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.

Rules

Compares two atomic items $value1 and $value2 for order, and returns the integer value -1, 0, or 1, depending on whether $value1 is less than, equal to, or greater than $value2, respectively.

This function differs from the operators lt, eq, and gt in that decimal values are not converted to doubles. This means that the comparison is fully transitive, which makes it safe for use in sorting algorithms. It is used to underpin sorting in XQuery 4.0 and XSLT 4.0, and is also available as a free-standing function in its own right.

If either $value1 or $value2 is the empty sequence, the function returns the empty sequence.

Otherwise, the result is determined as follows:

  1. If $value1 is an instance of xs:string, xs:anyURI or xs:untypedAtomic, and if $value2 is an instance of xs:string, xs:anyURI or xs:untypedAtomic, the values are compared as strings, and the result reflects the order according to the rules of the collation that is used.

    The collation is determined according to the rules in 5.3.5 Choosing a collation.

    When used with the default collation, the function defines the semantics of the eq, ne, gt, lt, le and ge operators on xs:string values.

  2. If both $value1 and $value2 are instances of xs:numeric, the function relies on a total order, which is defined as follows:

    1. A value $f of type xs:float is in all cases equal to the value xs:double($f). The remaining rules therefore only consider instances of xs:double and xs:decimal.

    2. NaN is equal to itself and less than any other value.

    3. Negative infinity is equal to itself and less than any other value except NaN.

    4. Positive infinity is equal to itself and greater than any other value.

    5. Negative zero is equal to positive zero.

    6. Other xs:double and xs:decimal values (that is, values other than the infinities, NaN, and negative zero) are ordered according to their mathematical magnitude, the comparison being done without any rounding or loss of precision. This effect can be achieved by converting xs:double values to xs:decimal using an implementation of xs:decimal that imposes no limits on precision or scale, or an implementation whose limits are such that all xs:double values can be represented precisely.

  3. If both $value1 and $value2 are instances of xs:boolean, then:

    1. -1 is returned if op:boolean-less-than($value1, $value2) returns true.

    2. 0 is returned if op:boolean-equal($value1, $value2) returns true.

    3. 1 is returned otherwise.

  4. If $value1 is an instance of xs:hexBinary or xs:base64Binary, and if $value2 is an instance of xs:hexBinary or xs:base64Binary, then:

    1. -1 is returned if op:binary-less-than($value1, $value2) returns true.

    2. 0 is returned if op:binary-equal($value1, $value2) returns true.

    3. 1 is returned otherwise.

  5. If both $value1 and $value2 are instances of xs:date, then:

    1. -1 is returned if op:date-less-than($value1, $value2) returns true.

    2. 0 is returned if op:date-equal($value1, $value2) returns true.

    3. 1 is returned otherwise.

  6. If both $value1 and $value2 are instances of xs:time, then:

    1. -1 is returned if op:time-less-than($value1, $value2) returns true.

    2. 0 is returned if op:time-equal($value1, $value2) returns true.

    3. 1 is returned otherwise.

  7. If both $value1 and $value2 are instances of xs:dateTime, then:

    1. -1 is returned if op:dateTime-less-than($value1, $value2) returns true.

    2. 0 is returned if op:dateTime-equal($value1, $value2) returns true.

    3. 1 is returned otherwise.

  8. If both $value1 and $value2 are instances of xs:dayTimeDuration, then:

    1. -1 is returned if op:dayTimeDuration-less-than($value1, $value2) returns true.

    2. 0 is returned if op:duration-equal($value1, $value2) returns true.

    3. 1 is returned otherwise.

  9. If both $value1 and $value2 are instances of xs:yearMonthDuration, then:

    1. -1 is returned if op:yearMonthDuration-less-than($value1, $value2) returns true.

    2. 0 is returned if op:duration-equal($value1, $value2) returns true.

    3. 1 is returned otherwise.

  10. For any other combination of types, a type error [err:XPTY0004]XP is raised.

Notes

For numeric values, consider the xs:double value written as 0.1e0 and the xs:decimal value written as 0.1: The mathematical magnitude of this xs:double value is 0.1000000000000000055511151231257827021181583404541015625. Therefore, compare(0.1e0, 0.1) returns +1. By contrast, 0.1e0 lt 0.1 is false and 0.1e0 eq 0.1 is true, because those expressions convert the xs:decimal value 0.1 to the xs:double value 0.1e0 before the comparison.

Although operations such as sorting and the fn:min and fn:max functions invoke fn:compare to perform numeric comparison, these functions in some cases treat NaN differently.

Examples
Expression:

compare('abc', 'abc')

Result:
0
Expression:

compare('Strasse', 'Straße')

Result:
-1
Expression:

compare('Strasse', 'Straße')

Result:
0

(Assuming the default collation equates “ss” and the German letter “ß”.)

Expression:
compare(
  'Strasse',
  'Straße',
  collation(map{'lang':'de', 'strength':'primary'})
)
Result:
0

(The specified collation equates “ss” and the German letter “ß”.)

Expression:

compare('text', parse-xml('<xml>text</xml>'))

Result:
0
Expression:

compare(9, 10)

Result:
-1
Expression:

compare(123, 123.0)

Result:
0
Expression:

compare(xs:double('NaN'), xs:float('NaN'))

Result:
0
Expression:

compare(xs:double('NaN'), xs:double('-INF'))

Result:
-1
Expression:

compare(xs:double('-INF'), -23)

Result:
-1
Expression:

compare(1, 1e0)

Result:
0
Expression:

compare(1.1, 1.1e0)

Result:
-1
Expression:

compare(1.2, 1.2e0)

Result:
+1
Expression:

compare(9999, xs:double('INF'))

Result:
-1
Expression:

compare(false(), true())

Result:
-1
Expression:

compare(xs:hexBinary(''), xs:base64Binary(''))

Result:
0
Expression:

compare(xs:time('23:59:59'), xs:time('00:00:00'))

Result:
1
Expression:

compare(xs:date('2001-01-01+01:00'), xs:date('2001-01-01+00:00'))

Result:
-1

13.2.4 fn:distinct-values

Changes in 4.0  

  1. Changed in 4.0 to use transitive equality comparisons for numeric values.

  2. The order of results is now prescribed; it was previously implementation-dependent.  [Issue 628 PR 987]

Summary

Returns the values that appear in a sequence, with duplicates eliminated.

Signature
fn:distinct-values(
$values as xs:anyAtomicType*,
$collation as xs:string? := fn:default-collation()
) as xs:anyAtomicType*
Properties

The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.

The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.

Rules

The function returns the sequence that results from removing from $values all but one of a set of values that are considered equal to one another. Two items $J and $K in the input sequence (after atomization, as required by the function signature) are considered equal if fn:deep-equal($J, $K, $coll) is true, where $coll is the collation selected according to the rules in 5.3.5 Choosing a collation. This collation is used when string comparison is required.

If ordering mode (in the static context) is ordered then:

  • For any set of values that compare equal, the one that is returned is the one that appears first in $values.

  • The items that are returned appear in the order in which they occur within $values.

By contrast, if ordering mode is unordered then:

If the input sequence contains values of different numeric types that differ from each other by small amounts, then the eq operator is not transitive, because of rounding effects occurring during type promotion. In the situation where the input contains three values A, B, and C such that A eq B, B eq C, but A ne C, then the number of items in the result of the function (as well as the choice of which items are returned) is ·implementation-dependent·, subject only to the constraints that (a) no two items in the result sequence compare equal to each other, and (b) every input item that does not appear in the result sequence compares equal to some item that does appear in the result sequence.

For example, this arises when computing:

    distinct-values(
            (xs:float('1.0'),
            xs:decimal('1.0000000000100000000001',
            xs:double('1.00000000001'))

because the values of type xs:float and xs:double both compare equal to the value of type xs:decimal but not equal to each other.

Notes

If $values is the empty sequence, the function returns the empty sequence.

Values of type xs:untypedAtomic are compared as if they were of type xs:string.

Values that cannot be compared, because the eq operator is not defined for their types, are considered to be distinct.

For xs:float and xs:double values, positive zero is equal to negative zero and, although NaN does not equal itself, if $values contains multiple NaN values a single NaN is returned.

If xs:dateTime, xs:date or xs:time values do not have a timezone, they are considered to have the implicit timezone provided by the dynamic context for the purpose of comparison. Note that xs:dateTime, xs:date or xs:time values can compare equal even if their timezones are different.

Editorial note  
Ordering mode has been dropped.
Examples
Expression Result
distinct-values((1, 2.0, 3, 2))
(1, 2.0, 3)

(Assuming ordering mode is ordered.)

distinct-values((
  xs:untypedAtomic("cherry"),
  xs:untypedAtomic("plum"),
  xs:untypedAtomic("plum")
))
(xs:untypedAtomic("cherry"),
                  xs:untypedAtomic("plum"))

(Assuming ordering mode is ordered.)

13.2.5 fn:duplicate-values

Changes in 4.0  

  1. New in 4.0

  2. The order of results is now prescribed; it was previously implementation-dependent.  [Issue 628 PR 987]

Summary

Returns the values that appear in a sequence more than once.

Signature
fn:duplicate-values(
$values as xs:anyAtomicType*,
$collation as xs:string? := fn:default-collation()
) as xs:anyAtomicType*
Properties

The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.

The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.

Rules

The items of $values are compared against each other, according to the rules of fn:distinct-values and with $coll as the collation selected according to the rules in 5.3.5 Choosing a collation.

From each resulting set of values that are considered equal, one value will be returned if the set contains more than one value.

If ordering mode (in the static context) is ordered then:

  • For any set of values that compare equal, the one that is returned is the one that appears first in $values.

  • The items that are returned appear in the order in which they occur within $values.

By contrast, if ordering mode is unordered then:

Notes

The effect of the function is equivalent to the following XSLT expression:

<xsl:for-each-group select="$values" group-by="." collation="{ $collation }">
  <xsl:sequence select="current-group()[2]"/>
</xsl:for-each>

The following XQuery expression is equivalent if no collation is specified (group by requires collation URIs to be static):

for $group in $values
group by $value := $group
where count($group) > 1
return $value
Examples
Expression:

duplicate-values((1, 2, 3, 1.0, 1e0))

Result:
1

(If ordering mode is ordered the result will be the xs:integer value 1.)

Expression:

duplicate-values(1 to 100)

Result:
()
Expression:

duplicate-values(('1', <x>1</x>, '2', 2))

Result:
"1"

(The string "1" and the untyped value of the element node are considered equal, whereas the string "2" and the integer are considered unequal.)

Raise an error for duplicates in an ID sequence:

let $ids := duplicate-values(//@id)
where exists($ids)
return error((), 'Duplicate IDs found: ' || string-join($ids, ', '))

13.2.6 fn:index-of

Summary

Returns a sequence of positive integers giving the positions within the sequence $input of items that are equal to $target.

Signature
fn:index-of(
$input as xs:anyAtomicType*,
$target as xs:anyAtomicType,
$collation as xs:string? := fn:default-collation()
) as xs:integer*
Properties

The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.

The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.

Rules

The function returns a sequence of positive integers giving the positions within the sequence $input of items that are equal to $target.

The collation used by this function is determined according to the rules in 5.3.5 Choosing a collation. This collation is used when string comparison is required.

The items in the sequence $input are compared with $target under the rules for the eq operator. Values of type xs:untypedAtomic are compared as if they were of type xs:string. Values that cannot be compared, because the eq operator is not defined for their types, are considered to be distinct. If an item compares equal, then the position of that item in the sequence $input is included in the result.

The first item in a sequence is at position 1, not position 0.

The result sequence is in ascending numeric order.

Notes

If $input is the empty sequence, or if no item in $input matches $target, then the function returns the empty sequence.

No error occurs if non-comparable values are encountered. So when comparing two atomic items, the effective boolean value of fn:index-of($a, $b) is true if $a and $b are equal, false if they are not equal or not comparable.

Examples
Expression:

index-of((10, 20, 30, 40), 35)

Result:
()
Expression:

index-of((10, 20, 30, 30, 20, 10), 20)

Result:
(2, 5)
Expression:
index-of(
  ("a", "sport", "and", "a", "pastime"),
  "a"
)
Result:
(1, 4)
Expression:
index-of(
  ("a", "b", "c"),
  "B",
  "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive"
)
Result:
2
Expression:

index-of(current-date(), 23)

Result:
()
Expression:

index-of([ 1, [ 5, 6 ], [ 6, 7 ] ], 6)

Result:
(3, 4)

(The array is atomized to a sequence of five integers).

If @a is an attribute of type xs:NMTOKENS whose string value is "red green blue", and whose typed value is therefore ("red", "green", "blue"), then fn:index-of(@a, "blue") returns 3. This is because the function calling mechanism atomizes the attribute node to produce a sequence of three xs:NMTOKEN values.

13.2.7 fn:starts-with-subsequence

Changes in 4.0  

  1. New in 4.0  [Issue 92 PR 222 1 November 2022]

Summary

Determines whether one sequence starts with another, using a supplied callback function to compare items.

Signature
fn:starts-with-subsequence(
$input as item()*,
$subsequence as item()*,
$compare as (fn(item(), item()) as xs:boolean?)? := fn:deep-equal#2
) as xs:boolean
Properties

The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.

The three-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function returns true if $input starts with $subsequence, when items are compared using the supplied (or default) $compare function.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

count($input) ge count($subsequence) and
every(for-each-pair($input, $subsequence, $compare))
Notes

There is no requirement that the $compare function should have the traditional qualities of equality comparison. The result is well-defined, for example, even if $compare is not transitive or not symmetric. A return value of () from the function is treated as false.

Examples
Expression:

starts-with-subsequence((), ())

Result:
true()
Expression:

starts-with-subsequence(1 to 10, 1 to 5)

Result:
true()
Expression:

starts-with-subsequence(1 to 10, ())

Result:
true()
Expression:

starts-with-subsequence(1 to 10, 1 to 10)

Result:
true()
Expression:

starts-with-subsequence(1 to 10, 1)

Result:
true()
Expression:
starts-with-subsequence(
  1 to 10,
  101 to 105,
  fn($x, $y) { $x mod 100 = $y mod 100 }
)
Result:
true()
Expression:
starts-with-subsequence(
  ("A", "B", "C"),
  ("a", "b"),
  fn($x, $y) {
    compare(
      $x,
      $y,
      "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive"
    ) eq 0
  }
)
Result:
true()
Expression:
let $p := parse-xml("<doc><chap><p/><p/></chap></doc>")//p[2]
return starts-with-subsequence(
  $p/ancestor::*[1],
  $p/parent::*,
  op("is")
)
Result:
true()
Expression:

starts-with-subsequence(10 to 20, 1 to 5, op("gt"))

Result:
true()
Expression:
starts-with-subsequence(
  ("Alpha", "Beta", "Gamma"),
  ("A", "B"),
  starts-with#2
)
Result:
true()
Expression:
starts-with-subsequence(
  ("Alpha", "Beta", "Gamma", "Delta"),
  1 to 3,
  fn($x, $y) { ends-with($x, 'a' ) }
)
Result:
true()

(True because the first three items in the input sequence end with "a".)

13.2.8 fn:ends-with-subsequence

Changes in 4.0  

  1. New in 4.0  [Issue 92 PR 222 1 November 2022]

Summary

Determines whether one sequence ends with another, using a supplied callback function to compare items.

Signature
fn:ends-with-subsequence(
$input as item()*,
$subsequence as item()*,
$compare as (fn(item(), item()) as xs:boolean?)? := fn:deep-equal#2
) as xs:boolean
Properties

The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.

The three-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function returns true if $input ends with $subsequence, when items are compared using the supplied (or default) $compare function.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

starts-with-subsequence(reverse($input), reverse($subsequence), $compare)
Notes

There is no requirement that the $compare function should have the traditional qualities of equality comparison. The result is well-defined, for example, even if $compare is not transitive or not symmetric.

A return value of () from the function is treated as false.

Examples
Expression:

ends-with-subsequence((), ())

Result:
true()
Expression:

ends-with-subsequence(1 to 10, 5 to 10)

Result:
true()
Expression:

ends-with-subsequence(1 to 10, ())

Result:
true()
Expression:

ends-with-subsequence(1 to 10, 1 to 10)

Result:
true()
Expression:

ends-with-subsequence(1 to 10, 10)

Result:
true()
Expression:
ends-with-subsequence(
  1 to 10,
  108 to 110,
  fn($x, $y) { $x mod 100 = $y mod 100 }
)
Result:
true()
Expression:
ends-with-subsequence(
  ("A", "B", "C"),
  ("b", "c"),
  fn($x, $y) {
    compare(
      $x,
      $y,
      "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive"
    ) eq 0
  }
)
Result:
true()
Expression:
let $p := parse-xml("<doc><chap><p/><p/></chap></doc>")//p[2]
return ends-with-subsequence(
  $p/ancestor::node()[last()],
  $p/root(),
  op("is")
)
Result:
true()
Expression:

ends-with-subsequence(10 to 20, 1 to 5, op("gt"))

Result:
true()
Expression:
ends-with-subsequence(
  ("Alpha", "Beta", "Gamma"),
  ("B", "G"),
  starts-with#2
)
Result:
true()
Expression:
ends-with-subsequence(
  ("Alpha", "Beta", "Gamma", "Delta"),
  1 to 2,
  fn($x, $y) { string-length($x) eq 5 }
)
Result:
true()

(True because the last two items in the input sequence have a string length of 5.)

13.2.9 fn:contains-subsequence

Changes in 4.0  

  1. New in 4.0  [Issue 92 PR 222 1 November 2022]

Summary

Determines whether one sequence contains another as a contiguous subsequence, using a supplied callback function to compare items.

Signature
fn:contains-subsequence(
$input as item()*,
$subsequence as item()*,
$compare as (fn(item(), item()) as xs:boolean?)? := fn:deep-equal#2
) as xs:boolean
Properties

The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.

The three-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function returns true if $input contains a consecutive subsequence matching $subsequence, when items are compared using the supplied (or default) $compare function.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

some $i in 0 to count($input) - count($subsequence) satisfies 
  every $j in 1 to count($subsequence)
  satisfies $compare($input[$i + $j], $subsequence[$j])
Notes

There is no requirement that the $compare function should have the traditional qualities of equality comparison. The result is well-defined, for example, even if $compare is not transitive or not symmetric.

A return value of () from the function is treated as false.

Examples
Expression:

contains-subsequence((), ())

Result:
true()
Expression:

contains-subsequence(1 to 10, 3 to 6)

Result:
true()
Expression:

contains-subsequence(1 to 10, (2, 4, 6))

Result:
false()
Expression:

contains-subsequence(1 to 10, ())

Result:
true()
Expression:

contains-subsequence(1 to 10, 1 to 10)

Result:
true()
Expression:

contains-subsequence(1 to 10, 5)

Result:
true()
Expression:
contains-subsequence(
  1 to 10,
  103 to 105,
  fn($x, $y) { $x mod 100 = $y mod 100 }
)
Result:
true()
Expression:
contains-subsequence(
  ("A", "B", "C", "D"),
  ("b", "c"),
  fn($x, $y) {
    compare(
      $x,
      $y,
      "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive"
    ) eq 0
  }
)
Result:
true()
Expression:
let $chap := parse-xml("<doc><chap><h1/><p/><p/><footnote/></chap></doc>")//chap
return contains-subsequence(
  $chap ! child::*,
  $chap ! child::p,
  op("is")
)
Result:
true()

(True because the p children of the chap element form a contiguous subsequence.)

Expression:

contains-subsequence(10 to 20, (5, 3, 1), op("gt"))

Result:
true()
Expression:
contains-subsequence(
  ("Alpha", "Beta", "Gamma", "Delta"), ("B", "G"),
  starts-with#2
)
Result:
true()
Expression:
contains-subsequence(
  ("Zero", "Alpha", "Beta", "Gamma", "Delta", "Epsilon"),
  1 to 4,
  fn($x, $y) { ends-with($x, 'a') }
)
Result:
true()

(True because there is a run of 4 consecutive items ending in "a".)

13.3 Functions that test the cardinality of sequences

The following functions test the cardinality of their sequence arguments.

Function Meaning
fn:zero-or-one Returns input if it contains zero or one items. Otherwise, raises an error.
fn:one-or-more Returns $input if it contains one or more items. Otherwise, raises an error.
fn:exactly-one Returns $input if it contains exactly one item. Otherwise, raises an error.

The functions fn:zero-or-one, fn:one-or-more, and fn:exactly-one defined in this section, check that the cardinality of a sequence is in the expected range. They are particularly useful with regard to static typing. For example, the function call fn:remove($seq, fn:index-of($seq2, 'abc')) requires the result of the call on fn:index-of to be a singleton integer, but the static type system cannot infer this; writing the expression as fn:remove($seq, fn:exactly-one(fn:index-of($seq2, 'abc'))) will provide a suitable static type at query analysis time, and ensures that the length of the sequence is correct with a dynamic check at query execution time.

The type signatures for these functions deliberately declare the argument type as item()*, permitting a sequence of any length. A more restrictive signature would defeat the purpose of the function, which is to defer cardinality checking until query execution time.

13.3.1 fn:zero-or-one

Summary

Returns input if it contains zero or one items. Otherwise, raises an error.

Signature
fn:zero-or-one(
$input as item()*
) as item()?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Except in error cases, the function returns $input unchanged.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression, except in error cases.

if (count($input) le 1) 
then $input 
else error(parse-QName('Q{http://www.w3.org/2005/xqt-errors}FORG0003'))
Error Conditions

A dynamic error is raised [err:FORG0003] if $input contains more than one item.

13.3.2 fn:one-or-more

Summary

Returns $input if it contains one or more items. Otherwise, raises an error.

Signature
fn:one-or-more(
$input as item()*
) as item()+
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Except in error cases, the function returns $input unchanged.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression, except in error cases.

if (count($input) ge 1) 
then $input 
else error(parse-QName('Q{http://www.w3.org/2005/xqt-errors}FORG0004'))
Error Conditions

A dynamic error is raised [err:FORG0004] if $input is an empty sequence.

13.3.3 fn:exactly-one

Summary

Returns $input if it contains exactly one item. Otherwise, raises an error.

Signature
fn:exactly-one(
$input as item()*
) as item()
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Except in error cases, the function returns $input unchanged.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression, except in error cases.

if (count($input) eq 1) 
then $input 
else error(parse-QName('Q{http://www.w3.org/2005/xqt-errors}FORG0005'))
Error Conditions

A dynamic error is raised [err:FORG0005] if $input is an empty sequence or a sequence containing more than one item.

13.4 Aggregate functions

Aggregate functions take a sequence as argument and return a single value computed from values in the sequence. Except for fn:count, the sequence must consist of values of a single type or one if its subtypes, or they must be numeric. xs:untypedAtomic values are permitted in the input sequence and handled by special conversion rules. The type of the items in the sequence must also support certain operations.

Function Meaning
fn:count Returns the number of items in a sequence.
fn:avg Returns the average of the values in the input sequence $values, that is, the sum of the values divided by the number of values.
fn:max Returns a value that is equal to the highest value appearing in the input sequence.
fn:min Returns a value that is equal to the lowest value appearing in the input sequence.
fn:sum Returns a value obtained by adding together the values in $values.
fn:all-equal Returns true if all items in a supplied sequence (after atomization) are equal.
fn:all-different Returns true if no two items in a supplied sequence are equal.

13.4.1 fn:count

Summary

Returns the number of items in a sequence.

Signature
fn:count(
$input as item()*
) as xs:integer
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the number of items in $input.

Formal Specification

The function is defined as follows, making use of primitive constructors and accessors defined in [XQuery and XPath Data Model (XDM) 4.0].

dm:count($input)
Notes

The function returns 0 if $input is the empty sequence.

Examples
Variables
let $tree := <doc><chap><p/><p/><p/></chap></doc>
let $seq2 := (98.5, 98.3, 98.9)
let $seq3 := ()
Expression Result
count($tree//chap/p)
3
count($seq3)
0
count($seq2)
3
count($seq2[. > 100])
0
count([])
1
count([ 1, 2, 3 ])
1

13.4.2 fn:avg

Summary

Returns the average of the values in the input sequence $values, that is, the sum of the values divided by the number of values.

Signature
fn:avg(
$values as xs:anyAtomicType*
) as xs:anyAtomicType?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $values is the empty sequence, the empty sequence is returned.

If $values contains values of type xs:untypedAtomic they are cast to xs:double.

Duration values must either all be xs:yearMonthDuration values or must all be xs:dayTimeDuration values. For numeric values, the numeric promotion rules defined in 4.2 Arithmetic operators on numeric values are used to promote all values to a single common type. After these operations, $values must satisfy the following condition:

There must be a type T such that:

  1. every item in $values is an instance of T.

  2. T is one of xs:double, xs:float, xs:decimal, xs:yearMonthDuration, or xs:dayTimeDuration.

The function returns the average of the values as sum($values) div count($values); but the implementation may use an otherwise equivalent algorithm that avoids arithmetic overflow.

Error Conditions

A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.

Examples
Variables
let $d1 := xs:yearMonthDuration("P20Y")
let $d2 := xs:yearMonthDuration("P10M")
let $seq3 := (3, 4, 5)
Expression Result
avg($seq3)
4.0

(The result is of type xs:decimal.)

avg(($d1, $d2))
xs:yearMonthDuration("P10Y5M")
avg(())
()
avg((xs:float('INF'), xs:float('-INF')))
xs:float('NaN')
avg(($seq3, xs:float('NaN')))
xs:float('NaN')

fn:avg(($d1, $seq3)) raises a type error [err:FORG0006].

13.4.3 fn:max

Summary

Returns a value that is equal to the highest value appearing in the input sequence.

Signature
fn:max(
$values as xs:anyAtomicType*,
$collation as xs:string? := fn:default-collation()
) as xs:anyAtomicType?
Properties

The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.

The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.

Rules

Any item in $values that is an instance of xs:untypedAtomic is first cast to xs:double. The resulting sequence is referred to as the converted sequence.

All pairs of values in the converted sequence must be mutually comparable. Two values are mutually comparable if one or more of the following conditions applies:

  1. Both values are instances of xs:string or xs:anyURI.

  2. Both values are instances of xs:numeric.

  3. Both values are instances of xs:hexBinary or xs:base64Binary.

  4. Both values are instances of xs:date.

  5. Both values are instances of xs:dateTime.

  6. Both values are instances of xs:time.

  7. Both values are instances of xs:dayTimeDuration.

  8. Both values are instances of xs:yearMonthDuration.

  9. Both values are instances of xs:boolean.

If the converted sequence contains a single value then it must be comparable to itself under the above rules. (So the input cannot be, for example, a singleton xs:QName.)

If the converted sequence is empty, the function returns the empty sequence.

If the converted sequence contains the value NaN, the value NaN is returned (as an xs:float or xs:double as appropriate).

Two items $v1 and $v2 from the converted sequence are compared as follows:

  1. If both values are instances of xs:string or xs:anyURI, they are compared using fn:compare($v1, $v2, $collation), where $collation is determined by the rules in 5.3.5 Choosing a collation.

    Note:

    In other cases, $collation is ignored.

  2. If both values are instances of xs:numeric, they are compared using fn:compare($v1, $v2).

  3. In all other cases, the values are compared using the lt and eq operators appropriate to their type.

The result of the function is a value from the converted sequence that is greater than or equal to every other value under the above rules. If there is more than one such value, then it is ·implementation-dependent· which of them is returned.

Error Conditions

A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.

Notes

If there are two or items that are “equal highest”, the specific item whose value is returned is ·implementation-dependent·. This can arise for example if two different strings compare equal under the selected collation, or if two different xs:dateTime values compare equal despite being in different timezones.

If the converted sequence contains exactly one value then that value is returned.

The default type when the fn:max function is applied to xs:untypedAtomic values is xs:double. This differs from the default type for operators such as lt, and for sorting in XQuery and XSLT, which is xs:string.

In version 4.0, if $values is a sequence of xs:decimal values (including the case where it is a sequence of xs:integer values), then the result will be one of these xs:decimal or xs:integer values. In earlier versions it would be the result of converting this xs:decimal to xs:double.

Examples
Expression Result
max((3, 2, 1))
3
max([ 3, 2, 1 ])
3

(Arrays are atomized).

max((xs:integer(5), xs:float(5), xs:double(0)))
5

(The result may be either the xs:integer or the xs:float, since they are equal.)

max((xs:float(0.0E0), xs:float(-0.0E0)))
xs:float(0.0e0)

(The result may be either positive or negative zero, since they are equal.)

max((current-date(), xs:date("2100-01-01")))
xs:date("2100-01-01")

(Assuming that the current date is during the 21st century.)

max(("a", "b", "c"))
"c"

(Assuming a typical default collation.)

max((3, 4, "Zero")) raises a type error [err:FORG0006].

13.4.4 fn:min

Summary

Returns a value that is equal to the lowest value appearing in the input sequence.

Signature
fn:min(
$values as xs:anyAtomicType*,
$collation as xs:string? := fn:default-collation()
) as xs:anyAtomicType?
Properties

The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.

The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.

Rules

Any item in $values that is an instance of xs:untypedAtomic is first cast to xs:double. The resulting sequence is referred to as the converted sequence.

All pairs of values in the converted sequence must be mutually comparable. Two values are mutually comparable if one or more of the following conditions applies:

  1. Both values are instances of xs:string or xs:anyURI.

  2. Both values are instances of xs:numeric.

  3. Both values are instances of xs:hexBinary or xs:base64Binary.

  4. Both values are instances of xs:date.

  5. Both values are instances of xs:dateTime.

  6. Both values are instances of xs:time.

  7. Both values are instances of xs:dayTimeDuration.

  8. Both values are instances of xs:yearMonthDuration.

  9. Both values are instances of xs:boolean.

If the converted sequence contains a single value then it must be comparable to itself under the above rules. (So the input cannot be, for example, a singleton xs:QName.)

If the converted sequence is empty, the function returns the empty sequence.

If the converted sequence contains the value NaN, the value NaN is returned (as an xs:float or xs:double as appropriate).

Two items $v1 and $v2 from the converted sequence are compared as follows:

  1. If both values are instances of xs:string or xs:anyURI, they are compared using fn:compare($v1, $v2, $collation), where $collation is determined by the rules in 5.3.5 Choosing a collation.

    Note:

    In other cases, $collation is ignored.

  2. If both values are instances of xs:numeric, they are compared using fn:compare($v1, $v2).

  3. In all other cases, the values are compared using the lt and eq operators appropriate to their type.

The result of the function is a value from the converted sequence that is less than or equal to every other value under the above rules. If there is more than one such value, then it is ·implementation-dependent· which of them is returned.

Error Conditions

A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.

Notes

If there are two or items that are “equal lowest”, the specific item whose value is returned is ·implementation-dependent·. This can arise for example if two different strings compare equal under the selected collation, or if two different xs:dateTime values compare equal despite being in different timezones.

If the converted sequence contains exactly one value then that value is returned.

The default type when the fn:min function is applied to xs:untypedAtomic values is xs:double. This differs from the default type for operators such as lt, and for sorting in XQuery and XSLT, which is xs:string.

In version 4.0, if $values is a sequence of xs:decimal values (including the case where it is a sequence of xs:integer values), then the result will be one of these xs:decimal or xs:integer values. In earlier versions it would be the result of converting this xs:decimal to xs:double.

Examples
Expression Result
min((3, 4, 5))
3
min([ 3, 4, 5 ])
3

(Arrays are atomized).

min((xs:integer(5), xs:float(5), xs:double(10)))
5

(The result may be either the xs:integer or the xs:float, since they are equal.)

min((xs:float(0.0E0), xs:float(-0.0E0)))
xs:float(0.0e0)

(The result may be either positive or negative zero, since they are equal.)

min((current-date(), xs:date("1900-01-01")))
xs:date("1900-01-01")

(Assuming that the current date is set to a reasonable value.)

min(("a", "b", "c"))
"a"

(Assuming a typical default collation.)

min((3, 4, "Zero")) raises a type error [err:FORG0006].

13.4.5 fn:sum

Summary

Returns a value obtained by adding together the values in $values.

Signature
fn:sum(
$values as xs:anyAtomicType*,
$zero as xs:anyAtomicType? := 0
) as xs:anyAtomicType?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Any values of type xs:untypedAtomic in $values are cast to xs:double. The items in the resulting sequence may be reordered in an arbitrary order. The resulting sequence is referred to below as the converted sequence.

If the converted sequence is empty, then the function returns the value of the argument $zero, which defaults to the xs:integer value 0.

If the converted sequence contains the value NaN, NaN is returned.

All items in $values must be numeric or derived from a single base type. In addition, the type must support addition. Duration values must either all be xs:yearMonthDuration values or must all be xs:dayTimeDuration values. For numeric values, the numeric promotion rules defined in 4.2 Arithmetic operators on numeric values are used to promote all values to a single common type. The sum of a sequence of integers will therefore be an integer, while the sum of a numeric sequence that includes at least one xs:double will be an xs:double.

The result of the function is the value of the expression:

if (count($c) eq 0) then $zero
else if (count($c) eq 1) then $c[1]
else $c[1] + sum(subsequence($c, 2))

where $c is the converted sequence.

The result of the function when a single argument is supplied is the result of the expression: fn:sum($arg, 0).

Error Conditions

A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.

Notes

The second argument allows an appropriate value to be defined to represent the sum of an empty sequence. For example, when summing a sequence of durations it would be appropriate to return a zero-length duration of the appropriate type. This argument is necessary because a system that does dynamic typing cannot distinguish “an empty sequence of integers", for example, from “an empty sequence of durations”.

The explicit or implicit value of the $zero argument is used only when the input sequence is empty, not when a non-empty sequence sums to zero. For example, sum((-1, +1), xs:double('NaN')) returns the xs:integer value 0, not NaN.

If the converted sequence contains exactly one value then that value is returned.

Examples
Variables
let $d1 := xs:yearMonthDuration("P20Y")
let $d2 := xs:yearMonthDuration("P10M")
let $seq1 := ($d1, $d2)
let $seq3 := (3, 4, 5)
Expression:

sum(($d1, $d2))

Result:
xs:yearMonthDuration("P20Y10M")
Expression:
sum(
  $seq1[. lt xs:yearMonthDuration('P3M')],
  xs:yearMonthDuration('P0M')
)
Result:
xs:yearMonthDuration("P0M")
Expression:

sum($seq3)

Result:
12
Expression:

sum(())

Result:
0
Expression:

sum((),())

Result:
()
Expression:

sum((1 to 100)[. lt 0], 0)

Result:
0
Expression:

sum(($d1, $d2), "ein Augenblick")

Result:
xs:yearMonthDuration("P20Y10M")

(There is no requirement that the $zero value should be the same type as the items in $value, or even that it should belong to a type that supports addition.)

Expression:

sum([ 1, 2, 3 ])

Result:
6

(Atomizing an array returns the sequence obtained by atomizing its members.)

Expression:

sum([ [ 1, 2 ], [ 3, 4 ] ])

Result:
10

(Atomizing an array returns the sequence obtained by atomizing its members.)

fn:sum(($d1, 9E1)) raises a type error [err:FORG0006].

13.4.6 fn:all-equal

Changes in 4.0  

  1. New in 4.0. Originally proposed under the name fn:uniform  [  20 September 2022]

Summary

Returns true if all items in a supplied sequence (after atomization) are equal.

Signature
fn:all-equal(
$values as xs:anyAtomicType*,
$collation as xs:string? := fn:default-collation()
) as xs:boolean
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.

Rules

Omitting the second argument, $collation, is equivalent to supplying fn:default-collation(). For more information on collations see 5.3.5 Choosing a collation.

The result of the function fn:all-equal($values, $collation) is true if and only if the result of fn:count(fn:distinct-values($values, $collation)) le 1 is true (that is, if the sequence is empty, or if all the items in the sequence are equal under the rules of the fn:distinct-values function).

Examples
Expression:

all-equal((1, 2, 3))

Result:
false()
Expression:

all-equal((1, 1.0, 1.0e0))

Result:
true()
Expression:

all-equal("one")

Result:
true()
Expression:

all-equal(())

Result:
true()
Expression:
all-equal(
  ("ABC", "abc"),
  "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive"
)
Result:
true()

The expression fn:all-equal(//p/@class) returns true if all p elements have the same value for @class.

The expression fn:all-equal(* ! fn:node-name()) returns true if all element children of the context node have the same name.

13.4.7 fn:all-different

Changes in 4.0  

  1. New in 4.0. Originally proposed under the name fn:unique  [  20 September 2022]

Summary

Returns true if no two items in a supplied sequence are equal.

Signature
fn:all-different(
$values as xs:anyAtomicType*,
$collation as xs:string? := fn:default-collation()
) as xs:boolean
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.

Rules

Omitting the second argument, $collation, is equivalent to supplying fn:default-collation(). For more information on collations see 5.3.5 Choosing a collation.

The result of the function fn:all-different($values, $collation) is true if and only if the result of fn:count(fn:distinct-values($values, $collation)) eq fn:count($values) is true (that is, if the sequence is empty, or if all the items in the sequence are distinct under the rules of the fn:distinct-values function).

Examples
Expression:

all-different((1, 2, 3))

Result:
true()
Expression:

all-different((1, 1.0, 1.0e0))

Result:
false()
Expression:

all-different("one")

Result:
true()
Expression:

all-different(())

Result:
true()
Expression:
all-different(
  ("ABC", "abc"),
  "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive"
)
Result:
false()

The expression fn:all-different(//employee/@ssn) is true if no two employees have the same value for their @ssn attribute.

The expression fn:all-different(* ! fn:node-name()) returns true if all element children of the context node have distinct names.

13.5 Functions on node identifiers

This section defines a number of functions used to find elements by ID or IDREF value, or to generate identifiers.

Function Meaning
fn:id Returns the sequence of element nodes that have an ID value matching the value of one or more of the IDREF values supplied in $values.
fn:element-with-id Returns the sequence of element nodes that have an ID value matching the value of one or more of the IDREF values supplied in $values.
fn:idref Returns the sequence of element or attribute nodes with an IDREF value matching the value of one or more of the ID values supplied in $values.
fn:generate-id This function returns a string that uniquely identifies a given node.
fn:element-number Allocates a sequence number to an element within a containing tree.

13.5.1 fn:id

Summary

Returns the sequence of element nodes that have an ID value matching the value of one or more of the IDREF values supplied in $values.

Signature
fn:id(
$values as xs:string*,
$node as node() := .
) as element()*
Properties

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·.

Rules

The function returns a sequence, in document order with duplicates eliminated, containing every element node E that satisfies all the following conditions:

  1. E is in the target document. The target document is the document containing $node, or the document containing the context value (.) if the second argument is omitted. The behavior of the function if $node is omitted is exactly the same as if the context value had been passed as $node.

  2. E has an ID value equal to one of the candidate IDREF values, where:

    • An element has an ID value equal to V if either or both of the following conditions are true:

      • The is-id property (See Section 4.5 is-id AccessorDM40.) of the element node is true, and the typed value of the element node is equal to V under the rules of the eq operator using the Unicode codepoint collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

      • The element has an attribute node whose is-id property (See Section 4.5 is-id AccessorDM40.) is true and whose typed value is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

    • Each xs:string in $values is parsed as if it were of type IDREFS, that is, each xs:string in $values is treated as a whitespace-separated sequence of tokens, each acting as an IDREF. These tokens are then included in the list of candidate IDREFs. If any of the tokens is not a lexically valid IDREF (that is, if it is not lexically an xs:NCName), it is ignored. Formally, the candidate IDREF values are the strings in the sequence given by the expression:

      for $s in $values
      return tokenize(normalize-space($s), ' ')[. castable as xs:IDREF]
  3. If several elements have the same ID value, then E is the one that is first in document order.

Error Conditions

A dynamic error is raised [err:FODC0001] if $node, or the context value if the second argument is absent, is a node in a tree whose root is not a document node.

The following errors may be raised when $node is omitted:

Notes

The effect of this function is anomalous in respect of element nodes with the is-id property. For legacy reasons, this function returns the element that has the is-id property, whereas it would be more appropriate to return its parent, that being the element that is uniquely identified by the ID. A new function fn:element-with-id has been introduced with the desired behavior.

If the data model is constructed from an Infoset, an attribute will have the is-id property if the corresponding attribute in the Infoset had an attribute type of ID: typically this means the attribute was declared as an ID in a DTD.

If the data model is constructed from a PSVI, an element or attribute will have the is-id property if its typed value is a single atomic item of type xs:ID or a type derived by restriction from xs:ID.

No error is raised in respect of a candidate IDREF value that does not match the ID of any element in the document. If no candidate IDREF value matches the ID value of any element, the function returns the empty sequence.

It is not necessary that the supplied argument should have type xs:IDREF or xs:IDREFS, or that it should be derived from a node with the is-idrefs property.

An element may have more than one ID value. This can occur with synthetic data models or with data models constructed from a PSVI where the element and one of its attributes are both typed as xs:ID.

If the source document is well-formed but not valid, it is possible for two or more elements to have the same ID value. In this situation, the function will select the first such element.

It is also possible in a well-formed but invalid document to have an element or attribute that has the is-id property but whose value does not conform to the lexical rules for the xs:ID type. Such a node will never be selected by this function.

Examples
Variables
let $emp := validate lax {
  document {
    <employee xml:id="ID21256"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
              xmlns:xs="http://www.w3.org/2001/XMLSchema">
      <empnr xsi:type="xs:ID">E21256</empnr>
      <first>John</first>
      <last>Brown</last>
    </employee>
  }
}
Expression Result
$emp/id('ID21256')/name()
"employee"

(The xml:id attribute has the is-id property, so the employee element is selected.)

$emp/id('E21256')/name()
"empnr"

(Assuming the empnr element is given the type xs:ID as a result of schema validation, the element will have the is-id property and is therefore selected. Note the difference from the behavior of fn:element-with-id.)

13.5.2 fn:element-with-id

Summary

Returns the sequence of element nodes that have an ID value matching the value of one or more of the IDREF values supplied in $values.

Signature
fn:element-with-id(
$values as xs:string*,
$node as node() := .
) as element()*
Properties

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·.

Rules

Note:

The effect of this function is identical to fn:id in respect of elements that have an attribute with the is-id property. However, it behaves differently in respect of element nodes with the is-id property. Whereas the fn:id function, for legacy reasons, returns the element that has the is-id property, this function returns the element identified by the ID, which is the parent of the element having the is-id property.

The function returns a sequence, in document order with duplicates eliminated, containing every element node E that satisfies all the following conditions:

  1. E is in the target document. The target document is the document containing $node, or the document containing the context value (.) if the second argument is omitted. The behavior of the function if $node is omitted is exactly the same as if the context value had been passed as $node.

  2. E has an ID value equal to one of the candidate IDREF values, where:

    • An element has an ID value equal to V if either or both of the following conditions are true:

      • The element has an child element node whose is-id property (See Section 4.5 is-id AccessorDM40.) is true and whose typed value is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

      • The element has an attribute node whose is-id property (See Section 4.5 is-id AccessorDM40.) is true and whose typed value is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

    • Each xs:string in $values is parsed as if it were of type IDREFS, that is, each xs:string in $values is treated as a whitespace-separated sequence of tokens, each acting as an IDREF. These tokens are then included in the list of candidate IDREFs. If any of the tokens is not a lexically valid IDREF (that is, if it is not lexically an xs:NCName), it is ignored. Formally, the candidate IDREF values are the strings in the sequence given by the expression:

      for $s in $arg
      return tokenize(normalize-space($s), ' ')[. castable as xs:IDREF]
  3. If several elements have the same ID value, then E is the one that is first in document order.

Error Conditions

A dynamic error is raised [err:FODC0001] if $node, or the context value if the second argument is omitted, is a node in a tree whose root is not a document node.

The following errors may be raised when $node is omitted:

Notes

This function is equivalent to the fn:id function except when dealing with ID-valued element nodes. Whereas the fn:id function selects the element containing the identifier, this function selects its parent.

If the data model is constructed from an Infoset, an attribute will have the is-id property if the corresponding attribute in the Infoset had an attribute type of ID: typically this means the attribute was declared as an ID in a DTD.

If the data model is constructed from a PSVI, an element or attribute will have the is-id property if its typed value is a single atomic item of type xs:ID or a type derived by restriction from xs:ID.

No error is raised in respect of a candidate IDREF value that does not match the ID of any element in the document. If no candidate IDREF value matches the ID value of any element, the function returns the empty sequence.

It is not necessary that the supplied argument should have type xs:IDREF or xs:IDREFS, or that it should be derived from a node with the is-idrefs property.

An element may have more than one ID value. This can occur with synthetic data models or with data models constructed from a PSVI where the element and one of its attributes are both typed as xs:ID.

If the source document is well-formed but not valid, it is possible for two or more elements to have the same ID value. In this situation, the function will select the first such element.

It is also possible in a well-formed but invalid document to have an element or attribute that has the is-id property but whose value does not conform to the lexical rules for the xs:ID type. Such a node will never be selected by this function.

Examples
Variables
let $emp := validate lax {    
  document {
    <employee xml:id="ID21256"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
              xmlns:xs="http://www.w3.org/2001/XMLSchema">
      <empnr xsi:type="xs:ID">E21256</empnr>
      <first>John</first>
      <last>Brown</last>
    </employee>
  }
}
Expression:
$emp/element-with-id('ID21256')/name()
Result:
"employee"

(The xml:id attribute has the is-id property, so the employee element is selected.)

Expression:

$emp/element-with-id('E21256')/name()

Result:
"employee"

(Assuming the empnr element is given the type xs:ID as a result of schema validation, the element will have the is-id property and is therefore its parent is selected. Note the difference from the behavior of fn:id.)

13.5.3 fn:idref

Summary

Returns the sequence of element or attribute nodes with an IDREF value matching the value of one or more of the ID values supplied in $values.

Signature
fn:idref(
$values as xs:string*,
$node as node() := .
) as node()*
Properties

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·.

Rules

The function returns a sequence, in document order with duplicates eliminated, containing every element or attribute node $N that satisfies all the following conditions:

  1. $N is in the target document. The target document is the document containing $node, or the document containing the context value (.) if the second argument is omitted. The behavior of the function if $node is omitted is exactly the same as if the context value had been passed as $node.

  2. $N has an IDREF value equal to one of the candidate ID values, where:

    • A node $N has an IDREF value equal to V if both of the following conditions are true:

      • The is-idrefs property (see Section 4.6 is-idrefs AccessorDM40) of $N is true.

      • The sequence

        tokenize(normalize-space(string($N)), ' ')

        contains a string that is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

    • Each xs:string in $values is parsed as if it were of lexically of type xs:ID. These xs:strings are then included in the list of candidate xs:IDs. If any of the strings in $values is not a lexically valid xs:ID (that is, if it is not lexically an xs:NCName), it is ignored. More formally, the candidate ID values are the strings in the sequence:

      $values[. castable as xs:NCName]
Error Conditions

A dynamic error is raised [err:FODC0001] if $node, or the context value if the second argument is omitted, is a node in a tree whose root is not a document node.

The following errors may be raised when $node is omitted:

Notes

An element or attribute typically acquires the is-idrefs property by being validated against the schema type xs:IDREF or xs:IDREFS, or (for attributes only) by being described as of type IDREF or IDREFS in a DTD.

Because the function is sensitive to the way in which the data model is constructed, calls on this function are not always interoperable.

No error is raised in respect of a candidate ID value that does not match the IDREF value of any element or attribute in the document. If no candidate ID value matches the IDREF value of any element or attribute, the function returns the empty sequence.

It is possible for two or more nodes to have an IDREF value that matches a given candidate ID value. In this situation, the function will return all such nodes. However, each matching node will be returned at most once, regardless how many candidate ID values it matches.

It is possible in a well-formed but invalid document to have a node whose is-idrefs property is true but that does not conform to the lexical rules for the xs:IDREF type. The effect of the above rules is that ill-formed candidate ID values and ill-formed IDREF values are ignored.

If the data model is constructed from a PSVI, the typed value of a node that has the is-idrefs property will contain at least one atomic item of type xs:IDREF (or a type derived by restriction from xs:IDREF). It may also contain atomic items of other types. These atomic items are treated as candidate ID values if two conditions are met: their lexical form must be valid as an xs:NCName, and there must be at least one instance of xs:IDREF in the typed value of the node. If these conditions are not satisfied, such values are ignored.

Examples
Variables
let $emp := validate lax {  
  document {    
    <employees xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
               xmlns:xs="http://www.w3.org/2001/XMLSchema">  
      <employee xml:id="ID21256">
        <empnr xsi:type="xs:ID">E21256</empnr>
        <first>Anil</first>
        <last>Singh</last>
        <deputy xsi:type="xs:IDREF">E30561</deputy>
      </employee>
      <employee xml:id="ID30561">
        <empnr xsi:type="xs:ID">E30561</empnr>
        <first>John</first>
        <last>Brown</last>
        <manager xsi:type="xs:IDREF">ID21256</manager>
      </employee>
    </employees>
  }
}
Expression:
$emp/(
  element-with-id('ID21256')/@xml:id => idref()
)/ancestor::employee/last
=> string()
Result:
"Brown"

(Assuming that manager has the is-idref property, the call on fn:idref selects the manager element. If, instead, the manager had a ref attribute with the is-idref property, the call on fn:idref would select the attribute node.)

Expression:
$emp/(
  element-with-id('E30561')/empnr => idref()
)/ancestor::employee/last
=> string()
Result:
"Singh"

(Assuming that employee/deputy has the is-idref property, the call on fn:idref selects the deputy element.)

13.5.4 fn:generate-id

Summary

This function returns a string that uniquely identifies a given node.

Signature
fn:generate-id(
$node as node()? := .
) as xs:string
Properties

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·.

Rules

If the argument is omitted, it defaults to the context value (.). The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

If the argument is the empty sequence, the result is the zero-length string.

In other cases, the function returns a string that uniquely identifies a given node. More formally, it is guaranteed that within a single ·execution scope·, fn:codepoint-equal(fn:generate-id($N), fn:generate-id($M)) returns true if and only if ($M is $N) returns true.

The returned identifier must consist of ASCII alphanumeric characters and must start with an alphabetic character. Thus, the string is syntactically an XML name.

Error Conditions

The following errors may be raised when $node is omitted:

Notes

An implementation is free to generate an identifier in any convenient way provided that it always generates the same identifier for the same node and that different identifiers are always generated from different nodes. An implementation is under no obligation to generate the same identifiers each time a document is transformed or queried.

There is no guarantee that a generated unique identifier will be distinct from any unique IDs specified in the source document.

There is no inverse to this function; it is not directly possible to find the node with a given generated ID. Of course, it is possible to search a given sequence of nodes using an expression such as $nodes[generate-id()=$id].

It is advisable, but not required, for implementations to generate IDs that are distinct even when compared using a case-blind collation.

Examples

The primary use case for this function is to generate hyperlinks. For example, when generating HTML, an anchor for a given section $sect can be generated by writing (in either XSLT or XQuery):

<a name="{ generate-id($sect) }"/>

and a link to that section can then be produced with code such as:

see <a href="#{ generate-id($sect) }">here</a>

Note that anchors generated in this way will not necessarily be the same each time a document is republished.

Since the keys in a map must be atomic items, it is possible to use generated IDs as surrogates for nodes when constructing a map. For example, in some implementations, testing whether a node $N is a member of a large node-set $S using the expression exists($N intersect $S) may be expensive; there may then be performance benefits in creating a map:

let $SMap := map:merge($S ! { generate-id(.) : . })

and then testing for membership of the node-set using:

map:contains($SMap, generate-id($N))

13.5.5 fn:element-number

Changes in 4.0  

  1. New in 4.0  [Issue 1427 PR 1430 24 September 2024]

Summary

Allocates a sequence number to an element within a containing tree.

Signature
fn:element-number(
$element as element()? := .,
$root as (document-node() | element())? := (),
$predicate as (fn(element()) as xs:boolean?)? := ()
) as xs:integer
Properties

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 two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.

The three-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns a non-negative integer reflecting the position of $element within the subtree rooted at $root.

More specifically, it returns the number of elements E that satisfy all three of the following conditions:

  1. E is a descendant-or-self of $root.

  2. E is either the same node as $element, or it precedes $element in document order.

  3. E satisfies the predicate supplied as $predicate.

If $element is omitted or empty, it defaults to the context node.

If $root is omitted or empty, it defaults to root($element) (that is, the document or element node at the root of the subtree containing $element).

If $predicate is omitted or empty, it defaults to a function that returns true if and only if its argument is an element having the same name as $element: that is, fn{node-name(.) eq node-name($element)}.

This means that if all arguments are omitted, the function returns 1 for the first element in the containing document that has a given name, 2 for the second such element, and so on.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression, except in error cases.

count($root/descendant-or-self::*[$predicate(.) and not(. >> $element)])
Error Conditions

The following errors may be raised when $element is omitted:

A dynamic error is raised [err:FORG0014] if the supplied $from node is not an ancestor-or-self of $element.

Notes

This function is intended to be used for generating sequence numbers for sections, paragraphs, footnotes, figures, or equations when rendering a structured document. It provides similar capability to the XSLT instruction xsl:number with level="any", but without any formatting of the returned number; formatting can be achieved using the format-integer function.

The motivation for providing this function is that calls to xsl:number are not possible in non-XSLT environments, and are inconvenient in some XSLT contexts, such as within a match pattern.

By default the function counts elements within the entire containing tree. To restart numbering within a subtree (for example, within a chapter of a larger document), the $root argument should be set to the root of that subtree.

By default the function counts all elements having the same name. The $predicate function can be used to modify this behavior. For example, if there is a single numbering sequence for diagram and image elements, $predicate can be set to fn{self::diagram or self::image}.

There is no requirement that $element itself must satisfy the $predicate function, though this will usually be the case. If $element does not satisfy $predicate, the result of the function may be zero.

The $root node, if it satisfies $predicate, will itself be counted. For example if $element is a section element and $root is a containing section, the result for the first contained section element will be 2.

The $predicate function can be used to restrict the elements that are counted according to their position in the tree. For example, if diagram elements occurring within a table are to be excluded, this can be achieved using by setting $predicate to the function fn{self::diagram and not(ancestor::table)}; or if the only elements to be counted are those that are immediate siblings of the element being numbered, this can be achieved with the function fn{self::diagram and .. is $element/..}.

Formatting of the resulting sequence numbers can be achieved by applying the function format-integer to the result: for example the items in a list can be given alphabetic labels (a, b, c ...) using element-number() => format-integer('a').

Unlike xsl:number, the element-number function considers only element nodes; other kinds of node cannot be given numbers, and are not counted when computing the result.

Examples
Variables
let $e := <doc>
  <section>
    <head>One</head>
    <p>First</p>
    <p>Second</p>
    <section>
       <head>OnePointOne</head>
       <p>Third</p>
       <p>Fourth</p>
       <equation>E = mc<sup>2</sup></equation>
    </section>
  </section>
  <appendix>
    <head>Glossary</head>
    <p>Fifth</p>
  </appendix>
</doc>
Expression:
let $n := $e//p[.='Fourth'] 
return element-number($n)
Result:
4

(Returns the number of the paragraph within the containing document.)

Expression:
let $n := $e//p[.='Fourth'] 
return element-number($n, $n/..)
Result:
2

(Returns the number of the paragraph within the containing section.)

Expression:
let $n := $e//appendix 
return element-number($n) => format-integer('A')
Result:
"A"

(Determines a number identifying the appendix within the containing document, and formats it using the numbering sequence "A", "B", "C", ...)

Expression:
let $n := $e//appendix 
return element-number(
          $n, 
          predicate:=fn{self::(section|appendix) and parent::doc}
       )
Result:
2

(Determines a number identifying the appendix, using a single consecutive numbering sequence for sections and appendices that have a doc element as their parent.)

Expression:
let $s := //section[head='OnePointOne']
return string-join(
         $s/ancestor-or-self::section ! element-number(),
         '.')
Result:
"1.1"

(Determines a hierarchic section number reflecting the position of a selected section element within a recursive hierarchy.)

13.6 Functions giving access to external information

The functions in this section provide access to resources (such as files) in the external environment.

Function Meaning
fn:doc Retrieves a document using a URI supplied as an xs:string, and returns the corresponding document node.
fn:doc-available The function returns true if and only if the function call fn:doc($source) would return a document node.
fn:collection Returns a sequence of items identified by a collection URI; or a default collection if no URI is supplied.
fn:uri-collection Returns a sequence of xs:anyURI values representing the URIs in a URI collection.
fn:unparsed-text The fn:unparsed-text function reads an external resource (for example, a file) and returns a string representation of the resource.
fn:unparsed-text-lines The fn:unparsed-text-lines function reads an external resource (for example, a file) and returns its contents as a sequence of strings, one for each line of text in the string representation of the resource.
fn:unparsed-text-available Allows an application to determine whether a call on fn:unparsed-text with particular arguments would succeed.
fn:environment-variable Returns the value of a system environment variable, if it exists.
fn:available-environment-variables Returns a list of environment variable names that are suitable for passing to fn:environment-variable, as a (possibly empty) sequence of strings.

13.6.1 fn:doc

Summary

Retrieves a document using a URI supplied as an xs:string, and returns the corresponding document node.

Signature
fn:doc(
$source as xs:string?
) as document-node()?
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on available documents, and static base URI.

Rules

If $source is the empty sequence, the result is an empty sequence.

If $source is a relative URI reference, it is resolved relative to the value of the static base URI property from the static context. The resulting absolute URI is promoted to an xs:string.

If the available documents described in Section 2.1.2 Dynamic Context XP31 provides a mapping from this string to a document node, the function returns that document node.

The URI may include a fragment identifier.

By default, this function is ·deterministic·. Two calls on this function return the same document node if the same URI Reference (after resolution to an absolute URI Reference) is supplied to both calls. Thus, the following expression (if it does not raise an error) will always return true:

doc("foo.xml") is doc("foo.xml")

Note:

This equivalence applies only because the two calls on the doc function have the same dynamic context. If two calls on doc have different dynamic contexts, then the mapping from URIs to document nodes in the two contexts may differ, which means that different document nodes may be returned for the same URI. This can happen, for example, if the two calls appear in different XSLT packages with different validation options or whitespace-stripping options; one call might produce a schema-validated document, the other an untyped document.

The requirement to deliver a deterministic result has performance implications, and for this reason implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is ·implementation-defined·. If the user has not selected such an option, a call of the function must either return a deterministic result or must raise a dynamic error [err:FODC0003].

Note:

If $source is read from a source document, it is generally appropriate to resolve it relative to the base URI property of the relevant node in the source document. This can be achieved by calling the fn:resolve-uri function, and passing the resulting absolute URI as an argument to the fn:doc function.

If two calls to this function supply different absolute URI References as arguments, the same document node may be returned if the implementation can determine that the two arguments refer to the same resource.

By defining the semantics of this function in terms of a string-to-document-node mapping in the dynamic context, the specification is acknowledging that the results of this function are outside the purview of the language specification itself, and depend entirely on the run-time environment in which the expression is evaluated. This run-time environment includes not only an unpredictable collection of resources (“the web”), but configurable machinery for locating resources and turning their contents into document nodes within the XPath data model. Both the set of resources that are reachable, and the mechanisms by which those resources are parsed and validated, are ·implementation-dependent·.

One possible processing model for this function is as follows. The resource identified by the URI Reference is retrieved. If the resource cannot be retrieved, a dynamic error is raised [err:FODC0002]. The data resulting from the retrieval action is then parsed as an XML document and a tree is constructed in accordance with the [XQuery and XPath Data Model (XDM) 3.0]. If the top-level media type is known and is "text", the content is parsed in the same way as if the media type were text/xml; otherwise, it is parsed in the same way as if the media type were application/xml. If the contents cannot be parsed successfully, a dynamic error is raised [err:FODC0002]. Otherwise, the result of the function is the document node at the root of the resulting tree. This tree is then optionally validated against a schema.

Various aspects of this processing are ·implementation-defined·. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:

  • The set of URI schemes that the implementation recognizes is implementation-defined. Implementations may allow the mapping of URIs to resources to be configured by the user, using mechanisms such as catalogs or user-written URI handlers.

  • The handling of non-XML media types is implementation-defined. Implementations may allow instances of the data model to be constructed from non-XML resources, under user control.

  • It is ·implementation-defined· whether DTD validation and/or schema validation is applied to the source document.

  • Implementations may provide user-defined error handling options that allow processing to continue following an error in retrieving a resource, or in parsing and validating its content. When errors have been handled in this way, the function may return either an empty sequence, or a fallback document provided by the error handler.

  • Implementations may provide user options that relax the requirement for the function to return deterministic results.

  • The effect of a fragment identifier in the supplied URI is ·implementation-defined·. One possible interpretation is to treat the fragment identifier as an ID attribute value, and to return a document node having the element with the selected ID value as its only child.

Error Conditions

A dynamic error may be raised [err:FODC0005] if $source is not a valid URI reference.

A dynamic error is raised [err:FODC0002] if a relative URI reference is supplied, and the base-URI property in the static context is absent.

A dynamic error is raised [err:FODC0002] if the available documents provides no mapping for the absolutized URI.

A dynamic error is raised [err:FODC0002] if the resource cannot be retrieved or cannot be parsed successfully as XML.

A dynamic error is raised [err:FODC0003] if the implementation is not able to guarantee that the result of the function will be deterministic, and the user has not indicated that an unstable result is acceptable.

13.6.2 fn:doc-available

Summary

The function returns true if and only if the function call fn:doc($source) would return a document node.

Signature
fn:doc-available(
$source as xs:string?
) as xs:boolean
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on available documents, and static base URI.

Rules

If $source is an empty sequence, this function returns false.

If a call on fn:doc($source) would return a document node, this function returns true.

In all other cases this function returns false. This includes the case where an invalid URI is supplied, and also the case where a valid relative URI reference is supplied, and cannot be resolved, for example because the static base URI is absent.

If this function returns true, then calling fn:doc($source) within the same ·execution scope· must return a document node. However, if nondeterministic processing has been selected for the fn:doc function, this guarantee is lost.

13.6.3 fn:collection

Summary

Returns a sequence of items identified by a collection URI; or a default collection if no URI is supplied.

Signature
fn:collection(
$source as xs:string? := ()
) as item()*
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on available collections, and static base URI.

Rules

This function takes an xs:string as argument and returns a sequence of items obtained by interpreting $source as an xs:anyURI and resolving it according to the mapping specified in available collections described in Section C.2 Dynamic Context Components XP31.

If available collections provides a mapping from this string to a sequence of items, the function returns that sequence. If available collections maps the string to an empty sequence, then the function returns an empty sequence.

If $source is not specified, the function returns the sequence of items in the default collection in the dynamic context. See Section C.2 Dynamic Context Components XP31.

If $source is a relative xs:anyURI, it is resolved against the value of the base-URI property from the static context.

If $source is the empty sequence, the function behaves as if it had been called without an argument. See above.

By default, this function is ·deterministic·. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is ·implementation-defined·. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error [err:FODC0003].

There is no requirement that any nodes in the result should be in document order, nor is there a requirement that the result should contain no duplicates.

Error Conditions

A dynamic error is raised [err:FODC0002] if no URI is supplied and the value of the default collection is absentDM40.

A dynamic error is raised [err:FODC0002] if a relative URI reference is supplied, and the base-URI property in the static context is absent.

A dynamic error is raised [err:FODC0002] if available node collections provides no mapping for the absolutized URI.

A dynamic error may be raised [err:FODC0004] if $source is not a valid xs:anyURI.

Notes

In earlier versions of this specification, the primary use for the fn:collection function was to retrieve a collection of XML documents, perhaps held as lexical XML in operating system filestore, or perhaps held in an XML database. In this release the concept has been generalised to allow other resources to be retrieved: for example JSON documents might be returned as arrays or maps, non-XML text files might be returned as strings, and binary files might be returned as instances of xs:base64Binary.

The abstract concept of a collection might be realized in different ways by different implementations, and the ways in which URIs map to collections can be equally variable. Specifying resources using URIs is useful because URIs are dynamic, can be parameterized, and do not rely on an external environment.

13.6.4 fn:uri-collection

Summary

Returns a sequence of xs:anyURI values representing the URIs in a URI collection.

Signature
fn:uri-collection(
$source as xs:string? := ()
) as xs:anyURI*
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on available URI collections, and static base URI.

Rules

The zero-argument form of the function returns the URIs in the default URI collection described in Section C.2 Dynamic Context Components XP31.

If $source is a relative xs:anyURI, it is resolved against the value of the base-URI property from the static context.

If $source is the empty sequence, the function behaves as if it had been called without an argument. See above.

The single-argument form of the function returns the sequence of URIs corresponding to the supplied URI in the available URI collections described in Section C.2 Dynamic Context Components XP31.

By default, this function is ·deterministic·. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is ·implementation-defined·. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error [err:FODC0003].

There is no requirement that the URIs returned by this function should all be distinct, and no assumptions can be made about the order of URIs in the sequence, unless the implementation defines otherwise.

Error Conditions

A dynamic error is raised [err:FODC0002] if no URI is supplied (that is, if the function is called with no arguments, or with a single argument that evaluates to an empty sequence), and the value of the default resource collection is absentDM40.

A dynamic error is raised [err:FODC0002] if a relative URI reference is supplied, and the base-URI property in the static context is absent.

A dynamic error is raised [err:FODC0002] if available resource collections provides no mapping for the absolutized URI.

A dynamic error may be raised [err:FODC0004] if $source is not a valid xs:anyURI.

Notes

In some implementations, there might be a close relationship between collections (as retrieved by the fn:collection function), and URI collections (as retrieved by this function). For example, a collection might return XML documents, and the corresponding URI collection might return the URIs of those documents. However, this specification does not impose such a close relationship. For example, there may be collection URIs accepted by one of the two functions and not by the other; a collection might contain items that do not have any URI; or a URI collection might contain URIs that cannot be dereferenced to return any resource.

Thus, some implementations might ensure that calling fn:uri-collection and then applying fn:doc to each of the returned URIs delivers the same result as calling fn:collection with the same argument; however, this is not guaranteed.

In the case where fn:uri-collection returns the URIs of resources that could also be retrieved directly using fn:collection, there are several reasons why it might be appropriate to use this function in preference to the fn:collection function. For example:

  • It allows different URIs for different kinds of resource to be dereferenced in different ways: for example, the returned URIs might be referenced using the fn:unparsed-text function rather than the fn:doc function.

  • In XSLT 3.0 it allows the documents in a collection to be processed in streaming mode using the xsl:stream instruction.

  • It allows recovery from failures to read, parse, or validate individual documents, by calling the fn:doc (or other dereferencing) function within the scope of try/catch.

  • It allows selection of which documents to read based on their URI, for example they can be filtered to select those whose URIs end in .xml, or those that use the https scheme.

  • An application might choose to limit the number of URIs processed in a single run, for example it might process only the first 50 URIs in the collection; or it might present the URIs to the user and allow the user to select which of them need to be further processed.

  • It allows the URIs to be modified before they are dereferenced, for example by adding or removing query parameters, or by redirecting the request to a local cache or to a mirror site.

For some of these use cases, this assumes that the cost of calling fn:collection might be significant (for example, it might involving retrieving all the documents in the collection over the network and parsing them). This will not necessarily be true of all implementations.

13.6.5 fn:unparsed-text

Changes in 4.0  

  1. The $options parameter has been added.  [Issue 1116 PR 1117 21 May 2024]

Summary

The fn:unparsed-text function reads an external resource (for example, a file) and returns a string representation of the resource.

Signature
fn:unparsed-text(
$source as xs:string?,
$options as (xs:string | map(*))? := ()
) as xs:string?
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.

Rules

The $source argument must be a string in the form of a URI reference, which must contain no fragment identifier, and must identify a resource for which a string representation is available. If the URI is a relative URI reference, then it is resolved relative to the static base URI property from the static context.

The $options argument, for backwards compatibility reasons, may be supplied either as a map, or as a string. Supplying a value $S that is not a map is equivalent to supplying the map map{"encoding":$S}. After that substitution, the ·option parameter conventions· apply.

The entries that may appear in the $options map are as follows:

record(
encoding? as xs:string?,
normalize-newlines? as xs:boolean
)
Key Value Meaning

encoding

Defines the encoding of the resource, as described below.
  • Type: xs:string?

  • Default: ()

normalize-newlines

Determines whether CR and CRLF character sequences are treated as equivalent to NL characters.
  • Type: xs:boolean

  • Default: false

false No normalization of line endings takes place.
true The character U+000D (CARRIAGE RETURN) and the character pair (U+000D (CARRIAGE RETURN) , U+000A (NEWLINE) ) are converted to the single character U+000A (NEWLINE) .

The mapping of URIs to the string representation of a resource is the mapping defined in the available text resourcesXP31 component of the dynamic context.

If the $source argument is an empty sequence, the function returns an empty sequence.

The encoding option, if present and non-empty, is the name of an encoding. The values for this option follow the same rules as for the encoding attribute in an XML declaration. The only values which every implementation is required to recognize are utf-8 and utf-16.

The encoding of the external resource is determined as follows:

  1. external encoding information is used if available, otherwise

  2. if the media type of the resource is text/xml or application/xml (see [RFC 2376]), or if it matches the conventions text/*+xml or application/*+xml (see [RFC 7303] and/or its successors), then the encoding is recognized as specified in [Extensible Markup Language (XML) 1.0 (Fifth Edition)], otherwise

  3. the encoding option is used if present, otherwise

  4. the processor may use ·implementation-defined· heuristics to determine the likely encoding, otherwise

  5. UTF-8 is assumed.

The result of the function is a string containing the string representation of the resource retrieved using the URI, decoded according to the specified encoding.

Error Conditions

A dynamic error is raised [err:FOUT1170] if the $source argument contains a fragment identifier, or if it cannot be resolved to an absolute URI (for example, because the base-URI property in the static context is absent), or if it cannot be used to retrieve the string representation of a resource.

A dynamic error is raised [err:FOUT1190] if the value of the encoding option is not a valid encoding name, if the processor does not support the specified encoding, if the string representation of the retrieved resource contains octets that cannot be decoded into Unicode ·characters· using the specified encoding, or if any resulting character is not a ·permitted character·.

A dynamic error is raised [err:FOUT1200] if the encoding option is absent and the processor cannot infer the encoding using external information and the actual encoding is not UTF-8.

Notes

If it is appropriate to use a base URI other than the dynamic base URI (for example, when resolving a relative URI reference read from a source document) then it is advisable to resolve the relative URI reference using the fn:resolve-uri function before passing it to the fn:unparsed-text function.

There is no essential relationship between the sets of URIs accepted by the two functions fn:unparsed-text and fn:doc (a URI accepted by one may or may not be accepted by the other), and if a URI is accepted by both there is no essential relationship between the results (different resource representations are permitted by the architecture of the web).

There are no constraints on the MIME type of the resource.

The fact that the resolution of URIs is defined by a mapping in the dynamic context means that in effect, various aspects of the behavior of this function are ·implementation-defined·. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:

  • The set of URI schemes that the implementation recognizes is implementation-defined. Implementations may allow the mapping of URIs to resources to be configured by the user, using mechanisms such as catalogs or user-written URI handlers.

  • The handling of media types is implementation-defined.

  • Implementations may provide user-defined error handling options that allow processing to continue following an error in retrieving a resource, or in reading its content. When errors have been handled in this way, the function may return a fallback document provided by the error handler.

  • For backwards compatibility reasons, implementations may provide configuration options that alter the default for the deterministic option.

The rules for determining the encoding are chosen for consistency with [XML Inclusions (XInclude) Version 1.0 (Second Edition)]. Files with an XML media type are treated specially because there are use cases for this function where the retrieved text is to be included as unparsed XML within a CDATA section of a containing document, and because processors are likely to be able to reuse the code that performs encoding detection for XML external entities.

If the text file contains characters such as < and &, these will typically be output as &lt; and &amp; if the string is serialized as XML or HTML. If these characters actually represent markup (for example, if the text file contains HTML), then an XSLT stylesheet can attempt to write them as markup to the output file using the disable-output-escaping attribute of the xsl:value-of instruction. Note, however, that XSLT implementations are not required to support this feature.

Examples

This XSLT example attempts to read a file containing “boilerplate” HTML and copy it directly to the serialized output file:

<xsl:output method="html"/>

<xsl:template match="/">
  <xsl:value-of select="unparsed-text('header.html', 'iso-8859-1')"
                disable-output-escaping="yes"/>
  <xsl:apply-templates/>
  <xsl:value-of select="unparsed-text('footer.html', 'iso-8859-1')"
                disable-output-escaping="yes"/>
</xsl:template>

13.6.6 fn:unparsed-text-lines

Changes in 4.0  

  1. The $options parameter has been added.  [Issues 1116 1278 PRs 1117 1279 21 May 2024]

Summary

The fn:unparsed-text-lines function reads an external resource (for example, a file) and returns its contents as a sequence of strings, one for each line of text in the string representation of the resource.

Signature
fn:unparsed-text-lines(
$source as xs:string?,
$options as (xs:string | map(*))? := ()
) as xs:string*
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.

Rules

The unparsed-text-lines function reads an external resource (for example, a file) and returns its string representation as a sequence of strings, separated at newline boundaries.

The $options argument, for backwards compatibility reasons, may be supplied either as a map, or as a string. Supplying a value $S that is not a map is equivalent to supplying the map map{"encoding":$S}. After that substitution, the ·option parameter conventions· apply.

The entries that may appear in the $options map are as follows:

record(
encoding? as xs:string?
)
Key Meaning

encoding

Defines the encoding of the resource, following the rules of fn:unparsed-text.
  • Type: xs:string?

  • Default: ()

The result of the function is the same as the result of the expression:

(fn:unparsed-text($source, map:put($options, 'normalize-newlines', true()))
   => fn:tokenize('\n'))
   [not(position()=last() and .='')]

The result is thus a sequence of strings containing the text of the resource retrieved using the URI, each string representing one line of text. Lines may be delimited by any of the character sequences U+000A (NEWLINE) , U+000D (CARRIAGE RETURN) , or U+000D (CARRIAGE RETURN) followed by U+000A (NEWLINE) . Line ending characters are not included in the returned strings. If there are two adjacent newline sequences, a zero-length string will be returned to represent the empty line; but if the external resource ends with a newline sequence, the result will be as if this final line ending were not present.

Error Conditions

Error conditions are the same as for the fn:unparsed-text function.

Notes

See the notes for fn:unparsed-text.

13.6.7 fn:unparsed-text-available

Changes in 4.0  

  1. The $options parameter has been added.  [Issue 1116 PR 1117 21 May 2024]

Summary

Allows an application to determine whether a call on fn:unparsed-text with particular arguments would succeed.

Signature
fn:unparsed-text-available(
$source as xs:string?,
$options as (xs:string | map(*))? := ()
) as xs:boolean
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.

Rules

The fn:unparsed-text-available function determines whether a call on the fn:unparsed-text function with identical arguments would return a string.

If the first argument is an empty sequence, the function returns false.

In other cases, the function returns true if a call on fn:unparsed-text or fn:unparsed-text-lines with the same arguments would succeed, and false if a call on fn:unparsed-text or fn:unparsed-text-lines with the same arguments would fail with a non-recoverable dynamic error.

The functions fn:unparsed-text and fn:unparsed-text-available have the same requirement for ·determinism· as the functions fn:doc and fn:doc-available. This means that unless the user has explicitly stated a requirement for a reduced level of determinism, either of these functions if called twice with the same arguments during the course of a transformation must return the same results each time; moreover, the results of a call on fn:unparsed-text-available must be consistent with the results of a subsequent call on unparsed-text with the same arguments.

Notes

This function was introduced before XQuery and XSLT allowed errors to be caught; with current versions of these host languages, catching an error from fn:unparsed-text may provide a better alternative.

The specification requires that the fn:unparsed-text-available function should actually attempt to read the resource identified by the URI, and check that it is correctly encoded and contains no characters that are invalid in XML. Implementations may avoid the cost of repeating these checks for example by caching the validated contents of the resource, to anticipate a subsequent call on the fn:unparsed-text or fn:unparsed-text-lines function. Alternatively, implementations may be able to rewrite an expression such as if (unparsed-text-available(A)) then unparsed-text(A) else ... to generate a single call internally.

Since the function fn:unparsed-text-lines succeeds or fails under exactly the same circumstances as fn:unparsed-text, the fn:unparsed-text-available function may equally be used to test whether a call on fn:unparsed-text-lines would succeed.

13.6.8 fn:environment-variable

Summary

Returns the value of a system environment variable, if it exists.

Signature
fn:environment-variable(
$name as xs:string
) as xs:string?
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on environment variables.

Rules

The set of available environment variablesXP31 is a set of (name, value) pairs forming part of the dynamic context, in which the name is unique within the set of pairs. The name and value are arbitrary strings.

If the $name argument matches the name of one of these pairs, the function returns the corresponding value.

If there is no environment variable with a matching name, the function returns the empty sequence.

The collation used for matching names is ·implementation-defined·, but must be the same as the collation used to ensure that the names of all environment variables are unique.

The function is ·deterministic·, which means that if it is called several times within the same ·execution scope·, with the same arguments, it must return the same result.

Notes

On many platforms, the term “environment variable” has a natural meaning in terms of facilities provided by the operating system. This interpretation of the concept does not exclude other interpretations, such as a mapping to a set of configuration parameters in a database system.

Environment variable names are usually case sensitive. Names are usually of the form (letter|_) (letter|_|digit)*, but this varies by platform.

On some platforms, there may sometimes be multiple environment variables with the same name; in this case, it is implementation-dependent as to which is returned; see for example [POSIX.1-2008] (Chapter 8, Environment Variables). Implementations may use prefixes or other naming conventions to disambiguate the names.

The requirement to ensure that the function is deterministic means in practice that the implementation must make a snapshot of the environment variables at some time during execution, and return values obtained from this snapshot, rather than using live values that are subject to change at any time.

Operating system environment variables may be associated with a particular process, while queries and stylesheets may execute across multiple processes (or multiple machines). In such circumstances implementations may choose to provide access to the environment variables associated with the process in which the query or stylesheet processing was initiated.

Security advice: Queries from untrusted sources should not be permitted unrestricted access to environment variables. For example, the name of the account under which the query is running may be useful information to a would-be intruder. An implementation may therefore choose to restrict access to the environment, or may provide a facility to make fn:environment-variable always return the empty sequence.

13.6.9 fn:available-environment-variables

Summary

Returns a list of environment variable names that are suitable for passing to fn:environment-variable, as a (possibly empty) sequence of strings.

Signature
fn:available-environment-variables() as xs:string*
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on environment variables.

Rules

The function returns a sequence of strings, being the names of the environment variables in the dynamic context in some ·implementation-dependent· order.

The function is ·deterministic·: that is, the set of available environment variables does not vary during evaluation.

Notes

The function returns a list of strings, containing no duplicates.

It is intended that the strings in this list should be suitable for passing to fn:environment-variable.

See also the note on security under the definition of the fn:environment-variable function. If access to environment variables has been disabled, fn:available-environment-variables always returns the empty sequence.

14 Parsing and serializing

These functions convert between the lexical representation and XPath and XQuery data model representation of various file formats.

14.1 Functions on XML Data

These functions convert between the lexical representation of XML and the tree representation.

(The fn:serialize function also handles HTML and JSON output, but is included in this section for editorial convenience.)

Function Meaning
fn:parse-xml This function takes as input an XML document represented as a string, and returns the document node at the root of an XDM tree representing the parsed document.
fn:parse-xml-fragment This function takes as input an XML external entity represented as a string, and returns the document node at the root of an XDM tree representing the parsed document fragment.
fn:serialize This function serializes the supplied input sequence $input as described in [XSLT and XQuery Serialization 3.1], returning the serialized representation of the sequence as a string.

14.1.1 fn:parse-xml

Changes in 4.0  

  1. The $options parameter has been added.  [Issue 305 PR 1257 11 June 2024]

  2. Additional error conditions have been defined.  [Issue 1287 PR 1288 25 June 2024]

Summary

This function takes as input an XML document represented as a string, and returns the document node at the root of an XDM tree representing the parsed document.

Signature
fn:parse-xml(
$value as xs:string?,
$options as map(*)? := {}
) as document-node(element(*))?
Properties

This function is ·nondeterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.

Rules

If $value is the empty sequence, the function returns the empty sequence.

The $options argument, if present and non-empty, defines the detailed behavior of the function. The ·option parameter conventions· apply. The options available are as follows:

record(
base-uri? as xs:anyURI,
dtd-validation? as xs:boolean,
strip-space? as xs:boolean,
xsd-validation? as xs:string
)
Key Value Meaning

base-uri

Determines the base URI. This is used both as the base URI used by the XML parser to resolve relative entity references within the document, and as the base URI of the document node that is returned. It defaults to the static base URI of the function call.
  • Type: xs:anyURI

  • Default: static-base-uri()

dtd-validation

Determines whether DTD validation takes place.
  • Type: xs:boolean

  • Default: false()

strip-space

Determines whether whitespace-only text nodes are removed from the resulting document.
  • Type: xs:boolean

  • Default: false()

true All whitespace-only text nodes are stripped, unless either (a) they are within the scope of the attribute xml:space="preserve", or (b) XSD validation identifies that the parent element has a simple type or a complex type with simple content.
false All whitespace-only text nodes are preserved, unless either (a) DTD validation marks them as ignorable, or (b) XSD validation recognizes the containing element as having element-only or empty content.

xsd-validation

Determines whether XSD validation takes place.
  • Type: xs:string

  • Default: "skip"

strict Strict XSD validation takes place
lax Lax XSD validation takes place
skip No XSD validation takes place
type Q{uri}local XSD validation takes place against the schema-defined type, present in the static context, that has the given URI and local name.

Except to the extent defined by these options, the precise process used to construct the XDM instance is ·implementation-defined·. In particular, it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used.

The document URI of the returned node is absentDM40.

The function is not ·deterministic·: that is, if the function is called twice with the same arguments, it is ·implementation-dependent· whether the same node is returned on both occasions.

Error Conditions

A dynamic error is raised [err:FODC0006] if the content of $value is not a well-formed and namespace-well-formed XML document.

A dynamic error is raised [err:FODC0007] if DTD validation is carried out and the content of $value is not valid against the relevant DTD.

A dynamic error is raised [err:FODC0008] if the value of the xsd-validation option is not one of the permitted values (for example, if the string that follows "type" is not a valid EQName, or if it does not identify a type that is present in the static context).

A dynamic error is raised [err:FODC0009] if the value of the xsd-validation option is set to anything other than skip when the processor is not schema-aware. (XSLT 4.0 and XQuery 4.0 define schema-awareness as an optional feature; other host languages may set their own rules.)

A dynamic error is raised [err:FODC0013] if DTD validation is requested and the processor does not have access to a validating XML parser.

A dynamic error is raised [err:FODC0014] if XSD validation is carried out and the content of $value is not valid against the relevant XSD schema.

Notes

Since the XML document is presented to the parser as a string, rather than as a sequence of octets, the encoding specified within the XML declaration has no meaning. If the XML parser accepts input only in the form of a sequence of octets, then the processor must ensure that the string is encoded as octets in a way that is consistent with rules used by the XML parser to detect the encoding.

A common use case for this function is to handle input documents that contain nested XML documents embedded within CDATA sections. Since the content of the CDATA section are exposed as text, the receiving query or stylesheet may pass this text to the fn:parse-xml function to create a tree representation of the nested document.

Similarly, nested XML within comments is sometimes encountered, and lexical XML is sometimes returned by extension functions, for example, functions that access web services or read from databases.

A use case arises in XSLT where there is a need to preprocess an input document before parsing. For example, an application might wish to edit the document to remove its DOCTYPE declaration. This can be done by reading the raw text using the fn:unparsed-text function, editing the resulting string, and then passing it to the fn:parse-xml function.

Examples

The expression fn:parse-xml("<alpha>abcd</alpha>") returns a newly created document node, having an alpha element as its only child; the alpha element in turn is the parent of a text node whose string value is "abcd".

The expression fn:parse-xml("<alpha><beta> </beta></alpha>", {"strip-space":true()}) returns a newly created document node, having an alpha element as its only child; the alpha element in turn is the parent of a beta element whose content is empty, as a result of whitespace stripping.

14.1.2 fn:parse-xml-fragment

Changes in 4.0  

  1. The $options parameter has been added.  [Issue 305 PR 1257 11 June 2024]

Summary

This function takes as input an XML external entity represented as a string, and returns the document node at the root of an XDM tree representing the parsed document fragment.

Signature
fn:parse-xml-fragment(
$value as xs:string?,
$options as map(*)? := {}
) as document-node()?
Properties

This function is ·nondeterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.

Rules

If $value is the empty sequence, the function returns the empty sequence.

The input must be a namespace-well-formed external general parsed entity. More specifically, it must be a string conforming to the production rule extParsedEntXML in [Extensible Markup Language (XML) 1.0 (Fifth Edition)], it must contain no entity references other than references to predefined entities, and it must satisfy all the rules of [Namespaces in XML] for namespace-well-formed documents with the exception that the rule requiring it to be a well-formed document is replaced by the rule requiring it to be a well-formed external general parsed entity.

The string is parsed to form a sequence of nodes which become children of the new document node, in the same way as the content of any element is converted into a sequence of children for the resulting element node.

The $options argument, if present and non-empty, defines the detailed behavior of the function. The ·option parameter conventions· apply. The options available are as follows:

record(
base-uri? as xs:anyURI,
strip-space? as xs:boolean
)
Key Value Meaning

base-uri

Determines the base URI. This is used as the base URI of the document node that is returned. It defaults to the static base URI of the function call.
  • Type: xs:anyURI

  • Default: static-base-uri()

strip-space

Determines whether whitespace-only text nodes are removed from the resulting document.
  • Type: xs:boolean

  • Default: false()

true All whitespace-only text nodes are stripped, unless they are within the scope of the attribute xml:space="preserve".
false All whitespace-only text nodes are preserved.

DTD validation is not invoked.

Schema validation is not invoked, which means that the nodes in the returned document will all be untyped.

Except as explicitly defined, the precise process used to construct the XDM instance is ·implementation-defined·. In particular, it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used.

The document URI of the returned node is absentDM40.

The function is not ·deterministic·: that is, if the function is called twice with the same arguments, it is ·implementation-dependent· whether the same node is returned on both occasions.

Error Conditions

A dynamic error is raised [err:FODC0006] if the content of $value is not a well-formed external general parsed entity, if it contains entity references other than references to predefined entities, or if a document that incorporates this well-formed parsed entity would not be namespace-well-formed.

Notes

See also the notes for the fn:parse-xml function.

The main differences between fn:parse-xml and fn:parse-xml-fragment are that for fn:parse-xml, the children of the resulting document node must contain exactly one element node and no text nodes, wheras for fn:parse-xml-fragment, the resulting document node can have any number (including zero) of element and text nodes among its children. An additional difference is that the text declaration at the start of an external entity has slightly different syntax from the XML declaration at the start of a well-formed document.

Note that all whitespace outside the text declaration is significant, including whitespace that precedes the first element node, unless the strip-space option is set.

One use case for this function is to handle XML fragments stored in databases, which frequently allow zero-or-more top level element nodes. Another use case is to parse the contents of a CDATA section embedded within another XML document.

Examples

The expression parse-xml-fragment("<alpha>abcd</alpha><beta>abcd</beta>") returns a newly created document node, having two elements named alpha and beta as its children; each of these elements in turn is the parent of a text node.

The expression parse-xml-fragment("He was <i>so</i> kind") returns a newly created document node having three children: a text node whose string value is "He was ", an element node named i having a child text node with string value "so", and a text node whose string value is " kind".

The expression parse-xml-fragment("") returns a document node having no children.

The expression parse-xml-fragment(" ") returns a document node whose children comprise a single text node whose string value is a single space.

The expression parse-xml-fragment(" ", {"strip-space":true()}) returns a document node having no children.

The expression parse-xml-fragment('<?xml version="1.0" encoding="utf8" standalone="yes"?><a/>') results in a dynamic error [err:FODC0006] because the standalone keyword is not permitted in the text declaration that appears at the start of an external general parsed entity. (Thus, it is not the case that any input accepted by the fn:parse-xml function will also be accepted by fn:parse-xml-fragment.)

14.1.3 fn:serialize

Summary

This function serializes the supplied input sequence $input as described in [XSLT and XQuery Serialization 3.1], returning the serialized representation of the sequence as a string.

Signature
fn:serialize(
$input as item()*,
$options as (element(output:serialization-parameters) | map(*))? := ()
) as xs:string
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The value of the first argument $input acts as the input sequence to the serialization process, which starts with sequence normalization.

The second argument $options, if present, provides serialization parameters. These may be supplied in either of two forms:

  1. As an output:serialization-parameters element, having the format described in Section 3.1 Setting Serialization Parameters by Means of a Data Model Instance SER31. In this case the type of the supplied argument must match the required type element(output:serialization-parameters).

  2. As a map. In this case the type of the supplied argument must match the required type map(*)

The single-argument version of this function has the same effect as the two-argument version called with $options set to an empty sequence. This in turn is the same as the effect of passing an output:serialization-parameters element with no child elements.

The final stage of serialization, that is, encoding, is skipped. If the serializer does not allow this phase to be skipped, then the sequence of octets returned by the serializer is decoded into a string by reversing the character encoding performed in the final stage.

If the second argument is omitted, or is supplied in the form of an output:serialization-parameters element, then the values of any serialization parameters that are not explicitly specified is ·implementation-defined·, and may depend on the context.

If the second argument is supplied as a map, then the ·option parameter conventions· apply. In this case:

  1. Each entry in the map defines one serialization parameter.

  2. The key of the entry is an xs:string value in the cases of parameter names defined in these specifications, or an xs:QName (with non-absent namespace) in the case of implementation-defined serialization parameters.

  3. The required type of each parameter, and its default value, are defined by the following table. The default value is used when the map contains no entry for the parameter in question, and also when an entry is present, with the empty sequence as its value. The table also indicates how the value of the map entry is to be interpreted in cases where further explanation is needed.

Parameter Required type Interpretation Default Value
allow-duplicate-names xs:boolean? true() means "yes", false() means "no" no
byte-order-mark xs:boolean? true() means "yes", false() means "no" no
cdata-section-elements xs:QName* ()
doctype-public xs:string? Zero-length string and () both represent "absent" absent
doctype-system xs:string? Zero-length string and () both represent "absent" absent
encoding xs:string? utf-8
escape-solidus xs:boolean? true() means "yes", false() means "no" yes
escape-uri-attributes xs:boolean? true() means "yes", false() means "no" yes
html-version xs:decimal? 5
include-content-type xs:boolean? true() means "yes", false() means "no" yes
indent xs:boolean? true() means "yes", false() means "no" no
item-delimiter xs:string? absent
json-node-output-method (xs:string | xs:QName)? See Notes 1, 2 xml
media-type xs:string? (a media type suitable for the chosen method)
method (xs:string | xs:QName)? See Notes 1, 2 xml
normalization-form xs:string? none
omit-xml-declaration xs:boolean? true() means "yes", false() means "no" yes
standalone xs:boolean? true() means "yes", false() means "no", () means "omit" omit
suppress-indentation xs:QName* ()
undeclare-prefixes xs:boolean? true() means "yes", false() means "no" no
use-character-maps map(xs:string, xs:string)? See Note 3 {}
version xs:string? 1.0

Notes to the table:

  1. The notation (A | B) represents a union type whose member types are A and B.

  2. If an xs:QName is supplied for the method or json-node-output-method options, then it must have a non-absent namespace URI. This means that system-defined serialization methods such as xml and json are defined as strings, not as xs:QName values.

  3. For the use-character-maps option, the value is a map, whose keys are the characters to be mapped (as xs:string instances), and whose corresponding values are the strings to be substituted for these characters.

Error Conditions

A type error [err:XPTY0004]XP occurs if the $options argument is present and does not match either of the types element(output:serialization-parameters)? or map(*).

Note:

This is defined as a type error so that it can be enforced via the function signature by implementations that generalize the type system in a suitable way.

If the host language makes serialization an optional feature and the implementation does not support serialization, then a dynamic error [err:FODC0010] is raised.

When the second argument is supplied as a map, and the supplied value is of the wrong type for the particular parameter, for example if the value of indent is a string rather than a boolean, then as defined by the ·option parameter conventions·, a type error [err:XPTY0004]XP is raised. If the value is of the correct type, but does not satisfy the rules for that parameter defined in [XSLT and XQuery Serialization 3.1], then a dynamic error [err:SEPM0016]SER31 is raised. (For example, this occurs if the map supplied to use-character-maps includes a key that is a string whose length is not one (1)).

If any serialization error occurs, including the detection of an invalid value for a serialization parameter as described above, this results in the fn:serialize call failing with a dynamic error.

Notes

One use case for this function arises when there is a need to construct an XML document containing nested XML documents within a CDATA section (or on occasions within a comment). See fn:parse-xml for further details.

Another use case arises when there is a need to call an extension function that expects a lexical XML document as input.

Another use case for this function is serializing instances of the data model into a human readable format for the purposes of debugging. Using the Section 10 Adaptive Output Method SER31 by specifying it as the output method defined in the second argument via output:serialization-parameters, allows for serializing any valid XDM instance without raising a serialization error.

There are also use cases where the application wants to post-process the output of a query or transformation, for example by adding an internal DTD subset, or by inserting proprietary markup delimiters such as the <% ... %> used by some templating languages.

The ability to specify the serialization parameters in an output:serialization-parameters element provides backwards compatibility with the 3.0 version of this specification; the ability to use a map takes advantage of new features in the 3.1 version. The default parameter values are implementation-defined when an output:serialization-parameters element is used (or when the argument is omitted), but are fixed by this specification in the case where a map (including an empty map) is supplied for the argument.

Examples
Variables
let $params := <output:serialization-parameters 
    xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization">
  <output:omit-xml-declaration value="yes"/>
</output:serialization-parameters>
let $data := <a b="3"/>

Given the variables:

The following call might produce the output shown:

Expression:

serialize($data, $params)

Result:
'<a b="3"/>'

The following call would also produce the output shown (though the second argument could equally well be supplied as an empty map ({}), since both parameters are given their default values):

Expression:
serialize(
  $data,
  { "method": "xml", "omit-xml-declaration": true() }
)
Result:
'<a b="3"/>'
Expression:

serialize({ "a": "AB", "b": "BC" }, { "method": "adaptive" })

Result:
'{"a":"AB","b":"BC"}'
Expression:
serialize(
  array { "a", 3, attribute test { "true" } },
  { "method": "adaptive" 
})
Result:
'["a",3,test="true"]'

14.2 Functions on HTML Data

Changes in 4.0  

  1. A new function is available for processing input data in HTML format.

These functions convert between the lexical representation of HTML and the tree representation.

Function Meaning
fn:parse-html This function takes as input an HTML document represented as a string, and returns the document node at the root of an XDM tree representing the parsed document.

14.2.1 XDM Mapping from HTML DOM Nodes

The fn:parse-html function conceptually works in two phases:

  1. The lexical HTML (supplied as a string) is parsed into an HTML DOM as defined by the HTML5 specification: see [HTML: Living Standard] and [DOM: Living Standard].

  2. The resulting DOM is converted to an XDM tree as described in this section. This is described by defining the actions of the accessor functions defined in Section 4 AccessorsDM40.

Note:

Because the [DOM: Living Standard] and [HTML: Living Standard] are not fixed, it is ·implementation-defined· which versions are used.

An implementation must match the semantics of the mapping described in this section, but the specific way it achieves that is ·implementation-dependent·.

Note:

Some possible implementation strategies are:

  1. Parse the HTML to an HTML DOM and then convert the HTML DOM to an XDM node tree.

  2. Parse the HTML to an HTML DOM and then implement a wrapper or facade that presents an XDM interface to the HTML DOM.

  3. Parse the lexical HTML directly to an XDM node tree, bypassing the HTML DOM.

The [DOM: Living Standard] defines parsing algorithms for two different formats, which it refers to as the HTML and XML serializations. The XML serialization is an XML document which typically uses the namespace http://www.w3.org/1999/xhtml and the content type application/xhtml+xml, and is popularly referred to as XHTML. The HTML parsing algorithm constructs an HTML DOM HTMLDocument document object for the HTML document. The XHTML parsing algorithm constructs an HTML DOM XMLDocument object for the HTML document, following XML parsing rules. This mapping supports both of these document types.

The [DOM: Living Standard] specification defines HTML DOM nodes that are mapped to XDM nodes as follows:

  1. The HTML DOM Document interface maps to Section 5.1 Document nodesDM40.

  2. The HTML DOM Element interface maps to Section 5.2 Element nodesDM40.

  3. The HTML DOM Attr interface maps to Section 5.3 Attribute nodesDM40.

    Note:

    Any HTML DOM Attr instances in an HTML DOM HTMLDocument that represent namespace declarations will have been filtered out: see 14.2.1.1 attributes Accessor.

  4. The HTML DOM ProcessingInstruction interface maps to Section 5.5 Processing instruction nodesDM40.

    Note:

    The HTML parsing algorithm does not generate processing instruction nodes. If encountered they are parsed as comment nodes. The HTML DOM ProcessingInstruction interface is relevant only when the XHTML parsing algorithm is used.

  5. The HTML DOM Comment interface maps to Section 5.6 Comment nodesDM40.

  6. The HTML DOM Text interface maps to Section 5.7 Text nodesDM40. Adjacent HTML DOM Text nodes are combined into a single Section 5.7 Text nodesDM40.

    Note:

    The HTML DOM CDATASection interface is an instance of HTML DOM Text, so CDATA sections also map to Section 5.7 Text nodesDM40.

    The use of CDATA sections can result in the HTML DOM containing adjacent text nodes, which the mapping to XDM will merge into a single node.

Note:

The HTML DOM DocumentFragment interface is not supported as an XML node. There are two places in the HTML DOM where this is used:

  1. The HTML DOM ShadowRoot interface is not present in the main HTML DOM tree. It is only accessible via JavaScript.

  2. The template element’s content property contains the child nodes of the template element. The behaviour of this is defined by the include-template-content key in the 14.2.2 HTML parser options map.

If an implementation allows these nodes to be passed in via an API or similar mechanism, their behaviour is ·implementation-defined·.

14.2.1.1 attributes Accessor

The result of the Section 4.1 attributes AccessorDM40 dm:attributes($node) for an HTML DOM Node is as follows:

  1. If the node is an instance of HTML DOM Element then the result is the value of the Element.attributes property mapped to a sequence as described below;

  2. Otherwise, the result is an empty sequence.

An HTML DOM NamedNodeMap is mapped to a sequence as follows:

  1. NamedNodeMap.length is the length of the sequence, where a length of 0 results in an empty sequence;

  2. NamedNodeMap.item(n) is the nth element of the sequence.

That sequence is then filtered as follows:

  1. If the Attr.namespaceURI property is "http://www.w3.org/2000/xmlns/", the attribute is not included in this sequence;

  2. If the Attr.localName property is "xmlns", the attribute is not included in this sequence;

  3. If the Attr.localName property starts with "xmlns:", the attribute is not included in this sequence;

  4. Otherwise, the attribute is included in this sequence using the XDM mapping rules described in this section.

Note:

The HTML DOM Element.attributes property includes namespace and non-namespace attributes in the list when the HTML or XML parser is used. As such, the namespace attributes have to be filtered from the resulting XDM attribute sequence.

Note:

When the resulting document is an HTML DOM HTMLDocument, the Attr.localName and Attr.name properties of HTML DOM Attr nodes are both set to the qualified name. This includes namespace declarations which are filtered out by the logic in this section.

Note:

The Attr.localName property will be ASCII lowercase. The [HTML: Living Standard] section 13.2.5.33, Attribute name state specifies that ASCII upper alpha characters are appended to the attribute’s name in lowercase.

14.2.1.2 base-uri Accessor

The result of the Section 4.2 base-uri AccessorDM40 dm:base-uri($node) for an HTML DOM Node is the value of the Node.baseURI property mapped as follows:

  1. If the value is null or an empty string, then the result is an empty sequence;

  2. Otherwise, the string value is cast to an xs:anyURI.

14.2.1.3 children Accessor

The result of the Section 4.3 children AccessorDM40 dm:children($node) for an HTML DOM Node is as follows:

  1. If the node is an instance of HTML DOM Document then the result is the value of the Node.childNodes property mapped to a sequence;

  2. If the node is an instance of HTML DOM HTMLTemplateElement then the result is determined as follows:

    1. If the include-template-content key of the parse-html-options map is false(), the result is an empty sequence;

    2. Select the HTML DOM DocumentFragment from the HTMLTemplateElement.content property;

    3. The HTML DOM DocumentFragment’s Node.childNodes property is mapped to a sequence;

  3. If the node is an instance of HTML DOM Element then the result the value of the Node.childNodes property mapped to a sequence;

  4. Otherwise, the result is an empty sequence.

An HTML DOM NodeList is mapped to a sequence as follows:

  1. NodeList.length is the length of the sequence, where a length of 0 results in an empty sequence;

  2. NodeList.item(n) is the nth element of the sequence.

That sequence is then filtered as follows:

  1. If the child is an instance of HTML DOM DocumentType, that child is not included in this sequence;

  2. A sequence of consecutive HTML DOM Text nodes is combined into a single XDM text node;

  3. Otherwise, the HTML DOM Node nodes are mapped to XDM according to the rules in this section.

14.2.1.4 document-uri Accessor

The result of the Section 4.4 document-uri AccessorDM40 dm:document-uri($node) for an HTML DOM Node is as follows:

  1. If the node is an instance of HTML DOM Document then the value of the Document.documentURI property mapped as follows:

    1. If the value is null or an empty string, then the result is an empty sequence;

    2. Otherwise, the string value is cast to an xs:anyURI.

  2. Otherwise, the result is an empty sequence.

14.2.1.5 is-id Accessor

The result of the Section 4.5 is-id AccessorDM40 dm:is-id($node) for an HTML DOM Node is as follows:

  1. If the node is an instance of HTML DOM Attr then:

    1. If the Attr.name property (its qualified name) is "id", then:

      1. If the Attr.value is castable to an xs:NCName, the result is true;

      2. Otherwise, the result is false;

    2. Otherwise, the result is false;

  2. Otherwise, the result is false.

Note:

In [HTML: Living Standard] section 3.2.5, Global attributes, the id attribute is defined as being unique in the element’s tree, containing at least one character, and not having any ASCII whitespace characters. This means that an HTML id attribute may not conform to an xs:NCName.

If an HTML id is not a valid xs:NCName then that attribute is not an XML ID.

14.2.1.6 is-idrefs Accessor

The result of the Section 4.6 is-idrefs AccessorDM40 dm:is-idrefs($node) for an HTML DOM Node is an empty sequence.

14.2.1.7 namespace-nodes Accessor

The result of the Section 4.7 namespace-nodes AccessorDM40 dm:namespace-nodes($node) for an HTML DOM Node is as follows:

  1. If the node is an instance of HTML DOM Element then an ·implementation-dependent· sequence of namespace nodes that is sufficient to define the namespace context of the node.

  2. Otherwise, the result is the empty sequence.

For the XHTML parsing algorithm, this will be equivalent to constructing the namespace nodes from an XML infoset, PSVI, or similar mapping.

For the HTML parsing algorithm, the [HTML: Living Standard] specification defines the namespace context in various places:

  1. Section 2.1.3 XML compatibility defines the default element namespace to be http://www.w3.org/1999/xhtml.

  2. Section 4.8.15 MathML defines rules for embedded MathML content in HTML documents. Section 13.1.2 Elements defines these elements as foreign elements, placing them in the MathML namespace (http://www.w3.org/1998/Math/MathML). The default element namespace for these elements is the MathML namespace.

  3. Section 4.8.16 SVG defines rules for embedded SVG content in HTML documents. Section 13.1.2 Elements defines these elements as foreign elements, placing them in the SVG namespace (http://www.w3.org/2000/svg). The default element namespace for these elements is the SVG namespace.

  4. Section 13.1.2.3 Attributes defines several namespaced attributes available on foreign elements. If any of these namespaced attributes are present, a namespace node for that namespace must be present on the element.

    The supported namespace prefixes are:

    1. xlink in the http://www.w3.org/1999/xlink namespace;

    2. xml in the http://www.w3.org/XML/1998/namespace namespace; and

    3. xmlns in the http://www.w3.org/2000/xmlns/ namespace.

No other namespaces are supported by the HTML parser.

Note:

Section number references to [HTML: Living Standard] may change over time.

14.2.1.8 nilled Accessor

The result of the Section 4.8 nilled AccessorDM40 dm:nilled($node) for an HTML DOM Node is false().

14.2.1.9 node-kind Accessor

The result of the Section 4.9 node-kind AccessorDM40 dm:node-kind($node) for an HTML DOM Node is as follows:

  1. If the node is an instance of HTML DOM Document then the result is "document".

  2. If the node is an instance of HTML DOM Element then the result is "element".

  3. If the node is an instance of HTML DOM Attr then the result is "attribute".

  4. If the node is an instance of HTML DOM ProcessingInstruction then the result is "processing-instruction".

  5. If the node is an instance of HTML DOM Comment then the result is "comment".

  6. If the node is an instance of HTML DOM Text then the result is "text".

14.2.1.10 node-name Accessor

The result of the Section 4.10 node-name AccessorDM40 dm:node-name($node) for an HTML DOM Node is as follows:

  1. If the node is an instance of HTML DOM Element then the result is determined as follows:

    1. The local name is the value of the Element.localName property. This is derived as follows:

      1. The local name is initially set to the ASCII lowercase tag name. The [HTML: Living Standard] section 13.2.5.8, Tag name state specifies that ASCII upper alpha characters are appended to the element’s name in lowercase.

      2. If the local name is an SVG element name, the case-sensitive name is used. [HTML: Living Standard] section 13.2.6.5, The rules for parsing tokens in foreign content has a table mapping the lowercase element names to their SVG names.

      3. If the local name contains a character that is not a valid XML NameStartChar or NameChar, then an ·implementation-defined· replacement string is used. The result must be a valid NCName.

        Note:

        [DOM: Living Standard] section 13.2.9 Coercing an HTML DOM into an infoset uses a Unnnnnn escape sequence. That would map : to U00003A.

        This local name escaping applies only to the HTML parsing algorithm. If the XHTML parsing algorithm is used, the localName and prefix will be correctly set for QName-based node names.

    2. The namespace prefix is the value of the Element.prefix property, or empty if the value is null;

    3. The namespace URI is the value of the Element.namespaceURI property, or empty if the value is null.

      1. If the element is an HTML element, the namespace URI is "http://www.w3.org/1999/xhtml".

      2. If the element is an SVG element, the namespace URI is "http://www.w3.org/2000/svg".

      3. If the element is a MathML element, the namespace URI is "http://www.w3.org/1998/Math/MathML".

  2. If the node is an instance of HTML DOM Attr then the result is determined as follows:

    1. The attribute name is the tokenized attribute name. The [HTML: Living Standard] section 13.2.5.33, Attribute name state specifies that ASCII upper alpha characters are appended to the attribute’s name in lowercase.

    2. The local name is the value of the Attr.localName property. This is derived as follows:

      1. The local name is initially set to the attribute name.

      2. If the local name is an SVG or MathML attribute name, the case-sensitive name is used. [HTML: Living Standard] section 13.2.6.1, Creating and inserting nodes has a table mapping the lowercase attribute names to their SVG/MathML names.

      3. If the local name is an allowed xlink, xml, or xmlns attribute name the local name is the value of the local name column of the attribute name mapping table in [HTML: Living Standard] section 13.2.6.1, Creating and inserting nodes.

      4. If the local name contains a character that is not a valid XML NameStartChar or NameChar, then an ·implementation-defined· replacement string is used. The result must be a valid NCName.

        Note:

        [DOM: Living Standard] section 13.2.9 Coercing an HTML DOM into an infoset uses a Unnnnnn escape sequence. That would map : to U00003A.

        This local name escaping applies only to the HTML parsing algorithm. If the XHTML parsing algorithm is used, the localName and prefix will be correctly set for QName-based node names.

    3. The namespace prefix is the value of the Attr.prefix property, or empty if the value is null.

      1. If the attribute name is an allowed xlink, xml, or xmlns attribute name the namespace prefix is the value of the prefix column of the attribute name mapping table in [HTML: Living Standard] section 13.2.6.1, Creating and inserting nodes.

    4. The namespace URI is the value of the Attr.namespaceURI property, or empty if the value is null;

      1. If the attribute name is an allowed xlink, xml, or xmlns attribute name the namespace URI is the value of the namespace column of the attribute name mapping table in [HTML: Living Standard] section 13.2.6.1, Creating and inserting nodes.

  3. If the node is an instance of HTML DOM ProcessingInstruction then the result is an xs:QName constructed as follows:

    1. The local name is the value of the ProcessingInstruction.target property;

    2. The namespace prefix is empty;

    3. The namespace URI is empty;

  4. Otherwise, the result is an empty sequence.

Note:

When the resulting document is an HTML DOM HTMLDocument, the Element.localName and Element.name properties of HTML DOM Element nodes are both set to the qualified name.

Note:

When the resulting document is an HTML DOM HTMLDocument, the Attr.localName and Attr.name properties of HTML DOM Attr nodes are both set to the qualified name.

14.2.1.11 parent Accessor

The result of the Section 4.11 parent AccessorDM40 dm:parent($node) for an HTML DOM Node is as follows:

  1. Let $parent be the Node.parentNode property of the node;

  2. If $parent is an instance of HTML DOM DocumentFragment, then for each HTML DOM HTMLTemplateElement $template in the parsed DOM tree:

    1. Let $content be the value of the HTMLTemplateElement.content property of $template;

    2. If $content is the same node as $parent, then the result is $template using the XDM mapping rules described in this section;

    3. If there are no more $template nodes, then the result is an empty sequence;

  3. If $parent is null, then the result is an empty sequence;

  4. Otherwise, the result is $parent using the XDM mapping rules described in this section.

Note:

The current node can have a HTML DOM DocumentFragment parent node only if the include-template-content key of the html-parser-options is true().

Note:

The HTML DOM DocumentFragment’s Node.parentNode property is null, and a DocumentFragment attached to HTMLTemplateElement.content property does not have a host property connecting the fragment back to the template element.

If a future version of [DOM: Living Standard] adds a DocumentFragment.host property that references the node’s template element, or the implementation has access to that internal property, the implementation may choose to use that instead of traversing the parsed HTML tree.

14.2.1.12 string-value Accessor

The result of the Section 4.12 string-value AccessorDM40 dm:string-value($node) for an HTML DOM Node is as follows:

  1. If the node is an instance of HTML DOM Document, then use the algorithm described in 14.2.1.12.1 Tree string construction;

  2. If the node is an instance of HTML DOM Element, then use the algorithm described in 14.2.1.12.1 Tree string construction;

  3. If the node is an instance of HTML DOM Text, then use the algorithm described in 14.2.1.12.2 Text node string construction;

  4. Otherwise, the result is the value of the Node.nodeValue property.

14.2.1.12.1 Tree string construction

The following algorithm is used to construct the concatenated string value of a node in the HTML DOM tree:

  1. Let $text be the string value "";

  2. For each descendant node $node in document order:

    1. If $node is not an instance of HTML DOM Text, process the next node in document order;

    2. Append the value of the Node.nodeValue property for $node to $text;

  3. The result is $text.

14.2.1.12.2 Text node string construction

The following algorithm is used to construct the maximal sequence of adjacent character information items for text node children of an element:

  1. Let $text be the string value "";

  2. Append the value of the Node.nodeValue property for $node to $text;

  3. Let $next be the value of Node.nextSibling;

  4. Let $next is null, or not an instance of HTML DOM Text, the result is $text;

  5. Otherwise, repeat from step 2 using $next as $node.

Note:

Adjacent text nodes in the HTML DOM are treated as a single XDM text node by only including the first text node and providing logic to ensure that the text content is merged into a single text block.

14.2.1.13 type-name Accessor

The result of the Section 4.13 type-name AccessorDM40 dm:type-name($node) for an HTML DOM Node is as follows:

  1. If the node is an instance of HTML DOM Element then the result is xs:untyped.

  2. If the node is an instance of HTML DOM Attr then the result is xs:untypedAtomic.

  3. If the node is an instance of HTML DOM Text then the result is xs:untypedAtomic.

  4. Otherwise, the result is an empty sequence.

14.2.1.14 typed-value Accessor

The result of the Section 4.14 typed-value AccessorDM40 dm:typed-value($node) for an HTML DOM Node is as follows:

  1. Let $string-value be the 14.2.1.12 string-value Accessor for the node;

  2. If the node is an instance of HTML DOM Document then the result is $string-value as an xs:untypedAtomic;

  3. If the node is an instance of HTML DOM Element then the result is $string-value as an xs:untypedAtomic;

  4. If the node is an instance of HTML DOM Attr then the result is $string-value as an xs:untypedAtomic;

  5. If the node is an instance of HTML DOM Text then the result is $string-value as an xs:untypedAtomic;

  6. Otherwise, the result is $string-value.

14.2.1.15 unparsed-entity-public-id Accessor

The result of the Section 4.15 unparsed-entity-public-id AccessorDM40 dm:unparsed-entity-public-id($node) for an HTML DOM Node is an empty sequence.

14.2.1.16 unparsed-entity-system-id Accessor

The result of the Section 4.16 unparsed-entity-system-id AccessorDM40 dm:unparsed-entity-system-id($node) for an HTML DOM Node is an empty sequence.

14.2.2 HTML parser options

This section describes the record structure used to pass options to the fn:parse-html function.

Additional ·implementation-defined· parser options are allowed.

Example:

An implementation may provide keys for options to the tidy HTML parser, allowing a user to configure the behaviour of that parser.

14.2.3 fn:parse-html

Changes in 4.0  

  1. New in 4.0  [Issue 850 PR 956 10 January 2023]

Summary

This function takes as input an HTML document represented as a string, and returns the document node at the root of an XDM tree representing the parsed document.

Signature
fn:parse-html(
$html as (xs:string | xs:hexBinary | xs:base64Binary)?,
$options as map(*) := { "method": "html", "html-version": 5 }
) as document-node(element(*:html))?
Properties

This function is ·nondeterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $html is the empty sequence the function returns the empty sequence.

The entries that may appear in the $options map are as follows:

record(
method? as xs:string,
html-version? as (enum('LS') | xs:decimal),
encoding? as xs:string?,
include-template-content? as xs:boolean?
)
Key Meaning

method

The approach used to parse the HTML document into XDM nodes.

Note:

An implementation may use this to specify a specific algorithm, tool, or library that is used, such as tidy or tagsoup.

An implementation may also use this to specify a non-standard variant of HTML to support, such as word for the Microsoft Word HTML variant.

  • Type: xs:string

html-version

The version of HTML to support when parsing HTML strings or sequences of octets.

Valid values an implementation must support for the html method are:

  1. 3, 3.2 for HTML 3.2 W3C Recommendation, 14 January 1997

  2. 4, 4.01 for HTML 4.01 W3C Recommendation, 24 December 1999

  3. 5.0 for HTML5 W3C Recommendation, 28 October 2014

  4. 5.1 for HTML 5.1 W3C Recommendation, 1 November 2016

  5. 5.2 for HTML 5.2 W3C Recommendation, 14 December 2017

  6. LS for HTML Living Standard, WHATWG

  7. 5 may be equivalent to any of 5.0, 5.1, 5.2, or LS

Valid values an implementation must support for the xhtml method are:

  1. 1.0 for XHTML 1.0 W3C Recommendation, 26 January 2000

  2. 1.1 for XHTML 1.1 W3C Recommendation, 31 May 2001

Any other method and html-version combinations are ·implementation-defined·.

  • Type: (enum('LS') | xs:decimal)

encoding

The character encoding to use to decode a sequence of octets that represents an HTML document.

  • Type: xs:string?

include-template-content

Defines how to handle elements in the HTMLTemplateElement.content property.

If this option is true, the template element’s children are the children of the content property’s document fragment node.

If this option is false, the template element’s children are the empty sequence.

The default behaviour is ·implementation-defined·.

Note:

This allows an implementation to support the behaviour defined in [HTML: Living Standard] section 4.12.3.1, Interaction of template elements with XSLT and XPath:

  1. This option would default to true for an XSLT processor operating on an HTML DOM constructed from an XHTML document.

  2. This option would default to false for an XPath processor using the [DOM: Living Standard] section 8, XPath APIs.

  • Type: xs:boolean?

If $html is not the empty sequence, an input byte stream is constructed as follows:

  1. If $html is an xs:string, the encoding of the input byte stream is determined in a way consistent with [HTML: Living Standard] section 13.2.3.1, Parsing with a known character encoding to generate the bytes for that string. The specific character encoding is the ·implementation-dependent· encoding corresponding to the implementation's string representation.

  2. If the type of $html is a sequence of octets (xs:hexBinary or xs:base64Binary) the encoding of the input byte stream is determined in a way consistent with [HTML: Living Standard] section 13.2.3.2, Determining the character encoding:

    1. The encoding key of $options is used in step 2 of Determining the character encoding as the user instructing the user agent to override the document’s character encoding with the specified encoding.

    2. If the encoding key of $options is not specified, step 2 of Determining the character encoding is skipped.

The resulting byte stream is then used to construct an XDM representation of the HTML document in a way that is equivalent to:

  1. Tokenizing the byte stream according to the HTML parsing algorithm determined by the method and html-version keys of $options (see below). For { "method": "html", "html-version": "LS" } this will be equivalent to [HTML: Living Standard] section 13.2.5, Tokenization.

  2. Constructing a HTMLDocument object for HTML documents, or an XMLDocument for XML/XHTML documents according to the method's tree construction algorithm from the tokens. For { "method": "html", "html-version": "LS" } this will be equivalent to [HTML: Living Standard] section 13.2.6, Tree construction.

  3. Building an XDM representation of the HTMLDocument or XMLDocument according to the rules in 14.2.1 XDM Mapping from HTML DOM Nodes.

For any given method key of $options the implementation must use a parser and validator consistent with the html-version key of $options. These are:

Valid method and html version combinations
method html-version Description
html 3, 3.2, 4, 4.01 An ·implementation-dependent· parsing algorithm, tree construction, and validation consistent with the specified HTML version.
html 5, 5.0, 5.1, 5.2 An HTML5 conformant parsing algorithm, tree construction, and validation consistent with the specified HTML version. An implementation may choose to use LS for all these HTML versions.
html LS A parsing algorithm, tree construction, and validation consistent with the [HTML: Living Standard].
xhtml 1.0, 1.1

An implementation may choose to use an XML parser to directly construct the XDM nodes, and then use an ·implementation-dependent· validation mechanism (such as DTD or XMLSchema) to validate the XHTML DOM tree.

An implementation may also choose to use [HTML: Living Standard] for all these XHTML versions, or some other HTML parser capable of processing XHTML documents.

* *

An ·implementation-defined· parsing algorithm, tree construction, and validation consistent with the specified HTML version.

This allows an implementation to provide their own method and html-version combinations. For example, an implementation could use the values "whatwg" and "2023-01-28" for an implementation of the WHATWG HTML Living Standard at a given date.

The function is ·nondeterministic with respect to node identity·: that is, if the function is called twice with the same arguments, it is ·implementation-dependent· whether the same node is returned on both occasions.

Error Conditions

A dynamic error is raised [err:FODC0011] if the content of $html is not a well-formed HTML document.

A dynamic error is raised [err:FODC0012] if the method key of $options is not supported by the implementation.

A dynamic error is raised [err:FODC0012] if a key passed to $options, or the value of that key, is not supported by the implementation.

Notes

If the HTML parser accepts a string as the input then that may be used directly when $html is an xs:string instead of converting the string to a sequence of octets in an ·implementation-dependent· encoding. The HTML parser must not perform character encoding processing on that input, treating the HTML string as being in a known character encoding that matches the encoding of the string.

The WHATWG Encoding specification defines the ISO 8859-1 (latin1) and ASCII encodings as aliases of the windows-1252 encoding.

Examples

The expression parse-html(()) returns ().

The expression parse-html("<p>Hello</p>") returns an XDM document node equivalent to the result of parsing the XML <html xmlns='http://www.w3.org/1999/xhtml'><head/><body><p>Hello</p></body></html>

The expression parse-html("<p>Hi</p>", method:="html") is equivalent to parse-html("<p>Hi</p>").

14.3 Functions on JSON Data

The functions listed in this section parse or serialize JSON data.

JSON is a popular format for exchange of structured data on the web: it is specified in [RFC 7159]. This section describes facilities allowing JSON data to be converted to and from XDM values.

This specification describes two ways of representing JSON data losslessly using XDM constructs. The first method uses XDM maps to represent JSON objects, and XDM arrays to represent JSON arrays. The second method represents all JSON constructs using XDM element and attribute nodes.

Function Meaning
fn:parse-json Parses a string supplied in the form of a JSON text, returning the results typically in the form of a map or array.
fn:json-doc Reads an external resource containing JSON, and returns the result of parsing the resource as JSON.
fn:json-to-xml Parses a string supplied in the form of a JSON text, returning the results in the form of an XML document node.
fn:xml-to-json Converts an XML tree, whose format corresponds to the XML representation of JSON defined in this specification, into a string conforming to the JSON grammar.
fn:pin Adapts a map or array so that retrieval operations retain additional information.
fn:label Returns the label associated with a labeled item, as a map.

Note also that the function fn:serialize has an option to act as the inverse function to fn:parse-json.

14.3.1 Representing JSON using maps and arrays

This section defines a mapping from JSON data to XDM maps and arrays. Two functions are available to support this mapping: fn:parse-json and fn:serialize (with options selecting JSON as the output method). The fn:parse-json function will accept any JSON text as input, and converts it to XDM data values. The fn:serialize function (with JSON as the output method) will accept any XDM value produced using fn:parse-json and convert it back to the original JSON text (subject to insignificant variations such as reordering the properties in a JSON object).

Note:

The conversion is lossless if recommended JSON good practice is followed. Information may however be lost if (a) JSON numbers are not exactly representable as double-precision floating point, or (b) duplicate key values appear within a JSON object.

The representation of JSON data produced by the fn:parse-json function has been chosen with ease of manipulation as a design aim. For example, a simple JSON object such as { "Sun": 1, "Mon": 2, "Tue": 3, ... } produces a simple map, so if the result of parsing is held in $weekdays, the number for a given weekday can be extracted using an expression such as $weekdays?Tue. Similarly, a simple array such as [ "Sun", "Mon", "Tue", ... ] produces an array that can be addressed as, for example, $weekdays(3). A more deeply nested structure can be addressed in a similar way: for example if the JSON text is an array of person objects, each of which has a property named phones which is an array of strings containing phone numbers, then the first phone number of each person in the data can be addressed as $data?phones(1).

14.3.2 XML Representation of JSON

This section defines a mapping from JSON data to XML (specifically, to XDM element and attribute nodes). A function fn:json-to-xml is provided to take a JSON string as input and convert it to the XML representation, and a second function fn:xml-to-json performs the reverse operation.

The XML representation is designed to be capable of representing any valid JSON text including one that uses characters which are not valid in XML. The transformation is normally lossless: that is, distinct JSON texts convert to distinct XML representations. When converting JSON to XML, options are provided to reject unsupported characters, to replace them with a substitute character, or to leave them in backslash-escaped form.

Note:

The conversion is lossless if recommended JSON good practice is followed. Information may however be lost if (a) JSON numbers are not exactly representable as double-precision floating point, or (b) duplicate key values appear within a JSON object.

The following example demonstrates the correspondence of a JSON text and the corresponding XML representation.

Example: A JSON Text and its XML Representation

Consider the following JSON text:

{
  "desc"    : "Distances between several cities, in kilometers.",
  "updated" : "2014-02-04T18:50:45",
  "uptodate": true,
  "author"  : null,
  "cities"  : {
    "Brussels": [
      { "to": "London",    "distance": 322 },
      { "to": "Paris",     "distance": 265 },
      { "to": "Amsterdam", "distance": 173 }
    ],
    "London": [
      { "to": "Brussels",  "distance": 322 },
      { "to": "Paris",     "distance": 344 },
      { "to": "Amsterdam", "distance": 358 }
    ],
    "Paris": [
      { "to": "Brussels",  "distance": 265 },
      { "to": "London",    "distance": 344 },
      { "to": "Amsterdam", "distance": 431 }
    ],
    "Amsterdam": [
      { "to": "Brussels",  "distance": 173 },
      { "to": "London",    "distance": 358 },
      { "to": "Paris",     "distance": 431 }
    ]
  }
}

The XML representation of this text is as follows. Whitespace is included in the XML representation for purposes of illustration, but it will not necessarily be present in the output of the json-to-xml function.

<map xmlns="http://www.w3.org/2005/xpath-functions">
  <string key="desc">Distances between several cities, in kilometers.</string>
  <string key="updated">2014-02-04T18:50:45</string>
  <boolean key="uptodate">true</boolean>
  <null key="author"/>
  <map key="cities">
    <array key="Brussels">
      <map>
        <string key="to">London</string>
        <number key="distance">322</number>
      </map>
      <map>
        <string key="to">Paris</string>
        <number key="distance">265</number>
      </map>
      <map>
        <string key="to">Amsterdam</string>
        <number key="distance">173</number>
      </map>
    </array>
    <array key="London">
      <map>
        <string key="to">Brussels</string>
        <number key="distance">322</number>
      </map>
      <map>
        <string key="to">Paris</string>
        <number key="distance">344</number>
      </map>
      <map>
        <string key="to">Amsterdam</string>
        <number key="distance">358</number>
      </map>
    </array>
    <array key="Paris">
      <map>
        <string key="to">Brussels</string>
        <number key="distance">265</number>
      </map>
      <map>
        <string key="to">London</string>
        <number key="distance">344</number>
      </map>
      <map>
        <string key="to">Amsterdam</string>
        <number key="distance">431</number>
      </map>
    </array>
    <array key="Amsterdam">
      <map>
        <string key="to">Brussels</string>
        <number key="distance">173</number>
      </map>
      <map>
        <string key="to">London</string>
        <number key="distance">358</number>
      </map>
      <map>
        <string key="to">Paris</string>
        <number key="distance">431</number>
      </map>
    </array>
  </map>
</map>

An XSD 1.0 schema for the XML representation is provided in C.2 Schema for the result of fn:json-to-xml. It is not necessary to import this schema into the static context unless the stylesheet or query makes explicit reference to the components defined in the schema. If the stylesheet or query does import a schema for the namespace http://www.w3.org/2005/xpath-functions, then:

  1. Unless the host language specifies otherwise, the processor (if it is schema-aware) must recognize an import declaration for this namespace, whether or not a schema location is supplied.

  2. If a schema location is provided, then the schema document at that location must be equivalent to the schema document at C.2 Schema for the result of fn:json-to-xml; the effect if it is not equivalent is ·implementation-dependent·

The rules governing the mapping from JSON to XML are as follows. In these rules, the phrase “an element named N” is to be interpreted as meaning “an element node whose local name is N and whose namespace URI is http://www.w3.org/2005/xpath-functions”.

  1. The JSON value null is represented by an element named null, with empty content.

  2. The JSON values true and false are represented by an element named boolean, with content conforming to the type xs:boolean. When the element is created by the fn:json-to-xml function, the string value of the element will be true or false. The fn:xml-to-json function also recognizes other strings that validate as xs:boolean, for example 1 and 0. Leading and trailing whitespace is accepted.

  3. A JSON number is represented by an element named number, with content conforming to the type xs:double, with the additional restriction that the value must not be positive or negative infinity, nor NaN. The fn:json-to-xml function creates an element whose string value is lexically the same as the JSON representation of the number. The fn:xml-to-json function generates a JSON representation that is the result of casting the (typed or untyped) value of the node to xs:double and then casting the result to xs:string. Leading and trailing whitespace is accepted. Since JSON does not impose limits on the range or precision of numbers, these rules mean that conversion from JSON to XML will always succeed, and will retain full precision in the lexical representation unless the data model implementation is one that reconstructs the string value from the typed value. In the reverse direction, conversion from XML to JSON may fail if the value is infinity or NaN, or if the string value is such that casting to xs:double produces positive or negative infinity.

  4. A JSON string is represented by an element named string, with content conforming to the type xs:string. The string element has two alternative representations: escaped form, and unescaped form.

  5. A JSON array is represented by an element named array. The content is a sequence of child elements representing the members of the array in order, each such element being the representation of the array member obtained by applying these rules recursively.

  6. A JSON object is represented by an element named map. The content is a sequence of child elements each of which represents one of the name/value pairs in the object. The representation of the name/value pair N:V is obtained by taking the element that represents the value V (by applying these rules recursively) and adding an attribute with name key (in no namespace), whose value is N as an instance of xs:string. The functions fn:json-to-xml and fn:xml-to-json both retain the order of entries, subject to rules about how duplicate keys are handled. The key may be represented in escaped or unescaped form.

The attribute escaped="true" may be specified on a string element to indicate that the string value contains backslash-escaped characters that are to be interpreted according to the JSON rules. The attribute escaped-key="true" may be specified on any element with a key attribute to indicate that the key contains backslash-escaped characters that are to be interpreted according to the JSON rules. Both attributes have the default value false, signifying that the relevant value is in unescaped form. In unescaped form, the backslash character has no special significance (it represents itself).

The JSON grammar for number is a subset of the lexical space of the XSD type xs:double. The mapping from JSON number values to xs:double values is defined by the XPath rules for casting from xs:string to xs:double. Note that these rules will never generate an error for out-of-range values; instead very large or very small values will be converted to +INF or -INF. Since JSON does not impose limits on the range or precision of numbers, the conversion is not guaranteed to retain full precision.

Although the order of entries in a JSON object is generally considered to have no significance, the functions json-to-xml and json-to-xml both retain order.

The XDM representation of a JSON value may either be untyped (all elements annotated as xs:untyped, attributes as xs:untypedAtomic), or it may be typed. If it is typed, then it must have the type annotations obtained by validating the untyped representation against the schema given in C.2 Schema for the result of fn:json-to-xml. If it is untyped, then it must be an XDM instance such that validation against this schema would succeed; with the proviso that all attributes other than those in no namespace or in namespace http://www.w3.org/2005/xpath-functions are ignored, including attributes such as xsi:type and xsi:nil that would normally influence the process of schema validation.

The namespace prefix associated with the namespace http://www.w3.org/2005/xpath-functions (if any) is immaterial. The effect of the fn:xml-to-json function does not depend on the choice of prefix, and the prefix (if any) generated by the fn:json-to-xml function is ·implementation-dependent·.

14.3.3 fn:parse-json

Changes in 4.0  

  1. An option is provided to control how the JSON null value should be handled.  [Issue 960 PR 1028 20 February 2024]

  2. An option is provided to control how JSON numbers should be formatted.  [Issues 973 1037 PRs 975 1058 1246 12 March 2024]

Summary

Parses a string supplied in the form of a JSON text, returning the results typically in the form of a map or array.

Signature
fn:parse-json(
$value as xs:string?,
$options as map(*)? := {}
) as item()?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If the second argument is omitted or an empty sequence, the result is the same as calling the two-argument form with an empty map as the value of the $options argument.

The first argument is a JSON text as defined in [RFC 7159], in the form of a string. The function parses this string to return an XDM value.

If $value is the empty sequence, the function returns the empty sequence.

Note:

The result will also be an empty sequence if $value is the string "null".

The $options argument can be used to control the way in which the parsing takes place. The ·option parameter conventions· apply.

The entries that may appear in the $options map are as follows:

record(
liberal? as xs:boolean,
duplicates? as xs:string,
escape? as xs:boolean,
fallback? as (fn(xs:string) as xs:anyAtomicType)?,
null? as item()*,
number-parser? as (fn(xs:untypedAtomic) as item()?)?
)
Key Value Meaning

liberal

Determines whether deviations from the syntax of RFC7159 are permitted.
  • Type: xs:boolean

  • Default: false

false The input must consist of an optional byte order mark (which is ignored) followed by a string that conforms to the grammar of JSON-text in [RFC 7159]. An error must be raised [err:FOJS0001] if the input does not conform to the grammar.
true The input may contain deviations from the grammar of [RFC 7159], which are handled in an ·implementation-defined· way. (Note: some popular extensions include allowing quotes on keys to be omitted, allowing a comma to appear after the last item in an array, allowing leading zeroes in numbers, and allowing control characters such as tab and newline to be present in unescaped form.) Since the extensions accepted are implementation-defined, an error may be raised [err:FOJS0001] if the input does not conform to the grammar.

duplicates

Determines the policy for handling duplicate keys in a JSON object. To determine whether keys are duplicates, they are compared using the Unicode codepoint collation, after expanding escape sequences, unless the escape option is set to true, in which case keys are compared in escaped form.
  • Type: xs:string

  • Default: use-first

reject An error is raised [err:FOJS0003] if duplicate keys are encountered.
use-first If duplicate keys are present in a JSON object, all but the first of a set of duplicates are ignored.
use-last If duplicate keys are present in a JSON object, all but the last of a set of duplicates are ignored.

escape

Determines whether special characters are represented in the XDM output in backslash-escaped form.
  • Type: xs:boolean

  • Default: true

false All characters in the input that are valid in the version of XML supported by the implementation, whether or not they are represented in the input by means of an escape sequence, are represented as unescaped characters in the result. Any characters or codepoints that are not valid XML characters (for example, unpaired surrogates) are passed to the fallback function as described below; in the absence of a fallback function, they are replaced by U+FFFD (REPLACEMENT CHARACTER, ) .
true JSON escape sequences are used in the result to represent special characters in the JSON input, as defined below, whether or not they were represented using JSON escape sequences in the input. The characters that are considered “special” for this purpose are:
  • all codepoints in the range U+0000 (NULL) to U+001F (IS1) or U+007F (DELETE) to U+009F (APC) ;

  • all codepoints that do not represent characters that are valid in the version of XML supported by the processor, including codepoints representing unpaired surrogates;

  • the character U+005C (REVERSE SOLIDUS, BACKSLASH, \) itself.

Such characters are represented using a two-character escape sequence where available (for example, \t), or a six-character escape sequence otherwise (for example \uDEAD). Characters other than these are not escaped in the result, even if they were escaped in the input.

fallback

Provides a function which is called when the input contains an escape sequence that represents a character that is not valid in the version of XML supported by the implementation. It is an error to supply the fallback option if the escape option is present with the value true.
  • Type: (fn(xs:string) as xs:anyAtomicType)?

  • Default: fn { char(0xFFFD) }

User-supplied function The function is called when the JSON input contains a special character (as defined under the escape option) that is valid according to the JSON grammar (whether the special character is represented in the input directly or as an escape sequence), but which does not represent a character that is valid in the version of XML supported by the processor. It is called once for any surrogate that is not properly paired with another surrogate. The untyped atomic item supplied as the argument will always be a two- or six-character escape sequence, starting with a backslash, that conforms to the rules in the JSON grammar (as extended by the implementation if liberal:true() is specified): for example \b or \uFFFF or \uDEAD.

By default, the escape sequence is replaced with the Unicode REPLACEMENT CHARACTER. The function is not called for an escape sequence that is invalid against the grammar (for example \x0A). The string, which results from invoking fn:string on the result of the function, is inserted into the result in place of the invalid character. The function also has the option of raising a dynamic error by calling fn:error.

null

Determines how the JSON null value should be represented.
  • Type: item()*

  • Default: ()

Value The supplied XDM value is used to represent the JSON null value. The default representation of null is an empty sequence, which works well in cases where setting a property of an object to null has the same meaning as omitting the property. It works less well in cases where null is used with some other meaning, because expressions such as the lookup operators ? and ?? flatten the result to a single sequence of items, which means that any entries whose value is an empty sequence effectively disappear. The property can be set to any XDM value; a suggested value is the xs:QName value fn:QName("http://www.w3.org/2005/xpath-functions", "null"), which is recognized by the JSON serialization method as representing the JSON value null.

number-parser

Determines how numeric values should be processed.
  • Type: (fn(xs:untypedAtomic) as item()?)?

  • Default: xs:double#1

User-supplied function The supplied function is called to process the string value of any JSON number in the input. By default, numbers are processed by converting to xs:double using the XPath casting rules. Supplying the value xs:decimal#1 will instead convert to xs:decimal (which potentially retains more precision, but disallows exponential notation), while supplying a function that casts to (xs:decimal | xs:double) will treat the value as xs:decimal if there is no exponent, or as xs:double otherwise. Supplying the value fn:identity#1 causes the value to be retained unchanged as an xs:untypedAtomic. If the liberal option is false (the default), then the supplied number-parser is called if and only if the value conforms to the JSON grammar for numbers (for example, a leading plus sign and redundant leading zeroes are not allowed). If the liberal option is true then it is also called if the value conforms to an ·implementation-defined· extension of this grammar.

The various structures that can occur in JSON are transformed recursively to XDM values as follows:

  1. A JSON object is converted to a map. The entries in the map correspond to the key/value pairs in the JSON object. The key is always of type xs:string; the associated value may be of any type, and is the result of converting the JSON value by recursive application of these rules. For example, the JSON text { "x": 2, "y": 5 } is transformed to the value { "x": 2, "y": 5 }.

    If duplicate keys are encountered in a JSON object, they are handled as determined by the duplicates option defined above.

  2. A JSON array is transformed to an array whose members are the result of converting the corresponding member of the array by recursive application of these rules. For example, the JSON text [ "a", "b", null ] is transformed (by default) to the value [ "a", "b", () ].

  3. A JSON string is converted to an xs:string value. The handling of special characters depends on the escape and fallback options, as described in the table above.

  4. A JSON number is processed using the function supplied in the number-parser option; by default it is converted to an xs:double value using the rules for casting from xs:string to xs:double.

  5. The JSON boolean values true and false are converted to the corresponding xs:boolean values.

  6. The JSON value null is converted to the value given by the null option, which defaults to an empty sequence.

Error Conditions

A dynamic error [err:FOJS0001] occurs if the value of $value does not conform to the JSON grammar, unless the option "liberal":true() is present and the processor chooses to accept the deviation.

A dynamic error [err:FOJS0003] occurs if the option "duplicates": "reject" is present and the value of $value contains a JSON object with duplicate keys.

A dynamic error [err:FOJS0005] occurs if the $options map contains an entry whose key is defined in this specification and whose value is not valid for that key, or if it contains an entry with the key fallback when the option "escape":true() is also present.

Notes

The result of the function will be an instance of one of the following types. An instance of test (or in XQuery, typeswitch) can be used to distinguish them:

  • map(xs:string, item()?) for a JSON object

  • array(item()?) for a JSON array

  • xs:string for a JSON string

  • xs:double for a JSON number

  • xs:boolean for a JSON boolean

  • empty-sequence() for a JSON null (or for empty input)

If the input starts with a byte order mark, this function ignores it. The byte order mark may have been added to the data stream in order to facilitate decoding of an octet stream to a character string, but since this function takes a character string as input, the byte order mark serves no useful purpose.

The possibility of the input containing characters that are not valid in XML (for example, unpaired surrogates) arises only when such characters are expressed using JSON escape sequences. This is the only possibility, because the input to the function is an instance of xs:string, which by definition can contain only those characters that are valid in XML.

Examples
Expression:

parse-json('{ "x": 1, "y": [ 3, 4, 5 ] }')

Result:
{ "x": 1e0, "y": [ 3e0, 4e0, 5e0 ] }
Expression:

parse-json('"abcd"')

Result:
"abcd"
Expression:

parse-json('{ "x": "\\", "y": "\u0025" }')

Result:
{ "x": "\", "y": "%" }
Expression:
parse-json(
  '{ "x": "\\", "y": "\u0025" }',
  { 'escape': true() }
)
Result:
{ "x": "\\", "y": "%" }
Expression:
parse-json(
  '{ "x": "\\", "y": "\u0000" }'
)
Result:
{ "x": "\", "y": char(0xFFFD) }
Expression:
parse-json(
  '{ "x": "\\", "y": "\u0000" }',
  { 'escape': true() }
)
Result:
{ "x": "\\", "y": "\u0000" }
Expression:
parse-json(
  '{ "x": "\\", "y": "\u0000" }',
  { 'fallback': fn($s) { '[' || $s || ']' } }
)
Result:
{ "x": "\", "y": "[\u0000]" }
Expression:
parse-json(
  "1984.2",
  { 'number-parser': fn { xs:integer(round(.)) } }
)
Result:
1984
Expression:
parse-json(
  '[ 1, -1, 2 ]',
  { 'number-parser': fn  { boolean(. >= 0) } }
)
Result:
[ true(), false(), true() ]
Expression:
parse-json('[ "a", null, "b" ]',
  { 'null': xs:QName("fn:null") }
)
Result:
[ "a", xs:QName("fn:null"), "b" ]

14.3.4 fn:json-doc

Changes in 4.0  

  1. Additional options are available, as defined by fn:parse-json.

Summary

Reads an external resource containing JSON, and returns the result of parsing the resource as JSON.

Signature
fn:json-doc(
$source as xs:string?,
$options as map(*)? := {}
) as item()?
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.

Rules

If the second argument is omitted or an empty sequence, the result is the same as calling the two-argument form with an empty map as the value of the $options argument.

The effect of the two-argument function call fn:json-doc($H, $M)is equivalent to the function composition fn:unparsed-text($H) => fn:parse-json($M); except that:

  1. The function may accept a resource in any encoding. [RFC 7159] requires UTF-8, UTF-16, or UTF-32 to be accepted, but it is not an error if a different encoding is used. Unless external encoding information is available, the function must assume that the encoding is one of UTF-8, UTF-16, or UTF-32, and must distinguish these cases by examination of the initial octets of the resource.

  2. If the resource contains characters that are not ·permitted characters·, then rather than raising an error as fn:unparsed-text#1 does, the function replaces such characters by the equivalent JSON escape sequence prior to parsing.

    Note:

    Equivalently, the implementation can use some other internal representation of strings that allows non-XML characters to be manipulated.

If $source is the empty sequence, the function returns the empty sequence.

Error Conditions

The function may raise any error defined for the fn:unparsed-text or fn:parse-json functions.

Notes

If the input cannot be decoded (that is, converted into a sequence of Unicode codepoints, which may or may not represent characters), then a dynamic error occurs as with the fn:unparsed-text function.

If the input can be decoded, then the possibility still arises that the resulting sequence of codepoints includes codepoints that do not represent characters that are valid in the version of XML that the processor supports. Such codepoints are translated into JSON escape sequences (for example, \uFFFF), and the JSON escape sequence is then passed to the fallback function specified in the $options argument, which in turn defaults to a function that returns the Unicode REPLACEMENT CHARACTER (xFFFD).

14.3.5 fn:json-to-xml

Summary

Parses a string supplied in the form of a JSON text, returning the results in the form of an XML document node.

Signature
fn:json-to-xml(
$value as xs:string?,
$options as map(*)? := {}
) as document-node()?
Properties

This function is ·nondeterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.

Rules

If the second argument is omitted or an empty sequence, the result is the same as calling the two-argument form with an empty map as the value of the $options argument.

The first argument is a JSON text as defined in [RFC 7159], in the form of a string. The function parses this string to return an XDM node.

If $value is an empty sequence, the function returns the empty sequence.

The $options argument can be used to control the way in which the parsing takes place. The ·option parameter conventions· apply.

The entries that may appear in the $options map are as follows:

record(
liberal? as xs:boolean,
duplicates? as xs:string,
validate? as xs:boolean,
escape? as xs:boolean,
fallback? as (fn(xs:string) as xs:anyAtomicType)?,
number-parser? as (fn(xs:untypedAtomic) as item()?)?
)
Key Value Meaning

liberal

Determines whether deviations from the syntax of RFC7159 are permitted.
  • Type: xs:boolean

  • Default: false

false The input must consist of an optional byte order mark (which is ignored) followed by a string that conforms to the grammar of JSON-text in [RFC 7159]. An error must be raised (see below) if the input does not conform to the grammar.
true The input may contain deviations from the grammar of [RFC 7159], which are handled in an ·implementation-defined· way. (Note: some popular extensions include allowing quotes on keys to be omitted, allowing a comma to appear after the last item in an array, allowing leading zeroes in numbers, and allowing control characters such as tab and newline to be present in unescaped form.) Since the extensions accepted are implementation-defined, an error may be raised (see below) if the input does not conform to the grammar.

duplicates

Determines the policy for handling duplicate keys in a JSON object. To determine whether keys are duplicates, they are compared using the Unicode codepoint collation, after expanding escape sequences, unless the escape option is set to true, in which case keys are compared in escaped form.
  • Type: xs:string

  • Default: If validate is true then reject, otherwise retain.

reject An error is raised [err:FOJS0003] if duplicate keys are encountered.
use-first If duplicate keys are present in a JSON object, all but the first of a set of duplicates are ignored.
retain If duplicate keys are present in a JSON object, the XML result of the function will also contain duplicates (making it invalid against the schema). This value is therefore incompatible with the option validate=true [err:FOJS0005]

validate

Determines whether the generated XML tree is schema-validated.
true Indicates that the resulting XDM instance must be typed; that is, the element and attribute nodes must carry the type annotations that result from validation against the schema given at C.2 Schema for the result of fn:json-to-xml, or against an ·implementation-defined· schema if the liberal option has the value true.
false Indicates that the resulting XDM instance must be untyped.

escape

Determines whether special characters are represented in the XDM output in backslash-escaped form.
  • Type: xs:boolean

  • Default: false

false All characters in the input that are valid in the version of XML supported by the implementation, whether or not they are represented in the input by means of an escape sequence, are represented as unescaped characters in the result. Any characters or codepoints that are not valid XML characters (for example, unpaired surrogates) are passed to the fallback function as described below; in the absence of a fallback function, they are replaced by the character U+FFFD (REPLACEMENT CHARACTER, ) . The attributes escaped and escaped-key will not be present in the XDM output.
true JSON escape sequences are used in the result to represent special characters in the JSON input, as defined below, whether or not they were represented using JSON escape sequences in the input. The characters that are considered “special” for this purpose are:
  • all codepoints in the range U+0000 (NULL) to U+001F (IS1) or U+007F (DELETE) to U+009F (APC) ;

  • all codepoints that do not represent characters that are valid in the version of XML supported by the processor, including codepoints representing unpaired surrogates;

  • the backslash character itself (U+005C (REVERSE SOLIDUS, BACKSLASH, \) ).

Such characters are represented using a two-character escape sequence where available (for example, \t), or a six-character escape sequence otherwise (for example \uDEAD). Characters other than these will not be escaped in the result, even if they were escaped in the input. In the result:
  • Any string element whose string value contains a backslash character must have the attribute value escaped="true".

  • Any element that contains a key attribute whose string value contains a backslash character must have the attribute escaped-key="true".

  • The values of the escaped and escaped-key attributes are immaterial when there is no backslash present, and it is never necessary to include either attribute when its value is false.

fallback

Provides a function which is called when the input contains an escape sequence that represents a character that is not valid in the version of XML supported by the implementation. It is an error to supply the fallback option if the escape option is present with the value true.
  • Type: (fn(xs:string) as xs:anyAtomicType)?

  • Default: fn { char(0xFFFD) }

User-supplied function The function is called when the JSON input contains an escape sequence that is valid according to the JSON grammar, but which does not represent a character that is valid in the version of XML supported by the processor. In the case of surrogates, it is called once for any six-character escape sequence that is not properly paired with another surrogate. The untyped atomic item supplied as the argument will always be a two- or six-character escape sequence, starting with a backslash, that conforms to the rules in the JSON grammar (as extended by the implementation if liberal:true() is specified): for example \b or \uFFFF or \uDEAD.

By default, the escape sequence is replaced with the Unicode REPLACEMENT CHARACTER. The function is not called for an escape sequence that is invalid against the grammar (for example \x0A). The string, which results from invoking fn:string on the result of the function, is inserted into the result in place of the invalid character. The function also has the option of raising a dynamic error by calling fn:error.

number-parser

Determines how numeric values should be processed.
  • Type: (fn(xs:untypedAtomic) as item()?)?

  • Default: xs:identity#1

User-supplied function The supplied function is called to process the string value of any JSON number in the input. The string value of the number element generated in the result will be the value obtained by calling the supplied function, and then converting its result to a string by calling fn:string#1.

By default, numbers are represented in the XML output exactly as they were written in the input. Supplying the value xs:double#1 will cause the value to be convered to type xs:double (which will then be represented in the XML by converting the xs:double to a string). Similarly xs:decimal#1 will convert to xs:decimal (which potentially retains more precision, but disallows exponential notation), while supplying a function that casts to (xs:decimal | xs:double) will treat the value as xs:decimal if there is no exponent, or as xs:double otherwise. The default value fn:identity#1 causes the value to be retained unchanged as an xs:untypedAtomic. Before calling the supplied number-parser, the value is first checked to ensure that it conforms to the JSON grammar (for example, a leading plus sign and redundant leading zeroes are not allowed); these checks are disabled if the liberal option is set to true. Note that the option validate=true will cause the result to be validated as type xs:double (disallowing NaN and infinity).

The various structures that can occur in JSON are transformed recursively to XDM values according to the rules given in 14.3.2 XML Representation of JSON.

The function returns a document node, whose only child is the element node representing the outermost construct in the JSON text.

The function is ·nondeterministic with respect to node identity·: that is, if the function is called twice with the same arguments, it is ·implementation-dependent· whether the same node is returned on both occasions.

The base URI of the returned document node is taken from the static base URI of the function call.

The choice of namespace prefix (or absence of a prefix) in the names of constructed nodes is ·implementation-dependent·.

The XDM tree returned by the function does not contain any unnecessary (albeit valid) nodes such as whitespace text nodes, comments, or processing instructions. It does not include any whitespace in the value of number or boolean element nodes, or in the value of escaped or escaped-key attribute nodes.

If the result is typed, every element named string will have an attribute named escaped whose value is either true or false, and every element having an attribute named key will also have an attribute named escaped-key whose value is either true or false.

If the result is untyped, the attributes escaped and escaped-key will either be present with the value true, or will be absent. They will never be present with the value false.

Error Conditions

An error is raised [err:FOJS0001] if the value of $value does not conform to the JSON grammar as defined by [RFC 7159], unless the option "liberal":true() is present and the processor chooses to accept the deviation.

An error is raised [err:FOJS0004] if the value of the validate option is true and the processor does not support schema validation or typed data.

An error is raised [err:FOJS0005] if the value of $options includes an entry whose key is defined in this specification, and whose value is not a permitted value for that key.

Notes

To read a JSON file, this function can be used in conjunction with the fn:unparsed-text function.

Many JSON implementations allow commas to be used after the last item in an object or array, although the specification does not permit it. The option spec="liberal" is provided to allow such deviations from the specification to be accepted. Some JSON implementations also allow constructors such as new Date("2000-12-13") to appear as values: specifying spec="liberal" allows such extensions to be accepted, but does not guarantee it. If such extensions are accepted, the resulting value is implementation-defined, and will not necessarily conform to the schema at C.2 Schema for the result of fn:json-to-xml.

If the input starts with a byte order mark, this function ignores it. The byte order mark may have been added to the data stream in order to facilitate decoding of an octet stream to a character string, but since this function takes a character string as input, the byte order mark serves no useful purpose.

The possibility of the input containing characters that are not valid in XML (for example, unpaired surrogates) arises only when such characters are expressed using JSON escape sequences. This is the only possibility because the input to the function is an instance of xs:string, which by definition can contain only those characters that are valid in XML.

Examples
Expression:
json-to-xml(
  '{ "x": 1, "y": [ 3, 4, 5 ] }',
  { "validate": false() }
)
Result:
<map xmlns="http://www.w3.org/2005/xpath-functions">
  <number key="x">1</number>
  <array key="y">
   <number>3</number>
   <number>4</number>
   <number>5</number>
  </array>
</map>

(with whitespace added for legibility)

Expression:
json-to-xml(
  '"abcd"',
  { 'liberal': false() }
)
Result:
<string xmlns="http://www.w3.org/2005/xpath-functions">abcd</string>
Expression:
json-to-xml(
  '{ "x": "\\", "y": "\u0025" }',
  { "validate": false() }
)
Result:
<map xmlns="http://www.w3.org/2005/xpath-functions">
  <string key="x">\</string>
  <string key="y">%</string>
</map>

(with whitespace added for legibility)

Expression:
json-to-xml(
  '{ "x": "\\", "y": "\u0025" }',
  { 'escape': true(), "validate": false() }
)
Result:
<map xmlns="http://www.w3.org/2005/xpath-functions">
  <string escaped="true" key="x">\\</string>
  <string key="y">%</string>
</map>

(with whitespace added for legibility)

(But see the detailed rules for alternative values of the escaped attribute on the second string element.)

The following example illustrates use of the fallback function to handle characters that are invalid in XML.

let $json := unparsed-text('http://example.com/endpoint')
let $options := {
  'liberal': true(),
  'fallback': fn($char as xs:string) as xs:string {
    let $c0chars := {
      '\u0000':'[NUL]',
      '\u0001':'[SOH]',
      '\u0002':'[STX]',
      ...
      '\u001E':'[RS]',
      '\u001F':'[US]'
    }
    let $replacement := $c0chars($char)
    return if (exists($replacement)) then (
      $replacement
    ) else (
      error(
        xs:QName('err:invalid-char'),
        'Error: ' || $char || ' is not a C0 control character.'
      )
    )
  }
}
return json-to-xml($json, $options)

14.3.6 fn:xml-to-json

Changes in 4.0  

  1. An option has been added to suppress the escaping of the solidus (forwards slash) character.  [Issue 1347 PR 1353]

  2. Numbers now retain their original lexical form, except for any changes needed to satisfy JSON syntax rules (for example, stripping leading zero digits).  [Issue 1445 PR 1455]

Summary

Converts an XML tree, whose format corresponds to the XML representation of JSON defined in this specification, into a string conforming to the JSON grammar.

Signature
fn:xml-to-json(
$node as node()?,
$options as map(*)? := {}
) as xs:string?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If the second argument is omitted or an empty sequence, the result is the same as calling the two-argument form with an empty map as the value of the $options argument.

The first argument $node is a node; the subtree rooted at this node will typically be the XML representation of a JSON document as defined in 14.3.2 XML Representation of JSON.

If $node is the empty sequence, the function returns the empty sequence.

The $options argument can be used to control the way in which the conversion takes place. The ·option parameter conventions· apply.

The entries that may appear in the $options map are as follows:

record(
escape-solidus? as xs:boolean,
indent? as xs:boolean
)
Key Value Meaning

escape-solidus

Determines whether the character U+002F (SOLIDUS, FORWARD SLASH, /) should be escaped as \/. By default the character is escaped, but this is only necessary when the resulting JSON is embedded in HTML.
  • Type: xs:boolean

  • Default: true

false The character U+002F (SOLIDUS, FORWARD SLASH, /) is output as is, without escaping.
true The character U+002F (SOLIDUS, FORWARD SLASH, /) is escaped by preceding it with U+005C (REVERSE SOLIDUS, BACKSLASH, \) .

indent

Determines whether additional whitespace should be added to the output to improve readability.
  • Type: xs:boolean

  • Default: false

false The processor must not insert any insignificant whitespace between JSON tokens.
true The processor may insert whitespace between JSON tokens in order to improve readability. The specification imposes no constraints on how this is done.

The node supplied as $node must be one of the following: [err:FOJS0006]

  1. An element node whose name matches the name of a global element declaration in the schema given in C.2 Schema for the result of fn:json-to-xml (“the schema”) and that is valid as defined below:

    1. If the type annotation of the element matches the type of the relevant element declaration in the schema (indicating that the element has been validated against the schema), then the element is considered valid.

    2. Otherwise, the processor may attempt to validate the element against the schema, in which case it is treated as valid if and only if the outcome of validation is valid.

    3. Otherwise (if the processor does not attempt validation using the schema), the processor must ensure that the content of the element, after stripping all attributes (at any depth) in namespaces other than http://www.w3.org/2005/xpath-functions, is such that validation against the schema would have an outcome of valid.

      Note:

      The process described here is not precisely equivalent to schema validation. For example, schema validation will fail if there is an invalid xsi:type or xsi:nil attribute, whereas this process will ignore such attributes.

  2. An element node E having a key attribute and/or an escaped-key attribute provided that E would satisfy one of the above conditions if the key and/or escaped-key attributes were removed.

  3. A document node having exactly one element child and no text node children, where the element child satisfies one of the conditions above.

Furthermore, $node must satisfy the following constraint (which cannot be conveniently expressed in the schema). Every element M that is a descendant-or-self of $node and has local name map and namespace URI http://www.w3.org/2005/xpath-functions must satisfy the following rule: there must not be two distinct children of M (say C1 and C2) such that the normalized key of C1 is equal to the normalized key of C2. The normalized key of an element C is as follows:

  • If C has the attribute value escaped-key="true", then the value of the key attribute of C, with all JSON escape sequences replaced by the corresponding Unicode characters according to the JSON escaping rules.

  • Otherwise (the escaped-key attribute of C is absent or set to false), the value of the key attribute of C.

Nodes in the input tree are handled by applying the following rules, recursively. In these rules the term “an element named N” means “an element node whose local name is N and whose namespace URI is http://www.w3.org/2005/xpath-functions”.

  1. A document node having a single element node child is processed by processing that child.

  2. An element named null results in the output null.

  3. An element $E named boolean results in the output true or false depending on the result of xs:boolean(fn:string($E)).

  4. An element $E named number is processed by copying the string value of $E to the output, making any changes that are necessary to ensure that the result is a valid JSON number. Such changes include:

    • Removing leading and trailing whitespace.

    • Removing a leading plus sign.

    • Removing redundant leading zero digits.

    • Adding a zero digit before or after a decimal point that is not preceded and followed by a digit.

    Note:

    The output uses exponential notation if and only if the input uses exponential notation.

    The rules have changed since version 3.1 of this specification. In previous versions, the supplied number was cast to an xs:double, and then serialized using the rules of the fn:string function. This resulted in JSON numbers using exponential notation for values outside the range 1e-6 to 1e6, and led to a loss of precision for 64-bit integer values.

  5. An element named string results in the output of the string value of the element, enclosed in quotation marks, with any special characters in the string escaped as described below.

  6. An element named array results in the output of the children of the array element, each processed by applying these rules recursively: the items in the resulting list are enclosed between square brackets, and separated by commas.

  7. An element named map results in the output of a sequence of map entries corresponding to the children of the map element, enclosed between curly braces and separated by commas. Each entry comprises the value of the key attribute of the child element, enclosed in quotation marks and escaped as described below, followed by a colon, followed by the result of processing the child element by applying these rules recursively.

  8. Comments, processing instructions, and whitespace text node children of map and array are ignored.

Strings are escaped as follows:

  1. If the attribute escaped="true" is present for a string value, or escaped-key="true" for a key value, then:

    1. any valid JSON escape sequence present in the string is copied unchanged to the output;

    2. any invalid JSON escape sequence results in a dynamic error [err:FOJS0007];

    3. any unescaped occurrence of U+0022 (QUOTATION MARK, ") , U+0008 (BACKSPACE) , U+000C (FORM FEED) , U+000A (NEWLINE) , U+000D (CARRIAGE RETURN) , U+0009 (TAB) , or (subject to the escape-solidus option) U+002F (SOLIDUS, FORWARD SLASH, /) is replaced by \", \b, \f, \n, \r, \t, or \/ respectively;

    4. any other codepoint in the range 1-31 or 127-159 is replaced by an escape in the form \uHHHH where HHHH is the upper-case hexadecimal representation of the codepoint value.

  2. Otherwise (that is, in the absence of the attribute escaped="true" for a string value, or escaped-key="true" for a key value):

    1. any occurrence of backslash is replaced by \\

    2. any occurrence of U+0022 (QUOTATION MARK, ") , U+0008 (BACKSPACE) , U+000C (FORM FEED) , U+000A (NEWLINE) , U+000D (CARRIAGE RETURN) , or U+0009 (TAB) is replaced by \", \b, \f, \n, \r, or \t respectively;

    3. any other codepoint in the range 1-31 or 127-159 is replaced by an escape in the form \uHHHH where HHHH is the upper-case hexadecimal representation of the codepoint value.

Error Conditions

A dynamic error is raised [err:FOJS0005] if the value of $options includes an entry whose key is defined in this specification, and whose value is not a permitted value for that key.

A dynamic error is raised [err:FOJS0006] if the value of $node is not a document or element node or is not valid according to the schema for the XML representation of JSON, or if a map element has two children whose normalized key values are the same.

A dynamic error is raised [err:FOJS0007] if the value of $node includes a string labeled with escaped="true", or a key labeled with escaped-key="true", where the content of the string or key contains an invalid JSON escape sequence: specifically, where it contains a backslash (\) that is not followed by one of the characters ", \, /, b, f, n, r, t, or u, or where it contains the characters \u not followed by four hexadecimal digits (that is [0-9A-Fa-f]{4}).

Notes

The rule requiring schema validity has a number of consequences, including the following:

  1. The input cannot contain no-namespace attributes, or attributes in the namespace http://www.w3.org/2005/xpath-functions, except where explicitly allowed by the schema. Attributes in other namespaces, however, are ignored.

  2. Nodes that do not affect schema validity, such as comments, processing instructions, namespace nodes, and whitespace text node children of map and array, are ignored.

  3. Numeric values are restricted to those that are valid in JSON: the schema disallows positive and negative infinity and NaN.

  4. Duplicate key values are not permitted. Most cases of duplicate keys are prevented by the rules in the schema; additional cases (where the keys are equal only after expanding JSON escape sequences) are prevented by the prose rules of this function. For example, the key values \n and \u000A are treated as duplicates even though the rules in the schema do not treat them as such.

The rule allowing the top-level element to have a key attribute (which is ignored) allows any element in the output of the fn:json-to-xml function to be processed: for example, it is possible to take a JSON document, convert it to XML, select a subtree based on the value of a key attribute, and then convert this subtree back to JSON, perhaps after a transformation. The rule means that an element with the appropriate name will be accepted if it has been validated against one of the types mapWithinMapType, arrayWithinMapType, stringWithinMapType, numberWithinMapType, booleanWithinMapType, or nullWithinMapType.

Examples

The input <array xmlns="http://www.w3.org/2005/xpath-functions"><number>1</number><string>is</string><boolean>1</boolean></array> produces the result [ 1, "is", true ].

The input <map xmlns="http://www.w3.org/2005/xpath-functions"><number key="Sunday">1</number><number key="Monday">2</number></map> produces the result { "Sunday": 1, "Monday": 2 }.

The input <array xmlns="http://www.w3.org/2005/xpath-functions"><number>10</number><number>17e2</number><number>0005</number></array> produces the result [ 10, 17e2, 5 ].

14.3.7 fn:pin

Changes in 4.0  

  1. New in 4.0  [Issue 960 PR 988 27 February 2024]

Summary

Adapts a map or array so that retrieval operations retain additional information.

Signature
fn:pin(
$input as (map(*)|array(*))
) as (map(*)|array(*))
Properties

This function is ·nondeterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function creates a deep copy of the supplied map or array, adapted so that navigation within the deep copy returns items that are labeled with additional information about their position within the containing tree structure.

Note:

The formal specification of the function describes it as constructing a deep copy of the entire tree, but a practical implementation is likely to use a lazy evaluation strategy, so the only costs incurred are for items actually selected within the tree.

The function makes use of the concept of labeled items, an extension to the data model described in Section 2.10 Labeled ItemsDM40.

The supplied value of $input must be either a map or an array.

The result is as follows:

  1. If $input is a map M, the result is a map M′ derived from M as follows:

    1. Any existing label on M is discarded.

    2. M′ acquires a label having the property pinned set to the value true, and the property id set to an arbitrary xs:string value that is unique within the execution scope.

    3. For every key-value pair (K, V) in M, M′ will have a key-value pair (K, V′) in which the key K is unchanged, and the value V′ is derived from V by applying the function derived-value(M', K, V), defined below.

  2. If $input is an array A, the result is an array A′ derived from A as follows:

    1. Any existing label on A is discarded.

    2. A′ acquires a label having the property pinned set to the value true, and the property id set to an arbitrary xs:string value that is unique within the execution scope.

    3. For every member V in A, whose 1-based index position in A is X, A′ will have a member V′ derived from V by applying the function derived-value(A', X, V), defined below.

  3. The id property described in the previous paragraphs is allocated only to the top-level map or array (the one supplied as an explicit argument to the fn:pin function). The function is not ·deterministic·: that is, if the function is called twice with the same arguments, it is ·implementation-dependent· whether the same id property is allocated on both occasions.

  4. If $input is anything other than a map or an array, a type error is raised.

  5. The function derived-value(P, K, V) has the following logic. For every item J in V, V′ will contain an item J′ that is derived from J as follows:

    1. Let TEMP be:

      1. If J is a map or array, then fn:pin(J).

        Note:

        Note however that the id property of TEMP is not used, so there is no need to generate it.

      2. Otherwise, J.

    2. J′ is then a labeled item having the same subject as TEMP, together with a label having the following properties:

      pinned

      true

      key

      K

      position

      The 1-based position of J within V.

      parent

      P

      ancestors

      A zero-arity function item delivering the value of (?parent, ?parent ! label(.)?ancestors()).

      path

      A zero-arity function item delivering the value of (?parent ! label(.)?path(), ?key).

Notes

The effect of calling pin on a map or array is that subsequent retrieval operations within the pinned map or array return labeled results, whose labels contain useful information about where the results were found. For example, an expression such as json-doc($source)??name will return the values of all entries in the JSON tree having the key "name"; but very little can be done with this information because the result is simply a sequence of (typically) strings with no context. By contrast, the result of pin(json-doc($source))??name is the same set of strings, labeled with information about where they were found. For example, if $result is the result of the expression pin(json-doc($source))??name, then:

  • $result => label()?parent?ssn locates the map that contained each name, and returns the value of the ssn entry in that map.

  • $result => label()?ancestors()?course returns the values of any course entries in containing maps.

  • $result => label()?path() returns a sequence of map keys and array index values representing the location of the found entries within the JSON structure.

Editorial note  
The id property on the root of a pinned map or array is intended to support deep update operations, which have not yet been defined.
Examples
Expression:

pin([ "a", "b", "c" ])?1 ! label(.)?parent ! array:foot(.)

Result:
"c"
Expression:

pin([ "a", "b", "c", "d" ]) ! array:remove(., 2)?* ! label(.)?key

Result:
1, 3, 4
Expression:
let $data := {
  "fr": { "capital": "Paris", "languages": [ "French" ] }, 
  "de": { "capital": "Berlin", "languages": [ "German" ] }
}
return pin($data)??languages[. = 'German'] ! label()?path()[1]
Result:
"de"

14.3.8 fn:label

Changes in 4.0  

  1. New in 4.0  [Issue 960 PR 988 27 February 2024]

Summary

Returns the label associated with a labeled item, as a map.

Signature
fn:label(
$input as item()?
) as map(xs:string, item()*)?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $input is an empty sequence, the function returns an empty sequence.

If $input is an item that has no label, the function returns an empty map.

If $input is a labeled item, the function returns the label, as a map.

Notes

The function makes use of the concept of labeled items, an extension to the data model described in Section 2.10 Labeled ItemsDM40.

The data model allows any item to be labeled, and allows the label to be any map with string-valued keys. Currently the only operation that creates labeled values is the fn:pin function. For examples illustrating the use of fn:label, see fn:pin.

14.4 Functions on CSV Data

Changes in 4.0  

  1. New functions are available for processing input data in CSV (comma separated values) format.   [Issue 413 PRs 533 719 834]

This section describes functions that parse CSV data.

[Definition] The term comma separated values or CSV refers to a wide variety of plain-text tabular data formats with fields and records separated by standard character delimiters (often, but not invariably, commas).

A CSV is a 2-dimensional tabular data structure consisting of multiple rows (also known as records). Each row contains multiple fields. Fields occupying the same position in successive rows constitute a column. Columns are identified by position and optionally by name. Column names can be assigned within a CSV using an optional header row.

CSV has developed informally for decades, and many variations are found. This specification refers to [RFC 4180], which provides a standardized grammar. This specification extends the grammar defined in [RFC 4180] as follows:

  • This specification uses the term row where RFC 4180 uses record.

  • Row delimiters other than CRLF are recognized.

  • Field delimiters other than comma (",") are recognized.

  • Quote characters other than the double quotation mark ('"') are recognized.

  • Non-ASCII characters are recognized.

This specification defines a mapping from this extended grammar to constructs in the XDM model, and provides illustrative examples of how these constructs can be combined with other language features to process CSV data.

Function Meaning
fn:csv-to-arrays Parses CSV data supplied as a string, returning the results in the form of a sequence of arrays of strings.
fn:parse-csv Parses CSV data supplied as a string, returning the results in the form of a record containing information about the names in the header, as well as the data itself.
fn:csv-to-xml Parses CSV data supplied as a string, returning the results as an XML document, as described by 14.4.7 Representing CSV data as XML.

The most basic function for parsing CSV is fn:csv-to-arrays which recognizes the delimiters for rows and fields and returns a sequence of arrays each corresponding to one row. The fields within each array are represented as instances of xs:string.

The other two functions recognize column names, and make it easier to address individual fields using these names. The parse-csv function delivers this capability using XDM maps and functions, while csv-to-xml function represents the information using XDM element nodes.

14.4.1 CSV delimiters

The delimiters used for rows, columns, and quoting are configurable. An error is raised if the same delimiter string is used in multiple roles [err:FOCV0003].

Rows in CSV files are typically delimited with CRLF (U+000D (CARRIAGE RETURN) , U+000A (NEWLINE) ), LF (U+000A (NEWLINE) ), or CR (U+000D (CARRIAGE RETURN) ) line endings, although RFC 4180 specifies CRLF. By contrast, the fn:unparsed-text function normalizes these line endings to LF (U+000A (NEWLINE) ). The CSV parsing functions therefore use LF by default. An option is available to normalize line endings so that CR and CRLF are converted to U+000A (NEWLINE) (except when they appear in quote fields). This option is off by default, because line ending normalization will usually have been carried out earlier: for example, the fn:unparsed-text function does it automatically.

The last row in the file may or may not be followed by a row delimiter.

Fields in CSV are frequently delimited with a comma. Other field delimiters are useful, for example when numeric data uses comma as a decimal separator. The chosen field delimiter is then often U+003B (SEMICOLON, ;) or U+0009 (TAB) .

The column delimiter defaults to U+002C (COMMA, ,) . The value may be any single Unicode character. An error is raised if the column-delimiter option is set to a multi-character string.

14.4.2 Field quoting

CSVs, as specified in [RFC 4180], require that fields be wrapped with a quote character if they contain either the row or column delimiter. For example:

"A single field, containing a comma","another field containing CRLF
                  within it"

If a field is to contain the quote character, the character must be escaped by doubling it, as with escaping of quotes in XPath string literals (see Section 4.2.1 LiteralsXP40). An error is raised [err:FOCV0001] if a quote character appears within a field incorrectly escaped, for example:

incorrectly escaped " quote character

The quotes surrounding quoted fields are not included in the result. The following input string, when parsed, produces a sequence of strings, as shown below:

'"Field 1","Field 2","Field ""with quotes"" 3"'
('Field 1', 'Field 2', 'Field "with quotes" 3')

The quote character defaults to U+0022 (QUOTATION MARK, ") .

No space is allowed between the column delimiter and a quote. An error is raised [err:FOCV0001] if whitespace or other characters occur between a quote character and the nearest column delimiter.

The following example is therefore invalid and parsing it will raise an error.

'"Field 1", "Field 2", "Field 3"'

14.4.3 Basic parsing of CSV to arrays

The result of fn:csv-to-arrays is a sequence of rows, where each row is represented as an array of xs:string values.

The first row of the CSV is returned in the same way as all the other rows. fn:csv-to-arrays does not distinguish between a header row and data rows, and returns all of them.

Example: A CSV with fixed-width rows

For example, given the input:

'Column 1,Column 2,Column 3
Field 1A,Field 1B,Field 1C
Field 2A,Field 2B,Field 2C'

the fn:csv-to-arrays function produces

(
  [ "Column 1", "Column 2", "Column 3" ],
  [ "Field 1A", "Field 1B", "Field 1C" ],
  [ "Field 2A", "Field 2B", "Field 2C" ]
)
Example: A CSV with variable-width rows

It is common practice for all rows in a CSV to have the same number of columns, but this is not required.

'Column 1,Column 2,Column 3
Field 1A,Field 1B,Field 1C
Field 2A,Field 2B,Field 2C,Field 2D'

produces

(
  [ "Column 1", "Column 2", "Column 3" ],
  [ "Field 1A", "Field 1B", "Field 1C" ],
  [ "Field 2A", "Field 2B", "Field 2C", "Field 2D" ]
)

[RFC 4180] states that CSVs should contain the same number of fields in each row, so that there are a uniform number of columns. However, the reality is that CSVs can, and sometimes do, contain a variable number of fields in a row. As a result, this function does not truncate or pad the number of fields in each row for any reason. The fn:csv-to-xml and fn:parse-csv functions provide facilities to enforce uniformity and an expected number of columns.

14.4.4 fn:csv-to-arrays

Changes in 4.0  

  1. New in 4.0  [Issues 413 1052 PRs 533 719 834 1066]

Summary

Parses CSV data supplied as a string, returning the results in the form of a sequence of arrays of strings.

Signature
fn:csv-to-arrays(
$value as xs:string?,
$options as map(*)? := {}
) as array(xs:string)*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The $value argument is CSV data, as defined in [RFC 4180], in the form of an xs:string value. The function parses this string. The result of the function is a sequence of arrays of strings, that is array(xs:string)*; each array represents one row of the CSV input.

If $value is the empty sequence or a zero-length string, the function returns an empty sequence.

The $options argument can be used to control the way in which the parsing takes place. The ·option parameter conventions· apply.

If the $options argument is omitted or an empty sequence, the result is the same as calling the two-argument form with an empty map as the value of the $options argument.

The entries that may appear in the $options map are as follows:

record(
field-delimiter? as xs:string,
row-delimiter? as xs:string+,
quote-character? as xs:string,
trim-whitespace? as xs:boolean,
normalize-newlines? as xs:boolean
)
Key Value Meaning

field-delimiter

The character used to delimit fields within a record. An instance of xs:string whose length is exactly one.
  • Type: xs:string

  • Default: ","

row-delimiter

The character used to delimit rows within the CSV string. An instance of xs:string whose length is exactly one. Defaults to a single newline character (U+000A (NEWLINE) ).
  • Type: xs:string+

  • Default: char('\n')

quote-character

The character used to quote fields within the CSV string. An instance of xs:string whose length is exactly one.
  • Type: xs:string

  • Default: '"'

trim-whitespace

Determines whether leading and trailing whitespace is removed from the content of fields.
  • Type: xs:boolean

  • Default: false

false Fields will be returned with any leading or trailing whitespace intact.
true Fields will be returned with leading or trailing whitespace removed, and all other whitespace preserved.

normalize-newlines

Determines whether CR and CRLF character sequences are treated as equivalent to NL characters.
  • Type: xs:boolean

  • Default: false

false No normalization takes place.
true The character sequences CR (U+000D (CARRIAGE RETURN) ) and CRLF (U+000D (CARRIAGE RETURN) , U+000A (NEWLINE) ) are treated as equivalent to the character NL (U+000A (NEWLINE) ), except when they appear within a quoted field. The normalization is done prior to recognition of row delimiters, and happens whether or not NL is used as the row delimiter.

An empty field is represented by a zero-length string. An empty field is deemed to exist when a field delimiter immediately follows either another field delimiter, or a row delimiter, or the start of $value; or when a row delimiter or the end of $value immediately follows a field delimiter.

A blank row is represented as an empty array (not as an array containing a single empty field). A blank row is deemed to exist when a row delimiter immediately follows either another row delimiter or the start of $value, after trimming of whitespace if the trim-whitespace option is true. No blank row occurs after the final row delimiter.

If $value is a zero-length string, the CSV is considered to contain no rows; while if $value consists of a single row delimiter, it is considered to contain a single blank row. The presence or absence of a final row delimiter generally has no effect on the result, except in the situation described in the previous paragraph where it causes a blank row to exist.

Error Conditions

A dynamic error [err:FOCV0001] occurs if the value of $csv does not conform to the required grammar.

A dynamic error [err:FOCV0002] occurs if the value of the field-delimiter, row-delimiter, or quote-character option is not a single character.

A dynamic error [err:FOCV0003] occurs if the same character is used for more than one of the field-delimiter, row-delimiter, and quote-character.

Notes

The default row delimiter is a single newline character U+000A (NEWLINE) . If the content is read using the unparsed-text function, alternative line endings such as CR and CRLF will have been normalized to a single newline. In other cases, this normalization can be achieved by setting the option normalize-newlines. This option does not affect CR or CRLF sequences occurring within quoted fields.

All fields are returned as xs:string values.

Quoted fields in the input are returned without the quotes.

The first row is not treated specially.

For more discussion of the returned data, see 14.4.3 Basic parsing of CSV to arrays.

Examples

Handling trivial input:

Expression:
csv-to-arrays(())
Result:
()
Expression:
csv-to-arrays("")
Result:
()
Expression:
csv-to-arrays(char('\n'))
Result:
[]
Expression:
csv-to-arrays(" ", { 'trim-whitespace': true() })
Result:
()
Expression:
csv-to-arrays(" ", { 'trim-whitespace': false() })
Result:
[" "]
Expression:
csv-to-arrays(` {char('\n')}`, { 'trim-whitespace': true() })
Result:
[]
Expression:
csv-to-arrays(` {char('\n')}`, { 'trim-whitespace': false() })
Result:
[" "]
Expression:
csv-to-arrays(`{char('\n')} `, { 'trim-whitespace': true() })
Result:
[]
Expression:
csv-to-arrays(`{char('\n')} `, { 'trim-whitespace': false() })
Result:
[], [" "]

Using newline separators:

Expression:
csv-to-arrays(
  `name,city{ char('\n') }` ||
  `Bob,Berlin{ char('\n') }` ||
  `Alice,Aachen{ char('\n') }`)
Result:
(
  [ "name", "city" ],
  [ "Bob", "Berlin" ],
  [ "Alice", "Aachen" ]
)
Expression:
let $CRLF := `{ char('\r') }{ char('\n') }`
return csv-to-arrays(
  `name,city{ $CRLF }` ||
  `Bob,Berlin{ $CRLF }` ||
  `Alice,Aachen{ $CRLF }`, 
  { "normalize-newlines": true() }
)
Result:
(
  [ "name", "city" ],
  [ "Bob", "Berlin" ],
  [ "Alice", "Aachen" ]
)

Quote handling:

Expression:
csv-to-arrays(
  string-join(
    (`"name","city"`, `"Bob","Berlin"`, `"Alice","Aachen"`),
    char('\n')
  )
)
Result:
(
  [ "name", "city" ],
  [ "Bob", "Berlin" ],
  [ "Alice", "Aachen" ]
)
Expression:
csv-to-arrays(
  `"name","city"{ char('\n') }` ||
  `"Bob ""The Exemplar"" Mustermann","Berlin"{ char('\n') }`
)
Result:
(
  [ "name", "city" ],
  [ 'Bob "The Exemplar" Mustermann', "Berlin" ]
)

Non-default record- and field-delimiters:

Expression:
csv-to-arrays(
  "name;city§Bob;Berlin§Alice;Aachen", 
  { "row-delimiter": "§", "field-delimiter": ";" }
)
Result:
(
  [ "name", "city" ],
  [ "Bob", "Berlin" ],
  [ "Alice", "Aachen" ]
)

Non-default quote character:

Expression:
csv-to-arrays(
  string-join(
    ("|name|,|city|", "|Bob|,|Berlin|"),
    char('\n')
  ), 
  { "quote-character": "|" }
)
Result:
(
  [ "name", "city" ],
  [ "Bob", "Berlin" ]
)

Trimming whitespace in fields:

Expression:
csv-to-arrays(
  string-join(
    ("name  ,city    ", "Bob   ,Berlin  ", "Alice ,Aachen  "),
    char('\n')
  ),
  { "trim-whitespace": true() }
)
Result:
(
  [ "name", "city" ],
  [ "Bob", "Berlin" ],
  [ "Alice", "Aachen" ]
)

14.4.5 Enhanced parsing of CSV data to maps and arrays

While fn:csv-to-arrays simply delivers the CSV content as a sequence of arrays, the fn:parse-csv function goes a step further and enables access to the data using column names. The column names may be taken either from the first row of the CSV data, or from data supplied by the caller in the options parameter.

14.4.6 fn:parse-csv

Changes in 4.0  

  1. New in 4.0  [Issues 413 1052 PRs 533 719 834 1066 19 March 2024]

Summary

Parses CSV data supplied as a string, returning the results in the form of a record containing information about the names in the header, as well as the data itself.

Signature
fn:parse-csv(
$value as xs:string?,
$options as map(*)? := {}
) as parsed-csv-structure-record
record parsed-csv-structure-record (
   columns as xs:string*,
   column-index as map(xs:string,xs:integer)?,
   rows as array(xs:string)*,
   get as function(xs:positiveInteger, (xs:positiveInteger | xs:string)) as xs:string?
)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The $value argument is CSV data, as defined in [RFC 4180], in the form of an xs:string value. The function first parses this string using fn:csv-to-arrays, and then further processes the result. The initial parsing is exactly as defined for fn:csv-to-arrays, and can be controlled using the same options. Additional options are available to control the way in which header information and column names are handled.

If $value is the empty sequence or a zero-length string, the function returns a parsed-csv-structure-record whose rows entry is the empty sequence.

The $options argument can be used to control the way in which the parsing takes place. The ·option parameter conventions· apply.

If the $options argument is omitted or is an empty sequence, the result is the same as calling the two-argument form with an empty map as the value of the $options argument.

The entries that may appear in the $options map are as follows:

record(
field-delimiter? as xs:string,
row-delimiter? as xs:string,
quote-character? as xs:string,
trim-whitespace? as xs:boolean,
normalize-newlines? as xs:boolean,
header? as item()*,
select-columns? as xs:positiveInteger*,
trim-rows? as xs:boolean
)
Key Value Meaning

field-delimiter

The character used to delimit fields within a record. An instance of xs:string whose length is exactly one.
  • Type: xs:string

  • Default: ","

row-delimiter

The character used to delimit rows within the CSV string. An instance of xs:string whose length is exactly one. Defaults to a single newline character (U+000A (NEWLINE) ).
  • Type: xs:string

  • Default: char('\n')

quote-character

The character used to quote fields within the CSV string. An instance of xs:string whose length is exactly one.
  • Type: xs:string

  • Default: '"'

trim-whitespace

Determines whether leading and trailing whitespace is removed from the content of unquoted fields.
  • Type: xs:boolean

  • Default: false

false Unquoted fields will be returned with any leading or trailing whitespace intact.
true Unquoted fields will be returned with leading or trailing whitespace removed, and all other whitespace preserved.

normalize-newlines

Determines whether CR and CRLF character sequences are treated as equivalent to NL characters.
  • Type: xs:boolean

  • Default: false

false No normalization takes place.
true The character sequences CR (U+000D (CARRIAGE RETURN) ) and CRLF (U+000D (CARRIAGE RETURN) , U+000A (NEWLINE) ) are treated as equivalent to the character NL (U+000A (NEWLINE) ), except when they appear within a quoted field. The normalization is done prior to recognition of row delimiters, and happens whether or not NL is used as the row delimiter.

header

Determines whether the first row of the CSV should be treated as a list of column names, or whether column names are being supplied by the caller. The value must either be a single boolean, or a sequence of one or more strings.
  • Type: item()*

  • Default: false

true Column names are taken from the first row of the CSV data.
false Column names are not available; all references to columns are by ordinal position.
xs:string+ Supplies explicit names for the columns. The Nth name in the list applies to the Nth column after any filtering or rearrangement. A zero-length string can be used when there is a column that requires no name.

select-columns

A sequence of integers indicating which columns to include and in which order. If this option is absent or empty, all columns are returned in their original order. For example, the value 1 to 4 indicates that the output contains the first, second, third, and fourth columns from the input, in order, while (1, 5, 4) indicates that the output contains three columns, taken from the first, fifth, and fourth columns of the input, in that order. An integer in the sequence is treated as the 1-based index of the column to include. Any other columns are dropped. If a particular row includes no field at the specified index, an empty field is included at the relevant position in the result. If an integer appears more than once then the result will include duplicated columns.
  • Type: xs:positiveInteger*

  • Default: ()

trim-rows

Determines whether all rows should be adjusted to contain the same number of fields. This option is ignored if select-columns is specified.
  • Type: xs:boolean

  • Default: false

false No padding or trimming of rows takes place, unless requested using the select-columns option.
true The number of fields in the first row (whether this be a header or a data row) determines the number of fields in every subsequent row; to achieve this, excess fields are removed, or additional zero-length fields are added.

The result of the function is a parsed-csv-structure-record, which is defined as follows:

Name Meaning

columns

This entry holds a sequence of strings containing column names. The content depends on the setting of the header entry in $options:

  • With "header":false() (which is the default), then the value is an empty sequence.

  • With "header":true(), the value is a sequence of strings taken from the first row of the data. The strings have leading and trailing whitespace trimmed, regardless of the value of the trim-whitespace option. The sequence of strings will potentially be truncated if the number-of-columns option is specified, and it will potentially be reordered if the filter-columns option is specified. Any strings that are zero-length or duplicated are retained as-is.

  • If the value of the header option is a sequence of strings, then the value is taken from the supplied sequence.

    The order of names is not adjusted based on the select-columns option; the supplied list of names is expected to refer to columns in the result, not to columns in the input.

  • Type: xs:string*

column-index

This entry holds a map from column names (as strings) to column positions (as 1-based positive integers). The content depends on the setting of the header entry in $options:

  • With "header":false() (which is the default), the value is an empty map.

  • With "header":true(), the map contains entries based on the contents of the first row of the data. The strings have leading and trailing whitespace trimmed, regardless of the value of the trim-whitespace option. Any string appearing in the header row that is non-zero-length and is not equal (using codepoint collation) to any previous string appearing in the header results in an entry pairing that string to its 1-based position in the header row.

    If the select-columns option is present then the entries are adjusted (or removed) to reflect their position in the adjusted data rows.

  • If the value of the header option is a sequence of strings, then the map contains entries based on the supplied value. Any string appearing in the option value that is non-zero-length and is not equal (using codepoint collation) to any previous string results in an entry pairing that string to its 1-based position in the sequence.

    The allocation of column numbers is not adjusted based on the select-columns option; the supplied list of names is expected to refer to columns in the result, not to columns in the input.

  • Type: map(xs:string,xs:integer)?

rows

This entry is a sequence of arrays of strings, holding the parsed rows of the CSV data. The format is the same as the result of the fn:csv-to-arrays function, except that the first row is omitted in the case where the header option is true. If there are no data rows in the CSV, the value will be an empty sequence.

  • Type: array(xs:string)*

get

A function providing ready access to a given field in a given row. The get function has signature:

function($row as xs:integer, $column as union(xs:string, xs:integer)) as xs:string?

The function takes two arguments: the first is an integer giving the row number (1-based), the second identifies a column either by its name or by its 1-based position.

Except in error cases (described below), the function call $csv?get($R, $C), where $C is an integer, returns the value of $csv?rows[$R] => array:get($C, fn{""}), and the function call $csv?get($R, $K), where $K is a string, returns the value of $csv?get($R, $csv?column-numbers($K)).

The properties of the function are as follows:

Name

Absent

Parameter names

($row, $col)

Signature

(xs:positiveInteger, (xs:positiveInteger | xs:string)) => xs:string?

Non-local variable bindings

None

Body

As described in the specification above

Errors

A dynamic error [err:FOCV0004] occurs if the supplied $key is a string and does not occur in the map of column names.

Rules

The function returns a field in the result.

The first argument $row selects a row within the sequence of rows returned as rows by position (one-based). If the value is out of range for the number of rows returned, the get function returns a zero-length string.

The second argument $col may be either an integer or a string.

If $col is an integer then it selects a field within the selected row by position (one-based). If the value is out of range for the number of fields in the selected row, the get function returns a zero-length string.

If $col is a string, the string is mapped to an integer using the map in the returned column-index. If the string is not present in this map, then an error is raised [err:FOCV0004]. The resulting integer is then used as if it were supplied as $col directly.

  • Type: function(xs:positiveInteger, (xs:positiveInteger | xs:string)) as xs:string?

Error Conditions

A dynamic error [err:FOCV0001] occurs if the value of $csv does not conform to the required grammar.

A dynamic error [err:FOCV0002] occurs if any of the options field-delimiter, row-delimiter, or quote-character is not a single character.

A dynamic error [err:FOCV0003] occurs if the same character is used for more than one of the options field-delimiter, row-delimiter, and quote-character.

Notes

The default row delimiter is a single newline character U+000A (NEWLINE) . If the content is read using the unparsed-text function, alternative line endings such as CR and CRLF will have been normalized to a single newline. In other cases, this normalization can be achieved by setting the normalize-newlines option.

All fields are returned as xs:string values.

Quoted fields in the input are returned without the quotes.

For more discussion of the returned data, see 14.4.5 Enhanced parsing of CSV data to maps and arrays.

Examples
Variables
let $display := fn($result) {
   (: tidy up the result for display (function items cannot be properly displayed) :)         
   map:put($result, "get", "(: function :)")
}

Default delimiters, no column headers:

Expression:
let $input := string-join(
  ("name,city", "Bob,Berlin", "Alice,Aachen"),
  char('\n')
)
let $result := parse-csv($input)
return (
  $result => $display(),
  $result?get(1, 2),
  $result?get(2, 2)
)
Result:
{
  "columns": (),
  "column-index": {},
  "rows": ([ "name", "city" ], [ "Bob", "Berlin" ], [ "Alice", "Aachen" ]),
  "get": "(: function :)"
},
"city",
"Berlin"

Default delimiters, column headers:

Expression:
let $input := string-join(
  ("name,city", "Bob,Berlin", "Alice,Aachen"),
  char('\n')
)
let $result := parse-csv($input, { "header": true() })
return (
  $result => $display(),
  $result?get(1, "name"),
  $result?get(2, "city")
)
Result:
{
  "columns": ("name", "city"),
  "column-index": { "name": 1, "city": 2 },
  "rows": ([ "Bob", "Berlin" ], [ "Alice", "Aachen" ]),
  "get": "(: function :)"
},
"Bob",
"Aachen"

Custom delimiters, no column headers:

Expression:
let $options := {
  "row-delimiter": "§", 
  "field-delimiter": ";", 
  "quote-character": "|"
}
let $input := "|name|;|city|§|Bob|;|Berlin|§|Alice|;|Aachen|"
let $result := parse-csv($csv, $options)
return (
  $result => $display(),
  $result?get(3, 1)
)
Result:
{
  "columns": (),
  "column-index": {},
  "rows": ([ "name", "city" ], [ "Bob", "Berlin" ], [ "Alice", "Aachen" ]),
  "get": "(: function :)"
},
"Alice"

Supplied column names:

Expression:
let $headers := ("Person", "Location")
let $options := { "header": $headers, "row-delimiter": ";" }
let $input := "Alice,Aachen;Bob,Berlin;"
let $parsed-csv := parse-csv($input, $options)
return (
  $parsed-csv => $display(), 
  $parsed-csv?get(2, "Location")
)
Result:
{
  "columns": ("Person", "Location"),
  "column-index": {"Person": 1, "Location": 2 },
  "rows": ([ "Alice", "Aachen" ], [ "Bob", "Berlin" ]),
  "get": "(: function :)"                  
},
"Berlin"

Filtering columns, with ragged input and header: true()

Expression:
let $input := string-join((
   "date,name,city,amount,currency,original amount,note",
   "2023-07-19,Bob,Berlin,10.00,USD,13.99",
   "2023-07-20,Alice,Aachen,15.00",
   "2023-07-20,Charlie,Celle,15.00,GBP,11.99,cake,not a lie"
), char('\n'))
let $options := { 
  "header": true(), 
  "select-columns": (2, 1, 4)
}
let $result := parse-csv($input, $options)
return (
  $result => $display(),
  $result?get(2, "city")
)
Result:
{
  "columns": ("name", "date", "amount"),
  "column-index": { "name": 1, "date": 2, "amount": 3 },
  "rows": (
    [ "Bob", "2023-07-19", "10.00" ],
    [ "Alice", "2023-07-20", "15.00" ],
    [ "Charlie", "2023-07-20", "15.00" ]
  ),
  "get": "(: function :)"                  
},
"Aachen"

Filtering columns, with supplied column map

Expression:
let $input := string-join((
  "2023-07-19,Bob,Berlin,10.00,USD,13.99",
  "2023-07-20,Alice,Aachen,15.00",
  "2023-07-20,Charlie,Celle,15.00,GBP,11.99,cake,not a lie"
), char('\n'))
let $options := { 
  "header": { "Person": 1, "Amount": 3 }, 
  "select-columns": (2, 1, 4)
}
let $result := parse-csv($input, $options)
return (
  $result => $display(),
  $result?get(2, "Person"),
  $result?get(2, "Amount")
)
Result:
{
  "columns": ("Person", "", "Amount"),
  "column-index": { "Person": 1, "Amount": 3 },
  "rows": ([ "Alice", "Aachen" ], [ "Bob", "Berlin" ]),
  "get": "(: function :)"                  
},
"Alice",
"15.00"

Specifying the number of columns explicitly, with header: false()

Expression:
let $input := string-join((
  "date,      name,     amount,    currency,   original amount",               
  "2023-07-19,Bob,      10.00,     USD,        13.99",
  "2023-07-20,Alice,    15.00",
  "2023-07-20,Charlie,  15.00,     GBP,        11.99,             extra data"
), char('\n'))
let $options := {
  "header": false(), 
  "select-columns": 1 to 5, 
  "trim-whitespace":true()
}
let $result := parse-csv($input, $options)
return (
  $result => $display(),
  $result?get(4, 3)
)
Result:
{
  "columns": (),
  "column-index": {},
  "rows": (
    [ "date", "name", "amount", "currency", "original amount" ],
    [ "2023-07-19", "Bob", "10.00", "USD", "13.99" ],
    [ "2023-07-20", "Alice", "15.00", "", "" ],
    [ "2023-07-20", "Charlie", "15.00", "GBP", "11.99" ]
  ),
  "get": "(: function :)"                  
},
"15:00"

Specifying the number of columns with a number and header: true()

Expression:
let $input := string-join((
  "date,name,city,amount,currency,original amount,note",               
  "2023-07-19,Bob,Berlin,10.00,USD,13.99",
  "2023-07-20,Alice,Aachen,15.00",
  "2023-07-20,Charlie,Celle,15.00,GBP,11.99,cake,not a lie"
), char('\n'))
let $options := { "header": true(), "select-columns": 1 to 6 }
let $result := parse-csv($input, $options)
return (
  $result => $display(),
  $result?get(3, "original amount")
)
Result:
{
  "columns": ("date", "name", "city", "amount", "currency", "original amount"),
  "column-index": {
    "date": 1, "name": 2, "city": 3, "amount": 4,
    "currency": 5, "original amount": 6
  },
  "rows": (
    [ "2023-07-19", "Bob", "Berlin", "10.00", "USD", "13.99"],
    [ "2023-07-20", "Alice", "Aachen", "15.00", "", ""],
    [ "2023-07-20", "Charlie", "Celle", "15.00", "GBP", "11.99"]
  ),
  "get": "(: function :)"                  
}, "11.99"

14.4.7 Representing CSV data as XML

The fn:csv-to-xml function returns an XDM node tree representing the CSV data. Following is a CSV text and the XML serialization of the corresponding node tree.

Name,Date,Amount
Alice,2023-07-14,1.23
Bob,2023-07-14,2.34
<csv xmlns="http://www.w3.org/2005/xpath-functions">
  <columns>
    <column>Name</column>
    <column>Date</column>
    <column>Amount</column>
  </columns>
  <rows>
    <row>
      <field column="Name">Alice</field>
      <field column="Date">2023-07-14</field>
      <field column="Amount">1.23</field>
    </row>
    <row>
      <field column="Name">Bob</field>
      <field column="Date">2023-07-14</field>
      <field column="Amount">2.34</field>
    </row>
  </rows>
</csv>

If column names were not extracted, then implementations should not include the <header> element, and <field> elements should not have the column attribute:

<csv xmlns="http://www.w3.org/2005/xpath-functions">
  <rows>
    <row>
      <field>Name</field>
      <field>Date</field>
      <field>Amount</field>
    </row>
    <row>
      <field>Alice</field>
      <field>2023-07-14</field>
      <field>1.23</field>
    </row>
    <row>
      <field>Bob</field>
      <field>2023-07-14</field>
      <field>2.34</field>
    </row>
  </rows>
</csv>

An XSD 1.0 schema for the XML representation is provided in C.3 Schema for the result of fn:csv-to-xml.

14.4.8 fn:csv-to-xml

Changes in 4.0  

  1. New in 4.0  [Issues 413 1052 PRs 533 719 834 1066]

Summary

Parses CSV data supplied as a string, returning the results as an XML document, as described by 14.4.7 Representing CSV data as XML.

Signature
fn:csv-to-xml(
$value as xs:string?,
$options as map(*)? := {}
) as element(fn:csv)?
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.

Rules

The arguments have the same meaning, and are subject to the same constraints, as the arguments of fn:parse-csv.

If $value is the empty sequence, the function returns the empty sequence.

In other cases, the effect of the function is equivalent to the result of the following XQuery expression (where $options is an empty map if the argument is not supplied):

let $parsedCSV := parse-csv($value, $options)
let $colNames := $parsedCSV?columns
return <csv xmlns="http://www.w3.org/2005/xpath-functions"> {
  if (exists($colNames)) {
    <columns>{ $colNames ! <column>{ . }</column> }</columns>
  },
  <rows>{
    for $row in $parsedCSV?rows
    return <row>{
      for member $field at $col in $row
      return <field>{
        if ($colnames[$col]) {
          attribute column { $colnames[$col] }
        },
        $field
      }</field>
    }</row>
  }</rows> 
}</csv>

The namespace prefix used in the names of elements (or its absence) is ·implementation-dependent·.

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.3 Schema for the result of fn:csv-to-xml.

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.

The returned element node has no parent node.

Error Conditions

See fn:parse-csv.

Examples
Variables
let $crlf := char('\r') || char('\n')
let $csv-string := `name,city{ $crlf }Bob,Berlin{ $crlf }Alice,Aachen{ $crlf }`
let $csv-uneven-cols := concat(
  `date,name,city,amount,currency,original amount,note{ $crlf }`,
  `2023-07-19,Bob,Berlin,10.00,USD,13.99{ $crlf }`,
  `2023-07-20,Alice,Aachen,15.00{ $crlf }`,
  `2023-07-20,Charlie,Celle,15.00,GBP,11.99,cake,not a lie{ $crlf }`
)

An empty CSV with default column extraction (false):

Expression:
csv-to-xml(())
Result:
()
Expression:
csv-to-xml("")
Result:
<csv xmlns="http://www.w3.org/2005/xpath-functions">
  <rows/>
</csv>
Expression:
csv-to-xml(char('\n'))
Result:
<csv xmlns="http://www.w3.org/2005/xpath-functions">
  <rows>
    <row/>
  </rows>
</csv>

An empty CSV with header extraction:

Expression:
csv-to-xml("", { "header": true() })
Result:
<csv xmlns="http://www.w3.org/2005/xpath-functions">
  <columns/>
  <rows/>
</csv>

An empty CSV with explicit column names:

Expression:
csv-to-xml("", { "header": ("name", "", "city") })
Result:
<csv xmlns="http://www.w3.org/2005/xpath-functions">
  <columns>
    <column>name</column>
    <column/>
    <column>city</column>
  </columns>
  <rows/>
</csv>

With defaults for delimiters and quotes, recognizing headers:

Expression:
csv-to-xml($csv-string, { "header": true() })
Result:
<csv xmlns="http://www.w3.org/2005/xpath-functions">
  <columns>
    <column>name</column>
    <column>city</column>
  </columns>
  <rows>
    <row>
      <field column="name">Bob</field>
      <field column="city">Berlin</field>
    </row>
    <row>
      <field column="name">Alice</field>
      <field column="city">Aachen</field>
    </row>
  </rows>
</csv>

Filtering columns

Expression:
csv-to-xml(
  $csv-uneven-cols, 
  { "header": true(), "select-columns": (2, 1, 4) }
)
Result:
<csv xmlns="http://www.w3.org/2005/xpath-functions">
  <columns>
    <column>name</column>
    <column>date</column>
    <column>amount</column>
  </columns>
  <rows>
    <row>
      <field column="name">Bob</field>
      <field column="date">2023-07-19</field>
      <field column="amount">10.00</field>
    </row>
    <row>
      <field column="name">Alice</field>
      <field column="date">2023-07-20</field>
      <field column="amount">15.00</field>
    </row>
    <row>
      <field column="name">Charlie</field>
      <field column="date">2023-07-20</field>
      <field column="amount">15.00</field>
    </row>
  </rows>
</csv>

Ragged rows

Expression:
csv-to-xml(
  $csv-uneven-cols, 
  { "header": true() }
)
Result:
<csv xmlns="http://www.w3.org/2005/xpath-functions">
  <columns>
    <column>date</column>
    <column>name</column>
    <column>city</column>
    <column>amount</column>
    <column>currency</column>
    <column>original amount</column>
    <column>note</column>
  </columns>
  <rows>
    <row>
      <field column="date">2023-07-19</field>
      <field column="name">Bob</field>
      <field column="city">Berlin</field>
      <field column="amount">10.00</field>
      <field column="currency">USD</field>
      <field column="original amount">13.99</field>
    </row>
    <row>
      <field column="date">2023-07-20</field>
      <field column="name">Alice</field>
      <field column="city">Aachen</field>
      <field column="amount">15.00</field>
    </row>
    <row>
      <field column="date">2023-07-20</field>
      <field column="name">Charlie</field>
      <field column="city">Celle</field>
      <field column="amount">15.00</field>
      <field column="currency">GBP</field>
      <field column="original amount">11.99</field>
      <field column="note">cake</field>
      <field>not a lie</field>
    </row>
  </rows>
</csv>

Trimming rows to constant width

Expression:
csv-to-xml(
  $csv-uneven-cols, 
  { "header": true(), "trim-rows": true() }
)
Result:
<csv xmlns="http://www.w3.org/2005/xpath-functions">
  <columns>
    <column>date</column>
    <column>name</column>
    <column>city</column>
    <column>amount</column>
    <column>currency</column>
    <column>original amount</column>
    <column>note</column>
  </columns>
  <rows>
    <row>
      <field column="date">2023-07-19</field>
      <field column="name">Bob</field>
      <field column="city">Berlin</field>
      <field column="amount">10.00</field>
      <field column="currency">USD</field>
      <field column="original amount">13.99</field>
      <field column="note"/>
    </row>
    <row>
      <field column="date">2023-07-20</field>
      <field column="name">Alice</field>
      <field column="city">Aachen</field>
      <field column="amount">15.00</field>
      <field column="currency"/>
      <field column="original amount"/>
      <field column="note"/>
    </row>
    <row>
      <field column="date">2023-07-20</field>
      <field column="name">Charlie</field>
      <field column="city">Celle</field>
      <field column="amount">15.00</field>
      <field column="currency">GBP</field>
      <field column="original amount">11.99</field>
      <field column="note">cake</field>
    </row>
  </rows>
</csv>

Specifying a fixed number of columns

Expression:
csv-to-xml(
  $csv-uneven-cols, 
  { "header": true(), "select-columns": 1 to 6 }
)
Result:
<csv xmlns="http://www.w3.org/2005/xpath-functions">
  <columns>
    <column>date</column>
    <column>name</column>
    <column>city</column>
    <column>amount</column>
    <column>currency</column>
    <column>original amount</column>
  </columns>
  <rows>
    <row>
      <field column="date">2023-07-19</field>
      <field column="name">Bob</field>
      <field column="city">Berlin</field>
      <field column="amount">10.00</field>
      <field column="currency">USD</field>
      <field column="original amount">13.99</field>
    </row>
    <row>
      <field column="date">2023-07-20</field>
      <field column="name">Alice</field>
      <field column="city">Aachen</field>
      <field column="amount">15.00</field>
      <field column="currency"/>
      <field column="original amount"/>
    </row>
    <row>
      <field column="date">2023-07-20</field>
      <field column="name">Charlie</field>
      <field column="city">Celle</field>
      <field column="amount">15.00</field>
      <field column="currency">GBP</field>
      <field column="original amount">11.99</field>
    </row>
  </rows>
</csv>

14.4.9 Illustrative examples of processing CSV data

The following examples illustrate more complex applications making use of CSV parsing functions.

A variable $crlf is assumed to be in scope representing the CRLF string:

let $crlf := fn:char(0x0D)||fn:char(0x0A)
Example: Converting a CSV into an HTML-style table using fn:parse-csv

Direct conversion is a matter of iterating across the records and fields to generate <tr> and <td> elements.

Using XQuery:

let $csv := fn:parse-csv(`name,city{ $crlf }Bob,Berlin`)
return <table>
  <thead>{
    for $column in $csv?columns?fields
    return <th>{ $column }</th>
  }</thead>
  <tbody>{
    for $row in $csv?rows
    return <tr>{ for $field in $row?fields return <td>{ $field }</td> }</tr>
  }</tbody>
</table>

Using XSLT:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:eg="http://example.org/eg"
  xmlns:array="http://www.w3.org/2005/xpath-functions/array"
  exclude-result-prefixes="eg array"
  version="4.0">
  <xsl:output method="xml" indent="true"/>

  <xsl:template match="." mode="csv-th" expand-text="true">
    <th>{ . }</th>
  </xsl:template>

  <xsl:template match="." mode="csv-td" expand-text="true">
    <td>{ . }</td>
  </xsl:template>

  <xsl:template match="." mode="csv-tr">
    <tr>
      <xsl:apply-templates select=".?fields" mode="csv-td"/>
    </tr>
  </xsl:function>

  <xsl:template name="xsl:initial-template">
    <xsl:variable name="csv" select="parse-csv(`name,city{ $crlf }Bob,Berlin`)"/>
    <table>
      <thead>
        <tr>
          <xsl:apply-templates select="$csv?columns?fields" mode="csv-th"/>
        </tr>
      </thead>
      <tbody>
        <xsl:apply-templates select="$csv?rows" mode="csv-tr"/>
      </tbody>
    </table>
  </xsl:template>
</xsl:stylesheet>
Example: Converting a CSV into an HTML-style table using fn:csv-to-xml

The fn:csv-to-xml function makes these kinds of conversion-to-XML-table tasks simpler by providing a simple XML represenation of the data. Here, in XQuery:

let $csv := csv-to-xml(`name,city{ $crlf }Bob,Berlin`)
return <table>
  <thead>{
    for $column in $csv/csv/columns/column
    return <th>{ $column }</th>
  }</thead>
  <tbody>{
    for $row in $csv/csv/rows/row
    return <tr>{ for $field in $row/field return <td>{ $field }</td> }</tr>
  }</tbody>
</table>

And in XSLT:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:fn="http://www.w3.org/2005/xpath-functions"
  exclude-result-prefixes="fn"
  version="4.0">
  <xsl:output method="xml" indent="true"/>

  <xsl:template match="fn:column" expand-text="true">
    <th>{ . }</th>
  </xsl:template>

  <xsl:template match="fn:field" expand-text="true">
    <td>{ . }</td>
  </xsl:template>

  <xsl:template match="fn:row">
    <tr>
      <xsl:apply-templates/>
    </tr>
  </xsl:function>

  <xsl:template match="fn:columns">
    <thead>
      <tr>
        <xsl:apply-templates/>
      </tr>
    </thead>
  </xsl:function>

  <xsl:template match="fn:rows">
    <tbody>
      <xsl:apply-templates/>
    </tbody>
  </xsl:function>

  <xsl:template match="fn:csv">
    <table>
      <xsl:apply-templates/>
    </table>
  </xsl:template>

  <xsl:template name="xsl:initial-template">
    <xsl:apply-templates select="fn:csv-to-xml(`name,city{ $crlf }Bob,Berlin`)"/>
  </xsl:template>
</xsl:stylesheet>

14.5 Functions on Invisible XML

This section describes functions that support [Invisible XML] parsing.

Invisible XML defines a BNF-like language for specifying grammars, together with a mapping from sentences in that grammar to an XML representation. By defining an Invisible XML grammar, a great variety of non-XML data formats can be manipulated as if they were XML. The function fn:invisible-xml takes a grammar as input, and returns a function which can be used for parsing data instances and converting them to XML node trees.

14.5.1 fn:invisible-xml

Changes in 4.0  

  1. New in 4.0  [Issues 238 991 1281 1404 PRs 791 1256 1282 1405]

Summary

Creates an Invisible XML parser for a grammar.

Signature
fn:invisible-xml(
$grammar as (xs:string | element(ixml))? := (),
$options as map(*)? := {}
) as fn(xs:string) as document-node()
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Conceptually, an [Invisible XML] processor takes two arguments: a grammar and an input string. The grammar is a description of some format and the parser will attempt to interpret the input string according to that description. The parser returns an XML representation of the input string as parsed by the provided grammar. If parsing fails, it returns an XML representation that indicates an error occurred and may provide additional error information.

If the function is called twice with the same arguments, it is ·nondeterministic with respect to node identity·.

For example, the following grammar describes a date as consisting of a year, a month, and a day. Each are a sequence of digits and they are separated by hyphens:

 date = year, -'-', month, -'-', day .
 year = d, d, d, d .
month = '0', d | '1', ['0'|'1'|'2'] .
  day = ['0'|'1'|'2'], d | '3', ['0'|'1'] .
   -d = ['0'-'9'] .

Using this grammar to parse “2023-10-31” will produce:

<date><year>2023</year><month>10</month><day>31</day></date>

Using this grammar to parse “2023-10-32” will produce something like this:

<fail xmlns:ixml='http://invisiblexml.org/NS' ixml:state='failed'>
  <line>1</line>
  <column>10</column>
  <pos>9</pos>
  <unexpected>3</unexpected>
  <permitted>'3', ['0'; '1'; '2']</permitted>
</fail>

The exact format of the error output will vary between implementations. The only required part of the output is the ixml:state attribute that contains the value failed.

Note:

Careful readers will observe that the example grammar will parse “2023-00-00” as a date. The grammar could easily be extended to exclude the “00” forms for month and day, but this is only intended to be an illustrative example.

The fn:invisible-xml function takes a grammar and returns a function that can be used to parse input strings. In practice, constructing a parser from a grammar may be an expensive operation. Returning a parsing function makes it easy to efficiently reuse a parser.

The provided grammar must be a string conforming to the Invisible XML specification grammar or an XML representation of such a grammar.

The following options are available. The ·option parameter conventions· apply.

record(
fail-on-error? as xs:boolean
)
Key Meaning

fail-on-error

Raise an error if the parse function fails
  • Type: xs:boolean

  • Default: false

Additional, ·implementation-defined· options may be available, for example, to control aspects of the XML serialization, to specify the grammar start symbol, or to produce output formats other than XML.

If $grammar is the empty sequence, a parser is returned for the Invisible XML specification grammar. This should be the same grammar that the implementation uses to parse iXML grammars. If $grammar is not empty, it must be a valid Invisible XML grammar. If it is not, fn:invisible-xml raises err:FOIX0001.

The parsing function that is returned behaves as follows:

  1. It takes a string as input and returns a document node as its result.

  2. It is ·nondeterministic with respect to node identity· (that is, if it is called twice with the same input string, it may or may not return the same document node each time).

If the fail-on-error option is true(), the parsing function will raise err:FOIX0002 if the input provided cannot be parsed successfully. Otherwise, it returns an XML representation of the error (rooted at a document node) as described by the [Invisible XML] specification.

Examples
Expression:
invisible-xml("S=A. A='a'.")("a")
Result:
<S><A>a</A></S>
Expression:
let $parser := invisible-xml("S=A. A='a'.")
let $result := $parser("b")
return $result/*/@*:state = 'failed'
Result:
true()

(The returned document contains information about the error in the parsed string.)

Expression:
let $parser := invisible-xml("S=A. A='a'.", { "fail-on-error": true() })
let $result := $parser("b")
return $result
Result:

Raises error FOIX0002.

15 Context functions

The following functions are defined to obtain information from the static or dynamic context.

Function Meaning
fn:position Returns the context position from the dynamic context.
fn:last Returns the context size from the dynamic context.
fn:current-dateTime Returns the current date and time (with timezone).
fn:current-date Returns the current date.
fn:current-time Returns the current time.
fn:implicit-timezone Returns the value of the implicit timezone property from the dynamic context.
fn:default-collation Returns the value of the default collation property from the dynamic context.
fn:default-language Returns the value of the default language property from the dynamic context.
fn:static-base-uri This function returns the value of the executable base URI property from the dynamic context.

15.1 fn:position

Summary

Returns the context position from the dynamic context.

Signature
fn:position() as xs:integer
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

Rules

Returns the context position from the dynamic context. (See Section C.2 Dynamic Context Components XP31.)

Error Conditions

A type error is raised [err:XPDY0002]XP if the context value is absentDM40.

15.2 fn:last

Summary

Returns the context size from the dynamic context.

Signature
fn:last() as xs:integer
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

Rules

Returns the context size from the dynamic context. (See Section C.2 Dynamic Context Components XP31.)

Error Conditions

A type error is raised [err:XPDY0002]XP if the context size is absentDM40.

Notes

Under most circumstances, the context size is absent only if the context value is absent. However, XSLT 3.0 with streaming defines situations in which the context value and context position are known, but the context size is unknown.

Examples
Expression Result
(1 to 20)[last() - 1]
19

15.3 fn:current-dateTime

Summary

Returns the current date and time (with timezone).

Signature
fn:current-dateTime() as xs:dateTimeStamp
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

Returns the current dateTime (with timezone) from the dynamic context. (See Section C.2 Dynamic Context Components XP31.) This is an xs:dateTime that is current at some time during the evaluation of a query or transformation in which fn:current-dateTime is executed.

This function is ·deterministic·. The precise instant during the query or transformation represented by the value of fn:current-dateTime() is ·implementation-dependent·.

If the implementation supports data types from XSD 1.1 then the returned value will be an instance of xs:dateTimeStamp. Otherwise, the only guarantees are that it will be an instance of xs:dateTime and will have a timezone component.

Notes

The returned xs:dateTime will always have an associated timezone, which will always be the same as the implicit timezone in the dynamic context

Examples

current-dateTime() returns an xs:dateTimeStamp corresponding to the current date and time. For example, a call of current-dateTime() might return 2004-05-12T18:17:15.125Z corresponding to the current time on May 12, 2004 in timezone Z.

15.4 fn:current-date

Summary

Returns the current date.

Signature
fn:current-date() as xs:date
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

Returns xs:date(fn:current-dateTime()). This is an xs:date (with timezone) that is current at some time during the evaluation of a query or transformation in which fn:current-date is executed.

This function is ·deterministic·. The precise instant during the query or transformation represented by the value of fn:current-date is ·implementation-dependent·.

Notes

The returned date will always have an associated timezone, which will always be the same as the implicit timezone in the dynamic context

Examples

current-date() returns an xs:date corresponding to the current date. For example, a call of current-date() might return 2004-05-12+01:00.

15.5 fn:current-time

Summary

Returns the current time.

Signature
fn:current-time() as xs:time
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

Returns xs:time(fn:current-dateTime()). This is an xs:time (with timezone) that is current at some time during the evaluation of a query or transformation in which fn:current-time is executed.

This function is ·deterministic·. The precise instant during the query or transformation represented by the value of fn:current-time() is ·implementation-dependent·.

Notes

The returned time will always have an associated timezone, which will always be the same as the implicit timezone in the dynamic context

Examples

current-time() returns an xs:time corresponding to the current time. For example, a call of current-time() might return 23:17:00.000-05:00.

15.6 fn:implicit-timezone

Summary

Returns the value of the implicit timezone property from the dynamic context.

Signature
fn:implicit-timezone() as xs:dayTimeDuration
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

Returns the value of the implicit timezone property from the dynamic context. Components of the dynamic context are described in Section C.2 Dynamic Context Components XP31.

15.7 fn:default-collation

Summary

Returns the value of the default collation property from the dynamic context.

Signature
fn:default-collation() as xs:string
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.

Rules

Returns the value of the default collation property from the dynamic context context. Components of the dynamic context are described in [TITLE OF XP40 SPEC, TITLE OF id-eval-context SECTION]XP40.

Notes

The default collation property can never be absent. If it is not explicitly defined, a system defined default can be invoked. If this is not provided, the Unicode codepoint collation (http://www.w3.org/2005/xpath-functions/collation/codepoint) is used.

In most cases, the default collation is known statically, and a call on this function can therefore be pre-evaluated during static analysis. The only notable exception is when a call on default-collation() is used to define the default value of a parameter to a user-defined function. In this case it is interpreted as a reference to the default collation in the context of the relevant function call, which may differ from the default collation of the function definition.

15.8 fn:default-language

Summary

Returns the value of the default language property from the dynamic context.

Signature
fn:default-language() as xs:language
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default language.

Rules

Returns the value of the default language property from the dynamic context. Components of the dynamic context are described in Section 2.1.2 Dynamic Context XP31.

Notes

The default language property can never be absent. The functions fn:format-integer, fn:format-date, fn:format-time, and fn:format-dateTime are defined to use the default language if no explicit language is supplied. The default language may play a role in selection of a default collation, but this is not a requirement.

15.9 fn:static-base-uri

Summary

This function returns the value of the executable base URI property from the dynamic context.

Signature
fn:static-base-uri() as xs:anyURI?
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base URI.

Rules

The function (despite its name) returns the value of the executable base URI property from the dynamic context. If the property is absent, the empty sequence is returned.

Components of the dynamic context are described in Section 2.2.2 Dynamic ContextXP40 .

Notes

The executable base URI will in many cases be the same as the static base URI in the static context. However, XQuery and XSLT give an implementation freedom to use different base URIs during the static analysis phase and the dynamic evaluation phase, that is, for retrieval of compile-time and run-time resources respectively. This is appropriate when the implementation allows the output of static analysis (a “compiled” query or stylesheet) to be deployed for execution to a different location from the one where static analysis took place. In this situation, the fn:static-base-uri function should return a URI suitable for locating resources needed during dynamic evaluation.

If a call on the fn:static-base-uri function appears within the expression used to define the value of an optional parameter to a user-defined function, then the value supplied to the function (if the argument is omitted) will be the executable base URI from the dynamic context of the function caller. This allows such a function to resolve relative URIs supplied in other parameters to the same function.

16 Higher-order functions

16.1 Functions on functions

The functions included in this section operate on function items, that is, values referring to a function.

[Definition] Functions that accept functions among their arguments, or that return functions in their result, are described in this specification as higher-order functions. Some host languages may exclude higher-order functions from the set of functions that they support, or may include such functions in an optional conformance feature.

Note:

Some functions such as fn:parse-json allow the option of supplying a callback function for example to define exception behavior. Where this is not essential to the use of the function, the function has not been classified as higher-order for this purpose; in applications where function items cannot be created, these particular options will not be available.

Function Meaning
fn:function-lookup Returns a function item having a given name and arity, if there is one.
fn:function-name Returns the name of the function identified by a function item.
fn:function-arity Returns the arity of the function identified by a function item.
fn:function-annotations Returns the annotations of the function item.

16.1.1 fn:function-lookup

Summary

Returns a function item having a given name and arity, if there is one.

Signature
fn:function-lookup(
$name as xs:QName,
$arity as xs:integer
) as fn(*)?
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

Rules

A call to fn:function-lookup starts by looking for a function definitionXP40 in the named functions component of the dynamic context (specifically, the dynamic context of the call to fn:function-lookup), using the expanded QName supplied as $name and the arity supplied as $arity. There can be at most one such function definition.

If no function definition can be identified (by name and arity), then an empty sequence is returned.

If a function definition is identified, then a function item is obtained from the function definition using the same rules as for evaluation of a named function reference (see Section 4.5.2.4 Named Function ReferencesXP40). The captured context of the returned function item (if it is context dependent) is the static and dynamic context of the call on fn:function-lookup.

If the arguments to fn:function-lookup identify a function that is present in the static context of the function call, the function will always return the same function that a static reference to this function would bind to. If there is no such function in the static context, then the results depend on what is present in the dynamic context, which is ·implementation-defined·.

Error Conditions

An error is raised if the identified function depends on components of the static or dynamic context that are not present, or that have unsuitable values. For example [err:XPDY0002]XP is raised for the call function-lookup(xs:QName("fn:name"), 0) if the context value is absent, and [err:FODC0001] is raised for the call function-lookup(xs:QName("fn:id"), 1) if the context value is not a single node in a tree that is rooted at a document node. The error that is raised is the same as the error that would be raised by the corresponding function if called with the same static and dynamic context.

Notes

This function can be useful where there is a need to make a dynamic decision on which of several statically known functions to call. It can thus be used as a substitute for polymorphism, in the case where the application has been designed so several functions implement the same interface.

The function can also be useful in cases where a query or stylesheet module is written to work with alternative versions of a library module. In such cases the author of the main module might wish to test whether an imported library module contains or does not contain a particular function, and to call a function in that module only if it is available in the version that was imported. A static call would cause a static error if the function is not available, whereas getting the function using fn:function-lookup allows the caller to take fallback action in this situation.

If the function that is retrieved by fn:function-lookup is ·context-dependent·, that is, if it has dependencies on the static or dynamic context of its caller, the context that applies is the static and/or dynamic context of the call to the fn:function-lookup function itself. The context thus effectively forms part of the closure of the returned function. In practice this applies only where the target of fn:function-lookup is a built-in function, because user-defined functions never depend on the static or dynamic context of the function call. The rule applies recursively, since fn:function-lookup is itself a context-dependent built-in function.

However, the static and dynamic context of the call to fn:function-lookup may play a role even when the selected function definition is not itself context dependent, if the expressions used to establish default parameter values are context dependent.

The function identity is determined in the same way as for a named function reference. Specifically, if there is no context dependency, two calls on fn:function-lookup with the same name and arity must return the same function.

These specifications do not define any circumstances in which the dynamic context will contain functions that are not present in the static context, but neither do they rule this out. For example an API may provide the ability to add functions to the dynamic context. Equally, these specifications do not define any mechanism for creating context-dependent functions other than the built-in context-dependent functions, but neither do they rule out the existence of such functions.

The mere fact that a function exists and has a name does not of itself mean that the function is present in the dynamic context. For example, functions obtained through use of the fn:load-xquery-module function are not added to the dynamic context.

Examples
Expression:

function-lookup(xs:QName('fn:substring'), 2)('abcd', 2)

Result:
'bcd'

The expression (fn:function-lookup(xs:QName('xs:dateTimeStamp'), 1), xs:dateTime#1)[1] ('2011-11-11T11:11:11Z') returns an xs:dateTime value set to the specified date, time, and timezone; if the implementation supports XSD 1.1 then the result will be an instance of the derived type xs:dateTimeStamp. The query is written to ensure that no failure occurs when the implementation does not recognize the type xs:dateTimeStamp.

The expression

let $f := function-lookup(xs:QName('zip:binary-entry'), 2)
return if (exists($f)) then $f($source, $entry) else ()
returns the result of calling zip:binary-entry($source, $entry) if the function is available, or an empty sequence otherwise.

16.1.2 fn:function-name

Summary

Returns the name of the function identified by a function item.

Signature
fn:function-name(
$function as fn(*)
) as xs:QName?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $function refers to a named function, fn:function-name($func) returns the name of that function.

Otherwise ($function refers to an anonymous function), fn:function-name($function) returns an empty sequence.

The prefix part of the returned QName is ·implementation-dependent·.

Examples
Expression:

function-name(substring#2)

Result:
QName("http://www.w3.org/2005/xpath-functions", "fn:substring")

(The namespace prefix of the returned QName is not predictable.)

Expression:

function-name(fn($node) { count($node/*) })

Result:
()

16.1.3 fn:function-arity

Summary

Returns the arity of the function identified by a function item.

Signature
fn:function-arity(
$function as fn(*)
) as xs:integer
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The fn:function-arity function returns the arity (number of arguments) of the function identified by $function.

Examples
Expression:

function-arity(substring#2)

Result:
2
Expression:

function-arity(fn($node) { name($node) })

Result:
1
Expression:
let $initial := substring(?, 1, 1)
return function-arity($initial)
Result:
1

16.1.4 fn:function-annotations

Changes in 4.0  

  1. Changes the function to return a sequence of key-value pairs rather than a map.  [Issue 36 PR 710 17 September 2023]

  2. Changes the function to return a sequence of key-value pairs rather than a map.  [Issue 1391 PR 1393 19 August 2024]

Summary

Returns the annotations of the function item.

Signature
fn:function-annotations(
$function as fn(*)
) as record(key as xs:QName, value as xs:anyAtomicType*)*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The fn:function-annotations function returns the annotations of $function as a sequence of (key, value) pairs. Note that several annotations on a function can share the same name. The order of the annotations is retained.

The result is a sequence of maps, each being an instance of record(key as xs:QName, value as xs:anyAtomicType*). If a function (for example, a built-in function) has no annotations, the result of the function is an empty sequence.

For each annotation, a map is returned, with two entries. One entry has the key "key" as an xs:string, with the associated value being the name of the annotation as an xs:QName. The other has the key "value" as an xs:string, with the associated value being the value of the annotation as a sequence of atomic items. If the annotation has no values, the associated value is an empty sequence.

Notes

The type of the result is the same as the type of the first argument to the map:of-pairs function. This means that in the common case where the annotation names are all unique, the result of the function can readily be converted into a map by calling map:of-pairs.

Examples
Expression:
function-annotations(true#0)
Result:
()
Expression:
declare %private function local:inc($c) { $c + 1 };
function-annotations(local:inc#1)
Result:
{ "key": xs:QName("http://www.w3.org/2012/xquery", "private"),
  "value": () 
}
Expression:
declare %private %variadic 
        function local:sum($c as xs:integer*) { sum($c) };
function-annotations(local:sum#3)
Result:
{ "key": xs:QName("http://www.w3.org/2012/xquery", "private"),
  "value": () 
},
{ "key": xs:QName("http://www.w3.org/2012/xquery", "variadic"),
  "value": () 
}
Expression:
let $old := %local:deprecated('0.1', '0.2') fn() {}
let $ann := function-annotations($old)
return map:of-pairs($ann)
Result:
{ xs:QName("http://www.w3.org/2005/xquery-local-functions", "deprecated"):
    ("0.1", "0.2") 
}

16.2 Basic higher-order functions

The following functions take function items as an argument.

Function Meaning
fn:apply Makes a dynamic call on a function with an argument list supplied in the form of an array.
fn:chain Applies a sequence of functions starting with an initial input.
fn:do-until Processes a supplied value repeatedly, continuing when some condition is false, and returning the value that satisfies the condition.
fn:every Returns true if every item in the input sequence matches a supplied predicate.
fn:filter Returns those items from the sequence $input for which the supplied function $predicate returns true.
fn:fold-left Processes the supplied sequence from left to right, applying the supplied function repeatedly to each item in turn, together with an accumulated result value.
fn:fold-right Processes the supplied sequence from right to left, applying the supplied function repeatedly to each item in turn, together with an accumulated result value.
fn:for-each Applies the function item $action to every item from the sequence $input in turn, returning the concatenation of the resulting sequences in order.
fn:for-each-pair Applies the function item $action to successive pairs of items taken one from $input1 and one from $input2, returning the concatenation of the resulting sequences in order.
fn:highest Returns those items from a supplied sequence that have the highest value of a sort key, where the sort key can be computed using a caller-supplied function.
fn:index-where Returns the positions in an input sequence of items that match a supplied predicate.
fn:lowest Returns those items from a supplied sequence that have the lowest value of a sort key, where the sort key can be computed using a caller-supplied function.
fn:partition Partitions a sequence of items into a sequence of non-empty arrays containing the same items, starting a new partition when a supplied condition is true.
fn:scan-left Produces the complete (ordered) sequence of all partial results from every new value the accumulator is assigned to during the evaluation of fn:fold-left.
fn:scan-right Produces the complete (ordered) sequence of all partial results from every new value the accumulator is assigned to during the evaluation of fn:fold-right.
fn:some Returns true if at least one item in the input sequence matches a supplied predicate.
fn:sort Sorts a supplied sequence, based on the value of a number of sort keys supplied as functions.
fn:sort-with Sorts a supplied sequence, according to the order induced by the supplied comparator functions.
fn:subsequence-where Returns a contiguous sequence of items from $input, with the start and end points located by applying predicates.
fn:take-while Returns items from the input sequence prior to the first one that fails to match a supplied predicate.
fn:transitive-closure Returns all the nodes reachable from a given start node by applying a supplied function repeatedly.
fn:while-do Processes a supplied value repeatedly, continuing while some condition remains true, and returning the first value that does not satisfy the condition.

With all these functions, if the caller-supplied function fails with a dynamic error, this error is propagated as an error from the higher-order function itself.

16.2.1 fn:apply

Changes in 4.0  

  1. As a result of changes to the coercion rules, the number of supplied arguments can be greater than the number required: extra arguments are ignored.  [Issue 1267 PR 1280 18 June 2024]

Summary

Makes a dynamic call on a function with an argument list supplied in the form of an array.

Signature
fn:apply(
$function as fn(*),
$arguments as array(*)
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The result of the function is obtained by invoking the supplied function $function with arguments taken from the members of the supplied array $arguments. The first argument of the function call is the first member of $arguments, the second argument is the second member of $arguments, and so on.

The arity of the supplied function $function must be less than or equal to the size of the array $arguments.

The effect of calling fn:apply($f, [$a, $b, $c, ...]) is the same as the effect of the dynamic function call $f($a, $b, $c, ....). For example, the coercion rules are applied to the supplied arguments in the usual way. Among other things this means that excess arguments are ignored.

Error Conditions

A dynamic error is raised if the arity of the function $function is greater than the size of the array $arguments ([err:FOAP0001]).

Notes

The function is useful where the arity of a function item is not known statically.

Examples
Expression Result
apply(concat#3, [ "a", "b", "c" ])
"abc"

The expression apply($f, array:subarray([ "a", "b", "c", "d", "e", "f" ], 1, function-arity($f))) calls the supplied function $f supplying the number of arguments required by its arity.

16.2.2 fn:chain

Changes in 4.0  

  1. New in 4.0  [Issue 517 PRs 734 1233 20 October 2022]

Summary

Applies a sequence of functions starting with an initial input.

Signature
fn:chain(
$input as item()*,
$functions as fn(*)*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function behaves as follows:

  1. If $functions is empty, then $input is returned, otherwise let $f be the first member of $functions.

  2. Let $current-output be the result of fn:apply($f, $input-array) where $input-array is constructed according to the following rules.

    1. If $f has arity 1, let $input-array be an array containing $input as a single member.

    2. Otherwise ($f has arity not equal to 1) if $input is not an array then let $input-array be an array containing each item of $input as a separate member.

    3. Otherwise ($f has arity not equal to 1 and $input is already an array) let $input-array be $input itself.

  3. Repeat the process from step 1, passing $current-output as $input and fn:tail($functions) as $functions.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

let $apply := function($x, $f)  {
  fn:apply($f,
    if (function-arity($f) eq 1) then [ $x ]
    else if ($x instance of array(*)) then $x 
    else array { $x }
  )
}
return fn($input as item()*, $functions as fn(*)*) as item()* {
  fold-left($functions, $input, $apply)
}
Error Conditions

An error [err:FOAP0001] is raised if the arity of any function $f in $functions is different from the number of members in the array that is passed to fn:apply.

An error [err:FORG0006] is raised if any item supplied as a function argument cannot be coerced to the required type.

Notes
  1. Functions are applied in sequence order, not right-to-left (as might be expected in mathematical composition).

  2. It is not a requirement that every function in $functions must have arity of one. Any function may have any arity.

  3. Using fn:chain may result in more readable XPath expressions than chaining expressions using arrow operators.

Examples
Variables
let $incr := fn($x) { op("+")($x, ?) }
let $double-all := fn($nums) { $nums ! op("*")(., 2) }
let $times := fn($y) { op("*")($y,  ?) }
let $append-all := fn($strings, $add) { $strings ! concat#2(., $add) }
let $make-upper-all := fn($strings) { $strings ! upper-case(.) }
let $count-all := fn($ar) { array:for-each($ar, count#1)?* }
let $product3 := fn($x, $y, $z) { $x * $y * $z }
let $range := fn($n) { 1 to $n }
Expression:
chain((2, 3), ($double-all, op("+"), $incr(3)))
Result:
13
Expression:
chain((2, 3), ($double-all, sum#1, $incr(3)))
Result:
13
Expression:
chain((2, 3), (op("+"), $incr(3)))
Result:
8
Expression:
chain((2, 3), (sum#1, $incr(3)))
Result:
8
Expression:
chain([ 1, (), 2, 3 ], (array:size#1, $incr(3)))
Result:
7
Expression:
chain((1, 2, 3), (count#1, $incr(3)))
Result:
6
Expression:
chain([ 1, 2, 3 ], (count#1, $incr(3)))
Result:
4
Expression:
chain(5, ($range, $double-all, sum#1))
Result:
30
Expression:
chain(2, ($range, $double-all, op("*")))
Result:
8
Expression:
chain([ (1, 2, 3), () ], ($count-all, op("+")))
Result:
3
Expression:
chain([ (1, 2, 3), (), (5, 6) ], ($count-all, sum#1))
Result:
5
Expression:
chain([ (1, 2, 3), (), (5, 6) ], ($count-all, $product3))
Result:
0
Expression:
chain("abra cadabra", (tokenize#2(?, " "), string-join#2(?, "+")))
Result:
"abra+cadabra"
Expression:
chain("The cat sat on the mat", (
  tokenize#2(?, " "), 
  $append-all(?, "."), 
  $make-upper-all, 
  string-join#2(?, " ") 
))
Result:
"THE. CAT. SAT. ON. THE. MAT."
Expression:
chain((
  chain(
    ("A    long   message   ", "   long "), 
    (head#1, normalize-space#1, normalize-unicode#1)
  ),
  chain(
    ("A    long   message   ", "   long "),  
    (tail#1, normalize-space#1, normalize-unicode#1)
  )
  ),
  contains#2
)
Result:
true()
Expression:
chain((), true#0)
Result:
true()
Expression:
chain(3, (array:append([1], ?), op("+")))
Result:
4
Expression:
chain((1, 2, 3), ($product3, $product3))
Result:

Raises error FOAP0001.

Expression:
chain((1, 2, 3, 4), $product3)
Result:

Raises error FOAP0001.

16.2.3 fn:do-until

Changes in 4.0  

  1. New in 4.0  [Issue 946 PR 962]

  2. The $predicate callback function may return an empty sequence (meaning false).  [Issue 1171 PR 1182 7 May 2024]

Summary

Processes a supplied value repeatedly, continuing when some condition is false, and returning the value that satisfies the condition.

Signature
fn:do-until(
$input as item()*,
$action as fn(item()*, xs:integer) as item()*,
$predicate as fn(item()*, xs:integer) as xs:boolean?
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function behaves as follows:

  1. $pos is initially set to 1.

  2. $action($input, $pos) is evaluated, and the resulting value is used as a new $input.

  3. $predicate($input, $pos) is evaluated. If the result is true, the function returns the value of $input. Otherwise, the process repeats from step 2 with $pos incremented by 1.

    When the predicate returns an empty sequence, this is treated as false.

Formal Specification

The function delivers the same result as the following XQuery implementation.

declare %private function do-until-helper(
  $input     as item()*,
  $action    as fn(item()*, xs:integer) as item()*,
  $predicate as fn(item()*, xs:integer) as xs:boolean?,
  $pos       as xs:integer
) as item()* {
  let $result := $action($input, $pos)
  return if ($predicate($result, $pos)) then (
    $result
  ) else (
    do-until-helper($result, $action, $predicate, $pos + 1)
  )
};

declare function do-until(
  $input     as item()*,
  $action    as fn(item()*, xs:integer) as item()*,
  $predicate as fn(item()*, xs:integer) as xs:boolean?
) as item()* {
  do-until-helper($input, $action, $predicate, 1)
};
Notes

Do-until loops are very common in procedural programming languages, and this function provides a way to write functionally clean and interruptible iterations without side-effects. A new value is computed and tested until a given condition fails. Depending on the use case, the value can be a simple atomic item or an arbitrarily complex data structure.

The function fn:while-do can be used to perform the action after the first predicate test.

Note that, just as when writing recursive functions, it is easy to construct infinite loops.

Examples
Expression:
do-until(
  (),
  fn($value, $pos) { $value, $pos * $pos },
  fn($value) { foot($value) > 50  }
)
Result:
1, 4, 9, 16, 25, 36, 49, 64

(The loop is interrupted once the last value of the generated sequence is greater than 50.)

Expression:
do-until(
  (1, 0),
  fn($value) { $value[1] + $value[2], $value },
  fn($value) { avg($value) > 10 }
)
Result:
55, 34, 21, 13, 8, 5, 3, 2, 1, 1, 0

(The computation is continued as long as the average of the first Fibonacci numbers is smaller than 10.)

16.2.4 fn:every

Changes in 4.0  

  1. New in 4.0  [  13 September 2022]

  2. The $predicate callback function may return an empty sequence (meaning false).  [Issue 1171 PR 1182 7 May 2024]

Summary

Returns true if every item in the input sequence matches a supplied predicate.

Signature
fn:every(
$input as item()*,
$predicate as (fn(item(), xs:integer) as xs:boolean?)? := fn:boolean#1
) as xs:boolean
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns true if $input is empty, or if $predicate($item, $pos) returns true for every item $item at position $pos (1-based) in $input.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

fold-left($input, true(), fn($result, $item, $pos) {
   $result and $predicate($item, $pos)
})
Error Conditions

An error is raised if the $predicate function raises an error. In particular, when the default predicate fn:boolean#1 is used, an error is raised if an item has no effective boolean value.

Notes

If the second argument is omitted or an empty sequence, the predicate defaults to fn:boolean#1, which takes the effective boolean value of each item.

It is possible for the supplied $predicate to be a function whose arity is less than two. The coercion rules mean that the additional parameters are effectively ignored. Frequently a predicate function will only consider the item itself, and disregard its position in the sequence.

The predicate is required to return either true, false, or an empty sequence (which is treated as false). A predicate such as fn{self::h1} results in a type error because it returns a node, not a boolean.

The implementation may deliver a result as soon as one item is found for which the predicate returns false; it is not required to evaluate the predicate for every item, nor is it required to examine items sequentially from left to right.

Examples
Expression:

every(())

Result:
true()
Expression:

every((1 = 1, 2 = 2, 3 = 4))

Result:
false()
Expression:

every((), boolean#1)

Result:
true()
Expression:

every((1, 3, 7), fn { . mod 2 = 1 })

Result:
true()
Expression:

every(-5 to +5, fn { . ge 0 })

Result:
false()
Expression:
every(
  ("January", "February", "March", "April",
   "September", "October", "November", "December"),
  contains(?, "r")
)
Result:
true()
Expression:
every(
  ("January", "February", "March", "April",
   "September", "October", "November", "December")
  =!> contains("r")
)
Result:
true()
Expression:

every((1, 2, number('NaN')))

Result:
false()

(The effective boolean value of NaN is false.)

Expression:

every(1 to 5, fn($num, $pos) { $num = $pos })

Result:
true()
Expression:
let $dl := <dl><dt>Morgawr</dt><dd>Sea giant</dd></dl>
return every($dl/*, fn($elem, $pos) {
  name($elem) = (
    if (($pos mod 2)) then "dt" else "dd"
  )
})
Result:
true()

16.2.5 fn:filter

Changes in 4.0  

  1. The $predicate callback function accepts an optional position argument.  [Issue 516 PR 828 14 November 2023]

  2. The $predicate callback function may return an empty sequence (meaning false).  [Issue 1171 PR 1182 7 May 2024]

Summary

Returns those items from the sequence $input for which the supplied function $predicate returns true.

Signature
fn:filter(
$input as item()*,
$predicate as fn(item(), xs:integer) as xs:boolean?
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns a sequence containing those items from $input for which $predicate($item, $pos) returns true, where $item is the item in question, and $pos is its 1-based ordinal position within $input.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

fold-left($input, (), fn($result, $next, $pos) {
   if ($predicate($next, $pos))
   then ($result, $next)
   else $result
})
Error Conditions

As a consequence of the function signature and the function calling rules, a type error occurs if the supplied $predicate function returns anything other than a single xs:boolean item or an empty sequence; there is no conversion to an effective boolean value, but an empty sequence is interpreted as false.

Notes

If $predicate is an arity-1 function, the function call fn:filter($input, $predicate) has a very similar effect to the expression $input[$predicate(.)]. There are some differences, however. In the case of fn:filter, the function $F is required to return an optional boolean; there is no special treatment for numeric predicate values, and no conversion to an effective boolean value. Also, with a filter expression $input[$predicate(.)], the focus within the predicate is different from that outside; this means that the use of a context-sensitive function such as fn:lang#1 will give different results in the two cases.

Examples
Expression:

filter(1 to 10, fn($a) { $a mod 2 = 0 })

Result:
(2, 4, 6, 8, 10)
Expression:
filter(parse-xml('<doc><a id="2"/><a/></doc>')//a, fn{@id eq "2"})
Result:
<a id="2"/>

(The function returns () when there is no @id attribute; this is treated as false.)

Expression:

filter((), lang("en", ?))

Result:
()
Expression:
let $sequence := (1, 1, 2, 3, 4, 4, 5)
return filter(
  $sequence,
  fn($item, $pos) { $item = $sequence[$pos - 1] }
)
Result:
(1, 4)

16.2.6 fn:fold-left

Changes in 4.0  

  1. The $predicate callback function accepts an optional position argument.  [Issue 516 PR 828 14 November 2023]

  2. The $predicate callback function may return an empty sequence (meaning false).  [Issue 1171 PR 1182 7 May 2024]

Summary

Processes the supplied sequence from left to right, applying the supplied function repeatedly to each item in turn, together with an accumulated result value.

Signature
fn:fold-left(
$input as item()*,
$zero as item()*,
$action as fn(item()*, item(), xs:integer) as item()*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $input is empty, the function returns $zero.

If $input contains a single item $item1, the function calls $action($zero, $item1, 1).

If $input contains a second item $item2, the function then calls $action($zero1, $item2, 2), where $zero1 is the result after processing the first item.

This continues in the same way until the end of the $input sequence; the final result is the result of the last call on $action.

Formal Specification

The function delivers the same result as the following XQuery implementation.

declare %private function fold-left-2 (
        $input as item()*,
        $zero as item()*,
        $action as function(item()*, item()) as item()*) 
        as item()* {
  if (empty($input))
  then $zero
  else fold-left-2(tail($input), $action($zero, head($input)), $action)
};

declare function fold-left (
        $input as item()*,
        $zero as item()*,
        $action as function(item()*, item(), xs:integer) as item()*) 
        as item()* {
  let $numbered-input := for-each($input, 
                                  fn($item, $pos) { 
                                     map{ 'item': $item, 'position': $pos }
                                  })
  return fold-left-2($numbered-input, fn($zero, $pair) {
                                         $action($zero, $pair?item, $pair?position)
                                      })   
};

(: Note: a practical implementation can optimize for the case where the
   supplied $action function has arity 2 :)
Error Conditions

As a consequence of the function signature and the function calling rules, a type error occurs if the supplied function $action cannot be applied to two arguments, where the first argument is either the value of $zero or the result of a previous application of $action, and the second is any single item from the sequence $input.

Notes

This operation is often referred to in the functional programming literature as “folding” or “reducing” a sequence. It typically takes a function that operates on a pair of values, and applies it repeatedly, with an accumulated result as the first argument, and the next item in the sequence as the second argument. Optionally the $action function may take a third argument, which is set to the 1-based position of the current item in the input sequence. The accumulated result is initially set to the value of the $zero argument, which is conventionally a value (such as zero in the case of addition, one in the case of multiplication, or a zero-length string in the case of string concatenation) that causes the function to return the value of the other argument unchanged.

Examples
Expression:
fold-left(
  1 to 5,
  0,
  fn($a, $b) { $a + $b }
)
Result:
15

(This returns the sum of the items in the sequence).

Expression:
fold-left(
  (2, 3, 5, 7),
  1,
  fn($a, $b) { $a * $b }
)
Result:
210

(This returns the product of the items in the sequence).

Expression:
fold-left(
  (true(), false(), false()),
  false(),
  fn($a, $b) { $a or $b }
)
Result:
true()

(This returns true if any item in the sequence has an effective boolean value of true).

Expression:
fold-left(
  (true(), false(), false()),
  false(),
  fn($a, $b) { $a and $b }
)
Result:
false()

(This returns true only if every item in the sequence has an effective boolean value of true).

Expression:
fold-left(
  1 to 5,
  (),
  fn($a, $b) { $b, $a }
)
Result:
(5, 4, 3, 2, 1)

(This reverses the order of the items in a sequence).

Expression:
fold-left(
  1 to 5,
  "",
  concat(?, ".", ?)
)
Result:
".1.2.3.4.5"
Expression:
fold-left(
  1 to 5,
  "$zero",
  concat("$f(", ?, ", ", ?, ")")
)
Result:
"$f($f($f($f($f($zero, 1), 2), 3), 4), 5)"
Expression:
fold-left(
  1 to 5,
  {},
  fn($map, $n) { map:put($map, $n, $n * 2) }
)
Result:
{ 1: 2, 2: 4, 3: 6, 4: 8, 5: 10 }
Expression:
let $input := (11 to 21, 21 to 31)
let $target := 21
return fold-left($input, (),
  fn($result, $curr, $pos) {
    $result, if ($curr = $target) { $pos }
  }
)
Result:
(11, 12)

16.2.7 fn:fold-right

Changes in 4.0  

  1. The $action callback function accepts an optional position argument.  [Issue 516 PR 828 14 November 2023]

Summary

Processes the supplied sequence from right to left, applying the supplied function repeatedly to each item in turn, together with an accumulated result value.

Signature
fn:fold-right(
$input as item()*,
$zero as item()*,
$action as fn(item(), item()*, xs:integer) as item()*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $input is empty, the function returns $zero.

Let $itemN be the last item in $input, and let $N be its 1-based ordinal position in $input (that is, the size of $input). The function starts by calling $action($itemN, $zero, $N).

If there is a previous item, $itemN-1, at position $N - 1, the function then calls $action($itemN-1, $zeroN, $N - 1), where $zeroN is the result of the previous call.

This continues in the same way until the start of the $input sequence is reached; the final result is the result of the last call on $action.

Formal Specification

The function delivers the same result as the following XQuery implementation.

declare %private function fold-right-2 (
        $input as item()*,
        $zero as item()*,
        $action as function(item(), item()*) as item()*) 
        as item()* {
  if (empty($input))
  then $zero
  else $action(head($input), fold-right-2(tail($input), $zero, $action)
};

declare function fold-right (
        $input as item()*,
        $zero as item()*,
        $action as function(item()*, item(), xs:integer) as item()*) 
        as item()* {
  let $numbered-input := for-each($input, 
                                  fn($item, $pos) { 
                                     map{ 'item': $item, 'position': $pos }
                                  })
  return fold-right-2($numbered-input, fn($zero, $pair) {
                                         $action($pair?item, $zero, $pair?position)
                                       })   
};

(: Note: a practical implementation can optimize for the case where the
   supplied $action function has arity 2 :)
Error Conditions

As a consequence of the function signature and the function calling rules, a type error occurs if the supplied function $action cannot be applied to two arguments, where the first argument is any item in the sequence $input, and the second is either the value of $zero or the result of a previous application of $action.

Notes

This operation is often referred to in the functional programming literature as “folding” or “reducing” a sequence. It takes a function that operates on a pair of values, and applies it repeatedly, with the next item in the sequence as the first argument, and the result of processing the remainder of the sequence as the second argument. The accumulated result is initially set to the value of the $zero argument, which is conventionally a value (such as zero in the case of addition, one in the case of multiplication, or a zero-length string in the case of string concatenation) that causes the function to return the value of the other argument unchanged.

In cases where the function performs an associative operation on its two arguments (such as addition or multiplication), fn:fold-right produces the same result as fn:fold-left.

The value of the third argument of $action corresponds to the position of the item in the input sequence. Thus, in contrast to fn:fold-left, it is initally set to the number of items in the input sequence.

Examples
Expression:
fold-right(
  1 to 5,
  0,
  fn($a, $b) { $a + $b }
)
Result:
15

(This returns the sum of the items in the sequence).

Expression:
fold-right(
  1 to 5,
  "",
  concat(?, ".", ?)
)
Result:
"1.2.3.4.5."
Expression:
fold-right(
  1 to 5,
  "$zero",
  concat("$f(", ?, ", ", ?, ")")
)
Result:
"$f(1, $f(2, $f(3, $f(4, $f(5, $zero)))))"
Expression:
let $input := (11 to 21, 21 to 31)
let $target := 21
return fold-right(
  $input,
  (),
  action := fn($current, $result, $pos) {
    $result, $pos[$current = $target]
  }
)
Result:
(12, 11)

16.2.8 fn:for-each

Changes in 4.0  

  1. The $action callback function accepts an optional position argument.  [Issue 516 PR 828 14 November 2023]

Summary

Applies the function item $action to every item from the sequence $input in turn, returning the concatenation of the resulting sequences in order.

Signature
fn:for-each(
$input as item()*,
$action as fn(item(), xs:integer) as item()*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function calls $action($item, $pos) for each item in $input, where $item is the item in question and $pos is its 1-based ordinal position in $input. The final result is the sequence concatenation of the result of these calls, preserving order (provided that ordering mode is ordered).

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

fold-left($input, (), 
          fn($result, $next, $pos) {
              $result, $action($next, $pos)
          })
Examples
Expression:

for-each(1 to 5, fn($a) { $a * $a })

Result:
(1, 4, 9, 16, 25)
Expression:
for-each(
  ("john", "jane"),
  string-to-codepoints#1
)
Result:
(106, 111, 104, 110, 106, 97, 110, 101)
Expression:

for-each(("23", "29"), xs:int#1)

Result:
(23, 29)
Expression:
for-each(
  ('one', 'two', 'three'),
  fn($item, $pos) { $pos || '. ' || $item }
)
Result:
("1. one", "2. two", "3. three")

16.2.9 fn:for-each-pair

Changes in 4.0  

  1. The $action callback function accepts an optional position argument.  [Issue 516 PR 828 14 November 2023]

Summary

Applies the function item $action to successive pairs of items taken one from $input1 and one from $input2, returning the concatenation of the resulting sequences in order.

Signature
fn:for-each-pair(
$input1 as item()*,
$input2 as item()*,
$action as fn(item(), item(), xs:integer) as item()*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the value of the expression:

for $pos in 1 to min(count($input1), count($input2))
return $action($input1[$pos], $input2[$pos], $pos)
Notes

If one sequence is longer than the other, excess items in the longer sequence are ignored.

Examples
Expression:
for-each-pair(
  ("a", "b", "c"),
  ("x", "y", "z"),
  concat#2
)
Result:
("ax", "by", "cz")
Expression:
for-each-pair(
  1 to 5,
  1 to 5,
  fn($a, $b) { 10 * $a + $b }
)
Result:
(11, 22, 33, 44, 55)
Expression:
let $s := 1 to 8
return for-each-pair($s, tail($s), fn($a, $b) { $a * $b })
Result:
(2, 6, 12, 20, 30, 42, 56)
Expression:
for-each-pair(
  (1, 8, 2),
  (3, 4, 3),
  fn($item1, $item2, $pos) {
    $pos || ': ' || max(($item1, $item2))
  }
)
Result:
("1: 3", "2: 8", "3: 3")

16.2.10 fn:highest

Changes in 4.0  

  1. New in 4.0  [  20 September 2022]

Summary

Returns those items from a supplied sequence that have the highest value of a sort key, where the sort key can be computed using a caller-supplied function.

Signature
fn:highest(
$input as item()*,
$collation as xs:string? := fn:default-collation(),
$key as fn(item()) as xs:anyAtomicType* := fn:data#1
) as item()*
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.

Rules

The second argument, $collation, defaults to ().

Supplying an empty sequence as $collation is equivalent to supplying fn:default-collation(). For more information on collations see 5.3.5 Choosing a collation.

The third argument defaults to the function data#1.

Let $modified-key be the function:

fn($item) {
  $key($item) => data() ! (
    if (. instance of xs:untypedAtomic)
    then xs:double(.)
    else .
  )
}

That is, the supplied function for computing key values is wrapped in a function that converts any xs:untypedAtomic values in its result to xs:double. This makes the function consistent with the behavior of fn:min and fn:max, but inconsistent with fn:sort, which treats untyped values as strings.

The result of the function is obtained as follows:

  • If the input is an empty sequence, the result is an empty sequence.

  • The input sequence is sorted, by applying the function fn:sort($input, $collation, $modified-key).

  • Let $C be the selected collation, or the default collation where applicable.

  • Let $B be the last item in the sorted sequence.

  • The function returns those items $A from the input sequence such that (fn:deep-equal($key($A), $key($B), $C), retaining their order.

Error Conditions

If the set of computed keys contains xs:untypedAtomic values that are not castable to xs:double then operation will fail with a dynamic error ([err:FORG0001]FO).

If the set of computed keys contains values that are not comparable using the lt operator then the sort operation will fail with a type error ([err:XPTY0004]XP).

Examples
Variables
let $e := <a x="10" y="5" z="2"/>
Expression:

highest($e/@*) ! name()

Result:
("x")

(By default, untyped values are compared as numbers.)

Expression:

highest($e/@*, (), string#1) ! name()

Result:
("y")

(Here, the attribute values are compared as strings.)

Expression:

highest(("red", "green", "blue"), (), string-length#1)

Result:
("green")
Expression:
highest(
  ("red", "green", "blue"),
  key := {
    "red"  : xs:hexBinary('FF0000'),
    "green": xs:hexBinary('008000'),
    "blue" : xs:hexBinary('0000FF')
  }
)
Result:
("red")
Expression:
highest(
  ("red", "orange", "yellow", "green", "blue", "indigo", "violet"),
  key := string-length#1
)
Result:
("orange", "yellow", "indigo", "violet")
Expression:

highest(1 to 25, (), fn { . idiv 10 })

Result:
(20, 21, 22, 23, 24, 25)

To find employees having the highest salary:

highest($employees, (), fn { xs:decimal(salary) })

16.2.11 fn:index-where

Changes in 4.0  

  1. New in 4.0  [  20 September 2022]

  2. The $predicate callback function may return an empty sequence (meaning false).  [Issue 1171 PR 1182 7 May 2024]

Summary

Returns the positions in an input sequence of items that match a supplied predicate.

Signature
fn:index-where(
$input as item()*,
$predicate as fn(item(), xs:integer) as xs:boolean?
) as xs:integer*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The result of the function is a sequence of integers, in monotonic ascending order, representing the 1-based positions in the input sequence of those items for which the supplied predicate function returns true. A return value of () from the predicate function is treated as false.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

fold-left($input, (), fn($indices, $item, $pos) {
   $indices, if ($predicate($item, $pos)) { $pos }
})
Examples
Expression:

index-where((), boolean#1)

Result:
()
Expression:

index-where((0, 4, 9), boolean#1)

Result:
(2, 3)
Expression:

index-where(1 to 10, fn { . mod 2 = 0 })

Result:
(2, 4, 6, 8, 10)
Expression:
index-where(
  ("January", "February", "March", "April", "May", "June",
   "July", "August", "September", "October", "November", "December"),
  contains(?, "r")
)
Result:
(1, 2, 3, 4, 9, 10, 11, 12)
Expression:
index-where(
  ( 1, 8, 2, 7, 3 ),
  fn($item, $pos) { $item < 5 and $pos > 2 }
)
Result:
(3, 5)

16.2.12 fn:lowest

Changes in 4.0  

  1. New in 4.0  [  20 September 2022]

Summary

Returns those items from a supplied sequence that have the lowest value of a sort key, where the sort key can be computed using a caller-supplied function.

Signature
fn:lowest(
$input as item()*,
$collation as xs:string? := fn:default-collation(),
$key as fn(item()) as xs:anyAtomicType* := fn:data#1
) as item()*
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.

Rules

The second argument, $collation, defaults to ().

Supplying an empty sequence as $collation is equivalent to supplying fn:default-collation(). For more information on collations see 5.3.5 Choosing a collation.

The third argument defaults to the function data#1.

Let $modified-key be the function:

fn($item) {
  $key($item) => data() ! (
    if (. instance of xs:untypedAtomic) then xs:double(.) else .
  )
}

That is, the supplied function for computing key values is wrapped in a function that converts any xs:untypedAtomic values in its result to xs:double. This makes the function consistent with the behavior of fn:min and fn:max, but inconsistent with fn:sort, which treats untyped values as strings.

The result of the function is obtained as follows:

  • If the input is an empty sequence, the result is an empty sequence.

  • The input sequence is sorted, by applying the function fn:sort($input, $collation, $modified-key).

  • Let $C be the selected collation, or the default collation where applicable.

  • Let $B be the first item in the sorted sequence.

  • The function returns those items $A from the input sequence such that (fn:deep-equal($key($A), $key($B), $C), retaining their order.

Error Conditions

If the set of computed keys contains xs:untypedAtomic values that are not castable to xs:double then operation will fail with a dynamic error ([err:FORG0001]FO).

If the set of computed keys contains values that are not comparable using the lt operator then the sort operation will fail with a type error ([err:XPTY0004]XP).

Examples
Variables
let $e := <a x="10" y="5" z="2"/>
Expression:

lowest($e/@*) ! name()

Result:
("z")

(By default, untyped values are compared as numbers.)

Expression:

lowest($e/@*, (), string#1) ! name()

Result:
("x")

(Here, the attribute values are compared as strings.)

Expression:

lowest(("red", "green", "blue"), (), string-length#1)

Result:
("red")
Expression:
lowest(
  ("red", "green", "blue"),
  key := {
    "red"  : xs:hexBinary('FF0000'),
    "green": xs:hexBinary('008000'),
    "blue" : xs:hexBinary('0000FF')
  }
)
Result:
("blue")
Expression:
lowest(
  ("April", "June", "July", "August"),
  key := string-length#1
)
Result:
("June", "July")
Expression:

lowest(1 to 25, (), fn { . idiv 10 })

Result:
(1, 2, 3, 4, 5, 6, 7, 8, 9)

To find employees having the lowest salary:

lowest($employees, (), fn { xs:decimal(salary) })

16.2.13 fn:partition

Changes in 4.0  

  1. New in 4.0  [Issue 125 PR 507 19 May 2023]

Summary

Partitions a sequence of items into a sequence of non-empty arrays containing the same items, starting a new partition when a supplied condition is true.

Signature
fn:partition(
$input as item()*,
$split-when as fn(item()*, item(), xs:integer) as xs:boolean?
) as array(item())*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function starts by creating a partition containing the first item in the input sequence, if any. For each remaining item J in the input sequence, other than the first, it calls the supplied $split-when function with three arguments: the contents of the current partition, the item J, and the current position in the input sequence.

Each partition is a sequence of items; the function result wraps each partition as an array, and returns the sequence of arrays.

If the $split-when function returns true, the current partition is wrapped as an array and added to the result, and a new current partition is created, initially containing the item J only. If the $split-when function returns false or (), the item J is added to the current partition.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

fold-left($input, (), fn($partitions, $next, $pos) {
  if (empty($partitions) or $split-when(foot($partitions)?*, $next, $pos))
  then ($partitions, [ $next ])
  else (trunk($partitions), array { foot($partitions)?*, $next })
})
Notes

The function enables a variety of positional grouping problems to be solved. For example:

  • partition($input, fn($a, $b) { count($a) eq 3 } partitions a sequence into fixed size groups of length 3.

  • partition($input, fn($a, $b) { boolean($b/self::h1) } starts a new group whenever an h1 element is encountered.

  • partition($input, fn($a, $b) { $b lt foot($a) } starts a new group whenever an item is encountered whose value is less than the value of the previous item.

The callback function is not called to process the first item in the input sequence, because this will always start a new partition. The first argument to the callback function (the current partition) is always a non-empty sequence.

Examples
Expression:
partition(
  ("Anita", "Anne", "Barbara", "Catherine", "Christine"), 
  fn($partition, $next) {
    substring(head($partition), 1, 1) ne substring($next, 1, 1)
  }
)
Result:
([ "Anita", "Anne" ], [ "Barbara" ], [ "Catherine", "Christine" ])
Expression:
partition(
  (1, 2, 3, 4, 5, 6, 7),
  fn($partition, $next) {
    count($partition) eq 2
  }
)
Result:
([ 1, 2 ], [ 3, 4 ], [ 5, 6 ], [ 7 ])
Expression:
partition(
  (1, 4, 6, 3, 1, 1),
  fn($partition, $next) {
    sum($partition) ge 5
  }
)
Result:
([ 1, 4 ], [ 6 ], [ 3, 1, 1 ])
Expression:
partition(
  tokenize("In the beginning was the word"), 
  fn($partition, $next) {
    sum(($partition, $next) ! string-length()) gt 10
  }
)
Result:
([ "In", "the" ], [ "beginning" ], [ "was", "the", "word" ])
Expression:
partition(
  (1, 2, 3, 6, 7, 9, 10),
  fn($partition, $next) { $next != foot($partition) + 1 }
)
Result:
([ 1, 2, 3 ], [ 6, 7 ], [ 9, 10 ])
Expression:
partition(
  ('a', 'b', 'c', 'd', 'e'),
  fn($all, $next, $p) { $p mod 2 = 1 }
)
Result:
[ "a", "b" ], [ "c", "d" ], [ "e" ]

16.2.14 fn:scan-left

Changes in 4.0  

  1. New in 4.0  [Issue 982 PR 1296 23 June 2024]

Summary

Produces the complete (ordered) sequence of all partial results from every new value the accumulator is assigned to during the evaluation of fn:fold-left.

Signature
fn:scan-left(
$input as item()*,
$zero as item()*,
$action as fn(item()*, item()) as item()*
) as array(*)*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function is equivalent to the following implementation in XPath (return clause added in comments for completeness):

let $scan-left-inner := fn(
  $input  as item()*, 
  $zero   as item()*, 
  $action as fn(item()*, item()) as item()*,
  $self   as fn(*)
) as array(*)* {
  let $result := [$zero]
  return if (empty($input)) then (
    $result
  ) else (
    $result, $self(tail($input), $action($zero, head($input)), $action, $self)
  )
}
let $scan-left := fn(
  $input  as item()*, 
  $zero   as item()*, 
  $action as fn(item()*, item()) as item()*
) as array(*)*  {
  $scan-left-inner($input, $zero, $action, $scan-left-inner)
}
(: return $scan-left(1 to 10, 0, op('+'))  :)
Error Conditions

As a consequence of the function signature and the function calling rules, a type error occurs if the supplied function $action cannot be applied to two arguments, where the first argument is either the value of $zero or the result of a previous application of $action, and the second is any single item from the sequence $input.

Notes
  1. Note that each intermediate result is placed in a separate singleton array. This is necessary because we cannot represent a sequence of results, some or all of which are a sequence - that is "sequence of sequences" as just a single sequence.

Examples
Expression:
scan-left(1 to 5, 0, op('+'))
Result:
[ 0 ], [ 1 ], [ 3 ], [ 6 ], [ 10 ], [ 15 ]
Expression:
scan-left(1 to 3, 0, op('-'))
Result:
[ 0 ], [ -1 ], [ -3 ], [ -6 ]

Produce the intermediate results of mapping each number in a sequence to its doubled value. This example shows the necessity to place each intermediate result (sequence) into a singleton array - otherwise the sequence of sequences (intermediate results) would not be possible to express as a single sequence without losing completely the intermediate results.

Expression:
let $double := fn($x) { 2 * $x }
return scan-left(1 to 3, (), fn($seq, $it) { $seq , $double($it) })
Result:
[ () ], [ 2 ], [ (2, 4) ], [ (2, 4, 6) ] ]

Produce the factorials of all numbers from 0 to 5

Expression:
scan-left(1 to 5, 1, op('*'))
Result:
[ 1 ], [ 1 ], [ 2 ], [ 6 ], [ 24 ], [ 120 ]

16.2.15 fn:scan-right

Changes in 4.0  

  1. New in 4.0

Summary

Produces the complete (ordered) sequence of all partial results from every new value the accumulator is assigned to during the evaluation of fn:fold-right.

Signature
fn:scan-right(
$input as item()*,
$zero as item()*,
$action as fn(item()*, item()) as item()*
) as array(*)*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function is equivalent to the following implementation in XPath (return clause in comments added for completeness):

let $scan-right-inner := fn(
  $input  as item()*,
  $zero   as item()*,
  $action as fn(item()*, item()) as item()*, $self as fn(*)
) as array(*)* {
  if (empty($input)) then (
    [ $zero ]
  ) else (
    let $rightResult := $self(tail($input), $zero, $action, $self)
    return ([ $action(head($input), head($rightResult)) ], $rightResult)
  )
}
let $scan-right := function(
  $input as item()*,
  $zero  as item()*,
  $f     as fn(item()*, item()) as item()*
) as array(*)* {
  $scan-right-inner($input, $zero, $f, $scan-right-inner)
}        
(: return $scan-right(1 to 10, 0, op('+')) :)
Error Conditions

As a consequence of the function signature and the function calling rules, a type error occurs if the supplied function $action cannot be applied to two arguments, where the first argument is any item in the sequence $input, and the second is either the value of $zero or the result of a previous application of $action.

Notes
  1. Note that each intermediate result is placed in a separate singleton array. This is necessary because we cannot represent a sequence of results, some or all of which are a sequence - that is "sequence of sequences" as just a single sequence.

Examples
Expression:
scan-right(1 to 10, 0, op('+'))
Result:
[ 55 ], [ 54 ], [ 52 ], [ 49 ], [ 45 ],
[ 40 ], [ 34 ], [ 27 ], [ 19 ], [ 10 ], [ 0 ]
Expression:
scan-right(1 to 3, 0, op('-'))
Result:
[ 2 ], [ -1 ], [ 3 ], [ 0 ]

16.2.16 fn:some

Changes in 4.0  

  1. New in 4.0  [  13 September 2022]

  2. The $predicate callback function may return an empty sequence (meaning false).  [Issue 1171 PR 1182 7 May 2024]

Summary

Returns true if at least one item in the input sequence matches a supplied predicate.

Signature
fn:some(
$input as item()*,
$predicate as (fn(item(), xs:integer) as xs:boolean?)? := fn:boolean#1
) as xs:boolean
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns true if (and only if) there is an item $item at position $pos in the input sequence such that $predicate($item, $pos) returns true.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

fold-left($input, false(), fn($result, $item, $pos) {
   $result or $predicate($item, $pos)
})
Error Conditions

An error is raised if the $predicate function raises an error. In particular, when the default predicate fn:boolean#1 is used, an error is raised if an item has no effective boolean value.

Notes

If the second argument is omitted or an empty sequence, the predicate defaults to fn:boolean#1, which takes the effective boolean value of each item.

It is possible for the supplied $predicate to be a function whose arity is less than two. The coercion rules mean that the additional parameters are effectively ignored. Frequently a predicate function will only consider the item itself, and disregard its position in the sequence.

The predicate is required to return either true, false, or an empty sequence (which is treated as false). A predicate such as fn{self::h1} results in a type error because it returns a node, not a boolean.

The implementation may deliver a result as soon as one item is found for which the predicate returns true; it is not required to evaluate the predicate for every item, nor is it required to examine items sequentially from left to right.

Examples
Expression:

some(())

Result:
false()
Expression:

some((1 = 1, 2 = 2, 3 = 4))

Result:
true()
Expression:

some((), boolean#1)

Result:
false()
Expression:

some((1, 3, 7), fn { . mod 2 = 1 })

Result:
true()
Expression:

some(-5 to +5, fn { . ge 0 })

Result:
true()
Expression:
some(
  ("January", "February", "March", "April",
   "September", "October", "November", "December"),
  contains(?, "z")
)
Result:
false()
Expression:
some(
  ("January", "February", "March", "April",
   "September", "October", "November", "December")
  =!> contains("r")
)
Result:
true()
Expression:

some(("", 0, number('NaN')))

Result:
false()

(The effective boolean value in each case is false.)

Expression:

some(reverse(1 to 5), fn($num, $pos) { $num = $pos })

Result:
true()

16.2.17 fn:sort

Changes in 4.0  

  1. Substantially revised to allow multiple sort key definitions.  [Issue 93 PR 623 19 July 2023]

Summary

Sorts a supplied sequence, based on the value of a number of sort keys supplied as functions.

Signature
fn:sort(
$input as item()*,
$collations as xs:string* := fn:default-collation(),
$keys as (fn(item()) as xs:anyAtomicType*)* := fn:data#1,
$orders as enum('ascending', 'descending')* := 'ascending'
) as item()*
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.

Rules

The result of the function is a sequence that contains all the items from $input, typically in a different order, the order being defined by the supplied sort key definitions.

A sort key definition has three parts:

  1. A sort key function, which is applied to each item in the input sequence to determine a sort key value.

  2. A collation, which is used when comparing sort key values that are of type xs:string or xs:untypedAtomic.

  3. An order direction, which is ascending or descending.

The number of sort key definitions is determined by the number of function items supplied in the $keys argument. If the argument is absent or empty, the default is a single sort key definition using the function data#1.

The $nth sort key definition (where $n counts from one (1)) is established as follows:

  1. The sort key function is $keys[$n] otherwise data#1.

  2. The collation is $collations[$n] otherwise $collations[last()] otherwise default-collation(). That is, it is the collation supplied in the corresponding item of the supplied $collations argument; or in its absence, the last entry in $collations; or if $collations is absent or empty, the default collation from the static context of the caller.

  3. The order direction is $orders[$n] otherwise $orders[last()] otherwise "ascending". That is, it is "ascending" or "descending" according to the value of the corresponding item in the supplied $orders argument; or in its absence, the last entry in $orders; or if $orders is absent or empty, then "ascending".

When comparing values of types other than xs:string or xs:untypedAtomic, the corresponding collation is ignored, and no error is reported if the supplied value is not a known or valid collation name. If it is necessary to supply such an ignored value (for example, in the case where a non-string sort key is followed by another sort key that requires a collation) the empty string can be supplied.

The result of the function is obtained as follows:

  1. The result sequence contains the same items as the input sequence $input, but generally in a different order.

  2. The sort key definitions are established as described above. The sort key definitions are in major-to-minor order. That is, the position of two items $A and $B in the result sequence is determined first by the relative magnitude of their primary sort key values, which are computed by evaluating the sort key function in the first sort key definition. If those two sort key values are equal, then the position is determined by the relative magnitude of their secondary sort key values, computed by evaluating the sort key function in the second sort key definition, and so on.

  3. When a pair of corresponding sort key values of $A and $B are found to be not equal, then $A precedes $B in the result sequence if both the following conditions are true, or if both conditions are false:

    1. The sort key value for $A is less than the sort key value for $B, as defined below.

    2. The order direction in the corresponding sort key definition is "ascending".

  4. If all the sort key values for $A and $B are pairwise equal, then $A precedes $B in the result sequence if and only if $A precedes $B in the input sequence.

    Note:

    That is, the sort is stable.

  5. Each sort key value for a given item is obtained by applying the sort key function of the corresponding sort key definition to that item. The result of this function is in the general case a sequence of atomic items. Two sort key values $a and $b are compared as follows:

    1. Let $C be the collation in the corresponding sort key definition.

    2. Let $REL be the result of evaluating op:lexicographic-compare($key($A), $key($B), $C) where op:lexicographic-compare($a, $b, $C) is defined as follows:

      if (empty($a) and empty($b)) then 0 
      else if (empty($a)) then -1
      else if (empty($b)) then +1
      else let $rel = op:simple-compare(head($a), head($b), $C)
           return if ($rel eq 0)
                  then op:lexicographic-compare(tail($a), tail($b), $C)
                  else $rel
    3. Here op:simple-compare($k1, $k2) is defined as follows:

      if ($k1 instance of (xs:string | xs:anyURI | xs:untypedAtomic)
          and $k2 instance of (xs:string | xs:anyURI | xs:untypedAtomic))
      then compare($k1, $k2, $C)
      else if ($k1 instance of xs:numeric and $k2 instance of xs:numeric)
      then compare($k1, $k2)
      else if ($k1 eq $k2) then 0
      else if ($k2 lt $k2) then -1
      else +1

      Note:

      This raises an error if two keys are not comparable, for example if one is a string and the other is a number, or if both belong to a non-ordered type such as xs:QName.

    4. If $REL is zero, then the two sort key values are deemed equal; if $REL is -1 then $a is deemed less than $b, and if $REL is +1 then $a is deemed greater than $b

Error Conditions

If the set of computed sort keys contains values that are not comparable using the lt operator then the sort operation will fail with a type error ([err:XPTY0004]XP).

Notes

XSLT and XQuery both provide native sorting capability, but earlier releases of XPath provided no sorting functionality for use in standalone environments.

In addition there are cases where this function may be more flexible than the built-in sorting capability for XQuery or XSLT, for example when the sort key or collation is chosen dynamically, or when the sort key is a sequence of items rather than a single item.

The results are compatible with the results of XSLT sorting (using xsl:sort) in the case where the sort key evaluates to a sequence of length zero or one, given the options stable="yes".

The results are compatible with the results of XQuery sorting (using the order by clause) in the case where the sort key evaluates to a sequence of length zero or one, given the options stable, ascending, and empty least.

The function has been enhanced in 4.0 to allow multiple sort keys to be defined, each potentially with a different collation, and to allow sorting in descending order.

The effect of the XQuery option empty least|greatest, which controls whether the empty sequence is sorted before or after all other values, can be achieved by adding an extra sort key definition that evaluates whether or not the actual sort key is empty (when sorting boolean values, false precedes true).

Supplying too many items in the $collations and/or $orders arguments is not an error; the excess values are ignored except for type-checking against the function signature.

Examples
Expression:

sort((1, 4, 6, 5, 3))

Result:
(1, 3, 4, 5, 6)
Expression:

sort((1, 4, 4e0, 6, 5, 3), orders := "descending")

Result:
(6, 5, 4, 4e0, 3, 1)
Expression:

sort((1, -2, 5, 10, -10, 10, 8), (), abs#1)

Result:
(1, -2, 5, 8, 10, -10, 10)

To sort a set of strings $in using Swedish collation:

let $SWEDISH := collation(map{'lang':'se'})
return sort($in, $SWEDISH)

To sort a sequence of employees by last name as the major sort key and first name as the minor sort key, using the default collation:

sort($employees, (), fn { name ! (last, first) })

To sort a sequence of employees first by increasing last name (using Swedish collation order) and then by decreasing salary:

sort(
  $employees, 
  collation(map{'lang':'se'}),
  (fn { name/last }, fn { xs:decimal(salary) }), 
  ("ascending", "descending")
)

16.2.18 fn:sort-with

Changes in 4.0  

  1. New in 4.0  [Issue 655 PR 795 20 February 2024]

Summary

Sorts a supplied sequence, according to the order induced by the supplied comparator functions.

Signature
fn:sort-with(
$input as item()*,
$comparators as (fn(item(), item()) as xs:integer)*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the items of the supplied $input are compared against each other, using the supplied $comparators. The result is a sorted sequence.

Each comparator function takes two items and returns an xs:integer that defines the relationship between these items, in accordance with the fn:compare function:

  • The comparators are evaluated one after the other, either completely or until the result is an integer other than 0.

  • If the last integer returned is negative or 0, the first item is returned before the second.

  • Otherwise, the second item is returned first.

Users are responsible for supplying transitive comparators; otherwise, the result might not be correctly sorted. An example for a non-transitive and thus unsuitable comparator is fn($a, $b) { if ($a mod 2 = 1) then 1 else -1 }, as it considers odd numbers to be greater than even numbers.

Sorting is stable, which means that the relative order of the input items is maintained.

More formally, assuming that the comparators raise no errors and are transitive, the effect of the function is equivalent to the following implementation in XQuery:

declare function sort-with(
  $input       as item()*,
  $comparators as (fn(item(), item()) as xs:integer)*
) as item()* {
  if (count($input) < 2) then (
    $input
  ) else (
    let $head := head($input), $sorted-tail := sort-with(tail($input), $comparators)
    let $diff := fold-left($comparators, 0, fn($df, $cmp) {
      if ($df != 0) then $df else $cmp($head, head($sorted-tail))
    })
    return if ($diff <= 0) then (
      $head, $sorted-tail
    ) else (
      head($sorted-tail), sort-with(($head, tail($sorted-tail)), $comparators)
    )
  )
};
Notes

An implementation is free to choose any sorting algorithm as long as the result returned is stable and matches the result of the implementation in XQuery.

Examples
Expression:

sort-with((1, 4, 6, 5, 3), compare#2)

Result:
(1, 3, 4, 5, 6)
Expression:

sort-with((1, 4, 6, 5, 3), op('-'))

Result:
(1, 3, 4, 5, 6)
Expression:

sort-with((1, 4, 4e0, 6, 5, 3), fn($a, $b) { compare($b, $a) })

Result:
(6, 5, 4, 4e0, 3, 1)
Expression:
sort-with(
  (1, -2, 5, 10, -12, 8),
  fn($a, $b) { abs($a) - abs($b) }
)
Result:
(1, -2, 5, 8, 10, -12)
Expression:
let $persons := <persons>
  <person name='Josipa' age='8'/>
  <person name='Jade' age='6'/>
  <person name='Jie' age='8'/>
</persons>
return sort-with($persons/person, (
  fn($a, $b) { compare($a/@age, $b/@age) },
  fn($a, $b) { compare($a/@name, $b/@name) }
))
Result:
<person name="Jade" age="6"/>
<person name="Jie" age="8"/>
<person name="Josipa" age="8"/>

16.2.19 fn:subsequence-where

Changes in 4.0  

  1. New in 4.0  [Issue 878 PR 940 5 February 2024]

Summary

Returns a contiguous sequence of items from $input, with the start and end points located by applying predicates.

Signature
fn:subsequence-where(
$input as item()*,
$from as (fn(item(), xs:integer) as xs:boolean?)? := true#0,
$to as (fn(item(), xs:integer) as xs:boolean?)? := false#0
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function returns the subsequence of $input starting with the first item that matches the $from predicate, and ending with the first subsequent item that matches the $to predicate. If $from is not supplied, it defaults to the start of $input; if $to is not supplied, it defaults to the end of $input. If $from does not match any items in $input, the result is the empty sequence; if $to does not match any items, all items up to the last are included in the result.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

let $start := index-where($input, $from)[1] 
              otherwise (count($input) + 1)
let   $end := index-where($input, $to)[. ge $start][1] 
              otherwise (count($input) + 1)
return slice($input, $start, $end)
Notes

The result includes both the item that matches the $from condition and the item that matches the $to condition. To select a subsequence that starts after the $from item, apply the fn:tail function to the result. To select a subsequence that ends before the $to item, apply the fn:trunk function to the result.

The predicate functions supplied to the $from and $to parameters can include an integer position argument as well as the item itself. This position will always be 1-based, relative to the start of $input. This means it is possible to select items based on their absolute position in the $input sequence, but there is no mechanism to select an end position relative to the start position. If this is needed, the function can be combined with others: for example, to select a subsequence of four items starting with "Barbara", use $input => subsequence-where(fn {. eq "Barbara" }) => slice(end := 4).

If the requirement is to select all elements stopping before the first h2 element if it exists, or up to the end of the sequence otherwise, the simplest solution is perhaps to write:

slice($input, end:=index-where($input, fn { boolean(self::h2) })[1])

A return value of () from the $from or $to predicate is treated as false.

Examples
Variables
let $names := ("Anna", "Barbara", "Catherine", "Delia",  "Eliza", "Freda",
  "Gertrude", "Hilda")
Expression:

subsequence-where($names, starts-with(?, "E"))

Result:
("Eliza", "Freda", "Gertrude", "Hilda")
Expression:

subsequence-where($names, to := starts-with(?, "D"))

Result:
("Anna", "Barbara", "Catherine", "Delia")
Expression:

subsequence-where($names, to := starts-with(?, "D")) => trunk()

Result:
("Anna", "Barbara", "Catherine")
Expression:

subsequence-where($names, starts-with(?, "E"), starts-with(?, "G"))

Result:
("Eliza", "Freda", "Gertrude")
Expression:
subsequence-where(
  $names,
  starts-with(?, "D"), fn { string-length(.) gt 5 }
)
Result:
("Delia", "Eliza", "Freda", "Gertrude")
Expression:

subsequence-where($names, starts-with(?, "M"))

Result:
()
Expression:

subsequence-where($names, starts-with(?, "G"), starts-with(?, "Z"))

Result:
("Gertrude", "Hilda")
Expression:

subsequence-where($names)

Result:
("Anna", "Barbara", "Catherine", "Delia", "Eliza", "Freda",
  "Gertrude", "Hilda")
Expression:
subsequence-where(
  $names,
  fn($it, $pos) { ends-with($it, "a") and $pos gt 5 }
)
Result:
("Freda", "Gertrude", "Hilda")
Expression:
subsequence-where(
  $names, 
  to := fn($it, $pos) { ends-with($it, "a") and $pos ge 5 }
)
Result:
("Anna", "Barbara", "Catherine", "Delia", "Eliza")

16.2.20 fn:take-while

Changes in 4.0  

  1. New in 4.0  [Issues 1002 1038 PR 1046]

  2. The $predicate callback function may return an empty sequence (meaning false).  [Issue 1171 PR 1182 7 May 2024]

Summary

Returns items from the input sequence prior to the first one that fails to match a supplied predicate.

Signature
fn:take-while(
$input as item()*,
$predicate as fn(item(), xs:integer) as xs:boolean?
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns all items in the sequence prior to the first one where the result of calling the supplied $predicate function, with the current item and its position as arguments, returns the value false or ().

If every item in the sequence satisfies the predicate, then $input is returned in its entirety.

Formal Specification

The effect of the function is equivalent to the result of the following XQuery expression.

for $it at $pos in $input
while $predicate($it, $pos)
return $it
Notes

There is no analogous drop-while or skip-while function, as found in some functional programming languages. The effect of drop-while($input, $predicate) can be achieved by calling fn:subsequence-where($input, fn { not($predicate(.)) }).

Examples
Expression:

take-while(10 to 20, fn {. le 12 })

Result:
(10, 11, 12)
Expression:

take-while(10 to 20, fn {. lt 100 })

Result:
(10 to 20)
Expression:

take-while((), boolean#1)

Result:
()
Expression:
take-while(
  ("A", "B", "C", " ", "E"), 
   fn { boolean(normalize-space()) }
 )
Result:
("A", "B", "C")
Expression:
parse-xml("<doc><p/><p/><h2/><img/><p/></doc>")/doc/*
=> take-while(fn { boolean(self::p) })
=> count()
Result:
2
Expression:
("Aardvark", "Antelope", "Bison", "Buffalo", "Camel", "Dingo")
=> take-while(starts-with(?, "A"))
Result:
"Aardvark", "Antelope"
Expression:
take-while(10 to 20, fn($num, $pos) { $num lt 18 and $pos lt 4 })
Result:
(10, 11, 12)
Expression:
take-while(
  characters("ABCD-123"), 
  fn($ch, $pos) { $pos lt 4 and $ch ne '-' }
) => string-join()
Result:
"ABC"
Expression:
take-while(
  ("A", "a", "B", "b", "C", "D", "d"),
   fn($ch, $pos) {
     matches($ch, if ($pos mod 2 eq 1) then "\p{Lu}" else "\p{Ll}")
   }
 )
Result:
"A", "a", "B", "b", "C"

16.2.21 fn:transitive-closure

Changes in 4.0  

  1. New in 4.0  [Issues 554 754 PR 761 18 October 2023]

Summary

Returns all the nodes reachable from a given start node by applying a supplied function repeatedly.

Signature
fn:transitive-closure(
$node as node()?,
$step as fn(node()) as node()*
) as node()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The value of $node is a node from which navigation starts. If $node is an empty sequence, the function returns an empty sequence.

The value of $step is a function that takes a single node as input, and returns a set of nodes as its result.

The result of the fn:transitive-closure function is the set of nodes that are reachable from $node by applying the $step function one or more times.

Although $step may return any sequence of nodes, the result is treated as a set: the order of nodes in the sequence is ignored, and duplicates are ignored. The result of of the transitive-closure function will always be a sequence of nodes in document order with no duplicates.

Formal Specification

The function delivers the same result as the following XQuery implementation.

declare %private function tc-inclusive(
  $nodes as node()*,
  $step  as (fn(node()) as node()*)
) as node()* {
  let $nextStep := $nodes/$step(.)
  let $newNodes := $nextStep except $nodes
  return if (exists($newNodes))
         then $nodes union tc-inclusive($newNodes, $step)
         else $nodes
};
declare function transitive-closure (
  $node  as node(),
  $step  as (fn(node()) as node()*)
) as node()* {
  tc-inclusive($node/$step(.), $step)
};
     
         
(: Explanation:

   The private helper function tc-inclusive takes a set of nodes as input,
   and calls the $step function on each one of those nodes; if the result 
   includes nodes that are not already present in the input, then it makes 
   a recursive call to find nodes reachable from these new nodes, and returns
   the union of the supplied nodes and the nodes returned from the recursive
   call (which will always include the new nodes selected in the first step).
   
   If there are no new nodes, the recursion ends, returning the nodes that 
   have been found up to this point.
   
   The main function fn:transitive-closure finds the nodes that are reachable 
   from the start node in a single step, and then invokes the helper function 
   tc-inclusive to add nodes that are reachable in multiple steps.
:)
Notes

Cycles in the data are not a problem; the function stops searching when it finds no new nodes.

The function may fail to terminate if the supplied $step function constructs and returns new nodes. A processor may detect this condition but is not required to do so.

The $node node is not included in the result, unless it is reachable by applying the $step function one or more times. If a result is required that does include $node, it can be readily added to the result using the union operator: $node | transitive-closure($node, $step).

Examples
Variables
let $data := document { <doc>
  <person id="0"/>
  <person id="1" manager="0"/>
  <person id="2" manager="0"/>
  <person id="3" manager="2"/>
  <person id="4" manager="2"/>
  <person id="5" manager="1"/>
  <person id="6" manager="3"/>
  <person id="7" manager="6"/>
  <person id="8" manager="6"/>
</doc> }
let $direct-reports := fn($p as element(person)) as element(person)* {
  $p/../person[@manager = $p/@id]
}
Expression:
transitive-closure(
  $data//person[@id = "2"],
  $direct-reports
)/string(@id)
Result:
("3", "4", "6", "7", "8")
Expression:
transitive-closure(
  $data, 
  function { child::* }
)/@id ! string()
Result:
("0", "1", "2", "3", "4", "5", "6", "7", "8")

The following example, given $root as the root of an XSLT stylesheet module, returns the URIs of all stylesheet modules reachable using xsl:import and xsl:include declarations:

transitive-closure($root, fn { document(//(xsl:import|xsl:include)/@href) }) 
=!> document-uri()

This example uses the XSLT-defined document() function.

16.2.22 fn:while-do

Changes in 4.0  

  1. New in 4.0  [Issue 946 PR 962]

  2. The $predicate callback function may return an empty sequence (meaning false).  [Issue 1171 PR 1182 7 May 2024]

Summary

Processes a supplied value repeatedly, continuing while some condition remains true, and returning the first value that does not satisfy the condition.

Signature
fn:while-do(
$input as item()*,
$predicate as fn(item()*, xs:integer) as xs:boolean?,
$action as fn(item()*, xs:integer) as item()*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function behaves as follows:

  1. $pos is initially set to 1.

  2. $predicate($input, $pos) is evaluated. If the result is false or (), the function returns the value of $input.

  3. Otherwise, $action($input, $pos) is evaluated, the resulting value is used as a new $input, and the process repeats from step 2 with $pos incremented by 1.

Formal Specification

The function delivers the same result as the following XQuery implementation.

declare %private function while-do-helper(
  $input     as item()*,
  $predicate as fn(item()*, xs:integer) as xs:boolean?,
  $action    as fn(item()*, xs:integer) as item()*,
  $pos       as xs:integer
) as item()* {
  if ($predicate($input, $pos))
  then while-do-helper($action($input, $pos), $predicate, $action, $pos + 1)
  else $input
};

declare function while-do(
  $input     as item()*,
  $predicate as fn(item()*, xs:integer) as xs:boolean?,
  $action    as fn(item()*, xs:integer) as item()*
) as item()* {
  while-do-helper($input, $predicate, $action, 1)
};
Notes

While-do loops are very common in procedural programming languages, and this function provides a way to write functionally clean and interruptible iterations without side-effects. As long as a given condition is met, an new value is computed and tested again. Depending on the use case, the value can be a simple atomic item or an arbitrarily complex data structure.

The function fn:do-until can be used to perform the action before the first predicate test.

Note that, just as when writing recursive functions, it is easy to construct infinite loops.

Examples
Expression:
while-do(2, fn { . <= 100 }, fn { . * . })
Result:
256

(The loop is interrupted as soon as the computed product is greater than 100.)

Expression:
while-do(
  1,
  fn($num, $pos) { $pos <= 10 },
  fn($num, $pos) { $num * $pos }
)
Result:
3628800

(This returns the factorial of 10, i.e., the product of all integers from 1 to 10.)

Expression:
let $input := (0 to 4, 6 to 10)
return while-do(
  0,
  fn($n) { $n = $input },
  fn($n) { $n + 1 }
)
Result:
5

(This returns the first positive number missing in a sequence.)

Expression:
while-do(
  1 to 9,
  fn($value) { head($value) < 5 },
  fn($value) { tail($value) }
)
Result:
(5, 6, 7, 8, 9)

(The first number of a sequence is removed as long as it is smaller than 5.)

Expression:
let $input := 3936256
return while-do(
  $input,
  fn($result) { abs($result * $result - $input) >= 0.0000000001 },
  fn($guess) { ($guess + $input div $guess) div 2 }
) => round(5)
Result:
1984

(This computes the square root of a number.)

The following example generates random doubles. It is interrupted once a number exceeds a given limit:

let $result := while-do(
  random-number-generator(),
  fn($random) {
    $random?number < 0.8
  },
  fn($random) {
    map:put($random?next(), 'numbers', ($random?numbers, $random?number))
  }
)
return $result?numbers

16.3 Dynamic Evaluation

The following functions allow dynamic loading and evaluation of XQuery queries, XSLT stylesheets, and XPath binary operators.

Function Meaning
fn:load-xquery-module Provides access to the public functions and global variables of a dynamically loaded XQuery library module.
fn:transform Invokes a transformation using a dynamically loaded XSLT stylesheet.
fn:op Returns a function whose effect is to apply a supplied binary operator to two arguments.

16.3.1 fn:load-xquery-module

Changes in 4.0  

  1. It has been clarified that loading a module has no effect on the static or dynamic context of the caller.  [Issue 725 PR 727 10 October 2023]

  2. The return type is now specified more precisely.  [Issue 883 PR 1072 19 March 2024]

  3. A new option is provided to allow the content of the loaded module to be supplied as a string.  [Issue 1329 PR 1333 22 July 2024]

Summary

Provides access to the public functions and global variables of a dynamically loaded XQuery library module.

Signature
fn:load-xquery-module(
$module-uri as xs:string,
$options as map(*)? := {}
) as load-xquery-module-record
record load-xquery-module-record (
   variables as map(xs:QName, item()*),
   functions as map(xs:QName, map(xs:integer, function(*)))
)
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

Rules

The function loads an implementation-defined set of modules having the target namespace $module-uri.

If the second argument is omitted or an empty sequence, the result is the same as calling the two-argument form with an empty map as the value of the $options argument.

The $options argument can be used to control the way in which the function operates. The ·option parameter conventions· apply.

record(
xquery-version? as xs:decimal,
location-hints? as xs:string*,
content? as xs:string?,
context-item? as item()?,
variables? as map(xs:QName, item()*),
vendor-options? as map(xs:QName, item()*)
)
Key Meaning

xquery-version

The minimum level of the XQuery language that the processor must support.
  • Type: xs:decimal

  • Default: The version given in the prolog of the library module; or ·implementation-defined· if this is absent.

location-hints

A sequence of URIs (in the form of xs:string values) which may be used or ignored in an ·implementation-defined· way.
  • Type: xs:string*

  • Default: Empty sequence

content

The content of the query module as a string. When this option is used, the location-hints option is ignored. The static base URI of the dynamically loaded module is the same as the static base URI of the caller.
  • Type: xs:string?

  • Default: Empty sequence

context-item

The item to be used as the initial context item when evaluating global variables in the library module. Supplying an empty sequence is equivalent to omitting the entry from the map, and indicates the absence of a context item. If the library module specifies a required type for the context item, then the supplied value must conform to this type, without conversion.
  • Type: item()?

  • Default: Absent

variables

Values for external variables defined in the library module. Values must be supplied for external variables that have no default value, and may be supplied for external variables that do have a default value. The supplied value must conform to the required type of the variable, without conversion. The map contains one entry for each external variable: the key is the variable’s name, and the associated value is the variable’s value. The ·option parameter conventions· do not apply to this contained map.
  • Type: map(xs:QName, item()*)

  • Default: An empty map

vendor-options

Values for vendor-defined configuration options for the XQuery processor used to process the request. The key is the name of an option, expressed as a QName: the namespace URI of the QName should be a URI controlled by the vendor of the XQuery processor. The meaning of the associated value is ·implementation-defined·. Implementations should ignore options whose names are in an unrecognized namespace. The ·option parameter conventions· do not apply to this contained map.
  • Type: map(xs:QName, item()*)

  • Default: An empty map

The result of the function is a map R with two entries:

Name Meaning

variables

This map (V ) contains one entry for each public global variable declared in the library module. The key of the entry is the name of the variable, as an xs:QName value; the associated value is the value of the variable.

  • Type: map(xs:QName, item()*)

functions

This map (F ) contains one entry for each distinct QName Q that represents the name of a public and non-external function declared in the library module. The key of the entry is Q, as an xs:QName value; the associated value is a map A. This map (A) contains one entry for each arity N within the arity range of any of the function declarations with the given name; its key is N, as an xs:integer value, and its associated value is a function item obtained as if by evaluating a named function reference Q#N, using the static and dynamic context of the call on fn:load-xquery-module. The function item can be invoked using the rules for dynamic function invocation.

  • Type: map(xs:QName, map(xs:integer, function(*)))

The static and dynamic context of the library module are established according to the rules in Section C Context Components XQ31.

It is ·implementation-defined· whether constructs in the library module are evaluated in the same ·execution scope· as the calling module.

The library module that is loaded may import other modules using an import module declaration. The result of fn:load-xquery-module does not include global variables or functions declared in such a transitively imported module. However, the options map supplied in the function call may (and if no default is defined, must) supply values for external variables declared in transitively loaded library modules.

The library module that is loaded may import schema declarations using an import schema declaration. It is ·implementation-defined· whether schema components in the in-scope schema definitions of the calling module are automatically added to the in-scope schema definitions of the dynamically loaded module. The in-scope schema definitions of the calling and called modules must be consistent, according to the rules defined in Section 2.2.5 Consistency Constraints XQ31.

Where nodes are passed to or from the dynamically loaded module, for example as an argument or result of a function, they should if possible retain their node identity, their base URI, their type annotations, and their relationships to all other nodes in the containing tree (including ancestors and siblings). If this is not possible, for example because the only way of passing nodes to the chosen XQuery implementation is by serializing and re-parsing, then a node may be passed in the form of a deep copy, which may lose information about the identity of the node, about its ancestors and siblings, about its base URI, about its type annotations, and about its relationships to other nodes passed across the interface.

Error Conditions

If $module-uri is a zero length string, a dynamic error is raised [err:FOQM0001].

If the implementation is not able to find a library module with the specified target namespace, an error is raised [err:FOQM0002].

If a static error (including a statically detected type error) is encountered when processing the library module, a dynamic error is raised [err:FOQM0003].

If a value is supplied for the initial context item or for an external variable and the value does not conform to the required type declared in the dynamically loaded module, a dynamic error is raised [err:FOQM0005].

If no suitable XQuery processor is available, a dynamic error is raised [err:FOQM0006]. This includes (but is not limited to) the following cases:

  1. No XQuery processor is available;

  2. Use of the function has been disabled;

  3. No XQuery processor supporting the requested version of XQuery is available;

  4. No XQuery processor supporting the optional Module Feature is available.

If a dynamic error (including a dynamically detected type error) is encountered when processing the module (for example, when evaluating its global variables), the dynamic error is returned as is.

Notes

If a function declaration F in the loaded module declares (say) four parameters of which one is optional, its arity range will be from 3 to 4, so the result will include two function items corresponding to F#3 and F#4. In the lower-arity function item, F#3, the fourth parameter will take its default value. If the expression that initializes the default value is context sensitive, the static and dynamic context for its evaluation are the static and dynamic contexts of the fn:load-xquery-module function call itself.

As with all other functions in this specification, conformance requirements depend on the host language. For example, a host language might specify that provision of this function is optional, or that it is excluded entirely, or that implementations are required to support XQuery modules using a specified version of XQuery.

Even where support for this function is mandatory, it is recommended for security reasons that implementations should provide a user option to disable its use, or to disable aspects of its functionality.

The load-xquery-module function does not modify the static or dynamic context. Functions and variables from the loaded module become available within the result returned by the function, but they are not added to the static or dynamic context of the caller. This means, for example, that function-lookup will not locate functions from the loaded module.

Examples
Expression:
let $expr := "2 + 2"
let $module := `xquery version "4.0"; 
                module namespace dyn="http://example.com/dyn";
                declare %public variable $dyn:value := {$expr};`
let $exec := load-xquery-module("http://example.com/dyn", 
                                {'content':$module})
let $variables := $exec?variables
return $variables(QName("http://example.com/dyn", "value"))
Result:
4

16.3.2 fn:transform

Summary

Invokes a transformation using a dynamically loaded XSLT stylesheet.

Signature
fn:transform(
$options as map(*)
) as map(*)
Properties

This function is ·nondeterministic·, ·context-dependent·, and ·focus-independent·.

Rules

This function loads an XSLT stylesheet and invokes it to perform a transformation.

The inputs to the transformation are supplied in the form of a map. The ·option parameter conventions· apply to this map; they do not apply to any nested map unless otherwise specified.

The function first identifies the requested XSLT version, as follows:

  • If the xslt-version option is present, the requested XSLT version is the value of that option.

  • Otherwise, the requested XSLT version is the value of the [xsl:]version attribute of the outermost element in the supplied stylesheet or package.

The function then attempts to locate an XSLT processor that implements the requested XSLT version.

  • If a processor that implements the requested XSLT version is available, then it is used.

  • Otherwise, if a processor that implements a version later than the requested version is available, then it is used.

  • Otherwise, the function fails indicating that no suitable XSLT processor is available.

Note:

The phrase locate an XSLT processor includes the possibility of locating a software product and configuring it to act as an XSLT processor that implements the requested XSLT version.

If more than one XSLT processor is available under the above rules, then the one that is chosen may be selected according to the availability of requested features: see below.

Once an XSLT processor has been selected that implements a given version of XSLT, the processor follows the rules of that version of the XSLT specification. This includes any decision to operate in backwards or forwards compatibility mode. For example, if an XSLT 2.0 processor is selected, and the stylesheet specifies version="1.0", then the processor will operate in backwards compatibility mode; if the same processor is selected and the stylesheet specifies version="3.0", the processor will operate in forwards compatibility mode.

The combinations of options that are relevant to each version of XSLT, other than xslt-version itself, are listed below. This is followed by a table giving the meaning of each option.

  1. For invocation of an XSLT 1.0 processor (see [XSL Transformations (XSLT) Version 1.0]), the supplied options must include all of the following (if anything else is present, it is ignored):

    1. The stylesheet, provided by supplying exactly one of the following:

      stylesheet-location
      stylesheet-node
      stylesheet-text

    2. The source tree, provided as the value of the source-node option.

    3. Zero or more of the following additional options:

      stylesheet-base-uri
      stylesheet-params (defaults to an empty map)
      initial-mode (defaults to the stylesheet’s default mode)
      delivery-format (defaults to document)
      serialization-params (defaults to an empty map)
      enable-messages (default is implementation-defined)
      requested-properties (default is an empty map)
      vendor-options (defaults to an empty map)
      cache (default is implementation-defined)

  2. For invocation of an XSLT 2.0 processor (see [XSL Transformations (XSLT) Version 2.0]), the supplied options must include all of the following (if anything else is present, it is ignored):

    1. The stylesheet, provided by supplying exactly one of the following:

      stylesheet-location
      stylesheet-node
      stylesheet-text

    2. Invocation details, as exactly one of the following:

      1. For apply-templates invocation, all of the following:

        source-node

        Optionally, initial-mode (defaults to the stylesheet’s default mode)

      2. For call-template invocation, all of the following:

        initial-template

        Optionally, source-node

    3. Zero or more of the following additional options:

      stylesheet-base-uri
      stylesheet-params (defaults to an empty map)
      base-output-uri (defaults to absent)
      delivery-format (defaults to document)
      serialization-params (defaults to an empty map)
      enable-messages (default is implementation-defined)
      enable-trace (default is implementation-defined)
      requested-properties (default is an empty map)
      vendor-options (defaults to an empty map)
      cache (default is implementation-defined)

  3. For invocation of an XSLT 3.0 processor (see [XSL Transformations (XSLT) Version 4.0]), the supplied options must include all of the following (if anything else is present, it is ignored):

    1. The stylesheet, provided either by supplying exactly one of the following:

      stylesheet-location
      stylesheet-node
      stylesheet-text

      Or by supplying exactly one of the following:

      package-location
      package-node
      package-text
      package-name plus optionally package-version

    2. Invocation details, as exactly one of the following combinations:

      1. For apply-templates invocation, all of the following:

        Exactly one of source-node or initial-match-selection

        Optionally, initial-mode

        Optionally, template-params

        Optionally, tunnel-params

      2. For call-template invocation using an explicit template name, all of the following:

        initial-template

        Optionally, template-params

        Optionally, tunnel-params

        Optionally, source-node

      3. For call-template invocation using the defaulted template name xsl:initial-template, all of the following:

        Optionally, template-params

        Optionally, tunnel-params

        Note:

        If the source-node option is present and initial-template is absent, then apply-templates invocation will be used. To use call-template invocation on the template named xsl:initial-template while also supplying a context item for use when evaluating global variables, either (a) supply the context item using the global-context-item option, or (b) supply source-node, and set the initial-template option explicitly to the QName xsl:initial-template

      4. For call-function invocation, all of the following:

        initial-function

        function-params

      Note:

      The invocation method can be determined as the first of the following which applies:

      • If initial-function is present, then call-function invocation.

      • If initial-template is present, then call-template invocation.

      • If source-node or initial-match-selection is present, then apply-templates invocation.

      • Otherwise, call-template invocation using the default entry point xsl:initial-template.

    3. Zero or more of the following additional options:

      stylesheet-base-uri
      static-params (defaults to an empty map)
      stylesheet-params (defaults to an empty map)
      global-context-item (defaults to absent)
      base-output-uri (defaults to absent)
      delivery-format
      serialization-params (defaults to an empty map)
      enable-assertions (default is false)
      enable-messages (default is implementation-defined)
      enable-trace (default is implementation-defined)
      requested-properties (default is an empty map)
      vendor-options (defaults to an empty map)
      cache (default is implementation-defined)

The meanings of each option are defined in the table below.

record(
base-output-uri? as xs:string,
cache? as xs:boolean,
delivery-format? as xs:string,
enable-assertions? as xs:boolean,
enable-messages? as xs:boolean,
enable-trace? as xs:boolean,
function-params? as array(item()*),
global-context-item? as item(),
initial-function? as xs:QName,
initial-match-selection? as item()*,
initial-mode? as xs:QName,
initial-template? as xs:QName,
package-name? as xs:string,
package-location? as xs:string,
package-node? as node(),
package-text? as xs:string,
package-version? as xs:string,
post-process? as fn(xs:string, item()*) as item()*,
requested-properties? as map(xs:QName, xs:anyAtomicType),
serialization-params? as map(xs:anyAtomicType, item()*),
source-node? as node(),
static-params? as map(xs:QName, item()*),
stylesheet-base-uri? as xs:string,
stylesheet-location? as xs:string,
stylesheet-node? as node(),
stylesheet-params? as map(xs:QName, item()*),
stylesheet-text? as xs:string,
template-params? as map(xs:QName, item()*),
tunnel-params? as map(xs:QName, item()*),
vendor-options? as { xs:QName, item()* },
xslt-version? as xs:decimal
)
Key Applies to Value Meaning

base-output-uri

1.0, 2.0, 3.0 The URI of the principal result document; also used as the base URI for resolving relative URIs of secondary result documents. If the value is a relative reference, it is resolved against the static base URI of the fn:transform function call.
  • Type: xs:string

  • Default: The effect of not supplying a base output URI is defined by the XSLT specification; the implementation may supply a default, for example the directory containing the stylesheet, or the current working directory.

cache

1.0, 2.0, 3.0 This option has no effect on the result of the transformation but may affect efficiency. The value true indicates an expectation that the same stylesheet is likely to be used for more than one transformation; the value false indicates an expectation that the stylesheet will be used once only.
  • Type: xs:boolean

  • Default: true()

delivery-format

1.0, 2.0, 3.0 The manner in which the transformation results should be delivered. Applies both to the principal result document and to secondary result documents created using xsl:result-document.
  • Type: xs:string

  • Default: document

    If the relevant xsl:output or xsl:result-document element specifies build-tree="no" (applies to XSLT 3.0 only), then the default is raw.

document The result is delivered as a document node.
serialized The result is delivered as a string, representing the results of serialization. Note that (as with the fn:serialize function) the final encoding stage of serialization (which turns a sequence of characters into a sequence of octets) is either skipped, or reversed by decoding the octet stream back into a character stream.
raw The result of the initial template or function is returned as an arbitrary XDM value (after conversion to the declared type, but without wrapping in a document node, and without serialization): when this option is chosen, the returned map contains the raw result.

enable-assertions

3.0 Indicates whether any xsl:assert instructions in the stylesheet are to be evaluated.
  • Type: xs:boolean

  • Default: false()

enable-messages

1.0, 2.0, 3.0 Indicates whether any xsl:message instructions in the stylesheet are to be evaluated. The destination and formatting of any such messages is implementation-defined.

enable-trace

2.0, 3.0 Indicates whether any fn:trace functions in the stylesheet are to generate diagnostic messages. The destination and formatting of any such messages is implementation-defined.

function-params

3.0 An array of values to be used as the arguments to the initial function call. The value is converted to the required type of the declared parameter using the function conversion rules.
  • Type: array(item()*)

  • Default: Empty array

global-context-item

3.0 The value of the global context item, as defined in XSLT 3.0
  • Type: item()

  • Default: The value of source-node

initial-function

3.0 The name of the initial function to be called for call-function invocation. The arity of the function is inferred from the length of function-params.
  • Type: xs:QName

  • Default: n/a

initial-match-selection

3.0 The value of the initial match selection, as defined in XSLT 3.0
  • Type: item()*

  • Default: The value of source-node

initial-mode

1.0, 2.0, 3.0 The name of the initial processing mode.
  • Type: xs:QName

  • Default: none

initial-template

2.0, 3.0 The name of a named template in the stylesheet to act as the initial entry point.
  • Type: xs:QName

  • Default: xsl:initial-template

package-name

3.0 The name of the top-level stylesheet package to be invoked (an absolute URI)
  • Type: xs:string

  • Default: n/a

package-location

3.0 The location of the top-level stylesheet package, as a relative or absolute URI
  • Type: xs:string

  • Default: n/a

package-node

3.0 A document or element node containing the top-level stylesheet package
  • Type: node()

  • Default: n/a

package-text

3.0 The top-level stylesheet package in the form of unparsed lexical XML.
  • Type: xs:string

  • Default: n/a

package-version

3.0 The version of the top-level stylesheet package to be invoked.
  • Type: xs:string

  • Default: "*" (any version)

post-process

1.0 2.0 3.0 A function that is used to post-process each result document of the transformation (both the principal result and secondary results), in whatever form it would otherwise be delivered (document, serialized, or raw). The first argument of the function is the key used to identify the result in the map return by the fn:transform function (for example, this will be the supplied base output URI in the case of the principal result, or the string “output” if no base output URI was supplied). The second argument is the actual value. The value that is returned in the result of the fn:transform function is the result of applying this post-processing.

Note:

If the implementation provides a way of writing or invoking functions with side-effects, this post-processing function might be used to save a copy of the result document to persistent storage. For example, if the implementation provides access to the EXPath File library [EXPath], then a serialized document might be written to filestore by calling the file:write function. Similar mechanisms might be used to issue an HTTP POST request that posts the result to an HTTP server, or to send the document to an email recipient. The semantics of calling functions with side-effects are entirely ·implementation-defined·.

If the primary purpose of the post-processing function is achieved by means of such side-effects, and if the actual results are not needed by the caller of the fn:transform function, then it does not matter what the post-processing function actually returns (it could be an empty sequence, for example).

Calls to fn:transform can potentially have side-effects even in the absence of the post-processing option, because the XSLT specification allows a stylesheet to invoke extension functions that have side-effects. The semantics in this case are ·implementation-defined·.

  • Type: fn(xs:string, item()*) as item()*

  • Default: fn($a, $b) { $b }

requested-properties

1.0, 2.0, 3.0 The keys in the map are QNames that could legitimately be supplied in a call to the XSLT system-property function; the values in the map are the requested settings of the corresponding property. The boolean values true() and false() are equivalent to the string values yes and no. As a special case, setting a value for xsl:version has no effect, because of the potential for conflict with other options. For example:
  • Setting xsl:product-name to a particular value requests a particular XSLT software product.

  • Setting xsl:product-version requests a specific version of that product.

  • Setting xsl:is-schema-aware to true() requests a schema-aware processor.

  • Setting xsl:xsd-version to "1.1" requests a processor that supports XML Schema version 1.1.

Setting a boolean property such as xsl:supports-dynamic-evaluation to false() is interpreted as an explicit request for a processor in which the value of the property is false. The effect if the requests cannot be precisely met is implementation-defined. In some cases it may be appropriate to ignore the request or to provide an alternative (for example, a later version of the product than the one requested); in other cases it may be more appropriate to raise an error [err:FOXT0001] indicating that no suitable XSLT processor is available.
  • Type: map(xs:QName, xs:anyAtomicType)

  • Default: Empty map

serialization-params

1.0, 2.0, 3.0 Serialization parameters for the principal result document. The supplied map follows the same rules that apply to a map supplied as the second argument of fn:serialize.
  • When a parameter is supplied, the corresponding value overrides or augments the value specified in the unnamed xsl:output declaration (or its default), following the same rules as when one xsl:output declaration overrides another with lower import precedence.

  • When a parameter is supplied and the corresponding value is an empty sequence (for example, { "standalone": () }), any value specified in the unnamed xsl:output declaration is overridden by the default value.

  • When a parameter is not supplied in serialization-params (that is, when the key is absent) the value that applies is the value appearing in the unnamed xsl:output declaration, or its default.

  • Type: map(xs:anyAtomicType, item()*)

  • Default: Empty map

source-node

1.0, 2.0, 3.0 When source-node is supplied then the global-context-item (the context item for evaluating global variables) is the root of the tree containing the supplied node. In addition, for apply-templates invocation, the source-node acts as the initial-match-selection, that is, stylesheet execution starts by applying templates to this node.
  • Type: node()

  • Default: n/a

static-params

3.0 The values of static parameters defined in the stylesheet; the keys are the names of the parameters, and the associated values are their values. The value is converted to the required type of the declared parameter using the coercion rules.
  • Type: map(xs:QName, item()*)

  • Default: Empty map

stylesheet-base-uri

1.0, 2.0, 3.0 A string intended to be used as the static base URI of the principal stylesheet module. This value must be used if no other static base URI is available. If the supplied stylesheet already has a base URI (which will generally be the case if the stylesheet is supplied using stylesheet-node or stylesheet-location) then it is ·implementation-defined· whether this parameter has any effect. If the value is a relative reference, it is resolved against the static base URI of the fn:transform function call.
  • Type: xs:string

  • Default: n/a

stylesheet-location

1.0, 2.0, 3.0 URI that can be used to locate the principal stylesheet module. If relative, it is resolved against the static base URI of the fn:transform function call. The value also acts as the default for stylesheet-base-uri.
  • Type: xs:string

  • Default: n/a

stylesheet-node

1.0, 2.0, 3.0 Root of the tree containing the principal stylesheet module, as a document or element node. The base URI of the node acts as the default for stylesheet-base-uri.
  • Type: node()

  • Default: n/a

stylesheet-params

1.0, 2.0, 3.0 A map holding values to be supplied for stylesheet parameters. The keys are the parameter names; the values are the corresponding parameter values. The values are converted if necessary to the required type using the coercion rules. The default is an empty map.
  • Type: map(xs:QName, item()*)

  • Default: Empty map

stylesheet-text

1.0, 2.0, 3.0 The principal stylesheet module in the form of unparsed lexical XML.
  • Type: xs:string

  • Default: n/a

template-params

3.0 The values of non-tunnel parameters to be supplied to the initial template, used with both apply-templates and call-template invocation. Each value is converted to the required type of the declared parameter using the coercion rules.
  • Type: map(xs:QName, item()*)

  • Default: none

tunnel-params

3.0 The values of tunnel parameters to be supplied to the initial template, used with both apply-templates and call-template invocation. Each value is converted to the required type of the declared parameter using the coercion rules.
  • Type: map(xs:QName, item()*)

  • Default: Empty map

vendor-options

1.0, 2.0, 3.0 Values for vendor-defined configuration options for the XSLT processor used to process the request. The key is the name of an option, expressed as a QName: the namespace URI of the QName should be a URI controlled by the vendor of the XSLT processor. The meaning of the associated value is ·implementation-defined·. Implementations should ignore options whose names are in an unrecognized namespace. Default is an empty map.
  • Type: { xs:QName, item()* }

  • Default: Empty map

xslt-version

1.0, 2.0, 3.0 The minimum level of the XSLT language that the processor must support.
  • Type: xs:decimal

  • Default: The [xsl:]version attribute at the outermost level of the stylesheet.

The result of the transformation is returned as a map. There is one entry in the map for the principal result document, and one for each secondary result document. The key is a URI in the form of an xs:string value. The key for the principal result document is the base output URI if specified, or the string "output" otherwise. The key for secondary result documents is the URI of the document, as an absolute URI. The associated value in each entry depends on the requested delivery format. If the delivery format is document, the value is a document node. If the delivery format is serialized, the value is a string containing the serialized result.

Where nodes are passed to or from the transformation, for example as the value of a stylesheet parameter or the result of a function, they should if possible retain their node identity, their base URI, their type annotations, and their relationships to all other nodes in the containing tree (including ancestors and siblings). If this is not possible, for example because the only way of passing nodes to the chosen XSLT implementation is by serializing and re-parsing, then a node may be passed in the form of a deep copy, which may lose information about the identity of the node, about its ancestors and siblings, about its base URI, about its type annotation, and about its relationships to other nodes passed across the interface.

It is ·implementation-defined· whether the XSLT transformation is executed within the same ·execution scope· as the calling code.

The function is ·nondeterministic· in that it is ·implementation-dependent· whether running the function twice against the same inputs produces identical results. The results of two invocations may differ in the identity of any returned nodes; they may also differ in other respects, for example because the value of fn:current-dateTime is different for the two invocations, or because the contents of external documents accessed using fn:doc or xsl:source-document change between one invocation and the next.

Error Conditions

A dynamic error is raised [err:FOXT0001] if the transformation cannot be invoked because no suitable XSLT processor is available. This includes (but is not limited to) the following cases:

  1. No XSLT processor is available;

  2. No XSLT processor supporting the requested version of XSLT is available;

  3. The XSLT processor API does not support some requested feature (for example, the ability to supply tunnel parameters externally);

A dynamic error is raised [err:FOXT0002] if an error is detected in the supplied parameters (for example if two mutually exclusive parameters are supplied).

If a static or dynamic error is reported by the XSLT processor, this function fails with a dynamic error, retaining the XSLT error code.

A dynamic error is raised [err:FOXT0003] if the XSLT transformation invoked by a call on fn:transform fails with a static or dynamic error, and no more specific error code is available.

Note:

XSLT 1.0 does not define any error codes, so this is the likely outcome with an XSLT 1.0 processor. XSLT 2.0 and 3.0 do define error codes, but some APIs do not expose them. If multiple errors are signaled by the transformation (which is most likely to happen with static errors) then the error code should where possible be that of one of these errors, chosen arbitrarily; the processor may make details of additional errors available to the application in an ·implementation-defined· way.

A dynamic error is raised [err:FOXT0004] if the use of this function (or of selected options) has been externally disabled, for example for security reasons.

A dynamic error is raised [err:FOXT0006] if the transformation produces output containing characters available only in XML 1.1, and the calling processor cannot handle such characters.

Recursive use of the fn:transform function may lead to catastrophic failures such as non-termination or stack overflow. No error code is assigned to such conditions, since they cannot necessarily be detected by the processor.

Notes

As with all other functions in this specification, conformance requirements depend on the host language. For example, a host language might specify that provision of this function is optional, or that it is excluded entirely, or that implementations are required to support a particular set of values for the xslt-version parameter.

Even where support for this function is mandatory, it is recommended for security reasons that implementations should provide a user option to disable its use, or to disable aspects of its functionality such as the ability to write to persistent resources.

Examples

The following example loads a stylesheet from the location render.xsl, applies it to a document loaded from test.xml, and uses an XPath expression to examine the result:

let $result := transform({
  "stylesheet-location": "render.xsl",
  "source-node": doc('test.xml')
})
return $result?output//body

16.3.3 fn:op

Changes in 4.0  

  1. New in 4.0  [Issue 83 PR 173 11 October 2022]

Summary

Returns a function whose effect is to apply a supplied binary operator to two arguments.

Signature
fn:op(
$operator as xs:string
) as fn(item()*, item()*) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The supplied operator must be one of:

",", "and", "or", "+", "-", "*", "div", "idiv", "mod", "=", "<", "<=", ">", ">=", "!=", "eq", "lt", "le", "gt", "ge", "ne", "<<", ">>", "is", "||", "|", "union", "except", "intersect", "to", "otherwise"

The result of calling fn:op("⊙"), where is one of the above operators, is the function represented by the XPath expression:

fn($x, $y) { $x ⊙ $y }

For example, op("+") returns fn($x, $y) { $x + $y }.

Error Conditions

A type error is raised [err:XPTY0004]XP if the supplied argument is not one of the supported operators.

Notes

The function is useful in contexts where an arity-2 callback function needs to be supplied, and a standard operator meets the requirement.

For example, the XSLT xsl:map instruction has an on-duplicates attribute that expects such a function. Specifying on-duplicates="op(',')" is equivalent to specifying on-duplicates="fn($x, $y) { $x, $y }

The function is also useful in cases where the choice of operator to apply is made dynamically.

Examples
Expression Result
for-each-pair(21 to 25, 1 to 5, op("+"))
22, 24, 26, 28, 30
for-each-pair(21 to 25, 1 to 5, op("-"))
20, 20, 20, 20, 20

17 Maps

Maps were introduced as a new datatype in XDM 3.1. This section describes functions that operate on maps.

A map is an additional kind of item.

[Definition] A map consists of a set of entries, also known as key-value pairs. Each entry comprises a key which is an arbitrary atomic item, and an arbitrary sequence called the associated value.

[Definition] Within a map, no two entries have the same key. Two atomic items K1 and K2 are the same key for this purpose if the function call fn:atomic-equal($K1, $K2) returns true.

It is not necessary that all the keys in a map should be of the same type (for example, they can include a mixture of integers and strings).

Maps are immutable, and have no identity separate from their content. For example, the map:remove function returns a map that differs from the supplied map by the omission (typically) of one entry, but the supplied map is not changed by the operation. Two calls on map:remove with the same arguments return maps that are indistinguishable from each other; there is no way of asking whether these are “the same map”.

A map can also be viewed as a function from keys to associated values. To achieve this, a map is also a function item. The function corresponding to the map has the signature function($key as xs:anyAtomicValue) as item()*. Calling the function has the same effect as calling the get function: the expression $map($key) returns the same result as get($map, $key). For example, if $books-by-isbn is a map whose keys are ISBNs and whose assocated values are book elements, then the expression $books-by-isbn("0470192747") returns the book element with the given ISBN. The fact that a map is a function item allows it to be passed as an argument to higher-order functions that expect a function item as one of their arguments.

17.1 Composing and Decomposing Maps

It is often useful to decompose a map into a sequence of entries, or key-value pairs (in which the key is an atomic item and the value is an arbitrary sequence). Subsequently it may be necessary to reconstruct a map from these components, typically after modification.

There are two conventional ways of representing key-value pairs, each with its own advantages and disadvantages. Both approaches are supported by functions in this library. These are described below:

  1. [Definition] A singleton map is a map containing a single entry.

    It is possible to decompose any map into a sequence of ·singleton maps·, and to construct a map from a sequence of singleton maps.

    For example the map { "x": 1, "y": 2 } can be decomposed to the sequence ({ "x": 1 }, { "y": 2 }).

  2. [Definition] A key-value pair map is a map containing two entries, one (with the key "key") containing the key part of a key value pair, the other (with the key "value") containing the value part of a key value pair.

    For example the map { "x": 1, "y": 2 } can be decomposed as ({ "key": "x", "value": 1 }, { "key": "y", "value": 2 })

    A ·key-value pair map· is an instance of the type record(key as xs:anyAtomicType, value as item()*).

The following table summarizes the way in which these two representations can be used to compose and decompose maps:

Operation Singleton Maps Key-Value Pair Maps

Decompose a map

map:entries($map)

map:pairs($map)

Compose a map

map:merge($entries)

map:of-pairs($key-value-pairs)

Create a single entry

map:entry($key, $value)

map:pair($key, $value)

Extract the key part of a single entry

map:keys($entry)

$key-value-pair?key

Extract the value part of a single entry

map:values($entry)

$key-value-pair?value

17.2 Formal Specification of Maps

The XDM data model ([XQuery and XPath Data Model (XDM) 4.0]) defines three primitive operations on maps:

  • dm:empty-map constructs an empty map.

  • dm:map-put adds or replaces an entry in a map.

  • dm:iterate-map applies a supplied function to every entry in a map.

The functions in this section are all specified by means of equivalent expressions that either call these primitives directly, or invoke other functions that rely on these primitives. The specifications avoid relying on XPath language constructs that manipulate maps, such as map constructor syntax, lookup expressions, or FLWOR expressions. This is done to allow these language constructs to be specified by reference to this function library, without risk of circularity.

There is one exception to this rule: for convenience, the notation {} is used to represent an empty map, in preference to a call on dm:empty-map().

The formal specifications are not intended to provide a realistic way of implementating the functions (in particular, any real implementation might be expected to implement map:get and map:put much more efficiently). They do, however, provide a framework that allows the correctness of a practical implementation to be verified.

Editorial note  
TODO: as yet there is no formal specification of map:find().

17.3 Functions that Operate on Maps

The functions defined in this section use a conventional namespace prefix map, which is assumed to be bound to the namespace URI http://www.w3.org/2005/xpath-functions/map.

The function call map:get($map, $key) can be used to retrieve the value associated with a given key.

There is no operation to atomize a map or convert it to a string. The function fn:serialize can in some cases be used to produce a JSON representation of a map.

Function Meaning
map:build Returns a map that typically contains one entry for each item in a supplied input sequence.
map:contains Tests whether a supplied map contains an entry for a given key.
map:empty Returns true if the supplied map contains no entries.
map:entries Returns a sequence containing all the key-value pairs present in a map, each represented as a ·singleton map·.
map:entry Returns a ·singleton map· that represents a single key-value pair.
map:filter Selects entries from a map, returning a new map.
map:find Searches the supplied input sequence and any contained maps and arrays for a map entry with the supplied key, and returns the corresponding values.
map:for-each Applies a supplied function to every entry in a map, returning the sequence concatenationXP40 of the results.
map:get Returns the value associated with a supplied key in a given map.
map:keys Returns a sequence containing all the keys present in a map.
map:keys-where Returns a sequence containing selected keys present in a map.
map:merge Returns a map that combines the entries from a number of existing maps.
map:of-pairs Returns a map that combines data from a sequence of ·key-value pair maps·.
map:pair Returns a ·key-value pair map· that represents a single key-value pair.
map:pairs Returns a sequence containing all the key-value pairs present in a map, each represented as a ·key-value pair map·.
map:put Returns a map containing all the contents of the supplied map, but with an additional entry, which replaces any existing entry for the same key.
map:remove Returns a map containing all the entries from a supplied map, except those having a specified key.
map:replace Returns a map based on the contents of an existing map, computing a new value to be associated with a supplied key.
map:size Returns the number of entries in the supplied map.
map:values Returns a sequence containing all the values present in a map, in unpredictable order.

17.3.1 map:build

Changes in 4.0  

  1. New in 4.0  [Issue 151 PR 203 18 October 2022]

Summary

Returns a map that typically contains one entry for each item in a supplied input sequence.

Signature
map:build(
$input as item()*,
$keys as fn(item(), xs:integer) as xs:anyAtomicType* := fn:identity#1,
$value as fn(item(), xs:integer) as item()* := fn:identity#1,
$combine as fn(item()*, item()*) as item()* := fn:op(',')
) as map(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function processes each item in $input in order. It calls the $keys function on that item to obtain a sequence of key values, and the $value function to obtain an associated value. Then, for each key value:

  • If the key is not already present in the target map, the processor adds a new key-value pair to the map, with that key and that value.

  • If the key is already present, the processor calls the $combine function to combine the existing value for the key with the new value, and replaces the entry with this combined value.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

fold-left($input, {}, fn($map, $item, $pos) {
  let $v := $value($item, $pos)
  return fold-left($keys($item, $pos), $map, fn($m, $k) {
    if (map:contains($m, $k)) then (
      map:put($m, $k, $combine($m($k), $v))
    ) else (
      map:put($m, $k, $v)
    )
  })
})
Notes

Although defined to process the input sequence in order, this is only relevant when combining the entries for duplicate keys.

The default function for both $keys and $value is the identity function. Although it is permitted to default both, this serves little purpose: usually at least one of these arguments will be supplied.

The default action for combining entries with duplicate keys is to perform a sequence concatenationXP40 of the corresponding values, equivalent to the duplicates: combine option on map:merge. Other potentially useful functions for combining duplicates include:

  • fn($a, $b) { $a } Use the first value and discard the remainder

  • fn($a, $b) { $b } Use the last value and discard the remainder

  • fn:concat(?, ",", ?) Form the string-concatenation of the values, comma-separated

  • fn:op('+') Compute the sum of the values

Examples
Expression:

map:build((), string#1)

Result:
{}
Expression:

map:build(1 to 10, fn { . mod 3 })

Result:
{ 0: (3, 6, 9), 1: (1, 4, 7, 10), 2: (2, 5, 8) }

(Returns a map with one entry for each distinct value of . mod 3. The function to compute the value is the identity function, and duplicates are combined by sequence concatenation.)

Expression:
map:build(
  1 to 5,
  value := format-integer(?, "w")
)
Result:
{ 1: "one", 2: "two", 3: "three", 4: "four", 5: "five" }

(Returns a map with five entries. The function to compute the key is an identity function, the function to compute the value invokes fn:format-integer.)

Expression:
map:build(
  ("January", "February", "March", "April", "May", "June",
   "July", "August", "September", "October", "November", "December"),
  substring(?, 1, 1)
)
Result:
{
  "A": ("April", "August"),
  "D": ("December"),
  "F": ("February"),
  "J": ("January", "June", "July"),
  "M": ("March", "May"),
  "N": ("November"),
  "O": ("October"),
  "S": ("September")
}
Expression:
map:build(
  ("apple", "apricot", "banana", "blueberry", "cherry"), 
  substring(?, 1, 1),
  string-length#1,
  op("+")
)
Result:
{ "a": 12, "b": 15, "c": 6 }

(Constructs a map where the key is the first character of an input item, and where the corresponding value is the total string-length of the items starting with that character.)

Expression:
map:build(
  ('Wang', 'Liu', 'Zhao'),
  keys := fn($name, $pos) { $name },
  value := fn($name, $pos) { $pos }
)
Result:
{ "Wang": 1, "Liu": 2, "Zhao": 3 }

(Returns an inverted index for the input sequence with the string stored as key and the position stored as value.)

Expression:
let $titles := <titles>
  <title>A Beginner’s Guide to <ix>Java</ix></title>
  <title>Learning <ix>XML</ix></title>
  <title>Using <ix>XML</ix> with <ix>Java</ix></title>
</titles>
return map:build($titles/title, fn($title) { $title/ix })
Result:
{
  "Java": (
    <title>A Beginner’s Guide to <ix>Java</ix></title>,
    <title>Using <ix>XML</ix> with <ix>Java</ix></title>
  ),
  "XML": (
    <title>Learning <ix>XML</ix></title>,
    <title>Using <ix>XML</ix> with <ix>Java</ix></title>
  )
}

The following expression creates a map whose keys are employee @ssn values, and whose corresponding values are the employee nodes:

map:build(//employee, fn { @ssn })

The following expression creates a map whose keys are employee @location values, and whose corresponding values represent the number of employees at each distinct location. Any employees that lack an @location attribute will be excluded from the result.

map:build(//employee, fn { @location }, fn { 1 }, op("+"))

The following expression creates a map whose keys are employee @location values, and whose corresponding values contain the employee node for the highest-paid employee at each distinct location:

map:build(
  //employee,
  keys := fn { @location }, 
  combine := fn($a, $b) { highest(($a, $b), fn { xs:decimal(@salary) }) }
)

The following expression creates a map allowing efficient access to every element in a document by means of its fn:generate-id value:

map:build(//*, generate-id#1)

17.3.2 map:contains

Summary

Tests whether a supplied map contains an entry for a given key.

Signature
map:contains(
$map as map(*),
$key as xs:anyAtomicType
) as xs:boolean
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function map:contains returns true if the ·map· supplied as $map contains an entry with the ·same key· as $key; otherwise it returns false.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

some( map:keys($map), atomic-equal(?, $key) )
Examples
Variables
let $week := {
  0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: "Samstag"
}
Expression Result
map:contains($week, 2)
true()
map:contains($week, 9)
false()
map:contains({}, "xyz")
false()
map:contains({ "xyz": 23 }, "xyz")
true()
map:contains({ "abc": 23, "xyz": () }, "xyz")
true()

17.3.3 map:empty

Changes in 4.0  

  1. New in 4.0  [Issues 827 843 PR 969 18 November 2023]

Summary

Returns true if the supplied map contains no entries.

Signature
map:empty(
$map as map(*)
) as xs:boolean
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns true if and only if $map contains no entries, that is, if map:size($map) eq 0.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

map:size($map) eq 0
Examples
Expression Result
map:empty({})
true()
map:empty({ 1: () })
false()

17.3.4 map:entries

Changes in 4.0  

  1. New in 4.0  [Issue 29 PR 314]

Summary

Returns a sequence containing all the key-value pairs present in a map, each represented as a ·singleton map·.

Signature
map:entries(
$map as map(*)
) as map(*)*
Properties

This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.

Rules

The function map:entries takes any ·map· as its $map argument and returns the key-value pairs that are present in the map as a sequence of ·singleton maps·, in ·implementation-dependent· order.

The function is nondeterministic with respect to ordering (see 1.9.5 Properties of functions). This means that two calls with the same argument are not guaranteed to produce the results in the same order.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

map:for-each($map, map:entry#2)
Examples
Expression Result
map:entries(
  { 1: "yes", 2: "no" }
)
({ 1: "yes" }, { 2: "no" })

(or some permutation thereof)

(The result sequence is in ·implementation-dependent· order.)

17.3.5 map:entry

Summary

Returns a ·singleton map· that represents a single key-value pair.

Signature
map:entry(
$key as xs:anyAtomicType,
$value as item()*
) as map(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function map:entry returns a ·map· which contains a single entry. The key of the entry in the new map is $key, and its associated value is $value.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

map:put({}, $key, $value)
Notes

The function map:entry is intended primarily for use in conjunction with the function map:merge. For example, a map containing seven entries may be constructed like this:

map:merge((
  map:entry("Su", "Sunday"),
  map:entry("Mo", "Monday"),
  map:entry("Tu", "Tuesday"),
  map:entry("We", "Wednesday"),
  map:entry("Th", "Thursday"),
  map:entry("Fr", "Friday"),
  map:entry("Sa", "Saturday")
))

The map:merge function can be used to construct a map with a variable number of entries, for example:

map:merge(//book ! map:entry(isbn, .))
Examples
Expression Result
map:entry("M", "Monday")
{ "M": "Monday" }

17.3.6 map:filter

Changes in 4.0  

  1. New in 4.0

  2. The $predicate callback function may return an empty sequence (meaning false).  [Issue 1171 PR 1182 7 May 2024]

Summary

Selects entries from a map, returning a new map.

Signature
map:filter(
$map as map(*),
$predicate as fn(xs:anyAtomicType, item()*) as xs:boolean?
) as map(*)
Properties

This function is ·context-independent·, and ·focus-independent·.

Rules

The function map:filter takes any ·map· as its $map argument and applies the supplied function to each entry in the map; the result is a new map containing those entries for which the function returns true. A return value of () from the predicate is treated as false.

The function supplied as $predicate takes two arguments. It is called supplying the key of the map entry as the first argument, and the associated value as the second argument.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

map:for-each($map, fn($key, $value) {
                      if ($predicate($key, $value)) {
                         map:pair($key, $value)
                      }
                   })
=> map:of-pairs()
Examples
Expression:
map:filter(
  { 1: "Sunday", 2: "Monday", 3: "Tuesday", 4: "Wednesday",
    5: "Thursday", 6: "Friday", 7: "Saturday" },
  fn($k, $v) { $k = (1, 7) }
)
Result:
{ 1: "Sunday", 7: "Saturday" }
Expression:
map:filter(
  { 1: "Sunday", 2: "Monday", 3: "Tuesday", 4: "Wednesday",
    5: "Thursday", 6: "Friday", 7: "Saturday" },
  fn($k, $v) { $v = ("Saturday", "Sunday") }
)
Result:
{ 1: "Sunday", 7: "Saturday" }

17.3.7 map:find

Summary

Searches the supplied input sequence and any contained maps and arrays for a map entry with the supplied key, and returns the corresponding values.

Signature
map:find(
$input as item()*,
$key as xs:anyAtomicType
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function map:find searches the sequence supplied as $input looking for map entries whose key is the ·same key· as $key. The associated value in any such map entry (each being in general a sequence) is returned as a member of the result array.

The search processes the $input sequence using the following recursively defined rules (any equivalent algorithm may be used provided it delivers the same result, respecting those rules that constrain the order of the result):

  1. To process a sequence, process each of its items in order.

  2. To process an item that is an array, process each of its members in order (each member is, in general, a sequence).

  3. To process an item that is a map, then for each key-value entry (K, V) in the map (in ·implementation-dependent· order) perform both of the following steps, in order:

    1. If K is the ·same key· as $key, then add V as a new member to the end of the result array.

    2. Process V (which is, in general, a sequence).

  4. To process an item that is neither a map nor an array, do nothing. (Such items are ignored).

Notes

If $input is an empty sequence, map, or array, or if the requested $key is not found, the result will be a zero-length array.

Examples
Variables
let $responses := [
  { 0: 'no', 1: 'yes' },
  { 0: 'non', 1: 'oui' },
  { 0: 'nein', 1: ('ja', 'doch') }
]
let $inventory := {
  "name": "car",
  "id": "QZ123", 
  "parts": [ { "name": "engine", "id": "YW678", "parts": [] } ]
}
Expression:

map:find($responses, 0)

Result:
[ 'no', 'non', 'nein' ]
Expression:

map:find($responses, 1)

Result:
[ 'yes', 'oui', ('ja', 'doch') ]
Expression:

map:find($responses, 2)

Result:
[]
Expression:

map:find($inventory, "parts")

Result:
[
  [ { "name": "engine", "id": "YW678", "parts": [] } ],
  []
]

17.3.8 map:for-each

Summary

Applies a supplied function to every entry in a map, returning the sequence concatenationXP40 of the results.

Signature
map:for-each(
$map as map(*),
$action as fn(xs:anyAtomicType, item()*) as item()*
) as item()*
Properties

This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.

Rules

The function map:for-each takes any ·map· as its $map argument and applies the supplied function to each entry in the map, in ·implementation-dependent· order; the result is the sequence obtained by concatenating the results of these function calls.

The function is nondeterministic with respect to ordering (see 1.9.5 Properties of functions). This means that two calls with the same arguments are not guaranteed to process the map entries in the same order.

The function supplied as $action takes two arguments. It is called supplying the key of the map entry as the first argument, and the associated value as the second argument.

Formal Specification

The function is defined as follows, making use of primitive constructors and accessors defined in [XQuery and XPath Data Model (XDM) 4.0].

dm:iterate-map($map, $action)
Examples
Expression:
map:for-each(
  { 1: "yes", 2: "no" },
  fn($k, $v) { $k }
)
Result:
(1, 2)

(or some permutation thereof)

(This function call is equivalent to calling map:keys. The result is in implementation-dependent order.)

Expression:
distinct-values(
  map:for-each(
    { 1: "yes", 2: "no" },
    fn($k, $v) { $v }
  )
)
Result:
("yes", "no")

(or some permutation thereof)

(This function call returns the distinct values present in the map, in implementation-dependent order.)

Expression:
map:merge(
  map:for-each(
    { "a": 1, "b": 2 },
    fn($k, $v) { map:entry($k, $v + 1) }
  )
)
Result:
{ "a": 2, "b": 3 }

(This function call returns a map with the same keys as the input map, with the value of each entry increased by one.)

This XQuery example converts the entries in a map to attributes on a newly constructed element node:

let $dimensions := { 'height': 3, 'width': 4, 'depth': 5 }
return <box>{
  map:for-each($dimensions, fn($k, $v) { attribute { $k } { $v } })
}</box>

The result is the element <box height="3" width="4" depth="5"/>.

17.3.9 map:get

Summary

Returns the value associated with a supplied key in a given map.

Signature
map:get(
$map as map(*),
$key as xs:anyAtomicType,
$fallback as fn(xs:anyAtomicType) as item()* := void#1
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function map:get attempts to find an entry within the ·map· supplied as $map that has the ·same key· as $key. If there is such an entry, it returns the associated value; if not, it invokes the supplied $fallback function, supplying the requested $key value as the argument, and returns the result of this call. The default $fallback function always returns an empty sequence.

Formal Specification

The function is defined as follows, making use of primitive constructors and accessors defined in [XQuery and XPath Data Model (XDM) 4.0].

let $entry := dm:iterate-map($map, 
                             fn($k, $v) {
                                if (atomic-equal($k, $key)) {
                                   map:entry($k, $v)
                                }
                             })
return if (exists($entry))
       then map:values($entry)
       else $fallback($key)
Notes

A return value of () from map:get could indicate that the key is present in the map with an associated value of (), or it could indicate that the key is not present in the map. The two cases can be distinguished by calling map:contains, or by using a $fallback function to return a value known never to appear in the map.

The $fallback function can be used in a number of ways:

  • It might return a conventional value such as NaN to indicate that no matching key was found.

  • It might raise a dynamic error, by means of a call on fn:error.

  • It might compute a result algorithmically. For example, if the map holds a table of abbreviations, such as { 'CA': 'Canada', 'UK': 'United Kingdom', 'US': 'United States' }, then specifying fallback := fn:identity#1 has the effect that the key value is returned unchanged if it is not found in the map.

Invoking the ·map· as a function item has the same effect as calling get with no $fallback function: that is, when $map is a map, the expression $map($K) is equivalent to map:get($map, $K). Similarly, the expression map:get(map:get(map:get($map, 'employee'), 'name'), 'first') can be written as $map('employee')('name')('first').

Examples
Variables
let $week := {
  0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: "Samstag"
}
Expression:

map:get($week, 4)

Result:
"Donnerstag"
Expression:

map:get($week, 9)

Result:
()

(When the key is not present, the function returns an empty sequence.)

Expression:

map:get(map:entry(7,()), 7)

Result:
()

(An empty sequence as the result can also signify that the key is present and the associated value is an empty sequence.)

Expression:
{ 1: "single", 2: "double", 3: "triple" }
=> map:get(10, fn { . || "-fold" })
Result:
"10-fold"

(The map holds special cases; the fallback function handles other cases.)

17.3.10 map:keys

Summary

Returns a sequence containing all the keys present in a map.

Signature
map:keys(
$map as map(*)
) as xs:anyAtomicType*
Properties

This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function map:keys takes any ·map· as its $map argument and returns the keys that are present in the map as a sequence of atomic items, in ·implementation-dependent· order.

The function is nondeterministic with respect to ordering (see 1.9.5 Properties of functions). This means that two calls with the same argument are not guaranteed to produce the results in the same order.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

map:for-each($map, fn($key, $value) { $key })
Notes

The number of items in the result will be the same as the number of entries in the map, and the result sequence will contain no duplicate values.

Examples
Expression Result
map:keys({ 1: "yes", 2: "no" })
(1, 2)

(or some permutation thereof)

(The result is in ·implementation-dependent· order.)

17.3.11 map:keys-where

Changes in 4.0  

  1. New in 4.0  [Issues 467 504 PRs 478 515]

  2. The $predicate callback function may return an empty sequence (meaning false).  [Issue 1171 PR 1182 7 May 2024]

Summary

Returns a sequence containing selected keys present in a map.

Signature
map:keys-where(
$map as map(*),
$predicate as fn(xs:anyAtomicType, item()*) as xs:boolean?
) as xs:anyAtomicType*
Properties

This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function map:keys takes any ·map· as its $map argument. The $predicate function takes the key and the value of the corresponding map entry as an argument, and the result is a sequence containing the keys of those entries for which the predicate function returns true in ·implementation-dependent· order. A return value of () is treated as false.

The function is nondeterministic with respect to ordering (see 1.9.5 Properties of functions). This means that two calls with the same argument are not guaranteed to produce the results in the same order.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

map:for-each($map, fn($key, $value) {
  if ($predicate($key, $value)) { $key }
})
Examples
Expression:
let $numbers := {
  0: "zero",
  1: "one",
  2: "two",
  3: "three"
}
return map:keys-where(
  $numbers,
  fn($key, $value) { $value = ("two", "three") }
)
Result:
(2, 3)

(or some permutation thereof)

Expression:
let $square := map:merge(
  (1 to 5) ! map:entry(., . * .)
)
return map:keys-where(
  $square,
  fn($key, $value) { $value > 5 and $value < 20 }
)
Result:
(3, 4)

(or some permutation thereof)

Expression:
let $birthdays := {
  "Agnieszka": xs:date("1980-12-31"),
  "Jabulile": xs:date("2001-05-05"),
  "Joel": xs:date("1969-11-10"),
  "Midori": xs:date("2012-01-08")
}
return map:keys-where($birthdays, fn($name, $date) {
  starts-with($name, "J") and year-from-date($date) = 1969
})
Result:
"Joel"

17.3.12 map:merge

Summary

Returns a map that combines the entries from a number of existing maps.

Signature
map:merge(
$maps as map(*)*,
$options as map(*)? := {}
) as map(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function map:merge returns a map that is formed by combining the contents of the maps supplied in the $maps argument.

Informally, the supplied maps are combined as follows:

  1. There is one entry in the returned map for each distinct key present in the union of the input maps, where two keys are distinct if they are not the ·same key·.

  2. If there are duplicate keys, that is, if two or more maps contain entries having the ·same key·, then the way this is handled is controlled by the second ($options) argument.

The definitive specification is as follows.

  1. If the second argument is omitted or an empty sequence, the effect is the same as calling the two-argument function with an empty map as the value of $options.

  2. The $options argument can be used to control the way in which duplicate keys are handled. The ·option parameter conventions· apply.

  3. The entries that may appear in the $options map are as follows:

    record(
    duplicates? as xs:string
    )
    Key Value Meaning

    duplicates

    Determines the policy for handling duplicate keys: specifically, the action to be taken if two maps in the input sequence $maps contain entries with key values K1 and K2 where K1 and K2 are the ·same key·.
    • Type: xs:string

    • Default: use-first

    reject An error is raised [err:FOJS0003] if duplicate keys are encountered.
    use-first If duplicate keys are present, all but the first of a set of duplicates are ignored, where the ordering is based on the order of maps in the $maps argument.
    use-last If duplicate keys are present, all but the last of a set of duplicates are ignored, where the ordering is based on the order of maps in the $maps argument.
    use-any If duplicate keys are present, all but one of a set of duplicates are ignored, and it is ·implementation-dependent· which one is retained.
    combine If duplicate keys are present, the result map includes an entry for the key whose associated value is the sequence concatenationXP40 of all the values associated with the key, retaining order based on the order of maps in the $maps argument. The key value in the result map that corresponds to such a set of duplicates must be the ·same key· as each of the duplicates, but it is otherwise unconstrained: for example if the duplicate keys are xs:byte(1) and xs:short(1), the key in the result could legitimately be xs:long(1).
Formal Specification

The effect of the function is equivalent to the result of the following XPath expression, except in error cases.

let $FOJS0003 := QName("http://www.w3.org/2005/xqt-errors", "FOJS0003")
let $duplicates-handler := {
  "use-first": fn($a, $b) { $a },
  "use-last":  fn($a, $b) { $b },
  "combine":   fn($a, $b) { $a, $b },
  "reject":    fn($a, $b) { fn:error($FOJS0003) },
  "use-any":   fn($a, $b) { fn:random-number-generator()?permute(($a, $b))[1] }
}
let $combine := fn($A as map(*), $B as map(*), $deduplicator as fn(*)) {
  fold-left(map:keys($B), $A, fn($z, $k) { 
    if (map:contains($z, $k))
    then map:put($z, $k, $deduplicator($z($k), $B($k)))
    else map:put($z, $k, $B($k))
  })
}
return fold-left($maps, {},
  $combine(?, ?, $duplicates-handler($options?duplicates otherwise "use-first"))
)
Error Conditions

An error is raised [err:FOJS0003] if the value of $options indicates that duplicates are to be rejected, and a duplicate key is encountered.

An error is raised [err:FOJS0005] if the value of $options includes an entry whose key is defined in this specification, and whose value is not a permitted value for that key.

Notes

Note:

By way of explanation, $combine is a function that combines two maps by iterating over the keys of the second map, adding each key and its corresponding value to the first map as it proceeds. The second call of fn:fold-left in the return clause then iterates over the maps supplied in the call to map:merge, accumulating a single map that absorbs successive maps in the input sequence by calling $combine.

This algorithm processes the supplied maps in a defined order, but processes the keys within each map in implementation-dependent order.

The use of fn:random-number-generator represents one possible conformant implementation for "duplicates": "use-any", but it is not the only conformant implementation and is not intended to be a realistic implementation. The purpose of this option is to allow the implementation to use whatever strategy is most efficient; for example, if the input maps are processed in parallel, then specifying "duplicates": "use-any" means that the implementation does not need to keep track of the original order of the sequence of input maps.

If the input is an empty sequence, the result is an empty map.

If the input is a sequence of length one, the result map is indistinguishable from the supplied map.

There is no requirement that the supplied input maps should have the same or compatible types. The type of a map (for example map(xs:integer, xs:string)) is descriptive of the entries it currently contains, but is not a constraint on how the map may be combined with other maps.

Examples
Variables
let $week := {
  0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: "Samstag"
}
Expression:

map:merge(())

Result:
{}

(Returns an empty map).

Expression:
map:merge((
  map:entry(0, "no"),
  map:entry(1, "yes")
))
Result:
{ 0: "no", 1: "yes" }

(Returns a map with two entries).

Expression:
map:merge(
  ($week, { 7: "Unbekannt" })
)
Result:
{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: "Samstag", 7: "Unbekannt" }

(The value of the existing map is unchanged; the returned map contains all the entries from $week, supplemented with an additional entry.)

Expression:
map:merge(
  ($week, { 6: "Sonnabend" }),
  { "duplicates": "use-last" }
)
Result:
{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: "Sonnabend" }

(The value of the existing map is unchanged; the returned map contains all the entries from $week, with one entry replaced by a new entry. Both input maps contain an entry with the key 6; the one used in the result is the one that comes last in the input sequence.)

Expression:
map:merge(
  ($week, { 6: "Sonnabend" }),
  { "duplicates": "use-first" }
)
Result:
{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: "Samstag" }

(The value of the existing map is unchanged; the returned map contains all the entries from $week, with one entry replaced by a new entry. Both input maps contain an entry with the key 6; the one used in the result is the one that comes first in the input sequence.)

Expression:
map:merge(
  ($week, { 6: "Sonnabend" }),
  { "duplicates": "combine" }
)
Result:
{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: ("Samstag", "Sonnabend") }

(The value of the existing map is unchanged; the returned map contains all the entries from $week, with one entry replaced by a new entry. Both input maps contain an entry with the key 6; the entry that appears in the result is the sequence concatenationXP40 of the entries in the input maps, retaining order.)

17.3.13 map:of-pairs

Changes in 4.0  

  1. New in 4.0

Summary

Returns a map that combines data from a sequence of ·key-value pair maps·.

Signature
map:of-pairs(
$input as record(key as xs:anyAtomicType, value as item()*)*,
$combine as fn(item()*, item()*) as item()* := fn:op(',')
) as map(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function map:of-pairs returns a map that is formed by combining ·key-value pair maps· supplied in the $input argument.

The optional $combine argument can be used to define how duplicate keys should be handled. The default is to form the sequence concatenation of the corresponding values, retaining their order in the input sequence.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

map:build($input, 
          fn($pair) { map:get($pair, 'key') }, 
          fn($pair) { map:get($pair, 'value') }, 
          $combine)
Error Conditions

The function can be made to fail with a dynamic error in the event that duplicate keys are present in the input sequence by supplying a $combine function that invokes the fn:error function.

Notes

If the input is an empty sequence, the result is an empty map.

There is no requirement that the supplied key-value pairs should have the same or compatible types. The type of a map (for example map(xs:integer, xs:string)) is descriptive of the entries it currently contains, but is not a constraint on how the map may be combined with other maps.

Examples
Variables
let $week := {
  0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: "Samstag"
}
Expression:

map:of-pairs(())

Result:
{}

(Returns an empty map).

Expression:

map:of-pairs(map:pairs($week))

Result:
{
  0: "Sonntag",
  1: "Montag", 
  2: "Dienstag",
  3: "Mittwoch", 
  4: "Donnerstag",
  5: "Freitag", 
  6: "Samstag"
}

(The function map:of-pairs is the inverse of map:pairs.)

Expression:
map:of-pairs((
  { "key": 0, "value": "no" },
  { "key": 1, "value": "yes" }
))
Result:
{ 0: "no", 1: "yes" }

(Returns a map with two entries).

Expression:
map:of-pairs((
  map:pairs($week),
  { "key": 7, "value": "Unbekannt" }
))
Result:
{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: "Samstag", 7: "Unbekannt" }

(The value of the existing map is unchanged; the returned map contains all the entries from $week, supplemented with an additional entry.)

Expression:
map:of-pairs((
  map:pairs($week),
  { "key": 6, "value": "Sonnabend" }
))
Result:
{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: ("Samstag", "Sonnabend") }

(The value of the existing map is unchanged; the returned map contains all the entries from $week, with one entry replaced by a new entry. Both input maps contain an entry with the key 6; the one used in the result combines the two supplied values into a single sequence.)

Expression:
map:of-pairs(
  (map:pairs($week), { "key": 6, "value": "Sonnabend" }),
  fn($old, $new) { $new }
)
Result:
{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: "Sonnabend" }

(The value of the existing map is unchanged; the returned map contains all the entries from $week, with one entry replaced by a new entry. Both input maps contain an entry with the key 6; the supplied $combine function ensures that the one used in the result is the one that comes last in the input sequence.)

Expression:
map:of-pairs(
  (map:pairs($week), { "key": 6, "value": "Sonnabend" }),
  fn($old, $new) { `{ $old }|{ $new }` }
)
Result:
{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: "Samstag|Sonnabend" }

(In the result map, the value for key 6 is obtained by concatenating the values from the two input maps, with a separator character.)

17.3.14 map:pair

Changes in 4.0  

  1. New in 4.0

Summary

Returns a ·key-value pair map· that represents a single key-value pair.

Signature
map:pair(
$key as xs:anyAtomicType,
$value as item()*
) as record(key as xs:anyAtomicType, value as item()*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function map:pair returns a ·map· which contains two entries, one (with the key "key") containing $key and the other (with the key "value") containing $value.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

{}
=> map:put("key", $key)
=> map:put("value", $value)
Notes

The function call map:pair(K, V) produces the same result as the expression { "key": K, "value": V }.

The function map:pair is intended primarily for use in conjunction with the function map:of-pairs. A map may be constructed like this:

map:of-pairs((
  map:pair("Su", "Sunday"),
  map:pair("Mo", "Monday"),
  map:pair("Tu", "Tuesday"),
  map:pair("We", "Wednesday"),
  map:pair("Th", "Thursday"),
  map:pair("Fr", "Friday"),
  map:pair("Sa", "Saturday")
))

The map:of-pairs function can be used to construct a map with a variable number of entries, for example:

map:of-pairs(//book ! map:pair(./isbn, .))
Examples
Expression Result
map:pair("M", "Monday")
{ "key": "M", "value": "Monday" }

17.3.15 map:pairs

Changes in 4.0  

  1. New in 4.0

Summary

Returns a sequence containing all the key-value pairs present in a map, each represented as a ·key-value pair map·.

Signature
map:pairs(
$map as map(*)
) as record(key as xs:anyAtomicType, value as item()*)*
Properties

This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.

Rules

The function map:pairs takes any ·map· as its $map argument and returns the keys that are present in the map as a sequence of ·key-value pair maps·, in ·implementation-dependent· order.

A key-value pair map is an instance of type record(key as xs:anyAtomicType, value as item()*): that is a map with two entries, one (with key "key") holding the key, and the other (with key "value") holding the value.

The function is nondeterministic with respect to ordering (see 1.9.5 Properties of functions). This means that two calls with the same argument are not guaranteed to produce the results in the same order.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

map:for-each($map, map:pair#2)
Examples
Expression:
map:pairs(
  { 1: "Y", 2: "N" }
)
Result:
({ "key": 1, "value": "Y" }, { "key": 2, "value": "N" })

(or some permutation thereof)

(The result is in ·implementation-dependent· order.)

17.3.16 map:put

Summary

Returns a map containing all the contents of the supplied map, but with an additional entry, which replaces any existing entry for the same key.

Signature
map:put(
$map as map(*),
$key as xs:anyAtomicType,
$value as item()*
) as map(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function map:put returns a ·map· that contains all entries from the supplied $map, with the exception of any entry whose key is the ·same key· as $key, together with a new entry whose key is $key and whose associated value is $value.

Formal Specification

The function is defined as follows, making use of primitive constructors and accessors defined in [XQuery and XPath Data Model (XDM) 4.0].

dm:map-put($map, $key, $value)
Notes

There is no requirement that the type of $key and $value be consistent with the types of any existing keys and values in the supplied map.

Examples
Variables
let $week := {
  0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: "Samstag"
}
Expression:

map:put($week, 6, "Sonnabend")

Result:
{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: "Sonnabend" }
Expression:

map:put($week, -1, "Unbekannt")

Result:
{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: "Samstag", -1: "Unbekannt" }

17.3.17 map:remove

Summary

Returns a map containing all the entries from a supplied map, except those having a specified key.

Signature
map:remove(
$map as map(*),
$keys as xs:anyAtomicType*
) as map(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function map:remove returns a ·map· containing all the entries in $map except for any entry whose key is the ·same key· as an item in $keys.

No failure occurs if an item in $keys does not correspond to any entry in $map; that key value is simply ignored.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

map:filter($map, fn($k, $v){not(some($keys, atomic-equal($k, ?)))})
Examples
Variables
let $week := {
  0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: "Samstag"
}
Expression:

map:remove($week, 4)

Result:
{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  5: "Freitag", 6: "Samstag" }
Expression:

map:remove($week, 23)

Result:
{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: "Samstag" }
Expression:

map:remove($week, (0, 6 to 7))

Result:
{ 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag",
  5: "Freitag" }
Expression:

map:remove($week, ())

Result:
{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch",
  4: "Donnerstag", 5: "Freitag", 6: "Samstag" }

17.3.18 map:replace

Changes in 4.0  

  1. New in 4.0

Summary

Returns a map based on the contents of an existing map, computing a new value to be associated with a supplied key.

Signature
map:replace(
$map as map(*),
$key as xs:anyAtomicType,
$action as fn(item()*) as item()*
) as map(*)
Properties

This function is ·context-independent·, and ·focus-independent·.

Rules

If the supplied $map contains an existing entry for the supplied $key, then the returned map contains an entry for that $key whose value is obtained by applying the supplied $action to the existing value associated with that key.

Otherwise, the returned map contains an entry for the supplied $key whose value is obtained by applying the supplied $action to an empty sequence.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

if (map:contains($map, $key)) 
then map:put($map, $key, $action(map:get($map, $key)))
else map:put($map, $key, $action(()))
Examples
Expression:

map:replace({ 1: "alpha", 2: "beta" }, 1, upper-case#1)

Result:
{ 1: "ALPHA", 2: "beta" }
Expression:

map:replace({ 1: "alpha", 2: "beta" }, 3, upper-case#1)

Result:
{ 1: "alpha", 2: "beta", 3: "" }
Expression:
fold-left(
  ("a", "b", "c", "a"),
  {},
  fn($map, $key) {
    map:replace($map, $key, fn($val) { ($val otherwise 0) + 1 })
  }
)
Result:
{ "a": 2, "b": 1, "c": 1 }

17.3.19 map:size

Summary

Returns the number of entries in the supplied map.

Signature
map:size(
$map as map(*)
) as xs:integer
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function map:size takes any ·map· as its $map argument and returns the number of entries that are present in the map.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

count(map:entries($map))
Examples
Expression Result
map:size({})
0
map:size({ "true": 1, "false": 0 })
2

17.3.20 map:values

Changes in 4.0  

  1. New in 4.0

Summary

Returns a sequence containing all the values present in a map, in unpredictable order.

Signature
map:values(
$map as map(*)
) as item()*
Properties

This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.

Rules

The function map:values takes any ·map· as its $map argument and returns the values that are present in the map as a sequence, in ·implementation-dependent· order.

The function is nondeterministic with respect to ordering (see 1.9.5 Properties of functions). This means that two calls with the same argument are not guaranteed to produce the results in the same order.

The effect of the function is equivalent to $map?*.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

map:for-each($map, fn($key, $value){ $value })
Examples
Expression:
map:values({ 1: "yes", 2: "no" })
Result:
("yes", "no")

(or some permutation thereof)

(The result is in ·implementation-dependent· order.)

Expression:
map:values({
  1: ("red", "green"),
  2: ("blue", "yellow"),
  3: ()
})
Result:
("red", "green", "blue", "yellow")

(or some permutation thereof)

(The result is in ·implementation-dependent· order.)

17.4 Other Operations on Maps

Because a map is a function item, functions that apply to functions also apply to maps. A map is an anonymous function, so fn:function-name returns the empty sequence; fn:function-arity always returns 1.

Maps may be compared using the fn:deep-equal function.

There is no function or operator to atomize a map or convert it to a string (other than fn:serialize, which can be used to serialize some maps as JSON texts).

18 Arrays

Arrays were introduced as a new datatype in XDM 3.1. This section describes functions that operate on arrays.

An array is an additional kind of item. An array of size N is a mapping from the integers (1 to N) to a set of values, called the members of the array, each of which is an arbitrary sequence. Because an array is an item, and therefore a sequence, arrays can be nested.

An array acts as a function from integer positions to associated values, so the function call $array($index) can be used to retrieve the array member at a given position. The function corresponding to the array has the signature function($index as xs:integer) as item()*. The fact that an array is a function item allows it to be passed as an argument to higher-order functions that expect a function item as one of their arguments.

18.1 Formal Specification of Arrays

The XDM data model ([XQuery and XPath Data Model (XDM) 4.0]) defines three primitive operations on maps:

  • dm:empty-array constructs an empty array.

  • dm:array-append adds a member to an array.

  • dm:iterate-array applies a supplied function to every member of an array, in order.

The functions in this section are all specified by means of equivalent expressions that either call these primitives directly, or invoke other functions that rely on these primitives. The specifications avoid relying on XPath language constructs that manipulate arrays, such as array constructor syntax, lookup expressions, or FLWOR expressions. This is done to allow these language constructs to be specified by reference to this function library, without risk of circularity.

There is one exception to this rule: for convenience, the notation [] is used to represent an empty array, in preference to a call on dm:empty-array().

The formal specifications are not intended to provide a realistic way of implementating the functions (in particular, any real implementation might be expected to implement array:get much more efficiently). They do, however, provide a framework that allows the correctness of a practical implementation to be verified.

18.2 Functions that Operate on Arrays

The functions defined in this section use a conventional namespace prefix array, which is assumed to be bound to the namespace URI http://www.w3.org/2005/xpath-functions/array.

As with all other values, arrays are treated as immutable. For example, the array:reverse function returns an array that differs from the supplied array in the order of its members, but the supplied array is not changed by the operation. Two calls on array:reverse with the same argument will return arrays that are indistinguishable from each other; there is no way of asking whether these are “the same array”. Like sequences, arrays have no identity.

All functionality on arrays is defined in terms of two primitives:

  • The function array:members decomposes an array to a sequence of value records.

  • The function array:of-members composes an array from a sequence of value records.

A value record here is an item that encapsulates an arbitrary value; the representation chosen for a value record is record(value as item()*), that is, a map containing a single entry whose key is the string "value" and whose value is the encapsulated sequence.

Function Meaning
array:append Returns an array containing all the members of a supplied array, plus one additional member at the end.
array:build Returns an array obtained by evaluating the supplied function once for each item in the input sequence.
array:empty Returns true if the supplied array contains no members.
array:filter Returns an array containing those members of the $array for which $predicate returns true. A return value of () is treated as false.
array:flatten Replaces any array appearing in a supplied sequence with the members of the array, recursively.
array:fold-left Evaluates the supplied function cumulatively on successive members of the supplied array.
array:fold-right Evaluates the supplied function cumulatively on successive values of the supplied array.
array:foot Returns the last member of an array.
array:for-each Returns an array whose size is the same as array:size($array), in which each member is computed by applying $action to the corresponding member of $array.
array:for-each-pair Returns an array obtained by evaluating the supplied function once for each pair of members at the same position in the two supplied arrays.
array:get Returns the value at the specified position in the supplied array (counting from 1).
array:head Returns the first member of an array, that is $array(1).
array:index-of Returns a sequence of positive integers giving the positions within the array $array of members that are equal to $target.
array:index-where Returns the positions in an input array of members that match a supplied predicate.
array:insert-before Returns an array containing all the members of the supplied array, with one additional member at a specified position.
array:join Concatenates the contents of several arrays into a single array.
array:members Delivers the contents of an array as a sequence of value records.
array:of-members Constructs an array from the contents of a sequence of value records.
array:put Returns an array containing all the members of a supplied array, except for one member which is replaced with a new value.
array:remove Returns an array containing all the members of the supplied array, except for the members at specified positions.
array:replace Returns an array containing all the members of a supplied array, except for one member which is replaced with a new value, the new value being computed from the previous value.
array:reverse Returns an array containing all the members of a supplied array, but in reverse order.
array:size Returns the number of members in the supplied array.
array:slice Returns an array containing selected members of a supplied input array based on their position.
array:sort Sorts a supplied array, based on the value of a number of sort keys supplied as functions.
array:split Delivers the contents of an array as a sequence of singleton arrays.
array:subarray Returns an array containing all members from a supplied array starting at a supplied position, up to a specified length.
array:tail Returns an array containing all members except the first from a supplied array.
array:trunk Returns an array containing all members except the last from a supplied array.
array:values Returns the sequence concatenation of the members of an array.

18.2.1 array:append

Summary

Returns an array containing all the members of a supplied array, plus one additional member at the end.

Signature
array:append(
$array as array(*),
$member as item()*
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the result is an array whose size is array:size($array) + 1, in which all members in positions 1 to array:size($array) are the same as the members in the corresponding position of $array, and the member in position array:size($array) + 1 is $member.

Formal Specification

The function is defined as follows, making use of primitive constructors and accessors defined in [XQuery and XPath Data Model (XDM) 4.0].

dm:array-append($array, $member)
Examples
Expression Result
array:append([ "a", "b", "c" ], "d")
[ "a", "b", "c", "d" ]
array:append([ "a", "b", "c" ], ("d", "e"))
[ "a", "b", "c", ("d", "e") ]
array:append([ "a", "b", "c" ], [ "d", "e" ])
[ "a", "b", "c", [ "d", "e" ] ]

18.2.2 array:build

Changes in 4.0  

  1. New in 4.0  [Issue 97 ]

Summary

Returns an array obtained by evaluating the supplied function once for each item in the input sequence.

Signature
array:build(
$input as item()*,
$action as fn(item(), xs:integer) as item()* := fn:identity#1
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If the function is called with one argument, the effect is the same as calling the two-argument function with fn:identity#1 as the second argument.

Informally, array:build#2 applies the supplied function to each item in the input sequence, and the resulting sequence becomes one member of the returned array.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

fold-left($input, [], fn($array, $next, $pos) {
   array:append($array, $action($next, $pos))
})
Notes

The single-argument function array:build($input) is equivalent to the XPath expression array { $input }, but it is useful to have this available as a function.

The two-argument form facilitates the construction of arrays whose members are arbitrary sequences.

Examples
Expression:

array:build(1 to 5)

Result:
[ 1, 2, 3, 4, 5 ]
Expression:
array:build(1 to 5, fn { 2 * . })
Result:
[ 2, 4, 6, 8, 10 ]
Expression:
array:build(1 to 5, fn { 1 to . })
Result:
[ 1, (1, 2), (1, 2, 3), (1, 2, 3, 4), (1, 2, 3, 4, 5) ]
Expression:
array:build(("red", "green", "blue"), characters#1)
Result:
[ ("r", "e", "d"), ("g", "r", "e", "e", "n"), ("b", "l", "u", "e") ]
Expression:
array:build(1 to 5, fn { array { 1 to . } })
Result:
[ [ 1 ], [ 1, 2 ], [ 1, 2, 3 ], [ 1, 2, 3, 4 ], [ 1, 2, 3, 4, 5 ] ]
Expression:
array:build(
  (0x41 to 0x48) ! char(.),
  fn($char, $pos) {
    if($pos mod 2 = 0) then lower-case($char) else $char
  }
)
Result:
[ "A", "b", "C", "d", "E", "f", "G", "h" ]

18.2.3 array:empty

Changes in 4.0  

  1. New in 4.0

Summary

Returns true if the supplied array contains no members.

Signature
array:empty(
$array as array(*)
) as xs:boolean
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns true if and only if $array contains no members.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

array:size($array) eq 0
Notes

The test for emptiness is not the same as the test used by the xsl:on-empty instruction in XSLT. For example, an array is not considered empty by this function if it contains a single member that is itself an empty array.

Examples
Expression Result
array:empty([ "a", "b", "c" ])
false()
array:empty([])
true()
array:empty([ [] ])
false()
array:empty([ () ])
false()

18.2.4 array:filter

Changes in 4.0  

  1. The $predicate callback function now accepts an optional position argument.  [Issue 516 PR 828 14 November 2023]

  2. The $predicate callback function may return an empty sequence (meaning false).  [Issue 1171 PR 1182 7 May 2024]

Summary

Returns an array containing those members of the $array for which $predicate returns true. A return value of () is treated as false.

Signature
array:filter(
$array as array(*),
$predicate as fn(item()*, xs:integer) as xs:boolean?
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function returns an array containing those members of the input array that satisfy the supplied predicate.

Formal Specification

The effect of the function is equivalent to the result of the following XQuery expression.

array:fold-left($array, [], fn($result, $next, $pos) {
   if ($predicate($next, $pos))
   then array:append($result, $next)
   else $result
})
Error Conditions

As a consequence of the function signature and the function calling rules, a type error occurs if the supplied function $function returns anything other than a single xs:boolean item or an empty sequence; there is no conversion to an effective boolean value.

Examples
Expression:
array:filter(
  [ "A", "B", 1, 2 ],
  fn($x) { $x instance of xs:integer }
)
Result:
[ 1, 2 ]
Expression:
array:filter(
  [ "the cat", "sat", "on the mat" ],
  function { count(tokenize(.)) > 1 }
)
Result:
[ "the cat", "on the mat" ]
Expression:

array:filter([ "A", "B", "", 0, 1 ], boolean#1)

Result:
[ "A", "B", 1]
Expression:
let $array := [ 1, 1, 2, 3, 4, 4, 5 ]
return array:filter(
  $array,
  fn($item, $pos) { $pos > 1 and $item = $array($pos - 1) }
)
Result:
[ 1, 4 ]

18.2.5 array:flatten

Summary

Replaces any array appearing in a supplied sequence with the members of the array, recursively.

Signature
array:flatten(
$input as item()*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function processes the items in the supplied sequence $input as follows:

  • An item that is an array is replaced by its members, retaining order.

  • Any other item is retained unchanged.

The process is then repeated so long as the sequence contains an array among its items.

Formal Specification

The function delivers the same result as the following XQuery implementation.

declare function array:flatten(
  $input as item()*
) as item()* {
  for $item in $input
  return if ($item instance of array(*)) 
         then array:flatten(array:values($item)) 
         else $item
};
Notes

The argument to the function will often be a single array item, but this is not essential.

Unlike atomization, this function retains any nodes contained in the array.

Examples
Expression Result
array:flatten([ 1, 4, 6, 5, 3 ])
(1, 4, 6, 5, 3)
array:flatten(([ 1, 2 ], [ [ 10, 11 ], 12 ], [], 13))
(1, 2, 10, 11, 12, 13)
array:flatten([ (1, 0), (1, 1), (0, 1), (0, 0) ])
(1, 0, 1, 1, 0, 1, 0, 0)

18.2.6 array:fold-left

Changes in 4.0  

  1. The $action callback function now accepts an optional position argument.  [Issue 516 PR 828 14 November 2023]

Summary

Evaluates the supplied function cumulatively on successive members of the supplied array.

Signature
array:fold-left(
$array as array(*),
$zero as item()*,
$action as fn(item()*, item()*, xs:integer) as item()*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function is defined formally below, in terms of the equivalent fn:fold-left function for sequences.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

fold-left(
  array:members($array),
  $zero,
  fn($result, $member, $pos) { $action($result, map:get($member, 'value'), $pos) }
)
Notes

If the supplied array is empty, the function returns $zero.

If the supplied array contains a single member $m, the function returns $zero => $action($m).

If the supplied array contains two members $m and $n, the function returns $zero => $action($m) => $action($n); and similarly for an input array with more than two members.

The value of the third argument of $action corresponds to the position of the member in the input array. It is initally set to 1.

Examples
Expression:
array:fold-left(
  [ true(), true(), false() ],
  true(),
  fn($x, $y) { $x and $y }
)
Result:
false()

(Returns true if every member of the input array has an effective boolean value of true().)

Expression:
array:fold-left(
  [ true(), true(), false() ],
  false(), 
  fn($x, $y) { $x or $y }
)
Result:
true()

(Returns true if at least one member of the input array has an effective boolean value of true().)

Expression:
array:fold-left(
  [ 1, 2, 3 ],
  [],
  fn($x, $y) { [ $x, $y ] }
)
Result:
[[[[], 1], 2], 3]
Expression:
let $input := array { 11 to 21, 21 to 31 }
let $target := 21
return array:fold-left($input, (),
  fn($result, $curr, $pos) {
    $result, if ($curr = $target) { $pos }
  }
)
Result:
(11, 12)

18.2.7 array:fold-right

Changes in 4.0  

  1. The $action callback function now accepts an optional position argument.  [Issue 516 PR 828 14 November 2023]

Summary

Evaluates the supplied function cumulatively on successive values of the supplied array.

Signature
array:fold-right(
$array as array(*),
$zero as item()*,
$action as fn(item()*, item()*, xs:integer) as item()*
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function is defined formally below, in terms of the equivalent fn:fold-right function for sequences.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

fold-right(
  array:members($array),
  $zero,
  fn($member, $result, $pos) { $action(map:get($member, 'value'), $result, $pos) }
)
Notes

If the supplied array is empty, the function returns $zero.

If the supplied array contains a single member $m, the function returns $action($m, $zero).

If the supplied array contains two members $m and $n, the function returns $action($m, $action($n, $zero)); and similarly for an input array with more than two members.

The value of the third argument of $action corresponds to the position of the member in the input array. Thus, in contrast to array:fold-left, it is initally set to the number of members in the input array.

Examples
Expression:
array:fold-right(
  [ true(), true(), false() ],
  true(),
  fn($x, $y) { $x and $y }
)
Result:
false()

(Returns true if every member of the input array has an effective boolean value of true().)

Expression:
array:fold-right(
  [ true(), true(), false() ],
  false(),
  fn($x, $y) { $x or $y }
)
Result:
true()

(Returns true if at least one member of the input array has an effective boolean value of true().)

Expression:
array:fold-right(
  [ 1, 2, 3 ],
  [],
  fn($x, $y) { [ $x, $y ] }
)
Result:
[ 1, [ 2, [ 3, [] ] ] ]
Expression:
let $input := array { 11 to 21, 21 to 31 }
let $target := 21
return array:fold-right(
  $input, (),
  action := fn($curr, $result, $pos) {
    $result, if ($curr = $target) { $pos }
  }
)
Result:
(12, 11)

18.2.8 array:foot

Changes in 4.0  

  1. New in 4.0  [Issue 97 PR 250]

Summary

Returns the last member of an array.

Signature
array:foot(
$array as array(*)
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the last member of $array.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

array:get($array, array:size($array))
Error Conditions

A dynamic error occurs [err:FOAY0001] if $array is empty.

Examples
Expression Result
array:foot([ 5, 6, 7, 8 ])
8
array:foot([ [ "a", "b" ], [ "c", "d" ] ])
[ "c", "d" ]
array:foot([ ("a", "b"), ("c", "d") ])
"c", "d"

18.2.9 array:for-each

Changes in 4.0  

  1. The $action callback function now accepts an optional position argument.  [Issue 516 PR 828 14 November 2023]

Summary

Returns an array whose size is the same as array:size($array), in which each member is computed by applying $action to the corresponding member of $array.

Signature
array:for-each(
$array as array(*),
$action as fn(item()*, xs:integer) as item()*
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function returns an array whose members are obtained by applying the supplied $action function to each member of the input array in turn.

The $action function is called with two arguments: the first is the array member (which in general is an arbitrary sequence), and the second is the 1-based integer position.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

array:fold-left($array, 
                [], 
                fn($zero, $next, $pos) {
                   array:append($zero, $action($next, $pos))
                })
Examples
Expression:
array:for-each(
  [ "A", "B", 1, 2 ],
  fn($z) { $z instance of xs:integer }
)
Result:
[false(), false(), true(), true()]
Expression:
array:for-each(
  [ "the cat", "sat", "on the mat" ],
  tokenize#1
)
Result:
[ ("the", "cat"), "sat", ("on", "the", "mat") ]
Expression:
array:for-each(
  [ [ "the", "cat" ], [ "sat" ], [ "on", "the", "mat" ] ],
  array:flatten#1
)
Result:
[ ("the", "cat"), "sat", ("on", "the", "mat") ]
Expression:
array:for-each(
  [ 'one', 'two', 'three' ],
  fn($member, $pos) { $pos || '. ' || $member }
)
Result:
[ "1. one", "2. two", "3. three" ]

18.2.10 array:for-each-pair

Changes in 4.0  

  1. The $action callback function now accepts an optional position argument.  [Issue 516 PR 828 14 November 2023]

Summary

Returns an array obtained by evaluating the supplied function once for each pair of members at the same position in the two supplied arrays.

Signature
array:for-each-pair(
$array1 as array(*),
$array2 as array(*),
$action as fn(item()*, item()*, xs:integer) as item()*
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function applies $action to each pair of values in corresponding positions within $array1 and $array2, ignoring any excess values if one array is longer than the other. The results are then assembed into a new array whose size is equal to the shorter of the two input arrays.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

array:of-members(
  for $pos in 1 to min((array:size($array1), array:size($array2)))
  return map:entry('value', $action($array1($pos), $array2($pos), $pos))
)
Notes

If the arrays have different size, excess members in the longer array are ignored.

Examples
Expression:
array:for-each-pair(
  [ "A", "B", "C" ],
  [ 1, 2, 3 ],
  fn($x, $y) { array { $x, $y }}
)
Result:
[ [ "A", 1 ], [ "B", 2 ], [ "C", 3 ] ]
Expression:
let $array := [ "A", "B", "C", "D" ]
return array:for-each-pair(
  $array,
  array:tail($array),
  concat#2
)
Result:
[ "AB", "BC", "CD" ]
Expression:
array:for-each-pair(
  [ 1, 8, 2 ],
  [ 3, 4, 3 ],
  fn($member1, $member2, $pos) {
    $pos || ': ' || max(($member1, $member2))
  }
)
Result:
[ "1: 3", "2: 8", "3: 3" ]

18.2.11 array:get

Changes in 4.0  

  1. A third argument is added, allowing user control of how index-out-of-bounds conditions should be handled.

Summary

Returns the value at the specified position in the supplied array (counting from 1).

Signature
array:get(
$array as array(*),
$position as xs:integer,
$fallback as fn(xs:integer) as item()* := fn($i) { fn:error(fn:QName('', 'FOAY0001')) }
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function returns the member at a specified position in the array. If $position is less than one or greater than array:size($array), then the $fallback function is called, supplying the value of $position as the argument value; and the result of this call is returned.

The default $fallback function raises a dynamic error. The call on fn:error shown as the default is for illustrative purposes only; apart from the error code (err:FOAY0001) the details of the error (such as the error message) are ·implementation-dependent·.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression, except in error cases.

if ($position = (1 to array:size($array)))
then array:members($array)[$position] => map:get('value') 
else $fallback($position)
Error Conditions

In the absence of a $fallback function, a dynamic error occurs [err:FOAY0001] if $position is not in the range 1 to array:size($array) inclusive.

Examples
Expression Result
[ "a", "b", "c" ] => array:get(2)
"b"
[ "a", [ "b", "c" ] ] => array:get(2)
[ "b", "c" ]
[ "a" ] => array:get(1, void#1)
"a"
[] => array:get(1, void#1)
()

18.2.12 array:head

Summary

Returns the first member of an array, that is $array(1).

Signature
array:head(
$array as array(*)
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns first member of $array.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

array:get($array, 1)
Error Conditions

A dynamic error occurs [err:FOAY0001] if $array is empty.

Examples
Expression Result
array:head([ 5, 6, 7, 8 ])
5
array:head([ [ "a", "b" ], [ "c", "d" ] ])
[ "a", "b" ]
array:head([ ("a", "b"), ("c", "d") ])
"a", "b"

18.2.13 array:index-of

Changes in 4.0  

  1. New in 4.0  [Issues 260 1096 PRs 968 1295 6 February 2024]

Summary

Returns a sequence of positive integers giving the positions within the array $array of members that are equal to $target.

Signature
array:index-of(
$array as array(*),
$target as item()*,
$collation as xs:string? := fn:default-collation()
) as xs:integer*
Properties

The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.

The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.

Rules

Informally, all members of $array are compared with $target. An array member is compared to the target value using the rules of the fn:deep-equal function, with the specified (or defaulted) collation. The index position of the member is included in the result sequence if the comparison returns true.

The collation used by this function is determined according to the rules in 5.3.5 Choosing a collation. This collation is used when string comparison is required.

The first member in an array is at position 1, not position 0.

The result sequence is in ascending numeric order.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

array:index-where($array, deep-equal(?, $target, $collation))
Notes

If $array is the empty array, or if no member in $array matches $target, then the function returns the empty sequence.

Examples
Expression:

array:index-of([ 10, 20, 30, 30, 20, 10 ], 20)

Result:
(2, 5)
Expression:

array:index-of([ (), 1, (5, 6), (6, 7) ], (6, 7))

Result:
4
Expression:
array:index-of(
  [ "a", ("b", "C"), "d" ],
  ("B", "c"),
  "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive"
)
Result:
2
Expression:
array:index-of(
  [ '1', xs:untypedAtomic('1'), 1, current-date() ],
  '1'
)
Result:
(1, 2)

18.2.14 array:index-where

Changes in 4.0  

  1. New in 4.0  [Issue 114  13 December 2022]

  2. The $predicate callback function may return an empty sequence (meaning false).  [Issue 1171 PR 1182 7 May 2024]

Summary

Returns the positions in an input array of members that match a supplied predicate.

Signature
array:index-where(
$array as array(*),
$predicate as fn(item()*, xs:integer) as xs:boolean?
) as xs:integer*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The result of the function is a sequence of integers, in monotonic ascending order, representing the 1-based positions in the input array of those members for which the supplied predicate function returns true. A return value of () is treated as false.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

array:fold-left($array, (), fn($indices, $member, $pos) {
   $indices, if ($predicate($member, $pos)) { $pos }
})
Examples
Expression:

array:index-where([], boolean#1)

Result:
()
Expression:

array:index-where([ 0, (), 4, 9 ], boolean#1)

Result:
(3, 4)
Expression:
array:index-where(
  array { 1 to 10 },
  function { . mod 2 = 0 }
)
Result:
(2, 4, 6, 8, 10)
Expression:
array:index-where(
  [ "January", "February", "March", "April",
    "May", "June", "July", "August", "September",
    "October", "November", "December" ],
  contains(?, "r")
)
Result:
(1, 2, 3, 4, 9, 10, 11, 12)
Expression:
array:index-where(
  [ (1, 2, 3), (4, 5, 6), (7, 8) ],
  fn($m) { count($m) = 3 }
)
Result:
(1, 2)
Expression:
array:index-where(
  [ 1, 8, 2, 7, 3 ],
  fn($member, $pos) { $member < 5 and $pos > 2 }
)
Result:
(3, 5)

18.2.15 array:insert-before

Summary

Returns an array containing all the members of the supplied array, with one additional member at a specified position.

Signature
array:insert-before(
$array as array(*),
$position as xs:integer,
$member as item()*
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function returns an array of size array:size($array) + 1 containing all members from $array whose position is less than $position, then a new member given by $member, and then all members from $array whose position is greater than or equal to $position. Positions are counted from 1.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression, except in error cases.

$array 
=> array:members() 
=> fn:insert-before($position, map:entry('value', $member )) 
=> array:of-members()
Error Conditions

A dynamic error occurs [err:FOAY0001] if $position is not in the range 1 to array:size($array) + 1 inclusive.

Notes

Setting $position to 1 has the effect of prepending the new member at the start of the array. Setting $position to the value array:size($array) + 1 delivers the same result as array:append($array, $member).

Examples
Expression Result
array:insert-before(
  [ "a", "b", "c", "d" ],
  3,
  ("x", "y")
)
[ "a", "b", ("x", "y"), "c", "d" ]
array:insert-before(
  [ "a", "b", "c", "d" ],
  5,
  ("x", "y")
)
[ "a", "b", "c", "d", ("x", "y") ]
array:insert-before(
  [ "a", "b", "c", "d" ],
  3,
  [ "x", "y" ]
)
[ "a", "b", [ "x", "y" ], "c", "d" ]

18.2.16 array:join

Summary

Concatenates the contents of several arrays into a single array.

Signature
array:join(
$arrays as array(*)*
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function concatenates the members of several arrays into a single array.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

array:of-members($arrays ! array:members(.))
Examples
Expression Result
array:join(())
[]
array:join([ 1, 2, 3 ])
[ 1, 2, 3 ]
array:join(([ "a", "b" ], [ "c", "d" ]))
[ "a", "b", "c", "d" ]
array:join(([ "a", "b" ], [ "c", "d" ], []))
[ "a", "b", "c", "d" ]
array:join(([ "a", "b" ], [ [ "c", "d" ] ]))
[ "a", "b", [ "c", "d" ] ]

18.2.17 array:members

Changes in 4.0  

  1. New in 4.0  [Issues 29 113 314 ]

Summary

Delivers the contents of an array as a sequence of value records.

Signature
array:members(
$array as array(*)
) as record(value as item()*)*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The members of the array are delivered as a sequence of value records. A value record is an item that encapsulates an arbitrary sequence $S: specifically it is a map comprising a single entry whose key is the xs:string value "value" and whose corresponding value is $S. The content encapsulated by a value record $V can be obtained using the expression $V?value.

Formal Specification

The function is defined as follows, making use of primitive constructors and accessors defined in [XQuery and XPath Data Model (XDM) 4.0].

dm:iterate-array($array, map:entry('value', ?) )
Notes

This function is the inverse of array:of-members.

Examples
Expression:

array:members([])

Result:
()
Expression:

array:members([ 1 to 5 ])?value

Result:
(1, 2, 3, 4, 5)
Expression:
array:members([ (1, 1), (2, 4), (3, 9), (4, 16), (5, 25) ])
! sum(?value)
Result:
(2, 6, 12, 20, 30)
Expression:
let $array := [ "any array" ]
return deep-equal(
  $array,
  array:of-members(array:members($array))
)
Result:
true()

18.2.18 array:of-members

Changes in 4.0  

  1. New in 4.0  [Issues 29 113 314 ]

Summary

Constructs an array from the contents of a sequence of value records.

Signature
array:of-members(
$input as record(value as item()*)*
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The input items must be value records, as defined in the type signature. A value record is an item that encapsulates an arbitrary sequence $S: specifically it is a map comprising a single entry whose key is the xs:string value "value" and whose corresponding value is $S. The content encapsulated by a value record $V can be obtained using the expression $V?value.

Formal Specification

The effect of the function is equivalent to the result of the following XQuery expression.

fold-left($input, [], fn($array, $record) { 
                         array:append($array, map:get($record, 'value'))
                      })
Notes

This function is the inverse of array:members.

Examples
Expression Result
array:of-members(())
[]
array:of-members({ 'value': (1 to 5) })
[ (1, 2, 3, 4, 5) ]
array:of-members((1 to 5) ! { 'value': . })
[ 1, 2, 3, 4, 5 ]
array:of-members((1 to 3) ! { 'value': (., . * .) })
[ (1, 1), (2, 4), (3, 9) ]

18.2.19 array:put

Summary

Returns an array containing all the members of a supplied array, except for one member which is replaced with a new value.

Signature
array:put(
$array as array(*),
$position as xs:integer,
$member as item()*
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the result is an array whose size is array:size($array), in which all members in positions other than $position are the same as the members in the corresponding position of $array, and the member in position $position is $member.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

$array 
=> array:remove($position) 
=> array:insert-before($position, $member)
Error Conditions

A dynamic error occurs [err:FOAY0001] if $position is not in the range 1 to array:size($array) inclusive.

This error will always occur if $array is empty.

Examples
Expression Result
array:put([ "a", "b", "c" ], 2, "d")
[ "a", "d", "c" ]
array:put([ "a", "b", "c" ], 2, ("d", "e"))
[ "a", ("d", "e"), "c" ]
array:put([ "a" ], 1, [ "d", "e" ])
[ [ "d", "e" ] ]

18.2.20 array:remove

Summary

Returns an array containing all the members of the supplied array, except for the members at specified positions.

Signature
array:remove(
$array as array(*),
$positions as xs:integer*
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the function returns an array of size array:size($array) - fn:count(fn:distinct-values($positions)) containing all members from $array except the members whose position (counting from 1) is present in the sequence $positions. The order of the remaining members is preserved.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression, except in error cases.

$array 
=> array:members() 
=> fn:remove($positions) 
=> array:of-members()
Error Conditions

A dynamic error is raised [err:FOAY0001] if any integer in $positions is not in the range 1 to array:size($array) inclusive. By implication, an error occurs if $array is empty, unless $positions is also empty.

Examples
Expression Result
array:remove([ "a", "b", "c", "d" ], 1)
[ "b", "c", "d" ]
array:remove([ "a", "b", "c", "d" ], 2)
[ "a", "c", "d" ]
array:remove([ "a" ], 1)
[]
array:remove([ "a", "b", "c", "d" ], 1 to 3)
[ "d" ]
array:remove([ "a", "b", "c", "d" ], ())
[ "a", "b", "c", "d" ]

18.2.21 array:replace

Changes in 4.0  

  1. New in 4.0

Summary

Returns an array containing all the members of a supplied array, except for one member which is replaced with a new value, the new value being computed from the previous value.

Signature
array:replace(
$array as array(*),
$position as xs:integer,
$action as fn(item()*) as item()*
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the result is an array whose size is array:size($array), in which all members in positions other than $position are the same as the members in the corresponding position of $array, and the member in position $position is the result of applying the $action function to the original value in that position.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

$array 
=> array:remove($position) 
=> array:insert-before($position, $action(array:get($array, $position)))
Error Conditions

A dynamic error occurs [err:FOAY0001] if $position is not in the range 1 to array:size($array) inclusive.

This error will always occur if $array is empty.

Examples
Expression Result
array:replace(
  [ 10, 11, 12 ],
  2,
  fn { . + 10 }
)
[ 10, 21, 12 ]
array:replace(
  [ "a", "b", "c" ],
  2,
  concat(?, "x")
)
[ "a", "bx", "c" ]
array:replace(
  [ ("a", "b"), ("c", "d") ],
  2,
  reverse#1
)
[ ("a", "b"), ("d", "c") ]

18.2.22 array:reverse

Summary

Returns an array containing all the members of a supplied array, but in reverse order.

Signature
array:reverse(
$array as array(*)
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns an array with the same number of members as $array, but in reverse order.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

$array 
=> array:members() 
=> reverse() 
=> array:of-members()
Examples
Expression Result
array:reverse([ "a", "b", "c", "d" ])
[ "d", "c", "b", "a" ]
array:reverse([ ("a", "b"), ("c", "d") ])
[ ("c", "d"), ("a", "b") ]
array:reverse([ 1 to 5 ])
[ (1, 2, 3, 4, 5) ]
array:reverse([])
[]

18.2.23 array:size

Summary

Returns the number of members in the supplied array.

Signature
array:size(
$array as array(*)
) as xs:integer
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the number of members in the array.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

count(array:members($array))
Notes

Note that because an array is an item, the fn:count function when applied to an array always returns 1.

Examples
Expression Result
array:size([ "a", "b", "c" ])
3
array:size([ "a", [ "b", "c" ] ])
2
array:size([])
0
array:size([ [] ])
1

18.2.24 array:slice

Changes in 4.0  

  1. New in 4.0

Summary

Returns an array containing selected members of a supplied input array based on their position.

Signature
array:slice(
$array as array(*),
$start as xs:integer? := (),
$end as xs:integer? := (),
$step as xs:integer? := ()
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Informally, the array is converted to a sequence, the function fn:slice is applied to this sequence, and the resulting sequence is converted back to an array.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

$array 
=> array:members() 
=> slice($start, $end, $step) 
=> array:of-members()
Notes

Note that unlike other operations on arrays, there are no out-of-bounds errors for inappropriate values of $start, $end, or $step.

Examples
Variables
let $in := [ 'a', 'b', 'c', 'd', 'e' ]
Expression Result
array:slice($in, start := 2, end := 4)
[ "b", "c", "d" ]
array:slice($in, start := 2)
[ "b", "c", "d", "e" ]
array:slice($in, end := 2)
[ "a", "b" ]
array:slice($in, start := 3, end := 3)
[ "c" ]
array:slice($in, start := 4, end := 3)
[ "d", "c" ]
array:slice($in, start := 2, end := 5, step := 2)
[ "b", "d" ]
array:slice($in, start := 5, end := 2, step := -2)
[ "e", "c" ]
array:slice($in, start := 2, end := 5, step := -2)
[]
array:slice($in, start := 5, end := 2, step := 2)
[]
array:slice($in)
[ "a", "b", "c", "d", "e" ]
array:slice($in, start := -1)
[ "e" ]
array:slice($in, start := -3)
[ "c", "d", "e" ]
array:slice($in, end := -2)
[ "a", "b", "c", "d" ]
array:slice($in, start := 2, end := -2)
[ "b", "c", "d" ]
array:slice($in, start := -2, end := 2)
[ "d", "c", "b" ]
array:slice($in, start := -4, end := -2)
[ "b", "c", "d" ]
array:slice($in, start := -2, end := -4)
[ "d", "c", "b" ]
array:slice($in, start := -4, end := -2, step := 2)
[ "b", "d" ]
array:slice($in, start := -2, end := -4, step := -2)
[ "d", "b" ]
array:slice([ "a", "b", "c", "d" ], 0)
[ "a", "b", "c", "d" ]

18.2.25 array:sort

Changes in 4.0  

  1. New in 4.0

Summary

Sorts a supplied array, based on the value of a number of sort keys supplied as functions.

Signature
array:sort(
$array as array(*),
$collations as xs:string* := fn:default-collation(),
$keys as (fn(item()*) as xs:anyAtomicType*)* := fn:data#1,
$orders as enum('ascending', 'descending')* := 'ascending'
) as item()*
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.

Rules

The result of the function is an array that contains all the members from $input, typically in a different order, the order being defined by the supplied sort key definitions.

A sort key definition has three parts:

  1. A sort key function, which is applied to each member in the input array to determine a sort key value.

  2. A collation, which is used when comparing sort key values that are of type xs:string or xs:untypedAtomic.

  3. An order direction, which is ascending or descending.

The number of sort key definitions is determined by the number of function items supplied in the $keys argument. If the argument is absent or empty, the default is a single sort key definition using the function data#1.

The $nth sort key definition (where $n counts from one (1)) is established as follows:

  1. The sort key function is $keys[$n] otherwise data#1.

  2. The collation is $collations[$n] otherwise $collations[last()] otherwise default-collation(). That is, it is the collation supplied in the corresponding item of the supplied $collations argument; or in its absence, the last entry in $collations; or if $collations is absent or empty, the default collation from the static context of the caller.

  3. The order direction is $orders[$n] otherwise $orders[last()] otherwise "ascending". That is, it is "ascending" or "descending" according to the value of the corresponding item in the supplied $orders argument; or in its absence, the last entry in $orders; or if $orders is absent or empty, then "ascending".

When comparing values of types other than xs:string or xs:untypedAtomic, the corresponding collation is ignored, and no error is reported if the supplied value is not a known or valid collation name. If it is necessary to supply such an ignored value (for example, in the case where a non-string sort key is followed by another sort key that requires a collation) the empty string can be supplied.

The result of the function is defined by reference to the fn:sort function.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

$array
=> array:members()
=> sort(
       $collations,
       for $key in ($keys otherwise data#1)
       return fn($member as record(value)) as xs:anyAtomicType* {
         $key($member?value)
       },
       $orders
   )
=> array:of-members()
Error Conditions

If the set of computed sort keys contains values that are not comparable using the lt operator then the sort operation will fail with a type error ([err:XPTY0004]XP).

Examples
Expression:

array:sort([ 1, 4, 6, 5, 3 ])

Result:
[ 1, 3, 4, 5, 6 ]
Expression:

array:sort([ 1, 4, 4e0, 6, 5, 3 ], orders := "descending")

Result:
[ 6, 5, 4, 4e0, 3, 1 ]
Expression:

array:sort([ 1, -2, 5, 10, -10, 10, 8 ], (), abs#1)

Result:
[ 1, -2, 5, 8, 10, -10, 10 ]
Expression:

array:sort([ [ 2, "i" ], [ 1, "e" ], [ 2, "g" ], [ 1, "f" ] ])

Result:
[ [ 1, "e" ], [ 1, "f" ], [ 2, "g" ], [ 2, "i" ] ]
Expression:
array:sort(
  [ [ 2, "i" ], [ 1, "e" ], [ 2, "g" ], [ 1, "f" ] ], 
  (), 
  (array:get(?, 1), array:get(?, 2)),
  ("ascending", "descending")
)
Result:
[ [ 1, "f" ], [ 1, "e" ], [ 2, "i" ], [ 2, "g" ]]

To sort an array of strings $in using Swedish collation:

let $SWEDISH := collation(map{'lang':'se'})
return array:sort($in, $SWEDISH)

To sort an array of maps representing employees, using last name as the major sort key and first name as the minor sort key, with the default collation:

array:sort($employees, (), fn($emp) { $emp?name?last, $emp?name?first })

18.2.26 array:split

Changes in 4.0  

  1. New in 4.0

Summary

Delivers the contents of an array as a sequence of singleton arrays.

Signature
array:split(
$array as array(*)
) as array(*)*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The members of the array are delivered as a sequence of arrays. Each returned array encapsulates the value of a single array member.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

array:for-each($array, 
               fn($member) { 
                  [] => array:append($member) 
               }) 
=> array:values()
Notes

The function call array:split($array) produces the same result as the expression for member $m in $array return [ $m ].

This function is the inverse of array:join.

Examples
Expression:

array:split([])

Result:
()
Expression:

array:split([ () ])

Result:
[ () ]
Expression:

array:split([ 1 to 5 ])

Result:
[ (1, 2, 3, 4, 5) ]
Expression:
array:split(
  array { 1 to 5 }
)
Result:
[ 1 ], [ 2 ], [ 3 ], [ 4 ], [ 5 ]
Expression:
array:split(
  [ (1, 1), (2, 4), (3, 9), (4, 16), (5, 25) ]
) ! sum(.)
Result:
2, 6, 12, 20, 30
Expression:
let $array := [ "any array" ]
return deep-equal(
  $array,
  array:join(array:split($array))
)
Result:
true()

18.2.27 array:subarray

Changes in 4.0  

  1. Supplying an empty sequence as the value of an optional argument is equivalent to omitting the argument.

Summary

Returns an array containing all members from a supplied array starting at a supplied position, up to a specified length.

Signature
array:subarray(
$array as array(*),
$start as xs:integer,
$length as xs:integer? := ()
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

Except in error cases, the two-argument version of the function returns the same result as the three-argument version when called with $length equal to the value of array:size($array) - $start + 1.

Setting the third argument to the empty sequence has the same effect as omitting the argument.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression, except in error cases.

$array
=> array:members()
=> subsequence($start, $length)
=> array:of-members()
Error Conditions

A dynamic error is raised [err:FOAY0001] if $start is less than one or greater than array:size($array) + 1.

For the three-argument version of the function:

  • A dynamic error is raised [err:FOAY0002] if $length is less than zero.

  • A dynamic error is raised [err:FOAY0001] if $start + $length is greater than array:size($array) + 1.

Notes

The value of $start can be equal to array:size($array) + 1 provided that $length is either equal to zero or omitted. In this case the result will be an empty array.

Examples
Expression Result
array:subarray([ "a", "b", "c", "d" ], 2)
[ "b", "c", "d" ]
array:subarray([ "a", "b", "c", "d" ], 5)
[]
array:subarray([ "a", "b", "c", "d" ], 2, 0)
[]
array:subarray([ "a", "b", "c", "d" ], 2, 1)
[ "b" ]
array:subarray([ "a", "b", "c", "d" ], 2, 2)
[ "b", "c" ]
array:subarray([ "a", "b", "c", "d" ], 5, 0)
[]
array:subarray([], 1, 0)
[]

18.2.28 array:tail

Summary

Returns an array containing all members except the first from a supplied array.

Signature
array:tail(
$array as array(*)
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns an array containing all members of the supplied array except the first.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

array:remove($array, 1)
Error Conditions

A dynamic error occurs [err:FOAY0001] if $array is empty.

Notes

If the supplied array contains exactly one member, the result will be an empty array.

Examples
Expression Result
array:tail([ 5, 6, 7, 8 ])
[ 6, 7, 8 ]
array:tail([ 5 ])
[]

18.2.29 array:trunk

Changes in 4.0  

  1. New in 4.0  [Issue 97 PR 250]

Summary

Returns an array containing all members except the last from a supplied array.

Signature
array:trunk(
$array as array(*)
) as array(*)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns an array containing all members of the supplied array except the last.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

array:remove($array, array:size($array))
Error Conditions

A dynamic error occurs [err:FOAY0001] if $array is empty.

Notes

If the supplied array contains exactly one member, the result will be an empty array.

Examples
Expression Result
array:trunk([ 5, 6, 7, 8 ])
[ 5, 6, 7 ]
array:trunk([ 5 ])
[]

18.2.30 array:values

Changes in 4.0  

  1. New in 4.0  [Issues 29 1086 PRs 476 1087 5 September 2023]

Summary

Returns the sequence concatenation of the members of an array.

Signature
array:values(
$array as array(*)
) as item()*
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the sequence concatenationXP40 of the members of $array, retaining order.

Formal Specification

The effect of the function is equivalent to the result of the following XPath expression.

for-each(array:members($array), map:get(?, 'value'))
Notes

Unlike array:flatten, the function does not apply recursively to nested arrays.

If $A is a single array item, then array:values($A) returns the same result as $A?*.

Examples
Expression Result
array:values(["one", "two", "three"])
("one", "two", "three")
array:values(["one", ("two", "three")])
("one", "two", "three")
array:values(["one", ("two", "three"), ()])
("one", "two", "three")
array:values(["one", ["two", "three"]])
("one", ["two", "three"])
array:values([ (), 1, (2 to 4), [ 5 ] ])
(1, 2, 3, 4, [ 5 ])

18.3 Additional Operations on Arrays

This section is non-normative.

The XPath language provides explicit syntax for certain operations on arrays. These constructs can also be specified in terms of function primitives:

18.3.1 Singleton Arrays

  • array { $sequence } constructs an array whose members are the items in $sequence. Every member of this array will be a singleton item. This can be defined as array:join($sequence ! array { . }).

  • [E1, E2, E3, ..., En] constructs an array in which E1 is the first member, E2 is the second member, and so on. The result is equivalent to the expression array:join(([ E1 ], [ E2 ], ... [ En ])).

  • The lookup expression $array?* is equivalent to array:split($array)?*.

  • The lookup expression $array?$N, where $N is an integer within the bounds of the array, is equivalent to array:split($array)[$N]?*.

  • Similarly, applying the array as a function, $array($N), is also equivalent to array:split($array)[$N]?*

18.3.2 Value Maps

  • array { $sequence } constructs an array whose members are the items in $sequence. Every member of this array will be a singleton item. This can be defined as array:of-members($sequence ! { 'value': . }).

  • [E1, E2, E3, ..., En] constructs an array in which E1 is the first member, E2 is the second member, and so on. The result is equivalent to the expression array:of-members(({ 'value': E1 }, { 'value': E2 }, { 'value': E3 }, ... { 'value': En })).

  • The lookup expression $array?* is equivalent to array:members($array) ! ?value.

  • The lookup expression $array?$N, where $N is an integer within the bounds of the array, is equivalent to array:members($array)[$N]?value.

  • Similarly, applying the array as a function, $array($N), is also equivalent to array:members($array)[$N]?value

19 Constructor functions

Changes in 4.0  

  1. Constructor functions now have a zero-arity form; the first argument defaults to the context item.   [Issue 658 PR 662 29 August 2023]

Constructor functions are used to convert a supplied value to a given type, and the name of the function is the same as the name of the target type. This section describes constructor functions corresponding to the following types:

Constructor functions are defined for all user-defined named simple types, and for most built-in atomic, list, and union types. The only named simple types that have no constructor function are those that have no instances other than instances of their derived types: specifically, xs:anySimpleType, xs:anyAtomicType, and xs:NOTATION.

19.1 Constructor functions for XML Schema built-in atomic types

Every built-in atomic type that is defined in [XML Schema Part 2: Datatypes Second Edition], except xs:anyAtomicType and xs:NOTATION, has an associated constructor function. The type xs:untypedAtomic, defined in Section 2.7 Schema Information DM31 and the two derived types xs:yearMonthDuration and xs:dayTimeDuration defined in Section 2.7 Schema Information DM31 also have associated constructor functions. Implementations may additionally provide a constructor functions for the new datatype xs:dateTimeStamp introduced in [Schema 1.1 Part 2].

A constructor function is not defined for xs:anyAtomicType as there are no atomic items with type annotation xs:anyAtomicType at runtime, although this can be a statically inferred type. A constructor function is not defined for xs:NOTATION since it is defined as an abstract type in [XML Schema Part 2: Datatypes Second Edition]. If the static context (See Section 2.1.1 Static Context XP31) contains a type derived from xs:NOTATION then a constructor function is defined for it. See 19.5 Constructor functions for user-defined atomic and union types.

The form of the constructor function for an atomic type eg:TYPE is:

eg:TYPE(
$value as xs:anyAtomicType? := .
) as eg:TYPE?

If $arg is the empty sequence, the empty sequence is returned. For example, the signature of the constructor function corresponding to the xs:unsignedInt type defined in [XML Schema Part 2: Datatypes Second Edition] is:

xs:unsignedInt(
$arg as xs:anyAtomicType? := .
) as xs:unsignedInt?

Calling the constructor function xs:unsignedInt(12) returns the xs:unsignedInt value 12. Another call of that constructor function that returns the same xs:unsignedInt value is xs:unsignedInt("12"). The same result would also be returned if the constructor function were to be called with a node that had a typed value equal to the xs:unsignedInt 12. The standard features described in Section 2.4.2 Atomization XP31 would atomize the node to extract its typed value and then call the constructor with that value. If the value passed to a constructor is not in the lexical space of the datatype to be constructed, and cannot be converted to a value in the value space of the datatype under the rules in this specification, then an dynamic error is raised [err:FORG0001].

The semantics of the constructor function xs:TYPE(arg) are identical to the semantics of arg cast as xs:TYPE? . See 20 Casting.

If the argument to a constructor function is a literal, the result of the function may be evaluated statically; if an error is found during such evaluation, it may be reported as a static error.

Special rules apply to constructor functions for xs:QName and types derived from xs:QName and xs:NOTATION. See 19.2 Constructor functions for xs:QName and xs:NOTATION.

The argument is optional, and defaults to the context value (which will be atomized if necessary).

The following constructor functions for the built-in atomic types are supported:

  • xs:string(
    $value as xs:anyAtomicType? := .
    ) as xs:string?
  • xs:boolean(
    $value as xs:anyAtomicType? := .
    ) as xs:boolean?
  • xs:decimal(
    $value as xs:anyAtomicType? := .
    ) as xs:decimal?
  • xs:float(
    $value as xs:anyAtomicType? := .
    ) as xs:float?

    Implementations should return negative zero for xs:float("-0.0E0"). But because [XML Schema Part 2: Datatypes Second Edition] does not distinguish between the values positive zero and negative zero, implementations may return positive zero in this case.

  • xs:double(
    $value as xs:anyAtomicType? := .
    ) as xs:double?

    Implementations should return negative zero for xs:double("-0.0E0"). But because [XML Schema Part 2: Datatypes Second Edition] does not distinguish between the values positive zero and negative zero, implementations may return positive zero in this case.

  • xs:duration(
    $value as xs:anyAtomicType? := .
    ) as xs:duration?
  • xs:dateTime(
    $value as xs:anyAtomicType? := .
    ) as xs:dateTime?
  • xs:time(
    $value as xs:anyAtomicType? := .
    ) as xs:time?
  • xs:date(
    $value as xs:anyAtomicType? := .
    ) as xs:date?
  • xs:gYearMonth(
    $value as xs:anyAtomicType? := .
    ) as xs:gYearMonth?
  • xs:gYear(
    $value as xs:anyAtomicType? := .
    ) as xs:gYear?
  • xs:gMonthDay(
    $value as xs:anyAtomicType? := .
    ) as xs:gMonthDay?
  • xs:gDay(
    $value as xs:anyAtomicType? := .
    ) as xs:gDay?
  • xs:gMonth(
    $value as xs:anyAtomicType? := .
    ) as xs:gMonth?
  • xs:hexBinary(
    $value as xs:anyAtomicType? := .
    ) as xs:hexBinary?
  • xs:base64Binary(
    $value as xs:anyAtomicType? := .
    ) as xs:base64Binary?
  • xs:anyURI(
    $value as xs:anyAtomicType? := .
    ) as xs:anyURI?
  • xs:QName(
    $value as xs:anyAtomicType? := .
    ) as xs:QName?

    See 19.2 Constructor functions for xs:QName and xs:NOTATION for special rules.

  • xs:normalizedString(
    $value as xs:anyAtomicType? := .
    ) as xs:normalizedString?
  • xs:token(
    $value as xs:anyAtomicType? := .
    ) as xs:token?
  • xs:language(
    $value as xs:anyAtomicType? := .
    ) as xs:language?
  • xs:NMTOKEN(
    $value as xs:anyAtomicType? := .
    ) as xs:NMTOKEN?
  • xs:Name(
    $value as xs:anyAtomicType? := .
    ) as xs:Name?
  • xs:NCName(
    $value as xs:anyAtomicType? := .
    ) as xs:NCName?
  • xs:ID(
    $value as xs:anyAtomicType? := .
    ) as xs:ID?
  • xs:IDREF(
    $value as xs:anyAtomicType? := .
    ) as xs:IDREF?
  • xs:ENTITY(
    $value as xs:anyAtomicType? := .
    ) as xs:ENTITY?

    See 20.1.10 Casting to xs:ENTITY for rules related to constructing values of type xs:ENTITY and types derived from it.

  • xs:integer(
    $value as xs:anyAtomicType? := .
    ) as xs:integer?
  • xs:nonPositiveInteger(
    $value as xs:anyAtomicType? := .
    ) as xs:nonPositiveInteger?
  • xs:negativeInteger(
    $value as xs:anyAtomicType? := .
    ) as xs:negativeInteger?
  • xs:long(
    $value as xs:anyAtomicType? := .
    ) as xs:long?
  • xs:int(
    $value as xs:anyAtomicType? := .
    ) as xs:int?
  • xs:short(
    $value as xs:anyAtomicType? := .
    ) as xs:short?
  • xs:byte(
    $value as xs:anyAtomicType? := .
    ) as xs:byte?
  • xs:nonNegativeInteger(
    $value as xs:anyAtomicType? := .
    ) as xs:nonNegativeInteger?
  • xs:unsignedLong(
    $value as xs:anyAtomicType? := .
    ) as xs:unsignedLong?
  • xs:unsignedInt(
    $value as xs:anyAtomicType? := .
    ) as xs:unsignedInt?
  • xs:unsignedShort(
    $value as xs:anyAtomicType? := .
    ) as xs:unsignedShort?
  • xs:unsignedByte(
    $value as xs:anyAtomicType? := .
    ) as xs:unsignedByte?
  • xs:positiveInteger(
    $value as xs:anyAtomicType? := .
    ) as xs:positiveInteger?
  • xs:yearMonthDuration(
    $value as xs:anyAtomicType? := .
    ) as xs:yearMonthDuration?
  • xs:dayTimeDuration(
    $value as xs:anyAtomicType? := .
    ) as xs:dayTimeDuration?
  • xs:untypedAtomic(
    $value as xs:anyAtomicType? := .
    ) as xs:untypedAtomic??
  • xs:dateTimeStamp(
    $value as xs:anyAtomicType? := .
    ) as xs:dateTimeStamp?

    Available only if the implementation supports XSD 1.1.

19.2 Constructor functions for xs:QName and xs:NOTATION

Special rules apply to constructor functions for the types xs:QName and xs:NOTATION, for two reasons:

  • Values cannot belong directly to the type xs:NOTATION, only to its subtypes.

  • The lexical representation of these types uses namespace prefixes, whose meaning is context-dependent.

These constraints result in the following rules:

  1. There is no constructor function for xs:NOTATION. Constructors are defined, however, for xs:QName, for types derived or constructed from xs:QName, and for types derived or constructed from xs:NOTATION.

  2. When converting from an xs:string, the prefix within the lexical xs:QName supplied as the argument is resolved to a namespace URI using the statically known namespaces from the static context. If the lexical xs:QName has no prefix, the namespace URI of the resulting expanded-QName is the default namespace for elements and types, taken from the static context. Components of the static context are defined in Section 2.1.1 Static Context XP31. A dynamic error is raised [err:FONS0004] if the prefix is not bound in the static context. As described in Section 2.1 Terminology DM31, the supplied prefix is retained as part of the expanded-QName value.

When a constructor function for a namespace-sensitive type is used as a literal function item or in a partial function application (for example, xs:QName#1 or xs:QName(?)) the namespace bindings that are relevant are those from the static context of the literal function item or partial function application. When a constructor function for a namespace-sensitive type is obtained by means of the fn:function-lookup function, the relevant namespace bindings are those from the static context of the call on fn:function-lookup.

Note:

When the supplied argument to the xs:QName constructor function is a node, the node is atomized in the usual way, and if the result is xs:untypedAtomic it is then converted as if a string had been supplied. The effect might not be what is desired. For example, given the attribute xsi:type="my:type", the expression xs:QName(@xsi:type) might fail on the grounds that the prefix my is undeclared. This is because the namespace bindings are taken from the static context (that is, from the query or stylesheet), and not from the source document containing the @xsi:type attribute. The solution to this problem is to use the function call resolve-QName(@xsi:type, .) instead.

19.3 Constructor functions for XML Schema built-in list types

Each of the three built-in list types defined in [XML Schema Part 2: Datatypes Second Edition], namely xs:NMTOKENS, xs:ENTITIES, and xs:IDREFS, has an associated constructor function.

The function signatures are as follows:

  • xs:NMTOKENS(
    $value as xs:string? := .
    ) as xs:NMTOKEN*
  • xs:ENTITIES(
    $value as xs:string? := .
    ) as xs:ENTITY*
  • xs:IDREFS(
    $value as xs:string? := .
    ) as xs:IDREF*

The semantics are equivalent to casting to the corresponding types from xs:string.

All three of these types have the facet minLength = 1 meaning that there must always be at least one item in the list. The return type, however, allows for the fact that when the argument to the function is an empty sequence, the result is an empty sequence.

Note:

In the case of atomic types, it is possible to use an expression such as xs:date(@date-of-birth) to convert an attribute value to an instance of xs:date, knowing that this will work both in the case where the attribute is already annotated as xs:date, and also in the case where it is xs:untypedAtomic. This approach does not work with list types, because it is not permitted to use a value of type xs:NMTOKEN* as input to the constructor function xs:NMTOKENS. Instead, it is necessary to use conditional logic that performs the conversion only in the case where the input is untyped: if (@x instance of attribute(*, xs:untypedAtomic)) then xs:NMTOKENS(@x) else data(@x)

19.4 Constructor functions for XML Schema built-in union types

There is a constructor function for the union type xs:numeric defined in [XQuery and XPath Data Model (XDM) 3.1]. The function signature is:

  • xs:numeric(
    $value as xs:anyAtomicType? := .
    ) as xs:numeric?

The semantics are determined by the rules in 20.3.7 Casting to union types. These rules have the effect that:

  1. If the argument is an instance of xs:double, xs:float, or xs:decimal, then the result is an instance of the same primitive type, with the same value;

  2. If the argument is an instance of xs:boolean, the result is the xs:double value 0.0e0 or 1.0e0;

  3. If the argument is an instance of xs:string or xs:untypedAtomic, then:

    1. If the value is in the lexical space of xs:double, the result will be the corresponding xs:double value;

    2. Otherwise, a dynamic error [err:FORG0001] occurs;

    Note:

    The result will never be an instance of xs:float, xs:decimal, or xs:integer. This is because xs:double appears first in the list of member types of xs:numeric, and its lexical space subsumes the lexical space of the other numeric types. Thus, unlike XPath numeric literals, the result does not depend on the lexical form of the supplied value. The reason for this design choice is to retain compatibility with the function conversion rules: functions such as fn:abs and fn:round are declared to expect an instance of xs:numeric as their first or only argument, and compatibility with the function conversion rules defined in earlier versions of these specifications demands that when an untyped atomic item (or untyped node) is supplied as the argument, it is converted to an xs:double value even if its lexical form is that (say) of an integer.

  4. In all other cases, a dynamic error [err:FORG0001] occurs.

In the case of an implementation that supports XSD 1.1, there is a constructor function associated with the built-in union type xs:error.

The function signature is as follows:

  • xs:error(
    $value as xs:anyAtomicType? := .
    ) as xs:error?

The semantics are equivalent to casting to the corresponding union type (see 20.3.7 Casting to union types).

Note:

Because xs:error has no member types, and therefore has an empty value space, casting will always fail with a dynamic error except in the case where the supplied argument is an empty sequence, in which case the result is also an empty sequence.

19.5 Constructor functions for user-defined atomic and union types

For every named user-defined simple type in the static context (See Section 2.1.1 Static Context XP31), there is a constructor function whose name is the same as the name of the typeand whose effect is to create a value of that type from the supplied argument. The rules for constructing user-defined types are defined in the same way as the rules for constructing built-in derived types defined in 19.1 Constructor functions for XML Schema built-in atomic types.

For named atomic types, the rules are the same as the rules for constructing built-in derived atomic types defined in 19.1 Constructor functions for XML Schema built-in atomic types. For a named atomic type T, the signature of the function takes the form T($value as xs:anyAtomicType? := .) as T?, and the semantics are the same as casting to derived types: see 20.3.1 Casting to derived types..

For named union types, the rules follow the same principles as the rules for constructing built-in union types defined in 19.4 Constructor functions for XML Schema built-in union types. For a named union type U, the signature of the function takes the form U($value as xs:anyAtomicType? := .) as U?, and the semantics are the same as casting to union types: see 20.3.7 Casting to union types.

For named list types, the rules follow the same principles as the rules for constructing built-in list types defined in 19.3 Constructor functions for XML Schema built-in list types. For a named list type L, where the item type of L is I, the signature of the function takes the form L($value as xs:string? := .) as I*, and the semantics are the same as casting to list types: see 20.3.8 Casting to list types.

Constructor functions are available both for named types defined in an imported schema (that is, named simple types in the in-scope schema typesXP40), and for types defined by means of named item typesXP40. Specifically, named enumeration types follow the same rules as schema types derived by restricting xs:string, and named local union types follow the same rules as union types defined in a schema.

Special rules apply to constructor functions for namespace-sensitive types, that is, atomic types derived from xs:QName and xs:NOTATION, list types that have a namespace-sensitive item type, and union types that have a namespace-sensitive member type. See 19.2 Constructor functions for xs:QName and xs:NOTATION.

Example: Using a Constructor Function for a User-Defined Atomic Type

Consider a situation where the static context contains an atomic type called hatSize defined in a schema whose target namespace is bound to the prefix eg. In such a case the following constructor function is available to users:

eg:hatSize(
$value as xs:anyAtomicType
) as my:hatSize?

The resulting function may be used in an expression such as eg:hatSize("10½").

In the case of an atomic type A, the return type of the function is A?, reflecting the fact that the result will be an empty sequence if the input is an empty sequence. For a union or list type, the return type of the function is specified only as xs:anyAtomicType*. Implementations performing static type checking will often be able to compute a more specific result type. For example, if the target type is a list type whose item type is the atomic type A, the result will always be an instance of A*; if the target type is a pure union type U then the result will always be an instance of U?. In general, however, applications needing interoperable behavior on implementations that do strict static type checking will need to use a treat as expression to assert the specific type of the result.

Note:

To construct an instance of a user-defined type that is not in a namespace, it is possible to use an EQName (for example Q{}hatsize(17)). Alternatives are to use a cast expression (17 cast as hatsize) or (if the host language allows it) to undeclare the default function namespace.

19.6 Constructor functions for named record tests

For every named item type in the static context (See Section 2.1.1 Static Context XP31) whose expansion is a record test, there is a constructor function whose name is the same as the name of the type, and whose parameters correspond to the fields defined in the record test.

For example, if there is a named item type with the XQuery definition:

declare item type my:location as record(
  latitude  as xs:double,
  longitude as xs:double
)

then there will be a function definition equivalent to:

declare function my:location (
  $latitude  as xs:double,
  $longitude as xs:double
) as my:location {
  { 'latitude': $latitude, 'longitude': $longitude }
}

Equivalently using XSLT syntax, if there is a named item type with the XSLT definition:

<xsl:item-type name="my:location"
  as="record(latitude as xs:double, longitude as xs:double)"/>

then there will be a function definition equivalent to:

<xsl:function name="my:location" as="my:location">
  <xsl:param name="latitude" as="xs:double"/>
  <xsl:param name="longitude" as="xs:double"/>
  <xsl:map>
    <xsl:map-entry key="'latitude'" select="$latitude"/>
    <xsl:map-entry key="'longitude'" select="$longitude"/>
  </xsl:map>
</xsl:function>

The rules defining the relationship of the function definition to the record test are as follows:

  1. The name of the function is the same as the name of the named item type. A static error occurs if this clashes with the name and arity of other function definitions in the static context.

  2. For every named field in the record test, in order, there is is one parameter defined as follows:

    1. If the name of the field is an NCName, then the name of the parameter is the name of the field.

    2. Otherwise, the name of the parameter is argNZ, where arg is the literal string "arg", N is the ordinal position of the field, counting from 1 (one), and Z is an implementation-defined suffix, added only when needed to make the parameter name unique.

    3. The declared type of the parameter is the same as the declared type of the field, but if the field is declared optional, then the occurrence indicator is adjusted to ? or * if needed to make the empty sequence a valid value for the parameter.

    4. If the field is optional and if all subsequent fields are optional, then the parameter is declared as optional with a default value of () (the empty sequence). In all other cases the parameter is declared as required.

  3. It is immaterial whether the record test is extensible; the constructor function cannot be used to create entries in the resulting map other than entries corresponding to named fields.

  4. The return type of the constructor function is the record test (with no occurrence indicator).

  5. The body of the function constructs a map having one entry for each mandatory field in the record test, and one entry for each optional field in the record test for which an actual value other than the empty sequence is supplied in the arguments of the function call. The key of the entry is the field name as an instance of xs:string, and the corresponding value is the value supplied in the arguments to the constructor function call, after applying the coercion rules.

Example: Record constructor with optional fields

Consider the record test (in XQuery syntax):

declare item type p:person as record(
  "1st-title"? as xs:string,
  "2nd-title"? as xs:string,
  first        as xs:string,
  middle?      as xs:string,
  last         as xs:string,
  suffix?      as xs:string,
  *)

This will result in an implicit function declaration equivalent to:

declare function p:person (
  $arg1   as xs:string?,
  $arg2   as xs:string?,
  $first  as xs:string,
  $middle as xs:string?,
  $last   as xs:string,
  $suffix as xs:string? := ()
) as p:person {
  map:merge((
    { "1st-title", $arg1 }[exists($arg1)],
    { "2nd-title", $arg2 }[exists($arg2)],
    { "first", $first },
    { "middle", $middle }[exists($middle)],
    { "last", $last },
    { "suffix", $suffix }[exists($suffix)]
  ))
};

20 Casting

Constructor functions and cast expressions accept an expression and return a value of a given type. They both convert a source value SV, of a source type, ST to a target value TV, of the given target type TT.

Constructor functions and cast expressions have identical semantics but different syntax. The name of the constructor function is the same as the name of the built-in [XML Schema Part 2: Datatypes Second Edition] datatype or the datatype defined in Section 2.7 Schema Information DM31 of [XQuery and XPath Data Model (XDM) 3.1] (see 19.1 Constructor functions for XML Schema built-in atomic types) or the user-derived datatype (see 19.5 Constructor functions for user-defined atomic and union types) that is the target for the conversion, and the semantics are exactly the same as for a cast expression; for example, xs:date("2003-01-01") means exactly the same as "2003-01-01" cast as xs:date?.

The cast expression takes a type name to indicate the target type of the conversion. See Section 3.14.2 Cast XP31. If the type name allows the empty sequence and the expression to be cast is the empty sequence, the empty sequence is returned. If the type name does not allow the empty sequence and the expression to be cast is the empty sequence, a type error is raised [err:XPTY0004]XP.

Where the argument to a cast is a literal, the result of the function may be evaluated statically; if an error is encountered during such evaluation, it may be reported as a static error.

The general rules for casting from primitive types to primitive types are defined in 20.1 Casting from primitive types to primitive types, and subsections describe the rules for specific target types. The general rules for casting from xs:string (and xs:untypedAtomic) follow in 20.2 Casting from xs:string and xs:untypedAtomic. Casting to non-primitive types, including atomic types derived by restriction, union types, and list types, is described in 20.3 Casting involving non-primitive types. Casting from derived types is defined in 20.3.4 Casting from derived types to parent types, 20.3.5 Casting within a branch of the type hierarchy and 20.3.6 Casting across the type hierarchy.

Casting is not supported to or from xs:anySimpleType. Casting to xs:anySimpleType is not permitted and raises a static error: [err:XPST0080]XP.

Similarly, casting is not supported to or from xs:anyAtomicType and will raise a static error: [err:XPST0080]XP. There are no atomic items with the type annotation xs:anyAtomicType, although this can be a statically inferred type.

20.1 Casting from primitive types to primitive types

Changes in 4.0  

  1. This section now uses the term primitive type strictly to refer to the 20 atomic types that are not derived by restriction from another atomic type: that is, the 19 primitive atomic types defined in XSD, plus xs:untypedAtomic. The three types xs:integer, xs:dayTimeDuration, and xs:yearMonthDuration, which have custom casting rules but are not strictly-speaking primitive, are now handled in other subsections.   [Issue 1401 PR 1409]

This section defines casting between ·primitive types· (specifically, the 19 primitive types defined in [XML Schema Part 2: Datatypes Second Edition] plus xs:untypedAtomic. The type conversions that are supported between primitive atomic types are indicated in the table below; casts between other (non-primitive) types are defined in terms of these primitives.

Where the target type TT is a primitive type, the result TV will always be an instance of TT. The result may also be an instance of a type derived from TT: for example casting an xs:NCName SV to xs:string may return SV unchanged, with its original type annotation.

In this table, there is a row for each ·primitive type· acting as the source of the conversion and there is a column for each ·primitive type· acting as the target of the conversion. The intersections of rows and columns contain one of three characters:

  • Y indicates that a conversion from values of the type to which the row applies to the type to which the column applies is supported;

  • N indicates that there are no supported conversions from values of the type to which the row applies to the type to which the column applies;

  • M indicates that a conversion from values of the type to which the row applies to the type to which the column applies may succeed for some values in the value space and fail for others.

There is no row or column for xs:untypedAtomic because the casting rules are exactly the same as for xs:string. When casting from xs:string or xs:untypedAtomic the semantics in 20.2 Casting from xs:string and xs:untypedAtomic apply, regardless of target type.

[XML Schema Part 2: Datatypes Second Edition] defines xs:NOTATION as an abstract type. Thus, casting to xs:NOTATION from any other type including xs:NOTATION is not permitted and raises a static error [err:XPST0080]XP. However, casting from one subtype of xs:NOTATION to another subtype of xs:NOTATION is permitted.

Casting is not supported to or from xs:anySimpleType. Thus, there is no row or column for this type in the table below. For any node that has not been validated or has been validated as xs:anySimpleType, the typed value of the node is an atomic item of type xs:untypedAtomic. There are no atomic items with the type annotation xs:anySimpleType at runtime. Casting to xs:anySimpleType is not permitted and raises a static error: [err:XPST0080]XP.

Similarly, casting is not supported to or from xs:anyAtomicType and will raise a static error: [err:XPST0080]XP. There are no atomic items with the type annotation xs:anyAtomicType at runtime, although this can be a statically inferred type.

If casting is attempted from an ST to a TT for which casting is not supported, as defined in the table below, a type error is raised [err:XPTY0004]XP.

In the following table, the columns and rows are identified by short codes that identify simple types as follows:

aURI = xs:anyURI
b64 = xs:base64Binary
bool = xs:boolean
dat = xs:date
gDay = xs:gDay
dbl = xs:double
dec = xs:decimal
dT = xs:dateTime
dur = xs:duration
flt = xs:float
hxB = xs:hexBinary
gMD = xs:gMonthDay
gMon = xs:gMonth
NOT = xs:NOTATION
QN = xs:QName
str = xs:string
tim = xs:time
gYM = xs:gYearMonth
gYr = xs:gYear

In the following table, the notation “S\T” indicates that the source (“S”) of the conversion is indicated in the column below the notation and that the target (“T”) is indicated in the row to the right of the notation.

S\T str flt dbl dec dur dT tim dat gYM gYr gMD gDay gMon bool b64 hxB aURI QN NOT
str Y M M M M M M M M M M M M M M M M M M
flt Y Y Y M N N N N N N N N N Y N N N N N
dbl Y Y Y M N N N N N N N N N Y N N N N N
dec Y Y Y Y N N N N N N N N N Y N N N N N
dur Y N N N Y N N N N N N N N N N N N N N
dT Y N N N N Y Y Y Y Y Y Y Y N N N N N N
tim Y N N N N N Y N N N N N N N N N N N N
dat Y N N N N Y N Y Y Y Y Y Y N N N N N N
gYM Y N N N N N N N Y N N N N N N N N N N
gYr Y N N N N N N N N Y N N N N N N N N N
gMD Y N N N N N N N N N Y N N N N N N N N
gDay Y N N N N N N N N N N Y N N N N N N N
gMon Y N N N N N N N N N N N Y N N N N N N
bool Y Y Y Y N N N N N N N N N Y N N N N N
b64 Y N N N N N N N N N N N N N Y Y N N N
hxB Y N N N N N N N N N N N N N Y Y N N N
aURI Y N N N N N N N N N N N N N N N Y N N
QN Y N N N N N N N N N N N N N N N N Y M
NOT Y N N N N N N N N N N N N N N N N Y M

20.1.1 Casting to xs:untypedAtomic

Any atomic item SV can be cast to xs:untypedAtomic.

The effect is the same as casting to xs:string (see 20.1.2 Casting to xs:string) and then returning the xs:untypedAtomic value comprising the same sequence of characters.

20.1.2 Casting to xs:string

Any atomic item SV can be cast to xs:string.

The resulting xs:string value TV depends on the source type ST as follows.

  • If SV is an instance of xs:string, TV is an instance of xs:string comprising the same sequence of characters as SV.

    Note:

    The implementation is free to return SV unchanged, including its original type annotation.

  • If SV is an instance of xs:anyURI, the result TV is an instance of xs:string comprising the same sequence of characters as SV, but with a type annotation of xs:anyURI. No escaping of special characters takes place.

  • If SV is an instance of xs:QName or xs:NOTATION:

    • if the qualified name has a prefix, then TV is the concatenation of the prefix of SV, a single colon (:), and the local name of SV.

    • otherwise TV is the local name of SV.

  • If SV is an instance of xs:numeric, the rules in 20.1.2.1 Casting numeric values to xs:string apply.

  • If SV is an instance of xs:dateTime, xs:date or xs:time, the rules in 20.1.2.2 Casting date/time values to xs:string apply.

  • If ST is xs:duration, or any subtype thereof including xs:yearMonthDuration and xs:dayTimeDuration, then the rules in 20.1.2.3 Casting xs:duration values to xs:string apply.

  • In all other cases, TV is the [XML Schema Part 2: Datatypes Second Edition] canonical representation of SV. For datatypes that do not have a canonical representation defined an ·implementation-dependent· canonical representation may be used.

To cast as xs:untypedAtomic the value is cast as xs:string, as described above, and the type annotation changed to xs:untypedAtomic.

20.1.2.1 Casting numeric values to xs:string

The following rules apply when the source type ST is xs:decimal, xs:double, or xs:float, or any subtype of these including xs:integer.

  1. If SV is an instance of xs:decimal, then the canonical representation of SV is returned, as defined in [Schema 1.1 Part 2]. Specifically, see [TITLE OF XS2 SPEC, TITLE OF f-decimalCanmap SECTION]XS2.

    Note:

    Unlike previous versions of this specification, no special rule is given for the case where SV is an instance of xs:integer. This is because the general rule for xs:decimal gives the same result. The result in this case will be a sequence of decimal digits in the range U+0030 (DIGIT ZERO, 0) to U+0039 (DIGIT NINE, 9) , optionally preceded by a minus sign, with no leading zeroes. For example: 42, -1, 0, or 1000000000.

    Note:

    An xs:decimal that is equal to an integer is converted to a string as if it were first cast to an xs:integer. Specifically, there will be no decimal point and no fractional part.

    If the value is not equal to an integer, then there will be a decimal point and a fractional part, which will be a sequence of decimal digits with no trailing zeroes. For example: 42.3, -1.5, or 0.00001.

  2. If SV is an instance of xs:float or xs:double, then:

    1. TV will be an xs:string in the lexical space of xs:double or xs:float that when converted to an xs:double or xs:float under the rules of 20.2 Casting from xs:string and xs:untypedAtomic produces a value that is equal to SV, or is NaN if SV is NaN. In addition, TV must satisfy the constraints in the following sub-bullets.

      1. If SV has an absolute value that is greater than or equal to 0.000001 (one millionth) and less than 1000000 (one million), then the value is converted to an xs:decimal and the resulting xs:decimal is converted to an xs:string according to the rules above, as though using an implementation of xs:decimal that imposes no limits on the totalDigits or fractionDigits facets.

      2. If SV has the value positive or negative zero, TV is "0" or "-0" respectively.

      3. If SV is positive or negative infinity, TV is the string "INF" or "-INF" respectively.

      4. In other cases, the result consists of a mantissa, which has the lexical form of an xs:decimal, followed by the letter "E", followed by an exponent which has the lexical form of an xs:integer. Leading zeroes and "+" signs are prohibited in the exponent. For the mantissa, there must be a decimal point, and there must be exactly one digit before the decimal point, which must be non-zero. The "+" sign is prohibited. There must be at least one digit after the decimal point. Apart from this mandatory digit, trailing zero digits are prohibited.

    Note:

    The above rules allow more than one representation of the same value. For example, the xs:float value whose exact decimal representation is 1.26743223E15 might be represented by any of the strings "1.26743223E15", "1.26743222E15" or "1.26743224E15" (inter alia). It is implementation-dependent which of these representations is chosen.

Note:

The string representations of numeric values are backwards compatible with XPath 1.0 except for the special values positive and negative infinity, negative zero and values outside the range 1.0e-6 to 1.0e+6.

20.1.2.2 Casting date/time values to xs:string

Changes in 4.0  

  1. The rules for conversion of dates and times to strings are now defined entirely in terms of XSD 1.1 canonical mappings, since these deliver exactly the same result as the XPath 3.1 rules.   [Issue 1401 PR 1409]

If SV is an instance of xs:dateTime, xs:date, xs:time, xs:gYear, xs:gYearMonth, xs:gMonth, xs:gMonthDay, or xs:gDay, then TV is the canonical representation of SV as defined in [Schema 1.1 Part 2].

Note:

The result TV includes the original timezone if a timezone is present.

All these data types contain different combinations of the components year, month, day, hour, minute, second, and timezone; all the components relevant to the data type (with the exception of the timezone) are output, and the results are concatenated together with suitable punctuation. Specifically:

  1. The year component is represented as a xs:string of four digits, or more if needed. A leading minus sign is present for BCE years.

  2. The month, day, hour and minute components are represented as two digits (with a leading zero if needed). For example, February is represented as 02.

    The hours component will never be "24": midnight is always represented as "00:00:00".

  3. The second component is output using as a two-digit integer if it is a whole number (for example, 30, 05, or 00), or if it is fractional, as two digits followed by a decimal point followed by as many digits as are necessary, with no trailing zeroes (for example 30.5 or 00.001).

  4. The timezone component, if present, is cast to xs:string by applying the function eg:convertTZtoString given in 20.1.5 Casting to date and time types. Examples are Z, +01:00, -05:00, or +05:30.

.

20.1.2.3 Casting xs:duration values to xs:string

Changes in 4.0  

  1. The rules for conversion of durations to strings are now defined entirely in terms of XSD 1.1 canonical mappings, since the XSD 1.1 rules deliver exactly the same result as the XPath 3.1 rules.   [Issue 1401 PR 1409]

If SV is an instance of xs:duration (including its subtypes xs:yearMonthDuration and xs:dayTimeDuration), then TV is the canonical representation of SV as defined in [Schema 1.1 Part 2]. Specifically, see [TITLE OF XS2 SPEC, TITLE OF f-durationCanMap SECTION]XS2.

Note:

The rules have the effect of normalizing the value so that the number of months is always less than 12, the number of hours less than 24, and the number of minutes and seconds less than 60. Zero-valued components are omitted. Fractional seconds follow the same rules as xs:decimal. For example, the duration P15MT30H is represented as P1Y3M1DT6H. A zero-length duration is output as PT0S.

Note:

At the time of writing, the published XSD 1.1 recommendation contains cut-and-paste errors in the definition of the dayTimeDuration canonical mapping. The binding of variable s should be to dt's ·seconds· (not ·months·) component, and the return expression given as sgn & 'P' & ·duYearMonthCanonicalFragmentMap·(|s|) should read sgn & 'P' & ·duDayTimeCanonicalFragmentMap·(|s|)

In reading these XSD formulations, be aware that a & b represents string concatenation, while |s| computes the absolute value of a number.

20.1.3 Casting to numeric types

This section defines the rules for casting to the primitive numeric types xs:float, xs:double, and xs:decimal. Rules for casting to the derived type xs:integer are given in 20.3.2 Casting to xs:integer.

20.1.3.1 Casting to xs:float

When a value of any simple type is cast as xs:float, the xs:float TV is derived from the ST and the SV as follows:

  • If ST is xs:float, then TV is SV and the conversion is complete.

  • If ST is xs:double, then TV is obtained as follows:

    • if SV is the xs:double value INF, -INF, NaN, positive zero, or negative zero, then TV is the xs:float value INF, -INF, NaN, positive zero, or negative zero respectively.

    • otherwise, SV can be expressed in the form m × 2^e where the mantissa m and exponent e are signed xs:integers whose value range is defined in [XML Schema Part 2: Datatypes Second Edition], and the following rules apply:

      • if m (the mantissa of SV) is outside the permitted range for the mantissa of an xs:float value (-2^24-1 to +2^24-1), then it is divided by 2^N where N is the lowest positive xs:integer that brings the result of the division within the permitted range, and the exponent e is increased by N. This is integer division (in effect, the binary value of the mantissa is truncated on the right). Let M be the mantissa and E the exponent after this adjustment.

      • if E exceeds 104 (the maximum exponent value in the value space of xs:float) then TV is the xs:float value INF or -INF depending on the sign of M.

      • if E is less than -149 (the minimum exponent value in the value space of xs:float) then TV is the xs:float value positive or negative zero depending on the sign of M

      • otherwise, TV is the xs:float value M × 2^E.

  • If ST is xs:decimal, or xs:integer, then TV is xs:float( SV cast as xs:string) and the conversion is complete.

  • If ST is xs:boolean, SV is converted to 1.0E0 if SV is true and to 0.0E0 if SV is false and the conversion is complete.

  • If ST is xs:untypedAtomic or xs:string, see 20.2 Casting from xs:string and xs:untypedAtomic.

    Note:

    XSD 1.1 adds the value +INF to the lexical space, as an alternative to INF. XSD 1.1 also adds negative zero to the value space.

Note:

Implementations should return negative zero for xs:float("-0.0E0"). But because [XML Schema Part 2: Datatypes Second Edition] does not distinguish between the values positive zero and negative zero. Implementations may return positive zero in this case.

20.1.3.2 Casting to xs:double

When a value of any simple type is cast as xs:double, the xs:double value TV is derived from the ST and the SV as follows:

  • If ST is xs:double, then TV is SV and the conversion is complete.

  • If ST is xs:float or a type derived from xs:float, then TV is obtained as follows:

    • if SV is the xs:float value INF, -INF, NaN, positive zero, or negative zero, then TV is the xs:double value INF, -INF, NaN, positive zero, or negative zero respectively.

    • otherwise, SV can be expressed in the form m × 2^e where the mantissa m and exponent e are signed xs:integer values whose value range is defined in [XML Schema Part 2: Datatypes Second Edition], and TV is the xs:double value m × 2^e.

  • If ST is xs:decimal or xs:integer, then TV is xs:double( SV cast as xs:string) and the conversion is complete.

  • If ST is xs:boolean, SV is converted to 1.0E0 if SV is true and to 0.0E0 if SV is false and the conversion is complete.

  • If ST is xs:untypedAtomic or xs:string, see 20.2 Casting from xs:string and xs:untypedAtomic.

    Note:

    XSD 1.1 adds the value +INF to the lexical space, as an alternative to INF. XSD 1.1 also adds negative zero to the value space.

Note:

Implementations should return negative zero for xs:double("-0.0E0"). But because [XML Schema Part 2: Datatypes Second Edition] does not distinguish between the values positive zero and negative zero. Implementations may return positive zero in this case.

20.1.3.3 Casting to xs:decimal

This section defines the rules for casting to the primitive type xs:decimal. The rules are also invoked implicitly as part of the process of converting to types derived from xs:decimal. There are special rules, however, if the target type TT is xs:integer, or a type derived from xs:integer: those rules are given in 20.3.2 Casting to xs:integer.

When the target type TT is xs:decimal, the resulting xs:decimal value TV is derived from ST and SV as follows:

  • If ST is xs:decimal or a subtype thereof (including xs:integer), then the result TV has the same ·datum· as SV. The type annotation may be xs:decimal or any subtype of xs:decimal for which this is a valid instance, including the original type ST.

  • If ST is xs:float or xs:double, then TV is the xs:decimal value, within the set of xs:decimal values that the implementation is capable of representing, that is numerically closest to SV. If two values are equally close, then the one that is closest to zero is chosen. If SV is too large to be accommodated as an xs:decimal, (see [XML Schema Part 2: Datatypes Second Edition] for ·implementation-defined· limits on numeric values) a dynamic error is raised [err:FOCA0001]. If SV is one of the special xs:float or xs:double values NaN, INF, or -INF, a dynamic error is raised [err:FOCA0002].

  • If ST is xs:boolean, the result TV is 1.0 if SV is 1 or true and to 0.0 if SV is 0 or false. The type annotation of the result may be any subtype of xs:decimal whose value space includes the integer values 0 and 1.

  • If ST is xs:untypedAtomic or xs:string, see 20.2 Casting from xs:string and xs:untypedAtomic.

20.1.4 Casting to duration types

This section defines the rules for casting to the primitive duration type xs:duration. Rules for casting to the derived types xs:yearMonthDuration and xs:dayTimeDuration are given in 20.3.3 Casting to xs:yearMonthDuration and xs:dayTimeDuration.

  • If the source value SV is an instance of xs:duration (including instances of subtypes such as xs:yearMonthDuration and xs:dayTimeDuration, then the datum of the result TV is the same as the datum of SV, and the type annotation is xs:duration or any subtype thereof that includes this datum in its value space (in particular, it may be the same as the type annotation of SV).

  • If ST is xs:untypedAtomic or xs:string, see 20.2 Casting from xs:string and xs:untypedAtomic.

20.1.5 Casting to date and time types

In several situations, casting to date and time types requires the extraction of a component from SV or from the result of fn:current-dateTime and converting it to an xs:string. These conversions must follow certain rules. For example, converting an xs:integer year value requires converting to an xs:string with four or more characters, preceded by a minus sign if the value is negative.

This document defines four functions to perform these conversions. These functions are for illustrative purposes only and make no recommendations as to style or efficiency. References to these functions from the following text are not normative.

The arguments to these functions come from functions defined in this document. Thus, the functions below assume that they are correct and do no range checking on them.

declare function eg:convertYearToString($year as xs:integer) as xs:string {
  let $plusMinus := if ($year >= 0) then "" else "-"
  let $yearString := abs($year) cast as xs:string
  let $length := string-length($yearString)
  return if ($length = 1) then concat($plusMinus, "000", $yearString)
         else if ($length = 2) then concat($plusMinus, "00", $yearString)
         else if ($length = 3) then concat($plusMinus, "0", $yearString)
         else concat($plusMinus, $yearString)
};
declare function eg:convertTo2CharString($value as xs:integer) as xs:string {
  let $string := $value cast as xs:string
  return if (string-length($string) = 1) then concat("0", $string)
         else $string
};
declare function eg:convertSecondsToString($seconds as xs:decimal) as xs:string {
  let $string := $seconds cast as xs:string
  let $intLength := string-length(($seconds cast as xs:integer) cast as xs:string)
  return if ($intLength = 1) then concat("0", $string)
         else $string
};
declare function eg:convertTZtoString($tz as xs:dayTimeDuration?) as xs:string {
  if (empty($tz)) then ""
  else if ($tz eq xs:dayTimeDuration('PT0S')) then "Z"
  else let $tzh := hours-from-duration($tz)
       let $tzm := minutes-from-duration($tz)
       let $plusMinus := if ($tzh >= 0) then "+" else "-"
       let $tzhString := eg:convertTo2CharString(abs($tzh))
       let $tzmString := eg:convertTo2CharString(abs($tzm))
       return concat($plusMinus, $tzhString, ":", $tzmString)
};

Conversion from ·primitive types· to date and time types follows the rules below.

  1. When a value of any primitive type is cast as xs:dateTime, the xs:dateTime value TV is derived from ST and SV as follows:

    • If ST is xs:dateTime, then TV is SV.

    • If ST is xs:date, then let SYR be eg:convertYearToString( year-from-date( SV )), let SMO be eg:convertTo2CharString( month-from-date( SV )), let SDA be eg:convertTo2CharString( day-from-date( SV )) and let STZ be eg:convertTZtoString( timezone-from-date( SV )); TV is xs:dateTime( concat( SYR , '-', SMO , '-', SDA , 'T00:00:00 ', STZ ) ).

    • If ST is xs:untypedAtomic or xs:string, see 20.2 Casting from xs:string and xs:untypedAtomic.

  2. When a value of any primitive type is cast as xs:time, the xs:time value TV is derived from ST and SV as follows:

    • If ST is xs:time, then TV is SV.

    • If ST is xs:dateTime, then TV is xs:time( concat( eg:convertTo2CharString( hours-from-dateTime( SV )), ':', eg:convertTo2CharString( minutes-from-dateTime( SV )), ':', eg:convertSecondsToString( seconds-from-dateTime( SV )), eg:convertTZtoString( timezone-from-dateTime( SV )) )).

    • If ST is xs:untypedAtomic or xs:string, see 20.2 Casting from xs:string and xs:untypedAtomic.

  3. When a value of any primitive type is cast as xs:date, the xs:date value TV is derived from ST and SV as follows:

    • If ST is xs:date, then TV is SV.

    • If ST is xs:dateTime, then let SYR be eg:convertYearToString( year-from-dateTime( SV )), let SMO be eg:convertTo2CharString( month-from-dateTime( SV )), let SDA be eg:convertTo2CharString( day-from-dateTime( SV )) and let STZ be eg:convertTZtoString(timezone-from-dateTime( SV )); TV is xs:date( concat( SYR , '-', SMO , '-', SDA, STZ ) ).

    • If ST is xs:untypedAtomic or xs:string, see 20.2 Casting from xs:string and xs:untypedAtomic.

  4. When a value of any primitive type is cast as xs:gYearMonth, the xs:gYearMonth value TV is derived from ST and SV as follows:

    • If ST is xs:gYearMonth, then TV is SV.

    • If ST is xs:dateTime, then let SYR be eg:convertYearToString( year-from-dateTime( SV )), let SMO be eg:convertTo2CharString( month-from-dateTime( SV )) and let STZ be eg:convertTZtoString( timezone-from-dateTime( SV )); TV is xs:gYearMonth( concat( SYR , '-', SMO, STZ ) ).

    • If ST is xs:date, then let SYR be eg:convertYearToString( year-from-date( SV )), let SMO be eg:convertTo2CharString( month-from-date( SV )) and let STZ be eg:convertTZtoString( timezone-from-date( SV )); TV is xs:gYearMonth( concat( SYR , '-', SMO, STZ ) ).

    • If ST is xs:untypedAtomic or xs:string, see 20.2 Casting from xs:string and xs:untypedAtomic.

  5. When a value of any primitive type is cast as xs:gYear, the xs:gYear value TV is derived from ST and SV as follows:

    • If ST is xs:gYear, then TV is SV.

    • If ST is xs:dateTime, let SYR be eg:convertYearToString( year-from-dateTime( SV )) and let STZ be eg:convertTZtoString( timezone-from-dateTime( SV )); TV is xs:gYear(concat( SYR, STZ )).

    • If ST is xs:date, let SYR be eg:convertYearToString( year-from-date( SV )); and let STZ be eg:convertTZtoString( timezone-from-date( SV )); TV is xs:gYear(concat( SYR, STZ )).

    • If ST is xs:untypedAtomic or xs:string, see 20.2 Casting from xs:string and xs:untypedAtomic.

  6. When a value of any primitive type is cast as xs:gMonthDay, the xs:gMonthDay value TV is derived from ST and SV as follows:

    • If ST is xs:gMonthDay, then TV is SV.

    • If ST is xs:dateTime, then let SMO be eg:convertTo2CharString( month-from-dateTime( SV )), let SDA be eg:convertTo2CharString( day-from-dateTime( SV )) and let STZ be eg:convertTZtoString( timezone-from-dateTime( SV )); TV is xs:gYearMonth( concat( '--', SMO '-', SDA, STZ ) ).

    • If ST is xs:date, then let SMO be eg:convertTo2CharString( month-from-date( SV )), let SDA be eg:convertTo2CharString( day-from-date( SV )) and let STZ be eg:convertTZtoString( timezone-from-date( SV )); TV is xs:gYearMonth( concat( '--', SMO , '-', SDA, STZ ) ).

    • If ST is xs:untypedAtomic or xs:string, see 20.2 Casting from xs:string and xs:untypedAtomic.

  7. When a value of any primitive type is cast as xs:gDay, the xs:gDay value TV is derived from ST and SV as follows:

    • If ST is xs:gDay, then TV is SV.

    • If ST is xs:dateTime, then let SDA be eg:convertTo2CharString( day-from-dateTime( SV )) and let STZ be eg:convertTZtoString( timezone-from-dateTime( SV )); TV is xs:gDay( concat( '---', SDA, STZ )).

    • If ST is xs:date, then let SDA be eg:convertTo2CharString( day-from-date( SV )) and let STZ be eg:convertTZtoString( timezone-from-date( SV )); TV is xs:gDay( concat( '---', SDA, STZ )).

    • If ST is xs:untypedAtomic or xs:string, see 20.2 Casting from xs:string and xs:untypedAtomic.

  8. When a value of any primitive type is cast as xs:gMonth, the xs:gMonth value TV is derived from ST and SV as follows:

    • If ST is xs:gMonth, then TV is SV.

    • If ST is xs:dateTime, then let SMO be eg:convertTo2CharString( month-from-dateTime( SV )) and let STZ be eg:convertTZtoString( timezone-from-dateTime( SV )); TV is xs:gMonth( concat( '--' , SMO, STZ )).

    • If ST is xs:date, then let SMO be eg:convertTo2CharString( month-from-date( SV )) and let STZ be eg:convertTZtoString( timezone-from-date( SV )); TV is xs:gMonth( concat( '--', SMO, STZ )).

    • If ST is xs:untypedAtomic or xs:string, see 20.2 Casting from xs:string and xs:untypedAtomic.

20.1.6 Casting to xs:boolean

When the target type TT is xs:boolean, the resulting xs:boolean value TV is derived from the source value SV as follows:

  • If SV is an instance of xs:boolean, then TV is SV.

  • If SV is an instance of xs:numeric and SV is 0, +0, -0, 0.0, 0.0E0 or NaN, then TV is false.

  • If ST is is an instance of xs:numeric and SV is not one of the above values, then TV is true.

  • If ST is xs:untypedAtomic or xs:string, see 20.2 Casting from xs:string and xs:untypedAtomic.

20.1.7 Casting to xs:base64Binary and xs:hexBinary

Values of type xs:base64Binary can be cast as xs:hexBinary and vice versa, since the two types have the same value space. Casting to xs:base64Binary and xs:hexBinary is also supported from the same type and from xs:untypedAtomic, xs:string and subtypes of xs:string using [XML Schema Part 2: Datatypes Second Edition] semantics.

20.1.8 Casting to xs:anyURI

Casting to xs:anyURI is supported only from the same type, xs:untypedAtomic or xs:string.

When a value of any ·primitive type· is cast as xs:anyURI, the xs:anyURI value TV is derived from the ST and SV as follows:

20.1.9 Casting to xs:QName and xs:NOTATION

Casting from xs:string or xs:untypedAtomic to xs:QName or xs:NOTATION is described in 20.2 Casting from xs:string and xs:untypedAtomic.

It is also possible to cast from xs:NOTATION to xs:QName, or from xs:QName to any type derived by restriction from xs:NOTATION. (Casting to xs:NOTATION itself is not allowed, because xs:NOTATION is an abstract type.) The resulting xs:QName or xs:NOTATION has the same prefix, local name, and namespace URI parts as the supplied value.

Note:

See 19.2 Constructor functions for xs:QName and xs:NOTATION for a discussion of how the combination of atomization and casting might not produce the desired effect.

20.1.10 Casting to xs:ENTITY

[XML Schema Part 2: Datatypes Second Edition] says that “The value space of ENTITY is the set of all strings that match the NCName production ... and have been declared as an unparsed entity in a document type definition.” However, [XSL Transformations (XSLT) Version 4.0] and [XQuery 4.1: An XML Query Language] do not check that constructed values of type xs:ENTITY match declared unparsed entities. Thus, this rule is relaxed in this specification and, in casting to xs:ENTITY and types derived from it, no check is made that the values correspond to declared unparsed entities.

20.2 Casting from xs:string and xs:untypedAtomic

Changes in 4.0 

  1. When casting from a string to a duration or time or dateTime, it is now specified that when there are more digits in the fractional seconds than the implementation is able to retain, excess digits are truncated. Rounding upwards (which could affect the number of minutes or hours in the value) is not permitted.   [Issue 1089 PR 1090 19 March 2024]

This section applies when the supplied value SV is an instance of xs:string or xs:untypedAtomic, including types derived from these by restriction. If the value is xs:untypedAtomic, it is treated in exactly the same way as a string containing the same sequence of characters.

The supplied string is mapped to a typed value of the target type as defined in [XML Schema Part 2: Datatypes Second Edition]. Whitespace normalization is applied as indicated by the whiteSpace facet for the datatype. The resulting whitespace-normalized string must be a valid lexical form for the datatype. The semantics of casting follow the rules of XML Schema validation. For example, "13" cast as xs:unsignedInt returns the xs:unsignedInt typed value 13. This could also be written xs:unsignedInt("13").

The target type can be any simple type other than an abstract type. Specifically, it can be a type whose variety is atomic, union, or list. In each case the effect of casting to the target type is the same as constructing an element with the supplied value as its content, validating the element using the target type as the governing type, and atomizing the element to obtain its typed value.

When the target type is a derived type that is restricted by a pattern facet, the lexical form is first checked against the pattern before further casting is attempted (See 20.3.1 Casting to derived types). If the lexical form does not conform to the pattern, a dynamic error [err:FORG0001] is raised.

For example, consider a user-defined type my:boolean which is derived by restriction from xs:boolean and specifies the pattern facet value="0|1". The expression "true" cast as my:boolean would fail with a dynamic error [err:FORG0001].

Facets other than pattern are checked after the conversion. For example if there is a user-defined datatype called my:height defined as a restriction of xs:integer with the facet <maxInclusive value="84"/>, then the expression "100" cast as my:height would fail with a dynamic error [err:FORG0001].

Casting to the types xs:NOTATION, xs:anySimpleType, or xs:anyAtomicType is not permitted because these types are abstract (they have no immediate instances).

Special rules apply when casting to namespace-sensitive types. The types xs:QName and xs:NOTATION are namespace-sensitive. Any type derived by restriction from a namespace-sensitive type is itself namespace-sensitive, as is any union type having a namespace-sensitive type among its members, and any list type having a namespace-sensitive type as its item type. For details, see 19.2 Constructor functions for xs:QName and xs:NOTATION.

Note:

Since version 3.0 of this specification, casting has been allowed between xs:QName and xs:NOTATION in either direction; this was not permitted in previous Recommendations. Version 3.0 also removed the rule that only a string literal (rather than a dynamic string) may be cast to an xs:QName

When casting to a numeric type:

  • If the value is too large or too small to be accurately represented by the implementation, it is handled as an overflow or underflow as defined in 4.2 Arithmetic operators on numeric values.

  • If the target type is xs:float or xs:double, the string -0 (and equivalents such as -0.0 or -000) should be converted to the value negative zero. However, if the implementation is reliant on an implementation of XML Schema 1.0 in which negative zero is not part of the value space for these types, these lexical forms may be converted to positive zero.

In casting to xs:decimal or to a type derived from xs:decimal, if the value is not too large or too small but nevertheless cannot be represented accurately with the number of decimal digits available to the implementation, the implementation may round to the nearest representable value or may raise a dynamic error [err:FOCA0006]. The choice of rounding algorithm and the choice between rounding and error behavior is ·implementation-defined·.

When casting to xs:duration, xs:dateTime, or xs:time, if the seconds component has more fractional digits than are supported by the implementation, excess digits must be truncated. This rule ensures that components other than the seconds component are unaffected: for example xs:dateTime('2023-12-31T23:59:59.999999999') is guaranteed to deliver an xs:dateTime value whose year component is 2023 rather than 2024.

Note:

Implementations are required to support millisecond precision or greater.

In casting to xs:date, xs:dateTime, xs:gYear, or xs:gYearMonth (or types derived from these), if the value is too large or too small to be represented by the implementation, a dynamic error [err:FODT0001] is raised.

In casting to a duration value, if the value is too large or too small to be represented by the implementation, a dynamic error [err:FODT0002] is raised.

For xs:anyURI, the extent to which an implementation validates the lexical form of xs:anyURI is ·implementation-dependent·.

If the cast fails for any other reason, a dynamic error [err:FORG0001] is raised.

20.3 Casting involving non-primitive types

Casting from xs:string and xs:untypedAtomic to any other type (primitive or non-primitive) has been described in 20.2 Casting from xs:string and xs:untypedAtomic. This section defines how other casts to non-primitive types operate, including casting to types derived by restriction, to union types, and to list types.

20.3.1 Casting to derived types

Casting a value to a derived type can be separated into a number of cases. In these rules:

  • The types xs:integer, xs:yearMonthDuration, and xs:dayTimeDuration are treated as quasi-primitive types (alongside the 20 truly ·primitive types·).

  • For any atomic type T, let P(T) denote the most specific primitive or quasi-primitive type such that itemType-subtype(T, P(T)) is true.

The rules are then:

  1. When the source type ST is the same type as the target type TT: this case always succeeds, returning the source value SV unchanged.

  2. When itemType-subtype(ST, TT) is true: see 20.3.4 Casting from derived types to parent types.

  3. When TT is the quasi-primitive type xs:integer and SV is an instance of xs:numeric: see 20.3.2 Casting to xs:integer.

  4. When TT is the quasi-primitive type xs:yearMonthDuration or xs:dayTimeDuration and SV is an instance of xs:duration: see 20.3.3 Casting to xs:yearMonthDuration and xs:dayTimeDuration.

  5. When P(ST) is the same type as P(TT): see 20.3.5 Casting within a branch of the type hierarchy.

  6. Otherwise (P(ST) is not the same type as P(TT)): see 20.3.6 Casting across the type hierarchy.

20.3.2 Casting to xs:integer

When an atomic item SV is cast as xs:integer, the resulting xs:integer value TV is obtained as follows:

Note:

When casting to a subtype of xs:integer (for example, xs:long), the rules in 20.3.1 Casting to derived types apply. Note, however, that these rules treat xs:integer as a quasi-primitive type.

20.3.3 Casting to xs:yearMonthDuration and xs:dayTimeDuration

When the source value SV is an instance of xs:duration (including any subtype of xs:duration), then:

  • If the target type TT is xs:yearMonthDuration, the result is an instance of xs:yearMonthDuration whose months component is equal to the months component of SV. The seconds component of SV is ignored.

  • If the target type TT is xs:dayTimeDuration, the result is an instance of xs:dayTimeDuration whose seconds component is equal to the seconds component of SV. The months component of SV is ignored.

In all other cases, the general rules of 20.3.1 Casting to derived types apply.

Note:

In general, casting to xs:yearMonthDuration or xs:dayTimeDuration loses information.

Note:

When casting to a subtype of xs:dayTimeDuration or xs:yearMonthDuration, the rules in 20.3.1 Casting to derived types apply. Note, however, that these rules treat xs:dayTimeDuration and xs:yearMonthDuration as quasi-primitive types.

20.3.4 Casting from derived types to parent types

It is always possible to cast an atomic item A to a type T if the relation A instance of T is true, provided that T is not an abstract type.

For example, it is possible to cast an xs:unsignedShort to an xs:unsignedInt, to an xs:integer, to an xs:decimal, or to a union type whose member types are xs:integer and xs:double.

Since the value space of the original type is a subset of the value space of the target type, such a cast is always successful.

For the expression A instance of T to be true, T must be either an atomic type, or a union type that has no constraining facets. It cannot be a list type, nor a union type derived by restriction from another union type, nor a union type that has a list type among its member types.

The result will have the same value as the original, but will have a new type annotation:

  • If T is an atomic type, then the type annotation of the result is T.

  • If T is a union type, then the type of the result is an atomic type M such that M is one of the atomic types in the transitive membership of the union type T and A instance of M is true; if there is more than one type M that satisfies these conditions (which could happen, for example, if T is the union of two overlapping types such as xs:int and xs:positiveInteger) then the first one is used, taking the member types in the order in which they appear within the definition of the union type.

20.3.5 Casting within a branch of the type hierarchy

It is possible to cast an SV to a TT if the type of the SV and the TT type are both derived by restriction (directly or indirectly) from the same ·primitive type·, provided that the supplied value conforms to the constraints implied by the facets of the target type. This includes the case where the target type is derived from the type of the supplied value, as well as the case where the type of the supplied value is derived from the target type. For example, an instance of xs:byte can be cast as xs:unsignedShort, provided the value is not negative.

If the value does not conform to the facets defined for the target type, then a dynamic error is raised [err:FORG0001]. See [XML Schema Part 2: Datatypes Second Edition]. In the case of the pattern facet (which applies to the lexical space rather than the value space), the pattern is tested against the canonical representation of the value, as defined for the source type (or the result of casting the value to an xs:string, in the case of types that have no canonical representation defined for them).

Note that this will cause casts to fail if the pattern excludes the canonical lexical representation of the source type. For example, if the type my:distance is defined as a restriction of xs:decimal with a pattern that requires two digits after the decimal point, casting of an xs:integer to my:distance will always fail, because the canonical representation of an xs:integer does not conform to this pattern.

In some cases, casting from a parent type to a derived type requires special rules. See 20.1.4 Casting to duration types for rules regarding casting to xs:yearMonthDuration and xs:dayTimeDuration. See 20.1.10 Casting to xs:ENTITY, below, for casting to xs:ENTITY and types derived from it.

20.3.6 Casting across the type hierarchy

When the ST and the TT are derived, directly or indirectly, from different ·primitive types·, this is called casting across the type hierarchy. Casting across the type hierarchy is logically equivalent to three separate steps performed in order. Errors can occur in either of the latter two steps.

  1. Cast the SV, up the hierarchy, to the ·primitive type· of the source, as described in 20.3.4 Casting from derived types to parent types.

    1. If SV is an instance of xs:string or xs:untypedAtomic, check its value against the pattern facet of TT, and raise a dynamic error [err:FORG0001] if the check fails.

  2. Let P(TT) be the most specific primitive or quasi-primitive type of which TT is a subtype, as described in 20.3.1 Casting to derived types.

    Cast the value to P(TT), as described in 20.1 Casting from primitive types to primitive types if P(TT) is primitive, or as described in 20.3.1 Casting to derived types if P(TT) is quasi-primitive.

    If TT is derived from xs:NOTATION, assume for the purposes of this rule that casting to xs:NOTATION succeeds.

  3. Cast the value down to the target type TT, as described in 20.3.5 Casting within a branch of the type hierarchy

20.3.7 Casting to union types

If the target type of a cast expression (or a constructor function) is a type with variety union, the supplied value must be one of the following:

  1. A value of type xs:string or xs:untypedAtomic. This case follows the general rules for casting from strings, and has already been described in 20.2 Casting from xs:string and xs:untypedAtomic.

    If the union type has a pattern facet, the pattern is tested against the supplied value after whitespace normalization, using the whiteSpace normalization rules of the member datatype against which validation succeeds.

  2. A value that is an instance of one of the atomic types in the transitive membership of the union type, and of the union type itself. This case has already been described in 20.3.4 Casting from derived types to parent types

    This situation only applies when the value is an instance of the union type, which means it will never apply when the union is derived by facet-based restriction from another union type.

  3. A value that is castable to one or more of the atomic types in the transitive membership of the union type (in the sense that the castable as operator returns true).

    In this case the supplied value is cast to each atomic type in the transitive membership of the union type in turn (in the order in which the member types appear in the declaration) until one of these casts is successful; if none of them is successful, a dynamic error occurs [err:FORG0001]. If the union type has constraining facets then the resulting value must satisfy these facets, otherwise a dynamic error occurs [err:FORG0001].

    If the union type has a pattern facet, the pattern is tested against the canonical representation of the result value.

    Only the atomic types in the transitive membership of the union type are considered. The union type may have list types in its transitive membership, but (unless the supplied value is of type xs:string or xs:untypedAtomic, in which case the rules in 20.2 Casting from xs:string and xs:untypedAtomic apply), any list types in the membership are effectively ignored.

If more than one of these conditions applies, then the casting is done according to the rules for the first condition that applies.

If none of these conditions applies, the cast fails with a dynamic error [err:FORG0001].

Example: consider a type U whose member types are xs:integer and xs:date.

  • The expression "123" cast as U returns the xs:integer value 123.

  • The expression current-date() cast as U returns the current date as an instance of xs:date.

  • The expression 23.1 cast as U returns the xs:integer value 23.

Example: consider a type V whose member types are xs:short and xs:negativeInteger.

  • The expression "-123" cast as V returns the xs:short value -123.

  • The expression "-100000" cast as V returns the xs:negativeInteger value -100000.

  • The expression 93.7 cast as V returns the xs:short value 93.

  • The expression "93.7" cast as V raises a dynamic error [err:FORG0001] on the grounds that the string "93.7" is not in the lexical space of the union type.

Example: consider a type W that is derived from the above type V by restriction, with a pattern facet of -?\d\d.

  • The expression "12" cast as V returns the xs:short value 12.

  • The expression "123" cast as V raises an dynamic error [err:FORG0001] on the grounds that the string "123" does not match the pattern facet.

20.3.8 Casting to list types

If the target type of a cast expression (or a constructor function) is a type with variety list, the supplied value must be of type xs:string or xs:untypedAtomic. The rules follow the general principle for all casts from xs:string outlined in 20.2 Casting from xs:string and xs:untypedAtomic.

If the supplied value is not of type xs:string or xs:untypedAtomic, a type error is raised [err:XPTY0004]XP.

The semantics of the operation are consistent with validation: that is, the effect of casting a string S to a list type L is the same as constructing an element or attribute node whose string value is S, validating it using L as the governing type, and atomizing the resulting node. The result will always be either failure, or a sequence of zero or more atomic items each of which is an instance of the item type of L (or if the item type of L is a union type, an instance of one of the atomic types in its transitive membership).

If the item type of the list type is namespace-sensitive, then the namespace bindings in the static context will be used to resolve any namespace prefix, in the same way as when the target type is xs:QName.

If the list type has a pattern facet, the pattern must match the supplied value after collapsing whitespace (an operation equivalent to the use of the fn:normalize-space function).

For example, the expression cast "A B C D" as xs:NMTOKENS produces a sequence of four xs:NMTOKEN values, ("A", "B", "C", "D").

For example, given a user-defined type my:coordinates defined as a list of xs:integer with the facet <xs:length value="2"/>, the expression my:coordinates("2 -1") will return a sequence of two xs:integer values (2, -1), while the expression my:coordinates("1 2 3") will result in a dynamic error because the length of the list does not conform to the length facet. The expression my:coordinates("1.0 3.0") will also fail because the strings 1.0 and 3.0 are not in the lexical space of xs:integer.

A References

A.1 Normative references

Character Model for the World Wide Web 1.0: Fundamentals
Character Model for the World Wide Web 1.0: Fundamentals, Martin J. Dürst, François Yergeau, et. al., Editors. World Wide Web Consortium, 15 February 2015. This version is http://www.w3.org/TR/2005/REC-charmod-20050215/. The latest version is available at https://www.w3.org/TR/charmod/.
HTML: Living Standard
HTML: Living Standard. WHATWG, 18 November 2022.
DOM: Living Standard
DOM: Living Standard. WHATWG, 26 October 2022.
IANA Timezone Database
The tz timezone database, available at http://www.iana.org/time-zones. It is ·implementation-defined· which version of the database is used.
IEEE 754-2019
IEEE. IEEE Standard for Floating-Point Arithmetic.
IEEE 1003.1-2024
IEEE 802-3
“IEEE Standard for Ethernet,” in IEEE Std 802.3-2022 (Revision of IEEE Std 802.3-2018). 29 July 2022. doi: 10.1109/IEEESTD.2022.9844436.
ISO 3166-1
ISO (International Organization for Standardization) Codes for the representation of names of countries and their subdivisions - Part 1: Country codes ISO 3166-1:2013.
ISO 8601
ISO (International Organization for Standardization). Representations of dates and times. Third edition, 2004-12-01. ISO 8601:2004(E). Available from: http://www.iso.org/".
ISO 10967
ISO (International Organization for Standardization). ISO/IEC 10967-1:2012, Information technology—Language Independent Arithmetic—Part 1: Integer and floating point arithmetic [Geneva]: International Organization for Standardization, 2012. Available from: http://www.iso.org/.
ISO 15924
ISO (International Organization for Standardization) Information and documentation — Codes for the representation of names of scripts ISO 15924:2004, January 2004.
ISO 15924 Register
Unicode Consortium. Codes for the representation of names of scripts — Alphabetical list of four-letter script codes. See http://www.unicode.org/iso15924/iso15924-codes.html. Retrieved February 2013; continually updated.
Legacy extended IRIs for XML resource identification
Legacy extended IRIs for XML resource identification. Henry S. Thomson, Richard Tobin, and Norman Walsh (eds), World Wide Web Consortium. 3 November 2008. Available at http://www.w3.org/TR/leiri/.
RFC 1321
IETF. RFC 1321: The MD5 Message-Digest Algorithm. Available at: http://www.ietf.org/rfc/rfc1321.txt.
RFC 2376
IETF. RFC 2376: XML Media Types. Available at: http://www.ietf.org/rfc/rfc2376.txt.
RFC 3986
IETF. RFC 3986: Uniform Resource Identifiers (URI): Generic Syntax. Available at: http://www.ietf.org/rfc/rfc3986.txt.
RFC 3987
IETF. RFC 3987: Internationalized Resource Identifiers (IRIs). Available at: http://www.ietf.org/rfc/rfc3987.txt.
RFC 4180
IETF. RFC 4180: Common Format and MIME Type for Comma-Separated Values (CSV) Files. Available at: http://www.ietf.org/rfc/rfc4180.txt.
RFC 6151
IETF. RFC 6151: Updated Security Considerations for the MD5 Message-Digest and the HMAC-MD5 Algorithms Available at: http://www.ietf.org/rfc/rfc6151.txt.
RFC 7159
IETF. RFC 7159: The Javascript Object Notation (JSON) Data Interchange Format Available at: http://www.rfc-editor.org/rfc/rfc7159.txt.
RFC 7303
H. Thompson and C. Lilley. XML Media Types. IETF RFC 7303. See http://www.ietf.org/rfc/rfc7303.txt.
FIPS 180-4
National Institute of Standards and Technology. Secure Hash Standard (SHS). FIPS PUB 180-4. August 2015. See http://dx.doi.org/10.6028/NIST.FIPS.180-4.
UAX #15
Unicode Standard Annex #15: Unicode Normalization Forms. Ed. Mark Davis and Ken Whistler, Unicode Consortium. The current version is 9.0.0, dated 2016-02-24. As with [The Unicode Standard], the version to be used is ·implementation-defined·. Available at: http://www.unicode.org/reports/tr15/.
UAX #29
Unicode Standard Annex #29: Unicode Text Segmentation. Ed. Josh Hadley, Unicode Consortium. The current version is 15.1.0, dated 2023-08-16. As with [The Unicode Standard], the version to be used is ·implementation-defined·. Available at: http://www.unicode.org/reports/tr29/.
The Unicode Standard
The Unicode Consortium, Reading, MA, Addison-Wesley, 2016. The Unicode Standard as updated from time to time by the publication of new versions. See http://www.unicode.org/standard/versions/ for the latest version and additional information on versions of the standard and of the Unicode Character Database. The version of Unicode to be used is ·implementation-defined·, but implementations are recommended to use the latest Unicode version; currently, Version 9.0.0.
UTS #10
Unicode Technical Standard #10: Unicode Collation Algorithm. Ed. Mark Davis and Ken Whistler, Unicode Consortium. The current version is 9.0.0, dated 2016-05-18. As with [The Unicode Standard], the version to be used is ·implementation-defined·. Available at: http://www.unicode.org/reports/tr10/.
UTS #35
Unicode Technical Standard #35: Unicode Locale Data Markup Language. Ed Mark Davis et al, Unicode Consortium. The current version is 29, dated 2016-03-15. As with [The Unicode Standard], the version to be used is ·implementation-defined·. Available at: http://www.unicode.org/reports/tr35/.
Extensible Markup Language (XML) 1.0 (Fifth Edition)
Extensible Markup Language (XML) 1.0 (Fifth Edition), Tim Bray, Jean Paoli, Michael Sperberg-McQueen, et. al., Editors. World Wide Web Consortium, 26 Nov 2008. This version is http://www.w3.org/TR/2008/REC-xml-20081126/. The latest version is available at http://www.w3.org/TR/xml.
Extensible Markup Language (XML) 1.1 Recommendation
Extensible Markup Language (XML) 1.1 (Second Edition), Tim Bray, Jean Paoli, Michael Sperberg-McQueen, et. al., Editors. World Wide Web Consortium, 16 Aug 2006. This version is http://www.w3.org/TR/2006/REC-xml11-20060816. The latest version is available at http://www.w3.org/TR/xml11/.
XML Path Language (XPath) Version 1.0
XML Path Language (XPath) Version 1.0, James Clark and Steven DeRose, Editors. World Wide Web Consortium, 16 Nov 1999. This version is http://www.w3.org/TR/1999/REC-xpath-19991116. The latest version is available at http://www.w3.org/TR/xpath.
XML Path Language (XPath) 4.0
CITATION: T.B.D.
XSL Transformations (XSLT) Version 1.0
XSL Transformations (XSLT) Version 1.0, James Clark, Editor. World Wide Web Consortium, 16 November 1999. This version is https://www.w3.org/TR/1999/REC-xslt-19991116/. The latest version is available at https://www.w3.org/TR/xslt/.
XSL Transformations (XSLT) Version 2.0
XSL Transformations (XSLT) Version 2.0 (Second Edition), Michael Kay, Editor. World Wide Web Consortium, 23 January 2007. This version is https://www.w3.org/TR/2007/REC-xslt20-20070123/. The latest version is available at https://www.w3.org/TR/xslt20/.
XSL Transformations (XSLT) Version 4.0
CITATION: T.B.D.
XQuery and XPath Data Model (XDM) 3.0
XQuery and XPath Data Model (XDM) 3.0, Norman Walsh, Anders Berglund, John Snelson, Editors. World Wide Web Consortium, 08 April 2014. This version is https://www.w3.org/TR/2014/REC-xpath-datamodel-30-20140408/. The latest version is available at https://www.w3.org/TR/xpath-datamodel-30/.
XQuery and XPath Data Model (XDM) 3.1
XQuery and XPath Data Model (XDM) 3.1, Norman Walsh, John Snelson, Andrew Coleman, Editors. World Wide Web Consortium, 21 March 2017. This version is https://www.w3.org/TR/2017/REC-xpath-datamodel-31-20170321/. The latest version is available at https://www.w3.org/TR/xpath-datamodel-31/.
XQuery and XPath Data Model (XDM) 4.0
XQuery and XPath Data Model (XDM) 4.0, XSLT Extensions Community Group, World Wide Web Consortium.
XSLT and XQuery Serialization 3.1
XSLT and XQuery Serialization 3.1, Andrew Coleman and Michael Sperberg-McQueen, Editors. World Wide Web Consortium, 21 March 2017. This version is https://www.w3.org/TR/2017/REC-xslt-xquery-serialization-31-20170321/. The latest version is available at https://www.w3.org/TR/xslt-xquery-serialization-31/.
XQuery 1.0 and XPath 2.0 Formal Semantics
XQuery 1.0 and XPath 2.0 Formal Semantics (Second Edition), Jérôme Siméon, Denise Draper, Peter Frankhauser, et. al., Editors. World Wide Web Consortium, 14 December 2010. This version is https://www.w3.org/TR/2010/REC-xquery-semantics-20101214/. The latest version is available at https://www.w3.org/TR/xquery-semantics/.
XQuery 4.1: An XML Query Language
CITATION: T.B.D.
XML Inclusions (XInclude) Version 1.0 (Second Edition)
XML Inclusions (XInclude) Version 1.0 (Second Edition), Jonathan Marsh, David Orchard, and Daniel Veillard, Editors. World Wide Web Consortium, 15 Nov 2006. This version is http://www.w3.org/TR/2006/REC-xinclude-20061115/. The latest version is available at http://www.w3.org/TR/xinclude/.
XML Schema Part 2: Datatypes Second Edition
XML Schema Part 2: Datatypes Second Edition, Oct. 28 2004. Available at: http://www.w3.org/TR/xmlschema-2/
Schema 1.1 Part 2
W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes, David Peterson, Sandy Gao, Ashok Malhotra, et. al., Editors. World Wide Web Consortium, 05 Apr 2012. This version is http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/. The latest version is available at http://www.w3.org/TR/xmlschema11-2/.
Namespaces in XML
Namespaces in XML 1.0 (Third Edition), Tim Bray, Dave Hollander, Andrew Layman, et. al., Editors. World Wide Web Consortium, 08 Dec 2009. This version is http://www.w3.org/TR/2009/REC-xml-names-20091208/. The latest version is available at http://www.w3.org/TR/xml-names/.
Invisible XML
Invisible XML Specification, Steven Pemberton, editor. World Wide Web Consortium, 20 June 2020. This version is https://invisiblexml.org/1.0/. The latest version is available at https://invisiblexml.org/current/.

A.2 Non-normative references

BLAKE3 Hashing
Blake3 Algorithm Specification. Available at: https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf
Calendrical Calculations
Edward M. Reingold and Nachum Dershowitz. Calendrical Calculations Millennium edition (2nd Edition). Cambridge University Press, ISBN 0 521 77752 6.
Unicode CLDR
CLDR - Unicode Common Locale Data Repository. Available at: http://cldr.unicode.org.
Character Model for the World Wide Web 1.0: Normalization
Character Model for the World Wide Web 1.0: Normalization, Last Call Working Draft. Available at: http://www.w3.org/TR/2004/WD-charmod-norm-20040225/.
EXPath
EXPath: Collaboratively Defining Open Standards for Portable XPath Extensions. http://expath.org/.
EXQuery
EXQuery: Collaboratively Defining Open Standards for Portable XQuery Extensions. http://exquery.org/.
EXSLT
EXSLT: A Community Initiative to Provide Extensions to XSLT. https://exslt.github.io.
FunctX
FunctX Functions. http://www.functx.com/.
HTML 4.0
HTML 4.01 Recommendation, 24 December 1999. Available at: http://www.w3.org/TR/REC-html40/.
ICU
ICU - International Components for Unicode. Available at http://site.icu-project.org.
POSIX.1-2008
The Open Group Base Specifications Issue 7 (IEEE Std 1003.1-2008). Available at: http://pubs.opengroup.org/onlinepubs/9699919799/.
RFC 822
IETF. RFC 822: Standard for the Format of ARPA Internet Text Messages. Available at: http://www.ietf.org/rfc/rfc822.txt.
RFC 850
IETF. RFC 850: Standard for Interchange of USENET Messages. Available at: http://www.ietf.org/rfc/rfc850.txt.
RFC 1036
IETF. RFC 1036: Standard for Interchange of USENET Messages. Available at: http://www.ietf.org/rfc/rfc1036.txt.
RFC 1123
IETF. RFC 1123: Requirements for Internet Hosts -- Application and Support. Available at: http://www.ietf.org/rfc/rfc1123.txt.
RFC 2616
IETF. RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1. Available at: http://www.ietf.org/rfc/rfc2616.txt.
RFC 3339
IETF. RFC 3339: Date and Time on the Internet: Timestamps. Available at: http://www.ietf.org/rfc/rfc3339.txt.
UTS #18
Unicode Technical Standard #18: Unicode Regular Expressions. Ed. Mark Davis and Andy Heniger, Unicode Consortium. The current version is 17, dated 2013-11-19. Available at: http://www.unicode.org/reports/tr18/.
Working With Timezones
World Wide Web Consortium Working Group Note. Working With Timezones, October 13, 2005. Available at: http://www.w3.org/TR/2005/NOTE-timezone-20051013/.

B Error summary

The error text provided with these errors is non-normative.

err:FOAP0001, Wrong number of arguments.

Raised when fn:apply is called and the arity of the supplied function is not the same as the number of members in the supplied array.

err:FOAR0001, Division by zero.

This error is raised whenever an attempt is made to divide by zero.

err:FOAR0002, Numeric operation overflow/underflow.

This error is raised whenever numeric operations result in an overflow or underflow.

err:FOAY0001, Array index out of bounds.

This error is raised when an integer used to select a member of an array is outside the range of values for that array.

err:FOAY0002, Negative array length.

This error is raised when the $length argument to array:subarray is negative.

err:FOCA0001, Input value too large for decimal.

Raised when casting to xs:decimal if the supplied value exceeds the implementation-defined limits for the datatype.

err:FOCA0002, Invalid lexical value.

Raised by fn:resolve-QName and fn:QName when a supplied value does not have the lexical form of a QName or URI respectively; and when casting to decimal, if the supplied value is NaN or Infinity.

err:FOCA0003, Input value too large for integer.

Raised when casting to xs:integer if the supplied value exceeds the implementation-defined limits for the datatype.

err:FOCA0005, NaN supplied as float/double value.

Raised when multiplying or dividing a duration by a number, if the number supplied is NaN.

err:FOCA0006, String to be cast to decimal has too many digits of precision.

Raised when casting a string to xs:decimal if the string has more digits of precision than the implementation can represent (the implementation also has the option of rounding).

err:FOCH0001, Codepoint not valid.

Raised by fn:codepoints-to-string if the input contains an integer that is not the codepoint of a ·permitted character·.

err:FOCH0002, Unsupported collation.

Raised by any function that uses a collation if the requested collation is not recognized.

err:FOCH0003, Unsupported normalization form.

Raised by fn:normalize-unicode if the requested normalization form is not supported by the implementation.

err:FOCH0004, Collation does not support collation units.

Raised by functions such as fn:contains if the requested collation does not operate on a character-by-character basis.

err:FOCH0005, Unrecognized or invalid character name.

Raised by fn:char if the supplied character name is not recognized, or if it represents a codepoint that is not a ·permitted character·.

err:FOCV0001, CSV field quoting error.

Raised when parsing CSV input if a syntax error in the input CSV is found.

err:FOCV0002, Invalid CSV delimiter error.

Raised when parsing CSV input if the field-separator, record-separator, or quote-character option is set to an invalid value.

err:FOCV0003, Duplicate CSV delimiter error.

Raised when parsing CSV input if the same delimiter character is assigned to more than one role.

err:FOCV0004, Argument supplied is not a known column name.

Raised by the function from the get entry of csv-columns-record, if its $key argument is an xs:string and is not one of the known column names.

err:FODC0001, No context document.

Raised by fn:id, fn:idref, and fn:element-with-id if the node that identifies the tree to be searched is a node in a tree whose root is not a document node.

err:FODC0002, Error retrieving resource.

Raised by fn:doc, fn:collection, and fn:uri-collection to indicate that either the supplied URI cannot be dereferenced to obtain a resource, or the resource that is returned is not parseable as XML.

err:FODC0003, Function not defined as deterministic.

Raised by fn:doc, fn:collection, and fn:uri-collection to indicate that it is not possible to return a result that is guaranteed deterministic.

err:FODC0004, Invalid collection URI.

Raised by fn:collection and fn:uri-collection if the argument is not a valid xs:anyURI.

err:FODC0005, Invalid URI reference.

Raised (optionally) by fn:doc if the argument is not a valid xs:anyURI.

err:FODC0006, String passed to fn:parse-xml is not a well-formed XML document.

Raised by fn:parse-xml if the supplied string is not a well-formed and namespace-well-formed XML document; or if DTD validation is requested and the document is not valid against its DTD.

err:FODC0007, String passed to fn:parse-xml is not a DTD-valid XML document.

Raised by fn:parse-xml if DTD validation is requested and the supplied string has no DTD or is not valid against the DTD.

err:FODC0008, Invalid value for the xsd-validation option of fn:parse-xml.

Raised when the xsd-validation option to fn:parse-xml is supplied, and the value is not one of the permitted values; for example if the option type Q{U}NNN is used, and Q{U}NNN does not identify a type in the static context.

err:FODC0009, Processor is not schema-aware.

Raised when the xsd-validation option to fn:parse-xml is set to a value other than skip, if the processor is not schema-aware.

err:FODC0010, The processor does not support serialization.

Raised when fn:serialize is called and the processor does not support serialization, in cases where the host language makes serialization an optional feature.

err:FODC0011, String passed to fn:parse-html is not a well-formed HTML document.

Raised by fn:parse-html if the supplied string is not a well-formed HTML document.

err:FODC0012, Unsupported HTML parser option.

Raised by fn:parse-html if a key passed to $options, or its value, is not supported by the implementation.

err:FODC0013, No validating XML parser available.

Raised when the dtd-validation option to fn:parse-xml is set, if no validating XML parser is available. Note: it is recommended that all processors should support the dtd-validation option, but there may be environments (such as web browsers) where this is not practically feasible.

err:FODC0014, String passed to fn:parse-xml is not a schema-valid XML document.

Raised by fn:parse-xml if XSD validation is requested and the XML document represented by the supplied string is not valid against the relevant XSD schema.

err:FODF1280, Invalid decimal format name.

This error is raised if the decimal format name supplied to fn:format-number is not a valid QName, or if the prefix in the QName is undeclared, or if there is no decimal format in the static context with a matching name.

err:FODF1290, Invalid decimal format property.

This error is raised if a decimal format value supplied to fn:format-number is not valid for the associated property, or if the properties of the decimal format resulting from a supplied map do not have distinct values.

err:FODF1310, Invalid decimal format picture string.

This error is raised if the picture string supplied to fn:format-number or fn:format-integer has invalid syntax.

err:FODT0001, Overflow/underflow in date/time operation.

Raised when casting to date/time datatypes, or performing arithmetic with date/time values, if arithmetic overflow or underflow occurs.

err:FODT0002, Overflow/underflow in duration operation.

Raised when casting to duration datatypes, or performing arithmetic with duration values, if arithmetic overflow or underflow occurs.

err:FODT0003, Invalid timezone value.

Raised by adjust-date-to-timezone and related functions if the supplied timezone is invalid.

err:FOER0000, Unidentified error.

Error code used by fn:error when no other error code is provided.

err:FOFD1340, Invalid date/time formatting parameters.

This error is raised if the picture string or calendar supplied to fn:format-date, fn:format-time, or fn:format-dateTime has invalid syntax.

err:FOFD1350, Invalid date/time formatting component.

This error is raised if the picture string supplied to fn:format-date selects a component that is not present in a date, or if the picture string supplied to fn:format-time selects a component that is not present in a time.

err:FOHA0001, Invalid algorithm.

Raised by fn:hash if the effective value of the supplied algorithm is not one of the values supported by the implementation.

err:FOJS0001, JSON syntax error.

Raised by functions such as fn:json-doc, fn:parse-json or fn:json-to-xml if the string supplied as input does not conform to the JSON grammar (optionally with implementation-defined extensions).

err:FOJS0003, JSON duplicate keys.

Raised by functions such as map:merge, fn:json-doc, fn:parse-json or fn:json-to-xml if the input contains duplicate keys, when the chosen policy is to reject duplicates.

err:FOJS0004, JSON: not schema-aware.

Raised by fn:json-to-xml if validation is requested when the processor does not support schema validation or typed nodes.

err:FOJS0005, Invalid options.

Raised by functions such as map:merge, fn:parse-json, and fn:xml-to-json if the $options map contains an invalid entry.

err:FOJS0006, Invalid XML representation of JSON.

Raised by fn:xml-to-json if the XML input does not conform to the rules for the XML representation of JSON.

err:FOJS0007, Bad JSON escape sequence.

Raised by fn:xml-to-json if the XML input uses the attribute escaped="true" or escaped-key="true", and the corresponding string or key contains an invalid JSON escape sequence.

err:FONS0004, No namespace found for prefix.

Raised by fn:resolve-QName and analogous functions if a supplied QName has a prefix that has no binding to a namespace.

err:FONS0005, Base-uri not defined in the static context.

Raised by fn:resolve-uri if no base URI is available for resolving a relative URI.

err:FOQM0001, Module URI is a zero-length string.

Raised by fn:load-xquery-module if the supplied module URI is zero-length.

err:FOQM0002, Module URI not found.

Raised by fn:load-xquery-module if no module can be found with the supplied module URI.

err:FOQM0003, Static error in dynamically loaded XQuery module.

Raised by fn:load-xquery-module if a static error (including a statically detected type error) is encountered when processing the library module.

err:FOQM0005, Parameter for dynamically loaded XQuery module has incorrect type.

Raised by fn:load-xquery-module if a value is supplied for the initial context item or for an external variable, and the value does not conform to the required type declared in the dynamically loaded module.

err:FOQM0006, No suitable XQuery processor available.

Raised by fn:load-xquery-module if no XQuery processor is available supporting the requested XQuery version (or if none is available at all).

err:FORG0001, Invalid value for cast/constructor.

A general-purpose error raised when casting, if a cast between two datatypes is allowed in principle, but the supplied value cannot be converted: for example when attempting to cast the string "nine" to an integer.

err:FORG0002, Invalid argument to fn:resolve-uri.

Raised when either argument to fn:resolve-uri is not a valid URI/IRI.

err:FORG0003, fn:zero-or-one called with a sequence containing more than one item.

Raised by fn:zero-or-one if the supplied value contains more than one item.

err:FORG0004, fn:one-or-more called with a sequence containing no items.

Raised by fn:one-or-more if the supplied value is an empty sequence.

err:FORG0005, fn:exactly-one called with a sequence containing zero or more than one item.

Raised by fn:exactly-one if the supplied value is not a singleton sequence.

err:FORG0006, Invalid argument type.

Raised by functions such as fn:max, fn:min, fn:avg, fn:sum if the supplied sequence contains values inappropriate to this function.

err:FORG0008, The two arguments to fn:dateTime have inconsistent timezones.

Raised by fn:dateTime if the two arguments both have timezones and the timezones are different.

err:FORG0009, Error in resolving a relative URI against a base URI in fn:resolve-uri.

A catch-all error for fn:resolve-uri, recognizing that the implementation can choose between a variety of algorithms and that some of these may fail for a variety of reasons.

err:FORG0010, Invalid date/time.

Raised when the input to fn:parse-ietf-date does not match the prescribed grammar, or when it represents an invalid date/time such as 31 February.

err:FORG0011, Invalid radix.

Raised when the radix supplied to fn:parse-integer is not in the range 2 to 36.

err:FORG0012, Invalid digits.

Raised when the digits in the string supplied to fn:parse-integer are not in the range appropriate to the chosen radix.

err:FORG0013, Unknown option.

Raised if the option in an ·option map· is not described in the specification, if it is not supported by the implementation and if its name is in no namespace.

err:FORG0013
(Error code unused?)
err:FORG0014, Node not in subtree.

Raised by fn:element-number if the supplied $from node is not an ancestor-or-self of the explicit or implicit $element node.

err:FORX0001, Invalid regular expression flags.

Raised by regular expression functions such as fn:matches and fn:replace if the regular expression flags contain a character other than i, m, q, s, or x.

err:FORX0002, Invalid regular expression.

Raised by regular expression functions such as fn:matches and fn:replace if the regular expression is syntactically invalid.

err:FORX0003, Regular expression matches zero-length string.

For functions such as fn:replace and fn:tokenize, raises an error if the supplied regular expression is capable of matching a zero length string.

err:FORX0004, Invalid replacement string.

Raised by fn:replace to report errors in the replacement string.

err:FORX0005, Incompatible arguments for fn:replace.

Raised by fn:replace if both the $replacement and $action arguments are supplied.

err:FOTY0012, Argument to fn:data contains a node that does not have a typed value.

Raised by fn:data, or by implicit atomization, if applied to a node with no typed value, the main example being an element validated against a complex type that defines it to have element-only content.

err:FOTY0013, The argument to fn:data contains a function item.

Raised by fn:data, or by implicit atomization, if the sequence to be atomized contains a function item other than an array.

err:FOTY0014, The argument to fn:string is a function item.

Raised by fn:string, or by implicit string conversion, if the input sequence contains a function item.

err:FOUR0001, Invalid IPv6/IPvFuture authority

A dynamic error is raised if the authority component of a URI contains an open square bracket but no corresponding close square bracket.

err:FOUT1170, Invalid URI reference.

Raised by fn:unparsed-text or fn:unparsed-text-lines if the $source argument contains a fragment identifier, or if it cannot be resolved to an absolute URI (for example, because the base-URI property in the static context is absent), or if it cannot be used to retrieve the string representation of a resource.

err:FOUT1190, Cannot decode external resource.

Raised by fn:unparsed-text or fn:unparsed-text-lines if the $encoding argument is not a valid encoding name, if the processor does not support the specified encoding, if the string representation of the retrieved resource contains octets that cannot be decoded into Unicode ·characters· using the specified encoding, or if the resulting characters are not ·permitted characters·.

err:FOUT1200, Cannot infer encoding of external resource.

Raised by fn:unparsed-text or fn:unparsed-text-lines if the $encoding argument is absent and the processor cannot infer the encoding using external information and the encoding is not UTF-8.

err:FOXT0001, No suitable XSLT processor available

A dynamic error is raised if no XSLT processor suitable for evaluating a call on fn:transform is available.

err:FOXT0002, Invalid parameters to XSLT transformation

A dynamic error is raised if the parameters supplied to fn:transform are invalid, for example if two mutually exclusive parameters are supplied. If a suitable XSLT error code is available (for example in the case where the requested initial-template does not exist in the stylesheet), that error code should be used in preference.

err:FOXT0003, XSLT transformation failed

A dynamic error is raised if an XSLT transformation invoked using fn:transform fails with a static or dynamic error. The XSLT error code is used if available; this error code provides a fallback when no XSLT error code is returned, for example because the processor is an XSLT 1.0 processor.

err:FOXT0004, XSLT transformation has been disabled

A dynamic error is raised if the fn:transform function is invoked when XSLT transformation (or a specific transformation option) has been disabled for security or other reasons.

err:FOXT0006, XSLT output contains non-accepted characters

A dynamic error is raised if the result of the fn:transform function contains characters available only in XML 1.1 and the calling processor cannot handle such characters.

C Schemas

Two functions in this specification, fn:analyze-string and fn:json-to-xml, produce results in the form of an XDM node tree that must conform to a specified schema, defined in this appendix. In both cases the elements in the result are in the namespace http://www.w3.org/2005/xpath-functions, which is therefore the target namespace of the relevant schema.

A processor may have built-in knowledge of this schema, or it may read it from external files. Any attempt to supply a modified form of this schema will have unpredictable consequences. Modification here includes not only actual changes to the text of a schema document, but also actions such as using xs:redefine or xs:override, adding members to substitution groups, or defining derived types. Processors are not required to detect and reject such modifications. When validating against this schema, it is recommended that processors should ignore or reject any xsi:schemaLocation or xsi:type attributes in the instance being validated.

The schema for this namespace is organized as three schema documents. The first is a simple umbrella document that includes the other two. A copy can be found at xpath-functions.xsd:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified"
    targetNamespace="http://www.w3.org/2005/xpath-functions">
    
    <!-- 
     * This is a schema for the namespace http://www.w3.org/2005/xpath-functions
     *
     * The schema is made available under the terms of the W3C software notice and license
     * at http://www.w3.org/Consortium/Legal/copyright-software-19980720
     *
     * The schema includes two schema documents, containing definitions of the structure
     * of the results of the fn:analyze-string and fn:json-to-xml functions respectively.
     *
    -->
    
    <xs:include schemaLocation="analyze-string.xsd"/>
    <xs:include schemaLocation="schema-for-json.xsd"/>
</xs:schema>

C.1 Schema for the result of fn:analyze-string

This schema describes the output of the function fn:analyze-string.

The schema is reproduced below, and can also be found in analyze-string.xsd:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://www.w3.org/2005/xpath-functions"
    xmlns:fn="http://www.w3.org/2005/xpath-functions"
    elementFormDefault="qualified">
    
    <!-- 
     * This is a schema for the XML representation of JSON used as the target for the
     * function fn:analyze-string()
     *
     * The schema is made available under the terms of the W3C software notice and license
     * at http://www.w3.org/Consortium/Legal/copyright-software-19980720
     *
    -->

    <xs:element name="analyze-string-result" type="fn:analyze-string-result-type"/>
    <xs:element name="match" type="fn:match-type"/>
    <xs:element name="non-match" type="xs:string"/>
    <xs:element name="group" type="fn:group-type"/>
    
    <xs:complexType name="analyze-string-result-type" mixed="true">
        <xs:choice minOccurs="0" maxOccurs="unbounded">
            <xs:element ref="fn:match"/>
            <xs:element ref="fn:non-match"/>
        </xs:choice>
    </xs:complexType>
        
    <xs:complexType name="match-type" mixed="true">
        <xs:sequence>
            <xs:element ref="fn:group" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>
    
    <xs:complexType name="group-type" mixed="true">
        <xs:sequence>
            <xs:element ref="fn:group" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attribute name="nr" type="xs:positiveInteger"/>
    </xs:complexType>    
 
</xs:schema>

C.2 Schema for the result of fn:json-to-xml

This schema describes the output of the function fn:json-to-xml, and the input to the function fn:xml-to-json.

The schema is reproduced below, and can also be found in schema-for-json.xsd:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified"
    targetNamespace="http://www.w3.org/2005/xpath-functions"
    xmlns:j="http://www.w3.org/2005/xpath-functions">
    
    <!-- 
     * This is a schema for the XML representation of JSON used as the target for the
     * function fn:json-to-xml()
     *
     * The schema is made available under the terms of the W3C software notice and license
     * at http://www.w3.org/Consortium/Legal/copyright-software-19980720
     *
    -->
    
    <xs:element name="map" type="j:mapType">
        <xs:unique name="unique-key">
            <xs:selector xpath="*"/>
            <xs:field xpath="@key"/>
            <xs:field xpath="@escaped-key"/>
        </xs:unique>
    </xs:element>
    
    <xs:element name="array" type="j:arrayType"/>
    
    <xs:element name="string" type="j:stringType"/>
    
    <xs:element name="number" type="j:numberType"/>
    
    <xs:element name="boolean" type="j:booleanType"/>
    
    <xs:element name="null" type="j:nullType"/>
    
    <xs:complexType name="nullType">
        <xs:sequence/>
        <xs:anyAttribute processContents="skip" namespace="##other"/>
    </xs:complexType>
    
    <xs:complexType name="booleanType">
        <xs:simpleContent>
            <xs:extension base="xs:boolean">
                <xs:anyAttribute processContents="skip" namespace="##other"/>
            </xs:extension>
        </xs:simpleContent>
    </xs:complexType>
    
    <xs:complexType name="stringType">
        <xs:simpleContent>
            <xs:extension base="xs:string">
                <xs:attribute name="escaped" type="xs:boolean" use="optional" default="false"/>
                <xs:anyAttribute processContents="skip" namespace="##other"/>
            </xs:extension>
        </xs:simpleContent>
    </xs:complexType>
    
    <xs:simpleType name="finiteNumberType">
        <xs:restriction base="xs:double">
            <!-- exclude positive and negative infinity, and NaN -->
            <xs:minExclusive value="-INF"/>
            <xs:maxExclusive value="INF"/>
        </xs:restriction>
    </xs:simpleType>
    
    <xs:complexType name="numberType">
        <xs:simpleContent>
            <xs:extension base="j:finiteNumberType">
                <xs:anyAttribute processContents="skip" namespace="##other"/>
            </xs:extension>
        </xs:simpleContent>
    </xs:complexType>
    
    <xs:complexType name="arrayType">
        <xs:choice minOccurs="0" maxOccurs="unbounded">
            <xs:element ref="j:map"/>
            <xs:element ref="j:array"/>
            <xs:element ref="j:string"/>
            <xs:element ref="j:number"/>
            <xs:element ref="j:boolean"/>
            <xs:element ref="j:null"/>
        </xs:choice>
        <xs:anyAttribute processContents="skip" namespace="##other"/>
    </xs:complexType>
    
    <xs:complexType name="mapWithinMapType">
        <xs:complexContent>
            <xs:extension base="j:mapType">
                <xs:attributeGroup ref="j:key-group"/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
    
    <xs:complexType name="arrayWithinMapType">
        <xs:complexContent>
            <xs:extension base="j:arrayType">
                <xs:attributeGroup ref="j:key-group"/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
    
    <xs:complexType name="stringWithinMapType">
        <xs:simpleContent>
            <xs:extension base="j:stringType">
                <xs:attributeGroup ref="j:key-group"/>
            </xs:extension>
        </xs:simpleContent>
    </xs:complexType>
    
    <xs:complexType name="numberWithinMapType">
        <xs:simpleContent>
            <xs:extension base="j:numberType">
                <xs:attributeGroup ref="j:key-group"/>
            </xs:extension>
        </xs:simpleContent>
    </xs:complexType>
    
    <xs:complexType name="booleanWithinMapType">
        <xs:simpleContent>
            <xs:extension base="j:booleanType">
                <xs:attributeGroup ref="j:key-group"/>
            </xs:extension>
        </xs:simpleContent>
    </xs:complexType>
    
    <xs:complexType name="nullWithinMapType">
        <xs:attributeGroup ref="j:key-group"/>
    </xs:complexType>
    
    <xs:complexType name="mapType">
        <xs:choice minOccurs="0" maxOccurs="unbounded">
            <xs:element name="map" type="j:mapWithinMapType">
                <xs:unique name="unique-key-2">
                    <xs:selector xpath="*"/>
                    <xs:field xpath="@key"/>
                </xs:unique>
            </xs:element>
            <xs:element name="array" type="j:arrayWithinMapType"/>            
            <xs:element name="string" type="j:stringWithinMapType"/>   
            <xs:element name="number" type="j:numberWithinMapType"/>
            <xs:element name="boolean" type="j:booleanWithinMapType"/>
            <xs:element name="null" type="j:nullWithinMapType"/>
        </xs:choice>
        <xs:anyAttribute processContents="skip" namespace="##other"/>
    </xs:complexType>
    
    <xs:attributeGroup name="key-group">
        <xs:attribute name="key" type="xs:string" use="required"/>
        <xs:attribute name="escaped-key" type="xs:boolean" use="optional" default="false"/>
    </xs:attributeGroup>
    
</xs:schema>

C.3 Schema for the result of fn:csv-to-xml

This schema describes the output of the function fn:csv-to-xml.

The schema is reproduced below, and can also be found in schema-for-csv.xsd:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
    targetNamespace="http://www.w3.org/2005/xpath-functions"
    xmlns:csv="http://www.w3.org/2005/xpath-functions">

    <!--
     * This is a schema for the XML representation of CSV used as the target for the
     * function fn:csv-to-xml()
     *
     * The schema is made available under the terms of the W3C software notice and license
     * at http://www.w3.org/Consortium/Legal/copyright-software-19980720
     *
    -->

    <xs:element name="csv" type="csv:csvType"/>

    <xs:element name="columns" type="csv:columnsType"/>

    <xs:element name="rows" type="csv:rowsType"/>

    <xs:element name="column" type="csv:columnFieldType"/>

    <xs:element name="row" type="csv:rowType"/>

    <xs:element name="field" type="csv:fieldType"/>

    <xs:complexType name="csvType">
        <xs:sequence>
            <xs:element ref="csv:columns" minOccurs="0" maxOccurs="1"/>
            <xs:element ref="csv:rows" minOccurs="1" maxOccurs="1"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="columnsType">
        <xs:sequence>
            <xs:element ref="csv:column" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="rowsType">
        <xs:sequence>
            <xs:element ref="csv:row" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="rowType">
        <xs:sequence>
            <xs:element ref="csv:field" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="columnFieldType">
        <xs:simpleContent>
            <xs:extension base="xs:string">
                <xs:anyAttribute processContents="skip" namespace="##other"/>
            </xs:extension>
        </xs:simpleContent>
    </xs:complexType>

    <xs:complexType name="fieldType">
        <xs:simpleContent>
            <xs:extension base="csv:columnFieldType">
                  <xs:attribute name="column" type="xs:string" use="optional"/>
            </xs:extension>
        </xs:simpleContent>
    </xs:complexType>
</xs:schema>

D Glossary (Non-Normative)

atomic item

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.

capturing sub-expression

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.

character

A character is an instance of the CharXML production of [Extensible Markup Language (XML) 1.0 (Fifth Edition)].

codepoint

A codepoint is an integer assigned to a ·character· by the Unicode consortium, or reserved for future assignment to a character.

context-dependent

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.

context-independent

A function definitionXP40 that is not ·context-dependent· is called context-independent.

CSV

The term comma separated values or CSV refers to a wide variety of plain-text tabular data formats with fields and records separated by standard character delimiters (often, but not invariably, commas).

date formatting function

The three functions fn:format-dateTime, fn:format-date, and fn:format-time are referred to collectively as the date formatting functions.

datum

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.

deterministic

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.

digit family

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.

execution scope

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.

expanded-QName

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.

focus-dependent

A function is focus-dependent if its result depends on the focusXP31 (that is, the context item, position, or size) of the caller.

focus-dependent

A function that is not ·focus-dependent· is called focus-independent.

Gregorian

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.

higher-order

Functions that accept functions among their arguments, or that return functions in their result, are described in this specification as higher-order functions.

identical

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:

implementation-defined

Where behavior is described as implementation-defined, variations between processors are permitted, but a conformant implementation must document the choices it has made.

implementation-dependent

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.

key-value pair map

A key-value pair map is a map containing two entries, one (with the key "key") containing the key part of a key value pair, the other (with the key "value") containing the value part of a key value pair.

map

A map consists of a set of entries, also known as key-value pairs. Each entry comprises a key which is an arbitrary atomic item, and an arbitrary sequence called the associated value.

nondeterministic

A function that is not ·deterministic· is referred to as nondeterministic.

nondeterministic with respect to ordering

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.

optional digit character

The optional digit character is the character that is the value of the digitXP31 property.

option parameter conventions

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.

permitted character

A permitted character is one within the repertoire accepted by the implementation.

picture string

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.

primitive type

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].

same key

Within a map, no two entries have the same key. Two atomic items K1 and K2 are the same key for this purpose if the function call fn:atomic-equal($K1, $K2) returns true.

singleton map

A singleton map is a map containing a single entry.

string

A string is a sequence of zero or more ·characters·, or equivalently, a value in the value space of the xs:string datatype.

type annotation

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).

Unicode codepoint collation

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).

URI

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].

variadic

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.

E Other Functions (Non-Normative)

This Appendix describes some sources of functions that fall outside the scope of the function library defined in this specification. It includes both function specifications and function implementations. Inclusion of a function in this appendix does not constitute any kind of recommendation or endorsement; neither is omission from this appendix to be construed negatively. This Appendix does not attempt to give any information about licensing arrangements for these function specifications or implementations.

E.1 XPath Functions Defined in Other W3C Recommendations

A number of W3C Recommendations make use of XPath, and in some cases such Recommmendations define additional functions to be made available when XPath is used in a specific host language.

E.1.1 Functions Defined in XSLT

The various versions of XSLT have all included additional functions intended to be available only when XPath is used within XSLT, and not in other host language environments. Some of these functions were originally defined in XSLT, and subsequently migrated into the core function library defined in this specification.

Generally, the reason that functions have been defined in XSLT rather than in the core library has been that they required additional static or dynamic context information.

XSLT-defined functions share the core namespace http://www.w3.org/2005/xpath-functions (but in XPath 1.0 and XSLT 1.0, no namespace was defined for these functions).

The conformance rules for XSLT 4.0 require implementations to support either XPath 3.0 or XPath 3.1. Some of the new functions in XPath 3.1, however, must be supported by all XSLT 4.0 implementations whether or not they implement other parts of XPath 3.1.

The following table lists all functions that have been defined in XSLT 1.0, 2.0, or 3.0, and summarizes their status.

Function name Availability
fn:accumulator-after XSLT 3.0 only
fn:accumulator-before XSLT 3.0 only
fn:available-system-properties XSLT 3.0 only
fn:collation-key Common to XSLT 3.0 and XPath 3.1
fn:copy-of XSLT 3.0 only
fn:current XSLT 1.0, 2.0, and 3.0
fn:current-group XSLT 2.0 and 3.0
fn:current-grouping-key XSLT 2.0 and 3.0
fn:current-merge-group XSLT 3.0 only
fn:current-merge-key XSLT 3.0 only
fn:current-output-uri XSLT 3.0 only
fn:document XSLT 1.0, 2.0, and 3.0
fn:element-available XSLT 1.0, 2.0, and 3.0
fn:format-date XSLT 2.0; migrated to XPath 3.0 and 3.1
fn:format-dateTime XSLT 2.0; migrated to XPath 3.0 and 3.1
fn:format-number XSLT 1.0 and 2.0; migrated to XPath 3.0 and 3.1
fn:format-time XSLT 2.0; migrated to XPath 3.0 and 3.1
fn:function-available XSLT 1.0, 2.0, and 3.0
fn:generate-id XSLT 1.0 and 2.0; migrated to XPath 3.0 and 3.1
fn:json-to-xml Common to XSLT 3.0 and XPath 3.1
fn:key XSLT 1.0, 2.0, and 3.0
fn:regex-group XSLT 2.0 and 3.0
fn:snapshot XSLT 3.0 only
fn:stream-available XSLT 3.0 only
fn:system-property XSLT 1.0, 2.0, and 3.0
fn:type-available XSLT 2.0 and 3.0
fn:unparsed-entity-public-id XSLT 2.0 and 3.0
fn:unparsed-entity-uri XSLT 1.0, 2.0, and 3.0
fn:unparsed-text XSLT 2.0; migrated to XPath 3.0 and 3.1
fn:xml-to-json Common to XSLT 3.0 and XPath 3.1
map:contains Common to XSLT 3.0 and XPath 3.1
map:entry Common to XSLT 3.0 and XPath 3.1
map:find Common to XSLT 3.0 and XPath 3.1
map:for-each Common to XSLT 3.0 and XPath 3.1
map:get Common to XSLT 3.0 and XPath 3.1
map:keys Common to XSLT 3.0 and XPath 3.1
map:merge Common to XSLT 3.0 and XPath 3.1
map:put Common to XSLT 3.0 and XPath 3.1
map:remove Common to XSLT 3.0 and XPath 3.1
map:size Common to XSLT 3.0 and XPath 3.1

E.1.2 Functions Defined in XForms

XForms 1.1 is based on XPath 1.0. It adds the following functions to the set defined in XPath 1.0, using the same namespace:

boolean-from-string, is-card-number, avg, min, max, count-non-empty, index, power, random, compare, if, property, digest, hmac, local-date, local-dateTime, now, days-from-date, days-to-date, seconds-from-dateTime, seconds-to-dateTime, adjust-dateTime-to-timezone, seconds, months, instance, current, id, context, choose, event.

XForms 2.0 was first published as a W3C Working Draft, and subsequently as a W3C Community Group specification. These draft specifications do not include any additional functions beyond those in the core XPath specification.

E.1.3 Function Defined in XQuery Update 1.0

The XQuery Update 1.0 specification defines one additional function in the core namespace http://www.w3.org/2005/xpath-functions, namely fn:put. This function can be used to write a document to external storage. It is thus unusual in that it has side-effects; the XQuery Update 1.0 specification defines semantics for updating expressions including this function.

Although XQuery Update 1.0 is defined as an extension of XQuery 1.0, a number of implementers have adapted it, in a fairly intuitive way, to work with later versions of XQuery. At the time of this publication, later versions of the XQuery Update specification remain at Working Draft status.

E.2 Functions Defined by Community Groups

A number of community groups, with varying levels of formal organization, have defined specifications for additional function libraries to augment the core functions defined in this specification. Many of the resulting function specifications have implementations available for popular XPath, XQuery, and XSLT processors, though the level of support is highly variable.

The first such group was EXSLT. This activity was primarily concerned with augmenting the capability of XSLT 1.0, and many of its specifications were overtaken by core functions that became available in XPath 2.0. EXSLT defined a number of function modules covering:

Dates and Times
Dynamic XPath Evaluation
Common (containing most notably the widely used node-set function)
Math (max, min, abs, and trigonometric functions)
Random Number Generation
Regular Expressions
Sets (operations on sets of nodes including set intersection and difference)
String Manipulation (tokenize, replace, join and split, etc.)

Specifications from the EXSLT group can be found at [EXSLT].

A renewed attempt to define additional function libraries using XPath 2.0 as its baseline formed under the name EXPath. Again, the specifications are in various states of maturity and stability, and implementation across popular processors is patchy. At the time of this publication the function libraries that exist in stable published form include:

Binary (functions for manipulating binary data)
File Handling (reading and writing files)
Geospatial (handling of geographic data)
HTTP Client (sending HTTP requests)
ZIP Facility (reading and creating ZIP files or similar archives)

The EXPath community has also been engaged in other related projects, such as defining packaging standards for distribution of XSLT/XQuery components, and tools for unit testing. Its specifications can be found at [EXPath].

A third activity has operated under the name EXQuery, which as the name suggests has focused on extensions to XQuery. EXQuery has published a single specification, RestXQ, which is primarily a system of function annotations allowing XQuery functions to act as endpoints for RESTful services. It also includes some simple functions to assist with the creation of such services. The RestXQ specification can be found at [EXQuery].

E.3 The FunctX Library

Many useful functions can be written in XSLT or XQuery, and in this case the function implementations themselves can be portable across different XSLT and XQuery processors. This section describes one such library.

FunctX is an open-source library of general-purpose functions, supplied in the form of XQuery 1.0 and XSLT 2.0 implementations. It contains over a hundred functions. Typical examples of these functions are:

Test whether a string is all-whitespace
Trim leading and trailing whitespace
Test whether all the values in a sequence are distinct
Capitalize the first character of a string
Change the namespace of all elements in a tree
Get the number of days in a given month
Get the first or last day in a given month
Get the date of the preceding or following day
Ask whether an element has element-only, mixed, or simple content
Find the position of a node in a sequence
Count words in a string

The FunctX library can be found at [FunctX].

F Checklist of implementation-defined features (Non-Normative)

  1. It is ·implementation-defined· which version of Unicode is supported, but it is recommended that the most recent version of Unicode be used. (See Conformance.)

  2. It is ·implementation-defined· whether the type system is based on XML Schema 1.0 or XML Schema 1.1. (See Conformance.)

  3. It is ·implementation-defined· whether definitions that rely on XML (for example, the set of valid XML characters) should use the definitions in XML 1.0 or XML 1.1. (See Conformance.)

  4. 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. (See Options.)

  5. It is ·implementation-defined· which version of [The Unicode Standard] is supported, but it is recommended that the most recent version of Unicode be used. (See Strings, characters, and codepoints.)

  6. [Definition] Some functions (such as fn:distinct-values, fn:unordered, map:keys, and map:for-each) produce results in an ·implementation-defined· or ·implementation-dependent· order. In such cases two calls with the same arguments are not guaranteed to produce the results in the same order. These functions are said to be nondeterministic with respect to ordering. (See .)

  7. Where the results of a function are described as being (to a greater or lesser extent) ·implementation-defined· or ·implementation-dependent·, this does not by itself remove the requirement that the results should be deterministic: that is, that repeated calls with the same explicit and implicit arguments must return identical results. (See Properties of functions.)

  8. In addition, the values of $input, typically serialized and converted to an xs:string, and $label (if supplied and non-empty) may be output to an ·implementation-defined· destination. (See fn:trace.)

  9. Consider a situation in which a user wants to investigate the actual value passed to a function. Assume that in a particular execution, $v is an xs:decimal with value 124.84. Writing fn:trace($v, 'the value of $v is:') will return $v. The processor may output "124.84" and "the value of $v is:" to an ·implementation-defined· destination. (See fn:trace.)

  10. Similar to fn:trace, the values of $input, typically serialized and converted to an xs:string, and $label (if supplied and non-empty) may be output to an ·implementation-defined· destination. (See fn:message.)

  11. They may provide an ·implementation-defined· mechanism that allows users to choose between raising an error and returning a result that is modulo the largest representable integer value. See [ISO 10967]. (See Arithmetic operators on numeric values.)

  12. For xs:decimal values, let N be the number of digits of precision supported by the implementation, and let M (M <= N) be the minimum limit on the number of digits required for conformance (18 digits for XSD 1.0, 16 digits for XSD 1.1). Then for addition, subtraction, and multiplication operations, the returned result should be accurate to N digits of precision, and for division and modulus operations, the returned result should be accurate to at least M digits of precision. The actual precision is ·implementation-defined·. If the number of digits in the mathematical result exceeds the number of digits that the implementation retains for that operation, the result is truncated or rounded in an ·implementation-defined· manner. (See Arithmetic operators on numeric values.)

  13. 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. (See Arithmetic operators on numeric values.)

  14. 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. (See Arithmetic operators on numeric values.)

  15. The implementation may adopt a different algorithm provided that it is equivalent to this formulation in all cases where ·implementation-dependent· or ·implementation-defined· behavior does not affect the outcome, for example, the implementation-defined precision of the result of xs:decimal division. (See op:numeric-integer-divide.)

  16. XSD 1.1 allows the string +INF as a representation of positive infinity; XSD 1.0 does not. It is ·implementation-defined· whether XSD 1.1 is supported. (See fn:number.)

  17. Any other format token, which indicates a numbering sequence in which that token represents the number 1 (one) (but see the note below). It is ·implementation-defined· which numbering sequences, additional to those listed above, are supported. If an implementation does not support a numbering sequence represented by the given token, it must use a format token of 1. (See fn:format-integer.)

  18. 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. (See fn:format-integer.)

  19. The set of languages for which numbering is supported is ·implementation-defined·. If the $language argument is absent, or is set to an empty sequence, or is invalid, or is not a language supported by the implementation, then the number is formatted using the default language from the dynamic context. (See fn:format-integer.)

  20. ...either a or t, to indicate alphabetic or traditional numbering respectively, the default being ·implementation-defined·. (See fn:format-integer.)

  21. The string of characters between the parentheses, if present, is used to select between other possible variations of cardinal or ordinal numbering sequences. The interpretation of this string is ·implementation-defined·. No error occurs if the implementation does not define any interpretation for the defined string. (See fn:format-integer.)

  22. It is ·implementation-defined· what combinations of values of the format token, the language, and the cardinal/ordinal modifier are supported. If ordinal numbering is not supported for the combination of the format token, the language, and the string appearing in parentheses, the request is ignored and cardinal numbers are generated instead. (See fn:format-integer.)

  23. The use of the a or t modifier disambiguates between numbering sequences that use letters. In many languages there are two commonly used numbering sequences that use letters. One numbering sequence assigns numeric values to letters in alphabetic sequence, and the other assigns numeric values to each letter in some other manner traditional in that language. In English, these would correspond to the numbering sequences specified by the format tokens a and i. In some languages, the first member of each sequence is the same, and so the format token alone would be ambiguous. In the absence of the a or t modifier, the default is ·implementation-defined·. (See fn:format-integer.)

  24. The static context provides a set of decimal formats. One of the decimal formats is unnamed, the others (if any) are identified by a QName. There is always an unnamed decimal format available, but its contents are ·implementation-defined·. (See Defining a decimal format.)

  25. IEEE states that the preferred quantum is language-defined. In this specification, it is ·implementation-defined·. (See Trigonometric and exponential functions.)

  26. IEEE defines various rounding algorithms for inexact results, and states that the choice of rounding direction, and the mechanisms for influencing this choice, are language-defined. In this specification, the rounding direction and any mechanisms for influencing it are ·implementation-defined·. (See Trigonometric and exponential functions.)

  27. 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. (See fn:random-number-generator.)

  28. If two query parameters use the same keyword then the last one wins. If a query parameter uses a keyword or value which is not defined in this specification then the meaning is ·implementation-defined·. If the implementation recognizes the meaning of the keyword and value then it should interpret it accordingly; if it does not recognize the keyword or value then if the fallback parameter is present with the value no it should reject the collation as unsupported, otherwise it should ignore the unrecognized parameter. (See The Unicode Collation Algorithm.)

  29. The following query parameters are defined. If any parameter is absent, the default is ·implementation-defined· except where otherwise stated. The meaning given for each parameter is non-normative; the normative specification is found in [UTS #35]. (See The Unicode Collation Algorithm.)

  30. Because the set of collations that are supported is ·implementation-defined·, an implementation has the option to support all collation URIs, in which case it will never raise this error. (See Choosing a collation.)

  31. 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. (See fn:collation.)

  32. It is possible to define collations that do not have the ability to generate collation keys. Supplying such a collation will cause the function to fail. The ability to generate collation keys is an ·implementation-defined· property of the collation. (See fn:collation-key.)

  33. Conforming implementations must support normalization form NFC and may support normalization forms NFD, NFKC, NFKD, and FULLY-NORMALIZED. They may also support other normalization forms with ·implementation-defined· semantics. (See fn:normalize-unicode.)

  34. It is ·implementation-defined· which version of Unicode (and therefore, of the normalization algorithms and their underlying data) is supported by the implementation. See [UAX #15] for details of the stability policy regarding changes to the normalization rules in future versions of Unicode. If the input string contains codepoints that are unassigned in the relevant version of Unicode, or for which no normalization rules are defined, the fn:normalize-unicode function leaves such codepoints unchanged. If the implementation supports the requested normalization form then it must be able to handle every input string without raising an error. (See fn:normalize-unicode.)

  35. It is possible to define collations that do not have the ability to decompose a string into units suitable for substring matching. An argument to a function defined in this section may be a URI that identifies a collation that is able to compare two strings, but that does not have the capability to split the string into collation units. Such a collation may cause the function to fail, or to give unexpected results, or it may be rejected as an unsuitable argument. The ability to decompose strings into collation units is an ·implementation-defined· property of the collation. (See Functions based on substring matching.)

  36. The result of the function will always be such that validation against this schema would succeed. However, it is ·implementation-defined· whether the result is typed or untyped, that is, whether the elements and attributes in the returned tree have type annotations that reflect the result of validating against this schema. (See fn:analyze-string.)

  37. 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. (See Parsing and building URIs.)

  38. If the omit-default-ports option is true, the port is discarded and set to the empty sequence if the port number is the same as the default port for the given scheme. Implementations should recognize the default ports for http (80), https (443), ftp (21), and ssh (22). Exactly which ports are recognized is ·implementation-defined·. (See fn:parse-uri.)

  39. If the omit-default-ports option is true then the $port is set to the empty sequence if the port number is the same as the default port for the given scheme. Implementations should recognize the default ports for http (80), https (443), ftp (21), and ssh (22). Exactly which ports are recognized is ·implementation-defined·. (See fn:build-uri.)

  40. Processors may support a greater range and/or precision. The limits are ·implementation-defined·. (See Limits and precision.)

  41. 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·. (See Limits and precision.)

  42. 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·. (See Limits and precision.)

  43. 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·. (See Limits and precision.)

  44. ...the format token n, N, or Nn, indicating that the value of the component is to be output by name, in lower-case, upper-case, or title-case respectively. Components that can be output by name include (but are not limited to) months, days of the week, timezones, and eras. If the processor cannot output these components by name for the chosen calendar and language then it must use an ·implementation-defined· fallback representation. (See The picture string.)

  45. ...indicates alphabetic or traditional numbering respectively, the default being ·implementation-defined·. This has the same meaning as in the second argument of fn:format-integer. (See The picture string.)

  46. The sequence of characters in the (adjusted) first presentation modifier is reversed (for example, 999'### becomes ###'999). If the result is not a valid decimal digit pattern, then the output is ·implementation-defined·. (See Formatting Fractional Seconds.)

  47. The output for these components is entirely ·implementation-defined·. The default presentation modifier for these components is n, indicating that they are output as names (or conventional abbreviations), and the chosen names will in many cases depend on the chosen language: see 9.8.4.8 The language, calendar, and place arguments. (See Formatting Other Components.)

  48. The set of languages, calendars, and places that are supported in the ·date formatting functions· is ·implementation-defined·. When any of these arguments is omitted or is an empty sequence, an ·implementation-defined· default value is used. (See The language, calendar, and place arguments.)

  49. The choice of the names and abbreviations used in any given language is ·implementation-defined·. For example, one implementation might abbreviate July as Jul while another uses Jly. In German, one implementation might represent Saturday as Samstag while another uses Sonnabend. Implementations may provide mechanisms allowing users to control such choices. (See The language, calendar, and place arguments.)

  50. The choice of the names and abbreviations used in any given language for calendar units such as days of the week and months of the year is ·implementation-defined·. (See The language, calendar, and place arguments.)

  51. The calendar value if present must be a valid EQName (dynamic error: [err:FOFD1340]). If it is a lexical QName then it is expanded into an expanded QName using the statically known namespaces; if it has no prefix then it represents an expanded-QName in no namespace. If the expanded QName is in no namespace, then it must identify a calendar with a designator specified below (dynamic error: [err:FOFD1340]). If the expanded QName is in a namespace then it identifies the calendar in an ·implementation-defined· way. (See The language, calendar, and place arguments.)

  52. At least one of the above calendars must be supported. It is ·implementation-defined· which calendars are supported. (See The language, calendar, and place arguments.)

  53. The requirement to deliver a deterministic result has performance implications, and for this reason implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is ·implementation-defined·. If the user has not selected such an option, a call of the function must either return a deterministic result or must raise a dynamic error [err:FODC0003]. (See fn:doc.)

  54. Various aspects of this processing are ·implementation-defined·. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:... (See fn:doc.)

  55. It is ·implementation-defined· whether DTD validation and/or schema validation is applied to the source document. (See fn:doc.)

  56. The effect of a fragment identifier in the supplied URI is ·implementation-defined·. One possible interpretation is to treat the fragment identifier as an ID attribute value, and to return a document node having the element with the selected ID value as its only child. (See fn:doc.)

  57. By default, this function is ·deterministic·. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is ·implementation-defined·. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error [err:FODC0003]. (See fn:collection.)

  58. By default, this function is ·deterministic·. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is ·implementation-defined·. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error [err:FODC0003]. (See fn:uri-collection.)

  59. ...the processor may use ·implementation-defined· heuristics to determine the likely encoding, otherwise... (See fn:unparsed-text.)

  60. The fact that the resolution of URIs is defined by a mapping in the dynamic context means that in effect, various aspects of the behavior of this function are ·implementation-defined·. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:... (See fn:unparsed-text.)

  61. The collation used for matching names is ·implementation-defined·, but must be the same as the collation used to ensure that the names of all environment variables are unique. (See fn:environment-variable.)

  62. Except to the extent defined by these options, the precise process used to construct the XDM instance is ·implementation-defined·. In particular, it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used. (See fn:parse-xml.)

  63. Except as explicitly defined, the precise process used to construct the XDM instance is ·implementation-defined·. In particular, it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used. (See fn:parse-xml-fragment.)

  64. If the second argument is omitted, or is supplied in the form of an output:serialization-parameters element, then the values of any serialization parameters that are not explicitly specified is ·implementation-defined·, and may depend on the context. (See fn:serialize.)

  65. Because the [DOM: Living Standard] and [HTML: Living Standard] are not fixed, it is ·implementation-defined· which versions are used. (See XDM Mapping from HTML DOM Nodes.)

  66. If an implementation allows these nodes to be passed in via an API or similar mechanism, their behaviour is ·implementation-defined·. (See XDM Mapping from HTML DOM Nodes.)

  67. If the local name contains a character that is not a valid XML NameStartChar or NameChar, then an ·implementation-defined· replacement string is used. The result must be a valid NCName. (See node-name Accessor.)

  68. If the local name contains a character that is not a valid XML NameStartChar or NameChar, then an ·implementation-defined· replacement string is used. The result must be a valid NCName. (See node-name Accessor.)

  69. Additional ·implementation-defined· parser options are allowed. (See HTML parser options.)

  70. Any other method and html-version combinations are ·implementation-defined·. (See fn:parse-html.)

  71. The default behaviour is ·implementation-defined·. (See fn:parse-html.)

  72. An ·implementation-defined· parsing algorithm, tree construction, and validation consistent with the specified HTML version. (See fn:parse-html.)

  73. The input may contain deviations from the grammar of [RFC 7159], which are handled in an ·implementation-defined· way. (Note: some popular extensions include allowing quotes on keys to be omitted, allowing a comma to appear after the last item in an array, allowing leading zeroes in numbers, and allowing control characters such as tab and newline to be present in unescaped form.) Since the extensions accepted are implementation-defined, an error may be raised [err:FOJS0001] if the input does not conform to the grammar. (See fn:parse-json.)

  74. The supplied function is called to process the string value of any JSON number in the input. By default, numbers are processed by converting to xs:double using the XPath casting rules. Supplying the value xs:decimal#1 will instead convert to xs:decimal (which potentially retains more precision, but disallows exponential notation), while supplying a function that casts to (xs:decimal | xs:double) will treat the value as xs:decimal if there is no exponent, or as xs:double otherwise. Supplying the value fn:identity#1 causes the value to be retained unchanged as an xs:untypedAtomic. If the liberal option is false (the default), then the supplied number-parser is called if and only if the value conforms to the JSON grammar for numbers (for example, a leading plus sign and redundant leading zeroes are not allowed). If the liberal option is true then it is also called if the value conforms to an ·implementation-defined· extension of this grammar. (See fn:parse-json.)

  75. The input may contain deviations from the grammar of [RFC 7159], which are handled in an ·implementation-defined· way. (Note: some popular extensions include allowing quotes on keys to be omitted, allowing a comma to appear after the last item in an array, allowing leading zeroes in numbers, and allowing control characters such as tab and newline to be present in unescaped form.) Since the extensions accepted are implementation-defined, an error may be raised (see below) if the input does not conform to the grammar. (See fn:json-to-xml.)

  76. Default: ·Implementation-defined·. (See fn:json-to-xml.)

  77. Indicates that the resulting XDM instance must be typed; that is, the element and attribute nodes must carry the type annotations that result from validation against the schema given at C.2 Schema for the result of fn:json-to-xml, or against an ·implementation-defined· schema if the liberal option has the value true. (See fn:json-to-xml.)

  78. The result of the function will always be such that validation against this schema would succeed. However, it is ·implementation-defined· whether the result is typed or untyped, that is, whether the elements and attributes in the returned tree have type annotations that reflect the result of validating against this schema. (See fn:csv-to-xml.)

  79. Additional, ·implementation-defined· options may be available, for example, to control aspects of the XML serialization, to specify the grammar start symbol, or to produce output formats other than XML. (See fn:invisible-xml.)

  80. If the arguments to fn:function-lookup identify a function that is present in the static context of the function call, the function will always return the same function that a static reference to this function would bind to. If there is no such function in the static context, then the results depend on what is present in the dynamic context, which is ·implementation-defined·. (See fn:function-lookup.)

  81. Default: The version given in the prolog of the library module; or ·implementation-defined· if this is absent. (See fn:load-xquery-module.)

  82. A sequence of URIs (in the form of xs:string values) which may be used or ignored in an ·implementation-defined· way.... (See fn:load-xquery-module.)

  83. Values for vendor-defined configuration options for the XQuery processor used to process the request. The key is the name of an option, expressed as a QName: the namespace URI of the QName should be a URI controlled by the vendor of the XQuery processor. The meaning of the associated value is ·implementation-defined·. Implementations should ignore options whose names are in an unrecognized namespace. The ·option parameter conventions· do not apply to this contained map.... (See fn:load-xquery-module.)

  84. It is ·implementation-defined· whether constructs in the library module are evaluated in the same ·execution scope· as the calling module. (See fn:load-xquery-module.)

  85. The library module that is loaded may import schema declarations using an import schema declaration. It is ·implementation-defined· whether schema components in the in-scope schema definitions of the calling module are automatically added to the in-scope schema definitions of the dynamically loaded module. The in-scope schema definitions of the calling and called modules must be consistent, according to the rules defined in Section 2.2.5 Consistency Constraints XQ31. (See fn:load-xquery-module.)

  86. Default: ·Implementation-defined·. (See fn:transform.)

  87. Default: ·Implementation-defined·. (See fn:transform.)

  88. If the implementation provides a way of writing or invoking functions with side-effects, this post-processing function might be used to save a copy of the result document to persistent storage. For example, if the implementation provides access to the EXPath File library [EXPath], then a serialized document might be written to filestore by calling the file:write function. Similar mechanisms might be used to issue an HTTP POST request that posts the result to an HTTP server, or to send the document to an email recipient. The semantics of calling functions with side-effects are entirely ·implementation-defined·. (See fn:transform.)

  89. Calls to fn:transform can potentially have side-effects even in the absence of the post-processing option, because the XSLT specification allows a stylesheet to invoke extension functions that have side-effects. The semantics in this case are ·implementation-defined·. (See fn:transform.)

  90. A string intended to be used as the static base URI of the principal stylesheet module. This value must be used if no other static base URI is available. If the supplied stylesheet already has a base URI (which will generally be the case if the stylesheet is supplied using stylesheet-node or stylesheet-location) then it is ·implementation-defined· whether this parameter has any effect. If the value is a relative reference, it is resolved against the static base URI of the fn:transform function call.... (See fn:transform.)

  91. Values for vendor-defined configuration options for the XSLT processor used to process the request. The key is the name of an option, expressed as a QName: the namespace URI of the QName should be a URI controlled by the vendor of the XSLT processor. The meaning of the associated value is ·implementation-defined·. Implementations should ignore options whose names are in an unrecognized namespace. Default is an empty map.... (See fn:transform.)

  92. It is ·implementation-defined· whether the XSLT transformation is executed within the same ·execution scope· as the calling code. (See fn:transform.)

  93. XSLT 1.0 does not define any error codes, so this is the likely outcome with an XSLT 1.0 processor. XSLT 2.0 and 3.0 do define error codes, but some APIs do not expose them. If multiple errors are signaled by the transformation (which is most likely to happen with static errors) then the error code should where possible be that of one of these errors, chosen arbitrarily; the processor may make details of additional errors available to the application in an ·implementation-defined· way. (See fn:transform.)

  94. If ST is xs:float or xs:double, then TV is the xs:decimal value, within the set of xs:decimal values that the implementation is capable of representing, that is numerically closest to SV. If two values are equally close, then the one that is closest to zero is chosen. If SV is too large to be accommodated as an xs:decimal, (see [XML Schema Part 2: Datatypes Second Edition] for ·implementation-defined· limits on numeric values) a dynamic error is raised [err:FOCA0001]. If SV is one of the special xs:float or xs:double values NaN, INF, or -INF, a dynamic error is raised [err:FOCA0002]. (See Casting to xs:decimal.)

  95. In casting to xs:decimal or to a type derived from xs:decimal, if the value is not too large or too small but nevertheless cannot be represented accurately with the number of decimal digits available to the implementation, the implementation may round to the nearest representable value or may raise a dynamic error [err:FOCA0006]. The choice of rounding algorithm and the choice between rounding and error behavior is ·implementation-defined·. (See Casting from xs:string and xs:untypedAtomic.)

  96. If ST is xs:decimal, xs:float or xs:double, then TV is SV with the fractional part discarded and the value converted to xs:integer. Thus, casting 3.1456 returns 3 while -17.89 returns -17. Casting 3.124E1 returns 31. If SV is too large to be accommodated as an integer, (see [XML Schema Part 2: Datatypes Second Edition] for ·implementation-defined· limits on numeric values) a dynamic error is raised [err:FOCA0003]. If SV is one of the special xs:float or xs:double values NaN, INF, or -INF, a dynamic error is raised [err:FOCA0002]. (See Casting to xs:integer.)

  97. The tz timezone database, available at http://www.iana.org/time-zones. It is ·implementation-defined· which version of the database is used. (See IANA Timezone Database.)

  98. Unicode Standard Annex #15: Unicode Normalization Forms. Ed. Mark Davis and Ken Whistler, Unicode Consortium. The current version is 9.0.0, dated 2016-02-24. As with [The Unicode Standard], the version to be used is ·implementation-defined·. Available at: http://www.unicode.org/reports/tr15/. (See UAX #15.)

  99. Unicode Standard Annex #29: Unicode Text Segmentation. Ed. Josh Hadley, Unicode Consortium. The current version is 15.1.0, dated 2023-08-16. As with [The Unicode Standard], the version to be used is ·implementation-defined·. Available at: http://www.unicode.org/reports/tr29/. (See UAX #29.)

  100. The Unicode Consortium, Reading, MA, Addison-Wesley, 2016. The Unicode Standard as updated from time to time by the publication of new versions. See http://www.unicode.org/standard/versions/ for the latest version and additional information on versions of the standard and of the Unicode Character Database. The version of Unicode to be used is ·implementation-defined·, but implementations are recommended to use the latest Unicode version; currently, Version 9.0.0. (See The Unicode Standard.)

  101. Unicode Technical Standard #10: Unicode Collation Algorithm. Ed. Mark Davis and Ken Whistler, Unicode Consortium. The current version is 9.0.0, dated 2016-05-18. As with [The Unicode Standard], the version to be used is ·implementation-defined·. Available at: http://www.unicode.org/reports/tr10/. (See UTS #10.)

  102. Unicode Technical Standard #35: Unicode Locale Data Markup Language. Ed Mark Davis et al, Unicode Consortium. The current version is 29, dated 2016-03-15. As with [The Unicode Standard], the version to be used is ·implementation-defined·. Available at: http://www.unicode.org/reports/tr35/. (See UTS #35.)

G Changes since version 3.1 (Non-Normative)

G.1 Summary of Changes

  1. Use the arrows to browse significant changes since the 3.1 version of this specification.

    See 1 Introduction

  2. Sections with significant changes are marked Δ in the table of contents. New functions introduced in this version are marked ➕ in the table of contents.

    See 1 Introduction

  3. PR 629 803 

    New in 4.0

    See 3.2.2 fn:message

  4. PR 1260 1275 

    A third argument has been added, providing control over the rounding mode.

    See 4.4.4 fn:round

  5. New in 4.0

    See 4.4.6 fn:is-NaN

  6. 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.

    See 4.7.2 fn:format-number

  7. PR 1049 1151 

    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.

    See 4.7.2 fn:format-number

  8. PR 1205 1230 

    New in 4.0

    See 4.8.2 math:e

    See 4.8.16 math:sinh

    See 4.8.17 math:cosh

    See 4.8.18 math:tanh

  9. 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).

    See 4.9.1 fn:random-number-generator

  10. PR 261 306 993 

    New in 4.0

    See 5.4.1 fn:char

  11. New in 4.0

    See 5.4.2 fn:characters

  12. PR 937 995 1190 

    New in 4.0

    See 5.4.13 fn:hash

  13. The $action argument is new in 4.0.

    See 5.6.4 fn:replace

  14. New in 4.0

    See 6.6.1 fn:parse-uri

  15. PR 1423 1413 

    New in 4.0

    See 6.6.2 fn:build-uri

  16. New in 4.0

    See 10.2.6 fn:in-scope-namespaces

  17. Reformulated in 4.0 in terms of the new fn:in-scope-namespaces function; the semantics are unchanged.

    See 10.2.7 fn:in-scope-prefixes

  18. Reformulated in 4.0 in terms of the new fn:in-scope-namespaces function; the semantics are unchanged.

    See 10.2.8 fn:namespace-uri-for-prefix

  19. New in 4.0

    See 13.1.5 fn:identity

  20. New in 4.0

    See 13.1.10 fn:replicate

  21. New in 4.0

    See 13.1.12 fn:slice

  22. New in 4.0. The function is identical to the internal op:same-key function in 3.1

    See 13.2.1 fn:atomic-equal

  23. PR 1120 1150 

    A callback function can be supplied for comparing individual items.

    See 13.2.2 fn:deep-equal

  24. The function has been expanded in scope to handle comparison of values other than strings.

    See 13.2.3 fn:compare

  25. Changed in 4.0 to use transitive equality comparisons for numeric values.

    See 13.2.4 fn:distinct-values

  26. New in 4.0

    See 13.2.5 fn:duplicate-values

  27. New in 4.0. Originally proposed under the name fn:uniform

    See 13.4.6 fn:all-equal

  28. New in 4.0. Originally proposed under the name fn:unique

    See 13.4.7 fn:all-different

  29. PR 1117 1279 

    The $options parameter has been added.

    See 13.6.6 fn:unparsed-text-lines

  30. A new function is available for processing input data in HTML format.

    See 14.2 Functions on HTML Data

  31. PR 975 1058 1246 

    An option is provided to control how JSON numbers should be formatted.

    See 14.3.3 fn:parse-json

  32. Additional options are available, as defined by fn:parse-json.

    See 14.3.4 fn:json-doc

  33. PR 533 719 834 1066 

    New in 4.0

    See 14.4.4 fn:csv-to-arrays

    See 14.4.6 fn:parse-csv

    See 14.4.8 fn:csv-to-xml

  34. PR 791 1256 1282 1405 

    New in 4.0

    See 14.5.1 fn:invisible-xml

  35. New in 4.0

    See 16.2.4 fn:every

  36. New in 4.0

    See 16.2.10 fn:highest

  37. New in 4.0

    See 16.2.11 fn:index-where

  38. New in 4.0

    See 16.2.12 fn:lowest

  39. New in 4.0

    See 16.2.15 fn:scan-right

  40. New in 4.0

    See 16.2.16 fn:some

  41. New in 4.0

    See 17.3.6 map:filter

  42. PR 478 515 

    New in 4.0

    See 17.3.11 map:keys-where

  43. New in 4.0

    See 17.3.13 map:of-pairs

  44. New in 4.0

    See 17.3.14 map:pair

  45. New in 4.0

    See 17.3.15 map:pairs

  46. New in 4.0

    See 17.3.18 map:replace

  47. New in 4.0

    See 17.3.20 map:values

  48. New in 4.0

    See 18.2.3 array:empty

  49. A third argument is added, allowing user control of how index-out-of-bounds conditions should be handled.

    See 18.2.11 array:get

  50. PR 968 1295 

    New in 4.0

    See 18.2.13 array:index-of

  51. New in 4.0

    See 18.2.17 array:members

    See 18.2.18 array:of-members

  52. New in 4.0

    See 18.2.21 array:replace

  53. New in 4.0

    See 18.2.24 array:slice

  54. New in 4.0

    See 18.2.25 array:sort

  55. New in 4.0

    See 18.2.26 array:split

  56. Supplying an empty sequence as the value of an optional argument is equivalent to omitting the argument.

    See 18.2.27 array:subarray

  57. PR 476 1087 

    New in 4.0

    See 18.2.30 array:values

  58. New in 4.0

    See 13.1.7 fn:intersperse

  59. New in 4.0

    See 18.2.2 array:build

  60. New in 4.0

    See 18.2.14 array:index-where

  61. PR 533 719 834 

    New functions are available for processing input data in CSV (comma separated values) format.

    See 14.4 Functions on CSV Data

  62. PR 734 1233 

    New in 4.0

    See 16.2.2 fn:chain

  63. New in 4.0

    See 9.3.2 fn:unix-dateTime

  64. The function has been extended to handle other Gregorian types such as xs:gYearMonth.

    See 9.5.1 fn:year-from-dateTime

    See 9.5.2 fn:month-from-dateTime

    The function has been extended to handle other Gregorian types such as xs:gMonthDay.

    See 9.5.3 fn:day-from-dateTime

    The function has been extended to handle other types including xs:time.

    See 9.5.4 fn:hours-from-dateTime

    See 9.5.5 fn:minutes-from-dateTime

    The function has been extended to handle other types such as xs:gYearMonth.

    See 9.5.7 fn:timezone-from-dateTime

  65. PR 173 

    New in 4.0

    See 16.3.3 fn:op

  66. PR 203 

    New in 4.0

    See 17.3.1 map:build

  67. PR 207 

    New in 4.0

    See 10.1.2 fn:parse-QName

    See 10.2.5 fn:expanded-QName

  68. PR 222 

    New in 4.0

    See 13.2.7 fn:starts-with-subsequence

    See 13.2.8 fn:ends-with-subsequence

    See 13.2.9 fn:contains-subsequence

  69. PR 250 

    New in 4.0

    See 13.1.3 fn:foot

    See 13.1.15 fn:trunk

    See 18.2.8 array:foot

    See 18.2.29 array:trunk

  70. PR 313 

    The second argument can now be a sequence of integers.

    See 13.1.9 fn:remove

  71. PR 314 

    New in 4.0

    See 17.3.4 map:entries

  72. PR 326 

    Higher-order functions are no longer an optional feature.

    See 1.2 Conformance

  73. PR 419 

    New in 4.0

    See 13.1.8 fn:items-at

  74. PR 434 

    New in 4.0

    See 4.5.2 fn:parse-integer

    The function has been extended to allow output in a radix other than 10, for example in hexadecimal.

    See 4.6.1 fn:format-integer

  75. PR 482 

    Deleted an inaccurate statement concerning the behavior of NaN.

    See 4.3 Comparison operators on numeric values

  76. PR 507 

    New in 4.0

    See 16.2.13 fn:partition

  77. PR 623 

    Substantially revised to allow multiple sort key definitions.

    See 16.2.17 fn:sort

  78. PR 631 

    New in 4.0

    See 6.3 fn:decode-from-uri

  79. PR 662 

    Constructor functions now have a zero-arity form; the first argument defaults to the context item.

    See 19 Constructor functions

  80. PR 702 

    The function can now take any number of arguments (previously it had to be two or more), and the arguments can sequences of strings rather than single strings.

    See 5.4.4 fn:concat

  81. PR 710 

    Changes the function to return a sequence of key-value pairs rather than a map.

    See 16.1.4 fn:function-annotations

  82. PR 727 

    It has been clarified that loading a module has no effect on the static or dynamic context of the caller.

    See 16.3.1 fn:load-xquery-module

  83. PR 761 

    New in 4.0

    See 16.2.21 fn:transitive-closure

  84. PR 795 

    New in 4.0

    See 16.2.18 fn:sort-with

  85. PR 828 

    The $predicate callback function accepts an optional position argument.

    See 16.2.5 fn:filter

    See 16.2.6 fn:fold-left

    The $action callback function accepts an optional position argument.

    See 16.2.7 fn:fold-right

    See 16.2.8 fn:for-each

    See 16.2.9 fn:for-each-pair

    The $predicate callback function now accepts an optional position argument.

    See 18.2.4 array:filter

    The $action callback function now accepts an optional position argument.

    See 18.2.6 array:fold-left

    See 18.2.7 array:fold-right

    See 18.2.9 array:for-each

    See 18.2.10 array:for-each-pair

  86. PR 901 

    All three arguments are now optional, and each argument can be set to an empty sequence. Previously if $description was supplied, it could not be empty.

    See 3.1.1 fn:error

    The $label argument can now be set to an empty sequence. Previously if $label was supplied, it could not be empty.

    See 3.2.1 fn:trace

    The third argument can now be supplied as an empty sequence.

    See 5.4.6 fn:substring

    The second argument can now be an empty sequence.

    See 5.6.5 fn:tokenize

    The optional second argument can now be supplied as an empty sequence.

    See 6.1 fn:resolve-uri

    The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.

    See 9.8.1 fn:format-dateTime

    See 9.8.2 fn:format-date

    See 9.8.3 fn:format-time

    The optional third argument can now be supplied as an empty sequence.

    See 13.1.13 fn:subsequence

  87. PR 940 

    New in 4.0

    See 16.2.19 fn:subsequence-where

  88. PR 956 

    New in 4.0

    See 14.2.3 fn:parse-html

  89. PR 962 

    New in 4.0

    See 16.2.3 fn:do-until

    See 16.2.22 fn:while-do

  90. PR 969 

    New in 4.0

    See 17.3.3 map:empty

  91. PR 984 

    New in 4.0

    See 8.4.1 fn:seconds

  92. PR 987 

    The order of results is now prescribed; it was previously implementation-dependent.

    See 13.2.4 fn:distinct-values

    See 13.2.5 fn:duplicate-values

  93. PR 988 

    New in 4.0

    See 14.3.7 fn:pin

    See 14.3.8 fn:label

  94. PR 1028 

    An option is provided to control how the JSON null value should be handled.

    See 14.3.3 fn:parse-json

  95. PR 1032 

    New in 4.0

    See 13.1.17 fn:void

  96. PR 1046 

    New in 4.0

    See 16.2.20 fn:take-while

  97. PR 1059 

    Use of an option keyword that is not defined in the specification and is not known to the implementation now results in a dynamic error; previously it was ignored.

    See 1.7 Options

  98. PR 1068 

    New in 4.0

    See 5.4.3 fn:graphemes

  99. PR 1072 

    The return type is now specified more precisely.

    See 16.3.1 fn:load-xquery-module

  100. PR 1074 

    New in 4.0

    See 3.2.3 fn:stack-trace

  101. PR 1090 

    When casting from a string to a duration or time or dateTime, it is now specified that when there are more digits in the fractional seconds than the implementation is able to retain, excess digits are truncated. Rounding upwards (which could affect the number of minutes or hours in the value) is not permitted.

    See 20.2 Casting from xs:string and xs:untypedAtomic

  102. PR 1093 

    New in 4.0

    See 5.3.7 fn:collation

  103. PR 1117 

    The $options parameter has been added.

    See 13.6.5 fn:unparsed-text

    See 13.6.7 fn:unparsed-text-available

  104. PR 1182 

    The $predicate callback function may return an empty sequence (meaning false).

    See 16.2.3 fn:do-until

    See 16.2.4 fn:every

    See 16.2.5 fn:filter

    See 16.2.6 fn:fold-left

    See 16.2.11 fn:index-where

    See 16.2.16 fn:some

    See 16.2.20 fn:take-while

    See 16.2.22 fn:while-do

    See 17.3.6 map:filter

    See 17.3.11 map:keys-where

    See 18.2.4 array:filter

    See 18.2.14 array:index-where

  105. PR 1191 

    New in 4.0

    See 2.3.1 fn:distinct-ordered-nodes

    The $options parameter has been added, absorbing the $collation parameter.

    See 13.2.2 fn:deep-equal

  106. PR 1250 

    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.

    See 4.7.2 fn:format-number

  107. PR 1257 

    The $options parameter has been added.

    See 14.1.1 fn:parse-xml

    See 14.1.2 fn:parse-xml-fragment

  108. PR 1262 

    New in 4.0

    See 5.3.8 fn:collation-available

  109. PR 1265 

    The constraints on the result of the function have been relaxed.

    See 2.1.6 fn:document-uri

  110. PR 1280 

    As a result of changes to the coercion rules, the number of supplied arguments can be greater than the number required: extra arguments are ignored.

    See 16.2.1 fn:apply

  111. PR 1288 

    Additional error conditions have been defined.

    See 14.1.1 fn:parse-xml

  112. PR 1296 

    New in 4.0

    See 16.2.14 fn:scan-left

  113. PR 1333 

    A new option is provided to allow the content of the loaded module to be supplied as a string.

    See 16.3.1 fn:load-xquery-module

  114. PR 1353 

    An option has been added to suppress the escaping of the solidus (forwards slash) character.

    See 14.3.6 fn:xml-to-json

  115. PR 1361 

    The term atomic value has been replaced by atomic item.

    See 1.9 Terminology

  116. PR 1393 

    Changes the function to return a sequence of key-value pairs rather than a map.

    See 16.1.4 fn:function-annotations

  117. PR 1409 

    This section now uses the term primitive type strictly to refer to the 20 atomic types that are not derived by restriction from another atomic type: that is, the 19 primitive atomic types defined in XSD, plus xs:untypedAtomic. The three types xs:integer, xs:dayTimeDuration, and xs:yearMonthDuration, which have custom casting rules but are not strictly-speaking primitive, are now handled in other subsections.

    See 20.1 Casting from primitive types to primitive types

    The rules for conversion of dates and times to strings are now defined entirely in terms of XSD 1.1 canonical mappings, since these deliver exactly the same result as the XPath 3.1 rules.

    See 20.1.2.2 Casting date/time values to xs:string

    The rules for conversion of durations to strings are now defined entirely in terms of XSD 1.1 canonical mappings, since the XSD 1.1 rules deliver exactly the same result as the XPath 3.1 rules.

    See 20.1.2.3 Casting xs:duration values to xs:string

  118. PR 1430 

    New in 4.0

    See 13.5.5 fn:element-number

  119. PR 1455 

    Numbers now retain their original lexical form, except for any changes needed to satisfy JSON syntax rules (for example, stripping leading zero digits).

    See 14.3.6 fn:xml-to-json

G.2 Changes to Casts and Constructor Functions

  1. The keyword for the argument has changed from arg to value.

  2. The argument is now optional, and defaults to the context value (which is atomized if necessary). This change aligns constructor functions such as xs:string, xs:boolean, and xs:numeric with fn:string, fn:boolean, and fn:number.

G.3 Miscellaneous Changes

  1. The semantics of the HTML case-insensitive collation "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive" are now defined normatively in this specification rather than by reference to the living HTML5 specification (which has changed since 3.1); and the rules now make ordering explicit rather than leaving it implementation-defined.

  2. An option in an ·option map· is now rejected if it is not described in the specification, if it is not supported by the implementation and if its name is in no namespace.

G.4 Editorial Changes

These changes are not highlighted in the change-marked version of the specification.

  1. The operator mapping table has been simplified so all the value comparison operators are now defined in terms of two functions (for each data type): op:XX-equal, and op:XX-less-than. The entries for op:XX-greater-than have therefore been removed.

  2. The names of parameters appearing in function signatures have been changed. This is to reflect the introduction of keyword arguments in XPath 4.0; the names chosen for parameters are now more consistent across the function library.

    In 3.1 and earlier versions, the keywords used in the specification were for documentation purposes only, so these changes do not affect backwards compatibility.

  3. Where appropriate, the phrase "the value of $x" has been replaced by the simpler $x. No change in meaning is intended.

  4. For functions that take a variable number of arguments, wherever possible the specification now gives a single function signature indicating default values for arguments that may be omitted, rather than multiple signatures.

  5. The formal specifications of array functions have been rewritten to use two new primitives: array:members which converts an array to a sequence of value records, and array:of-members which does the inverse. This has enabled many of the functions to be specified more concisely, and with less duplication between similar functions for sequences and arrays.

  6. The appendix containing illustrative user-written functions has been dropped; many of these functions are no longer needed.

H Compatibility with Previous Versions (Non-Normative)

This section summarizes the extent to which this specification is compatible with previous versions.

Version 4.0 of this function library is fully backwards compatible with version 3.1, except as noted below:

  1. In fn:deep-equal, and in other functions such as fn:distinct-values that refer to fn:deep-equal, the rules for comparing values of different numeric types (for example, xs:double and xs:decimal) have changed. In previous versions of the specification, xs:decimal values were converted to xs:double, leading to a possible loss of precision. This could make comparisons non-transitive, leading to problems when grouping, and potentially (depending on the sort algorithm) with sorting. The problem has been fixed by requiring comparisons to be performed based on the exact mathematical value without any loss of precision.

    This means, for example, that deep-equal(0.2, 0.2e0) is now false, whereas in previous versions it was true. The two values are not mathematically equal, because the exact decimal equivalent of the xs:double value written as 0.2e0 is 0.200000000000000011102230246251565404236316680908203125.

    The corresponding change has not been made to the = and eq operators, because it was found to be too disruptive. For example, if the context node is the element <e price="10.0" discount="0.2"/>, there is an expectation that the expression @price - @discount = 9.8 should return true. But (assuming untyped data), the result of the subtraction is an xs:double whose precise value is 9.800000000000000710542735760100185871124267578125, so comparing the two values as decimals would return false.

  2. In previous versions, unrecognized options supplied to the $options parameter of functions such as fn:parse-json were silently ignored. In 4.0, they are rejected as a type error, unless they are QNames with a non-absent namespace, or are extensions recognized by the implementation.

  3. In version 4.0, omitting the $value of fn:error has the same effect as setting it to an empty sequence. In 3.1, the effects could be different (the effect of omitting the argument was implementation-defined).

  4. In version 3.1, the fn:deep-equal function did not merge adjacent text nodes after stripping comments and processing instructions, so the elements <a>abc<!--note1-->def</code> and <a>abcde<!--note2-->f</code> were considered non-equal. In version 4.0, the text nodes are now merged prior to comparison, so these two elements compare equal.

  5. The format of numeric values in the output of fn:xml-to-json may be different. In version 3.1, the supplied value was parsed as an xs:double and then serialized using the casting rules, resulting in an input value of 10000000 being output as 1e7. In version 4.0, the value is output as is, except for any changes (such as stripping of leading zeroes or a leading plus sign) that might be needed to ensure the result is valid JSON.

  6. In version 4.0, the function signature of fn:namespace-uri-for-prefix constrains the first argument to be either an xs:NCName or a zero-length string (the new coercion rules mean that any string in the form of an xs:NCName is acceptable). If a string is supplied that does not meet these requirements, a type error will be raised. In version 3.1, this was not an error: it came under the rule that when no namespace binding existed for the supplied prefix, the function would return an empty sequence.

    Furthermore, because the expected type of this parameter is no longer xs:string, the special coercion rules for xs:string parameters in XPath 1.0 compatibility mode no longer apply. For example, supplying xs:duration('PT1H') as the first argument will now raise a type error, rather than looking for a namespace binding for the prefix PT1H.

  7. Version 4.0 makes it clear that the casting of a value other than xs:string or xs:untypedAtomic to a list type (whether using a cast expression or a constructor function) is a type error [err:XPTY0004]XP. Previously this was defined as an error, but the kind of error and the error code were left unspecified. Accordingly, the function signatures of the constructor functions for built-in list types have been changed to use an argument type of xs:string?.

  8. The way that fn:min and fn:max compare numeric values of different types has changed. The most noticeable effect is that when these functions are applied to a sequence of xs:integer or xs:decimal values, the result is an xs:integer or xs:decimal, rather than the result of converting this to an xs:double.

  9. The type of the third argument of fn:format-number has changed from xs:string to (xs:string | xs:QName). Because the expected type of this parameter is no longer xs:string, the special coercion rules for xs:string parameters no longer apply. For example, it is no longer possible to supply an instance of xs:anyURI or (when XPath 1.0 compatibility mode is in force) an instance of xs:boolean or xs:duration.

For compatibility issues regarding earlier versions, see the 3.1 version of this specification.