W3C

XQuery 1.0 and XPath 2.0 Functions and Operators

W3C Working Draft 12 November 2003

This version:
http://www.w3.org/TR/2003/WD-xpath-functions-20031112/
Latest version:
http://www.w3.org/TR/xpath-functions/
Previous version:
http://www.w3.org/TR/2003/WD-xpath-functions-20030502/
Editors:
Ashok Malhotra (XML Query and XSL WGs), Microsoft <ashokma@microsoft.com>
Jim Melton (XML Query WG), Oracle Corp <jim.melton@acm.org>
Norman Walsh (XSL WG), Sun Microsystems <Norman.Walsh@Sun.COM>

Abstract

This document defines basic operators and functions on the datatypes defined in [XML Schema Part 2: Datatypes] and the datatypes defined in this document for use in [XPath 2.0], [XQuery 1.0: An XML Query Language] and [XSLT 2.0] and other related XML standards. It also discusses operators and functions on nodes and node sequences as defined in the [XQuery 1.0 and XPath 2.0 Data Model] for use in [XPath 2.0], [XQuery 1.0: An XML Query Language] and [XSLT 2.0] and other related XML standards.

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 a Last Call Working Draft. Comments on this document are due by 15 February, 2004. Comments should be sent to the W3C mailing list, public-qt-comments@w3.org (archived at http://lists.w3.org/Archives/Public/public-qt-comments/).

This is a Public Working Draft for review by W3C Members and other interested parties. Publication as a Working Draft 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 describes constructor functions, operators and functions that are used in [XPath 2.0], [XQuery 1.0: An XML Query Language] and [XSLT 2.0] and possibly other W3C specifications.

A number of changes have been made to this document as a result of "Last Call" comments on the previous version of the document. Feedback is solicited on these changes. The more significant of these changes are listed below.

A proposal related to the two totally ordered subtypes of xs:duration, xdt:yearMonthDuration and xs:dayTimeDuration has been received. See http://lists.w3.org/Archives/Public/public-qt-comments/2003Sep/0114.html.

This proposal argues that since the value space for these datatypes is integer months and decimal seconds respectively, these datatypes should be removed and functions that work with these datatypes should be removed and replaced by functions on numeric types. An alternative is to retain the datatypes but remove the functions and provide casting facilities for these datatypes to and from numbers.

This is a far-reaching proposal and the Working Groups felt that its consideration should be postponed until after this document was published. This note is to alert readers that such a change may appear in future versions of this document.

We have also been made aware of ongoing work to provide URI-based names for collations and collation algorithms and to create an IANA registry for such names. See member-only communication: http://lists.w3.org/Archives/Member/w3c-query-operators/2003Aug/0017.html. References to this work may also appear in future versions of this document.

In addition, a number of editorial corrections and improvements have been made as the result of public and member-only comments. The editors wish to thank the people who have sent in comments for their close reading of the document.

XQuery 1.0 and XPath 2.0 Functions and Operators has been defined through the efforts of a joint task force of the XML Query Working Group and the XSL Working Group (both part of the XML Activity). It is designed to be read in conjunction with the following documents: [XQuery 1.0 and XPath 2.0 Data Model], [XPath 2.0], [XQuery 1.0: An XML Query Language] and [XSLT 2.0].

This is a Last Call Working Draft which consolidates changes and editorial improvements undertaken in response to feedback received during the previous Last Call publication which began on 2 May 2003. A list of the first Last Call issues addressed by the Working Groups is also available at http://www.w3.org/XML/2003/05/xpath-functions-issues.

Comments on this document are due on 15 February 2004. Comments should be sent to the W3C mailing list public-qt-comments@w3.org (archived at http://lists.w3.org/Archives/Public/public-qt-comments/) with "[F&O]" as the beginning of the subject field.

Patent disclosures relevant to this specification may be found on the XML Query Working Group's patent disclosure page and the XSL Working Group's patent disclosure page.

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR/.

Table of Contents

1 Introduction
    1.1 Function Overloading
    1.2 Function Signatures and Descriptions
    1.3 Namespace Terminology
    1.4 Type Hierarchy
    1.5 xdt:anyAtomicType and xdt:untypedAtomic
        1.5.1 xdt:anyAtomicType
        1.5.2 xdt:untypedAtomic
        1.5.3 xdt:untypedAny
    1.6 xs:dateTime, xs:date and xs:time values
        1.6.1 Examples
    1.7 Namespaces and Prefixes
    1.8 Terminology
2 Accessors
    2.1 fn:node-name
    2.2 fn:string
    2.3 fn:data
    2.4 fn:base-uri
    2.5 fn:document-uri
3 The Error Function
    3.1 Examples
4 The Trace Function
    4.1 Examples
5 Constructor Functions
    5.1 Constructor Functions for XML Schema Built-in Types
    5.2 Constructor Functions for User-Defined Types
6 Functions and Operators on Numerics
    6.1 Numeric Types
    6.2 Operators on Numeric Values
        6.2.1 op:numeric-add
        6.2.2 op:numeric-subtract
        6.2.3 op:numeric-multiply
        6.2.4 op:numeric-divide
        6.2.5 op:numeric-integer-divide
        6.2.6 op:numeric-mod
        6.2.7 op:numeric-unary-plus
        6.2.8 op:numeric-unary-minus
    6.3 Comparison of Numeric Values
        6.3.1 op:numeric-equal
        6.3.2 op:numeric-less-than
        6.3.3 op:numeric-greater-than
    6.4 Functions on Numeric Values
        6.4.1 fn:abs
        6.4.2 fn:ceiling
        6.4.3 fn:floor
        6.4.4 fn:round
        6.4.5 fn:round-half-to-even
7 Functions on Strings
    7.1 String Types
    7.2 Functions to Assemble and Disassemble Strings
        7.2.1 fn:codepoints-to-string
        7.2.2 fn:string-to-codepoints
    7.3 Equality and Comparison of Strings
        7.3.1 Collations
        7.3.2 fn:compare
    7.4 Functions on String Values
        7.4.1 fn:concat
        7.4.2 fn:string-join
        7.4.3 fn:substring
        7.4.4 fn:string-length
        7.4.5 fn:normalize-space
        7.4.6 fn:normalize-unicode
        7.4.7 fn:upper-case
        7.4.8 fn:lower-case
        7.4.9 fn:translate
        7.4.10 fn:escape-uri
    7.5 Functions Based on Substring Matching
        7.5.1 fn:contains
        7.5.2 fn:starts-with
        7.5.3 fn:ends-with
        7.5.4 fn:substring-before
        7.5.5 fn:substring-after
    7.6 String Functions that Use Pattern Matching
        7.6.1 Regular Expression Syntax
        7.6.2 fn:matches
        7.6.3 fn:replace
        7.6.4 fn:tokenize
8 Functions and Operators on Boolean Values
    8.1 Additional Boolean Constructor Functions
        8.1.1 fn:true
        8.1.2 fn:false
    8.2 Operators on Boolean Values
        8.2.1 op:boolean-equal
        8.2.2 op:boolean-less-than
        8.2.3 op:boolean-greater-than
    8.3 Functions on Boolean Values
        8.3.1 fn:not
9 Functions and Operators on Durations, Dates and Times
    9.1 Duration, Date and Time Types
        9.1.1 Limits and Precision
    9.2 Two Totally Ordered Subtypes of Duration
        9.2.1 xdt:yearMonthDuration
        9.2.2 xdt:dayTimeDuration
    9.3 Comparisons of Duration, Date and Time Values
        9.3.1 op:yearMonthDuration-equal
        9.3.2 op:yearMonthDuration-less-than
        9.3.3 op:yearMonthDuration-greater-than
        9.3.4 op:dayTimeDuration-equal
        9.3.5 op:dayTimeDuration-less-than
        9.3.6 op:dayTimeDuration-greater-than
        9.3.7 op:dateTime-equal
        9.3.8 op:dateTime-less-than
        9.3.9 op:dateTime-greater-than
        9.3.10 op:date-equal
        9.3.11 op:date-less-than
        9.3.12 op:date-greater-than
        9.3.13 op:time-equal
        9.3.14 op:time-less-than
        9.3.15 op:time-greater-than
        9.3.16 op:gYearMonth-equal
        9.3.17 op:gYear-equal
        9.3.18 op:gMonthDay-equal
        9.3.19 op:gMonth-equal
        9.3.20 op:gDay-equal
    9.4 Component Extraction Functions on Duration, Date and Time Values
        9.4.1 fn:get-years-from-yearMonthDuration
        9.4.2 fn:get-months-from-yearMonthDuration
        9.4.3 fn:get-days-from-dayTimeDuration
        9.4.4 fn:get-hours-from-dayTimeDuration
        9.4.5 fn:get-minutes-from-dayTimeDuration
        9.4.6 fn:get-seconds-from-dayTimeDuration
        9.4.7 fn:get-year-from-dateTime
        9.4.8 fn:get-month-from-dateTime
        9.4.9 fn:get-day-from-dateTime
        9.4.10 fn:get-hours-from-dateTime
        9.4.11 fn:get-minutes-from-dateTime
        9.4.12 fn:get-seconds-from-dateTime
        9.4.13 fn:get-timezone-from-dateTime
        9.4.14 fn:get-year-from-date
        9.4.15 fn:get-month-from-date
        9.4.16 fn:get-day-from-date
        9.4.17 fn:get-timezone-from-date
        9.4.18 fn:get-hours-from-time
        9.4.19 fn:get-minutes-from-time
        9.4.20 fn:get-seconds-from-time
        9.4.21 fn:get-timezone-from-time
    9.5 Arithmetic Functions on xdt:yearMonthDuration and xdt:dayTimeDuration
        9.5.1 op:add-yearMonthDurations
        9.5.2 op:subtract-yearMonthDurations
        9.5.3 op:multiply-yearMonthDuration
        9.5.4 op:divide-yearMonthDuration
        9.5.5 op:add-dayTimeDurations
        9.5.6 op:subtract-dayTimeDurations
        9.5.7 op:multiply-dayTimeDuration
        9.5.8 op:divide-dayTimeDuration
    9.6 Timezone Adjustment on dateTime, date 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 Adding and Subtracting Durations From dateTime, date and time
        9.7.1 fn:subtract-dateTimes-yielding-yearMonthDuration
        9.7.2 fn:subtract-dateTimes-yielding-dayTimeDuration
        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
10 Functions Related to QNames
    10.1 Additional Constructor Functions for QNames
        10.1.1 fn:resolve-QName
        10.1.2 fn:expanded-QName
    10.2 Operators and Functions Related to QNames
        10.2.1 op:QName-equal
        10.2.2 fn:get-local-name-from-QName
        10.2.3 fn:get-namespace-uri-from-QName
        10.2.4 fn:get-namespace-uri-for-prefix
        10.2.5 fn:get-in-scope-prefixes
11 Functions and Operators for anyURI
    11.1 fn:resolve-uri
    11.2 op:anyURI-equal
        11.2.1 Examples
12 Functions and Operators on base64Binary and hexBinary
    12.1 Comparisons of base64Binary and hexBinary Values
        12.1.1 op:hexBinary-equal
        12.1.2 op:base64Binary-equal
13 Functions and Operators on NOTATION
    13.1 Operators on NOTATION
        13.1.1 op:NOTATION-equal
14 Functions and Operators on Nodes
    14.1 Functions and Operators on Nodes
        14.1.1 fn:name
        14.1.2 fn:local-name
        14.1.3 fn:namespace-uri
        14.1.4 fn:number
        14.1.5 fn:lang
        14.1.6 op:is-same-node
        14.1.7 op:node-before
        14.1.8 op:node-after
        14.1.9 fn:root
15 Functions and Operators on Sequences
    15.1 Functions and Operators on Sequences
        15.1.1 fn:zero-or-one
        15.1.2 fn:one-or-more
        15.1.3 fn:exactly-one
        15.1.4 fn:boolean
        15.1.5 op:concatenate
        15.1.6 fn:index-of
        15.1.7 fn:empty
        15.1.8 fn:exists
        15.1.9 fn:distinct-values
        15.1.10 fn:insert-before
        15.1.11 fn:remove
        15.1.12 fn:reverse
        15.1.13 fn:subsequence
        15.1.14 fn:unordered
    15.2 Equals, Union, Intersection and Except
        15.2.1 fn:deep-equal
        15.2.2 op:union
        15.2.3 op:intersect
        15.2.4 op:except
    15.3 Aggregate Functions
        15.3.1 fn:count
        15.3.2 fn:avg
        15.3.3 fn:max
        15.3.4 fn:min
        15.3.5 fn:sum
    15.4 Functions and Operators that Generate Sequences
        15.4.1 op:to
        15.4.2 fn:id
        15.4.3 fn:idref
        15.4.4 fn:doc
        15.4.5 fn:collection
16 Context Functions
    16.1 fn:position
    16.2 fn:last
    16.3 fn:current-dateTime
        16.3.1 Examples
    16.4 fn:current-date
        16.4.1 Examples
    16.5 fn:current-time
        16.5.1 Examples
    16.6 fn:default-collation
    16.7 fn:implicit-timezone
17 Casting
    17.1 Casting from primitive types to primitive types
    17.2 Casting to derived types
    17.3 Casting from derived types to parent types
    17.4 Casting within a branch of the type hierarchy
    17.5 Casting across the type hierarchy
    17.6 Casting from xs:string and xdt:untypedAtomic
    17.7 Casting to xs:string and xdt:untypedAtomic
    17.8 Casting to numeric types
        17.8.1 Casting to xs:float
        17.8.2 Casting to xs:double
        17.8.3 Casting to xs:decimal
        17.8.4 Casting to xs:integer
    17.9 Casting to duration types
    17.10 Casting to date and time types
    17.11 Casting to xs:boolean
    17.12 Casting to xs:base64Binary and xs:hexBinary
    17.13 Casting to xs:anyURI
    17.14 Casting to xs:QName
        17.14.1 Usage Note
    17.15 Casting to xs:NOTATION

Appendices

A References
    A.1 Normative
    A.2 Non-normative
B Compatibility with XPath 1.0 (Non-Normative)
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, intersect and except 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 Working With xs:duration Values
D Error Summary (Non-Normative)
E Functions and Operators Issues List (Non-Normative)
F ChangeLog since Last Call Version on 2003-05-02 (Non-Normative)
G Function and Operator Quick Reference (Non-Normative)
    G.1 Functions and Operators by Section
    G.2 Functions and Operators Alphabetically


1 Introduction

The purpose of this document is to catalog the functions and operators required for XPath 2.0, XML Query 1.0 and XSLT 2.0. The exact syntax used to invoke these functions and operators is specified in [XPath 2.0], [XQuery 1.0: An XML Query Language] and [XSLT 2.0].

This document defines a few new datatypes, constructor functions and functions that take typed values as arguments. Some of the functions define the semantics of operators discussed in [XQuery 1.0: An XML Query Language].

[XML Schema Part 2: Datatypes] defines a number of primitive and derived datatypes, collectively known as built-in datatypes. This document defines operations on these datatypes as well as the two datatypes defined in 1.5 xdt:anyAtomicType and xdt:untypedAtomic and the two totally ordered subtypes of xs:duration defined in 9.2 Two Totally Ordered Subtypes of Duration, for use in [XPath 2.0], [XQuery 1.0: An XML Query Language] and [XSLT 2.0] and related XML standards. This document also discusses operators and functions on nodes and node sequences as defined in the [XQuery 1.0 and XPath 2.0 Data Model] for use in [XPath 2.0], [XQuery 1.0: An XML Query Language] and [XSLT 2.0] and other related XML standards.

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 1.0: An XML Query Language], 'XT' [XSLT 2.0], 'XP' [XPath 2.0], 'DM' [XQuery 1.0 and XPath 2.0 Data Model] and 'FS' [XQuery 1.0 and XPath 2.0 Formal Semantics].

1.1 Function Overloading

In general, the specifications named above do not support function overloading. Consequently, there are no overloaded functions in this document except for legacy [XPath 1.0] functions such as fn:string(), which accepts a single argument of a variety of types, and concat() which accepts a variable number of xs:string arguments. In addition, the functions defined in 6 Functions and Operators on Numerics that accept numeric arguments accept arguments of type xs:integer, xs:decimal, xs:float or xs:double. See 1.2 Function Signatures and Descriptions. Operators such as "+" may be overloaded.

1.2 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 set of parentheses: "()"; otherwise, the name is followed by a parenthesized list of parameter declarations, each declaration specifying the static type of the parameter, in italics, and a non-normative name used to describe the function's semantics. 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. In most cases, the dynamic type returned by the function is the same as its static type. The types "node" and "item" are indicated in function signatures as "node()" and "item()" repectively.

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 functions 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 ...
Similarly, for return types.

For most functions there is a 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.

In some cases, the dynamic type returned by a function depends on the type(s) of its argument(s). These special functions are indicated by using bold italics for the return type. The semantic rules specifying the type of the value returned are documented in the function definition. The rules are described more formally in Section 6.2 Standard functions with specific typing rulesFS.

The function name is a QName as defined in [XML Schema Part 2: Datatypes] and must adhere to its syntactic conventions. Following [XPath 1.0], function names are composed of English words separated by hyphens,"-". If a function name contains a [XML Schema Part 2: Datatypes] datatype name, it may have intercapitalized spelling and is used in the function name as such. For example, fn:get-timezone-from-dateTime.

As is customary, the parameter type name indicates that the function accepts arguments of that type, or types derived from it, in that position. This is called subtype substitution. Details of the semantics of passing arguments to functions are discussed in Section B.1 Type PromotionXQ .

Some functions accept the empty sequence as an argument and some may return 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(.). In the second signature, the argument must be present but may be the empty sequence ().

Some functions accept a sequence as an argument. This is indicated by following the name of 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.3 Namespace Terminology

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

[Definition] Expanded-QName

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

1.4 Type Hierarchy

The diagram below shows the types for which functions are defined in this document. These include the built-in types defined by [XML Schema Part 2: Datatypes] (shown on the right) as well as types defined in [XPath 2.0] (shown on the left). Solid lines connect a base datatype above to a derived datatype except in the case of xsIDREFS, xs:IDREFS, xs:NMTOKENS, xs:ENTITIES and user-defined list and union types. These types are lists or unions of their parent types(s) rather than true subtypes. Dashed lines connect a union type above with its component types below.

Type hierarchy graphic

The information in the above diagram is reproduced below in tabular form. For ease of presentation the information is divided into three tables. The first table shows the top three layers of the hierarchy starting at xs:anyType. The second table shows the types derived from xdt:anyAtomicType. The third table shows the types defined in [XPath 2.0]

Each type whose name is indented is derived from the type whose name appears nearest above with one less level of indent.

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

The table below shows the datatypes derived from xdt:anyAtomicType. This includes all the [XML Schema Part 2: Datatypes] built-in datatypes as well as the two totally ordered subtypes of duration defined 9.2 Two Totally Ordered Subtypes of Duration.

Each type whose name is indented is derived from the type whose name appears nearest above with one less level of indent.

xdt:untypedAtomic
xs:dateTime
xs:date
xs:time
xs:duration
xdt:yearMonthDuration
xdt: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: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

The table below shows type hierarchy for the types introduced in [XPath 2.0]. For these types, each type whose name is indented is a component of the union type whose name appears nearest above with one less level of indent.

item
xdt:anyAtomicType
node
attribute
user-defined attribute types
comment
document
user-defined document types
element
user-defined element types
processing-instruction
text

1.5 xdt:anyAtomicType and xdt:untypedAtomic

1.5.1 xdt:anyAtomicType

The abstract datatype xdt:anyAtomicType is a child of xs:anySimpleType and is the base type for all the primitive atomic types described in [XML Schema Part 2: Datatypes]. This datatype cannot be used in [XML Schema Part 1: Structures] type declarations, nor can it be used as a base for user-defined atomic types. It can be used, as discussed in the Section 3.12 Expressions on SequenceTypesXQ, to define a required type (for example in a function signature) to indicate that any of the primitive atomic types or xdt:untypedAtomic is acceptable. This datatype resides in the namespace http://www.w3.org/2003/11/xpath-datatypes.

1.5.2 xdt:untypedAtomic

The abstract datatype xdt:untypedAtomic is a child of xdt:anyAtomicType and serves as a special type annotation to indicate atomic values that have not been validated by a XML Schema or a DTD or have received an instance type annotation of xs:anySimpleType in the PSVI. This datatype cannot be used in [XML Schema Part 1: Structures] type declarations, nor can it be used as a base for user-defined atomic types. It can be used, as discussed in the Section 3.12 Expressions on SequenceTypesXQ, to define a required type (for example in a function signature) to indicate that only an untyped atomic value is acceptable. This datatype resides in the namespace http://www.w3.org/2003/11/xpath-datatypes.

1.5.3 xdt:untypedAny

The abstract datatype xdt:untypedAny is a child of xs:anyType and serves as a special type annotation to indicate types that have not been validated by a XML Schema or a DTD. This type cannot be used in [XML Schema Part 1: Structures] type declarations, nor can it be used as a base for user-defined types. It can be used, as discussed in the Section 3.12 Expressions on SequenceTypesXQ, to define a required type (for example in a function signature) to indicate that only an untyped value is acceptable. This datatype resides in the namespace http://www.w3.org/2003/11/xpath-datatypes.

1.6 xs:dateTime, xs:date and xs:time values

xs:dateTime, xs:date and xs:time values are represented in the Section 3.3.1 Mapping PSVI Additions to TypesDM as tuples: a xs:dateTime, xs:date or xs:time value without a timezone and a timezone represented as a xdt:dayTimeDuration value. The value space of these types consists of the normalized value for these datatypes. This means that the xs:dateTime, xs:date or xs:time is first normalized to UTC or timezone Z. To create a value from a lexical representation of xs:dateTime, xs:date and xs:time lexical representations that have a timezone are converted to timezone Z as defined by [XML Schema Part 2: Datatypes] and the timezone in the lexical representation is converted to a xdt:dayTimeDuration value. Lexical representations that do not contain a timezone are assumed to be in timezone Z and the timezone part of the value set to the empty sequence "()".

We also define the localized value for a xs:dateTime, xs:date and xs:time as the xs:dateTime, xs:date and xs:time value in its original timezone or no timezone, as the case may be, followed by the timezone represented as a xdt:dayTimeDuration. Lexical representations that do not contain a timezone are given a timezone value set to the empty sequence "()".

1.6.1 Examples

  • A dateTime with lexical representation 1999-05-31T05:00:00 has a value represented by the tuple (1999-05-31T05:00:00Z, ())

  • A dateTime with lexical representation 1999-05-31T13:20:00-05:00 has a value represented by the tuple (1999-05-31T18:20:00Z, -PT5H)

1.7 Namespaces and Prefixes

The functions and operators discussed in this document are contained in one of three namespaces (see [Namespaces in XML]) and referenced using a xs:QName. Constructor functions for the built-in datatypes defined in [XML Schema Part 2: Datatypes] discussed in 5 Constructor Functions are in the XML Schema namespace, http://www.w3.org/2001/XMLSchema, and named in this document using the xs: prefix. The namespace prefix used in this document is fn: for the functions available to users and op: for the operator functions. The purpose of the functions indicated by the op: prefix is to define the semantics of operators in the host languages. In [XQuery 1.0: An XML Query Language] and [XPath 2.0] they are not directly accessible by users.

The datatypes described in this document in 1.5 xdt:anyAtomicType and xdt:untypedAtomic and 9.2 Two Totally Ordered Subtypes of Duration are contained in a separate namespace and are named using the prefix xdt:.

The namespace prefix for these functions and datatypes can vary, as long as the prefix is bound to the correct URI.

The URIs of the namespaces are:

  • http://www.w3.org/2001/XMLSchema for constructors

  • http://www.w3.org/2003/11/xpath-functions for functions.

  • http://www.w3.org/2003/11/xpath-datatypes for the datatypes.

The functions defined with an fn: prefix are callable by the user. Functions defined with the op: prefix are described here to underpin the definitions of the operators in [XPath 2.0], [XQuery 1.0: An XML Query Language] and [XSLT 2.0]. These functions are not available directly to users, and there is no requirement that implementations should actually provide these functions. For this reason, no namespace is associated with the op: prefix. For example, multiplication is generally associated with the * operator, but it is described as a function in this document:

op:multiply($arg1 as numeric, $arg2 as numeric) as numeric

1.8 Terminology

The terminology used to describe the functions and operators on [XML Schema Part 2: Datatypes] is defined in the body of this specification. The terms defined in the following list are used in building those definitions:

[Definition] for compatibility

A feature of this specification included to ensure that implementations that use this feature remain compatible with [XPath 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.

[Definition] stable

Most of the functions in the core library have the property that calling the same function twice with the same arguments returns the same result: these functions are said to be stable. This category includes a number of functions such as fn:doc(), fn:collection(), fn:current-dateTime(), fn:current-date and fn:current-time() whose result depends on the external environment. Where the function returns nodes, stability means that the returned nodes are identical, not merely equal. The scope over which the results are stable depends on the processing context. In XSLT, it applies to any two calls on the function executed during the same transformation. In XQuery, it applies to any two calls executed during the evaluation of a top-level expression i.e. an expression not contained in any other expression. In other contexts, the scope is specified by the host environment that invokes the function library.

Some other functions, for example fn:position() and fn:last(), depend on the dynamic context and may, therefore, produce different results each time they are called. These functions are said to be contextual.

2 Accessors

Accessors and their semantics are described in [XQuery 1.0 and XPath 2.0 Data Model]. 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: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:string
fn:document-uri document-uri an optional node zero or one xs:string

2.1 fn:node-name

fn:node-name($arg as node()?) as xs:QName?

Summary: Returns an expanded-QName for node kinds that can have names. For other kinds of nodes it returns the empty sequence. If $arg is the empty sequence, the empty sequence is returned.

2.2 fn:string

fn:string() as xs:string
fn:string($arg as item()?) as xs:string

Summary: Returns the value of $arg represented as a xs:string. If no argument is supplied, this function returns the string value of the context item (.).

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

If $arg is a node, the function returns the string-value of the node, as obtained using the dm:string-value accessor defined in the Section 5.5 string-value AccessorDM.

If $arg is an atomic value, then the function returns the same string as is returned by the expression "$arg cast as xs:string" (see 17 Casting).

2.3 fn:data

fn:data($arg as item()*) as xdt:anyAtomicType*

Summary: fn:data takes a sequence of items and returns a sequence of atomic values.

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

  • If the item is a node, fn:data() returns the typed value of the node as defined by the accessor function dm:typed-value in Section 5.6 typed-value AccessorDM.

2.4 fn:base-uri

fn:base-uri($arg as node()?) as xs:string?

Summary: Returns the value of the base-uri property for $arg as defined by the accessor function dm:base-uri for that kind of node in Section 5.1 base-uri AccessorDM.

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

Document, element and processing-instruction nodes have a base-uri property which may be empty. The base-uri of all other node types is the empty sequence. If the base-uri property for $arg is non-empty, its value is returned. If the base-uri property for $arg is empty, the base-uri of that node's parent is returned. If the node has no parent, the empty sequence is returned.

fn:base-uri() as xs:string

Summary: This version of the function returns the value of the base-uri property from the static context using the preceding rules. The static context is discussed in Section 2.1.1 Static ContextXQ .

2.5 fn:document-uri

fn:document-uri($arg as node()?) as xs:string?

Summary: Returns the value of the document-uri property for $arg as defined by the accessor function dm:document-uri in Section 5.1 base-uri AccessorDM.

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

Returns the empty sequence if the node is not a document node or if its document-uri property is a relative URI. Otherwise, returns an absolute URI expressed as an xs:string.

If the document-uri property of $arg is not the empty sequence, then the following expression always holds:

fn:doc(fn:document-uri($arg)) is $arg

3 The Error Function

In this document, as well as in [XQuery 1.0: An XML Query Language], [XPath 2.0], and [XQuery 1.0 and XPath 2.0 Formal Semantics], the phrase "an error is raised" is used to describe the behavior of conforming processors in certain situations. When such situations arise in a running system, a conforming implementation of this specification must invoke the fn:error function defined in this section.

The phrase is normally accompanied by specification of a specific error, in which case the phrase "an error is raised [name of error]" is used. The "name of error" specifies a phrase that is mnemonic for the actual error, but the error code to which it refers is an xs:QName. Each error defined in this document is identified by an xs:QName that is in the namespace asssociated with the xdt: prefix. It is the xs:QName that is actually passed as an argument to the fn:error function invocation. Invocation of this function causes the evaluation phase of the outermost XQuery or transformation to be terminated. For a more detailed treatment of error handing, see Section 2.5.2 Handling Dynamic ErrorsXQ and Section 6.2.5 The fn:error functionFS.

The fn:error function is a general function that may be invoked as above but may also be invoked from XQuery and XPath 2.0 applications with, for example, an xs:string argument.

fn:error() as none
fn:error($arg as item()?) as none

One version of the fn:error function takes no argments; a second version of the function accepts an optional item() as argument. The fn:error function never returns a value.

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

3.1 Examples

  • fn:error()

  • fn:error(xs:QName("xdt:FOAR0003"))

  • fn:error("Catch Fire and Burn!")

4 The Trace Function

This function is intended to be used in debugging queries by providing a trace of their execution.

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

The input $value is returned, unchanged, as the result of the function. In addition, the inputs $value and $label are directed to a trace data set. The location and format of the trace data set are ·implementation dependent·. The ordering of output from invocations of the fn:trace() function is ·implementation dependent·.

4.1 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 defined order.

5 Constructor Functions

5.1 Constructor Functions for XML Schema Built-in Types

Every built-in atomic type that is defined in [XML Schema Part 2: Datatypes], except xs:NOTATION has an associated constructor function; as do xdt:untypedAtomic, defined in 1.5 xdt:anyAtomicType and xdt:untypedAtomic and the two derived types xdt:yearMonthDuration and xdt:dayTimeDuration defined in 9.2 Two Totally Ordered Subtypes of Duration. The form of that function for a type pref:TYPE is:

pref:TYPE($arg as xdt:anyAtomicType) as pref:TYPE

For example, the signature of the constructor function corresponding to the xs:unsignedInt type defined in [XML Schema Part 2: Datatypes] is:

xs:unsignedInt($arg as xdt:anyAtomicType) as xs:unsignedInt

Invoking the constructor function xs:unsignedInt(12) returns the xs:unsignedInt value 12. Another invocation 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 invoked with a node that had a value equal to the xs:unsignedInt 12. The standard features described in Section 2.3.2 AtomizationXQ would 'atomize' the node to extract its value and then call the constructor with that value. If the value passed to a constructor is illegal for the datatype to be constructed, an error is raised [invalid value for constructor].

If the argument to a constructor function is an xs:string, 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 type, as specified in [XML Schema Part 2: Datatypes]. The semantics of constructor functions when invoked with a xs:string are identical to XML Schema validation. In the case of xs:dateTime, xs:date and xs:time, the value returned differs from [XML Schema Part 2: Datatypes] and is defined in 1.6 xs:dateTime, xs:date and xs:time values.

The semantics of the constructor function "xs:TYPE(arg)" are identical to the semantics of "arg cast as xs:TYPE". See 17 Casting. In some cases, the semantics of casting are explained using constructor functions; but there is no circularity. The constructors used invariably take xs:string arguments and, in this case, the semantics are the semantics of XML Schema validation as discussed above.

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.

The following constructor functions for the built-in types are supported:

  • xs:string($arg as xdt:anyAtomicType) as xs:string
  • xs:boolean($arg as xdt:anyAtomicType) as xs:boolean
  • xs:decimal($arg as xdt:anyAtomicType) as xs:decimal
  • xs:float($arg as xdt:anyAtomicType) as xs:float

    Implementations ·may· return negative zero for xs:float("-0.0E0").

  • xs:double($arg as xdt:anyAtomicType) as xs:double

    Implementations ·may· return negative zero for xs:double("-0.0E0").

  • xs:duration($arg  as xdt:anyAtomicType) as xs:duration
  • xs:dateTime($arg  as xdt:anyAtomicType) as (xs:dateTime, xdt:dayTimeDuration)
  • xs:time($arg as xdt:anyAtomicType) as (xs:time, xdt:dayTimeDuration)
  • xs:date($arg as xdt:anyAtomicType) as (xs:date, xdt:dayTimeDuration)
  • xs:gYearMonth($arg as xdt:anyAtomicType) as xs:gYearMonth
  • xs:gYear($arg as xdt:anyAtomicType) as xs:gYear
  • xs:gMonthDay($arg as xdt:anyAtomicType) as xs:gMonthDay
  • xs:gDay($arg as xdt:anyAtomicType) as xs:gDay
  • xs:gMonth($arg as xdt:anyAtomicType) as xs:gMonth
  • xs:hexBinary($arg as xdt:anyAtomicType) as xs:hexBinary
  • xs:base64Binary($arg as xdt:anyAtomicType) as xs:base64Binary
  • xs:anyURI($arg as xdt:anyAtomicType) as xs:anyURI
  • xs:QName($arg as xdt:anyAtomicType) as xs:QName

    See 17.14 Casting to xs:QName for semantics of xs:QName.

  • xs:normalizedString($arg as xdt:anyAtomicType) as xs:normalizedString
  • xs:token($arg as xdt:anyAtomicType) as xs:token