Copyright © 2003 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensingrules apply.
This document defines basic operators and functions on the datatypes defined in [XML Schema Part 2: Datatypes] for use in XQuery, XPath, XSLT 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 XQuery, XPath, XSLT and other related XML standards.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.
This is a Public Working Draft of this document for review by W3C Members and other interested parties. It is a draft document and may be updated, replaced, or made obsolete by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". This is work in progress and does not imply endorsement by the W3C membership.
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.
The more significant changes from the previous version of this document are listed below. Public comment is solicited on these changes.
Two new datatypes, xdt:anyAtomicType and
xdt:untypedAtomic have been added (see 1.3 xdt:anyAtomicType and
xdt:untypedAtomic) and the datatypes introduced in
this document have been put into their own namespace.
The semantics of functions whose return type varies with their input type is now described in greater detail. The return type of such functions is identified typographically to call attention to their special semantics.
There also has been some amplification of the rules for
constructing simple types and for casting (see section 5 Constructor
Functions and section 17
Casting Functions). A constructor for
xs:QName has been added with special semantics.
See 17.14 Casting to
xs:QName.
Another area where there has been a significant change
from earlier versions is the implementation of the decision
to preserve the input timezone in xs:dateTime,
xs:date and xs:time values. This
has impacted a large number of functions and has had a
pervasive effect over 9
Functions and Operators on Durations, Dates and
Times.
The fn:document() function has been replaced
by a much simpler function called fn:doc().
The rules for overflow and underflow in numeric operations have been spelled out in greater detail. See 6.2 Operators on Numeric Values
An error function, fn:error(), and a trace
function, fn:trace(),
have been added.
This document has been produced following the procedures set out for the W3C Process. This document was produced through the efforts of a joint task force of the W3C XML Query Working Group and the W3C XSL Working Group (both part of the W3C XML Activity). It is designed to be read in conjunction with the following documents: [XQuery 1.0 and XPath 2.0 Data Model], [XPath 2.0], [XQuery 1.0: An XML Query Language] and [XSLT 2.0].
This is a Last Call Working Draft. Comments on this document are due on 30 June 2003. Comments should be sent to the W3C mailing list, public-qt-comments@w3.org (archived at http://lists.w3.org/Archives/Public/public-qt-comments/).
Patent disclosures relevant to this specification may be found on the XML Query Working Group's patent disclosure page and the XSL Working Group's patent disclosure page.
A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR/.
1 Introduction
1.1 Terminology
1.2 Datatypes
1.3 xdt:anyAtomicType and
xdt:untypedAtomic
1.3.1 xdt:anyAtomicType
1.3.2 xdt:untypedAtomic
1.4 xs:dateTime, xs:date and xs:time
values
1.4.1 Examples
1.5 Syntax
1.6 Notations
1.7 Namespace Prefix
2 Accessors
2.1 fn:node-kind
2.2 fn:node-name
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 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:floor
6.4.2 fn:ceiling
6.4.3 fn:round
6.4.4 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 fn:compare
7.4 Functions on
String Values
7.4.1 fn:concat
7.4.2 fn:string-join
7.4.3 fn:starts-with
7.4.4 fn:ends-with
7.4.5 fn:contains
7.4.6 fn:substring
7.4.7 fn:string-length
7.4.8 fn:substring-before
7.4.9 fn:substring-after
7.4.10 fn:normalize-space
7.4.11 fn:normalize-unicode
7.4.12 fn:upper-case
7.4.13 fn:lower-case
7.4.14 fn:translate
7.4.15 fn:string-pad
7.4.16 fn:escape-uri
7.5 String
Functions that Use Pattern Matching
7.5.1 Regular Expression Syntax
7.5.2 fn:matches
7.5.3 fn:replace
7.5.4 fn:tokenize
8 Functions and Operators on
Booleans
8.1 Boolean
Constructor Functions
8.1.1 fn:true
8.1.2 fn:false
8.2 Operators on
Boolean Values
8.2.1 op:boolean-equal
8.2.2 op:boolean-less-than
8.2.3 op:boolean-greater-than
8.3 Functions on
Boolean Values
8.3.1 fn:not
9 Functions and Operators on
Durations, Dates and Times
9.1 Duration, Date
and Time Types
9.1.1 CONFORMANCE NOTE
9.2 Two
Totally Ordered Subtypes of Duration
9.2.1 xdt:yearMonthDuration
9.2.2 xdt:dayTimeDuration
9.3 Comparisons of Duration, Date
and Time Values
9.3.1 op:yearMonthDuration-equal
9.3.2 op:yearMonthDuration-less-than
9.3.3 op:yearMonthDuration-greater-than
9.3.4 op:dayTimeDuration-equal
9.3.5 op:dayTimeDuration-less-than
9.3.6 op:dayTimeDuration-greater-than
9.3.7 op:dateTime-equal
9.3.8 op:dateTime-less-than
9.3.9 op:dateTime-greater-than
9.3.10 op:date-equal
9.3.11 op:date-less-than
9.3.12 op:date-greater-than
9.3.13 op:time-equal
9.3.14 op:time-less-than
9.3.15 op:time-greater-than
9.3.16 op:gYearMonth-equal
9.3.17 op:gYear-equal
9.3.18 op:gMonthDay-equal
9.3.19 op:gMonth-equal
9.3.20 op:gDay-equal
9.4 Component
Extraction Functions on Duration, Date and Time
Values
9.4.1 fn:get-years-from-yearMonthDuration
9.4.2 fn:get-months-from-yearMonthDuration
9.4.3 fn:get-days-from-dayTimeDuration
9.4.4 fn:get-hours-from-dayTimeDuration
9.4.5 fn:get-minutes-from-dayTimeDuration
9.4.6 fn:get-seconds-from-dayTimeDuration
9.4.7 fn:get-year-from-dateTime
9.4.8 fn:get-month-from-dateTime
9.4.9 fn:get-day-from-dateTime
9.4.10 fn:get-hours-from-dateTime
9.4.11 fn:get-minutes-from-dateTime
9.4.12 fn:get-seconds-from-dateTime
9.4.13 fn:get-timezone-from-dateTime
9.4.14 fn:get-year-from-date
9.4.15 fn:get-month-from-date
9.4.16 fn:get-day-from-date
9.4.17 fn:get-timezone-from-date
9.4.18 fn:get-hours-from-time
9.4.19 fn:get-minutes-from-time
9.4.20 fn:get-seconds-from-time
9.4.21 fn:get-timezone-from-time
9.5 Arithmetic Functions on
xdt:yearMonthDuration and xdt:dayTimeDuration
9.5.1 op:add-yearMonthDurations
9.5.2 op:subtract-yearMonthDurations
9.5.3 op:multiply-yearMonthDuration
9.5.4 op:divide-yearMonthDuration
9.5.5 op:add-dayTimeDurations
9.5.6 op:subtract-dayTimeDurations
9.5.7 op:multiply-dayTimeDuration
9.5.8 op:divide-dayTimeDuration
9.6 Timezone Adjustment on dateTime,
date and time Values
9.6.1 fn:adjust-dateTime-to-timezone
9.6.2 fn:adjust-date-to-timezone
9.6.3 fn:adjust-time-to-timezone
9.7 Adding and Subtracting Durations
From dateTime, date and time
9.7.1 fn:subtract-dateTimes-yielding-yearMonthDuration
9.7.2 fn:subtract-dateTimes-yielding-dayTimeDuration
9.7.3 op:subtract-dates
9.7.4 op:subtract-times
9.7.5 op:add-yearMonthDuration-to-dateTime
9.7.6 op:add-dayTimeDuration-to-dateTime
9.7.7 op:subtract-yearMonthDuration-from-dateTime
9.7.8 op:subtract-dayTimeDuration-from-dateTime
9.7.9 op:add-yearMonthDuration-to-date
9.7.10 op:add-dayTimeDuration-to-date
9.7.11 op:subtract-yearMonthDuration-from-date
9.7.12 op:subtract-dayTimeDuration-from-date
9.7.13 op:add-dayTimeDuration-to-time
9.7.14 op:subtract-dayTimeDuration-from-time
10 Functions Related to QNames
10.1 Constructor
Functions for QNames
10.1.1 fn:resolve-QName
10.1.2 fn:expanded-QName
10.2 Functions
Related to QNames
10.2.1 op:QName-equal
10.2.2 fn:get-local-name-from-QName
10.2.3 fn:get-namespace-from-QName
10.2.4 fn:get-namespace-uri-for-prefix
10.2.5 fn:get-in-scope-namespaces
11 Functions and Operators for
anyURI
11.1 fn:resolve-uri
11.2 op:anyURI-equal
11.2.1 Examples
12 Functions and Operators on base64Binary
and hexBinary
12.1 Comparisons
of base64Binary and hexBinary Values
12.1.1 op:hexBinary-equal
12.1.2 op:base64Binary-equal
13 Functions and Operators on
NOTATION
13.1 Operators on
NOTATION
13.1.1 op:NOTATION-equal
14 Functions and Operators on
Nodes
14.1 Functions and
Operators on Nodes
14.1.1 fn:name
14.1.2 fn:local-name
14.1.3 fn:namespace-uri
14.1.4 fn:number
14.1.5 fn:lang
14.1.6 op:node-equal
14.1.7 op:node-before
14.1.8 op:node-after
14.1.9 fn:root
15 Functions and Operators on
Sequences
15.1 Functions and
Operators on Sequences
15.1.1 fn:zero-or-one
15.1.2 fn:one-or-more
15.1.3 fn:exactly-one
15.1.4 fn:boolean
15.1.5 op:concatenate
15.1.6 fn:item-at
15.1.7 fn:index-of
15.1.8 fn:empty
15.1.9 fn:exists
15.1.10 fn:distinct-nodes
15.1.11 fn:distinct-values
15.1.12 fn:insert-before
15.1.13 fn:remove
15.1.14 fn:subsequence
15.1.15 fn:unordered
15.2 Equals,
Union, Intersection and Except
15.2.1 fn:deep-equal
15.2.2 fn:sequence-node-identical
15.2.3 op:union
15.2.4 op:intersect
15.2.5 op:except
15.3 Aggregate
Functions
15.3.1 fn:count
15.3.2 fn:avg
15.3.3 fn:max
15.3.4 fn:min
15.3.5 fn:sum
15.4 Functions that Generate
Sequences
15.4.1 op:to
15.4.2 fn:id
15.4.3 fn:idref
15.4.4 fn:doc
15.4.5 fn:collection
15.4.6 fn:input
16 Context Functions
16.1 fn:context-item
16.2 fn:position
16.3 fn:last
16.4 fn:current-dateTime
16.4.1 Examples
16.5 fn:current-date
16.5.1 Examples
16.6 fn:current-time
16.6.1 Examples
16.7 fn:default-collation
16.8 fn:implicit-timezone
17 Casting Functions
17.1 Casting from
primitive types to primitive types
17.2 Casting to derived
types
17.3 Casting from derived
types to parent types
17.4 Casting within a branch of the
type hierarchy
17.5 Casting across the type
hierarchy
17.6 Casting from xs:string,
xdt:untypedAtomic and xs:anySimpleType
17.7 Casting to xs:string,
xs:anySimpleType and xdt:untypedAtomic
17.8 Casting to numeric
types
17.9 Casting to duration
types
17.10 Casting to date and time
types
17.11 Casting to xs:boolean
17.12 Casting to
xs:base64Binary and xs:hexBinary
17.13 Casting to xs:anyURI
17.14 Casting to xs:QName
17.14.1 Usage Note
17.15 Casting to xs:NOTATION
A References
A.1 Normative
A.2 Non-normative
B Compatibility with XPath
1.0 (Non-Normative)
C Illustrative User-written Functions
(Non-Normative)
C.1 eg:if-empty and
eg:if-absent
C.1.1 eg:if-empty
C.1.2 eg:if-absent
C.2 union, intersect and
except on sequences of values
C.2.1 eg:value-union
C.2.2 eg:value-intersect
C.2.3 eg:value-except
C.3 eg:index-of-node
C.4 Working With xs:duration
Values
D Functions and Operators Issues List
(Non-Normative)
E ChangeLog since Last Public Version on
2002-11-15 (Non-Normative)
F Function and Operator Quick
Reference (Non-Normative)
F.1 Functions and
Operators by Section
F.2 Functions and
Operators Alphabetically
[XML Schema Part 2: Datatypes]
defines a number of primitive and derived datatypes,
collectively known as built-in datatypes. This document
defines operations on these datatypes as well as the two
datatypes defined in 1.3
xdt:anyAtomicType and xdt:untypedAtomic and the two
totally ordered subtypes of xs:duration
defined in 9.2 Two Totally
Ordered Subtypes of Duration, for use in XQuery,
XPath, XSLT and related XML standards. This document also
discusses operators and functions on nodes and node
sequences as defined in the [XQuery
1.0 and XPath 2.0 Data Model] for use in XQuery, XPath,
XSLT and other related XML standards.
The terminology used to describe the functions and operators on [XML Schema Part 2: Datatypes] is defined in the body of this specification. The terms defined in the following list are used in building those definitions:
A feature of this specification included to ensure that implementations that use this feature remain compatible with [XPath 1.0]
Conforming documents and processors are permitted to, but need not, behave as described.
Conforming documents and processors are required to behave as described; otherwise, they are non-conformant or in error.
Possibly differing between implementations, but specified by the implementor for each particular implementation.
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.
Most of the functions in the core library have the
property that calling the same function twice with
the same arguments returns the same result: these
functions are said to be stable. This category
includes a number of functions such as fn:doc(), fn:collection(),
fn:input(), fn:current-dateTime(),
fn:current-date
and fn:current-time()
whose result depends on the external environment.
Where the function returns nodes, stability means
that the returned nodes are identical, not merely
equal. The scope over which the results are stable
depends on the processing context. In XSLT, it
applies to any two calls on the function executed
during the same transformation. In XQuery, it applies
to any two calls executed during the evaluation of a
top-level expression i.e. an expression not contained
in any other expression. In other contexts, the scope
is specified by the host environment that invokes the
function library.
Some other functions, for example fn:position()
and fn:last(),
have an explicit dependency on the dynamic context,
and may therefore produce different results each time
they are called. These functions are said to be
contextual.
The diagram below shows the built-in [XML Schema Part 2: Datatypes]. Solid lines connect a base datatype above to a derived datatype below. Dashed lines connect a datatype created as a list of an item type above.
Diagram courtesy Asir Vedamuthu, webMethods and Jim Melton, Oracle
The abstract datatype xdt:anyAtomicType is a
child of xs:anySimpleType and is the base type
for all the primitive atomic types described in [XML Schema Part 2: Datatypes].
This datatype cannot be used in [XML
Schema Part 1: Structures] type declarations, nor
can it be used as a base for user-defined atomic types.
It can be used in the [XQuery 1.0: An
XML Query Language] SequenceType production to
define a required type (for example in a function
signature) to indicate that any of the primitive atomic
types or xdt:untypedAtomic is acceptable.
This datatype resides in the namespace
http://www.w3.org/2003/05/xpath-datatypes.
The abstract datatype xdt:untypedAtomic is a
child of xdt:anyAtomicType and serves as a
special type annotation to indicate atomic values that
have not been validated by a XML Schema or a DTD or
have received an instance type annotation of
xs:anySimpleType in the PSVI. This
datatype cannot be used in [XML
Schema Part 1: Structures] type declarations, nor
can it be used as a base for user-defined atomic types.
It can be used in the [XQuery 1.0: An
XML Query Language] SequenceType production to
define a required type (for example in a function
signature) to indicate that only an untyped atomic
value is acceptable. This datatype resides in the
namespace
http://www.w3.org/2003/05/xpath-datatypes.
xs:dateTime, xs:date and
xs:time values are represented in the [XQuery 1.0 and XPath 2.0 Data
Model] as tuples: a normalized value with timezone
Z and a timezone represented as a
xdt:dayTimeDuration value. Lexical
representations of xs:dateTime,
xs:date and xs:time that have a
timezone are converted to timezone Z as
defined by [XML Schema Part 2:
Datatypes] and the timezone in the lexical
representation is converted to a
xdt:dayTimeDuration value. Lexical
representations that do not contain a timezone are given
a normalized value with the timezone Z and
the timezone part of the value set to the empty sequence
"()".
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].
In general, the specifications named above do not
support function overloading. Consequently, there are no
overloaded functions in this document except for legacy
[XPath 1.0] functions such as
string(), which takes a single argument of a
variety of types, and concat() which takes a
variable number of xs:string arguments. In
addition, the functions defined in 6 Functions and Operators on
Numerics that take numeric arguments take
arguments of type xs:integer,
xs:decimal, xs:float or
xs:double. Operators such as "+" may be
overloaded.
This document defines a few new datatypes, constructor functions and functions that take typed values as arguments. Some of the functions back up operators defined in [XQuery 1.0: An XML Query Language]. Each function is defined by specifying its signature, a description of each of its arguments 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 is the
name of the function whose signature is being specified.
If the function takes no parameters, then the name is
followed by an empty set of parentheses:
"()"; otherwise, the name is followed by a
parenthesized list of parameter declarations, each
declaration specifying the static type of the parameter
and a non-normative name used to describe the function's
semantics. If there are two or more parameter
declarations, they are separated by a comma. The
return-type specifies the static type of the
value returned by the function. In most cases, the
dynamic type returned by the function is the same as its
static type.
For most functions there is a paragraph describing what the function does followed by semantic rules. These rules are meant to be followed in the order that they appear in this document.
In some cases, the dynamic type returned by a function depends on the type(s) of its argument(s). These special functions are indicated by using bold italics for the return type. The semantic rules specifying the type of the value returned are documented in the function definition. The rules are described more formally in Section 6.2 of [XQuery 1.0 and XPath 2.0 Formal Semantics].
The function name is a QName as defined
in [XML 1.0 Recommendation (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]
datatype name, it may have intercapitalized spelling and
is used in the function name as such. For example, fn:get-timezone-from-dateTime.
As is customary, the parameter type name indicates that the function accepts arguments of that type, or types derived from it, in that position. This is called subtype substitution. Details of the semantics of passing parameters to functions are discussed in Appendix B of [XQuery 1.0: An XML Query Language].
Some functions accept the empty sequence as an
argument and some may return the empty sequence. This is
indicated in the function signature by following the
parameter or return type name with a question mark:
"?"
fn:function-name($parameter-name as parameter-type?) as return-type?
The functions and operators discussed in this document
are contained in one of three namespaces (see [Namespaces in XML]) and
referenced using a QName. Constructor functions for the
built-in datatypes defined in [XML
Schema Part 2: Datatypes] discussed in 5 Constructor
Functions are in the XML Schema namespace and
named in this document using the xs: prefix.
The namespace prefix used in this document is
fn: for the functions available to users and
op: for the operator functions.The functions
indicated by the op: prefix back up
operators in the host languages and are not directly
accessible by the user.
The datatypes described in this document are contained
in a fourth namespace and are named using the prefix
xdt:.
The namespace prefix for these functions and datatypes can vary, as long as the prefix is bound to the correct URI.
The URIs of the namespaces are:
http://www.w3.org/2001/XMLSchema for
constructors
http://www.w3.org/2003/05/xpath-operators
for operators
http://www.w3.org/2003/05/xpath-functions
for functions.
http://www.w3.org/2003/05/xpath-datatypes
for the datatypes.
The functions defined with an fn: prefix
are callable by the user. Functions defined with the
op: prefix are described here to underpin
the definitions of the operators in [XPath 2.0], [XQuery
1.0: An XML Query Language] and [XSLT 2.0]. These functions are not
available directly to users, and there is no requirement
that implementations should actually provide these
functions. For example, multiplication is generally
associated with the * operator, but it is
described as a function in this document. For
example:
op:multiply($operand1 as numeric, $operand2 as numeric) as numeric
The [XQuery 1.0 and XPath 2.0 Data Model] describes accessors on different types of nodes and defines their semantics. Some of these accessors are exposed to the user through the functions described below.
| Function | Accessor | Accepts | Returns |
|---|---|---|---|
fn:node-kind |
node-kind |
any kind of node | xs:string |
fn:node-name |
node-name |
any kind of node | zero or one
xs:QName |
fn:string |
string-value |
item | xs:string |
fn:data |
typed-value |
zero or more nodes | a sequence of atomic values |
fn:base-uri |
base-uri |
Element, document or PI node or no argument | zero or one
xs:string |
fn:document-uri |
document-uri |
Node | zero or one
xs:string |
fn:node-kind($srcval as node) as xs:string
This function returns a xs:string
representing the node's kind: either "document",
"element", "attribute", "text", "namespace",
"processing-instruction", or "comment".
fn:node-name($srcval as node) as xs:QName?
This function returns an expanded-QName for node kinds that can have names. For other node kinds, it returns the empty sequence. Expanded-QName is defined in [XQuery 1.0 and XPath 2.0 Data Model], and consists of a pair of values: a namespace URI and a local name.
fn:string() as xs:string
fn:string($srcval as item?) as xs:string
Returns the value of $srcval represented
as a xs:string. If no argument is supplied,
$srcval defaults to the context item
(.).
If $srcval is the empty sequence, the
zero-length string is returned.
If $srcval is a node, the function
returns the string-value of the node, as obtained using
the string-value accessor defined in the [XQuery 1.0 and XPath 2.0 Data
Model].
If $srcval is an atomic value, then the
function returns the same string as is returned by the
expression cast as xs:string ($srcval),
except in the cases listed below:
If the type of $srcval is
xs:anyURI, the URI is converted to a
string without any escaping of special
characters.
Note:
The reason for the special rule for
xs:anyURI is that, although XML Schema
strongly discourages the use of spaces within URI
values, the escaping of spaces can cause problems with
legacy applications (for example, this applies to
spaces within fragment identifiers in many HTML
browsers), and should therefore be under user
control.
Note:
The string representation of xs:double
values is not backwards-compatible with the
representation of number values in [XPath 1.0]. Ordinary
xs:double values are now represented using
scientific notation; the representations of positive
and negative infinity are now 'INF' and '-INF' rather
than 'Infinity' and '-Infinity'. (It should be observed
that '+INF' is not supported as a lexical form of
infinity in [XML Schema Part 2:
Datatypes] and is thus not supported by this
specification; if that lexical form is added in a
future version of [XML Schema Part
2: Datatypes], then it will be supported by a
future version of this specification that aligns with
that future version of [XML Schema
Part 2: Datatypes].) However, most expressions that
would have produced a number in [XPath 1.0] will produce a decimal
(or integer) in [XPath 2.0], so
unless there is a loss of precision caused by numeric
approximation, the result of the expression will in
most simple cases be the same after conversion to a
string.
fn:data($srcval as item*) as xdt:anyAtomicType*
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 $srcval:
If the item is an atomic value, it is returned.
If the item is a node, fn:data()
returns the typed value of the node as defined by the
accessor function dm:typed-value in [XQuery 1.0 and XPath 2.0 Data
Model].
fn:base-uri($srcval as node) as xs:string?
Returns the value of the base-uri property for
$srcval as defined by the accessor function
dm:base-uri for that kind of node in [XQuery 1.0 and XPath 2.0 Data
Model]. Document, element and processing-instruction
nodes have a base-uri property. If that property is
non-empty, its value is returned. The base-uri of all
other node types is the empty sequence.
If the accessor is called on a node that does not have a base-uri property, or whose base-uri property is empty, the base-uri of that node's parent is returned. If the node has no parent, the empty sequence is returned.
fn:base-uri() as xs:string?
This version of the function returns the value of the base-uri property from the static context using the preceding rules.
fn:document-uri($srcval as node) as xs:string?
Returns the value of the document-uri property for
$srcval as defined by the accessor function
dm:document-uri in [XQuery 1.0 and XPath 2.0 Data
Model]. The empty sequence is returned if the node
does not have a document-uri property or if the
document-uri property is a relative URI. Otherwise,
returns an absolute URI expressed as an
xs:string.
If the document-uri property of $srcval
is not the empty sequence, then the following expression
always holds:
fn:doc(fn:document-uri($srcval)) is $srcval
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
whenever the semantics being described encounter an error.
The occurrence of that phrase implicitly causes the
invocation of the fn:error function defined in
this section. Whenever the raising of an error is
accompanied by a specific error, the phrase "an error is
raised (name-of-error)" is used, and the value
name-of-error is passed as an argument to the
fn:error function invocation. Invocation of
this function causes the evaluation phase of the outermost
XQuery or transformation to be terminated. For a more
detailed treatment of error handing see section 2.5.1 of [XQuery 1.0: An XML Query Language] and
section 6.2.1 of [XQuery 1.0
and XPath 2.0 Formal Semantics].
The fn:error function may also be invoked
from XQuery and XPath 2.0 applications.
fn:error() as none
fn:error($srcval as item?) as none
The fn:error function accepts any item
(e.g., an atomic value or an element) as an argument. An
alternate version of the function takes no arguments. The
fn:error function never returns a value.
Note that "none" is a special type defined in the [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.
This function is intended to be used in debugging queries by providing a trace of their execution.
fn:trace($value as item*, $label as xs:string) as item*
The input $value is returned, unchanged, as
the result of the function. In addition, the inputs
$value and $label are directed to
a trace data set. The location and format of the trace data
set are ·implementation defined·. The ordering of output
from invocations of the fn:trace() function is
·implementation defined·.
Consider a situation in which a user wants to
investigate the actual value passed to a function.
Assume that in a particular execution,
$v is an xs:decimal with
value 124.84. Writing fn:trace($v,
'the value of $v is:') will put the strings
"124.84" and "the value of $v
is" in the trace data set in implementation
defined order.
Every built-in atomic type that is defined in [XML Schema Part 2: Datatypes],
except xs:NOTATION, as well as
xdt:untypedAtomic and the two derived types
xdt:yearMonthDuration and
xdt:dayTimeDuration defined in this
specification, has an associated constructor function.
The form of that function for a type pref:TYPE
is:
pref:TYPE($srcval as xdt:anyAtomicType) as pref:TYPE
For example, the signature of the constructor function
corresponding to the xs:unsignedInt type
defined in [XML Schema Part 2:
Datatypes] is:
xs:unsignedInt($srcval as xdt:anyAtomicType) as xs:unsignedInt
Invoking the constructor function
xs:unsignedInt(12) returns the
xs:unsignedInt value 12. Another invocation
of that constructor function that returns the same
xs:unsignedInt value is
xs:unsignedInt("12"). The same result would
also be returned if the constructor function were to be
invoked with a node that had a value equal to the
xs:unsignedInt 12. The standard features
described in [XQuery 1.0: An XML Query
Language] would 'atomize' the node to extract its
value and then call the constructor with that value. If
the value passed to a constructor is illegal for the
datatype to be constructed, an error is raised ("Illegal
value for constructor").
If the argument to a constructor function is a string
literal, the literal must be a valid lexical form for its
type, as specified in [XML Schema Part
2: Datatypes] and the semantics of the function are
identical to XML Schema validation. In the case of
xs:dateTime, xs:date and
xs:time, the value returned differs from [XML Schema Part 2: Datatypes] and is
defined in 1.4
xs:dateTime, xs:date and xs:time values.
Whitespace normalization is applied before validation as
indicated by the value of the whitespace facet for the
datatype.
If the argument to a constructor function is a literal, the result of the function may be evaluated statically; if an error is found during such evaluation, it may be reported as a static error.
The semantics of the constructor function
xs:TYP(xdt:anyAtomicType) are identical to
the semantics of "cast as xs:TYP
(xdt:anyAtomicType)". See 17 Casting Functions
The following constructor functions for the built-in types are supported:
xs:string($srcval as xdt:anyAtomicType) as xs:string
xs:boolean($srcval as xdt:anyAtomicType) as xs:boolean
xs:decimal($srcval as xdt:anyAtomicType) as xs:decimal
xs:float($srcval as xdt:anyAtomicType) as xs:float
Implementations ·may· return negative zero
for xs:float(-0.0E0).
xs:double($srcval as xdt:anyAtomicType) as xs:double
Implementations ·may· return negative zero
for xs:double(-0.0E0).
xs:duration($srcval as xdt:anyAtomicType) as xs:duration
xs:dateTime( |
$srcval |
as xdt:anyAtomicType) as (xs:dateTime,
xdt:dayTimeDuration) |
xs:time($srcval as xdt:anyAtomicType) as (xs:time,
xdt:dayTimeDuration)
xs:date($srcval as xdt:anyAtomicType) as (xs:date,
xdt:dayTimeDuration)
xs:gYearMonth($srcval as xdt:anyAtomicType) as xs:gYearMonth
xs:gYear($srcval as xdt:anyAtomicType) as xs:gYear
xs:gMonthDay($srcval as xdt:anyAtomicType) as xs:gMonthDay
xs:gDay($srcval as xdt:anyAtomicType) as xs:gDay
xs:gMonth($srcval as xdt:anyAtomicType) as xs:gMonth
xs:hexBinary($srcval as xdt:anyAtomicType) as xs:hexBinary
xs:base64Binary($srcval as xdt:anyAtomicType) as xs:base64Binary
xs:anyURI($srcval as xdt:anyAtomicType) as xs:anyURI
xs:anyURI($srcval as xdt:anyAtomicType) as xs:QName
See 17.14 Casting
to xs:QName for semantics of
xs:anyURI.
xs:normalizedString($srcval as xdt:anyAtomicType) as xs:normalizedString
xs:token($srcval as xdt:anyAtomicType) as xs:token
xs:language($srcval as xdt:anyAtomicType) as xs:language
xs:NMTOKEN($srcval as xdt:anyAtomicType) as xs:NMTOKEN
xs:Name($srcval as xdt:anyAtomicType) as xs:Name
xs:NCName($srcval as xdt:anyAtomicType) as xs:NCName
xs:ID($srcval as xdt:anyAtomicType) as xs:ID
xs:IDREF($srcval as xdt:anyAtomicType) as xs:IDREF
xs:ENTITY($srcval as xdt:anyAtomicType) as xs:ENTITY
xs:integer($srcval as xdt:anyAtomicType) as xs:integer
xs:nonPositiveInteger($srcval as xdt:anyAtomicType) as xs:nonPositiveInteger
xs:negativeInteger($srcval as xdt:anyAtomicType) as xs:negativeInteger
xs:long($srcval as xdt:anyAtomicType) as xs:long
xs:int($srcval as xdt:anyAtomicType) as xs:int
xs:short($srcval as xdt:anyAtomicType) as xs:short
xs:byte($srcval as xdt:anyAtomicType) as xs:byte
xs:nonNegativeInteger($srcval as xdt:anyAtomicType) as xs:nonNegativeInteger
xs:unsignedLong($srcval as xdt:anyAtomicType) as xs:unsignedLong
xs:unsignedInt($srcval as xdt:anyAtomicType) as xs:unsignedInt
xs:unsignedShort($srcval as xdt:anyAtomicType) as xs:unsignedShort
xs:unsignedByte($srcval as xdt:anyAtomicType) as xs:unsignedByte
xs:positiveInteger($srcval as xdt:anyAtomicType) as xs:positiveInteger
xdt:yearMonthDuration($srcval as xdt:anyAtomicType) as xdt:yearMonthDuration
xdt:dayTimeDuration($srcval as xdt:anyAtomicType) as xdt:dayTimeDuration
xdt:untypedAtomic($srcval as xdt:anyAtomicType) as xdt:untypedAtomic
For every globally-defined atomic type in the static context (See [XQuery 1.0: An XML Query Language] that is derived by restriction 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 are defined in the same way as for built-in derived types as discussed in 5.1 Constructor Functions for XML Schema Built-in Types.
Consider a situation where the static context contains
a type called hatSize defined in a schema
that is bound to the prefix my. In such a
case the constructor function:
my:hatSize($srcval as xdt:anyAtomicType) as my:hatSize
is available to users.
This section discusses arithmetic operators on the numeric datatypes defined in [XML Schema Part 2: Datatypes]. It uses an approach that permits lightweight implementation whenever possible.
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:
The value space for xs:float and
xs:double, as defined in the errata to [XML Schema Part 2: Datatypes],
defines only a single zero. [IEEE
754-1985] arithmetic, however, can produce distinct
results of positive zero and negative zero. The value
space for atomic values of type xs:float
and xs:double, as defined in this suite of
documents, contains this extra value of negative zero
which compares equal to positive zero. The value
negative zero will never be obtained from the typed
value of a node. However, negative zero may be produced
as the result of a computation; for example, the unary
minus operator produces negative zero if its operand is
positive zero.
The following functions are defined to back up 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 arguments and return types for the arithmetic
operators are the basic numeric types:
xs:integer, xs:decimal,
xs:float and xs:double, and
types derived from them. For simplicity, each operator is
defined to operate on operands of the same type and to
return the same type. The one exception is op:numeric-divide,
which returns an xs:decimal if called with
two xs:integer operands.)
Operands of type xdt:untypedAtomic are
converted to xs:double, except for arguments
to 6.2.5
op:numeric-integer-divide which are converted to
xs:integer. If the two operands are not of
the same type, subtype substitution and type
promotion may be used to obtain two operands of the
same type. Appendix B of [XQuery 1.0:
An XML Query Language] describes the semantics of
these operations in detail.
Subtype substitution: A derived type may
substitute for its base type. In particular,
xs:integer may be used where
xs:decimal is expected.
Type promotion: xs:decimal
may be promoted to xs:float, and
xs:float may be promoted to
xs:double.
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 promoted to
xs:decimal, xs:decimal can be
promoted to xs:float, and
xs:float can be promoted to
xs:double. As far as possible, the
promotions should be done in a single step. Specifically,
when a decimal is promoted to a double, it must not be
converted to a float and then to 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
oddHeight using a pattern to restrict the
value to odd integers.
op:operation(oddHeight, xs:integer) => op:operation(xs:integer, xs:integer)
oddHeight 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 a number of options:
Raising an error ("overflow on float or double operation") 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 a number of options:
Raising an error ("underflow on float or double operation") 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
("overflow on decimal operation"). On underflow,
0.0 must be returned.
For xs:integer operations,
implementations ·may· choose to always
raise an error ("overflow on integer operation").
Alternatively, implementations ·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.
The number of digits of precision returned by various numeric functions is ·implementation dependent·.
op:numeric-add($operand1 as numeric, $operand2 as numeric) as numeric
Backs up the "+" operator and returns the arithmetic
sum of its operands: ($operand1 +
$operand2).
op:numeric-subtract($operand1 as numeric, $operand2 as numeric) as numeric
Backs up the "-" operator and returns the arithmetic
difference of its operands: ($operand1 -
$operand2).
op:numeric-multiply($operand1 as numeric, $operand2 as numeric) as numeric
Backs up the "*" operator and returns the arithmetic
product of its operands: ($operand1 *
$operand2).
op:numeric-divide($operand1 as numeric, $operand2 as numeric) as numeric
Backs up the "div" operator and returns the
arithmetic quotient of its operands: ($operand1
div $operand2).
As a special case, if the types of both
$operand1 and $operand2 are
xs:integer, then the return type is
xs:decimal.
For xs:decimal and
xs:integer operands, if the divisor is
0, then an error is raised ("Division by
zero"). For xs:float and
xs:double operands, floating point
division is performed as specified in [IEEE 754-1985] and
INF or -INF is returned if
the divisor is zero.