W3C

XPath and XQuery Functions and Operators 3.0

W3C Candidate Recommendation 21 May 2013

This version:
http://www.w3.org/TR/2013/CR-xpath-functions-30-20130521/
Latest version:
http://www.w3.org/TR/xpath-functions-30/
Previous versions:
http://www.w3.org/TR/2013/CR-xpath-functions-30-20130108/ http://www.w3.org/TR/2011/WD-xpath-functions-30-20111213/ http://www.w3.org/TR/2011/WD-xpath-functions-30-20110614/ http://www.w3.org/TR/2010/WD-xpath-functions-30-20101214/ http://www.w3.org/TR/2009/WD-xpath-functions-11-20091215/
Editor:
Michael Kay (XSL WG), Saxonica <http://www.saxonica.com/>

See also translations.

This document is also available in these non-normative formats: XML and Change markings relative to previous Working Draft.


Abstract

Change markings are relative to the Recommendation of 23 January 2007.

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.0]. It also defines functions and operators on nodes and node sequences as defined in the [XQuery and XPath Data Model (XDM) 3.0]. These functions and operators are defined for use in [XML Path Language (XPath) 3.0], [XQuery 3.0: An XML Query Language] and [XSL Transformations (XSLT) Version 3.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/.

This is the third version of the specification of this function library. The first version was included as an intrinsic part of the [XML Path Language (XPath) Version 1.0] specification published on 16 November 1999. The second version was published under the title XQuery 1.0 and XPath 2.0 Functions and Operators on 23 January 2007, subsequently revised in a second edition published on 14 December 2010. This third version is the first to carry its own version number, which has been set at 3.0 to align with the version numbering for XPath, XQuery, and XSLT.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is one document in a set of seven documents that are being progressed to Recommendation together (XQuery 3.0, XQueryX 3.0, XSLT 3.0, Data Model 3.0, Functions and Operators 3.0, Serialization 3.0, XPath 3.0).

W3C publishes a Candidate Recommendation, as described in the Process Document, to indicate that the document is believed to be stable and to encourage implementation by the developer community. The publication of this document constitutes a call for implementations of this specification.

This document was jointly developed by the W3C XML Query Working Group and the W3C XSLT Working Group, each of which is part of the XML Activity. It will remain a Candidate Recommendation until at least 08 April 2013. The Working Groups expect to advance this specification to Recommendation Status.

Once the entrance criteria for Proposed Recommendation have been achieved, the Director will be requested to advance this document to Proposed Recommendation status. Working closely with the developer community, we expect to show evidence of implementations by approximately 31 July 2013.

This updated Candidate Recommendation is being published to allow document reviewers and implementors to see in context all changes that have been made during the CR review period. The most important changes are to the names of the functions formerly named "fn:map" and "fn:map-pairs" (renamed "fn:for-each" and "fn:for-each-pair", respectively), and to the order of arguments for these two functions as well as fn:filter, fn:fold-left, and fn:fold-right. The motivation for the change is partly usability, and partly concern about possible conflicts with features being considered for future releases. A full list of changes since the Candidate Recommendation of 08 January 2013 is at E.4 Substantive changes (post Candidate Recommendation). Please note that this Candidate Recommendation of XPath and XQuery Functions and Operators 3.0 represents the second version of a previous W3C Recommendation.

This specification is designed to be referenced normatively from other specifications defining a host language for it; it is not intended to be implemented outside a host language. The implementability of this specification has been tested in the context of its normative inclusion in host languages defined by the XQuery 3.0 and XSLT 3.0 (expected in 2013) specifications; see the XQuery 3.0 implementation report (and, in the future, the WGs expect that there will also be a — possibly member-only — XSLT 3.0 implementation report) for details.

This document incorporates changes made against the Last Call Working Draft of 13 December 2011. Changes to this document since the Last Call Working Draft are detailed in E Changes since previous Recommendation.

Please report errors in this document using W3C's public Bugzilla system (instructions can be found at http://www.w3.org/XML/2005/04/qt-bugzilla). If access to that system is not feasible, you may send your comments to the W3C XSLT/XPath/XQuery public comments mailing list, public-qt-comments@w3.org. It will be very helpful if you include the string “[FO30]” in the subject line of your report, whether made in Bugzilla or in email. Please use multiple Bugzilla entries (or, if necessary, multiple email messages) if you have more than one comment to make. Archives of the comments and responses are available at http://lists.w3.org/Archives/Public/public-qt-comments/.

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by groups operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the XML Query Working Group and also maintains a public list of any patent disclosures made in connection with the deliverables of the XSL Working Group; those pages also include instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Quick Contents

Table of Contents

1 Introduction
    1.1 Conformance
    1.2 Namespaces and prefixes
    1.3 Function overloading
    1.4 Function signatures and descriptions
    1.5 Type system
    1.6 Terminology
        1.6.1 Strings, characters, and codepoints
        1.6.2 Namespaces and URIs
        1.6.3 Conformance terminology
        1.6.4 Properties of functions
2 Accessors
    2.1 fn:node-name
    2.2 fn:nilled
    2.3 fn:string
    2.4 fn:data
    2.5 fn:base-uri
    2.6 fn:document-uri
3 Errors and diagnostics
    3.1 Raising errors
        3.1.1 fn:error
    3.2 Diagnostic tracing
        3.2.1 fn:trace
4 Functions and operators on numerics
    4.1 Numeric types
    4.2 Arithmetic operators on numeric values
        4.2.1 op:numeric-add
        4.2.2 op:numeric-subtract
        4.2.3 op:numeric-multiply
        4.2.4 op:numeric-divide
        4.2.5 op:numeric-integer-divide
        4.2.6 op:numeric-mod
        4.2.7 op:numeric-unary-plus
        4.2.8 op:numeric-unary-minus
    4.3 Comparison operators on numeric values
        4.3.1 op:numeric-equal
        4.3.2 op:numeric-less-than
        4.3.3 op:numeric-greater-than
    4.4 Functions on numeric values
        4.4.1 fn:abs
        4.4.2 fn:ceiling
        4.4.3 fn:floor
        4.4.4 fn:round
        4.4.5 fn:round-half-to-even
    4.5 Parsing numbers
        4.5.1 fn:number
    4.6 Formatting integers
        4.6.1 fn:format-integer
    4.7 Formatting numbers
        4.7.1 Defining a decimal format
        4.7.2 fn:format-number
        4.7.3 Syntax of the picture string
        4.7.4 Analysing the picture string
        4.7.5 Formatting the number
    4.8 Trigonometric and exponential functions
        4.8.1 math:pi
        4.8.2 math:exp
        4.8.3 math:exp10
        4.8.4 math:log
        4.8.5 math:log10
        4.8.6 math:pow
        4.8.7 math:sqrt
        4.8.8 math:sin
        4.8.9 math:cos
        4.8.10 math:tan
        4.8.11 math:asin
        4.8.12 math:acos
        4.8.13 math:atan
        4.8.14 math:atan2
5 Functions on strings
    5.1 String types
    5.2 Functions to assemble and disassemble strings
        5.2.1 fn:codepoints-to-string
        5.2.2 fn:string-to-codepoints
    5.3 Comparison of strings
        5.3.1 Collations
        5.3.2 The Unicode Codepoint Collation
        5.3.3 Choosing a collation
        5.3.4 fn:compare
        5.3.5 fn:codepoint-equal
    5.4 Functions on string values
        5.4.1 fn:concat
        5.4.2 fn:string-join
        5.4.3 fn:substring
        5.4.4 fn:string-length
        5.4.5 fn:normalize-space
        5.4.6 fn:normalize-unicode
        5.4.7 fn:upper-case
        5.4.8 fn:lower-case
        5.4.9 fn:translate
    5.5 Functions based on substring matching
        5.5.1 fn:contains
        5.5.2 fn:starts-with
        5.5.3 fn:ends-with
        5.5.4 fn:substring-before
        5.5.5 fn:substring-after
    5.6 String functions that use regular expressions
        5.6.1 Regular expression syntax
        5.6.2 fn:matches
        5.6.3 fn:replace
        5.6.4 fn:tokenize
        5.6.5 fn:analyze-string
6 Functions that manipulate URIs
    6.1 fn:resolve-uri
    6.2 fn:encode-for-uri
    6.3 fn:iri-to-uri
    6.4 fn:escape-html-uri
7 Functions and operators on Boolean values
    7.1 Boolean constant functions
        7.1.1 fn:true
        7.1.2 fn:false
    7.2 Operators on Boolean values
        7.2.1 op:boolean-equal
        7.2.2 op:boolean-less-than
        7.2.3 op:boolean-greater-than
    7.3 Functions on Boolean values
        7.3.1 fn:boolean
        7.3.2 fn:not
8 Functions and operators on durations
    8.1 Two totally ordered subtypes of duration
        8.1.1 xs:yearMonthDuration
        8.1.2 xs:dayTimeDuration
    8.2 Comparison operators on durations
        8.2.1 op:yearMonthDuration-less-than
        8.2.2 op:yearMonthDuration-greater-than
        8.2.3 op:dayTimeDuration-less-than
        8.2.4 op:dayTimeDuration-greater-than
        8.2.5 op:duration-equal
    8.3 Component extraction functions on durations
        8.3.1 fn:years-from-duration
        8.3.2 fn:months-from-duration
        8.3.3 fn:days-from-duration
        8.3.4 fn:hours-from-duration
        8.3.5 fn:minutes-from-duration
        8.3.6 fn:seconds-from-duration
    8.4 Arithmetic operators on durations
        8.4.1 op:add-yearMonthDurations
        8.4.2 op:subtract-yearMonthDurations
        8.4.3 op:multiply-yearMonthDuration
        8.4.4 op:divide-yearMonthDuration
        8.4.5 op:divide-yearMonthDuration-by-yearMonthDuration
        8.4.6 op:add-dayTimeDurations
        8.4.7 op:subtract-dayTimeDurations
        8.4.8 op:multiply-dayTimeDuration
        8.4.9 op:divide-dayTimeDuration
        8.4.10 op:divide-dayTimeDuration-by-dayTimeDuration
9 Functions and operators on dates and times
    9.1 Date and time types
        9.1.1 Limits and precision
    9.2 Date/time datatype values
        9.2.1 Examples
    9.3 Constructing a dateTime
        9.3.1 fn:dateTime
    9.4 Comparison operators on duration, date and time values
        9.4.1 op:dateTime-equal
        9.4.2 op:dateTime-less-than
        9.4.3 op:dateTime-greater-than
        9.4.4 op:date-equal
        9.4.5 op:date-less-than
        9.4.6 op:date-greater-than
        9.4.7 op:time-equal
        9.4.8 op:time-less-than
        9.4.9 op:time-greater-than
        9.4.10 op:gYearMonth-equal
        9.4.11 op:gYear-equal
        9.4.12 op:gMonthDay-equal
        9.4.13 op:gMonth-equal
        9.4.14 op:gDay-equal
    9.5 Component extraction functions on dates and times
        9.5.1 fn:year-from-dateTime
        9.5.2 fn:month-from-dateTime
        9.5.3 fn:day-from-dateTime
        9.5.4 fn:hours-from-dateTime
        9.5.5 fn:minutes-from-dateTime
        9.5.6 fn:seconds-from-dateTime
        9.5.7 fn:timezone-from-dateTime
        9.5.8 fn:year-from-date
        9.5.9 fn:month-from-date
        9.5.10 fn:day-from-date
        9.5.11 fn:timezone-from-date
        9.5.12 fn:hours-from-time
        9.5.13 fn:minutes-from-time
        9.5.14 fn:seconds-from-time
        9.5.15 fn:timezone-from-time
    9.6 Timezone adjustment functions on dates and time values
        9.6.1 fn:adjust-dateTime-to-timezone
        9.6.2 fn:adjust-date-to-timezone
        9.6.3 fn:adjust-time-to-timezone
    9.7 Arithmetic operators on durations, dates and times
        9.7.1 Limits and precision
        9.7.2 op:subtract-dateTimes
        9.7.3 op:subtract-dates
        9.7.4 op:subtract-times
        9.7.5 op:add-yearMonthDuration-to-dateTime
        9.7.6 op:add-dayTimeDuration-to-dateTime
        9.7.7 op:subtract-yearMonthDuration-from-dateTime
        9.7.8 op:subtract-dayTimeDuration-from-dateTime
        9.7.9 op:add-yearMonthDuration-to-date
        9.7.10 op:add-dayTimeDuration-to-date
        9.7.11 op:subtract-yearMonthDuration-from-date
        9.7.12 op:subtract-dayTimeDuration-from-date
        9.7.13 op:add-dayTimeDuration-to-time
        9.7.14 op:subtract-dayTimeDuration-from-time
    9.8 Formatting dates and times
        9.8.1 fn:format-dateTime
        9.8.2 fn:format-date
        9.8.3 fn:format-time
        9.8.4 The date/time formatting functions
        9.8.5 Examples of date and time formatting
10 Functions related to QNames
    10.1 Functions to create a QName
        10.1.1 fn:resolve-QName
        10.1.2 fn:QName
    10.2 Functions and operators related to QNames
        10.2.1 op:QName-equal
        10.2.2 fn:prefix-from-QName
        10.2.3 fn:local-name-from-QName
        10.2.4 fn:namespace-uri-from-QName
        10.2.5 fn:namespace-uri-for-prefix
        10.2.6 fn:in-scope-prefixes
11 Operators on base64Binary and hexBinary
    11.1 Comparisons of base64Binary and hexBinary values
        11.1.1 op:hexBinary-equal
        11.1.2 op:base64Binary-equal
12 Operators on NOTATION
    12.1 op:NOTATION-equal
13 Functions and operators on nodes
    13.1 fn:name
    13.2 fn:local-name
    13.3 fn:namespace-uri
    13.4 fn:lang
    13.5 op:is-same-node
    13.6 op:node-before
    13.7 op:node-after
    13.8 fn:root
    13.9 fn:path
    13.10 fn:has-children
    13.11 fn:innermost
    13.12 fn:outermost
14 Functions and operators on sequences
    14.1 General functions and operators on sequences
        14.1.1 op:concatenate
        14.1.2 fn:empty
        14.1.3 fn:exists
        14.1.4 fn:head
        14.1.5 fn:tail
        14.1.6 fn:insert-before
        14.1.7 fn:remove
        14.1.8 fn:reverse
        14.1.9 fn:subsequence
        14.1.10 fn:unordered
    14.2 Functions that compare values in sequences
        14.2.1 fn:distinct-values
        14.2.2 fn:index-of
        14.2.3 fn:deep-equal
    14.3 Functions that test the cardinality of sequences
        14.3.1 fn:zero-or-one
        14.3.2 fn:one-or-more
        14.3.3 fn:exactly-one
    14.4 Union, intersection and difference
        14.4.1 op:union
        14.4.2 op:intersect
        14.4.3 op:except
    14.5 Aggregate functions
        14.5.1 fn:count
        14.5.2 fn:avg
        14.5.3 fn:max
        14.5.4 fn:min
        14.5.5 fn:sum
    14.6 Functions and operators that generate sequences
        14.6.1 op:to
    14.7 Functions on node identifiers
        14.7.1 fn:id
        14.7.2 fn:element-with-id
        14.7.3 fn:idref
        14.7.4 fn:generate-id
    14.8 Functions giving access to external information
        14.8.1 fn:doc
        14.8.2 fn:doc-available
        14.8.3 fn:collection
        14.8.4 fn:uri-collection
        14.8.5 fn:unparsed-text
        14.8.6 fn:unparsed-text-lines
        14.8.7 fn:unparsed-text-available
        14.8.8 fn:environment-variable
        14.8.9 fn:available-environment-variables
    14.9 Parsing and serializing
        14.9.1 fn:parse-xml
        14.9.2 fn:parse-xml-fragment
        14.9.3 fn:serialize
15 Context functions
    15.1 fn:position
    15.2 fn:last
    15.3 fn:current-dateTime
    15.4 fn:current-date
    15.5 fn:current-time
    15.6 fn:implicit-timezone
    15.7 fn:default-collation
    15.8 fn:static-base-uri
16 Higher-order functions
    16.1 Functions on functions
        16.1.1 fn:function-lookup
        16.1.2 fn:function-name
        16.1.3 fn:function-arity
    16.2 Basic higher-order functions
        16.2.1 fn:for-each
        16.2.2 fn:filter
        16.2.3 fn:fold-left
        16.2.4 fn:fold-right
        16.2.5 fn:for-each-pair
17 Constructor functions
    17.1 Constructor functions for XML Schema built-in atomic types
    17.2 Constructor functions for xs:QName and xs:NOTATION
    17.3 Constructor functions for XML Schema built-in list types
    17.4 Constructor functions for XML Schema built-in union types
    17.5 Constructor functions for user-defined types
18 Casting
    18.1 Casting from primitive types to primitive types
        18.1.1 Casting to xs:string and xs:untypedAtomic
        18.1.2 Casting to numeric types
        18.1.3 Casting to duration types
        18.1.4 Casting to date and time types
        18.1.5 Casting to xs:boolean
        18.1.6 Casting to xs:base64Binary and xs:hexBinary
        18.1.7 Casting to xs:anyURI
        18.1.8 Casting to xs:QName and xs:NOTATION
        18.1.9 Casting to xs:ENTITY
    18.2 Casting from xs:string and xs:untypedAtomic
    18.3 Casting involving non-primitive types
        18.3.1 Casting to derived types
        18.3.2 Casting from derived types to parent types
        18.3.3 Casting within a branch of the type hierarchy
        18.3.4 Casting across the type hierarchy
        18.3.5 Casting to union types
        18.3.6 Casting to list types

Appendices

A References
    A.1 Normative references
    A.2 Non-normative references
B Error summary
C Illustrative user-written functions (Non-Normative)
    C.1 eg:if-empty and eg:if-absent
        C.1.1 eg:if-empty
        C.1.2 eg:if-absent
    C.2 Union, intersection and difference on sequences of values
        C.2.1 eg:value-union
        C.2.2 eg:value-intersect
        C.2.3 eg:value-except
    C.3 eg:index-of-node
    C.4 eg:string-pad
    C.5 eg:distinct-nodes-stable
    C.6 Finding minima and maxima
        C.6.1 eg:highest
        C.6.2 eg:lowest
    C.7 Sorting
D Checklist of implementation-defined features (Non-Normative)
E Changes since previous Recommendation (Non-Normative)
    E.1 Substantive changes (15 December 2009)
    E.2 Substantive changes (18 June 2012)
    E.3 Substantive changes (Candidate Recommendation)
    E.4 Substantive changes (post Candidate Recommendation)
    E.5 Editorial changes
F Compatibility with Previous Versions (Non-Normative)
    F.1 Compatibility between XPath 2.0 and XPath 1.0
    F.2 Compatibility between XPath 3.0 and XPath 2.0


1 Introduction

The purpose of this document is to catalog the functions and operators required for XPath 3.0, XQuery 3.0 and XSLT 3.0. The exact syntax used to call these functions and operators is specified in [XML Path Language (XPath) 3.0], [XQuery 3.0: An XML Query Language] and [XSL Transformations (XSLT) Version 3.0].

This document defines constructor functions and functions that take typed values as arguments. Some of the functions specify the semantics of operators defined in [XML Path Language (XPath) 3.0] and [XQuery 3.0: An XML Query Language].

[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 datatypes defined in Section 2.7 Schema Information DM30 of the [XQuery and XPath Data Model (XDM) 3.0]. These functions and operations are defined for use in [XML Path Language (XPath) 3.0], [XQuery 3.0: An XML Query Language] and [XSL Transformations (XSLT) Version 3.0] and related XML standards. This document also defines functions and operators on nodes and node sequences as defined in the [XQuery and XPath Data Model (XDM) 3.0] for use in [XML Path Language (XPath) 3.0], [XQuery 3.0: An XML Query Language] and [XSL Transformations (XSLT) Version 3.0] and other related XML standards.

[XML Schema 1.1 Part 2: Datatypes] adds to the data types 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 data types: for example, it extends the value space of xs:double to allow both positive and negative zero, and extends the lexical space to allow +INF; it modifies the value space of xs:Name to permit additional Unicode characters; it allows year zero and disallows leap seconds in xs:dateTime values; and it allows any character string to appear as the value of an xs:anyURI item. Implementations of this specification may support either XSD 1.0 or XSD 1.1 or both.

References to specific sections of some of the above documents are indicated by cross-document links in this document. Each such link consists of a pointer to a specific section followed a superscript specifying the linked document. The superscripts have the following meanings: 'XQ' [XQuery 3.0: An XML Query Language], 'XT' [XSL Transformations (XSLT) Version 3.0], 'XP' [XML Path Language (XPath) 3.0], and 'DM' [XQuery and XPath Data Model (XDM) 3.0].

1.1 Conformance

The Functions and Operators specification is intended primarily as a component that can be used by other specifications. Therefore, Functions and Operators relies on specifications that use it (such as [XML Path Language (XPath) 3.0], [XSL Transformations (XSLT) Version 3.0] and [XQuery 3.0: An XML Query Language]) to specify conformance criteria for their respective environments.

Authors of conformance criteria for the use of the Functions and Operators should pay particular attention to the following features:

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

  • Support for XML 1.0 and XML 1.1 by the datatypes used in Functions and Operators.

Note:

The XML Schema 1.1 recommendation introduces one new concrete data type: xs:dateTimeStamp; it also incorporates the types xs:dayTimeDuration, xs:yearMonthDuration, and xs:anyAtomicType which were previously defined as part of [XQuery and XPath Data Model (XDM) 3.0]. 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.

In this document, text labeled as an example or as a Note is provided for explanatory purposes and is not normative.

1.2 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 17 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 DM30 of [XQuery and XPath Data Model (XDM) 3.0]. 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/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.

    Note:

    The namespace URI associated with the err prefix is not expected to change from one version of this document to another. The contents of this namespace may be extended to allow additional errors to be returned.

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

  • Functions defined with the op prefix are described here to underpin the definitions of the operators in [XML Path Language (XPath) 3.0], [XQuery 3.0: An XML Query Language] and [XSL Transformations (XSLT) Version 3.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:

    fn:numeric-multiply($arg1 as numeric, $arg2 as numeric) as numeric

1.3 Function overloading

In general, the specifications named above do not support function overloading in the sense that functions that have multiple signatures with the same name and the same number of parameters are not supported. Consequently, there are no such overloaded functions in this document except for legacy [XML Path Language (XPath) Version 1.0] functions such as fn:string, which accepts a single parameter of a variety of types. In addition, it should be noted that the functions defined in 4 Functions and operators on numerics that accept numeric parameters accept arguments of type xs:integer, xs:decimal, xs:float or xs:double. See 1.4 Function signatures and descriptions. Operators such as "+" may be overloaded. This document does define some functions with more than one signature with the same name and different number of parameters. User-defined functions with more than one signature with the same name and different number of parameters are also supported.

1.4 Function signatures and descriptions

Each function is defined by specifying its signature, a description of the return type and each of the parameters and its semantics. For many functions, examples are included to illustrate their use.

Each function's signature is presented in a form like this:

fn:function-name($parameter-name as parameter-type, ...) as return-type

In this notation, function-name, in bold-face, is the name of the function whose signature is being specified. 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 declaration specifies the static type of the parameter, in italics, and a descriptive, but non-normative, name. 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 XP30.

One function, fn:concat, has a variable number of arguments (two or more). More strictly, there is an infinite set of functions having the name fn:concat, with arity ranging from 2 to infinity. For this special case, a single function signature is given, with an ellipsis indicating an indefinite number of arguments.

In some cases the word " numeric " is used in function signatures as a shorthand to indicate the four numeric types: xs:integer, xs:decimal, xs:float and xs:double. For example, a function with the signature:

fn:numeric-function($arg as numeric) as ...

represents the following four function signatures:

fn:numeric-function($arg as xs:integer) as ...
fn:numeric-function($arg as xs:decimal) as ...
fn:numeric-function($arg as xs:float) as ...
fn:numeric-function($arg as xs:double) as ...

For most functions there is an initial paragraph describing what the function does followed by semantic rules. These rules are meant to be followed in the order that they appear in this document.

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 ("-"). 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. For example, fn:timezone-from-dateTime.

Rules for passing parameters to operators are described in the relevant sections of [XQuery 3.0: An XML Query Language] and [XML Path Language (XPath) 3.0]. For example, the rules for passing parameters to arithmetic operators are described in Section 3.5 Arithmetic Expressions XP30. 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 XP30). 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 XP30).

  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 item, referred to as ".". In the second signature, the argument must be present but may be the empty sequence, written as ().

Some functions accept a sequence of zero or more values as an argument. This is indicated by following the name of the type of the items in the sequence with *. The sequence may contain zero or more items of the named type. For example, the function below accepts a sequence of xs:double and returns a xs:double or the empty sequence.

fn:median($arg as xs:double*) as xs:double?

1.5 Type system

The diagrams below show how nodes, function items, primitive simple types, and user defined types fit together into a type system. This type system comprises two distinct hierarchies that both include the primitive simple types. In the diagrams, connecting lines represent relationships between derived types and the types from which they are derived; the arrowheads point toward the type from which they are derived. The dashed line represents relationships not present in this diagram, but that appear in one of the other diagrams. Dotted lines represent additional relationships that follow an evident pattern. The information that appears in each diagram is recapitulated in tabular form.

The xs:IDREFS, xs:NMTOKENS, and xs:ENTITIES types and the user-defined list and union types are special types in that these types are lists or unions rather than types derived by extension or restriction.

The first diagram and its corresponding table illustrate the relationship of various item types. Item types in the data model form a lattice rather than a hierarchy: in the relationship defined by the derived-from(A, B) function, some types are derived from more than one other type. Examples include functions (function(xs:string) as xs:int is substitutable for function(xs:NCName) as xs:int and also for function(xs:string) as xs:decimal), and union types (A is substitutable for union(A, B) and also for union(A, C). In XDM, item types include node types, function types, and built-in atomic types. The diagram, which shows only hierarchic relationships, is therefore a simplification of the full model.

Type hierarchy graphic, item hierarchy

In the table, each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.

item
xs:anyAtomicType
function(*)
function(item()*) as item()*
function(item()*) as item()
function(item()*) as item()?
function(item()*, item()*) as item()*
node
attribute
user-defined attribute types
comment
document
user-defined document types
element
user-defined element types
namespace
processing-instruction
text

The next diagram and table illustrate the "any type" type hierarchy, in which all types are derived from distinguished type xs:anyType.

Type hierarchy graphic, anyType hierarchy

In the table, each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.

xs:anyType
user-defined complex types
xs:untyped
xs:anySimpleType
user-defined list and union types
xs:IDREFS
xs:NMTOKENS
xs:ENTITIES
xs:anyAtomicType

The final diagram and table show 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] as well as the two totally ordered subtypes of duration defined in 8.1 Two totally ordered subtypes of duration.

Type hierarchy graphic, anyAtomicType hierarchy

In the table, each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.

xs:untypedAtomic
xs:dateTime
xs:dateTimeStamp
xs:date
xs:time
xs:duration
xs:yearMonthDuration
xs:dayTimeDuration
xs:float
xs:double
xs:decimal
xs:integer
xs:nonPositiveInteger
xs:negativeInteger
xs:long
xs:int
xs:short
xs:byte
xs:nonNegativeInteger
xs:unsignedLong
xs:unsignedInt
xs:unsignedShort
xs:unsignedByte
xs:positiveInteger
xs:gYearMonth
xs:gYear
xs:gMonthDay
xs:gDay
xs:gMonth
xs:string
xs:normalizedString
xs:token
xs:language
xs:NMTOKEN
xs:Name
xs:NCName
xs:ID
xs:IDREF
xs:ENTITY
xs:boolean
xs:base64Binary
xs:hexBinary
xs:anyURI
xs:QName
xs:NOTATION

1.6 Terminology

The terminology used to describe the functions and operators on [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

1.6.1 Strings, characters, and codepoints

This document uses the terms string, character, and codepoint with the following meanings:

[Definition] A character is an instance of the CharXML production of [REC-xml].

Note:

This definition excludes Unicode characters in the surrogate blocks as well as xFFFE and xFFFF, while including characters with codepoints greater than xFFFF which some programming languages treat as two characters. The valid characters are defined by their codepoints, and include some whose codepoints have not been assigned by the Unicode consortium to any character.

[Definition] A string is a sequence of zero or more ·characters·, or equivalently, a value in the value space of the xs:string data type.

[Definition] A codepoint is a non-negative integer assigned to a ·character· by the Unicode consortium, or reserved for future assignment to a character.

Note:

The set of codepoints is thus wider than the set of characters.

This specification spells "codepoint" as one word; the Unicode specification spells it as "code point". Equivalent terms found in other specifications are "character number" or "code position". See [Character Model for the World Wide Web 1.0: Fundamentals]

Because these terms appear so frequently, they are hyperlinked to the definition only when there is a particular desire to draw the reader's attention to the definition; the absence of a hyperlink does not mean that the term is being used in some other sense.

It is ·implementation-defined· which version of [The Unicode Standard] is supported, but it is recommended that the most recent version of Unicode be used.

Unless explicitly stated, the xs:string values returned by the functions in this document are not normalized in the sense of [Character Model for the World Wide Web 1.0: Fundamentals].

Notes:

In functions that involve character counting such as fn:substring, fn:string-length and fn:translate, what is counted is the number of XML ·characters· in the string (or equivalently, the number of Unicode codepoints). Some implementations may represent a codepoint above xFFFF using two 16-bit values known as a surrogate pair. A surrogate pair counts as one character, not two.

1.6.2 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 pair of values consisting of a namespace URI and a local name. They belong to the value space of the [XML Schema Part 2: Datatypes Second Edition] datatype xs:QName. When this document refers to xs:QName we always mean the value space, i.e. a namespace URI, local name pair (and not the lexical space referring to constructs of the form prefix:local-name).

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:

Note that 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.6.3 Conformance terminology

[Definition] for compatibility

A feature of this specification included to ensure that implementations that use this feature remain compatible with [XML Path Language (XPath) Version 1.0]

[Definition] may

Conforming documents and processors are permitted to, but need not, behave as described.

[Definition] must

Conforming documents and processors are required to behave as described; otherwise, they are either non-conformant or else in error.

[Definition] implementation-defined

Possibly differing between implementations, but specified and documented by the implementor for each particular implementation.

[Definition] implementation-dependent

Possibly differing between implementations, but not specified by this or other W3C specification, and not required to be specified by the implementor for any particular implementation.

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

[Definition] Two function calls are said to be within the same execution scope if the host environment defines them as such. In XSLT, any two calls executed during the same transformation are in the same execution scope. In XQuery, any two calls executed during the evaluation of a top-level expression are in the same execution scope. In other contexts, the execution scope is specified by the host environment that invokes the function library.

The following definition explains more precisely what it means for two function calls to return the same result:

[Definition] Two values are defined to be identical if they contain the same number of items and the items are pairwise identical. Two items are identical if and only if one of the following conditions applies:

  • Both items are atomic values, of precisely the same type, and the values are equal as defined using the eq operator, using the Unicode codepoint collation when comparing strings

  • Both items are nodes, and represent the same node

  • Both items are function items, and have the same name (or absence of a name), arity, function signature, and closure. (Note that there is no function or operator defined in the specification that tests whether two function items are identical.)

Some functions produce results that depend not only on their explicit arguments, but also on the static and dynamic context.

[Definition] A function 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 as well as on the actual supplied arguments (if any).

[Definition] A function that is not ·context-dependent· is called context-independent.

A function that is context-dependent can be used as 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. In effect, the static and dynamic part of the context thus act as part of the closure of the function item.

Context-dependent functions fall into a number of categories:

  1. The functions fn:current-date, fn:current-dateTime, fn:current-time, 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:position, fn:last, fn:id#1, fn:idref#1, fn:element-with-id#1, fn:lang#1, fn:local-name#0, fn:name#0, fn:namespace-uri#0, fn:normalize-space#0, fn:number#0, fn:root#0, fn:string#0, fn:string-length#0, and fn:path#0 depend on the focus. These functions will in general return different results on different calls if the focus is different.

    [Definition] A function is focus-dependent if its result depends on the focus (that is, the context item, position, or size).

    [Definition] 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 are used as the static and dynamic context of the function 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 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:

  • Some functions (such as fn:distinct-values and fn:unordered) produce results in an ·implementation-defined· or ·implementation-dependent· order. In such cases there is no guarantee that the order of results from different calls will be the same. These functions are said to be non-deterministic with respect to ordering.

  • The function fn:analyze-string constructs an element node to represent its results. There is no guarantee that repeated calls with the same arguments will return the same identical node (in the sense of the is operator). However, if non-identical nodes are returned, their content will be the same in the sense of the fn:deep-equal function. Such a function is said to be non-deterministic with respect to node identity.

  • Some functions (such as fn:doc and fn:collection) create new nodes by reading external documents. Such functions are guaranteed to be ·deterministic· with the exception that an implementation is allowed to make them non-deterministic as a user option.

Where the results of a function are described as being (to a greater or lesser extent) ·implementation-defined· or ·implementation-dependent·, this does not by itself remove the requirement that the results should be deterministic: that is, that repeated calls with the same explicit and implicit arguments must return identical results.

2 Accessors

Accessors and their semantics are described in [XQuery and XPath Data Model (XDM) 3.0]. Some of these accessors are exposed to the user through the functions described below.

Function Accessor Accepts Returns
fn:node-name node-name an optional node zero or one xs:QName
fn:nilled nilled a node an optional xs:boolean
fn:string string-value an optional item or no argument xs:string
fn:data typed-value zero or more items a sequence of atomic values
fn:base-uri base-uri an optional node or no argument zero or one xs:anyURI
fn:document-uri document-uri an optional node zero or one xs:anyURI

2.1 fn:node-name

Summary

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

Signatures
fn:node-name() as xs:QName?
fn:node-name($arg 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 item (.). The behavior of the function if the argument is omitted is exactly the same as if the context item had been passed as the argument.

If $arg 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.0] (see Section 5.11 node-name Accessor DM30).

Error Conditions

The following errors may be raised when $arg 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 absentDM30.

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 absentDM30 and the local part is the namespace prefix being bound).

For all other kinds of node, the function returns the empty sequence.

2.2 fn:nilled

Summary

Returns true for an element that is nilled.

Signatures
fn:nilled() as xs:boolean
fn:nilled($arg 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 item (.). The behavior of the function if the argument is omitted is exactly the same as if the context item had been passed as the argument.

If $arg 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.0] (see Section 5.9 nilled Accessor DM30).

Error Conditions

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

Notes

If $arg is not an element node, the function returns the empty sequence.

If $arg 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.0].

2.3 fn:string

Summary

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

Signatures
fn:string() as xs:string
fn:string($arg 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, $arg defaults to the context item. That is, calling fn:string() is equivalent to calling fn:string(.).

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

If $arg 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.0] (see Section 5.13 string-value Accessor DM30).

If $arg is an atomic value, the function returns the result of the expression $arg cast as xs:string (see 18 Casting).

Error Conditions

A dynamic error is raised [err:XPDY0002]XP30 by the zero-argument version of the function if the context item is absentDM30.

A type error is raised [err:FOTY0014] if $arg is a function item.

Examples

The expression string(23) returns "23".

The expression string(false()) returns "false".

The expression string("Paris") returns "Paris".

The expression string(abs#1) raises error FOTY0014.

let $para :=

<para>In a hole in the ground there lived a <term author="Tolkein">hobbit</term>.</para>
         

The expression string($para) returns "In a hole in the ground there lived a hobbit.".

2.4 fn:data

Summary

Returns the result of atomizing a sequence, that is, replacing all nodes in the sequence by their typed values.

Signatures
fn:data() as xs:anyAtomicType*
fn:data($arg 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 item (.). The behavior of the function if the argument is omitted is exactly the same as if the context item had been passed as the argument.

The result of fn:data is the sequence of atomic values produced by applying the following rules to each item in $arg:

  • If the item is an atomic value, it is appended to the result sequence.

  • If the item is a node, the typed value of the node is appended to the result sequence. The typed value is a sequence of zero or more atomic values: specifically, the result of the dm:typed-value accessor as defined in [XQuery and XPath Data Model (XDM) 3.0] (See Section 5.15 typed-value Accessor DM30).

Error Conditions

A type error is raised [err:FOTY0012] if an item in the sequence $arg is a node that does not have a typed value.

A type error is raised [err:FOTY0013] if an item in the sequence $arg is a function item.

A dynamic error is raised if $arg is omitted and the context item is absentDM30.

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 value or sequence of atomic values is required.

Examples

The expression data(123) returns 123.

let $para :=

<para>In a hole in the ground there lived a <term author="Tolkein">hobbit</term>.</para>
            

The expression data($para) returns xs:untypedAtomic("In a hole in the ground there lived a hobbit.").

The expression data($para/term/@author) returns xs:untypedAtomic("Tolkein").

The expression data(abs#1) raises error FOTY0013.

2.5 fn:base-uri

Summary

Returns the base URI of a node.

Signatures
fn:base-uri() as xs:anyURI?
fn:base-uri($arg 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 $arg 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 $arg. This accessor is defined, for each kind of node, in the XDM specification (See Section 5.2 base-uri Accessor DM30).

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 $arg is omitted:

2.6 fn:document-uri

Summary

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

Signatures
fn:document-uri() as xs:anyURI?
fn:document-uri($arg 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 item (.). The behavior of the function if the argument is omitted is exactly the same as if the context item had been passed as the argument.

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

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

Otherwise, the function returns the value of the document-uri accessor applied to $arg, as defined in [XQuery and XPath Data Model (XDM) 3.0] (See Section 6.1.2 Accessors DM30).

Error Conditions

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

Notes

In the case of a document node $D returned by the fn:doc function, or a document node at the root of a tree containing a node returned by the fn:collection function, it will always be true that either fn:document-uri($D) returns the empty sequence, or that the following expression is true: fn:doc(fn:document-uri($D)) is $D. It is ·implementation-defined· whether this guarantee also holds for document nodes obtained by other means, for example a document node passed as the initial context node of a query or transformation.

3 Errors and diagnostics

3.1 Raising errors

In this document, as well as in [XQuery 3.0: An XML Query Language] and [XML Path Language (XPath) 3.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.

The above phrase is normally accompanied by specification of a specific error, to wit: "an error is raised [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 XP30.

The fn:error function is a general function that may be called as above but may also be called from [XQuery 3.0: An XML Query Language] or [XML Path Language (XPath) 3.0] applications with, for example, an xs:QName argument.

3.1.1 fn:error

Summary

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

Signatures
fn:error() as none
fn:error($code as xs:QName) as none
fn:error($code as xs:QName?, $description as xs:string) as none
fn:error( $code  as xs:QName?,
$description  as xs:string,
$error-object  as item()*) as none
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·

If fn:error is called with no arguments, then its behavior is the same as the function call:

 fn:error(fn:QName('http://www.w3.org/2005/xqt-errors', 'err:FOER0000')) 

If $code is the empty sequence then the effective value is the xs:QName constructed by:

 fn:QName('http://www.w3.org/2005/xqt-errors', 'err:FOER0000')

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.

  • The $description is a natural-language description of the error condition.

  • The $error-object is an arbitrary value used to convey additional information about the error, and may be used in any way the application chooses.

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.

The type "none" is a special type defined in [XQuery 1.0 and XPath 2.0 Formal Semantics] and is not available to the user. It indicates that the function never returns and ensures that it has the correct static type.

Any QName may be used as an error code; there are no reserved names or namespaces. The error is always classified as a dynamic error, even if the error code used is one that is normally used for static errors or type errors.

Examples

The expression fn:error() 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.).

The expression fn:error(fn:QName('http://www.example.com/HR', 'myerr:toohighsal'), 'Does not apply because salary is too high') raises error myerr:toohighsal. (This returns http://www.example.com/HR#toohighsal and the xs:string "Does not apply because 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

Summary

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

Signature
fn:trace($value as item()*, $label as xs:string) as item()*
Properties

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

Rules

The function returns the value of $value, unchanged.

In addition, the values of $value, converted to an xs:string, and $label may be directed to a trace data set. The destination of the trace output is ·implementation-defined·. The format of the trace output is ·implementation dependent·. The ordering of output from calls of the fn:trace function is ·implementation dependent·.

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 put the strings "124.84" and "the value of $v is:" in the trace data set in implementation dependent order.

4 Functions and operators on numerics

This section specifies arithmetic operators on the numeric datatypes defined in [XML Schema Part 2: Datatypes Second Edition]. It uses an approach that permits lightweight implementation whenever possible.

4.1 Numeric types

The operators described in this section are defined on the following numeric types. Each type whose name is indented is derived from the type whose name appears nearest above with one less level of indentation.

xs:decimal
xs:integer
xs:float
xs:double

They also apply to types derived by restriction from the above types.

Note:

This specification uses [IEEE 754-2008] arithmetic for xs:float and xs:double values. One consequence of this is that some operations result in the value NaN (not-a number), which has the unusual property that it is not equal to itself. Another consequence is that some operations return the value negative zero. This differs from [XML Schema Part 2: Datatypes Second Edition] which defines NaN as being equal to itself and defines only a single zero in the value space. The text accompanying several functions defines behavior for both positive and negative zero inputs and outputs in the interest of alignment with [IEEE 754-2008]. A conformant implementation must respect these semantics. In consequence, the expression -0.0e0 (which is actually a unary minus operator applied to an xs:double value) will always return negative zero: see 4.2.8 op:numeric-unary-minus. As a concession to implementations that rely on implementations of XSD 1.0, however, when casting from string to double the lexical form -0 may be converted to positive zero, though negative zero is recommended.

XML Schema 1.1 introduces support for positive and negative zero as distinct values, and also uses the [IEEE 754-2008] semantics for comparisons involving NaN.

4.2 Arithmetic operators on numeric values

The following functions define the semantics of arithmetic operators defined in [XQuery 3.0: An XML Query Language] and [XML Path Language (XPath) 3.0] on these numeric types.

Operators 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 the basic numeric types: xs:integer, xs:decimal, xs:float and xs:double, and types derived from them. The word " numeric " in function signatures signifies these four types. For simplicity, each operator is defined to operate on operands of the same type and return the 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 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 XP30 and Section B.2 Operator Mapping XP30 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. He may then derive fenceHeight using an enumeration to restrict the permitted set of values to, say, 36, 48 and 60.

op:operation(fenceHeight, xs:integer) => op:operation(xs:integer, xs:integer)

fenceHeight can be substituted for its base type height and height can be substituted for its base type xs:integer.

The basic rules for addition, subtraction, and multiplication of ordinary numbers are not set out in this specification; they are taken as given. In the case of xs:double and xs:float the rules are as defined in [IEEE 754-2008]. The rules for handling division and modulus operations, as well as the rules for handling special values such as infinity and NaN, and exception conditions such as overflow and underflow, are described more explicitly since they are not necessarily obvious.

On overflow and underflow situations during arithmetic operations conforming implementations ·must· behave as follows:

  • For xs:float and xs:double operations, overflow behavior ·must· be conformant with [IEEE 754-2008]. This specification allows the following options:

    • Raising a dynamic error [err:FOAR0002] via an overflow trap.

    • Returning INF or -INF.

    • Returning the largest (positive or negative) non-infinite number.

  • For xs:float and xs:double operations, underflow behavior ·must· be conformant with [IEEE 754-2008]. This specification allows the following options:

    • Raising a dynamic error [err:FOAR0002] via an underflow trap.

    • Returning 0.0E0 or +/- 2**Emin or a denormalized value; where Emin is the smallest possible xs:float or xs:double exponent.

  • For xs:decimal operations, overflow behavior ·must· raise a dynamic error [err:FOAR0002]. On underflow, 0.0 must be returned.

  • For xs:integer operations, implementations that support limited-precision integer operations ·must· select from the following options:

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 the number of digits of precision returned by the numeric operators is ·implementation-defined·. If the number of digits in the result exceeds the number of digits that the implementation supports, the result is truncated or rounded in an ·implementation-defined· manner.

The [IEEE 754-2008] specification also describes handling of two exception conditions called divideByZero and invalidOperation. The IEEE divideByZero exception is raised not only by a direct attempt to divide by zero, but also by operations such as log(0). The IEEE invalidOperation exception is raised by attempts to call a function with an argument that is outside the function's domain (for example, sqrt(-1) or log(-1). These IEEE exceptions do not cause a dynamic error at the application level; rather they result in the relevant function or operator returning NaN. 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 NaN with no error.

The [IEEE 754-2008] specification distinguishes two NaN values, a quiet NaN and a signaling NaN. These two values are not distinguishable in the XDM model: the value spaces of xs:float and xs:double each include only a single NaN value. This does not prevent the implementation distinguishing them internally, and triggering different ·implementation-defined· warning conditions, but such distinctions do not affect the observable behavior of an application using the functions and operators defined in this specification.

4.2.1 op:numeric-add

Summary

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

Operator Mapping

Defines the semantics of the "+" operator applied to numeric values

Signature
op:numeric-add($arg1 as numeric, $arg2 as numeric) as 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 applied to numeric values.

Signature
op:numeric-subtract($arg1 as numeric, $arg2 as numeric) as 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 applied to numeric values.

Signature
op:numeric-multiply($arg1 as numeric, $arg2 as numeric) as 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 applied to numeric values.

Signature
op:numeric-divide($arg1 as numeric, $arg2 as numeric) as 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-2008]. A positive number divided by positive zero returns INF. A negative number divided by positive zero returns -INF. Division by negative zero returns -INF and INF, respectively. Positive or negative zero divided by positive or negative zero returns NaN. Also, INF or -INF divided by INF or -INF returns NaN.

4.2.5 op:numeric-integer-divide

Summary

Performs an integer division.

Operator Mapping

Defines the semantics of the "idiv" operator applied to numeric values.

Signature
op:numeric-integer-divide($arg1 as numeric, $arg2 as 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 fn:abs($N * $arg2) le fn:abs($arg1) and fn:compare($N * $arg2, 0) eq fn: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

The expression op:numeric-integer-divide(10,3) returns 3.

The expression op:numeric-integer-divide(3,-2) returns -1.

The expression op:numeric-integer-divide(-3,2) returns -1.

The expression op:numeric-integer-divide(-3,-2) returns 1.

The expression op:numeric-integer-divide(9.0,3) returns 3.

The expression op:numeric-integer-divide(-3.5,3) returns -1.

The expression op:numeric-integer-divide(3.0,4) returns 0.

The expression op:numeric-integer-divide(3.1E1,6) returns 5.

The expression op:numeric-integer-divide(3.1E1,7) returns 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 applied to numeric values.

Signature
op:numeric-mod($arg1 as numeric, $arg2 as numeric) as 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-2008] 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

The expression op:numeric-mod(10,3) returns 1.

The expression op:numeric-mod(6,-2) returns 0.

The expression op:numeric-mod(4.5,1.2) returns 0.9.

The expression op:numeric-mod(1.23E2, 0.6E1) returns 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 numeric values.

Signature
op:numeric-unary-plus($arg as numeric) as 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 function conversion rules are applied in the normal way, the unary + 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 applied to numeric values.

Signature
op:numeric-unary-minus($arg as numeric) as 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

This specification defines the following comparison operators on numeric values. Comparisons take two arguments of the same type. If the arguments are of different types, one argument is promoted to the type of the other as described above in 4.2 Arithmetic operators on numeric values. Each comparison operator returns a boolean value. If either, or both, operands are NaN, false is returned.

Function Meaning
op:numeric-equal Returns true if and only if the value of $arg1 is equal to the value of $arg2.
op:numeric-less-than Returns true if and only if $arg1 is numerically less than $arg2.
op:numeric-greater-than Returns true if and only if $arg1 is numerically greater 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 on numeric values, and is also used in defining the semantics of "ne", "le" and "ge".

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

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

For xs:float and xs:double values, positive zero and negative zero compare equal. INF equals INF, and -INF equals -INF. NaN does not equal itself.

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 on numeric values, and is also used in defining the semantics of "le".

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

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

For xs:float and xs:double values, positive infinity is greater than all other non-NaN values; negative infinity is less than all other non-NaN values. If $arg1 or $arg2 is NaN, the function returns false.

4.3.3 op:numeric-greater-than

Summary

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

Operator Mapping

Defines the semantics of the "gt" operator on numeric values, and is also used in defining the semantics of "ge".

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

The function call op:numeric-greater-than($A, $B) is defined to return the same result as op:numeric-less-than($B, $A)

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.

  • Except for fn:abs, for xs:float and xs:double arguments, if the argument is positive or negative infinity, positive or negative infinity is returned.

Function Meaning
fn:abs Returns the absolute value of $arg.
fn:ceiling Rounds $arg upwards to a whole number.
fn:floor Rounds $arg downwards to a whole number.
fn:round Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near.
fn:round-half-to-even Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near.

Note:

fn:round and fn:round-half-to-even produce the same result in all cases except when the argument is exactly midway between two values with the required precision.

Other ways of rounding midway values can be achieved as follows:

4.4.1 fn:abs

Summary

Returns the absolute value of $arg.

Signature
fn:abs($arg as numeric?) as numeric?
Properties

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

Rules

General rules: see 4.4 Functions on numeric values.

If $arg is negative the function returns -$arg, otherwise it returns $arg.

If the type of $arg is one of the four numeric types xs:float, xs:double, xs:decimal or xs:integer the type of the result is the same as the type of $arg. If the type of $arg is a type derived from one of the numeric types, the result is an instance of the base numeric type.

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

The expression fn:abs(10.5) returns 10.5.

The expression fn:abs(-10.5) returns 10.5.

4.4.2 fn:ceiling

Summary

Rounds $arg upwards to a whole number.

Signature
fn:ceiling($arg as numeric?) as 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 the value of $arg.

If the type of $arg is one of the four numeric types xs:float, xs:double, xs:decimal or xs:integer the type of the result is the same as the type of $arg. If the type of $arg is a type derived from one of the numeric types, the result is an instance of the base numeric type.

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.

Examples

The expression fn:ceiling(10.5) returns 11.

The expression fn:ceiling(-10.5) returns -10.

4.4.3 fn:floor

Summary

Rounds $arg downwards to a whole number.

Signature
fn:floor($arg as numeric?) as 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 the value of $arg.

If the type of $arg is one of the four numeric types xs:float, xs:double, xs:decimal or xs:integer the type of the result is the same as the type of $arg. If the type of $arg is a type derived from one of the numeric types, the result is an instance of the base numeric type.

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.

Examples

The expression fn:floor(10.5) returns 10.

The expression fn:floor(-10.5) returns -11.

4.4.4 fn:round

Summary

Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near.

Signatures
fn:round($arg as numeric?) as numeric?
fn:round($arg as numeric?, $precision as xs:integer) as 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 $arg that is a multiple of ten to the power of minus $precision. If two such values are equally near (for example, if the fractional part in $arg is exactly .5), the function returns the one that is closest to positive infinity.

If the type of $arg is one of the four numeric types xs:float, xs:double, xs:decimal or xs:integer the type of the result is the same as the type of $arg. If the type of $arg is a type derived from one of the numeric types, the result is an instance of the base numeric type.

The single-argument version of this function produces the same result as the two-argument version with $precision=0 (that is, it rounds to a whole number).

When $arg is of type xs:float and xs:double:

  1. If $arg 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 $arg.

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.

Examples

The expression fn:round(2.5) returns 3.0.

The expression fn:round(2.4999) returns 2.0.

The expression fn:round(-2.5) returns -2.0. (Not the possible alternative, -3).

The expression fn:round(1.125, 2) returns 1.13.

The expression fn:round(8452, -2) returns 8500.

The expression fn:round(3.1415e0, 2) returns 3.14e0.

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.

Signatures
fn:round-half-to-even($arg as numeric?) as numeric?
fn:round-half-to-even($arg as numeric?, $precision as xs:integer) as 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 $arg 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 $arg is exactly .500...), the function returns the one whose least significant digit is even.

If the type of $arg is one of the four numeric types xs:float, xs:double, xs:decimal or xs:integer the type of the result is the same as the type of $arg. If the type of $arg is a type derived from one of the numeric types, the result is an instance of the base numeric type.

The first signature of this function produces the same result as the second signature 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.

Examples

The expression fn:round-half-to-even(0.5) returns 0.0.

The expression fn:round-half-to-even(1.5) returns 2.0.

The expression fn:round-half-to-even(2.5) returns 2.0.

The expression fn:round-half-to-even(3.567812e+3, 2) returns 3567.81e0.

The expression fn:round-half-to-even(4.7564e-3, 2) returns 0.0e0.

The expression fn:round-half-to-even(35612.25, -2) returns 35600.

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 17 Constructor functions or using cast expressions as described in 18 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.

4.5.1 fn:number

Summary

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

Signatures
fn:number() as xs:double
fn:number($arg 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 item (.). That is, fn:number() is equivalent to fn:number(.), as defined by the rules that follow.

If $arg is the empty sequence or if $arg cannot be converted to an xs:double, the xs:double value NaN is returned.

Otherwise, $arg is converted to an xs:double following the rules of 18.1.2.2 Casting to xs:double. If the conversion to xs:double fails, the xs:double value NaN is returned.

Error Conditions

A dynamic error is raised [err:XPDY0002]XP30 if $arg is omitted and the context item is absentDM30.

As a consequence of the rules given above, a type error occurs if the context item cannot be atomized, or if the result of atomizing the context item is a sequence containing more than one atomic value.

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

The expression fn:number($item1/quantity) returns 5.0e0.

The expression fn:number($item2/description) returns xs:double('NaN').

Assume that the context item is the xs:string value "15". Then fn:number() returns 1.5e1.

4.6 Formatting integers

4.6.1 fn:format-integer

Summary

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

Signatures
fn:format-integer($value as xs:integer?, $picture as xs:string) as xs:string
fn:format-integer( $value  as xs:integer?,
$picture  as xs:string,
$lang  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 a primary format token, optionally followed by a format modifier. The primary format token is always present and must not be zero-length. If the string contains one or more semicolons then everything that precedes the last semicolon is taken as the primary format token and everything that follows is taken as the format modifier; if the string contains no semicolon then the entire picture is taken as the primary format token, and the format modifier is taken to be absent (which is equivalent to supplying a zero-length string).

The primary format token is classified as one of the following:

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

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

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

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

    If the primary format token contains at least one Unicode digit then it 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].

    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 decimal-digit-pattern, nor adjacent to another grouping-separator-sign.

    The corresponding output format is a decimal number, 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 ..., and 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 &#x661; (Arabic-Indic digit one) generates the sequence ١ then ٢ then ٣ ...

    The grouping-separator-signs are handled as follows. The position of grouping separators within the format token, counting backwards from the last digit, indicates the position of grouping separators to appear within the formatted number, and the character used as the grouping-separator-sign within the format token indicates the character to be used as the corresponding grouping separator in the formatted number. If grouping-separator-signs appear at regular intervals within the format token, that is if the same grouping separator appears at positions forming a sequence N, 2N, 3N, ... for some integer value N (including the case where there is only one number in the list), then the sequence is extrapolated to the left, so grouping separators will be used in the formatted number at every multiple of N. For example, if the format token is 0'000 then the number one million will be formatted as 1'000'000, while the number fifteen will be formatted as 0'015.

    The only purpose of optional-digit-signs is to mark the position of grouping-separator-signs. For example, if the format token is #'##0 then the number one million will be formatted as 1'000'000, while the number fifteen will be formatted as 15. A grouping separator is included in the formatted number only if there is a digit to its left, which will only be the case if either (a) the number is large enough to require that digit, or (b) the number of mandatory-digit-signs in the format token requires insignificant leading zeros to be present.

    Note:

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

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

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

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

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

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

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

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

  • Any other format token, which indicates a numbering sequence in which that token represents the number 1 (one) (but see the note below). It is ·implementation-defined· which numbering sequences, additional to those listed above, are supported. If an implementation does not support a numbering sequence represented by the given token, it must use a format token of 1.

    Note:

    In some traditional numbering sequences additional signs are added to denote that the letters should be interpreted as numbers; these are not included in the format token. An example (see also the example below) is classical Greek where a dexia keraia (x0374, ʹ) and sometimes an aristeri keraia (x0375, ͵) is added.

For all format tokens other than the first kind above (one that consists of decimal digits), 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 &#x2460; (circled digit one, ①) has a range imposed by the Unicode character repertoire — 1 to 20 in Unicode versions prior to 4.0, increased in subsequent versions. For the numbering sequences described above any upper bound imposed by the implementation must not be less than 1000 (one thousand) and any lower bound must not be greater than 1. Numbers that fall outside this range must be formatted using the format token 1.

The above expansions of numbering sequences for format tokens such as a and i are indicative but not prescriptive. There are various conventions in use for how alphabetic sequences continue when the alphabet is exhausted, and differing conventions for how roman numerals are written (for example, IV versus IIII as the representation of the number 4). Sometimes alphabetic sequences are used that omit letters such as i and o. This specification does not prescribe the detail of any sequence other than those sequences consisting entirely of decimal digits.

Many numbering sequences are language-sensitive. This applies especially to the sequence selected by the tokens w, W and Ww. It also applies to other sequences, for example different languages using the Cyrillic alphabet use different sequences of characters, each starting with the letter #x410 (Cyrillic capital letter A). In such cases, the $lang argument specifies which language's 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 [REC-xml]). 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 $lang 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.

For example, in some languages, ordinal numbers vary 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 o may be used to indicate the variation of the 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 recommended approach is to indicate the required ending, preceded by a hyphen: for example in German, appropriate values are o(-e), o(-er), o(-es), o(-en).

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.

Example: Ordinal Numbering in Italian

The specification "1;o(-º)" with $lang equal to it, if supported, should produce the sequence:

1º 2º 3º 4º ...

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

Primo Secondo Terzo Quarto Quinto ...

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

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.

Examples

The expression format-integer(123, '0000') returns "0123".

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

The expression format-integer(21, '1;o', 'en') returns "21st".

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

The expression format-integer(7, 'a') returns "g".

The expression format-integer(57, 'I') returns "LVII".

The expression format-integer(1234, '#;##0;') returns "1;234".

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, taking account of decimal formats specified in the static context.

Note:

This function can be used to format any numeric quantity, including an integer. For integers, however, the fn:format-integer function offers additional possibilities. Note also that the picture strings used by the two functions are not 100% compatible, though they share some options in common.

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, described in the following table:

Name Type Usage (non-normative)
decimal-separator-sign A single ·character· Defines the character used to represent the decimal point (typically ".") both in the picture string and in the formatted number
grouping-separator-sign A single ·character· Defines the character used to separate groups of digits (typically ",") both in the picture string and in the formatted number
infinity A ·string· Defines the string used to represent the value positive or negative infinity in the formatted number (typically "Infinity")
minus-sign A single ·character· Defines the character used as a minus sign in the formatted number if there is no subpicture for formatting negative numbers (typically "-", x2D)
NaN A ·string· Defines the string used to represent the value NaN in the formatted number
percent-sign A single ·character· Defines the character used as a percent sign (typically "%") both in the picture string and in the formatted number
per-mille-sign A single ·character· Defines the character used as a per-mille sign (typically "‰", x2030) both in the picture string and in the formatted number
mandatory-digit-sign A single ·character·, which must be a character in Unicode category Nd with decimal digit value 0 (zero) Defines the characters used in the picture string to represent a mandatory digit: for example, if the mandatory-digit-sign 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 one to nine.
optional-digit-sign A single ·character· Defines the character used in the picture string to represent an optional digit (typically "#")
pattern-separator-sign A single ·character· Defines the character used in the picture string to separate the positive and negative subpictures (typically ";")

[Definition] The decimal digit family of a decimal format is the sequence of ten digits with consecutive Unicode ·codepoints· starting with the mandatory-digit-sign.

It is a constraint that, for any named or unnamed decimal format, the properties representing characters used in a ·picture string· must have distinct values. These properties are decimal-separator-sign, grouping-separator-sign, percent-sign, per-mille-sign, optional-digit-sign, and pattern-separator-sign. Furthermore, none of these properties may be equal to any ·character· in the ·decimal digit family·.

4.7.2 fn:format-number

Summary

Returns a string containing a number formatted according to a given picture string, taking account of decimal formats specified in the static context.

Signatures
fn:format-number($value as numeric?, $picture as xs:string) as xs:string
fn:format-number( $value  as numeric?,
$picture  as xs:string,
$decimal-format-name  as xs:string?) 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 effect of the two-argument form of the function is equivalent to calling the three-argument form with an empty sequence as the value of the third argument.

The function formats $value as a string using the ·picture string· specified by the $picture argument and the decimal-format named by the $decimal-format-name argument, or the default decimal-format, if there is no $decimal-format-name argument. The syntax of the picture string is described in 4.7.3 Syntax of the picture string.

The $value argument may be of any numeric data type (xs:double, xs:float, xs:decimal, or their subtypes including xs:integer). Note that if an xs:decimal is supplied, it is not automatically promoted to an xs:double, as such promotion can involve a loss of precision.

If the supplied value of the $value argument is an empty sequence, the function behaves as if the supplied value were the xs:double value NaN.

The value of $decimal-format-name, if present and non-empty, must be a string which after removal of leading and trailing whitespace is in the form of an an EQName as defined in the XPath 3.0 grammar, that is one of the following:

  • A lexical QName, which is expanded using the statically known namespaces. The default namespace is not used (no prefix means no namespace).

  • A URIQualifiedName using the syntax Q{uri}local, where the URI can be zero-length to indicate a name in no namespace.

The decimal format that is used is the decimal format in the static context whose name matches $decimal-format-name if supplied, or the default decimal format in the static context otherwise.

The evaluation of the format-number function takes place in two phases, an analysis phase described in 4.7.4 Analysing 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 name specified as the $decimal-format-name argument is neither a valid lexical QName nor a valid URIQualifiedName, or if it uses a prefix that is not found in the statically known namespaces, or if the static context does not contain a declaration of a decimal-format with a matching expanded QName. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

Notes

Numbers will always be formatted with the most significant digit on the left.

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

The expression format-number(12345.6, '#,###.00') returns "12,345.60".

The expression format-number(12345678.9, '9,999.99') returns "12,345,678.90".

The expression format-number(123.9, '9999') returns "0124".

The expression format-number(0.14, '01%') returns "14%".

The expression format-number(-6, '000') returns "-006".

The following example assumes the existence of a decimal format named 'ch' in which the grouping separator is ʹ and the decimal separator is ·:

The expression format-number(1234.5678, '#ʹ##0·00', 'ch') returns "1ʹ234·57".

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 used must all be from the same decimal digit family, specifically, the sequence of ten consecutive digits starting with the mandatory-digit-sign. 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-separator-sign, grouping-sign, decimal-digit-family, optional-digit-sign and pattern-separator-sign are classified as active characters, and all other characters (including the percent-sign and per-mille-sign) are classified as passive characters.

The integer part of the sub-picture is defined as the part that appears to the left of the decimal-separator-sign if there is one, or the entire sub-picture otherwise. The fractional part of the sub-picture is defined as the part that appears to the right of the decimal-separator-sign 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.

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 a pattern-separator-sign. A picture-string must not contain more than one pattern-separator-sign. If the picture-string contains two sub-pictures, the first is used for positive values and the second for negative values.

  • A sub-picture must not contain more than one decimal-separator-sign.

  • A sub-picture must not contain more than one percent-sign or per-mille-sign, and it must not contain one of each.

  • A sub-picture must contain at least one character that is an optional-digit-sign 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-separator-sign adjacent to a decimal-separator-sign.

  • The integer part of a sub-picture must not contain a member of the decimal-digit-family that is followed by an optional-digit-sign. The fractional part of a sub-picture must not contain an optional-digit-sign that is followed by a member of the decimal-digit-family.

4.7.4 Analysing the picture string

This phase of the algorithm analyses 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 data type.

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 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-separator-sign 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-sign and decimal-digit-family characters that appear within the integer part of the sub-picture and to the right of the grouping-separator-sign. In addition, if these integer-part-grouping-positions are at regular intervals (that is, if they form a sequence N, 2N, 3N, ... for some integer value N, including the case where there is only one number in the list), then the sequence contains all integer multiples of N 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-sign. It is normally set to the number of decimal-digit-family characters found in the integer part of the sub-picture. But if the sub-picture contains no decimal-digit-family character and no decimal-separator-sign, it is set to one.

    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-sign and decimal-digit-family characters in the subpicture.

  • 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-sign 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-separator-sign 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-sign and decimal-digit-family characters that appear within the fractional part of the sub-picture and to the left of the grouping-separator-sign.

    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-sign and decimal-digit-family 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-sign and decimal-digit-family characters found in the fractional part of the sub-picture.

  • 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-sign 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 analysing 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 specified NaN-symbol (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 otherwise. Negative zero is taken as negative, positive zero as positive.

  3. If the input number is positive or negative infinity, the result is the concatenation of the appropriate prefix, the infinity-symbol, and the appropriate suffix.

  4. If the sub-picture contains a percent-sign, the number is multiplied by 100. If the sub-picture contains a per-mille-sign, the number is multiplied by 1000. The resulting number is referred to below as the adjusted number.

  5. The adjusted number 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 adjusted number (bearing in mind that if the adjusted number 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 adjusted number 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.

  6. The absolute value of the rounded number is converted to a string in decimal notation, with no insignificant leading or trailing zeroes, using the digits in the decimal-digit-family to represent the ten decimal digits, and the decimal-separator-sign to separate the integer part and the fractional part. (The value zero will at this stage be represented by a decimal-separator-sign on its own.)

  7. If the number of digits to the left of the decimal-separator-sign is less than minimum-integer-part-size, leading zero-digit-sign characters are added to pad out to that size.

  8. If the number of digits to the right of the decimal-separator-sign is less than minimum-fractional-part-size, trailing zero-digit-sign characters are added to pad out to that size.

  9. For each integer N in the integer-part-grouping-positions list, a grouping-separator-sign 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-separator-sign, if there is such a digit.

  10. For each integer N in the fractional-part-grouping-positions list, a grouping-separator-sign 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-separator-sign, if there is such a digit.

  11. If there is no decimal-separator-sign in the sub-picture, or if there are no digits to the right of the decimal-separator-sign character in the string, then the decimal-separator-sign character is removed from the string (it will be the rightmost character in the string).

  12. 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-2008], where they appear as Recommended operations in section 9. IEEE defines these functions for a variety of floating point formats; this specification defines them only for xs:double values. The IEEE specification applies with the following caveats:

  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:exp Returns the value of ex.
math:exp10 Returns the value of 10x.
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, expressed in radians.
math:cos Returns the cosine of the argument, expressed in radians.
math:tan Returns the tangent of the argument, expressed in radians.
math:asin Returns the arc sine of the argument, the result being in the range -π/2 to +π/2 radians.
math:acos Returns the arc cosine of the argument, the result being in the range zero to +π radians.
math:atan Returns the arc tangent of the argument, the result being in the range -π/2 to +π/2 radians.
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, the result being in the range -π to +π.

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

The expression 2*math:pi() returns 6.283185307179586e0.

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

4.8.2 math:exp

Summary

Returns the value of ex.

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

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

Rules

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

Otherwise the result is the mathematical constant e raised to the power of $arg, as defined in the [IEEE 754-2008] 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

The expression math:exp(()) returns ().

The expression math:exp(0) returns 1.0e0.

The expression math:exp(1) returns 2.7182818284590455e0.

The expression math:exp(2) returns 7.38905609893065e0.

The expression math:exp(-1) returns 0.36787944117144233e0.

The expression math:exp(math:pi()) returns 23.140692632779267e0.

The expression math:exp(xs:double('NaN')) returns xs:double('NaN').

The expression math:exp(xs:double('INF')) returns xs:double('INF').

The expression math:exp(xs:double('-INF')) returns 0.0e0.

4.8.3 math:exp10

Summary

Returns the value of 10x.

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

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

Rules

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

Otherwise the result is ten raised to the power of $arg, as defined in the [IEEE 754-2008] 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

The expression math:exp10(()) returns ().

The expression math:exp10(0) returns 1.0e0.

The expression math:exp10(1) returns 1.0e1.

The expression math:exp10(0.5) returns 3.1622776601683795e0.

The expression math:exp10(-1) returns 1.0e-1.

The expression math:exp10(xs:double('NaN')) returns xs:double('NaN').

The expression math:exp10(xs:double('INF')) returns xs:double('INF').

The expression math:exp10(xs:double('-INF')) returns 0.0e0.

4.8.4 math:log

Summary

Returns the natural logarithm of the argument.

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

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

Rules

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

Otherwise the result is the natural logarithm of $arg, as defined in the [IEEE 754-2008] 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 less than or equal to zero, the result is NaN.

Examples

The expression math:log(()) returns ().

The expression math:log(0) returns xs:double('-INF').

The expression math:log(math:exp(1)) returns 1.0e0.

The expression math:log(1.0e-3) returns -6.907755278982137e0.

The expression math:log(2) returns 0.6931471805599453e0.

The expression math:log(-1) returns xs:double('NaN').

The expression math:log(xs:double('NaN')) returns xs:double('NaN').

The expression math:log(xs:double('INF')) returns xs:double('INF').

The expression math:log(xs:double('-INF')) returns xs:double('NaN').

4.8.5 math:log10

Summary

Returns the base-ten logarithm of the argument.

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

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

Rules

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

Otherwise the result is the base-10 logarithm of $arg, as defined in the [IEEE 754-2008] 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 less than or equal to zero, the result is NaN.

Examples

The expression math:log10(()) returns ().

The expression math:log10(0) returns xs:double('-INF').

The expression math:log10(1.0e3) returns 3.0e0.

The expression math:log10(1.0e-3) returns -3.0e0.

The expression math:log10(2) returns 0.3010299956639812e0.

The expression math:log10(-1) returns xs:double('NaN').

The expression math:log10(xs:double('NaN')) returns xs:double('NaN').

The expression math:log10(xs:double('INF')) returns xs:double('INF').

The expression math:log10(xs:double('-INF')) returns xs:double('NaN').

4.8.6 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 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-2008] specification of the pown function applied to a 64-bit binary floating point value and an integer.

Otherwise $y is converted to an xs:double by numeric promotion, and the result is the value of $x raised to the power of $y as defined in the [IEEE 754-2008] specification of the pow function applied to two 64-bit binary floating point values.

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

The expression math:pow((), 93.7) returns ().

The expression math:pow(2, 3) returns 8.0e0.

The expression math:pow(-2, 3) returns -8.0e0.

The expression math:pow(2, -3) returns 0.125e0.

The expression math:pow(-2, -3) returns -0.125e0.

The expression math:pow(2, 0) returns 1.0e0.

The expression math:pow(0, 0) returns 1.0e0.

The expression math:pow(xs:double('INF'), 0) returns 1.0e0.

The expression math:pow(xs:double('NaN'), 0) returns 1.0e0.

The expression math:pow(-math:pi(), 0) returns 1.0e0.

The expression math:pow(0e0, 3) returns 0.0e0.

The expression math:pow(0e0, 4) returns 0.0e0.

The expression math:pow(-0e0, 3) returns -0.0e0.

The expression math:pow(0, 4) returns 0.0e0.

The expression math:pow(0e0, -3) returns xs:double('INF').

The expression math:pow(0e0, -4) returns xs:double('INF').

The expression math:pow(-0e0, -3) returns xs:double('-INF').

The expression math:pow(0, -4) returns xs:double('INF').

The expression math:pow(16, 0.5e0) returns 4.0e0.

The expression math:pow(16, 0.25e0) returns 2.0e0.

The expression math:pow(0e0, -3.0e0) returns xs:double('INF').

The expression math:pow(-0e0, -3.0e0) returns xs:double('-INF'). (Odd-valued whole numbers are treated specially).

The expression math:pow(0e0, -3.1e0) returns xs:double('INF').

The expression math:pow(-0e0, -3.1e0) returns xs:double('INF').

The expression math:pow(0e0, 3.0e0) returns 0.0e0.

The expression math:pow(-0e0, 3.0e0) returns -0.0e0. (Odd-valued whole numbers are treated specially).

The expression math:pow(0e0, 3.1e0) returns 0.0e0.

The expression math:pow(-0e0, 3.1e0) returns 0.0e0.

The expression math:pow(-1, xs:double('INF')) returns 1.0e0.

The expression math:pow(-1, xs:double('-INF')) returns 1.0e0.

The expression math:pow(1, xs:double('INF')) returns 1.0e0.

The expression math:pow(1, xs:double('-INF')) returns 1.0e0.

The expression math:pow(1, xs:double('NaN')) returns 1.0e0.

The expression math:pow(-2.5e0, 2.0e0) returns 6.25e0.

The expression math:pow(-2.5e0, 2.00000001e0) returns xs:double('NaN').

4.8.7 math:sqrt

Summary

Returns the non-negative square root of the argument.

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

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

Rules

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

Otherwise the result is the mathematical non-negative square root of $arg as defined in the [IEEE 754-2008] 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 $arg is positive or negative zero, positive infinity, or NaN, then the result is $arg. (Negative zero is the only case where the result can have negative sign)

Examples

The expression math:sqrt(()) returns ().

The expression math:sqrt(0.0e0) returns 0.0e0.

The expression math:sqrt(-0.0e0) returns -0.0e0.

The expression math:sqrt(1.0e6) returns 1.0e3.

The expression math:sqrt(2.0e0) returns 1.4142135623730951e0.

The expression math:sqrt(-2.0e0) returns xs:double('NaN').

The expression math:sqrt(xs:double('NaN')) returns xs:double('NaN').

The expression math:sqrt(xs:double('INF')) returns xs:double('INF').

The expression math:sqrt(xs:double('-INF')) returns xs:double('NaN').

4.8.8 math:sin

Summary

Returns the sine of the argument, expressed in radians.

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

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

Rules

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

Otherwise the result is the sine of $θ, treated as an angle in radians, as defined in the [IEEE 754-2008] specification of the sin function applied to 64-bit binary floating point values.

Notes

The treatment of the invalidOperation and underflow exceptions is defined in 4.2 Arithmetic operators on numeric values.

If $θ is positive or negative zero, the result is $θ.

If $θ 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

The expression math:sin(()) returns ().

The expression math:sin(0) returns 0.0e0.

The expression math:sin(-0.0e0) returns -0.0e0.

The expression math:sin(math:pi() div 2) returns 1.0e0.

The expression math:sin(-math:pi() div 2) returns -1.0e0.

The expression math:sin(math:pi()) returns 0.0e0 (approximately).

The expression math:sin(xs:double('NaN')) returns xs:double('NaN').

The expression math:sin(xs:double('INF')) returns xs:double('NaN').

The expression math:sin(xs:double('-INF')) returns xs:double('NaN').

4.8.9 math:cos

Summary

Returns the cosine of the argument, expressed in radians.

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

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

Rules

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

If $θ is positive or negative infinity, or NaN, then the result is NaN.

Otherwise the result is the cosine of $θ, treated as an angle in radians, as defined in the [IEEE 754-2008] specification of the cos function applied to 64-bit binary floating point values.

Notes

The treatment of the invalidOperation exception is defined in 4.2 Arithmetic operators on numeric values.

If $θ is positive or negative zero, the result is $θ.

If $θ 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

The expression math:cos(()) returns ().

The expression math:cos(0) returns 1.0e0.

The expression math:cos(-0.0e0) returns 1.0e0.

The expression math:cos(math:pi() div 2) returns 0.0e0 (approximately).

The expression math:cos(-math:pi() div 2) returns 0.0e0 (approximately).

The expression math:cos(math:pi()) returns -1.0e0.

The expression math:cos(xs:double('NaN')) returns xs:double('NaN').

The expression math:cos(xs:double('INF')) returns xs:double('NaN').

The expression math:cos(xs:double('-INF')) returns xs:double('NaN').

4.8.10 math:tan

Summary

Returns the tangent of the argument, expressed in radians.

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

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

Rules

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

Otherwise the result is the tangent of $θ, treated as an angle in radians, as defined in the [IEEE 754-2008] specification of the tan function applied to 64-bit binary floating point values.

Notes

The treatment of the invalidOperation and underflow exceptions is defined in 4.2 Arithmetic operators on numeric values.

If $θ is positive or negative infinity, or NaN, then the result is NaN.

Examples

The expression math:tan(()) returns ().

The expression math:tan(0) returns 0.0e0.

The expression math:tan(-0.0e0) returns -0.0e0.

The expression math:tan(math:pi() div 4) returns 1.0e0 (approximately).

The expression math:tan(-math:pi() div 4) returns -1.0e0 (approximately).

The expression math:tan(math:pi() div 2) returns 1.633123935319537E16 (approximately).

The expression math:tan(-math:pi() div 2) returns -1.633123935319537E16 (approximately).

The expression math:tan(math:pi()) returns 0.0e0 (approximately).

The expression math:tan(xs:double('NaN')) returns xs:double('NaN').

The expression math:tan(xs:double('INF')) returns xs:double('NaN').

The expression math:tan(xs:double('-INF')) returns xs:double('NaN').

4.8.11 math:asin

Summary

Returns the arc sine of the argument, the result being in the range -π/2 to +π/2 radians.

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

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

Rules

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

Otherwise the result is the arc sine of $θ, treated as an angle in radians, as defined in the [IEEE 754-2008] specification of the asin 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 $arg is positive or negative zero, the result is $arg.

If $arg is NaN, or if its absolute value is greater than one, then the result is NaN.

In other cases the result is an xs:double value representing an angle θ in radians in the range -π/2 <= $θ <= +π/2.

Examples

The expression math:asin(()) returns ().

The expression math:asin(0) returns 0.0e0.

The expression math:asin(-0.0e0) returns -0.0e0.

The expression math:asin(1.0e0) returns 1.5707963267948966e0 (approximately).

The expression math:asin(-1.0e0) returns -1.5707963267948966e0 (approximately).

The expression math:asin(2.0e0) returns xs:double('NaN').

The expression math:asin(xs:double('NaN')) returns xs:double('NaN').

The expression math:asin(xs:double('INF')) returns xs:double('NaN').

The expression math:asin(xs:double('-INF')) returns xs:double('NaN').

4.8.12 math:acos

Summary

Returns the arc cosine of the argument, the result being in the range zero to +π radians.

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

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

Rules

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

Otherwise the result is the arc cosine of $θ, treated as an angle in radians, as defined in the [IEEE 754-2008] specification of the acos 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 $arg 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 <= $θ <= +π.

Examples

The expression math:acos(()) returns ().

The expression math:acos(0) returns 1.5707963267948966e0 (approximately).

The expression math:acos(-0.0e0) returns 1.5707963267948966e0 (approximately).

The expression math:acos(1.0e0) returns 0.0e0.

The expression math:acos(-1.0e0) returns 3.141592653589793e0 (approximately).

The expression math:acos(2.0e0) returns xs:double('NaN').

The expression math:acos(xs:double('NaN')) returns xs:double('NaN').

The expression math:acos(xs:double('INF')) returns xs:double('NaN').

The expression math:acos(xs:double('-INF')) returns xs:double('NaN').

4.8.13 math:atan

Summary

Returns the arc tangent of the argument, the result being in the range -π/2 to +π/2 radians.

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

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

Rules

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

Otherwise the result is the arc tangent of $θ, treated as an angle in radians, as defined in the [IEEE 754-2008] specification of the atan 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 $arg is positive or negative zero, the result is $arg.

If $arg is NaN then the result is NaN.

In other cases the result is an xs:double value representing an angle θ in radians in the range -π/2 <= $θ <= +π/2.

Examples

The expression math:atan(()) returns ().

The expression math:atan(0) returns 0.0e0.

The expression math:atan(-0.0e0) returns -0.0e0.

The expression math:atan(1.0e0) returns 0.7853981633974483e0 (approximately).

The expression math:atan(-1.0e0) returns -0.7853981633974483e0 (approximately).

The expression math:atan(xs:double('NaN')) returns xs:double('NaN').

The expression math:atan(xs:double('INF')) returns 1.5707963267948966e0 (approximately).

The expression math:atan(xs:double('-INF')) returns -1.5707963267948966e0 (approximately).

4.8.14 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, the result being in the range -π to +π.

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-2008] specification of the atan2 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 either argument is NaN then the result is NaN.

If $y is positive and $x is positive and finite, then (subject to rules for overflow, underflow and approximation) the value of atan2($y, $x) is atan($y div $x).

If $y is positive and $x is negative and finite, then (subject to the same caveats) 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

The expression math:atan2(+0.0e0, 0.0e0) returns 0.0e0.

The expression math:atan2(-0.0e0, 0.0e0) returns -0.0e0.

The expression math:atan2(+0.0e0, -0.0e0) returns math:pi().

The expression math:atan2(-0.0e0, -0.0e0) returns -math:pi().

The expression math:atan2(-1, 0.0e0) returns -math:pi() div 2.

The expression math:atan2(+1, 0.0e0) returns +math:pi() div 2.

The expression math:atan2(-0.0e0, -1) returns -math:pi().

The expression math:atan2(+0.0e0, -1) returns +math:pi().

The expression math:atan2(-0.0e0, +1) returns -0.0e0.

The expression math:atan2(+0.0e0, +1) returns +0.0e0.

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. Each type whose name is indented is derived from the type whose name appears nearest above with one less level of indentation.

xs:string
xs:normalizedString
xs:token
xs:language
xs:NMTOKEN
xs:Name
xs:NCName
xs:ID
xs:IDREF
xs:ENTITY

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 Creates an xs:string from a sequence of ·codepoints·.
fn:string-to-codepoints Returns the sequence of ·codepoints· that constitute an xs:string value.

5.2.1 fn:codepoints-to-string

Summary

Creates an xs:string from a sequence of ·codepoints·.

Signature
fn:codepoints-to-string($arg 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 $arg. This will be the zero-length string if $arg is the empty sequence.

Error Conditions

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

Examples

The expression fn:codepoints-to-string((66, 65, 67, 72)) returns "BACH".

The expression fn:codepoints-to-string((2309, 2358, 2378, 2325)) returns "अशॊक".

The expression fn:codepoints-to-string(()) returns "".

The expression fn: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($arg 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 ·codepoints· of the corresponding ·character· in $arg.

If $arg is a zero-length string or the empty sequence, the function returns the empty sequence.

Examples

The expression fn:string-to-codepoints("Thérèse") returns (84, 104, 233, 114, 232, 115, 101).

5.3 Comparison of strings

Function Meaning
fn:compare Returns -1, 0, or 1, depending on whether $comparand1 collates before, equal to, or after $comparand2 according to the rules of a selected collation.
fn:codepoint-equal Returns true if two strings are equal, considered codepoint-by-codepoint.

5.3.1 Collations

A collation is a specification of the manner in which ·strings·s 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] 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

In the ideal case, a collation should treat two strings as equal if the two strings are identical after Unicode normalization. Thus, the [Character Model for the World Wide Web 1.0: Normalization] recommends that all strings be subjected to early Unicode normalization and some collations will raise runtime errors if they encounter strings that are not properly normalized. However, it is not possible to guarantee that all strings in all XML documents are, in fact, normalized, or that they are normalized in the same manner. In order to maximize interoperability of operations on XML documents in general, there may be collations that operate on unnormalized strings and other collations that implicitly normalize strings before comparing them. Applications may choose the kind of collation best suited for their needs. Note that collations based on the Unicode collation algorithm implicitly normalize strings before comparison and produce equivalent results regardless of a string's normalization.

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. If the collation is specified using a relative URI reference, it is resolved relative to the value of the Static Base URI property from the static context. 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.

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 [Locale Data Markup Language].

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

  • If both sequences are empty, the strings are equal

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

  • If the first integer in $A is less than the first integer in $B, then the string corresponding to $A is less than the string corresponding to $B.

  • If the first integer in $A is greater than the first integer in $B, then the string corresponding to $A is greater than the string corresponding to $B.

  • Otherwise (the first pair of integers are equal), the result is obtained by applying the same rules recursively to fn:subsequence($A, 2) and fn:subsequence($B, 2)

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 Choosing a collation

Many functions have two signatures, where one signature includes a $collation argument and the other omits this argument.

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

5.3.4 fn:compare

Summary

Returns -1, 0, or 1, depending on whether $comparand1 collates before, equal to, or after $comparand2 according to the rules of a selected collation.

Signatures
fn:compare($comparand1 as xs:string?, $comparand2 as xs:string?) as xs:integer?
fn:compare( $comparand1  as xs:string?,
$comparand2  as xs:string?,
$collation  as xs:string) 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

Returns -1, 0, or 1, depending on whether the value of the $comparand1 is respectively less than, equal to, or greater than the value of $comparand2, according to the rules of the collation that is used.

The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation.

If either $comparand1 or $comparand2 is the empty sequence, the function returns the empty sequence.

This function, called with the first signature, defines the semantics of the "eq", "ne", "gt", "lt", "le" and "ge" operators on xs:string values.

Examples

The expression fn:compare('abc', 'abc') returns 0.

The expression fn:compare('Strasse', 'Straße') returns 0. (Assuming the default collation includes provisions that equate "ss" and the (German) character "ß" ("sharp-s"). Otherwise, the returned value depends on the semantics of the default collation.).

The expression fn:compare('Strasse', 'Straße', 'http://example.com/deutsch') returns 0. (Assuming the collation identified by the URI http://example.com/deutsch includes provisions that equate "ss" and the (German) character "ß" ("sharp-s"). Otherwise, the returned value depends on the semantics of that collation.).

The expression fn:compare('Strassen', 'Straße') returns 1. (Assuming the default collation includes provisions that treat differences between "ss" and the (German) character "ß" ("sharp-s") with less strength than the differences between the base characters, such as the final "n". ).

5.3.5 fn:codepoint-equal

Summary

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

Signature
fn:codepoint-equal( $comparand1  as xs:string?,
$comparand2  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 the value of $comparand1 is equal to the value of $comparand2, 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

The expression fn:codepoint-equal("abcd", "abcd") returns true().

The expression fn:codepoint-equal("abcd", "abcd ") returns false().

The expression fn:codepoint-equal("", "") returns true().

The expression fn:codepoint-equal("", ()) returns ().

The expression fn:codepoint-equal((), ()) returns ().

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:concat Returns the concatenation of the string values of the arguments.
fn:string-join Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items.
fn:substring Returns the portion of the value of $sourceString beginning at the position indicated by the value of $start and continuing for the number of ·characters· indicated by the value of $length.
fn:string-length Returns the number of ·characters· in a string.
fn:normalize-space Returns the value of $arg with leading and trailing whitespace removed, and sequences of internal whitespace reduced to a single space character.
fn:normalize-unicode Returns the value of $arg 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 the value of $arg modified by replacing or removing individual characters.

Notes:

When the above operators and functions are applied to datatypes derived from xs:string, they are guaranteed to return values that are instances of xs:string, but the value might or might not be an instance of the particular subtype of xs:string to which they were applied.

The strings returned by fn:concat and fn:string-join are not guaranteed to be normalized. But see note in fn:concat.

5.4.1 fn:concat

Summary

Returns the concatenation of the string values of the arguments.

Operator Mapping

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

Signature
fn:concat( $arg1  as xs:anyAtomicType?,
$arg2  as xs:anyAtomicType?,
... ) as xs:string
Properties

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

Rules

This function accepts two or more xs:anyAtomicType arguments and casts each one to xs:string. The function returns the xs:string that is the concatenation of the values of its arguments after conversion. If any argument is the empty sequence, that argument is treated as the zero-length string.

The fn:concat function is specified to allow two or more arguments, which are concatenated together. This is the only function specified in this document that allows a variable number of arguments. This capability is retained for compatibility with [XML Path Language (XPath) Version 1.0].

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 COMBINING DIARESIS (Unicode codepoint U+0308) or "&#x0308;", will return:

"I plan to go to Mu?nchen in September"

where the "?" represents either the actual Unicode character COMBINING DIARESIS (Unicode codepoint U+0308) or "&#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 the "?" represents either the actual Unicode character COMBINING DIARESIS (Unicode codepoint U+0308) or "&#x0308;", will return:

"I plan to go to München in September"

This returned result is normalized in NFC.

Examples

The expression fn:concat('un', 'grateful') returns "ungrateful".

The expression fn:concat('Thy ', (), 'old ', "groans", "", ' ring', ' yet', ' in', ' my', ' ancient',' ears.') returns "Thy old groans ring yet in my ancient ears.".

The expression fn:concat('Ciao!',()) returns "Ciao!".

The expression fn:concat('Ingratitude, ', 'thou ', 'marble-hearted', ' fiend!') returns "Ingratitude, thou marble-hearted fiend!".

The expression fn:concat(01, 02, 03, 04, true()) returns "1234true".

The expression 10 || '/' || 6 returns "10/6".

5.4.2 fn:string-join

Summary

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

Signatures
fn:string-join($arg1 as xs:string*) as xs:string
fn:string-join($arg1 as xs:string*, $arg2 as xs:string) as xs:string
Properties

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

Rules

The effect of calling the single-argument version of this function is the same as calling the two-argument version with $arg2 set to a zero-length string.

The function returns an xs:string created by concatenating the items in the sequence $arg1, in order, using the value of $arg2 as a separator between adjacent items. If the value of $arg2 is the zero-length string, then the members of $arg1 are concatenated without a separator.

Notes

If the value of $arg1 is the empty sequence, the function returns the zero-length string.

Examples

The expression fn:string-join(('Now', 'is', 'the', 'time', '...'), ' ') returns "Now is the time ...".

The expression fn:string-join(('Blow, ', 'blow, ', 'thou ', 'winter ', 'wind!'), '') returns "Blow, blow, thou winter wind!".

The expression fn:string-join((), 'separator') returns "".

Assume a document:

<doc>
  <chap>
    <section/>
  </chap>
</doc>

with the <section> element as the context node, the [XML Path Language (XPath) 2.0] expression:

fn:string-join(ancestor-or-self::*/name(), '/')

returns "doc/chap/section"

5.4.3 fn:substring

Summary

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

Signatures
fn:substring($sourceString as xs:string?, $start as xs:double) as xs:string
fn:substring( $sourceString  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 the value of $sourceString is the empty sequence, the function returns the zero-length string.

Otherwise, the function returns a string comprising those ·characters· of $sourceString whose index position (counting from one) is greater than or equal to the value of $start (rounded to an integer), and (if $length is specified) less than the sum of $start and $length (both rounded to integers).

The characters returned do not extend beyond $sourceString. 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 $sourceString whose position $p satisfies:

fn:round($start) <= $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 $sourceString 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.

Examples

The expression fn:substring("motor car", 6) returns " car". (Characters starting at position 6 to the end of $sourceString are selected.).

The expression fn:substring("metadata", 4, 3) returns "ada". (Characters at positions greater than or equal to 4 and less than 7 are selected.).

The expression fn:substring("12345", 1.5, 2.6) returns "234". (Characters at positions greater than or equal to 2 and less than 5 are selected.).

The expression fn:substring("12345", 0, 3) returns "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.).

The expression fn:substring("12345", 5, -3) returns "". (Characters at positions greater than or equal to 5 and less than 2 are selected.).

The expression fn:substring("12345", -3, 5) returns "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.).

The expression fn:substring("12345", 0 div 0E0, 3) returns "". (Since 0 div 0E0 returns NaN, and NaN compared to any other number returns false, no characters are selected.).

The expression fn:substring("12345", 1, 0 div 0E0) returns "". (As above.).

The expression fn:substring((), 1, 3) returns "".

The expression fn:substring("12345", -42, 1 div 0E0) returns "12345". (Characters at positions greater than or equal to -42 and less than INF are selected.).

The expression fn:substring("12345", -1 div 0E0, 1 div 0E0) returns "". (Since the value of -INF + INF is NaN, no characters are selected.).

5.4.4 fn:string-length

Summary

Returns the number of ·characters· in a string.

Signatures
fn:string-length() as xs:integer
fn:string-length($arg as xs: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 the value of $arg.

Calling the zero-argument version of the function is equivalent to calling fn:string-length(fn:string(.)).

If the value of $arg is the empty sequence, the function returns the xs:integer value zero (0).

Error Conditions

If $arg is not specified and the context item is absentDM30, a dynamic error is raised: [err:XPDY0002]XP30.

Notes

Unlike some programming languages, a ·codepoint· greater than 65535 counts as one character, not two.

Examples

The expression fn:string-length("Harp not on that string, madam; that is past.") returns 45.

The expression fn:string-length(()) returns 0.

5.4.5 fn:normalize-space

Summary

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

Signatures
fn:normalize-space() as xs:string
fn:normalize-space($arg as xs: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 the value of $arg is the empty sequence, the function returns the zero-length string.

The function returns a string constructed by stripping leading and trailing whitespace from the value of $arg, and replacing sequences of one or more adjacent whitespace characters with a single space, #x20.

The whitespace characters are defined in the metasymbol S (Production 3) of [REC-xml].

If no argument is supplied, then $arg defaults to the string value (calculated using fn:string) of the context item (.).

Error Conditions

If no argument is supplied and the context item is absentDM30 then a dynamic error is raised: [err:XPDY0002]XP30.

Notes

The definition of whitespace is unchanged in [Extensible Markup Language (XML) 1.1 Recommendation].

Examples

The expression fn:normalize-space(" The    wealthy curled darlings                                         of    our    nation. ") returns "The wealthy curled darlings of our nation.".

The expression fn:normalize-space(()) returns "".

5.4.6 fn:normalize-unicode

Summary

Returns the value of $arg after applying Unicode normalization.

Signatures
fn:normalize-unicode($arg as xs:string?) as xs:string
fn:normalize-unicode( $arg  as xs:string?,
$normalizationForm  as xs:string) as xs:string
Properties

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

Rules

If the value of $arg is the empty sequence, the function returns the zero-length string.

If the single-argument version of the function is used, the result is the same as calling the two-argument version with $normalizationForm set to the string "NFC".

Otherwise, the function returns the value of $arg normalized according to the rules of the normalization form identified by the value of $normalizationForm.

The effective value of $normalizationForm is the value of the expression fn:upper-case(fn:normalize-space($normalizationForm)).

  • If the effective value of $normalizationForm is "NFC", then the function returns the value of $arg converted to Unicode Normalization Form C (NFC).

  • If the effective value of $normalizationForm is "NFD", then the function returns the value of $arg converted to Unicode Normalization Form D (NFD).

  • If the effective value of $normalizationForm is "NFKC", then the function returns the value of $arg in Unicode Normalization Form KC (NFKC).

  • If the effective value of $normalizationForm is "NFKD", then the function returns the value of $arg converted to Unicode Normalization Form KD (NFKD).

  • If the effective value of $normalizationForm is "FULLY-NORMALIZED", then the function returns the value of $arg converted to fully normalized form.

  • If the effective value of $normalizationForm is the zero-length string, no normalization is performed and $arg 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 [Unicode Normalization Forms].

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 [Unicode Normalization Forms], and (b) it does not start with a composing character.

  • A composing character is a character that is one or both of the following:

  • 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 [Unicode Normalization Forms] 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 $normalizationForm argument is not one of the values supported by the implementation.

5.4.7 fn:upper-case

Summary

Converts a string to upper case.

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

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

Rules

If the value of $arg is the empty sequence, the zero-length string is returned.

Otherwise, the function returns the value of $arg 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($arg)) is not guaranteed to return $arg, nor is fn:upper-case(fn:lower-case($arg)). The Latin small letter dotless i (as used in Turkish) is perhaps the most prominent lower-case letter which will not round-trip. The Latin capital letter i with dot above is the most prominent upper-case letter which will not round trip; there are others, such as Latin capital letter Sharp S (#1E9E) which is 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

The expression fn:upper-case("abCd0") returns "ABCD0".

5.4.8 fn:lower-case

Summary

Converts a string to lower case.

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

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

Rules

If the value of $arg is the empty sequence, the zero-length string is returned.

Otherwise, the function returns the value of $arg 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($arg)) is not guaranteed to return $arg, nor is fn:upper-case(fn:lower-case($arg)). The Latin small letter dotless i (as used in Turkish) is perhaps the most prominent lower-case letter which will not round-trip. The Latin capital letter i with dot above is the most prominent upper-case letter which will not round trip; there are others, such as Latin capital letter Sharp S (#1E9E) which is 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

The expression fn:lower-case("ABc!D") returns "abc!d".

5.4.9 fn:translate

Summary

Returns the value of $arg modified by replacing or removing individual characters.

Signature
fn:translate( $arg  as xs:string?,
$mapString  as xs:string,
$transString  as xs:string) as xs:string
Properties

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

Rules

If the value of $arg is the empty sequence, the function returns the zero-length string.

Otherwise, the function returns a result string constructed by processing each ·character· in the value of $arg, in order, according to the following rules:

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

  2. If the character first appears in the value of $mapString at some position M, where the value of $transString is M or more characters in length, then the character at position M in $transString is added to the result string.

  3. If the character first appears in the value of $mapString at some position M, where the value of $transString is less than M characters in length, then the character is omitted from the result string.

Notes

If $mapString is the zero-length string then the function returns $arg unchanged.

If a character occurs more than once in $mapString, then the first occurrence determines the action taken.

If $transString is longer than $mapString, the excess characters are ignored.

Examples

The expression fn:translate("bar","abc","ABC") returns "BAr".

The expression fn:translate("--aaa--","abc-","ABC") returns "AAA".

The expression fn:translate("abcdabc", "abc", "AB") returns "ABdAB".

5.5 Functions based on substring matching

The functions described in the section examine a string $arg1 to see whether it contains another string $arg2 as a substring. The result depends on whether $arg2 is a substring of $arg1, and if so, on the range of ·characters· in $arg1 which $arg2 matches.

When the ·Unicode codepoint collation· is used, this simply involves determining whether $arg1 contains a contiguous sequence of characters whose ·codepoints· are the same, one for one, with the codepoints of the characters in $arg2.

When a collation is specified, the rules are more complex.

All collations support the capability of deciding whether two ·strings· are considered equal, and if not, which of the strings should be regarded as preceding the other. For functions such as fn:compare, this is all that is required. For other functions, such as fn:contains, the collation needs to support an additional property: it must be able to decompose the string into a sequence of collation units, each unit consisting of one or more characters, such that two strings can be compared by pairwise comparison of these units. ("collation unit" is equivalent to "collation element" as defined in [Unicode Collation Algorithm].) 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 [Unicode Collation Algorithm]. 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 [Unicode Collation Algorithm]). 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 $arg1 contains $arg2 as a substring, taking collations into account.
fn:starts-with Returns true if the string $arg1 contains $arg2 as a leading substring, taking collations into account.
fn:ends-with Returns true if the string $arg1 contains $arg2 as a trailing substring, taking collations into account.
fn:substring-before Returns the part of $arg1 that precedes the first occurrence of $arg2, taking collations into account.
fn:substring-after Returns the part of $arg1 that follows the first occurrence of $arg2, taking collations into account.

5.5.1 fn:contains

Summary

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

Signatures
fn:contains($arg1 as xs:string?, $arg2 as xs:string?) as xs:boolean
fn:contains( $arg1  as xs:string?,
$arg2  as xs:string?,
$collation  as xs:string) 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 the value of $arg1 or $arg2 is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.

If the value of $arg2 is the zero-length string, then the function returns true.

If the value of $arg1 is the zero-length string, the function returns false.

The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation.

The function returns an xs:boolean indicating whether or not the value of $arg1 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 the value of $arg2, according to the collation that is used.

Note:

Minimal match is defined in [Unicode Collation Algorithm].

Error Conditions

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

Examples

The collation used in these examples, http://example.com/CollationA is a collation in which both "-" and "*" are ignorable collation units.

"Ignorable collation unit" is equivalent to "ignorable collation element" in [Unicode Collation Algorithm].

The expression fn:contains ( "tattoo", "t") returns true().

The expression fn:contains ( "tattoo", "ttt") returns false().

The expression fn:contains ( "", ()) returns true(). (The first rule is applied, followed by the second rule.).

The expression fn:contains ( "abcdefghi", "-d-e-f-", "http://example.com/CollationA") returns true().

The expression fn:contains ( "a*b*c*d*e*f*g*h*i*", "d-ef-", "http://example.com/CollationA") returns true().

The expression fn:contains ( "abcd***e---f*--*ghi", "def", "http://example.com/CollationA") returns true().

The expression fn:contains ( (), "--***-*---", "http://example.com/CollationA") returns 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 $arg1 contains $arg2 as a leading substring, taking collations into account.

Signatures
fn:starts-with($arg1 as xs:string?, $arg2 as xs:string?) as xs:boolean
fn:starts-with( $arg1  as xs:string?,
$arg2  as xs:string?,
$collation  as xs:string) 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 the value of $arg1 or $arg2 is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.

If the value of $arg2 is the zero-length string, then the function returns true. If the value of $arg1 is the zero-length string and the value of $arg2 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.3 Choosing a collation.

The function returns an xs:boolean indicating whether or not the value of $arg1 starts with a sequence of collation units that provides a match to the collation units of $arg2 according to the collation that is used.

Note:

Match is defined in [Unicode Collation Algorithm].

Error Conditions

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

Examples

The collation used in these examples, http://example.com/CollationA is a collation in which both "-" and "*" are ignorable collation units.

"Ignorable collation unit" is equivalent to "ignorable collation element" in [Unicode Collation Algorithm].

The expression fn:starts-with("tattoo", "tat") returns true().

The expression fn:starts-with ( "tattoo", "att") returns false().

The expression fn:starts-with ((), ()) returns true().

The expression fn:starts-with ( "abcdefghi", "-a-b-c-", "http://example.com/CollationA") returns true().

The expression fn:starts-with ( "a*b*c*d*e*f*g*h*i*", "a-bc-", "http://example.com/CollationA") returns true().

The expression fn:starts-with ( "abcd***e---f*--*ghi", "abcdef", "http://example.com/CollationA") returns true().

The expression fn:starts-with ( (), "--***-*---", "http://example.com/CollationA") returns true(). (The second argument contains only ignorable collation units and is equivalent to the zero-length string.).

The expression fn:starts-with ( "-abcdefghi", "-abc", "http://example.com/CollationA") returns true().

5.5.3 fn:ends-with

Summary

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

Signatures
fn:ends-with($arg1 as xs:string?, $arg2 as xs:string?) as xs:boolean
fn:ends-with( $arg1  as xs:string?,
$arg2  as xs:string?,
$collation  as xs:string) 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 the value of $arg1 or $arg2 is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.

If the value of $arg2 is the zero-length string, then the function returns true. If the value of $arg1 is the zero-length string and the value of $arg2 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.3 Choosing a collation.

The function returns an xs:boolean indicating whether or not the value of $arg1 starts with a sequence of collation units that provides a match to the collation units of $arg2 according to the collation that is used.

Note:

Match is defined in [Unicode Collation Algorithm].

Error Conditions

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

Examples

The collation used in these examples, http://example.com/CollationA is a collation in which both "-" and "*" are ignorable collation units.

"Ignorable collation unit" is equivalent to "ignorable collation element" in [Unicode Collation Algorithm].

The expression fn:ends-with ( "tattoo", "tattoo") returns true().

The expression fn:ends-with ( "tattoo", "atto") returns false().

The expression fn:ends-with ((), ()) returns true().

The expression fn:ends-with ( "abcdefghi", "-g-h-i-", "http://example.com/CollationA") returns true().

The expression fn:ends-with ( "abcd***e---f*--*ghi", "defghi", "http://example.com/CollationA") returns true().

The expression fn:ends-with ( "abcd***e---f*--*ghi", "defghi", "http://example.com/CollationA") returns true().

The expression fn:ends-with ( (), "--***-*---", "http://example.com/CollationA") returns true(). (The second argument contains only ignorable collation units and is equivalent to the zero-length string.).

The expression fn:ends-with ( "abcdefghi", "ghi-", "http://example.com/CollationA") returns true().

5.5.4 fn:substring-before

Summary

Returns the part of $arg1 that precedes the first occurrence of $arg2, taking collations into account.

Signatures
fn:substring-before($arg1 as xs:string?, $arg2 as xs:string?) as xs:string
fn:substring-before( $arg1  as xs:string?,
$arg2  as xs:string?,
$collation  as xs:string) 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 the value of $arg1 or $arg2 is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.

If the value of $arg2 is the zero-length string, then the function returns the zero-length string.

If the value of $arg1 does not contain a string that is equal to the value of $arg2, then the function returns the zero-length string.

The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation.

The function returns the substring of the value of $arg1 that precedes in the value of $arg1 the first occurrence of a sequence of collation units that provides a minimal match to the collation units of $arg2 according to the collation that is used.

Note:

Minimal match is defined in [Unicode Collation Algorithm].

Error Conditions

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

Examples

The collation used in these examples, http://example.com/CollationA is a collation in which both "-" and "*" are ignorable collation units.

"Ignorable collation unit" is equivalent to "ignorable collation element" in [Unicode Collation Algorithm].

The expression fn:substring-before ( "tattoo", "attoo") returns "t".

The expression fn:substring-before ( "tattoo", "tatto") returns "".

The expression fn:substring-before ((), ()) returns "".

The expression fn:substring-before ( "abcdefghi", "--d-e-", "http://example.com/CollationA") returns "abc".

The expression fn:substring-before ( "abc--d-e-fghi", "--d-e-", "http://example.com/CollationA") returns "abc--".

The expression fn:substring-before ( "a*b*c*d*e*f*g*h*i*", "***cde", "http://example.com/CollationA") returns "a*b*".

The expression fn:substring-before ( "Eureka!", "--***-*---", "http://example.com/CollationA") returns "". (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 $arg1 that follows the first occurrence of $arg2, taking collations into account.

Signatures
fn:substring-after($arg1 as xs:string?, $arg2 as xs:string?) as xs:string
fn:substring-after( $arg1  as xs:string?,
$arg2  as xs:string?,
$collation  as xs:string) 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 the value of $arg1 or $arg2 is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.

If the value of $arg2 is the zero-length string, then the function returns the value of $arg1.

If the value of $arg1 does not contain a string that is equal to the value of $arg2, then the function returns the zero-length string.

The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation.

The function returns the substring of the value of $arg1 that follows in the value of $arg1 the first occurrence of a sequence of collation units that provides a minimal match to the collation units of $arg2 according to the collation that is used.

Note:

Minimal match is defined in [Unicode Collation Algorithm].

Error Conditions

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

Examples

The collation used in these examples, http://example.com/CollationA is a collation in which both "-" and "*" are ignorable collation units.

"Ignorable collation unit" is equivalent to "ignorable collation element" in [Unicode Collation Algorithm].

The expression fn:substring-after("tattoo", "tat") returns "too".

The expression fn:substring-after("tattoo", "tattoo") returns "".

The expression fn:substring-after((), ()) returns "".

The expression fn:substring-after("abcdefghi", "--d-e-", "http://example.com/CollationA") returns "fghi".

The expression fn:substring-after("abc--d-e-fghi", "--d-e-", "http://example.com/CollationA") returns "-fghi".

The expression fn:substring-after ( "a*b*c*d*e*f*g*h*i*", "***cde***", "http://example.com/CollationA") returns "*f*g*h*i*".

The expression fn:substring-after ( "Eureka!", "--***-*---", "http://example.com/CollationA") returns "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 three functions described in this section make use of a regular expression syntax for pattern matching. This is described below.

Function Meaning
fn:matches Returns true if the supplied string matches a given regular expression.
fn:replace Returns a string produced from the input string by replacing any substrings that match a given regular expression with a supplied replacement string.
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 [Unicode Regular Expressions] 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 following additions:

  • 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 | "^" | "$"

  • Reluctant quantifiers are supported. They are indicated by a " ? " following a quantifier. Specifically:

    • X?? matches X, once or not at all

    • X*? matches X, zero or more times

    • X+? matches X, one or more times

    • X{n}? matches X, exactly n times

    • X{n,}? matches X, at least n times

    • X{n,m}? matches X, at least n times, but not more than m times

    The effect of these quantifiers is that the regular expression matches the shortest possible substring consistent with the match as a whole succeeding. Without the " ? ", the regular expression matches the longest possible substring.

    To achieve this, the production in [XML Schema Part 2: Datatypes Second Edition]:

    [4] quantifier ::= [?*+] | ( '{' quantity '}' )

    is changed to:

    [4] quantifier ::= ( [?*+] | ( '{' quantity '}' ) ) '?'?

    (In the XSD 1.1 version of the regular expression grammar, this rule is unchanged, but is renumbered [67])

    Note:

    Reluctant quantifiers have no effect on the results of the boolean fn:matches function, since this function is only interested in discovering whether a match exists, and not where it exists.

  • Sub-expressions (groups) within the regular expression are recognized. The regular expression syntax defined by [XML Schema Part 2: Datatypes Second Edition] allows a regular expression to contain parenthesized sub-expressions, but attaches no special significance to them. Some operations associated with regular expressions (for example, back-references, and the fn:replace function) allow access to the parts of the input string that matched a sub-expression (called captured substrings). The sub-expressions are numbered according to the position of the opening parenthesis in left-to-right order within the top-level regular expression: the first opening parenthesis identifies captured substring 1, the second identifies captured substring 2, and so on. 0 identifies the substring captured by the entire regular expression.

    When parentheses are used in a part of the regular expression that 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.

    Non-capturing groups are also recognized. These are indicated by the syntax (?:xxxx). 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.)

    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 that number the groups within a regular expression, for example the fn:replace function.

  • 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 NN or more unescaped opening parentheses. The regular expression is invalid if a back-reference refers to a subexpression that does not exist or whose closing right parenthesis occurs after the back-reference.

    A back-reference matches the string that was matched by the Nth capturing subexpression within the regular expression, that is, the parenthesized subexpression whose opening left parenthesis is the Nth unescaped left parenthesis within the regular expression. 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 is matched by the Nth capturing subexpression, 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.

  • Single character escapes are extended to allow the $ character to be escaped. The following production is changed:

    [24]SingleCharEsc ::= '\' [nrt\|.?*+(){}#x2D#x5B#x5D#x5E]

    to

    [24]SingleCharEsc ::= '\' [nrt\|.?*+(){}$#x2D#x5B#x5D#x5E]

    (In the XSD 1.1 version of the regular expression grammar, the production rule for SingleCharEsc is unchanged, but is renumbered [84])

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

Note:

In [XML Schema 1.1 Part 2: Datatypes] 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.

5.6.1.1 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. 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 "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-Z and all the letters a-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()

  • q: if present, all characters in the regular expression are treated as representing themselves, not as metacharacters. In effect, every character that would normally have a special meaning in a regular expression is implicitly escaped by preceding it with a backslash.

    Furthermore, when this flag is present, the characters $ and \ have no special significance when used in the replacement string supplied to the fn:replace function.

    This flag can be used in conjunction with the i flag. If it is used together with the m, s, or x flag, that flag has no effect.

    Examples:

    fn:tokenize("12.3.5.6", ".", "q") returns ("12", "3", "5", "6")

    fn:replace("a\b\c", "\", "\\", "q") returns "a\\b\\c"

    fn:replace("a/b/c", "/", "$", "q") returns "a$b$c"

    fn:matches("abcd", ".*", "q") returns false()

    fn:matches("Mr. B. Obama", "B. OBAMA", "iq") returns true()

5.6.2 fn:matches

Summary

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

Signatures
fn:matches($input as xs:string?, $pattern as xs:string) as xs:boolean
fn:matches( $input  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

The effect of calling the first version of this function (omitting the argument $flags) is the same as the effect of calling the second version with the $flags argument set to a zero-length string. Flags are defined in 5.6.1.1 Flags.

If $input is the empty sequence, it is interpreted as the zero-length string.

The function returns true if $input or some substring of $input matches the regular expression supplied as $pattern. Otherwise, the function returns false. The matching rules are influenced by the value of $flags if present.

Error Conditions

A dynamic error is raised [err:FORX0002] if the value of $pattern is invalid according to the rules described in 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 5.6.1.1 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 code points; it takes no account of collations.

Examples

The expression fn:matches("abracadabra", "bra") returns true().

The expression fn:matches("abracadabra", "^a.*a$") returns true().

The expression fn:matches("abracadabra", "^bra") returns false().

Given the source document:

let $poem :=

<poem author="Wilhelm Busch"> 
Kaum hat dies der Hahn gesehen, 
Fängt er auch schon an zu krähen: 
Kikeriki! Kikikerikih!! 
Tak, tak, tak! - da kommen sie. 
</poem>

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

The expression fn:matches($poem, "Kaum.*krähen") returns false().

The expression fn:matches($poem, "Kaum.*krähen", "s") returns true().

The expression fn:matches($poem, "^Kaum.*gesehen,$", "m") returns true().

The expression fn:matches($poem, "^Kaum.*gesehen,$") returns false().

The expression fn:matches($poem, "kiki", "i") returns true().

5.6.3 fn:replace

Summary

Returns a string produced from the input string by replacing any substrings that match a given regular expression with a supplied replacement string.

Signatures
fn:replace( $input  as xs:string?,
$pattern  as xs:string,
$replacement  as xs:string) as xs:string
fn:replace( $input  as xs:string?,
$pattern  as xs:string,
$replacement  as xs:string,
$flags  as xs:string) as xs:string
Properties

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

Rules

The effect of calling the first version of this function (omitting the argument $flags) is the same as the effect of calling the second version with the $flags argument set to a zero-length string. Flags are defined in 5.6.1.1 Flags.

The $flags argument is interpreted in the same manner as for the fn:matches function.

If $input is the empty sequence, it is interpreted as the zero-length string.

The function returns the xs:string that is obtained by replacing each non-overlapping substring of $input that matches the given $pattern with an occurrence of the $replacement string.

If two overlapping substrings of $input both match the $pattern, then only the first one (that is, the one whose first ·character· comes first in the $input string) is replaced.

If the q flag is present, 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 $input 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:

 fn: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.1 Regular expression syntax.

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.

A dynamic error is raised [err:FORX0004] if the value of $replacement contains a "$" character that is not immediately followed by a digit 0-9 and not immediately preceded by a "\".

A dynamic error is raised [err:FORX0004] if the value of $replacement contains a "\" character that is not part of a "\\" pair, unless it is immediately followed by a "$" character.

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

The expression replace("abracadabra", "bra", "*") returns "a*cada*".

The expression replace("abracadabra", "a.*a", "*") returns "*".

The expression replace("abracadabra", "a.*?a", "*") returns "*c*bra".

The expression replace("abracadabra", "a", "") returns "brcdbr".

The expression replace("abracadabra", "a(.)", "a$1$1") returns "abbraccaddabbra".

The expression replace("abracadabra", ".*?", "$1") raises an error, because the pattern matches the zero-length string

The expression replace("AAAA", "A+", "b") returns "b".

The expression replace("AAAA", "A+?", "b") returns "bbbb".

The expression replace("darted", "^(.*?)d(.*)$", "$1c$2") returns "carted". (The first d is replaced.).

5.6.4 fn:tokenize

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.

Signatures
fn:tokenize($input as xs:string?, $pattern as xs:string) as xs:string*
fn:tokenize( $input  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 effect of calling the first version of this function (omitting the argument $flags) is the same as the effect of calling the second version with the $flags argument set to a zero-length string. Flags are defined in 5.6.1.1 Flags.

The $flags argument is interpreted in the same way as for the fn:matches function.

If $input is the empty sequence, or if $input is the zero-length string, the function returns the empty sequence.

The function returns a sequence of strings formed by breaking the $input 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 $input string, the result sequence will start with a zero-length string. Zero-length strings will also occur in the result sequence if a separator occurs at the end of the $input 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 $input string, then the match that is chosen is the first. For example:

 fn: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.1 Regular expression syntax.

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.

Examples

The expression fn:tokenize("The cat sat on the mat", "\s+") returns ("The", "cat", "sat", "on", "the", "mat").

The expression fn:tokenize("1, 15, 24, 50", ",\s*") returns ("1", "15", "24", "50").

The expression fn:tokenize("1,15,,24,50,", ",") returns ("1", "15", "", "24", "50", "").

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

The expression fn:tokenize("Some unparsed <br> HTML <BR> text", "\s*<br>\s*", "i") returns ("Some unparsed", "HTML", "text").

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

Signatures
fn:analyze-string( $input  as xs:string?,
$pattern  as xs:string) as element(fn:analyze-string-result)
fn:analyze-string( $input  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

The effect of calling the first version of this function (omitting the argument $flags) is the same as the effect of calling the second version with the $flags argument set to a zero-length string. Flags are defined in 5.6.1.1 Flags.

The $flags argument is interpreted in the same way as for the fn:matches function.

If $input is the empty sequence the function behaves as if $input 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 $input 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·.

The base URI of the element nodes in the result is ·implementation dependent·

A schema is defined for the structure of the returned element, containing the definitions below. The returned element and its descendants will have type annotations obtained by validating the returned element against this schema, unless the function is used in an environment where type annotations are not supported (for example, a Basic XSLT Processor), in which case the elements will all be annotated as xs:untyped and the attributes as xs:untypedAtomic.

Note:

A free-standing copy of this schema can be found at 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"> 

    <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>
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.1 Regular expression syntax.

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

The declarations and definitions in the above 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.

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.

The expression fn:analyze-string("The cat sat on the mat.", "\w+") returns <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>.

The expression fn:analyze-string("2008-12-03", "^(\d+)\-(\d+)\-(\d+)$") returns <analyze-string-result xmlns="http://www.w3.org/2005/xpath-functions"> <match><group nr="1">2008</group>-<group nr="2">12</group>-<group nr="3">03</group></match> </analyze-string-result>.

The expression fn:analyze-string("A1,C15,,D24, X50,", "([A-Z])([0-9]+)") returns <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>.

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

Summary

Resolves a relative IRI reference against an absolute IRI.

Signatures
fn:resolve-uri($relative as xs:string?) as xs:anyURI?
fn:resolve-uri($relative as xs:string?, $base as xs:string) as xs:anyURI?
Properties

The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on static base uri.

The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If the second argument is absent, the effect is the same as calling the two-argument function with the value of fn:static-base-uri() as the second argument.

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.

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

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

Otherwise, the function resolves the relative IRI reference $relative 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 $relative 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 $relative 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, if it is a non-hierarchic URI, or if it contains a fragment identifier).

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.

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($uri-part as xs:string?) as xs:string
Properties

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

Rules

If $uri-part 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 $uri-part. 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-Z, the digits 0-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

The expression fn:encode-for-uri("http://www.example.com/00/Weather/CA/Los%20Angeles#ocean") returns "http%3A%2F%2Fwww.example.com%2F00%2FWeather%2FCA%2FLos%2520Angeles%23ocean". (This is probably not what the user intended because all of the delimiters have been encoded.).

The expression concat("http://www.example.com/", encode-for-uri("~bébé")) returns "http://www.example.com/~b%C3%A9b%C3%A9".

The expression concat("http://www.example.com/", encode-for-uri("100% organic")) returns "http://www.example.com/100%25%20organic".

6.3 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($iri as xs:string?) as xs:string
Properties

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

Rules

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

Otherwise, the function converts the value of $iri 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 $iri 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: "<", ">", " " " (double quote), space, "{", "}", "|", "\", "^", and "`". Since these characters should not appear in an IRI, if they do appear in $iri they will be percent-encoded. In addition, characters outside the range x20-x7E will be percent-encoded because they are invalid in a URI.

Since this function does not escape the PERCENT SIGN "%" and this character is not allowed in data within a URI, users wishing to convert character strings (such as file names) that include "%" to a URI should manually escape "%" by replacing it with "%25".

Examples

The expression fn:iri-to-uri ("http://www.example.com/00/Weather/CA/Los%20Angeles#ocean") returns "http://www.example.com/00/Weather/CA/Los%20Angeles#ocean".

The expression fn:iri-to-uri ("http://www.example.com/~bébé") returns "http://www.example.com/~b%C3%A9b%C3%A9".

6.4 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($uri as xs:string?) as xs:string
Properties

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

Rules

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

Otherwise, the function escapes all ·characters· except printable characters of the US-ASCII coded character set, specifically the ·codepoints· between 32 and 126 (decimal) inclusive. Each character in $uri to be escaped is replaced by an escape sequence, which is formed by encoding the character as a sequence of octets in UTF-8, and then representing each of these octets in the form %HH, where HH is the hexadecimal representation of the octet. This function must always generate hexadecimal values using the upper-case letters A-F.

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

The expression fn:escape-html-uri ("http://www.example.com/00/Weather/CA/Los Angeles#ocean") returns "http://www.example.com/00/Weather/CA/Los Angeles#ocean".

The expression fn:escape-html-uri ("javascript:if (navigator.browserLanguage == 'fr') window.open('http://www.example.com/~bébé');") returns "javascript:if (navigator.browserLanguage == 'fr') window.open('http://www.example.com/~b%C3%A9b%C3%A9');".

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

The expression fn:true() returns 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

The expression fn:false() returns xs:boolean(0).

7.2 Operators on Boolean values

The following functions define the semantics of operators on boolean values in [XQuery 3.0: An XML Query Language] and [XML Path Language (XPath) 3.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.
op:boolean-greater-than Returns true if the first argument is true and the second is false.

The ordering operators op:boolean-less-than and op:boolean-greater-than are 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 on 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 on 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.2.3 op:boolean-greater-than

Summary

Returns true if the first argument is true and the second is false.

Operator Mapping

Defines the semantics of the "gt" operator on xs:boolean values. Also used in the definition of the "le" operator.

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

The function call op:boolean-greater-than($A, $B) is defined to return the same result as op:boolean-less-than($B, $A)

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 $arg.
fn:not Returns true if the effective boolean value of $arg is false, or false if it is true.

7.3.1 fn:boolean

Summary

Computes the effective boolean value of the sequence $arg.

Signature
fn:boolean($arg 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 XP30.

  • If $arg is the empty sequence, fn:boolean returns false.

  • If $arg is a sequence whose first item is a node, fn:boolean returns true.

  • If $arg is a singleton value of type xs:boolean or a derived from xs:boolean, fn:boolean returns $arg.

  • If $arg is a singleton value of type xs:string or a type derived from xs:string, xs:anyURI or a type derived from xs:anyURI or xs:untypedAtomic, fn:boolean returns false if the operand value has zero length; otherwise it returns true.

  • If $arg is a singleton value of any numeric type or a type derived from a numeric type, fn:boolean returns false if the operand value is NaN or is numerically equal to zero; otherwise it returns true.

  • In all other cases, fn:boolean raises a type error [err:FORG0006].

Notes

The result of this function is not necessarily the same as $arg 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

let $abc := ("a", "b", "")

fn:boolean($abc) raises a type error [err:FORG0006].

The expression fn:boolean($abc[1]) returns true().

The expression fn:boolean($abc[0]) returns false().

The expression fn:boolean($abc[3]) returns false().

7.3.2 fn:not

Summary

Returns true if the effective boolean value of $arg is false, or false if it is true.

Signature
fn:not($arg as item()*) as xs:boolean
Properties

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

Rules

The value of $arg 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

The expression fn:not(fn:true()) returns false().

The expression fn:not("false") returns false().

8 Functions and operators on durations

Operators are defined on the following type:

and on the two defined subtypes (see 8.1 Two totally ordered subtypes of duration):

No ordering relation is defined on xs:duration values. Two xs:duration values may however be compared for equality.

Operations on durations (including equality comparison, casting to string, and extraction of components) all treat the duration as normalized. This means that the seconds and minutes components will always be less than 60, the hours component less than 24, and the months component less than 12. Thus, for example, a duration of 120 seconds always gives the same result as a duration of two minutes.

Conditions such as underflow and overflow may occur with arithmetic on durations: see 9.7.1 Limits and precision

Note:

This means that in practice, the information content of an xs:duration value can be reduced to an xs:integer number of months, and an xs:decimal number of seconds. For the two defined subtypes this is further simplified so that one of these two components is fixed at zero. Operations such as comparison of durations and arithmetic on durations can be expressed in terms of numeric operations applied to these two components.

8.1 Two totally ordered subtypes of duration

Two totally ordered subtypes of xs:duration are defined in Section 2.7 Schema Information DM30 specification using the mechanisms described in [XML Schema Part 2: Datatypes Second Edition] for defining user-defined types. Additional details about these types is given below.

Note:

These types were not defined in XSD 1.0, but they are defined in the current draft of XSD 1.1. The description given here is believed to be equivalent to that in XSD 1.1, and will become non-normative when XSD 1.1 reaches Recommendation status.

8.1.1 xs:yearMonthDuration

[Definition] xs:yearMonthDuration is derived from xs:duration by restricting its lexical representation to contain only the year and month components. The value space of xs:yearMonthDuration is the set of xs:integer month values. The year and month components of xs:yearMonthDuration correspond to the Gregorian year and month components defined in section 5.5.3.2 of [ISO 8601], respectively.

8.1.1.1 Lexical representation

The lexical representation for xs:yearMonthDuration is the [ISO 8601] reduced format PnYnM, where nY represents the number of years and nM the number of months. The values of the years and months components are not restricted but allow an arbitrary unsigned xs:integer.

An optional preceding minus sign ('-') is allowed to indicate a negative duration. If the sign is omitted a positive duration is indicated. To indicate a xs:yearMonthDuration of 1 year, 2 months, one would write: P1Y2M. One could also indicate a xs:yearMonthDuration of minus 13 months as: -P13M.

Reduced precision and truncated representations of this format are allowed provided they conform to the following:

If the number of years or months in any expression equals zero (0), the number and its corresponding designator ·may· be omitted. However, at least one number and its designator ·must· be present. For example, P1347Y and P1347M are allowed; P-1347M is not allowed, although -P1347M is allowed. P1Y2MT is not allowed. Also, P24YM is not allowed, nor is PY43M since Y must have at least one preceding digit and M must have one preceding digit.

8.1.1.2 Calculating the value from the lexical representation

The value of a xs:yearMonthDuration lexical form is obtained by multiplying the value of the years component by 12 and adding the value of the months component. The value is positive or negative depending on the preceding sign.

8.1.1.3 Canonical representation

The canonical representation of xs:yearMonthDuration restricts the value of the months component to xs:integer values between 0 and 11, both inclusive. To convert from a non-canonical representation to the canonical representation, the lexical representation is first converted to a value in xs:integer months as defined above. This value is then divided by 12 to obtain the value of the years component of the canonical representation. The remaining number of months is the value of the months component of the canonical representation. For negative durations, the canonical form is calculated using the absolute value of the duration and a negative sign is prepended to it. If a component has the value zero (0), then the number and the designator for that component ·must· be omitted. However, if the value is zero (0) months, the canonical form is "P0M".

8.1.1.4 Order relation on xs:yearMonthDuration

Let the function that calculates the value of an xs:yearMonthDuration in the manner described above be called V(d). Then for two xs:yearMonthDuration values x and y, x > y if and only if V(x) > V(y). The order relation on yearMonthDuration is a total order.

8.1.2 xs:dayTimeDuration

[Definition] xs:dayTimeDuration is derived from xs:duration by restricting its lexical representation to contain only the days, hours, minutes and seconds components. The value space of xs:dayTimeDuration is the set of fractional second values. The components of xs:dayTimeDuration correspond to the day, hour, minute and second components defined in Section 5.5.3.2 of [ISO 8601], respectively.

8.1.2.1 Lexical representation

The lexical representation for xs:dayTimeDuration is the [ISO 8601] truncated format PnDTnHnMnS, where nD represents the number of days, T is the date/time separator, nH the number of hours, nM the number of minutes and nS the number of seconds.

The values of the days, hours and minutes components are not restricted, but allow an arbitrary unsigned xs:integer. Similarly, the value of the seconds component allows an arbitrary unsigned xs:decimal. An optional minus sign ('-') is allowed to precede the 'P', indicating a negative duration. If the sign is omitted, the duration is positive. See also [ISO 8601] Date and Time Formats.

For example, to indicate a duration of 3 days, 10 hours and 30 minutes, one would write: P3DT10H30M. One could also indicate a duration of minus 120 days as: -P120D. Reduced precision and truncated representations of this format are allowed, provided they conform to the following:

  • If the number of days, hours, minutes, or seconds in any expression equals zero (0), the number and its corresponding designator ·may· be omitted. However, at least one number and its designator ·must· be present.

  • The seconds part ·may· have a decimal fraction.

  • The designator 'T' ·must· be absent if and only if all of the time items are absent. The designator 'P' ·must· always be present.

For example, P13D, PT47H, P3DT2H, -PT35.89S and P4DT251M are all allowed. P-134D is not allowed (invalid location of minus sign), although -P134D is allowed.

8.1.2.2 Calculating the value of a xs:dayTimeDuration from the lexical representation

The value of a xs:dayTimeDuration lexical form in fractional seconds is obtained by converting the days, hours, minutes and seconds value to fractional seconds using the conversion rules: 24 hours = 1 day, 60 minutes = 1 hour and 60 seconds = 1 minute.

8.1.2.3 Canonical representation

The canonical representation of xs:dayTimeDuration restricts the value of the hours component to xs:integer values between 0 and 23, both inclusive; the value of the minutes component to xs:integer values between 0 and 59; both inclusive; and the value of the seconds component to xs:decimal valued from 0.0 to 59.999... (see [XML Schema Part 2: Datatypes Second Edition], Appendix D).

To convert from a non-canonical representation to the canonical representation, the value of the lexical form in fractional seconds is first calculated in the manner described above. The value of the days component in the canonical form is then calculated by dividing the value by 86,400 (24*60*60). The remainder is in fractional seconds. The value of the hours component in the canonical form is calculated by dividing this remainder by 3,600 (60*60). The remainder is again in fractional seconds. The value of the minutes component in the canonical form is calculated by dividing this remainder by 60. The remainder in fractional seconds is the value of the seconds component in the canonical form. For negative durations, the canonical form is calculated using the absolute value of the duration and a negative sign is prepended to it. If a component has the value zero (0) then the number and the designator for that component must be omitted. However, if all the components of the lexical form are zero (0), the canonical form is "PT0S".

8.1.2.4 Order relation on xs:dayTimeDuration

Let the function that calculates the value of a xs:dayTimeDuration in the manner described above be called V(d). Then for two xs:dayTimeDuration values x and y, x > y if and only if V(x) > V(y). The order relation on xs:dayTimeDuration is a total order.

8.2 Comparison operators on durations

Function Meaning
op:yearMonthDuration-less-than Returns true if $arg1 is a shorter duration than $arg2.
op:yearMonthDuration-greater-than Returns true if $arg1 is a longer duration than $arg2.
op:dayTimeDuration-less-than Returns true if $arg1 is a shorter duration than $arg2.
op:dayTimeDuration-greater-than Returns true if $arg1 is a longer duration than $arg2.
op:duration-equal Returns true if $arg1 and $arg2 are durations of the same length.

The following comparison operators are defined on the [XML Schema Part 2: Datatypes Second Edition] duration datatypes. Each operator takes two operands of the same type and returns an xs:boolean result. As discussed in [XML Schema Part 2: Datatypes Second Edition], the order relation on xs:duration is a partial order rather than a total order. For this reason, only equality is defined on xs:duration. A full complement of comparison and arithmetic functions are defined on the two subtypes of duration described in 8.1 Two totally ordered subtypes of duration which do have a total order.

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 on 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 the value of $arg1 is numerically less than the number of months in the value of $arg2, the function returns true.

Otherwise, the function returns false.

Notes

Either or both durations may be negative

8.2.2 op:yearMonthDuration-greater-than

Summary

Returns true if $arg1 is a longer duration than $arg2.

Operator Mapping

Defines the semantics of the "gt" operator on xs:yearMonthDuration values. Also used in the definition of the "le" operator.

Signature
op:yearMonthDuration-greater-than( $arg1  as xs:yearMonthDuration,
$arg2  as xs:yearMonthDuration) as xs:boolean
Rules

The function call op:yearMonthDuration-greater-than($A, $B) is defined to return the same result as op:yearMonthDuration-less-than($B, $A)

8.2.3 op:dayTimeDuration-less-than

Summary

Returns true if $arg1 is a shorter duration than $arg2.

Operator Mapping

Defines the semantics of the "lt" operator on 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 the value of $arg1 is numerically less than the number of seconds in the value of $arg2, the function returns true.

Otherwise, the function returns false.

Notes

Either or both durations may be negative

8.2.4 op:dayTimeDuration-greater-than

Summary

Returns true if $arg1 is a longer duration than $arg2.

Operator Mapping

Defines the semantics of the "gt" operator on xs:dayTimeDuration values. Also used in the definition of the "le" operator.

Signature
op:dayTimeDuration-greater-than( $arg1  as xs:dayTimeDuration,
$arg2  as xs:dayTimeDuration) as xs:boolean
Rules

The function call op:dayTimeDuration-greater-than($A, $B) is defined to return the same result as op:dayTimeDuration-less-than($B, $A)

8.2.5 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 on 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

The expression op:duration-equal(xs:duration("P1Y"), xs:duration("P12M")) returns true().

The expression op:duration-equal(xs:duration("PT24H"), xs:duration("P1D")) returns true().

The expression op:duration-equal(xs:duration("P1Y"), xs:duration("P365D")) returns false().

The expression op:duration-equal(xs:yearMonthDuration("P0Y"), xs:dayTimeDuration("P0D")) returns true().

The expression op:duration-equal(xs:yearMonthDuration("P1Y"), xs:dayTimeDuration("P365D")) returns false().

The expression op:duration-equal(xs:yearMonthDuration("P2Y"), xs:yearMonthDuration("P24M")) returns true().

The expression op:duration-equal(xs:dayTimeDuration("P10D"), xs:dayTimeDuration("PT240H")) returns true().

The expression op:duration-equal(xs:duration("P2Y0M0DT0H0M0S"), xs:yearMonthDuration("P24M")) returns true().

The expression op:duration-equal(xs:duration("P0Y0M10D"), xs:dayTimeDuration("PT240H")) returns true().

8.3 Component extraction functions on durations

The duration datatype may be considered to be a composite datatypes in that it contains distinct properties or components. The extraction functions specified below extract a single component from a duration value. For xs:duration and its subtypes, including the two subtypes xs:yearMonthDuration and xs:dayTimeDuration, the components are normalized: this means that the seconds and minutes components will always be less than 60, the hours component less than 24, and the months component less than 12.

Function Meaning
fn:years-from-duration Returns the number of years in a duration.
fn:months-from-duration Returns the number of months in a duration.
fn:days-from-duration Returns the number of days in a duration.
fn:hours-from-duration Returns the number of hours in a duration.
fn:minutes-from-duration Returns the number of minutes in a duration.
fn:seconds-from-duration Returns the number of seconds in a duration.

8.3.1 fn:years-from-duration

Summary

Returns the number of years in a duration.

Signature
fn:years-from-duration($arg as xs:duration?) as xs:integer?
Properties

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

Rules

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

Otherwise, the function returns an xs:integer representing the years component in the value of $arg. The result is obtained by casting $arg to an xs:yearMonthDuration (see 18.1.3 Casting to duration types) and then computing the years component as described in 8.1.1.3 Canonical representation.

If $arg is a negative duration then the result will be negative..

If $arg is an xs:dayTimeDuration the function returns 0.

Examples

The expression fn:years-from-duration(xs:yearMonthDuration("P20Y15M")) returns 21.

The expression fn:years-from-duration(xs:yearMonthDuration("-P15M")) returns -1.

The expression fn:years-from-duration(xs:dayTimeDuration("-P2DT15H")) returns 0.

8.3.2 fn:months-from-duration

Summary

Returns the number of months in a duration.

Signature
fn:months-from-duration($arg as xs:duration?) as xs:integer?
Properties

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

Rules

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

Otherwise, the function returns an xs:integer representing the months component in the value of $arg. The result is obtained by casting $arg to an xs:yearMonthDuration (see 18.1.3 Casting to duration types) and then computing the months component as described in 8.1.1.3 Canonical representation.

If $arg is a negative duration then the result will be negative..

If $arg is an xs:dayTimeDuration the function returns 0.

Examples

The expression fn:months-from-duration(xs:yearMonthDuration("P20Y15M")) returns 3.

The expression fn:months-from-duration(xs:yearMonthDuration("-P20Y18M")) returns -6.

The expression fn:months-from-duration(xs:dayTimeDuration("-P2DT15H0M0S")) returns 0.

8.3.3 fn:days-from-duration

Summary

Returns the number of days in a duration.

Signature
fn:days-from-duration($arg as xs:duration?) as xs:integer?
Properties

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

Rules

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

Otherwise, the function returns an xs:integer representing the days component in the value of $arg. The result is obtained by casting $arg to an xs:dayTimeDuration (see 18.1.3 Casting to duration types) and then computing the days component as described in 8.1.2.3 Canonical representation.

If $arg is a negative duration then the result will be negative..

If $arg is an xs:yearMonthDuration the function returns 0.

Examples

The expression fn:days-from-duration(xs:dayTimeDuration("P3DT10H")) returns 3.

The expression fn:days-from-duration(xs:dayTimeDuration("P3DT55H")) returns 5.

The expression fn:days-from-duration(xs:yearMonthDuration("P3Y5M")) returns 0.

8.3.4 fn:hours-from-duration

Summary

Returns the number of hours in a duration.

Signature
fn:hours-from-duration($arg as xs:duration?) as xs:integer?
Properties

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

Rules

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

Otherwise, the function returns an xs:integer representing the hours component in the value of $arg. The result is obtained by casting $arg to an xs:dayTimeDuration (see 18.1.3 Casting to duration types) and then computing the hours component as described in 8.1.2.3 Canonical representation.

If $arg is a negative duration then the result will be negative..

If $arg is an xs:yearMonthDuration the function returns 0.

Examples

The expression fn:hours-from-duration(xs:dayTimeDuration("P3DT10H")) returns 10.

The expression fn:hours-from-duration(xs:dayTimeDuration("P3DT12H32M12S")) returns 12.

The expression fn:hours-from-duration(xs:dayTimeDuration("PT123H")) returns 3.

The expression fn:hours-from-duration(xs:dayTimeDuration("-P3DT10H")) returns -10.

8.3.5 fn:minutes-from-duration

Summary

Returns the number of minutes in a duration.

Signature
fn:minutes-from-duration($arg as xs:duration?) as xs:integer?
Properties

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

Rules

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

Otherwise, the function returns an xs:integer representing the minutes component in the value of $arg. The result is obtained by casting $arg to an xs:dayTimeDuration (see 18.1.3 Casting to duration types) and then computing the minutes component as described in 8.1.2.3 Canonical representation.

If $arg is a negative duration then the result will be negative..

If $arg is an xs:yearMonthDuration the function returns 0.

Examples

The expression fn:minutes-from-duration(xs:dayTimeDuration("P3DT10H")) returns 0.

The expression fn:minutes-from-duration(xs:dayTimeDuration("-P5DT12H30M")) returns -30.

8.3.6 fn:seconds-from-duration

Summary

Returns the number of seconds in a duration.

Signature
fn:seconds-from-duration($arg as xs:duration?) as xs:decimal?
Properties

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

Rules

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

Otherwise, the function returns an xs:decimal representing the seconds component in the value of $arg. The result is obtained by casting $arg to an xs:dayTimeDuration (see 18.1.3 Casting to duration types) and then computing the seconds component as described in 8.1.2.3 Canonical representation.

If $arg is a negative duration then the result will be negative..

If $arg is an xs:yearMonthDuration the function returns 0.

Examples

The expression fn:seconds-from-duration(xs:dayTimeDuration("P3DT10H12.5S")) returns 12.5.

The expression fn:seconds-from-duration(xs:dayTimeDuration("-PT256S")) returns -16.0.

8.4 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 the value of $arg1 by $arg2. The result is rounded to the nearest month.
op:divide-yearMonthDuration Returns the result of dividing the value of $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.4.1 op:add-yearMonthDurations

Summary

Returns the result of adding two xs:yearMonthDuration values.

Operator Mapping

Defines the semantics of the "+" operator on 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 the value of $arg1 to the value of $arg2. The result will be an xs:yearMonthDuration whose length in months is equal to the length in months of $arg1 plus the length in months of $arg2.

For handling of overflow, see 9.7.1 Limits and precision.

Notes

Either duration (and therefore the result) may be negative.

Examples

The expression op:add-yearMonthDurations(xs:yearMonthDuration("P2Y11M"), xs:yearMonthDuration("P3Y3M")) returns xs:yearMonthDuration("P6Y2M").

8.4.2 op:subtract-yearMonthDurations

Summary

Returns the result of subtracting one xs:yearMonthDuration value from another.

Operator Mapping

Defines the semantics of the "-" operator on 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 the value of $arg2 from the value of $arg1. The result will be an xs:yearMonthDuration whose length in months is equal to the length in months of $arg1 minus the length in months of $arg2.

For handling of overflow, see 9.7.1 Limits and precision.

Notes

Either duration (and therefore the result) may be negative.

Examples

The expression op:subtract-yearMonthDurations(xs:yearMonthDuration("P2Y11M"), xs:yearMonthDuration("P3Y3M")) returns xs:yearMonthDuration("-P4M").

8.4.3 op:multiply-yearMonthDuration

Summary

Returns the result of multiplying the value of $arg1 by $arg2. The result is rounded to the nearest month.

Operator Mapping

Defines the semantics of the "*" operator on xs:yearMonthDuration values.

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 discussed in 9.7.1 Limits and precision.

For handling of overflow and underflow, see 9.7.1 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

The expression op:multiply-yearMonthDuration(xs:yearMonthDuration("P2Y11M"), 2.3) returns xs:yearMonthDuration("P6Y9M").

8.4.4 op:divide-yearMonthDuration

Summary

Returns the result of dividing the value of $arg1 by $arg2. The result is rounded to the nearest month.

Operator Mapping

Defines the semantics of the "div" operator on xs:yearMonthDuration and numeric values.

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 discussed in 9.7.1 Limits and precision.

For handling of overflow and underflow, see 9.7.1 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

The expression op:divide-yearMonthDuration(xs:yearMonthDuration("P2Y11M"), 1.5) returns xs:yearMonthDuration("P1Y11M").

8.4.5 op:divide-yearMonthDuration-by-yearMonthDuration

Summary

Returns the ratio of two xs:yearMonthDuration values.

Operator Mapping

Defines the semantics of the "div" operator on 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 and underflow, see 9.7.1 Limits and precision.

Notes

Either duration (and therefore the result) may be negative.

Examples

The expression op:divide-yearMonthDuration-by-yearMonthDuration(xs:yearMonthDuration("P3Y4M"), xs:yearMonthDuration("-P1Y4M")) returns -2.5.

The following example demonstrates how to calculate the length of an xs:yearMonthDuration value in months:

The expression op:divide-yearMonthDuration-by-yearMonthDuration(xs:yearMonthDuration("P3Y4M"), xs:yearMonthDuration("P1M")) returns 40.

8.4.6 op:add-dayTimeDurations

Summary

Returns the sum of two xs:dayTimeDuration values.

Operator Mapping

Defines the semantics of the "+" operator on 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 the value of $arg1 to the value of $arg2. The result is the xs:dayTimeDuration whose length in seconds is equal to the sum of the length in seconds of the two input durations.

For handling of overflow, see 9.7.1 Limits and precision.

Notes

Either duration (and therefore the result) may be negative.

Examples

The expression op:add-dayTimeDurations(xs:dayTimeDuration("P2DT12H5M"), xs:dayTimeDuration("P5DT12H")) returns xs:dayTimeDuration('P8DT5M').

8.4.7 op:subtract-dayTimeDurations

Summary

Returns the result of subtracting one xs:dayTimeDuration from another.

Operator Mapping

Defines the semantics of the "-" operator on 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 the value of $arg2 from the value of $arg1. The result is the xs:dayTimeDuration whose length in seconds is equal to the length in seconds of $arg1 minus the length in seconds of $arg2.

For handling of overflow, see 9.7.1 Limits and precision.

Notes

Either duration (and therefore the result) may be negative.

Examples

The expression op:subtract-dayTimeDurations(xs:dayTimeDuration("P2DT12H"), xs:dayTimeDuration("P1DT10H30M")) returns xs:dayTimeDuration('P1DT1H30M').

8.4.8 op:multiply-dayTimeDuration

Summary

Returns the result of multiplying a xs:dayTimeDuration by a number.

Operator Mapping

Defines the semantics of the "*" operator on xs:dayTimeDuration and numeric values.

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

The function returns the result of multiplying the value of $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 discussed in 9.1.1 Limits and precision.

For handling of overflow and underflow, see 9.7.1 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

The expression op:multiply-dayTimeDuration(xs:dayTimeDuration("PT2H10M"), 2.1) returns xs:dayTimeDuration('PT4H33M').

8.4.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 on 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 the value of $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 discussed in 9.1.1 Limits and precision.

For handling of overflow and underflow, see 9.7.1 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

The expression op:divide-dayTimeDuration(xs:dayTimeDuration("P1DT2H30M10.5S"), 1.5) returns xs:duration("PT17H40M7S").

8.4.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 on 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 the value of $arg1 by $arg2. The result is the xs:dayTimeDuration whose length in seconds is equal to the length in seconds of $arg1 divided by the length in seconds of $arg2. The calculation is performed by applying op:numeric-divide to the two xs:decimal operands.

For handling of overflow and underflow, see 9.7.1 Limits and precision.

Notes

Either operand (and therefore the result) may be negative.

Examples

The expression fn:round-half-to-even( op:divide-dayTimeDuration-by-dayTimeDuration( xs:dayTimeDuration("P2DT53M11S"), xs:dayTimeDuration("P1DT10H")), 4) returns 1.4378.

This examples shows how to determine the number of seconds in a duration.

The expression op:divide-dayTimeDuration-by-dayTimeDuration(xs:dayTimeDuration("P2DT53M11S"), xs:dayTimeDuration("PT1S")) returns 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

The operators described in this section are defined on the following date and time types:

  • xs:dateTime

  • xs:date

  • xs:time

  • xs:gYearMonth

  • xs:gYear

  • xs:gMonthDay

  • xs:gMonth

  • xs:gDay

The only 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

For a number of the above datatypes [XML Schema Part 2: Datatypes Second Edition] extends the basic [ISO 8601] lexical representations, such as YYYY-MM-DDThh:mm:ss.s for dateTime, by allowing a preceding minus sign, more than four digits to represent the year field — no maximum is specified — and an unlimited number of digits for fractional seconds. Leap seconds are not supported.

All minimally conforming processors ·must· support positive year values with a minimum of 4 digits (i.e., YYYY) and a minimum fractional second precision of 1 millisecond or three digits (i.e., s.sss). However, conforming processors ·may· set larger ·implementation-defined· limits on the maximum number of digits they support in these two situations. Processors ·may· also choose to support the year 0000 and years with negative values. The results of operations on dates that cross the year 0000 are ·implementation-defined·.

A processor that limits the number of digits in date and time datatype representations may encounter overflow and underflow conditions when it tries to execute the functions in 9.7 Arithmetic operators on durations, dates and times. In these situations, the processor ·must· return 00:00:00 in case of time underflow. It ·must· raise a dynamic error [err:FODT0001] in case of overflow.

9.2 Date/time datatype values

As defined in Section 3.3.2 Dates and Times DM30, 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 absentDM30. 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, -PT5H}.

  • An xs:dateTime with lexical representation 1999-12-31T24:00:00 is represented by {2000, 1, 1, 0, 0, 0.0, ()}.

  • An xs:date with lexical representation 2005-02-28+8:00 is represented by {2005, 2, 28, (), (), (), PT8H}.

  • An xs:time with lexical representation 24:00:00 is represented by {(), (), (), 0, 0, 0, ()}.

9.3 Constructing a dateTime

A function is provided for constructing a xs:dateTime value from a xs:date value and a xs:time value.

9.3.1 fn:dateTime

Summary

Returns an xs:dateTime value created by combining an xs:date and an xs:time.

Signature
fn:dateTime($arg1 as xs:date?, $arg2 as xs:time?) as xs:dateTime?
Properties

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

Rules

If either $arg1 or $arg2 is the empty sequence the function returns the empty sequence.

Otherwise, the function returns an xs:dateTime whose date component is equal to $arg1 and whose time component is equal to $arg2.

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

The expression fn:dateTime(xs:date("1999-12-31"), xs:time("12:00:00")) returns xs:dateTime("1999-12-31T12:00:00").

The expression fn:dateTime(xs:date("1999-12-31"), xs:time("24:00:00")) returns xs:dateTime("1999-12-31T00:00:00"). (This is because "24:00:00" is an alternate lexical form for "00:00:00").

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:dateTime-greater-than Returns true if the first argument represents a later 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:date-greater-than Returns true if and only if the starting instant of $arg1 is greater 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:time-greater-than Returns true if the first xs:time value represents a later 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 XP30, 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 absentDM30. 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 [XML Schema 1.1 Part 2: Datatypes], 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 on 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

The expression op:dateTime-equal(xs:dateTime("2002-04-02T12:00:00-01:00"), xs:dateTime("2002-04-02T17:00:00+04:00")) returns true().

The expression op:dateTime-equal(xs:dateTime("2002-04-02T12:00:00"), xs:dateTime("2002-04-02T23:00:00+06:00")) returns true().

The expression op:dateTime-equal(xs:dateTime("2002-04-02T12:00:00"), xs:dateTime("2002-04-02T17:00:00")) returns false().

The expression op:dateTime-equal(xs:dateTime("2002-04-02T12:00:00"), xs:dateTime("2002-04-02T12:00:00")) returns true().

The expression op:dateTime-equal(xs:dateTime("2002-04-02T23:00:00-04:00"), xs:dateTime("2002-04-03T02:00:00-01:00")) returns true().

The expression op:dateTime-equal(xs:dateTime("1999-12-31T24:00:00"), xs:dateTime("2000-01-01T00:00:00")) returns true().

The expression op:dateTime-equal(xs:dateTime("2005-04-04T24:00:00"), xs:dateTime("2005-04-04T00:00:00")) returns 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 on 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:dateTime-greater-than

Summary

Returns true if the first argument represents a later instant in time than the second argument.

Operator Mapping

Defines the semantics of the "gt" operator on xs:dateTime values. Also used in the definition of the "le" operator.

Signature
op:dateTime-greater-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

The function call op:dateTime-greater-than($A, $B) is defined to return the same result as op:dateTime-less-than($B, $A)

9.4.4 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 on 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

The expression op:date-equal(xs:date("2004-12-25Z"), xs:date("2004-12-25+07:00")) returns 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"). ).

The expression op:date-equal(xs:date("2004-12-25-12:00"), xs:date("2004-12-26+12:00")) returns true().

9.4.5 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 on 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

The expression op:date-less-than(xs:date("2004-12-25Z"), xs:date("2004-12-25-05:00")) returns true().

The expression op:date-less-than(xs:date("2004-12-25-12:00"), xs:date("2004-12-26+12:00")) returns false().

9.4.6 op:date-greater-than

Summary

Returns true if and only if the starting instant of $arg1 is greater than the starting instant of $arg2. Returns false otherwise.

Operator Mapping

Defines the semantics of the "gt" operator on xs:date values. Also used in the definition of the "le" operator.

Signature
op:date-greater-than($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 function call op:date-greater-than($A, $B) is defined to return the same result as op:date-less-than($B, $A)

Examples

The expression op:date-greater-than(xs:date("2004-12-25Z"), xs:date("2004-12-25+07:00")) returns true().

The expression op:date-greater-than(xs:date("2004-12-25-12:00"), xs:date("2004-12-26+12:00")) returns false().

9.4.7 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 on 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(
        fn:dateTime(xs:date('1972-12-31'), $arg1), 
        fn:dateTime(xs:date('1972-12-31'), $arg2))
Examples

Assume that the date components from the reference xs:dateTime correspond to 1972-12-31.

The expression op:time-equal(xs:time("08:00:00+09:00"), xs:time("17:00:00-06:00")) returns false(). (The xs:dateTimes calculated using the reference date components are 1972-12-31T08:00:00+09:00 and 1972-12-31T17:00:00-06:00. These normalize to 1972-12-30T23:00:00Z and 1972-12-31T23:00:00Z. ).

The expression op:time-equal(xs:time("21:30:00+10:30"), xs:time("06:00:00-05:00")) returns true().

The expression op:time-equal(xs:time("24:00:00+01:00"), xs:time("00:00:00+01:00")) returns 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.8 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 on 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(
        fn:dateTime(xs:date('1972-12-31'), $arg1), 
        fn:dateTime(xs:date('1972-12-31'), $arg2))
Examples

Assume that the dynamic context provides an implicit timezone value of -05:00.

The expression op:time-less-than(xs:time("12:00:00"), xs:time("23:00:00+06:00")) returns false().

The expression op:time-less-than(xs:time("11:00:00"), xs:time("17:00:00Z")) returns true().

The expression op:time-less-than(xs:time("23:59:59"), xs:time("24:00:00")) returns false().

9.4.9 op:time-greater-than

Summary

Returns true if the first xs:time value represents a later 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 "gt" operator on xs:time values. Also used in the definition of the "le" operator.

Signature
op:time-greater-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

The function call op:time-greater-than($A, $B) is defined to return the same result as op:time-less-than($B, $A)

Examples

The expression op:time-greater-than(xs:time("08:00:00+09:00"), xs:time("17:00:00-06:00")) returns false().

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

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.

The expression op:gYear-equal(xs:gYear("1976-05:00"), xs:gYear("1976")) returns true().

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

The expression op:gMonthDay-equal(xs:gMonthDay("--12-25-14:00"), xs:gMonthDay("--12-26+10:00")) returns 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. ).

The expression op:gMonthDay-equal(xs:gMonthDay("--12-25"), xs:gMonthDay("--12-26Z")) returns false().

9.4.13 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 on 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

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.

The expression op:gMonth-equal(xs:gMonth("--12-14:00"), xs:gMonth("--12+10:00")) returns 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. ).

The expression op:gMonth-equal(xs:gMonth("--12"), xs:gMonth("--12Z")) returns false().

9.4.14 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 on 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

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.

The expression op:gDay-equal(xs:gDay("---25-14:00"), xs:gDay("---25+10:00")) returns 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. ).

The expression op:gDay-equal(xs:gDay("---12"), xs:gDay("---12Z")) returns 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 an xs:dateTime.
fn:month-from-dateTime Returns the month component of an xs:dateTime.
fn:day-from-dateTime Returns the day component of an xs:dateTime.
fn:hours-from-dateTime Returns the hours component of an xs:dateTime.
fn:minutes-from-dateTime Returns the minute component of an xs:dateTime.
fn:seconds-from-dateTime Returns the seconds component of an xs:dateTime.
fn:timezone-from-dateTime Returns the timezone component of an xs:dateTime.
fn:year-from-date Returns the year component of an xs:date.
fn:month-from-date Returns the month component of an xs:date.
fn:day-from-date Returns the day component of an xs:date.
fn:timezone-from-date Returns the timezone component of an xs:date.
fn:hours-from-time Returns the hours component of an xs:time.
fn:minutes-from-time Returns the minutes component of an xs:time.
fn:seconds-from-time Returns the seconds component of an xs:time.
fn:timezone-from-time Returns the timezone component of an xs:time.

9.5.1 fn:year-from-dateTime

Summary

Returns the year component of an xs:dateTime.

Signature
fn:year-from-dateTime($arg as xs:dateTime?) as xs:integer?
Properties

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

Rules

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

Otherwise, the function returns an xs:integer representing the year component in the local value of $arg. The result may be negative.

Examples

The expression fn:year-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00")) returns 1999.

The expression fn:year-from-dateTime(xs:dateTime("1999-05-31T21:30:00-05:00")) returns 1999.

The expression fn:year-from-dateTime(xs:dateTime("1999-12-31T19:20:00")) returns 1999.

The expression fn:year-from-dateTime(xs:dateTime("1999-12-31T24:00:00")) returns 2000.

9.5.2 fn:month-from-dateTime

Summary

Returns the month component of an xs:dateTime.

Signature
fn:month-from-dateTime($arg as xs:dateTime?) as xs:integer?
Properties

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

Rules

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

Examples

The expression fn:month-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00")) returns 5.

The expression fn:month-from-dateTime(xs:dateTime("1999-12-31T19:20:00-05:00")) returns 12.

The expression fn:month-from-dateTime(fn:adjust-dateTime-to-timezone(xs:dateTime("1999-12-31T19:20:00-05:00"), xs:dayTimeDuration("PT0S"))) returns 1.

9.5.3 fn:day-from-dateTime

Summary

Returns the day component of an xs:dateTime.

Signature
fn:day-from-dateTime($arg as xs:dateTime?) as xs:integer?
Properties

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

Rules

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

Otherwise, the function returns an xs:integer between 1 and 31, both inclusive, representing the day component in the local value of $arg.

Examples

The expression fn:day-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00")) returns 31.

The expression fn:day-from-dateTime(xs:dateTime("1999-12-31T20:00:00-05:00")) returns 31.

The expression fn:day-from-dateTime(fn:adjust-dateTime-to-timezone(xs:dateTime("1999-12-31T19:20:00-05:00"), xs:dayTimeDuration("PT0S"))) returns 1.

9.5.4 fn:hours-from-dateTime

Summary

Returns the hours component of an xs:dateTime.

Signature
fn:hours-from-dateTime($arg as xs:dateTime?) as xs:integer?
Properties

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

Rules

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

Otherwise, the function returns an xs:integer between 0 and 23, both inclusive, representing the hours component in the local value of $arg.

Examples

The expression fn:hours-from-dateTime(xs:dateTime("1999-05-31T08:20:00-05:00")) returns 8.

The expression fn:hours-from-dateTime(xs:dateTime("1999-12-31T21:20:00-05:00")) returns 21.

The expression fn:hours-from-dateTime(fn:adjust-dateTime-to-timezone(xs:dateTime("1999-12-31T21:20:00-05:00"), xs:dayTimeDuration("PT0S"))) returns 2.

The expression fn:hours-from-dateTime(xs:dateTime("1999-12-31T12:00:00")) returns 12.

The expression fn:hours-from-dateTime(xs:dateTime("1999-12-31T24:00:00")) returns 0.

9.5.5 fn:minutes-from-dateTime

Summary

Returns the minute component of an xs:dateTime.

Signature
fn:minutes-from-dateTime($arg as xs:dateTime?) as xs:integer?
Properties

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

Rules

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

Otherwise, the function returns an xs:integer value between 0 and 59, both inclusive, representing the minute component in the local value of $arg.

Examples

The expression fn:minutes-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00")) returns 20.

The expression fn:minutes-from-dateTime(xs:dateTime("1999-05-31T13:30:00+05:30")) returns 30.

9.5.6 fn:seconds-from-dateTime

Summary

Returns the seconds component of an xs:dateTime.

Signature
fn:seconds-from-dateTime($arg as xs:dateTime?) as xs:decimal?
Properties

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

Rules

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

Examples

The expression fn:seconds-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00")) returns 0.

9.5.7 fn:timezone-from-dateTime

Summary

Returns the timezone component of an xs:dateTime.

Signature
fn:timezone-from-dateTime($arg as xs:dateTime?) as xs:dayTimeDuration?
Properties

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

Rules

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

Otherwise, the function returns the timezone component of $arg, if any. If $arg 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 $arg has no timezone component, the result is the empty sequence.

Examples

The expression fn:timezone-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00")) returns xs:dayTimeDuration("-PT5H").

The expression fn:timezone-from-dateTime(xs:dateTime("2000-06-12T13:20:00Z")) returns xs:dayTimeDuration("PT0S").

The expression fn:timezone-from-dateTime(xs:dateTime("2004-08-27T00:00:00")) returns ().

9.5.8 fn:year-from-date

Summary

Returns the year component of an xs:date.

Signature
fn:year-from-date($arg as xs:date?) as xs:integer?
Properties

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

Rules

If $arg 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 $arg. The value may be negative.

Examples

The expression fn:year-from-date(xs:date("1999-05-31")) returns 1999.

The expression fn:year-from-date(xs:date("2000-01-01+05:00")) returns 2000.

9.5.9 fn:month-from-date

Summary

Returns the month component of an xs:date.

Signature
fn:month-from-date($arg as xs:date?) as xs:integer?
Properties

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

Rules

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

Examples

The expression fn:month-from-date(xs:date("1999-05-31-05:00")) returns 5.

The expression fn:month-from-date(xs:date("2000-01-01+05:00")) returns 1.

9.5.10 fn:day-from-date

Summary

Returns the day component of an xs:date.

Signature
fn:day-from-date($arg as xs:date?) as xs:integer?
Properties

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

Rules

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

Examples

The expression fn:day-from-date(xs:date("1999-05-31-05:00")) returns 31.

The expression fn:day-from-date(xs:date("2000-01-01+05:00")) returns 1.

9.5.11 fn:timezone-from-date

Summary

Returns the timezone component of an xs:date.

Signature
fn:timezone-from-date($arg as xs:date?) as xs:dayTimeDuration?
Properties

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

Rules

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

Otherwise, the function returns the timezone component of $arg, if any. If $arg 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 $arg has no timezone component, the result is the empty sequence.

Examples

The expression fn:timezone-from-date(xs:date("1999-05-31-05:00")) returns xs:dayTimeDuration("-PT5H").

The expression fn:timezone-from-date(xs:date("2000-06-12Z")) returns xs:dayTimeDuration("PT0S").

9.5.12 fn:hours-from-time

Summary

Returns the hours component of an xs:time.

Signature
fn:hours-from-time($arg as xs:time?) as xs:integer?
Properties

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

Rules

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

Examples

Assume that the dynamic context provides an implicit timezone value of -05:00.

The expression fn:hours-from-time(xs:time("11:23:00")) returns 11.

The expression fn:hours-from-time(xs:time("21:23:00")) returns 21.

The expression fn:hours-from-time(xs:time("01:23:00+05:00")) returns 1.

The expression fn:hours-from-time(fn:adjust-time-to-timezone(xs:time("01:23:00+05:00"), xs:dayTimeDuration("PT0S"))) returns 20.

The expression fn:hours-from-time(xs:time("24:00:00")) returns 0.

9.5.13 fn:minutes-from-time

Summary

Returns the minutes component of an xs:time.

Signature
fn:minutes-from-time($arg as xs:time?) as xs:integer?
Properties

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

Rules

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

Examples

The expression fn:minutes-from-time(xs:time("13:00:00Z")) returns 0.

9.5.14 fn:seconds-from-time

Summary

Returns the seconds component of an xs:time.

Signature
fn:seconds-from-time($arg as xs:time?) as xs:decimal?
Properties

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

Rules

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

Examples

The expression fn:seconds-from-time(xs:time("13:20:10.5")) returns 10.5.

9.5.15 fn:timezone-from-time

Summary

Returns the timezone component of an xs:time.

Signature
fn:timezone-from-time($arg as xs:time?) as xs:dayTimeDuration?
Properties

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

Rules

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

Otherwise, the function returns the timezone component of $arg, if any. If $arg 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 $arg has no timezone component, the result is the empty sequence.

Examples

The expression fn:timezone-from-time(xs:time("13:20:00-05:00")) returns xs:dayTimeDuration("-PT5H").

The expression fn:timezone-from-time(xs:time("13:20:00")) returns ().

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.

Signatures
fn:adjust-dateTime-to-timezone($arg as xs:dateTime?) as xs:dateTime?
fn:adjust-dateTime-to-timezone( $arg  as xs:dateTime?,
$timezone  as xs:dayTimeDuration?) 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 $arg is the empty sequence, then the function returns the empty sequence.

If $arg does not have a timezone component and $timezone is the empty sequence, then the result is $arg.

If $arg does not have a timezone component and $timezone is not the empty sequence, then the result is $arg with $timezone as the timezone component.

If $arg has a timezone component and $timezone is the empty sequence, then the result is the local value of $arg without its timezone component.

If $arg has a timezone component and $timezone is not the empty sequence, then the result is the xs:dateTime value that is equal to $arg 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

Assume the dynamic context provides an implicit timezone of -05:00 (-PT5H0M).

let $tz-10 := xs:dayTimeDuration("-PT10H")

The expression fn:adjust-dateTime-to-timezone(xs:dateTime('2002-03-07T10:00:00')) returns xs:dateTime('2002-03-07T10:00:00-05:00').

The expression fn:adjust-dateTime-to-timezone(xs:dateTime('2002-03-07T10:00:00-07:00')) returns xs:dateTime('2002-03-07T12:00:00-05:00').

The expression fn:adjust-dateTime-to-timezone(xs:dateTime('2002-03-07T10:00:00'), $tz-10) returns xs:dateTime('2002-03-07T10:00:00-10:00').

The expression fn:adjust-dateTime-to-timezone(xs:dateTime('2002-03-07T10:00:00-07:00'), $tz-10) returns xs:dateTime('2002-03-07T07:00:00-10:00').

The expression fn:adjust-dateTime-to-timezone(xs:dateTime('2002-03-07T10:00:00-07:00'), xs:dayTimeDuration("PT10H")) returns xs:dateTime('2002-03-08T03:00:00+10:00').

The expression fn:adjust-dateTime-to-timezone(xs:dateTime('2002-03-07T00:00:00+01:00'), xs:dayTimeDuration("-PT8H")) returns xs:dateTime('2002-03-06T15:00:00-08:00').

The expression fn:adjust-dateTime-to-timezone(xs:dateTime('2002-03-07T10:00:00'), ()) returns xs:dateTime('2002-03-07T10:00:00').

The expression fn:adjust-dateTime-to-timezone(xs:dateTime('2002-03-07T10:00:00-07:00'), ()) returns 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.

Signatures
fn:adjust-date-to-timezone($arg as xs:date?) as xs:date?
fn:adjust-date-to-timezone( $arg  as xs:date?,
$timezone  as xs:dayTimeDuration?) 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 $arg is the empty sequence, then the function returns the empty sequence.

If $arg does not have a timezone component and $timezone is the empty sequence, then the result is the value of $arg.

If $arg does not have a timezone component and $timezone is not the empty sequence, then the result is $arg with $timezone as the timezone component.

If $arg has a timezone component and $timezone is the empty sequence, then the result is the local value of $arg without its timezone component.

If $arg has a timezone component and $timezone is not the empty sequence, then the function returns the value of the expression:

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

Assume the dynamic context provides an implicit timezone of -05:00 (-PT5H0M).

let $tz-10 := xs:dayTimeDuration("-PT10H")

The expression fn:adjust-date-to-timezone(xs:date("2002-03-07")) returns xs:date("2002-03-07-05:00").

The expression fn:adjust-date-to-timezone(xs:date("2002-03-07-07:00")) returns xs:date("2002-03-07-05:00"). ($arg 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". ).

The expression fn:adjust-date-to-timezone(xs:date("2002-03-07"), $tz-10) returns xs:date("2002-03-07-10:00").

The expression fn:adjust-date-to-timezone(xs:date("2002-03-07-07:00"), $tz-10) returns xs:date("2002-03-06-10:00"). ($arg is converted to the xs:dateTime "2002-03-07T00:00:00-07:00". This is adjusted to the given timezone, giving "2002-03-06T21:00:00-10:00". ).

The expression fn:adjust-date-to-timezone(xs:date("2002-03-07"), ()) returns xs:date("2002-03-07").

The expression fn:adjust-date-to-timezone(xs:date("2002-03-07-07:00"), ()) returns 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.

Signatures
fn:adjust-time-to-timezone($arg as xs:time?) as xs:time?
fn:adjust-time-to-timezone( $arg  as xs:time?,
$timezone  as xs:dayTimeDuration?) 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 $arg is the empty sequence, then the function returns the empty sequence.

If $arg does not have a timezone component and $timezone is the empty sequence, then the result is $arg.

If $arg does not have a timezone component and $timezone is not the empty sequence, then the result is $arg with $timezone as the timezone component.

If $arg has a timezone component and $timezone is the empty sequence, then the result is the localized value of $arg without its timezone component.

If $arg has a timezone component and $timezone is not the empty sequence, then:

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

Assume the dynamic context provides an implicit timezone of -05:00 (-PT5H0M).

let $tz-10 := xs:dayTimeDuration("-PT10H")

The expression fn:adjust-time-to-timezone(xs:time("10:00:00")) returns xs:time("10:00:00-05:00").

The expression fn:adjust-time-to-timezone(xs:time("10:00:00-07:00")) returns xs:time("12:00:00-05:00").

The expression fn:adjust-time-to-timezone(xs:time("10:00:00"), $tz-10) returns xs:time("10:00:00-10:00").

The expression fn:adjust-time-to-timezone(xs:time("10:00:00-07:00"), $tz-10) returns xs:time("07:00:00-10:00").

The expression fn:adjust-time-to-timezone(xs:time("10:00:00"), ()) returns xs:time("10:00:00").

The expression fn:adjust-time-to-timezone(xs:time("10:00:00-07:00"), ()) returns xs:time("10:00:00").

The expression fn:adjust-time-to-timezone(xs:time("10:00:00-07:00"), xs:dayTimeDuration("PT10H")) returns 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 Two totally ordered subtypes of duration are xs:integer months for xs:yearMonthDuration and xs:decimal seconds for xs:dayTimeDuration. If a processor limits the number of digits allowed in the representation of xs:integer and xs:decimal then overflow and underflow situations can arise when it tries to execute the functions in 8.4 Arithmetic operators on durations. In these situations the processor ·must· return zero in case of numeric underflow and P0M or PT0S in case of duration underflow. It ·must· raise a dynamic error [err:FODT0002] in case of overflow.

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

The expression op:subtract-dateTimes(xs:dateTime("2000-10-30T06:12:00"), xs:dateTime("1999-11-28T09:00:00Z")) returns 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 on 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 XP30.) 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

Assume that the dynamic context provides an implicit timezone value of Z.

The expression op:subtract-dates(xs:date("2000-10-30"), xs:date("1999-11-28")) returns xs:dayTimeDuration("P337D"). (The normalized values of the two starting instants are {2000, 10, 30, 0, 0, 0, PT0S} and {1999, 11, 28, 0, 0, 0, PT0S}.).

Now assume that the dynamic context provides an implicit timezone value of +05:00.

The expression op:subtract-dates(xs:date("2000-10-30"), xs:date("1999-11-28Z")) returns xs:dayTimeDuration("P336DT19H"). ( The normalized values of the two starting instants are {2000, 10, 29, 19, 0, 0, PT0S} and {1999, 11, 28, 0, 0, 0, PT0S}.).

The expression op:subtract-dates(xs:date("2000-10-15-05:00"), xs:date("2000-10-10+02:00")) returns 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 on 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(
        fn:dateTime(xs:date('1972-12-31'), $arg1),
        fn:dateTime(xs:date('1972-12-31'), $arg2))
Notes

Any other reference date would work equally well.

Examples

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

The expression op:subtract-times(xs:time("11:12:00Z"), xs:time("04:00:00")) returns xs:dayTimeDuration("PT2H12M"). (This is obtained by subtracting from the xs:dateTime value {1972, 12, 31, 11, 12, 0, PT0S} the xs:dateTime value {1972, 12, 31, 9, 0, 0, PT0S}.).

The expression op:subtract-times(xs:time("11:00:00-05:00"), xs:time("21:30:00+05:30")) returns xs:dayTimeDuration("PT0S"). (The two xs:dateTime values are {1972, 12, 31, 11, 0, 0, -PT5H} and {1972, 12, 31, 21, 30, 0, PT5H30M}. These normalize to {1972, 12, 31, 16, 0, 0, PT0S} and {1972, 12, 31, 16, 0, 0, PT0S}. ).

The expression op:subtract-times(xs:time("17:00:00-06:00"), xs:time("08:00:00+09:00")) returns xs:dayTimeDuration("P1D"). (The two normalized xs:dateTime values are {1972, 12, 31, 23, 0, 0, PT0S} and {1972, 12, 30, 23, 0, 0, PT0S}.).

The expression op:subtract-times(xs:time("24:00:00"), xs:time("23:59:59")) returns 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 on xs:dateTime and xs:yearMonthDuration values.

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

The expression op:add-yearMonthDuration-to-dateTime(xs:dateTime("2000-10-30T11:12:00"), xs:yearMonthDuration("P1Y2M")) returns 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 on xs:dateTime and xs:dayTimeDuration values.

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

The expression op:add-dayTimeDuration-to-dateTime(xs:dateTime("2000-10-30T11:12:00"), xs:dayTimeDuration("P3DT1H15M")) returns 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 on xs:dateTime and xs:yearMonthDuration values.

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 the value of $arg1 using the function op:add-yearMonthDuration-to-dateTime.

Examples

The expression op:subtract-yearMonthDuration-from-dateTime(xs:dateTime("2000-10-30T11:12:00"), xs:yearMonthDuration("P1Y2M")) returns 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 on xs:dateTime 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 the value of $arg1 using the function op:add-dayTimeDuration-to-dateTime.

Examples

The expression op:subtract-dayTimeDuration-from-dateTime(xs:dateTime("2000-10-30T11:12:00"), xs:dayTimeDuration("P3DT1H15M")) returns 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 on xs:date and xs:yearMonthDuration values.

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

The expression op:add-yearMonthDuration-to-date(xs:date("2000-10-30"), xs:yearMonthDuration("P1Y2M")) returns 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 on xs:date and xs:dayTimeDuration values.

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

The expression op:add-dayTimeDuration-to-date(xs:date("2004-10-30Z"), xs:dayTimeDuration("P2DT2H30M0S")) returns xs:date("2004-11-01Z"). ( The starting instant of the first argument is the xs:dateTime value {2004, 10, 30, 0, 0, 0, PT0S}. Adding the second argument to this gives the xs:dateTime value {2004, 11, 1, 2, 30, 0, PT0S}. The time components are then discarded. ).

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 on xs:date and xs:yearMonthDuration values.

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

The expression op:subtract-yearMonthDuration-from-date(xs:date("2000-10-30"), xs:yearMonthDuration("P1Y2M")) returns xs:date("1999-08-30").

The expression op:subtract-yearMonthDuration-from-date(xs:date("2000-02-29Z"), xs:yearMonthDuration("P1Y")) returns xs:date("1999-02-28Z").

The expression op:subtract-yearMonthDuration-from-date(xs:date("2000-10-31-05:00"), xs:yearMonthDuration("P1Y1M")) returns 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 on xs:date and xs:dayTimeDuration values.

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

The expression op:subtract-dayTimeDuration-from-date(xs:date("2000-10-30"), xs:dayTimeDuration("P3DT1H15M")) returns 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 on xs:time and xs:dayTimeDuration values.

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

The expression op:add-dayTimeDuration-to-time(xs:time("11:12:00"), xs:dayTimeDuration("P3DT1H15M")) returns xs:time("12:27:00").

The expression op:add-dayTimeDuration-to-time(xs:time("23:12:00+03:00"), xs:dayTimeDuration("P1DT3H15M")) returns xs:time("02:27:00+03:00"). (That is, {0, 0, 0, 2, 27, 0, 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 on xs:time and xs:dayTimeDuration values.

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 add-dayTimeDuration-to-time.

Examples

The expression op:subtract-dayTimeDuration-from-time(xs:time("11:12:00"), xs:dayTimeDuration("P3DT1H15M")) returns xs:time("09:57:00").

The expression op:subtract-dayTimeDuration-from-time(xs:time("08:20:00-05:00"), xs:dayTimeDuration("P23DT10H10M")) returns 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 signatures are presented first, followed by the rules which apply to each of the functions.

9.8.1 fn:format-dateTime

Summary

Returns a string containing an xs:dateTime value formatted for display.

Signatures
fn:format-dateTime($value as xs:dateTime?, $picture as xs:string) as xs:string?
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

The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default calendar, and default language, and default place, and implicit timezone.

The five-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

See 9.8.4 The date/time formatting functions.

9.8.2 fn:format-date

Summary

Returns a string containing an xs:date value formatted for display.

Signatures
fn:format-date($value as xs:date?, $picture as xs:string) as xs:string?
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

The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default calendar, and default language, and default place, and implicit timezone.

The five-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

Rules

See 9.8.4 The date/time formatting functions.

9.8.3 fn:format-time

Summary

Returns a string containing an xs:time value formatted for display.

Signatures
fn:format-time($value as xs:time?, $picture as xs:string) as xs:string?
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

The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default calendar, and default language, and default place, and implicit timezone.

The five-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.

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

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

Whether or not a presentation modifier is included, a width modifier may be supplied. This indicates the number of characters or digits to be included in the representation of the value.

The width modifier, if present, is introduced by a comma or semicolon. 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. Both integers, if present, must be greater than zero.

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.

A numeric format token may contain optional-digit-signs and grouping-separators as described for fn:format-integer. However, the grouping separator cannot be a closing square bracket ("]").

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 produce an ·implementation-defined· number of digits. If exactly one digit is required, this can be achieved using the component specifier [f1,1-1].

If the minimum and maximum width are unspecified, then the output uses as many characters as are required to represent the value of the component without truncation and without padding: this is referred to below as the full representation of the value. For a timezone offset (component specifier z), the full representation consists of a sign for the offset, the number of hours of the offset, and if the offset is not an integral number of hours, a colon (:) followed by the two digits of the minutes of the offset..

If the full representation of the value exceeds the specified maximum width, then the processor should attempt to use an alternative shorter representation that fits within the maximum width. Where the presentation modifier is N, n, or Nn, this is done by abbreviating the name, using either conventional abbreviations if available, or crude right-truncation if not. For example, setting max-width to 4 indicates that four-letter abbreviations should be used, though it would be acceptable to use a three-letter abbreviation if this is in conventional use. (For example, "Tuesday" might be abbreviated to "Tues", and "Friday" to "Fri".) In the case of the year component, setting max-width requests omission of high-order digits from the year, for example, if max-width is set to 2 then the year 2003 will be output as 03. In the case of the fractional seconds component, the value is rounded to the specified size as if by applying the function round-half-to-even(fractional-seconds, max-width). If no mechanism is available for fitting the value within the specified maximum width (for example, when roman numerals are used), then the value should be output in its full representation.

If the full representation of the value is shorter than the specified minimum width, then the processor should pad the value to the specified width.

  • For decimal representations of numbers, this should be done by prepending zero digits from the appropriate set of digit characters, or appending zero digits in the case of the fractional seconds component.

  • For timezone offsets this should be done by first appending a colon (:) followed by two zero digits from the appropriate set of digit characters if the full representation does not already include a minutes component and if the specified minimum width permits adding three characters, and then if necessary prepending zero digits from the appropriate set of digit characters to the hour component.

  • In other cases, it should be done by appending spaces.

9.8.4.2 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 or Olson timezone name 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
9.8.4.3 The language, calendar, and place arguments

The set of languages, calendars, and places that are supported in the ·date formatting functions· is ·implementation-defined·. When any of these arguments is omitted or is an empty sequence, an ·implementation-defined· default value is used.

If the fallback representation uses a different calendar from that requested, the output string must identify the calendar actually used, for example by prefixing the string with [Calendar: X] (where X is the calendar actually used), localized as appropriate to the requested language. If the fallback representation uses a different language from that requested, the output string must identify the language actually used, for example by prefixing the string with [Language: Y] (where Y is the language actually used) localized in an implementation-dependent way. If a particular component of the value cannot be output in the requested format, it should be output in the default format for that component.

The $language argument specifies the language to be used for the result string of the function. The value of the argument should be either the empty sequence or a value that would be valid for the xml:lang attribute (see [XML]). Note that this permits the identification of sublanguages based on country codes (from [ISO 3166-1]) as well as identification of dialects and of regions within a country.

If the $language argument is omitted or is set to an empty sequence, or if it is set to an invalid value or a value that the implementation does not recognize, then the processor uses the default language defined in the dynamic context.

The language is used to select the appropriate language-dependent forms of:

names (for example, of months)
numbers expressed as words or as ordinals (twenty, 20th, twentieth)
hour convention (0-23 vs 1-24, 0-11 vs 1-12)
first day of week, first week of year

Where appropriate this choice may also take into account the value of the $place argument, though this should not be used to override the language or any sublanguage that is specified as part of the language argument.

The choice of the names and abbreviations used in any given language is ·implementation-defined·. For example, one implementation might abbreviate July as Jul while another uses Jly. In German, one implementation might represent Saturday as Samstag while another uses Sonnabend. Implementations may provide mechanisms allowing users to control such choices.

Where ordinal numbers are used, the selection of the correct representation of the ordinal (for example, the linguistic gender) may depend on the component being formatted and on its textual context in the picture string.

The calendar attribute specifies that the dateTime, date, or time supplied in the $value argument must be converted to a value in the specified calendar and then converted to a string using the conventions of that calendar.

The calendar value if present must be a valid EQName (dynamic error: [err:FOFD1340]). If it is a lexical QName then it is expanded into an expanded QName using the statically known namespaces; if it has no prefix then it represents an expanded-QName in no namespace. If the expanded QName is in no namespace, then it must identify a calendar with a designator specified below (dynamic error: [err:FOFD1340]). If the expanded QName is in a namespace then it identifies the calendar in an ·implementation-defined· way.

If the $calendar argument is omitted or is set to an empty sequence then the default calendar defined in the dynamic context is used.

Note:

The calendars listed below were known to be in use during the last hundred years. Many other calendars have been used in the past.

This specification does not define any of these calendars, nor the way that they map to the value space of the xs:date data type in [XML Schema Part 2: Datatypes Second Edition]. There may be ambiguities when dates are recorded using different calendars. For example, the start of a new day is not simultaneous in different calendars, and may also vary geographically (for example, based on the time of sunrise or sunset). Translation of dates is therefore more reliable when the time of day is also known, and when the geographic location is known. When translating dates between one calendar and another, the processor may take account of the values of the $place and/or $language arguments, with the $place argument taking precedence.

Information about some of these calendars, and algorithms for converting between them, may be found in [Calendrical Calculations].

Designator Calendar
AD Anno Domini (Christian Era)
AH Anno Hegirae (Muhammedan Era)
AME Mauludi Era (solar years since Mohammed's birth)
AM Anno Mundi (Jewish Calendar)
AP Anno Persici
AS Aji Saka Era (Java)
BE Buddhist Era
CB Cooch Behar Era
CE Common Era
CL Chinese Lunar Era
CS Chula Sakarat Era
EE Ethiopian Era
FE Fasli Era
ISO ISO 8601 calendar
JE Japanese Calendar
KE Khalsa Era (Sikh calendar)
KY Kali Yuga
ME Malabar Era
MS Monarchic Solar Era
NS Nepal Samwat Era
OS Old Style (Julian Calendar)
RS Rattanakosin (Bangkok) Era
SE Saka Era
SH Mohammedan Solar Era (Iran)
SS Saka Samvat
TE Tripurabda Era
VE Vikrama Era
VS Vikrama Samvat Era

At least one of the above calendars must be supported. It is ·implementation-defined· which calendars are supported.

The ISO 8601 calendar ([ISO 8601]), which is included in the above list and designated ISO, is very similar to the Gregorian calendar designated AD, but it differs in several ways. The ISO calendar is intended to ensure that date and time formats can be read easily by other software, as well as being legible for human users. The ISO calendar prescribes the use of particular numbering conventions as defined in ISO 8601, rather than allowing these to be localized on a per-language basis. In particular it provides a numeric 'week date' format which identifies dates by year, week of the year, and day in the week; in the ISO calendar the days of the week are numbered from 1 (Monday) to 7 (Sunday), and week 1 in any calendar year is the week (from Monday to Sunday) that includes the first Thursday of that year. The numeric values of the components year, month, day, hour, minute, and second are the same in the ISO calendar as the values used in the lexical representation of the date and time as defined in [XML Schema Part 2: Datatypes Second Edition]. The era ("E" component) with this calendar is either a minus sign (for negative years) or a zero-length string (for positive years). For dates before 1 January, AD 1, year numbers in the ISO and AD calendars are off by one from each other: ISO year 0000 is 1 BC, -0001 is 2 BC, etc.

ISO 8601 does not define a numbering for weeks within a month. When the w component is used, the convention to be adopted is that each Monday-to-Sunday week is considered to fall within a particular month if its Thursday occurs in that month; the weeks that fall in a particular month under this definition are numbered starting from 1. Thus, for example, 29 January 2013 falls in week 5 because the Thursday of the week (31 January 2013) is the fifth Thursday in January, and 1 February 2013 is also in week 5 for the same reason.

Note:

The value space of the date and time data types, as defined in XML Schema, is based on absolute points in time. The lexical space of these data types 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 (dependant 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 Olson 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

  • Olson timezone names are defined in the public-domain tz timezone database [Olson 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 Olson 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

Example: Gregorian calendar

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]")
Example: Non-Gregorian calendars

The following examples use calendars other than the Gregorian calendar.

These examples use non-Latin characters which might not display correctly in all browsers, depending on the system configuration.

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", ()) ๓๑ ธันวาคม ๒๕๔๕

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 these functions. Leading and trailing whitespace, if present, is stripped from string arguments before the result is constructed.

Function Meaning
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.
fn:QName Constructs an xs:QName value given a namespace URI and a lexical QName.

10.1.1 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($qname as xs:string?, $element as element()) as xs:QName?
Properties

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

Rules

If $qname 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 $qname, or the zero-length string if it has no prefix, and constructs an expanded-QName whose local name is taken from the supplied $qname, and whose namespace URI is taken from the string value of the namespace binding.

If the $qname 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 $qname argument is retained in the returned expanded-QName, as discussed in Section 2.1 Terminology DM30.

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:FONS0004] if $qname 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($qname, ":")) then fn:resolve-QName($qname, $element) else
            fn:QName("", $qname)

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.1.2 fn:QName

Summary

Constructs an xs:QName value given a namespace URI and a lexical QName.

Signature
fn:QName($paramURI as xs:string?, $paramQName 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 $paramURI. If $paramURI is the zero-length string or the empty sequence, it represents "no namespace".

The prefix (or absence of a prefix) in $paramQName is retained in the returned xs:QName value.

The local name in the result is taken from the local part of $paramQName.

Error Conditions

A dynamic error is raised [err:FOCA0002] if $paramQName does not have the correct lexical form for an instance of xs:QName.

A dynamic error is raised [err:FOCA0002] if $paramURI is the zero-length string or the empty sequence, and the value of $paramQName contains a colon (:).

A dynamic error may be raised [err:FOCA0002] if $paramURI is not a valid URI (XML Namespaces 1.0) or IRI (XML Namespaces 1.1).

Notes
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.2 Functions and operators related to QNames

This section specifies functions on QNames as defined in [XML Schema Part 2: Datatypes Second Edition].

Function Meaning
op:QName-equal Returns true if two supplied QNames have the same namespace URI and the same local part.
fn:prefix-from-QName Returns the prefix component of the supplied QName.
fn:local-name-from-QName Returns the local part of the supplied QName.
fn:namespace-uri-from-QName Returns the namespace URI part of the supplied QName.
fn:namespace-uri-for-prefix Returns the namespace URI of one of the in-scope namespaces for $element, identified by its namespace prefix.
fn:in-scope-prefixes Returns the prefixes of the in-scope namespaces for an element node.

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 on 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 absentDM30, 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($arg as xs:QName?) as xs:NCName?
Properties

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

Rules

If $arg is the empty sequence the function returns the empty sequence.

If $arg has no prefix component the function returns the empty sequence.

Otherwise, the function returns an xs:NCName representing the prefix component of $arg.

10.2.3 fn:local-name-from-QName

Summary

Returns the local part of the supplied QName.

Signature
fn:local-name-from-QName($arg as xs:QName?) as xs:NCName?
Properties

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

Rules

If $arg is the empty sequence the function returns the empty sequence.

Otherwise, the function returns an xs:NCName representing the local part of $arg.

Examples

The expression fn:local-name-from-QName(fn:QName("http://www.example.com/example", "person")) returns "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($arg as xs:QName?) as xs:anyURI?
Properties

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

Rules

If $arg is the empty sequence the function returns the empty sequence.

Otherwise, the function returns an xs:anyURI representing the namespace URI part of $arg.

If $arg is in no namespace, the function returns the zero-length xs:anyURI.

Examples

The expression fn:namespace-uri-from-QName(fn:QName("http://www.example.com/example", "person")) returns xs:anyURI("http://www.example.com/example").

10.2.5 fn:namespace-uri-for-prefix

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( $prefix  as xs:string?,
$element  as element()) as xs:anyURI?
Properties

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

Rules

If $element has an in-scope namespace whose namespace prefix is equal to $prefix, the function returns the namespace URI of that namespace.

If $element has no in-scope namespace whose namespace prefix is equal to $prefix, the function returns the empty sequence.

If $prefix is the zero-length string or the empty sequence, then if $element has a default namespace (that is, a namespace node with no name), the function returns the namespace URI of the default namespace. If $element has no default namespace, the function returns the empty sequence.

Prefixes are equal only if their Unicode codepoints match exactly.

Examples

let $e :=

<z:a xmlns="http://example.org/one" xmlns:z="http://example.org/two">
  <b xmlns=""/>
</z:a>

The expression fn:namespace-uri-for-prefix("z", $e) returns "http://example.org/two".

The expression fn:namespace-uri-for-prefix("", $e) returns "http://example.org/one".

The expression fn:namespace-uri-for-prefix((), $e) returns "http://example.org/one".

The expression fn:namespace-uri-for-prefix("xml", $e) returns "http://www.w3.org/XML/1998/namespace".

The expression fn:namespace-uri-for-prefix("xml", $e) returns "http://www.w3.org/XML/1998/namespace".

10.2.6 fn:in-scope-prefixes

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 ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns a sequence of strings representing the prefixes of the in-scope namespaces for $element.

For namespace bindings that have a prefix, the function returns the prefix as an xs:NCName. For the default namespace, which has no prefix, it returns the zero-length string.

The result sequence contains no duplicates.

The ordering of the result sequence is ·implementation-dependent·.

11 Operators on base64Binary and hexBinary

11.1 Comparisons of base64Binary and hexBinary values

The following comparison operators on xs:base64Binary and xs:hexBinary values are defined. Comparisons take two operands of the same type; that is, both operands must be xs:base64Binary or both operands may be xs:hexBinary. Each returns a boolean value.

A value of type xs:hexBinary can be compared with a value of type xs:base64Binary by casting one value to the other type. See 18.1.6 Casting to xs:base64Binary and xs:hexBinary.

Function Meaning
op:hexBinary-equal Returns true if two xs:hexBinary values contain the same octet sequence.
op:base64Binary-equal Returns true if two xs:base64Binary values contain the same octet sequence.

11.1.1 op:hexBinary-equal

Summary

Returns true if two xs:hexBinary values contain the same octet sequence.

Operator Mapping

Defines the semantics of the "eq" and "ne" operators on xs:hexBinary values.

Signature
op:hexBinary-equal( $value1  as xs:hexBinary,
$value2  as xs:hexBinary) 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:base64Binary-equal

Summary

Returns true if two xs:base64Binary values contain the same octet sequence.

Operator Mapping

Defines the semantics of the "eq" and "ne" operators on xs:base64Binary values.

Signature
op:base64Binary-equal( $value1  as xs:base64Binary,
$value2  as 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.

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 on 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 absentDM30, 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 nodes

This section specifies functions and operators on nodes. Nodes are formally defined in Section 6 Nodes DM30.

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 $arg 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 $arg, as an xs:anyURI value.
fn:lang This function tests whether the language of $node, or the context item if the second argument is omitted, as specified by xml:lang attributes is the same as, or is a sublanguage of, the language specified by $testlang.
op:is-same-node Returns true if the two arguments refer to the same node.
op:node-before Returns true if the node identified by the first argument precedes the node identified by the second argument in document order.
op:node-after Returns true if the node identified by the first argument follows the node identified by the second argument in document order.
fn:root Returns the root of the tree to which $arg belongs. This will usually, but not necessarily, be a document node.
fn:path Returns a path expression that can be used to select the supplied node relative to the root of its containing document.
fn:has-children Returns true if the supplied node has one or more child nodes (of any kind).
fn:innermost Returns every node within the input sequence that is not an ancestor of another member of the input sequence; the nodes are returned in document order with duplicates eliminated.
fn:outermost Returns every node within the input sequence that has no ancestor that is itself a member of the input sequence; the nodes are returned in document order with duplicates eliminated.

For the illustrative examples below assume an XQuery or transformation operating on a PurchaseOrder document containing a number of line-item elements. Each line-item has child elements called description, price, quantity, etc. whose content is different for each line-item. Quantity has simple content of type xs:decimal. Further assume that variables $item1, $item2, etc. are each bound to single line-item element nodes in the document in sequence and that the value of the quantity child of the first line-item is 5.0.

let $po :=

<PurchaseOrder>
  <line-item>
    <description>Large widget</description>
    <price>8.95</price>
    <quantity>5.0</quantity>
  </line-item>
  <line-item>
    <description>Small widget</description>
    <price>3.99</price>
    <quantity>2.0</quantity>
  </line-item>
  <line-item>
    <description>Tiny widget</description>
    <price>1.49</price>
    <quantity>805</quantity>
  </line-item>
</PurchaseOrder>

let $item1 := $po/line-item[1]

let $item2 := $po/line-item[2]

let $item3 := $po/line-item[3]

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

Signatures
fn:name() as xs:string
fn:name($arg 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 item (.). The behavior of the function if the argument is omitted is exactly the same as if the context item had been passed as the argument.

If the argument is supplied and is the empty sequence, the function returns the zero-length string.

If the node identified by $arg 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($arg)).

Error Conditions

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

13.2 fn:local-name

Summary

Returns the local part of the name of $arg as an xs:string that is either the zero-length string, or has the lexical form of an xs:NCName.

Signatures
fn:local-name() as xs:string
fn:local-name($arg 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 item (.). The behavior of the function if the argument is omitted is exactly the same as if the context item had been passed as the argument.

If the argument is supplied and is the empty sequence, the function returns the zero-length string.

If the node identified by $arg 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 $arg, as determined by the dm:node-name accessor defined in Section 5.11 node-name Accessor DM30). This will be an xs:string whose lexical form is an xs:NCName.

Error Conditions

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

13.3 fn:namespace-uri

Summary

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

Signatures
fn:namespace-uri() as xs:anyURI
fn:namespace-uri($arg 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 item had been passed as the argument.

If the node identified by $arg 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 5.11 node-name Accessor DM30) 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 $arg, as determined by the dm:node-name accessor defined in Section 5.11 node-name Accessor DM30), returned as an xs:anyURI value.

Error Conditions

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

13.4 fn:lang

Summary

This function tests whether the language of $node, or the context item if the second argument is omitted, as specified by xml:lang attributes is the same as, or is a sublanguage of, the language specified by $testlang.

Signatures
fn:lang($testlang as xs:string?) as xs:boolean
fn:lang($testlang 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 item (.) had been passed as the second argument.

The language of the argument $node, or the context item if the second argument is omitted, is determined by the value of the xml:lang attribute on the node, or, if the node has no such attribute, by the value of the xml:lang attribute on the nearest ancestor of the node that has an xml:lang attribute. If there is no such ancestor, then the function returns false.

If $testlang 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. $testlang is equal to the string-value of the relevant xml:lang attribute, or

  2. $testlang 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, "-" (the character "-" is HYPHEN-MINUS, #x002D).

Error Conditions

The following errors may be raised when $arg 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"/>

13.5 op:is-same-node

Summary

Returns true if the two arguments refer to the same node.

Operator Mapping

Defines the semantics of the "is" operator on nodes.

Signature
op:is-same-node($arg1 as node(), $arg2 as node()) as xs:boolean
Rules

If the node identified by the value of $arg1 is the same node as the node identified by the value of $arg2 (that is, the two nodes have the same identity), then the function returns true; otherwise, the function returns false.

Examples

The expression op:is-same-node($item1, $item1) returns true().

The expression op:is-same-node($item1, $item2) returns false().

13.6 op:node-before

Summary

Returns true if the node identified by the first argument precedes the node identified by the second argument in document order.

Operator Mapping

Defines the semantics of the "<<" operator.

Signature
op:node-before($arg1 as node(), $arg2 as node()) as xs:boolean
Rules

If the node identified by the value of $arg1 occurs in document order before the node identified by the value of $arg2, then the function returns true; otherwise, it returns false.

The rules determining the order of nodes within a single document and in different documents can be found in Section 2.4 Document Order DM30.

Examples

The expression op:node-before($item1, $item2) returns true().

The expression op:node-before($item1, $item1) returns false().

13.7 op:node-after

Summary

Returns true if the node identified by the first argument follows the node identified by the second argument in document order.

Operator Mapping

Defines the semantics of the ">>" operator.

Signature
op:node-after($arg1 as node(), $arg2 as node()) as xs:boolean
Rules

If the node identified by the value of $arg1 occurs in document order after the node identified by the value of $arg2, the function returns true; otherwise, it returns false.

The rules determining the order of nodes within a single document and in different documents can be found in Section 2.4 Document Order DM30.

Examples

The expression op:node-after($item1, $item2) returns false().

The expression op:node-after($item1, $item1) returns false().

The expression op:node-after($item2, $item1) returns true().

13.8 fn:root

Summary

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

Signatures
fn:root() as node()
fn:root($arg 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 item (.) is used as the default argument. The behavior of the function if the argument is omitted is exactly the same as if the context item had been passed as the argument.

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

Error Conditions

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

Examples

These examples use some variables which could be defined in [XQuery 1.0: 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 2.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"/>

fn:root($i) returns the element node $i

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

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

fn:root($newi) returns the element node $o

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

13.9 fn:path

Summary

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

Signatures
fn:path() as xs:string?
fn:path($arg as node()?) as xs:string?
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 argument is omitted is exactly the same as if the context item (.) had been passed as the argument.

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

If $arg is a document node, the function returns the string "/".

Otherwise, the function constructs a string that consists of a sequence of steps, one for each ancestor-or-self of $arg 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()=""]

Examples

let $e :=

fn:parse-xml('<?xml version="1.0"?>
<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>')
         

The expression fn:path($e) returns '/'.

The expression fn:path($e/*:p) returns '/Q{http://example.com/one}p[1]'.

The expression fn:path($e/*:p/@xml:lang) returns '/Q{http://example.com/one}p[1]/@Q{http://www.w3.org/XML/1998/namespace}lang'.

The expression fn:path($e/*:p/@author) returns '/Q{http://example.com/one}p[1]/@author'.

The expression fn:path($e/*:p/*:br[2]) returns '/Q{http://example.com/one}p[1]/Q{http://example.com/one}br[2]'.

The expression fn:path($e//text()[starts-with(normalize-space(), 'Tochter')]) returns '/Q{http://example.com/one}p[1]/text()[2]'.

let $emp :=

            <employee xml:id="ID21256">
               <empnr>E21256</empnr>
               <first>John</first>
               <last>Brown</last>
            </employee>
         

The expression fn:path($emp) returns 'Q{http://www.w3.org/2005/xpath-functions}root()'.

The expression fn:path($emp/@xml:id) returns 'Q{http://www.w3.org/2005/xpath-functions}root()/@Q{http://www.w3.org/XML/1998/namespace}id'.

The expression fn:path($emp/empnr) returns 'Q{http://www.w3.org/2005/xpath-functions}root()/Q{}empnr[1]'.

13.10 fn:has-children

Summary

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

Signatures
fn:has-children() as xs:boolean
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 item (.). The behavior of the function if the argument is omitted is exactly the same as if the context item had been passed as the argument.

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 3.0], the following construct is not streamable:

<xsl:if test="exists(row)">
  <ul>
    <xsl:for-each select="row">
       <li><xsl:value-of select="."/></li>
    </xsl:for-each>
  </ul>
</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.

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

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

14 Functions and operators on sequences

A sequence is an ordered collection of zero or more items. An item is either a node or an atomic value. The terms sequence and item are defined formally in [XQuery 3.0: An XML Query Language] and [XML Path Language (XPath) 3.0].

14.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
op:concatenate Returns the concatenation of two sequences.
fn:empty Returns true if the argument is the empty sequence.
fn:exists Returns true if the argument is a non-empty sequence.
fn:head Returns the first item in a sequence.
fn:tail Returns all but the first item in a sequence.
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:remove Returns a new sequence containing all the items of $target except the item at position $position.
fn:reverse Reverses the order of items in a sequence.
fn:subsequence Returns the contiguous sequence of items in the value of $sourceSeq beginning at the position indicated by the value of $startingLoc and continuing for the number of items indicated by the value of $length.
fn:unordered Returns the items of $sourceSeq in an ·implementation dependent· order.

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.

14.1.1 op:concatenate

Summary

Returns the concatenation of two sequences.

Operator Mapping

Defines the semantics of the infix operator ",".

Signature
op:concatenate($seq1 as item()*, $seq2 as item()*) as item()*
Properties

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

Rules

The function returns a sequence consisting of all the items in $seq1 followed by all the items in $seq2.

Notes

If either sequence is the empty sequence, the other operand is returned.

Examples

The expression op:concatenate((1, 2, 3), (4, 5)) returns (1, 2, 3, 4, 5).

The expression op:concatenate((1, 2, 3), ()) returns (1, 2, 3).

The expression op:concatenate((), ()) returns ().

14.1.2 fn:empty

Summary

Returns true if the argument is the empty sequence.

Signature
fn:empty($arg as item()*) as xs:boolean
Properties

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

Rules

If the value of $arg is the empty sequence, the function returns true; otherwise, the function returns false.

Examples

The expression fn:empty((1,2,3)[10]) returns true().

The expression fn:empty(fn:remove(("hello", "world"), 1)) returns false().

14.1.3 fn:exists

Summary

Returns true if the argument is a non-empty sequence.

Signature
fn:exists($arg as item()*) as xs:boolean
Properties

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

Rules

If the value of $arg is a non-empty sequence, the function returns true; otherwise, the function returns false.

Examples

The expression fn:exists(fn:remove(("hello"), 1)) returns false().

The expression fn:exists(fn:remove(("hello", "world"), 1)) returns true().

14.1.4 fn:head

Summary

Returns the first item in a sequence.

Signature
fn:head($arg as item()*) as item()?
Properties

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

Rules

The function returns the value of the expression $arg[1]

Notes

If $arg is the empty sequence, the empty sequence is returned. Otherwise the first item in the sequence is returned.

Examples

The expression fn:head(1 to 5) returns 1.

The expression fn:head(("a", "b", "c")) returns "a".

The expression fn:head(()) returns ().

14.1.5 fn:tail

Summary

Returns all but the first item in a sequence.

Signature
fn:tail($arg as item()*) as item()*
Properties

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

Rules

The function returns the value of the expression subsequence($arg, 2)

Notes

If $arg is the empty sequence, or a sequence containing a single item, then the empty sequence is returned.

Examples

The expression fn:tail(1 to 5) returns (2, 3, 4, 5).

The expression fn:tail(("a", "b", "c")) returns ("b", "c").

The expression fn:tail("a") returns ().

The expression fn:tail(()) returns ().

14.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( $target  as item()*,
$position  as xs:integer,
$inserts  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 $target whose index is less than $position, followed by all items of $inserts, followed by the remaining elements of $target, in that order.

Notes

If $target is the empty sequence, $inserts is returned. If $inserts is the empty sequence, $target 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 $target, then the effective value of $position is equal to the number of items in $target plus 1.

The value of $target is not affected by the sequence construction.

Examples

let $abc := ("a", "b", "c")

The expression fn:insert-before($abc, 0, "z") returns ("z", "a", "b", "c").

The expression fn:insert-before($abc, 1, "z") returns ("z", "a", "b", "c").

The expression fn:insert-before($abc, 2, "z") returns ("a", "z", "b", "c").

The expression fn:insert-before($abc, 3, "z") returns ("a", "b", "z", "c").

The expression fn:insert-before($abc, 4, "z") returns ("a", "b", "c", "z").

14.1.7 fn:remove

Summary

Returns a new sequence containing all the items of $target except the item at position $position.

Signature
fn:remove($target as item()*, $position 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 $target whose index is less than $position, followed by all items of $target whose index is greater than $position.

Notes

If $position is less than 1 or greater than the number of items in $target, $target is returned.

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

Examples

let $abc := ("a", "b", "c")

The expression fn:remove($abc, 0) returns ("a", "b", "c").

The expression fn:remove($abc, 1) returns ("b", "c").

The expression fn:remove($abc, 6) returns ("a", "b", "c").

The expression fn:remove((), 3) returns ().

14.1.8 fn:reverse

Summary

Reverses the order of items in a sequence.

Signature
fn:reverse($arg as item()*) as item()*
Properties

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

Rules

The function returns a sequence containing the items in $arg in reverse order.

Notes

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

Examples

let $abc := ("a", "b", "c")

The expression fn:reverse($abc) returns ("c", "b", "a").

The expression fn:reverse(("hello")) returns ("hello").

The expression fn:reverse(()) returns ().

14.1.9 fn:subsequence

Summary

Returns the contiguous sequence of items in the value of $sourceSeq beginning at the position indicated by the value of $startingLoc and continuing for the number of items indicated by the value of $length.

Signatures
fn:subsequence($sourceSeq as item()*, $startingLoc as xs:double) as item()*
fn:subsequence( $sourceSeq  as item()*,
$startingLoc  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, returns:

$sourceSeq[fn:round($startingLoc) le position()]

In the three-argument case, returns:

$sourceSeq[fn:round($startingLoc) le position() 
         and position() lt fn:round($startingLoc) + fn:round($length)]
Notes

The first item of a sequence is located at position 1, not position 0.

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

If $startingLoc is zero or negative, the subsequence includes items from the beginning of the $sourceSeq.

If $length is not specified, the subsequence includes items to the end of $sourceSeq.

If $length is greater than the number of items in the value of $sourceSeq following $startingLoc, the subsequence includes items to the end of $sourceSeq.

As an exception to the previous two notes, if $startingLoc is -INF and $length is +INF, then fn:round($startingLoc) + fn:round($length) is NaN; since position() lt NaN is always 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

let $seq := ("item1", "item2", "item3", "item4", "item5")

The expression fn:subsequence($seq, 4) returns ("item4", "item5").

The expression fn:subsequence($seq, 3, 2) returns ("item3", "item4").

14.1.10 fn:unordered

Summary

Returns the items of $sourceSeq in an ·implementation dependent· order.

Signature
fn:unordered($sourceSeq as item()*) as item()*
Properties

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

Rules

The function returns the items of $sourceSeq 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.

Examples

The expression fn:unordered((1, 2, 3, 4, 5)) returns some permutation of (1, 2, 3, 4, 5).

14.2 Functions that compare values in sequences

The functions in this section rely on comparisons between the items in one or more sequences.

Function Meaning
fn:distinct-values Returns the values that appear in a sequence, with duplicates eliminated.
fn:index-of Returns a sequence of positive integers giving the positions within the sequence $seq of items that are equal to $search.
fn:deep-equal This function assesses whether two sequences are deep-equal to each other. To be deep-equal, they must contain items that are pairwise deep-equal; and for two items to be deep-equal, they must either be atomic values that compare equal, or nodes of the same kind, with the same name, whose children are deep-equal.

14.2.1 fn:distinct-values

Summary

Returns the values that appear in a sequence, with duplicates eliminated.

Signatures
fn:distinct-values($arg as xs:anyAtomicType*) as xs:anyAtomicType*
fn:distinct-values( $arg  as xs:anyAtomicType*,
$collation  as xs:string) 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 $arg all but one of a set of values that are equal to one another. Values are compared using the eq operator, subject to the caveats defined below.

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.

The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation. This collation is used when string comparison is required.

For xs:float and xs:double values, positive zero is equal to negative zero and, although NaN does not equal itself, if $arg 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.

The order in which the sequence of values is returned is ·implementation dependent·.

Which value of a set of values that compare equal is returned is ·implementation dependent·.

If 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 $arg is the empty sequence, the function returns the empty sequence.

Examples

The expression fn:distinct-values((1, 2.0, 3, 2)) returns some permutation of (1, 3, 2.0).

The expression fn:distinct-values((xs:untypedAtomic("cherry"), xs:untypedAtomic("plum"), xs:untypedAtomic("plum"))) returns some permutation of (xs:untypedAtomic("cherry"), xs:untypedAtomic("plum")).

14.2.2 fn:index-of

Summary

Returns a sequence of positive integers giving the positions within the sequence $seq of items that are equal to $search.

Signatures
fn:index-of( $seq  as xs:anyAtomicType*,
$search  as xs:anyAtomicType) as xs:integer*
fn:index-of( $seq  as xs:anyAtomicType*,
$search  as xs:anyAtomicType,
$collation  as xs:string) 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 $seq of items that are equal to $search.

The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation. This collation is used when string comparison is required.

The items in the sequence $seq are compared with $search under the rules for the eq operator. Values of type xs:untypedAtomic are compared as if they were of type xs:string. Values that cannot be compared, because the eq operator is not defined for their types, are considered to be distinct. If an item compares equal, then the position of that item in the sequence $seq 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 the value of $seq is the empty sequence, or if no item in $seq matches $search, then the function returns the empty sequence.

No error occurs if non-comparable values are encountered. So when comparing two atomic values, the effective boolean value of fn:index-of($a, $b) is true if $a and $b are equal, false if they are not equal or not comparable.

Examples

The expression fn:index-of((10, 20, 30, 40), 35) returns ().

The expression fn:index-of((10, 20, 30, 30, 20, 10), 20) returns (2, 5).

The expression fn:index-of(("a", "sport", "and", "a", "pastime"), "a") returns (1, 4).

The expression fn:index-of(current-date(), 23) returns ().

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.

14.2.3 fn:deep-equal

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 values that compare equal, or nodes of the same kind, with the same name, whose children are deep-equal.

Signatures
fn:deep-equal($parameter1 as item()*, $parameter2 as item()*) as xs:boolean
fn:deep-equal( $parameter1  as item()*,
$parameter2  as item()*,
$collation  as xs:string) 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 $collation argument identifies a collation which is used at all levels of recursion when strings are compared (but not when names are compared), according to the rules in 5.3.3 Choosing a collation.

If the two sequences are both empty, the function returns true.

If the two sequences are of different lengths, the function returns false.

If the two sequences are of the same length, the function returns true if and only if every item in the sequence $parameter1 is deep-equal to the item at the same position in the sequence $parameter2. The rules for deciding whether two items are deep-equal follow.

Call the two items $i1 and $i2 respectively.

If $i1 and $i2 are both atomic values, they are deep-equal if and only if ($i1 eq $i2) is true, or if both values are NaN. If the eq operator is not defined for $i1 and $i2, the function returns false.

If one of the pair $i1 or $i2 is an atomic value and the other is not, the function returns false.

If $i1 and $i2 are both nodes, they are compared as described below:

  1. If the two nodes are of different kinds, the result is false.

  2. If the two nodes are both document nodes then they are deep-equal if and only if the sequence $i1/(*|text()) is deep-equal to the sequence $i2/(*|text()).

  3. If the two nodes are both element nodes then they are deep-equal if and only if all of the following conditions are satisfied:

    1. The two nodes have the same name, that is (node-name($i1) eq node-name($i2)).

    2. Either both nodes are both annotated as having simple content or both nodes are annotated as having complex content. For this purpose "simple content" means either a simple type or a complex type with simple content; "complex content" means a complex type whose variety is mixed, element-only, or empty.

      Note:

      It is a consequence of this rule that 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.

    3. The two nodes have the same number of attributes, and for every attribute $a1 in $i1/@* there exists an attribute $a2 in $i2/@* such that $a1 and $a2 are deep-equal.

    4. One of the following conditions holds:

      • Both element nodes are annotated as having simple content (as defined in 3(b) above), and the typed value of $i1 is deep-equal to the typed value of $i2.

      • Both element nodes have a type annotation that is a complex type with variety element-only, and the sequence $i1/* is deep-equal to the sequence $i2/*.

      • Both element nodes have a type annotation that is a complex type with variety mixed, and the sequence $i1/(*|text()) is deep-equal to the sequence $i2/(*|text()).

      • Both element nodes have a type annotation that is a complex type with variety empty.

  4. If the two nodes are both attribute nodes then they are deep-equal if and only if both the following conditions are satisfied:

    1. The two nodes have the same name, that is (node-name($i1) eq node-name($i2)).

    2. The typed value of $i1 is deep-equal to the typed value of $i2.

  5. If the two nodes are both processing instruction nodes, then they are deep-equal if and only if both the following conditions are satisfied:

    1. The two nodes have the same name, that is (node-name($i1) eq node-name($i2)).

    2. The string value of $i1 is equal to the string value of $i2.

  6. If the two nodes are both namespace nodes, then they are deep-equal if and only if both the following conditions are satisfied:

    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.

  7. If the two nodes are both text nodes or comment nodes, then they are deep-equal if and only if their string-values are equal.

Error Conditions

A type error is raised [err:FOTY0015] if either input sequence contains a function item.

Notes

The 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 5.5 is-id Accessor DM30 and Section 5.6 is-idrefs Accessor DM30). The order of children is significant, but the order of attributes is insignificant.

The contents of comments and processing instructions are significant only if these nodes appear directly as items in the two sequences being compared. The content of a comment or processing instruction that appears as a descendant of an item in one of the sequences being compared does not affect the result. However, the presence of a comment or processing instruction, if it causes a text node to be split into two text nodes, may affect the result.

The result of fn:deep-equal(1, current-dateTime()) is false; it does not raise an error.

Examples

let $at :=

<attendees> <name last='Parker'
            first='Peter'/> <name last='Barker' first='Bob'/> <name last='Parker'
            first='Peter'/> </attendees>

The expression fn:deep-equal($at, $at/*) returns false().

The expression fn:deep-equal($at/name[1], $at/name[2]) returns false().

The expression fn:deep-equal($at/name[1], $at/name[3]) returns true().

The expression fn:deep-equal($at/name[1], 'Peter Parker') returns false().

14.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 $arg if it contains zero or one items. Otherwise, raises an error.
fn:one-or-more Returns $arg if it contains one or more items. Otherwise, raises an error.
fn:exactly-one Returns $arg 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.

14.3.1 fn:zero-or-one

Summary

Returns $arg if it contains zero or one items. Otherwise, raises an error.

Signature
fn:zero-or-one($arg as item()*) as item()?
Properties

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

Rules

Except in error cases, the function returns $arg unchanged.

Error Conditions

A dynamic error is raised [err:FORG0003] if $arg contains more than one item.

14.3.2 fn:one-or-more

Summary

Returns $arg if it contains one or more items. Otherwise, raises an error.

Signature
fn:one-or-more($arg as item()*) as item()+
Properties

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

Rules

Except in error cases, the function returns $arg unchanged.

Error Conditions

A dynamic error is raised [err:FORG0004] if $arg is an empty sequence.

14.3.3 fn:exactly-one

Summary

Returns $arg if it contains exactly one item. Otherwise, raises an error.

Signature
fn:exactly-one($arg as item()*) as item()
Properties

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

Rules

Except in error cases, the function returns $arg unchanged.

Error Conditions

A dynamic error is raised [err:FORG0005] if $arg is an empty sequence or a sequence containing more than one item.

14.4 Union, intersection and difference

Function Meaning
op:union Constructs a sequence containing every node that occurs in the values of either $arg1 or $arg2, eliminating duplicates and sorting the result in document order.
op:intersect Constructs a sequence containing every node that occurs in the values of both $arg1 and $arg2, eliminating duplicates and sorting the result in document order.
op:except Constructs a sequence containing every node that occurs in the value of $arg1 but not in the value of $arg2, eliminating duplicates and sorting the result in document order.

As in the previous sections, for the illustrative examples below, assume an XQuery or transformation operating on a Purchase Order document containing a number of line-item elements. The variables $item1, $item2, etc. are bound to individual line-item nodes in the sequence. We use sequences of these nodes in some of the examples below.

14.4.1 op:union

Summary

Constructs a sequence containing every node that occurs in the values of either $arg1 or $arg2, eliminating duplicates and sorting the result in document order.

Operator Mapping

Defines the semantics of the "union" or "|" operator.

Signature
op:union($arg1 as node()*, $arg2 as node()*) as node()*
Rules

The function returns a sequence containing every node that occurs in the values of either $arg1 or $arg2, eliminating duplicate nodes. Nodes are returned in document order.

Two nodes $n1 and $n2 are duplicates if they satisfy op:is-same-node($n1, $n2).

Notes

If either operand is the empty sequence, the result is a sequence containing the nodes in the other operand in document order after eliminating duplicates.

Examples

let $seq1 := ($item1, $item2)

let $seq2 := ($item2, $item2, $item1)

let $seq3 := ($item2, $item3)

The expression op:union($seq1, $seq1) returns ($item1, $item2).

The expression op:union($seq2, $seq3) returns ($item1, $item2, $item3).

The expression op:union($seq2, ()) returns ($item1, $item2).

14.4.2 op:intersect

Summary

Constructs a sequence containing every node that occurs in the values of both $arg1 and $arg2, eliminating duplicates and sorting the result in document order.

Operator Mapping

Defines the semantics of the "intersect" operator.

Signature
op:intersect($arg1 as node()*, $arg2 as node()*) as node()*
Rules

The function returns a sequence containing every node that occurs in the values of both $arg1 and $arg2, eliminating duplicate nodes. Nodes are returned in document order.

Two nodes $n1 and $n2 are duplicates if they satisfy op:is-same-node($n1, $n2).

Notes

If either operand is the empty sequence, the function returns the empty sequence.

Examples

let $seq1 := ($item1, $item2)

let $seq2 := ($item2, $item2, $item1)

let $seq3 := ($item2, $item3)

The expression op:intersect($seq1, $seq1) returns ($item1, $item2).

The expression op:intersect($seq2, $seq3) returns ($item2).

The expression op:intersect($seq2, ()) returns ().

The expression op:intersect($item1, $item3) returns ().

14.4.3 op:except

Summary

Constructs a sequence containing every node that occurs in the value of $arg1 but not in the value of $arg2, eliminating duplicates and sorting the result in document order.

Operator Mapping

Defines the semantics of the "except" operator.

Signature
op:except($arg1 as node()*, $arg2 as node()*) as node()*
Rules

The function returns a sequence containing every node that occurs in the value of $arg1 provided that it does not occur in the value of $arg2. Duplicate nodes are eliminated, and nodes are returned in document order.

Two nodes $n1 and $n2 are duplicates if they satisfy op:is-same-node($n1, $n2).

Notes

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

If $arg2 is the empty sequence, a sequence is returned containing the nodes in $arg1 in document order after eliminating duplicates.

Examples

let $seq1 := ($item1, $item2)

let $seq2 := ($item2, $item2, $item1)

let $seq3 := ($item2, $item3)

The expression op:except($seq1, $seq1) returns ().

The expression op:except($seq2, $seq1) returns ().

The expression op:except($seq2, $seq3) returns ($item1).

The expression op:except($seq2, ()) returns ($item1, $item2).

The expression op:except($seq3, $seq2) returns ($item3).

14.5 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 $arg, 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 $arg.

14.5.1 fn:count

Summary

Returns the number of items in a sequence.

Signature
fn:count($arg as item()*) as xs:integer
Properties

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

Rules

The function returns the number of items in the value of $arg.

Notes

Returns 0 if $arg is the empty sequence.

Examples

let $seq1 := ($item1, $item2)

let $seq2 := (98.5, 98.3, 98.9)

let $seq3 := ()

The expression fn:count($seq1) returns 2.

The expression fn:count($seq3) returns 0.

The expression fn:count($seq2) returns 3.

The expression fn:count($seq2[. > 100]) returns 0.

14.5.2 fn:avg

Summary

Returns the average of the values in the input sequence $arg, that is, the sum of the values divided by the number of values.

Signature
fn:avg($arg as xs:anyAtomicType*) as xs:anyAtomicType?
Properties

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

Rules

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

If $arg 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, $arg must contain items of a single type, which must be one of the four numeric types, xs:yearMonthDuration or xs:dayTimeDuration or one if its subtypes.

The function returns the average of the values as sum($arg) div count($arg); 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

let $d1 := xs:yearMonthDuration("P20Y")

let $d2 := xs:yearMonthDuration("P10M")

let $seq3 := (3, 4, 5)

The expression fn:avg($seq3) returns 4.0. (The result is of type xs:decimal.).

The expression fn:avg(($d1, $d2)) returns xs:yearMonthDuration("P10Y5M").

fn:avg(($d1, $seq3)) raises a type error [err:FORG0006].

The expression fn:avg(()) returns ().

The expression fn:avg((xs:float('INF'), xs:float('-INF'))) returns xs:float('NaN').

The expression fn:avg(($seq3, xs:float('NaN'))) returns xs:float('NaN').

14.5.3 fn:max

Summary

Returns a value that is equal to the highest value appearing in the input sequence.

Signatures
fn:max($arg as xs:anyAtomicType*) as xs:anyAtomicType?
fn:max($arg as xs:anyAtomicType*, $collation as xs:string) as xs:anyAtomicType?
Properties

The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.

The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base uri, and implicit timezone.

Rules

The following rules are applied to the input sequence $arg:

  • Values of type xs:untypedAtomic in $arg are cast to xs:double.

  • Numeric and xs:anyURI values are converted to the least common type reachable by a combination of type promotion and subtype substitution. See Section B.1 Type Promotion XP30 and Section B.2 Operator Mapping XP30.

The items in the resulting sequence may be reordered in an arbitrary order. The resulting sequence is referred to below as the converted sequence. The function returns an item from the converted sequence rather than the input sequence.

If the converted sequence is empty, the function returns the empty sequence.

All items in the converted sequence must be derived from a single base type for which the le operator is defined. In addition, the values in the sequence must have a total order. If date/time values do not have a timezone, they are considered to have the implicit timezone provided by the dynamic context for the purpose of comparison. Duration values must either all be xs:yearMonthDuration values or must all be xs:dayTimeDuration values.

If the converted sequence contains the value NaN, the value NaN is returned.

If the items in the converted sequence are of type xs:string or types derived by restriction from xs:string, then the determination of the item with the smallest value is made according to the collation that is used. If the type of the items in the converted sequence is not xs:string and $collation is specified, the collation is ignored.

The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation.

The function returns the result of the expression:

   if (every $v in $c satisfies $c[1] ge $v)
   then $c[1] 
   else fn:max(fn:subsequence($c, 2))

evaluated with $collation as the default collation if specified, and with $c as the converted sequence.

Error Conditions

A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.

Notes

Because the rules allow the sequence to be reordered, 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 gt, and for sorting in XQuery and XSLT, which is xs:string.

Examples

The expression fn:max((3,4,5)) returns 5.

The expression fn:max((xs:integer(5), xs:float(5.0), xs:double(0))) returns xs:double(5.0e0).

fn:max((3,4,"Zero")) raises a type error [err:FORG0006].

The expression fn:max((fn:current-date(), xs:date("2100-01-01"))) returns xs:date("2100-01-01"). (Assuming that the current date is during the 21st century.).

The expression fn:max(("a", "b", "c")) returns "c". (Assuming a typical default collation.).

14.5.4 fn:min

Summary

Returns a value that is equal to the lowest value appearing in the input sequence.

Signatures
fn:min($arg as xs:anyAtomicType*) as xs:anyAtomicType?
fn:min($arg as xs:anyAtomicType*, $collation as xs:string) as xs:anyAtomicType?
Properties

The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.

The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base uri, and implicit timezone.

Rules

The following rules are applied to the input sequence:

  • Values of type xs:untypedAtomic in $arg are cast to xs:double.

  • Numeric and xs:anyURI values are converted to the least common type reachable by a combination of type promotion and subtype substitution. See Section B.1 Type Promotion XP30 and Section B.2 Operator Mapping XP30.

The items in the resulting sequence may be reordered in an arbitrary order. The resulting sequence is referred to below as the converted sequence. The function returns an item from the converted sequence rather than the input sequence.

If the converted sequence is empty, the empty sequence is returned.

All items in the converted sequence must be derived from a single base type for which the le operator is defined. In addition, the values in the sequence must have a total order. If date/time values do not have a timezone, they are considered to have the implicit timezone provided by the dynamic context for the purpose of comparison. Duration values must either all be xs:yearMonthDuration values or must all be xs:dayTimeDuration values.

If the converted sequence contains the value NaN, the value NaN is returned.

If the items in the converted sequence are of type xs:string or types derived by restriction from xs:string, then the determination of the item with the smallest value is made according to the collation that is used. If the type of the items in the converted sequence is not xs:string and $collation is specified, the collation is ignored.

The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation.

The function returns the result of the expression:

   if (every $v in $c satisfies $c[1] le $v) 
   then $c[1] 
   else fn:min(fn:subsequence($c, 2))

evaluated with $collation as the default collation if specified, and with $c as the converted sequence.

Error Conditions

A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.

Notes

Because the rules allow the sequence to be reordered, if there are two or items that are "equal lowest", the specific item whose value is returned is ·implementation dependent·. This can arise for example if two different strings compare equal under the selected collation, or if two different xs:dateTime values compare equal despite being in different timezones.

If the converted sequence contains exactly one value then that value is returned.

The default type when the fn:min function is applied to xs:untypedAtomic values is xs:double. This differs from the default type for operators such as lt, and for sorting in XQuery and XSLT, which is xs:string.

Examples

The expression fn:min((3,4,5)) returns 3.

The expression fn:min((xs:integer(5), xs:float(5), xs:double(10))) returns xs:double(5.0e0).

fn:min((3,4,"Zero")) raises a type error [err:FORG0006].

fn:min((xs:float(0.0E0), xs:float(-0.0E0))) can return either positive or negative zero. The two items are equal, so it is ·implementation dependent· which is returned.

The expression fn:min((fn:current-date(), xs:date("1900-01-01"))) returns xs:date("1900-01-01"). (Assuming that the current date is set to a reasonable value.).

The expression fn:min(("a", "b", "c")) returns "a". (Assuming a typical default collation.).

14.5.5 fn:sum

Summary

Returns a value obtained by adding together the values in $arg.

Signatures
fn:sum($arg as xs:anyAtomicType*) as xs:anyAtomicType
fn:sum( $arg  as xs:anyAtomicType*,
$zero  as xs:anyAtomicType?) as xs:anyAtomicType?
Properties

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

Rules

Any values of type xs:untypedAtomic in $arg 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 single-argument form of the function returns the xs:integer value 0; the two-argument form returns the value of the argument $zero.

If the converted sequence contains the value NaN, NaN is returned.

All items in $arg 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, using the second signature, is the result of the expression:

if (fn:count($c) eq 0) then
    $zero
else if (fn:count($c) eq 1) then
    $c[1]
else
    $c[1] + fn:sum(subsequence($c, 2))

where $c is the converted sequence.

The result of the function, using the first signature, 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".

If the converted sequence contains exactly one value then that value is returned.

Examples

let $d1 := xs:yearMonthDuration("P20Y")

let $d2 := xs:yearMonthDuration("P10M")

let $seq1 := ($d1, $d2)

let $seq3 := (3, 4, 5)

The expression fn:sum(($d1, $d2)) returns xs:yearMonthDuration("P20Y10M").

The expression fn:sum($seq1[. lt xs:yearMonthDuration('P3M')], xs:yearMonthDuration('P0M')) returns xs:yearMonthDuration("P0M").

The expression fn:sum($seq3) returns 12.

The expression fn:sum(()) returns 0.

The expression fn:sum((),()) returns ().

The expression fn:sum((1 to 100)[. lt 0], 0) returns 0.

fn:sum(($d1, 9E1)) raises a type error [err:FORG0006].

The expression fn:sum(($d1, $d2), "ein Augenblick") returns xs:yearMonthDuration("P20Y10M"). (There is no requirement that the $zero value should be the same type as the items in $arg, or even that it should belong to a type that supports addition.).

14.6 Functions and operators that generate sequences

Function Meaning
op:to Returns a sequence of consecutive integers in a given range.

14.6.1 op:to

Summary

Returns a sequence of consecutive integers in a given range.

Operator Mapping

Defines the semantics of the "to" operator.

Signature
op:to($firstval as xs:integer, $lastval as xs:integer) as xs:integer*
Rules

The function returns the sequence containing every xs:integer whose value is between the value of $firstval (inclusive) and the value of $lastval (inclusive), in monotonic increasing order.

If the value of the first operand is greater than the value of the second, the function returns the empty sequence.

If the values of the two operands are equal, the function returns a sequence containing a single xs:integer equal to that value.

Examples

The expression 1 to 3 returns (1, 2, 3).

The expression 3 to 1 returns ().

The expression 5 to 5 returns 5.

14.7 Functions on node identifiers

14.7.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 $arg.

Signatures
fn:id($arg as xs:string*) as element()*
fn:id($arg 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 item (.) if the second argument is omitted. The behavior of the function if $node is omitted is exactly the same as if the context item had been passed as $node.

  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 5.5 is-id Accessor DM30.) 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 5.5 is-id Accessor DM30.) 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 $arg is parsed as if it were of type IDREFS, that is, each xs:string in $arg 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 
          fn:tokenize(fn: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 item if the second argument is absent, is a node in a tree whose root is not a document node.

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

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 element-with-id is being introduced with the desired behavior.

If the data model is constructed from an Infoset, an attribute will have the is-id property if the corresponding attribute in the Infoset had an attribute type of ID: typically this means the attribute was declared as an ID in a DTD.

If the data model is constructed from a PSVI, an element or attribute will have the is-id property if its typed value is a single atomic value of type xs:ID or a type derived by restriction from xs:ID.

No error is raised in respect of a candidate IDREF value that does not match the ID of any element in the document. If no candidate IDREF value matches the ID value of any element, the function returns the empty sequence.

It is not necessary that the supplied argument should have type xs:IDREF or xs:IDREFS, or that it should be derived from a node with the is-idrefs property.

An element may have more than one ID value. This can occur with synthetic data models or with data models constructed from a PSVI where the element and one of its attributes are both typed as xs:ID.

If the source document is well-formed but not valid, it is possible for two or more elements to have the same ID value. In this situation, the function will select the first such element.

It is also possible in a well-formed but invalid document to have an element or attribute that has the is-id property but whose value does not conform to the lexical rules for the xs:ID type. Such a node will never be selected by this function.

Examples

let $emp :=

            <employee xml:id="ID21256">
               <empnr>E21256</empnr>
               <first>John</first>
               <last>Brown</last>
            </employee>
         

The expression id('ID21256')/name() returns employee. (The xml:id attribute has the is-id property, so the employee element is selected.).

The expression id('E21256')/name() returns 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.).

14.7.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 $arg.

Signatures
fn:element-with-id($arg as xs:string*) as element()*
fn:element-with-id($arg 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, for legacy reasons, returns the element that has the is-id property, this parent 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 item (.) if the second argument is omitted. The behavior of the function if $node is omitted is exactly the same as if the context item had been passed as $node.

  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 5.5 is-id Accessor DM30.) 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 5.5 is-id Accessor DM30.) 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 $arg is parsed as if it were of type IDREFS, that is, each xs:string in $arg 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 
         fn:tokenize(fn: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 item if the second argument is omitted, is a node in a tree whose root is not a document node.

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

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 value of type xs:ID or a type derived by restriction from xs:ID.

No error is raised in respect of a candidate IDREF value that does not match the ID of any element in the document. If no candidate IDREF value matches the ID value of any element, the function returns the empty sequence.

It is not necessary that the supplied argument should have type xs:IDREF or xs:IDREFS, or that it should be derived from a node with the is-idrefs property.

An element may have more than one ID value. This can occur with synthetic data models or with data models constructed from a PSVI where the element and one of its attributes are both typed as xs:ID.

If the source document is well-formed but not valid, it is possible for two or more elements to have the same ID value. In this situation, the function will select the first such element.

It is also possible in a well-formed but invalid document to have an element or attribute that has the is-id property but whose value does not conform to the lexical rules for the xs:ID type. Such a node will never be selected by this function.

Examples

let $emp :=

            <employee xml:id="ID21256">
               <empnr>E21256</empnr>
               <first>John</first>
               <last>Brown</last>
            </employee>
         

The expression id('ID21256')/name() returns "employee". (The xml:id attribute has the is-id property, so the employee element is selected.).

The expression id('E21256')/name() returns "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.).

14.7.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 $arg.

Signatures
fn:idref($arg as xs:string*) as node()*
fn:idref($arg 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 item (.) if the second argument is omitted. The behavior of the function if $node is omitted is exactly the same as if the context item had been passed as $node.

  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 5.6 is-idrefs Accessor DM30) of $N is true.

      • The sequence

        fn:tokenize(fn:normalize-space(fn: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 $arg 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 $arg 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:

      $arg[. castable as xs:NCName]
      
Error Conditions

A dynamic error is raised [err:FODC0001] if $node, or the context item if the second argument is omitted, is a node in a tree whose root is not a document node.

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

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.

No error is raised in respect of a candidate ID value that does not match the IDREF value of any element or attribute in the document. If no candidate ID value matches the IDREF value of any element or attribute, the function returns the empty sequence.

It is possible for two or more nodes to have an IDREF value that matches a given candidate ID value. In this situation, the function will return all such nodes. However, each matching node will be returned at most once, regardless how many candidate ID values it matches.

It is possible in a well-formed but invalid document to have a node whose is-idrefs property is true but that does not conform to the lexical rules for the xs:IDREF type. The effect of the above rules is that ill-formed candidate ID values and ill-formed IDREF values are ignored.

If the data model is constructed from a PSVI, the typed value of a node that has the is-idrefs property will contain at least one atomic value of type xs:IDREF (or a type derived by restriction from xs:IDREF). It may also contain atomic values of other types. These atomic values are treated as candidate ID values if their lexical form is valid as an xs:NCName, and they are ignored otherwise.

14.7.4 fn:generate-id

Summary

This function returns a string that uniquely identifies a given node.

Signatures
fn:generate-id() as xs:string
fn:generate-id($arg 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 item (.). The behavior of the function if the argument is omitted is exactly the same as if the context item had been passed as the argument.

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

The returned identifier must consist of ASCII alphanumeric characters and must start with an alphabetic character. Thus, the string is syntactically an XML name.

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.

Error Conditions

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

Notes

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.

14.8 Functions giving access to external information

14.8.1 fn:doc

Summary

Retrieves a document using a URI supplied as an xs:string, and returns the corresponding document node.

Signature
fn:doc($uri 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 $uri is the empty sequence, the result is an empty sequence.

If $uri 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 XP30 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 be true:

doc("foo.xml") is doc("foo.xml")

However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is implementation-defined. If the user has not selected such an option, a call of the function must either return a deterministic result or must raise a dynamic error [err:FODC0003].

Note:

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

Error Conditions

A dynamic error may be raised [err:FODC0005] if $uri is not a valid URI.

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.

14.8.2 fn:doc-available

Summary

The function returns true if and only if the function call fn:doc($uri) would return a document node.

Signature
fn:doc-available($uri 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 $uri is an empty sequence, this function returns false.

If a call on fn:doc($uri) would return a document node, this function returns true.

A dynamic error is raised [err:FODC0005] if $uri is not a valid URI according to the rules applied by the implementation of fn:doc.

Otherwise, this function returns false.

If this function returns true, then calling fn:doc($uri) 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.

14.8.3 fn:collection

Summary

Returns a sequence of nodes representing a collection of documents indentified by a collection URI; or a default collection if no URI is supplied.

Signatures
fn:collection() as node()*
fn:collection($arg as xs:string?) as node()*
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on available node collections, and static base uri.

Rules

This function takes an xs:string as argument and returns a sequence of nodes obtained by interpreting $arg as an xs:anyURI and resolving it according to the mapping specified in Available node collections described in Section C.2 Dynamic Context Components XP30.

If Available node collections provides a mapping from this string to a sequence of nodes, the function returns that sequence. If Available node collections maps the string to an empty sequence, then the function returns an empty sequence.

If $arg is not specified, the function returns the sequence of the nodes in the default node collection in the dynamic context. See Section C.2 Dynamic Context Components XP30.

If the value of $arg is a relative xs:anyURI, it is resolved against the value of the base-URI property from the static context.

If $arg 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 the returned nodes 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 absentDM30.

A dynamic error is raised [err:FODC0002] if available node collections provides no mapping for the absolutized URI.

A dynamic error is raised [err:FODC0004] if $arg is not a valid xs:anyURI.

Notes

This function provides a facility for users to work with a collection of documents which may be contained in a directory, or in the rows of a relational table, or in some other implementation-specific construct. An implementation may also use external variables to identify external resources, but fn:collection provides functionality not provided by external variables. Specifying resources using URIs is useful because URIs are dynamic, can be parameterized, and do not rely on an external environment.

14.8.4 fn:uri-collection

Summary

Returns a sequence of xs:anyURI values representing the URIs in a resource collection.

Signatures
fn:uri-collection() as xs:anyURI*
fn:uri-collection($arg as xs:string?) as xs:anyURI*
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on available resource collections, and static base uri.

Rules

The zero-argument form of the function returns the URIs in the Default resource collection described in Section C.2 Dynamic Context Components XP30.

If the value of $arg is a relative xs:anyURI, it is resolved against the value of the base-URI property from the static context.

If $arg 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 resource collections described in Section C.2 Dynamic Context Components XP30.

Error Conditions

A dynamic error is raised [err:FODC0002] if no URI is supplied (that is, if the 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 absentDM30.

A dynamic error is raised [err:FODC0002] if available resource collections provides no mapping for the absolutized URI.

A dynamic error is raised [err:FODC0004] if $arg is not a valid xs:anyURI.

Notes

There are several reasons why it might be appropriate to use this function in preference to the fn:collection function:

  • It allows resources to be retrieved that are not well-formed XML documents: 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 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 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.

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.

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.

14.8.5 fn:unparsed-text

Summary

The fn:unparsed-text function reads an external resource (for example, a file) and returns a string representation of the resource.

Signatures
fn:unparsed-text($href as xs:string?) as xs:string?
fn:unparsed-text($href as xs:string?, $encoding as xs:string) as xs:string?
Properties

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

Rules

The $href argument must be a string in the form of a URI reference, which must contain no fragment identifier, and must identify a resource for which a string representation is available. If the URI is a relative URI reference, then it is resolved relative to the Static Base URI property from the static context.

The mapping of URIs to the string representation of a resource is the mapping defined in the available text resourcesXP30 component of the dynamic context.

If the value of the $href argument is an empty sequence, the function returns an empty sequence.

The $encoding argument, if present, is the name of an encoding. The values for this attribute follow the same rules as for the encoding attribute in an XML declaration. The only values which every ·implementation· is required to recognize are utf-8 and utf-16.

The encoding of the external resource is determined as follows:

  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 3023] and/or its successors), then the encoding is recognized as specified in [REC-xml], otherwise

  3. the value of the $encoding argument 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.

Error Conditions

A dynamic error is raised [err:FOUT1170] if $href contains a fragment identifier, or if it cannot be used to retrieve the string representation of a resource.

A dynamic error is raised [err:FOUT1190] if the value of the $encoding argument is not a valid encoding name, if the ·processor· does not support the specified encoding, if the string representation of the retrieved resource contains octets that cannot be decoded into Unicode ·characters· using the specified encoding, or if the resulting characters are not permitted XML characters.

A dynamic error is raised [err:FOUT1200] if $encoding is absent and the ·processor· cannot infer the encoding using external information and the encoding is not UTF-8.

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.

  • Implementations may provide user options that relax the requirement for the function to return deterministic results.

The rules for determining the encoding are chosen for consistency with [XML Inclusions (XInclude) Version 1.0 (Second Edition)]. Files with an XML media type are treated specially because there are use cases for this function where the retrieved text is to be included as unparsed XML within a CDATA section of a containing document, and because processors are likely to be able to reuse the code that performs encoding detection for XML external entities.

If the text file contains characters such as < and &, these will typically be output as &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>

14.8.6 fn:unparsed-text-lines

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.

Signatures
fn:unparsed-text-lines($href as xs:string?) as xs:string*
fn:unparsed-text-lines( $href  as xs:string?,
$encoding  as xs:string) 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 result of the single-argument function is the same as the result of the expression fn:tokenize(fn:unparsed-text($href), '\r\n|\r|\n')[not(position()=last() and .='')]. The result of the two-argument function is the same as the result of the expression fn:tokenize(fn:unparsed-text($href, $encoding), '\r\n|\r|\n'))[not(position()=last() and .='')].

The result is a thus a sequence of strings containing the text of the resource retrieved using the URI, each string representing one line of text. Lines are separated by one of the sequences x0A, x0D, or x0Dx0A. The characters representing the newline are not included in the returned strings. If there are two adjacent newline sequences, a zero-length string will be returned to represent the empty line; but if the external resource ends with a newline sequence, no zero-length string will be returned as the last item in the result.

Error Conditions

Error conditions are the same as for the fn:unparsed-text function.

Notes

See the notes for fn:unparsed-text.

14.8.7 fn:unparsed-text-available

Summary

Because errors in evaluating the fn:unparsed-text function are non-recoverable, these two functions are provided to allow an application to determine whether a call with particular arguments would succeed.

Signatures
fn:unparsed-text-available($href as xs:string?) as xs:boolean
fn:unparsed-text-available( $href  as xs:string?,
$encoding  as xs:string) 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 with the same arguments would succeed, and false if a call on fn:unparsed-text with the same arguments would fail with a non-recoverable dynamic error.

The functions fn:unparsed-text and fn:unparsed-text-available have the same requirement for ·determinism· as the functions fn:doc and fn:doc-available. This means that unless the user has explicitly stated a requirement for a reduced level of determinism, either of these functions if called twice with the same arguments during the course of a transformation must return the same results each time; moreover, the results of a call on fn:unparsed-text-available must be consistent with the results of a subsequent call on unparsed-text with the same arguments.

Notes

This requires that the 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 unparsed-text or 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.

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

14.8.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.9 Parsing and serializing

14.9.1 fn:parse-xml

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($arg as xs:string?) as document-node(element(*))?
Properties

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

Rules

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

The precise process used to construct the XDM instance is ·implementation-defined·. In particular, it is implementation-defined whether DTD and/or schema validation is invoked, and it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used.

The Static Base URI property from the static context of the fn:parse-xml function call is used both as the base URI used by the XML parser to resolve relative entity references within the document, and as the base URI of the document node that is returned.

The document URI of the returned node is ·absent·.

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 $arg is not a well-formed and namespace-well-formed XML document.

A dynamic error is raised [err:FODC0006] if DTD-based validation is carried out and the content of $arg is not valid against its DTD.

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.

The primary use case for this function is to handle input documents that contain nested XML documents embedded within CDATA sections. Since the content of the CDATA section are exposed as text, the receiving query or stylesheet may pass this text to the fn:parse-xml function to create a tree representation of the nested document.

Similarly, nested XML within comments is sometimes encountered, and lexical XML is sometimes returned by extension functions, for example, functions that access web services or read from databases.

A use case arises in XSLT where there is a need to preprocess an input document before parsing. For example, an application might wish to edit the document to remove its DOCTYPE declaration. This can be done by reading the raw text using the fn:unparsed-text function, editing the resulting string, and then passing it to the fn:parse-xml function.

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

14.9.2 fn:parse-xml-fragment

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($arg as xs:string?) as document-node()?
Properties

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

Rules

If $arg 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 [REC-xml], it must contain no entity references other than references to predefined entities, and it must satisfy all the rules of [Namespaces in XML] for namespace-well-formed documents with the exception that the rule requiring it to be a well-formed document is replaced by the rule requiring it to be a well-formed external general parsed entity.

The string is parsed to form a sequence of nodes which become children of the new document node, in the same way as the content of any element is converted into a sequence of children for the resulting element node.

Schema validation is not invoked, which means that the nodes in the returned document will all be untyped.

The precise process used to construct the XDM instance is ·implementation-defined·. In particular, it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used.

The Static Base URI from the static context of the fn:parse-xml-fragment function call is used as the base URI of the document node that is returned.

The document URI of the returned node is ·absent·.

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

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 fn: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 fn: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 fn:parse-xml-fragment("") returns a document node having no children.

The expression fn:parse-xml-fragment(" ") returns a document node whose children comprise a single text node whose string value is a single space.

The expression fn: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.9.3 fn:serialize

Summary

This function serializes the supplied input sequence $arg as described in [XSLT and XQuery Serialization 3.0], returning the serialized representation of the sequence as a string.

Signatures
fn:serialize($arg as item()*) as xs:string
fn:serialize( $arg  as item()*,
$params  as element(output:serialization-parameters)?) as xs:string
Properties

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

Rules

The value of $arg acts as the input sequence to the serialization process, which starts with sequence normalization.

The single-argument version of this function has the same effect as the two-argument version called with $params 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 $params argument is used to identify a set of serialization parameters. These are supplied in the form of an output:serialization-parameters element, having the format described in Section 3.1 Setting Serialization Parameters by Means of a Data Model Instance SER30.

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.

Error Conditions

If the host language makes serialization an optional feature and the implementation does not support serialization, then a dynamic error [err:FODC0010] is raised.

The serialization process will raise an error if $arg is an attribute or namespace node.

If any serialization error occurs, including the detection of an invalid value for a serialization parameter, 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.

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.

Examples

Given the output parameters:

let $params :=

<output:serialization-parameters xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization">
  <output:omit-xml-declaration value="yes"/>
</output:serialization-parameters>
         

let $data :=

<a b='3'/>
         

The following call might produce the output shown:

The expression fn:serialize($data, $params) returns '<a b="3"/>'.

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 static context.
fn:static-base-uri This function returns the value of the Static Base URI property from the static 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 XP30.)

Error Conditions

A dynamic error is raised [err:XPDY0002]XP30 if the context item is absentDM30.

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

Error Conditions

A dynamic error is raised [err:XPDY0002]XP30 if the context item is absentDM30.

Examples

The expression (1 to 20)[fn:last() - 1] returns 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 XP30.) 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

fn:current-dateTime() returns an xs:dateTimeStamp corresponding to the current date and time. For example, a call of fn: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

fn:current-date() returns an xs:date corresponding to the current date. For example, a call of fn: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

fn:current-time() returns an xs:time corresponding to the current time. For example, a call of fn: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 discussed in Section C.2 Dynamic Context Components XP30.

15.7 fn:default-collation

Summary

Returns the value of the default collation property from the static 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 static context. Components of the static context are discussed in Section C.1 Static Context Components XP30.

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.

15.8 fn:static-base-uri

Summary

This function returns the value of the Static Base URI property from the static 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 returns the value of the Static Base URI property from the static context. If the property is absent, the empty sequence is returned.

Components of the static context are discussed in Section 2.1.2 Dynamic Context XP30 .

Notes

XQuery 3.0 and XSLT 3.0 give an implementation freedom to use different base URIs during the static analysis phase and the dynamic evaluation phase, that is, for compile-time and run-time resources respectively. In this situation, the fn:static-base-uri function should return a URI suitable for locating resources needed during dynamic evaluation.

16 Higher-order functions

16.1 Functions on functions

The following functions operate on function items, that is, values referring to a function.

Function Meaning
fn:function-lookup Returns the function 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.

16.1.1 fn:function-lookup

Summary

Returns the function having a given name and arity, if there is one.

Signature
fn:function-lookup($name as xs:QName, $arity as xs:integer) as function(*)?
Properties

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

Rules

If $function-name and $function-arity identify a named function that is present in the dynamic context, then a function item corresponding to that named function is returned.

Otherwise (if no known function can be identified by name and arity), an empty sequence is returned.

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

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 has dependencies on the static or dynamic context, 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.

Examples

The expression fn:function-lookup(xs:QName('fn:substring'), 2)('abcd', 2) returns '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 := fn:function-lookup(xs:QName('zip:binary-entry', 2) return if (exists($f)) then $f($href, $entry) else () returns the result of calling zip:binary-entry($href, $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($func as function(*)) as xs:QName?
Properties

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

Rules

If $func refers to a named function, fn:function-name($func) returns the name of that function.

Otherwise ($func refers to an anonymous function), fn:function-name($func) returns an empty sequence.

The prefix part of the returned QName is ·implementation dependent·.

Examples

The expression fn:function-name(fn:substring#2) returns fn:QName("http://www.w3.org/2005/xpath-functions", "fn:substring"). (The namespace prefix of the returned QName is not predictable.).

The expression fn:function-name(function($node){count($node/*)}) returns ().

16.1.3 fn:function-arity

Summary

Returns the arity of the function identified by a function item.

Signature
fn:function-arity($func as function(*)) 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 $func.

Examples

The expression fn:function-arity(fn:substring#2) returns 2.

The expression fn:function-arity(function($node){name($node)}) returns 1.

The expression let $initial := fn:substring(?, 1, 1) return fn:function-arity($initial) returns 1.

16.2 Basic higher-order functions

The following functions take function items as an argument.

Function Meaning
fn:for-each Applies the function item $f to every item from the sequence $seq in turn, returning the concatenation of the resulting sequences in order.
fn:filter Returns those items from the sequence $seq for which the supplied function $f 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-pair Applies the function item $f to successive pairs of items taken one from $seq1 and one from $seq2, returning the concatenation of the resulting sequences in order.

16.2.1 fn:for-each

Summary

Applies the function item $f to every item from the sequence $seq in turn, returning the concatenation of the resulting sequences in order.

Signature
fn:for-each($seq as item()*, $f as function(item()) as item()*) as item()*
Properties

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

Rules

The effect of the function is equivalent to the following implementation in XQuery:

declare function fn:for-each($seq, $f) {
  if (fn:empty($seq))
  then ()
  else $f(fn:head($seq)), fn:for-each(fn:tail($seq), $f)
};

or its equivalent in XSLT:

<xsl:function name="fn:for-each">
  <xsl:param name="seq/>
  <xsl:param name="f"/>
  <xsl:if test="fn:exists($seq)">
    <xsl:sequence select="$f(fn:head($seq)), fn:for-each(fn:tail($seq), $f)"/>
  </xsl:if>
</xsl:function>
         
Notes

The function call fn:for-each($SEQ, $F) is equivalent to the expression for $i in $SEQ return $F($i), assuming that ordering mode is ordered.

Examples

The expression fn:for-each(1 to 5, function($a) { $a * $a }) returns (1, 4, 9, 16, 25).

The expression fn:for-each(("john", "jane"), fn:string-to-codepoints#1) returns (106, 111, 104, 110, 106, 97, 110, 101).

The expression fn:for-each(("23", "29"), xs:int#1) returns (23, 29).

16.2.2 fn:filter

Summary

Returns those items from the sequence $seq for which the supplied function $f returns true.

Signature
fn:filter($seq as item()*, $f as function(item()) as xs:boolean) as item()*
Properties

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

Rules

The effect of the function is equivalent to the following implementation in XQuery:

declare function fn:filter(
        $seq as item()*,
        $f as function(item()) as xs:boolean)
        as item()* {
  if (fn:empty($seq))
  then ()
  else ( fn:head($seq)[$f(.) eq fn:true()], 
         fn:filter(fn:tail($seq), $f)
       )
};

or its equivalent in XSLT:

<xsl:function name="fn:filter" as="item()*">
  <xsl:param name="seq" as="item()*"/>
  <xsl:param name="f" as="function(item()) as xs:boolean"/>
  <xsl:if test="fn:exists($seq)">
    <xsl:sequence select="fn:head($seq)[$f(.) eq fn:true()], fn:filter(fn:tail($seq), $f)"/>
  </xsl:if>
</xsl:function>
         
Error Conditions

As a consequence of the function signature and the function calling rules, a type error occurs if the supplied function $f returns anything other than a single xs:boolean item; there is no conversion to an effective boolean value.

Notes

The function call fn:filter($SEQ, $F) has a very similar effect to the expression $SEQ[$F(.)]. There are some differences, however. In the case of fn:filter, the function $F is required to return a boolean; there is no special treatment for numeric predicate values, and no conversion to an effective boolean value. Also, with a filter expression $SEQ[$F(.)], the focus within the predicate is different from that outside; this means that the use of a context-sensitive function such as fn:lang#1 will give different results in the two cases.

Examples

The expression fn:filter(1 to 10, function($a) {$a mod 2 = 0}) returns (2, 4, 6, 8, 10).

16.2.3 fn:fold-left

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( $seq  as item()*,
$zero  as item()*,
$f  as function(item()*, item()) as item()*) as item()*
Properties

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

Rules

The effect of the function is equivalent to the following implementation in XQuery:

declare function fn:fold-left(
        $seq as item()*
        $zero as item()*,
        $f as function(item()*, item()) as item()*) 
        as item()* {
  if (fn:empty($seq))
  then $zero
  else fn:fold-left(fn:tail($seq), $f($zero, fn:head($seq)), $f)
};

or its equivalent in XSLT:

<xsl:function name="fn:fold-left" as="item()*">
  <xsl:param name="seq" as="item()*"/>
  <xsl:param name="zero" as="item()*"/>
  <xsl:param name="f" as="function(item()*, item()) as item()*"/>
  <xsl:choose>
    <xsl:when test="fn:empty($seq)">
      <xsl:sequence select="$zero"/>
    </xsl:when>
    <xsl:otherwise>
      <xsl:sequence select="fn:fold-left(fn:tail($seq), $f($zero, fn:head($seq)), $f)"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:function>
         
Error Conditions

As a consequence of the function signature and the function calling rules, a type error occurs if the supplied function $f cannot be applied to two arguments, where the first argument is either the value of $zero or the result of a previous application of $f, and the second is $seq or any trailing subsequence of $seq.

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 an accumulated result as the first argument, and the next item in the sequence as the second argument. The accumulated result is initially set to the value of the $zero argument, which is conventionally a value (such as zero in the case of addition, one in the case of multiplication, or a zero-length string in the case of string concatenation) that causes the function to return the value of the other argument unchanged.

Examples

The expression fn:fold-left(1 to 5, 0, function($a, $b) { $a + $b }) returns 15. (This returns the sum of the items in the sequence).

The expression fn:fold-left((2,3,5,7), 1, function($a, $b) { $a * $b }) returns 210. (This returns the product of the items in the sequence).

The expression fn:fold-left((true(), false(), false()), false(), function($a, $b) { $a or $b }) returns true(). (This returns true if any item in the sequence has an effective boolean value of true).

The expression fn:fold-left((true(), false(), false()), false(), function($a, $b) { $a and $b }) returns false(). (This returns true only if every item in the sequence has an effective boolean value of true).

The expression fn:fold-left(1 to 5, (), function($a, $b) {($b, $a)}) returns (5,4,3,2,1). (This reverses the order of the items in a sequence).

The expression fn:fold-left(1 to 5, "", fn:concat(?, ".", ?)) returns ".1.2.3.4.5".

The expression fn:fold-left(1 to 5, "$zero", fn:concat("$f(", ?, ", ", ?, ")") returns "$f($f($f($f($f($zero, 1), 2), 3), 4), 5)".

16.2.4 fn:fold-right

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( $seq  as item()*,
$zero  as item()*,
$f  as function(item()*, item()) as item()*) as item()*
Properties

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

Rules

The effect of the function is equivalent to the following implementation in XQuery:

declare function fn:fold-right(
        $seq as item()*, 
        $zero as item()*, 
        $f as function(item(), item()*) as item()*) 
        as item()* {
  if (fn:empty($seq))
  then $zero
  else $f(fn:head($seq), fn:fold-right(fn:tail($seq), $zero, $f))
};

or its equivalent in XSLT:

<xsl:function name="fn:fold-right" as="item()*">
  <xsl:param name="seq" as="item()*"/>
  <xsl:param name="zero" as="item()*"/>
  <xsl:param name="f" as="function(item(), item()*) as item()*"/>
  <xsl:choose>
    <xsl:when test="fn:empty($seq)">
      <xsl:sequence select="$zero"/>
    </xsl:when>
    <xsl:otherwise>
      <xsl:sequence select="$f(fn:head($seq), fn:fold-right(fn:tail($seq), $zero, $f))"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:function>
         
Error Conditions

As a consequence of the function signature and the function calling rules, a type error occurs if the supplied function $f cannot be applied to two arguments, where the first argument is any item in the sequence $seq, and the second is either the value of $zero or the result of a previous application of $f.

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.

Examples

The expression fn:fold-right(1 to 5, 0, function($a, $b) { $a + $b }) returns 15. (This returns the sum of the items in the sequence).

The expression fn:fold-right(1 to 5, "", fn:concat(?, ".", ?)) returns "1.2.3.4.5.".

The expression fn:fold-right(1 to 5, "$zero", concat("$f(", ?, ", ", ?, ")")) returns "$f(1, $f(2, $f(3, $f(4, $f(5, $zero)))))".

16.2.5 fn:for-each-pair

Summary

Applies the function item $f to successive pairs of items taken one from $seq1 and one from $seq2, returning the concatenation of the resulting sequences in order.

Signature
fn:for-each-pair( $seq1  as item()*,
$seq2  as item()*,
$f  as function(item(), item()) as item()*) as item()*
Properties

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

Rules

The effect of the function is equivalent to the following implementation in XQuery:

declare function fn:for-each-pair($seq1, $seq2, $f)
{
   if(fn:exists($seq1) and fn:exists($seq2)) 
   then (
     $f(fn:head($seq1), fn:head($seq2)),
     fn:for-each-pair(fn:tail($seq1), fn:tail($seq2), $f)
   )
   else ()
};

or its equivalent in XSLT:

<xsl:function name="fn:for-each-pair">
  <xsl:param name="seq1/>
  <xsl:param name="seq2/>
  <xsl:param name="f"/>
  <xsl:if test="fn:exists($seq1) and fn:exists($seq2)">
    <xsl:sequence select="$f(fn:head($seq1), fn:head($seq2))"/>
    <xsl:sequence select="fn:for-each-pair(fn:tail($seq1), fn:tail($seq2), $f)"/>
  </xsl:if>
</xsl:function>
         
Examples

The expression fn:for-each-pair(("a", "b", "c"), ("x", "y", "z"), concat#2) returns ("ax", "by", "cz").

The expression fn:for-each-pair(1 to 5, 1 to 5, function($a, $b){10*$a + $b} returns (11, 22, 33, 44, 55).

17 Constructor functions

17.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 DM30 and the two derived types xs:yearMonthDuration and xs:dayTimeDuration defined in Section 2.7 Schema Information DM30 also have associated constructor functions. Implementations may additionally provide a constructor functions for the new data type xs:dateTimeStamp introduced in [XML Schema 1.1 Part 2: Datatypes].

A constructor function is not defined for xs:anyAtomicType as there are no atomic values with type annotation xs:anyAtomicType at runtime, although this can be a statically inferred type. A constructor function is not defined for xs:NOTATION since it is defined as an abstract type in [XML Schema Part 2: Datatypes Second Edition]. If the static context (See Section 2.1.1 Static Context XP30) contains a type derived from xs:NOTATION then a constructor function is defined for it. See 17.5 Constructor functions for user-defined types.

The form of the constructor function for an atomic type prefix:TYPE is:

fn:prefix:TYPE($arg as xs:anyAtomicType?) as prefix: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:

fn: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 XP30 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 18 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 17.2 Constructor functions for xs:QName and xs:NOTATION.

The following constructor functions for the built-in atomic types are supported:

  • fn:string($arg as xs:anyAtomicType?) as xs:string?
  • fn:boolean($arg as xs:anyAtomicType?) as xs:boolean?
  • fn:decimal($arg as xs:anyAtomicType?) as xs:decimal?
  • fn:float($arg 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.

  • fn:double($arg 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.

  • fn:duration($arg as xs:anyAtomicType?) as xs:duration?
  • fn:dateTime($arg as xs:anyAtomicType?) as xs:dateTime?
  • fn:time($arg as xs:anyAtomicType?) as xs:time?
  • fn:date($arg as xs:anyAtomicType?) as xs:date?
  • fn:gYearMonth($arg as xs:anyAtomicType?) as xs:gYearMonth?
  • fn:gYear($arg as xs:anyAtomicType?) as xs:gYear?
  • fn:gMonthDay($arg as xs:anyAtomicType?) as xs:gMonthDay?
  • fn:gDay($arg as xs:anyAtomicType?) as xs:gDay?
  • fn:gMonth($arg as xs:anyAtomicType?) as xs:gMonth?
  • fn:hexBinary($arg as xs:anyAtomicType?) as xs:hexBinary?
  • fn:base64Binary($arg as xs:anyAtomicType?) as xs:base64Binary?
  • fn:anyURI($arg as xs:anyAtomicType?) as xs:anyURI?
  • fn:QName($arg as xs:anyAtomicType?) as xs:QName?

    See 17.2 Constructor functions for xs:QName and xs:NOTATION for special rules.

  • fn:normalizedString($arg as xs:anyAtomicType?) as xs:normalizedString?
  • fn:token($arg as xs:anyAtomicType?) as xs:token?
  • fn:language($arg as xs:anyAtomicType?) as xs:language?
  • fn:NMTOKEN($arg as xs:anyAtomicType?) as xs:NMTOKEN?
  • fn:Name($arg as xs:anyAtomicType?) as xs:Name?
  • fn:NCName($arg as xs:anyAtomicType?) as xs:NCName?
  • fn:ID($arg as xs:anyAtomicType?) as xs:ID?
  • fn:IDREF($arg as xs:anyAtomicType?) as xs:IDREF?
  • fn:ENTITY($arg as xs:anyAtomicType?) as xs:ENTITY?

    See 18.1.9 Casting to xs:ENTITY for rules related to constructing values of type xs:ENTITY and types derived from it.

  • fn:integer($arg as xs:anyAtomicType?) as xs:integer?
  • fn:nonPositiveInteger($arg as xs:anyAtomicType?) as xs:nonPositiveInteger?
  • fn:negativeInteger($arg as xs:anyAtomicType?) as xs:negativeInteger?
  • fn:long($arg as xs:anyAtomicType?) as xs:long?
  • fn:int($arg as xs:anyAtomicType?) as xs:int?
  • fn:short($arg as xs:anyAtomicType?) as xs:short?
  • fn:byte($arg as xs:anyAtomicType?) as xs:byte?
  • fn:nonNegativeInteger($arg as xs:anyAtomicType?) as xs:nonNegativeInteger?
  • fn:unsignedLong($arg as xs:anyAtomicType?) as xs:unsignedLong?
  • fn:unsignedInt($arg as xs:anyAtomicType?) as xs:unsignedInt?
  • fn:unsignedShort($arg as xs:anyAtomicType?) as xs:unsignedShort?
  • fn:unsignedByte($arg as xs:anyAtomicType?) as xs:unsignedByte?
  • fn:positiveInteger($arg as xs:anyAtomicType?) as xs:positiveInteger?
  • fn:yearMonthDuration($arg as xs:anyAtomicType?) as xs:yearMonthDuration?
  • fn:dayTimeDuration($arg as xs:anyAtomicType?) as xs:dayTimeDuration?
  • fn:untypedAtomic($arg as xs:anyAtomicType?) as xs:untypedAtomic?
  • fn:dateTimeStamp($arg as xs:anyAtomicType?) as xs:dateTimeStamp?

    Available only if the implementation supports XSD 1.1.

17.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 element/type namespace from the static context. Components of the static context are defined in Section 2.1.1 Static Context XP30. A dynamic error is raised [err:FONS0004] if the prefix is not bound in the static context. As described in Section 2.1 Terminology DM30, 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, fn:QName#1 or fn: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.

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

  • fn:NMTOKENS($arg as xs:anyAtomicType?) as xs:NMTOKEN*
  • fn:ENTITIES($arg as xs:anyAtomicType?) as xs:ENTITY*
  • fn:IDREFS($arg as xs:anyAtomicType?) 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)

17.4 Constructor functions for XML Schema built-in union types

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:

  • fn:error($arg as xs:anyAtomicType?) as xs:error?

The semantics are equivalent to casting to the corresponding union type (see 18.3.5 Casting to union types).

Note:

Because xs:error has no member types, and therefore has an empty value space, casting will always fail with a dynamic error except in the case where the supplied argument is an empty sequence, in which case the result is also an empty sequence.

17.5 Constructor functions for user-defined types

For every user-defined simple type in the static context (See Section 2.1.1 Static Context XP30), there is a constructor function whose name is the same as the name of the type and 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 17.1 Constructor functions for XML Schema built-in atomic types.

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 17.2 Constructor functions for xs:QName and xs:NOTATION.

Consider a situation where the static context contains an atomic type called hatSize defined in a schema whose target namespace is bound to the prefix eg. In such a case the following constructor function is available to users:

eg:hatSize($arg as xs:anyAtomicType?) as my:hatSize?

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.

To construct an instance of a user-defined type that is not in a namespace, it is necessary to use a cast expression or undeclare the default function namespace. For example, if the user-defined type apple is derived from xs:integer but is not in a namespace, an instance of this type can be constructed as follows using a cast expression (this requires that the default element/type namespace is no namespace):

17 cast as apple

The following shows the use of the constructor function:

declare default function namespace ""; apple(17)

18 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, with identical semantics and different syntax. The name of the constructor function is the same as the name of the built-in [XML Schema Part 2: Datatypes Second Edition] datatype or the datatype defined in Section 2.7 Schema Information DM30 of [XQuery and XPath Data Model (XDM) 3.0] (see 17.1 Constructor functions for XML Schema built-in atomic types) or the user-derived datatype (see 17.5 Constructor functions for user-defined types) that is the target for the conversion, and the semantics are exactly the same as for a cast expression; for example," xs:date("2003-01-01") " means exactly the same as " "2003-01-01" cast as xs:date? ".

The cast expression takes a type name to indicate the target type of the conversion. See Section 3.13.2 Cast XP30. 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]XP30.

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 18.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 18.2 Casting from xs:string and xs:untypedAtomic. Casting to non-primitive types, including atomic types derived by resctriction, union types, and list types, is described in 18.3 Casting involving non-primitive types. Casting from derived types is defined in 18.3.2 Casting from derived types to parent types, 18.3.3 Casting within a branch of the type hierarchy and 18.3.4 Casting across the type hierarchy.

When casting from xs:string or xs:untypedAtomic the semantics in 18.2 Casting from xs:string and xs:untypedAtomic apply, regardless of target type.

18.1 Casting from primitive types to primitive types

This section defines casting between the 19 primitive types defined in [XML Schema Part 2: Datatypes Second Edition] as well as xs:untypedAtomic, xs:integer and the two derived types of xs:duration (xs:yearMonthDuration and xs:dayTimeDuration). These four types are not primitive types but they are treated as primitive types in this section. The type conversions that are supported between primitive atomic types are indicated in the table below; casts between other (non-primitive) types are defined in terms of these primitives.

In this table, there is a row for each primitive type acting as the source of the conversion and there is a column for each primitive type acting as the target of the conversion. The intersections of rows and columns contain one of three characters: "Y" indicates that a conversion from values of the type to which the row applies to the type to which the column applies is supported; "N" indicates that there are no supported conversions from values of the type to which the row applies to the type to which the column applies; and "M" indicates that a conversion from values of the type to which the row applies to the type to which the column applies may succeed for some values in the value space and fail for others.

[XML Schema Part 2: Datatypes Second Edition] defines xs:NOTATION as an abstract type. Thus, casting to xs:NOTATION from any other type including xs:NOTATION is not permitted and raises a static error [err:XPST0080]XP30. However, casting from one subtype of xs:NOTATION to another subtype of xs:NOTATION is permitted.

Casting is not supported to or from xs:anySimpleType. Thus, there is no row or column for this type in the table below. For any node that has not been validated or has been validated as xs:anySimpleType, the typed value of the node is an atomic value of type xs:untypedAtomic. There are no atomic values with the type annotation xs:anySimpleType at runtime. Casting to xs:anySimpleType is not permitted and raises a static error: [err:XPST0080]XP30.

Similarly, casting is not supported to or from xs:anyAtomicType and will raise a static error: [err:XPST0080]XP30. There are no atomic values with the type annotation xs:anyAtomicType at runtime, although this can be a statically inferred type.

If casting is attempted from an ST to a TT for which casting is not supported, as defined in the table below, a type error is raised [err:XPTY0004]XP30.

In the following table, the columns and rows are identified by short codes that identify simple types as follows:

uA = xs:untypedAtomic
aURI = xs:anyURI
b64 = xs:base64Binary
bool = xs:boolean
dat = xs:date
gDay = xs:gDay
dbl = xs:double
dec = xs:decimal
dT = xs:dateTime
dTD = xs:dayTimeDuration
dur = xs:duration
flt = xs:float
hxB = xs:hexBinary
gMD = xs:gMonthDay
gMon = xs:gMonth
int = xs:integer
NOT = xs:NOTATION
QN = xs:QName
str = xs:string
tim = xs:time
gYM = xs:gYearMonth
yMD = xs:yearMonthDuration
gYr = xs:gYear

In the following table, the notation "S\T" indicates that the source ("S") of the conversion is indicated in the column below the notation and that the target ("T") is indicated in the row to the right of the notation.

S\T uA str flt dbl dec int dur yMD dTD dT tim dat gYM gYr gMD gDay gMon bool b64 hxB aURI QN NOT
uA Y Y M M M M M M M M M M M M M M M M M M M M M
str Y Y M M M M M M M M M M M M M M M M M M M M M
flt Y Y Y Y M M N N N N N N N N N N N Y N N N N N
dbl Y Y Y Y M M N N N N N N N N N N N Y N N N N N
dec Y Y Y Y Y Y N N N N N N N N N N N Y N N N N N
int Y Y Y Y Y Y N N N N N N N N N N N Y N N N N N
dur Y Y N N N N Y Y Y N N N N N N N N N N N N N N
yMD Y Y N N N N Y Y Y N N N N N N N N N N N N N N
dTD Y Y N N N N Y Y Y N N N N N N N N N N N N N N
dT Y Y N N N N N N N Y Y Y Y Y Y Y Y N N N N N N
tim Y Y N N N N N N N N Y N N N N N N N N N N N N
dat Y Y N N N N N N N Y N Y Y Y Y Y Y N N N N N N
gYM Y Y N N N N N N N N N N Y N N N N N N N N N N
gYr Y Y N N N N N N N N N N N Y N N N N N N N N N
gMD Y Y N N N N N N N N N N N N Y N N N N N N N N
gDay Y Y N N N N N N N N N N N N N Y N N N N N N N
gMon Y Y N N N N N N N N N N N N N N Y N N N N N N
bool Y Y Y Y Y Y N N N N N N N N N N N Y N N N N N
b64 Y Y N N N N N N N N N N N N N N N N Y Y N N N
hxB Y Y N N N N N N N N N N N N N N N N Y Y N N N
aURI Y Y N N N N N N N N N N N N N N N N N N Y N N
QN Y Y N N N N N N N N N N N N N N N N N N N Y M
NOT Y Y N N N N N N N N N N N N N N N N N N N Y M

18.1.1 Casting to xs:string and xs:untypedAtomic

Casting is permitted from any primitive type to the primitive types xs:string and xs:untypedAtomic.

When a value of any simple type is cast as xs:string, the derivation of the xs:string value TV depends on the ST and on the SV, as follows.

  • If ST is xs:string or a type derived from xs:string, TV is SV.

  • If ST is xs:anyURI, the type conversion is performed without escaping any characters.

  • If ST is xs:QName or xs:NOTATION:

    • if the qualified name has a prefix, then TV is the concatenation of the prefix of SV, a single colon (:), and the local name of SV.

    • otherwise TV is the local-name.

  • If ST is a numeric type, the following rules apply:

    • If ST is xs:integer, TV is the canonical lexical representation of SV as defined in [XML Schema Part 2: Datatypes Second Edition]. There is no decimal point.

    • If ST is xs:decimal, then:

      • If SV is in the value space of xs:integer, that is, if there are no significant digits after the decimal point, then the value is converted from an xs:decimal to an xs:integer and the resulting xs:integer is converted to an xs:string using the rule above.

      • Otherwise, the canonical lexical representation of SV is returned, as defined in [XML Schema Part 2: Datatypes Second Edition].

    • If ST is xs:float or xs:double, then:

      • TV will be an xs:string in the lexical space of xs:double or xs:float that when converted to an xs:double or xs:float under the rules of 18.2 Casting from xs:string and xs:untypedAtomic produces a value that is equal to SV, or is "NaN" if SV is NaN. In addition, TV must satisfy the constraints in the following sub-bullets.

        • If SV has an absolute value that is greater than or equal to 0.000001 (one millionth) and less than 1000000 (one million), then the value is converted to an xs:decimal and the resulting xs:decimal is converted to an xs:string according to the rules above, as though using an implementation of xs:decimal that imposes no limits on the totalDigits or fractionDigits facets.

        • If SV has the value positive or negative zero, TV is "0" or "-0" respectively.

        • If SV is positive or negative infinity, TV is the string "INF" or "-INF" respectively.

        • In other cases, the result consists of a mantissa, which has the lexical form of an xs:decimal, followed by the letter "E", followed by an exponent which has the lexical form of an xs:integer. Leading zeroes and "+" signs are prohibited in the exponent. For the mantissa, there must be a decimal point, and there must be exactly one digit before the decimal point, which must be non-zero. The "+" sign is prohibited. There must be at least one digit after the decimal point. Apart from this mandatory digit, trailing zero digits are prohibited.

      Note:

      The above rules allow more than one representation of the same value. For example, the xs:float value whose exact decimal representation is 1.26743223E15 might be represented by any of the strings "1.26743223E15", "1.26743222E15" or "1.26743224E15" (inter alia). It is implementation-dependent which of these representations is chosen.

  • If ST is xs:dateTime, xs:date or xs:time, TV is the local value. The components of TV are individually cast to xs:string using the functions described in [casting-to-datetimes] and the results are concatenated together. The year component is cast to xs:string using eg:convertYearToString. The month, day, hour and minute components are cast to xs:string using eg:convertTo2CharString. The second component is cast to xs:string using eg:convertSecondsToString. The timezone component, if present, is cast to xs:string using eg:convertTZtoString.

    Note that the hours component of the resulting string will never be "24". Midnight is always represented as "00:00:00".

  • If ST is xs:yearMonthDuration or xs:dayTimeDuration, TV is the canonical representation of SV as defined in 8.1.1 xs:yearMonthDuration or 8.1.2 xs:dayTimeDuration, respectively.

  • If ST is xs:duration then let SYM be SV cast as xs:yearMonthDuration, and let SDT be SV cast as xs:dayTimeDuration; Now, let the next intermediate value, TYM, be SYM cast as TT , and let TDT be SDT cast as TT . If TYM is "P0M", then TV is TDT. Otherwise, TYM and TDT are merged according to the following rules:

    1. If TDT is "PT0S", then TV is TYM.

    2. Otherwise, TV is the concatenation of all the characters in TYM and all the characters except the first "P" and the optional negative sign in TDT.

  • In all other cases, TV is the [XML Schema Part 2: Datatypes Second Edition] canonical representation of SV. For datatypes that do not have a canonical lexical representation defined an ·implementation dependent· canonical representation may be used.

To cast as xs:untypedAtomic the value is cast as xs:string, as described above, and the type annotation changed to xs:untypedAtomic.

Note:

The string representations of numeric values are backwards compatible with XPath 1.0 except for the special values positive and negative infinity, negative zero and values outside the range 1.0e-6 to 1.0e+6.

18.1.2 Casting to numeric types

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

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

18.1.2.3 Casting to xs:decimal

When a value of any simple type is cast as xs:decimal, the xs:decimal value TV is derived from ST and SV as follows:

  • If ST is xs:decimal, xs:integer or a type derived from them, then TV is SV, converted to an xs:decimal value if need be, and the conversion is complete.

  • If ST is xs:float or xs:double, then TV is the xs:decimal value, within the set of xs:decimal values that the implementation is capable of representing, that is numerically closest to SV. If two values are equally close, then the one that is closest to zero is chosen. If SV is too large to be accommodated as an xs:decimal, (see [XML Schema Part 2: Datatypes Second Edition] for ·implementation-defined· limits on numeric values) a dynamic error is raised [err:FOCA0001]. If SV is one of the special xs:float or xs:double values NaN, INF, or -INF, a dynamic error is raised [err:FOCA0002].

  • If ST is xs:boolean, SV is converted to 1.0 if SV is 1 or true and to 0.0 if SV is 0 or false and the conversion is complete.

  • If ST is xs:untypedAtomic or xs:string, see 18.2 Casting from xs:string and xs:untypedAtomic.

18.1.2.4 Casting to xs:integer

When a value of any simple type is cast as xs:integer, the xs:integer value TV is derived from ST and SV as follows:

  • If ST is xs:integer, or a type derived from xs:integer, then TV is SV, converted to an xs:integer value if need be, and the conversion is complete.

  • If ST is xs:decimal, xs:float or xs:double, then TV is SV with the fractional part discarded and the value converted to xs:integer. Thus, casting 3.1456 returns 3 and -17.89 returns -17. Casting 3.124E1 returns 31. If SV is too large to be accommodated as an integer, (see [XML Schema Part 2: Datatypes Second Edition] for ·implementation-defined· limits on numeric values) a dynamic error is raised [err:FOCA0003]. If SV is one of the special xs:float or xs:double values NaN, INF, or -INF, a dynamic error is raised [err:FOCA0002].

  • If ST is xs:boolean, SV is converted to 1 if SV is 1 or true and to 0 if SV is 0 or false and the conversion is complete.

  • If ST is xs:untypedAtomic or xs:string, see 18.2 Casting from xs:string and xs:untypedAtomic.

18.1.3 Casting to duration types

When a value of type xs:untypedAtomic, xs:string, a type derived from xs:string, xs:yearMonthDuration or xs:dayTimeDuration is cast as xs:duration, xs:yearMonthDuration or xs:dayTimeDuration, TV is derived from ST and SV as follows:

  • If ST is the same as TT, then TV is SV.

  • If ST is xs:duration, or a type derived from xs:duration, but not xs:dayTimeDuration or a type derived from xs:dayTimeDuration, and TT is xs:yearMonthDuration, then TV is derived from SV by removing the day, hour, minute and second components from SV.

  • If ST is xs:duration, or a type derived from duration, but not xs:yearMonthDuration or a type derived from xs:yearMonthDuration, and TT is xs:dayTimeDuration, then TV is derived from SV by removing the year and month components from SV.

  • If ST is xs:yearMonthDuration or xs:dayTimeDuration, and TT is xs:duration, then TV is derived from SV as defined in 18.3.2 Casting from derived types to parent types.

  • If ST is xs:yearMonthDuration and TT is xs:dayTimeDuration, the cast is permitted and returns a xs:dayTimeDuration with value 0.0 seconds.

  • If ST is xs:dayTimeDuration and TT is xs:yearMonthDuration, the cast is permitted and returns a xs:yearMonthDuration with value 0 months.

  • If ST is xs:untypedAtomic or xs:string, see 18.2 Casting from xs:string and xs:untypedAtomic.

Note that casting from xs:duration to xs:yearMonthDuration or xs:dayTimeDuration loses information. To avoid this, users can cast the xs:duration value to both an xs:yearMonthDuration and an xs:dayTimeDuration and work with both values.

18.1.4 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 := fn:abs($year) cast as xs:string
   let $length := fn:string-length($yearString)
   return
     if ($length = 1)  then fn:concat($plusMinus, "000", $yearString)
     else
     if ($length = 2)  then fn:concat($plusMinus, "00", $yearString)
       else
       if ($length = 3)  then fn:concat($plusMinus, "0", $yearString)
       else fn:concat($plusMinus, $yearString)
}
                    
declare function eg:convertTo2CharString($value as xs:integer) as xs:string
{
   let $string := $value cast as xs:string
   return 
     if (fn:string-length($string) = 1) then fn: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 := fn:string-length(($seconds cast as xs:integer) cast as xs:string)
   return 
     if ($intLength = 1) then fn: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 := fn:hours-from-duration($tz)
     let $tzm := fn:minutes-from-duration($tz)
     let $plusMinus := if ($tzh >= 0) then "+" else "-"
     let $tzhString := eg:convertTo2CharString(fn:abs($tzh))
     let $tzmString := eg:convertTo2CharString(fn:abs($tzm))
     return fn: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( fn:year-from-date( SV )), let SMO be eg:convertTo2CharString( fn:month-from-date( SV )), let SDA be eg:convertTo2CharString( fn:day-from-date( SV )) and let STZ be eg:convertTZtoString( fn:timezone-from-date( SV )); TV is xs:dateTime( fn:concat( SYR , '-', SMO , '-', SDA , 'T00:00:00 ', STZ ) ).

    • If ST is xs:untypedAtomic or xs:string, see 18.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( fn:concat( eg:convertTo2CharString( fn:hours-from-dateTime( SV )), ':', eg:convertTo2CharString( fn:minutes-from-dateTime( SV )), ':', eg:convertSecondsToString( fn:seconds-from-dateTime( SV )), eg:convertTZtoString( fn:timezone-from-dateTime( SV )) )).

    • If ST is xs:untypedAtomic or xs:string, see 18.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( fn:year-from-dateTime( SV )), let SMO be eg:convertTo2CharString( fn:month-from-dateTime( SV )), let SDA be eg:convertTo2CharString( fn:day-from-dateTime( SV )) and let STZ be eg:convertTZtoString(fn:timezone-from-dateTime( SV )); TV is xs:date( fn:concat( SYR , '-', SMO , '-', SDA, STZ ) ).

    • If ST is xs:untypedAtomic or xs:string, see 18.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( fn:year-from-dateTime( SV )), let SMO be eg:convertTo2CharString( fn:month-from-dateTime( SV )) and let STZ be eg:convertTZtoString( fn:timezone-from-dateTime( SV )); TV is xs:gYearMonth( fn:concat( SYR , '-', SMO, STZ ) ).

    • If ST is xs:date, then let SYR be eg:convertYearToString( fn:year-from-date( SV )), let SMO be eg:convertTo2CharString( fn:month-from-date( SV )) and let STZ be eg:convertTZtoString( fn:timezone-from-date( SV )); TV is xs:gYearMonth( fn:concat( SYR , '-', SMO, STZ ) ).

    • If ST is xs:untypedAtomic or xs:string, see 18.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( fn:year-from-dateTime( SV )) and let STZ be eg:convertTZtoString( fn:timezone-from-dateTime( SV )); TV is xs:gYear(fn:concat( SYR, STZ )).

    • If ST is xs:date, let SYR be eg:convertYearToString( fn:year-from-date( SV )); and let STZ be eg:convertTZtoString( fn:timezone-from-date( SV )); TV is xs:gYear(fn:concat( SYR, STZ )).

    • If ST is xs:untypedAtomic or xs:string, see 18.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( fn:month-from-dateTime( SV )), let SDA be eg:convertTo2CharString( fn:day-from-dateTime( SV )) and let STZ be eg:convertTZtoString( fn:timezone-from-dateTime( SV )); TV is xs:gYearMonth( fn:concat( '--', SMO '-', SDA, STZ ) ).

    • If ST is xs:date, then let SMO be eg:convertTo2CharString( fn:month-from-date( SV )), let SDA be eg:convertTo2CharString( fn:day-from-date( SV )) and let STZ be eg:convertTZtoString( fn:timezone-from-date( SV )); TV is xs:gYearMonth( fn:concat( '--', SMO , '-', SDA, STZ ) ).

    • If ST is xs:untypedAtomic or xs:string, see 18.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( fn:day-from-dateTime( SV )) and let STZ be eg:convertTZtoString( fn:timezone-from-dateTime( SV )); TV is xs:gDay( fn:concat( '---', SDA, STZ )).

    • If ST is xs:date, then let SDA be eg:convertTo2CharString( fn:day-from-date( SV )) and let STZ be eg:convertTZtoString( fn:timezone-from-date( SV )); TV is xs:gDay( fn:concat( '---', SDA, STZ )).

    • If ST is xs:untypedAtomic or xs:string, see 18.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( fn:month-from-dateTime( SV )) and let STZ be eg:convertTZtoString( fn:timezone-from-dateTime( SV )); TV is xs:gMonth( fn:concat( '--' , SMO, STZ )).

    • If ST is xs:date, then let SMO be eg:convertTo2CharString( fn:month-from-date( SV )) and let STZ be eg:convertTZtoString( fn:timezone-from-date( SV )); TV is xs:gMonth( fn:concat( '--', SMO, STZ )).

    • If ST is xs:untypedAtomic or xs:string, see 18.2 Casting from xs:string and xs:untypedAtomic.

18.1.5 Casting to xs:boolean

When a value of any primitive type is cast as xs:boolean, the xs:boolean value TV is derived from ST and SV as follows:

  • If ST is xs:boolean, then TV is SV.

  • If ST is xs:float, xs:double, xs:decimal or xs:integer and SV is 0, +0, -0, 0.0, 0.0E0 or NaN, then TV is false.

  • If ST is xs:float, xs:double, xs:decimal or xs:integer and SV is not one of the above values, then TV is true.

  • If ST is xs:untypedAtomic or xs:string, see 18.2 Casting from xs:string and xs:untypedAtomic.

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

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

18.1.8 Casting to xs:QName and xs:NOTATION

Casting from xs:string or xs:untypedAtomic to xs:QName or xs:NOTATION is described in 18.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 17.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.

18.1.9 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 3.0] and [XQuery 3.0: 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.

18.2 Casting from xs:string and xs:untypedAtomic

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 18.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 17.2 Constructor functions for xs:QName and xs:NOTATION.

Note:

This version of the specification allows casting between xs:QName and xs:NOTATION in either direction; this was not permitted in the previous Recommendation. This version also removes the rule that only a string literal (rather than a dynamic string) may be cast to an xs:QName

When casting to a numeric type:

  • If the value is too large or too small to be accurately represented by the implementation, it is handled as an overflow or underflow as defined in 4.2 Arithmetic operators on numeric values.

  • If the target type is xs:float or xs:double, the string -0 (and equivalents such as -0.0 or -000) should be converted to the value negative zero. However, if the implementation is reliant on an implementation of XML Schema 1.0 in which negative zero is not part of the value space for these types, these lexical forms may be converted to positive zero.

In casting to xs:decimal or to a type derived from xs:decimal, if the value is not too large or too small but nevertheless cannot be represented accurately with the number of decimal digits available to the implementation, the implementation may round to the nearest representable value or may raise a dynamic error [err:FOCA0006]. The choice of rounding algorithm and the choice between rounding and error behavior and is ·implementation-defined·.

In casting to xs:date, xs:dateTime, xs:gYear, or xs:gYearMonth (or types derived from these), if the value is too large or too small to be represented by the implementation, a dynamic error [err:FODT0001] is raised.

In casting to a duration value, if the value is too large or too small to be represented by the implementation, a dynamic error [err:FODT0002] is raised.

For xs:anyURI, the extent to which an implementation validates the lexical form of xs:anyURI is ·implementation dependent·.

If the cast fails for any other reason, a dynamic error [err:FORG0001] is raised.

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

18.3.1 Casting to derived types

Casting a value to a derived type can be separated into four cases. Note that xs:untypedAtomic, xs:integer and the two derived types of xs:duration:xs:yearMonthDuration and xs:dayTimeDuration are treated as primitive types.

  1. When SV is an instance of a type that is derived by restriction from TT. This is described in section 18.3.2 Casting from derived types to parent types.

  2. When SV is an instance of a type derived by restriction from the same primitive type as TT. This is described in 18.3.3 Casting within a branch of the type hierarchy.

  3. When the derived type is derived, directly or indirectly, from a different primitive type than the primitive type of ST. This is described in 18.3.4 Casting across the type hierarchy.

  4. When SV is an immediate instance of TT, the cast always succeeds, returning SV unchanged.

18.3.2 Casting from derived types to parent types

It is always possible to cast an atomic value A to a type T if the relation A instance of T is true, provided that T is not an abstract type.

For example, it is possible to cast an xs:unsignedShort to an xs:unsignedInt, to an xs:integer, to an xs:decimal, or to a union type whose member types are xs:integer and xs:double.

Since the value space of the original type is a subset of the value space of the target type, such a cast is always successful.

For the expression A instance of T to be true, T must be either an atomic type, or a union type that has no constraining facets. It cannot be a list type, nor a union type derived by restriction from another union type, nor a union type that has a list type among its member types.

The result will have the same value as the original, but will have a new type annotation:

  • If T is an atomic type, then the type annotation of the result is T.

  • If T is a union type, then the type of the result is an atomic type M such that M is one of the atomic types in the transitive membership of the union type T and A instance of M is true; if there is more than one type M that satisfies these conditions (which could happen, for example, if T is the union of two overlapping types such as xs:int and xs:positiveInteger) then the first one is used, taking the member types in the order in which they appear within the definition of the union type.

18.3.3 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 lexical representation of the value, as defined for the source type (or the result of casting the value to an xs:string, in the case of types that have no canonical lexical representation defined for them).

Note that this will cause casts to fail if the pattern excludes the canonical lexical representation of the source type. For example, if the type my:distance is defined as a restriction of xs:decimal with a pattern that requires two digits after the decimal point, casting of an xs:integer to my:distance will always fail, because the canonical representation of an xs:integer does not conform to this pattern.

In some cases, casting from a parent type to a derived type requires special rules. See 18.1.3 Casting to duration types for rules regarding casting to xs:yearMonthDuration and xs:dayTimeDuration. See 18.1.9 Casting to xs:ENTITY, below, for casting to xs:ENTITY and types derived from it.

18.3.4 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 18.3.2 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. Cast the value to the primitive type of TT, as described in 18.1 Casting from primitive types to primitive types.

    • If TT is derived from xs:NOTATION, assume for the purposes of this rule that casting to xs:NOTATION succeeds.

  3. Cast the value down to the TT, as described in 18.3.3 Casting within a branch of the type hierarchy

18.3.5 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 18.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 18.3.2 Casting from derived types to parent types

    This situation only applies when the value is an instance of the union type, which means it will never apply when the union is derived by facet-based restriction from another union type.

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

18.3.6 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 18.2 Casting from xs:string and xs:untypedAtomic.

The semantics of the operation are consistent with validation: that is, the effect of casting a string S to a list type L is the same as constructing an element or attribute node whose string value is S, validating it using L as the governing type, and atomizing the resulting node. The result will always be either failure, or a sequence of zero or more atomic values each of which is an instance of the item type of L (or if the item type of L is a union type, an instance of one of the atomic types in its transitive membership).

If the item type of the list type is namespace-sensitive, then the namespace bindings in the static context will be used to resolve any namespace prefix, in the same way as when the target type is xs:QName.

If the list type has a pattern facet, the pattern must match the supplied value after collapsing whitespace (an operation equivalent to the use of the fn:normalize-space function).

For example, the expression cast "A B C D" as xs:NMTOKENS produces a sequence of four xs:NMTOKEN values, ("A", "B", "C", "D").

For example, given a user-defined type my:coordinates defined as a list of xs:integer with the facet <xs:length value="3"/>, 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. Available at: http://www.w3.org/TR/2005/REC-charmod-20050215/
IEEE 754-2008
IEEE. IEEE Standard for Floating-Point Arithmetic.
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:1997.
ISO 10967
ISO (International Organization for Standardization). ISO/IEC 10967-1:1994, Information technology—Language Independent Arithmetic—Part 1: Integer and floating point arithmetic [Geneva]: International Organization for Standardization, 1994. Available from: http://www.iso.org/
Locale Data Markup Language
Unicode Technical Standard #35, Locale Data Markup Language. Available at: http://www.unicode.org/reports/tr35/
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 2376
IETF. RFC 2376: XML Media Types. Available at: http://www.ietf.org/rfc/rfc2376.txt
RFC 3023
IETF. RFC 2376: XML Media Types. Available at: http://www.ietf.org/rfc/rfc3023.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
Olson Timezone Database
The tz timezone database, available at http://www.twinsun.com/tz/tz-link.htm. It is ·implementation-defined· which version of the database is used.
The Unicode Standard
The Unicode Consortium, Reading, MA, Addison-Wesley, 2003. 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 6.0.0.
Unicode Collation Algorithm
Unicode Technical Standard #10, Unicode Collation Algorithm. Available at: http://www.unicode.org/reports/tr10/
Unicode Normalization Forms
Unicode Standard Annex #15, Unicode Normalization Forms. Available at: http://www.unicode.org/reports/tr15/. As with [The Unicode Standard], the version to be used is ·implementation-defined·.
Unicode Regular Expressions
Unicode Technical Standard #18, Unicode Regular Expressions. Available at: http://www.unicode.org/reports/tr18/
REC-xml
World Wide Web Consortium. Extensible Markup Language (XML) 1.0 Third Edition. Available at: http://www.w3.org/TR/REC-xml/
Extensible Markup Language (XML) 1.1 Recommendation
World Wide Web Consortium. Extensible Markup Language (XML) 1.1. Available at: http://www.w3.org/TR/2004/REC-xml11-20040204/
XML Path Language (XPath) Version 1.0
XML Path Language (XPath) Version 1.0, Steven DeRose and James Clark, 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) 2.0
XML Path Language (XPath) 2.0 (Second Edition), Don Chamberlin, Anders Berglund, Scott Boag, et. al., Editors. World Wide Web Consortium, 14 December 2010. This version is http://www.w3.org/TR/2010/REC-xpath20-20101214/. The latest version is available at http://www.w3.org/TR/xpath20/.
XML Path Language (XPath) 3.0
XML Path Language (XPath) 3.0, Jonathan Robie, Don Chamberlin, Michael Dyck, John Snelson, Editors. World Wide Web Consortium, 08 January 2013. This version is http://www.w3.org/TR/2013/CR-xpath-30-20130108/. The latest version is available at http://www.w3.org/TR/xpath-30/.
XQuery 1.0 and XPath 2.0 Functions and Operators
XQuery 1.0 and XPath 2.0 Functions and Operators (Second Edition), Ashok Malhotra, Jim Melton, and Norman Walsh, Editors. World Wide Web Consortium, 14 December 2010. This version is http://www.w3.org/TR/2010/REC-xpath-functions-20101214/. The latest version is available at http://www.w3.org/TR/xpath-functions/.
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 http://www.w3.org/TR/2007/REC-xslt20-20070123/. The latest version is available at http://www.w3.org/TR/xslt20/.
XSL Transformations (XSLT) Version 3.0
XSL Transformations (XSLT) Version 3.0, Michael Kay, Editor. World Wide Web Consortium, 10 July 2012. This version is http://www.w3.org/TR/2012/WD-xslt-30-20120710/. The latest version is available at http://www.w3.org/TR/xslt-30/.
XQuery and XPath Data Model (XDM) 3.0
XQuery and XPath Data Model (XDM) 3.0, Norman Walsh, John Snelson, Editors. World Wide Web Consortium, 08 January 2013. This version is http://www.w3.org/TR/2013/CR-xpath-datamodel-30-20130108/. The latest version is available at http://www.w3.org/TR/xpath-datamodel-30/.
XSLT and XQuery Serialization 3.0
XSLT and XQuery Serialization 3.0, Henry Zongaro, Editor. World Wide Web Consortium, 19 March 2013. This version is http://www.w3.org/TR/2013/CR-xslt-xquery-serialization-30-20130319/. The latest version is available at http://www.w3.org/TR/xslt-xquery-serialization-30/.
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 http://www.w3.org/TR/2010/REC-xquery-semantics-20101214/. The latest version is available at http://www.w3.org/TR/xquery-semantics/.
XQuery 1.0: An XML Query Language
XQuery 1.0: An XML Query Language (Second Edition), Don Chamberlin, Anders Berglund, Scott Boag, et. al., Editors. World Wide Web Consortium, 14 December 2010. This version is http://www.w3.org/TR/2010/REC-xquery-20101214/. The latest version is available at http://www.w3.org/TR/xquery/.
XQuery 3.0: An XML Query Language
XQuery 3.0: An XML Query Language, Jonathan Robie, Don Chamberlin, Michael Dyck, John Snelson, Editors. World Wide Web Consortium, 08 January 2013. This version is http://www.w3.org/TR/2013/CR-xquery-30-20130108/. The latest version is available at http://www.w3.org/TR/xquery-30/.
XML Inclusions (XInclude) Version 1.0 (Second Edition)
XML Inclusions (XInclude) Version 1.0 (Second Edition), David Orchard, Jonathan Marsh, 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/
XML Schema 1.1 Part 2: Datatypes
XML Schema 1.1 Part 2: Datatypes, 3 December 2009. Available at: http://www.w3.org/TR/xmlschema11-2/
Namespaces in XML
Namespaces in XML. Available at: http://www.w3.org/TR/1999/REC-xml-names-19990114/

A.2 Non-normative references

Calendrical Calculations
Edward M. Reingold and Nachum Dershowitz. Calendrical Calculations Millennium edition (2nd Edition). Cambridge University Press, ISBN 0 521 77752 6
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/
HTML 4.0
HTML 4.01 Recommendation, 24 December 1999. Available at: http://www.w3.org/TR/REC-html40/
ISO 8601
ISO (International Organization for Standardization). Representations of dates and times, 2000-08-03. Available from: http://www.iso.org/"
POSIX.1-2008
The Open Group Base Specifications Isuse 7 (IEEE Std 1003.1-2008). Available at: http://pubs.opengroup.org/onlinepubs/9699919799/
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: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:FOCA0001, Input value too large for decimal.

Raised when casting to xs:decimal if the supplied value exceeds the implementation-defined limits for the data type.

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

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 valid XML 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: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 in not parseable as XML.

err:FODC0003, Function not defined as deterministic.

Raised by fn:doc, fn:collection to indicate that it is not possible to return a result that is guaranteed deterministic.

err:FODC0004, Invalid argument to fn:collection.

Raised by fn:collection if the argument is not a valid xs:anyURI.

err:FODC0005, Invalid argument to fn:doc or fn:doc-available.

Raised (optionally) by fn:doc and fn:doc-available 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: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: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:FODF1310, Invalid decimal format picture string.

This error is raised if the picture string supplied to fn:format-number has invalid syntax.

err:FODT0001, Overflow/underflow in date/time operation.

Raised when casting to date/time data types, 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 data types, 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 picture string.

This error is raised if the picture string 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:FONS0004, No namespace found for prefix.

Raised by fn:resolve-QName and analagous 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:FORG0001, Invalid value for cast/constructor.

A general-purpose error raised when casting, if a cast between two data types 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: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 imsx

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

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:FOTY0015, An argument to fn:deep-equal() contains a function item.

Raised by fn:deep-equal if either input sequence contains a function item.

err:FOUT1170, Invalid $href argument to fn:unparsed-text() (etc.)

A dynamic error is raised if the $href argument contains a fragment identifier, or if it cannot be used to retrieve a resource containing text.

err:FOUT1190, Cannot decode resource retrieved by fn:unparsed-text() (etc.)

A dynamic error is raised if the retrieved resource contains octets that cannot be decoded into Unicode ·characters· using the specified encoding, or if the resulting characters are not permitted XML characters. This includes the case where the processor does not support the requested encoding.

err:FOUT1200, Cannot infer encoding of resource retrieved by fn:unparsed-text() (etc.)

A dynamic error is raised if $encoding is absent and the processor cannot infer the encoding using external information and the encoding is not UTF-8.

C Illustrative user-written functions (Non-Normative)

Certain functions that were proposed for inclusion in this function library have been excluded on the basis that it is straightforward for users to implement these functions themselves using XSLT 2.0 or XQuery 1.0.

This Appendix provides sample implementations of some of these functions.

To emphasize that these functions are examples of functions that vendors may write, their names carry the prefix 'eg'. Vendors are free to define such functions in any namespace. A group of vendors may also choose to create a collection of such useful functions and put them in a common namespace.

C.1 eg:if-empty and eg:if-absent

In some situations, users may want to provide default values for missing information that may be signaled by elements that are omitted, have no value or have the empty sequence as their value. For example, a missing middle initial may be indicated by omitting the element or a non-existent bonus signaled with an empty sequence. This section includes examples of functions that provide such defaults. These functions return xs:anyAtomicType*. Users may want to write functions that return more specific types.

C.1.1 eg:if-empty

eg:if-empty($node as node()?, $value as xs:anyAtomicType) as xs:anyAtomicType*

If the first argument is the empty sequence or an element without simple or complex content, eg:if-empty() returns the second argument; otherwise, it returns the content of the first argument.

XSLT implementation

<xsl:function name="eg:if-empty" as="xs:anyAtomicType*">
  <xsl:param name="node" as="node()?"/>
  <xsl:param name="value" as="xs:anyAtomicType"/>
  <xsl:sequence select="($node[child::node()], $value)[1]"/>
</xsl:function>

XQuery implementation

declare function eg:if-empty (
  $node as node()?,
  $value as xs:anyAtomicType) as xs:anyAtomicType* 
{
  ($node[child::node()], $value)[1]
}
                    

C.1.2 eg:if-absent

eg:if-absent($node as node()?, $value as xs:anyAtomicType) as xs:anyAtomicType*

If the first argument is the empty sequence, eg:if-absent() returns the second argument; otherwise, it returns the content of the first argument.

XSLT implementation

<xsl:function name="eg:if-absent" as="xs:anyAtomicType*">
  <xsl:param name="node" as="node()?"/>
  <xsl:param name="value" as="xs:anyAtomicType"/>
  <xsl:sequence select="($node, $value)[1]"/>
</xsl:function>

XQuery implementation

declare function eg:if-absent (
  $node as node()?,
  $value as xs:anyAtomicType) as xs:anyAtomicType* 
{
  ($node, $value)[1]
}
                    

C.2 Union, intersection and difference on sequences of values

C.2.1 eg:value-union

eg:value-union( $arg1  as xs:anyAtomicType*,
$arg2  as xs:anyAtomicType*) as xs:anyAtomicType*

This function returns a sequence containing all the distinct items in $arg1 and $arg2, in an arbitrary order.

XSLT implementation

<xsl:function name="eg:value-union" as="xs:anyAtomicType*">
  <xsl:param name="arg1" as="xs:anyAtomicType*"/>
  <xsl:param name="arg2" as="xs:anyAtomicType*"/>
  <xsl:sequence
     select="fn:distinct-values(($arg1, $arg2))"/> 
</xsl:function>

XQuery implementation

declare function eg:value-union (
  $arg1 as xs:anyAtomicType*,
  $arg2 as xs:anyAtomicType*) as xs:anyAtomicType* 
{
  fn:distinct-values(($arg1, $arg2))
}
                    

C.2.2 eg:value-intersect

eg:value-intersect( $arg1  as xs:anyAtomicType*,
$arg2  as xs:anyAtomicType*) as xs:anyAtomicType*

This function returns a sequence containing all the distinct items that appear in both $arg1 and $arg2, in an arbitrary order.

XSLT implementation>

<xsl:function name="eg:value-intersect" as="xs:anyAtomicType*">
  <xsl:param name="arg1" as="xs:anyAtomicType*"/>
  <xsl:param name="arg2" as="xs:anyAtomicType*"/>
  <xsl:sequence 
     select="fn:distinct-values($arg1[.=$arg2])"/>
</xsl:function>

XQuery implementation

declare function eg:value-intersect (
  $arg1 as xs:anyAtomicType*,
  $arg2 as xs:anyAtomicType* ) as xs:anyAtomicType* 
{
  fn:distinct-values($arg1[.=$arg2])
}
                    

C.2.3 eg:value-except

eg:value-except( $arg1  as xs:anyAtomicType*,
$arg2  as xs:anyAtomicType*) as xs:anyAtomicType*

This function returns a sequence containing all the distinct items that appear in $arg1 but not in $arg2, in an arbitrary order.

XSLT implementation

<xsl:function name="eg:value-except" as="xs:anyAtomicType*">
  <xsl:param name="arg1" as="xs:anyAtomicType*"/>
  <xsl:param name="arg2" as="xs:anyAtomicType*"/>
  <xsl:sequence
     select="fn:distinct-values($arg1[not(.=$arg2)])"/>
</xsl:function>

XQuery implementation

declare function eg:value-except (
  $arg1 as xs:anyAtomicType*,
  $arg2 as xs:anyAtomicType*) as xs:anyAtomicType* 
{
  fn:distinct-values($arg1[not(.=$arg2)])
}

C.3 eg:index-of-node

eg:index-of-node($seq as node()*, $search as node()) as xs:integer*

This function returns a sequence of positive integers giving the positions within the sequence $seq of nodes that are identical to $search.

The nodes in the sequence $seq are compared with $search under the rules for the is operator. If a node compares identical, then the position of that node in the sequence $seq is included in the result.

If the value of $seq is the empty sequence, or if no node in $seq matches $search, then the empty sequence is returned.

The index is 1-based, not 0-based.

The result sequence is in ascending numeric order.

XSLT implementation

<xsl:function name="eg:index-of-node" as="xs:integer*">
  <xsl:param name="seq" as="node()*"/>
  <xsl:param name="search" as="node()"/>
  <xsl:sequence select="filter(
      function($i as xs:integer) as xs:boolean {$seq[$i] is $search}, 
      1 to count($seq)
    )
  "/>
</xsl:function>

XQuery implementation

declare function eg:index-of-node($seq as node()*, $search as node()) as xs:integer* 
{
    fn:filter(
      function($i as xs:integer) as xs:boolean {$seq[$i] is $search}, 
      1 to fn:count($seq)
    )

}

An alternative implementation, which might be faster in systems where indexing into a sequence is slow, is:

declare function eg:index-of-node($seq as node()*, $search as node()) as xs:integer* 
{
  fn:for-each-pair(function($node, $index) {
     if($node is $search) then $index else () 
  }, $seq, 1 to fn:count($seq))
}

C.4 eg:string-pad

eg:string-pad($padString as xs:string?, $padCount as xs:integer) as xs:string

Returns a xs:string consisting of a given number of copies of an xs:string argument concatenated together.

XSLT implementation

<xsl:function name="eg:string-pad" as="xs:string">
  <xsl:param name="padString" as="xs:string?"/>
  <xsl:param name="padCount" as="xs:integer"/>
  <xsl:sequence select="
     fn:string-join(for $i in 1 to $padCount return $padString)"/>
 </xsl:function>
                

XQuery implementation

declare function eg:string-pad (
  $padString as xs:string?,
  $padCount as xs:integer) as xs:string 
{
   fn:string-join(for $i in 1 to $padCount return $padString)
}
                

This returns the zero-length string if $padString is the empty sequence, which is consistent with the general principle that if an xs:string argument is the empty sequence it is treated as if it were the zero-length string.

C.5 eg:distinct-nodes-stable

eg:distinct-nodes-stable($arg as node()*) as node()*

This function illustrates one possible implementation of a distinct-nodes function. It removes duplicate nodes by identity, preserving the first occurrence of each node.

XPath

$arg[empty(subsequence($arg, 1, position()-1) intersect .)]
                

XSLT implementation

<xsl:function name="eg:distinct-nodes-stable" as="node()*">
  <xsl:param name="arg" as="node()*"/>
  <xsl:sequence select=""
    fn:fold-left(
      function($foundSoFar as node()*, $this as node()) as node()* {
        if ($foundSoFar intersect $this)
        then $foundSoFar
        else ($foundSoFar, $this)
      }, (), $seq)
  "/> 
</xsl:function>
                

XQuery implementation

declare function distinct-nodes-stable ($arg as node()*) as node()* { 
  fn:fold-left(
      function($foundSoFar as node()*, $this as node()) as node()* {
        if ($foundSoFar intersect $this)
        then $foundSoFar
        else ($foundSoFar, $this)
      }, (), $seq)

};

C.6 Finding minima and maxima

The fn:min and fn:max functions allow one to determine the smallest and largest values in a set of values, but they do not directly allow one to determine the elements having the smallest or largest value for some property, for example the employees earning the highest or lowest salary. The functions in this section show how this can be achieved.

The functions take as input an arbitrary sequence of items (typically but not necessarily a sequence of elements) and a function that computes a property value for each of these items. This must be a value of an atomic type for which order comparisons are defined. The functions return those items from the input sequence that have a higher (or lower) value for the given property than any others in the sequence. If there are several that are joint highest (or lowest) then they are all returned.

C.6.1 eg:highest

The function eg:highest returns the items having the highest value for the supplied function.

XSLT implementation

<xsl:function name="eg:highest" as="item()*">
  <xsl:param name="f" as="function(item()) as xs:anyAtomicType"/>
  <xsl:param name="seq" as="item()*"/>
  <xsl:sequence select="
     fold-left(
       function($highestSoFar as item()*, $this as item()*) as item()* {
         let $thisValue := $f($this)
         let $highestValue := $f($highestSoFar[1])
         return
           if ($thisValue gt $highestValue)
             then $this
           else if ($thisValue eq $highestValue)
             then ($highestSoFar, $this)
           else $highestSoFar
       }, head($seq), tail($seq))"/>
</xsl:function>

XQuery implementation

declare function eg:highest(
                     $f as function(item()) as xs:anyAtomicType, 
                     $seq as item()*)
                  as item()* {
     fn:fold-left(
       function($highestSoFar as item()*, $this as item()*) as item()* {
         let $thisValue := $f($this)
         let $highestValue := $f($highestSoFar[1])
         return
           if ($thisValue gt $highestValue)
             then $this
           else if ($thisValue eq $highestValue)
             then ($highestSoFar, $this)
           else $highestSoFar
       }, fn:head($seq), fn:tail($seq))
};

To find the employees with the highest salary, the function might be called as:

eg:highest(function($emp){$emp/salary}, //employee)

C.6.2 eg:lowest

The function eg:lowest returns the items having the lowest value for the supplied function.

XSLT implementation

<xsl:function name="eg:lowest" as="item()*">
  <xsl:param name="f" as="function(item()) as xs:anyAtomicType"/>
  <xsl:param name="seq" as="item()*"/>
  <xsl:sequence select="
     fold-left(
       function($lowestSoFar as item()*, $this as item()*) as item()* {
         let $thisValue := $f($this)
         let $lowestValue := $f($lowestSoFar[1])
         return
           if ($thisValue lt $lowestValue)
             then $this
           else if ($thisValue eq $lowestValue)
             then ($lowestSoFar, $this)
           else $lowestSoFar
       }, head($seq), tail($seq))"/>
</xsl:function>

XQuery implementation

declare function eg:highest(
                     $f as function(item()) as xs:anyAtomicType, 
                     $seq as item()*)
                  as item()* {
     fn:fold-left(
       function($lowestSoFar as item()*, $this as item()*) as item()* {
         let $thisValue := $f($this)
         let $lowestValue := $f($lowestSoFar[1])
         return
           if ($thisValue gt $lowestValue)
             then $this
           else if ($thisValue eq $lowestValue)
             then ($lowestSoFar, $this)
           else $lowestSoFar
       }, fn:head($seq), fn:tail($seq))
};

To find the employees with the lowest total number of hours worked, the function might be called as:

eg:lowest(function($emp){sum($emp/timesheet/period/hours}, //employee)

C.7 Sorting

Both XSLT and XQuery include constructs for sorting sequences. However, it can often be convenient to invoke sorting via a simple function call. The example function in this section takes two arguments, a sequence to be sorted, and a function to compute a sort key, and it returns the items from the input sequence in sorted order of this sort key.

XSLT implementation

<xsl:function name="eg:sort" as="item()*">
  <xsl:param name="f" as="function(item()) as xs:anyAtomicType"/>
  <xsl:param name="seq" as="item()*"/>
  <xsl:perform-sort select="$seq">
    <xsl:sort select="$f(.)"/>
  </xsl:perform-sort>
</xsl:function>

XQuery implementation

declare function eg:sort(
                     $f as function(item()) as xs:anyAtomicType, 
                     $seq as item()*)
                  as item()* {
     for $item in $seq order by $f($item) return $item
};

To obtain a list of employees sorted by salary, the function might be called as:

eg:sort(function($emp){$emp/salary}, //employee)

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

  4. Some functions (such as fn:distinct-values and fn:unordered) produce results in an ·implementation-defined· or ·implementation-dependent· order. In such cases there is no guarantee that the order of results from different calls will be the same. These functions are said to be non-deterministic with respect to ordering. (See Properties of functions.)

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

  6. In the case of a document node $D returned by the fn:doc function, or a document node at the root of a tree containing a node returned by the fn:collection function, it will always be true that either fn:document-uri($D) returns the empty sequence, or that the following expression is true: fn:doc(fn:document-uri($D)) is $D. It is ·implementation-defined· whether this guarantee also holds for document nodes obtained by other means, for example a document node passed as the initial context node of a query or transformation. (See fn:document-uri.)

  7. In addition, the values of $value, converted to an xs:string, and $label may be directed to a trace data set. The destination of the trace output is ·implementation-defined·. The format of the trace output is ·implementation dependent·. The ordering of output from calls of the fn:trace function is ·implementation dependent·. (See fn:trace.)

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

  9. For xs:decimal values the number of digits of precision returned by the numeric operators is ·implementation-defined·. If the number of digits in the result exceeds the number of digits that the implementation supports, the result is truncated or rounded in an ·implementation-defined· manner. (See Arithmetic operators on numeric values.)

  10. For xs:decimal values the number of digits of precision returned by the numeric operators is ·implementation-defined·. If the number of digits in the result exceeds the number of digits that the implementation supports, the result is truncated or rounded in an ·implementation-defined· manner. (See Arithmetic operators on numeric values.)

  11. The [IEEE 754-2008] specification also describes handling of two exception conditions called divideByZero and invalidOperation. The IEEE divideByZero exception is raised not only by a direct attempt to divide by zero, but also by operations such as log(0). The IEEE invalidOperation exception is raised by attempts to call a function with an argument that is outside the function's domain (for example, sqrt(-1) or log(-1). These IEEE exceptions do not cause a dynamic error at the application level; rather they result in the relevant function or operator returning NaN. 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 NaN with no error. (See Arithmetic operators on numeric values.)

  12. The [IEEE 754-2008] specification distinguishes two NaN values, a quiet NaN and a signaling NaN. These two values are not distinguishable in the XDM model: the value spaces of xs:float and xs:double each include only a single NaN value. This does not prevent the implementation distinguishing them internally, and triggering different ·implementation-defined· warning conditions, but such distinctions do not affect the observable behavior of an application using the functions and operators defined in this specification. (See Arithmetic operators on numeric values.)

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

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

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

  16. For all format tokens other than the first kind above (one that consists of decimal digits), 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 &#x2460; (circled digit one, ①) has a range imposed by the Unicode character repertoire — 1 to 20 in Unicode versions prior to 4.0, increased 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.)

  17. The set of languages for which numbering is supported is ·implementation-defined·. If the $lang 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.)

  18. ...either a or t, to indicate alphabetic or traditional numbering respectively, the default being ·implementation-defined·. (See fn:format-integer.)

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

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

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

  22. IEEE states that the preferred quantum is language-defined. In this specification, it is ·implementation-defined·. (See Trigonometric and exponential functions.)

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

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

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

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

  27. All minimally conforming processors ·must· support positive year values with a minimum of 4 digits (i.e., YYYY) and a minimum fractional second precision of 1 millisecond or three digits (i.e., s.sss). However, conforming processors ·may· set larger ·implementation-defined· limits on the maximum number of digits they support in these two situations. Processors ·may· also choose to support the year 0000 and years with negative values. The results of operations on dates that cross the year 0000 are ·implementation-defined·. (See Limits and precision.)

  28. All minimally conforming processors ·must· support positive year values with a minimum of 4 digits (i.e., YYYY) and a minimum fractional second precision of 1 millisecond or three digits (i.e., s.sss). However, conforming processors ·may· set larger ·implementation-defined· limits on the maximum number of digits they support in these two situations. Processors ·may· also choose to support the year 0000 and years with negative values. The results of operations on dates that cross the year 0000 are ·implementation-defined·. (See Limits and precision.)

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

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

  31. 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 produce an ·implementation-defined· number of digits. If exactly one digit is required, this can be achieved using the component specifier [f1,1-1]. (See The picture string.)

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

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

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

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

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

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

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

  39. It is ·implementation-defined· whether DTD validation and/or schema validation is applied to the source document. (See fn:doc.)

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

  41. ...the processor may use ·implementation-defined· heuristics to determine the likely encoding, otherwise... (See fn:unparsed-text.)

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

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

  44. The precise process used to construct the XDM instance is ·implementation-defined·. In particular, it is implementation-defined whether DTD and/or schema validation is invoked, and it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used. (See fn:parse-xml.)

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

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

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

  48. If ST is xs:decimal, xs:float or xs:double, then TV is SV with the fractional part discarded and the value converted to xs:integer. Thus, casting 3.1456 returns 3 and -17.89 returns -17. Casting 3.124E1 returns 31. If SV is too large to be accommodated as an integer, (see [XML Schema Part 2: Datatypes Second Edition] for ·implementation-defined· limits on numeric values) a dynamic error is raised [err:FOCA0003]. If SV is one of the special xs:float or xs:double values NaN, INF, or -INF, a dynamic error is raised [err:FOCA0002]. (See Casting to xs:integer.)

  49. In casting to xs:decimal or to a type derived from xs:decimal, if the value is not too large or too small but nevertheless cannot be represented accurately with the number of decimal digits available to the implementation, the implementation may round to the nearest representable value or may raise a dynamic error [err:FOCA0006]. The choice of rounding algorithm and the choice between rounding and error behavior and is ·implementation-defined·. (See Casting from xs:string and xs:untypedAtomic.)

  50. The tz timezone database, available at http://www.twinsun.com/tz/tz-link.htm. It is ·implementation-defined· which version of the database is used. (See Olson Timezone Database.)

  51. The Unicode Consortium, Reading, MA, Addison-Wesley, 2003. 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 6.0.0. (See The Unicode Standard.)

  52. Unicode Standard Annex #15, Unicode Normalization Forms. Available at: http://www.unicode.org/reports/tr15/. As with [The Unicode Standard], the version to be used is ·implementation-defined·. (See Unicode Normalization Forms.)

E Changes since previous Recommendation (Non-Normative)

E.1 Substantive changes (15 December 2009)

In the Working Draft of 15 December 2009, the following changes were made relative to the first edition of the Functions and Operators specification for XPath 2.0 and XQuery 1.0 published on 23 January 2007:

  1. Errata E1 through E47 were applied.

  2. A two-argument version of the fn:round function was introduced. (Bugzilla 6240)

  3. A single-argument version of the fn:string-join function was introduced.

  4. Specifications for the functions fn:format-date, fn:format-time, and fn:format-dateTime were transferred from the XSLT 2.0 specification.

  5. The specification of fn:format-number was transferred from the XSLT specification.

  6. A function fn:format-integer was introduced.

  7. The function fn:generate-id was introduced, transferred from the XSLT specification.

  8. A range of trigonometric functions was defined (in a new namespace).

  9. New functions fn:parse-xml and fn:serialize were defined. (The fn:parse function was subsequently renamed fn:parse-xml

  10. A new function fn:analyze-string was defined.

  11. The syntax of regular expressions was extended to allow non-capturing groups.

  12. A new flag was introduced for the $flags argument of functions that use regular expressions: the q flag causes all characters in a regular expression to be treated as ordinary characters rather than metacharacters.

  13. Supporting the new language feature of higher-order functions, a number of functions were defined that operate on function items as their arguments: fn:map (subsequently renamed fn:for-each), fn:filter, fn:map-pairs (subsequently renamed fn:for-each-pair, fn:fold-left, fn:fold-right. The function fn:partial-apply, however, which was introduced in the previous version of this Working Draft, has now been dropped in favor of custom syntax for partial application using "?" as a place-holder for missing arguments.

  14. The description of the fn:error function was rewritten to allow for the introduction of try/catch facilities into XQuery and XSLT.

  15. The section describing what it means for functions to be contextual and/or deterministic was rewritten. The term deterministic has replaced stable.

E.2 Substantive changes (18 June 2012)

In the Last Call Working Draft of 18 June 2012, the following substantive changes are made relative to the draft of 15 December 2009:

  1. The version number of the specification is changed from 1.1 to 3.0.

  2. New functions math:exp, math:exp10, math:log, math:log10, math:atan2, and math:pow are defined. The trigonometric and exponential functions are now specified by reference to [IEEE 754-2008].

  3. In the rules for fn:format-dateTime and related functions, the rules for formatting of timezones have been expanded and clarified; the $country argument is renamed $place, and its value may now be an Olson timezone name.

  4. The rules for the fn:normalize-unicode function are now defined directly by reference to the Unicode specifications rather than the W3C Working Draft on the Character Model for the World Wide Web (which never progressed beyond Working Draft status). The rules for the normalization form FULLY_NORMALIZED are now defined normatively in this specification.

  5. The syntax for the picture string used by fn:format-integer has been extended to allow grouping positions to be associated with optional digit positions.

  6. Two convenience functions fn:head and fn:tail are added, reflecting the increased role played by head-tail recursive functions when writing code to take advantage of higher-order functions.

  7. The function fn:partial-apply has been removed, as this functionality is now provided by custom syntax (partial function application, using "?" as a placeholder for missing arguments).

  8. New functions fn:function-name, fn:function-arity, and fn:function-lookup are available.

  9. A new function fn:parse-xml-fragment was introduced. (This change went unremarked in the change log up to and including the Candidate Recommendation of 8 January 2013.)

  10. Casting from a dynamic string to an xs:QName or a type derived from xs:NOTATION is now permitted (the restriction that the argument must be a string literal has been removed). (Bug 9183)

  11. Zero-argument forms have been introduced for the functions fn:data, fn:document-uri, and fn:node-name, fn:base-uri, fn:nilled, and fn:has-children, with the argument defaulting to the context item in each case. (Bug 9571)

  12. The new function fn:parse is renamed fn:parse-xml. (Bug 9751)

  13. The rules for handling of negative zero have been clarified. Where operations return negative zero, then in general implementations must respect this; the only exception is for casting from string to float or double, where the lexical form -0 may result in positive zero for compatibility with existing XML Schema 1.0 processors. (Bug 9907)

  14. The functions fn:unparsed-text and fn:unparsed-text-available have been transferred unchanged from XSLT 2.0. (Bug 9067), and fn:unparsed-text-lines has been transferred from the XSLT 2.1 draft.

  15. The function fn:uri-collection has been added. This was originally defined as an output of the work on streaming in XSLT 3.0; its purpose is to give applications greater control of the processing of individual documents within a large collection.

  16. The rules for the fn:resolve-uri function have been rewritten to refer to more up-to-date specifications, specifically the IRI and LEIRI specifications. Implementations are required to support the IRI syntax as a minimum, and are permitted to support the legacy extensions defined in LEIRI.

  17. Two new functions fn:environment-variable and fn:available-environment-variables have been defined.

  18. Casting from a string or xs:untypedAtomic value to a union or list type is now allowed.

  19. References to the Formal Semantics have been removed.

  20. Rules for the precision of the results of trigonometric and exponential functions have been removed, and replaced with a normative reference to the rules in the IEEE specifications.

  21. The functions fn:unparsed-text-lines, fn:has-children, fn:innermost and fn:outermost have been transferred from the XSLT 3.0 working draft.

  22. The function fn:path has been added.

  23. References to IEEE 754-1985 (to define the semantics of operations on 32-bit and 64-bit floating point) have been updated to refer to IEEE 754-2008.

  24. The error codes produced by fn:collection have been clarified, possibly involving incompatible changes.

  25. In regular expressions (without the "m" option) the meta-character "." now matches everything except x0A and x0D. Previously it was defined to match everything except x0A, which was an unnecessary and unintended incompatibility with regular expressions in XSD.

E.3 Substantive changes (Candidate Recommendation)

In this Candidate Recommendation, the following substantive changes are made relative to the Last Call Working Draft draft of 18 June 2012:

  1. Functions with dependencies on the static or dynamic context can now be bound to function items (for example, by the use of fn:function-lookup), and the rules for doing so have been clarified.

  2. The specification of fn:format-integer makes a more precise distinction between situations where the processor must report an error in the supplied picture, and situations where it must adopt a fallback representation.

  3. The conditions under which the static base URI used during static analysis can differ from the base URI used during evaluation are now more clearly and consistently described. The concept of dynamic base URI is dropped.

  4. The syntax for regular expressions is now described by reference to the XSD 1.1 specification as well as the XSD 1.0 specification. (XSD 1.1 gives a much clearer exposition of the syntax and semantics of regular expressions without introducing any intended changes to the functionality.)

  5. Some edge cases for capturing subgroups in regular expressions are described.

  6. The role of the schema for the data returned by fn:analyze-string is more clearly defined.

  7. In the result of fn:path, dependencies on the default namespace for functions have been removed, by ensuring that any function calls in the return path use fully-qualified names.

  8. In the specification of fn:deep-equal, the consequences of the existing rules for comparing validated against unvalidated trees are more carefully explained.

  9. The rules for the fn:unparsed-text function have been expressed at a higher level of abstraction, using the context in the same way as the fn:doc function, and making use of concepts such as the distinction in web architecture between a resource and its representation.

  10. A number of rules have been added, which were previously omitted, concerning casts and constructors where the target type is a union or list type.

E.4 Substantive changes (post Candidate Recommendation)

The following changes are made subsequent to the Candidate Recommendation of 8 January 2013:

  1. The functions fn:map and fn:map-pairs are renamed fn:for-each and fn:for-each-pair respectively. This change is made to remove the risk of potential confusion and syntactic conflicts if and when a map data type is added to the language, as proposed in the current XSLT 3.0 Working Draft. (Bug 21128).

  2. The arguments of the functions fn:for-each and fn:for-each-pair, fn:filter, fn:fold-left, and fn:fold-right are re-ordered. This change has been made in the interests of usability and consistency with other functions. (Bug 21797).

  3. The regular expression matching the format modifier in the picture string supplied to fn:format-integer has been corrected to match the accompanying prose. (Bug 19004).

  4. The function signature for the xs:QName constructor function has been corrected to show that the supplied value may be an empty sequence (the error arose because in XPath 2.0, this constructor was a special case, requiring that the supplied argument be an string literal). (Bug 20856)

  5. The function signature for the fn:adjust-dateTime-to-timezone function has been corrected to show that the returned value may be an empty sequence, making the signature consistent with the prose description and with the XPath 2.0/XQuery 1.0 version of the specification. (Bug 20850)

  6. The $calendar argument of functions in the fn:format-date family may now be an EQName for consistency, and the error conditions for the arguments to these functions are more clearly spelled out. (Bug 21284).

  7. A section has been added to describe the constructor function xs:error present in implementations that support XSD 1.1. The existence of such a function is a consequence of general rules included in the published Candidate Recommendation, but the function was not listed along with other constructor functions for built-in XSD types. (Bug 20634).

  8. A paragraph has been added explaining how to interpret the week-in-month (w) component for the fn:format-date family of functions in the case where the chosen calendar is the ISO calendar. (Bug 21370).

  9. It is now stated that it is an error in a regular expression to use a Unicode block name which is not defined in the version(s) of Unicode supported by the processor. This differs from the treatment of this condition in XSD 1.1. (Bug 20575).

  10. Error conditions are now properly categorized as type errors or dynamic errors, and in particular where the error condition XPDY0002 was previously categorized as a type error this has been corrected. (Bug 21315).

  11. It is now stated that failure to cast to a union type is always a dynamic error, not a type error. (Bug 21766)

E.5 Editorial changes

The following editorial changes have been made since the first edition of the Functions and Operators specification for XPath 2.0 and XQuery 1.0 published on 23 January 2007. These are not explicitly marked in the change-highlighted version of the specification:

  1. References to the Formal Semantics (which in nearly all cases were references to detailed rules for static type inferencing) have been removed, as the Formal Semantics is not being maintained. (Bug 9056)

  2. A quick reference section containing links to the functions has been added before the full table of contents. The end-of-document indexes have been dropped in this draft (any readers disappointed by this decision are invited to make representations to the editor, since they can easily be re-instated).

  3. The section on constructor functions has been moved so that it is now adjacent to the closely-related section on casting.

  4. The function fn:dateTime has been moved out of the section describing constructor functions, and is no longer described as "a special constructor function". It is now an ordinary function described in the appropriate section along with other functions on dates and times. This allows the term "constructor function" to be associated exclusively with single-argument functions whose name is the same as the type name of the value that they return, and avoids any suggestion that this function has special behavior. Similarly, the functions fn:true and fn:false are no longer described as constructor functions.

  5. Where a function is referred to by name, the reference is now always in the form (for example) fn:base-uri rather than fn:base-uri(). The latter form is used only to indicate a call on the function in which no arguments are supplied.

  6. The specification of each function now consists of a set of standard subsections: Summary, Operator Mapping, Signature, Properties, Rules, Error Conditions, Notes, and Examples.

  7. The "Summary" of the effect of each function is now just that: it never contains any information that cannot be found in the more detailed rules, and it does not attempt to list unusual or error conditions. Such rules have been moved into separate paragraphs. Sometimes the language used in the summary is relatively informal. Although the summary remains normative, it must be regarded as being subservient to the rules that follow.

  8. Functions are always called, never invoked.

  9. The specification no longer discusses functions, it now specifies or defines them.

  10. A seperate section for each function now lists the properties of the function: whether or not it is deterministic, context-dependent, or focus-dependent. These properties are linked to their definitions.

  11. Rules have been rewritten in a more consistent style: "If $arg is X, the function returns Y" (avoiding alternatives such as "Returns Y if $arg is X", and avoiding the passive "is returned"). In nearly all cases the language used for error conditions has been standardized to the form "An error is raised [code] if ...".

  12. The section heading for a section that defines a function is now always the name of the function. Some function definitions have been moved into subsections to achieve this.

  13. Statements within the rules of a function that follow inevitably from other rules have in many cases been downgraded to notes. An example is the statement that fn:remove($seq, N) returns an empty sequence if $seq is an empty sequence.

  14. The functions for durations and those for dates/times have been split into separate sections.

  15. The fn:boolean function has been moved from "General Functions and Operators on Sequences" to "Functions on Boolean Values".

  16. In the interests of automating the testing of examples, the convention has been adopted that the result of an example expression is wherever possible given in the form of a simple XPath expression. Specifically a numeric or string literal is used for numbers and strings; the expressions true() and false() for booleans; constructors such as xs:duration('PT0S') for other atomic types; expressions such as (1, 2, 3, 4) for sequences. The expression will always return a value of the correct type; so the xs:double value zero is shown as 0.0e0, not as 0, which is the way the value would be serialized on output. The value NaN is given as xs:double('NaN'). Previously results were sometimes given in this form, sometimes in the form of a serialization of the result value, and sometimes (particularly for dates, times, and durations) in the form of an informal description.

  17. In some cases where one function can be readily specified in terms of another, the opportunity has been taken to simplify the specification. For example, all the operator support functions of the form op:xx-greater-than are now specified by reference to the corresponding op:xx-less-than function with the arguments reversed. This reduces the risk of introducing errors and inconsistencies.

  18. In some cases, the rules for a function have been reordered. For example, the rule describing how an empty sequence is handled now generally comes before any rule that works only if the argument is not an empty sequence.

  19. Some non-normative examples and notes have been added.

  20. The non-normative example functions in Appendix D have been revised, and new functions are supplied to illustrate use cases for higher-order functions.

  21. The appendix describing error codes gives more information.

  22. The checklist of implementation-defined features is now automatically aligned with the text.

F Compatibility with Previous Versions (Non-Normative)

This section summarizes the extent to which this specification is compatible with previous versions.

It describes first the incompatibilities between XPath 1.0 and XPath 2.0 (or XQuery 1.0), then the incompatibilities between XPath 2.0 (or XQuery 1.0) and XPath/XQuery 3.0.

F.1 Compatibility between XPath 2.0 and XPath 1.0

Note: XPath 2.0 and XQuery 1.0 were aligned, so all references to XPath 2.0 in this section apply equally to XQuery 1.0.

This appendix summarizes the relationship between certain functions defined in [XML Path Language (XPath) Version 1.0] and the corresponding functions defined in this document. The first column of the table provides the name of the function. The second column describes the differences in the semantics of the corresponding functions. The functions appear in the order they appear in [XML Path Language (XPath) Version 1.0].

A more detailed version of this information can be found in [XQuery 1.0 and XPath 2.0 Functions and Operators].

This appendix does not include incompatibilities that arise solely from the change in function calling rules that occurred between XPath 1.0 and XPath 2.0, that is, incompatibilities that can be avoided by ensuring that XPath 1.0 compatibility mode is enabled. For example, in XPath 1.0 the fn:name function when applied to a sequence of three nodes would return the name of the first (in document order); in XPath 2.0 and XPath 3.0 such a call is a type error, unless XPath 1.0 compatiblity mode is enabled. Similarly, functions such as fn:substring, fn:contains, and fn:translate that expect string arguments will raise a type error in XPath 2.0 if called with a boolean or numeric argument, unless XPath 1.0 compatibility mode is enabled. A more complete list of these incompatibilities can be found in [XQuery 1.0 and XPath 2.0 Functions and Operators].

In addition, this appendix does not include incompatibilities that arise when the default collation is set to something other than Unicode codepoint collation.

This appendix does not include incompatibilities that might arise due to XPath 2.0 defining the specification with greater clarity or precision. For example, an implementation of fn:sum in XPath 1.0 that returned NaN when given an empty node-set as the argument would not have contradicted any explicit statement in the specification, while XPath 2.0 is explicit that the expected result in this case is zero.

Function Notes
fn:last Because the result is an integer rather than a double, the precision of subsequent computations may be different.
fn:position Because the result is an integer rather than a double, the precision of subsequent computations may be different.
fn:count Because the result is an integer rather than a double, the precision of subsequent computations may be different.
fn:id XPath 2.0 raises a type error with boolean and numeric arguments. The rules for recognizing a node as an id value changed. In XPath 1.0 the whole string is treated as a unit, while in XPath 2.0 each string is treated as a list.
fn:name The rules for determining the prefix are more precisely defined in [XML Path Language (XPath) 2.0].
fn:string Representations of numeric values are XPath 1.0 compatible except for the special values positive and negative infinity, and for values outside the range 1.0e-6 to 1.0e+6.
fn:string-length Because the result is an integer rather than a double, the precision of subsequent computations may be different.
fn:sum XPath 2.0 raises an error if the sequence contains values that cannot be added together, such as strings. XPath 1.0 returns NaN.
fn:floor In XPath 2.0, if the argument is (), the result is (). In XPath 1.0, the result is NaN.
fn:ceiling In XPath 2.0, if the argument is (), the result is (). In XPath 1.0, the result is NaN.
fn:round In XPath 2.0, if the argument is (), the result is (). In XPath 1.0, the result is NaN.

F.2 Compatibility between XPath 3.0 and XPath 2.0

Note: XPath 2.0 and XQuery 1.0 were aligned, and XPath 3.0 and XQuery 3.0 are aligned. So all references to XPath 2.0 in this section apply equally to XQuery 1.0, and all references to XPath 3.0 apply equally to XQuery 3.0.

There are no incompatibilities between this version of the specification and the version that applied to XPath 2.0 and XQuery 1.0, other than clarifications where this version of the specification might describe the intended behavior more precisely. Such clarifications have been made mainly to the description of functions that have significant interactions with the processing environment: examples are fn:resolve-uri, fn:collection, and fn:doc.

Some functions appearing in this specification previously appeared as part of the specification of XSLT 2.0. Incompatibilities applying to these functions are as follows:

  1. The rules for timezone formatting using the [Z] component in the second argument of fn:format-date, fn:format-dateTime, and fn:format-time were previously very unclear, and have been completely revised. The new rules are likely to be different from the interpretation adopted by particular XSLT 2.0 processors.

  2. Error codes have been changed to fit with the coding scheme used in this specification. (Note however, that in XSLT 2.0 there was no interoperable way of testing error codes, and the specification explicitly made the error codes non-normative.)

  3. In regular expressions (without the "m" option) the meta-character "." now matches everything except x0A and x0D. Previously it was defined to match everything except x0A, which was an unnecessary and unintended incompatibility with regular expressions in XSD.