W3C

XQuery 1.0 and XPath 2.0 Functions and Operators

W3C Working Draft 11 February 2005

This version:
http://www.w3.org/TR/2005/WD-xpath-functions-20050211/
Latest version:
http://www.w3.org/TR/xpath-functions/
Previous version:
http://www.w3.org/TR/2004/WD-xpath-functions-20041029/
Editors:
Ashok Malhotra (XML Query and XSL WGs), Oracle Corporation <ashok.malhotra@alum.mit.edu>
Jim Melton (XML Query WG), Oracle Corporation <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 Second Edition] and the datatypes defined in [XQuery 1.0 and XPath 2.0 Data Model] and 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 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.

XQuery 1.0 and XPath 2.0 Functions and Operators has been defined through the efforts of a joint task force of theXML Query Working Group and theXSL Working Group (both part of theXML 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 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.

This draft includes many corrections and changes based on member-only and public comments on theLast Call Working Draft (http://www.w3.org/TR/2003/WD-xpath-functions-20031112/) and subsequent public and private drafts. The XML Query and XSL WGs wish to thank the people who have sent in comments for their close reading of the document.

This draft reflects decisions taken through the meeting in Redwood Shores, CA during the week of November 8, 2004 and subsequent telcons. These decisions are recorded in the XPath Functions issues list (http://www.w3.org/2005/02/xpath-functions-issues.html).

Some of the more significant changes that appear in this version of the document are:

There are two public comments having to do with the Character Model documents that are currently under preparation in the W3C. We decided to postpone consideration of these comments until such time as the Character Model documents progress to recommendation status. These comments are:

http://lists.w3.org/Archives/Public/public-qt-comments/2003Nov/0215.html and http://lists.w3.org/Archives/Public/public-qt-comments/2003Nov/0214.html

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

Public comments on this document and its open issues are invited. Comments should be sent to the W3C XPath/XQuery mailing list, public-qt-comments@w3.org (archived at http://lists.w3.org/Archives/Public/public-qt-comments/), with “[F&O]” at the beginning of the subject field.

The patent policy for this document is the 5 February 2004 W3C Patent Policy. 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. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1 Introduction
    1.1 Namespaces and Prefixes
    1.2 Function Overloading
    1.3 Function Signatures and Descriptions
    1.4 Namespace Terminology
    1.5 Type Hierarchy
    1.6 Terminology
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 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 A Special Constructor Function for xs:dateTime
    5.3 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.3.3 fn:codepoint-equal
    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 for anyURI
    8.1 fn:resolve-uri
9 Functions and Operators on Boolean Values
    9.1 Additional Boolean Constructor Functions
        9.1.1 fn:true
        9.1.2 fn:false
    9.2 Operators on Boolean Values
        9.2.1 op:boolean-equal
        9.2.2 op:boolean-less-than
        9.2.3 op:boolean-greater-than
    9.3 Functions on Boolean Values
        9.3.1 fn:not
10 Functions and Operators on Durations, Dates and Times
    10.1 xs:dateTime, xs:date and xs:time values
        10.1.1 Examples
    10.2 Duration, Date and Time Types
        10.2.1 Limits and Precision
    10.3 Two Totally Ordered Subtypes of Duration
        10.3.1 xdt:yearMonthDuration
        10.3.2 xdt:dayTimeDuration
    10.4 Comparisons of Duration, Date and Time Values
        10.4.1 op:yearMonthDuration-equal
        10.4.2 op:yearMonthDuration-less-than
        10.4.3 op:yearMonthDuration-greater-than
        10.4.4 op:dayTimeDuration-equal
        10.4.5 op:dayTimeDuration-less-than
        10.4.6 op:dayTimeDuration-greater-than
        10.4.7 op:dateTime-equal
        10.4.8 op:dateTime-less-than
        10.4.9 op:dateTime-greater-than
        10.4.10 op:date-equal
        10.4.11 op:date-less-than
        10.4.12 op:date-greater-than
        10.4.13 op:time-equal
        10.4.14 op:time-less-than
        10.4.15 op:time-greater-than
        10.4.16 op:gYearMonth-equal
        10.4.17 op:gYear-equal
        10.4.18 op:gMonthDay-equal
        10.4.19 op:gMonth-equal
        10.4.20 op:gDay-equal
    10.5 Component Extraction Functions on Durations, Dates and Times
        10.5.1 fn:years-from-duration
        10.5.2 fn:months-from-duration
        10.5.3 fn:days-from-duration
        10.5.4 fn:hours-from-duration
        10.5.5 fn:minutes-from-duration
        10.5.6 fn:seconds-from-duration
        10.5.7 fn:year-from-dateTime
        10.5.8 fn:month-from-dateTime
        10.5.9 fn:day-from-dateTime
        10.5.10 fn:hours-from-dateTime
        10.5.11 fn:minutes-from-dateTime
        10.5.12 fn:seconds-from-dateTime
        10.5.13 fn:timezone-from-dateTime
        10.5.14 fn:year-from-date
        10.5.15 fn:month-from-date
        10.5.16 fn:day-from-date
        10.5.17 fn:timezone-from-date
        10.5.18 fn:hours-from-time
        10.5.19 fn:minutes-from-time
        10.5.20 fn:seconds-from-time
        10.5.21 fn:timezone-from-time
    10.6 Arithmetic Functions on Durations
        10.6.1 op:add-yearMonthDurations
        10.6.2 op:subtract-yearMonthDurations
        10.6.3 op:multiply-yearMonthDuration
        10.6.4 op:divide-yearMonthDuration
        10.6.5 op:divide-yearMonthDuration-by-yearMonthDuration
        10.6.6 op:add-dayTimeDurations
        10.6.7 op:subtract-dayTimeDurations
        10.6.8 op:multiply-dayTimeDuration
        10.6.9 op:divide-dayTimeDuration
        10.6.10 op:divide-dayTimeDuration-by-dayTimeDuration
    10.7 Timezone Adjustment on Dates and Time Values
        10.7.1 fn:adjust-dateTime-to-timezone
        10.7.2 fn:adjust-date-to-timezone
        10.7.3 fn:adjust-time-to-timezone
    10.8 Arithmetic Functions on Durations, Dates and Times
        10.8.1 op:subtract-dateTimes-yielding-dayTimeDuration
        10.8.2 op:subtract-dates-yielding-dayTimeDuration
        10.8.3 op:subtract-times
        10.8.4 op:add-yearMonthDuration-to-dateTime
        10.8.5 op:add-dayTimeDuration-to-dateTime
        10.8.6 op:subtract-yearMonthDuration-from-dateTime
        10.8.7 op:subtract-dayTimeDuration-from-dateTime
        10.8.8 op:add-yearMonthDuration-to-date
        10.8.9 op:add-dayTimeDuration-to-date
        10.8.10 op:subtract-yearMonthDuration-from-date
        10.8.11 op:subtract-dayTimeDuration-from-date
        10.8.12 op:add-dayTimeDuration-to-time
        10.8.13 op:subtract-dayTimeDuration-from-time
11 Functions Related to QNames
    11.1 Additional Constructor Functions for QNames
        11.1.1 fn:resolve-QName
        11.1.2 fn:QName
    11.2 Operators and Functions Related to QNames
        11.2.1 op:QName-equal
        11.2.2 fn:local-name-from-QName
        11.2.3 fn:namespace-uri-from-QName
        11.2.4 fn:namespace-uri-for-prefix
        11.2.5 fn:in-scope-prefixes
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 fn:name
    14.2 fn:local-name
    14.3 fn:namespace-uri
    14.4 fn:number
        14.4.1 Examples
    14.5 fn:lang
        14.5.1 Examples
    14.6 op:is-same-node
        14.6.1 Examples
    14.7 op:node-before
        14.7.1 Examples
    14.8 op:node-after
        14.8.1 Examples
    14.9 fn:root
        14.9.1 Examples
15 Functions and Operators on Sequences
    15.1 General Functions and Operators on Sequences
        15.1.1 fn:boolean
        15.1.2 op:concatenate
        15.1.3 fn:index-of
        15.1.4 fn:empty
        15.1.5 fn:exists
        15.1.6 fn:distinct-values
        15.1.7 fn:insert-before
        15.1.8 fn:remove
        15.1.9 fn:reverse
        15.1.10 fn:subsequence
        15.1.11 fn:unordered
    15.2 Functions That Test the Cardinality of Sequences
        15.2.1 fn:zero-or-one
        15.2.2 fn:one-or-more
        15.2.3 fn:exactly-one
    15.3 Equals, Union, Intersection and Except
        15.3.1 fn:deep-equal
        15.3.2 op:union
        15.3.3 op:intersect
        15.3.4 op:except
    15.4 Aggregate Functions
        15.4.1 fn:count
        15.4.2 fn:avg
        15.4.3 fn:max
        15.4.4 fn:min
        15.4.5 fn:sum
    15.5 Functions and Operators that Generate Sequences
        15.5.1 op:to
        15.5.2 fn:id
        15.5.3 fn:idref
        15.5.4 fn:doc
        15.5.5 fn:doc-available
        15.5.6 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:implicit-timezone
    16.7 fn:default-collation
    16.8 fn:static-base-uri
17 Casting
    17.1 Casting from primitive types to primitive types
        17.1.1 Casting from xs:string and xdt:untypedAtomic
        17.1.2 Casting to xs:string and xdt:untypedAtomic
        17.1.3 Casting to numeric types
        17.1.4 Casting to duration types
        17.1.5 Casting to date and time types
        17.1.6 Casting to xs:boolean
        17.1.7 Casting to xs:base64Binary and xs:hexBinary
        17.1.8 Casting to xs:anyURI
    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

Appendices

A References
    A.1 Normative
    A.2 Non-normative
B Error Summary
C Compatibility with XPath 1.0 (Non-Normative)
D Illustrative User-written Functions (Non-Normative)
    D.1 eg:if-empty and eg:if-absent
        D.1.1 eg:if-empty
        D.1.2 eg:if-absent
    D.2 union, intersect and except on sequences of values
        D.2.1 eg:value-union
        D.2.2 eg:value-intersect
        D.2.3 eg:value-except
    D.3 eg:index-of-node
    D.4 eg:string-pad
    D.5 eg:distinct-nodes-stable
    D.6 Working With xs:duration Values
E XML Schema for xdt:yearMonthDuration and xdt:dayTimeDurations (Non-Normative)
F Function and Operator Quick Reference (Non-Normative)
    F.1 Functions and Operators by Section
    F.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 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 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 three datatypes defined in Section 2.6 TypesDM and the two totally ordered subtypes of the duration datatype from [XML Schema Part 2: Datatypes Second Edition] defined in 10.3 Two Totally Ordered Subtypes of Duration. These functions and operations are defined 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 functions and operators 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 Namespaces and Prefixes

The functions and operators discussed in this document are contained in one of four 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 Second Edition] 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 for functions that are available to users is fn:. Operator functions are named with the prefix op:.

The datatypes described in Section 2.6 TypesDM of the Data Model and 10.3 Two Totally Ordered Subtypes of Duration in this document are contained in a separate namespace and are named using the prefix xdt:.

The error codes and messages used in this document and related documents are named with the prefix err:.

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

The URIs of the namespaces and the default prefixes associated with them are:

  • http://www.w3.org/2001/XMLSchema for constructors -- associated with xs:

  • http://www.w3.org/2005/02/xpath-functions for functions -- associated with fn:.

  • http://www.w3.org/2005/02/xpath-datatypes for the datatypes -- associated with xdt:.

  • http://www.w3.org/2004/07/xqt-errors -- associated with err:.

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.

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.2 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 [XPath 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 6 Functions and Operators on Numerics that accept numeric parameters accept arguments of type xs:integer, xs:decimal, xs:float or xs:double. See 1.3 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.3 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 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.3 SequenceType SyntaxXP.

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.

In some cases, the static 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 7.2 Standard functions with specific typing rulesFS.

The function name is aQName as defined in [XML Schema Part 2: Datatypes Second Edition] 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 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 1.0: An XML Query Language] and [XPath 2.0]. For example, the rules for passing parameters to arithmetic operators are described in Section 3.4 Arithmetic ExpressionsXP. Specifically, rules for parameters of typexdt: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.4 SequenceType MatchingXP). In addition, numeric type instances and instances of typexs:anyURI can be promoted to produce an argument of the required type. (See Section B.1 Type PromotionXP).

  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, and xs:float may be promoted to xs:double.

  3. anyURI Type Promotion: A value of typexs:anyURI can be promoted to the typexs: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 forfn: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, referred to as "()."

Some functions accept a sequence of zero or more values 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.4 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" defined below.

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

1.5 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 Second Edition] (shown on the right) as well as types defined in [XQuery 1.0 and XPath 2.0 Data Model] (shown on the left). Solid lines connect a base datatype above to a derived datatype.xs:IDREFS, xs:NMTOKENS, xs:ENTITIES and user-defined list and union types are special types in that these types are lists or unions 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 [XQuery 1.0 and XPath 2.0 Data Model]

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
xdt:untyped
xs:anySimpleType
user-defined list and union types
xs:IDREFS
xs:NMTOKENS
xs:ENTITIES
xdt:anyAtomicType

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

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

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

The table below shows the type hierarchy for the types introduced in[XQuery 1.0 and XPath 2.0 Data Model]. 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.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 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] execution scope

