XQuery 1.0 and XPath 2.0 Functions and Operators (Second Edition)

XQuery 1.0 and XPath 2.0 Functions and Operators (Second
Edition)
XQuery 1.0 and XPath 2.0
Functions and Operators (Second Edition)
W3C Recommendation
14 December 2010 (revised 13 April 2015)
This version:
Latest version:
Previous versions:
Editors:
Ashok Malhotra, Oracle Corporation

Jim Melton, Oracle Corporation

Norman Walsh, Mark Logic

Michael Kay, Saxonica

Second Edition
Please refer to the
errata
for this document, which may include
some normative corrections.
See also
translations
This document is also available in these non-normative formats:
XML
and
Change
markings relative to first edition
W3C
MIT
ERCIM
Keio
), All Rights Reserved.
W3C
liability
trademark
and
document
use
rules apply.
Note:
This paragraph is informative.
This document is currently not maintained.
This document remains available on the W3C's Technical Report
web page for reference and use by interested parties. Readers are advised that no further maintenance
(including correction of reported errors) is planned for this
document. Readers interested in the most recent version of the
XQuery and XPath Functions and Operators specification are encouraged to refer to
Abstract
This document defines constructor functions, operators and
functions on the datatypes defined in
[XML
Schema Part 2: Datatypes Second Edition]
and the datatypes
defined in
[XQuery 1.0 and XPath 2.0
Data Model]
. It also discusses functions and operators on nodes
and node sequences as defined in the
[XQuery 1.0 and XPath 2.0 Data Model]
. These
functions and operators are defined for use in
[XML Path Language (XPath) 2.0]
[XQuery 1.0: An XML Query Language]
and
[XSL Transformations (XSLT) Version 2.0]
and other
related XML standards. The signatures and summaries of functions
defined in this document are available at:
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
This is one document in a set of eight documents that are being
progressed to Edited Recommendation together (XPath 2.0, XQuery
1.0, XQueryX 1.0, XSLT 2.0, Data Model (XDM), Functions and
Operators, Formal Semantics, Serialization).
This document, published on 14 December 2010, is an Edited
Recommendation
of the W3C. This second edition is not a new version of this
specification; its purpose is to clarify a number of issues that
have become apparent since the first edition was published. All of
these clarifications (excepting trivial editorial fixes) have been
published in a separate errata document, and published in a
Proposed Edited Recommendation
in April, 2009. The changes are
summarized in an appendix.
This document has been jointly developed by the W3C
XML Query Working Group
and the
W3C
XSL Working Group
each of which is part of the
XML Activity
This document has been reviewed by W3C Members, by software
developers, and by other W3C groups and interested parties, and is
endorsed by the Director as a W3C Recommendation. It is a stable
document and may be used as reference material or cited from
another document. W3C's role in making the Recommendation is to
draw attention to the specification and to promote its widespread
deployment. This enhances the functionality and interoperability of
the Web.
This document incorporates changes made against the
Recommendation
of 23 January 2007 that resolve all errata known at the date of
publication. A list of the errata that have been applied, with
links to the Bugzilla database, is provided in
F Changes since the First
Edition
. The version of this document with change
highlighting indicates where the textual changes have been made,
and cross-references each textual change to the erratum where it
originated. This document supersedes the
first
edition
This specification is designed to be referred to normatively
from other specifications defining a host language for it; it is
not intended to be implemented outside a host language. The
implementability of this specification has been tested in the
context of its normative inclusion in host languages defined by the
XQuery 1.0
and
XSLT 2.0
specifications; see the
XQuery 1.0
implementation report
and the
XSLT 2.0 implementation report
(member-only) for details.
This document was produced by groups operating under the
February 2004 W3C Patent Policy
. W3C maintains a
public
list of any patent disclosures
made in connection with the
deliverables of the XML Query Working Group and also maintains a
public
list of any patent disclosures
made in connection with the
deliverables of the XSL Working Group; those pages also include
instructions for disclosing a patent. An individual who has actual
knowledge of a patent which the individual believes contains
Essential Claim(s)
must disclose the information in accordance
with
section 6 of the W3C Patent Policy
Table of Contents
Introduction
1.1
Conformance
1.2
Namespaces and Prefixes
1.3
Function
Overloading
1.4
Function
Signatures and Descriptions
1.5
Namespace Terminology
1.6
Type
Hierarchy
1.7
Terminology
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
The Error Function
3.1
Examples
The Trace Function
4.1
Examples
Constructor Functions
5.1
Constructor Functions for
XML Schema Built-in Types
5.2
A Special
Constructor Function for xs:dateTime
5.2.1
Examples
5.3
Constructor Functions for xs:QName
and xs:NOTATION
5.4
Constructor
Functions for User-Defined Types
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
Operators on 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
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:encode-for-uri
7.4.11
fn:iri-to-uri
7.4.12
fn:escape-html-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
Functions on anyURI
8.1
fn:resolve-uri
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
Duration, Date and Time Types
10.1.1
Limits and Precision
10.2
Date/time
datatype values
10.2.1
Examples
10.3
Two
Totally Ordered Subtypes of Duration
10.3.1
xs:yearMonthDuration
10.3.2
xs:dayTimeDuration
10.4
Comparison Operators on Duration, Date
and Time Values
10.4.1
op:yearMonthDuration-less-than
10.4.2
op:yearMonthDuration-greater-than
10.4.3
op:dayTimeDuration-less-than
10.4.4
op:dayTimeDuration-greater-than
10.4.5
op:duration-equal
10.4.6
op:dateTime-equal
10.4.7
op:dateTime-less-than
10.4.8
op:dateTime-greater-than
10.4.9
op:date-equal
10.4.10
op:date-less-than
10.4.11
op:date-greater-than
10.4.12
op:time-equal
10.4.13
op:time-less-than
10.4.14
op:time-greater-than
10.4.15
op:gYearMonth-equal
10.4.16
op:gYear-equal
10.4.17
op:gMonthDay-equal
10.4.18
op:gMonth-equal
10.4.19
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 Operators 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 Functions 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 Operators on Durations, Dates and
Times
10.8.1
op:subtract-dateTimes
10.8.2
op:subtract-dates
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
Functions
and Operators Related to QNames
11.2.1
op:QName-equal
11.2.2
fn:prefix-from-QName
11.2.3
fn:local-name-from-QName
11.2.4
fn:namespace-uri-from-QName
11.2.5
fn:namespace-uri-for-prefix
11.2.6
fn:in-scope-prefixes
12
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
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
15.5.7
fn:element-with-id
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
xs:untypedAtomic
17.1.2
Casting to xs:string and
xs: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.4.1
Casting to xs:ENTITY
17.5
Casting across the type
hierarchy
Appendices
References
A.1
Normative
References
A.2
Non-normative References
Error Summary
Compatibility with XPath 1.0
(Non-Normative)
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
Checklist of Implementation-Defined
Features
(Non-Normative)
Changes since the First
Edition
(Non-Normative)
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
[XML Path Language (XPath)
2.0]
[XQuery 1.0: An XML Query Language]
and
[XSL Transformations (XSLT) Version
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
datatypes defined in
Section 2.6
Types
DM
of the
[XQuery 1.0 and XPath 2.0 Data Model]
. These
functions and operations are defined for use in
[XML Path Language (XPath) 2.0]
[XQuery 1.0: An XML Query Language]
and
[XSL Transformations (XSLT) Version 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
[XML Path Language (XPath) 2.0]
[XQuery 1.0: An XML Query Language]
and
[XSL Transformations (XSLT) Version 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'
[XSL Transformations
(XSLT) Version 2.0]
, 'XP'
[XML Path Language
(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 Conformance
The Functions and Operators specification is intended primarily
as a component that can be used by other specifications. Therefore,
Functions and Operators relies on specifications that use it (such
as
[XML Path Language (XPath) 2.0]
[XSL Transformations (XSLT) Version 2.0]
and
[XQuery 1.0: An XML Query Language]
) to specify
conformance criteria for their respective environments.
Authors of conformance criteria for the use of the Functions and
Operators should pay particular attention to the following
features:
It is
implementation-defined
which version of Unicode is supported, but it
is recommended that the most recent version of Unicode be used.
Support for XML 1.0 and XML 1.1 by the datatypes used in
Functions and Operators.
Note:
At the time of writing there is no published version of XML
Schema that references the XML 1.1 specifications. This means that
datatypes such as
xs:NCName
and
xs:ID
are
constrained by the XML 1.0 rules. Authors of conformance
requirements for the use of Functions and Operators should state
clearly the implications for conformance of any changes to the
rules in later versions of XML Schema.
In this document, text labeled as an example or as a Note is
provided for explanatory purposes and is not normative.
1.2
Namespaces and Prefixes
The functions and operators discussed in this document are
contained in one of three namespaces (see
[Namespaces in XML]
) and referenced using an
xs:QName
. The datatypes and constructor functions for
the built-in datatypes defined in
[XML
Schema Part 2: Datatypes Second Edition]
and in
Section 2.6
Types
DM
of
[XQuery 1.0 and XPath 2.0 Data Model]
and
discussed in
5 Constructor
Functions
are in the XML Schema namespace,
, 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
This document uses the prefix
err
to represent the
namespace URI
, which
is the namespace for all XPath and XQuery error codes and messages.
This namespace prefix is not predeclared and its use in this
document is not normative.
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:
for constructors
-- associated with
xs
for
functions -- associated with
fn
-- 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
[XML Path Language (XPath)
2.0]
[XQuery 1.0: An XML Query Language]
and
[XSL Transformations (XSLT) Version 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:numeric-multiply
$arg1
as
numeric
$arg2
as
numeric
as
numeric
1.3
Function Overloading
In general, the specifications named above do not support
function overloading in the sense that functions that have multiple
signatures with the same name and the same number of parameters are
not supported. Consequently, there are no such overloaded functions
in this document except for legacy
[XML Path
Language (XPath) Version 1.0]
functions such as
fn:string()
, which accepts a single
parameter of a variety of types. In addition, it should be noted
that the functions defined in
Functions and Operators on Numerics
that accept
numeric
parameters accept arguments of type
xs:integer
xs:decimal
xs:float
or
xs:double
. See
1.4 Function Signatures and
Descriptions
. Operators such as "+" may be overloaded. This
document does define some functions with more than one signature
with the same name and different number of parameters. User-defined
functions with more than one signature with the same name and
different number of parameters are also supported.
1.4 Function
Signatures and Descriptions
Each function is defined by specifying its signature, a
description of the return type and each of the parameters and its
semantics. For many functions, examples are included to illustrate
their use.
Each function's signature is presented in a form like this:
fn:function-name
$parameter-name
as
parameter-type
...
as
return-type
In this notation,
function-name
, in bold-face, is the
name of the function whose signature is being specified. If the
function takes no parameters, then the name is followed by an empty
parameter list: "
()
"; otherwise, the name is followed
by a parenthesized list of parameter declarations, each declaration
specifies the static type of the parameter, in italics, and a
descriptive, but non-normative, name. If there are two or more
parameter declarations, they are separated by a comma. The
return-type
, also in italics, specifies the
static type of the value returned by the function. The dynamic type
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 Syntax
XP
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 static typing
rules
FS
The function name is a
QName
as defined in
[XML Schema Part 2: Datatypes Second Edition]
and must adhere to its syntactic conventions. Following
[XML Path Language (XPath) Version 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
[XML Path Language (XPath)
2.0]
. For example, the rules for passing parameters to
arithmetic operators are described in
Section 3.4
Arithmetic Expressions
XP
Specifically, rules for parameters of type
xs:untypedAtomic
and the empty sequence are specified
in this section.
As is customary, the parameter type name indicates that the
function or operator accepts arguments of that type, or types
derived from it, in that position. This is called
subtype
substitution
(See
Section
2.5.4 SequenceType Matching
XP
). In
addition, numeric type instances and instances of type
xs:anyURI
can be promoted to produce an argument of
the required type. (See
Section B.1 Type
Promotion
XP
).
Subtype Substitution
: A derived type may substitute for
its base type. In particular,
xs:integer
may be used
where
xs:decimal
is expected.
Numeric Type Promotion
xs:decimal
may be
promoted to
xs:float
or
xs:double
Promotion to
xs:double
should be done directly, not
via
xs:float
, to avoid loss of precision.
anyURI Type Promotion
: A value of type
xs:anyURI
can be promoted to the type
xs:string
Some functions accept a single value or the empty sequence as an
argument and some may return a single value or the empty sequence.
This is indicated in the function signature by following the
parameter or return type name with a question mark:
", indicating that either a single value or the
empty sequence must appear. See below.
fn:function-name
$parameter-name
as
parameter-type?
as
return-type?
Note that this function signature is different from a signature
in which the parameter is omitted. See, for example, the two
signatures for
fn:string()
In the first signature, the parameter is omitted and the argument
defaults to the context item, referred to as ".". In the second
signature, the argument must be present but may be the empty
sequence, 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.5 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.6 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.
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
xs: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
xs:untyped
xs:anySimpleType
user-defined
list and union types
xs:IDREFS
xs:NMTOKENS
xs:ENTITIES
xs:anyAtomicType
The table below shows the datatypes derived from
xs: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 in
Section 2.6
Types
DM
Each type whose name is indented is derived from the type whose
name appears nearest above it with one less level of
indentation.
xs:untypedAtomic
xs:dateTime
xs:date
xs:time
xs:duration
xs:yearMonthDuration
xs:dayTimeDuration
xs:float
xs:double
xs:decimal
xs:integer
xs:nonPositiveInteger
xs:negativeInteger
xs:long
xs:int
xs:short
xs:byte
xs:nonNegativeInteger
xs:unsignedLong
xs:unsignedInt
xs:unsignedShort
xs:unsignedByte
xs:positiveInteger
xs:gYearMonth
xs:gYear
xs:gMonthDay
xs:gDay
xs:gMonth
xs:string
xs:normalizedString
xs:token
xs:language
xs:NMTOKEN
xs:Name
xs:NCName
xs:ID
xs:IDREF
xs:ENTITY
xs:boolean
xs:base64Binary
xs:hexBinary
xs:anyURI
xs:QName
xs:NOTATION
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 indentation.
item
xs:anyAtomicType
node
attribute
user-defined
attribute types
comment
document
user-defined
document types
element
user-defined
element types
processing-instruction
text
1.7 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
[XML Path Language (XPath) Version 1.0]
[Definition]
may
Conforming documents and processors are permitted to, but need
not, behave as described.
[Definition]
must
Conforming documents and processors are required to behave as
described; otherwise, they are either non-conformant or else in
error.
[Definition]
implementation-defined
Possibly differing between implementations, but specified and
documented by the implementor for each particular
implementation.
[Definition]
implementation-dependent
Possibly differing between implementations, but not specified by
this or other W3C specification, and not required to be specified
by the implementor for any particular implementation.
[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 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.
Note:
in the case of
fn:collection()
and
fn:doc()
, the requirement for
stability may be relaxed: see the function definitions for
details.
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
[Definition]
URI and URI reference
Within this specification, the term "URI" refers to Universal
Resource Identifiers as defined in
[RFC
3986]
and extended in
[RFC 3987]
with a
new name "IRI". The term "URI Reference", unless otherwise stated,
refers to a string in the lexical space of the
xs:anyURI
datatype as defined in
[XML Schema Part 2: Datatypes Second Edition]
Note that this means, in practice, that where this specification
requires a "URI Reference", an IRI as defined in
[RFC 3987]
will be accepted, provided that other
relevant specifications also permit an IRI. The term URI has been
retained in preference to IRI to avoid introducing new names for
concepts such as "Base URI" that are defined or referenced across
the whole family of XML specifications. Note also that the
definition of
xs:anyURI
is a wider definition than the
definition in
[RFC 3987]
; for example it
does not require non-ASCII characters to be escaped.
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 an
xs: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, the context
item (
) is used as the default argument. The behavior
of the function if the argument is omitted is exactly the same as
if the context item had been passed as the argument.
If the context item is undefined, error [
err:XPDY0002
XP
is
raised.
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 Accessor
DM
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
xs: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:FOTY0012
].
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 Accessor
DM
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 URI property for
$arg
as defined by the accessor function
dm:base-uri()
for that kind of node in
Section 5.2
base-uri Accessor
DM
. If
$arg
is not specified, the behavior is identical to
calling the function with the context item (
) as
argument. The following errors may be raised: if the context item
is undefined [
err:XPDY0002
XP
if the context item is not a node [
err:XPTY0004
XP
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 Accessors
DM
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.
In the case of a document node
$D
returned by the
fn:doc
function, or a document
node at the root of a tree containing a node returned by the
fn:collection
function,
it will always be true that either
fn:document-uri($D)
returns the empty sequence, or that the following expression is
true:
fn:doc(fn:document-uri($D))
is
$D
. It is implementation-defined whether this
guarantee also holds for document nodes obtained by other means,
for example a document node passed as the initial context node of a
query or transformation.
3 The Error
Function
In this document, as well as in
[XQuery 1.0:
An XML Query Language]
[XML Path 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
namespace,
represented in this document by the
err
prefix. It is
this
xs:QName
that is actually passed as an argument
to the
fn:error
function invocation. Invocation of
this function raises an error. For a more detailed treatment of
error handing, see
Section 2.3.3
Handling Dynamic Errors
XP
and
Section
7.2.9 The fn:error function
FS
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
[XML Path Language (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()*
as
none
Summary: The
fn:error
function raises an error.
While this function never returns a value, an error 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:
The value of the
$description
parameter may need to
be localized.
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/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/xqt-errors', 'err:FOER0000')
3.1
Examples
fn:error()
returns
(or the
corresponding
xs:QName
) to the external processing
environment.
fn:error(fn:QName('http://www.example.com/HR',
'myerr:toohighsal'), 'Does not apply because salary is too
high')
returns
and the
xs:string
"Does not apply because salary is too
high"
(or the corresponding
xs:QName
) to the
external processing environment.
4 The Trace
Function
fn:trace
$value
as
item()*
$label
as
xs:string
as
item()*
Summary: Provides an execution trace intended to be used in
debugging queries.
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:anyAtomicType
and
xs:NOTATION
has an associated constructor function.
xs:untypedAtomic
, defined in
Section 2.6
Types
DM
and the two derived types
xs:yearMonthDuration
and
xs:dayTimeDuration
defined in
Section 2.6
Types
DM
also have associated
constructor functions.
A constructor function is not defined for
xs:anyAtomicType
as there are no atomic values with
type annotation
xs:anyAtomicType
at runtime, although
this can be a statically inferred type. A constructor function is
not defined for
xs:NOTATION
since it is defined as an
abstract type in
[XML Schema Part 2:
Datatypes Second Edition]
. If the static context (See
Section 2.1.1 Static
Context
XP
) contains a type derived
from
xs:NOTATION
then a constructor function is
defined for it. See
5.4 Constructor
Functions for User-Defined Types
The form of the constructor function for a type
prefix:TYPE
is:
prefix:TYPE
$arg
as
xs:anyAtomicType?
as
prefix:TYPE?
If
$arg
is the empty sequence, the empty sequence
is returned. For example, the signature of the constructor function
corresponding to the
xs:unsignedInt
type defined in
[XML Schema Part 2: Datatypes Second
Edition]
is:
xs:unsignedInt
$arg
as
xs: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 typed value equal to the
xs:unsignedInt
12.
The standard features described in
Section 2.4.2
Atomization
XP
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
].
The semantics of the constructor function "
xs:TYPE(arg)
" are identical to the semantics of "
arg
cast as
xs:TYPE?
". See
17 Casting
If the argument to a constructor function is a literal, the
result of the function may be evaluated statically; if an error is
found during such evaluation, it may be reported as a static
error.
Special rules apply to constructor functions for
xs:QName
and types derived from
xs:QName
and
xs:NOTATION
. See
5.3 Constructor Functions for
xs:QName and xs:NOTATION
The following constructor functions for the built-in types are
supported:
xs:string
$arg
as
xs:anyAtomicType?
as
xs:string?
xs:boolean
$arg
as
xs:anyAtomicType?
as
xs:boolean?
xs:decimal
$arg
as
xs:anyAtomicType?
as
xs:decimal?
xs:float
$arg
as
xs:anyAtomicType?
as
xs:float?
Implementations
may
return negative zero for
xs:float("-0.0E0")
[XML Schema
Part 2: Datatypes Second Edition]
does not distinguish between
the values positive zero and negative zero.
xs:double
$arg
as
xs:anyAtomicType?
as
xs:double?
Implementations
may
return negative zero for
xs:double("-0.0E0").
[XML
Schema Part 2: Datatypes Second Edition]
does not distinguish
between the values positive zero and negative zero.
xs:duration
$arg
as
xs:anyAtomicType?
as
xs:duration?
xs:dateTime
$arg
as
xs:anyAtomicType?
as
xs:dateTime?
xs:time
$arg
as
xs:anyAtomicType?
as
xs:time?
xs:date
$arg
as
xs:anyAtomicType?
as
xs:date?
xs:gYearMonth
$arg
as
xs:anyAtomicType?
as
xs:gYearMonth?
xs:gYear
$arg
as
xs:anyAtomicType?
as
xs:gYear?
xs:gMonthDay
$arg
as
xs:anyAtomicType?
as
xs:gMonthDay?
xs:gDay
$arg
as
xs:anyAtomicType?
as
xs:gDay?
xs:gMonth
$arg
as
xs:anyAtomicType?
as
xs:gMonth?
xs:hexBinary
$arg
as
xs:anyAtomicType?
as
xs:hexBinary?
xs:base64Binary
$arg
as
xs:anyAtomicType?
as
xs:base64Binary?
xs:anyURI
$arg
as
xs:anyAtomicType?
as
xs:anyURI?
xs:QName
$arg
as
xs:anyAtomicType
as
xs:QName?
See
5.3 Constructor
Functions for xs:QName and xs:NOTATION
for special
rules.
xs:normalizedString
$arg
as
xs:anyAtomicType?
as
xs:normalizedString?
xs:token
$arg
as
xs:anyAtomicType?
as
xs:token?
xs:language
$arg
as
xs:anyAtomicType?
as
xs:language?
xs:NMTOKEN
$arg
as
xs:anyAtomicType?
as
xs:NMTOKEN?
xs:Name
$arg
as
xs:anyAtomicType?
as
xs:Name?
xs:NCName
$arg
as
xs:anyAtomicType?
as
xs:NCName?
xs:ID
$arg
as
xs:anyAtomicType?
as
xs:ID?
xs:IDREF
$arg
as
xs:anyAtomicType?
as
xs:IDREF?
xs:ENTITY
$arg
as
xs:anyAtomicType?
as
xs:ENTITY?
See
17.4.1 Casting to
xs:ENTITY
for rules related to constructing values of type
xs:ENTITY
and types derived from it.
xs:integer
$arg
as
xs:anyAtomicType?
as
xs:integer?
xs:nonPositiveInteger
$arg
as
xs:anyAtomicType?
as
xs:nonPositiveInteger?
xs:negativeInteger
$arg
as
xs:anyAtomicType?
as
xs:negativeInteger?
xs:long
$arg
as
xs:anyAtomicType?
as
xs:long?
xs:int
$arg
as
xs:anyAtomicType?
as
xs:int?
xs:short
$arg
as
xs:anyAtomicType?
as
xs:short?
xs:byte
$arg
as
xs:anyAtomicType?
as
xs:byte?
xs:nonNegativeInteger
$arg
as
xs:anyAtomicType?
as
xs:nonNegativeInteger?
xs:unsignedLong
$arg
as
xs:anyAtomicType?
as
xs:unsignedLong?
xs:unsignedInt
$arg
as
xs:anyAtomicType?
as
xs:unsignedInt?
xs:unsignedShort
$arg
as
xs:anyAtomicType?
as
xs:unsignedShort?
xs:unsignedByte
$arg
as
xs:anyAtomicType?
as
xs:unsignedByte?
xs:positiveInteger
$arg
as
xs:anyAtomicType?
as
xs:positiveInteger?
xs:yearMonthDuration
$arg
as
xs:anyAtomicType?
as
xs:yearMonthDuration?
xs:dayTimeDuration
$arg
as
xs:anyAtomicType?
as
xs:dayTimeDuration?
xs:untypedAtomic
$arg
as
xs:anyAtomicType?
as
xs: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 result is the empty
sequence if either of the parameters is the empty sequence.
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.2.1 Examples
fn:dateTime(xs:date("1999-12-31"),
xs:time("12:00:00"))
returns
xs:dateTime("1999-12-31T12:00:00").
fn:dateTime(xs:date("1999-12-31"),
xs:time("24:00:00"))
returns
xs:dateTime("1999-12-31T00:00:00")
because
"24:00:00"
is an alternate lexical form for
"00:00:00".
5.3 Constructor Functions for
xs:QName and xs:NOTATION
Special rules apply to constructor functions for the types
xs:QName
and
xs:NOTATION
, for two
reasons:
The lexical representation of these types uses namespace
prefixes, whose meaning is context-dependent.
Values cannot belong directly to the type
xs:NOTATION
, only to its subtypes.
These constraints result in the following restrictions:
Conversion from an
xs:string
to a value of type
xs:QName
, a type derived from
xs:QName
or
a type derived from
xs:NOTATION
is permitted only if
the
xs:string
is written as a string literal. This
applies whether the conversion is expressed using a constructor
function or using the "cast as" syntax. Such a conversion can be
regarded as a pseudo-function, which is always evaluated
statically. It is also permitted for these constructors and casts
to take a dynamically-supplied argument in the normal manner, but
as the casting table (see
17.1 Casting from
primitive types to primitive types
) indicates, the only
arguments that are supported in this case are values of type
xs:QName
or
xs:NOTATION
respectively.
There is no constructor function for
xs:NOTATION
Constructors are defined, however, for
xs:QName
, for
types derived from
xs:QName
, and for types derived
from
xs:NOTATION
When converting from an
xs:string
, the prefix
within the lexical
xs:QName
supplied as the argument
is resolved to a namespace URI using the statically known
namespaces from the static context. If the lexical
xs:QName
has no prefix, the namespace URI of the
resulting expanded-QName is the default element/type namespace from
the static context. Components of the static context are discussed
in
Section
2.1.1 Static Context
XP
. A static
error is raised [
err:FONS0004
] if the prefix is not bound in the
static context. As described in
Section 2.1
Terminology
DM
, the supplied prefix is
retained as part of the expanded-QName value.
5.4 Constructor
Functions for User-Defined Types
For every atomic type in the static context (See
Section 2.1.1 Static
Context
XP
) 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
Special rules apply to constructor functions for types derived
from
xs:QName
and
xs:NOTATION
. See
5.3 Constructor Functions
for xs:QName and xs:NOTATION
Consider a situation where the static context contains a type
called
hatSize
defined in a schema whose target
namespace is bound to the prefix
my
. In such a case
the constructor function:
my:hatSize
$arg
as
xs: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. For example, if the user-defined
type
apple
is derived from
xs:integer
but
is not in a namespace, an instance of this type can be constructed
as follows using a cast expression (this requires that the default
element/type namespace is no namespace):
17 cast as apple
The following shows the use of the constructor function:
declare default function namespace ""; apple(17)
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 indentation.
xs:decimal
xs:integer
xs:float
xs:double
They also apply to types derived by restriction from the above
types.
Note:
This specification uses
[IEEE 754-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
[XML Path Language (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 an
xs:decimal
if called with two
xs:integer
operands and
op:numeric-integer-divide
which always returns an
xs:integer
If the two operands are not of the same type,
subtype
substitution
and
numeric type promotion
are used to
obtain two operands of the same type.
Section B.1 Type
Promotion
XP
and
Section B.2 Operator
Mapping
XP
describe the semantics of
these operations in detail.
The result type of operations depends on their argument
datatypes and is defined in the following table:
Operator
Returns
op:operation(xs:integer, xs:integer)
xs:integer
(except for
op:numeric-divide(integer,
integer)
, which returns
xs:decimal
op:operation(xs:decimal, xs:decimal)
xs:decimal
op:operation(xs:float, xs:float)
xs:float
op:operation(xs:double, xs:double)
xs:double
op:operation(xs:integer)
xs:integer
op:operation(xs:decimal)
xs:decimal
op:operation(xs:float)
xs:float
op:operation(xs:double)
xs:double
These rules define any operation on any pair of arithmetic
types. Consider the following example:
op:operation(xs:int, xs:double) => op:operation(xs:double, xs:double)
For this operation,
xs:int
must be converted to
xs:double
. This can be done, since by the rules above:
xs:int
can be substituted for
xs:integer
xs:integer
can be substituted for
xs:decimal
xs:decimal
can be promoted to
xs:double
. As far as possible, the promotions should
be done in a single step. Specifically, when an
xs:decimal
is promoted to an
xs:double
it should not be converted to an
xs:float
and then to
xs:double
, as this risks loss of precision.
As another example, a user may define
height
as a
derived type of
xs:integer
with a minimum value of 20
and a maximum value of 100. He may then derive
fenceHeight
using an enumeration to restrict the
permitted set of values to, say, 36, 48 and 60.
op:operation(fenceHeight, xs:integer) => op:operation(xs:integer, xs:integer)
fenceHeight
can be substituted for its base type
height
and
height
can be substituted for
its base type
xs:integer
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:
They
may
choose to
always raise an error [
err:FOAR0002
].
They
may
provide an
implementation-defined
mechanism that allows users to choose between
raising an error and returning a result that is modulo the largest
representable integer value. See
[ISO
10967]
The functions
op:numeric-add
op:numeric-subtract
op:numeric-multiply
op:numeric-divide
op:numeric-integer-divide
and
op:numeric-mod
are
each defined for pairs of numeric operands, each of which has the
same type:
xs:integer
xs:decimal
xs:float
, or
xs:double
. The functions
op:numeric-unary-plus
and
op:numeric-unary-minus
are defined for a single operand whose type is one of those same
numeric types.
For
xs:float
and
xs:double
arguments,
if either argument is
NaN
, the result is
NaN
For
xs:decimal
values the number of digits of
precision returned by the numeric operators is
implementation-defined
. If the number of digits in the result exceeds
the number of digits that the implementation supports, the result
is truncated or rounded in an
implementation-defined
manner.
6.2.1
op:numeric-add
op:numeric-add
$arg1
as
numeric
$arg2
as
numeric
as
numeric
Summary: Backs up the "+" operator and returns the arithmetic
sum of its operands: (
$arg1 + $arg2
).
Note:
For
xs:float
or
xs:double
values, if
one of the operands is a zero or a finite number and the other is
INF
or
-INF
INF
or
-INF
is returned. If both operands are
INF
INF
is returned. If both operands
are
-INF
-INF
is returned. If one of the
operands is
INF
and the other is
-INF
NaN
is returned.
6.2.2 op:numeric-subtract
op:numeric-subtract
$arg1
as
numeric
$arg2
as
numeric
as
numeric
Summary: Backs up the "-" operator and returns the arithmetic
difference of its operands: (
$arg1 - $arg2
).
Note:
For
xs:float
or
xs:double
values, if
one of the operands is a zero or a finite number and the other is
INF
or
-INF
, an infinity of the
appropriate sign is returned. If both operands are
INF
or
-INF
NaN
is returned. If one of the
operands is
INF
and the other is
-INF
, an
infinity of the appropriate sign is returned.
6.2.3 op:numeric-multiply
op:numeric-multiply
$arg1
as
numeric
$arg2
as
numeric
as
numeric
Summary: Backs up the "*" operator and returns the arithmetic
product of its operands: (
$arg1 * $arg2
).
Note:
For
xs:float
or
xs:double
values, if
one of the operands is a zero and the other is an infinity,
NaN
is returned. If one of the operands is a non-zero
number and the other is an infinity, an infinity with the
appropriate sign is returned.
6.2.4 op:numeric-divide
op:numeric-divide
$arg1
as
numeric
$arg2
as
numeric
as
numeric
Summary: Backs up the "div" operator and returns the arithmetic
quotient of its operands: (
$arg1 div $arg2
).
As a special case, if the types of both
$arg1
and
$arg2
are
xs:integer
, then the return
type is
xs:decimal
Notes:
For
xs:decimal
and
xs:integer
operands, if the divisor is (positive or negative) zero, an error
is raised [
err:FOAR0001
]. For
xs:float
and
xs:double
operands, floating point division is
performed as specified in
[IEEE
754-1985]
For
xs:float
or
xs:double
values, a
positive number divided by positive zero returns
INF
A negative number divided by positive zero returns
-INF
. Division by negative zero returns
-INF
and
INF
, respectively. Positive or
negative zero divided by positive or negative zero returns
NaN
. Also,
INF
or
-INF
divided by
INF
or
-INF
returns
NaN
6.2.5
op:numeric-integer-divide
op:numeric-integer-divide
$arg1
as
numeric
$arg2
as
numeric
as
xs:integer
Summary: This function backs up the "idiv" operator by
performing an integer division.
If
$arg2
is (positive or negative) zero, then an
error is raised [
err:FOAR0001
]. If either operand is
NaN
or if
$arg1
is
INF
or
-INF
then an error is raised [
err:FOAR0002
]. If
$arg2
is
INF
or
-INF
(and
$arg1
is
not) then the result is zero.
Otherwise, subject to limits of precision and overflow/underflow
conditions, the result is the largest (furthest from zero)
xs:integer
value
$N
such that
fn:abs($N * $arg2) le fn:abs($arg1) and
fn:compare($N * $arg2, 0) eq fn:compare($arg1, 0)
Note:
The second term in this condition ensures that the result has
the correct sign.
The implementation may adopt a different algorithm provided that
it is equivalent to this formulation in all cases where
implementation-dependent
or
implementation-defined
behavior does not affect the outcome, for
example, the implementation-defined precision of the result of
xs:decimal
division.
Note:
Except in situations involving errors, loss of precision, or
overflow/underflow, the result of
$a idiv $b
is the
same as
($a div $b) cast as xs:integer
Note:
The semantics of this function are different from integer
division as defined in programming languages such as Java and
C++.
6.2.5.1 Examples
op:numeric-integer-divide(10,3)
returns
op:numeric-integer-divide(3,-2)
returns
-1
op:numeric-integer-divide(-3,2)
returns
-1
op:numeric-integer-divide(-3,-2)
returns
op:numeric-integer-divide(9.0,3)
returns
op:numeric-integer-divide(-3.5,3)
returns
-1
op:numeric-integer-divide(3.0,4)
returns
op:numeric-integer-divide(3.1E1,6)
returns
op:numeric-integer-divide(3.1E1,7)
returns
6.2.6
op:numeric-mod
op:numeric-mod
$arg1
as
numeric
$arg2
as
numeric
as
numeric
Summary: Backs up the "mod" operator. Informally, this function
returns the remainder resulting from dividing
$arg1
the dividend, by
$arg2
, the divisor. The operation
a mod b
for operands that are
xs:integer
or
xs:decimal
, or types derived from them, produces a
result such that
(a idiv b)*b+(a mod b)
is equal to
and the magnitude of the result is always less than
the magnitude of
. This identity holds even in the
special case that the dividend is the negative integer of largest
possible magnitude for its type and the divisor is -1 (the
remainder is 0). It follows from this rule that the sign of the
result is the sign of the dividend.
For
xs:integer
and
xs:decimal
operands, if
$arg2
is zero, then an error is raised
err:FOAR0001
].
For
xs:float
and
xs:double
operands
the following rules apply:
If either operand is
NaN
, the result is
NaN
If the dividend is positive or negative infinity, or the divisor
is positive or negative zero (0), or both, the result is
NaN
If the dividend is finite and the divisor is an infinity, the
result equals the dividend.
If the dividend is positive or negative zero and the divisor is
finite, the result is the same as the dividend.
In the remaining cases, where neither positive or negative
infinity, nor positive or negative zero, nor
NaN
is
involved, the result obeys
(a idiv b)*b+(a mod b)
. Division is truncating division, analogous to
integer division, not
[IEEE 754-1985]
rounding division i.e. additional digits are truncated, not rounded
to the required precision.
6.2.6.1 Examples
op:numeric-mod(10,3)
returns
op:numeric-mod(6,-2)
returns
op:numeric-mod(4.5,1.2)
returns
0.9
op:numeric-mod(1.23E2, 0.6E1)
returns
3.0E0
6.2.7 op:numeric-unary-plus
op:numeric-unary-plus
$arg
as
numeric
as
numeric
Summary: Backs up the unary "+" operator and returns its operand
with the sign unchanged: (+
$arg
).
The returned value is equal to
$arg
, and is an
instance of
xs:integer
xs:decimal
xs:double
, or
xs:float
depending on the
type of
$arg
6.2.8 op:numeric-unary-minus
op:numeric-unary-minus
$arg
as
numeric
as
numeric
Summary: Backs up the unary "-" operator and returns its operand
with the sign reversed: (-
$arg
).
The returned value is an instance of
xs:integer
xs:decimal
xs:double
, or
xs:float
depending on the type of
$arg
For
xs:integer
and
xs:decimal
arguments,
and
0.0
return
and
0.0
, respectively. For
xs:float
and
xs:double
arguments,
NaN
returns
NaN
0.0E0
returns
-0.0E0
and vice versa.
INF
returns
-INF
-INF
returns
INF
6.3 Comparison
Operators on Numeric Values
This specification defines the following comparison operators on
numeric values. Comparisons take two arguments of the same type. If
the arguments are of different types, one argument is promoted to
the type of the other as described above in
6.2 Operators on Numeric Values
. Each
comparison operator returns a boolean value. If either, or both,
operands are
NaN
false
is returned.
Operator
Meaning
op:numeric-equal
Equality comparison
op:numeric-less-than
Less-than comparison
op:numeric-greater-than
Greater-than comparison
6.3.1
op:numeric-equal
op:numeric-equal
$arg1
as
numeric
$arg2
as
numeric
as
xs:boolean
Summary: Returns true if and only if the value of
$arg1
is equal to the value of
$arg2
. For
xs:float
and
xs:double
values, positive
zero and negative zero compare equal.
INF
equals
INF
and
-INF
equals
-INF
NaN
does not equal itself.
This function backs up the "eq", "ne", "le" and "ge" operators
on numeric values.
6.3.2 op:numeric-less-than
op:numeric-less-than
$arg1
as
numeric
$arg2
as
numeric
as
xs:boolean
Summary: Returns
true
if and only if
$arg1
is less than
$arg2
. For
xs:float
and
xs:double
values, positive
infinity is greater than all other non-
NaN
values;
negative infinity is less than all other non-
NaN
values. If
$arg1
or
$arg2
is
NaN
, the function returns
false
This function backs up the "lt" and "le" operators on numeric
values.
6.3.3 op:numeric-greater-than
op:numeric-greater-than
$arg1
as
numeric
$arg2
as
numeric
as
xs:boolean
Summary: Returns
true
if and only if
$arg1
is greater than
$arg2
. For
xs:float
and
xs:double
values, positive
infinity is greater than all other non-
NaN
values;
negative infinity is less than all other non-
NaN
values. If
$arg1
or
$arg2
is
NaN
, the function returns
false
This function backs up the "gt" and "ge" operators on numeric
values.
6.4 Functions on Numeric Values
The following functions are defined on numeric types. Each
function returns a value of the same type as the type of its
argument.
If the argument is the empty sequence, the empty sequence is
returned.
For
xs:float
and
xs:double
arguments,
if the argument is "NaN", "NaN" is returned.
Except for
fn:abs()
, for
xs:float
and
xs:double
arguments, if the
argument is positive or negative infinity, positive or negative
infinity is returned.
Function
Meaning
fn:abs
Returns the absolute value of the argument.
fn:ceiling
Returns the smallest number with no fractional part that is
greater than or equal to the argument.
fn:floor
Returns the largest number with no fractional part that is less
than or equal to the argument.
fn:round
Rounds to the nearest number with no fractional part.
fn:round-half-to-even
Takes a number and a precision and returns a number rounded to
the given precision. If the fractional part is exactly half, the
result is the number whose least significant digit is even.
6.4.1 fn:abs
fn:abs
$arg
as
numeric?
as
numeric?
Summary: Returns the absolute value of
$arg
. If
$arg
is negative returns
-$arg
otherwise
returns
$arg
. If type of
$arg
is one of
the four numeric types
xs:float
xs:double
xs:decimal
or
xs:integer
the type of the result is the same as the
type of
$arg
. If the type of
$arg
is a
type derived from one of the numeric types, the result is an
instance of the base numeric type.
For
xs:float
and
xs:double
arguments,
if the argument is positive zero or negative zero, then positive
zero is returned. If the argument is positive or negative infinity,
positive infinity is returned.
For detailed type semantics, see
Section 7.2.3 The fn:abs, fn:ceiling, fn:floor, fn:round, and
fn:round-half-to-even functions
FS
6.4.1.1
Examples
fn:abs(10.5)
returns
10.5
fn:abs(-10.5)
returns
10.5
6.4.2
fn:ceiling
fn:ceiling
$arg
as
numeric?
as
numeric?
Summary: Returns the smallest (closest to negative infinity)
number with no fractional part that is not less than the value of
$arg
. If type of
$arg
is one of the four
numeric types
xs:float
xs:double
xs:decimal
or
xs:integer
the type of the
result is the same as the type of
$arg
. If the type of
$arg
is a type derived from one of the numeric types,
the result is an instance of the base numeric type.
For
xs:float
and
xs:double
arguments,
if the argument is positive zero, then positive zero is returned.
If the argument is negative zero, then negative zero is returned.
If the argument is less than zero and greater than -1, negative
zero is returned.
For detailed type semantics, see
Section 7.2.3 The fn:abs, fn:ceiling, fn:floor, fn:round, and
fn:round-half-to-even functions
FS
6.4.2.1 Examples
fn:ceiling(10.5)
returns
11
fn:ceiling(-10.5)
returns
-10
6.4.3 fn:floor
fn:floor
$arg
as
numeric?
as
numeric?
Summary: Returns the largest (closest to positive infinity)
number with no fractional part that is not greater than the value
of
$arg
. If type of
$arg
is one of the
four numeric types
xs:float
xs:double
xs:decimal
or
xs:integer
the type of the
result is the same as the type of
$arg
. If the type of
$arg
is a type derived from one of the numeric types,
the result is an instance of the base numeric type.
For
float
and
double
arguments, if the
argument is positive zero, then positive zero is returned. If the
argument is negative zero, then negative zero is returned.
For detailed type semantics, see
Section 7.2.3 The fn:abs, fn:ceiling, fn:floor, fn:round, and
fn:round-half-to-even functions
FS
6.4.3.1 Examples
fn:floor(10.5)
returns
10
fn:floor(-10.5)
returns
-11
6.4.4 fn:round
fn:round
$arg
as
numeric?
as
numeric?
Summary: Returns the number with no fractional part that is
closest to the argument. If there are two such numbers, then the
one that is closest to positive infinity is returned. If type of
$arg
is one of the four numeric types
xs:float
xs:double
xs:decimal
or
xs:integer
the type of the
result is the same as the type of
$arg
. If the type of
$arg
is a type derived from one of the numeric types,
the result is an instance of the base numeric type.
For
xs:float
and
xs:double
arguments,
if the argument is positive infinity, then positive infinity is
returned. If the argument is negative infinity, then negative
infinity is returned. If the argument is positive zero, then
positive zero is returned. If the argument is negative zero, then
negative zero is returned. If the argument is less than zero, but
greater than or equal to -0.5, then negative zero is returned. In
the cases where positive zero or negative zero is returned,
negative zero or positive zero may be returned as
[XML Schema Part 2: Datatypes Second Edition]
does not distinguish between the values positive zero and negative
zero.
For the last two cases, note that the result is not the same as
fn:floor(x+0.5)
For detailed type semantics, see
Section 7.2.3 The fn:abs, fn:ceiling, fn:floor, fn:round, and
fn:round-half-to-even functions
FS
6.4.4.1 Examples
fn:round(2.5)
returns
3.
fn:round(2.4999)
returns
fn:round(-2.5)
returns
-2
(not the
possible alternative,
-3
).
6.4.5 fn:round-half-to-even
fn:round-half-to-even
$arg
as
numeric?
as
numeric?
fn:round-half-to-even
$arg
as
numeric?
$precision
as
xs:integer
as
numeric?
Summary: The value returned is the nearest (that is, numerically
closest) value to
$arg
that is a multiple of ten to
the power of minus
$precision
. If two such values are
equally near (e.g. if the fractional part in
$arg
is
exactly .500...), the function returns the one whose least
significant digit is even.
If the type of
$arg
is one of the four numeric
types
xs:float
xs:double
xs:decimal
or
xs:integer
the type of the
result is the same as the type of
$arg
. If the type of
$arg
is a type derived from one of the numeric types,
the result is an instance of the base numeric type.
The first signature of this function produces the same result as
the second signature with
$precision=0
For arguments of type
xs:float
and
xs:double
, if the argument is
NaN
positive or negative zero, or positive or negative infinity, then
the result is the same as the argument. In all other cases, the
argument is cast to
xs:decimal
, the function is
applied to this
xs:decimal
value, and the resulting
xs:decimal
is cast back to
xs:float
or
xs:double
as appropriate to form the function result.
If the resulting
xs:decimal
value is zero, then
positive or negative zero is returned according to the sign of the
original argument.
Note that the process of casting to
xs:decimal
may
result in an error [
err:FOCA0001
].
If
$arg
is of type
xs:float
or
xs:double
, rounding occurs on the value of the
mantissa computed with exponent = 0.
For detailed type semantics, see
Section 7.2.3 The fn:abs, fn:ceiling, fn:floor, fn:round, and
fn:round-half-to-even functions
FS
Note:
This function is typically used in financial applications where
the argument is of type
xs:decimal
. For arguments of
type
xs:float
and
xs:double
the results
may be counterintuitive. For example, consider
round-half-to-even(xs:float(150.0150), 2)
An implementation that supports 18 digits for
xs:decimal
will convert the argument to the
xs:decimal
150.014999389... which will then be rounded
to the
xs:decimal
150.01 which will be converted back
to the
xs:float
whose exact value is 150.0099945068...
whereas
round-half-to-even(xs:decimal(150.0150), 2)
will result in the
xs:decimal
whose exact value is
150.02.
6.4.5.1 Examples
fn:round-half-to-even(0.5)
returns
fn:round-half-to-even(1.5)
returns
fn:round-half-to-even(2.5)
returns
fn:round-half-to-even(3.567812E+3, 2)
returns
3567.81E0
fn:round-half-to-even(4.7564E-3, 2)
returns
0.0E0
fn:round-half-to-even(35612.25, -2)
returns
35600
Functions on Strings
This section discusses functions and operators on the
[XML Schema Part 2: Datatypes Second Edition]
xs:string
datatype and the datatypes derived from
it.
7.1 String
Types
The operators described in this section are defined on the
following types. Each type whose name is indented is derived from
the type whose name appears nearest above with one less level of
indentation.
xs:string
xs:normalizedString
xs:token
xs:language
xs:NMTOKEN
xs:Name
xs:NCName
xs:ID
xs:IDREF
xs:ENTITY
They also apply to user-defined types derived by restriction
from the above types.
It is
implementation-defined
which version of
[The
Unicode Standard]
is supported, but it is recommended that the
most recent version of Unicode be used.
Unless explicitly stated, the
xs:string
values
returned by the functions in this document are not normalized in
the sense of
[Character Model for the World Wide
Web 1.0: Fundamentals]
Notes:
This document uses the term "code point", sometimes spelt
"codepoint" (also known as "character number" or "code position")
to mean a non-negative integer that represents a character in some
encoding. See
[Character Model for the World
Wide Web 1.0: Fundamentals]
. The use of the word "character" in
this document is in the sense of production [2] of
[Extensible Markup Language (XML) 1.0 Recommendation
(Third Edition)]
[The Unicode
Standard]
, defines code points that range from #x0000 to
#x10FFFF inclusive and may include code points that have not yet
been assigned to characters.
In functions that involve character counting such as
fn:substring
fn:string-length
and
fn:translate
, what is
counted is the number of XML characters in the string (or
equivalently, the number of Unicode code points). Some
implementations may represent a code point above xFFFF using two
16-bit values known as a surrogate. A surrogate counts as one
character, not two.
7.2 Functions to Assemble
and Disassemble Strings
Function
Meaning
fn:codepoints-to-string
Creates an
xs:string
from a sequence of Unicode
code points.
fn:string-to-codepoints
Returns the sequence of Unicode code points that constitute an
xs:string
7.2.1 fn:codepoints-to-string
fn:codepoints-to-string
$arg
as
xs:integer*
as
xs:string
Summary: Creates an
xs:string
from a sequence of
[The Unicode Standard]
code points. Returns
the zero-length string if
$arg
is the empty sequence.
If any of the code points in
$arg
is not a legal XML
character, an error is raised [
err:FOCH0001
].
7.2.1.1 Examples
fn:codepoints-to-string((2309, 2358, 2378, 2325))
returns "अशॊक"
7.2.2 fn:string-to-codepoints
fn:string-to-codepoints
$arg
as
xs:string?
as
xs:integer*
Summary: Returns the sequence of
[The
Unicode Standard]
code points that constitute an
xs:string
. If
$arg
is a zero-length
string or the empty sequence, the empty sequence is returned.
7.2.2.1 Examples
fn:string-to-codepoints("Thérèse")
returns the
sequence (84, 104, 233, 114, 232, 115, 101)
7.3 Equality
and Comparison of Strings
7.3.1 Collations
A collation is a specification of the manner in which character
strings are compared and, by extension, ordered. When values whose
type is
xs:string
or a type derived from
xs:string
are compared (or, equivalently, sorted), the
comparisons are inherently performed according to some collation
(even if that collation is defined entirely on code point values).
The
[Character Model for the World Wide Web 1.0:
Fundamentals]
observes that some applications may require
different comparison and ordering behaviors than other
applications. Similarly, some users having particular linguistic
expectations may require different behaviors than other users.
Consequently, the collation must be taken into account when
comparing strings in any context. Several functions in this and the
following section make use of a collation.
Collations can indicate that two different code points are, in
fact, equal for comparison purposes (e.g., "v" and "w" are
considered equivalent in Swedish). Strings can be compared
codepoint-by-codepoint or in a linguistically appropriate manner,
as defined by the collation.
Some collations, especially those based on the
[Unicode Collation Algorithm]
can be
"tailored" for various purposes. This document does not discuss
such tailoring, nor does it provide a mechanism to perform
tailoring. Instead, it assumes that the collation argument to the
various functions below is a tailored and named collation. A
specific collation with a distinguished name,
provides the ability to compare strings based on code point values.
Every implementation of XQuery/XPath must support the collation
based on code point values.
In the ideal case, a collation should treat two strings as equal
if the two strings are identical after Unicode normalization. Thus,
the
[Character Model for the World
Wide Web 1.0: Normalization]
recommends that all strings be
subjected to early Unicode normalization and some collations will
raise runtime errors if they encounter strings that are not
properly normalized. However, it is not possible to guarantee that
all strings in all XML documents are, in fact, normalized, or that
they are normalized in the same manner. In order to maximize
interoperability of operations on XML documents in general, there
may be collations that operate on unnormalized strings and other
collations that implicitly normalize strings before comparing them.
Applications may choose the kind of collation best suited for their
needs. Note that collations based on the Unicode collation
algorithm implicitly normalize strings before comparison and
produce equivalent results regardless of a string's
normalization.
This specification assumes that collations are named and that
the collation name may be provided as an argument to string
functions. Functions that allow specification of a collation do so
with an argument whose type is
xs:string
but whose
lexical form must conform to an
xs:anyURI
. If the
collation is specified using a relative URI, it is assumed to be
relative to the value of the base-uri property in the static
context. This specification also defines the manner in which a
default collation is determined if the collation argument is not
specified in invocations of functions that use a collation but
allow it to be omitted.
This specification does not define whether or not the collation
URI is dereferenced. The collation URI may be an abstract
identifier, or it may refer to an actual resource describing the
collation. If it refers to a resource, this specification does not
define the nature of that resource. One possible candidate is that
the resource is a locale description expressed using the Locale
Data Markup Language: see
[Locale Data Markup
Language]
Functions such as
fn:compare
and
fn:max
that compare
xs:string
values use a single collation URI to
identify all aspects of the collation rules. This means that any
parameters such as the strength of the collation must be specified
as part of the collation URI. For example, suppose there is a
collation "
that refers to a French collation that compares on the basis of
base characters. Collations that use the same basic rules, but with
higher strengths, for example, base characters and accents, or base
characters, accents and case, would need to be given different
names, say "
" and "
".
Note that some specifications use the term collation to refer to an
algorithm that can be parameterized, but in this specification,
each possible parameterization is considered to be a distinct
collation.
The XQuery/XPath static context includes a provision for a
default collation that can be used for string comparisons and
ordering operations. See the description of the static context in
Section
2.1.1 Static Context
XP
. If the
default collation is not specified by the user or the system, the
default collation is the Unicode code point collation
).
The decision of which collation to use for a given comparison or
ordering function is determined by the following algorithm:
If the function specifies an explicit collation, CollationA
(e.g., if the optional collation argument is specified in an
invocation of the
fn:compare()
function), then:
If CollationA is supported by the implementation, then
CollationA is used.
Otherwise, an error is raised [
err:FOCH0002
].
If no collation is explicitly specified for the function and the
default collation in the XQuery/XPath static context is CollationB,
then:
If CollationB is supported by the implementation, then
CollationB is used.
Otherwise, an error is raised [
err:FOCH0002
].
Note:
XML allows elements to specify the
xml:lang
attribute to indicate the language associated with the content of
such an element. This specification does not use
xml:lang
to identify the default collation because
using
xml:lang
does not produce desired effects when
the two strings to be compared have different
xml:lang
values or when a string is multilingual.
Function
Meaning
fn:compare
Returns -1, 0, or 1, depending on whether the value of the
first argument is respectively less than, equal to, or greater than
the value of the second argument, according to the rules of the
collation that is used.
fn:codepoint-equal
Returns
true
if the two arguments are equal using
the Unicode code point collation.
7.3.2
fn:compare
fn:compare
$comparand1
as
xs:string?
$comparand2
as
xs:string?
as
xs:integer?
fn:compare
$comparand1
as
xs:string?
$comparand2
as
xs:string?
$collation
as
xs:string
as
xs:integer?
Summary: Returns -1, 0, or 1, depending on whether the value of
the
$comparand1
is respectively less than, equal to,
or greater than the value of
$comparand2
, according to
the rules of the collation that is used.
The collation used by the invocation of this function is
determined according to the rules in
7.3.1
Collations
If either argument is the empty sequence, the result is the
empty sequence.
This function, invoked with the first signature, backs up the
"eq", "ne", "gt", "lt", "le" and "ge" operators on string
values.
7.3.2.1 Examples
fn:compare('abc', 'abc')
returns 0.
fn:compare('Strasse', 'Straße')
returns 0 if and
only if the default collation includes provisions that equate "ss"
and the (German) character "ß" ("sharp-s"). (Otherwise, the
returned value depends on the semantics of the default
collation.)
fn:compare('Strasse', 'Straße', 'deutsch')
returns
0 if the collation identified by the relative URI constructed from
the
string
value "deutsch" includes provisions that
equate "ss" and the (German) character "ß" ("sharp-s"). (Otherwise,
the returned value depends on the semantics of that collation.)
fn:compare('Strassen', 'Straße')
returns 1 if the
default collation includes provisions that treat differences
between "ss" and the (German) character "ß" ("sharp-s") with less
strength than the differences between the base characters, such as
the final "n".
7.3.3 fn:codepoint-equal
fn:codepoint-equal
$comparand1
as
xs:string?
$comparand2
as
xs:string?
as
xs:boolean?
Summary: Returns
true
or
false
depending on whether the value of
$comparand1
is equal
to the value of
$comparand2
, according to the Unicode
code point collation
).
If either argument is the empty sequence, the result is the
empty sequence.
Note:
This function allows
xs:anyURI
values to be
compared without having to specify the Unicode code point
collation.
7.4 Functions on String Values
The following functions are defined on values of type
xs:string
and types derived from it.
Function
Meaning
fn:concat
Concatenates two or more
xs:anyAtomicType
arguments cast to
xs:string
fn:string-join
Returns the
xs:string
produced by concatenating a
sequence of
xs:string
s using an optional
separator.
fn:substring
Returns the
xs:string
located at a specified place
within an argument
xs:string
fn:string-length
Returns the length of the argument.
fn:normalize-space
Returns the whitespace-normalized value of the argument.
fn:normalize-unicode
Returns the normalized value of the first argument in the
normalization form specified by the second argument.
fn:upper-case
Returns the upper-cased value of the argument.
fn:lower-case
Returns the lower-cased value of the argument.
fn:translate
Returns the first
xs:string
argument with
occurrences of characters contained in the second argument replaced
by the character at the corresponding position in the third
argument.
fn:encode-for-uri
Returns the
xs:string
argument with certain
characters escaped to enable the resulting string to be used as a
path segment in a URI.
fn:iri-to-uri
Returns the
xs:string
argument with certain
characters escaped to enable the resulting string to be used as
(part of) a URI.
fn:escape-html-uri
Returns the
xs:string
argument with certain
characters escaped in the manner that html user agents handle
attribute values that expect URIs.
Notes:
When the above operators and functions are applied to datatypes
derived from
xs:string
, they are guaranteed to return
legal
xs:string
s, but they might not return a legal
value for the particular subtype to which they were applied.
The strings returned by
fn:concat
and
fn:string-join
are not
guaranteed to be normalized. But see note in
fn:concat
7.4.1 fn:concat
fn:concat
$arg1
as
xs:anyAtomicType?
$arg2
as
xs:anyAtomicType?
...
as
xs:string
Summary: Accepts two or more
xs:anyAtomicType
arguments and casts them to
xs:string
. Returns the
xs:string
that is the concatenation of the values of
its arguments after conversion. If any of the arguments is the
empty sequence, the argument is treated as the zero-length
string.
The
fn:concat
function is specified to allow two or
more arguments, which are concatenated together. This is the only
function specified in this document that allows a variable number
of arguments. This capability is retained for compatibility with
[XML Path Language (XPath) Version 1.0]
Note:
As mentioned in
7.1 String
Types
Unicode normalization is not automatically applied to
the result of
fn:concat
. If a normalized result is
required,
fn:normalize-unicode
can
be applied to the
xs:string
returned by
fn:concat
. The following XQuery:
let $v1 := "I plan to go to Mu"
let $v2 := "?nchen in September"
return concat($v1, $v2)
where the "?" represents either the actual Unicode character
COMBINING DIARESIS (Unicode codepoint U+0308) or "̈",
will return:
"I plan to go to Mu?nchen in September"
where the "?" represents either the actual Unicode character
COMBINING DIARESIS (Unicode codepoint U+0308) or "̈". It
is worth noting that the returned value is not normalized in NFC;
however, it is normalized in NFD. .
However, the following XQuery:
let $v1 := "I plan to go to Mu"
let $v2 := "?nchen in September"
return normalize-unicode(concat($v1, $v2))
where the "?" represents either the actual Unicode character
COMBINING DIARESIS (Unicode codepoint U+0308) or "̈",
will return:
"I plan to go to München in September"
This returned result is normalized in NFC.
7.4.1.1 Examples
fn:concat('un', 'grateful')
returns
"ungrateful"
fn:concat('Thy ', (), 'old ', "groans", "", ' ring', '
yet', ' in', ' my', ' ancient',' ears.')
returns
"Thy
old groans ring yet in my ancient ears."
fn:concat('Ciao!',())
returns
"Ciao!"
fn:concat('Ingratitude, ', 'thou ', 'marble-hearted', '
fiend!')
returns
"Ingratitude, thou marble-hearted
fiend!"
7.4.2
fn:string-join
fn:string-join
$arg1
as
xs:string*
$arg2
as
xs:string
as
xs:string
Summary: Returns a
xs:string
created by
concatenating the members of the
$arg1
sequence using
$arg2
as a separator. If the value of
$arg2
is the zero-length string, then the members of
$arg1
are concatenated without a separator.
If the value of
$arg1
is the empty sequence, the
zero-length string is returned.
7.4.2.1 Examples
fn:string-join(('Now', 'is', 'the', 'time', '...'), '
')
returns
"Now is the time ..."
fn:string-join(('Blow, ', 'blow, ', 'thou ', 'winter ',
'wind!'), '')
returns
"Blow, blow, thou winter
wind!"
fn:string-join((), 'separator')
returns
""
Assume a document: