See also translations.
This document is also available in these nonnormative formats: XML and Change markings relative to previous Working Draft.
Copyright © 2010 W3C^{®} (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This is a draft for internal review. Change markings are relative to the Recommendation of 23 January 2007.
This document defines constructor functions, operators, and functions on the datatypes defined in [XML Schema Part 2: Datatypes Second Edition] and the datatypes defined in [XQuery and XPath Data Model (XDM) 3.0]. It also defines functions and operators on nodes and node sequences as defined in the [XQuery and XPath Data Model (XDM) 3.0]. These functions and operators are defined for use in [XML Path Language (XPath) 3.0], [XQuery 3.0: An XML Query Language] and [XSL Transformations (XSLT) Version 3.0] and other related XML standards. The signatures and summaries of functions defined in this document are available at: http://www.w3.org/2005/xpathfunctions/.
This is the third version of the specification of this function library. The first version was included as an intrinsic part of the [XML Path Language (XPath) Version 1.0] specification published on 16 November 1999. The second version was published under the title XQuery 1.0 and XPath 2.0 Functions and Operators on 23 January 2007. This third version is the first to carry its own version number, which has been set at 3.0 to align with version numbering for XPath, XQuery, and XSLT. A previous draft of this version of the specification carried the version number 1.1.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is one document in a set of seven documents that are being progressed to Recommendation together (XQuery 3.0, XQueryX 3.0, XSLT 3.0, Data Model 3.0, Functions and Operators 3.0, Serialization 3.0, XPath 3.0).
This is a Working Draft as described in the Process Document. It 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. The Working Groups expect to advance this specification to Recommendation Status.
This public Working Draft differs from the previous Working Draft in two important ways. First, the version number of the document has changed from "1.1" to "3.0"; this was done in order to align the version numbers of the entire suite of documents of which this WD is a part. Second, a number of substantive technical changes (as well as many editorial changes) have been made in this WD. Please note that this Working Draft of XPath and XQuery Functions and Operators 3.0 represents the second version of a previous W3C Recommendation.
We particularly solicit feedback on the changes made in this document in response to Bugzilla Bug #10868 (prohibiting the xml namespace in module import, schema import, and default namespace declarations).
A Test Suite has been created for this document. Implementors are encouraged to run this test suite and report their results. The Test Suite can be found at http://dev.w3.org/cvsweb/2006/xquerytestsuite/. An implementation report is available at http://www.w3.org/XML/Query/testsuite/XQTSReport.html.
This document incorporates changes made against the previous publication of the Working Draft of 14 December 2010. Changes to this document since the previous publication of the Working Draft are detailed in F Changes since previous Recommendation.
Please report errors in this document using W3C's public Bugzilla system (instructions can be found at http://www.w3.org/XML/2005/04/qtbugzilla). If access to that system is not feasible, you may send your comments to the W3C XSLT/XPath/XQuery public comments mailing list, publicqtcomments@w3.org. It will be very helpful if you include the string “[FO30]” in the subject line of your report, whether made in Bugzilla or in email. Please use multiple Bugzilla entries (or, if necessary, multiple email messages) if you have more than one comment to make. Archives of the comments and responses are available at http://lists.w3.org/Archives/Public/publicqtcomments/.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by groups operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the XML Query Working Group and also maintains a public list of any patent disclosures made in connection with the deliverables of the XSL Working Group; those pages also include instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
abs acos adddayTimeDurations adddayTimeDurationtodate adddayTimeDurationtodateTime adddayTimeDurationtotime addyearMonthDurations addyearMonthDurationtodate addyearMonthDurationtodateTime adjustdateTimetotimezone adjustdatetotimezone adjusttimetotimezone analyzestring asin atan atan2 availableenvironmentvariables avg
base64Binaryequal baseuri boolean booleanequal booleangreaterthan booleanlessthan
ceiling codepointequal codepointstostring collection compare concat concatenate contains cos count currentdate currentdateTime currenttime
data dateequal dategreaterthan datelessthan dateTime dateTimeequal dateTimegreaterthan dateTimelessthan dayfromdate dayfromdateTime daysfromduration dayTimeDurationgreaterthan dayTimeDurationlessthan deepequal defaultcollation distinctvalues dividedayTimeDuration dividedayTimeDurationbydayTimeDuration divideyearMonthDuration divideyearMonthDurationbyyearMonthDuration doc docavailable documenturi durationequal
elementwithid empty encodeforuri endswith environmentvariable error escapehtmluri exactlyone except exists exp exp10
false filter float floor foldleft foldright formatdate formatdateTime formatinteger formatnumber formattime functionarity functionname
gDayequal generateid gMonthDayequal gMonthequal gYearequal gYearMonthequal
haschildren head hexBinaryequal hoursfromdateTime hoursfromduration hoursfromtime
id idref implicittimezone indexof innermost inscopeprefixes insertbefore intersect iritouri issamenode
lang last localname localnamefromQName log log10 lowercase
map mappairs matches max min minutesfromdateTime minutesfromduration minutesfromtime monthfromdate monthfromdateTime monthsfromduration multiplydayTimeDuration multiplyyearMonthDuration
name namespaceuri namespaceuriforprefix namespaceurifromQName nilled nodeafter nodebefore nodename normalizespace normalizeunicode not NOTATIONequal number numericadd numericdivide numericequal numericgreaterthan numericintegerdivide numericlessthan numericmod numericmultiply numericsubtract numericunaryminus numericunaryplus
remove replace resolveQName resolveuri reverse root round roundhalftoeven
secondsfromdateTime secondsfromduration secondsfromtime serialize sin sqrt startswith staticbaseuri string stringjoin stringlength stringtocodepoints subsequence substring substringafter substringbefore subtractdates subtractdateTimes subtractdayTimeDurationfromdate subtractdayTimeDurationfromdateTime subtractdayTimeDurationfromtime subtractdayTimeDurations subtracttimes subtractyearMonthDurationfromdate subtractyearMonthDurationfromdateTime subtractyearMonthDurations sum
tail tan timeequal timegreaterthan timelessthan timezonefromdate timezonefromdateTime timezonefromtime to tokenize trace translate true
union unordered unparsedtext unparsedtextavailable unparsedtextlines uppercase uricollection
yearfromdate yearfromdateTime yearMonthDurationgreaterthan yearMonthDurationlessthan yearsfromduration
1 Introduction
1.1 Conformance
1.2 Namespaces and prefixes
1.3 Function
overloading
1.4 Function
signatures and descriptions
1.5 Type
system
1.6 Terminology
1.6.1 Strings, characters, and
codepoints
1.6.2 Namespaces and URIs
1.6.3 Conformance terminology
1.6.4 Properties of functions
2 Accessors
2.1 fn:nodename
2.2 fn:nilled
2.3 fn:string
2.4 fn:data
2.5 fn:baseuri
2.6 fn:documenturi
3 Errors and
diagnostics
3.1 Raising
errors
3.1.1 fn:error
3.2 Diagnostic
tracing
3.2.1 fn:trace
4 Functions and operators on
numerics
4.1 Numeric
types
4.2 Arithmetic
operators on numeric values
4.2.1 op:numericadd
4.2.2 op:numericsubtract
4.2.3 op:numericmultiply
4.2.4 op:numericdivide
4.2.5 op:numericintegerdivide
4.2.6 op:numericmod
4.2.7 op:numericunaryplus
4.2.8 op:numericunaryminus
4.3 Comparison
operators on numeric values
4.3.1 op:numericequal
4.3.2 op:numericlessthan
4.3.3 op:numericgreaterthan
4.4 Functions on numeric values
4.4.1 fn:abs
4.4.2 fn:ceiling
4.4.3 fn:floor
4.4.4 fn:round
4.4.5 fn:roundhalftoeven
4.5 Formatting integers
4.5.1 fn:formatinteger
4.6 Formatting numbers
4.6.1 Defining a decimal format
4.6.2 fn:formatnumber
4.6.3 Syntax of the picture string
4.6.4 Analysing the picture string
4.6.5 Formatting the number
4.7 Trigonometric
and exponential functions
4.7.1 math:pi
4.7.2 math:exp
4.7.3 math:exp10
4.7.4 math:log
4.7.5 math:log10
4.7.6 math:pow
4.7.7 math:sqrt
4.7.8 math:sin
4.7.9 math:cos
4.7.10 math:tan
4.7.11 math:asin
4.7.12 math:acos
4.7.13 math:atan
4.7.14 math:atan2
5 Functions on strings
5.1 String
types
5.2 Functions to assemble and
disassemble strings
5.2.1 fn:codepointstostring
5.2.2 fn:stringtocodepoints
5.3 Comparison of
strings
5.3.1 Collations
5.3.2 The Unicode Codepoint Collation
5.3.3 Choosing a collation
5.3.4 fn:compare
5.3.5 fn:codepointequal
5.4 Functions on string values
5.4.1 fn:concat
5.4.2 fn:stringjoin
5.4.3 fn:substring
5.4.4 fn:stringlength
5.4.5 fn:normalizespace
5.4.6 fn:normalizeunicode
5.4.7 fn:uppercase
5.4.8 fn:lowercase
5.4.9 fn:translate
5.5 Functions based on substring
matching
5.5.1 fn:contains
5.5.2 fn:startswith
5.5.3 fn:endswith
5.5.4 fn:substringbefore
5.5.5 fn:substringafter
5.6 String
functions that use regular expressions
5.6.1 Regular expression syntax
5.6.2 fn:matches
5.6.3 fn:replace
5.6.4 fn:tokenize
5.6.5 fn:analyzestring
6 Functions that manipulate
URIs
6.1 fn:resolveuri
6.2 fn:encodeforuri
6.3 fn:iritouri
6.4 fn:escapehtmluri
7 Functions and operators on Boolean
values
7.1 Boolean
constant functions
7.1.1 fn:true
7.1.2 fn:false
7.2 Operators on
Boolean values
7.2.1 op:booleanequal
7.2.2 op:booleanlessthan
7.2.3 op:booleangreaterthan
7.3 Functions on Boolean values
7.3.1 fn:boolean
7.3.2 fn:not
8 Functions and operators on
durations
8.1 Two
totally ordered subtypes of duration
8.1.1 xs:yearMonthDuration
8.1.2 xs:dayTimeDuration
8.2 Comparison
operators on durations
8.2.1 op:yearMonthDurationlessthan
8.2.2 op:yearMonthDurationgreaterthan
8.2.3 op:dayTimeDurationlessthan
8.2.4 op:dayTimeDurationgreaterthan
8.2.5 op:durationequal
8.3 Component extraction functions on
durations
8.3.1 fn:yearsfromduration
8.3.2 fn:monthsfromduration
8.3.3 fn:daysfromduration
8.3.4 fn:hoursfromduration
8.3.5 fn:minutesfromduration
8.3.6 fn:secondsfromduration
8.4 Arithmetic operators on durations
8.4.1 op:addyearMonthDurations
8.4.2 op:subtractyearMonthDurations
8.4.3 op:multiplyyearMonthDuration
8.4.4 op:divideyearMonthDuration
8.4.5 op:divideyearMonthDurationbyyearMonthDuration
8.4.6 op:adddayTimeDurations
8.4.7 op:subtractdayTimeDurations
8.4.8 op:multiplydayTimeDuration
8.4.9 op:dividedayTimeDuration
8.4.10 op:dividedayTimeDurationbydayTimeDuration
9 Functions and operators on dates and
times
9.1 Date and
time types
9.1.1 Limits and precision
9.2 Date/time
datatype values
9.2.1 Examples
9.3 Constructing a dateTime
9.3.1 fn:dateTime
9.4 Comparison
operators on duration, date and time values
9.4.1 op:dateTimeequal
9.4.2 op:dateTimelessthan
9.4.3 op:dateTimegreaterthan
9.4.4 op:dateequal
9.4.5 op:datelessthan
9.4.6 op:dategreaterthan
9.4.7 op:timeequal
9.4.8 op:timelessthan
9.4.9 op:timegreaterthan
9.4.10 op:gYearMonthequal
9.4.11 op:gYearequal
9.4.12 op:gMonthDayequal
9.4.13 op:gMonthequal
9.4.14 op:gDayequal
9.5 Component extraction functions on
dates and times
9.5.1 fn:yearfromdateTime
9.5.2 fn:monthfromdateTime
9.5.3 fn:dayfromdateTime
9.5.4 fn:hoursfromdateTime
9.5.5 fn:minutesfromdateTime
9.5.6 fn:secondsfromdateTime
9.5.7 fn:timezonefromdateTime
9.5.8 fn:yearfromdate
9.5.9 fn:monthfromdate
9.5.10 fn:dayfromdate
9.5.11 fn:timezonefromdate
9.5.12 fn:hoursfromtime
9.5.13 fn:minutesfromtime
9.5.14 fn:secondsfromtime
9.5.15 fn:timezonefromtime
9.6 Timezone
adjustment functions on dates and time values
9.6.1 fn:adjustdateTimetotimezone
9.6.2 fn:adjustdatetotimezone
9.6.3 fn:adjusttimetotimezone
9.7 Arithmetic operators on durations, dates and
times
9.7.1 Limits and precision
9.7.2 op:subtractdateTimes
9.7.3 op:subtractdates
9.7.4 op:subtracttimes
9.7.5 op:addyearMonthDurationtodateTime
9.7.6 op:adddayTimeDurationtodateTime
9.7.7 op:subtractyearMonthDurationfromdateTime
9.7.8 op:subtractdayTimeDurationfromdateTime
9.7.9 op:addyearMonthDurationtodate
9.7.10 op:adddayTimeDurationtodate
9.7.11 op:subtractyearMonthDurationfromdate
9.7.12 op:subtractdayTimeDurationfromdate
9.7.13 op:adddayTimeDurationtotime
9.7.14 op:subtractdayTimeDurationfromtime
9.8 Formatting dates and times
9.8.1 fn:formatdateTime
9.8.2 fn:formatdate
9.8.3 fn:formattime
9.8.4 The date/time formatting
functions
9.8.5 Examples of date and time
formatting
10 Functions related to QNames
10.1 Functions to create a QName
10.1.1 fn:resolveQName
10.1.2 fn:QName
10.2 Functions
and operators related to QNames
10.2.1 op:QNameequal
10.2.2 fn:prefixfromQName
10.2.3 fn:localnamefromQName
10.2.4 fn:namespaceurifromQName
10.2.5 fn:namespaceuriforprefix
10.2.6 fn:inscopeprefixes
11 Operators on base64Binary and
hexBinary
11.1 Comparisons of base64Binary and
hexBinary values
11.1.1 op:hexBinaryequal
11.1.2 op:base64Binaryequal
12 Operators on NOTATION
12.1 op:NOTATIONequal
13 Functions and operators on
nodes
13.1 fn:name
13.2 fn:localname
13.3 fn:namespaceuri
13.4 fn:number
13.5 fn:lang
13.6 op:issamenode
13.7 op:nodebefore
13.8 op:nodeafter
13.9 fn:root
13.10 fn:haschildren
13.11 fn:innermost
13.12 fn:outermost
14 Functions and operators on
sequences
14.1 General
functions and operators on sequences
14.1.1 op:concatenate
14.1.2 fn:empty
14.1.3 fn:exists
14.1.4 fn:head
14.1.5 fn:tail
14.1.6 fn:insertbefore
14.1.7 fn:remove
14.1.8 fn:reverse
14.1.9 fn:subsequence
14.1.10 fn:unordered
14.2 Functions that compare values in
sequences
14.2.1 fn:distinctvalues
14.2.2 fn:indexof
14.2.3 fn:deepequal
14.3 Functions that test the cardinality of
sequences
14.3.1 fn:zeroorone
14.3.2 fn:oneormore
14.3.3 fn:exactlyone
14.4 Union, intersection and
difference
14.4.1 op:union
14.4.2 op:intersect
14.4.3 op:except
14.5 Aggregate functions
14.5.1 fn:count
14.5.2 fn:avg
14.5.3 fn:max
14.5.4 fn:min
14.5.5 fn:sum
14.6 Functions and operators that
generate sequences
14.6.1 op:to
14.7 Functions on node identifiers
14.7.1 fn:id
14.7.2 fn:elementwithid
14.7.3 fn:idref
14.7.4 fn:generateid
14.8 Functions
giving access to external information
14.8.1 fn:doc
14.8.2 fn:docavailable
14.8.3 fn:collection
14.8.4 fn:uricollection
14.8.5 fn:unparsedtext
14.8.6 fn:unparsedtextlines
14.8.7 fn:unparsedtextavailable
14.8.8 fn:environmentvariable
14.8.9 fn:availableenvironmentvariables
14.9 Parsing and serializing
14.9.1 fn:parsexml
14.9.2 fn:serialize
15 Context functions
15.1 fn:position
15.2 fn:last
15.3 fn:currentdateTime
15.4 fn:currentdate
15.5 fn:currenttime
15.6 fn:implicittimezone
15.7 fn:defaultcollation
15.8 fn:staticbaseuri
16 Higherorder
functions
16.1 Functions on functions
16.1.1 fn:functionname
16.1.2 fn:functionarity
16.2 Basic
higherorder functions
16.2.1 fn:map
16.2.2 fn:filter
16.2.3 fn:foldleft
16.2.4 fn:foldright
16.2.5 fn:mappairs
17 Constructor functions
17.1 Constructor functions for
XML Schema builtin types
17.2 Constructor functions for xs:QName
and xs:NOTATION
17.3 Constructor
functions for userdefined types
18 Casting
18.1 Casting from primitive types
to primitive types
18.1.1 Casting from xs:string and
xs:untypedAtomic
18.1.2 Casting to xs:string and
xs:untypedAtomic
18.1.3 Casting to numeric types
18.1.4 Casting to duration types
18.1.5 Casting to date and time types
18.1.6 Casting to xs:boolean
18.1.7 Casting to xs:base64Binary and
xs:hexBinary
18.1.8 Casting to xs:anyURI
18.1.9 Casting to xs:QName and
xs:NOTATION
18.2 Casting to derived types
18.3 Casting from derived types to
parent types
18.4 Casting within a branch of the type
hierarchy
18.4.1 Casting to xs:ENTITY
18.5 Casting across the type
hierarchy
18.6 Casting to
union types
A References
A.1 Normative
references
A.2 Nonnormative references
B Error summary
C Compatibility with XPath 1.0
(NonNormative)
D Illustrative userwritten functions
(NonNormative)
D.1 eg:ifempty and eg:ifabsent
D.1.1 eg:ifempty
D.1.2 eg:ifabsent
D.2 Union, intersection and
difference on sequences of values
D.2.1 eg:valueunion
D.2.2 eg:valueintersect
D.2.3 eg:valueexcept
D.3 eg:indexofnode
D.4 eg:stringpad
D.5 eg:distinctnodesstable
D.6 Finding
minima and maxima
D.6.1 eg:highest
D.6.2 eg:lowest
D.7 Sorting
E Checklist of implementationdefined
features (NonNormative)
F Changes since previous Recommendation
(NonNormative)
F.1 Substantive changes (15 December
2009)
F.2 Substantive changes (current
draft)
F.3 Incompatibilities
F.4 Editorial
changes
G Function and Operator Quick Reference
(NonNormative)
G.1 Functions
and Operators by Section
G.2 Functions and
Operators Alphabetically
The purpose of this document is to catalog the functions and operators required for XPath 3.0, XQuery 3.0 and XSLT 3.0. The exact syntax used to call these functions and operators is specified in [XML Path Language (XPath) 3.0], [XQuery 3.0: An XML Query Language] and [XSL Transformations (XSLT) Version 3.0].
This document defines constructor functions and functions that take typed values as arguments. Some of the functions define the semantics of operators discussed in [XML Path Language (XPath) 3.0] and [XQuery 3.0: An XML Query Language].
[XML Schema Part 2: Datatypes Second Edition] defines a number of primitive and derived datatypes, collectively known as builtin datatypes. This document defines functions and operations on these datatypes as well as the datatypes defined in Section Types^{DM30} of the [XQuery and XPath Data Model (XDM) 3.0]. These functions and operations are defined for use in [XML Path Language (XPath) 3.0], [XQuery 3.0: An XML Query Language] and [XSL Transformations (XSLT) Version 3.0] and related XML standards. This document also defines functions and operators on nodes and node sequences as defined in the [XQuery and XPath Data Model (XDM) 3.0] for use in [XML Path Language (XPath) 3.0], [XQuery 3.0: An XML Query Language] and [XSL Transformations (XSLT) Version 3.0] and other related XML standards.
[XML Schema 1.1 Part 2: Datatypes]
adds to the data types defined in [XML
Schema Part 2: Datatypes Second Edition]. It introduces a new
primitive type xs:precisionDecimal
which at the time
of writing is not supported by any functions or operators in this
specification. It also introduces a new derived type
xs:dateTimeStamp
which is supported, and it
incorporates as builtin types the two types
xs:yearMonthDuration
and
xs:dayTimeDuration
which were previously XDM additions
to the type system. In addition, XSD 1.1 clarifies and updates many
aspects of the definitions of the existing data types: for example,
it extends the value space of xs:double
to allow both
positive and negative zero; it modifies the value space of
xs:Name
to permit additional Unicode characters; it
allows year zero and disallows leap seconds in
xs:dateTime
values; and it allows any character string
to appear as the value of an xs:anyURI
item.
Implementations of this specification may support
either XSD 1.0 or XSD 1.1 or both.
References to specific sections of some of the above documents are indicated by crossdocument links in this document. Each such link consists of a pointer to a specific section followed a superscript specifying the linked document. The superscripts have the following meanings: 'XQ' [XQuery 3.0: An XML Query Language], 'XT' [XSL Transformations (XSLT) Version 3.0], 'XP' [XML Path Language (XPath) 3.0], and 'DM' [XQuery and XPath Data Model (XDM) 3.0].
The Functions and Operators specification is intended primarily as a component that can be used by other specifications. Therefore, Functions and Operators relies on specifications that use it (such as [XML Path Language (XPath) 3.0], [XSL Transformations (XSLT) Version 3.0] and [XQuery 3.0: An XML Query Language]) to specify conformance criteria for their respective environments.
Authors of conformance criteria for the use of the Functions and Operators should pay particular attention to the following features:
It is ·implementationdefined· which version of Unicode is supported, but it is recommended that the most recent version of Unicode be used.
It is ·implementationdefined· whether the type system is based on XML Schema 1.0 or XML Schema 1.1.
Support for XML 1.0 and XML 1.1 by the datatypes used in Functions and Operators.
Note:
At the time of writing there is a Candidate Recommendation of
XML Schema 1.1 that introduces some new data types including
xs:precisionDecimal
and xs:dateTimeStamp
.
This specification provides some limited support for the latter,
but does not yet include support for
xs:precisionDecimal
. This is likely to come in a later
draft of this specification. Furthermore, XSD 1.1 includes the
option of supporting revised definitions of types such as
xs:NCName
based on the rules in XML 1.1 rather than
1.0. The rules affecting support for XSD 1.0 versus XSD 1.1 and XML
1.0 versus XML 1.1 are likely to be refined in later drafts of this
specification.
In this document, text labeled as an example or as a Note is provided for explanatory purposes and is not normative.
The functions and operators discussed in this document are
contained in one of several namespaces (see [Namespaces in XML]) and referenced using an
xs:QName
.
This document uses conventional prefixes to refer to these
namespaces. Userwritten applications can choose a different prefix
to refer to the namespace, so long as it is bound to the correct
URI. The host language may also define a default namespace for
function calls, in which case function names in that namespace need
not be prefixed at all. In many cases the default namespace will be
http://www.w3.org/2005/xpathfunctions
, allowing a
call on the fn:name
function
(for example) to be written as name()
rather than
fn:name()
; in this document,
however, all example function calls are explicitly prefixed.
The URIs of the namespaces and the conventional prefixes associated with them are:
http://www.w3.org/2001/XMLSchema
for constructors
 associated with xs
.
The datatypes and constructor functions for the builtin
datatypes defined in [XML Schema Part 2:
Datatypes Second Edition] and in Section
Types^{DM30} of [XQuery and XPath Data Model (XDM) 3.0]
and discussed in 17 Constructor
functions are in the XML Schema namespace,
http://www.w3.org/2001/XMLSchema
, and named in this
document using the xs
prefix.
http://www.w3.org/2005/xpathfunctions
for
functions — associated with fn
.
The namespace prefix used in this document for most functions
that are available to users is fn
.
http://www.w3.org/2005/xpathfunctions/math
for
functions — associated with math
.
This namespace is used for some mathematical functions. The
namespace prefix used in this document for these functions is
math
. These functions are available to users in
exactly the same way as those in the fn
namespace.
http://www.w3.org/2005/xqterrors
— associated with
err
.
There are no functions in this namespace; it is used for error codes.
This document uses the prefix err
to represent the
namespace URI http://www.w3.org/2005/xqterrors
, which
is the namespace for all XPath and XQuery error codes and messages.
This namespace prefix is not predeclared and its use in this
document is not normative.
Note:
The namespace URI associated with the err
prefix is
not expected to change from one version of this document to
another. The contents of this namespace may be extended to allow
additional errors to be returned.
Functions defined with the op
prefix are described
here to underpin the definitions of the operators in [XML Path Language (XPath) 3.0], [XQuery 3.0: An XML Query Language] and [XSL Transformations (XSLT) Version 3.0]. These
functions are not available directly to users, and there is no
requirement that implementations should actually provide these
functions. For this reason, no namespace is associated with the
op
prefix. For example, multiplication is generally
associated with the *
operator, but it is described as
a function in this document:
op:numericmultiply
($arg1
as
numeric
,
$arg2
as
numeric
) as
numeric
In general, the specifications named above do not support
function overloading in the sense that functions that have multiple
signatures with the same name and the same number of parameters are
not supported. Consequently, there are no such overloaded functions
in this document except for legacy [XML Path
Language (XPath) Version 1.0] functions such as fn:string
, which accepts a single
parameter of a variety of types. In addition, it should be noted
that the functions defined in 4
Functions and operators on numerics that accept
numeric
parameters accept arguments of type
xs:integer
, xs:decimal
,
xs:float
or xs:double
. See 1.4 Function signatures and
descriptions. Operators such as "+" may be overloaded. This
document does define some functions with more than one signature
with the same name and different number of parameters. Userdefined
functions with more than one signature with the same name and
different number of parameters are also supported.
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:functionname
($parametername
as
parametertype
,
...) as
returntype
In this notation, functionname, in boldface, 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 nonnormative, name. If there are two or more
parameter declarations, they are separated by a comma. The
returntype
, also in italics, specifies the
static type of the value returned by the function. The dynamic type
of the value returned by the function is the same as its static
type or derived from the static type. All parameter types and
return types are specified using the SequenceType notation defined
in Section
2.5.3 SequenceType Syntax^{XP}.
One function, fn:concat
,
has a variable number of arguments (two or more). More strictly,
there is an infinite set of functions having the name fn:concat
, with arity ranging from
2 to infinity. For this special case, a single function signature
is given, with an ellipsis indicating an indefinite number of
arguments.
In some cases the word " numeric
" is used in
function signatures as a shorthand to indicate the four numeric
types: xs:integer
, xs:decimal
,
xs:float
and xs:double
. For example, a
function with the signature:
fn:numericfunction
($arg
as
numeric
) as
...
represents the following four function signatures:
fn:numericfunction
($arg
as
xs:integer
) as
...
fn:numericfunction
($arg
as
xs:decimal
) as
...
fn:numericfunction
($arg
as
xs:float
) as
...
fn:numericfunction
($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 [the Formal Semantics].
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:timezonefromdateTime
.
Rules for passing parameters to operators are described in the
relevant sections of [XQuery 3.0: An XML Query
Language] and [XML Path Language (XPath)
3.0]. For example, the rules for passing parameters to
arithmetic operators are described in Section 3.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:functionname
($parametername
as
parametertype?
) as
returntype?
Note that this function signature is different from a signature
in which the parameter is omitted. See, for example, the two
signatures for fn:string
.
In the first signature, the parameter is omitted and the argument
defaults to the context item, referred to as ".". In the second
signature, the argument must be present but may be the empty
sequence, written as ()
.
Some functions accept a sequence of zero or more values as an
argument. This is indicated by following the name of the type of
the items in the sequence with *
. The sequence may
contain zero or more items of the named type. For example, the
function below accepts a sequence of xs:double
and
returns a xs:double
or the empty sequence.
fn:median
($arg
as
xs:double*
) as
xs:double?
The diagrams below show how nodes, function items, primitive simple types, and user defined types fit together into a type system. This type system comprises two distinct hierarchies that both include the primitive simple types. In the diagrams, connecting lines represent relationships between derived types and the types from which they are derived; the arrowheads point toward the type from which they are derived. The dashed line represents relationships not present in this diagram, but that appear in one of the other diagrams. Dotted lines represent additional relationships that follow an evident pattern. The information that appears in each diagram is recapitulated in tabular form.
The xs:IDREFS
, xs:NMTOKENS
, and
xs:ENTITIES
types and the userdefined list and
union types
are special types in that these types are lists
or unions rather than types derived by extension or
restriction.
The first diagram and its corresponding table illustrate the "item" type hierarchy. In XDM, items include node types, function types, and builtin atomic types.
In the table, each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.
item  
xs:anyAtomicType  
node  
attribute  
userdefined attribute types  
comment  
document  
userdefined document types  
element  
userdefined element types  
processinginstruction  
text 
The next diagram and table illustrate the "any type" type
hierarchy, in which all types are derived from distinguished type
xs:anyType
.
In the table, each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.
xs:anyType  
userdefined complex types  
xs:untyped  
xs:anySimpleType  
userdefined list and union types  
xs:IDREFS  
xs:NMTOKENS  
xs:ENTITIES  
xs:anyAtomicType 
The final diagram and table show all of the atomic types, including the primitive simple types and the builtin types derived from the primitive simple types. This includes all the builtin datatypes defined in [XML Schema Part 2: Datatypes Second Edition] as well as the two totally ordered subtypes of duration defined in 8.1 Two totally ordered subtypes of duration.
In the table, each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.
xs:untypedAtomic  
xs:dateTime  
xs:dateTimeStamp  
xs:date  
xs:time  
xs:duration  
xs:yearMonthDuration  
xs:dayTimeDuration  
xs:float  
xs:double  
xs:precisionDecimal  
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 terminology used to describe the functions and operators on [XML Schema Part 2: Datatypes Second Edition] is defined in the body of this specification. The terms defined in this section are used in building those definitions
This document uses the terms string
,
character
, and codepoint
with the
following meanings:
[Definition] A character is an instance of the Char^{XML} production of [RECxml].
Note:
This definition excludes Unicode characters in the surrogate blocks as well as xFFFE and xFFFF, while including characters with codepoints greater than xFFFF which some programming languages treat as two characters. The valid characters are defined by their codepoints, and include some whose codepoints have not been assigned by the Unicode consortium to any character.
[Definition] A string is a sequence of zero or
more ·characters·, or equivalently, a value in the value space
of the xs:string
data type.
[Definition] A codepoint is a nonnegative integer assigned to a ·character· by the Unicode consortium, or reserved for future assignment to a character.
Note:
The set of codepoints is thus wider than the set of characters.
This specification spells "codepoint" as one word; the Unicode specification spells it as "code point". Equivalent terms found in other specifications are "character number" or "code position". See [Character Model for the World Wide Web 1.0: Fundamentals]
Because these terms appear so frequently, they are hyperlinked to the definition only when there is a particular desire to draw the reader's attention to the definition; the absence of a hyperlink does not mean that the term is being used in some other sense.
It is ·implementationdefined· which version of [The Unicode Standard] is supported, but it is recommended that the most recent version of Unicode be used.
Unless explicitly stated, the xs:string
values
returned by the functions in this document are not normalized in
the sense of [Character Model for the World Wide
Web 1.0: Fundamentals].
Notes:
In functions that involve character counting such as fn:substring
, fn:stringlength
and
fn:translate
, what is
counted is the number of XML ·characters· in the
string (or equivalently, the number of Unicode codepoints). Some
implementations may represent a codepoint above xFFFF using two
16bit values known as a surrogate pair. A surrogate pair counts as
one character, not two.
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 "expandedQName" defined below.
[Definition] An expandedQName 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:localname).
The term URI is used as follows:
[Definition] Within this specification, the term
URI refers to Universal Resource Identifiers as defined in
[RFC 3986] and extended in [RFC 3987] with a new name IRI. The term
URI Reference, unless otherwise stated, refers to a string
in the lexical space of the xs:anyURI
datatype as
defined in [XML Schema Part 2: Datatypes
Second Edition].
Note:
Note that this means, in practice, that where this specification
requires a "URI Reference", an IRI as defined in [RFC 3987] will be accepted, provided that other
relevant specifications also permit an IRI. The term URI has been
retained in preference to IRI to avoid introducing new names for
concepts such as "Base URI" that are defined or referenced across
the whole family of XML specifications. Note also that the
definition of xs:anyURI
is a wider definition than the
definition in [RFC 3987]; for example it
does not require nonASCII characters to be escaped.
A feature of this specification included to ensure that implementations that use this feature remain compatible with [XML Path Language (XPath) Version 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 either nonconformant or else in error.
Possibly differing between implementations, but specified and documented 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.
This section is concerned with the question of whether two calls on a function, with the same arguments, may produce different results.
[Definition] Two function calls are said to be within the same execution scope if the host environment defines them as such. In XSLT, any two calls executed during the same transformation are in the same execution scope. In XQuery, any two calls executed during the evaluation of a toplevel expression are in the same execution scope. In other contexts, the execution scope is specified by the host environment that invokes the function library.
The following definition explains more precisely what it means for two function calls to return the same result:
[Definition] Two values are defined to be identical if they contain the same number of items and the items are pairwise identical. Two items are identical if and only if one of the following conditions applies:
Both items are atomic values, of precisely the same type, and
the values are equal as defined using the eq
operator,
using the Unicode codepoint collation when comparing strings
Both items are nodes, and represent the same node
Both items are function items, and have the same name (or absence of a name), arity, function signature, and closure
Some functions produce results that depend not only on their explicit arguments, but also on the static and dynamic context.
[Definition] A function may have the property of being contextdependent: the result of such a function depends on the values of properties in the static and dynamic evaluation context as well as on the actual supplied arguments (if any).
Contextdependent functions fall into a number of categories:
The functions fn:currentdate
, fn:currentdateTime
,
fn:currenttime
,
fn:implicittimezone
,
fn:adjustdatetotimezone
,
fn:adjustdateTimetotimezone
,
and fn:adjusttimetotimezone
depend on properties of the dynamic context that are fixed within
the ·execution
scope·. The same applies to a number
of functions in the op:
namespace that manipulate
dates and times and that make use of the implicit timezone. These
functions will return the same result if called repeatedly during a
single ·execution
scope·.
The functions fn:position
, fn:last
, fn:id
, fn:idref
, fn:elementwithid
,
fn:lang
, fn:localname
, fn:name
, fn:namespaceuri
, fn:normalizespace
,
fn:number
, fn:root
, fn:string
, and fn:stringlength
depend on
the focus. These functions will in general return different results
on different calls if the focus is different.
[Definition] A function is focusdependent if its result depends on the focus (that is, the context item, position, or size).
Functions that are focusdependent cannot be used as
function items. For example the expression fn:map($sequence, fn:id#1)
is not
allowed, because the function fn:id
is focusdependent.
The function fn:defaultcollation
and
many stringhandling operators and functions depend on the default
collation and the inscope collations, which are both properties of
the static context. If a particular call of one of these functions
is evaluated twice with the same arguments then it will return the
same result each time (because the static context, by definition,
does not change at run time). However, two distinct calls (that is,
two calls on the function appearing in different places in the
source code) may produce different results even if the explicit
arguments are the same.
Functions such as fn:staticbaseuri
,
fn:doc
, and fn:collection
depend on other
aspects of the static context. As with functions that depend on
collations, a single call will produce the same results on each
call if the explicit arguments are the same, but two calls
appearing in different places in the source code may produce
different results.
[Definition] For a ·contextdependent· function, the parts of the context on which it depends are referred to as implicit arguments.
[Definition] A function that is guaranteed to produce ·identical· results from repeated calls if the explicit and implicit arguments are identical is referred to as deterministic.
All functions defined in this specification are ·deterministic· unless otherwise stated. Exceptions include the following:
Some functions (such as fn:distinctvalues
and
fn:unordered
) produce
results in an ·implementationdefined· or ·implementationdependent·order. In such cases there is no guarantee that
the order of results from different calls will be the same. These
functions are said to be nondeterministic with respect to
ordering.
The function fn:analyzestring
constructs an element node to represent its results. There is no
guarantee that repeated calls with the same arguments will return
the same identical node (in the sense of the is
operator). However, if nonidentical nodes are returned, their
content will be the same in the sense of the fn:deepequal
function. Such a
function is said to be nondeterministic with respect to node
identity.
Some functions (such as fn:doc
and fn:collection
) create new nodes
by reading external documents. Such functions are guaranteed to be
·deterministic· with
the exception that an implementation is allowed to make them
nondeterministic as a user option.
Where the results of a function are described as being (to a greater or lesser extent) ·implementationdefined· or ·implementationdependent·, this does not by itself remove the requirement that the results should be deterministic: that is, that repeated calls with the same explicit and implicit arguments must return identical results.
Accessors and their semantics are described in [XQuery and XPath Data Model (XDM) 3.0]. Some of these accessors are exposed to the user through the functions described below.
Function  Accessor  Accepts  Returns 

fn:nodename 
nodename 
an optional node  zero or one xs:QName 
fn:nilled 
nilled 
a node  an optional xs:boolean 
fn:string 
stringvalue 
an optional item or no argument  xs:string 
fn:data 
typedvalue 
zero or more items  a sequence of atomic values 
fn:baseuri 
baseuri 
an optional node or no argument  zero or one xs:anyURI 
fn:documenturi 
documenturi 
an optional node  zero or one xs:anyURI 
Returns the name of a node, as an xs:QName
.
fn:nodename
() as
xs:QName?
fn:nodename
($arg
as
node()?
) as
xs:QName?
If the argument is omitted, it defaults to the context item
(.
). The behavior of the function if the argument is
omitted is exactly the same as if the context item had been passed
as the argument.
If $arg
is the empty sequence, the empty sequence
is returned.
Otherwise, the function returns the result of the
dm:nodename
accessor as defined in [XQuery and XPath Data Model (XDM) 3.0]
(see Section
nodename Accessor^{DM30}).
For element and attribute nodes, the name of the node is
returned as an xs:QName
, retaining the prefix,
namespace URI, and local part.
For processing instructions, the name of the node is returned as
an xs:QName
in which the prefix and namespace URI are
absent.
For a namespace node, the function returns an empty sequence if
the node represents the default namespace; otherwise it returns an
xs:QName
in which prefix and namespace URI are absent
and the local part is the the namespace prefix being bound).
For all other kinds of node, the function returns the empty sequence.
Returns true for an element that is nilled.
fn:nilled
($arg
as
node()?
) as
xs:boolean?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise the function returns the result of the
dm:nilled
accessor as defined in [XQuery and XPath Data Model (XDM) 3.0]
(see Section nilled
Accessor^{DM30}).
If $arg
is not an element node, the function
returns the empty sequence.
If $arg
is an untyped element node, the function
returns false.
In practice, the function returns true
only for an
element node that has the attribute xsi:nil="true"
and
that is successfully validated against a schema that defines the
element to be nillable; the detailed rules, however, are defined in
[XQuery and XPath Data Model (XDM)
3.0].
Returns the value of $arg
represented as an
xs:string
.
fn:string
() as
xs:string
fn:string
($arg
as
item()?
) as
xs:string
In the zeroargument version of the function, $arg
defaults to the context item. That is, calling
fn:string()
is equivalent to calling
fn:string(.)
.
If $arg
is the empty sequence, the function returns
the zerolength string.
If $arg
is a node, the function returns the
stringvalue of the node, as obtained using the
dm:stringvalue
accessor defined in [XQuery and XPath Data Model (XDM) 3.0]
(see Section
stringvalue Accessor^{DM30}).
If $arg
is an atomic value, the function returns
the result of the expression $arg cast as xs:string
(see 18 Casting).
In the zeroargument version of the function, if the context item is absent, error [err:XPDY0002]^{XP} is raised.
If $arg
is a function item, error [err:FOTY0014] is
raised.
The expression string(23)
returns
"23"
.
The expression string(false())
returns
"false"
.
The expression string("Paris")
returns
"Paris"
.
let $para
:=
<para>In a hole in the ground there lived a <term author="Tolkein">hobbit</term>.</para>
The expression string($para)
returns "In a
hole in the ground there lived a hobbit."
.
Returns the result of atomizing a sequence, that is, replacing all nodes in the sequence by their typed values.
fn:data
() as
xs:anyAtomicType*
fn:data
($arg
as
item()*
) as
xs:anyAtomicType*
If the argument is omitted, it defaults to the context item
(.
). The behavior of the function if the argument is
omitted is exactly the same as if the context item had been passed
as the argument.
The result of fn:data
is the sequence of atomic
values produced by applying the following rules to each item in
$arg
:
If the item is an atomic value, it is appended to the result sequence.
If the item is a node, the typed value of the node is appended
to the result sequence. The typed value is a sequence of zero or
more atomic values: specifically, the result of the
dm:typedvalue
accessor as defined in [XQuery and XPath Data Model (XDM) 3.0]
(See Section
typedvalue Accessor^{DM30}).
If an item in the sequence $arg
is a node that does
not have a typed value then an error is raised [err:FOTY0012].
If an item in the sequence $arg
is a function item
then an error is raised [err:FOTY0013].
The process of applying the fn:data
function to a
sequence is referred to as atomization
. In many cases
an explicit call on fn:data
is not required, because
atomization is invoked implicitly when a node or sequence of nodes
is supplied in a context where an atomic value or sequence of
atomic values is required.
Returns the base URI of a node.
fn:baseuri
() as
xs:anyURI?
fn:baseuri
($arg
as
node()?
) as
xs:anyURI?
The zeroargument version of the function returns the base URI
of the context node: it is equivalent to calling
fn:baseuri(.)
. This may result in an error being
raised: if the context item is absent [err:XPDY0002]^{XP}; if
the context item is not a node [err:XPTY0004]^{XP}.
The singleargument version of the function behaves as follows:
$arg
is the empty sequence, the function
returns the empty sequence.dm:baseuri
accessor applied to the node
$arg
. This accessor is defined, for each kind of node,
in the XDM specification (See Section
baseuri Accessor^{DM30}).Note:
As explained in XDM, document, element and processinginstruction nodes have a baseuri property which may be empty. The baseuri property for all other node kinds is the empty sequence. The dm:baseuri accessor returns the baseuri property of a node if it exists and is nonempty; otherwise it returns the result of applying the dm:baseuri accessor to its parent, recursively. If the node does not have a parent, or if the recursive ascent up the ancestor chain encounters a parentless node whose baseuri property is empty, the empty sequence is returned. In the case of namespace nodes, however, the result is always an empty sequence  it does not depend on the base URI of the parent element.See also fn:staticbaseuri
.
If $arg
is not specified, the following errors may
be raised: if the context item is absent [err:XPDY0002]^{XP}; if
the context item is not a node [err:XPTY0004]^{XP}.
Returns the URI of a resource where a document can be found, if available.
fn:documenturi
() as
xs:anyURI?
fn:documenturi
($arg
as
node()?
) as
xs:anyURI?
If the argument is omitted, it defaults to the context item
(.
). The behavior of the function if the argument is
omitted is exactly the same as if the context item had been passed
as the argument.
If $arg
is the empty sequence, the function returns
the empty sequence.
If $arg
is not a document node, the function
returns the empty sequence.
Otherwise, the function returns the value of the
documenturi
accessor applied to $arg
, as
defined in [XQuery and XPath Data
Model (XDM) 3.0] (See Section
Accessors^{DM30}).
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:documenturi($D)
returns the empty sequence, or that the following expression is
true: fn:doc(fn:documenturi($D))
is
$D
. It is implementationdefined 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.
In this document, as well as in [XQuery
3.0: An XML Query Language] and [XML Path
Language (XPath) 3.0], the phrase "an error is raised" is used.
Raising an error is equivalent to calling the fn:error
function defined in this
section with the provided error code.
The above phrase is normally accompanied by specification of a
specific error, to wit: "an error is raised [error code]".
Each error defined in this document is identified by an
xs:QName
that is in the
http://www.w3.org/2005/xqterrors
namespace,
represented in this document by the err
prefix. It is
this xs:QName
that is actually passed as an argument
to the fn:error
function.
Calling this function raises an error. For a more detailed
treatment of error handing, see Section 2.3.3
Handling Dynamic Errors^{XP}.
The fn:error
function is
a general function that may be called as above but may also be
called from [XQuery 3.0: An XML Query
Language] or [XML Path Language (XPath)
3.0] applications with, for example, an xs:QName
argument.
Calling the fn:error
function raises an
applicationdefined error.
fn:error
() as
none
fn:error
($code
as
xs:QName
) as
none
fn:error
($code
as
xs:QName?
,
$description
as
xs:string
) as
none
fn:error ( 
$code 
as xs:QName? , 
$description 
as xs:string , 

$errorobject 
as item()* ) as none 
This function never returns a value. Instead it always raises an error. The effect of the error is identical to the effect of dynamic errors raised implicitly, for example when an incorrect argument is supplied to a function.
The parameters to the fn:error
function supply
information that is associated with the error condition and that is
made available to a caller that asks for information about the
error. The error may be caught either by the host language (using a
try/catch construct in XSLT or XQuery, for example), or by the
calling application or external processing environment. The way in
which error information is returned to the external processing
environment is ·implementation dependent·
If fn:error
is called with no arguments, then its
behavior is the same as the function call:
fn:error(fn:QName('http://www.w3.org/2005/xqterrors', 'err:FOER0000'))
If $code
is the empty sequence then the effective
value is the xs:QName
constructed by:
fn:QName('http://www.w3.org/2005/xqterrors', 'err:FOER0000')
There are three pieces of information that may be associated with an error:
The $code
is an error code that distinguishes this
error from others. It is an xs:QName
; the namespace
URI conventionally identifies the component, subsystem, or
authority responsible for defining the meaning of the error code,
while the local part identifies the specific error condition. The
namespace URI http://www.w3.org/2005/xqterrors
is
used for errors defined in this specification; other namespace URIs
may be used for errors defined by the application.
If the external processing environment expects the error code to
be returned as a URI or a string rather than as an
xs:QName
, then an error code with namespace URI
NS
and local part LP
will be returned in
the form NS#LP
. The namespace URI part of the error
code should therefore not include a fragment identifier.
The $description
is a naturallanguage description
of the error condition.
The $errorobject
is an arbitrary value used to
convey additional information about the error, and may be used in
any way the application chooses.
This function always raises an error.
The value of the $description
parameter may need to
be localized.
The type "none" is a special type defined in [XQuery 1.0 and XPath 2.0 Formal Semantics] and is not available to the user. It indicates that the function never returns and ensures that it has the correct static type.
fn:error()
returns
http://www.w3.org/2005/xqterrors#FOER0000
(or the
corresponding xs:QName
) to the external processing
environment, unless the error is caught using a try/catch construct
in the host language.
fn:error(fn:QName('http://www.example.com/HR',
'myerr:toohighsal'), 'Does not apply because salary is too
high')
returns
http://www.example.com/HR#toohighsal
and the
xs:string
"Does not apply because salary is too
high"
(or the corresponding xs:QName
) to the
external processing environment, unless the error is caught using a
try/catch construct in the host language.
Provides an execution trace intended to be used in debugging queries.
fn:trace
($value
as
item()*
,
$label
as
xs:string
) as
item()*
The function returns the value of $value
,
unchanged.
In addition, the values of $value
, converted to an
xs:string
, and $label
may be directed to a trace data set. The
destination of the trace output is ·implementationdefined·. The format of the trace output is ·implementation dependent·. The ordering of output from calls of the
fn:trace
function is ·implementation dependent·.
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.
This section specifies arithmetic operators on the numeric datatypes defined in [XML Schema Part 2: Datatypes Second Edition]. It uses an approach that permits lightweight implementation whenever possible.
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 7541985]
arithmetic for xs:float
and xs:double
values. One consequence of this is that some operations
result in the value NaN
(nota number), which has the
unusual property that it is not equal to itself. Another
consequence is that some operations return the value negative
zero. This differs from [XML Schema
Part 2: Datatypes Second Edition] which defines
NaN
as being equal to itself and defines only a single
zero in the value space. The text accompanying several functions
defines behavior for both positive and negative zero inputs and
outputs in the interest of alignment with [IEEE
7541985]. A conformant implementation must respect these
semantics. In consequence, the expression 0.0e0
(which is actually a unary minus operator applied to an
xs:double
value) will always return negative zero: see
4.2.8
op:numericunaryminus. As a concession to implementations
that rely on implementations of XSD 1.0, however, when casting from
string to double the lexical form 0
may be converted to positive zero, though negative
zero is recommended.
XML Schema 1.1 introduces support for positive and negative zero
as distinct values, and also uses the [IEEE
7541985] semantics for comparisons involving
NaN
.
The following functions define the semantics of arithmetic operators defined in [XQuery 3.0: An XML Query Language] and [XML Path Language (XPath) 3.0] on these numeric types.
Operators  Meaning 

op:numericadd 
Addition 
op:numericsubtract 
Subtraction 
op:numericmultiply 
Multiplication 
op:numericdivide 
Division 
op:numericintegerdivide 
Integer division 
op:numericmod 
Modulus 
op:numericunaryplus 
Unary plus 
op:numericunaryminus 
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:numericdivide
, which
returns an xs:decimal
if called with two
xs:integer
operands and op:numericintegerdivide
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:numericdivide(integer,
integer) , which returns xs:decimal ) 
op:operation(xs:decimal, xs:decimal) 
xs:decimal 
op:operation(xs:float, xs:float) 
xs:float 
op:operation(xs:double, xs:double) 
xs:double 
op:operation(xs:integer) 
xs:integer 
op:operation(xs:decimal) 
xs:decimal 
op:operation(xs:float) 
xs:float 
op:operation(xs:double) 
xs:double 
These rules define any operation on any pair of arithmetic types. Consider the following example:
op:operation(xs:int, xs:double) => op:operation(xs:double, xs:double)
For this operation, xs:int
must be converted to
xs:double
. This can be done, since by the rules above:
xs:int
can be substituted for xs:integer
,
xs:integer
can be substituted for
xs:decimal
, xs:decimal
can be promoted to
xs:double
. As far as possible, the promotions should
be done in a single step. Specifically, when an
xs:decimal
is promoted to an xs:double
,
it should not be converted to an xs:float
and then to
xs:double
, as this risks loss of precision.
As another example, a user may define height
as a
derived type of xs:integer
with a minimum value of 20
and a maximum value of 100. He may then derive
fenceHeight
using an enumeration to restrict the
permitted set of values to, say, 36, 48 and 60.
op:operation(fenceHeight, xs:integer) => op:operation(xs:integer, xs:integer)
fenceHeight
can be substituted for its base type
height
and height
can be substituted for
its base type xs:integer
.
The basic rules for addition, subtraction, and multiplication of
ordinary numbers are not set out in this specification; they are
taken as given. In the case of xs:double
and
xs:float
the rules are as defined in [IEEE 7541985]. The rules for handling division and
modulus operations, as well as the rules for handling special
values such as infinity and NaN
, and exception
conditions such as overflow and underflow, are described more
explicitly since they are not necessarily obvious.
On overflow and underflow situations during arithmetic operations conforming implementations ·must· behave as follows:
For xs:float
and xs:double
operations,
overflow behavior ·must· be conformant with [IEEE
7541985]. 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) noninfinite number.
For xs:float
and xs:double
operations,
underflow behavior ·must· be conformant with [IEEE
7541985]. 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 limitedprecision integer operations ·must· select from the following options:
They ·may· choose to always raise an error [err:FOAR0002].
They ·may· provide an ·implementationdefined· 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:numericadd
, op:numericsubtract
,
op:numericmultiply
,
op:numericdivide
,
op:numericintegerdivide
and op:numericmod
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:numericunaryplus
and op:numericunaryminus
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 ·implementationdefined·. 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 ·implementationdefined· manner.
The [IEEE 7542008] specification
also describes handling of two exception conditions called
divideByZero
and invalidOperation
. The
IEEE divideByZero
exception is raised not only by a
direct attempt to divide by zero, but also by operations such as
log(0)
. The IEEE invalidOperation
exception is raised by attempts to invoke a function on an argument
that is outside the function's domain (for example,
sqrt(1)
or log(1)
. These IEEE
exceptions do not cause a dynamic error at the application level;
rather they result in the relevant function or operator returning
NaN
. The underlying IEEE exception
may be notified to the application or to the user
by some ·implementationdefined· warning condition, but the observable effect
on an application using the functions and operators defined in this
specification is simply to return NaN
with no
error.
The [IEEE 7542008] specification
distinguishes two NaN values, a quiet NaN and a signaling NaN.
These two values are not distinguishable in the XDM model: the
value spaces of xs:float
and xs:double
each include only a single NaN
value. This does not
prevent the implementation distinguishing them internally, and
triggering different ·implementationdefined· warning conditions, but such distinctions do
not affect the observable behavior of an application using the
functions and operators defined in this specification.
Returns the arithmetic sum of its operands: ($arg1 +
$arg2
).
Defines the semantics of the "+" operator applied to numeric values
op:numericadd
($arg1
as
numeric
,
$arg2
as
numeric
) as
numeric
General rules: see 4.2 Arithmetic operators on numeric values.
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.
Returns the arithmetic difference of its operands: ($arg1
 $arg2
).
Defines the semantics of the "" operator applied to numeric values.
op:numericsubtract
($arg1
as
numeric
,
$arg2
as
numeric
) as
numeric
General rules: see 4.2 Arithmetic operators on numeric values.
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.
Returns the arithmetic product of its operands: ($arg1 *
$arg2
).
Defines the semantics of the "*" operator applied to numeric values.
op:numericmultiply
($arg1
as
numeric
,
$arg2
as
numeric
) as
numeric
General rules: see 4.2 Arithmetic operators on numeric values.
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 nonzero
number and the other is an infinity, an infinity with the
appropriate sign is returned.
Returns the arithmetic quotient of its operands: ($arg1
div $arg2
).
Defines the semantics of the "div" operator applied to numeric values.
op:numericdivide
($arg1
as
numeric
,
$arg2
as
numeric
) as
numeric
General rules: see 4.2 Arithmetic operators on numeric values.
As a special case, if the types of both $arg1
and
$arg2
are xs:integer
, then the return
type is xs:decimal
.
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 7541985]. 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
.
Performs an integer division.
Defines the semantics of the "idiv" operator applied to numeric values.
op:numericintegerdivide
($arg1
as
numeric
,
$arg2
as
numeric
) as
xs:integer
General rules: see 4.2 Arithmetic operators on numeric values.
If $arg2 is INF or INF, and $arg1 is not INF or INF, then the result is zero.
Otherwise, subject to limits of precision and overflow/underflow
conditions, the result is the largest (furthest from zero)
xs:integer
value $N
such that fn:abs($N * $arg2) le fn:abs($arg1) and
fn:compare($N * $arg2, 0) eq fn:compare($arg1, 0)
.
Note:
The second term in this condition ensures that the result has the correct sign.
The implementation may adopt a different algorithm provided that
it is equivalent to this formulation in all cases where ·implementationdependent· or ·implementationdefined· behavior does not affect the outcome, for
example, the implementationdefined precision of the result of
xs:decimal
division.
If the divisor 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].
Except in situations involving errors, loss of precision, or
overflow/underflow, the result of $a idiv $b
is the
same as ($a div $b) cast as xs:integer
.
The semantics of this function are different from integer division as defined in programming languages such as Java and C++.
The expression op:numericintegerdivide(10,3)
returns 3
.
The expression op:numericintegerdivide(3,2)
returns 1
.
The expression op:numericintegerdivide(3,2)
returns 1
.
The expression op:numericintegerdivide(3,2)
returns 1
.
The expression op:numericintegerdivide(9.0,3)
returns 3
.
The expression op:numericintegerdivide(3.5,3)
returns 1
.
The expression op:numericintegerdivide(3.0,4)
returns 0
.
The expression op:numericintegerdivide(3.1E1,6)
returns 5
.
The expression op:numericintegerdivide(3.1E1,7)
returns 4
.
Returns the remainder resulting from dividing
$arg1
, the dividend, by $arg2
, the
divisor.
Defines the semantics of the "mod" operator applied to numeric values.
op:numericmod
($arg1
as
numeric
,
$arg2
as
numeric
) as
numeric
General rules: see 4.2 Arithmetic operators on numeric values.
The operation a mod b
for operands that are
xs:integer
or xs:decimal
, or types
derived from them, produces a result such that (a idiv
b)*b+(a mod b)
is equal to a
and the magnitude
of the result is always less than the magnitude of b
.
This identity holds even in the special case that the dividend is
the negative integer of largest possible magnitude for its type and
the divisor is 1 (the remainder is 0). It follows from this rule
that the sign of the result is the sign of the dividend.
For xs:float
and xs:double
operands
the following rules apply:
If either operand is NaN
, the result is
NaN
.
If the dividend is positive or negative infinity, or the divisor
is positive or negative zero (0), or both, the result is
NaN
.
If the dividend is finite and the divisor is an infinity, the result equals the dividend.
If the dividend is positive or negative zero and the divisor is finite, the result is the same as the dividend.
In the remaining cases, where neither positive or negative
infinity, nor positive or negative zero, nor NaN
is
involved, the result obeys (a idiv b)*b+(a mod b)
=
a
. Division is truncating division, analogous to
integer division, not [IEEE 7541985]
rounding division i.e. additional digits are truncated, not rounded
to the required precision.
For xs:integer
and xs:decimal
operands, if $arg2
is zero, then an error is raised
[err:FOAR0001].
The expression op:numericmod(10,3)
returns
1
.
The expression op:numericmod(6,2)
returns
0
.
The expression op:numericmod(4.5,1.2)
returns
0.9
.
The expression op:numericmod(1.23E2, 0.6E1)
returns 3.0E0
.
Returns its operand with the sign unchanged: (+
$arg
).
Defines the semantics of the unary "+" operator applied to numeric values.
op:numericunaryplus
($arg
as
numeric
) as
numeric
General rules: see 4.2 Arithmetic operators on numeric values.
The returned value is equal to $arg
, and is an
instance of xs:integer
, xs:decimal
,
xs:double
, or xs:float
depending on the
type of $arg
.
Returns its operand with the sign reversed: (
$arg
).
Defines the semantics of the unary "" operator applied to numeric values.
op:numericunaryminus
($arg
as
numeric
) as
numeric
General rules: see 4.2 Arithmetic operators on numeric values.
The returned value is an instance of xs:integer
,
xs:decimal
, xs:double
, or
xs:float
depending on the type of
$arg
.
For xs:integer
and xs:decimal
arguments, 0
and 0.0
return
0
and 0.0
, respectively. For
xs:float
and xs:double
arguments,
NaN
returns NaN
, 0.0E0
returns 0.0E0
and vice versa. INF
returns INF
. INF
returns
INF
.
This specification defines the following comparison operators on
numeric values. Comparisons take two arguments of the same type. If
the arguments are of different types, one argument is promoted to
the type of the other as described above in 4.2 Arithmetic operators on numeric
values. Each comparison operator returns a boolean value.
If either, or both, operands are NaN
,
false
is returned.
Function  Meaning 

op:numericequal 
Returns true if and only if the value of $arg1 is
equal to the value of $arg2 . 
op:numericlessthan 
Returns true if and only if $arg1 is
numerically less than $arg2 . 
op:numericgreaterthan 
Returns true if and only if $arg1 is
numerically greater than $arg2 . 
Returns true if and only if the value of $arg1
is
equal to the value of $arg2
.
Defines the semantics of the "eq" operator on numeric values, and is also used in defining the semantics of "ne", "le" and "ge".
op:numericequal
($arg1
as
numeric
,
$arg2
as
numeric
) as
xs:boolean
General rules: see 4.2 Arithmetic operators on numeric values and 4.3 Comparison operators on numeric values.
For xs:float
and xs:double
values,
positive zero and negative zero compare equal. INF
equals INF
, and INF
equals
INF
. NaN
does not equal itself.
Returns true
if and only if $arg1
is
numerically less than $arg2
.
Defines the semantics of the "lt" operator on numeric values, and is also used in defining the semantics of "le".
op:numericlessthan
($arg1
as
numeric
,
$arg2
as
numeric
) as
xs:boolean
General rules: see 4.2 Arithmetic operators on numeric values and 4.3 Comparison operators on numeric values.
For xs:float
and xs:double
values,
positive infinity is greater than all other nonNaN
values; negative infinity is less than all other
nonNaN
values. If $arg1
or
$arg2
is NaN
, the function returns
false
.
Returns true
if and only if $arg1
is
numerically greater than $arg2
.
Defines the semantics of the "gt" operator on numeric values, and is also used in defining the semantics of "ge".
op:numericgreaterthan
($arg1
as
numeric
,
$arg2
as
numeric
) as
xs:boolean
The function call op:numericgreaterthan($A, $B)
is defined to return the same result as op:numericlessthan($B,
$A)
The following functions are defined on numeric types. Each function returns a value of the same type as the type of its argument.
If the argument is the empty sequence, the empty sequence is returned.
For xs:float
and xs:double
arguments,
if the argument is "NaN", "NaN" is returned.
Except for fn:abs
, for
xs:float
and xs:double
arguments, if the
argument is positive or negative infinity, positive or negative
infinity is returned.
Function  Meaning 

fn:abs 
Returns the absolute value of $arg . 
fn:ceiling 
Rounds $arg upwards to a whole number. 
fn:floor 
Rounds $arg downwards to a whole number. 
fn:round 
Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near. 
fn:roundhalftoeven 
Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near. 
Note:
fn:round
and fn:roundhalftoeven
produce the same result in all cases except when the argument is
exactly midway between two values with the required precision.
Other ways of rounding midway values can be achieved as follows:
Towards negative infinity: fn:round($x)
Away from zero: fn:round(fn:abs($x))*fn:compare($x,0)
Towards zero: fn:abs(fn:round($x))*fn:compare($x,0)
Returns the absolute value of $arg
.
fn:abs
($arg
as
numeric?
) as
numeric?
General rules: see 4.4 Functions on numeric values.
If $arg
is negative the function returns
$arg
, otherwise it returns $arg
.
If the type of $arg
is one of the four numeric
types xs:float
, xs:double
,
xs:decimal
or xs:integer
the type of the
result is the same as the type of $arg
. If the type of
$arg
is a type derived from one of the numeric types,
the result is an instance of the base numeric type.
For xs:float
and xs:double
arguments,
if the argument is positive zero or negative zero, then positive
zero is returned. If the argument is positive or negative infinity,
positive infinity is returned.
For detailed type semantics, see [Formal Semantics].
The expression fn:abs(10.5)
returns
10.5
.
The expression fn:abs(10.5)
returns
10.5
.
Rounds $arg
upwards to a whole number.
fn:ceiling
($arg
as
numeric?
) as
numeric?
General rules: see 4.4 Functions on numeric values.
The function returns the smallest (closest to negative infinity)
number with no fractional part that is not less than the value of
$arg
.
If the type of $arg
is one of the four numeric
types xs:float
, xs:double
,
xs:decimal
or xs:integer
the type of the
result is the same as the type of $arg
. If the type of
$arg
is a type derived from one of the numeric types,
the result is an instance of the base numeric type.
For xs:float
and xs:double
arguments,
if the argument is positive zero, then positive zero is returned.
If the argument is negative zero, then negative zero is returned.
If the argument is less than zero and greater than 1, negative
zero is returned.
For detailed type semantics, see [Formal Semantics].
The expression fn:ceiling(10.5)
returns
11
.
The expression fn:ceiling(10.5)
returns
10
.
Rounds $arg
downwards to a whole number.
fn:floor
($arg
as
numeric?
) as
numeric?
General rules: see 4.4 Functions on numeric values.
The function returns the largest (closest to positive infinity)
number with no fractional part that is not greater than the value
of $arg
.
If the type of $arg
is one of the four numeric
types xs:float
, xs:double
,
xs:decimal
or xs:integer
the type of the
result is the same as the type of $arg
. If the type of
$arg
is a type derived from one of the numeric types,
the result is an instance of the base numeric type.
For xs:float
and xs:double
arguments,
if the argument is positive zero, then positive zero is returned.
If the argument is negative zero, then negative zero is
returned.
For detailed type semantics, see [Formal Semantics].
The expression fn:floor(10.5)
returns
10
.
The expression fn:floor(10.5)
returns
11
.
Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near.
fn:round
($arg
as
numeric?
) as
numeric?
fn:round
($arg
as
numeric?
, $precision
as
xs:integer
) as
numeric?
General rules: see 4.4 Functions on numeric values.
The function returns the nearest (that is, numerically closest)
value to $arg
that is a multiple of ten to the power
of minus $precision
. If two such values are equally
near (for example, if the fractional part in $arg
is
exactly .5), the function returns the one that is closest to
positive infinity.
If the type of $arg
is one of the four numeric
types xs:float
, xs:double
,
xs:decimal
or xs:integer
the type of the
result is the same as the type of $arg
. If the type of
$arg
is a type derived from one of the numeric types,
the result is an instance of the base numeric type.
The singleargument version of this function produces the same
result as the twoargument version with $precision=0
(that is, it rounds to a whole number).
When $arg
is of type xs:float
and
xs:double
:
If $arg
is NaN, positive or negative zero, or
positive or negative infinity, then the result is the same as the
argument.
For other values, the argument is cast to
xs:decimal
using an implementation of
xs:decimal
that imposes no limits on the number of
digits that can be represented. The function is applied to this
xs:decimal
value, and the resulting
xs:decimal
is cast back to xs:float
or
xs:double
as appropriate to form the function result.
If the resulting xs:decimal
value is zero, then
positive or negative zero is returned according to the sign of
$arg
.
For detailed type semantics, see [Formal Semantics].
This function is typically used with a nonzero
$precision
in financial applications where the
argument is of type xs:decimal
. For arguments of type
xs:float
and xs:double
the results may be
counterintuitive. For example, consider round(35.425e0,
2)
. The result is not 35.43, as might be expected, but
35.42. This is because the conversion of 35.425e0 to
xs:decimal
produces the decimal value
35.42499999999..., which is closer to 35.42 than to 35.43.
The expression fn:round(2.5)
returns
3.0
.
The expression fn:round(2.4999)
returns
2.0
.
The expression fn:round(2.5)
returns
2.0
. (Not the possible alternative,
3
).
The expression fn:round(1.125, 2)
returns
1.13
.
The expression fn:round(8452, 2)
returns
8500
.
The expression fn:round(3.1415e0, 2)
returns
3.14e0
.
Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near.
fn:roundhalftoeven
($arg
as
numeric?
) as
numeric?
fn:roundhalftoeven
($arg
as
numeric?
, $precision
as
xs:integer
) as
numeric?
General rules: see 4.4 Functions on numeric values.
The function returns the nearest (that is, numerically closest)
value to $arg
that is a multiple of ten to the power
of minus $precision
. If two such values are equally
near (e.g. if the fractional part in $arg
is exactly
.500...), the function returns the one whose least significant
digit is even.
If the type of $arg
is one of the four numeric
types xs:float
, xs:double
,
xs:decimal
or xs:integer
the type of the
result is the same as the type of $arg
. If the type of
$arg
is a type derived from one of the numeric types,
the result is an instance of the base numeric type.
The first signature of this function produces the same result as
the second signature with $precision=0
.
For arguments of type xs:float
and
xs:double
:
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
using an implementation of xs:decimal
that imposes no limits on the number of digits that can be
represented. The function is applied to this
xs:decimal
value, and the resulting
xs:decimal
is cast back to xs:float
or
xs:double
as appropriate to form the function result.
If the resulting xs:decimal
value is zero, then
positive or negative zero is returned according to the sign of the
original argument.
For detailed type semantics, see [Formal Semantics].
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
roundhalftoeven(xs:float(150.015), 2)
. The result
is not 150.02 as might be expected, but 150.01. This is because the
conversion of the xs:float
value represented by the
literal 150.015 to an xs:decimal
produces the
xs:decimal
value 150.014999389..., which is closer to
150.01 than to 150.02.
The expression fn:roundhalftoeven(0.5)
returns
0.0
.
The expression fn:roundhalftoeven(1.5)
returns
2.0
.
The expression fn:roundhalftoeven(2.5)
returns
2.0
.
The expression fn:roundhalftoeven(3.567812e+3,
2)
returns 3567.81e0
.
The expression fn:roundhalftoeven(4.7564e3, 2)
returns 0.0e0
.
The expression fn:roundhalftoeven(35612.25, 2)
returns 35600
.
formats an integer according to a given picture string, using the conventions of a given natural language if specified.
fn:formatinteger
($value
as
xs:integer?
,
$picture
as
xs:string
) as
xs:string
fn:formatinteger ( 
$value 
as xs:integer? , 
$picture 
as xs:string , 

$language 
as xs:string ) as xs:string 
If $value
is an empty sequence, the function
returns a zerolength string.
In all other cases, the $picture
argument describes
the format in which $value
is output.
The rules that follow describe how nonnegative numbers are
output. If the value of $value
is negative, the rules
below are applied to the absolute value of $value
, and
the result is prepended with a minus sign.
A picture consists of a primary format token, followed by an optional format modifier.
The primary format token is one of the following:
A decimaldigitpattern made up of optionaldigitsigns, mandatorydigitsigns, and groupingseparatorsigns.
an optionaldigitsign is the character "#".
a mandatorydigitsign is a ·character· in
Unicode category Nd. All mandatorydigitsigns within
the format token must be from the same digit family, where a digit
family is a sequence of ten consecutive characters in Unicode
category Nd, having digit values 0 through 9. Within the format
token, these digits are interchangeable: a threedigit number may
thus be indicated equivalently by 000
,
001
, or 999
.
a groupingseparatorsign is a nonalphanumeric character, that is a ·character· whose Unicode category is other than Nd, Nl, No, Lu, Ll, Lt, Lm or Lo.
There must be at least one mandatorydigitsign. There may be zero or more optionaldigitsigns, and (if present) these must precede all mandatorydigitsigns. There may be zero or more groupingseparatorsigns. A groupingseparatorsign must not appear at the start or end of the decimaldigitpattern, nor adjacent to another groupingseparatorsign.
The corresponding output format is a decimal number, using this
digit family, with at least as many digits as there are
mandatorydigitsigns in the format token. Thus, a
format token 1
generates the sequence 0 1 2 ...
10 11 12 ...
, and a format token 01
(or
equivalently, 00
or 99
) generates the
sequence 00 01 02 ... 09 10 11 12 ... 99 100 101
. A
format token of ١
(ArabicIndic digit one)
generates the sequence ١
then ٢
then
٣
...
The groupingseparatorsigns are handled as follows.
The position of grouping separators within the format token,
counting backwards from the last digit, indicates the position of
grouping separators to appear within the formatted number, and the
character used as the groupingseparatorsign within the
format token indicates the character to be used as the
corresponding grouping separator in the formatted number. If
groupingseparatorsigns appear at regular intervals
within the format token, that is if the same grouping separator
appears at positions forming a sequence N,
2N, 3N, ... for some integer value
N (including the case where there is only one number in
the list), then the sequence is extrapolated to the left, so
grouping separators will be used in the formatted number at every
multiple of N. For example, if the format token is
0'000
then the number one million will be formatted as
1'000'000
, while the number fifteen will be formatted
as 0'015
.
The only purpose of optionaldigitsigns is to mark
the position of groupingseparatorsigns. For example,
if the format token is #'##0
then the number one
million will be formatted as 1'000'000
, while the
number fifteen will be formatted as 15
. A grouping
separator is included in the formatted number only if there is a
digit to its left, which will only be the case if either (a) the
number is large enough to require that digit, or (b) the number of
mandatorydigitsigns in the format token requires
insignificant leading zeros to be present.
Note:
Numbers will never be truncated. Given the
decimaldigitpattern 01
, the number three
hundred will be output as 300
, despite the absence of
any optionaldigitsign.
A format token A
generates the sequence A B C
... Z AA AB AC...
.
A format token a
generates the sequence a b c
... z aa ab ac...
.
A format token i
generates the sequence i ii
iii iv v vi vii viii ix x ...
.
A format token I
generates the sequence I II
III IV V VI VII VIII IX X ...
.
A format token w
generates numbers written as
lowercase words, for example in English, one two three four
...
A format token W
generates numbers written as
uppercase words, for example in English, ONE TWO THREE FOUR
...
A format token Ww
generates numbers written as
titlecase words, for example in English, One Two Three Four
...
Any other format token indicates a numbering sequence in which
that token represents the number 1 (one) (but see the note below).
It is ·implementationdefined· which numbering sequences, additional to those
listed above, are supported. If an implementation does not support
a numbering sequence represented by the given token, it
must use a format token of 1
.
Note:
In some traditional numbering sequences additional signs are added to denote that the letters should be interpreted as numbers; these are not included in the format token. An example, see also the example below, is classical Greek where a dexia keraia and sometimes an aristeri keraia is added.
For all format tokens other than the first kind above (one that
consists of decimal digits), there may be
·implementationdefined· lower and upper bounds on the range of numbers
that can be formatted using this format token; indeed, for some
numbering sequences there may be intrinsic limits. For example, the
format token ①
(circled digit one, ①) has a
range of 1 to 20 imposed by the Unicode character repertoire. For
the numbering sequences described above any upper bound imposed by
the implementation must not be less than 1000 (one
thousand) and any lower bound must not be greater than 1. Numbers
that fall outside this range must be formatted
using the format token 1
.
The above expansions of numbering sequences for format tokens
such as a
and i
are indicative but not
prescriptive. There are various conventions in use for how
alphabetic sequences continue when the alphabet is exhausted, and
differing conventions for how roman numerals are written (for
example, IV
versus IIII
as the
representation of the number 4). Sometimes alphabetic sequences are
used that omit letters such as i
and o
.
This specification does not prescribe the detail of any sequence
other than those sequences consisting entirely of decimal
digits.
Many numbering sequences are languagesensitive. This applies
especially to the sequence selected by the tokens w
,
W
and Ww
. It also applies to other
sequences, for example different languages using the Cyrillic
alphabet use different sequences of characters, each starting with
the letter #x410 (Cyrillic capital letter A). In such cases, the
$language
argument specifies which language's
conventions are to be used; it has the same range of values as
xml:lang
(see [RECxml]). If no
$language
argument is specified, the language that is
used is ·implementationdefined·. The set of languages for which numbering is
supported is ·implementationdefined·. If a language is requested that is not
supported, the processor uses the language that it would use if the
$language
argument were omitted.
The format modifier, if present, is one or more of the following, in any order:
either c
or o
, optionally followed by
a sequence of characters enclosed between parentheses, to indicate
cardinal or ordinal numbering respectively, the default being
cardinal numbering
either a
or t
to indicate alphabetic
or traditional numbering respectively, the default being ·implementationdefined·.
If the o
modifier is present, this indicates a
request to output ordinal numbers rather than cardinal numbers. For
example, in English, when used with the format token
1
, this outputs the sequence 1st 2nd 3rd 4th
...
, and when used with the format token w
outputs the sequence first second third fourth
...
.
In some languages, ordinal numbers vary depending on the
grammatical context, for example they may have different genders
and may decline with the noun that they qualify. In such cases the
string appearing in parentheses after the letter o
may
be used to indicate the variation of the ordinal number required.
The way in which the variation is indicated will depend on the
conventions of the language. For inflected languages that vary the
ending of the word, the preferred approach is to indicate the
required ending, preceded by a hyphen: for example in German,
appropriate values are o(e)
, o(er)
,
o(es)
, o(en)
.
It is ·implementationdefined· what combinations of values of the format token, the language, and the cardinal/ordinal modifier are supported. If ordinal numbering is not supported for the combination of the format token, the language, and the string appearing in parentheses, the request is ignored and cardinal numbers are generated instead.
The specification "1o(º)"
with
$language
equal to it
, if supported,
should produce the sequence:
1º 2º 3º 4º ...
The specification "Wwo"
with $language
equal to it
, if supported, should produce the
sequence:
Primo Secondo Terzo Quarto Quinto ...
The use of the a
or t
modifier disambiguates between numbering sequences that use
letters. In many languages there are two commonly used numbering
sequences that use letters. One numbering sequence assigns numeric
values to letters in alphabetic sequence, and the other assigns
numeric values to each letter in some other manner traditional in
that language. In English, these would correspond to the numbering
sequences specified by the format tokens a
and
i
. In some languages, the first member of each
sequence is the same, and so the format token alone would be
ambiguous. In the absence of the a
or
t
modifier, the default is ·implementationdefined·.
An error is raised [err:FOFI0001] if the $language
argument is supplied as is not castable to
xs:language
.
The expression formatinteger(123, '0000')
returns
"0123"
.
formatinteger(123, 'w')
might return "one
hundred and twentythree"
The expression formatinteger(21, '1o', 'en')
returns "21st"
.
formatinteger(14, 'Wwo(e)', 'de')
might return
"Vierzehnte"
The expression formatinteger(7, 'a')
returns
"g"
.
The expression formatinteger(57, 'I')
returns
"LVII"
.
This section defines a function for formatting decimal and floating point numbers.
Function  Meaning 

fn:formatnumber 
Returns a string containing a number formatted according to a given picture string, taking account of decimal formats specified in the static context. 
Note:
This function can be used to format any numeric quantity,
including an integer. For integers, however, the fn:formatinteger
function
offers additional possibilities. Note also that the picture strings
used by the two functions are not 100% compatible, though they
share some options in common.
Decimal formats are defined in the static context, and the way they are defined is therefore outside the scope of this specification. XSLT and XQuery both provide custom syntax for creating a decimal format.
The static context provides a set of decimal formats. One of the decimal formats is unnamed, the others (if any) are identified by a QName. There is always an unnamed decimal format available, but its contents are implementationdefined.
Each decimal format provides a set of named variables, described in the following table:
Name  Type  Usage (nonnormative) 

decimalseparatorsign  A single ·character·  Defines the character used to represent the decimal point (typically ".") both in the picture string and in the formatted number 
groupingseparatorsign  A single ·character·  Defines the character used to separate groups of digits (typically ",") both in the picture string and in the formatted number 
infinity  A ·string·  Defines the string used to represent the value positive or negative infinity in the formatted number (typically "Infinity") 
minussign  A single ·character·  Defines the character used as a minus sign in the formatted number if there is no subpicture for formatting negative numbers (typically "", x2D) 
NaN  valign="top"A ·string·  Defines the string used to represent the value
NaN in the formatted number 
percentsign  A single ·character·  Defines the character used as a percent sign (typically "%") both in the picture string and in the formatted number 
permillesign  A single ·character·  Defines the character used as a permille sign (typically "‰", x2030) both in the picture string and in the formatted number 
mandatorydigitsign  A single ·character·, which must be defined in Unicode as a digit  Defines the character (typically "0") used in the picture string to represent a mandatory digit, and in the formatted number to represent the digit zero; by implication, this also defines the characters used to represent the digits one to nine. 
optionaldigitsign  A single ·character·  Defines the character used in the picture string to represent an optional digit (typically "#") 
patternseparatorsign  valign="top"A single ·character·  Defines the character used in the picture string to separate the positive and negative subpictures (typically ";") 
[Definition] The decimal digit family of a decimal format is the sequence of ten digits with consecutive Unicode ·codepoints· starting with the mandatorydigitsign.
It is a constraint that, for any named or unnamed decimal format, the variables representing characters used in a ·picture string· must have distinct values. These variables are decimalseparatorsign, groupingseparatorsign, percentsign, permillesign, optionaldigitsign, and patternseparatorsign. Furthermore, none of these variables may be equal to any ·character· in the ·decimal digit family·.
Returns a string containing a number formatted according to a given picture string, taking account of decimal formats specified in the static context.
fn:formatnumber
($value
as
numeric?
,
$picture
as
xs:string
) as
xs:string
fn:formatnumber ( 
$value 
as numeric? , 
$picture 
as xs:string , 

$decimalformatname 
as xs:string ) as xs:string 
The function formats $value
as a string using the
·picture
string· specified by the
$picture
argument and the decimalformat named by the
$decimalformatname
argument, or the default
decimalformat, if there is no $decimalformatname
argument. The syntax of the picture string is described in 4.6.3 Syntax of the picture
string.
The $value
argument may be of any numeric data type
(xs:double
, xs:float
,
xs:decimal
, or their subtypes including
xs:integer
). Note that if an xs:decimal
is supplied, it is not automatically promoted to an
xs:double
, as such promotion can involve a loss of
precision.
If the supplied value of the $value
argument is an
empty sequence, the function behaves as if the supplied value were
the xs:double
value NaN
.
The value of $decimalformatname
must be a lexical QName, which is expanded using
the inscope namespaces from the static context. The default
namespace is not used (no prefix means no namespace).
The evaluation of the formatnumber
function takes
place in two phases, an analysis phase described in 4.6.4 Analysing the picture
string and a formatting phase described in 4.6.5 Formatting the
number.
The analysis phase takes as its inputs the ·picture string· and the variables derived from the relevant decimal format in the static context, and produces as its output a number of variables with defined values. The formatting phase takes as its inputs the number to be formatted and the variables produced by the analysis phase, and produces as its output a string containing a formatted representation of the number.
The result of the function is the formatted string representation of the supplied number.
An error is raised [err:FODF1280] if the name specified as the
$decimalformatname
argument is not a valid lexical
QName, or if its prefix has not been declared in an inscope
namespace declaration, or if the static context does not contain a
declaration of a decimalformat with a matching expanded QName. If
the processor is able to detect the error statically (for example,
when the argument is supplied as a string literal), then the
processor may optionally signal this as a static
error.
Numbers will always be formatted with the most significant digit on the left.
Note:
This differs from the formatnumber
function
previously defined in XSLT 2.0 in that any digit can be used in the
picture string to represent a mandatory digit: for example the
picture strings '000', '001', and '999' are equivalent. This is to
align formatnumber
(which previously used '000') with
formatdateTime
(which used '001').
[Definition] The formatting of a number is controlled by a picture string. The picture string is a sequence of ·characters·, in which the characters assigned to the variables decimalseparatorsign, groupingsign, decimaldigitfamily, optionaldigitsign and patternseparatorsign are classified as active characters, and all other characters (including the percentsign and permillesign) are classified as passive characters.
The integer part of the subpicture is defined as the part that appears to the left of the decimalseparatorsign if there is one, or the entire subpicture otherwise. The fractional part of the subpicture is defined as the part that appears to the right of the decimalseparatorsign if there is one; it is a zerolength string otherwise.
An error is raised [err:FODF1310] if the ·picture string· does not conform to the following rules. Note that in these rules the words "preceded" and "followed" refer to characters anywhere in the string, they are not to be read as "immediately preceded" and "immediately followed".
A picturestring consists either of a subpicture, or of two subpictures separated by a patternseparatorsign. A picturestring must not contain more than one patternseparatorsign. If the picturestring contains two subpictures, the first is used for positive values and the second for negative values.
A subpicture must not contain more than one decimalseparatorsign.
A subpicture must not contain more than one percentsign or permillesign, and it must not contain one of each.
A subpicture must contain at least one character that is an optionaldigitsign or a member of the decimaldigitfamily.
A subpicture must not contain a passive character that is preceded by an active character and that is followed by another active character.
A subpicture must not contain a groupingseparatorsign adjacent to a decimalseparatorsign.
The integer part of a subpicture must not contain a member of the decimaldigitfamily that is followed by an optionaldigitsign. The fractional part of a subpicture must not contain an optionaldigitsign that is followed by a member of the decimaldigitfamily.
This phase of the algorithm analyses the ·picture string· and the variables from the selected decimal format in the static context, and it has the effect of setting the values of various variables, which are used in the subsequent formatting phase. These variables are listed below. Each is shown with its initial setting and its data type.
Several variables are associated with each subpicture. If there are two subpictures, then these rules are applied to one subpicture to obtain the values that apply to positive numbers, and to the other to obtain the values that apply to negative numbers. If there is only one subpicture, then the values for both cases are derived from this subpicture.
The variables are as follows:
The integerpartgroupingpositions is a sequence of integers representing the positions of grouping separators within the integer part of the subpicture. For each groupingseparatorsign that appears within the integer part of the subpicture, this sequence contains an integer that is equal to the total number of optionaldigitsign and decimaldigitfamily characters that appear within the integer part of the subpicture and to the right of the groupingseparatorsign. In addition, if these integerpartgroupingpositions are at regular intervals (that is, if they form a sequence N, 2N, 3N, ... for some integer value N, including the case where there is only one number in the list), then the sequence contains all integer multiples of N as far as necessary to accommodate the largest possible number.
The minimumintegerpartsize is an integer indicating the minimum number of digits that will appear to the left of the decimalseparatorsign. It is normally set to the number of decimaldigitfamily characters found in the integer part of the subpicture. But if the subpicture contains no decimaldigitfamily character and no decimalseparatorsign, it is set to one.
Note:
There is no maximum integer part size. All significant digits in the integer part of the number will be displayed, even if this exceeds the number of optionaldigitsign and decimaldigitfamily characters in the subpicture.
The prefix is set to contain all passive characters in the subpicture to the left of the leftmost active character. If the picture string contains only one subpicture, the prefix for the negative subpicture is set by concatenating the minussign character and the prefix for the positive subpicture (if any), in that order.
The fractionalpartgroupingpositions is a sequence of integers representing the positions of grouping separators within the fractional part of the subpicture. For each groupingseparatorsign that appears within the fractional part of the subpicture, this sequence contains an integer that is equal to the total number of optionaldigitsign and decimaldigitfamily characters that appear within the fractional part of the subpicture and to the left of the groupingseparatorsign.
The minimumfractionalpartsize is set to the number of decimaldigitfamily characters found in the fractional part of the subpicture.
The maximumfractionalpartsize is set to the total number of optionaldigitsign and decimaldigitfamily characters found in the fractional part of the subpicture.
The suffix is set to contain all passive characters to the right of the rightmost active character in the fractional part of the subpicture.
Note:
If there is only one subpicture, then all variables for positive numbers and negative numbers will be the same, except for prefix: the prefix for negative numbers will be preceded by the minussign character.
This section describes the second phase of processing of the
formatnumber
function. This phase takes as input a
number to be formatted (referred to as the input number),
and the variables set up by analysing the decimal format in the
static context and the ·picture
string·, as described above. The
result of this phase is a string, which forms the return value of
the formatnumber
function.
The algorithm for this second stage of processing is as follows:
If the input number is NaN (not a number), the result is the specified NaNsymbol (with no prefix or suffix).
In the rules below, the positive subpicture and its associated variables are used if the input number is positive, and the negative subpicture and its associated variables are used otherwise. Negative zero is taken as negative, positive zero as positive.
If the input number is positive or negative infinity, the result is the concatenation of the appropriate prefix, the infinitysymbol, and the appropriate suffix.
If the subpicture contains a percentsign, the number is multiplied by 100. If the subpicture contains a permillesign, the number is multiplied by 1000. The resulting number is referred to below as the adjusted number.
The adjusted number is converted (if necessary) to an
xs:decimal
value, using an implementation of
xs:decimal
that imposes no limits on the
totalDigits
or fractionDigits
facets. If
there are several such values that are numerically equal to the
adjusted number (bearing in mind that if the
adjusted number is an xs:double
or
xs:float
, the comparison will be done by converting
the decimal value back to an xs:double
or
xs:float
), the one that is chosen
should be one with the smallest possible number of
digits not counting leading or trailing zeroes (whether significant
or insignificant). For example, 1.0 is preferred to 0.9999999999,
and 100000000 is preferred to 100000001. This value is then rounded
so that it uses no more than
maximumfractionalpartsize
digits in its fractional
part. The rounded number is defined to be the result of
converting the adjusted number to an
xs:decimal
value, as described above, and then calling
the function fn:roundhalftoeven
with this converted
number as the first argument and the
maximumfractionalpartsize
as the second argument,
again with no limits on the totalDigits
or
fractionDigits
in the result.
The absolute value of the rounded number is converted to a string in decimal notation, with no insignificant leading or trailing zeroes, using the digits in the decimaldigitfamily to represent the ten decimal digits, and the decimalseparatorsign to separate the integer part and the fractional part. (The value zero will at this stage be represented by a decimalseparatorsign on its own.)
If the number of digits to the left of the decimalseparatorsign is less than minimumintegerpartsize, leading zerodigitsign characters are added to pad out to that size.
If the number of digits to the right of the decimalseparatorsign is less than minimumfractionalpartsize, trailing zerodigitsign characters are added to pad out to that size.
For each integer N in the integerpartgroupingpositions list, a groupingseparatorsign character is inserted into the string immediately after that digit that appears in the integer part of the number and has N digits between it and the decimalseparatorsign, if there is such a digit.
For each integer N in the fractionalpartgroupingpositions list, a groupingseparatorsign character is inserted into the string immediately before that digit that appears in the fractional part of the number and has N digits between it and the decimalseparatorsign, if there is such a digit.
If there is no decimalseparatorsign in the subpicture, or if there are no digits to the right of the decimalseparatorsign character in the string, then the decimalseparatorsign character is removed from the string (it will be the rightmost character in the string).
The result of the function is the concatenation of the appropriate prefix, the string conversion of the number as obtained above, and the appropriate suffix.
The functions in this section perform trigonometric and other
mathematical calculations on xs:double
values. They
are provided primarily for use in applications performing
geometrical computation, for example when generating SVG
graphics.
Functions are provided to support the six most commonly used trigonometric calculations: sine, cosine and tangent, and their inverses arc sine, arc cosine, and arc tangent. Other functions such as secant, cosecant, and cotangent are not provided because they are easily computed in terms of these six.
The functions in this section (with the exception of fn:pi
) are specified by reference to
[IEEE 7542008], where they appear as
Recommended operations in section 9. IEEE defines these
functions for a variety of floating point formats; this
specification defines them only for xs:double
values.
The IEEE specification applies with the following caveats:
IEEE states that the preferred quantum is languagedefined. In this specification, it is implementationdefined.
IEEE states that certain functions should raise the inexact exception if the result is inexact. In this specification, this exception if it occurs does not result in an error. Any diagnostic information is outside the scope of this specification.
Certain operations (such as taking the square root of a negative
number) are defined in IEEE to signal the invalid operation
exception and return a quiet NaN. In this specification, such
operations return NaN
and do not raise an error. The
same policy applies to operations (such as taking the logarithm of
zero) that raise a dividebyzero exception. Any diagnostic
information is outside the scope of this specification.
Operations whose mathematical result is greater than the largest
finite xs:double
value are defined in IEEE to signal
the overflow exception; operations whose mathematical result is
closer to zero than the smallest nonzero xs:double
value are similarly defined in IEEE to signal the underflow
exception. The treatment of these exceptions in this specification
is defined in 4.2 Arithmetic operators on
numeric values.
Function  Meaning 

math:pi 
Returns an approximation to the mathematical constant π. 
math:exp 
Returns the value of e^{x}. 
math:exp10 
Returns the value of
10 ^{x}. 
math:log 
Returns the natural logarithm of the argument. 
math:log10 
Returns the baseten logarithm of the argument. 
math:pow 
Returns the result of raising the first argument to the power of the second. 
math:sqrt 
Returns the nonnegative square root of the argument. 
math:sin 
Returns the sine of the argument, expressed in radians. 
math:cos 
Returns the cosine of the argument, expressed in radians. 
math:tan 
Returns the tangent of the argument, expressed in radians. 
math:asin 
Returns the arc sine of the argument, the result being in the range π/2 to +π/2 radians. 
math:acos 
Returns the arc cosine of the argument, the result being in the range zero to +π radians. 
math:atan 
Returns the arc tangent of the argument, the result being in the range π/2 to +π/2 radians. 
math:atan2 
Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive xaxis, the result being in the range π to +π. 
Returns an approximation to the mathematical constant π.
math:pi
() as
xs:double
This function returns the xs:double
value whose
lexical representation is 3.141592653589793e0
The expression 2*math:pi()
returns
6.283185307179586e0
.
The expression 60 * (math:pi() div 180)
converts an
angle of 60 degrees to radians.
Returns the value of e^{x}.
math:exp
($arg
as
xs:double?
) as
xs:double?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise the result is the the mathematical constant
e raised to the power of $arg
, as defined
in the [IEEE 7542008] specification of
the exp
function applied to 64bit binary floating
point values.
The treatment of overflow and underflow is defined in 4.2 Arithmetic operators on numeric values.
The expression math:exp(())
returns
()
.
The expression math:exp(0)
returns
1.0e0
.
The expression math:exp(1)
returns
2.7182818284590455e0
.
The expression math:exp(2)
returns
7.38905609893065e0
.
The expression math:exp(1)
returns
0.36787944117144233e0
.
The expression math:exp(math:pi())
returns
23.140692632779267e0
.
The expression math:exp(xs:double('NaN'))
returns
xs:double('NaN')
.
The expression math:exp(xs:double('INF'))
returns
xs:double('INF')
.
The expression math:exp(xs:double('INF'))
returns
0.0e0
.
Returns the value of 10
^{x}.
math:exp10
($arg
as
xs:double?
) as
xs:double?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise the result is ten raised to the power of
$arg
, as defined in the [IEEE
7542008] specification of the exp10
function
applied to 64bit binary floating point values.
The treatment of overflow and underflow is defined in 4.2 Arithmetic operators on numeric values.
The expression math:exp10(())
returns
()
.
The expression math:exp10(0)
returns
1.0e0
.
The expression math:exp10(1)
returns
1.0e1
.
The expression math:exp10(0.5)
returns
3.1622776601683795e0
.
The expression math:exp10(1)
returns
1.0e1
.
The expression math:exp10(xs:double('NaN'))
returns
xs:double('NaN')
.
The expression math:exp10(xs:double('INF'))
returns
xs:double('INF')
.
The expression math:exp10(xs:double('INF'))
returns 0.0e0
.
Returns the natural logarithm of the argument.
math:log
($arg
as
xs:double?
) as
xs:double?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise the result is the natural logarithm of
$arg
, as defined in the [IEEE
7542008] specification of the log
function
applied to 64bit binary floating point values.
The treatment of divideByZero
and
invalidOperation
exceptions is defined in 4.2 Arithmetic operators on numeric
values. The effect is that if the argument is less than or
equal to zero, the result is NaN
.
The expression math:log(())
returns
()
.
The expression math:log(0)
returns
xs:double('INF')
.
The expression math:log(math:exp(1))
returns
1.0e0
.
The expression math:log(1.0e3)
returns
6.907755278982137e0
.
The expression math:log(2)
returns
0.6931471805599453e0
.
The expression math:log(1)
returns
xs:double('NaN')
.
The expression math:log(xs:double('NaN'))
returns
xs:double('NaN')
.
The expression math:log(xs:double('INF'))
returns
xs:double('INF')
.
The expression math:log(xs:double('INF'))
returns
xs:double('NaN')
.
Returns the baseten logarithm of the argument.
math:log10
($arg
as
xs:double?
) as
xs:double?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise the result is the base10 logarithm of
$arg
, as defined in the [IEEE
7542008] specification of the log10
function
applied to 64bit binary floating point values.
The treatment of divideByZero
and
invalidOperation
exceptions is defined in 4.2 Arithmetic operators on numeric
values. The effect is that if the argument is less than or
equal to zero, the result is NaN
.
The expression math:log10(())
returns
()
.
The expression math:log10(0)
returns
xs:double('INF')
.
The expression math:log10(1.0e3)
returns
3.0e0
.
The expression math:log10(1.0e3)
returns
3.0e0
.
The expression math:log10(2)
returns
0.3010299956639812e0
.
The expression math:log10(1)
returns
xs:double('NaN')
.
The expression math:log10(xs:double('NaN'))
returns
xs:double('NaN')
.
The expression math:log10(xs:double('INF'))
returns
xs:double('INF')
.
The expression math:log10(xs:double('INF'))
returns xs:double('NaN')
.
Returns the result of raising the first argument to the power of the second.
math:pow
($x
as
xs:double?
,
$y
as
numeric
) as
xs:double?
If $x
is the empty sequence, the function returns
the empty sequence.
If $y
is an instance of xs:integer
,
the result is $x
raised to the power of
$y
as defined in the [IEEE
7542008] specification of the pown
function
applied to a 64bit binary floating point value and an integer.
Otherwise $y
is converted to an
xs:double
by numeric promotion, and the result is the
value of $x
raised to the power of $y
as
defined in the [IEEE 7542008]
specification of the pow
function applied to two
64bit binary floating point values.
The treatment of the divideByZero
and
invalidOperation
exceptions is defined in 4.2 Arithmetic operators on numeric
values. Some of the consequences are illustrated in the
examples below.
The expression math:pow((), 93.7)
returns
()
.
The expression math:pow(2, 3)
returns
8.0e0
.
The expression math:pow(2, 3)
returns
8.0e0
.
The expression math:pow(2, 3)
returns
0.125e0
.
The expression math:pow(2, 3)
returns
0.125e0
.
The expression math:pow(2, 0)
returns
1.0e0
.
The expression math:pow(0, 0)
returns
1.0e0
.
The expression math:pow(xs:double('INF'), 0)
returns 1.0e0
.
The expression math:pow(xs:double('NaN'), 0)
returns 1.0e0
.
The expression math:pow(math:pi(), 0)
returns
1.0e0
.
The expression math:pow(0e0, 3)
returns
0.0e0
.
The expression math:pow(0e0, 4)
returns
0.0e0
.
The expression math:pow(0e0, 3)
returns
0.0e0
.
The expression math:pow(0, 4)
returns
0.0e0
.
The expression math:pow(0e0, 3)
returns
xs:double('INF')
.
The expression math:pow(0e0, 4)
returns
xs:double('INF')
.
The expression math:pow(0e0, 3)
returns
xs:double('INF')
.
The expression math:pow(0, 4)
returns
xs:double('INF')
.
The expression math:pow(16, 0.5e0)
returns
4.0e0
.
The expression math:pow(16, 0.25e0)
returns
2.0e0
.
The expression math:pow(0e0, 3.0e0)
returns
xs:double('INF')
.
The expression math:pow(0e0, 3.0e0)
returns
xs:double('INF')
. (Oddvalued whole numbers are
treated specially).
The expression math:pow(0e0, 3.1e0)
returns
xs:double('INF')
.
The expression math:pow(0e0, 3.1e0)
returns
xs:double('INF')
.
The expression math:pow(0e0, 3.0e0)
returns
0.0e0
.
The expression math:pow(0e0, 3.0e0)
returns
0.0e0
. (Oddvalued whole numbers are treated
specially).
The expression math:pow(0e0, 3.1e0)
returns
0.0e0
.
The expression math:pow(0e0, 3.1e0)
returns
0.0e0
.
The expression math:pow(1, xs:double('INF'))
returns 1.0e0
.
The expression math:pow(1, xs:double('INF'))
returns 1.0e0
.
The expression math:pow(1, xs:double('INF'))
returns 1.0e0
.
The expression math:pow(1, xs:double('INF'))
returns 1.0e0
.
The expression math:pow(1, xs:double('NaN'))
returns 1.0e0
.
The expression math:pow(2.5e0, 2.0e0)
returns
6.25e0
.
The expression math:pow(2.5e0, 2.00000001e0)
returns xs:double('NaN')
.
Returns the nonnegative square root of the argument.
math:sqrt
($arg
as
xs:double?
) as
xs:double?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise the result is the the mathematical square root of
$arg
as defined in the [IEEE
7542008] specification of the squareRoot
function
applied to 64bit binary floating point values.
The treatment of the invalidOperation
exception is
defined in 4.2 Arithmetic operators on
numeric values. The effect is that if the argument is less
than zero, the result is NaN
.
If $arg
is positive or negative zero, positive
infinity, or NaN
, then the result is
$arg
. (Negative zero is the only case where the result
can have negative sign)
The expression math:sqrt(())
returns
()
.
The expression math:sqrt(0.0e0)
returns
0.0e0
.
The expression math:sqrt(0.0e0)
returns
0.0e0
.
The expression math:sqrt(1.0e6)
returns
1.0e3
.
The expression math:sqrt(2.0e0)
returns
1.4142135623730951e0
.
The expression math:sqrt(2.0e0)
returns
xs:double('NaN')
.
The expression math:log10(xs:double('NaN'))
returns
xs:double('NaN')
.
The expression math:log10(xs:double('INF'))
returns
xs:double('INF')
.
The expression math:log10(xs:double('INF'))
returns xs:double('NaN')
.
Returns the sine of the argument, expressed in radians.
math:sin
($
θ as
xs:double?
) as
xs:double?
If $
θ is the empty
sequence, the function returns the empty sequence.
Otherwise the result is the sine of $
θ, treated as an
angle in radians, as defined in the [IEEE
7542008] specification of the sin
function
applied to 64bit binary floating point values.
The treatment of the invalidOperation
and
underflow
exceptions is defined in 4.2 Arithmetic operators on numeric
values.
If $
θ is positive or
negative zero, the result is $
θ.
If $
θ is positive or
negative infinity, or NaN
, then the result is
NaN
.
Otherwise the result is always in the range 1.0e0 to +1.0e0
The expression math:sin(())
returns
()
.
The expression math:sin(0)
returns
0.0e0
.
The expression math:sin(0.0e0)
returns
0.0e0
.
The expression math:sin(math:pi() div 2)
returns
1.0e0
.
The expression math:sin(math:pi() div 2)
returns
1.0e0
.
The expression math:sin(math:pi())
returns
0.0e0
. (or a close approximation
thereto).
The expression math:sin(xs:double('NaN'))
returns
xs:double('NaN')
.
The expression math:sin(xs:double('INF'))
returns
xs:double('NaN')
.
The expression math:sin(xs:double('INF'))
returns
xs:double('NaN')
.
Returns the cosine of the argument, expressed in radians.
math:cos
($
θ as
xs:double?
) as
xs:double?
If $
θ is the empty
sequence, the function returns the empty sequence.
If $
θ is positive or
negative infinity, or NaN
, then the result is
NaN
.
Otherwise the result is the cosine of $
θ, treated as an
angle in radians, as defined in the [IEEE
7542008] specification of the cos
function
applied to 64bit binary floating point values.
The treatment of the invalidOperation
exception is
defined in 4.2 Arithmetic operators on
numeric values.
If $
θ is positive or
negative zero, the result is $
θ.
If $
θ is positive or
negative infinity, or NaN
, then the result is
NaN
.
Otherwise the result is always in the range 1.0e0 to +1.0e0
The expression math:cos(())
returns
()
.
The expression math:cos(0)
returns
1.0e0
.
The expression math:cos(0.0e0)
returns
1.0e0
.
The expression math:cos(math:pi() div 2)
returns
0.0e0
. (or a close approximation
thereto).
The expression math:cos(math:pi() div 2)
returns
0.0e0
. (or a close approximation
thereto).
The expression math:cos(math:pi())
returns
1.0e0
.
The expression math:cos(xs:double('NaN'))
returns
xs:double('NaN')
.
The expression math:cos(xs:double('INF'))
returns
xs:double('NaN')
.
The expression math:cos(xs:double('INF'))
returns
xs:double('NaN')
.
Returns the tangent of the argument, expressed in radians.
math:tan
($
θ as
xs:double?
) as
xs:double?
If $
θ is the empty
sequence, the function returns the empty sequence.
Otherwise the result is the tangent of
$
θ,
treated as an angle in radians, as defined in the [IEEE 7542008] specification of the
tan
function applied to 64bit binary floating point
values.
The treatment of the invalidOperation
and
underflow
exceptions is defined in 4.2 Arithmetic operators on numeric
values.
If $
θ is positive or
negative infinity, or NaN
, then the result is
NaN
.
The expression math:tan(())
returns
()
.
The expression math:tan(0)
returns
0.0e0
.
The expression math:tan(0.0e0)
returns
0.0e0
.
The expression math:tan(math:pi() div 4)
returns
1.0e0
. (or a close approximation
thereto).
The expression math:tan(math:pi() div 4)
returns
1.0e0
. (or a close approximation
thereto).
The expression math:tan(math:pi() div 2)
returns
1.633123935319537E16
. (or some other suitably
large number).
The expression math:tan(math:pi() div 2)
returns
1.633123935319537E16
. (or some other suitably
large number).
The expression math:tan(math:pi())
returns
0.0e0
. (or a close approximation
thereto).
The expression math:tan(xs:double('NaN'))
returns
xs:double('NaN')
.
The expression math:tan(xs:double('INF'))
returns
xs:double('NaN')
.
The expression math:tan(xs:double('INF'))
returns
xs:double('NaN')
.
Returns the arc sine of the argument, the result being in the range π/2 to +π/2 radians.
math:asin
($arg
as
xs:double?
) as
xs:double?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise the result is the arc sine of
$
θ, treated as an
angle in radians, as defined in the [IEEE
7542008] specification of the asin
function
applied to 64bit binary floating point values.
The treatment of the invalidOperation
and
underflow
exceptions is defined in 4.2 Arithmetic operators on numeric
values.
If $arg
is positive or negative zero, the result is
$arg
.
If $arg
is NaN
, or if its absolute
value is greater than one, then the result is NaN
.
In other cases the result is an xs:double
value
representing an angle θ in radians in the
range π/2 <=
$
θ
<= +
π/2
.
The expression math:asin(())
returns
()
.
The expression math:asin(0)
returns
0.0e0
.
The expression math:asin(0.0e0)
returns
0.0e0
.
The expression math:asin(1.0e0)
returns
1.5707963267948966e0
. (or a close approximation
thereto).
The expression math:asin(1.0e0)
returns
1.5707963267948966e0
. (or a close approximation
thereto).
The expression math:asin(2.0e0)
returns
xs:double('NaN')
.
The expression math:asin(xs:double('NaN'))
returns
xs:double('NaN')
.
The expression math:asin(xs:double('INF'))
returns
xs:double('NaN')
.
The expression math:asin(xs:double('INF'))
returns
xs:double('NaN')
.
Returns the arc cosine of the argument, the result being in the range zero to +π radians.
math:acos
($arg
as
xs:double?
) as
xs:double?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise the result is the arc cosine of
$
θ, treated as an
angle in radians, as defined in the [IEEE
7542008] specification of the acos
function
applied to 64bit binary floating point values.
The treatment of the invalidOperation
exception is
defined in 4.2 Arithmetic operators on
numeric values.
If $arg
is NaN
, or if its absolute
value is greater than one, then the result is NaN
.
In other cases the result is an xs:double
value
representing an angle θ in radians in the
range 0 <= $
θ <=
+
π.
The expression math:acos(())
returns
()
.
The expression math:acos(0)
returns
1.5707963267948966e0
. (or a close approximation
thereto).
The expression math:acos(0.0e0)
returns
1.5707963267948966e0
. (or a close approximation
thereto).
The expression math:acos(1.0e0)
returns
0.0e0
.
The expression math:acos(1.0e0)
returns
3.141592653589793e0
. (or a close approximation
thereto).
The expression math:acos(2.0e0)
returns
xs:double('NaN')
.
The expression math:acos(xs:double('NaN'))
returns
xs:double('NaN')
.
The expression math:acos(xs:double('INF'))
returns
xs:double('NaN')
.
The expression math:acos(xs:double('INF'))
returns
xs:double('NaN')
.
Returns the arc tangent of the argument, the result being in the range π/2 to +π/2 radians.
math:atan
($arg
as
xs:double?
) as
xs:double?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise the result is the arc tangent of
$
θ, treated as an
angle in radians, as defined in the [IEEE
7542008] specification of the atan
function
applied to 64bit binary floating point values.
The treatment of the underflow
exception is defined
in 4.2 Arithmetic operators on numeric
values.
If $arg
is positive or negative zero, the result is
$arg
.
If $arg
is NaN
then the result is
NaN
.
In other cases the result is an xs:double
value
representing an angle θ in radians in the
range π/2 <=
$
θ
<= +
π/2
.
The expression math:atan(())
returns
()
.
The expression math:atan(0)
returns
0.0e0
.
The expression math:atan(0.0e0)
returns
0.0e0
.
The expression math:atan(1.0e0)
returns
0.7853981633974483e0
. (or a close approximation
thereto).
The expression math:atan(1.0e0)
returns
0.7853981633974483e0
. (or a close approximation
thereto).
The expression math:atan(xs:double('NaN'))
returns
xs:double('NaN')
.
The expression math:atan(xs:double('INF'))
returns
1.5707963267948966e0
. (or a close approximation
thereto).
The expression math:atan(xs:double('INF'))
returns
1.5707963267948966e0
. (or a close approximation
thereto).
Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive xaxis, the result being in the range π to +π.
math:atan2
($y
as
xs:double
, $x
as
xs:double
) as
xs:double
The result is the value of atan2(y, x)
as defined
in the [IEEE 7542008] specification of
the atan2
function applied to 64bit binary floating
point values.
The treatment of the underflow
exception is defined
in 4.2 Arithmetic operators on numeric
values.
If $arg
is NaN
then the result is
NaN
.
Some results for special values of the arguments are shown below:
Editorial note  
Add results for infinite arguments 
The expression math:atan2(+0.0e0, 0.0e0)
returns
0.0e0
.
The expression math:atan2(0.0e0, 0.0e0)
returns
0.0e0
.
The expression math:atan2(+0.0e0, 0.0e0)
returns
math:pi()
.
The expression math:atan2(0.0e0, 0.0e0)
returns
math:pi()
.
The expression math:atan2(1, 0.0e0)
returns
math:pi() div 2
.
The expression math:atan2(+1, 0.0e0)
returns
+math:pi() div 2
.
The expression math:atan2(0.0e0, 1)
returns
math:pi()
.
The expression math:atan2(+0.0e0, 1)
returns
+math:pi()
.
The expression math:atan2(0.0e0, +1)
returns
0.0e0
.
The expression math:atan2(+0.0e0, +1)
returns
+0.0e0
.
This section specifies functions and operators on the [XML Schema Part 2: Datatypes Second Edition]
xs:string
datatype and the datatypes derived from
it.
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 userdefined types derived by restriction from the above types.
Function  Meaning 

fn:codepointstostring 
Creates an xs:string from a sequence of ·codepoints·. 
fn:stringtocodepoints 
Returns the sequence of ·codepoints· that
constitute an xs:string value. 
Creates an xs:string
from a sequence of ·codepoints·.
fn:codepointstostring
($arg
as
xs:integer*
) as
xs:string
The function returns the string made up from the ·characters· whose
Unicode ·codepoints· are supplied in $arg
. This will
be the zerolength string if $arg
is the empty
sequence.
If any of the codepoints in $arg
is not a permitted
XML character, an error is raised [err:FOCH0001].
The expression fn:codepointstostring((2309, 2358, 2378,
2325))
returns "अशॊक"
.
Returns the sequence of ·codepoints· that
constitute an xs:string
value.
fn:stringtocodepoints
($arg
as
xs:string?
) as
xs:integer*
The function returns a sequence of integers, each integer being
the Unicode ·codepoints· of the corresponding ·character· in
$arg
.
If $arg
is a zerolength string or the empty
sequence, the function returns the empty sequence.
The expression fn:stringtocodepoints("Thérèse")
returns (84, 104, 233, 114, 232, 115, 101)
.
Function  Meaning 

fn:compare 
Returns 1, 0, or 1, depending on whether
$comparand1 collates before, equal to, or after
$comparand2 according to the rules of a selected
collation. 
fn:codepointequal 
Returns true if two strings are equal, considered codepointbycodepoint. 
A collation is a specification of the manner in which ·strings·s are
compared and, by extension, ordered. When values whose type is
xs:string
or a type derived from
xs:string
are compared (or, equivalently, sorted), the
comparisons are inherently performed according to some collation
(even if that collation is defined entirely on codepoint values).
The [Character Model for the World Wide Web 1.0:
Fundamentals] observes that some applications may require
different comparison and ordering behaviors than other
applications. Similarly, some users having particular linguistic
expectations may require different behaviors than other users.
Consequently, the collation must be taken into account when
comparing strings in any context. Several functions in this and the
following section make use of a collation.
Collations can indicate that two different codepoints are, in fact, equal for comparison purposes (e.g., "v" and "w" are considered equivalent in some Swedish collations). Strings can be compared codepointbycodepoint or in a linguistically appropriate manner, as defined by the collation.
Some collations, especially those based on the [Unicode Collation Algorithm] can be "tailored" for various purposes. This document does not discuss such tailoring, nor does it provide a mechanism to perform tailoring. Instead, it assumes that the collation argument to the various functions below is a tailored and named collation.
The ·Unicode codepoint collation· is a collation available in every implementation, which sorts based on codepoint values. For further details see 5.3.2 The Unicode Codepoint Collation
In the ideal case, a collation should treat two strings as equal if the two strings are identical after Unicode normalization. Thus, the [Character Model for the World Wide Web 1.0: Normalization] recommends that all strings be subjected to early Unicode normalization and some collations will raise runtime errors if they encounter strings that are not properly normalized. However, it is not possible to guarantee that all strings in all XML documents are, in fact, normalized, or that they are normalized in the same manner. In order to maximize interoperability of operations on XML documents in general, there may be collations that operate on unnormalized strings and other collations that implicitly normalize strings before comparing them. Applications may choose the kind of collation best suited for their needs. Note that collations based on the Unicode collation algorithm implicitly normalize strings before comparison and produce equivalent results regardless of a string's normalization.
This specification assumes that collations are named and that
the collation name may be provided as an argument to string
functions. Functions that allow specification of a collation do so
with an argument whose type is xs:string
but whose
lexical form must conform to an xs:anyURI
. If the
collation is specified using a relative URI, it is assumed to be
relative to the value of the baseuri 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 calls of functions that use a collation but allow it
to be omitted.
This specification does not define whether or not the collation URI is dereferenced. The collation URI may be an abstract identifier, or it may refer to an actual resource describing the collation. If it refers to a resource, this specification does not define the nature of that resource. One possible candidate is that the resource is a locale description expressed using the Locale Data Markup Language: see [Locale Data Markup Language].
Functions such as fn:compare
and fn:max
that compare
xs:string
values use a single collation URI to
identify all aspects of the collation rules. This means that any
parameters such as the strength of the collation must be specified
as part of the collation URI. For example, suppose there is a
collation " http://www.example.com/collations/French
"
that refers to a French collation that compares on the basis of
base characters. Collations that use the same basic rules, but with
higher strengths, for example, base characters and accents, or base
characters, accents and case, would need to be given different
names, say " http://www.example.com/collations/French1
" and " http://www.example.com/collations/French2
".
Note that some specifications use the term collation to refer to an
algorithm that can be parameterized, but in this specification,
each possible parameterization is considered to be a distinct
collation.
The XQuery/XPath static context includes a provision for a default collation that can be used for string comparisons and ordering operations. See the description of the static context in Section 2.1.1 Static Context^{XP}. If the default collation is not specified by the user or the system, the default collation is the ·Unicode codepoint collation·.
Note:
XML allows elements to specify the xml:lang
attribute to indicate the language associated with the content of
such an element. This specification does not use
xml:lang
to identify the default collation because
using xml:lang
does not produce desired effects when
the two strings to be compared have different xml:lang
values or when a string is multilingual.
[Definition] The collation URI
http://www.w3.org/2005/xpathfunctions/collation/codepoint
identifies a collation which must be recognized by every
implementation: it is referred to as the Unicode codepoint
collation (not to be confused with the Unicode collation
algorithm).
The Unicode codepoint collation does not perform any normalization on the supplied strings.
The collation is defined as follows. Each of the two strings is
converted to a sequence of integers using the
fn:stringtocodepoints
function. These two sequences
$A
and $B
are then compared as
follows:
If both sequences are empty, the strings are equal
If one sequence is empty and the other is not, then the string corresponding to the empty sequence is less than the other string.
If the first integer in $A
is less than the first
integer in $B
, then the string corresponding to
$A
is less than the string corresponding to
$B
.
If the first integer in $A
is greater than the
first integer in $B
, then the string corresponding to
$A
is greater than the string corresponding to
$B
.
Otherwise (the first pair of integers are equal), the result is
obtained by applying the same rules recursively to fn:subsequence($A, 2)
and
fn:subsequence($B,
2)
Note:
While the Unicode codepoint collation does not produce results suitable for quality publishing of printed indexes or directories, it is adequate for many purposes where a restricted alphabet is used, such as sorting of vehicle registrations.
Many functions have two signatures, where one signature includes
a $collation
argument and the other omits this
argument.
The collation to use for these functions is determined by the following rules:
If the function specifies an explicit collation, CollationA
(e.g., if the optional collation argument is specified in a call of
the fn:compare
function),
then:
If CollationA is supported by the implementation, then CollationA is used.
Otherwise, 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:
Because the set of collations that are supported is ·implementationdefined·, an implementation has the option to support all collation URIs, in which case it will never raise this error.
Returns 1, 0, or 1, depending on whether
$comparand1
collates before, equal to, or after
$comparand2
according to the rules of a selected
collation.
fn: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? 
Returns 1, 0, or 1, depending on whether the value of the
$comparand1
is respectively less than, equal to, or
greater than the value of $comparand2
, according to
the rules of the collation that is used.
The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation.
If either $comparand1
or $comparand2
is the empty sequence, the function returns the empty sequence.
This function, called with the first signature, defines the
semantics of the "eq", "ne", "gt", "lt", "le" and "ge" operators on
xs:string
values.
The expression fn:compare('abc', 'abc')
returns
0
.
The expression fn:compare('Strasse', 'Straße')
returns 0
. (Assuming the default collation
includes provisions that equate "ss" and the (German) character "ß"
("sharps"). Otherwise, the returned value depends on the semantics
of the default collation.).
The expression fn:compare('Strasse', 'Straße',
'http://example.com/deutsch')
returns 0
.
(Assuming the collation identified by the URI
http://example.com/deutsch
includes provisions that
equate "ss" and the (German) character "ß" ("sharps"). Otherwise,
the returned value depends on the semantics of that
collation.).
The expression fn:compare('Strassen', 'Straße')
returns 1
. (Assuming the default collation
includes provisions that treat differences between "ss" and the
(German) character "ß" ("sharps") with less strength than the
differences between the base characters, such as the final "n".
).
Returns true if two strings are equal, considered codepointbycodepoint.
fn:codepointequal ( 
$comparand1 
as xs:string? , 
$comparand2 
as xs:string? ) as xs:boolean? 
If either argument is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns true
or
false
depending on whether the value of
$comparand1
is equal to the value of
$comparand2
, according to the Unicode codepoint
collation
(http://www.w3.org/2005/xpathfunctions/collation/codepoint
).
This function allows xs:anyURI
values to be
compared without having to specify the Unicode codepoint
collation.
The following functions are defined on values of type
xs:string
and types derived from it.
Function  Meaning 

fn:concat 
Returns the concatenation of the string values of the arguments. 
fn:stringjoin 
Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items. 
fn:substring 
Returns the portion of the value of $sourceString
beginning at the position indicated by the value of
$start and continuing for the number of ·characters·
indicated by the value of $length . 
fn:stringlength 
Returns the number of ·characters· in a string. 
fn:normalizespace 
Returns the value of $arg with leading and
trailing whitespace removed, and sequences of internal whitespace
reduced to a single space character. 
fn:normalizeunicode 
Returns the value of $arg after applying Unicode
normalization. 
fn:uppercase 
Converts a string to upper case. 
fn:lowercase 
Converts a string to lower case. 
fn:translate 
Returns the value of $arg modified by replacing or
removing individual characters. 
Notes:
When the above operators and functions are applied to datatypes
derived from xs:string
, they are guaranteed to return
values that are instances of xs:string
, but the value
might or might not be an instance of the particular subtype of
xs:string
to which they were applied.
The strings returned by fn:concat
and fn:stringjoin
are not
guaranteed to be normalized. But see note in fn:concat
.
Returns the concatenation of the string values of the arguments.
fn:concat ( 
$arg1 
as xs:anyAtomicType? , 
$arg2 
as xs:anyAtomicType? , 

...  ) as xs:string 
This function accepts two or more xs:anyAtomicType
arguments and casts each one to xs:string
. The
function returns the xs:string
that is the
concatenation of the values of its arguments after conversion. If
any argument is the empty sequence, that argument is treated as the
zerolength 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].
As mentioned in 5.1 String
types Unicode normalization is not automatically applied to
the result of fn:concat
. If a normalized result is
required, fn:normalizeunicode
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 normalizeunicode(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.
The expression fn:concat('un', 'grateful')
returns
"ungrateful"
.
The expression fn:concat('Thy ', (), 'old ', "groans", "",
' ring', ' yet', ' in', ' my', ' ancient',' ears.')
returns
"Thy old groans ring yet in my ancient ears."
.
The expression fn:concat('Ciao!',())
returns
"Ciao!"
.
The expression fn:concat('Ingratitude, ', 'thou ',
'marblehearted', ' fiend!')
returns "Ingratitude,
thou marblehearted fiend!"
.
Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items.
fn:stringjoin
($arg1
as
xs:string*
) as
xs:string
fn:stringjoin
($arg1
as
xs:string*
,
$arg2
as
xs:string
) as
xs:string
The effect of calling the singleargument version of this
function is the same as calling the twoargument version with
$arg2
set to a zerolength string.
The function returns an xs:string
created by
concatenating the items in the sequence $arg1
, in
order, using the value of $arg2
as a separator between
adjacent items. If the value of $arg2
is the
zerolength string, then the members of $arg1
are
concatenated without a separator.
If the value of $arg1
is the empty sequence, the
function returns the zerolength string.
The expression fn:stringjoin(('Now', 'is', 'the', 'time',
'...'), ' ')
returns "Now is the time ..."
.
The expression fn:stringjoin(('Blow, ', 'blow, ', 'thou
', 'winter ', 'wind!'), '')
returns "Blow, blow, thou
winter wind!"
.
The expression fn:stringjoin((), 'separator')
returns ""
.
Assume a document:
<doc> <chap> <section/> </chap> </doc>
with the <section>
element as the context
node, the [XML Path Language (XPath) 2.0]
expression:
fn:stringjoin(ancestororself::*/name(), '/')
returns "doc/chap/section"
Returns the portion of the value of $sourceString
beginning at the position indicated by the value of
$start
and continuing for the number of ·characters·
indicated by the value of $length
.
fn:substring
($sourceString
as
xs:string?
,
$start
as
xs:double
) as
xs:string
fn:substring ( 
$sourceString 
as xs:string? , 
$start 
as xs:double , 

$length 
as xs:double ) as xs:string 
If the value of $sourceString
is the empty
sequence, the function returns the zerolength string.
Otherwise, the function returns a string comprising those
·characters· of
$sourceString
whose index position (counting from one)
is greater than or equal to the value of $start
(rounded to an integer), and (if $length
is specified)
less than the sum of $start
and $length
(both rounded to integers).
The characters returned do not extend beyond
$sourceString
. If $start
is zero or
negative, only those characters in positions greater than zero are
returned.
More specifically, the three argument version of the function
returns the characters in $sourceString
whose position
$p
satisfies:
fn:round($start) <= $p <
fn:round($start) + fn:round($length)
The two argument version of the function assumes that
$length
is infinite and thus returns the ·characters· in
$sourceString
whose position $p
satisfies:
In the above computations, the rules for op:numericlessthan
and
op:numericgreaterthan
apply.
The first character of a string is located at position 1, not position 0.
The expression fn:substring("motor car", 6)
returns
" car"
. (Characters starting at position 6 to the
end of $sourceString
are selected.).
The expression fn:substring("metadata", 4, 3)
returns "ada"
. (Characters at positions greater
than or equal to 4 and less than 7 are selected.).
The expression fn:substring("12345", 1.5, 2.6)
returns "234"
. (Characters at positions greater
than or equal to 2 and less than 5 are selected.).
The expression fn:substring("12345", 0, 3)
returns
"12"
. (Characters at positions greater than or
equal to 0 and less than 3 are selected. Since the first position
is 1, these are the characters at positions 1 and 2.).
The expression fn:substring("12345", 5, 3)
returns
""
. (Characters at positions greater than or equal
to 5 and less than 2 are selected.).
The expression fn:substring("12345", 3, 5)
returns
"1"
. (Characters at positions greater than or
equal to 3 and less than 2 are selected. Since the first position
is 1, this is the character at position 1.).
The expression fn:substring("12345", 0 div 0E0, 3)
returns ""
. (Since 0 div 0E0
returns
NaN
, and NaN
compared to any other number
returns false
, no characters are selected.).
The expression fn:substring("12345", 1, 0 div 0E0)
returns ""
. (As above.).
The expression fn:substring((), 1, 3)
returns
""
.
The expression fn:substring("12345", 42, 1 div
0E0)
returns "12345"
. (Characters at
positions greater than or equal to 42 and less than INF are
selected.).
The expression fn:substring("12345", 1 div 0E0, 1 div
0E0)
returns ""
. (Since the value of
INF + INF
is NaN
, no characters are
selected.).
Returns the number of ·characters· in a string.
fn:stringlength
() as
xs:integer
fn:stringlength
($arg
as
xs:string?
) as
xs:integer
The function returns an xs:integer
equal to the
length in ·characters· of the value of $arg
.
Calling the zeroargument version of the function is equivalent
to calling fn:stringlength(fn:string(.))
.
If the value of $arg
is the empty sequence, the
function returns the xs:integer
value zero (0).
If $arg
is not specified and the context item is
absent, an error is raised: [err:XPDY0002]^{XP}.
Unlike some programming languages, a ·codepoint· greater than 65535 counts as one character, not two.
The expression fn:stringlength("Harp not on that string,
madam; that is past.")
returns 45
.
The expression fn:stringlength(())
returns
0
.
Returns the value of $arg
with leading and trailing
whitespace removed, and sequences of internal whitespace reduced to
a single space character.
fn:normalizespace
() as
xs:string
fn:normalizespace
($arg
as
xs:string?
) as
xs:string
If the value of $arg
is the empty sequence, the
function returns the zerolength string.
The function returns a string constructed by stripping leading
and trailing whitespace from the value of $arg
, and
replacing sequences of one or more adjacent whitespace characters
with a single space, #x20
.
The whitespace characters are defined in the metasymbol S (Production 3) of [RECxml].
If no argument is supplied, then $arg
defaults to
the string value (calculated using fn:string
) of the context item
(.
).
If no argument is supplied and the context item is absent then an error is raised: [err:XPDY0002]^{XP}.
The definition of whitespace is unchanged in [Extensible Markup Language (XML) 1.1 Recommendation].
The expression
fn:normalizespace(" The wealthy curled darlings
of our nation. ")
returns "The wealthy curled darlings of our
nation."
.
The expression fn:normalizespace(())
returns
""
.
Returns the value of $arg
after applying Unicode
normalization.
fn:normalizeunicode
($arg
as
xs:string?
) as
xs:string
fn:normalizeunicode ( 
$arg 
as xs:string? , 
$normalizationForm 
as xs:string ) as xs:string 
If the value of $arg
is the empty sequence, the
function returns the zerolength string.
If the singleargument version of the function is used, the
result is the same as calling the twoargument version with
$normalizationForm
set to the string "NFC".
Otherwise, the function returns the value of $arg
normalized according to the rules of the normalization form
identified by the value of $normalizationForm
.
The effective value of $normalizationForm
is the
value of the expression fn:uppercase(fn:normalizespace($normalizationForm))
.
See [Character Model for the World Wide Web 1.0: Normalization] for a description of the normalization forms.
If the effective value of $normalizationForm
is
"NFC", then the function returns the value of $arg
converted to Unicode Normalization Form C (NFC).
If the effective value of $normalizationForm
is
"NFD", then the function returns the value of $arg
converted to Unicode Normalization Form D (NFD).
If the effective value of $normalizationForm
is
"NFKC", then the function returns the value of $arg
in
Unicode Normalization Form KC (NFKC).
If the effective value of $normalizationForm
is
"NFKD", then the function returns the value of $arg
converted to Unicode Normalization Form KD (NFKD).
If the effective value of $normalizationForm
is
"FULLYNORMALIZED", then the function returns the value of
$arg
converted to fully normalized form.
If the effective value of $normalizationForm
is the
zerolength string, no normalization is performed and
$arg
is returned.
Normalization forms NFC, NFD, NFKC, and NFKD, and the algorithms to be used for converting a string to each of these forms, are defined in [Unicode Normaliation Forms].
The motivation for normalization form FULLYNORMALIZED is explained in [Character Model for the World Wide Web 1.0: Normalization]. However, as that specification did not progress beyond working draft status, the normative specification is as follows:
A string is fullynormalized if (a) it is in normalization form NFC as defined in [Unicode Normaliation Forms], and (b) it does not start with a composing character.
A composing character is a character that is one or both of the following:
the second character in the canonical decomposition mapping of some character that is not listed in the Composition Exclusion Table defined in [Unicode Normaliation Forms];
of nonzero canonical combining class (as defined in [The Unicode Standard]).
A string is converted to FULLYNORMALIZED form as follows:
if the first character in the string is a composing character, prepend a single space (x20);
convert the resulting string to normalization form NFC.
Conforming implementations ·must· support normalization form "NFC" and ·may· support normalization forms "NFD", "NFKC", "NFKD", and "FULLYNORMALIZED". They ·may· also support other normalization forms with ·implementationdefined· semantics.
If the effective value of the $normalizationForm
argument is not one of the values supported by the implementation,
then an error is raised [err:FOCH0003].
Converts a string to upper case.
fn:uppercase
($arg
as
xs:string?
) as
xs:string
If the value of $arg
is the empty sequence, the
zerolength string is returned.
Otherwise, the function returns the value of $arg
after translating every ·character· to its uppercase correspondent as defined in
the appropriate case mappings section in the Unicode standard
[The Unicode Standard]. For versions of
Unicode beginning with the 2.1.8 update, only localeinsensitive
case mappings should be applied. Beginning with version 3.2.0 (and
likely future versions) of Unicode, precise mappings are described
in default case operations, which are full case mappings in the
absence of tailoring for particular languages and environments.
Every lowercase character that does not have an uppercase
correspondent, as well as every uppercase character, is included
in the returned value in its original form.
Case mappings may change the length of a string. In general, the
fn:uppercase
and fn:lowercase
functions are not
inverses of each other: fn:lowercase(fn:uppercase($arg))
is not guaranteed to return $arg
, nor is
fn:uppercase(fn:lowercase($arg))
. The Latin small
letter dotless i (as used in Turkish) is perhaps the most prominent
lowercase letter which will not roundtrip. The Latin capital
letter i with dot above is the most prominent uppercase letter
which will not round trip; there are others, such as Latin capital
letter Sharp S (#1E9E) which is introduced in Unicode 5.1.
These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.
Because the function is not sensitive to locale, results will not always match user expectations. In Quebec, for example, the standard uppercase equivalent of "è" is "È", while in metropolitan France it is more commonly "E"; only one of these is supported by the functions as defined.
Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.
The expression fn:uppercase("abCd0")
returns
"ABCD0"
.
Converts a string to lower case.
fn:lowercase
($arg
as
xs:string?
) as
xs:string
If the value of $arg
is the empty sequence, the
zerolength string is returned.
Otherwise, the function returns the value of $arg
after translating every ·character· to its lowercase correspondent as defined in
the appropriate case mappings section in the Unicode standard
[The Unicode Standard]. For versions of
Unicode beginning with the 2.1.8 update, only localeinsensitive
case mappings should be applied. Beginning with version 3.2.0 (and
likely future versions) of Unicode, precise mappings are described
in default case operations, which are full case mappings in the
absence of tailoring for particular languages and environments.
Every uppercase character that does not have a lowercase
correspondent, as well as every lowercase character, is included
in the returned value in its original form.
Case mappings may change the length of a string. In general, the
fn:uppercase
and
fn:lowercase
functions are not inverses of each
other: fn:lowercase(fn:uppercase($arg))
is not
guaranteed to return $arg
, nor is fn:uppercase(fn:lowercase($arg))
.
The Latin small letter dotless i (as used in Turkish) is perhaps
the most prominent lowercase letter which will not roundtrip. The
Latin capital letter i with dot above is the most prominent
uppercase letter which will not round trip; there are others, such
as Latin capital letter Sharp S (#1E9E) which is introduced in
Unicode 5.1.
These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.
Because the function is not sensitive to locale, results will not always match user expectations. In Quebec, for example, the standard uppercase equivalent of "è" is "È", while in metropolitan France it is more commonly "E"; only one of these is supported by the functions as defined.
Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.
The expression fn:lowercase("ABc!D")
returns
"abc!d"
.
Returns the value of $arg
modified by replacing or
removing individual characters.
fn:translate ( 
$arg 
as xs:string? , 
$mapString 
as xs:string , 

$transString 
as xs:string ) as xs:string 
If the value of $arg
is the empty sequence, the
function returns the zerolength string.
Otherwise, the function returns a result string constructed by
processing each ·character· in the value of $arg
, in order,
according to the following rules:
If the character does not appear in the value of
$mapString
then it is added to the result string
unchanged.
If the character first appears in the value of
$mapString
at some position M, where the
value of $transString
is M or more characters
in length, then the character at position M in
$transString
is added to the result string.
If the character first appears in the value of
$mapString
at some position M, where the
value of $transString
is less than M
characters in length, then the character is omitted from the result
string.
If $mapString
is the zerolength string then the
function returns $arg
unchanged.
If a character occurs more than once in $mapString
,
then the first occurrence determines the action taken.
If $transString
is longer than
$mapString
, the excess characters are ignored.
The expression fn:translate("bar","abc","ABC")
returns "BAr"
.
The expression fn:translate("aaa","abc","ABC")
returns "AAA"
.
The expression fn:translate("abcdabc", "abc", "AB")
returns "ABdAB"
.
The functions described in the section examine a string
$arg1
to see whether it contains another string
$arg2
as a substring. The result depends on whether
$arg2
is a substring of $arg1
, and if so,
on the range of ·characters· in $arg1
which $arg2
matches.
When the ·Unicode
codepoint collation· is used, this
simply involves determining whether $arg1
contains a
contiguous sequence of characters whose ·codepoints· are the
same, one for one, with the codepoints of the characters in
$arg2
.
When a collation is specified, the rules are more complex.
All collations support the capability of deciding whether two
·strings· are
considered equal, and if not, which of the strings should be
regarded as preceding the other. For functions such as fn:compare
, this is all that is
required. For other functions, such as fn:contains
, the collation needs
to support an additional property: it must be able to decompose the
string into a sequence of collation units, each unit consisting of
one or more characters, such that two strings can be compared by
pairwise comparison of these units. ("collation unit" is equivalent
to "collation element" as defined in [Unicode Collation Algorithm].) The
string $arg1
is then considered to contain
$arg2
as a substring if the sequence of collation
units corresponding to $arg2
is a subsequence of the
sequence of the collation units corresponding to
$arg1
. The characters in $arg1
that match
are the characters corresponding to these collation units.
This rule may occasionally lead to surprises. For example,
consider a collation that treats "Jaeger" and "Jäger" as equal. It
might do this by treating "ä" as representing two collation units,
in which case the expression fn:contains("Jäger", "eg")
will
return true
. Alternatively, a collation might treat
"ae" as a single collation unit, in which case the expression
fn:contains("Jaeger",
"eg")
will return false
. The results of
these functions thus depend strongly on the properties of the
collation that is used.
In addition, collations may specify that some collation units
should be ignored during matching. If hyphen is an ignored
collation unit, then fn:contains("codepoint",
"codepoint")
will be true, and fn:contains("codepoint", "")
will also be true.
In the definitions below, we refer to the terms match and minimal match as defined in definitions DS2 and DS4 of [Unicode Collation Algorithm]. In applying these definitions:
C is the collation; that is, the value of the
$collation
argument if specified, otherwise the
default collation.
P is the (candidate) substring $arg2
Q is the (candidate) containing string
$arg1
The boundary condition B is satisfied at the start and end of a string, and between any two characters that belong to different collation units ("collation elements" in the language of [Unicode Collation Algorithm]). It is not satisfied between two characters that belong to the same collation unit.
It is possible to define collations that do not have the ability to decompose a string into units suitable for substring matching. An argument to a function defined in this section may be a URI that identifies a collation that is able to compare two strings, but that does not have the capability to split the string into collation units. Such a collation may cause the function to fail, or to give unexpected results or it may be rejected as an unsuitable argument. The ability to decompose strings into collation units is an ·implementationdefined· property of the collation.
Function  Meaning 

fn:contains 
Returns true if the string $arg1 contains
$arg2 as a substring, taking collations into
account. 
fn:startswith 
Returns true if the string $arg1 contains
$arg2 as a leading substring, taking collations into
account. 
fn:endswith 
Returns true if the string $arg1 contains
$arg2 as a trailing substring, taking collations into
account. 
fn:substringbefore 
Returns the part of $arg1 that precedes the first
occurrence of $arg2 , taking collations into
account. 
fn:substringafter 
Returns the part of $arg1 that follows the first
occurrence of $arg2 , taking collations into
account. 
Returns true if the string $arg1
contains
$arg2
as a substring, taking collations into
account.
fn:contains
($arg1
as
xs:string?
,
$arg2
as
xs:string?
) as
xs:boolean
fn:contains ( 
$arg1 
as xs:string? , 
$arg2 
as xs:string? , 

$collation 
as xs:string ) as xs:boolean 
If the value of $arg1
or $arg2
is the
empty sequence, or contains only ignorable collation units, it is
interpreted as the zerolength string.
If the value of $arg2
is the zerolength string,
then the function returns true
.
If the value of $arg1
is the zerolength string,
the function returns false
.
The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation.
The function returns an xs:boolean
indicating
whether or not the value of $arg1
contains (at the
beginning, at the end, or anywhere within) at least one sequence of
collation units that provides a minimal match to the
collation units in the value of $arg2
, according to
the collation that is used.
Note:
Minimal match is defined in [Unicode Collation Algorithm].
If the specified collation does not support collation units an error ·may· be raised [err:FOCH0004].
The collation used in these examples,
http://example.com/CollationA
is a collation in which
both "" and "*" are ignorable collation units.
"Ignorable collation unit" is equivalent to "ignorable collation element" in [Unicode Collation Algorithm].
The expression fn:contains ( "tattoo", "t")
returns
true()
.
The expression fn:contains ( "tattoo", "ttt")
returns false()
.
The expression fn:contains ( "", ())
returns
true()
. (The first rule is applied, followed by
the second rule.).
The expression fn:contains ( "abcdefghi", "def",
"http://example.com/CollationA")
returns
true()
.
The expression fn:contains ( "a*b*c*d*e*f*g*h*i*",
"def", "http://example.com/CollationA")
returns
true()
.
The expression fn:contains ( "abcd***ef**ghi", "def",
"http://example.com/CollationA")
returns
true()
.
The expression fn:contains ( (), "****",
"http://example.com/CollationA")
returns
true()
. (The second argument contains only
ignorable collation units and is equivalent to the zerolength
string.).
Returns true if the string $arg1
contains
$arg2
as a leading substring, taking collations into
account.
fn:startswith
($arg1
as
xs:string?
,
$arg2
as
xs:string?
) as
xs:boolean
fn:startswith ( 
$arg1 
as xs:string? , 
$arg2 
as xs:string? , 

$collation 
as xs:string ) as xs:boolean 
If the value of $arg1
or $arg2
is the
empty sequence, or contains only ignorable collation units, it is
interpreted as the zerolength string.
If the value of $arg2
is the zerolength string,
then the function returns true
. If the value of
$arg1
is the zerolength string and the value of
$arg2
is not the zerolength string, then the function
returns false
.
The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation.
The function returns an xs:boolean
indicating
whether or not the value of $arg1
starts with a
sequence of collation units that provides a match to the
collation units of $arg2
according to the collation
that is used.
Note:
Match is defined in [Unicode Collation Algorithm].
If the specified collation does not support collation units an error ·may· be raised [err:FOCH0004].
The collation used in these examples,
http://example.com/CollationA
is a collation in which
both "" and "*" are ignorable collation units.
"Ignorable collation unit" is equivalent to "ignorable collation element" in [Unicode Collation Algorithm].
The expression fn:startswith("tattoo", "tat")
returns true()
.
The expression fn:startswith ( "tattoo", "att")
returns false()
.
The expression fn:startswith ((), ())
returns
true()
.
The expression fn:startswith ( "abcdefghi", "abc",
"http://example.com/CollationA")
returns
true()
.
The expression fn:startswith ( "a*b*c*d*e*f*g*h*i*",
"abc", "http://example.com/CollationA")
returns
true()
.
The expression fn:startswith ( "abcd***ef**ghi",
"abcdef", "http://example.com/CollationA")
returns
true()
.
The expression fn:startswith ( (), "****",
"http://example.com/CollationA")
returns
true()
. (The second argument contains only
ignorable collation units and is equivalent to the zerolength
string.).
The expression fn:startswith ( "abcdefghi", "abc",
"http://example.com/CollationA")
returns
true()
.
Returns true if the string $arg1
contains
$arg2
as a trailing substring, taking collations into
account.
fn:endswith
($arg1
as
xs:string?
,
$arg2
as
xs:string?
) as
xs:boolean
fn:endswith ( 
$arg1 
as xs:string? , 
$arg2 
as xs:string? , 

$collation 
as xs:string ) as xs:boolean 
If the value of $arg1
or $arg2
is the
empty sequence, or contains only ignorable collation units, it is
interpreted as the zerolength string.
If the value of $arg2
is the zerolength string,
then the function returns true
. If the value of
$arg1
is the zerolength string and the value of
$arg2
is not the zerolength string, then the function
returns false
.
The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation.
The function returns an xs:boolean
indicating
whether or not the value of $arg1
starts with a
sequence of collation units that provides a match to the
collation units of $arg2
according to the collation
that is used.
Note:
Match is defined in [Unicode Collation Algorithm].
If the specified collation does not support collation units an error ·may· be raised [err:FOCH0004].
The collation used in these examples,
http://example.com/CollationA
is a collation in which
both "" and "*" are ignorable collation units.
"Ignorable collation unit" is equivalent to "ignorable collation element" in [Unicode Collation Algorithm].
The expression fn:endswith ( "tattoo", "tattoo")
returns true()
.
The expression fn:endswith ( "tattoo", "atto")
returns false()
.
The expression fn:endswith ((), ())
returns
true()
.
The expression fn:endswith ( "abcdefghi", "ghi",
"http://example.com/CollationA")
returns
true()
.
The expression fn:endswith ( "abcd***ef**ghi",
"defghi", "http://example.com/CollationA")
returns
true()
.
The expression fn:endswith ( "abcd***ef**ghi",
"defghi", "http://example.com/CollationA")
returns
true()
.
The expression fn:endswith ( (), "****",
"http://example.com/CollationA")
returns
true()
. (The second argument contains only
ignorable collation units and is equivalent to the zerolength
string.).
The expression fn:endswith ( "abcdefghi", "ghi",
"http://example.com/CollationA")
returns
true()
.
Returns the part of $arg1
that precedes the first
occurrence of $arg2
, taking collations into
account.
fn:substringbefore
($arg1
as
xs:string?
,
$arg2
as
xs:string?
) as
xs:string
fn:substringbefore ( 
$arg1 
as xs:string? , 
$arg2 
as xs:string? , 

$collation 
as xs:string ) as xs:string 
If the value of $arg1
or $arg2
is the
empty sequence, or contains only ignorable collation units, it is
interpreted as the zerolength string.
If the value of $arg2
is the zerolength string,
then the function returns the zerolength string.
If the value of $arg1
does not contain a string
that is equal to the value of $arg2
, then the function
returns the zerolength string.
The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation.
The function returns the substring of the value of
$arg1
that precedes in the value of $arg1
the first occurrence of a sequence of collation units that provides
a minimal match to the collation units of $arg2
according to the collation that is used.
Note:
Minimal match is defined in [Unicode Collation Algorithm].
If the specified collation does not support collation units an error ·may· be raised [err:FOCH0004].
The collation used in these examples,
http://example.com/CollationA
is a collation in which
both "" and "*" are ignorable collation units.
"Ignorable collation unit" is equivalent to "ignorable collation element" in [Unicode Collation Algorithm].
The expression fn:substringbefore ( "tattoo",
"attoo")
returns "t"
.
The expression fn:substringbefore ( "tattoo",
"tatto")
returns ""
.
The expression fn:substringbefore ((), ())
returns
""
.
The expression fn:substringbefore ( "abcdefghi",
"de", "http://example.com/CollationA")
returns
"abc"
.
The expression fn:substringbefore ( "abcdefghi",
"de", "http://example.com/CollationA")
returns
"abc"
.
The expression fn:substringbefore ( "a*b*c*d*e*f*g*h*i*",
"***cde", "http://example.com/CollationA")
returns
"a*b*"
.
The expression fn:substringbefore ( "Eureka!",
"****", "http://example.com/CollationA")
returns
""
. (The second argument contains only ignorable
collation units and is equivalent to the zerolength
string.).
Returns the part of $arg1
that follows the first
occurrence of $arg2
, taking collations into
account.
fn:substringafter
($arg1
as
xs:string?
,
$arg2
as
xs:string?
) as
xs:string
fn:substringafter ( 
$arg1 
as xs:string? , 
$arg2 
as xs:string? , 

$collation 
as xs:string ) as xs:string 
If the value of $arg1
or $arg2
is the
empty sequence, or contains only ignorable collation units, it is
interpreted as the zerolength string.
If the value of $arg2
is the zerolength string,
then the function returns the value of $arg1
.
If the value of $arg1
does not contain a string
that is equal to the value of $arg2
, then the function
returns the zerolength string.
The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation.
The function returns the substring of the value of
$arg1
that follows in the value of $arg1
the first occurrence of a sequence of collation units that provides
a minimal match to the collation units of $arg2
according to the collation that is used.
Note:
Minimal match is defined in [Unicode Collation Algorithm].
If the specified collation does not support collation units an error ·may· be raised [err:FOCH0004].
The collation used in these examples,
http://example.com/CollationA
is a collation in which
both "" and "*" are ignorable collation units.
"Ignorable collation unit" is equivalent to "ignorable collation element" in [Unicode Collation Algorithm].
The expression fn:substringafter("tattoo", "tat")
returns "too"
.
The expression fn:substringafter("tattoo",
"tattoo")
returns ""
.
The expression fn:substringafter((), ())
returns
""
.
The expression fn:substringafter("abcdefghi", "de",
"http://example.com/CollationA")
returns
"fghi"
.
The expression fn:substringafter("abcdefghi",
"de", "http://example.com/CollationA")
returns
"fghi"
.
The expression fn:substringafter ( "a*b*c*d*e*f*g*h*i*",
"***cde***", "http://example.com/CollationA")
returns
"*f*g*h*i*"
.
The expression fn:substringafter ( "Eureka!",
"****", "http://example.com/CollationA")
returns
"Eureka!"
. (The second argument contains only
ignorable collation units and is equivalent to the zerolength
string.).
The three functions described in this section make use of a regular expression syntax for pattern matching. This is described below.
Function  Meaning 

fn:matches 
Returns true if the supplied string matches a given regular expression. 
fn:replace 
Returns a string produced from the input string by replacing any substrings that match a given regular expression with a supplied replacement string. 
fn:tokenize 
Returns a sequence of strings constructed by splitting the input wherever a separator is found; the separator is any substring that matches a given regular expression. 
fn:analyzestring 
Analyzes a string using a regular expression, returning an XML structure that identifies which parts of the input string matched or failed to match the regular expression, and in the case of matched substrings, which substrings matched each capturing group in the regular expression. 
The regular expression syntax used by these functions is defined in terms of the regular expression syntax specified in XML Schema (see [XML Schema Part 2: Datatypes Second Edition]), which in turn is based on the established conventions of languages such as Perl. However, because XML Schema uses regular expressions only for validity checking, it omits some facilities that are widelyused with languages such as Perl. This section, therefore, describes extensions to the XML Schema regular expressions syntax that reinstate these capabilities.
Note:
It is recommended that implementers consult [Unicode Regular Expressions] for information on using regular expression processing on Unicode characters.
The regular expression syntax and semantics are identical to those defined in [XML Schema Part 2: Datatypes Second Edition] with the following additions:
Two metacharacters, ^
and $
are
added. By default, the metacharacter ^
matches the
start of the entire string, while $
matches the end of
the entire string. In multiline mode, ^
matches the
start of any line (that is, the start of the entire string, and the
position immediately after a newline character), while
$
matches the end of any line (that is, the end of the
entire string, and the position immediately before a newline
character). Newline here means the character #x0A
only.
This means that the production in [XML Schema Part 2: Datatypes Second Edition]:
[10] Char ::= [^.\?*+()#x5B#x5D]
is modified to read:
[10] Char ::= [^.\?*+{}()^$#x5B#x5D]
The characters #x5B
and #x5D
correspond to "[
" and "]
"
respectively.
Note:
The definition of Char (production [10]) in [XML Schema Part 2: Datatypes Second Edition] has a known error in which it omits the left brace ("{") and right brace ("}"). That error is corrected here.
The following production:
[11] charClass ::= charClassEsc  charClassExpr 
WildCardEsc
is modified to read:
[11] charClass ::= charClassEsc  charClassExpr 
WildCardEsc  "^"  "$"
Reluctant quantifiers are supported. They are indicated
by a " ?
" following a quantifier. Specifically:
X??
matches X, once or not at all
X*?
matches X, zero or more times
X+?
matches X, one or more times
X{n}?
matches X, exactly n times
X{n,}?
matches X, at least n times
X{n,m}?
matches X, at least n times, but not more
than m times
The effect of these quantifiers is that the regular expression
matches the shortest possible substring consistent with
the match as a whole succeeding. Without the " ?
",
the regular expression matches the longest possible
substring.
To achieve this, the production in [XML Schema Part 2: Datatypes Second Edition]:
[4] quantifier ::= [?*+]  ( '{' quantity '}' )
is changed to:
[4] quantifier ::= ( [?*+]  ( '{' quantity '}' ) )
'?'?
Note:
Reluctant quantifiers have no effect on the results of the
boolean fn:matches
function, since this function is only interested in discovering
whether a match exists, and not where it exists.
Subexpressions (groups) within the regular expression are
recognized. The regular expression syntax defined by [XML Schema Part 2: Datatypes Second Edition]
allows a regular expression to contain parenthesized
subexpressions, but attaches no special significance to them. The
fn:replace
function
described below allows access to the parts of the input string that
matched a subexpression (called captured substrings). The
subexpressions are numbered according to the position of the
opening parenthesis in lefttoright order within the toplevel
regular expression: the first opening parenthesis identifies
captured substring 1, the second identifies captured substring 2,
and so on. 0 identifies the substring captured by the entire
regular expression. If a subexpression matches more than one
substring (because it is within a construct that allows
repetition), then only the last substring that it matched
will be captured.
Noncapturing groups are also recognized. These are indicated by
the syntax (?:xxxx)
. Specifically, the production rule
for atom
in [XML Schema Part 2:
Datatypes Second Edition] is changed from:
[9] atom ::= Char  charClass  ( '(' regExp ')'
)
to:
[9] atom ::= Char  charClass  ( '(' '?:'? regExp ')'
)
The presence of the optional ?:
has no effect on
the set of strings that match the regular expression, but causes
the left parenthesis not to be counted by operations that number
the groups within a regular expression, for example the fn:replace
function.
Backreferences are allowed outside a character class
expression. A backreference is an additional kind of atom.
The construct \N
where N
is a single
digit is always recognized as a backreference; if this is followed
by further digits, these digits are taken to be part of the
backreference if and only if the resulting number
NN
is such that the backreference is preceded by
NN
or more unescaped opening parentheses. The regular
expression is invalid if a backreference refers to a subexpression
that does not exist or whose closing right parenthesis occurs after
the backreference.
A backreference matches the string that was matched by the
N
th capturing subexpression within the regular
expression, that is, the parenthesized subexpression whose opening
left parenthesis is the N
th unescaped left parenthesis
within the regular expression. For example, the regular expression
('").*\1
matches a sequence of characters delimited
either by an apostrophe at the start and end, or by a quotation
mark at the start and end.
If no string is matched by the N
th capturing
subexpression, the backreference is interpreted as matching a
zerolength string.
Backreferences change the following production:
[9] atom ::= Char  charClass  ( '(' regExp ')'
)
to
[9] atom ::= Char  charClass  ( '(' regExp ')' ) 
backReference
[9a] backReference ::= "\"
[19][09]*
Note:
Within a character class expression, \
followed by a digit is invalid. Some other regular expression
languages interpret this as an octal character
reference.
Single character escapes are extended to allow the
$
character to be escaped. The following production is
changed:
[24]SingleCharEsc ::= '\'
[nrt\.?*+(){}#x2D#x5B#x5D#x5E]
to
[24]SingleCharEsc ::= '\'
[nrt\.?*+(){}$#x2D#x5B#x5D#x5E]
All these functions provide an optional parameter,
$flags
, to set options for the interpretation of the
regular expression. The parameter accepts a xs:string
,
in which individual letters are used to set options. The presence
of a letter within the string indicates that the option is on; its
absence indicates that the option is off. Letters may appear in any
order and may be repeated. If there are characters present that are
not defined here as flags, then an error is raised [err:FORX0001].
The following options are defined:
s
: If present, the match operates in "dotall"
mode. (Perl calls this the singleline mode.) If the s
flag is not specified, the metacharacter .
matches
any character except a newline (#x0A
) character. In
dotall mode, the metacharacter .
matches any
character whatsoever. Suppose the input contains "hello" and
"world" on two lines. This will not be matched by the regular
expression "hello.*world" unless dotall mode is enabled.
m
: If present, the match operates in multiline
mode. By default, the metacharacter ^
matches the
start of the entire string, while $ matches the end of the entire
string. In multiline mode, ^
matches the start of any
line (that is, the start of the entire string, and the position
immediately after a newline character other than a newline
that appears as the last character in the string), while
$
matches the end of any line (that is, the
position immediately before a newline character, and the end of the
entire string if there is no newline character at the end of the
string). Newline here means the character #x0A
only.
i
: If present, the match operates in
caseinsensitive mode. The detailed rules are as follows. In these
rules, a character C2 is considered to be a casevariant
of another character C1 if the following XPath expression returns
true
when the two characters are considered as strings
of length one, and the ·Unicode codepoint collation· is used:
fn:lowercase(C1) eq
fn:lowercase(C2)
or
fn:uppercase(C1) eq
fn:uppercase(C2)
Note that the casevariants of a character under this definition are always single characters.
When a normal character (Char
) is used as an atom,
it represents the set containing that character and all its
casevariants. For example, the regular expression "z" will match
both "z" and "Z".
A character range (charRange
) represents the set
containing all the characters that it would match in the absence of
the "i
" flag, together with their casevariants. For
example, the regular expression "[AZ]" will match all the letters
AZ and all the letters az. It will also match certain other
characters such as #x212A
(KELVIN SIGN), since
fn:lowercase("#x212A")
is "k".
This rule applies also to a character range used in a character
class subtraction (charClassSub
): thus [AZ[IO]] will
match characters such as "A", "B", "a", and "b", but will not match
"I", "O", "i", or "o".
The rule also applies to a character range used as part of a negative character group: thus [^Q] will match every character except "Q" and "q" (these being the only casevariants of "Q" in Unicode).
A backreference is compared using caseblind comparison: that
is, each character must either be the same as the corresponding
character of the previously matched string, or must be a
casevariant of that character. For example, the strings "Mum",
"mom", "Dad", and "DUD" all match the regular expression
"([md])[aeiou]\1" when the "i
" flag is used.
All other constructs are unaffected by the "i
"
flag. For example, "\p{Lu}" continues to match uppercase letters
only.
x
: If present, whitespace characters (#x9, #xA, #xD
and #x20) in the regular expression are removed prior to matching
with one exception: whitespace characters within character class
expressions (charClassExpr
) are not removed. This flag
can be used, for example, to break up long regular expressions into
readable lines.
Examples:
fn:matches("helloworld", "hello
world", "x")
returns true()
fn:matches("helloworld", "hello[
]world", "x")
returns false()
fn:matches("hello world", "hello\
sworld", "x")
returns true()
fn:matches("hello world", "hello
world", "x")
returns false()
q
: if present, all characters in the regular
expression are treated as representing themselves, not as
metacharacters. In effect, every character that would normally have
a special meaning in a regular expression is implicitly escaped by
preceding it with a backslash.
Furthermore, when this flag is present, the characters
$
and \
have no special significance when
used in the replacement string supplied to the fn:replace
function.
This flag can be used in conjunction with the i
flag. If it is used together with the m
,
s
, or x
flag, that flag has no
effect.
Examples:
fn:tokenize("12.3.5.6", ".",
"q")
returns ("12", "3", "5", "6")
fn:replace("a\b\c", "\", "\\",
"q")
returns "a\\b\\c"
fn:replace("a/b/c", "/", "$",
"q")
returns "a$b$c"
fn:matches("abcd", ".*",
"q")
returns false()
fn:matches("Mr. B. Obama", "B.
OBAMA", "iq")
returns true()
Returns true if the supplied string matches a given regular expression.
fn:matches
($input
as
xs:string?
,
$pattern
as
xs:string
) as
xs:boolean
fn:matches ( 
$input 
as xs:string? , 
$pattern 
as xs:string , 

$flags 
as xs:string ) as xs:boolean 
The effect of calling the first version of this function
(omitting the argument $flags
) is the same as the
effect of calling the second version with the $flags
argument set to a zerolength string. Flags are defined in 5.6.1.1 Flags.
If $input
is the empty sequence, it is interpreted
as the zerolength string.
The function returns true
if $input
or
some substring of $input
matches the regular
expression supplied as $pattern
. Otherwise, the
function returns false
. The matching rules are
influenced by the value of $flags
if present.
An error is raised [err:FORX0002] if the value of
$pattern
is invalid according to the rules described
in 5.6.1 Regular expression
syntax.
An error is raised [err:FORX0001] if the value of
$flags
is invalid according to the rules described in
5.6.1.1 Flags.
Unless the metacharacters ^
and $
are
used as anchors, the string is considered to match the pattern if
any substring matches the pattern. But if anchors are used, the
anchors must match the start/end of the string (in string mode), or
the start/end of a line (in multiline mode).
This is different from the behavior of patterns in [XML Schema Part 2: Datatypes Second Edition], where regular expressions are implicitly anchored.
Regular expression matching is defined on the basis of Unicode code points; it takes no account of collations.
The expression fn:matches("abracadabra", "bra")
returns true()
.
The expression fn:matches("abracadabra", "^a.*a$")
returns true()
.
The expression fn:matches("abracadabra", "^bra")
returns false()
.
Given the source document:
let $poem
:=
<poem author="Wilhelm Busch"> Kaum hat dies der Hahn gesehen, Fängt er auch schon an zu krähen: Kikeriki! Kikikerikih!! Tak, tak, tak!  da kommen sie. </poem>
the following function calls produce the following results, with
the poem
element as the context node:
The expression fn:matches($poem, "Kaum.*krähen")
returns false()
.
The expression fn:matches($poem, "Kaum.*krähen",
"s")
returns true()
.
The expression fn:matches($poem, "^Kaum.*gesehen,$",
"m")
returns true()
.
The expression fn:matches($poem,
"^Kaum.*gesehen,$")
returns false()
.
The expression fn:matches($poem, "kiki", "i")
returns true()
.
Returns a string produced from the input string by replacing any substrings that match a given regular expression with a supplied replacement string.
fn:replace ( 
$input 
as xs:string? , 
$pattern 
as xs:string , 

$replacement 
as xs:string ) as xs:string 
fn:replace ( 
$input 
as xs:string? , 
$pattern 
as xs:string , 

$replacement 
as xs:string , 

$flags 
as xs:string ) as xs:string 
The effect of calling the first version of this function
(omitting the argument $flags
) is the same as the
effect of calling the second version with the $flags
argument set to a zerolength string. Flags are defined in 5.6.1.1 Flags.
The $flags
argument is interpreted in the same
manner as for the fn:matches
function.
If $input
is the empty sequence, it is interpreted
as the zerolength string.
The function returns the xs:string
that is obtained
by replacing each nonoverlapping substring of $input
that matches the given $pattern
with an occurrence of
the $replacement
string.
If two overlapping substrings of $input
both match
the $pattern
, then only the first one (that is, the
one whose first ·character· comes first in the $input
string)
is replaced.
If the q
flag is present, the replacement string is
used as is.
Otherwise, within the $replacement
string, a variable $N
may be used to refer to the
substring captured by the Nth parenthesized subexpression in the
regular expression. For each match of the pattern, these variables
are assigned the value of the content matched by the relevant
subexpression, and the modified replacement string is then
substituted for the ·characters· in $input
that matched the
pattern. $0
refers to the substring captured by the
regular expression as a whole.
More specifically, the rules are as follows, where
S
is the number of parenthesized subexpressions in
the regular expression, and N
is the decimal number
formed by taking all the digits that consecutively follow the
$
character:
If N
=0
, then the variable is replaced
by the substring matched by the regular expression as a whole.
If 1
<=N
<=S
, then
the variable is replaced by the substring captured by the Nth
parenthesized subexpression. If the Nth
parenthesized
subexpression was not matched, then the variable is replaced by
the zerolength string.
If S
<N
<=9
, then the
variable is replaced by the zerolength string.
Otherwise (if N
>S
and
N
>9
), the last digit of N
is taken to be a literal character to be included "as is" in the
replacement string, and the rules are reapplied using the number
N
formed by stripping off this last digit.
For example, if the replacement string is " $23
"
and there are 5 substrings, the result contains the value of the
substring that matches the second subexpression, followed by the
digit " 3
".
Unless the q
flag is used, a literal $
character within the replacement string must be written as
\$
, and a literal \
character must be
written as \\
.
If two alternatives within the pattern both match at the same
position in the $input
, then the match that is chosen
is the one matched by the first alternative. For example:
fn:replace("abcd", "(ab)(a)", "[1=$1][2=$2]") returns "[1=ab][2=]cd"
An error is raised [err:FORX0002] if the value of
$pattern
is invalid according to the rules described
in section 5.6.1 Regular expression
syntax.
An error is raised [err:FORX0001] if the value of
$flags
is invalid according to the rules described in
section 5.6.1 Regular expression
syntax.
An error is raised [err:FORX0003] if the pattern matches a
zerolength string, that is, if the expression fn:matches("", $pattern, $flags)
returns true
. It is not an error, however, if a
captured substring is zerolength.
An error is raised [err:FORX0004] if the value of
$replacement
contains a "$
" character
that is not immediately followed by a digit 09
and
not immediately preceded by a "\".
An error is raised [err:FORX0004] if the value of
$replacement
contains a "\
" character
that is not part of a "\\
" pair, unless it is
immediately followed by a "$
" character.
If the input string contains no substring that matches the regular expression, the result of the function is a single string identical to the input string.
The expression replace("abracadabra", "bra", "*")
returns "a*cada*"
.
The expression replace("abracadabra", "a.*a", "*")
returns "*"
.
The expression replace("abracadabra", "a.*?a", "*")
returns "*c*bra"
.
The expression replace("abracadabra", "a", "")
returns "brcdbr"
.
The expression replace("abracadabra", "a(.)",
"a$1$1")
returns "abbraccaddabbra"
.
The expression replace("abracadabra", ".*?", "$1")
raises an error, because the pattern matches the zerolength
string
The expression replace("AAAA", "A+", "b")
returns
"b"
.
The expression replace("AAAA", "A+?", "b")
returns
"bbbb"
.
The expression replace("darted", "^(.*?)d(.*)$",
"$1c$2")
returns "carted"
. (The first
d
is replaced.).
Returns a sequence of strings constructed by splitting the input wherever a separator is found; the separator is any substring that matches a given regular expression.
fn:tokenize
($input
as
xs:string?
,
$pattern
as
xs:string
) as
xs:string*
fn:tokenize ( 
$input 
as xs:string? , 
$pattern 
as xs:string , 

$flags 
as xs:string ) as xs:string* 
The effect of calling the first version of this function
(omitting the argument $flags
) is the same as the
effect of calling the second version with the $flags
argument set to a zerolength string. Flags are defined in 5.6.1.1 Flags.
The $flags
argument is interpreted in the same way
as for the fn:matches
function.
If $input
is the empty sequence, or if
$input
is the zerolength string, the function returns
the empty sequence.
The function returns a sequence of strings formed by breaking
the $input
string into a sequence of strings, treating
any substring that matches $pattern
as a separator.
The separators themselves are not returned.
If a separator occurs at the start of the $input
string, the result sequence will start with a zerolength string.
Zerolength strings will also occur in the result sequence if a
separator occurs at the end of the $input
string, or
if two adjacent substrings match the supplied
$pattern
.
If two alternatives within the supplied $pattern
both match at the same position in the $input
string,
then the match that is chosen is the first. For example:
fn:tokenize("abracadabra", "(ab)(a)") returns ("", "r", "c", "d", "r", "")
An error is raised [err:FORX0002] if the value of
$pattern
is invalid according to the rules described
in section 5.6.1 Regular expression
syntax.
An error is raised [err:FORX0001] if the value of
$flags
is invalid according to the rules described in
section 5.6.1 Regular expression
syntax.
If the supplied $pattern
matches a zerolength
string, that is, if fn:matches("",
$pattern, $flags)
returns true
, then an
error is raised: [err:FORX0003].
If the input string is not zero length, and no separators are found in the input string, the result of the function is a single string identical to the input string.
The expression fn:tokenize("The cat sat on the mat",
"\s+")
returns ("The", "cat", "sat", "on", "the",
"mat")
.
The expression fn:tokenize("1, 15, 24, 50", ",\s*")
returns ("1", "15", "24", "50")
.
The expression fn:tokenize("1,15,,24,50,", ",")
returns ("1", "15", "", "24", "50", "")
.
fn:tokenize("abba", ".?")
raises the error
[err:FORX0003].
The expression fn:tokenize("Some unparsed <br> HTML
<BR> text", "\s*<br>\s*", "i")
returns
("Some unparsed", "HTML", "text")
.
Analyzes a string using a regular expression, returning an XML structure that identifies which parts of the input string matched or failed to match the regular expression, and in the case of matched substrings, which substrings matched each capturing group in the regular expression.
fn:analyzestring ( 
$input 
as xs:string? , 
$pattern 
as xs:string ) as element(fn:analyzestringresult) 
fn:analyzestring ( 
$input 
as xs:string? , 
$pattern 
as xs:string , 

$flags 
as xs:string ) as element(fn:analyzestringresult) 
The effect of calling the first version of this function
(omitting the argument $flags
) is the same as the
effect of calling the second version with the $flags
argument set to a zerolength string. Flags are defined in 5.6.1.1 Flags.
The $flags
argument is interpreted in the same way
as for the fn:matches
function.
If $input
is the empty sequence the function
behaves as if $input
were the zerolength string. In
this situation the result will be an element node with no
children.
The function returns an element node whose local name is
analyzestringresult
. This element and all its
descendant elements have the namespace URI
http://www.w3.org/2005/xpathfunctions
. The namespace
prefix is ·implementation dependent·. The children of this element are a sequence
of fn:match
and fn:nonmatch
elements.
This sequence is formed by breaking the $input
string
into a sequence of strings, returning any substring that matches
$pattern
as the content of a match
element, and any intervening substring as the content of a
nonmatch
element.
More specifically, the function starts at the beginning of the
input string and attempts to find the first substring that matches
the regular expression. If there are several matches, the first
match is defined to be the one whose starting position comes first
in the string. If several alternatives within the regular
expression both match at the same position in the input string,
then the match that is chosen is the first alternative that
matches. For example, if the input string is The quick brown
fox jumps
and the regular expression is
jumpjumps
, then the match that is chosen is
jump
.
Having found the first match, the instruction proceeds to find the second and subsequent matches by repeating the search, starting at the first ·character· that was not included in the previous match.
The input string is thus partitioned into a sequence of
substrings, some of which match the regular expression, others
which do not match it. Each substring will contain at least one
character. This sequence is represented in the result by the
sequence of fn:match
and fn:nonmatch
children of the returned element node; the string value of the
fn:match
or fn:nonmatch
element will be
the corresponding substring of $input
, and the string
value of the returned element node will therefore be the same as
$input
.
The content of an fn:nonmatch
element is always a
single text node.
The content of a fn:match
element, however, is in
general a sequence of text nodes and fn:group
element
children. An fn:group
element with a nr
attribute having the integer value N identifies the
substring captured by the Nth parenthesized
subexpression in the regular expression. For each capturing
subexpression there will be at most one corresponding
fn:group
element in each fn:match
element
in the result.
If the function is called twice with the same arguments, it is ·implementation dependent· whether the two calls return the same element node or distinct (but deep equal) element nodes.
A schema is defined for the structure of the returned element,
containing the definitions below. The returned element and its
descendants will have type annotations obtained by validating the
returned element against this schema, unless the function is used
in an environment where type annotations are not supported (for
example, a Basic XSLT Processor), in which case the elements will
all be annotated as xs:untyped
and the attributes as
xs:untypedAtomic
.
<?xml version="1.0" encoding="UTF8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.w3.org/2005/xpathfunctions" xmlns:fn="http://www.w3.org/2005/xpathfunctions" elementFormDefault="qualified"> <xs:element name="analyzestringresult" type="fn:analyzestringresulttype"/> <xs:element name="match" type="fn:matchtype"/> <xs:element name="nonmatch" type="xs:string"/> <xs:element name="group" type="fn:grouptype"/> <xs:complexType name="analyzestringresulttype" mixed="true"> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element ref="fn:match"/> <xs:element ref="fn:nonmatch"/> </xs:choice> </xs:complexType> <xs:complexType name="matchtype" mixed="true"> <xs:sequence> <xs:element ref="fn:group" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <xs:complexType name="grouptype" mixed="true"> <xs:sequence> <xs:element ref="fn:group" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="nr" type="xs:positiveInteger"/> </xs:complexType> </xs:schema>
An error is raised [err:FORX0002] if the value of
$pattern
is invalid according to the rules described
in section 5.6.1 Regular expression
syntax.
An error is raised [err:FORX0001] if the value of
$flags
is invalid according to the rules described in
section 5.6.1 Regular expression
syntax.
If the supplied $pattern
matches a zerolength
string, that is, if fn:matches("",
$pattern, $flags)
returns true
, then an
error is raised: [err:FORX0003].
In the following examples, the result document is shown in serialized form, with whitespace between the element nodes. This whitespace is not actually present in the result.
The expression fn:analyzestring("The cat sat on the
mat.", "\w+")
returns <analyzestringresult
xmlns="http://www.w3.org/2005/xpathfunctions">
<match>The</match> <nonmatch> </nonmatch>
<match>cat</match> <nonmatch> </nonmatch>
<match>sat</match> <nonmatch> </nonmatch>
<match>on</match> <nonmatch> </nonmatch>
<match>the</match> <nonmatch> </nonmatch>
<match>mat</match> <nonmatch>.</nonmatch>
</analyzestringresult>
.
The expression fn:analyzestring("20081203",
"^(\d+)\(\d+)\(\d+)$")
returns
<analyzestringresult
xmlns="http://www.w3.org/2005/xpathfunctions">
<match><group nr="1">2008</group><group
nr="2">12</group><group
nr="3">03</group></match>
</analyzestringresult>
.
The expression fn:analyzestring("A1,C15,,D24, X50,",
"([AZ])([09]+)")
returns <analyzestringresult
xmlns="http://www.w3.org/2005/xpathfunctions">
<match><group nr="1">A</group><group
nr="2">1</group></match>
<nonmatch>,</nonmatch> <match><group
nr="1">C</group><group
nr="2">15</group></match>
<nonmatch>,,</nonmatch> <match><group
nr="1">D</group><group
nr="2">24</group></match> <nonmatch>,
</nonmatch> <match><group
nr="1">X</group><group
nr="2">50</group></match>
<nonmatch>,</nonmatch>
</analyzestringresult>
.
This section specifies functions that manipulate URI values,
either as instances of xs:anyURI
or as strings.
Function  Meaning 

fn:resolveuri 
Resolves a relative IRI reference against an absolute IRI. 
fn:encodeforuri 
Encodes reserved characters in a string that is intended to be used in the path segment of a URI. 
fn:iritouri 
Converts a string containing an IRI into a URI according to the rules of [RFC 3987]. 
fn:escapehtmluri 
Escapes a URI in the same way that HTML user agents handle attribute values expected to contain URIs. 
Resolves a relative IRI reference against an absolute IRI.
fn:resolveuri
($relative
as
xs:string?
) as
xs:anyURI?
fn:resolveuri
($relative
as
xs:string?
,
$base
as
xs:string
) as
xs:anyURI?
If the second argument is absent, the effect is the same as
calling the twoargument function with the value of fn:staticbaseuri()
as
the second argument.
The function is defined to operate on IRI references as defined in [RFC 3987], and the implementation must permit all arguments that are valid according to that specification. In addition, the implementation may accept some or all strings that conform to the rules for (absolute or relative) Legacy Extended IRI references as defined in [Legacy extended IRIs for XML resource identification]. For the purposes of this section, the terms IRI and IRI reference include these extensions, insofar as the implementation chooses to support them.
If $relative
is the empty sequence, the function
returns the empty sequence.
If $relative
is an absolute IRI (as defined above),
then it is returned unchanged.
Otherwise, the function resolves the relative IRI reference
$relative
against the base IRI $base
using the algorithm defined in [RFC 3986],
adapted by treating any ·character· that would not be valid in an RFC3986 URI or
relative reference in the same way that RFC3986 treats unreserved
characters. No percentencoding takes place.
The first form of this function resolves $relative
against the value of the baseuri property from the static context.
If the baseuri property is not initialized in the static context
an error is raised [err:FONS0005].
If $relative
is not a valid IRI according to the
rules of RFC3987, extended with an implementationdefined subset of
the extensions permitted in LEIRI, or if it is not a suitable
relative reference to use as input to the RFC3986 resolution
algorithm extended to handle additional unreserved characters, then
an error is raised [err:FORG0002].
If $base
is not a valid IRI according to the rules
of RFC3987, extended with an implementationdefined subset of the
extensions permitted in LEIRI, or if it is not a suitable IRI to
use as input to the chosen resolution algorithm (for example, if it
is a relative IRI reference, if it is a nonhierarchic URI, or if
it contains a fragment identifier), then an error is raised
[err:FORG0002].
If the chosen resolution algorithm fails for any other reason then an error is raised [err:FORG0009].
Resolving a URI does not dereference it. This is merely a syntactic operation on two ·strings·.
The algorithms in the cited RFCs include some variations that are optional or recommended rather than mandatory; they also describe some common practices that are not recommended, but which are permitted for backwards compatibility. Where the cited RFCs permit variations in behavior, so does this specification.
Throughout this family of specifications, the phrase "resolving a relative URI (or IRI) reference" should be understood as using the rules of this function, unless otherwise stated.
Encodes reserved characters in a string that is intended to be used in the path segment of a URI.
fn:encodeforuri
($uripart
as
xs:string?
) as
xs:string
If $uripart
is the empty sequence, the function
returns the zerolength string.
This function applies the URI escaping rules defined in section
2 of [RFC 3986] to the
xs:string
supplied as $uripart
. The
effect of the function is to escape reserved characters. Each such
character in the string is replaced with its percentencoded form
as described in [RFC 3986].
Since [RFC 3986] recommends that, for consistency, URI producers and normalizers should use uppercase hexadecimal digits for all percentencodings, this function must always generate hexadecimal values using the uppercase letters AF.
All characters are escaped except those identified as "unreserved" by [RFC 3986], that is the upper and lowercase letters AZ, the digits 09, HYPHENMINUS (""), LOW LINE ("_"), FULL STOP ".", and TILDE "~".
This function escapes URI delimiters and therefore cannot be used indiscriminately to encode "invalid" characters in a path segment.
This function is invertible but not idempotent. This is because
a string containing a percent character will be modified by
applying the function: for example 100%
becomes
100%25
, while 100%25
becomes
100%2525
.
The expression
fn:encodeforuri("http://www.example.com/00/Weather/CA/Los%20Angeles#ocean")
returns
"http%3A%2F%2Fwww.example.com%2F00%2FWeather%2FCA%2FLos%2520Angeles%23ocean"
.
(This is probably not what the user intended because all of the
delimiters have been encoded.).
The expression concat("http://www.example.com/",
encodeforuri("~bébé"))
returns
"http://www.example.com/~b%C3%A9b%C3%A9"
.
The expression concat("http://www.example.com/",
encodeforuri("100% organic"))
returns
"http://www.example.com/100%25%20organic"
.
Converts a string containing an IRI into a URI according to the rules of [RFC 3987].
fn:iritouri
($iri
as
xs:string?
) as
xs:string
If $iri
is the empty sequence, the function returns
the zerolength string.
Otherwise, the function converts the value of $iri
into a URI according to the rules given in Section 3.1 of [RFC 3987] by percentencoding characters that are
allowed in an IRI but not in a URI. If $iri
contains a
character that is invalid in an IRI, such as the space character
(see note below), the invalid character is replaced by its
percentencoded form as described in [RFC
3986] before the conversion is performed.
Since [RFC 3986] recommends that, for consistency, URI producers and normalizers should use uppercase hexadecimal digits for all percentencodings, this function must always generate hexadecimal values using the uppercase letters AF.
The function is idempotent but not invertible. Both the inputs
My Documents
and My%20Documents
will be
converted to the output My%20Documents
.
This function does not check whether $iri
is a
valid IRI. It treats it as an ·string· and operates on the ·characters· in the
string.
The following printable ASCII characters are invalid in an IRI:
"<", ">", " " " (double quote), space, "{", "}", "", "\",
"^", and "`". Since these characters should not appear in an IRI,
if they do appear in $iri
they will be
percentencoded. In addition, characters outside the range
x20x7E will be percentencoded because they are
invalid in a URI.
Since this function does not escape the PERCENT SIGN "%" and this character is not allowed in data within a URI, users wishing to convert character strings (such as file names) that include "%" to a URI should manually escape "%" by replacing it with "%25".
The expression fn:iritouri
("http://www.example.com/00/Weather/CA/Los%20Angeles#ocean")
returns
"http://www.example.com/00/Weather/CA/Los%20Angeles#ocean"
.
The expression fn:iritouri
("http://www.example.com/~bébé")
returns
"http://www.example.com/~b%C3%A9b%C3%A9"
.
Escapes a URI in the same way that HTML user agents handle attribute values expected to contain URIs.
fn:escapehtmluri
($uri
as
xs:string?
) as
xs:string
If $uri
is the empty sequence, the function returns
the zerolength string.
Otherwise, the function escapes all ·characters· except
printable characters of the USASCII coded character set,
specifically the ·codepoints· between 32 and 126 (decimal) inclusive. Each
character in $uri
to be escaped is replaced by an
escape sequence, which is formed by encoding the character as a
sequence of octets in UTF8, and then representing each of these
octets in the form %HH, where HH is the hexadecimal representation
of the octet. This function must always generate hexadecimal values
using the uppercase letters AF.
The behavior of this function corresponds to the recommended handling of nonASCII characters in URI attribute values as described in [HTML 4.0] Appendix B.2.1.
The expression fn:escapehtmluri
("http://www.example.com/00/Weather/CA/Los Angeles#ocean")
returns "http://www.example.com/00/Weather/CA/Los
Angeles#ocean"
.
The expression fn:escapehtmluri ("javascript:if
(navigator.browserLanguage == 'fr')
window.open('http://www.example.com/~bébé');")
returns
"javascript:if (navigator.browserLanguage == 'fr')
window.open('http://www.example.com/~b%C3%A9b%C3%A9');"
.
This section defines functions and operators on the
xs:boolean
datatype.
Since no literals are defined in XPath to reference the constant boolean values true and false, two functions are provided for the purpose.
Function  Meaning 

fn:true 
Returns the xs:boolean value
true . 
fn:false 
Returns the xs:boolean value
false . 
The following functions define the semantics of operators on boolean values in [XQuery 3.0: An XML Query Language] and [XML Path Language (XPath) 3.0]:
Function  Meaning 

op:booleanequal 
Returns true if the two arguments are the same
boolean value. 
op:booleanlessthan 
Returns true if the first argument is false and the second is true. 
op:booleangreaterthan 
Returns true if the first argument is true and the second is false. 
The ordering operators op:booleanlessthan
and
op:booleangreaterthan
are provided for application purposes and for compatibility with
[XML Path Language (XPath) Version 1.0]. The
[XML Schema Part 2: Datatypes Second
Edition] datatype xs:boolean
is not ordered.
Returns true
if the two arguments are the same
boolean value.
Defines the semantics of the "eq" operator on
xs:boolean
values.
op:booleanequal
($value1
as
xs:boolean
,
$value2
as
xs:boolean
) as
xs:boolean
The function returns true
if both arguments are
true
or if both arguments are false
. It
returns false
if one of the arguments is
true
and the other argument is false
.
Returns true if the first argument is false and the second is true.
Defines the semantics of the "lt" operator on
xs:boolean
values. Also used in the definition of the
"ge" operator.
op:booleanlessthan
($arg1
as
xs:boolean
,
$arg2
as
xs:boolean
) as
xs:boolean
The function returns true
if $arg1
is
false
and $arg2
is true
.
Otherwise, it returns false
.
Returns true if the first argument is true and the second is false.
Defines the semantics of the "gt" operator on
xs:boolean
values. Also used in the definition of the
"le" operator.
op:booleangreaterthan
($arg1
as
xs:boolean
,
$arg2
as
xs:boolean
) as
xs:boolean
The function call op:booleangreaterthan($A, $B)
is defined to return the same result as op:booleanlessthan($B,
$A)
The following functions are defined on boolean values:
Function  Meaning 

fn:boolean 
Computes the effective boolean value of the sequence
$arg . 
fn:not 
Returns true if the effective boolean value of
$arg is false , or false if
it is true . 
Computes the effective boolean value of the sequence
$arg
.
fn:boolean
($arg
as
item()*
) as
xs:boolean
The function computes the effective boolean value of a sequence, defined according to the following rules. See also Section 2.4.3 Effective Boolean Value^{XP}.
If $arg
is the empty sequence,
fn:boolean
returns false
.
If $arg
is a sequence whose first item is a node,
fn:boolean
returns true
.
If $arg
is a singleton value of type
xs:boolean
or a derived from xs:boolean
,
fn:boolean
returns $arg
.
If $arg
is a singleton value of type
xs:string
or a type derived from
xs:string
, xs:anyURI
or a type derived
from xs:anyURI
or xs:untypedAtomic
,
fn:boolean
returns false
if the operand
value has zero length; otherwise it returns true
.
If $arg
is a singleton value of any numeric type or
a type derived from a numeric type, fn:boolean
returns
false
if the operand value is NaN
or is
numerically equal to zero; otherwise it returns
true
.
In all other cases, fn:boolean
raises a type error
[err:FORG0006].
The static semantics of this function are described in [Formal Semantics].
The result of this function is not necessarily the same as
$arg cast as xs:boolean
. For example,
fn:boolean("false")
returns the value
true
whereas "false"cast as xs:boolean
(which can also be written xs:boolean("false")
)
returns false
.
let $abc
:= ("a", "b", "")
fn:boolean($abc)
raises a type error [err:FORG0006].
The expression fn:boolean($abc[1])
returns
true()
.
The expression fn:boolean($abc[0])
returns
false()
.
The expression fn:boolean($abc[3])
returns
false()
.
Returns true
if the effective boolean value of
$arg
is false
, or false
if
it is true
.
fn:not
($arg
as
item()*
) as
xs:boolean
The value of $arg
is first reduced to an effective
boolean value by applying the fn:boolean()
function. The
function returns true
if the effective boolean value
is false
, or false
if the effective
boolean value is true
.
The expression fn:not(fn:true())
returns
false()
.
The expression fn:not("false")
returns
false()
.
Operators are defined on the following type:
xs:duration
and on the two defined subtypes (see 8.1 Two totally ordered subtypes of duration):
xs:yearMonthDuration
xs:dayTimeDuration
No ordering relation is defined on xs:duration
values. Two xs:duration
values may however be compared
for equality.
Operations on durations (including equality comparison, casting to string, and extraction of components) all treat the duration as normalized. This means that the seconds and minutes components will always be less than 60, the hours component less than 24, and the months component less than 12. Thus, for example, a duration of 120 seconds always gives the same result as a duration of two minutes.
Conditions such as underflow and overflow may occur with arithmetic on durations: see 9.7.1 Limits and precision
Note:
This means that in practice, the information content of an
xs:duration
value can be reduced to an
xs:integer
number of months, and an
xs:decimal
number of seconds. For the two defined
subtypes this is further simplified so that one of these two
components is fixed at zero. Operations such as comparison of
durations and arithmetic on durations can be expressed in terms of
numeric operations applied to these two components.
Two totally ordered subtypes of xs:duration
are
defined in Section
Types^{DM30} specification using the
mechanisms described in [XML Schema Part 2:
Datatypes Second Edition] for defining userdefined types.
Additional details about these types is given below.
Note:
These types were not defined in XSD 1.0, but they are defined in the current draft of XSD 1.1. The description given here is believed to be equivalent to that in XSD 1.1, and will become nonnormative when XSD 1.1 reaches Recommendation status.
[Definition] xs:yearMonthDuration
is derived from
xs:duration
by restricting its lexical representation
to contain only the year and month components. The value space of
xs:yearMonthDuration
is the set of
xs:integer
month values. The year and month components
of xs:yearMonthDuration
correspond to the Gregorian
year and month components defined in section 5.5.3.2 of [ISO 8601], respectively.
The lexical representation for xs:yearMonthDuration
is the [ISO 8601] reduced format PnYnM,
where nY represents the number of years and nM the number of
months. The values of the years and months components are not
restricted but allow an arbitrary unsigned
xs:integer
.
An optional preceding minus sign ('') is allowed to indicate a
negative duration. If the sign is omitted a positive duration is
indicated. To indicate a xs:yearMonthDuration
of 1
year, 2 months, one would write: P1Y2M. One could also indicate a
xs:yearMonthDuration
of minus 13 months as: P13M.
Reduced precision and truncated representations of this format are allowed provided they conform to the following:
If the number of years or months in any expression equals zero (0), the number and its corresponding designator ·may· be omitted. However, at least one number and its designator ·must· be present. For example, P1347Y and P1347M are allowed; P1347M is not allowed, although P1347M is allowed. P1Y2MT is not allowed. Also, P24YM is not allowed, nor is PY43M since Y must have at least one preceding digit and M must have one preceding digit.
The value of a xs:yearMonthDuration
lexical form is
obtained by multiplying the value of the years component by 12 and
adding the value of the months component. The value is positive or
negative depending on the preceding sign.
The canonical representation of
xs:yearMonthDuration
restricts the value of the months
component to xs:integer
values between 0 and 11, both
inclusive. To convert from a noncanonical representation to the
canonical representation, the lexical representation is first
converted to a value in xs:integer
months as defined
above. This value is then divided by 12 to obtain the value of the
years component of the canonical representation. The remaining
number of months is the value of the months component of the
canonical representation. For negative durations, the canonical
form is calculated using the absolute value of the duration and a
negative sign is prepended to it. If a component has the value zero
(0), then the number and the designator for that component
·must· be omitted.
However, if the value is zero (0) months, the canonical form is
"P0M".
Let the function that calculates the value of an
xs:yearMonthDuration
in the manner described above be
called V(d). Then for two xs:yearMonthDuration
values
x and y, x > y if and only if V(x) > V(y). The order relation
on yearMonthDuration
is a total order.
[Definition] xs:dayTimeDuration
is derived from
xs:duration
by restricting its lexical representation
to contain only the days, hours, minutes and seconds components.
The value space of xs:dayTimeDuration
is the set of
fractional second values. The components of
xs:dayTimeDuration
correspond to the day, hour, minute
and second components defined in Section 5.5.3.2 of [ISO 8601], respectively.
The lexical representation for xs:dayTimeDuration
is the [ISO 8601] truncated format
PnDTnHnMnS, where nD represents the number of days, T is the
date/time separator, nH the number of hours, nM the number of
minutes and nS the number of seconds.
The values of the days, hours and minutes components are not
restricted, but allow an arbitrary unsigned
xs:integer
. Similarly, the value of the seconds
component allows an arbitrary unsigned xs:decimal
. An
optional minus sign ('') is allowed to precede the 'P', indicating
a negative duration. If the sign is omitted, the duration is
positive. See also [ISO 8601] Date and Time
Formats.
For example, to indicate a duration of 3 days, 10 hours and 30 minutes, one would write: P3DT10H30M. One could also indicate a duration of minus 120 days as: P120D. Reduced precision and truncated representations of this format are allowed, provided they conform to the following:
If the number of days, hours, minutes, or seconds in any expression equals zero (0), the number and its corresponding designator ·may· be omitted. However, at least one number and its designator ·must· be present.
The seconds part ·may· have a decimal fraction.
The designator 'T' ·must· be absent if and only if all of the time items are absent. The designator 'P' ·must· always be present.
For example, P13D, PT47H, P3DT2H, PT35.89S and P4DT251M are all allowed. P134D is not allowed (invalid location of minus sign), although P134D is allowed.
The value of a xs:dayTimeDuration
lexical form in
fractional seconds is obtained by converting the days, hours,
minutes and seconds value to fractional seconds using the
conversion rules: 24 hours = 1 day, 60 minutes = 1 hour and 60
seconds = 1 minute.
The canonical representation of xs:dayTimeDuration
restricts the value of the hours component to
xs:integer
values between 0 and 23, both inclusive;
the value of the minutes component to xs:integer
values between 0 and 59; both inclusive; and the value of the
seconds component to xs:decimal
valued from 0.0 to
59.999... (see [XML Schema Part 2: Datatypes
Second Edition], Appendix D).
To convert from a noncanonical representation to the canonical representation, the value of the lexical form in fractional seconds is first calculated in the manner described above. The value of the days component in the canonical form is then calculated by dividing the value by 86,400 (24*60*60). The remainder is in fractional seconds. The value of the hours component in the canonical form is calculated by dividing this remainder by 3,600 (60*60). The remainder is again in fractional seconds. The value of the minutes component in the canonical form is calculated by dividing this remainder by 60. The remainder in fractional seconds is the value of the seconds component in the canonical form. For negative durations, the canonical form is calculated using the absolute value of the duration and a negative sign is prepended to it. If a component has the value zero (0) then the number and the designator for that component must be omitted. However, if all the components of the lexical form are zero (0), the canonical form is "PT0S".
Function  Meaning 

op:yearMonthDurationlessthan 
Returns true if $arg1 is a shorter duration than
$arg2 . 
op:yearMonthDurationgreaterthan 
Returns true if $arg1 is a longer duration than
$arg2 . 
op:dayTimeDurationlessthan 
Returns true if $arg1 is a shorter duration than
$arg2 . 
op:dayTimeDurationgreaterthan 
Returns true if $arg1 is a longer duration than
$arg2 . 
op:durationequal 
Returns true if $arg1 and $arg2 are
durations of the same length. 
The following comparison operators are defined on the [XML Schema Part 2: Datatypes Second Edition]
duration datatypes. Each operator takes two operands of the same
type and returns an xs:boolean
result. As discussed in
[XML Schema Part 2: Datatypes Second
Edition], the order relation on xs:duration
is not
a total order but, rather, a partial order. For this reason, only
equality is defined on xs:duration
. A full complement
of comparison and arithmetic functions are defined on the two
subtypes of duration described in 8.1 Two totally ordered subtypes of
duration which do have a total order.
Returns true if $arg1
is a shorter duration than
$arg2
.
Defines the semantics of the "lt" operator on
xs:yearMonthDuration
values. Also used in the
definition of the "ge" operator.
op:yearMonthDurationlessthan ( 
$arg1 
as xs:yearMonthDuration , 
$arg2 
as xs:yearMonthDuration ) as xs:boolean 
If the number of months in the value of $arg1
is
numerically less than the number of months in the value of
$arg2
, the function returns true.
Otherwise, the function returns false.
Either or both durations may be negative
Returns true if $arg1
is a longer duration than
$arg2
.
Defines the semantics of the "gt" operator on
xs:yearMonthDuration
values. Also used in the
definition of the "le" operator.
op:yearMonthDurationgreaterthan ( 
$arg1 
as xs:yearMonthDuration , 
$arg2 
as xs:yearMonthDuration ) as xs:boolean 
The function call op:yearMonthDurationgreaterthan($A,
$B)
is defined to return the same result as op:yearMonthDurationlessthan($B,
$A)
Returns true if $arg1
is a shorter duration than
$arg2
.
Defines the semantics of the "lt" operator on
xs:dayTimeDuration
values. Also used in the definition
of the "ge" operator.
op:dayTimeDurationlessthan ( 
$arg1 
as xs:dayTimeDuration , 
$arg2 
as xs:dayTimeDuration ) as xs:boolean 
If the number of seconds in the value of $arg1
is
numerically less than the number of seconds in the value of
$arg2
, the function returns true.
Otherwise, the function returns false.
Either or both durations may be negative
Returns true if $arg1
is a longer duration than
$arg2
.
Defines the semantics of the "gt" operator on
xs:dayTimeDuration
values. Also used in the definition
of the "le" operator.
op:dayTimeDurationgreaterthan ( 
$arg1 
as xs:dayTimeDuration , 
$arg2 
as xs:dayTimeDuration ) as xs:boolean 
The function call op:dayTimeDurationgreaterthan($A,
$B)
is defined to return the same result as op:dayTimeDurationlessthan($B,
$A)
Returns true if $arg1
and $arg2
are
durations of the same length.
Defines the semantics of the "eq" operators on
xs:duration
values. Also used in the definition of the
"ne" operator.
op:durationequal
($arg1
as
xs:duration
,
$arg2
as
xs:duration
) as
xs:boolean
If the xs:yearMonthDuration
components of
$arg1
and $arg2
are equal and the
xs:dayTimeDuration
components of $arg1
and $arg2
are equal, the function returns
true
.
Otherwise, the function returns false.
The semantics of this function are:
xs:yearMonthDuration($arg1) div xs:yearMonthDuration('P1M') eq xs:yearMonthDuration($arg2) div xs:yearMonthDuration('P1M') and xs:dayTimeDuration($arg1) div xs:dayTimeDuration('PT1S') eq xs:dayTimeDuration($arg2) div xs:dayTimeDuration('PT1S')
that is, the function returns true
if the months
and seconds values of the two durations are equal.
Note that this function, like any other, may be applied to
arguments that are derived from the types given in the function
signature, including the two subtypes
xs:dayTimeDuration
and
xs:yearMonthDuration
. With the exception of the
zerolength duration, no instance of
xs:dayTimeDuration
can ever be equal to an instance of
xs:yearMonthDuration
.
The expression op:durationequal(xs:duration("P1Y"),
xs:duration("P12M"))
returns true()
.
The expression op:durationequal(xs:duration("PT24H"),
xs:duration("P1D"))
returns true()
.
The expression op:durationequal(xs:duration("P1Y"),
xs:duration("P365D"))
returns false()
.
The expression
op:durationequal(xs:yearMonthDuration("P0Y"),
xs:dayTimeDuration("P0D"))
returns true()
.
The expression
op:durationequal(xs:yearMonthDuration("P1Y"),
xs:dayTimeDuration("P365D"))
returns
false()
.
The expression
op:durationequal(xs:yearMonthDuration("P2Y"),
xs:yearMonthDuration("P24M"))
returns
true()
.
The expression
op:durationequal(xs:dayTimeDuration("P10D"),
xs:dayTimeDuration("PT240H"))
returns
true()
.
The expression
op:durationequal(xs:duration("P2Y0M0DT0H0M0S"),
xs:yearMonthDuration("P24M"))
returns
true()
.
The expression op:durationequal(xs:duration("P0Y0M10D"),
xs:dayTimeDuration("PT240H"))
returns
true()
.
The duration datatype may be considered to be a composite
datatypes in that it contains distinct properties or components.
The extraction functions specified below extract a single component
from a duration value. For xs:duration
and its
subtypes, including the two subtypes
xs:yearMonthDuration
and
xs:dayTimeDuration
, the components are normalized:
this means that the seconds and minutes components will always be
less than 60, the hours component less than 24, and the months
component less than 12.
Function  Meaning 

fn:yearsfromduration 
Returns the number of years in a duration. 
fn:monthsfromduration 
Returns the number of months in a duration. 
fn:daysfromduration 
Returns the number of days in a duration. 
fn:hoursfromduration 
Returns the number of hours in a duration. 
fn:minutesfromduration 
Returns the number of minutes in a duration. 
fn:secondsfromduration 
Returns the number of seconds in a duration. 
Returns the number of years in a duration.
fn:yearsfromduration
($arg
as
xs:duration?
) as
xs:integer?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:integer
representing the years component in the value of $arg
.
The result is obtained by casting $arg
to an
xs:yearMonthDuration
(see 18.1.4 Casting to duration
types) and then computing the years component as described
in 8.1.1.3 Canonical
representation.
If $arg
is a negative duration then the result will
be negative..
If $arg
is an xs:dayTimeDuration
the
function returns 0.
The expression
fn:yearsfromduration(xs:yearMonthDuration("P20Y15M"))
returns 21
.
The expression
fn:yearsfromduration(xs:yearMonthDuration("P15M"))
returns 1
.
The expression
fn:yearsfromduration(xs:dayTimeDuration("P2DT15H"))
returns 0
.
Returns the number of months in a duration.
fn:monthsfromduration
($arg
as
xs:duration?
) as
xs:integer?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:integer
representing the months component in the value of
$arg
. The result is obtained by casting
$arg
to an xs:yearMonthDuration
(see
18.1.4 Casting to duration
types) and then computing the months component as described
in 8.1.1.3 Canonical
representation.
If $arg
is a negative duration then the result will
be negative..
If $arg
is an xs:dayTimeDuration
the
function returns 0.
The expression
fn:monthsfromduration(xs:yearMonthDuration("P20Y15M"))
returns 3
.
The expression
fn:monthsfromduration(xs:yearMonthDuration("P20Y18M"))
returns 6
.
The expression
fn:monthsfromduration(xs:dayTimeDuration("P2DT15H0M0S"))
returns 0
.
Returns the number of days in a duration.
fn:daysfromduration
($arg
as
xs:duration?
) as
xs:integer?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:integer
representing the days component in the value of $arg
.
The result is obtained by casting $arg
to an
xs:dayTimeDuration
(see 18.1.4 Casting to duration
types) and then computing the days component as described
in 8.1.2.3 Canonical
representation.
If $arg
is a negative duration then the result will
be negative..
If $arg
is an xs:yearMonthDuration
the
function returns 0.
The expression
fn:daysfromduration(xs:dayTimeDuration("P3DT10H"))
returns 3
.
The expression
fn:daysfromduration(xs:dayTimeDuration("P3DT55H"))
returns 5
.
The expression
fn:daysfromduration(xs:yearMonthDuration("P3Y5M"))
returns 0
.
Returns the number of hours in a duration.
fn:hoursfromduration
($arg
as
xs:duration?
) as
xs:integer?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:integer
representing the hours component in the value of $arg
.
The result is obtained by casting $arg
to an
xs:dayTimeDuration
(see 18.1.4 Casting to duration
types) and then computing the hours component as described
in 8.1.2.3 Canonical
representation.
If $arg
is a negative duration then the result will
be negative..
If $arg
is an xs:yearMonthDuration
the
function returns 0.
The expression
fn:hoursfromduration(xs:dayTimeDuration("P3DT10H"))
returns 10
.
The expression
fn:hoursfromduration(xs:dayTimeDuration("P3DT12H32M12S"))
returns 12
.
The expression
fn:hoursfromduration(xs:dayTimeDuration("PT123H"))
returns 3
.
The expression
fn:hoursfromduration(xs:dayTimeDuration("P3DT10H"))
returns 10
.
Returns the number of minutes in a duration.
fn:minutesfromduration
($arg
as
xs:duration?
) as
xs:integer?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:integer
representing the minutes component in the value of
$arg
. The result is obtained by casting
$arg
to an xs:dayTimeDuration
(see
18.1.4 Casting to duration
types) and then computing the minutes component as
described in 8.1.2.3
Canonical representation.
If $arg
is a negative duration then the result will
be negative..
If $arg
is an xs:yearMonthDuration
the
function returns 0.
The expression
fn:minutesfromduration(xs:dayTimeDuration("P3DT10H"))
returns 0
.
The expression
fn:minutesfromduration(xs:dayTimeDuration("P5DT12H30M"))
returns 30
.
Returns the number of seconds in a duration.
fn:secondsfromduration
($arg
as
xs:duration?
) as
xs:decimal?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:decimal
representing the seconds component in the value of
$arg
. The result is obtained by casting
$arg
to an xs:dayTimeDuration
(see
18.1.4 Casting to duration
types) and then computing the seconds component as
described in 8.1.2.3
Canonical representation.
If $arg
is a negative duration then the result will
be negative..
If $arg
is an xs:yearMonthDuration
the
function returns 0.
The expression
fn:secondsfromduration(xs:dayTimeDuration("P3DT10H12.5S"))
returns 12.5
.
The expression
fn:secondsfromduration(xs:dayTimeDuration("PT256S"))
returns 16.0
.
Function  Meaning 

op:addyearMonthDurations 
Returns the result of adding two
xs:yearMonthDuration values. 
op:subtractyearMonthDurations 
Returns the result of subtracting one
xs:yearMonthDuration value from another. 
op:multiplyyearMonthDuration 
Returns the result of multiplying the value of
$arg1 by $arg2 . The result is rounded to
the nearest month. 
op:divideyearMonthDuration 
Returns the result of dividing the value of $arg1
by $arg2 . The result is rounded to the nearest
month. 
op:divideyearMonthDurationbyyearMonthDuration 
Returns the ratio of two xs:yearMonthDuration
values. 
op:adddayTimeDurations 
Returns the sum of two xs:dayTimeDuration
values. 
op:subtractdayTimeDurations 
Returns the result of subtracting one
xs:dayTimeDuration from another. 
op:multiplydayTimeDuration 
Returns the result of multiplying a
xs:dayTimeDuration by a number. 
op:dividedayTimeDuration 
Returns the result of multiplying a
xs:dayTimeDuration by a number. 
op:dividedayTimeDurationbydayTimeDuration 
Returns the ratio of two xs:dayTimeDuration
values, as a decimal number. 
For operators that combine a duration and a date/time value, see 9.7 Arithmetic operators on durations, dates and times.
Returns the result of adding two
xs:yearMonthDuration
values.
Defines the semantics of the "+" operator on
xs:yearMonthDuration
values.
op:addyearMonthDurations ( 
$arg1 
as xs:yearMonthDuration , 
$arg2 
as xs:yearMonthDuration ) as xs:yearMonthDuration 
The function returns the result of adding the value of
$arg1
to the value of $arg2
. The result
will be an xs:yearMonthDuration
whose length in months
is equal to the length in months of $arg1
plus the
length in months of $arg2
.
For handling of overflow, see 9.7.1 Limits and precision.
Either duration (and therefore the result) may be negative.
The expression
op:addyearMonthDurations(xs:yearMonthDuration("P2Y11M"),
xs:yearMonthDuration("P3Y3M"))
returns
xs:yearMonthDuration("P6Y2M")
.
Returns the result of subtracting one
xs:yearMonthDuration
value from another.
Defines the semantics of the "" operator on
xs:yearMonthDuration
values.
op:subtractyearMonthDurations ( 
$arg1 
as xs:yearMonthDuration , 
$arg2 
as xs:yearMonthDuration ) as xs:yearMonthDuration 
The function returns the result of subtracting the value of
$arg2
from the value of $arg1
. The result
will be an xs:yearMonthDuration
whose length in months
is equal to the length in months of $arg1
minus the
length in months of $arg2
.
For handling of overflow, see 9.7.1 Limits and precision.
Either duration (and therefore the result) may be negative.
The expression
op:subtractyearMonthDurations(xs:yearMonthDuration("P2Y11M"),
xs:yearMonthDuration("P3Y3M"))
returns
xs:yearMonthDuration("P4M")
.
Returns the result of multiplying the value of
$arg1
by $arg2
. The result is rounded to
the nearest month.
Defines the semantics of the "*" operator on
xs:yearMonthDuration
values.
op:multiplyyearMonthDuration ( 
$arg1 
as xs:yearMonthDuration , 
$arg2 
as xs:double ) as xs:yearMonthDuration 
The result is the xs:yearMonthDuration
whose length
in months is equal to the result of applying the fn:round
function to the value
obtained by multiplying the length in months of $arg1
by the value of $arg2
.
If $arg2
is positive or negative zero, the result
is a zerolength duration. If $arg2
is positive or
negative infinity, the result overflows and is handled as discussed
in 9.7.1 Limits and
precision.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
If $arg2
is NaN
an error is raised
[err:FOCA0005].
Either duration (and therefore the result) may be negative.
The expression
op:multiplyyearMonthDuration(xs:yearMonthDuration("P2Y11M"),
2.3)
returns xs:yearMonthDuration("P6Y9M")
.
Returns the result of dividing the value of $arg1
by $arg2
. The result is rounded to the nearest
month.
Defines the semantics of the "div" operator on
xs:yearMonthDuration
and numeric values.
op:divideyearMonthDuration ( 
$arg1 
as xs:yearMonthDuration , 
$arg2 
as xs:double ) as xs:yearMonthDuration 
The result is the xs:yearMonthDuration
whose length
in months is equal to the result of applying the fn:round
function to the value
obtained by dividing the length in months of $arg1
by
the value of $arg2
.
If $arg2
is positive or negative infinity, the
result is a zerolength duration. If $arg2
is positive
or negative zero, the result overflows and is handled as discussed
in 9.7.1 Limits and
precision.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
If $arg2
is NaN
an error is raised
[err:FOCA0005].
Either operand (and therefore the result) may be negative.
The expression
op:divideyearMonthDuration(xs:yearMonthDuration("P2Y11M"),
1.5)
returns
xs:yearMonthDuration("P1Y11M")
.
Returns the ratio of two xs:yearMonthDuration
values.
Defines the semantics of the "div" operator on
xs:yearMonthDuration
values.
op:divideyearMonthDurationbyyearMonthDuration ( 
$arg1 
as xs:yearMonthDuration , 
$arg2 
as xs:yearMonthDuration ) as xs:decimal 
The function returns the result of dividing the length in months
of $arg1
by the length in months of
$arg2
, according to the rules of the op:numericdivide
function
for integer operands.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
Either duration (and therefore the result) may be negative.
The expression
op:divideyearMonthDurationbyyearMonthDuration(xs:yearMonthDuration("P3Y4M"),
xs:yearMonthDuration("P1Y4M"))
returns
2.5
.
The following example demonstrates how to calculate the length
of an xs:yearMonthDuration
value in months:
The expression
op:divideyearMonthDurationbyyearMonthDuration(xs:yearMonthDuration("P3Y4M"),
xs:yearMonthDuration("P1M"))
returns 40
.
Returns the sum of two xs:dayTimeDuration
values.
Defines the semantics of the "+" operator on
xs:dayTimeDuration
values.
op:adddayTimeDurations ( 
$arg1 
as xs:dayTimeDuration , 
$arg2 
as xs:dayTimeDuration ) as xs:dayTimeDuration 
The function returns the result of adding the value of
$arg1
to the value of $arg2
. The result
is the xs:dayTimeDuration
whose length in seconds is
equal to the sum of the length in seconds of the two input
durations.
For handling of overflow, see 9.7.1 Limits and precision.
Either duration (and therefore the result) may be negative.
The expression
op:adddayTimeDurations(xs:dayTimeDuration("P2DT12H5M"),
xs:dayTimeDuration("P5DT12H"))
returns
xs:dayTimeDuration('P8DT5M')
.
Returns the result of subtracting one
xs:dayTimeDuration
from another.
Defines the semantics of the "" operator on
xs:dayTimeDuration
values.
op:subtractdayTimeDurations ( 
$arg1 
as xs:dayTimeDuration , 
$arg2 
as xs:dayTimeDuration ) as xs:dayTimeDuration 
The function returns the result of subtracting the value of
$arg2
from the value of $arg1
. The result
is the xs:dayTimeDuration
whose length in seconds is
equal to the length in seconds of $arg1
minus the
length in seconds of $arg2
.
For handling of overflow, see 9.7.1 Limits and precision.
Either duration (and therefore the result) may be negative.
The expression
op:subtractdayTimeDurations(xs:dayTimeDuration("P2DT12H"),
xs:dayTimeDuration("P1DT10H30M"))
returns
xs:dayTimeDuration('P1DT1H30M')
.
Returns the result of multiplying a
xs:dayTimeDuration
by a number.
Defines the semantics of the "*" operator on
xs:dayTimeDuration
and numeric values.
op:multiplydayTimeDuration ( 
$arg1 
as xs:dayTimeDuration , 
$arg2 
as xs:double ) as xs:dayTimeDuration 
The function returns the result of multiplying the value of
$arg1
by $arg2
. The result is the
xs:dayTimeDuration
whose length in seconds is equal to
the length in seconds of $arg1
multiplied by the
numeric value $arg2
.
Editorial note  
We ought to say whether the calculation is performed using double or decimal arithmetic. 
If $arg2
is positive or negative zero, the result
is a zerolength duration. If $arg2
is positive or
negative infinity, the result overflows and is handled as discussed
in 9.1.1 Limits and
precision.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
If $arg2
is NaN
an error is raised
[err:FOCA0005].
Either operand (and therefore the result) may be negative.
The expression
op:multiplydayTimeDuration(xs:dayTimeDuration("PT2H10M"),
2.1)
returns xs:dayTimeDuration('PT4H33M')
.
Returns the result of multiplying a
xs:dayTimeDuration
by a number.
Defines the semantics of the "div" operator on
xs:dayTimeDuration
values.
op:dividedayTimeDuration ( 
$arg1 
as xs:dayTimeDuration , 
$arg2 
as xs:double ) as xs:dayTimeDuration 
The function returns the result of dividing the value of
$arg1
by $arg2
. The result is the
xs:dayTimeDuration
whose length in seconds is equal to
the length in seconds of $arg1
divided by the numeric
value $arg2
.
If $arg2
is positive or negative infinity, the
result is a zerolength duration. If $arg2
is positive
or negative zero, the result overflows and is handled as discussed
in 9.1.1 Limits and
precision.
Editorial note  
We ought to say whether the calculation is performed using double or decimal arithmetic. 
For handling of overflow and underflow, see 9.7.1 Limits and precision.
If $arg2
is NaN
an error is raised
[err:FOCA0005]
Either operand (and therefore the result) may be negative.
The expression
op:dividedayTimeDuration(xs:dayTimeDuration("P1DT2H30M10.5S"),
1.5)
returns xs:duration("PT17H40M7S")
.
Returns the ratio of two xs:dayTimeDuration
values,
as a decimal number.
Defines the semantics of the "div" operator on
xs:dayTimeDuration
values.
op:dividedayTimeDurationbydayTimeDuration ( 
$arg1 
as xs:dayTimeDuration , 
$arg2 
as xs:dayTimeDuration ) as xs:decimal 
The function returns the result of dividing the value of
$arg1
by $arg2
. The result is the
xs:dayTimeDuration
whose length in seconds is equal to
the length in seconds of $arg1
divided by the length
in seconds of $arg2
. The calculation is performed by
applying op:numericdivide
to the
two xs:decimal
operands.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
Either operand (and therefore the result) may be negative.
The expression fn:roundhalftoeven(
op:dividedayTimeDurationbydayTimeDuration(
xs:dayTimeDuration("P2DT53M11S"), xs:dayTimeDuration("P1DT10H")),
4)
returns 1.4378
.
This examples shows how to determine the number of seconds in a duration.
The expression
op:dividedayTimeDurationbydayTimeDuration(xs:dayTimeDuration("P2DT53M11S"),
xs:dayTimeDuration("PT1S"))
returns
175991.0
.
This section defines operations on the [XML Schema Part 2: Datatypes Second Edition] date and time types.
See [Working With Timezones] for a disquisition on working with date and time values with and without timezones.
The operators described in this section are defined on the following date and time types:
xs:dateTime
xs:date
xs:time
xs:gYearMonth
xs:gYear
xs:gMonthDay
xs:gMonth
xs:gDay
The only operations defined on xs:gYearMonth
,
xs:gYear
, xs:gMonthDay
,
xs:gMonth
and xs:gDay
values are equality
comparison and component extraction. For other types, further
operations are provided, including order comparisons, arithmetic,
formatted display, and timezone adjustment.
For a number of the above datatypes [XML Schema Part 2: Datatypes Second Edition] extends the basic [ISO 8601] lexical representations, such as YYYYMMDDThh:mm:ss.s for dateTime, by allowing a preceding minus sign, more than four digits to represent the year field — no maximum is specified — and an unlimited number of digits for fractional seconds. Leap seconds are not supported.
All minimally conforming processors ·must· support positive year values with a minimum of 4 digits (i.e., YYYY) and a minimum fractional second precision of 1 millisecond or three digits (i.e., s.sss). However, conforming processors ·may· set larger ·implementationdefined· limits on the maximum number of digits they support in these two situations. Processors ·may· also choose to support the year 0000 and years with negative values. The results of operations on dates that cross the year 0000 are ·implementationdefined·.
A processor that limits the number of digits in date and time datatype representations may encounter overflow and underflow conditions when it tries to execute the functions in 9.7 Arithmetic operators on durations, dates and times. In these situations, the processor ·must· return 00:00:00 in case of time underflow. It ·must· raise an error [err:FODT0001] in case of overflow.
As defined in Section
Dates and Times^{DM30},
xs:dateTime
, xs:date
,
xs:time
, xs:gYearMonth
,
xs:gYear
, xs:gMonthDay
,
xs:gMonth
, xs:gDay
values, referred to
collectively as date/time values, are represented as seven
components or properties: year
, month
,
day
, hour
, minute
,
second
and timezone
. The value of the
first five components are xs:integer
s. The value of
the second
component is an xs:decimal
and
the value of the timezone
component is an
xs:dayTimeDuration
. For all the primitive date/time
datatypes, the timezone
property is optional and may
or may not be present. Depending on the datatype, some of the
remaining six properties must be present and some must be absent.
Absent, or missing, properties are represented by the empty
sequence. This value is referred to as the local value in
that the value retains its original timezone. Before comparing or
subtracting xs:dateTime
values, this local value
·must· be translated
or normalized to UTC.
For xs:time
, 00:00:00
and
24:00:00
are alternate lexical forms for the same
value, whose canonical representation is 00:00:00
. For
xs:dateTime
, a time component 24:00:00
translates to 00:00:00"
of the following day.
An xs:dateTime
with lexical representation
19990531T05:00:00
is represented in the datamodel by
{1999, 5, 31, 5, 0, 0.0, ()}
.
An xs:dateTime
with lexical representation
19990531T13:20:0005:00
is represented by
{1999, 5, 31, 13, 20, 0.0, PT5H}
.
An xs:dateTime
with lexical representation
19991231T24:00:00
is represented by {2000, 1,
1, 0, 0, 0.0, ()}
.
An xs:date
with lexical representation
20050228+8:00
is represented by {2005, 2, 28,
(), (), (), PT8H}
.
An xs:time
with lexical representation
24:00:00
is represented by {(), (), (), 0, 0, 0,
()}
.
A function is provided for constructing a
xs:dateTime
value from a xs:date
value
and a xs:time
value.
Returns an xs:dateTime
value created by combining
an xs:date
and an xs:time
.
fn:dateTime
($arg1
as
xs:date?
,
$arg2
as
xs:time?
) as
xs:dateTime?
If either $arg1
or $arg2
is the empty
sequence the function returns the empty sequence.
Otherwise, the function returns an xs:dateTime
whose date component is equal to $arg1
and whose time
component is equal to $arg2
.
The timezone of the result is computed as follows:
If neither argument has a timezone, the result has no timezone.
If exactly one of the arguments has a timezone, or if both arguments have the same timezone, the result has this timezone.
If the two arguments both have timezones and the timezones are different, an error is raised: [err:FORG0008]
The expression fn:dateTime(xs:date("19991231"),
xs:time("12:00:00"))
returns
xs:dateTime("19991231T12:00:00")
.
The expression fn:dateTime(xs:date("19991231"),
xs:time("24:00:00"))
returns
xs:dateTime("19991231T00:00:00")
. (This is
because "24:00:00"
is an alternate lexical form for
"00:00:00"
).
Function  Meaning 

op:dateTimeequal 
Returns true if the two supplied xs:dateTime
values refer to the same instant in time. 
op:dateTimelessthan 
Returns true if the first argument represents an
earlier instant in time than the second argument. 
op:dateTimegreaterthan 
Returns true if the first argument represents a
later instant in time than the second argument. 
op:dateequal 
Returns true if and only if the starting instants
of the two supplied xs:date values are the same. 
op:datelessthan 
Returns true if and only if the starting instant
of $arg1 is less than the starting instant of
$arg2 . Returns false otherwise. 
op:dategreaterthan 
Returns true if and only if the starting instant
of $arg1 is greater than the starting instant of
$arg2 . Returns false otherwise. 
op:timeequal 
Returns true if the two xs:time
values represent the same instant in time, when treated as being
times on the same date, before adjusting the timezone. 
op:timelessthan 
Returns true if the first xs:time
value represents an earlier instant in time than the second, when
both are treated as being times on the same date, before adjusting
the timezone. 
op:timegreaterthan 
Returns true if the first xs:time
value represents a later instant in time than the second, when both
are treated as being times on the same date, before adjusting the
timezone. 
op:gYearMonthequal 
Returns true if the two xs:gYearMonth values have
the same starting instant. 
op:gYearequal 
Returns true if the two xs:gYear values have the
same starting instant. 
op:gMonthDayequal 
Returns true if the two xs:gMonthDay values have
the same starting instant, when considered as days in the same
year. 
op:gMonthequal 
Returns true if the two xs:gMonth values have the
same starting instant, when considered as months in the same
year. 
op:gDayequal 
Returns true if the two xs:gDay values have the
same starting instant, when considered as days in the same month of
the same year. 
The following comparison operators are defined on the [XML Schema Part 2: Datatypes Second Edition]
date/time datatypes. Each operator takes two operands of the same
type and returns an xs:boolean
result.
[XML Schema Part 2: Datatypes Second Edition] also states that the order relation on date and time datatypes is not a total order but a partial order because these datatypes may or may not have a timezone. This is handled as follows. If either operand to a comparison function on date or time values does not have an (explicit) timezone then, for the purpose of the operation, an implicit timezone, provided by the dynamic context Section C.2 Dynamic Context Components^{XP}, is assumed to be present as part of the value. This creates a total order for all date and time values.
Editorial note  
The following paragraph seems to duplicate material that has already been covered. 
An xs:dateTime
can be considered to consist of
seven components: year
, month
,
day
, hour
, minute
,
second
and timezone
. For
xs:dateTime
six components: year
,
month
, day
, hour
,
minute
and second
are required and
timezone
is optional. For other date/time values, of
the first six components, some are required and others must be
absent or missing. Timezone
is always optional. For
example, for xs:date
, the year
,
month
and day
components are required and
hour
, minute
and second
components must be absent; for xs:time
the
hour
, minute
and second
components are required and year
, month
and day
are missing; for xs:gDay
,
day
is required and year
,
month
, hour
, minute
and
second
are missing.
Values of the date/time datatypes xs:time
,
xs:gMonthDay
, xs:gMonth
, and
xs:gDay
, can be considered to represent a sequence of
recurring time instants or time periods. An xs:time
occurs every day. An xs:gMonth
occurs every year.
Comparison operators on these datatypes compare the starting
instants of equivalent occurrences in the recurring series. These
xs:dateTime
values are calculated as described
below.
Comparison operators on xs:date
,
xs:gYearMonth
and xs:gYear
compare their
starting instants. These xs:dateTime
values are
calculated as described below.
The starting instant of an occurrence of a date/time value is an
xs:dateTime
calculated by filling in the missing
components of the local value from a reference
xs:dateTime
. An example of a suitable reference
xs:dateTime
is 19720101T00:00:00
. Then,
for example, the starting instant corresponding to the
xs:date
value 20090312
is
20090312T00:00:00
; the starting instant
corresponding to the xs:time
value
13:30:02
is 19720101T13:30:02
; and the
starting instant corresponding to the gMonthDay
value
0229
is 19720229T00:00:00
(which
explains why a leap year was chosen for the reference).
Note:
In the previous version of this specification, the reference
date/time chosen was 19721231T00:00:00
. While this
gives the same results, it produces a "starting instant" for a
gMonth
or gMonthDay
that bears no
relation to the English meaning of the term, and it also required
special handling of short months. The original choice was made to
allow for leap seconds; but since leap seconds are not recognized
in date/time arithmetic, this is not actually necessary.
If the xs:time
value written as
24:00:00
is to be compared, filling in the missing
components gives 19720101T00:00:00
, because
24:00:00
is an alternative representation of
00:00:00
(the lexical value "24:00:00"
is
converted to the time components {0,0,0} before the missing
components are filled in). This has the consequence that when
ordering xs:time
values, 24:00:00
is
considered to be earlier than 23:59:59
. However, when
ordering xs:dateTime
values, a time component of
24:00:00
is considered equivalent to
00:00:00
on the following day.
Note that the reference xs:dateTime
does not have a
timezone. The timezone
component is never filled in
from the reference xs:dateTime
. In some cases, if the
date/time value does not have a timezone, the implicit timezone
from the dynamic context is used as the timezone.
Note:
This specification uses the reference xs:dateTime
19720101T00:00:00
in the description of the comparison
operators. Implementations may use other reference
xs:dateTime
values as long as they yield the same
results. The reference xs:dateTime
used must meet the
following constraints: when it is used to supply components into
xs:gMonthDay
values, the year must allow for February
29 and so must be a leap year; when it is used to supply missing
components into xs:gDay
values, the month must allow
for 31 days. Different reference xs:dateTime
values
may be used for different operators.
Returns true if the two supplied xs:dateTime
values
refer to the same instant in time.
Defines the semantics of the "eq" operator on
xs:dateTime
values. Also used in the definition of the
"ne", "le" and "ge" operators.
op:dateTimeequal
($arg1
as
xs:dateTime
,
$arg2
as
xs:dateTime
) as
xs:boolean
If either $arg1
or $arg2
has no
timezone component, the effective value of the argument is obtained
by substituting the implicit timezone from the dynamic evaluation
context.
The function then returns true
if and only if the
effective value of $arg1
is equal to the effective
value of $arg2
according to the algorithm defined in
section 3.2.7.4 of [XML Schema Part 2:
Datatypes Second Edition] "Order relation on dateTime" for
xs:dateTime
values with timezones. Otherwise the
function returns false
.
Assume that the dynamic context provides an implicit timezone
value of 05:00
The expression
op:dateTimeequal(xs:dateTime("20020402T12:00:0001:00"),
xs:dateTime("20020402T17:00:00+04:00"))
returns
true()
.
The expression
op:dateTimeequal(xs:dateTime("20020402T12:00:00"),
xs:dateTime("20020402T23:00:00+06:00"))
returns
true()
.
The expression
op:dateTimeequal(xs:dateTime("20020402T12:00:00"),
xs:dateTime("20020402T17:00:00"))
returns
false()
.
The expression
op:dateTimeequal(xs:dateTime("20020402T12:00:00"),
xs:dateTime("20020402T12:00:00"))
returns
true()
.
The expression
op:dateTimeequal(xs:dateTime("20020402T23:00:0004:00"),
xs:dateTime("20020403T02:00:0001:00"))
returns
true()
.
The expression
op:dateTimeequal(xs:dateTime("19991231T24:00:00"),
xs:dateTime("20000101T00:00:00"))
returns
true()
.
The expression
op:dateTimeequal(xs:dateTime("20050404T24:00:00"),
xs:dateTime("20050404T00:00:00"))
returns
false()
.
Returns true
if the first argument represents an
earlier instant in time than the second argument.
Defines the semantics of the "lt" operator on
xs:dateTime
values. Also used in the definition of the
"le" operator.
op:dateTimelessthan
($arg1
as
xs:dateTime
,
$arg2
as
xs:dateTime
) as
xs:boolean
If either $arg1
or $arg2
has no
timezone component, the effective value of the argument is obtained
by substituting the implicit timezone from the dynamic evaluation
context.
The function then returns true
if and only if the
effective value of $arg1
is less than the effective
value of $arg2
according to the algorithm defined in
section 3.2.7.4 of [XML Schema Part 2:
Datatypes Second Edition] "Order relation on dateTime" for
xs:dateTime
values with timezones. Otherwise the
function returns false
.
Returns true
if the first argument represents a
later instant in time than the second argument.
Defines the semantics of the "gt" operator on
xs:dateTime
values. Also used in the definition of the
"ge" operator.
op:dateTimegreaterthan ( 
$arg1 
as xs:dateTime , 
$arg2 
as xs:dateTime ) as xs:boolean 
The function call op:dateTimegreaterthan($A, $B)
is defined to return the same result as op:dateTimelessthan($B,
$A)
Returns true
if and only if the starting instants
of the two supplied xs:date
values are the same.
Defines the semantics of the "eq" operator on
xs:date
values. Also used in the definition of the
"ne", "le" and "ge" operators.
op:dateequal
($arg1
as
xs:date
,
$arg2
as
xs:date
) as
xs:boolean
The starting instant of an xs:date
is the
xs:dateTime
at time 00:00:00
on that
date.
The function returns the result of the expression:
op:dateTimeequal(xs:dateTime($arg1), xs:dateTime($arg2))
The expression op:dateequal(xs:date("20041225Z"),
xs:date("20041225+07:00"))
returns false()
.
(The starting instants are
xs:dateTime("20041225T00:00:00Z")
and
xs:dateTime("20041225T00:00:00+07:00")
. These are
normalized to xs:dateTime("20041225T00:00:00Z")
and
xs:dateTime("20041224T17:00:00Z")
. ).
The expression op:dateequal(xs:date("2004122512:00"),
xs:date("20041226+12:00"))
returns
true()
.
Returns true
if and only if the starting instant of
$arg1
is less than the starting instant of
$arg2
. Returns false
otherwise.
Defines the semantics of the "lt" operator on
xs:date
values. Also used in the definition of the
"le" operator.
op:datelessthan
($arg1
as
xs:date
,
$arg2
as
xs:date
) as
xs:boolean
The starting instant of an xs:date
is the
xs:dateTime
at time 00:00:00
on that
date.
The function returns the result of the expression:
op:dateTimelessthan(xs:dateTime($arg1), xs:dateTime($arg2))
The expression op:datelessthan(xs:date("20041225Z"),
xs:date("2004122505:00"))
returns
true()
.
The expression
op:datelessthan(xs:date("2004122512:00"),
xs:date("20041226+12:00"))
returns
false()
.
Returns true
if and only if the starting instant of
$arg1
is greater than the starting instant of
$arg2
. Returns false
otherwise.
Defines the semantics of the "gt" operator on
xs:date
values. Also used in the definition of the
"ge" operator.
op:dategreaterthan
($arg1
as
xs:date
,
$arg2
as
xs:date
) as
xs:boolean
The function call op:dategreaterthan($A, $B)
is
defined to return the same result as op:datelessthan($B,
$A)
The expression
op:dategreaterthan(xs:date("20041225Z"),
xs:date("20041225+07:00"))
returns
true()
.
The expression
op:dategreaterthan(xs:date("2004122512:00"),
xs:date("20041226+12:00"))
returns
false()
.
Returns true
if the two xs:time
values
represent the same instant in time, when treated as being times on
the same date, before adjusting the timezone.
Defines the semantics of the "eq" operator on
xs:time
values. Also used in the definition of the
"ne", "le" and "ge" operators.
op:timeequal
($arg1
as
xs:time
,
$arg2
as
xs:time
) as
xs:boolean
Each of the supplied xs:time
values is expanded to
an xs:dateTime
value by associating the time with an
arbitrary date. The function returns the result of comparing these
two xs:dateTime
values using op:dateTimeequal
.
The result of the function is thus the same as the value of the expression:
op:dateTimeequal( fn:dateTime(xs:date('19721231'), $arg1), fn:dateTime(xs:date('19721231'), $arg2))
Assume that the date components from the reference
xs:dateTime
correspond to 19721231
.
The expression op:timeequal(xs:time("08:00:00+09:00"),
xs:time("17:00:0006:00"))
returns false()
.
(The xs:dateTime
s calculated using the reference
date components are 19721231T08:00:00+09:00
and
19721231T17:00:0006:00
. These normalize to
19721230T23:00:00Z
and
19721231T23:00:00
. ).
The expression op:timeequal(xs:time("21:30:00+10:30"),
xs:time("06:00:0005:00"))
returns true()
.
The expression op:timeequal(xs:time("24:00:00+01:00"),
xs:time("00:00:00+01:00"))
returns true()
.
(This not the result one might expect. For
xs:dateTime
values, a time of 24:00:00
is
equivalent to 00:00:00
on the following day. For
xs:time
, the normalization from 24:00:00
to 00:00:00
happens before the xs:time
is
converted into an xs:dateTime
for the purpose of the
equality comparison. For xs:time
, any operation on
24:00:00
produces the same result as the same
operation on 00:00:00
because these are two different
lexical representations of the same value. ).
Returns true
if the first xs:time
value represents an earlier instant in time than the second, when
both are treated as being times on the same date, before adjusting
the timezone.
Defines the semantics of the "lt" operator on
xs:time
values. Also used in the definition of the
"le" operator.
op:timelessthan
($arg1
as
xs:time
,
$arg2
as
xs:time
) as
xs:boolean
Each of the supplied xs:time
values is expanded to
an xs:dateTime
value by associating the time with an
arbitrary date. The function returns the result of comparing these
two xs:dateTime
values using op:dateTimelessthan
.
The result of the function is thus the same as the value of the expression:
op:dateTimelessthan( fn:dateTime(xs:date('19721231'), $arg1), fn:dateTime(xs:date('19721231'), $arg2))
Assume that the dynamic context provides an implicit timezone
value of 05:00
.
The expression op:timelessthan(xs:time("12:00:00"),
xs:time("23:00:00+06:00"))
returns false()
.
The expression op:timelessthan(xs:time("11:00:00"),
xs:time("17:00:00Z"))
returns true()
.
The expression op:timelessthan(xs:time("23:59:59"),
xs:time("24:00:00"))
returns false()
.
Returns true
if the first xs:time
value represents a later instant in time than the second, when both
are treated as being times on the same date, before adjusting the
timezone.
Defines the semantics of the "gt" operator on
xs:time
values. Also used in the definition of the
"ge" operator.
op:timegreaterthan
($arg1
as
xs:time
,
$arg2
as
xs:time
) as
xs:boolean
The function call op:timegreaterthan($A, $B)
is
defined to return the same result as op:timelessthan($B,
$A)
The expression
op:timegreaterthan(xs:time("08:00:00+09:00"),
xs:time("17:00:0006:00"))
returns false()
.
Returns true if the two xs:gYearMonth
values have
the same starting instant.
Defines the semantics of the "eq" operator on
xs:gYearMonth
values. Also used in the definition of
the "ne" operator.
op:gYearMonthequal ( 
$arg1 
as xs:gYearMonth , 
$arg2 
as xs:gYearMonth ) as xs:boolean 
The starting instants of $arg1
and
$arg2
are calculated by supplying the missing
components of $arg1
and $arg2
from the
xs:dateTime
template xxxxxx01T00:00:00
.
The function returns the result of comparing these two starting
instants using op:dateTimeequal
.
Assume that the dynamic context provides an implicit timezone
value of 05:00
.
op:gYearMonthequal(xs:gYearMonth("198602"),
xs:gYearMonth("198603"))
returns false()
. The
starting instants are 19860201T00:00:0005:00
and
19860301T00:00:00
, respectively.
op:gYearMonthequal(xs:gYearMonth("197803"),
xs:gYearMonth("198603Z"))
returns false()
. The
starting instants are 19860301T00:00:0005:00
and
19860301T00:00:00Z
, respectively.
Returns true if the two xs:gYear
values have the
same starting instant.
Defines the semantics of the "eq" operator on
xs:gYear
values. Also used in the definition of the
"ne" operator.
op:gYearequal
($arg1
as
xs:gYear
,
$arg2
as
xs:gYear
) as
xs:boolean
The starting instants of $arg1
and
$arg2
are calculated by supplying the missing
components of $arg1
and $arg2
from the
xs:dateTime
template xxxx0101T00:00:00
.
The function returns the result of comparing these two starting
instants using op:dateTimeequal
.
Assume that the dynamic context provides an implicit timezone
value of 05:00
. Assume, also, that the
xs:dateTime
template is
xxxx0101T00:00:00
.
op:gYearequal(xs:gYear("200512:00"),
xs:gYear("2005+12:00"))
returns false()
. The
starting instants are 20050101T00:00:0012:00
and
20050101T00:00:00+12:00
, respectively, and normalize
to 20050101T12:00:00Z
and
20041231T12:00:00Z
.
The expression op:gYearequal(xs:gYear("197605:00"),
xs:gYear("1976"))
returns true()
.
Returns true if the two xs:gMonthDay
values have
the same starting instant, when considered as days in the same
year.
Defines the semantics of the "eq" operator on
xs:gMonthDay
values. Also used in the definition of
the "ne" operator.
op:gMonthDayequal
($arg1
as
xs:gMonthDay
,
$arg2
as
xs:gMonthDay
) as
xs:boolean
The starting instants of $arg1
and
$arg2
are calculated by supplying the missing
components of $arg1
and $arg2
from the
xs:dateTime
template 1972xxxxT00:00:00
or an equivalent. The function returns the result of comparing
these two starting instants using op:dateTimeequal
.
Assume that the dynamic context provides an implicit timezone
value of 05:00
. Assume for the purposes of
illustration that the xs:dateTime
template used is
1972xxxxT00:00:00
(this does not affect the
result).
The expression
op:gMonthDayequal(xs:gMonthDay("122514:00"),
xs:gMonthDay("1226+10:00"))
returns true()
.
( The starting instants are
19721225T00:00:0014:00
and
19721226T00:00:00+10:00
, respectively, and normalize
to 19721225T14:00:00Z
and
19721225T14:00:00Z
. ).
The expression op:gMonthDayequal(xs:gMonthDay("1225"),
xs:gMonthDay("1226Z"))
returns false()
.
Returns true if the two xs:gMonth
values have the
same starting instant, when considered as months in the same
year.
Defines the semantics of the "eq" operator on
xs:gMonth
values. Also used in the definition of the
"ne" operator.
op:gMonthequal
($arg1
as
xs:gMonth
,
$arg2
as
xs:gMonth
) as
xs:boolean
The starting instants of $arg1
and
$arg2
are calculated by supplying the missing
components of $arg1
and $arg2
from the
xs:dateTime
template 1972xx01T00:00:00
or an equivalent. The function returns the result of comparing
these two starting instants using op:dateTimeequal
.
Assume that the dynamic context provides an implicit timezone
value of 05:00
. Assume, also, that the
xs:dateTime
template chosen is
1972xx01T00:00:00
.
The expression op:gMonthequal(xs:gMonth("1214:00"),
xs:gMonth("12+10:00"))
returns false()
. (
The starting instants are 19721201T00:00:0014:00
and 19721201T00:00:00+10:00
, respectively, and
normalize to 19721130T14:00:00Z
and
19721201T14:00:00Z
. ).
The expression op:gMonthequal(xs:gMonth("12"),
xs:gMonth("12Z"))
returns false()
.
Returns true if the two xs:gDay
values have the
same starting instant, when considered as days in the same month of
the same year.
Defines the semantics of the "eq" operator on
xs:gDay
values. Also used in the definition of the
"ne" operator.
op:gDayequal
($arg1
as
xs:gDay
,
$arg2
as
xs:gDay
) as
xs:boolean
The starting instants of $arg1
and
$arg2
are calculated by supplying the missing
components of $arg1
and $arg2
from the
xs:dateTime
template 197212xxT00:00:00
or an equivalent. The function returns the result of comparing
these two starting instants using op:dateTimeequal
.
Assume that the dynamic context provides an implicit timezone
value of 05:00
. Assume, also, that the
xs:dateTime
template is
197212xxT00:00:00
.
The expression op:gDayequal(xs:gDay("2514:00"),
xs:gDay("25+10:00"))
returns false()
. (
The starting instants are 19721225T00:00:0014:00
and 19721225T00:00:00+10:00
, respectively, and
normalize to 19721225T14:00:00Z
and
19721224T14:00:00Z
. ).
The expression op:gDayequal(xs:gDay("12"),
xs:gDay("12Z"))
returns false()
.
The date and time datatypes may be considered to be composite datatypes in that they contain distinct properties or components. The extraction functions specified below extract a single component from a date or time value. In all cases the local value (that is, the original value as written, without any timezone adjustment) is used.
Note:
A time written as 24:00:00
is treated as
00:00:00
on the following day.
Function  Meaning 

fn:yearfromdateTime 
Returns the year component of an xs:dateTime . 
fn:monthfromdateTime 
Returns the month component of an
xs:dateTime . 
fn:dayfromdateTime 
Returns the day component of an xs:dateTime . 
fn:hoursfromdateTime 
Returns the hours component of an
xs:dateTime . 
fn:minutesfromdateTime 
Returns the minute component of an
xs:dateTime . 
fn:secondsfromdateTime 
Returns the seconds component of an
xs:dateTime . 
fn:timezonefromdateTime 
Returns the timezone component of an
xs:dateTime . 
fn:yearfromdate 
Returns the year component of an xs:date . 
fn:monthfromdate 
Returns the month component of an xs:date . 
fn:dayfromdate 
Returns the day component of an xs:date . 
fn:timezonefromdate 
Returns the timezone component of an xs:date . 
fn:hoursfromtime 
Returns the hours component of an xs:time . 
fn:minutesfromtime 
Returns the minutes component of an xs:time . 
fn:secondsfromtime 
Returns the seconds component of an xs:time . 
fn:timezonefromtime 
Returns the timezone component of an xs:time . 
Returns the year component of an xs:dateTime
.
op:yearfromdateTime
($arg
as
xs:dateTime?
) as
xs:integer?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:integer
representing the year component in the local value of
$arg
. The result may be negative.
The expression
fn:yearfromdateTime(xs:dateTime("19990531T13:20:0005:00"))
returns 1999
.
The expression
fn:yearfromdateTime(xs:dateTime("19990531T21:30:0005:00"))
returns 1999
.
The expression
fn:yearfromdateTime(xs:dateTime("19991231T19:20:00"))
returns 1999
.
The expression
fn:yearfromdateTime(xs:dateTime("19991231T24:00:00"))
returns 2000
.
Returns the month component of an xs:dateTime
.
op:monthfromdateTime
($arg
as
xs:dateTime?
) as
xs:integer?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:integer
between 1 and 12, both inclusive, representing the month component
in the local value of $arg
.
The expression
fn:monthfromdateTime(xs:dateTime("19990531T13:20:0005:00"))
returns 5
.
The expression
fn:monthfromdateTime(xs:dateTime("19991231T19:20:0005:00"))
returns 12
.
The expression
fn:monthfromdateTime(fn:adjustdateTimetotimezone(xs:dateTime("19991231T19:20:0005:00"),
xs:dayTimeDuration("PT0S")))
returns 1
.
Returns the day component of an xs:dateTime
.
op:dayfromdateTime
($arg
as
xs:dateTime?
) as
xs:integer?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:integer
between 1 and 31, both inclusive, representing the day component in
the local value of $arg
.
The expression
fn:dayfromdateTime(xs:dateTime("19990531T13:20:0005:00"))
returns 31
.
The expression
fn:dayfromdateTime(xs:dateTime("19991231T20:00:0005:00"))
returns 31
.
The expression
fn:dayfromdateTime(fn:adjustdateTimetotimezone(xs:dateTime("19991231T19:20:0005:00"),
xs:dayTimeDuration("PT0S")))
returns 1
.
Returns the hours component of an xs:dateTime
.
op:hoursfromdateTime
($arg
as
xs:dateTime?
) as
xs:integer?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:integer
between 0 and 23, both inclusive, representing the hours component
in the local value of $arg
.
The expression
fn:hoursfromdateTime(xs:dateTime("19990531T08:20:0005:00"))
returns 8
.
The expression
fn:hoursfromdateTime(xs:dateTime("19991231T21:20:0005:00"))
returns 21
.
The expression
fn:hoursfromdateTime(fn:adjustdateTimetotimezone(xs:dateTime("19991231T21:20:0005:00"),
xs:dayTimeDuration("PT0S")))
returns 2
.
The expression
fn:hoursfromdateTime(xs:dateTime("19991231T12:00:00"))
returns 12
.
The expression
fn:hoursfromdateTime(xs:dateTime("19991231T24:00:00"))
returns 0
.
Returns the minute component of an xs:dateTime
.
fn:minutesfromdateTime
($arg
as
xs:dateTime?
) as
xs:integer?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:integer
value
between 0 and 59, both inclusive, representing the minute component
in the local value of $arg
.
The expression
fn:minutesfromdateTime(xs:dateTime("19990531T13:20:0005:00"))
returns 20
.
The expression
fn:minutesfromdateTime(xs:dateTime("19990531T13:30:00+05:30"))
returns 30
.
Returns the seconds component of an
xs:dateTime
.
fn:secondsfromdateTime
($arg
as
xs:dateTime?
) as
xs:decimal?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:decimal
value
greater than or equal to zero and less than 60, representing the
seconds and fractional seconds in the local value of
$arg
.
The expression
fn:secondsfromdateTime(xs:dateTime("19990531T13:20:0005:00"))
returns 0
.
Returns the timezone component of an
xs:dateTime
.
fn:timezonefromdateTime
($arg
as
xs:dateTime?
) as
xs:dayTimeDuration?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns the timezone component of
$arg
, if any. If $arg
has a timezone
component, then the result is an xs:dayTimeDuration
that indicates deviation from UTC; its value may range from +14:00
to 14:00 hours, both inclusive. If $arg
has no
timezone component, the result is the empty sequence.
The expression
fn:timezonefromdateTime(xs:dateTime("19990531T13:20:0005:00"))
returns xs:dayTimeDuration("PT5H")
.
The expression
fn:timezonefromdateTime(xs:dateTime("20000612T13:20:00Z"))
returns xs:dayTimeDuration("PT0S")
.
The expression
fn:timezonefromdateTime(xs:dateTime("20040827T00:00:00"))
returns ()
.
Returns the year component of an xs:date
.
fn:yearfromdate
($arg
as
xs:date?
) as
xs:integer?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:integer
representing the year in the local value of $arg
. The
value may be negative.
The expression
fn:yearfromdate(xs:date("19990531"))
returns
1999
.
The expression
fn:yearfromdate(xs:date("20000101+05:00"))
returns
2000
.
Returns the month component of an xs:date
.
fn:monthfromdate
($arg
as
xs:date?
) as
xs:integer?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:integer
between 1 and 12, both inclusive, representing the month component
in the local value of $arg
.
The expression
fn:monthfromdate(xs:date("1999053105:00"))
returns 5
.
The expression
fn:monthfromdate(xs:date("20000101+05:00"))
returns 1
.
Returns the day component of an xs:date
.
fn:dayfromdate
($arg
as
xs:date?
) as
xs:integer?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:integer
between 1 and 31, both inclusive, representing the day component in
the localized value of $arg
.
The expression
fn:dayfromdate(xs:date("1999053105:00"))
returns
31
.
The expression
fn:dayfromdate(xs:date("20000101+05:00"))
returns
1
.
Returns the timezone component of an xs:date
.
fn:timezonefromdate
($arg
as
xs:date?
) as
xs:dayTimeDuration?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns the timezone component of
$arg
, if any. If $arg
has a timezone
component, then the result is an xs:dayTimeDuration
that indicates deviation from UTC; its value may range from +14:00
to 14:00 hours, both inclusive. If $arg
has no
timezone component, the result is the empty sequence.
The expression
fn:timezonefromdate(xs:date("1999053105:00"))
returns xs:dayTimeDuration("PT5H")
.
The expression
fn:timezonefromdate(xs:date("20000612Z"))
returns
xs:dayTimeDuration("PT0S")
.
Returns the hours component of an xs:time
.
fn:hoursfromtime
($arg
as
xs:time?
) as
xs:integer?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:integer
between 0 and 23, both inclusive, representing the value of the
hours component in the local value of $arg
.
Assume that the dynamic context provides an implicit timezone
value of 05:00
.
The expression
fn:hoursfromtime(xs:time("11:23:00"))
returns
11
.
The expression
fn:hoursfromtime(xs:time("21:23:00"))
returns
21
.
The expression
fn:hoursfromtime(xs:time("01:23:00+05:00"))
returns
1
.
The expression
fn:hoursfromtime(fn:adjusttimetotimezone(xs:time("01:23:00+05:00"),
xs:dayTimeDuration("PT0S")))
returns 20
.
The expression
fn:hoursfromtime(xs:time("24:00:00"))
returns
0
.
Returns the minutes component of an xs:time
.
fn:minutesfromtime
($arg
as
xs:time?
) as
xs:integer?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:integer
value
between 0 and 59, both inclusive, representing the value of the
minutes component in the local value of $arg
.
The expression
fn:minutesfromtime(xs:time("13:00:00Z"))
returns
0
.
Returns the seconds component of an xs:time
.
fn:secondsfromtime
($arg
as
xs:time?
) as
xs:decimal?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns an xs:decimal
value
greater than or equal to zero and less than 60, representing the
seconds and fractional seconds in the local value of
$arg
.
The expression
fn:secondsfromtime(xs:time("13:20:10.5"))
returns
10.5
.
Returns the timezone component of an xs:time
.
fn:timezonefromtime
($arg
as
xs:time?
) as
xs:dayTimeDuration?
If $arg
is the empty sequence, the function returns
the empty sequence.
Otherwise, the function returns the timezone component of
$arg
, if any. If $arg
has a timezone
component, then the result is an xs:dayTimeDuration
that indicates deviation from UTC; its value may range from +14:00
to 14:00 hours, both inclusive. If $arg
has no
timezone component, the result is the empty sequence.
The expression
fn:timezonefromtime(xs:time("13:20:0005:00"))
returns xs:dayTimeDuration("PT5H")
.
The expression
fn:timezonefromtime(xs:time("13:20:00"))
returns
()
.
Function  Meaning 

fn:adjustdateTimetotimezone 
Adjusts an xs:dateTime value to a specific
timezone, or to no timezone at all. 
fn:adjustdatetotimezone 
Adjusts an xs:date value to a specific timezone,
or to no timezone at all; the result is the date in the target
timezone that contains the starting instant of the supplied
date. 
fn:adjusttimetotimezone 
Adjusts an xs:time value to a specific timezone,
or to no timezone at all. 
These functions adjust the timezone component of an
xs:dateTime
, xs:date
or
xs:time
value. The $timezone
argument to
these functions is defined as an xs:dayTimeDuration
but must be a valid timezone value.
Adjusts an xs:dateTime
value to a specific
timezone, or to no timezone at all.
fn:adjustdateTimetotimezone
($arg
as
xs:dateTime?
) as
xs:dateTime
fn:adjustdateTimetotimezone ( 
$arg 
as xs:dateTime? , 
$timezone 
as xs:dayTimeDuration? ) as xs:dateTime 
If $timezone
is not specified, then the effective
value of $timezone
is the value of the implicit
timezone in the dynamic context.
If $arg
is the empty sequence, then the function
returns the empty sequence.
If $arg
does not have a timezone component and
$timezone
is the empty sequence, then the result is
$arg
.
If $arg
does not have a timezone component and
$timezone
is not the empty sequence, then the result
is $arg
with $timezone
as the timezone
component.
If $arg
has a timezone component and
$timezone
is the empty sequence, then the result is
the local value of $arg
without its timezone
component.
If $arg
has a timezone component and
$timezone
is not the empty sequence, then the result
is the xs:dateTime
value that is equal to
$arg
and that has a timezone component equal to
$timezone
.
A dynamic error is raised [err:FODT0003] if $timezone
is less
than PT14H
or greater than PT14H
or is
not an integral number of minutes.
Assume the dynamic context provides an implicit timezone of
05:00 (PT5H0M)
.
let $tz10
:=
xs:dayTimeDuration("PT10H")
The expression
fn:adjustdateTimetotimezone(xs:dateTime('20020307T10:00:00'))
returns xs:dateTime('20020307T10:00:0005:00')
.
The expression
fn:adjustdateTimetotimezone(xs:dateTime('20020307T10:00:0007:00'))
returns xs:dateTime('20020307T12:00:0005:00')
.
The expression
fn:adjustdateTimetotimezone(xs:dateTime('20020307T10:00:00'),
$tz10)
returns
xs:dateTime('20020307T10:00:0010:00')
.
The expression
fn:adjustdateTimetotimezone(xs:dateTime('20020307T10:00:0007:00'),
$tz10)
returns
xs:dateTime('20020307T07:00:0010:00')
.
The expression
fn:adjustdateTimetotimezone(xs:dateTime('20020307T10:00:0007:00'),
xs:dayTimeDuration("PT10H"))
returns
xs:dateTime('20020308T03:00:00+10:00')
.
The expression
fn:adjustdateTimetotimezone(xs:dateTime('20020307T00:00:00+01:00'),
xs:dayTimeDuration("PT8H"))
returns
xs:dateTime('20020306T15:00:0008:00')
.
The expression
fn:adjustdateTimetotimezone(xs:dateTime('20020307T10:00:00'),
())
returns
xs:dateTime('20020307T10:00:00')
.
The expression
fn:adjustdateTimetotimezone(xs:dateTime('20020307T10:00:0007:00'),
())
returns
xs:dateTime('20020307T10:00:00')
.
Adjusts an xs:date
value to a specific timezone, or
to no timezone at all; the result is the date in the target
timezone that contains the starting instant of the supplied
date.
fn:adjustdatetotimezone
($arg
as
xs:date?
) as
xs:date?
fn:adjustdatetotimezone ( 
$arg 
as xs:date? , 
$timezone 
as xs:dayTimeDuration? ) as xs:date? 
If $timezone
is not specified, then the effective
value of $timezone
is the value of the implicit
timezone in the dynamic context.
If $arg
is the empty sequence, then the function
returns the empty sequence.
If $arg
does not have a timezone component and
$timezone
is the empty sequence, then the result is
the value of $arg
.
If $arg
does not have a timezone component and
$timezone
is not the empty sequence, then the result
is $arg
with $timezone
as the timezone
component.
If $arg
has a timezone component and
$timezone
is the empty sequence, then the result is
the local value of $arg
without its timezone
component.
If $arg
has a timezone component and
$timezone
is not the empty sequence, then the function
returns the value of the expression:
Let $dt
be the value of fn:dateTime($arg,
xs:time('00:00:00'))
.
Let $adt
be the value of fn:adjustdateTimetotimezone($dt,
$timezone)
The function returns the value of xs:date($adt)
Editorial note  
I suspect this procedure actually gives the right result in all cases, so the whole description can be simplified. 
A dynamic error is raised [err:FODT0003] if $timezone
is less
than PT14H
or greater than PT14H
or is
not an integral number of minutes.
Assume the dynamic context provides an implicit timezone of
05:00 (PT5H0M)
.
let $tz10
:=
xs:dayTimeDuration("PT10H")
The expression
fn:adjustdatetotimezone(xs:date("20020307"))
returns xs:date("2002030705:00")
.
The expression
fn:adjustdatetotimezone(xs:date("2002030707:00"))
returns xs:date("2002030705:00")
.
($arg
is converted to
xs:dateTime("20020307T00:00:0007:00")
. This is
adjusted to the implicit timezone, giving
"20020307T02:00:0005:00"
. ).
The expression
fn:adjustdatetotimezone(xs:date("20020307"),
$tz10)
returns
xs:date("2002030710:00")
.
The expression
fn:adjustdatetotimezone(xs:date("2002030707:00"),
$tz10)
returns xs:date("2002030610:00")
.
($arg
is converted to the xs:dateTime
"20020307T00:00:0007:00"
. This is adjusted to the given
timezone, giving "20020306T21:00:0010:00"
.
).
The expression
fn:adjustdatetotimezone(xs:date("20020307"), ())
returns xs:date("20020307")
.
The expression
fn:adjustdatetotimezone(xs:date("2002030707:00"),
())
returns xs:date("20020307")
.
Adjusts an xs:time
value to a specific timezone, or
to no timezone at all.
fn:adjusttimetotimezone
($arg
as
xs:time?
) as
xs:time?
fn:adjusttimetotimezone ( 
$arg 
as xs:time? , 
$timezone 
as xs:dayTimeDuration? ) as xs:time? 
If $timezone
is not specified, then the effective
value of $timezone
is the value of the implicit
timezone in the dynamic context.
If $arg
is the empty sequence, then the function
returns the empty sequence.
If $arg
does not have a timezone component and
$timezone
is the empty sequence, then the result is
$arg
.
If $arg
does not have a timezone component and
$timezone
is not the empty sequence, then the result
is $arg
with $timezone
as the timezone
component.
If $arg
has a timezone component and
$timezone
is the empty sequence, then the result is
the localized value of $arg
without its timezone
component.
If $arg
has a timezone component and
$timezone
is not the empty sequence, then:
Let $dt
be the xs:dateTime
value
fn:dateTime(xs:date('19721231'),
$arg)
.
Let $adt
be the value of fn:adjustdateTimetotimezone($dt,
$timezone)
The function returns the xs:time
value
xs:time($adt)
.
A dynamic error is raised [err:FODT0003] if $timezone
is less
than PT14H
or greater than PT14H
or if
does not contain an integral number of minutes.
Assume the dynamic context provides an implicit timezone of
05:00 (PT5H0M)
.
let $tz10
:=
xs:dayTimeDuration("PT10H")
The expression
fn:adjusttimetotimezone(xs:time("10:00:00"))
returns xs:time("10:00:0005:00")
.
The expression
fn:adjusttimetotimezone(xs:time("10:00:0007:00"))
returns xs:time("12:00:0005:00")
.
The expression
fn:adjusttimetotimezone(xs:time("10:00:00"),
$tz10)
returns xs:time("10:00:0010:00")
.
The expression
fn:adjusttimetotimezone(xs:time("10:00:0007:00"),
$tz10)
returns xs:time("07:00:0010:00")
.
The expression
fn:adjusttimetotimezone(xs:time("10:00:00"), ())
returns xs:time("10:00:00")
.
The expression
fn:adjusttimetotimezone(xs:time("10:00:0007:00"),
())
returns xs:time("10:00:00")
.
The expression
fn:adjusttimetotimezone(xs:time("10:00:0007:00"),
xs:dayTimeDuration("PT10H"))
returns
xs:time("03:00:00+10:00")
.
These functions support adding or subtracting a duration value
to or from an xs:dateTime
, an xs:date
or
an xs:time
value. Appendix E of [XML Schema Part 2: Datatypes Second Edition]
describes an algorithm for performing such operations.
Function  Meaning 

op:subtractdateTimes 
Returns an xs:dayTimeDuration representing the
amount of elapsed time between the instants arg2 and
arg1 . 
op:subtractdates 
Returns the xs:dayTimeDuration that corresponds to
the elapsed time between the starting instant of $arg2
and the the starting instant of $arg2 . 
op:subtracttimes 
Returns the xs:dayTimeDuration that corresponds to
the elapsed time between the values of $arg2 and
$arg1 treated as times on the same date. 
op:addyearMonthDurationtodateTime 
Returns the xs:dateTime that is a given duration
after a specified xs:dateTime (or before, if the
duration is negative). 
op:adddayTimeDurationtodateTime 
Returns the xs:dateTime that is a given duration
after a specified xs:dateTime (or before, if the
duration is negative). 
op:subtractyearMonthDurationfromdateTime 
Returns the xs:dateTime that is a given duration
before a specified xs:dateTime (or after, if the
duration is negative). 
op:subtractdayTimeDurationfromdateTime 
Returns the xs:dateTime that is a given duration
before a specified xs:dateTime (or after, if the
duration is negative). 
op:addyearMonthDurationtodate 
Returns the xs:date that is a given duration after
a specified xs:date (or before, if the duration is
negative). 
op:adddayTimeDurationtodate 
Returns the xs:date that is a given duration after
a specified xs:date (or before, if the duration is
negative). 
op:subtractyearMonthDurationfromdate 
Returns the xs:date that is a given duration
before a specified xs:date (or after, if the duration
is negative). 
op:subtractdayTimeDurationfromdate 
Returns the xs:date that is a given duration
before a specified xs:date (or after, if the duration
is negative). 
op:adddayTimeDurationtotime 
Returns the xs:time value that is a given duration
after a specified xs:time (or before, if the duration
is negative or causes wraparound past midnight) 
op:subtractdayTimeDurationfromtime 
Returns the xs:time value that is a given duration
before a specified xs:time (or after, if the duration
is negative or causes wraparound past midnight) 
A processor that limits the number of digits in date and time datatype representations may encounter overflow and underflow conditions when it tries to execute the functions in this section. In these situations, the processor ·must· return P0M or PT0S in case of duration underflow and 00:00:00 in case of time underflow. It ·must· raise an error [err:FODT0001] in case of overflow.
The value spaces of the two totally ordered subtypes of
xs:duration
described in 8.1 Two totally ordered subtypes of
duration are xs:integer
months for
xs:yearMonthDuration
and xs:decimal
seconds for xs:dayTimeDuration
. If a processor limits
the number of digits allowed in the representation of
xs:integer
and xs:decimal
then overflow
and underflow situations can arise when it tries to execute the
functions in 8.4 Arithmetic
operators on durations. In these situations the processor
·must· return zero in
case of numeric underflow and P0M or PT0S in case of duration
underflow. It ·must· raise an error [err:FODT0002] in case of overflow.
Returns an xs:dayTimeDuration
representing the
amount of elapsed time between the instants arg2
and
arg1
.
Defines the semantics of the "" operator on
xs:dateTime
values.
op:subtractdateTimes ( 
$arg1 
as xs:dateTime , 
$arg2 
as xs:dateTime ) as xs:dayTimeDuration 
If either $arg1
or $arg2
do not
contain an explicit timezone then, for the purpose of the
operation, the implicit timezone provided by the dynamic context
(See
Section C.2 Dynamic Context
Components^{XP}.) is assumed to be
present as part of the value.
The function returns the elapsed time between the date/time
instant arg2
and the date/time instant
arg1
, computed according to the algorithm given in
Appendix E of [XML Schema Part 2: Datatypes
Second Edition], and expressed as a
xs:dayTimeDuration
.
If the normalized value of $arg1
precedes in time
the normalized value of $arg2
, then the returned value
is a negative duration.
Assume that the dynamic context provides an implicit timezone
value of 05:00
.
The expression
op:subtractdateTimes(xs:dateTime("20001030T06:12:00"),
xs:dateTime("19991128T09:00:00Z"))
returns
xs:dayTimeDuration("P337DT2H12M")
.
Returns the xs:dayTimeDuration
that corresponds to
the elapsed time between the starting instant of $arg2
and the the starting instant of $arg2
.
Defines the semantics of the "" operator on
xs:date
values.
op:subtractdates
($arg1
as
xs:date
,
$arg2
as
xs:date
) as
xs:dayTimeDuration
If either $arg1
or $arg2
do not
contain an explicit timezone then, for the purpose of the
operation, the implicit timezone provided by the dynamic context
(See
Section C.2 Dynamic Context
Components^{XP}.) is assumed to be
present as part of the value.
The starting instant of an xs:date
is the
xs:dateTime
at 00:00:00
on that date.
The function returns the result of subtracting the two starting
instants using op:subtractdateTimes
.
If the starting instant of $arg1
precedes in time
the starting instant of $arg2
, then the returned value
is a negative duration.
Assume that the dynamic context provides an implicit timezone
value of Z
.
The expression op:subtractdates(xs:date("20001030"),
xs:date("19991128"))
returns
xs:dayTimeDuration("P337D")
. (The normalized
values of the two starting instants are {2000, 10, 30, 0, 0,
0, PT0S}
and {1999, 11, 28, 0, 0, 0,
PT0S}
.).
Now assume that the dynamic context provides an implicit
timezone value of +05:00
.
The expression op:subtractdates(xs:date("20001030"),
xs:date("19991128Z"))
returns
xs:dayTimeDuration("P336DT19H")
. ( The normalized
values of the two starting instants are {2000, 10, 29, 19, 0,
0, PT0S}
and {1999, 11, 28, 0, 0, 0,
PT0S}
.).
The expression
op:subtractdates(xs:date("2000101505:00"),
xs:date("20001010+02:00"))
returns
xs:dayTimeDuration("P5DT7H")
.
Returns the xs:dayTimeDuration
that corresponds to
the elapsed time between the values of $arg2
and
$arg1
treated as times on the same date.
Defines the semantics of the "" operator on
xs:time
values.
op:subtracttimes
($arg1
as
xs:time
,
$arg2
as
xs:time
) as
xs:dayTimeDuration
The function returns the result of the expression:
opsubtractdateTimes( fn:dateTime(xs:date('19721231'), $arg1), fn:dateTime(xs:date('19721231'), $arg2))
Any other reference date would work equally well.
Assume that the dynamic context provides an implicit timezone
value of 05:00
. Assume, also, that the date
components of the reference xs:dateTime
correspond to
"19721231"
.
The expression op:subtracttimes(xs:time("11:12:00Z"),
xs:time("04:00:00"))
returns
xs:dayTimeDuration("PT2H12M")
. (This is obtained
by subtracting from the xs:dateTime
value {1972,
12, 31, 11, 12, 0, PT0S}
the xs:dateTime
value
{1972, 12, 31, 9, 0, 0, PT0S}
.).
The expression
op:subtracttimes(xs:time("11:00:0005:00"),
xs:time("21:30:00+05:30"))
returns
xs:dayTimeDuration("PT0S")
. (The two
xs:dateTime
values are {1972, 12, 31, 11, 0, 0,
PT5H}
and {1972, 12, 31, 21, 30, 0, PT5H30M}
.
These normalize to {1972, 12, 31, 16, 0, 0, PT0S}
and
{1972, 12, 31, 16, 0, 0, PT0S}
. ).
The expression
op:subtracttimes(xs:time("17:00:0006:00"),
xs:time("08:00:00+09:00"))
returns
xs:dayTimeDuration("P1D")
. (The two normalized
xs:dateTime
values are {1972, 12, 31, 23, 0, 0,
PT0S}
and {1972, 12, 30, 23, 0, 0,
PT0S}
.).
The expression op:subtracttimes(xs:time("24:00:00"),
xs:time("23:59:59"))
returns
xs:dayTimeDuration("PT23H59M59S")
. (The two
normalized xs:dateTime
values are {1972, 12, 31,
0, 0, 0, ()}
and {1972, 12, 31, 23, 59, 59.0,
()}
.).
Returns the xs:dateTime
that is a given duration
after a specified xs:dateTime
(or before, if the
duration is negative).
Defines the semantics of the "+" operator on
xs:dateTime
and xs:yearMonthDuration
values.
op:addyearMonthDurationtodateTime ( 
$arg1 
as xs:dateTime , 
$arg2 
as xs:yearMonthDuration ) as xs:dateTime 
The function returns the result of adding $arg2
to
the value of $arg1
using the algorithm described in
Appendix E of [XML Schema Part 2: Datatypes
Second Edition], disregarding the rule about leap seconds. If
$arg2
is negative, then the result
xs:dateTime
precedes $arg1
.
The result has the same timezone as $arg1
. If
$arg1
has no timezone, the result has no timezone.
The expression
op:addyearMonthDurationtodateTime(xs:dateTime("20001030T11:12:00"),
xs:yearMonthDuration("P1Y2M"))
returns
xs:dateTime("20011230T11:12:00")
.
Returns the xs:dateTime
that is a given duration
after a specified xs:dateTime
(or before, if the
duration is negative).
Defines the semantics of the "+" operator on
xs:dateTime
and xs:dayTimeDuration
values.
op:adddayTimeDurationtodateTime ( 
$arg1 
as xs:dateTime , 
$arg2 
as xs:dayTimeDuration ) as xs:dateTime 
The function returns the result of adding $arg2
to
the value of $arg1
using the algorithm described in
Appendix E of [XML Schema Part 2: Datatypes
Second Edition], disregarding the rule about leap seconds. If
$arg2
is negative, then the result
xs:dateTime
precedes $arg1
.
The result has the same timezone as $arg1
. If
$arg1
has no timezone, the result has no timezone.
The expression
op:adddayTimeDurationtodateTime(xs:dateTime("20001030T11:12:00"),
xs:dayTimeDuration("P3DT1H15M"))
returns
xs:dateTime("20001102T12:27:00")
.
Returns the xs:dateTime
that is a given duration
before a specified xs:dateTime
(or after, if the
duration is negative).
Defines the semantics of the "" operator on
xs:dateTime
and xs:yearMonthDuration
values.
op:subtractyearMonthDurationfromdateTime ( 
$arg1 
as xs:dateTime , 
$arg2 
as xs:yearMonthDuration ) as xs:dateTime 
The function returns the xs:dateTime
computed by
negating $arg2
and adding the result to the value of
$arg1
using the function op:addyearMonthDurationtodateTime
.
The expression
op:subtractyearMonthDurationfromdateTime(xs:dateTime("20001030T11:12:00"),
xs:yearMonthDuration("P1Y2M"))
returns
xs:dateTime("19990830T11:12:00")
.
Returns the xs:dateTime
that is a given duration
before a specified xs:dateTime
(or after, if the
duration is negative).
Defines the semantics of the "" operator on
xs:dateTime
and xs:dayTimeDuration
values.
op:subtractdayTimeDurationfromdateTime ( 
$arg1 
as xs:dateTime , 
$arg2 
as xs:dayTimeDuration ) as xs:dateTime 
The function returns the xs:dateTime
computed by
negating $arg2
and adding the result to the value of
$arg1
using the function op:adddayTimeDurationtodateTime
.
The expression
op:subtractdayTimeDurationfromdateTime(xs:dateTime("20001030T11:12:00"),
xs:dayTimeDuration("P3DT1H15M"))
returns
xs:dateTime("20001027T09:57:00")
.
Returns the xs:date
that is a given duration after
a specified xs:date
(or before, if the duration is
negative).
Defines the semantics of the "+" operator on
xs:date
and xs:yearMonthDuration
values.
op:addyearMonthDurationtodate ( 
$arg1 
as xs:date , 
$arg2 
as xs:yearMonthDuration ) as xs:date 
The function returns the result of casting $arg1
to
an xs:dateTime
, adding $arg2
using the
function op:addyearMonthDurationtodateTime
,
and casting the result back to an xs:date
.
The expression
op:addyearMonthDurationtodate(xs:date("20001030"),
xs:yearMonthDuration("P1Y2M"))
returns
xs:date("20011230")
.
Returns the xs:date
that is a given duration after
a specified xs:date
(or before, if the duration is
negative).
Defines the semantics of the "+" operator on
xs:date
and xs:dayTimeDuration
values.
op:adddayTimeDurationtodate ( 
$arg1 
as xs:date , 
$arg2 
as xs:dayTimeDuration ) as xs:date 
The function returns the result of casting $arg1
to
an xs:dateTime
, adding $arg2
using the
function op:adddayTimeDurationtodateTime
,
and casting the result back to an xs:date
.
The expression
op:adddayTimeDurationtodate(xs:date("20041030Z"),
xs:dayTimeDuration("P2DT2H30M0S"))
returns
xs:date("20041101Z")
. ( The starting instant of
the first argument is the xs:dateTime
value
{2004, 10, 30, 0, 0, 0, PT0S}
. Adding the second
argument to this gives the xs:dateTime
value
{2004, 11, 1, 2, 30, 0, PT0S}
. The time components are
then discarded. ).
Returns the xs:date
that is a given duration before
a specified xs:date
(or after, if the duration is
negative).
Defines the semantics of the "" operator on
xs:date
and xs:yearMonthDuration
values.
op:subtractyearMonthDurationfromdate ( 
$arg1 
as xs:date , 
$arg2 
as xs:yearMonthDuration ) as xs:date 
Returns the xs:date
computed by negating
$arg2
and adding the result to $arg1
using the function op:addyearMonthDurationtodate
.
The expression
op:subtractyearMonthDurationfromdate(xs:date("20001030"),
xs:yearMonthDuration("P1Y2M"))
returns
xs:date("19990830")
.
The expression
op:subtractyearMonthDurationfromdate(xs:date("20000229Z"),
xs:yearMonthDuration("P1Y"))
returns
xs:date("19990228Z")
.
The expression
op:subtractyearMonthDurationfromdate(xs:date("2000103105:00"),
xs:yearMonthDuration("P1Y1M"))
returns
xs:date("1999093005:00")
.
Returns the xs:date
that is a given duration before
a specified xs:date
(or after, if the duration is
negative).
Defines the semantics of the "" operator on
xs:date
and xs:dayTimeDuration
values.
op:subtractdayTimeDurationfromdate ( 
$arg1 
as xs:date , 
$arg2 
as xs:dayTimeDuration ) as xs:date 
Returns the xs:date
computed by negating
$arg2
and adding the result to $arg1
using the function op:adddayTimeDurationtodate
.
The expression
op:subtractdayTimeDurationfromdate(xs:date("20001030"),
xs:dayTimeDuration("P3DT1H15M"))
returns
xs:date("20001026")
.
Returns the xs:time
value that is a given duration
after a specified xs:time
(or before, if the duration
is negative or causes wraparound past midnight)
Defines the semantics of the "+" operator on
xs:time
and xs:dayTimeDuration
values.
op:adddayTimeDurationtotime ( 
$arg1 
as xs:time , 
$arg2 
as xs:dayTimeDuration ) as xs:time 
First, the days component in the canonical lexical
representation of $arg2
is set to zero (0) and the
value of the resulting xs:dayTimeDuration
is
calculated. Alternatively, the value of $arg2
modulus
86,400 is used as the second argument. This value is added to the
value of $arg1
converted to an
xs:dateTime
using a reference date such as
19721231
, and the time component of the result is
returned. Note that the xs:time
returned may occur in
a following or preceding day and may be less than
$arg1
.
The result has the same timezone as $arg1
. If
$arg1
has no timezone, the result has no timezone.
The expression
op:adddayTimeDurationtotime(xs:time("11:12:00"),
xs:dayTimeDuration("P3DT1H15M"))
returns
xs:time("12:27:00")
.
The expression
op:adddayTimeDurationtotime(xs:time("23:12:00+03:00"),
xs:dayTimeDuration("P1DT3H15M"))
returns
xs:time("02:27:00+03:00")
. (That is, {0, 0,
0, 2, 27, 0, PT3H}
).
Returns the xs:time
value that is a given duration
before a specified xs:time
(or after, if the duration
is negative or causes wraparound past midnight)
Defines the semantics of the "" operator on
xs:time
and xs:dayTimeDuration
values.
op:subtractdayTimeDurationfromtime ( 
$arg1 
as xs:time , 
$arg2 
as xs:dayTimeDuration ) as xs:time 
The function returns the result of negating $arg2
and adding the result to $arg1
using the function
adddayTimeDurationtotime
.
The expression
op:subtractdayTimeDurationfromtime(xs:time("11:12:00"),
xs:dayTimeDuration("P3DT1H15M"))
returns
xs:time("09:57:00")
.
The expression
op:subtractdayTimeDurationfromtime(xs:time("08:20:0005:00"),
xs:dayTimeDuration("P23DT10H10M"))
returns
xs:time("22:10:0005:00")
.
Function  Meaning 

fn:formatdateTime 
Returns a string containing an xs:dateTime value
formatted for display. 
fn:formatdate 
Returns a string containing an xs:date value
formatted for display. 
fn:formattime 
Returns a string containing an xs:time value
formatted for display. 
Three functions are provided to represent dates and times as a string, using the conventions of a selected calendar, language, and country. The signatures are presented first, followed by the rules which apply to each of the functions.
Returns a string containing an xs:dateTime
value
formatted for display.
fn:formatdateTime ( 
$value 
as xs:dateTime? , 
$picture 
as xs:string , 

$language 
as xs:string? , 

$calendar 
as xs:string? , 

$place 
as xs:string? ) as xs:string? 
fn:formatdateTime
($value
as
xs:dateTime?
,
$picture
as
xs:string
) as
xs:string?
Returns a string containing an xs:date
value
formatted for display.
fn:formatdate ( 
$value 
as xs:date? , 
$picture 
as xs:string , 

$language 
as xs:string? , 

$calendar 
as xs:string? , 

$place 
as xs:string? ) as xs:string? 
fn:formatdate
($value
as
xs:date?
,
$picture
as
xs:string
) as
xs:string?
Returns a string containing an xs:time
value
formatted for display.
fn:formattime ( 
$value 
as xs:time? , 
$picture 
as xs:string , 

$language 
as xs:string? , 

$calendar 
as xs:string? , 

$place 
as xs:string? ) as xs:string? 
fn:formattime
($value
as
xs:time?
,
$picture
as
xs:string
) as
xs:string?
The fn:formatdateTime
,
fn:formatdate
, and
fn:formattime
functions format $value
as a string using the picture
string specified by the $picture
argument, the
calendar specified by the $calendar
argument, the
language specified by the $language
argument, and the
country or other place name specified by the
$place
argument. The result of the function is the
formatted string representation of the supplied
xs:dateTime
, xs:date
, or
xs:time
value.
[Definition] The three functions
fn:formatdateTime
,
fn:formatdate
, and
fn:formattime
are
referred to collectively as the date formatting
functions.
If $value
is the empty sequence, the function
returns the empty sequence.
Calling the twoargument form of each of the three functions is equivalent to calling the fiveargument form with each of the last three arguments set to an empty sequence.
For details of the $language
,
$calendar
, and $place
arguments, see
9.8.4.3 The language, calendar, and
place arguments.
In general, the use of an invalid $picture
,
$language
, $calendar
, or
$place
argument results in a dynamic error. By
contrast, use of an option in any of these arguments that is valid
but not supported by the implementation is not an error, and in
these cases the implementation is required to output the value in a
fallback representation.
The picture consists of a sequence of variable markers and literal substrings. A substring enclosed in square brackets is interpreted as a variable marker; substrings not enclosed in square brackets are taken as literal substrings. The literal substrings are optional and if present are rendered unchanged, including any whitespace. If an opening or closing square bracket is required within a literal substring, it must be doubled. The variable markers are replaced in the result by strings representing aspects of the date and/or time to be formatted. These are described in detail below.
A variable marker consists of a component specifier followed optionally by one or two presentation modifiers and/or optionally by a width modifier. Whitespace within a variable marker is ignored.
The component specifier indicates the component of the date or time that is required, and takes the following values:
Specifier  Meaning  Default Presentation Modifier 

Y  year (absolute value)  1 
M  month in year  1 
D  day in month  1 
d  day in year  1 
F  day of week  n 
W  week in year  1 
w  week in month  1 
H  hour in day (24 hours)  1 
h  hour in halfday (12 hours)  1 
P  am/pm marker  n 
m  minute in hour  01 
s  second in minute  01 
f  fractional seconds  1 
Z  timezone  01:01 
z  timezone (same as Z, but modified where appropriate to include
a prefix as a time offset using GMT, for example GMT+1 or
GMT05:00. For this component there is a fixed prefix of
GMT , or a localized variation thereof for the chosen
language, and the remainder of the value is formatted as for
specifier Z . 
01:01 
C  calendar: the name or abbreviation of a calendar name  n 
E  era: the name of a baseline for the numbering of years, for example the reign of a monarch  n 
An error is reported [err:FOFD1340] if the syntax of the picture is incorrect.
An error is reported [err:FOFD1350] if a component specifier within
the picture refers to components that are not available in the
given type of $value
, for example if the picture
supplied to the formattime
refers to the year, month,
or day component.
It is not an error to include a timezone component when the supplied value has no timezone. In these circumstances the timezone component will be ignored.
The first presentation modifier indicates the style in which the value of a component is to be represented. Its value may be either:
any format token permitted as a primary format token in the
second argument of the formatinteger
function,
indicating that the value of the component is to be output
numerically using the specified number format (for example,
1
, 01
, i
, I
,
w
, W
, or Ww
) or
the format token n
, N
, or
Nn
, indicating that the value of the component is to
be output by name, in lowercase, uppercase, or titlecase
respectively. Components that can be output by name include (but
are not limited to) months, days of the week, timezones, and eras.
If the processor cannot output these components by name for the
chosen calendar and language then it must use an
implementationdefined fallback representation.
If a comma is to be used as a grouping separator within the
format token, then there must be a width specifier. More
specifically: if a variable marker contains one or more commas,
then the last comma is treated as introducing the width modifier,
and all others are treated as grouping separators. So
[Y9,999,*]
will output the year as
2,008
.
If the implementation does not support the use of the requested format token, it must use the default presentation modifier for that component.
If the first presentation modifier is present, then it may optionally be followed by a second presentation modifier as follows:
Modifier  Meaning 

t  traditional numbering. This has the same meaning
as in the second argument of fn:formatinteger . 
o  ordinal form of a number, for example
8th or 8º . This has the same meaning as
in the second argument of fn:formatinteger . The
actual representation of the ordinal form of a number may depend
not only on the language, but also on the grammatical context (for
example, in some languages it must agree in gender). 
Note:
Although the formatting rules are expressed in terms of the
rules for format tokens in fn:formatinteger
, the
formats actually used may be specialized to the numbering of date
components where appropriate. For example, in Italian, it is
conventional to use an ordinal number (primo
) for the
first day of the month, and cardinal numbers (due, tre,
quattro ...
) for the remaining days. A processor may
therefore use this convention to number days of the month, ignoring
the presence or absence of the ordinal presentation modifier.
Whether or not a presentation modifier is included, a width modifier may be supplied. This indicates the number of characters or digits to be included in the representation of the value.
The width modifier, if present, is introduced by a comma or semicolon. It takes the form:
"," minwidth (""
maxwidth)?
where minwidth
is either an unsigned integer
indicating the minimum number of characters to be output, or
*
indicating that there is no explicit minimum, and
maxwidth
is either an unsigned integer indicating the
maximum number of characters to be output, or *
indicating that there is no explicit maximum; if
maxwidth
is omitted then *
is assumed.
Both integers, if present, must be greater than
zero.
A format token containing more than one digit, such as
001
or 9999
, sets the minimum and maximum
width to the number of digits appearing in the format token; if a
width modifier is also present, then the width modifier takes
precedence.
A numeric format token may contain
optionaldigitsigns and groupingseparators
as described for fn:formatinteger
. However,
the grouping separator cannot be a closing square bracket
("]"
).
Note:
A format token consisting of a single digit, such as
1
, does not constrain the number of digits in the
output. In the case of fractional seconds in particular,
[f001]
requests three decimal digits,
[f01]
requests two digits, but [f1]
will
produce an implementationdefined number of digits. If exactly one
digit is required, this can be achieved using the component
specifier [f1,11]
.
If the minimum and maximum width are unspecified, then the
output uses as many characters as are required to represent the
value of the component without truncation and without padding: this
is referred to below as the full representation of the
value. For a timezone offset (component specifier z
),
the full representation consists of a sign for the offset, the
number of hours of the offset, and if the offset is not an integral
number of hours, a colon (:
) followed by the two
digits of the minutes of the offset..
If the full representation of the value exceeds the specified
maximum width, then the processor should attempt
to use an alternative shorter representation that fits within the
maximum width. Where the presentation modifier is N
,
n
, or Nn
, this is done by abbreviating
the name, using either conventional abbreviations if available, or
crude righttruncation if not. For example, setting
maxwidth
to 4
indicates that fourletter
abbreviations should be used, though it would be
acceptable to use a threeletter abbreviation if this is in
conventional use. (For example, "Tuesday" might be abbreviated to
"Tues", and "Friday" to "Fri".) In the case of the year component,
setting maxwidth
requests omission of highorder
digits from the year, for example, if maxwidth
is set
to 2
then the year 2003 will be output as
03
. In the case of the fractional seconds component,
the value is rounded to the specified size as if by applying the
function roundhalftoeven(fractionalseconds,
maxwidth)
. If no mechanism is available for fitting the
value within the specified maximum width (for example, when roman
numerals are used), then the value should be
output in its full representation.
If the full representation of the value is shorter than the specified minimum width, then the processor should pad the value to the specified width.
For decimal representations of numbers, this should be done by prepending zero digits from the appropriate set of digit characters, or appending zero digits in the case of the fractional seconds component.
For timezone offsets this should be done by first appending a
colon (:
) followed by two zero digits from the
appropriate set of digit characters if the full representation does
not already include a minutes component and if the specified
minimum width permits adding three characters, and then if
necessary prepending zero digits from the appropriate set of digit
characters to the hour component.
In other cases, it should be done by appending spaces.
Special rules apply to the formatting of timezones. When the
component specifiers Z
or z
are used, the
rules in this section override any rules given elsewhere in the
case of discrepancies.
If the date/time value to be formatted does not include a timezone offset, then the timezone component specifier is generally ignored (results in no output). The exception is where military timezones are used (format ZZ) in which case the string "J" is output, indicating local time.
When the component specifier is z
, the output is
the same as for component specifier Z
, except that it
is prefixed by the characters GMT
or some localized
equivalent. The prefix is omitted, however, in cases where the
timezone is identified by name rather than by a numeric offset from
UTC.
If the first presentation modifier is numeric and
comprises one or two digits with no groupingseparator
(for example 1
or 01
), then the timezone
is formatted as a displacement from UTC in hours, preceded by a
plus or minus sign: for example 5
or
+03
. If the actual timezone offset is not an integral
number of hours, then the minutes part of the offset is appended,
separated by a colon: for example +10:30
or
1:15
.
If the first presentation modifier is numeric with a
groupingseparator (for example 1:01
or
01.01
), then the timezone offset is output in hours
and minutes, separated by the grouping separator, even if the
number of minutes is zero: for example +5:00
or
+10.30
.
If the first presentation modifier is numeric and
comprises three or four digits with no
groupingseparator, for example 001
or
0001
, then the timezone offset is shown in hours and
minutes with no separator, for example 0500
or
+1030
,
If the first presentation modifier is numeric, in any
of the above formats, and the second presentation
modifier is t
, then a zero timezone offset (that
is, UTC) is output as Z
instead of a signed numeric
value. In this presentation modifier is absent or if the timezone
offset is nonzero, then the displayed timezone offset is preceded
by a "" sign for negative offsets or a "+" sign for nonnegative
offsets.
If the first presentation modifier is Z
,
then the timezone is formatted as a military timezone letter, using
the convention Z = +00:00, A = +01:00, B = +02:00, ..., M = +12:00,
N = 01:00, O = 02:00, ... Y = 12:00. The letter J (meaning local
time) is used in the case of a value that does not specify a
timezone offset. Timezone offsets that have no representation in
this system (for example Indian Standard Time, +05:30) are output
as if the format 01:01
had been requested.
If the first presentation modifier is N
,
then the timezone is output (where possible) as a timezone name,
for example EST
or CET
. The same timezone
offset has different names in different places; it is therefore
recommended that this option should be used only
if a country code or Olson timezone name is supplied in the
$place
argument. In the absence of this information,
the implementation may apply a default, for example by using the
timezone names that are conventional in North America. If no
timezone name can be identified, the timezone offset is output
using the fallback format +01:01
.
The following examples illustrate options for timezone formatting.
Variable marker  $place 
Timezone offsets (with time = 12:00:00)  

10:00  05:00  +00:00  +05:30  +13:00  
[Z]  ()  10:00  05:00  +00:00  +05:30  +13:00 
[Z0]  ()  10  5  +0  +5:30  +13:00 
[Z0:00]  ()  10:00  5:00  +0:00  +5:30  +13:00 
[Z00:00]  ()  10:00  05:00  +00:00  +05:30  +13:00 
[Z0000]  ()  1000  0500  +0000  +0530  +1300 
[Z00:00t]  ()  10:00  05:00  Z  +05:30  +13:00 
[z]  ()  GMT10:00  GMT05:00  GMT+00:00  GMT+05:30  GMT+13:00 
[ZZ]  ()  W  R  Z  +05:30  +13:00 
[ZN]  "us"  HST  EST  GMT  IST  +13:00 
[H00]:[M00] [ZN]  "America/New_York"  06:00 EST  12:00 EST  07:00 EST  01:30 EST  18:00 EST 
The set of languages, calendars, and places that are supported in the ·date formatting functions· is ·implementationdefined·. When any of these arguments is omitted or is an empty sequence, an ·implementationdefined· default value is used.
If the fallback representation uses a different calendar from
that requested, the output string must identify
the calendar actually used, for example by prefixing the string
with [Calendar: X]
(where X is the calendar actually
used), localized as appropriate to the requested language. If the
fallback representation uses a different language from that
requested, the output string must identify the
language actually used, for example by prefixing the string with
[Language: Y]
(where Y is the language actually used)
localized in an implementationdependent way. If a particular
component of the value cannot be output in the requested format, it
should be output in the default format for that
component.
The $language
argument specifies the language to be
used for the result string of the function. The value of the
argument must be either the empty sequence or a
value that would be valid for the xml:lang
attribute
(see [XML]). Note that this permits the identification of
sublanguages based on country codes (from [ISO
31661]) as well as identification of dialects and of regions
within a country.
If the $language
argument is omitted or is set to
an empty sequence, or if it is set to an invalid value or a value
that the implementation does not recognize, then the processor uses
an ·implementationdefined· language.
The language is used to select the appropriate languagedependent forms of:
names (for example, of months)
numbers expressed as words or as ordinals (twenty, 20th, twentieth
)
hour convention (023 vs 124, 011 vs 112)
first day of week, first week of year
Where appropriate this choice may also take into account the
value of the $place
argument, though this
should not be used to override the language or any
sublanguage that is specified as part of the language
argument.
The choice of the names and abbreviations used in any given
language is ·implementationdefined·. For example, one implementation might
abbreviate July as Jul
while another uses
Jly
. In German, one implementation might represent
Saturday as Samstag
while another uses
Sonnabend
. Implementations may
provide mechanisms allowing users to control such choices.
Where ordinal numbers are used, the selection of the correct representation of the ordinal (for example, the linguistic gender) may depend on the component being formatted and on its textual context in the picture string.
The calendar
attribute specifies that the
dateTime
, date
, or time
supplied in the $value
argument must
be converted to a value in the specified calendar and then
converted to a string using the conventions of that calendar.
A calendar value must be a valid lexical QName. If the QName does not have a prefix, then it identifies a calendar with the designator specified below. If the QName has a prefix, then the QName is expanded into an expandedQName using the inscope namespaces from the static context; the expandedQName identifies the calendar; the behavior in this case is ·implementationdefined·.
If the calendar attribute is omitted an ·implementationdefined· value is used.
Note:
The calendars listed below were known to be in use during the last hundred years. Many other calendars have been used in the past.
This specification does not define any of these calendars, nor
the way that they map to the value space of the
xs:date
data type in [XML
Schema Part 2: Datatypes Second Edition]. There may be
ambiguities when dates are recorded using different calendars. For
example, the start of a new day is not simultaneous in different
calendars, and may also vary geographically (for example, based on
the time of sunrise or sunset). Translation of dates is therefore
more reliable when the time of day is also known, and when the
geographic location is known. When translating dates between one
calendar and another, the processor may take account of the values
of the $place
and/or $language
arguments,
with the $place
argument taking precedence.
Information about some of these calendars, and algorithms for converting between them, may be found in [Calendrical Calculations].
Designator  Calendar 

AD  Anno Domini (Christian Era) 
AH  Anno Hegirae (Muhammedan Era) 
AME  Mauludi Era (solar years since Mohammed's birth) 
AM  Anno Mundi (Jewish Calendar) 
AP  Anno Persici 
AS  Aji Saka Era (Java) 
BE  Buddhist Era 
CB  Cooch Behar Era 
CE  Common Era 
CL  Chinese Lunar Era 
CS  Chula Sakarat Era 
EE  Ethiopian Era 
FE  Fasli Era 
ISO  ISO 8601 calendar 
JE  Japanese Calendar 
KE  Khalsa Era (Sikh calendar) 
KY  Kali Yuga 
ME  Malabar Era 
MS  Monarchic Solar Era 
NS  Nepal Samwat Era 
OS  Old Style (Julian Calendar) 
RS  Rattanakosin (Bangkok) Era 
SE  Saka Era 
SH  Mohammedan Solar Era (Iran) 
SS  Saka Samvat 
TE  Tripurabda Era 
VE  Vikrama Era 
VS  Vikrama Samvat Era 
At least one of the above calendars must be supported. It is ·implementationdefined· which calendars are supported.
The ISO 8601 calendar ([ISO 8601]), which
is included in the above list and designated ISO
, is
very similar to the Gregorian calendar designated AD
,
but it differs in several ways. The ISO calendar is intended to
ensure that date and time formats can be read easily by other
software, as well as being legible for human users. The ISO
calendar prescribes the use of particular numbering conventions as
defined in ISO 8601, rather than allowing these to be localized on
a perlanguage basis. In particular it provides a numeric 'week
date' format which identifies dates by year, week of the year, and
day in the week; in the ISO calendar the days of the week are
numbered from 1 (Monday) to 7 (Sunday), and week 1 in any calendar
year is the week (from Monday to Sunday) that includes the first
Thursday of that year. The numeric values of the components year,
month, day, hour, minute, and second are the same in the ISO
calendar as the values used in the lexical representation of the
date and time as defined in [XML Schema Part
2: Datatypes Second Edition]. The era ("E" component) with this
calendar is either a minus sign (for negative years) or a
zerolength string (for positive years). For dates before 1
January, AD 1, year numbers in the ISO and AD calendars are off by
one from each other: ISO year 0000 is 1 BC, 0001 is 2 BC, etc.
Note:
The value space of the date and time data types, as defined in
XML Schema, is based on absolute points in time. The lexical space
of these data types defines a representation of these absolute
points in time using the proleptic Gregorian calendar, that is, the
modern Western calendar extrapolated into the past and the future;
but the value space is calendarneutral. The ·date
formatting functions· produce a
representation of this absolute point in time, but denoted in a
possibly different calendar. So, for example, the date whose
lexical representation in XML Schema is 15020111
(the day on which Pope Gregory XIII was born) might be formatted
using the Old Style (Julian) calendar as 1 January
1502
. This reflects the fact that there was at that time a
tenday difference between the two calendars. It would be
incorrect, and would produce incorrect results, to represent this
date in an element or attribute of type xs:date
as
15020101
, even though this might reflect the way the
date was recorded in contemporary documents.
When referring to years occurring in antiquity, modern
historians generally use a numbering system in which there is no
year zero (the year before 1 CE is thus 1 BCE). This is the
convention that should be used when the requested
calendar is OS (Julian) or AD (Gregorian). When the requested
calendar is ISO, however, the conventions of ISO 8601
should be followed: here the year before +0001 is
numbered zero. In [XML Schema Part 2:
Datatypes Second Edition] (version 1.0), the value space for
xs:date
and xs:dateTime
does not include
a year zero: however, a future edition is expected to endorse the
ISO 8601 convention. This means that the date on which Julius
Caesar was assassinated has the ISO 8601 lexical representation
00430313, but will be formatted as 15 March 44 BCE in the Julian
calendar or 13 March 44 BCE in the Gregorian calendar (dependant on
the chosen localization of the names of months and eras).
The intended use of the $place
argument is to
identify the place where an event represented by the
dateTime
, date
, or time
supplied in the $value
argument took place or will
take place. If the value is supplied, and is not the empty
sequence, then it should either be a country
code or an Olson timezone name.
Country codes are defined in [ISO 31661]. Examples are "de" for Germany and "jp" for Japan. Implementations may also allow the use of codes representing subdivisions of a country from ISO 31662, or codes representing formerly used names of countries from ISO 31663
Olson timezone names are defined in the publicdomain tz timezone database [Olson Timezone Database]. Examples are "America/New_York" and "Europe/Rome".
This argument is not intended to identify the location of the
user for whom the date or time is being formatted; that should be
done by means of the $language
attribute. This
information may be used to provide additional
information when converting dates between calendars or when
deciding how individual components of the date and time are to be
formatted. For example, different countries using the Old Style
(Julian) calendar started the new year on different days, and some
countries used variants of the calendar that were out of
synchronization as a result of differences in calculating leap
years.
The geographical area identified by a country code is defined by the boundaries as they existed at the time of the date to be formatted, or the presentday boundaries for dates in the future.
If the $place
argument is supplied in the form of
an Olson timezone name that is recognized by the implementation,
then the date or time being formatted is adjusted to the timezone
offset applicable in that timezone. For example, if the
xs:dateTime
value 20100215T12:00:00Z
is
formatted with the $place
argument set to
America/New_York
, then the output will be as if the
value 20100215T07:00:0005:00
had been supplied.
This adjustment takes daylight savings time into account where
possible; if the date in question falls during daylight savings
time in New York, then it is adjusted to timezone offset
PT4H
rather than PT5H
. Adjustment using
daylight savings time is only possible where the value includes a
date, and where the date is within the range covered by the
timezone database.
The following examples show a selection of dates and times and the way they might be formatted. These examples assume the use of the Gregorian calendar as the default calendar.
Required Output  Expression 

20021231 
formatdate($d, "[Y0001][M01][D01]") 
12312002 
formatdate($d, "[M][D][Y]") 
31122002 
formatdate($d, "[D][M][Y]") 
31 XII 2002 
formatdate($d, "[D1] [MI] [Y]") 
31st December, 2002 
formatdate($d, "[D1o] [MNn], [Y]", "en", (),
()) 
31 DEC 2002 
formatdate($d, "[D01] [MN,*3] [Y0001]", "en", (),
()) 
December 31, 2002 
formatdate($d, "[MNn] [D], [Y]", "en", (),
()) 
31 Dezember, 2002 
formatdate($d, "[D] [MNn], [Y]", "de", (),
()) 
Tisdag 31 December 2002 
formatdate($d, "[FNn] [D] [MNn] [Y]", "sv", (),
()) 
[20021231] 
formatdate($d, "[[[Y0001][M01][D01]]]") 
Two Thousand and Three 
formatdate($d, "[YWw]", "en", (), ()) 
einunddreißigste Dezember 
formatdate($d, "[Dwo] [MNn]", "de", (), ()) 
3:58 PM 
formattime($t, "[h]:[m01] [PN]", "en", (),
()) 
3:58:45 pm 
formattime($t, "[h]:[m01]:[s01] [Pn]", "en", (),
()) 
3:58:45 PM PDT 
formattime($t, "[h]:[m01]:[s01] [PN] [ZN,*3]", "en",
(), ()) 
3:58:45 o'clock PM PDT 
formattime($t, "[h]:[m01]:[s01] o'clock [PN] [ZN,*3]",
"en", (), ()) 
15:58 
formattime($t,"[H01]:[m01]") 
15:58:45.762 
formattime($t,"[H01]:[m01]:[s01].[f001]") 
15:58:45 GMT+02:00 
formattime($t,"[H01]:[m01]:[s01] [z,66]", "en", (),
()) 
15.58 Uhr GMT+2 
formattime($t,"[H01]:[m01] Uhr [z]", "de", (),
()) 
3.58pm on Tuesday, 31st December 
formatdateTime($dt, "[h].[m01][Pn] on [FNn], [D1o]
[MNn]") 
12/31/2002 at 15:58:45 
formatdateTime($dt, "[M01]/[D01]/[Y0001] at
[H01]:[m01]:[s01]") 
The following examples use calendars other than the Gregorian calendar.
These examples use nonLatin characters which might not display correctly in all browsers, depending on the system configuration.
Description  Request  Result 

Islamic  formatdate($d, "[D١] [Mn]
[Y١]", "ar", "AH", ()) 
٢٦ ﺸﻭّﺍﻝ ١٤٢٣ 
Jewish (with Western numbering)  formatdate($d, "[D] [Mn] [Y]", "he", "AM",
()) 
26 טבת 5763 
Jewish (with traditional numbering)  formatdate($d, "[Dאt] [Mn]
[Yאt]", "he", "AM", ()) 
כ״ו טבת תשס״ג 
Julian (Old Style)  formatdate($d, "[D] [MNn] [Y]", "en", "OS",
()) 
18 December 2002 
Thai  formatdate($d, "[D๑] [Mn]
[Y๑]", "th", "BE", ()) 
๓๑ ธันวาคม ๒๕๔๕ 
In addition to the xs:QName
constructor function,
QName values can be constructed by combining a namespace URI,
prefix, and local name, or by resolving a lexical QName against the
inscope namespaces of an element node. This section defines these
functions. Leading and trailing whitespace, if present, is stripped
from string arguments before the result is constructed.
Function  Meaning 

fn:resolveQName 
Returns an xs:QName value (that is, an
expandedQName) by taking an xs:string that has the
lexical form of an xs:QName (a string in the form
"prefix:localname" or "localname") and resolving it using the
inscope namespaces for a given element. 
fn:QName 
Constructs an xs:QName value given a namespace URI
and a lexical QName. 
Returns an xs:QName
value (that is, an
expandedQName) by taking an xs:string
that has the
lexical form of an xs:QName
(a string in the form
"prefix:localname" or "localname") and resolving it using the
inscope namespaces for a given element.
fn:resolveQName
($qname
as
xs:string?
,
$element
as
element()
) as
xs:QName?
If $qname
is the empty sequence, returns the empty
sequence.
More specifically, the function searches the namespace bindings
of $element
for a binding whose name matches the
prefix of $qname
, or the zerolength string if it has
no prefix, and constructs an expandedQName whose local name is
taken from the supplied $qname
, and whose namespace
URI is taken from the string value of the namespace binding.
If the $qname
has a prefix and if there is no
namespace binding for $element
that matches this
prefix, then an error is raised [err:FONS0004].
If the $qname
has no prefix, and there is no
namespace binding for $element
corresponding to the
default (unnamed) namespace, then the resulting expandedQName has
no namespace part.
The prefix (or absence of a prefix) in the supplied
$qname
argument is retained in the returned
expandedQName, as discussed in Section
Terminology^{DM30}.
If $qname
does not have the correct lexical form
for xs:QName
an error is raised [err:FOCA0002].
Sometimes the requirement is to construct an
xs:QName
without using the default namespace. This can
be achieved by writing:
if (contains($qname, ":")) then fn:resolveQName($qname, $element) else fn:QName("", $qname)
If the requirement is to construct an xs:QName
using the namespaces in the static context, then the
xs:QName
constructor should be used.
Assume that the element bound to $element
has a
single namespace binding bound to the prefix eg
.
fn:resolveQName("hello", $element)
returns a QName
with local name "hello" that is in no namespace.
fn:resolveQName("eg:myFunc", $element)
returns an
xs:QName
whose namespace URI is specified by the
namespace binding corresponding to the prefix "eg" and whose local
name is "myFunc".
Constructs an xs:QName
value given a namespace URI
and a lexical QName.
fn:QName
($paramURI
as
xs:string?
,
$paramQName
as
xs:string
) as
xs:QName
The namespace URI in the returned QName is taken from
$paramURI
. If $paramURI
is the
zerolength string or the empty sequence, it represents "no
namespace".
The prefix (or absence of a prefix) in $paramQName
is retained in the returned xs:QName
value.
The local name in the result is taken from the local part of
$paramQName
.
If $paramQName
does not have the correct lexical
form for an xs:QName
an error is raised [err:FOCA0002].
If $paramURI
is the zerolength string or the empty
sequence, and the value of $paramQName
contains a
colon (:
), an error is raised [err:FOCA0002].
If $paramURI
is not a valid URI (XML Namespaces
1.0) or IRI (XML Namespaces 1.1) then an error may
be raised [err:FOCA0002].
Note that unlike the xs:QName
constructor, this
function does not require a string literal as the argument.
fn:QName("http://www.example.com/example",
"person")
returns an xs:QName
with namespace
URI = "http://www.example.com/example", local name = "person" and
prefix = "".
fn:QName("http://www.example.com/example",
"ht:person")
returns an xs:QName
with namespace
URI = "http://www.example.com/example", local name = "person" and
prefix = "ht".
This section specifies functions on QNames as defined in [XML Schema Part 2: Datatypes Second Edition].
Function  Meaning 

op:QNameequal 
Returns true if two supplied QNames have the same
namespace URI and the same local part. 
fn:prefixfromQName 
Returns the prefix component of the supplied QName. 
fn:localnamefromQName 
Returns the local part of the supplied QName. 
fn:namespaceurifromQName 
Returns the namespace URI part of the supplied QName. 
fn:namespaceuriforprefix 
Returns the namespace URI of one of the inscope namespaces for
$element , identified by its namespace prefix. 
fn:inscopeprefixes 
Returns the prefixes of the inscope namespaces for an element node. 
Returns true
if two supplied QNames have the same
namespace URI and the same local part.
Defines the semantics of the "eq" and "ne" operators on values
of type xs:QName
.
op:QNameequal
($arg1
as
xs:QName
,
$arg2
as
xs:QName
) as
xs:boolean
The function returns true
if the namespace URIs of
$arg1
and $arg2
are equal and the local
names of $arg1
and $arg2
are equal.
Otherwise, the function returns false
.
The namespace URI parts are considered equal if they are both
absent, or if they are both present and equal under the rules of
the fn:codepointequal
function.
The local parts are also compared under the rules of the
fn:codepointequal
function.
The prefix parts of $arg1
and $arg2
,
if any, are ignored.
Returns the prefix component of the supplied QName.
fn:prefixfromQName
($arg
as
xs:QName?
) as
xs:NCName?
If $arg
is the empty sequence the function returns
the empty sequence.
If $arg
has no prefix component the function
returns the empty sequence.
Otherwise, the function returns an xs:NCName
representing the prefix component of $arg
.
Returns the local part of the supplied QName.
fn:localnamefromQName
($arg
as
xs:QName?
) as
xs:NCName?
If $arg
is the empty sequence the function returns
the empty sequence.
Otherwise, the function returns an xs:NCName
representing the local part of $arg
.
The expression
fn:localnamefromQName(fn:QName("http://www.example.com/example",
"person"))
returns "person"
.
Returns the namespace URI part of the supplied QName.
fn:namespaceurifromQName
($arg
as
xs:QName?
) as
xs:anyURI?
If $arg
is the empty sequence the function returns
the empty sequence.
Otherwise, the function returns an xs:anyURI
representing the namespace URI part of $arg
.
If $arg
is in no namespace, the function returns
the zerolength xs:anyURI
.
The expression
fn:namespaceurifromQName(fn:QName("http://www.example.com/example",
"person"))
returns
xs:anyURI("http://www.example.com/example")
.
Returns the namespace URI of one of the inscope namespaces for
$element
, identified by its namespace prefix.
fn:namespaceuriforprefix ( 
$prefix 
as xs:string? , 
$element 
as element() ) as xs:anyURI? 
If $element
has an inscope namespace whose
namespace prefix is equal to $prefix
, it returns the
namespace URI of that namespace. If $prefix
is the
zerolength string or the empty sequence, it returns the namespace
URI of the default (unnamed) namespace. Otherwise, it returns the
empty sequence.
Prefixes are equal only if their Unicode codepoints match exactly.
Returns the prefixes of the inscope namespaces for an element node.
fn:inscopeprefixes
($element
as
element()
) as
xs:string*
The function returns a sequence of strings representing the
prefixes of the inscope namespaces for $element
.
For namespace bindings that have a prefix, the function returns
the prefix as an xs:NCName
. For the default namespace,
which has no prefix, it returns the zerolength string.
The result sequence contains no duplicates.
The ordering of the result sequence is ·implementationdependent·.
The following comparison operators on
xs:base64Binary
and xs:hexBinary
values
are defined. Comparisons take two operands of the same type; that
is, both operands must be xs:base64Binary
or both
operands may be xs:hexBinary
. Each returns a boolean
value.
A value of type xs:hexBinary
can be compared with a
value of type xs:base64Binary
by casting one value to
the other type. See 18.1.7 Casting
to xs:base64Binary and xs:hexBinary.
Function  Meaning 

op:hexBinaryequal 
Returns true if two xs:hexBinary values contain
the same octet sequence. 
op:base64Binaryequal 
Returns true if two xs:base64Binary values contain
the same octet sequence. 
Returns true if two xs:hexBinary
values contain the
same octet sequence.
Defines the semantics of the "eq" and "ne" operators on
xs:hexBinary
values.
op:hexBinaryequal ( 
$value1 
as xs:hexBinary , 
$value2 
as xs:hexBinary ) as xs:boolean 
The function returns true
if $value1
and $value2
are of the same length, measured in binary
octets, and contain the same octets in the same order. Otherwise,
it returns false
.
Returns true if two xs:base64Binary
values contain
the same octet sequence.
Defines the semantics of the "eq" and "ne" operators on
xs:base64Binary
values.
op:base64Binaryequal ( 
$value1 
as xs:base64Binary , 
$value2 
as xs:base64Binary ) as xs:boolean 
The function returns true
if $value1
and $value2
are of the same length, measured in binary
octets, and contain the same octets in the same order. Otherwise,
it returns false
.
This section specifies operators that take
xs:NOTATION
values as arguments.
Function  Meaning 

op:NOTATIONequal 
Returns true if the two xs:NOTATION
values have the same namespace URI and the same local part. 
Returns true
if the two xs:NOTATION
values have the same namespace URI and the same local part.
Defines the semantics of the "eq" and "ne" operators on values
of type xs:NOTATION
.
op:NOTATIONequal
($arg1
as
xs:NOTATION
,
$arg2
as
xs:NOTATION
) as
xs:boolean
The function returns true
if the namespace URIs of
$arg1
and $arg2
are equal and the local
names of $arg1
and $arg2
are equal.
Otherwise, the function returns false
.
The namespace URI parts are considered equal if they are both
absent, or if they are both present and equal under the rules of
the fn:codepointequal
function.
The local parts are also compared under the rules of the
fn:codepointequal
function.
The prefix parts of $arg1
and $arg2
,
if any, are ignored.
This section specifies functions and operators on nodes. Nodes are formally defined in Section Nodes^{DM30}.
Function  Meaning 

fn:name 
Returns the name of a node, as an xs:string that
is either the zerolength string, or has the lexical form of an
xs:QName . 
fn:localname 
Returns the local part of the name of $arg as an
xs:string that is either the zerolength string, or
has the lexical form of an xs:NCName . 
fn:namespaceuri 
Returns the namespace URI part of the name of
$arg , as an xs:anyURI value. 
fn:number 
Returns the value indicated by $arg or, if
$arg is not specified, the context item after
atomization, converted to an xs:double . 
fn:lang 
This function tests whether the language of $node ,
or the context item if the second argument is omitted, as specified
by xml:lang attributes is the same as, or is a
sublanguage of, the language specified by
$testlang . 
op:issamenode 
Returns true if the two arguments refer to the same node. 
op:nodebefore 
Returns true if the node identified by the first argument precedes the node identified by the second argument in document order. 
op:nodeafter 
Returns true if the node identified by the first argument follows the node identified by the second argument in document order. 
fn:root 
Returns the root of the tree to which $arg
belongs. This will usually, but not necessarily, be a document
node. 
fn:haschildren 
Returns true if the supplied node has one or more child nodes (of any kind). 
fn:innermost 
Returns every node within the input sequence that is not an ancestor of another member of the input sequence; the nodes are returned in document order with duplicates eliminated. 
fn:outermost 
Returns every node within the input sequence that has no ancestor that is itself a member of the input sequence; the nodes are returned in document order with duplicates eliminated. 
For the illustrative examples below assume an XQuery or
transformation operating on a PurchaseOrder document containing a
number of lineitem elements. Each lineitem has child elements
called description, price, quantity, etc. whose content is
different for each lineitem. Quantity has simple content of type
xs:decimal
. Further assume that variables
$item1
, $item2
, etc. are each bound to
single lineitem element nodes in the document in sequence and that
the value of the quantity child of the first lineitem is
5.0
.
let $po
:=
<PurchaseOrder> <lineitem> <description>Large widget</description> <price>8.95</price> <quantity>5.0</quantity> </lineitem> <lineitem> <description>Small widget</description> <price>3.99</price> <quantity>2.0</quantity> </lineitem> <lineitem> <description>Tiny widget</description> <price>1.49</price> <quantity>805</quantity> </lineitem> </PurchaseOrder>
let $item1
:=
$po/lineitem[1]
let $item2
:=
$po/lineitem[2]
let $item3
:=
$po/lineitem[3]
Returns the name of a node, as an xs:string
that is
either the zerolength string, or has the lexical form of an
xs:QName
.
fn:name
() as
xs:string
fn:name
($arg
as
node()?
) as
xs:string
If the argument is omitted, it defaults to the context item
(.
). The behavior of the function if the argument is
omitted is exactly the same as if the context item had been passed
as the argument.
If the argument is supplied and is the empty sequence, the function returns the zerolength string.
If the node identified by $arg
has no name (that
is, if it is a document node, a comment, a text node, or a
namespace node having no name), the function returns the
zerolength string.
Otherwise, the function returns the value of the expression
fn:string(fn:nodename($arg))
.
The following errors may be raised when $arg
is
omitted: if the context item is absent [err:XPDY0002]^{XP}; if
the context item is not a node [err:XPTY0004]^{XP}.
Returns the local part of the name of $arg
as an
xs:string
that is either the zerolength string, or
has the lexical form of an xs:NCName
.
fn:localname
() as
xs:string
fn:localname
($arg
as
node()?
) as
xs:string
If the argument is omitted, it defaults to the context item
(.
). The behavior of the function if the argument is
omitted is exactly the same as if the context item had been passed
as the argument.
If the argument is supplied and is the empty sequence, the function returns the zerolength string.
If the node identified by $arg
has no name (that
is, if it is a document node, a comment, a text node, or a
namespace node having no name), the function returns the
zerolength string.
Otherwise, the function returns the local part of the
expandedQName of the node identified by $arg
, as
determined by the dm:nodename
accessor defined in
Section
nodename Accessor^{DM30}). This will be
an xs:string
whose lexical form is an
xs:NCName
.
The following errors may be raised when $arg
is
omitted: if the context item is absent [err:XPDY0002]^{XP}; if
the context item is not a node [err:XPTY0004]^{XP}.
Returns the namespace URI part of the name of $arg
,
as an xs:anyURI
value.
fn:namespaceuri
() as
xs:anyURI
fn:namespaceuri
($arg
as
node()?
) as
xs:anyURI
If the argument is omitted, it defaults to the context node
(.
). The behavior of the function if the argument is
omitted is exactly the same as if the context item had been passed
as the argument.
If the node identified by $arg
is neither an
element nor an attribute node, or if it is an element or attribute
node whose expandedQName (as determined by the
dm:nodename
accessor in the Section
nodename Accessor^{DM30}) is in no
namespace, then the function returns the zerolength
xs:anyURI
value.
Otherwise, the result will be the namespace URI part of the
expandedQName of the node identified by $arg
, as
determined by the dm:nodename
accessor defined in
Section
nodename Accessor^{DM30}), returned as
an xs:anyURI
value.
The following errors may be raised when $arg
is
omitted: if the context item is absent [err:XPDY0002]^{XP}; if
the context item is not a node [err:XPTY0004]^{XP}.
Returns the value indicated by $arg
or, if
$arg
is not specified, the context item after
atomization, converted to an xs:double
.
fn:number
() as
xs:double
fn:number
($arg
as
xs:anyAtomicType?
) as
xs:double
Calling the zeroargument version of the function is defined to
give the same result as calling the singleargument version with
the context item (.
). That is,
fn:number()
is equivalent to
fn:number(.)
.
If $arg
is the empty sequence or if
$arg
or the context item cannot be converted to an
xs:double
, the xs:double
value
NaN
is returned.
Otherwise, $arg
, or the context item after
atomization, is converted to an xs:double
following
the rules of 18.1.3.2 Casting to
xs:double. If the conversion to xs:double
fails, the xs:double
value NaN
is
returned.
If $arg
is omitted and the context item is absent
an error is raised: [err:XPDY0002]^{XP}.
The expression fn:number($item1/quantity)
returns
5.0e0
.
The expression fn:number($item2/description)
returns xs:double('NaN')
.
Assume that the context item is the xs:string
value
"15
". Then fn:number()
returns
1.5e1
.
This function tests whether the language of $node
,
or the context item if the second argument is omitted, as specified
by xml:lang
attributes is the same as, or is a
sublanguage of, the language specified by
$testlang
.
fn:lang
($testlang
as
xs:string?
) as
xs:boolean
fn:lang
($testlang
as
xs:string?
,
$node
as
node()
) as
xs:boolean
The behavior of the function if the second argument is omitted
is exactly the same as if the context item (.
) had
been passed as the second argument.
The language of the argument $node
, or the context
item if the second argument is omitted, is determined by the value
of the xml:lang
attribute on the node, or, if the node
has no such attribute, by the value of the xml:lang
attribute on the nearest ancestor of the node that has an
xml:lang
attribute. If there is no such ancestor, then
the function returns false
.
If $testlang
is the empty sequence it is
interpreted as the zerolength string.
The relevant xml:lang
attribute is determined by
the value of the XPath expression:
(ancestororself::*/@xml:lang)[last()]
If this expression returns an empty sequence, the function
returns false
.
Otherwise, the function returns true
if and only
if, based on a caseless default match as specified in section 3.13
of [The Unicode Standard], either:
$testlang
is equal to the stringvalue of the
relevant xml:lang
attribute, or
$testlang
is equal to some substring of the
stringvalue of the relevant xml:lang
attribute that
starts at the start of the stringvalue and ends immediately before
a hyphen, "" (the character "" is HYPHENMINUS, #x002D).
When $arg
is omitted the following errors may be
raised: if the context item is absent [err:XPDY0002]^{XP}; if
the context item is not a node [err:XPTY0004]^{XP}.
The expression fn:lang("en")
would return
true
if the context node were any of the following
four elements:
<para xml:lang="en"/>
<div xml:lang="en"><para>And now, and
forever!</para></div>
<para xml:lang="EN"/>
<para xml:lang="enus"/>
The expression fn:lang("fr")
would return
false
if the context node were <para
xml:lang="EN"/>
Returns true if the two arguments refer to the same node.
Defines the semantics of the "is" operator on nodes.
op:issamenode
($arg1
as
node()
,
$arg2
as
node()
) as
xs:boolean
If the node identified by the value of $arg1
is the
same node as the node identified by the value of $arg2
(that is, the two nodes have the same identity), then the function
returns true
; otherwise, the function returns
false
.
The expression op:issamenode($item1, $item1)
returns true()
.
The expression op:issamenode($item1, $item2)
returns false()
.
Returns true if the node identified by the first argument precedes the node identified by the second argument in document order.
Defines the semantics of the "<<" operator.
op:nodebefore
($arg1
as
node()
,
$arg2
as
node()
) as
xs:boolean
If the node identified by the value of $arg1
occurs
in document order before the node identified by the value of
$arg2
, then the function returns true
;
otherwise, it returns false
.
The rules determining the order of nodes within a single document and in different documents can be found in Section Document Order^{DM30}.
The expression op:nodebefore($item1, $item2)
returns true()
.
The expression op:nodebefore($item1, $item1)
returns false()
.
Returns true if the node identified by the first argument follows the node identified by the second argument in document order.
Defines the semantics of the ">>" operator.
op:nodeafter
($arg1
as
node()
,
$arg2
as
node()
) as
xs:boolean
If the node identified by the value of $arg1
occurs
in document order after the node identified by the value of
$arg2
, the function returns true
;
otherwise, it returns false
.
The rules determining the order of nodes within a single document and in different documents can be found in Section Document Order^{DM30}.
The expression op:nodeafter($item1, $item2)
returns false()
.
The expression op:nodeafter($item1, $item1)
returns false()
.
The expression op:nodeafter($item2, $item1)
returns true()
.
Returns the root of the tree to which $arg
belongs.
This will usually, but not necessarily, be a document node.
fn:root
() as
node()
fn:root
($arg
as
node()?
) as
node()?
If the function is called without an argument, the context item
(.
) is used as the default argument. The behavior of
the function if the argument is omitted is exactly the same as if
the context item had been passed as the argument.
The function returns the value of the expression
($arg/ancestororself::node())[1]
.
When $arg
is omitted the following errors may be
raised : if the context item is absent [err:XPDY0002]^{XP}; if
the context item is not a node [err:XPTY0004]^{XP}.
These examples use some variables which could be defined in [XQuery 1.0: An XML Query Language] as:
let $i := <tool>wrench</tool> let $o := <order> {$i} <quantity>5</quantity> </order> let $odoc := document {$o} let $newi := $o/tool
Or they could be defined in [XSL Transformations (XSLT) Version 2.0] as:
<xsl:variable name="i" as="element()"> <tool>wrench</tool> </xsl:variable> <xsl:variable name="o" as="element()"> <order> <xsl:copyof select="$i"/> <quantity>5</quantity> </order> </xsl:variable> <xsl:variable name="odoc"> <xsl:copyof select="$o"/> </xsl:variable> <xsl:variable name="newi" select="$o/tool"/>
fn:root($i)
returns the element node
$i
fn:root($o/quantity)
returns the element node
$o
fn:root($odoc//quantity)
returns the document node
$odoc
fn:root($newi)
returns the element node
$o
The final three examples could be made typesafe by wrapping
their operands with fn:exactlyone()
.
Returns true if the supplied node has one or more child nodes (of any kind).
fn:haschildren
($node
as
node()?
) as
xs:boolean
The result of the the function call
fn:haschildren($node)
is defined to be the same as
the result of the expression fn:exists($node/child::node())
.
If $node
is an empty sequence the result is
false.
The motivation for this function is to support streamed evaluation. According to the streaming rules in [XSL Transformations (XSLT) Version 3.0], the following construct is not streamable:
<xsl:if test="exists(row)"> <ul> <xsl:foreach select="row"> <li><xsl:valueof select="."/></li> </xsl:foreach> </ul> </xsl:if>
This is because it makes two downward selections to read the
child row
elements. The use of
fn:haschildren
in the xsl:if
conditional
is intended to circumvent this restriction.
Although the function was introduced to support streaming use cases, it has general utility as a convenience function.
Returns every node within the input sequence that is not an ancestor of another member of the input sequence; the nodes are returned in document order with duplicates eliminated.
fn:innermost
($nodes
as
node()*
) as
node()*
The effect of the function call
fn:innermost($nodes)
is defined to be equivalent to
the result of the expression $nodes except
$nodes/ancestor::node()
.
That is, the function takes as input a sequence of nodes, and returns every node within the sequence that is not an ancestor of another node within the sequence; the nodes are returned in document order with duplicates eliminated.
If the source document contains nested sections represented by
div
elements, the expression
innermost(//div)
returns those div
elements that do not contain further div
elements.
Returns every node within the input sequence that has no ancestor that is itself a member of the input sequence; the nodes are returned in document order with duplicates eliminated.
fn:outermost
($nodes
as
node()*
) as
node()*
The effect of the function call
fn:outermost($nodes)
is defined to be equivalent to
the result of the expression $nodes[not(ancestor::node()
intersect $nodes)]
.
That is, the function takes as input a sequence of nodes, and returns every node within the sequence that is not an ancestor of another node within the sequence; the nodes are returned in document order with duplicates eliminated.
The formulation $nodes except
$nodes/descendant::node()
might appear to be simpler, but
does not correctly account for attribute nodes, as these are not
descendants of their parent element.
The motivation for the function was based on XSLT streaming use
cases; there are cases where the [XSL
Transformations (XSLT) Version 3.0] streaming rules allow the
construct outermost(//section)
but do not allow
//section
; the function can therefore be useful in
cases where it is known that sections will not be nested, as well
as cases where the application actually wishes to process all
sections except those that are nested within another.
If the source document contains nested sections represented by
div
elements, the expression
innermost(//div)
returns those div
elements that do not contain further div
elements.
A sequence
is an ordered collection of zero or more
items
. An item
is either a node or an
atomic value. The terms sequence
and item
are defined formally in [XQuery 3.0: An XML
Query Language] and [XML Path Language
(XPath) 3.0].
The following functions are defined on sequences. These functions work on any sequence, without performing any operations that are sensitive to the individual items in the sequence.
Function  Meaning 

op:concatenate 
Returns the concatenation of two sequences. 
fn:empty 
Returns true if the argument is the empty sequence. 
fn:exists 
Returns true if the argument is a nonempty sequence. 
fn:head 
Returns the first item in a sequence. 
fn:tail 
Returns all but the first item in a sequence. 
fn:insertbefore 
Returns a sequence constructed by inserting an item or a sequence of items at a given position within an existing sequence. 
fn:remove 
Returns a new sequence containing all the items of
$target except the item at position
$position . 
fn:reverse 
Reverses the order of items in a sequence. 
fn:subsequence 
Returns the contiguous sequence of items in the value of
$sourceSeq beginning at the position indicated by the
value of $startingLoc and continuing for the number of
items indicated by the value of $length . 
fn:unordered 
Returns the items of $sourceSeq in an ·implementation dependent· order. 
As in the previous section, for the illustrative examples below,
assume an XQuery or transformation operating on a nonempty
Purchase Order document containing a number of lineitem elements.
The variable $seq
is bound to the sequence of
lineitem nodes in document order. The variables
$item1
, $item2
, etc. are bound to
separate, individual lineitem nodes in the sequence.
Returns the concatenation of two sequences.
Defines the semantics of the infix operator ",".
op:concatenate
($seq1
as
item()*
,
$seq2
as
item()*
) as
item()*
The function returns a sequence consisting of all the items in
$seq1
followed by all the items in
$seq2
.
For detailed type semantics, see [Formal Semantics].
If either sequence is the empty sequence, the other operand is returned.
The expression op:concatenate((1, 2, 3), (4, 5))
returns (1, 2, 3, 4, 5)
.
The expression op:concatenate((1, 2, 3), ())
returns (1, 2, 3)
.
The expression op:concatenate((), ())
returns
()
.
Returns true if the argument is the empty sequence.
fn:empty
($arg
as
item()*
) as
xs:boolean
If the value of $arg
is the empty sequence, the
function returns true
; otherwise, the function returns
false
.
The expression fn:empty((1,2,3)[10])
returns
true()
.
The expression fn:empty(fn:remove(("hello", "world"),
1))
returns false()
.
Returns true if the argument is a nonempty sequence.
fn:exists
($arg
as
item()*
) as
xs:boolean
If the value of $arg
is a nonempty sequence, the
function returns true
; otherwise, the function returns
false
.
The expression fn:exists(fn:remove(("hello"), 1))
returns false()
.
The expression fn:exists(fn:remove(("hello", "world"),
1))
returns true()
.
Returns the first item in a sequence.
fn:head
($arg
as
item()*
) as
item()?
The function returns the value of the expression
$arg[1]
If $arg
is the empty sequence, the empty sequence
is returned. Otherwise the first item in the sequence is
returned.
The expression fn:head(1 to 5)
returns
1
.
The expression fn:head(("a", "b", "c"))
returns
"a"
.
The expression fn:head(())
returns
()
.
Returns all but the first item in a sequence.
fn:tail
($arg
as
item()*
) as
item()*
The function returns the value of the expression
subsequence($arg, 2)
If $arg
is the empty sequence, or a sequence
containing a single item, then the empty sequence is returned.
The expression fn:tail(1 to 5)
returns (2, 3,
4, 5)
.
The expression fn:tail(("a", "b", "c"))
returns
("b", "c")
.
The expression fn:tail("a")
returns
()
.
The expression fn:tail(())
returns
()
.
Returns a sequence constructed by inserting an item or a sequence of items at a given position within an existing sequence.
fn:insertbefore ( 
$target 
as item()* , 
$position 
as xs:integer , 

$inserts 
as item()* ) as item()* 
The value returned by the function consists of all items of
$target
whose index is less than
$position
, followed by all items of
$inserts
, followed by the remaining elements of
$target
, in that order.
For detailed type semantics, see [Formal Semantics].
If $target
is the empty sequence,
$inserts
is returned. If $inserts
is the
empty sequence, $target
is returned.
If $position
is less than one (1), the first
position, the effective value of $position
is one (1).
If $position
is greater than the number of items in
$target
, then the effective value of
$position
is equal to the number of items in
$target
plus 1.
The value of $target
is not affected by the
sequence construction.
let $abc
:= ("a", "b", "c")
The expression fn:insertbefore($abc, 0, "z")
returns ("z", "a", "b", "c")
.
The expression fn:insertbefore($abc, 1, "z")
returns ("z", "a", "b", "c")
.
The expression fn:insertbefore($abc, 2, "z")
returns ("a", "z", "b", "c")
.
The expression fn:insertbefore($abc, 3, "z")
returns ("a", "b", "z", "c")
.
The expression fn:insertbefore($abc, 4, "z")
returns ("a", "b", "c", "z")
.
Returns a new sequence containing all the items of
$target
except the item at position
$position
.
fn:remove
($target
as
item()*
,
$position
as
xs:integer
) as
item()*
The function returns a sequence consisting of all items of
$target
whose index is less than
$position
, followed by all items of
$target
whose index is greater than
$position
.
For detailed type semantics, see [Formal Semantics].
If $position
is less than 1 or greater than the
number of items in $target
, $target
is
returned.
If $target
is the empty sequence, the empty
sequence is returned.
let $abc
:= ("a", "b", "c")
The expression fn:remove($abc, 0)
returns
("a", "b", "c")
.
The expression fn:remove($abc, 1)
returns
("b", "c")
.
The expression fn:remove($abc, 6)
returns
("a", "b", "c")
.
The expression fn:remove((), 3)
returns
()
.
Reverses the order of items in a sequence.
fn:reverse
($arg
as
item()*
) as
item()*
The function returns a sequence containing the items in
$arg
in reverse order.
For detailed type semantics, see [Formal Semantics].
If $arg
is the empty sequence, the empty sequence
is returned.
let $abc
:= ("a", "b", "c")
The expression fn:reverse($abc)
returns ("c",
"b", "a")
.
The expression fn:reverse(("hello"))
returns
("hello")
.
The expression fn:reverse(())
returns
()
.
Returns the contiguous sequence of items in the value of
$sourceSeq
beginning at the position indicated by the
value of $startingLoc
and continuing for the number of
items indicated by the value of $length
.
fn:subsequence
($sourceSeq
as
item()*
,
$startingLoc
as
xs:double
) as
item()*
fn:subsequence ( 
$sourceSeq 
as item()* , 
$startingLoc 
as xs:double , 

$length 
as xs:double ) as item()* 
In the twoargument case, returns:
$sourceSeq[fn:round($startingLoc) le position()]
In the threeargument case, returns:
$sourceSeq[fn:round($startingLoc) le position() and position() lt fn:round($startingLoc) + fn:round($length)]
For detailed type semantics, see [Formal Semantics].
The first item of a sequence is located at position 1, not position 0.
If $sourceSeq
is the empty sequence, the empty
sequence is returned.
If $startingLoc
is zero or negative, the
subsequence includes items from the beginning of the
$sourceSeq
.
If $length
is not specified, the subsequence
includes items to the end of $sourceSeq
.
If $length
is greater than the number of items in
the value of $sourceSeq
following
$startingLoc
, the subsequence includes items to the
end of $sourceSeq
.
As an exception to the previous two notes, if
$startingLoc
is INF
and
$length
is +INF
, then fn:round($startingLoc) +
fn:round($length)
is NaN
; since
position() lt NaN
is always false, the result is an
empty sequence.
The reason the function accepts arguments of type
xs:double
is that many computations on untyped data
return an xs:double
result; and the reason for the
rounding rules is to compensate for any imprecision in these
floatingpoint computations.
let $seq
:= ("item1", "item2", "item3",
"item4", "item5")
The expression fn:subsequence($seq, 4)
returns
("item4", "item5")
.
The expression fn:subsequence($seq, 3, 2)
returns
("item3", "item4")
.
Returns the items of $sourceSeq
in an ·implementation dependent· order.
fn:unordered
($sourceSeq
as
item()*
) as
item()*
The function returns the items of $sourceSeq
in an
·implementation dependent· order.
Query optimizers may be able to do a better job if the order of the output sequence is not specified. For example, when retrieving prices from a purchase order, if an index exists on prices, it may be more efficient to return the prices in index order rather than in document order.
The expression fn:unordered((1, 2, 3, 4, 5))
returns some permutation of (1, 2, 3, 4, 5)
.
The functions in this section rely on comparisons between the items in one or more sequences.
Function  Meaning 

fn:distinctvalues 
Returns the values that appear in a sequence, with duplicates eliminated. 
fn:indexof 
Returns a sequence of positive integers giving the positions
within the sequence $seq of items that are equal to
$search . 
fn:deepequal 
This function assesses whether two sequences are deepequal to each other. To be deepequal, they must contain items that are pairwise deepequal; and for two items to be deepequal, they must either be atomic values that compare equal, or nodes of the same kind, with the same name, whose children are deepequal. 
Returns the values that appear in a sequence, with duplicates eliminated.
fn:distinctvalues
($arg
as
xs:anyAtomicType*
) as
xs:anyAtomicType*
fn:distinctvalues ( 
$arg 
as xs:anyAtomicType* , 
$collation 
as xs:string ) as xs:anyAtomicType* 
The function returns the sequence that results from removing
from $arg
all but one of a set of values that are
equal to one another. Values are compared using the eq
operator, subject to the caveats defined below.
Values of type xs:untypedAtomic
are compared as if
they were of type xs:string
.
Values that cannot be compared, because the eq
operator is not defined for their types, are considered to be
distinct.
The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation. This collation is used when string comparison is required.
For xs:float
and xs:double
values,
positive zero is equal to negative zero and, although
NaN
does not equal itself, if $arg
contains multiple NaN
values a single NaN
is returned.
If xs:dateTime
, xs:date
or
xs:time
values do not have a timezone, they are
considered to have the implicit timezone provided by the dynamic
context for the purpose of comparison. Note that
xs:dateTime
, xs:date
or
xs:time
values can compare equal even if their
timezones are different.
The order in which the sequence of values is returned is ·implementation dependent·.
Which value of a set of values that compare equal is returned is ·implementation dependent·.
The static type of the result is a sequence of prime types as defined in [Formal Semantics].
If the input sequence contains values of different numeric types
that differ from each other by small amounts, then the eq operator
is not transitive, because of rounding effects occurring during
type promotion. In the situation where the input contains three
values A
, B
, and C
such that
A eq B
, B eq C
, but A ne C
,
then the number of items in the result of the function (as well as
the choice of which items are returned) is ·implementation dependent·, subject only to the constraints that (a) no
two items in the result sequence compare equal to each other, and
(b) every input item that does not appear in the result sequence
compares equal to some item that does appear in the result
sequence.
For example, this arises when computing:
distinctvalues( (xs:float('1.0'), xs:decimal('1.0000000000100000000001', xs:double( '1.00000000001'))
because the values of type xs:float
and
xs:double
both compare equal to the value of type
xs:decimal
but not equal to each other.
If $arg
is the empty sequence, the function returns
the empty sequence.
The expression fn:distinctvalues((1, 2.0, 3, 2))
returns some permutation of (1, 3, 2.0)
.
The expression
fn:distinctvalues((xs:untypedAtomic("cherry"),
xs:untypedAtomic("plum"), xs:untypedAtomic("plum")))
returns
some permutation of (xs:untypedAtomic("cherry"),
xs:untypedAtomic("plum"))
.
Returns a sequence of positive integers giving the positions
within the sequence $seq
of items that are equal to
$search
.
fn:indexof ( 
$seq 
as xs:anyAtomicType* , 
$search 
as xs:anyAtomicType ) as xs:integer* 
fn:indexof ( 
$seq 
as xs:anyAtomicType* , 
$search 
as xs:anyAtomicType , 

$collation 
as xs:string ) as xs:integer* 
The function returns a sequence of positive integers giving the
positions within the sequence $seq
of items that are
equal to $search
.
The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation. This collation is used when string comparison is required.
The items in the sequence $seq
are compared with
$search
under the rules for the eq
operator. Values of type xs:untypedAtomic
are compared
as if they were of type xs:string
. Values that cannot
be compared, because the eq
operator is not defined
for their types, are considered to be distinct. If an item compares
equal, then the position of that item in the sequence
$seq
is included in the result.
The first item in a sequence is at position 1, not position 0.
The result sequence is in ascending numeric order.
If the value of $seq
is the empty sequence, or if
no item in $seq
matches $search
, then the
function returns the empty sequence.
No error occurs if noncomparable values are encountered. So
when comparing two atomic values, the effective boolean value of
fn:indexof($a, $b)
is true if $a
and
$b
are equal, false if they are not equal or not
comparable.
The expression fn:indexof((10, 20, 30, 40), 35)
returns ()
.
The expression fn:indexof((10, 20, 30, 30, 20, 10),
20)
returns (2, 5)
.
The expression fn:indexof(("a", "sport", "and", "a",
"pastime"), "a")
returns (1, 4)
.
The expression fn:indexof(currentdate(), 23)
returns ()
.
If @a
is an attribute of type
xs:NMTOKENS
whose string value is "red green
blue"
, and whose typed value is therefore ("red",
"green", "blue")
, then fn:indexof(@a, "blue")
returns 3
. This is because the function calling
mechanism atomizes the attribute node to produce a sequence of
three xs:NMTOKEN
values.
This function assesses whether two sequences are deepequal to each other. To be deepequal, they must contain items that are pairwise deepequal; and for two items to be deepequal, they must either be atomic values that compare equal, or nodes of the same kind, with the same name, whose children are deepequal.
fn:deepequal
($parameter1
as
item()*
,
$parameter2
as
item()*
) as
xs:boolean
fn:deepequal ( 
$parameter1 
as item()* , 
$parameter2 
as item()* , 

$collation 
as xs:string ) as xs:boolean 
The $collation
argument identifies a collation
which is used at all levels of recursion when strings are compared
(but not when names are compared), according to the rules in
5.3.3 Choosing a
collation.
If the two sequences are both empty, the function returns
true
.
If the two sequences are of different lengths, the function
returns false
.
If the two sequences are of the same length, the function
returns true
if and only if every item in the sequence
$parameter1
is deepequal to the item at the same
position in the sequence $parameter2
. The rules for
deciding whether two items are deepequal follow.
Call the two items $i1
and $i2
respectively.
If $i1
and $i2
are both atomic values,
they are deepequal if and only if ($i1 eq $i2)
is
true
, or if both values are NaN
. If the
eq
operator is not defined for $i1
and
$i2
, the function returns false
.
If one of the pair $i1
or $i2
is an
atomic value and the other is a node, the function returns
false
.
If $i1
and $i2
are both nodes, they
are compared as described below:
If the two nodes are of different kinds, the result is
false
.
If the two nodes are both document nodes then they are
deepequal if and only if the sequence $i1/(*text())
is deepequal to the sequence $i2/(*text())
.
If the two nodes are both element nodes then they are deepequal if and only if all of the following conditions are satisfied:
The two nodes have the same name, that is (nodename($i1)
eq nodename($i2))
.
The two nodes are both annotated as having simple content or both nodes are annotated as having complex content.
The two nodes have the same number of attributes, and for every
attribute $a1
in $i1/@*
there exists an
attribute $a2
in $i2/@*
such that
$a1
and $a2
are deepequal.
One of the following conditions holds:
Both element nodes have a type annotation that is simple
content, and the typed value of $i1
is deepequal to
the typed value of $i2
.
Both element nodes have a type annotation that is complex
content with elementOnly content, and each child element of
$i1
is deepequal to the corresponding child element
of $i2
.
Both element nodes have a type annotation that is complex
content with mixed content, and the sequence
$i1/(*text())
is deepequal to the sequence
$i2/(*text())
.
Both element nodes have a type annotation that is complex content with empty content.
If the two nodes are both attribute nodes then they are deepequal if and only if both the following conditions are satisfied:
The two nodes have the same name, that is (nodename($i1)
eq nodename($i2))
.
The typed value of $i1
is deepequal to the typed
value of $i2
.
If the two nodes are both processing instruction nodes , then they are deepequal if and only if both the following conditions are satisfied:
The two nodes have the same name, that is (nodename($i1)
eq nodename($i2))
.
The string value of $i1
is equal to the string
value of $i2
.
If the two nodes are both namespace nodes, then they are deepequal if and only if both the following conditions are satisfied:
The two nodes either have the same name or are both nameless,
that is fn:deepequal(nodename($i1),
nodename($i2))
.
The string value of $i1
is equal to the string
value of $i2
when compared using the Unicode codepoint
collation.
If the two nodes are both text nodes or comment nodes, then they are deepequal if and only if their stringvalues are equal.
If either input sequence contains a function item, the function raises an error [err:FOTY0015]
The two nodes are not required to have the same type annotation,
and they are not required to have the same inscope namespaces.
They may also differ in their parent, their base URI, and the
values returned by the isid
and
isidrefs
accessors (see Section isid
Accessor^{DM30} and Section
isidrefs Accessor^{DM30}). The order of
children is significant, but the order of attributes is
insignificant.
The contents of comments and processing instructions are significant only if these nodes appear directly as items in the two sequences being compared. The content of a comment or processing instruction that appears as a descendant of an item in one of the sequences being compared does not affect the result. However, the presence of a comment or processing instruction, if it causes a text node to be split into two text nodes, may affect the result.
The result of fn:deepequal(1, currentdateTime())
is false
; it does not raise an error.
let $at
:=
<attendees> <name last='Parker' first='Peter'/> <name last='Barker' first='Bob'/> <name last='Parker' first='Peter'/> </attendees>
The expression fn:deepequal($at, $at/*)
returns
false()
.
The expression fn:deepequal($at/name[1],
$at/name[2])
returns false()
.
The expression fn:deepequal($at/name[1],
$at/name[3])
returns true()
.
The expression fn:deepequal($at/name[1], 'Peter
Parker')
returns false()
.
The following functions test the cardinality of their sequence arguments.
Function  Meaning 

fn:zeroorone 
Returns $arg if it contains zero or one items.
Otherwise, raises an error. 
fn:oneormore 
Returns $arg if it contains one or more items.
Otherwise, raises an error. 
fn:exactlyone 
Returns $arg if it contains exactly one item.
Otherwise, raises an error. 
The functions fn:zeroorone
, fn:oneormore
, and fn:exactlyone
defined in this
section, check that the cardinality of a sequence is in the
expected range. They are particularly useful with regard to static
typing. For example, the function call fn:remove($seq, fn:indexof($seq2,
'abc'))
requires the result of the call on fn:indexof
to be a singleton
integer, but the static type system cannot infer this; writing the
expression as fn:remove($seq,
fn:exactlyone(fn:indexof($seq2, 'abc')))
will provide
a suitable static type at query analysis time, and ensures that the
length of the sequence is correct with a dynamic check at query
execution time.
The type signatures for these functions deliberately declare the
argument type as item()*
, permitting a sequence of any
length. A more restrictive signature would defeat the purpose of
the function, which is to defer cardinality checking until query
execution time.
Returns $arg
if it contains zero or one items.
Otherwise, raises an error.
fn:zeroorone
($arg
as
item()*
) as
item()?
Except in error cases, the function returns $arg
unchanged.
For detailed type semantics, see [Formal Semantics].
An error is raised [err:FORG0003] if $arg
contains more
than one item.
Returns $arg
if it contains one or more items.
Otherwise, raises an error.
fn:oneormore
($arg
as
item()*
) as
item()+
Except in error cases, the function returns $arg
unchanged.
For detailed type semantics, see [Formal Semantics].
An error is raised [err:FORG0004] if $arg
is an empty
sequence.
Returns $arg
if it contains exactly one item.
Otherwise, raises an error.
fn:exactlyone
($arg
as
item()*
) as
item()
Except in error cases, the function returns $arg
unchanged.
For detailed type semantics, see [Formal Semantics].
An error is raised [err:FORG0005] if $arg
is an empty
sequence or a sequence containing more than one item.
Function  Meaning 

op:union 
Constructs a sequence containing every node that occurs in the
values of either $arg1 or $arg2 ,
eliminating duplicates and sorting the result in document
order. 
op:intersect 
Constructs a sequence containing every node that occurs in the
values of both $arg1 and $arg2 ,
eliminating duplicates and sorting the result in document
order. 
op:except 
Constructs a sequence containing every node that occurs in the
value of $arg1 but not in the value of
$arg2 , eliminating duplicates and sorting the result
in document order. 
As in the previous sections, for the illustrative examples
below, assume an XQuery or transformation operating on a Purchase
Order document containing a number of lineitem elements. The
variables $item1
, $item2
, etc. are bound
to individual lineitem nodes in the sequence. We use sequences of
these nodes in some of the examples below.
Constructs a sequence containing every node that occurs in the
values of either $arg1
or $arg2
,
eliminating duplicates and sorting the result in document
order.
Defines the semantics of the "union" or "" operator.
op:union
($arg1
as
node()*
,
$arg2
as
node()*
) as
node()*
The function returns a sequence containing every node that
occurs in the values of either $arg1
or
$arg2
, eliminating duplicate nodes. Nodes are returned
in document order.
Two nodes $n1
and $n2
are duplicates
if they satisfy op:issamenode($n1,
$n2)
.
For detailed type semantics, see [Formal Semantics].
If either operand is the empty sequence, the result is a sequence containing the nodes in the other operand in document order after eliminating duplicates.
let $seq1
:= ($item1, $item2)
let $seq2
:= ($item2, $item2,
$item1)
let $seq3
:= ($item2, $item3)
The expression op:union($seq1, $seq1)
returns
($item1, $item2)
.
The expression op:union($seq2, $seq3)
returns
($item1, $item2, $item3)
.
The expression op:union($seq2, ())
returns
($item1, $item2)
.
Constructs a sequence containing every node that occurs in the
values of both $arg1
and $arg2
,
eliminating duplicates and sorting the result in document
order.
Defines the semantics of the "intersect" operator.
op:intersect
($arg1
as
node()*
,
$arg2
as
node()*
) as
node()*
The function returns a sequence containing every node that
occurs in the values of both $arg1
and
$arg2
, eliminating duplicate nodes. Nodes are returned
in document order.
Two nodes $n1
and $n2
are duplicates
if they satisfy op:issamenode($n1,
$n2)
.
For detailed type semantics, see [Formal Semantics].
If either operand is the empty sequence, the function returns the empty sequence.
let $seq1
:= ($item1, $item2)
let $seq2
:= ($item2, $item2,
$item1)
let $seq3
:= ($item2, $item3)
The expression op:intersect($seq1, $seq1)
returns
($item1, $item2)
.
The expression op:intersect($seq2, $seq3)
returns
($item2)
.
The expression op:intersect($seq2, ())
returns
()
.
The expression op:intersect($item1, $item3)
returns
()
.
Constructs a sequence containing every node that occurs in the
value of $arg1
but not in the value of
$arg2
, eliminating duplicates and sorting the result
in document order.
Defines the semantics of the "except" operator.
op:except
($arg1
as
node()*
,
$arg2
as
node()*
) as
node()*
The function returns a sequence containing every node that
occurs in the value of $arg1
provided that it does not
occur in the value of $arg2
. Duplicate nodes are
eliminated, and nodes are returned in document order.
Two nodes $n1
and $n2
are duplicates
if they satisfy op:issamenode($n1,
$n2)
.
For detailed type semantics, see [Formal Semantics].
If $arg1
is the empty sequence, the empty sequence
is returned.
If $arg2
is the empty sequence, a sequence is
returned containing the nodes in $arg1
in document
order after eliminating duplicates.
let $seq1
:= ($item1, $item2)
let $seq2
:= ($item2, $item2,
$item1)
let $seq3
:= ($item2, $item3)
The expression op:except($seq1, $seq1)
returns
()
.
The expression op:except($seq2, $seq1)
returns
()
.
The expression op:except($seq2, $seq3)
returns
($item1)
.
The expression op:except($seq2, ())
returns
($item1, $item2)
.
The expression op:except($seq3, $seq2)
returns
($item3)
.
Aggregate functions take a sequence as argument and return a
single value computed from values in the sequence. Except for
fn:count
, the sequence must
consist of values of a single type or one if its subtypes, or they
must be numeric. xs:untypedAtomic
values are permitted
in the input sequence and handled by special conversion rules. The
type of the items in the sequence must also support certain
operations.
Function  Meaning 

fn:count 
Returns the number of items in a sequence. 
fn:avg 
Returns the average of the values in the input sequence
$arg , that is, the sum of the values divided by the
number of values. 
fn:max 
Returns a value that is equal to the highest value appearing in the input sequence. 
fn:min 
Returns a value that is equal to the lowest value appearing in the input sequence. 
fn:sum 
Returns a value obtained by adding together the values in
$arg . 
Returns the number of items in a sequence.
fn:count
($arg
as
item()*
) as
xs:integer
The function returns the number of items in the value of
$arg
.
Returns 0 if $arg
is the empty sequence.
let $seq1
:= ($item1, $item2)
let $seq2
:= (98.5, 98.3, 98.9)
let $seq3
:= ()
The expression fn:count($seq1)
returns
2
.
The expression fn:count($seq3)
returns
0
.
The expression fn:count($seq2)
returns
3
.
The expression fn:count($seq2[. > 100])
returns
0
.
Returns the average of the values in the input sequence
$arg
, that is, the sum of the values divided by the
number of values.
fn:avg
($arg
as
xs:anyAtomicType*
) as
xs:anyAtomicType?
If $arg
is the empty sequence, the empty sequence
is returned.
If $arg
contains values of type
xs:untypedAtomic
they are cast to
xs:double
.
Duration values must either all be
xs:yearMonthDuration
values or must all be
xs:dayTimeDuration
values. For numeric values, the
numeric promotion rules defined in 4.2
Arithmetic operators on numeric values are used to promote
all values to a single common type. After these operations,
$arg
must contain items of a single type, which must
be one of the four numeric types, xs:yearMonthDuration
or xs:dayTimeDuration
or one if its subtypes.
The function returns the average of the values as
sum($arg) div count($arg)
; but the implementation may
use an otherwise equivalent algorithm that avoids arithmetic
overflow.
For detailed type semantics, see [Formal Semantics].
If the input sequence contains items of incompatible types, as described above, then a type error is raised [err:FORG0006].
let $d1
:=
xs:yearMonthDuration("P20Y")
let $d2
:=
xs:yearMonthDuration("P10M")
let $seq3
:= (3, 4, 5)
The expression fn:avg($seq3)
returns
4.0
. (The result is of type
xs:decimal
.).
The expression fn:avg(($d1, $d2))
returns
xs:yearMonthDuration("P10Y5M")
.
fn:avg(($d1, $seq3))
raises a type error [err:FORG0006].
The expression fn:avg(())
returns
()
.
The expression fn:avg((xs:float('INF'),
xs:float('INF')))
returns xs:float('NaN')
.
The expression fn:avg(($seq3, xs:float('NaN')))
returns xs:float('NaN')
.
Returns a value that is equal to the highest value appearing in the input sequence.
fn:max
($arg
as
xs:anyAtomicType*
) as
xs:anyAtomicType?
fn:max
($arg
as
xs:anyAtomicType*
, $collation
as
xs:string
) as
xs:anyAtomicType?
The following rules are applied to the input sequence
$arg
:
Values of type xs:untypedAtomic
in
$arg
are cast to xs:double
.
Numeric and xs:anyURI
values are converted to the
least common type reachable by a combination of type promotion and
subtype substitution. See Section B.1 Type
Promotion^{XP} and Section B.2 Operator
Mapping^{XP}.
The items in the resulting sequence may be reordered in an arbitrary order. The resulting sequence is referred to below as the converted sequence. The function returns an item from the converted sequence rather than the input sequence.
If the converted sequence is empty, the function returns the empty sequence.
All items in the converted sequence must be derived
from a single base type for which the le
operator is
defined. In addition, the values in the sequence must have a total
order. If date/time values do not have a timezone, they are
considered to have the implicit timezone provided by the dynamic
context for the purpose of comparison. Duration values must either
all be xs:yearMonthDuration
values or must all be
xs:dayTimeDuration
values.
If the converted sequence contains the value NaN
,
the value NaN
is returned.
If the items in the converted sequence are of type
xs:string
or types derived by restriction from
xs:string
, then the determination of the item with the
smallest value is made according to the collation that is used. If
the type of the items in the converted sequence is not
xs:string
and $collation
is specified,
the collation is ignored.
The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation.
The function returns the result of the expression:
if (every $v in $c satisfies $c[1] ge $v) then $c[1] else fn:max(fn:subsequence($c, 2))
evaluated with $collation
as the default collation
if specified, and with $c
as the converted
sequence.
For detailed type semantics, see [Formal Semantics].
If the input sequence contains items of incompatible types, as described above, then a type error is raised [err:FORG0006].
Because the rules allow the sequence to be reordered, if there
are two or items that are "equal highest", the specific item whose
value is returned is ·implementation dependent·. This can arise for example if two different
strings compare equal under the selected collation, or if two
different xs:dateTime
values compare equal despite
being in different timezones.
If the converted sequence contains exactly one value then that value is returned.
The default type when the fn:max
function is
applied to xs:untypedAtomic
values is
xs:double
. This differs from the default type for
operators such as gt
, and for sorting in XQuery and
XSLT, which is xs:string
.
The expression fn:max((3,4,5))
returns
5
.
The expression fn:max((xs:integer(5), xs:float(5.0),
xs:double(0)))
returns xs:double(5.0e0)
.
fn:max((3,4,"Zero"))
raises a type error [err:FORG0006].
The expression fn:max((fn:currentdate(),
xs:date("21000101")))
returns
xs:date("21000101")
. (Assuming that the current
date is during the 21st century.).
The expression fn:max(("a", "b", "c"))
returns
"c"
. (Assuming a typical default
collation.).
Returns a value that is equal to the lowest value appearing in the input sequence.
fn:min
($arg
as
xs:anyAtomicType*
) as
xs:anyAtomicType?
fn:min
($arg
as
xs:anyAtomicType*
, $collation
as
xs:string
) as
xs:anyAtomicType?
The following rules are applied to the input sequence:
Values of type xs:untypedAtomic
in
$arg
are cast to xs:double
.
Numeric and xs:anyURI
values are converted to the
least common type reachable by a combination of type promotion and
subtype substitution. See Section B.1 Type
Promotion^{XP} and Section B.2 Operator
Mapping^{XP}.
The items in the resulting sequence may be reordered in an arbitrary order. The resulting sequence is referred to below as the converted sequence. The function returns an item from the converted sequence rather than the input sequence.
If the converted sequence is empty, the empty sequence is returned.
All items in the converted sequence must be derived
from a single base type for which the le
operator is
defined. In addition, the values in the sequence must have a total
order. If date/time values do not have a timezone, they are
considered to have the implicit timezone provided by the dynamic
context for the purpose of comparison. Duration values must either
all be xs:yearMonthDuration
values or must all be
xs:dayTimeDuration
values.
If the converted sequence contains the value NaN
,
the value NaN
is returned.
If the items in the converted sequence are of type
xs:string
or types derived by restriction from
xs:string
, then the determination of the item with the
smallest value is made according to the collation that is used. If
the type of the items in the converted sequence is not
xs:string
and $collation
is specified,
the collation is ignored.
The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation.
The function returns the result of the expression:
if (every $v in $c satisfies $c[1] le $v) then $c[1] else fn:min(fn:subsequence($c, 2))
evaluated with $collation
as the default collation
if specified, and with $c
as the converted
sequence.
For detailed type semantics, see [Formal Semantics].
If the input sequence contains items of incompatible types, as described above, then a type error is raised [err:FORG0006].
Because the rules allow the sequence to be reordered, if there
are two or items that are "equal lowest", the specific item whose
value is returned is ·implementation dependent·. This can arise for example if two different
strings compare equal under the selected collation, or if two
different xs:dateTime
values compare equal despite
being in different timezones.
If the converted sequence contains exactly one value then that value is returned.
The default type when the fn:min
function is
applied to xs:untypedAtomic
values is
xs:double
. This differs from the default type for
operators such as lt
, and for sorting in XQuery and
XSLT, which is xs:string
.
The expression fn:min((3,4,5))
returns
3
.
The expression fn:min((xs:integer(5), xs:float(5),
xs:double(10)))
returns xs:double(5.0e0)
.
fn:min((3,4,"Zero"))
raises a type error [err:FORG0006].
fn:min((xs:float(0.0E0), xs:float(0.0E0)))
can
return either positive or negative zero. The two items are
equal, so it is ·implementation dependent· which is returned.
The expression fn:min((fn:currentdate(),
xs:date("19000101")))
returns
xs:date("19000101")
. (Assuming that the current
date is set to a reasonable value.).
The expression fn:min(("a", "b", "c"))
returns
"a"
. (Assuming a typical default
collation.).
Returns a value obtained by adding together the values in
$arg
.
fn:sum
($arg
as
xs:anyAtomicType*
) as
xs:anyAtomicType
fn:sum ( 
$arg 
as xs:anyAtomicType* , 
$zero 
as xs:anyAtomicType? ) as xs:anyAtomicType? 
Any values of type xs:untypedAtomic
in
$arg
are cast to xs:double
. The items in
the resulting sequence may be reordered in an arbitrary order. The
resulting sequence is referred to below as the converted
sequence.
If the converted sequence is empty, then the singleargument
form of the function returns the xs:integer
value
0
; the twoargument form returns the value of the
argument $zero
.
If the converted sequence contains the value NaN
,
NaN
is returned.
All items in $arg
must be numeric or derived from a
single base type. In addition, the type must support addition.
Duration values must either all be
xs:yearMonthDuration
values or must all be
xs:dayTimeDuration
values. For numeric values, the
numeric promotion rules defined in 4.2
Arithmetic operators on numeric values are used to promote
all values to a single common type. The sum of a sequence of
integers will therefore be an integer, while the sum of a numeric
sequence that includes at least one xs:double
will be
an xs:double
.
The result of the function, using the second signature, is the result of the expression:
if (fn:count($c) eq 0) then $zero else if (fn:count($c) eq 1) then $c[1] else $c[1] + fn:sum(subsequence($c, 2))
where $c
is the converted sequence.
The result of the function, using the first signature, is the
result of the expression: fn:sum($arg, 0)
.
For detailed type semantics, see [Formal Semantics].
If the input sequence contains items of incompatible types, as described above, then a type error is raised [err:FORG0006].
The second argument allows an appropriate value to be defined to represent the sum of an empty sequence. For example, when summing a sequence of durations it would be appropriate to return a zerolength duration of the appropriate type. This argument is necessary because a system that does dynamic typing cannot distinguish "an empty sequence of integers", for example, from "an empty sequence of durations".
If the converted sequence contains exactly one value then that value is returned.
let $d1
:=
xs:yearMonthDuration("P20Y")
let $d2
:=
xs:yearMonthDuration("P10M")
let $seq1
:= ($d1, $d2)
let $seq3
:= (3, 4, 5)
The expression fn:sum(($d1, $d2))
returns
xs:yearMonthDuration("P20Y10M")
.
The expression fn:sum($seq1[. lt
xs:yearMonthDuration('P3M')], xs:yearMonthDuration('P0M'))
returns xs:yearMonthDuration("P0M")
.
The expression fn:sum($seq3)
returns
12
.
The expression fn:sum(())
returns
0
.
The expression fn:sum((),())
returns
()
.
The expression fn:sum((1 to 100)[. lt 0], 0)
returns 0
.
fn:sum(($d1, 9E1))
raises an error [err:FORG0006].
The expression fn:sum(($d1, $d2), "ein Augenblick")
returns xs:yearMonthDuration("P20Y10M")
. (There is
no requirement that the $zero
value should be the same
type as the items in $arg
, or even that it should
belong to a type that supports addition.).
Function  Meaning 

op:to 
Returns a sequence of consecutive integers in a given range. 
Returns a sequence of consecutive integers in a given range.
Defines the semantics of the "to" operator.
op:to
($firstval
as
xs:integer
,
$lastval
as
xs:integer
) as
xs:integer*
The function returns the sequence containing every
xs:integer
whose value is between the value of
$firstval
(inclusive) and the value of
$lastval
(inclusive), in monotonic increasing
order.
If the value of the first operand is greater than the value of the second, the function returns the empty sequence.
If the values of the two operands are equal, the function
returns a sequence containing a single xs:integer
equal to that value.
The expression 1 to 3
returns (1, 2,
3)
.
The expression 3 to 1
returns ()
.
The expression 5 to 5
returns 5
.
Returns the sequence of element nodes that have an
ID
value matching the value of one or more of the
IDREF
values supplied in $arg
.
fn:id
($arg
as
xs:string*
) as
element()*
fn:id
($arg
as
xs:string*
, $node
as
node()
) as
element()*
The function returns a sequence, in document order with
duplicates eliminated, containing every element node E
that satisfies all the following conditions:
E
is in the target document. The target document is
the document containing $node
, or the document
containing the context item (.
) if the second argument
is omitted. The behavior of the function if $node
is
omitted is exactly the same as if the context item had been passed
as $node
.
E
has an ID
value equal to one of the
candidate IDREF
values, where:
An element has an ID
value equal to V
if either or both of the following conditions are true:
The isid
property (See Section isid
Accessor^{DM30}.) of the element node is
true, and the typed value of the element node is equal to V under
the rules of the eq
operator using the Unicode
codepoint collation
(http://www.w3.org/2005/xpathfunctions/collation/codepoint
).
The element has an attribute node whose isid
property (See Section isid
Accessor^{DM30}.) is true and whose
typed value is equal to V
under the rules of the
eq
operator using the Unicode code point collation
(http://www.w3.org/2005/xpathfunctions/collation/codepoint
).
Each xs:string
in $arg
is parsed as if
it were of type IDREFS
, that is, each
xs:string
in $arg
is treated as a
whitespaceseparated sequence of tokens, each acting as an
IDREF
. These tokens are then included in the list of
candidate IDREF
s. If any of the tokens is not a
lexically valid IDREF
(that is, if it is not lexically
an xs:NCName
), it is ignored. Formally, the candidate
IDREF
values are the strings in the sequence given by
the expression:
for $s in $arg return fn:tokenize(fn:normalizespace($s), ' ')[. castable as xs:IDREF]
If several elements have the same ID
value, then
E
is the one that is first in document order.
If $node
, or the context item if the second
argument is omitted, is a node in a tree whose root is not a
document node [err:FODC0001] is raised.
If the second argument is the context item, or is omitted, the following errors may be raised: if there is no context item, [err:XPDY0002]^{XP}; if the context item is not a node [err:XPTY0004]^{XP}.
The effect of this function is anomalous in respect of element
nodes with the isid
property. For legacy reasons,
this function returns the element that has the isid
property, whereas it would be more appropriate to return its
parent, that being the element that is uniquely identified by the
ID. A new function elementwithid
is being introduced
with the desired behavior.
If the data model is constructed from an Infoset, an attribute
will have the isid
property if the corresponding
attribute in the Infoset had an attribute type of ID
:
typically this means the attribute was declared as an
ID
in a DTD.
If the data model is constructed from a PSVI, an element or
attribute will have the isid
property if its typed
value is a single atomic value of type xs:ID
or a type
derived by restriction from xs:ID
.
No error is raised in respect of a candidate IDREF
value that does not match the ID
of any element in the
document. If no candidate IDREF
value matches the
ID
value of any element, the function returns the
empty sequence.
It is not necessary that the supplied argument should have type
xs:IDREF
or xs:IDREFS
, or that it should
be derived from a node with the isidrefs
property.
An element may have more than one ID
value. This
can occur with synthetic data models or with data models
constructed from a PSVI where the element and one of its attributes
are both typed as xs:ID
.
If the source document is wellformed but not valid, it is
possible for two or more elements to have the same ID
value. In this situation, the function will select the first such
element.
It is also possible in a wellformed but invalid document to
have an element or attribute that has the isid
property but whose value does not conform to the lexical rules for
the xs:ID
type. Such a node will never be selected by
this function.
let $emp
:=
<employee xml:id="ID21256"> <empnr>E21256</empnr> <first>John</first> <last>Brown</last> </employee>
The expression id('ID21256')/name()
returns
employee
. (The xml:id
attribute has
the isid
property, so the employee element is
selected.).
The expression id('E21256')/name()
returns
empnr
. (Assuming the empnr
element is
given the type xs:ID
as a result of schema validation,
the element will have the isid
property and is
therefore selected. Note the difference from the behavior of
fn:elementwithid
.).
Returns the sequence of element nodes that have an
ID
value matching the value of one or more of the
IDREF
values supplied in $arg
.
fn:elementwithid
($arg
as
xs:string*
) as
element()*
fn:elementwithid
($arg
as
xs:string*
, $node
as
node()
) as
element()*
Note:
The effect of this function is identical to fn:id
in respect of elements that have an attribute with the
isid
property. However, it behaves differently in
respect of element nodes with the isid
property.
Whereas the fn:id
, for legacy
reasons, returns the element that has the isid
property, this parent returns the element identified by the ID,
which is the parent of the element having the isid
property.
The function returns a sequence, in document order with
duplicates eliminated, containing every element node E
that satisfies all the following conditions:
E
is in the target document. The target document is
the document containing $node
, or the document
containing the context item (.
) if the second argument
is omitted. The behavior of the function if $node
is
omitted is exactly the same as if the context item had been passed
as $node
.
E
has an ID
value equal to one of the
candidate IDREF
values, where:
An element has an ID
value equal to V
if either or both of the following conditions are true:
The element has an child element node whose isid
property (See Section isid
Accessor^{DM30}.) is true and whose
typed value is equal to V
under the rules of the
eq
operator using the Unicode code point collation
(http://www.w3.org/2005/xpathfunctions/collation/codepoint
).
The element has an attribute node whose isid
property (See Section isid
Accessor^{DM30}.) is true and whose
typed value is equal to V
under the rules of the
eq
operator using the Unicode code point collation
(http://www.w3.org/2005/xpathfunctions/collation/codepoint
).
Each xs:string
in $arg
is parsed as if
it were of type IDREFS
, that is, each
xs:string
in $arg
is treated as a
whitespaceseparated sequence of tokens, each acting as an
IDREF
. These tokens are then included in the list of
candidate IDREF
s. If any of the tokens is not a
lexically valid IDREF
(that is, if it is not lexically
an xs:NCName
), it is ignored. Formally, the candidate
IDREF
values are the strings in the sequence given by
the expression:
for $s in $arg return fn:tokenize(fn:normalizespace($s), ' ')[. castable as xs:IDREF]
If several elements have the same ID
value, then
E
is the one that is first in document order.
If $node
, or the context item if the second
argument is omitted, is a node in a tree whose root is not a
document node [err:FODC0001] is raised.
If the second argument is the context item, or is omitted, the following errors may be raised: if there is no context item, [err:XPDY0002]^{XP}; if the context item is not a node [err:XPTY0004]^{XP}.
This function is equivalent to the fn:id
function except when dealing with
IDvalued element nodes. Whereas the fn:id
function selects the element
containing the identifier, this function selects its parent.
If the data model is constructed from an Infoset, an attribute
will have the isid
property if the corresponding
attribute in the Infoset had an attribute type of ID
:
typically this means the attribute was declared as an
ID
in a DTD.
If the data model is constructed from a PSVI, an element or
attribute will have the isid
property if its typed
value is a single atomic value of type xs:ID
or a type
derived by restriction from xs:ID
.
No error is raised in respect of a candidate IDREF
value that does not match the ID
of any element in the
document. If no candidate IDREF
value matches the
ID
value of any element, the function returns the
empty sequence.
It is not necessary that the supplied argument should have type
xs:IDREF
or xs:IDREFS
, or that it should
be derived from a node with the isidrefs
property.
An element may have more than one ID
value. This
can occur with synthetic data models or with data models
constructed from a PSVI where the element and one of its attributes
are both typed as xs:ID
.
If the source document is wellformed but not valid, it is
possible for two or more elements to have the same ID
value. In this situation, the function will select the first such
element.
It is also possible in a wellformed but invalid document to
have an element or attribute that has the isid
property but whose value does not conform to the lexical rules for
the xs:ID
type. Such a node will never be selected by
this function.
let $emp
:=
<employee xml:id="ID21256"> <empnr>E21256</empnr> <first>John</first> <last>Brown</last> </employee>
The expression id('ID21256')/name()
returns
"employee"
. (The xml:id
attribute has
the isid
property, so the employee element is
selected.).
The expression id('E21256')/name()
returns
"employee"
. (Assuming the empnr
element is given the type xs:ID
as a result of schema
validation, the element will have the isid
property
and is therefore its parent is selected. Note the difference from
the behavior of fn:id
.).
Returns the sequence of element or attribute nodes with an
IDREF
value matching the value of one or more of the
ID
values supplied in $arg
.
fn:idref
($arg
as
xs:string*
) as
node()*
fn:idref
($arg
as
xs:string*
, $node
as
node()
) as
node()*
The function returns a sequence, in document order with
duplicates eliminated, containing every element or attribute node
$N
that satisfies all the following conditions:
$N
is in the target document. The target document
is the document containing $node
or the document
containing the context item (.
) if the second argument
is omitted. The behavior of the function if $node
is
omitted is exactly the same as if the context item had been passed
as $node
.
$N
has an IDREF
value equal to one of
the candidate ID
values, where:
A node $N
has an IDREF
value equal to
V
if both of the following conditions are true:
The isidrefs
property (see Section
isidrefs Accessor^{DM30}) of
$N
is true
.
The sequence
fn:tokenize(fn:normalizespace(fn:string($N)), ' ')
V
under the rules
of the eq
operator using the Unicode code point
collation
(http://www.w3.org/2005/xpathfunctions/collation/codepoint
).Each xs:string
in $arg
is parsed as if
it were of lexically of type xs:ID
. These
xs:string
s are then included in the list of candidate
xs:ID
s. If any of the strings in $arg
is
not a lexically valid xs:ID
(that is, if it is not
lexically an xs:NCName
), it is ignored. More formally,
the candidate ID
values are the strings in the
sequence:
$arg[. castable as xs:NCName]
If $node
, or the context item if the second
argument is omitted, is a node in a tree whose root is not a
document node [err:FODC0001] is raised.
If the second argument is the context item, or is omitted, the following errors may be raised: if there is no context item [err:XPDY0002]^{XP}; if the context item is not a node [err:XPTY0004]^{XP}.
An element or attribute typically acquires the
isidrefs
property by being validated against the
schema type xs:IDREF
or xs:IDREFS
, or
(for attributes only) by being described as of type
IDREF
or IDREFS
in a DTD.
No error is raised in respect of a candidate ID
value that does not match the IDREF
value of any
element or attribute in the document. If no candidate
ID
value matches the IDREF
value of any
element or attribute, the function returns the empty sequence.
It is possible for two or more nodes to have an
IDREF
value that matches a given candidate
ID
value. In this situation, the function will return
all such nodes. However, each matching node will be returned at
most once, regardless how many candidate ID
values it
matches.
It is possible in a wellformed but invalid document to have a
node whose isidrefs
property is true but that does
not conform to the lexical rules for the xs:IDREF
type. The effect of the above rules is that illformed candidate
ID
values and illformed IDREF
values are
ignored.
If the data model is constructed from a PSVI, the typed value of
a node that has the isidrefs
property will contain at
least one atomic value of type xs:IDREF
(or a type
derived by restriction from xs:IDREF
). It may also
contain atomic values of other types. These atomic values are
treated as candidate ID
values if their lexical form
is valid as an xs:NCName
, and they are ignored
otherwise.
This function returns a string that uniquely identifies a given node.
fn:generateid
() as
xs:string
fn:generateid
($arg
as
node()?
) as
xs:string
If the argument is omitted, it defaults to the context item
(.
). The behavior of the function if the argument is
omitted is exactly the same as if the context item had been passed
as the argument.
If the argument is the empty sequence, the result is the zerolength string.
In other cases, the function returns a string that uniquely identifies a given node.
The returned identifier must consist of ASCII alphanumeric characters and must start with an alphabetic character. Thus, the string is syntactically an XML name.
An implementation is free to generate an identifier in any convenient way provided that it always generates the same identifier for the same node and that different identifiers are always generated from different nodes. An implementation is under no obligation to generate the same identifiers each time a document is transformed or queried.
The following errors may be raised when $arg
is
omitted: if the context item is absent [err:XPDY0002]^{XP}; if
the context item is not a node [err:XPTY0004]^{XP}.
There is no guarantee that a generated unique identifier will be distinct from any unique IDs specified in the source document.
There is no inverse to this function; it is not directly
possible to find the node with a given generated ID. Of course, it
is possible to search a given sequence of nodes using an expression
such as $nodes[generateid()=$id]
.
It is advisable, but not required, for implementations to generate IDs that are distinct even when compared using a caseblind collation.
The primary use case for this function is to generate
hyperlinks. For example, when generating HTML, an anchor for a
given section $sect
can be generated by writing (in
either XSLT or XQuery):
<a name="{generateid($sect)}"/>
and a link to that section can then be produced with code such as:
see <a
href="#{generateid($sect)}">here</a>
Note that anchors generated in this way will not necessarily be the same each time a document is republished.
Retrieves a document using a URI supplied as an
xs:string
, and returns the corresponding document
node.
fn:doc
($uri
as
xs:string?
) as
documentnode()?
If $uri
is the empty sequence, the result is an
empty sequence.
If $uri
is a relative URI reference, it is resolved
relative to the value of the base URI property from the static
context. The resulting absolute URI is promoted to an
xs:string
.
If the Available documents described in Section 2.1.2 Dynamic Context^{XP} provides a mapping from this string to a document node, the function returns that document node.
The URI may include a fragment identifier.
By default, this function is ··. Two calls on this function return the same document node if the same URI Reference (after resolution to an absolute URI Reference) is supplied to both calls. Thus, the following expression (if it does not raise an error) will always be true:
doc("foo.xml") is doc("foo.xml")
However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of stability. The manner in which any such option is provided is implementationdefined. If the user has not selected such an option, a call of the function must either return a stable result or must raise an error: [err:FODC0003].
For detailed type semantics, see [Formal Semantics].
Note:
If $uri
is read from a source document, it is
generally appropriate to resolve it relative to the base URI
property of the relevant node in the source document. This can be
achieved by calling the fn:resolveuri
function, and
passing the resulting absolute URI as an argument to the
fn:doc
function.
If two calls to this function supply different absolute URI References as arguments, the same document node may be returned if the implementation can determine that the two arguments refer to the same resource.
By defining the semantics of this function in terms of a stringtodocumentnode mapping in the dynamic context, the specification is acknowledging that the results of this function are outside the purview of the language specification itself, and depend entirely on the runtime environment in which the expression is evaluated. This runtime environment includes not only an unpredictable collection of resources ("the web"), but configurable machinery for locating resources and turning their contents into document nodes within the XPath data model. Both the set of resources that are reachable, and the mechanisms by which those resources are parsed and validated, are ·implementation dependent·.
One possible processing model for this function is as follows. The resource identified by the URI Reference is retrieved. If the resource cannot be retrieved, an error is raised [err:FODC0002]. The data resulting from the retrieval action is then parsed as an XML document and a tree is constructed in accordance with the [XQuery and XPath Data Model (XDM) 3.0]. If the toplevel media type is known and is "text", the content is parsed in the same way as if the media type were text/xml; otherwise, it is parsed in the same way as if the media type were application/xml. If the contents cannot be parsed successfully, an error is raised [err:FODC0002]. Otherwise, the result of the function is the document node at the root of the resulting tree. This tree is then optionally validated against a schema.
Various aspects of this processing are ·implementationdefined·. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:
The set of URI schemes that the implementation recognizes is implementationdefined. Implementations may allow the mapping of URIs to resources to be configured by the user, using mechanisms such as catalogs or userwritten URI handlers.
The handling of nonXML media types is implementationdefined. Implementations may allow instances of the data model to be constructed from nonXML resources, under user control.
It is ·implementationdefined· whether DTD validation and/or schema validation is applied to the source document.
Implementations may provide userdefined error handling options that allow processing to continue following an error in retrieving a resource, or in parsing and validating its content. When errors have been handled in this way, the function may return either an empty sequence, or a fallback document provided by the error handler.
Implementations may provide user options that relax the requirement for the function to return stable results.
If $uri
is not a valid URI, an error
may be raised [err:FODC0005].
If the Available documents provides no mapping for the absolutized URI, an error is raised [err:FODC0002].
If the resource cannot be retrieved or cannot be parsed successfully as XML, an error is raised [err:FODC0002]
If the implementation is not able to guarantee that the result of the function will be stable, and the user has not indicated that an unstable result is acceptable, an error is raised [err:FODC0003].
The function returns true if and only if the function call
fn:doc($uri)
would return a
document node.
fn:docavailable
($uri
as
xs:string?
) as
xs:boolean
If $uri
is an empty sequence, this function returns
false
.
If a call on fn:doc($uri)
would return a document node, this function returns
true
.
If $uri
is not a valid URI according to the rules
applied by the implementation of fn:doc
, an error is raised [err:FODC0005].
Otherwise, this function returns false
.
If this function returns true
, then calling
fn:doc($uri)
within the same
·execution
scope· must return a document node.
However, if nonstable processing has been selected for the
fn:doc
function, this
guarantee is lost.
Returns a sequence of nodes representing a collection of documents indentified by a collection URI; or a default collection if no URI is supplied.
fn:collection
() as
node()*
fn:collection
($arg
as
xs:string?
) as
node()*
This function takes an xs:string
as argument and
returns a sequence of nodes obtained by interpreting
$arg
as an xs:anyURI
and resolving it
according to the mapping specified in Available collections
described in
Section C.2 Dynamic Context
Components^{XP}.
If Available collections provides a mapping from this string to a sequence of nodes, the function returns that sequence. If Available collections maps the string to an empty sequence, then the function returns an empty sequence.
If $arg
is not specified, the function returns the
sequence of the nodes in the default collection in the dynamic
context. See
Section C.2 Dynamic Context
Components^{XP}.
If the value of $arg
is a relative
xs:anyURI
, it is resolved against the value of the
baseURI property from the static context.
If $arg
is the empty sequence, the function behaves
as if it had been called without an argument. See above.
By default, this function is ··. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of stability. The manner in which any such option is provided is ·implementationdefined·. If the user has not selected such an option, a call to this function must either return a stable result or must raise an error: [err:FODC0003].
There is no requirement that the returned nodes should be in document order, nor is there a requirement that the result should contain no duplicates.
For detailed type semantics, see [Formal Semantics].
If no URI is supplied and the value of the default collection is absent, an error is raised [err:FODC0002].
If Available collections provides no mapping for the absolutized URI, an error is raised [err:FODC0004]
If $arg
is not a valid xs:anyURI
, an
error is raised [err:FODC0004].
This function provides a facility for users to work with a
collection of documents which may be contained in a directory or
rows of a Relational table or other implementationspecific
construct. An implementation may also use external variables to
identify external resources, but fn:collection
provides functionality not provided by external variables.
Specifying resources using URIs is useful because URIs are dynamic,
can be parameterized, and do not rely on an external
environment.
Returns a sequence of xs:anyURI
values representing
the document URIs of the documents in a collection.
fn:uricollection
() as
xs:anyURI*
fn:uricollection
($arg
as
xs:string?
) as
xs:anyURI*
A collection, as returned by the fn:collection
function, is in general a sequence of nodes. Some of these nodes
may be document nodes, and some of these document nodes may have a
nonempty document URI, accessible using the
fn:documenturi
function. The
fn:uricollection
function returns a sequence of URIs,
being the document URIs of those nodes in the collection that are
document nodes and that have a document URI (other nodes in the
collection are ignored). That is, in the absence of errors,
fn:uricollection(X)
returns the same set of URIs as
fn:collection(X)/fn:documenturi()
,
though not necessarily in the same order.
The purpose in providing the function, however, is to allow the
URIs of the documents in a collection to be retrieved without
incurring the cost (which might be significant in some
implementations) of dereferencing the URIs to obtain the actual
nodes. Where required, the returned URIs can then be dereferenced
by calling the fn:doc
function.
The zeroargument form of the function returns the document URIs of the document nodes in the default collection.
The singleargument form returns the document URIs of the document nodes in the collection with a given collection URI. If the value of the argument is an empty sequence, the action is as for the zeroargument form of the function. If the argument is a relative URI reference, it is resolved against the base URI property of the static context.
There is no requirement that the nodes in a collection should all be distinct, and therefore no requirement that the URIs in the result of this function should all be distinct.
If no URI is supplied and the value of the default collection is absent, an error is raised [err:FODC0002].
If Available collections provides no mapping for the absolutized URI, an error is raised [err:FODC0004]
If $arg
is not a valid xs:anyURI
, an
error is raised [err:FODC0004].
There are several reasons it might be appriopriate to retrieve the URIs of the documents in a collection without retrieving the documents themselves. For example:
In XSLT it allows the documents to be processed in streaming
mode using the xsl:stream
instruction.
It allows recovery from failures to read, parse, or validate
individual documents, by calling the fn:doc
function within the scope of
try/catch.
It allows selection of which documents to read based on their
URI, for example they can be filtered to select those whose URIs
end in .xml
.
However, there may be collections that cannot be processed in this way: specifically, those that contain nodes other than document nodes, and those that contain document nodes having no document URI.
The fn:unparsedtext
function reads an external
resource (for example, a file) and returns its contents as a
string.
fn:unparsedtext
($href
as
xs:string?
) as
xs:string?
fn:unparsedtext
($href
as
xs:string?
,
$encoding
as
xs:string
) as
xs:string?
The $href
argument must be a
string in the form of a URI reference, which must
contain no fragment identifier, and must identify
a resource that can be read as text. If the URI is a relative URI
reference, then it is resolved relative to the base URI from the
static context.
If the value of the $href
argument is an empty
sequence, the function returns an empty sequence.
The $encoding
argument, if present, is the name of
an encoding. The values for this attribute follow the same rules as
for the encoding
attribute in an XML declaration. The
only values which every ·implementation· is required to recognize are
utf8
and utf16
.
The encoding of the external resource is determined as follows:
external encoding information is used if available, otherwise
if the media type of the resource is text/xml
or
application/xml
(see [RFC
2376]), or if it matches the conventions
text/*+xml
or application/*+xml
(see
[RFC 3023] and/or its successors), then the
encoding is recognized as specified in [RECxml], otherwise
the value of the $encoding
argument is used if
present, otherwise
the processor may use ·implementationdefined· heuristics to determine the likely encoding, otherwise
UTF8 is assumed.
The result of the function is a string containing the text of the resource retrieved using the URI.
If it is appropriate to use a base URI other than the static
base URI (for example, when resolving a relative URI reference read
from a source document) then it is advisable to resolve the
relative URI reference using the fn:resolveuri
function before
passing it to the fn:unparsedtext
function.
The rules for determining the encoding are chosen for consistency with [XML Inclusions (XInclude) Version 1.0 (Second Edition)]. Files with an XML media type are treated specially because there are use cases for this function where the retrieved text is to be included as unparsed XML within a CDATA section of a containing document, and because processors are likely to be able to reuse the code that performs encoding detection for XML external entities.
If the text file contains characters such as <
and &
, these will typically be output as
<
and &
when the string
serialized as XML or HTML. If these characters actually represent
markup (for example, if the text file contains HTML), then an XSLT
stylesheet can attempt to write them as markup to the output file
using the disableoutputescaping
attribute of the
xsl:valueof
instruction. Note, however, that XSLT
implementations are not required to support this feature.
Copying Unparsed HTML Boilerplate
This example attempts to read an HTML file and copy it, as HTML, to the serialized output file:
<xsl:output method="html"/> <xsl:template match="/"> <xsl:valueof select="unparsedtext('header.html', 'iso88591')" disableoutputescaping="yes"/> <xsl:applytemplates/> <xsl:valueof select="unparsedtext('footer.html', 'iso88591')" disableoutputescaping="yes"/> </xsl:template>
The fn:unparsedtextlines
function reads an
external resource (for example, a file) and returns its contents as
a sequence of strings, one for each line of text in the file.
fn:unparsedtextlines
($href
as
xs:string?
) as
xs:string*
fn:unparsedtextlines ( 
$href 
as xs:string? , 
$encoding 
as xs:string ) as xs:string* 
The unparsedtextlines
function reads an external
resource (for example, a file) and returns its contents as a
sequence of strings, separated at newline boundaries.
The result of the singleargument function is the same as the
result of the expression fn:tokenize(fn:unparsedtext($href),
'\r\n\r\n')[not(position()=last() and .='')]
. The
result of the twoargument function is the same as the result of
the expression fn:tokenize(fn:unparsedtext($href,
$encoding), '\r\n\r\n'))[not(position()=last() and
.='')]
.
The result is a thus a sequence of strings containing the text of the resource retrieved using the URI, each string representing one line of text. Lines are separated by one of the sequences x0A, x0D, or x0Dx0A. The characters representing the newline are not included in the returned strings. If there are two adjacent newline sequences, a zerolength string will be returned to represent the empty line; but if the external resource ends with a newline sequence, no zerolength string will be returned as the last item in the result.
Error conditions are the same as for the fn:unparsedtext
function.
See the notes for fn:unparsedtext
.
Because errors in evaluating the fn:unparsedtext
function are nonrecoverable, these two functions are provided to
allow an application to determine whether a call with particular
arguments would succeed.
fn:unparsedtextavailable
($href
as
xs:string?
) as
xs:boolean
fn:unparsedtextavailable ( 
$href 
as xs:string? , 
$encoding 
as xs:string ) as xs:boolean 
The fn:unparsedtextavailable
function determines
whether a call on the fn:unparsedtext
function with
identical arguments would return a string.
If the first argument is an empty sequence, the function returns false. If the second argument is an empty sequence, the function behaves as if the second argument were omitted.
In other cases, the function returns true if a call on
fn:unparsedtext
with the same arguments would
succeed, and false if a call on fn:unparsedtext
with
the same arguments would fail with a nonrecoverable dynamic
error.
The functions fn:unparsedtext
and
fn:unparsedtextavailable
have the same requirement
for stability^{FO}
as the functions fn:doc
and
fn:docavailable
.
This means that unless the user has explicitly stated a requirement
for a reduced level of stability, either of these functions if
called twice with the same arguments during the course of a
transformation must return the same results each
time; moreover, the results of a call on
fn:unparsedtextavailable
must be
consistent with the results of a subsequent call on
unparsedtext
with the same arguments.
This requires that the unparsedtextavailable
function should actually attempt to read the resource identified by
the URI, and check that it is correctly encoded and contains no
characters that are invalid in XML. Implementations may avoid the
cost of repeating these checks for example by caching the validated
contents of the resource, to anticipate a subsequent call on the
unparsedtext
or
unparsedtextlines
function. Alternatively,
implementations may be able to rewrite an expression such as
if (unparsedtextavailable(A)) then unparsedtext(A) else
...
to generate a single call internally.
Returns the value of a system environment variable, if it exists.
fn:environmentvariable
($name
as
xs:string
) as
xs:string?
The set of available environment variables is a set of (name, value) pairs forming part of the dynamic context, in which the name is unique within the set of pairs. The name and value are arbitrary strings.
If the $name
argument matches the name of one of
these pairs, the function returns the corresponding value.
If there is no environment variable with a matching name, the function returns the empty sequence.
The collation used for matching names is ·implementation dependent·, but must be the same as the collation used to ensure that the names of all environment variables are unique.
On many platforms, the term "environment variable" has a natural meaning in terms of facilities provided by the operating system. This interpretation of the concept does not exclude other interpretations, such as a mapping to a set of configuration parameters in a database system.
Environment variable names are usually case sensitive. Names are
usually of the form (letter_) (letter_digit)*
, but
this varies by platform.
On some platforms, there may sometimes be multiple environment names with the same name; in this case, it is implementationdependent as to which is returned; see for example [POSIX.12008] (Chapter 8, Environment Variables).
Calls to external functions, or other external events, may
result in changes to environment variables: both to the set of
available variables and to their values. Calling
environmentvariable()
multiple times with the same
name may or may not reflect such changes, depending on the
implementation.
Security advice: Queries from untrusted sources should not be
permitted unrestricted access to environment variables. For
example, the name of the account under which the query is running
may be useful information to a wouldbe intruder. An implementation
may therefore choose to restrict access to the environment, or may
provide a facility to make fn:environmentvariable
always return the empty sequence.
Returns a list of environment variable names that are suitable
for passing to fn:environmentvariable
,
as a (possibly empty) sequence of strings.
fn:availableenvironmentvariables
() as
xs:string*
The function returns a list of strings, containing no duplicates.
It is intended that the strings in this list should be suitable
for passing to fn:environmentvariable
.
However, since external events can cause the set of available
environment variables to change at any time, there is no guarantee
that this represents precisely the environment variables available
in the dynamic context at any point in time.
Calls to external functions may result in changes to the set of environment variables, including creating new variables or deleting existing ones, as well as changing values.
See also the note on security under the definition of the
fn:environmentvariable
function. If access to environment variables has been disabled,
fn:availableenvironmentvariables
always returns the
empty sequence.
This function takes as input an XML document represented as a string, and returns the document node at the root of an XDM tree representing the parsed document.
fn:parsexml
($arg
as
xs:string?
) as
documentnode(element(*, xs:untyped))
fn:parsexml ( 
$arg 
as xs:string? , 
$baseURI 
as xs:string ) as documentnode(element(*, xs:untyped)) 
If $arg
is the empty sequence, the function returns
the empty sequence.
Schema validation is not invoked, which means that the nodes in the returned document will all be untyped.
The precise process used to construct the XDM instance is implementationdefined. In particular, it is implementationdefined whether DTD validation is invoked, and it is implementationdefined whether an XML 1.0 or XML 1.1 parser is used.
If the second argument is present then it provides a URI which
will be used as the base URI of the document. This serves both as
the base URI used by the XML parser to resolve relative entity
references within the document, and as the base URI of the document
node that is returned. If the second argument is omitted, then the
static base URI of the fn:parsexml
function call is
used.
The function is not ·stable·: that is, if the function is called twice with the same arguments, it is ·implementationdependent· whether the same node is returned on both occasions.
A dynamic error [err:FODC0006] is raised if the content of
$arg
is not a wellformed and namespacewellformed
XML document.
If DTDbased validation is carried out, then a dynamic error
[err:FODC0006] is
raised if the content of $arg
is not valid against its
DTD.
A dynamic error [err:FODC0007] is raised if the content of
$baseURI
is not a valid absolute URI.
Since the XML document is presented to the parser as a string, rather than as a sequence of octets, the encoding specified within the XML declaration has no meaning. If the XML parser accepts input only in the form of a sequence of octets, then the processor must ensure that the string is encoded as octets in a way that is consistent with rules used by the XML parser to detect the encoding.
The primary use case for this function is to handle input
documents that contain nested XML documents embedded within CDATA
sections. Since the content of the CDATA section are exposed as
text, the receiving query or stylesheet may pass this text to the
fn:parsexml
function to create a tree representation
of the nested document.
Similarly, nested XML within comments is sometimes encountered, and lexical XML is sometimes returned by extension functions, for example, functions that access web services or read from databases.
A use case arises in XSLT where there is a need to preprocess an
input document before parsing. For example, an application might
wish to edit the document to remove its DOCTYPE declaration. This
can be done by reading the raw text using the fn:unparsedtext
function,
editing the resulting string, and then passing it to the
fn:parsexml
function.
The expression
fn:parsexml("<alpha>abcd</alpha>")
returns a newly created document node, having an alpha
element as its only child; the alpha
element in turn
is the parent of a text node whose string value is
"abcd"
.
This function serializes the supplied input
sequence $arg
as described in [XSLT and XQuery Serialization
3.0], returning the serialized representation of the
sequence as a string.
fn:serialize
($arg
as
item()*
) as
xs:string
fn:serialize ( 
$arg 
as item()* , 
$params 
as element(output:serializationparameters)? ) as xs:string 
The value of $arg
acts as the input sequence to the
serialization process, which starts with sequence
normalization.
The singleargument version of this function has the same effect
as the twoargument version called with $params
set to
an empty sequence. This in turn is the same as the effect of
passing an output:serializationparameters
element
with no child elements.
The $params
argument is used to identify a set of
serialization parameters. These are supplied in the form of an
output:serializationparameters
element, having the
format described in
Section Setting Serialization Parameters by Means of a Data Model
Instance^{SER30}.
The final stage of serialization, that is, encoding, is skipped. If the serializer does not allow this phase to be skipped, then the sequence of octets returned by the serializer is decoded into a string by reversing the character encoding performed in the final stage.
The serialization process will raise an error if
$arg
is an attribute or namespace node.
If any serialization error occurs, including the detection of an
invalid value for a serialization parameter, this results in the
fn:serialize
call failing with a dynamic error.
One use case for this function arises when there is a need to
construct an XML document containing nested XML documents within a
CDATA section (or on occasions within a comment). See fn:parsexml
for further
details.
Another use case arises when there is a need to call an extension function that expects a lexical XML document as input.
There are also use cases where the application wants to
postprocess the output of a query or transformation, for example
by adding an internal DTD subset, or by inserting proprietary
markup delimiters such as the <% ... %>
used by
some templating languages.
Given the output parameters:
let $params
:=
<output:serializationparameters> <output:omitxmldeclaration>yes</output:omitxmldeclaration> </output:serializationparameters>
let $data
:=
<a b='3'/>
The following call might produce the output shown:
The expression fn:serialize($data, $params)
returns
'<a b="3"/>'
.
The following functions are defined to obtain information from the dynamic context.
Function  Meaning 

fn:position 
Returns the context position from the dynamic context. 
fn:last 
Returns the context size from the dynamic context. 
fn:currentdateTime 
Returns the current date and time (with timezone). 
fn:currentdate 
Returns the current date. 
fn:currenttime 
Returns the current time. 
fn:implicittimezone 
Returns the value of the implicit timezone property from the dynamic context. 
fn:defaultcollation 
Returns the value of the default collation property from the static context. 
fn:staticbaseuri 
Returns the value of the Base URI property from the static context. 
Returns the context position from the dynamic context.
fn:position
() as
xs:integer
Returns the context position from the dynamic context. (See Section C.2 Dynamic Context Components^{XP}.)
If the context item is absent, an error is raised: [err:XPDY0002]^{XP}.
Returns the context size from the dynamic context.
fn:last
() as
xs:integer
Returns the context size from the dynamic context. (See Section C.2 Dynamic Context Components^{XP}.)
If the context item is absent, an error is raised: [err:XPDY0002]^{XP}.
The expression (1 to 20)[fn:last()  1]
returns
19
.
Returns the current date and time (with timezone).
fn:currentdateTime
() as
xs:dateTimeStamp
Returns the current dateTime (with timezone) from the dynamic
context. (See
Section C.2 Dynamic Context
Components^{XP}.) This is an
xs:dateTime
that is current at some time during the
evaluation of a query or transformation in which
fn:currentdateTime
is executed.
This function is ··.
The precise instant during the query or transformation represented
by the value of fn:currentdateTime()
is ·implementation dependent·.
If the implementation supports data types from XSD 1.1 then the
returned value will be an instance of
xs:dateTimeStamp
. Otherwise, the only guarantees are
that it will be an instance of xs:dateTime
and will
have a timezone component.
The returned xs:dateTime
will always have an
associated timezone, which will always be the same as the implicit
timezone in the dynamic context
fn:currentdateTime()
returns an
xs:dateTimeStamp
corresponding to the current date and
time. For example, a call of fn:currentdateTime()
might return 20040512T18:17:15.125Z
corresponding to
the current time on May 12, 2004 in timezone Z
.
Returns the current date.
fn:currentdate
() as
xs:date
Returns xs:date(fn:currentdateTime())
. This is an
xs:date
(with timezone) that is current at some time
during the evaluation of a query or transformation in which
fn:currentdate
is executed.
This function is ··.
The precise instant during the query or transformation represented
by the value of fn:currentdate
is ·implementation dependent·.
The returned date will always have an associated timezone, which will always be the same as the implicit timezone in the dynamic context
fn:currentdate()
returns an xs:date
corresponding to the current date. For example, a call of
fn:currentdate()
might return
20040512+01:00
.
Returns the current time.
fn:currenttime
() as
xs:time
Returns xs:time(fn:currentdateTime())
. This is an
xs:time
(with timezone) that is current at some time
during the evaluation of a query or transformation in which
fn:currenttime
is executed.
This function is ··.
The precise instant during the query or transformation represented
by the value of fn:currenttime()
is ·implementation dependent·.
The returned time will always have an associated timezone, which will always be the same as the implicit timezone in the dynamic context
fn:currenttime()
returns an xs:time
corresponding to the current time. For example, a call of
fn:currenttime()
might return
23:17:00.00005:00
.
Returns the value of the implicit timezone property from the dynamic context.
fn:implicittimezone
() as
xs:dayTimeDuration
Returns the value of the implicit timezone property from the dynamic context. Components of the dynamic context are discussed in Section C.2 Dynamic Context Components^{XP}.
Returns the value of the default collation property from the static context.
fn:defaultcollation
() as
xs:string
Returns the value of the default collation property from the static context. Components of the static context are discussed in Section C.1 Static Context Components^{XP}.
The default collation property can never be absent. If it is not
explicitly defined, a system defined default can be invoked. If
this is not provided, the Unicode codepoint collation
(http://www.w3.org/2005/xpathfunctions/collation/codepoint
)
is used.
Returns the value of the Base URI property from the static context.
fn:staticbaseuri
() as
xs:anyURI?
The function returns the value of the Base URI property from the static context. If the Base URI property is absent, the empty sequence is returned.
Components of the static context are discussed in Section C.1 Static Context Components^{XP} .
The following functions operate on function items, that is, values referring to a function.
Function  Meaning 

fn:functionname 
Returns the name of the function identified by a function item. 
fn:functionarity 
Returns the arity of the function identified by a function item. 
Returns the name of the function identified by a function item.
fn:functionname
($func
as
function(*)
) as
xs:QName?
If $func
refers to a named function,
fn:functionname($func)
returns the name of that
function.
Otherwise ($func
refers to an anonymous function),
fn:functionname($func)
returns an empty sequence.
The prefix part of the returned QName is ·implementation dependent·.
The expression fn:functionname(fn:contains#2)
returns fn:QName("http://www.w3.org/2005/xpathfunctions",
"fn:contains")
.
The expression
fn:functionname(function($node){count($node/*)})
returns ()
.
Returns the arity of the function identified by a function item.
fn:functionarity
($func
as
function(*)
) as
xs:integer
The fn:functionarity
function returns the arity
(number of arguments) of the function identified by
$func
.
The expression fn:functionarity(fn:contains#2)
returns 2
.
The expression
fn:functionarity(function($node){name($node)})
returns 1
.
The following functions take function items as an argument.
Function  Meaning 

fn:map 
Applies the function item $f to every item from the sequence $seq in turn, returning the concatenation of the resulting sequences in order. 
fn:filter 
Returns those items from the sequence $seq for which the supplied function $f returns true. 
fn:foldleft 
Processes the supplied sequence from left to right, applying the supplied function repeatedly to each item in turn, together with an accumulated result value. 
fn:foldright 
Processes the supplied sequence from right to left, applying the supplied function repeatedly to each item in turn, together with an accumulated result value. 
fn:mappairs 
Applies the function item $f to successive pairs of items taken one from $seq1 and one from $seq2, returning the concatenation of the resulting sequences in order. 
Applies the function item $f to every item from the sequence $seq in turn, returning the concatenation of the resulting sequences in order.
fn:map
($f
as
function(item()) as
item()*
, $seq
as
item()*
) as
item()*
The effect of the function is equivalent to the following implementation in XQuery:
declare function fn:map($f, $seq) { if (fn:empty($seq)) then () else $f(fn:head($seq)), fn:map($f, fn:tail($seq)) };
or its equivalent in XSLT:
<xsl:function name="fn:map"> <xsl:param name="f"/> <xsl:param name="seq/> <xsl:if test="fn:exists($seq)"> <xsl:sequence select="$f(fn:head($seq)), fn:map($f, fn:tail($seq))"/> </xsl:if> </xsl:function>
The function call fn:map($F, $SEQ)
is equivalent to
the expression for $i in $SEQ return $F($i)
,
assuming that ordering mode is ordered
.
The expression fn:map(function($a) { $a * $a }, 1 to
5)
returns (1, 4, 9, 16, 25)
.
The expression fn:map(fn:stringtocodepoints#1, ("john",
"jane"))
returns (106, 111, 104, 110, 106, 97, 110,
101)
.
The expression fn:map(xs:int#1, ("23", "29"))
returns (23, 29)
.
Returns those items from the sequence $seq for which the supplied function $f returns true.
fn:filter
($f
as
function(item()) as
xs:boolean
, $seq
as
item()*
) as
item()*
The effect of the function is equivalent to the following implementation in XQuery:
declare function fn:filter( $f as function(item()) as xs:boolean, $seq as item()*) as item()* { if (fn:empty($seq)) then () else ( fn:head($seq)[$f(.) eq fn:true()], fn:filter($f, fn:tail($seq)) ) };
or its equivalent in XSLT:
<xsl:function name="fn:filter" as="item()*"> <xsl:param name="f" as="function(item()) as xs:boolean"/> <xsl:param name="seq" as="item()*"/> <xsl:if test="fn:exists($seq)"> <xsl:sequence select="fn:head($seq)[$f(.) eq fn:true()], fn:filter($f, fn:tail($seq))"/> </xsl:if> </xsl:function>
As a consequence of the function signature and the function
calling rules, a type error occurs if the supplied function
$f returns anything other than a single
xs:boolean
item; there is no conversion to an
effective boolean value.
The function call fn:filter($F, $SEQ)
has a very
similar effect to the expression $SEQ[$F(.)]
. There
are some differences, however. In the case of
fn:filter
, the function $F
is required to
return a boolean; there is no special treatment for numeric
predicate values, and no conversion to an effective boolean value.
Also, with a filter expression $SEQ[$F(.)]
, the focus
within the predicate is different from that outside; this means
that the use of of a contextsensitive function such as fn:lang#1
will give different results
in the two cases.
The expression fn:filter(function($a) {$a mod 2 = 0}, 1 to
10)
returns (2, 4, 6, 8, 10)
.
Processes the supplied sequence from left to right, applying the supplied function repeatedly to each item in turn, together with an accumulated result value.
fn:foldleft ( 
$f 
as function(item()*,
item()) as item()* , 
$zero 
as item()* , 

$seq 
as item()* ) as item()* 
The effect of the function is equivalent to the following implementation in XQuery:
declare function fn:foldleft( $f as function(item()*, item()) as item()*, $zero as item()*, $seq as item()*) as item()* { if (fn:empty($seq)) then $zero else fn:foldleft($f, $f($zero, fn:head($seq)), fn:tail($seq)) };
or its equivalent in XSLT:
<xsl:function name="fn:foldleft" as="item()*"> <xsl:param name="f" as="function(item()*, item()) as item()*"/> <xsl:param name="zero" as="item()*"/> <xsl:param name="seq" as="item()*"/> <xsl:choose> <xsl:when test="fn:empty($seq)"> <xsl:sequence select="$zero"/> </xsl:when> <xsl:otherwise> <xsl:sequence select="fn:foldleft($f, $f($zero, fn:head($seq)), fn:tail($seq))"/> </xsl:otherwise> </xsl:choose> </xsl:function>
As a consequence of the function signature and the function calling rules, a type error occurs if the supplied function $f cannot be applied to two arguments, where the first argument is either the value of $zero or the result of a previous application of $f, and the second is $seq or any trailing subsequence of $seq.
This operation is often referred to in the functional programming literature as "folding" or "reducing" a sequence. It takes a function that operates on a pair of values, and applies it repeatedly, with an accumulated result as the first argument, and the next item in the sequence as the second argument. The accumulated result is initially set to the value of the $zero argument, which is conventionally a value (such as zero in the case of addition, one in the case of multiplication, or a zerolength string in the case of string concatenation) that causes the function to return the value of the other argument unchanged.
The expression fn:foldleft(function($a, $b) { $a + $b },
0, 1 to 5)
returns 15
. (This returns the
sum of the items in the sequence).
The expression fn:foldleft(function($a, $b) { $a * $b },
1, (2,3,5,7))
returns 210
. (This returns
the product of the items in the sequence).
The expression fn:foldleft(function($a, $b) { $a or $b },
false(), (true(), false(), false()))
returns
true()
. (This returns true if any item in the
sequence has an effective boolean value of true).
The expression fn:foldleft(function($a, $b) { $a and $b
}, false(), (true(), false(), false()))
returns
false()
. (This returns true only if every item in
the sequence has an effective boolean value of true).
The expression fn:foldleft(function($a, $b) {($b, $a)},
(), 1 to 5)
returns "(5,4,3,2,1)"
. (This
reverses the order of the items in a sequence).
The expression fn:foldleft(fn:concat(?, ".", ?), "", 1 to
5)
returns ".1.2.3.4.5"
.
The expression fn:foldleft(fn:concat("$f(", ?, ", ", ?,
")"), "$zero", 1 to 5)
returns "$f($f($f($f($f($zero,
1), 2), 3), 4), 5)"
.
Processes the supplied sequence from right to left, applying the supplied function repeatedly to each item in turn, together with an accumulated result value.
fn:foldright ( 
$f 
as function(item(),
item()*) as item()* , 
$zero 
as item()* , 

$seq 
as item()* ) as item()* 
The effect of the function is equivalent to the following implementation in XQuery:
declare function fn:foldright( $f as function(item(), item()*) as item()*, $zero as item()*, $seq as item()*) as item()* { if (fn:empty($seq)) then $zero else $f(fn:head($seq), fn:foldright($f, $zero, fn:tail($seq))) };
or its equivalent in XSLT:
<xsl:function name="fn:foldright" as="item()*"> <xsl:param name="f" as="function(item(), item()*) as item()*"/> <xsl:param name="zero" as="item()*"/> <xsl:param name="seq" as="item()*"/> <xsl:choose> <xsl:when test="fn:empty($seq)"> <xsl:sequence select="$zero"/> </xsl:when> <xsl:otherwise> <xsl:sequence select="$f(fn:head($seq), fn:foldright($f, $zero, fn:tail($seq))"/> </xsl:otherwise> </xsl:choose> </xsl:function>
As a consequence of the function signature and the function calling rules, a type error occurs if the supplied function $f cannot be applied to two arguments, where the first argument is any item in the sequence $seq, and the second is either the value of $zero or the result of a previous application of $f.
This operation is often referred to in the functional programming literature as "folding" or "reducing" a sequence. It takes a function that operates on a pair of values, and applies it repeatedly, with the next item in the sequence as the first argument, and the result of processing the remainder of the sequence as the second argument. The accumulated result is initially set to the value of the $zero argument, which is conventionally a value (such as zero in the case of addition, one in the case of multiplication, or a zerolength string in the case of string concatenation) that causes the function to return the value of the other argument unchanged.
In cases where the function performs an associative operation on
its two arguments (such as addition or multiplication),
fn:foldright
produces the same result as fn:foldleft
.
The expression fn:foldright(function($a, $b) { $a + $b },
0, 1 to 5)
returns 15
. (This returns the
sum of the items in the sequence).
The expression fn:foldright(fn:concat(?, ".", ?), "", 1
to 5)
returns "1.2.3.4.5."
.
The expression fn:foldright(concat("$f(", ?, ", ", ?,
")"), "$zero", 1 to 5)
returns "$f(1, $f(2, $f(3,
$f(4, $f(5, $zero)))))"
.
Applies the function item $f to successive pairs of items taken one from $seq1 and one from $seq2, returning the concatenation of the resulting sequences in order.
fn:mappairs ( 
$f 
as function(item(),
item()) as item()* , 
$seq1 
as item()* , 

$seq2 
as item()* ) as item()* 
The effect of the function is equivalent to the following implementation in XQuery:
declare function fn:mappairs($f, $seq1, $seq2) { if(fn:exists($seq1) and fn:exists($seq2)) then ( $f(fn:head($seq1), fn:head($seq2)), fn:mappairs($f, fn:tail($seq1), fn:tail($seq2)) ) else () };
or its equivalent in XSLT:
<xsl:function name="fn:mappairs"> <xsl:param name="f"/> <xsl:param name="seq1/> <xsl:param name="seq2/> <xsl:if test="fn:exists($seq1) and fn:exists($seq2"> <xsl:sequence select="$f(fn:head($seq1), fn:head($seq2))"/> <xsl:sequence select="fn:mappairs($f, fn:tail($seq1), fn:tail($seq2))"/> </xsl:if> </xsl:function>
The expression fn:mappairs(concat#2, ("a", "b", "c"),
("x", "y", "z"))
returns ("ax", "by",
"cz")
.
The expression fn:mappairs(function($a, $b){10*$a + $b},
1 to 5, 1 to 5)
returns (11, 22, 33, 44,
55)
.
Every builtin 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
Types^{DM30} and the two derived types
xs:yearMonthDuration
and
xs:dayTimeDuration
defined in Section
Types^{DM30} also have associated
constructor functions. Implementations may
additionally provide constructor functions for new data types
introduced in [XML Schema 1.1 Part 2:
Datatypes].
A constructor function is not defined for
xs:anyAtomicType
as there are no atomic values with
type annotation xs:anyAtomicType
at runtime, although
this can be a statically inferred type. A constructor function is
not defined for xs:NOTATION
since it is defined as an
abstract type in [XML Schema Part 2:
Datatypes Second Edition]. If the static context (See Section 2.1.1 Static
Context^{XP}) contains a type derived
from xs:NOTATION
then a constructor function is
defined for it. See 17.3 Constructor
functions for userdefined 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 not in the lexical
space of the datatype to be constructed, and cannot be converted to
a value in the value space of the datatype under the rules in this
specification, then an error is raised [err:FORG0001].
The semantics of the constructor function "
xs:TYPE(arg)
" are identical to the semantics of "
arg
cast as xs:TYPE?
". See 18 Casting.
If the argument to a constructor function is a literal, the result of the function may be evaluated statically; if an error is found during such evaluation, it may be reported as a static error.
Special rules apply to constructor functions for
xs:QName
and types derived from xs:QName
and xs:NOTATION
. See 17.2 Constructor functions for
xs:QName and xs:NOTATION.
The following constructor functions for the builtin 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 should return negative zero for
xs:float("0.0E0")
. But because [XML Schema Part 2: Datatypes Second Edition]
does not distinguish between the values positive zero and negative
zero. implementations ·may· return positive zero in this case.
xs:double
($arg
as
xs:anyAtomicType?
) as
xs:double?
Implementations should return negative zero for
xs:double("0.0E0")
. But because [XML Schema Part 2: Datatypes Second Edition]
does not distinguish between the values positive zero and negative
zero. implementations ·may· return positive zero in this case.
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 17.2 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 18.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?
xs:dateTimeStamp
($arg
as
xs:anyAtomicType?
) as
xs:dateTimeStamp?
Available only if the implementation supports XSD 1.1.
Special rules apply to constructor functions for the types
xs:QName
and xs:NOTATION
, for two
reasons:
Values cannot belong directly to the type
xs:NOTATION
, only to its subtypes.
The lexical representation of these types uses namespace prefixes, whose meaning is contextdependent.
These constraints result in the following rules:
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 expandedQName 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
Terminology^{DM30}, the supplied prefix
is retained as part of the expandedQName value.
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 pseudofunction, which is always evaluated
statically. It is also permitted for these constructors and casts
to take a dynamicallysupplied argument in the normal manner, but
as the casting table (see 18.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.
For every userdefined type in the static context (See Section 2.1.1 Static Context^{XP}) whose variety is atomic or union, there is a constructor function whose name is the same as the name of the type and whose effect is to create a value of that type from the supplied argument. The rules for constructing userdefined types are defined in the same way as the rules for constructing builtin derived types discussed in 17.1 Constructor functions for XML Schema builtin types.
Special rules apply to constructor functions for types derived
from xs:QName
and xs:NOTATION
. See
17.2 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 following constructor function is available to users:
my:hatSize
($arg
as
xs:anyAtomicType?
) as
my:hatSize?
To construct an instance of a userdefined 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 userdefined 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)
Constructor functions and cast expressions accept an expression
and return a value of a given type. They both convert a source
value, SV, of a source type, ST, to a target
value, TV, of the given target type, TT, with
identical semantics and different syntax. The name of the
constructor function is the same as the name of the builtin
[XML Schema Part 2: Datatypes Second
Edition] datatype or the datatype defined in Section
Types^{DM30} of [XQuery and XPath Data Model (XDM) 3.0]
(see 17.1
Constructor functions for XML Schema builtin types) or the
userderived datatype (see 17.3 Constructor
functions for userdefined types) that is the target for
the conversion, and the semantics are exactly the same as for a
cast expression; for example," xs:date("20030101")
"
means exactly the same as " "20030101"
cast as
xs:date?
".
The cast expression takes a type name to indicate the target type of the conversion. See Section 3.10.2 Cast^{XP}. If the type name allows the empty sequence and the expression to be cast is the empty sequence, the empty sequence is returned. If the type name does not allow the empty sequence and the expression to be cast is the empty sequence, a type error is raised [err:XPTY0004]^{XP}.
Where the argument to a cast is a literal, the result of the function may be evaluated statically; if an error is encountered during such evaluation, it may be reported as a static error.
Casting from primitive types to primitive types is defined in 18.1 Casting from primitive types to primitive types. Casting to derived types is discussed in 18.2 Casting to derived types. Casting from derived types is discussed in 18.3 Casting from derived types to parent types, 18.4 Casting within a branch of the type hierarchy and 18.5 Casting across the type hierarchy.
Casting to union types is defined in 18.6 Casting to union types.
When casting from xs:string
the semantics in
18.1.1 Casting from xs:string
and xs:untypedAtomic apply, regardless of target type.
This section defines casting between the 19 primitive types
defined in [XML Schema Part 2: Datatypes
Second Edition] as well as xs:untypedAtomic
,
xs:integer
and the two derived types of
xs:duration
(xs:yearMonthDuration
and
xs:dayTimeDuration
). These four types are not
primitive types but they are treated as primitive types in this
section. The type conversions that are supported are indicated in
the table below. In this table, there is a row for each primitive
type with that type as the source of the conversion and there is a
column for each primitive type as the target of the conversion. The
intersections of rows and columns contain one of three characters:
"Y" indicates that a conversion from values of the type to which
the row applies to the type to which the column applies is
supported; "N" indicates that there are no supported conversions
from values of the type to which the row applies to the type to
which the column applies; and "M" indicates that a conversion from
values of the type to which the row applies to the type to which
the column applies may succeed for some values in the value space
and fails for others.
[XML Schema Part 2: Datatypes Second
Edition] defines xs:NOTATION
as an abstract type.
Thus, casting to xs:NOTATION
from any other type
including xs:NOTATION
is not permitted and raises
[err:XPST0080]^{XP}.
However, casting from one subtype of xs:NOTATION
to
another subtype of xs:NOTATION
is permitted.
Casting is not supported to or from
xs:anySimpleType
. Thus, there is no row or column for
this type in the table below. For any node that has not been
validated or has been validated as xs:anySimpleType
,
the typed value of the node is an atomic value of type
xs:untypedAtomic
. There are no atomic values with the
type annotation xs:anySimpleType
at runtime. Casting
to a type that is not atomic raises [err:XPST0051]^{XP}.
Similarly, casting is not supported to or from
xs:anyAtomicType
and will raise error [err:XPST0080]^{XP}. There
are no atomic values with the type annotation
xs:anyAtomicType
at runtime, although this can be a
statically inferred type.
If casting is attempted from an ST to a TT for which casting is not supported, as defined in the table below, a type error is raised [err:XPTY0004]^{XP}.
In the following table, the columns and rows are identified by short codes that identify simple types as follows:
uA = xs:untypedAtomic
aURI = xs:anyURI
b64 = xs:base64Binary
bool = xs:boolean
dat = xs:date
gDay = xs:gDay
dbl = xs:double
dec = xs:decimal
dT = xs:dateTime
dTD = xs:dayTimeDuration
dur = xs:duration
flt = xs:float
hxB = xs:hexBinary
gMD = xs:gMonthDay
gMon = xs:gMonth
int = xs:integer
NOT = xs:NOTATION
QN = xs:QName
str = xs:string
tim = xs:time
gYM = xs:gYearMonth
yMD = xs:yearMonthDuration
gYr = xs:gYear
In the following table, the notation "S\T" indicates that the source ("S") of the conversion is indicated in the column below the notation and that the target ("T") is indicated in the row to the right of the notation.
S\T  uA  str  flt  dbl  dec  int  dur  yMD  dTD  dT  tim  dat  gYM  gYr  gMD  gDay  gMon  bool  b64  hxB  aURI  QN  NOT 

uA  Y  Y  M  M  M  M  M  M  M  M  M  M  M  M  M  M  M  M  M  M  M  N  N 
str  Y  Y  M  M  M  M  M  M  M  M  M  M  M  M  M  M  M  M  M  M  M  M  M 
flt  Y  Y  Y  Y  M  M  N  N  N  N  N  N  N  N  N  N  N  Y  N  N  N  N  N 
dbl  Y  Y  Y  Y  M  M  N  N  N  N  N  N  N  N  N  N  N  Y  N  N  N  N  N 
dec  Y  Y  Y  Y  Y  Y  N  N  N  N  N  N  N  N  N  N  N  Y  N  N  N  N  N 
int  Y  Y  Y  Y  Y  Y  N  N  N  N  N  N  N  N  N  N  N  Y  N  N  N  N  N 
dur  Y  Y  N  N  N  N  Y  Y  Y  N  N  N  N  N  N  N  N  N  N  N  N  N  N 
yMD  Y  Y  N  N  N  N  Y  Y  Y  N  N  N  N  N  N  N  N  N  N  N  N  N  N 
dTD  Y  Y  N  N  N  N  Y  Y  Y  N  N  N  N  N  N  N  N  N  N  N  N  N  N 
dT  Y  Y  N  N  N  N  N  N  N  Y  Y  Y  Y  Y  Y  Y  Y  N  N  N  N  N  N 
tim  Y  Y  N  N  N  N  N  N  N  N  Y  N  N  N  N  N  N  N  N  N  N  N  N 
dat  Y  Y  N  N  N  N  N  N  N  Y  N  Y  Y  Y  Y  Y  Y  N  N  N  N  N  N 
gYM  Y  Y  N  N  N  N  N  N  N  N  N  N  Y  N  N  N  N  N  N  N  N  N  N 
gYr  Y  Y  N  N  N  N  N  N  N  N  N  N  N  Y  N  N  N  N  N  N  N  N  N 
gMD  Y  Y  N  N  N  N  N  N  N  N  N  N  N  N  Y  N  N  N  N  N  N  N  N 
gDay  Y  Y  N  N  N  N  N  N  N  N  N  N  N  N  N  Y  N  N  N  N  N  N  N 
gMon  Y  Y  N  N  N  N  N  N  N  N  N  N  N  N  N  N  Y  N  N  N  N  N  N 
bool  Y  Y  Y  Y  Y  Y  N  N  N  N  N  N  N  N  N  N  N  Y  N  N  N  N  N 
b64  Y  Y  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  Y  Y  N  N  N 
hxB  Y  Y  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  Y  Y  N  N  N 
aURI  Y  Y  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  Y  N  N 
QN  Y  Y  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  Y  M 
NOT  Y  Y  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  N  Y  M 
The following subsections define the semantics of casting from a primitive type to a primitive type. Semantics of casting to and from a derived type are defined in sections 18.2 Casting to derived types, 18.3 Casting from derived types to parent types, 18.4 Casting within a branch of the type hierarchy and 18.5 Casting across the type hierarchy.
When the supplied value is an instance of xs:string
or an instance of xs:untypedAtomic
, it is treated as
being a string value and mapped to a typed value of the target type
as defined in [XML Schema Part 2: Datatypes
Second Edition]. Whitespace normalization is applied as
indicated by the whiteSpace facet for the datatype. The resulting
whitespacenormalized string must be a valid lexical form for the
datatype. The semantics of casting are identical to XML Schema
validation. For example, "13" cast as xs:unsignedInt
returns the xs:unsignedInt
typed value
13
. This could also be written
xs:unsignedInt("13")
.
When casting from xs:string
or
xs:untypedAtomic
to a derived type where the derived
type is restricted by a pattern facet, the lexical form is first
checked against the pattern before further casting is attempted
(See 18.2 Casting to derived
types). If the lexical form does not conform to the
pattern, error [err:FORG0001] is raised.
Consider a userdefined Schema whose target namespace is bound
to the prefix mySchema
which defines a restriction of
xs:boolean
called trueBool
which allows
only the lexical forms " 1
" and " 0
".
"true" cast as mySchema:trueBool
would fail with
[err:FORG0001]. If
the Schema also defines a datatype called height
as a
restriction of xs:integer
with a maximum value of
84
then "100" cast as mySchema:height
would also fail with [err:FORG0001].
Casting is permitted from xs:string
and
xs:untypedAtomic
to any primitive atomic type or any
atomic type derived by restriction, except
xs:NOTATION
. Casting to xs:NOTATION
is
not permitted because it is an abstract type.
Casting is permitted from xs:string
literals to
xs:QName
and types derived from
xs:NOTATION
. The process is described in more detail
in 17.2 Constructor
functions for xs:QName and xs:NOTATION.
Note:
This version of the specification allows casting between
xs:QName
and xs:NOTATION
in either
direction; this was not permitted in the previous Recommendation.
This version also removes the rule that only a string literal
(rather than a dynamic string) may be cast to an
xs:QName
When casting to a numeric type:
If the value is too large or too small to be accurately represented by the implementation, it is handled as an overflow or underflow as defined in 4.2 Arithmetic operators on numeric values.
If the target type is xs:float
or
xs:double
, the string 0
(and equivalents
such as 0.0
or 000
)
should be converted to the value negative zero.
However, if the implementation is reliant on an implementation of
XML Schema 1.0 in which negative zero is not part of the value
space for these types, these lexical forms may be
converted to positive zero.
In casting to xs:decimal
or to a type derived from
xs:decimal
, if the value is not too large or too small
but nevertheless cannot be represented accurately with the number
of decimal digits available to the implementation, the
implementation may round to the nearest representable value or may
raise a dynamic error [err:FOCA0006]. The choice of rounding algorithm
and the choice between rounding and error behavior and is
implementationdefined.
In casting to xs:date
, xs:dateTime
,
xs:gYear
, or xs:gYearMonth
(or types
derived from these), if the value is too large or too small to be
represented by the implementation, error [err:FODT0001] is raised.
In casting to a duration value, if the value is too large or too small to be represented by the implementation, error [err:FODT0002] is raised.
For xs:anyURI
, the extent to which an
implementation validates the lexical form of xs:anyURI
is ·implementation dependent·.
If the cast fails for any other reason, error [err:FORG0001] is raised.
Casting is permitted from any primitive type to the primitive
types xs:string
and xs:untypedAtomic
.
When a value of any simple type is cast as
xs:string
, the derivation of the
xs:string
value TV depends on the ST
and on the SV, as follows.
If ST is xs:string
or a type derived from
xs:string
, TV is SV.
If ST is xs:anyURI
, the type conversion is
performed without escaping any characters.
If ST is xs:QName
or
xs:NOTATION
:
if the qualified name has a prefix, then TV is the concatenation of the prefix of SV, a single colon (:), and the local name of SV.
otherwise TV is the localname.
If ST is a numeric type, the following rules apply:
If ST is xs:integer
, TV is the
canonical lexical representation of SV as defined in
[XML Schema Part 2: Datatypes Second
Edition]. There is no decimal point.
If ST is xs:decimal
, then:
If SV is in the value space of xs:integer
,
that is, if there are no significant digits after the decimal
point, then the value is converted from an xs:decimal
to an xs:integer
and the resulting
xs:integer
is converted to an xs:string
using the rule above.
Otherwise, the canonical lexical representation of SV is returned, as defined in [XML Schema Part 2: Datatypes Second Edition].
If ST is xs:float
or
xs:double
, then:
TV will be an xs:string
in the lexical
space of xs:double
or xs:float
that when
converted to an xs:double
or xs:float
under the rules of 18.1.1
Casting from xs:string and xs:untypedAtomic produces a
value that is equal to SV, or is "NaN" if SV is
NaN
. In addition, TV must satisfy the
constraints in the following subbullets.
If SV has an absolute value that is greater than or
equal to 0.000001 (one millionth) and less than 1000000 (one
million), then the value is converted to an xs:decimal
and the resulting xs:decimal
is converted to an
xs:string
according to the rules above, as though
using an implementation of xs:decimal
that imposes no
limits on the totalDigits
or
fractionDigits
facets.
If SV has the value positive or negative zero, TV is "0" or "0" respectively.
If SV is positive or negative infinity, TV is
the string "INF
" or "INF
"
respectively.
In other cases, the result consists of a mantissa, which has the
lexical form of an xs:decimal
, followed by the letter
"E", followed by an exponent which has the lexical form of an
xs:integer
. Leading zeroes and "+" signs are
prohibited in the exponent. For the mantissa, there must be a
decimal point, and there must be exactly one digit before the
decimal point, which must be nonzero. The "+" sign is prohibited.
There must be at least one digit after the decimal point. Apart
from this mandatory digit, trailing zero digits are prohibited.
Note:
The above rules allow more than one representation of the same
value. For example, the xs:float
value whose exact
decimal representation is 1.26743223E15 might be represented by any
of the strings "1.26743223E15", "1.26743222E15" or "1.26743224E15"
(inter alia). It is implementationdependent which of these
representations is chosen.
If ST is xs:dateTime
, xs:date
or xs:time
, TV is the local value. The
components of TV are individually cast to
xs:string
using the functions described in [castingtodatetimes] and the results
are concatenated together. The year
component is cast
to xs:string
using
eg:convertYearToString
. The month
,
day
, hour
and minute
components are cast to xs:string
using
eg:convertTo2CharString
. The second
component is cast to xs:string
using
eg:convertSecondsToString
. The timezone component, if
present, is cast to xs:string
using
eg:convertTZtoString
.
Note that the hours component of the resulting string will never
be "24"
. Midnight is always represented as
"00:00:00"
.
If ST is xs:yearMonthDuration
or
xs:dayTimeDuration
, TV is the canonical
representation of SV as defined in 8.1.1 xs:yearMonthDuration or
8.1.2 xs:dayTimeDuration,
respectively.
If ST is xs:duration
then let SYM
be SV
cast as
xs:yearMonthDuration
, and let SDT be
SV
cast as xs:dayTimeDuration
;
Now, let the next intermediate value, TYM, be
SYM
cast as
TT
, and let TDT be
SDT
cast as
TT
. If TYM is "P0M", then
TV is TDT. Otherwise, TYM and
TDT are merged according to the following rules:
If TDT is "PT0S", then TV is TYM.
Otherwise, TV is the concatenation of all the characters in TYM and all the characters except the first "P" and the optional negative sign in TDT.
In all other cases, TV is the [XML Schema Part 2: Datatypes Second Edition] canonical representation of SV. For datatypes that do not have a canonical lexical representation defined an ·implementation dependent· canonical representation may be used.
To cast as xs:untypedAtomic
the value is cast as
xs:string
, as described above, and the type annotation
changed to xs:untypedAtomic
.
Note:
The string representations of numeric values are backwards
compatible with XPath 1.0 except for the special values positive
and negative infinity, negative zero and values outside the range
1.0e6
to 1.0e+6
.
When a value of any simple type is cast as
xs:float
, the xs:float
TV is
derived from the ST and the SV as follows:
If ST is xs:float
, then TV is
SV and the conversion is complete.
If ST is xs:double
, then TV is
obtained as follows:
if SV is the xs:double
value
INF
, INF
, NaN
, positive
zero, or negative zero, then TV is the
xs:float
value INF
, INF
,
NaN
, positive zero, or negative zero respectively.
otherwise, SV can be expressed in the form m ×
2^e
where the mantissa m
and exponent
e
are signed xs:integer
s whose value
range is defined in [XML Schema Part 2:
Datatypes Second Edition], and the following rules apply:
if m
(the mantissa of SV) is outside the
permitted range for the mantissa of an xs:float
value
(2^241 to +2^241)
, then it is divided by
2^N
where N
is the lowest positive
xs:integer
that brings the result of the division
within the permitted range, and the exponent e
is
increased by N
. This is integer division (in effect,
the binary value of the mantissa is truncated on the right). Let
M
be the mantissa and E
the exponent
after this adjustment.
if E
exceeds 104
(the maximum exponent
value in the value space of xs:float
) then TV
is the xs:float
value INF
or
INF
depending on the sign of M
.
if E
is less than 149
(the minimum
exponent value in the value space of xs:float
) then
TV is the xs:float
value positive or negative
zero depending on the sign of M
otherwise, TV is the xs:float
value
M × 2^E
.
If ST is xs:decimal
, or
xs:integer
, then TV is xs:float(
SV cast as xs:string)
and the conversion is
complete.
If ST is xs:boolean
, SV is
converted to 1.0E0
if SV is true
and to 0.0E0
if SV is false
and
the conversion is complete.
If ST is xs:untypedAtomic
or
xs:string
, see 18.1.1 Casting from xs:string and
xs:untypedAtomic.
Note:
Implementations should return negative zero for
xs:float("0.0E0")
. But because [XML Schema Part 2: Datatypes Second Edition]
does not distinguish between the values positive zero and negative
zero. implementations ·may· return positive zero in this case.
When a value of any simple type is cast as
xs:double
, the xs:double
value
TV is derived from the ST and the SV as
follows:
If ST is xs:double
, then TV is
SV and the conversion is complete.
If ST is xs:float
or a type derived from
xs:float
, then TV is obtained as follows:
if SV is the xs:float
value
INF
, INF
, NaN
, positive
zero, or negative zero, then TV is the
xs:double
value INF
, INF
,
NaN
, positive zero, or negative zero respectively.
otherwise, SV can be expressed in the form m ×
2^e
where the mantissa m
and exponent
e
are signed xs:integer
values whose
value range is defined in [XML Schema Part
2: Datatypes Second Edition], and TV is the
xs:double
value m × 2^e
.
If ST is xs:decimal
or
xs:integer
, then TV is
xs:double(
SV cast as xs:string)
and the conversion is complete.
If ST is xs:boolean
, SV is
converted to 1.0E0
if SV is true
and to 0.0E0
if SV is false
and
the conversion is complete.
If ST is xs:untypedAtomic
or
xs:string
, see 18.1.1 Casting from xs:string and
xs:untypedAtomic.
Note:
Implementations should return negative zero for
xs:double("0.0E0")
. But because [XML Schema Part 2: Datatypes Second Edition]
does not distinguish between the values positive zero and negative
zero. implementations ·may· return positive zero in this case.
When a value of any simple type is cast as
xs:decimal
, the xs:decimal
value
TV is derived from ST and SV as
follows:
If ST is xs:decimal
,
xs:integer
or a type derived from them, then
TV is SV, converted to an xs:decimal
value if need be, and the conversion is complete.
If ST is xs:float
or
xs:double
, then TV is the
xs:decimal
value, within the set of
xs:decimal
values that the implementation is capable
of representing, that is numerically closest to SV. If two
values are equally close, then the one that is closest to zero is
chosen. If SV is too large to be accommodated as an
xs:decimal
, (see [XML Schema
Part 2: Datatypes Second Edition] for ·implementationdefined· limits on numeric values) an error is raised
[err:FOCA0001]. If
SV is one of the special xs:float
or
xs:double
values NaN
, INF
,
or INF
, an error is raised [err:FOCA0002].
If ST is xs:boolean
, SV is
converted to 1.0
if SV is 1
or
true
and to 0.0
if SV is
0
or false
and the conversion is
complete.
If ST is xs:untypedAtomic
or
xs:string
, see 18.1.1 Casting from xs:string and
xs:untypedAtomic.
When a value of any simple type is cast as
xs:integer
, the xs:integer
value
TV is derived from ST and SV as
follows:
If ST is xs:integer
, or a type derived
from xs:integer
, then TV is SV,
converted to an xs:integer
value if need be, and the
conversion is complete.
If ST is xs:decimal
, xs:float
or xs:double
, then TV is SV with the
fractional part discarded and the value converted to
xs:integer
. Thus, casting 3.1456
returns
3
and 17.89
returns 17
.
Casting 3.124E1
returns 31
. If
SV is too large to be accommodated as an integer, (see
[XML Schema Part 2: Datatypes Second
Edition] for ·implementationdefined· limits on numeric values) an error is raised
[err:FOCA0003]. If
SV is one of the special xs:float
or
xs:double
values NaN
, INF
,
or INF
, an error is raised [err:FOCA0002].
If ST is xs:boolean
, SV is
converted to 1
if SV is 1
or
true
and to 0
if SV is
0
or false
and the conversion is
complete.
If ST is xs:untypedAtomic
or
xs:string
, see 18.1.1 Casting from xs:string and
xs:untypedAtomic.
When a value of type xs:untypedAtomic
,
xs:string
, a type derived from xs:string
,
xs:yearMonthDuration
or
xs:dayTimeDuration
is cast as
xs:duration
, xs:yearMonthDuration
or
xs:dayTimeDuration
, TV is derived from
ST and SV as follows:
If ST is the same as TT, then TV is SV.
If ST is xs:duration
, or a type derived
from xs:duration
, but not
xs:dayTimeDuration
or a type derived from
xs:dayTimeDuration
, and TT is
xs:yearMonthDuration
, then TV is derived from
SV by removing the day, hour, minute and second components
from SV.
If ST is xs:duration
, or a type derived
from duration
, but not
xs:yearMonthDuration
or a type derived from
xs:yearMonthDuration
, and TT is
xs:dayTimeDuration
, then TV is derived from
SV by removing the year and month components from
SV.
If ST is xs:yearMonthDuration
or
xs:dayTimeDuration
, and TT is
xs:duration
, then TV is derived from
SV as discussed in 18.3 Casting from derived
types to parent types.
If ST is xs:yearMonthDuration
and
TT is xs:dayTimeDuration
, the cast is
permitted and returns a xs:dayTimeDuration
with value
0.0 seconds.
If ST is xs:dayTimeDuration
and
TT is xs:yearMonthDuration
, the cast is
permitted and returns a xs:yearMonthDuration
with
value 0 months.
If ST is xs:untypedAtomic
or
xs:string
, see 18.1.1 Casting from xs:string and
xs:untypedAtomic.
Note that casting from xs:duration
to
xs:yearMonthDuration
or
xs:dayTimeDuration
loses information. To avoid this,
users can cast the xs:duration
value to both an
xs:yearMonthDuration
and an
xs:dayTimeDuration
and work with both values.
In several situations, casting to date and time types requires
the extraction of a component from SV or from the result
of fn:currentdateTime
and
converting it to an xs:string
. These conversions must
follow certain rules. For example, converting an
xs:integer
year value requires converting to an
xs:string
with four or more characters, preceded by a
minus sign if the value is negative.
This document defines four functions to perform these conversions. These functions are for illustrative purposes only and make no recommendations as to style or efficiency. References to these functions from the following text are not normative.
The arguments to these functions come from functions defined in this document. Thus, the functions below assume that they are correct and do no range checking on them.
declare function eg:convertYearToString($year as xs:integer) as xs:string { let $plusMinus := if ($year >= 0) then "" else "" let $yearString := fn:abs($year) cast as xs:string let $length := fn:stringlength($yearString) return if ($length = 1) then fn:concat($plusMinus, "000", $yearString) else if ($length = 2) then fn:concat($plusMinus, "00", $yearString) else if ($length = 3) then fn:concat($plusMinus, "0", $yearString) else fn:concat($plusMinus, $yearString) }
declare function eg:convertTo2CharString($value as xs:integer) as xs:string { let $string := $value cast as xs:string return if (fn:stringlength($string) = 1) then fn:concat("0", $string) else $string }
declare function eg:convertSecondsToString($seconds as xs:decimal) as xs:string { let $string := $seconds cast as xs:string let $intLength := fn:stringlength(($seconds cast as xs:integer) cast as xs:string) return if ($intLength = 1) then fn:concat("0", $string) else $string }
declare function eg:convertTZtoString($tz as xs:dayTimeDuration?) as xs:string { if (empty($tz)) then "" else if ($tz eq xs:dayTimeDuration('PT0S')) then "Z" else let $tzh := fn:hoursfromduration($tz) let $tzm := fn:minutesfromduration($tz) let $plusMinus := if ($tzh >= 0) then "+" else "" let $tzhString := eg:convertTo2CharString(fn:abs($tzh)) let $tzmString := eg:convertTo2CharString(fn:abs($tzm)) return fn:concat($plusMinus, $tzhString, ":", $tzmString) }
Conversion from primitive types to date and time types follows the rules below.
When a value of any primitive type is cast as
xs:dateTime
, the xs:dateTime
value
TV is derived from ST and SV as
follows:
If ST is xs:dateTime
, then TV is
SV.
If ST is xs:date
, then let SYR be
eg:convertYearToString( fn:yearfromdate(
SV
))
, let SMO be eg:convertTo2CharString(
fn:monthfromdate(
SV ))
, let
SDA be eg:convertTo2CharString(
fn:dayfromdate(
SV ))
and let
STZ be eg:convertTZtoString(
fn:timezonefromdate(
SV ))
;
TV is xs:dateTime( fn:concat(
SYR
, '',
SMO , '',
SDA
, 'T00:00:00 '
, STZ ) )
.
If ST is xs:untypedAtomic
or
xs:string
, see 18.1.1 Casting from xs:string and
xs:untypedAtomic.
When a value of any primitive type is cast as
xs:time
, the xs:time
value TV is
derived from ST and SV as follows:
If ST is xs:time
, then TV is
SV.
If ST is xs:dateTime
, then TV is
xs:time( fn:concat( eg:convertTo2CharString(
fn:hoursfromdateTime(
SV )), ':',
eg:convertTo2CharString( fn:minutesfromdateTime(
SV )), ':', eg:convertSecondsToString(
fn:secondsfromdateTime(
SV )),
eg:convertTZtoString( fn:timezonefromdateTime(
SV
)) ))
.
If ST is xs:untypedAtomic
or
xs:string
, see 18.1.1 Casting from xs:string and
xs:untypedAtomic.
When a value of any primitive type is cast as
xs:date
, the xs:date
value TV is
derived from ST and SV as follows:
If ST is xs:date
, then TV is
SV.
If ST is xs:dateTime
, then let
SYR be eg:convertYearToString(
fn:yearfromdateTime(
SV ))
, let
SMO be eg:convertTo2CharString(
fn:monthfromdateTime(
SV ))
, let
SDA be eg:convertTo2CharString(
fn:dayfromdateTime(
SV ))
and let
STZ be
eg:convertTZtoString(fn:timezonefromdateTime(
SV ))
; TV is xs:date(
fn:concat(
SYR , '',
SMO
, '',
SDA, STZ )
)
.
If ST is xs:untypedAtomic
or
xs:string
, see 18.1.1 Casting from xs:string and
xs:untypedAtomic.
When a value of any primitive type is cast as
xs:gYearMonth
, the xs:gYearMonth
value
TV is derived from ST and SV as
follows:
If ST is xs:gYearMonth
, then TV
is SV.
If ST is xs:dateTime
, then let
SYR be eg:convertYearToString(
fn:yearfromdateTime(
SV ))
, let
SMO be eg:convertTo2CharString(
fn:monthfromdateTime(
SV ))
and let
STZ be eg:convertTZtoString(
fn:timezonefromdateTime(
SV ))
;
TV is xs:gYearMonth( fn:concat(
SYR
, '',
SMO, STZ )
)
.
If ST is xs:date
, then let SYR be
eg:convertYearToString( fn:yearfromdate(
SV
))
, let SMO be eg:convertTo2CharString(
fn:monthfromdate(
SV ))
and let
STZ be eg:convertTZtoString(
fn:timezonefromdate(
SV ))
;
TV is xs:gYearMonth( fn:concat(
SYR
, '',
SMO, STZ )
)
.
If ST is xs:untypedAtomic
or
xs:string
, see 18.1.1 Casting from xs:string and
xs:untypedAtomic.
When a value of any primitive type is cast as
xs:gYear
, the xs:gYear
value TV
is derived from ST and SV as follows:
If ST is xs:gYear
, then TV is
SV.
If ST is xs:dateTime
, let SYR be
eg:convertYearToString( fn:yearfromdateTime(
SV ))
and let STZ be
eg:convertTZtoString( fn:timezonefromdateTime(
SV ))
; TV is
xs:gYear(fn:concat(
SYR, STZ
))
.
If ST is xs:date
, let SYR be
eg:convertYearToString( fn:yearfromdate(
SV
))
; and let STZ be
eg:convertTZtoString( fn:timezonefromdate(
SV ))
; TV is
xs:gYear(fn:concat(
SYR, STZ
))
.
If ST is xs:untypedAtomic
or
xs:string
, see 18.1.1 Casting from xs:string and
xs:untypedAtomic.
When a value of any primitive type is cast as
xs:gMonthDay
, the xs:gMonthDay
value
TV is derived from ST and SV as
follows:
If ST is xs:gMonthDay
, then TV is
SV.
If ST is xs:dateTime
, then let
SMO be eg:convertTo2CharString(
fn:monthfromdateTime(
SV ))
, let
SDA be eg:convertTo2CharString(
fn:dayfromdateTime(
SV ))
and let
STZ be eg:convertTZtoString(
fn:timezonefromdateTime(
SV ))
;
TV is xs:gYearMonth( fn:concat(
'',
SMO '',
SDA,
STZ ) )
.
If ST is xs:date
, then let SMO be
eg:convertTo2CharString( fn:monthfromdate(
SV ))
, let SDA be
eg:convertTo2CharString( fn:dayfromdate(
SV
))
and let STZ be eg:convertTZtoString(
fn:timezonefromdate(
SV ))
;
TV is xs:gYearMonth( fn:concat(
'',
SMO , '',
SDA,
STZ ) )
.
If ST is xs:untypedAtomic
or
xs:string
, see 18.1.1 Casting from xs:string and
xs:untypedAtomic.
When a value of any primitive type is cast as
xs:gDay
, the xs:gDay
value TV is
derived from ST and SV as follows:
If ST is xs:gDay
, then TV is
SV.
If ST is xs:dateTime
, then let
SDA be eg:convertTo2CharString(
fn:dayfromdateTime(
SV ))
and let
STZ be eg:convertTZtoString(
fn:timezonefromdateTime(
SV ))
;
TV is xs:gDay( fn:concat( ''
,
SDA, STZ ))
.
If ST is xs:date
, then let SDA be
eg:convertTo2CharString( fn:dayfromdate(
SV
))
and let STZ be eg:convertTZtoString(
fn:timezonefromdate(
SV ))
;
TV is xs:gDay( fn:concat( ''
,
SDA, STZ ))
.
If ST is xs:untypedAtomic
or
xs:string
, see 18.1.1 Casting from xs:string and
xs:untypedAtomic.
When a value of any primitive type is cast as
xs:gMonth
, the xs:gMonth
value
TV is derived from ST and SV as
follows:
If ST is xs:gMonth
, then TV is
SV.
If ST is xs:dateTime
, then let
SMO be eg:convertTo2CharString(
fn:monthfromdateTime(
SV ))
and let
STZ be eg:convertTZtoString(
fn:timezonefromdateTime(
SV ))
;
TV is xs:gMonth( fn:concat( ''
,
SMO, STZ ))
.
If ST is xs:date
, then let SMO be
eg:convertTo2CharString( fn:monthfromdate(
SV ))
and let STZ be
eg:convertTZtoString( fn:timezonefromdate(
SV ))
; TV is xs:gMonth(
fn:concat( ''
, SMO, STZ
))
.
If ST is xs:untypedAtomic
or
xs:string
, see 18.1.1 Casting from xs:string and
xs:untypedAtomic.
When a value of any primitive type is cast as
xs:boolean
, the xs:boolean
value
TV is derived from ST and SV as
follows:
If ST is xs:boolean
, then TV is
SV.
If ST is xs:float
, xs:double
,
xs:decimal
or xs:integer
and SV
is 0
, +0
, 0
,
0.0
, 0.0E0
or NaN
, then
TV is false
.
If ST is xs:float
, xs:double
,
xs:decimal
or xs:integer
and SV
is not one of the above values, then TV is
true
.
If ST is xs:untypedAtomic
or
xs:string
, see 18.1.1 Casting from xs:string and
xs:untypedAtomic.
Values of type xs:base64Binary
can be cast as
xs:hexBinary
and vice versa, since the two types have
the same value space. Casting to xs:base64Binary
and
xs:hexBinary
is also supported from the same type and
from xs:untypedAtomic
, xs:string
and
subtypes of xs:string
using [XML Schema Part 2: Datatypes Second Edition]
semantics.
Casting to xs:anyURI
is supported only from the
same type, xs:untypedAtomic
or
xs:string
.
When a value of any primitive type is cast as
xs:anyURI
, the xs:anyURI
value
TV is derived from the ST and SV as
follows:
If ST is xs:untypedAtomic
or
xs:string
see 18.1.1 Casting from xs:string and
xs:untypedAtomic.
Casting from xs:string
or
xs:untypedAtomic
to xs:QName
or
xs:NOTATION
is described in 18.1.1 Casting from xs:string and
xs:untypedAtomic.
It is also possible to cast from xs:NOTATION
to
xs:QName
, or from xs:QName
to any type
derived by restriction from xs:NOTATION
. (Casting to
xs:NOTATION
itself is not allowed, because
xs:NOTATION
is an abstract type.) The resulting
xs:QName
or xs:NOTATION
has the same
prefix, local name, and namespace URI parts as the supplied
value.
Casting a value to a derived type can be separated into four
cases. Note that xs:untypedAtomic
,
xs:integer
and the two derived types of
xs:duration
:xs:yearMonthDuration
and
xs:dayTimeDuration
are treated as primitive types.
When SV is an instance of a type that is derived by restriction from TT. This is described in section 18.3 Casting from derived types to parent types.
When SV is an instance of a type derived by restriction from the same primitive type as TT. This is described in 18.4 Casting within a branch of the type hierarchy.
When the derived type is derived, directly or indirectly, from a different primitive type than the primitive type of ST. This is described in 18.5 Casting across the type hierarchy.
When SV is an instance of the TT, the cast always succeeds (Identity cast).
Except in the case of xs:NOTATION
, it is always
possible to cast a value of any atomic type to an atomic type from
which it is derived, directly or indirectly, by restriction. For
example, it is possible to cast an xs:unsignedShort
to
an xs:unsignedInt
, an xs:integer
, or an
xs:decimal
. Since the value space of the original type
is a subset of the value space of the target type, such a cast is
always successful. The result will have the same value as the
original, but will have a new type annotation.
It is possible to cast an SV to a TT if the
type of the SV and the TT type are both derived
by restriction (directly or indirectly) from the same primitive
type, provided that the supplied value conforms to the constraints
implied by the facets of the target type. This includes the case
where the target type is derived from the type of the supplied
value, as well as the case where the type of the supplied value is
derived from the target type. For example, an instance of
xs:byte
can be cast as xs:unsignedShort
,
provided the value is not negative.
If the value does not conform to the facets defined for the
target type, then an error is raised [err:FORG0001]. See [XML
Schema Part 2: Datatypes Second Edition]. In the case of the
pattern facet (which applies to the lexical space rather than the
value space), the pattern is tested against the canonical lexical
representation of the value, as defined for the source type (or the
result of casting the value to an xs:string
, in the
case of types that have no canonical lexical representation defined
for them).
Note that this will cause casts to fail if the pattern excludes
the canonical lexical representation of the source type. For
example, if the type my:distance
is defined as a
restriction of xs:decimal
with a pattern that requires
two digits after the decimal point, casting of an
xs:integer
to my:distance
will always
fail, because the canonical representation of an
xs:integer
does not conform to this pattern.
In some cases, casting from a parent type to a derived type
requires special rules. See 18.1.4 Casting to duration types
for rules regarding casting to xs:yearMonthDuration
and xs:dayTimeDuration
. See 18.4.1 Casting to xs:ENTITY, below,
for casting to xs:ENTITY
and types derived from
it.
[XML Schema Part 2: Datatypes Second
Edition] says that "The value space of ENTITY is the set of all
strings that match the NCName production ... and have been declared
as an unparsed entity in a document type definition." However,
[XSL Transformations (XSLT) Version 3.0] and
[XQuery 3.0: An XML Query Language] do not
check that constructed values of type xs:ENTITY
match
declared unparsed entities. Thus, this rule is relaxed in this
specification and, in casting to xs:ENTITY
and types
derived from it, no check is made that the values correspond to
declared unparsed entities.
When the ST and the TT are derived, directly or indirectly, from different primitive types, this is called casting across the type hierarchy. Casting across the type hierarchy is logically equivalent to three separate steps performed in order. Errors can occur in either of the latter two steps.
Cast the SV, up the hierarchy, to the primitive type of the source, as described in 18.3 Casting from derived types to parent types.
If SV is an instance of xs:string
or
xs:untypedAtomic
, check its value against the pattern
facet of TT, and raise an error [err:FORG0001] if the check fails.
Cast the value to the primitive type of TT, as described in 18.1 Casting from primitive types to primitive types.
If TT is derived from xs:NOTATION
, assume
for the purposes of this rule that casting to
xs:NOTATION
succeeds.
Cast the value down to the TT, as described in 18.4 Casting within a branch of the type hierarchy
If the target type of a cast expression (or a constructor
function) is a type with variety union, the supplied value must be
of type xs:string
or
xs:untypedAtomic
.
The semantics of the operation are consistent with validation: that is, the effect of casting a string S to a union type U is the same as constructing an element or attribute node whose string value is S, validating it using U as the governing type, and atomizing the resulting node. The result will always be either failure, or an atomic value that is an instance of an atomic type in the transitive membership of U.
If the transitive membership of the union type includes
xs:QName
, xs:NOTATION
, or a type derived
from either of these by restriction, then the namespace bindings in
the static context will be used to resolve any namespace prefix, in
the same way as when the target type is xs:QName
itself.