The scope over which any two calls on a function would be executed. 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.

[Definition] stable

Most of the functions in the core library have the property that calling the same function twice within an ·execution scope· with the same arguments returns the same result: these functions are said to 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 and are returned in the same order.. 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.

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

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

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

fn:nilled($arg as node()?) as xs:boolean?

Summary: Returns anxs:boolean indicating whether the argument node is"nilled". If the argument is not an element node, returns the empty sequence. If the argument is the empty sequence, returns the empty sequence.

2.3 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 no argument is supplied and the context item is undefined, an error is raised: [err:FONC0001].

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

    • If the node does not have a typed value an error is raised [err:XP0007]XP.

    • Otherwise, fn:data() returns the typed value of the node as defined by the accessor function dm:typed-value in Section 5.15 typed-value AccessorDM.

2.5 fn:base-uri

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

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.2 base-uri AccessorDM. If $arg is not specified, returns the value of the base-uri property of the context item (.) with the above semantics. If the context item is not a node, an error is raised:[err:XP0006]XP If the context item is undefined, an error is raised: [err:FONC0001].

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 property of all other node types is the empty sequence. The value of the base-uri property is returned if it exists and is not empty. Otherwise, if the node has a parent, the value of dm:base-uri() applied to its parent is returned, recursively. If the node does not have a parent, or if the recursive ascent up the ancestor chain encounters a node whose base-uri property is empty and it does not have a parent, the empty sequence is returned.

See also fn:static-base-uri.

2.6 fn:document-uri

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

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

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

Returns the empty sequence if the node is not a document node. Otherwise, returns the value of the dm:document-uri accessor of the document node.

If fn:document-uri($arg) does not return 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. Raising an error is equivalent to invoking 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/2004/07/xqt-errors namespace. 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, seeSection 2.3.3 Handling Dynamic ErrorsXP and Section 7.2.6 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 1.0: An XML Query Language] or [XPath 2.0] applications with, for example, an xs:QName argument.

fn:error() as none
fn:error($error as xs:QName) as none
fn:error($error as xs:QName?, $description as xs:string) as none
fn:error( $error  as xs:QName?,
$description  as xs:string,
$error-object  as item()*)

Summary: The fn:error function causes the evaluation of the outermost XQuery or transformation to stop. While this function never returns a value, an error, if it occurs, is returned to the external processing environment as an xs:anyURI or an xs:QName. The error xs:anyURI is derived from the error xs:QName. An error xs:QName with namespace URI NS and local part LP will be returned as the xs:anyURI NS#LP. The method by which the xs:anyURI or xs:QName is returned to the external processing environment is ·implementation dependent·.

If an invocation provides $description and$error-object, then these values may also be returned to the external processing environment. The method by which these values are provided to the external environment is ·implementation dependent·.

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.

If fn:error is invoked with no arguments, then its behavior is the same as the invocation of the following expression:

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

If the first argument in the third or fourth signature is the empty sequence it is assumed to be the xs:QName constructed by:

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

3.1 Examples

  • fn:error() returns http://www.w3.org/2005/02/xqt-errors#FOER0000 to the external processing environment.

  • fn:error(xs:QName("err:FOAR0003")) returns http://www.w3.org/2005/02/xqt-errors#FOAR0003 to the external processing environment.

  • fn:error(fn:QName('http://www.example.com/HR', 'err:toohighsal'), 'Does not apply because salary is too high') returns http://www.example.com/HR#toohighsal and the xs:string "Does not apply because salary is too high" to the external processing environment.

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, 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 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 dependent 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 Second Edition], except xs:NOTATION, has an associated constructor function; as do xdt:untypedAtomic, defined in Section 2.6 TypesDM and the two derived types xdt:yearMonthDuration and xdt:dayTimeDuration defined in 10.3 Two Totally Ordered Subtypes of Duration. 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 ContextXP) contains a type derived from xs:NOTATION then a constructor function is defined for it. See 5.3 Constructor Functions for User-Defined Types.

The form of that function for a type prefix:TYPE is:

prefix:TYPE($arg as xdt: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:

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

Invoking the constructor functionxs:unsignedInt(12) returns thexs: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 typed value equal to the xs:unsignedInt 12. The standard features described in Section 2.4.2 AtomizationXP 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 illegal for the datatype to be constructed, an error is raised [err:FORG0001].

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 Second Edition]. If the value passed to a constructor is illegal for the datatype to be constructed, an error is raised[err:FORG0001]. The semantics of constructor functions when invoked with an xs:string are identical to XML Schema validation and return a value of the given type, except in the case of xs:dateTime, xs:date and xs:time. For these types the value returned differs from [XML Schema Part 2: Datatypes Second Edition] and is defined in 10.1 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? ", except for constructors for xs:QName and types derived from xs:NOTATION which are identical to "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 in these explanations invariably take xs:string arguments and, in this case, the semantics are the semantics of XML Schema validation as discussed above.

Constructor functions for xs:QName and types derived from xs:QName and xs:NOTATION, are constrained to take a string literal as their argument. (This means that they are actually pseudo-functions: they can always be evaluated statically.)

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.

Any prefix within the lexical QName supplied as the argument is resolved to a namespace URI using the statically known namespaces from the static context. If the lexical 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 discussed in Section C.1 Static Context ComponentsXP. A static error is raised[err:FONS0004] if the prefix is not bound in the static context. As described inSection 2.1 TerminologyDM, the supplied prefix is retained as part of the expanded-QName value.

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?
  • xs:time($arg as xdt:anyAtomicType?) as xs:time?
  • xs:date($arg as xdt:anyAtomicType?) as xs:date?
  • 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 xs:string) as xs:QName

    $arg must be a xs:string literal.

  • xs:normalizedString($arg as xdt:anyAtomicType?) as xs:normalizedString?
  • xs:token($arg as xdt:anyAtomicType?) as xs:token?
  • xs:language($arg as xdt:anyAtomicType?) as xs:language?
  • xs:NMTOKEN($arg as xdt:anyAtomicType?) as xs:NMTOKEN?
  • xs:Name($arg as xdt:anyAtomicType?) as xs:Name?
  • xs:NCName($arg as xdt:anyAtomicType?) as xs:NCName?
  • xs:ID($arg as xdt:anyAtomicType?) as xs:ID?
  • xs:IDREF($arg as xdt:anyAtomicType?) as xs:IDREF?
  • xs:ENTITY($arg as xdt:anyAtomicType?) as xs:ENTITY?
  • xs:integer($arg as xdt:anyAtomicType?) as xs:integer?
  • xs:nonPositiveInteger($arg as xdt:anyAtomicType?) as xs:nonPositiveInteger?
  • xs:negativeInteger($arg as xdt:anyAtomicType?) as xs:negativeInteger?
  • xs:long($arg as xdt:anyAtomicType?) as xs:long?
  • xs:int($arg as xdt:anyAtomicType?) as xs:int?
  • xs:short($arg as xdt:anyAtomicType?) as xs:short?
  • xs:byte($arg as xdt:anyAtomicType?) as xs:byte?
  • xs:nonNegativeInteger($arg as xdt:anyAtomicType?) as xs:nonNegativeInteger?
  • xs:unsignedLong($arg as xdt:anyAtomicType?) as xs:unsignedLong?
  • xs:unsignedInt($arg as xdt:anyAtomicType?) as xs:unsignedInt?
  • xs:unsignedShort($arg as xdt:anyAtomicType?) as xs:unsignedShort?
  • xs:unsignedByte($arg as xdt:anyAtomicType?) as xs:unsignedByte?
  • xs:positiveInteger($arg as xdt:anyAtomicType?) as xs:positiveInteger?
  • xdt:yearMonthDuration($arg as xdt:anyAtomicType?) as xdt:yearMonthDuration?
  • xdt:dayTimeDuration($arg as xdt:anyAtomicType?) as xdt:dayTimeDuration?
  • xdt:untypedAtomic($arg as xdt:anyAtomicType?) as xdt:untypedAtomic?

5.2 A Special Constructor Function for xs:dateTime

A special constructor function is provided for constructing a xs:dateTime value from a xs:date value and a xs:time value.

fn:dateTime($arg1 as xs:date, $arg2 as xs:time) as xs:dateTime

The result xs:dateTime has a date component whose value is equal to $arg1 and a time component whose value 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.

  • If the two arguments have different timezones, an error is raised:[err:FORG0008]

5.3 Constructor Functions for User-Defined Types

For every atomic type in the static context (See Section 2.1.1 Static ContextXP) that is derived from a primitive type, there is a constructor function (whose name is the same as the name of the type) 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 discussed in 5.1 Constructor Functions for XML Schema Built-in Types.

Consider a situation where the static context contains a type calledhatSize defined in a schema whose target namespace is bound to the prefix my. In such a case the constructor function:

my:hatSize($arg as xdt:anyAtomicType) as my:hatSize

is available to users.

To construct an instance of an atomic type that is not in a namespace, it is necessary to use a cast expression or undeclare the default function namespace declaration. For example, if the user-defined typeapple 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)

6 Functions and Operators on Numerics

This section discusses 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.

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

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

They also apply to types derived by restriction from these types.

Note:

This specification uses [IEEE 754-1985] arithmetic for xs:float and xs:double values. 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 while [IEEE 754-1985] arithmetic treats NaN as unequal to all other values including itself and can produce distinct results of positive zero and negative zero. (These are two different machine representations for the same [XML Schema Part 2: Datatypes Second Edition] value.) The text accompanying several functions discusses behaviour for both positive and negative zero inputs and outputs in the interest of alignment with [IEEE 754-1985].

6.2 Operators on Numeric Values

The following functions define the semantics of operators defined in [XQuery 1.0: An XML Query Language] and [XPath 2.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 anxs: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 2.5.4 SequenceType MatchingXP andSection B.1 Type PromotionXP 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:float or xs:double, and xs:float 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.

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-1985]. This specification allows the following options:

    • Raising an 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-1985]. This specification allows the following options:

    • Raising an 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 an 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