The presentation of this document has been augmented to identify changes from a previous version. Three kinds of changes are highlighted: new, added text, changed text, and deleted text.
See also translations.
This document is also available in these nonnormative formats: XML and Change markings relative to previous edition.
Copyright © 2014 W3C^{®} (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
Change markings are relative to the XPath and XQuery Functions and Operators 3.0 Recommendation of 8 April 2014.
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.1]. It also defines functions and operators on nodes and node sequences as defined in the [XQuery and XPath Data Model (XDM) 3.1]. These functions and operators are defined for use in [XML Path Language (XPath) 3.1] and [XQuery 3.1: 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/.
At the time of writing, there is no version of XSLT that refers to the functions and operators in this version of this specification. Nevertheless, the XSLT Working Group is actively involved in the development of the specification, and references to XSLT as a host language are therefore retained from previous versions.
This is the fourth 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, subsequently revised in a second edition published on 14 December 2010. The third version, published on 8 April 2014, was the first to carry its own version number, 3.0. This version 3.1 is a revision of 3.0 that adds additional functions and operators, notably to work with the new data types of maps and arrays.
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 document is governed by the 14 October 2005 W3C Process Document.
This is a Last Call Working Draft as described in the Process Document. It was jointly developed by the W3C XML Query Working Group and the W3C XSLT Working Group, each of which is part of the XML Activity. Comments on this document will be formally accepted at least through 7 November 2014. The Working Groups expect to advance this specification to Recommendation Status.
This Last Call Working Draft specifies the XSLT and XQuery Functions and Operators (F&O) version 3.1, a fully compatible extension of F&O version 3.0. This publication differs from its immediate predecessor primarily by the addition of maps and arrays. There are numerous other difference as well, all documented in the change log.
This specification is designed to be referenced normatively from other specifications defining a host language for it; it is not intended to be implemented outside a host language. The implementability of this specification has been tested in the context of its normative inclusion in host languages defined by the XQuery 3.1 and XSLT 3.0 (expected in 2015) specifications; see the XQuery 3.1 implementation report (and, in the future, the WGs expect that there will also be an XSLT 3.0 implementation report) for details.
This document incorporates changes made against the previous publication of the Working Draft. Changes to this document since the previous publication of the Working Draft are detailed in E Changes since version 3.0.
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 “[FO31]” 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 Last Call 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 math:acos op:adddayTimeDurations op:adddayTimeDurationtodate op:adddayTimeDurationtodateTime op:adddayTimeDurationtotime op:addyearMonthDurations op:addyearMonthDurationtodate op:addyearMonthDurationtodateTime adjustdateTimetotimezone adjustdatetotimezone adjusttimetotimezone analyzestring array:append math:asin math:atan math:atan2 availableenvironmentvariables avg
op:base64Binaryequal op:base64Binarygreaterthan op:base64Binarylessthan baseuri boolean op:booleanequal op:booleangreaterthan op:booleanlessthan
ceiling codepointequal codepointstostring collationkey collection compare concat op:concatenate contains map:contains containstoken math:cos count currentdate currentdateTime currenttime
data op:dateequal op:dategreaterthan op:datelessthan dateTime op:dateTimeequal op:dateTimegreaterthan op:dateTimelessthan dayfromdate dayfromdateTime daysfromduration op:dayTimeDurationgreaterthan op:dayTimeDurationlessthan deepequal defaultcollation distinctvalues op:dividedayTimeDuration op:dividedayTimeDurationbydayTimeDuration op:divideyearMonthDuration op:divideyearMonthDurationbyyearMonthDuration doc docavailable documenturi op:durationequal
elementwithid empty encodeforuri endswith map:entry environmentvariable error escapehtmluri exactlyone op:except exists math:exp math:exp10
false filter array:filter floor foldleft array:foldleft foldright array:foldright foreach map:foreach array:foreach foreachpair array:foreachpair formatdate formatdateTime formatinteger formatnumber formattime functionarity functionlookup functionname
op:gDayequal generateid map:get op:gMonthDayequal op:gMonthequal op:gYearequal op:gYearMonthequal
haschildren head array:head op:hexBinaryequal op:hexBinarygreaterthan op:hexBinarylessthan hoursfromdateTime hoursfromduration hoursfromtime
id idref implicittimezone indexof innermost inscopeprefixes insertbefore array:insertbefore op:intersect iritouri op:issamenode
lang last loadxquerymodule localname localnamefromQName math:log math:log10 lowercase
matches max map:merge min minutesfromdateTime minutesfromduration minutesfromtime monthfromdate monthfromdateTime monthsfromduration op:multiplydayTimeDuration op:multiplyyearMonthDuration
name namespaceuri namespaceuriforprefix namespaceurifromQName nilled op:nodeafter op:nodebefore nodename normalizespace normalizeunicode not op:NOTATIONequal number op:numericadd op:numericdivide op:numericequal op:numericgreaterthan op:numericintegerdivide op:numericlessthan op:numericmod op:numericmultiply op:numericsubtract op:numericunaryminus op:numericunaryplus
parseietfdate parsejson parsexml parsexmlfragment path math:pi position math:pow prefixfromQName map:put
randomnumbergenerator remove map:remove array:remove replace resolveQName resolveuri reverse array:reverse root round roundhalftoeven
secondsfromdateTime secondsfromduration secondsfromtime serialize math:sin map:size array:size sort array:sort math:sqrt startswith staticbaseuri string stringjoin stringlength stringtocodepoints array:subarray subsequence substring substringafter substringbefore op:subtractdates op:subtractdateTimes op:subtractdayTimeDurationfromdate op:subtractdayTimeDurationfromdateTime op:subtractdayTimeDurationfromtime op:subtractdayTimeDurations op:subtracttimes op:subtractyearMonthDurationfromdate op:subtractyearMonthDurationfromdateTime op:subtractyearMonthDurations sum
tail array:tail math:tan op:timeequal op:timegreaterthan op:timelessthan timezonefromdate timezonefromdateTime timezonefromtime op:to tokenize trace transform translate true
op:union unordered unparsedtext unparsedtextavailable unparsedtextlines uppercase uricollection
yearfromdate yearfromdateTime op:yearMonthDurationgreaterthan op: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 Parsing numbers
4.5.1 fn:number
4.6 Formatting integers
4.6.1 fn:formatinteger
4.7 Formatting numbers
4.7.1 Defining a decimal format
4.7.2 fn:formatnumber
4.7.3 Syntax of the picture string
4.7.4 Analysing the picture string
4.7.5 Formatting the number
4.8 Trigonometric and exponential functions
4.8.1 math:pi
4.8.2 math:exp
4.8.3 math:exp10
4.8.4 math:log
4.8.5 math:log10
4.8.6 math:pow
4.8.7 math:sqrt
4.8.8 math:sin
4.8.9 math:cos
4.8.10 math:tan
4.8.11 math:asin
4.8.12 math:acos
4.8.13 math:atan
4.8.14 math:atan2
4.9 Random Numbers
4.9.1 fn:randomnumbergenerator
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 The Unicode Collation Algorithm
5.3.4 The HTML ASCII CaseInsensitive Collation
5.3.5 Choosing a collation
5.3.6 fn:compare
5.3.7 fn:codepointequal
5.3.8 fn:collationkey
5.3.9 fn:containstoken
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
9.9 Parsing dates and times
9.9.1 fn:parseietfdate
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:hexBinarylessthan
11.1.3 op:hexBinarygreaterthan
11.1.4 op:base64Binaryequal
11.1.5 op:base64Binarylessthan
11.1.6 op:base64Binarygreaterthan
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:lang
13.5 op:issamenode
13.6 op:nodebefore
13.7 op:nodeafter
13.8 fn:root
13.9 fn:path
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:parsexmlfragment
14.9.3 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:functionlookup
16.1.2 fn:functionname
16.1.3 fn:functionarity
16.2 Basic higherorder functions
16.2.1 fn:foreach
16.2.2 fn:filter
16.2.3 fn:foldleft
16.2.4 fn:foldright
16.2.5 fn:foreachpair
16.2.6 fn:sort
16.3 Dynamic Loading
16.3.1 fn:loadxquerymodule
16.3.2 fn:transform
17 Maps and Arrays
17.1 Functions that Operate on Maps
17.1.1 map:merge
17.1.2 map:size
17.1.3 map:keys
17.1.4 map:contains
17.1.5 map:get
17.1.6 map:put
17.1.7 map:entry
17.1.8 map:remove
17.1.9 map:foreach
17.2 Other Operations on Maps
17.3 Functions that Operate on Arrays
17.3.1 array:size
17.3.2 array:append
17.3.3 array:subarray
17.3.4 array:remove
17.3.5 array:insertbefore
17.3.6 array:head
17.3.7 array:tail
17.3.8 array:reverse
17.3.9 array:join
17.3.10 array:foreach
17.3.11 array:filter
17.3.12 array:foldleft
17.3.13 array:foldright
17.3.14 array:foreachpair
17.3.15 array:sort
17.4 Conversion to and from JSON
17.5 Functions on JSON Data
17.5.1 fn:parsejson
17.5.2 fn:jsondoc
18 Constructor functions
18.1 Constructor functions for XML Schema builtin atomic types
18.2 Constructor functions for xs:QName and xs:NOTATION
18.3 Constructor functions for XML Schema builtin list types
18.4 Constructor functions for XML Schema builtin union types
18.5 Constructor functions for userdefined types
19 Casting
19.1 Casting from primitive types to primitive types
19.1.1 Casting to xs:string and xs:untypedAtomic
19.1.2 Casting to numeric types
19.1.3 Casting to duration types
19.1.4 Casting to date and time types
19.1.5 Casting to xs:boolean
19.1.6 Casting to xs:base64Binary and xs:hexBinary
19.1.7 Casting to xs:anyURI
19.1.8 Casting to xs:QName and xs:NOTATION
19.1.9 Casting to xs:ENTITY
19.2 Casting from xs:string and xs:untypedAtomic
19.3 Casting involving nonprimitive types
19.3.1 Casting to derived types
19.3.2 Casting from derived types to parent types
19.3.3 Casting within a branch of the type hierarchy
19.3.4 Casting across the type hierarchy
19.3.5 Casting to union types
19.3.6 Casting to list types
A References
A.1 Normative references
A.2 Nonnormative references
B Error summary
C Illustrative userwritten functions (NonNormative)
C.1 eg:ifempty and eg:ifabsent
C.1.1 eg:ifempty
C.1.2 eg:ifabsent
C.2 Union, intersection and difference on sequences of values
C.2.1 eg:valueunion
C.2.2 eg:valueintersect
C.2.3 eg:valueexcept
C.3 eg:indexofnode
C.4 eg:stringpad
C.5 eg:distinctnodesstable
C.6 Finding minima and maxima
C.6.1 eg:highest
C.6.2 eg:lowest
C.7 Sorting
D Checklist of implementationdefined features (NonNormative)
E Changes since version 3.0 (NonNormative)
E.1 Substantive changes
E.2 Editorial changes
F Compatibility with Previous Versions (NonNormative)
The purpose of this document is to catalog the functions and operators required for XPath 3.1, XQuery 3.1 and potentially a future version of XSLT. The exact syntax used to call these functions and operators is specified in [XML Path Language (XPath) 3.1], [XQuery 3.1: An XML Query Language] and [XSL Transformations (XSLT) Version 3.0].
This document defines three classes of functions:
General purpose functions, available for direct use in userwritten queries, stylesheets, and XPath expressions, whose arguments and results are values defined by the [XQuery and XPath Data Model (XDM) 3.1].
Constructor functions, used for creating instances of a datatype from values of (in general) a different data type. These functions are also available for general use; they are named after the datatype that they return, and they always take a single argument.
Functions that specify the semantics of operators defined in [XML Path Language (XPath) 3.1] and [XQuery 3.1: An XML Query Language]. These exist for specification purposes only, and are not intended for direct calling from userwritten code.
[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 other types (for example, nodes and sequences of nodes) defined in Section 2.7 Schema Information ^{DM30} of the [XQuery and XPath Data Model (XDM) 3.1]. These functions and operations are available for use in [XML Path Language (XPath) 3.1], [XQuery 3.1: An XML Query Language] and any other host language that chooses to reference them. In particular, they may be referenced in future versions of XSLT and related XML standards.
[Schema 1.1 Part 2] adds to the data types defined
in [XML Schema Part 2: Datatypes Second Edition]. It introduces a new derived type xs:dateTimeStamp
, 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, and extends the lexical space to allow +INF
;
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.1: An XML Query Language], 'XT' [XSL Transformations (XSLT) Version 3.0], 'XP' [XML Path Language (XPath) 3.1], and 'DM' [XQuery and XPath Data Model (XDM) 3.1].
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.1], [XQuery 3.1: An XML Query Language], and potentially future versions of XSLT) to specify conformance criteria for their respective environments.
Authors of conformance criteria for the use of these 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.
It is ·implementationdefined· whether definitions that rely on XML (for example, the set of valid XML characters) should use the definitions in XML 1.0 or XML 1.1.
Note:
The XML Schema 1.1 recommendation
introduces one new concrete data type: xs:dateTimeStamp
; it also incorporates
the types xs:dayTimeDuration
, xs:yearMonthDuration
,
and xs:anyAtomicType
which were previously defined in earlier versions of [XQuery and XPath Data Model (XDM) 3.1].
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.
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 defined 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 section 18 Constructor functions defines
constructor functions for the builtin datatypes defined
in [XML Schema Part 2: Datatypes Second Edition] and in Section
2.7 Schema Information
^{DM30}
of [XQuery and XPath Data Model (XDM) 3.1]. These datatypes and the corresponding constructor functions
are in the XML Schema namespace, http://www.w3.org/2001/XMLSchema
,
and are 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.
http://www.w3.org/2010/xsltxqueryserialization
— associated with
output
.
There are no functions in this namespace: it is used for serialization parameters, as described in [XSLT and XQuery Serialization 3.0]
Functions defined with the op
prefix are described here to
underpin the definitions of the operators in [XML Path Language (XPath) 3.1], [XQuery 3.1: 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
xs:numeric
, $arg2
as
xs:numeric
) as
xs:numeric
A function is uniquely defined by its name and arity (number of arguments); it is therefore
not possible to have two different functions that have the same name and arity, but different
types in their signature. That is, function overloading in this sense of the term is not permitted.
Consequently, functions such as fn:string
which accept arguments of many different
types have a signature that defines a very general argument type, in this case item()?
which accepts any single item; supplying an inappropriate item (such as a function item) causes
a dynamic error.
Some functions on numeric types include the type xs:numeric
in their signature
as an argument or result type. In this version of the specification, xs:numeric
has been redefined as a builtin union type representing the union of
xs:decimal
, xs:float
, xs:double
(and thus automatically
accepting types derived from these, including xs:integer
).
Operators such as "+" may be overloaded: they map to different underlying functions depending on the dynamic types of the supplied operands.
It is possible for two functions to have the same name provided they have different arity (number of arguments). For the functions defined in this specification, where two functions have the same name and different arity, they also have closely related behavior, so they are defined in the same section of this document.
Each function (or group of functions having the same name) is defined in this specification using a standard proforma.
The function name is a QName
as defined in [XML Schema Part 2: Datatypes Second Edition]
and must adhere to its syntactic conventions. Following the precedent set by [XML Path Language (XPath) Version 1.0],
function names are generally composed of English words separated by hyphens (""). Abbreviations are
used only where there is a strong precedent in other programming languages (as with math:sin
and
math:cos
for sine and cosine). 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. An example is fn:timezonefromdateTime
.
The first section in the proforma is a short summary of what the function does. This is intended to be informative rather than normative.
Each function is then defined by specifying its signature, which defines the types of the parameters and of the result value.
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, in which 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.4 SequenceType Syntax
^{XP31}.
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.
The next section in the proforma defines the semantics of the function as a set of rules. The order in which the rules appear is significant; they are to be applied in the order in which they are written. Error conditions, however, are generally listed in a separate section that follows the main rules, and take precedence over nonerror rules except where otherwise stated. The principles outlined in Section 2.3.4 Errors and Optimization ^{XP31} apply by default: to paraphrase, if the result of the function can be determined without evaluating all its arguments, then it is not necessary to evaluate the remaining arguments merely in order to determine whether any error conditions apply.
Where the proforma includes sections headed Notes or Examples, these are nonnormative.
Rules for passing parameters to operators are described in the relevant sections
of [XQuery 3.1: An XML Query Language] and [XML Path Language (XPath) 3.1]. For example, the rules for
passing parameters to arithmetic operators are described in Section
3.5 Arithmetic Expressions
^{XP31}. 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.5 SequenceType Matching
^{XP31}). 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
^{XP31}).
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, functions, primitive simple types, and user defined types fit together into a type system. This type system comprises two distinct subsystems that both include the primitive atomic 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
,
xs:ENTITIES
types, and xs:numeric
and both the
userdefined list types
and
userdefined 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 relationship of various item types. Item types in the data model
form a directed graph, rather than a hierarchy or lattice: in the relationship defined
by the derivedfrom(A, B)
function, some types are derived
from more than one other type. Examples include functions (function(xs:string) as xs:int
is substitutable for function(xs:NCName) as xs:int
and also for
function(xs:string) as xs:decimal
), and union types (A
is substitutable for union(A, B)
and also for union(A, C)
.
In XDM, item types include node types, function types, and builtin atomic types.
The diagram, which shows only hierarchic relationships, is therefore a simplification of
the full model.
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  
namespace  
processinginstruction  
text  
function(*)  
array(*)  
map(*) 
The next diagram and table illustrate the "any type" type subsystem, 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  
xs:anySimpleType  
xs:anyAtomicType  
list types  
xs:IDREFS  
xs:NMTOKENS  
xs:ENTITIES  
userdefined list types  
union types  
xs:numeric  
userdefined union types  
complex types  
xs:untyped  
userdefined complex types 
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].
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: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 [Extensible Markup Language (XML) 1.0 (Fifth Edition)].
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.
Note:
Where this specification states that something is implementationdefined or implementationdependent, it is open to host languages to place further constraints on the behavior.
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 (except that static expressions, such as those used in
usewhen
attributes, are in a separate 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 all the following conditions apply:
Either both functions have the same name, or both names are absent^{DM30}.
Both functions have the same arity.
Both functions have the same function signature.
Both functions have the same nonlocal variable bindings (sometimes called the function's closure).
The processor is able to determine that the implementations of the two functions are equivalent, in the sense that for all possible combinations of arguments, the two functions have the same effect.
Note:
There is no function or operator defined in the specification that tests whether two function items are identical. Where the specification requires two function items to be identical, for example in the results of repeated calls of a function whose result is a function, then the processor must ensure that it returns functions that are indistinguishable in their observable effect. Where the specification defines behavior conditional on two function items being identical, the determination of identity is to some degree implementationdependent. There are cases where function items are definitely not identical (for example if they have different name or arity), but positive determination of identity is possible only using implementationdependent techniques, for example when both items contain references to the same piece of code representing the function's implementation.
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).
[Definition] A function that is not ·contextdependent· is called contextindependent.
A function that is contextdependent can be used as a named
function reference, can be partially applied, and can be found using fn:functionlookup
.
The principle in such cases is that the static context used for the function evaluation
is taken from the static context of the named function reference, partial function application, or the call
on fn:functionlookup
; and the dynamic context for the function evaluation is taken from the dynamic
context of the evaluation of the named function reference, partial function application, or the call
of fn:functionlookup
. In effect, the static and dynamic part of the context thus act
as part of the closure of the function item.
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·.
A number of functions including fn:baseuri#0
, fn:data#0
,
fn:documenturi#0
, fn:elementwithid#1
, fn:id#1
,
fn:idref#1
, fn:lang#1
, fn:last#0
, fn:localname#0
,
fn:name#0
, fn:namespaceuri#0
, fn:normalizespace#0
,
fn:number#0
, fn:path#0
, fn:position#0
,
fn:root#0
, fn:string#0
, and
fn:stringlength#0
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).
[Definition] A function that is not ·focusdependent· is called focusindependent
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.
The fn:functionlookup
function is a special case because it is
potentially dependent on everything in the static and dynamic context. This is because the static and dynamic
context of the call to fn:functionlookup
are used as the static and dynamic context of the
function that fn:functionlookup
returns.
[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 within a single ·execution scope· if the explicit and implicit arguments are identical is referred to as deterministic.
[Definition] A function that is not ·deterministic· is referred to as nondeterministic.
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.1]. 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?
The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
5.11 nodename Accessor
^{DM30}).
The following errors may be raised when $arg
is omitted:
If the context item is absent^{DM30}, dynamic error [err:XPDY0002]^{XP30}
If the context item is not a node, type error [err:XPTY0004]^{XP30}.
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^{DM30}.
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^{DM30} and the local
part is 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
() as
xs:boolean
fn:nilled
($arg
as
node()?
) as
xs:boolean?
The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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.
Otherwise the function returns the result of the dm:nilled
accessor as
defined in [XQuery and XPath Data Model (XDM) 3.0] (see Section
5.9 nilled Accessor
^{DM30}).
The following errors may be raised when $arg
is omitted:
If the context item is absent^{DM30}, dynamic error [err:XPDY0002]^{XP30}
If the context item is not a node, type error [err:XPTY0004]^{XP30}.
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
The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 string value of the node, as obtained using the
dm:stringvalue
accessor defined in [XQuery and XPath Data Model (XDM) 3.0] (see Section
5.13 stringvalue Accessor
^{DM30}).
If $arg is an atomic value, the function returns the result of the expression $arg cast
as xs:string
(see 19 Casting).
In all other cases, a dynamic error occurs (see below).
A dynamic error is raised [err:XPDY0002]^{XP30} by the zeroargument version of the function if the context item is absent^{DM30}.
A type error is raised [err:FOTY0014] if
$arg
is a function item (this includes maps and arrays).
Every node has a string value, even an element with elementonly content (which has no typed value). Moreover, casting an atomic value to a string always succeeds. Functions, maps, and arrays have no string value, so these are the only arguments that satisfy the type signature but cause failure.
The expression string(23)
returns "23"
.
The expression string(false())
returns "false"
.
The expression string("Paris")
returns "Paris"
.
The expression string((1, 2, 3))
raises error XPTY0004
.
The expression string([[1, 2], [3, 4]])
raises error FOTY0014
.
The expression string(abs#1)
raises error FOTY0014
.
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*
The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
5.15 typedvalue Accessor
^{DM30}).
If the item is an array, the result of applying fn:data
to
each member of the array, in order, is appended to the result sequence.
A type error is raised [err:FOTY0012] if an item in the
sequence $arg
is a node that does not have a typed value.
A type error is raised [err:FOTY0013] if an item in
the sequence $arg
is a function item other than
an array.
A dynamic error is raised if $arg
is omitted and the context item is
absent^{DM30}.
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.
The expression data(123)
returns 123
.
The expression data((123, 456))
returns 123, 456
.
The expression data([[1,2],[3,4]])
returns 1, 2, 3, 4
.
let $para
:=
<para>In a hole in the ground there lived a <term author="Tolkein">hobbit</term>.</para>
The expression data($para)
returns xs:untypedAtomic("In a hole in the ground there lived a
hobbit.")
.
The expression data($para/term/@author)
returns xs:untypedAtomic("Tolkein")
.
The expression data(abs#1)
raises error FOTY0013
.
Returns the base URI of a node.
fn:baseuri
() as
xs:anyURI?
fn:baseuri
($arg
as
node()?
) as
xs:anyURI?
The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The zeroargument version of the function returns the base URI of the context node: it
is equivalent to calling fn:baseuri(.)
.
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
5.2 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
.
The following errors may be raised when $arg
is omitted:
If the context item is absent^{DM30}, dynamic error [err:XPDY0002]^{XP30}
If the context item is not a node, type error [err:XPTY0004]^{XP30}.
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?
The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
6.1.2 Accessors
^{DM30}).
The following errors may be raised when $arg
is omitted:
If the context item is absent^{DM30}, dynamic error [err:XPDY0002]^{XP30}
If the context item is not a node, type error [err:XPTY0004]^{XP30}.
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.1: An XML Query Language] and [XML Path Language (XPath) 3.1],
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
^{XP31}.
The fn:error
function is a general function that may be called as above
but may also be called from [XQuery 3.1: An XML Query Language] or [XML Path Language (XPath) 3.1]
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 is ·nondeterministic·, ·contextindependent·, and ·focusindependent·.
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 ·implementationdependent·.
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.
If no value is supplied for the $code
argument (that is,
if the function is called with no arguments or if the first argument is an empty sequence),
the effective value of the error code is fn:QName('http://www.w3.org/2005/xqterrors', 'err:FOER0000')
.
The $description
is a naturallanguage description of the error
condition.
If no value is supplied for the $description
argument (that is, if the function is called with less than two arguments), then the
effective value of the description is ·implementationdependent·.
The $errorobject
is an arbitrary value used to convey additional
information about the error, and may be used in any way the application
chooses.
If no value is supplied for the $errorobject
argument (that is, if the function is called with less than three arguments), then the
effective value of the error object is ·implementationdependent·.
This function always raises a dynamic error. By default, it raises [err:FOER0000]
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.
Any QName may be used as an error code; there are no reserved names or namespaces. The error is always classified as a dynamic error, even if the error code used is one that is normally used for static errors or type errors.
The expression fn:error()
raises error FOER0000
. (This returns the URI
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.).
The expression fn:error(fn:QName('http://www.example.com/HR', 'myerr:toohighsal'),
'Does not apply because salary is too high')
raises error myerr:toohighsal
. (This 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()*
) as
item()*
fn:trace
($value
as
item()*
, $label
as
xs:string
) as
item()*
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The function returns the value of $value
, unchanged.
In addition, the values of $value
, converted to an xs:string
,
and $label
(if supplied)
may be directed to a trace data set. The destination of the trace
output is ·implementationdefined·. The format of the trace output is
·implementationdependent·. The ordering of output from calls of the
fn:trace
function is ·implementationdependent·.
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 atomic 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.
The type xs:numeric
is defined as a union type whose member types are
(in order) xs:double
, xs:float
, and xs:decimal
. This type is implicitly imported
into the static context, so it can also be used in defining the signature of userwritten functions. Apart from the fact that
it is implicitly imported, it behaves exactly like a userdefined type with the same definition. This means, for example:
If the expected type of a function parameter is given as xs:numeric
, the actual value supplied
can be an instance of any of these three types, or any type derived from these three by restriction (this includes the builtin
type xs:integer
, which is derived from xs:decimal
).
If the expected type of a function parameter is given as xs:numeric
, and the actual value supplied
is xs:untypedAtomic
(or a node whose atomized value is xs:untypedAtomic
), then it will
be cast to the union type xs:numeric
using the rules in 19.3.5 Casting to union types.
Because the lexical space of xs:double
subsumes the lexical space of the other member types, and
xs:double
is listed first, the effect is that if the untyped atomic value is in the lexical space of
xs:double
, it will be converted to an xs:double
, and if not, a dynamic error occurs.
When the return type of a function is given as xs:numeric
, the actual value returned will be
an instance of one of the three member types (and perhaps also of types derived from these by restriction). The rules
for the particular function will specify how the type of the result depends on the values supplied as arguments.
In many cases, for the functions in this specification, the result is defined to be the same type as the first
argument.
Note:
This specification uses [IEEE 7542008] 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 7542008]. 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 7542008]
semantics for comparisons involving NaN
.
The following functions define the semantics of arithmetic operators defined in [XQuery 3.1: An XML Query Language] and [XML Path Language (XPath) 3.1] 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 in most cases declared to be of type
xs:numeric
, which permits the basic numeric
types: xs:integer
, xs:decimal
, xs:float
and xs:double
, and types derived from them.
In general the twoargument functions require that both arguments are of the same primitive type,
and they return a value of this 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 of an arithmetic expression 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 ^{XP31} and Section B.2 Operator Mapping ^{XP31} 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 7542008]. 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 7542008]. This specification allows the following options:
Raising a dynamic 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 7542008]. This specification allows the following options:
Raising a dynamic 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 a dynamic 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 a dynamic 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 call a function with 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 when applied to two numeric values
op:numericadd
($arg1
as
xs:numeric
, $arg2
as
xs:numeric
) as
xs: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 when applied to two numeric values.
op:numericsubtract
($arg1
as
xs:numeric
, $arg2
as
xs:numeric
) as
xs: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 when applied to two numeric values.
op:numericmultiply
($arg1
as
xs:numeric
, $arg2
as
xs:numeric
) as
xs: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 when applied to two numeric values.
op:numericdivide
($arg1
as
xs:numeric
, $arg2
as
xs:numeric
) as
xs: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
.
A dynamic error is raised [err:FOAR0001] for xs:decimal
and xs:integer
operands, if the divisor is (positive or negative) zero.
For xs:float
and xs:double
operands, floating point division
is performed as specified in [IEEE 7542008]. 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 when applied to two numeric values.
op:numericintegerdivide (  $arg1  as xs:numeric , 
$arg2  as xs: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.
A dynamic error is raised [err:FOAR0001] if the divisor is (positive or negative) zero.
A dynamic error is raised [err:FOAR0002] if either operand is
NaN
or if $arg1
is INF
or
INF
.
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 when applied to two numeric values.
op:numericmod
($arg1
as
xs:numeric
, $arg2
as
xs:numeric
) as
xs: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 7542008] rounding division i.e. additional digits are truncated,
not rounded to the required precision.
A dynamic error is raised [err:FOAR0001] for xs:integer
and xs:decimal
operands, if $arg2
is zero.
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 a numeric value.
op:numericunaryplus
($arg
as
xs:numeric
) as
xs: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
.
Because function conversion rules are applied in the normal way, the unary
+
operator can be used to force conversion of an untyped node to a
number: the result of +@price
is the same as xs:double(@price)
if the type of @price
is xs:untypedAtomic
.
Returns its operand with the sign reversed: ( $arg
).
Defines the semantics of the unary "" operator when applied to a numeric value.
op:numericunaryminus
($arg
as
xs:numeric
) as
xs: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 when applied to two numeric values, and is also used in defining the semantics of "ne", "le" and "ge".
op:numericequal
($arg1
as
xs:numeric
, $arg2
as
xs: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 when applied to two numeric values, and is also used in defining the semantics of "le".
op:numericlessthan
($arg1
as
xs:numeric
, $arg2
as
xs: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 when applied to two numeric values, and is also used in defining the semantics of "ge".
op:numericgreaterthan
($arg1
as
xs:numeric
, $arg2
as
xs: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
xs:numeric?
) as
xs:numeric?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
General rules: see 4.4 Functions on numeric values.
If $arg
is negative the function returns $arg
, otherwise it
returns $arg
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $arg
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example, if
$arg
is an instance of xs:positiveInteger
then the value of
$arg
may be returned unchanged.
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.
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
xs:numeric?
) as
xs:numeric?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $arg
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example, if
$arg
is an instance of xs:decimal
then the result may
be an instance of xs:integer
.
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.
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
xs:numeric?
) as
xs:numeric?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $arg
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example, if
$arg
is an instance of xs:decimal
then the result may
be an instance of xs:integer
.
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.
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
xs:numeric?
) as
xs:numeric?
fn:round
($arg
as
xs:numeric?
, $precision
as
xs:integer
) as
xs:numeric?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $arg
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example, if
$arg
is an instance of xs:decimal
and $precision
is less than one,
then the result may
be an instance of xs:integer
.
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
.
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 xs:double
written as 35.425e0 has an exact value equal to 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
xs:numeric?
) as
xs:numeric?
fn:roundhalftoeven (  $arg  as xs:numeric? , 
$precision  as xs:integer ) as xs:numeric? 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $arg
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example, if
$arg
is an instance of xs:decimal
and $precision
is less than one, then the result may
be an instance of xs:integer
.
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.
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
.
It is possible to convert strings to values of type xs:integer
,
xs:float
, xs:decimal
, or xs:double
using the constructor functions described in 18 Constructor functions
or using cast
expressions as described in 19 Casting.
In addition the fn:number
function is available to convert strings
to values of type xs:double
. It differs from the xs:double
constructor function in that any value outside the lexical space of the xs:double
datatype is converted to the xs:double
value NaN
.
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
The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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(.)
, as defined by
the rules that follow.
If $arg
is the empty sequence or if $arg
cannot be converted
to an xs:double
, the xs:double
value NaN
is
returned.
Otherwise, $arg
is converted to an xs:double
following the
rules of 19.1.2.2 Casting to xs:double. If the conversion to xs:double
fails, the xs:double
value NaN
is returned.
A dynamic error is raised [err:XPDY0002]^{XP30}
if $arg
is omitted and the context item is absent^{DM30}.
As a consequence of the rules given above, a type error occurs if the context item cannot be atomized, or if the result of atomizing the context item is a sequence containing more than one atomic value.
XSD 1.1 allows the string +INF
as a representation of positive infinity;
XSD 1.0 does not. It is ·implementationdefined· whether XSD 1.1 is
supported.
Generally fn:number
returns NaN
rather than raising a dynamic
error if the argument cannot be converted to xs:double
. However, a type
error is raised in the usual way if the supplied argument cannot be atomized or if the
result of atomization does not match the required argument type.
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
.
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 ,  
$lang  as xs:string? ) as xs:string 
The twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on default language.
The threeargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 a minus sign is prepended to the result.
The value of $picture
consists of a primary format token, optionally
followed by a format modifier. The primary format token is always present and
must not be zerolength. If the string contains one or more
semicolons then everything that precedes the last semicolon is taken as the primary
format token and everything that follows is taken as the format modifier; if the string
contains no semicolon then the entire picture is taken as the primary format token, and
the format modifier is taken to be absent (which is equivalent to supplying a
zerolength string).
The primary format token is classified as one of the following:
A decimaldigitpattern made up of optionaldigitsigns, mandatorydigitsigns, and groupingseparatorsigns.
The 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.
If the primary format token contains at least one Unicode digit then it is taken
as a decimal digit pattern, and in this case it must match the
regular expression ^((\p{Nd}#[^\p{N}\p{L}])+?)$
. If it contains a
digit but does not match this pattern, a dynamic error is raised [err:FODF1310].
Note:
If a semicolon is to be used as a grouping separator, then the primary format token as a whole must be followed by another semicolon, to ensure that the grouping separator is not mistaken as a separator between the primary format token and the format modifier.
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.
The format token A
, which generates the sequence A B C ... Z AA
AB AC...
.
The format token a
, which generates the sequence a b c ... z aa
ab ac...
.
The format token i
, which generates the sequence i ii iii iv v
vi vii viii ix x ...
.
The format token I
, which generates the sequence I II III IV V
VI VII VIII IX X ...
.
The format token w
, which generates numbers written as lowercase
words, for example in English, one two three four ...
The format token W
, which generates numbers written as uppercase
words, for example in English, ONE TWO THREE FOUR ...
The format token Ww
, which generates numbers written as titlecase
words, for example in English, One Two Three Four ...
Any other format token, which 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 (x0374, ʹ) and sometimes an aristeri keraia (x0375, ͵) 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 imposed by the Unicode character repertoire — 1 to 20
in Unicode versions prior to 4.0, increased in subsequent versions. 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 $lang
argument specifies which
language's conventions are to be used. If the argument is specified, the value
should be either an empty sequence or a value that would be valid
for the xml:lang
attribute (see [Extensible Markup Language (XML) 1.0 (Fifth Edition)]). Note that this
permits the identification of sublanguages based on country codes (from ISO 31661) as
well as identification of dialects and regions within a country.
The set of languages for which numbering is supported is ·implementationdefined·. If the $lang
argument is absent, or is
set to an empty sequence, or is invalid, or is not a language supported by the
implementation, then the number is formatted using the default language from the dynamic
context.
The format modifier must be a string that matches the regular
expression ^([co](\(.+\))?)?[at]?$
. That is, if it is present it must
consist of one or more of the following, in 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 ...
.
The string of characters between the parentheses, if present, is used to select between other possible variations of cardinal or ordinal numbering sequences. The interpretation of this string is ·implementationdefined·. No error occurs if the implementation does not define any interpretation for the defined string.
For example, in some languages, ordinal numbers vary depending on the grammatical
context: 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
recommended 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 "1;o(º)"
with $lang
equal to
it
, if supported, should produce the sequence:
1º 2º 3º 4º ...
The specification "Ww;o"
with $lang
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·.
A dynamic error is raised [err:FODF1310] if the format token is invalid, that is, if it violates any mandatory rules (indicated by an emphasized must or required keyword in the above rules). For example, the error is raised if the primary format token contains a digit but does not match the required regular expression.
Note the careful distinction between conditions that are errors and conditions where fallback occurs. The principle is that an error in the syntax of the format picture will be reported by all processors, while a construct that is recognized by some implementations but not others will never result in an error, but will instead cause a fallback representation of the integer to be used.
The expression formatinteger(123, '0000')
returns "0123"
.
formatinteger(123, 'w')
might return "one hundred and
twentythree"
The expression formatinteger(21, '1;o', 'en')
returns "21st"
.
formatinteger(14, 'Ww;o(e)', 'de')
might return
"Vierzehnte"
The expression formatinteger(7, 'a')
returns "g"
.
The expression formatinteger(57, 'I')
returns "LVII"
.
The expression formatinteger(1234, '#;##0;')
returns "1;234"
.
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 properties, 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 
exponentseparatorsign  A single ·character·  Defines the character used to separate the mantissa from the exponent in scientific notation (typically "e") 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  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 a character in Unicode category Nd with decimal digit value 0 (zero)  Defines the characters used in the picture string to represent a mandatory digit: for example, if the mandatorydigitsign is "0" then any of the digits "0" to "9" may be used (interchangeably) in the picture string to represent a mandatory digit, and in the formatted number the characters "0" to "9" will be 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  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 properties representing characters used in a ·picture string· must have distinct values. These properties are decimalseparatorsign, groupingseparatorsign, exponentseparatorsign, percentsign, permillesign, optionaldigitsign, and patternseparatorsign. Furthermore, none of these properties 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
xs:numeric?
, $picture
as
xs:string
) as
xs:string
fn:formatnumber (  $value  as xs:numeric? , 
$picture  as xs:string ,  
$decimalformatname  as xs:string? ) as xs:string 
The twoargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The threeargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on decimal formats, and namespaces.
The effect of the twoargument form of the function is equivalent to calling the threeargument form with an empty sequence as the value of the third argument.
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.7.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
, if present and nonempty,
must be a string which after removal of leading and trailing
whitespace is in the form of an an EQName
as defined in the XPath 3.0
grammar, that is one of the following:
A lexical QName, which is expanded using the statically known namespaces. The default namespace is not used (no prefix means no namespace).
A URIQualifiedName
using the syntax Q{uri}local
, where
the URI can be zerolength to indicate a name in no namespace.
The decimal format that is used is the decimal format in the static context whose name
matches $decimalformatname
if supplied, or the default decimal format in
the static context otherwise.
The evaluation of the formatnumber
function takes place in two
phases, an analysis phase described in 4.7.4 Analysing the picture string and a
formatting phase described in 4.7.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.
A dynamic error is raised [err:FODF1280] if the name specified as
the $decimalformatname
argument is neither a valid lexical QName nor a
valid URIQualifiedName
, or if it uses a prefix that is not found in the
statically known namespaces, 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.
The following examples assume a default decimal format in which the chosen digits are the ASCII digits 09, the decimal separator is ".", the grouping separator is ",", the minussign is "", and the percentsign is "%".
The expression formatnumber(12345.6, '#,###.00')
returns "12,345.60"
.
The expression formatnumber(12345678.9, '9,999.99')
returns "12,345,678.90"
.
The expression formatnumber(123.9, '9999')
returns "0124"
.
The expression formatnumber(0.14, '01%')
returns "14%"
.
The expression formatnumber(6, '000')
returns "006"
.
The following example assumes the existence of a decimal format named 'ch' in which
the grouping separator is ʹ
and the decimal separator is
·
:
The expression formatnumber(1234.5678, '#ʹ##0·00',
'ch')
returns "1ʹ234·57"
.
The following example assumes that the exponent separator is 'E':
The expression formatnumber(1234.5678, '00.000E0')
returns "12.569E2"
.
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. The digits used must all be from the same decimal digit family,
specifically, the sequence of ten consecutive digits starting with the mandatorydigitsign.
This change 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 properties decimalseparatorsign, exponentseparatorsign, groupingsign, decimaldigitfamily, optionaldigitsign and patternseparatorsign are classified as active characters, and all other characters (including the percentsign and permillesign) are classified as passive characters.
A dynamic 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.
A character that matches the chosen exponentseparatorsign is treated as an exponentseparatorsign if it is both preceded and followed within the subpicture by an active character. Otherwise, it is treated as a passive character. A subpicture must not contain more than one character that is treated as an exponentseparatorsign.
A subpicture that contains a percentsign or permillesign must not contain a character treated as an exponentseparatorsign.
If a subpicture contains a character treated as an exponentseparatorsign then this must be followed by one or more characters that are members of the decimaldigitfamily, and it must not be followed by any active character that is not a member of the decimaldigitfamily.
The mantissa part of the subpicture is defined as the part that appears to the left of the exponentseparatorsign if there is one, or the entire subpicture otherwise. The exponent part of the subpicture is defined as the part that appears to the right of the exponentseparatorsign; if there is no exponentseparatorsign then the exponent part is absent.
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 mantissa part otherwise. The fractional part of the subpicture is defined as that part of the mantissa part that appears to the right of the decimalseparatorsign if there is one, or the part that appears to the right of the rightmost active character otherwise. The fractional part may be zerolength.
This phase of the algorithm analyses the ·picture string· and the properties 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.
Note:
There is no need to extrapolate grouping positions on the fractional side, because the number of digits in the output will never exceed the number of optionaldigitsign and decimaldigitfamily in the fractional part of the subpicture.
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 minimumexponentsize is set to the number of decimaldigitfamily characters found in the exponent part of the subpicture if present, or zero otherwise.
The suffix is set to contain all passive characters to the right of the rightmost active character in 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
fn: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 fn: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.
If the minimum exponent size is nonzero, then the adjusted number is scaled to establish a mantissa and an integer exponent. The mantissa and exponent are chosen such that (a) the primitive type of the mantissa is the same as the primitive type of the adjusted number (integer, decimal, float, or double), (b) the mantissa multiplied by ten to the power of the exponent is equal to the adjusted number, and (c) the number of significant digits in the integer part of the mantissa is equal to the minimum integer part size.
If the minimum exponent size is zero, then the mantissa is the adjusted number and there is no exponent.
The mantissa 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 mantissa (bearing in mind that if the
mantissa 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 mantissa 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).
If an exponent exists, then the string produced from the mantissa as described above is extended with the following, in order: (a) the exponent separator sign; (b) if the exponent is negative, the minus sign; (c) the value of the exponent represented as a decimal integer, extended if necessary with leading zeroes to make it up to the minimum exponent size, using digits taken from the decimal digit family.
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 math: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.
IEEE defines various rounding algorithms for inexact results, and states that the choice of rounding direction, and the mechanisms for influencing this choice, are languagedefined. In this specification, the rounding direction and any mechanisms for influencing it are ·implementationdefined·.
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 is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
If $arg
is the empty sequence, the function returns the empty sequence.
Otherwise the result is 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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
xs:numeric
) as
xs:double?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
If $arg
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the mathematical nonnegative 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:sqrt(xs:double('NaN'))
returns xs:double('NaN')
.
The expression math:sqrt(xs:double('INF'))
returns xs:double('INF')
.
The expression math:sqrt(xs:double('INF'))
returns xs:double('NaN')
.
Returns the sine of the argument, expressed in radians.
math:sin
($
θ as
xs:double?
) as
xs:double?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
(approximately).
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
(approximately).
The expression math:cos(math:pi() div 2)
returns 0.0e0
(approximately).
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
(approximately).
The expression math:tan(math:pi() div 4)
returns 1.0e0
(approximately).
The expression math:tan(math:pi() div 2)
returns 1.633123935319537E16
(approximately).
The expression math:tan(math:pi() div 2)
returns 1.633123935319537E16
(approximately).
The expression math:tan(math:pi())
returns 0.0e0
(approximately).
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
(approximately).
The expression math:asin(1.0e0)
returns 1.5707963267948966e0
(approximately).
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
(approximately).
The expression math:acos(0.0e0)
returns 1.5707963267948966e0
(approximately).
The expression math:acos(1.0e0)
returns 0.0e0
.
The expression math:acos(1.0e0)
returns 3.141592653589793e0
(approximately).
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
(approximately).
The expression math:atan(1.0e0)
returns 0.7853981633974483e0
(approximately).
The expression math:atan(xs:double('NaN'))
returns xs:double('NaN')
.
The expression math:atan(xs:double('INF'))
returns 1.5707963267948966e0
(approximately).
The expression math:atan(xs:double('INF'))
returns 1.5707963267948966e0
(approximately).
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
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 either argument is NaN
then the result is NaN
.
If $y
is positive and $x
is positive and finite, then (subject
to rules for overflow, underflow and approximation) the value of atan2($y,
$x)
is atan($y div $x)
.
If $y
is positive and $x
is negative and finite, then (subject
to the same caveats) the value of atan2($y, $x)
is π
 atan($y div $x)
.
Some results for special values of the arguments are shown in the examples below.
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
.
Returns a random number generator, which can be used to generate sequences of random numbers.
fn:randomnumbergenerator
() as
map(xs:string, item())
fn:randomnumbergenerator (  $seed  as xs:anyAtomicType ) as map(xs:string, item()) 
The function returns a random number generator. A random number generator is represented as a map containing three entries. The keys of each entry are strings:
The entry with key "number"
holds a random number; it is an xs:double
greater than or equal
to zero (0.0e0), and less than one (1.0e0).
The entry with key "next"
is a zeroarity function that can be called to return another random number
generator.
The entry with key "permute"
is a function with arity 1 (one), which takes an arbitrary sequence
as its argument, and returns a random permutation of that sequence.
Calling the fn:randomnumbergenerator
function with no arguments is equivalent to calling the singleargument
form of the function with an implementationdependent seed.
If a $seed
is supplied, it may be an atomic value of any type.
Both forms of the function are ·deterministic·: calling the function twice with the same arguments, within a single ·execution scope·, produces the same results.
The value of the number
entry should be such that all eligible xs:double
values are equally likely to be chosen.
The function returned in the permute
entry should be such that all permutations
of the supplied sequence are equally likely to be chosen.
The map returned by the randomnumbergenerator
function may contain additional entries beyond
those specified here, but it must match the type map(xs:string, item())
. The meaning of any additional entries
is ·implementationdefined·. To avoid conflict with any future version of this specification, the keys of any
such entries should start with an underscore character.
It is not meaningful to ask whether the functions returned in the next
and permute
functions resulting from two separate calls with the same seed are "the same function", but the functions must be equivalent in the sense
that calling them produces the same sequence of random numbers.
The repeatability of the results of function calls in different execution scopes is outside the scope of this
specification. It is recommended that when the same seed is provided explicitly, the same random number sequence
should be delivered even in different execution scopes; while if no seed is provided, the processor should choose a seed
that is likely to be different from one execution scope to another. (The same effect can be achieved explicitly by using
fn:currentdateTime()
as a seed.)
The specification does not place strong conformance requirements on the actual randomness of the result; this is left to the implementation. It is desirable, for example, when generating a sequence of random numbers that the sequence should not get into a repeating loop; but the specification does not attempt to dictate this.
The following example returns a random permutation of the integers in the range 1 to 100:
fn:randomnumbergenerator()?permute(1 to 100)
The following example returns a 10% sample of the items in an input sequence $seq
, chosen at random:
fn:randomnumbergenerator()?permute($seq)[position() = 1 to (count($seq) idiv 10)]
The following code defines a function that can be called to produce a random sequence of xs:double
values in the range zero to one, of specified length:
declare %public function r:randomsequence($length as xs:integer) as xs:double* { r:randomsequence($length, fn:randomnumbergenerator()) }; declare %private function r:randomsequence($length as xs:integer, $G as map(xs:string, item())) { if ($length eq 0) then () else ($G?number, r:randomsequence($length  1, $G?next()) }; r:randomsequence(200);
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
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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.
A dynamic error is raised [err:FOCH0001] if any of the codepoints in
$arg
is not a permitted XML character.
The expression fn:codepointstostring((66, 65, 67, 72))
returns "BACH"
.
The expression fn:codepointstostring((2309, 2358, 2378, 2325))
returns "अशॊक"
.
The expression fn:codepointstostring(())
returns ""
.
The expression fn:codepointstostring(0)
raises error FOCH0001
.
Returns the sequence of ·codepoints· that constitute an
xs:string
value.
fn:stringtocodepoints
($arg
as
xs:string?
) as
xs:integer*
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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. 
fn:collationkey  Given a string value and a collation, generates an internal value called a collation key, with the property that the matching and ordering of collation keys reflects the matching and ordering of strings under the specified collation. 
fn:containstoken  Determines whether or not any of the supplied strings, when tokenized at whitespace boundaries, contains the supplied token, under the rules of the supplied collation. 
A collation is a specification of the manner in which ·strings· are
compared and, by extension, ordered. When values whose type is
xs:string
or a type derived from xs:string
are
compared (or, equivalently, sorted), the comparisons are inherently
performed according to some collation (even if that collation is defined
entirely on 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.
Collations may or may not perform Unicode normalization on strings before comparing them.
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 reference,
it is resolved relative to the value of the
Static Base URI property from 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 ^{XP31}. 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.
This specification defines a family of collation URIs representing tailorings of the Unicode Collation Algorithm (UCA) as defined in [UNICODE TR10]. The parameters used for tailoring the UCA are based on the parameters defined in the Locale Data Markup Language (LDML), defined in [UNICODE TR35].
This family of URIs use the scheme and path http://www.w3.org/2013/collation/UCA
followed by an optional query part. The query part, if present, consists of a question mark followed
by a sequence of zero or more semicolonseparated parameters. Each parameter is a keywordvalue pair, the
keyword and value being separated by an equals sign.
All implementations must recognize URIs in this family in the collation
argument of functions that
take a collation argument.
If the fallback
parameter is
present with the value no
, then the implementation must either use a collation that conforms with
the rules in the Unicode specifications for the requested tailoring, or fail with a static or dynamic error indicating that it
does not provide the collation (the error code should be the same as if the collation URI were not recognized).
If the fallback
parameter
is omitted or takes the value yes
, and if the collation URI is wellformed according to the rules in this section,
then the implementation must accept the collation URI, and should use the available
collation that most closely reflects the user's intentions. For example, if the collation URI requested is
http://www.w3.org/2013/collation/UCA?lang=se;fallback=yes
and the implementation does not include a fully
conformant version of the UCA tailored for Swedish, then it may choose to use a Swedish collation that is known to differ
from the UCA definition, or one whose conformance has not been established. It might even, as a last resort, fall back to using
codepoint collation.
If two query parameters use the same keyword then the last one wins. If a query parameter uses a keyword or value which is not
defined in this specification then the meaning is ·implementationdefined·. If the implementation recognizes
the meaning of the keyword and value then it should interpret it accordingly; if it does not recognize
the keyword or value then if the fallback
parameter is present with the value no
it should reject
the collation as unsupported, otherwise it should ignore the unrecognized parameter.
The following query parameters are defined. If any parameter is absent, the default is ·implementationdefined· except where otherwise stated. The meaning given for each parameter is nonnormative; the normative specification is found in [UNICODE TR35].
Keyword  Values  Meaning 

fallback  yes  no (default yes)  Determines whether the processor uses a fallback collation if a conformant collation is not available. 
lang  language code, as defined for the lang attribute of xsl:sort  The language whose collation conventions are to be used. 
version  string  The version number of the UCA to be used. 
strength  primary  secondary  tertiary  quaternary  identical, or 12345 as synonyms  The collation strength as defined in UCA. Primary
strength takes only the base form of the character into account (so A=a=Ä=ä); secondary strength ignores case but considers accents
and diacritics as significant (so A=a and √Ç=√¢ but √¢!=a); tertiary considers case as significant (A!=a!=√Ç!=√¢); quaternary considers
spaces and punctuation that would otherwise be ignored (for example database =database ). 
alternate  nonignorable  shifted  blanked  Controls the effect of characters such as spaces and hyphens. 
backwards  yes  no  The value backwards=yes indicates that the last accent in the search term is the most significant. 
normalization  yes  no  Indicates whether search terms are converted to normalization form D. 
caseLevel  yes  no  When used with primary strength, setting caseLevel=yes has the effect of ignoring accents
while taking account of case. 
caseFirst  upper  lower  Indicates whether uppercase precedes lowercase or vice versa. 
hiraganaQuaternary  yes  no  Controls special treatment of Hiragana codepoints when strength is quaternary or greater. 
numeric  yes  no  When numeric=yes is specified, a sequence of consecutive digits is interpreted as a number,
for example chap2 sorts before chap12 . 
reorder  a commaseparated sequence of reorder codes, where a reorder code is one of space , punct ,
symbol , currency , digit , or a fourletter script code defined in [ISO 15924 Register], the register
of scripts maintained by the Unicode Consortium in its capacity as registration authority for [ISO 15924].  Determines the relative ordering of text in different scripts; for example the value digit,Grek,Latn indicates
that digits precede Greek letters, which precede Latin letters. 
Note:
This list excludes parameters that are inconvenient to express in a URI, or that are applicable only to substring matching.
The collation URI http://www.w3.org/2005/xpathfunctions/collation/htmlasciicaseinsensitive
must be recognized
by every implementation. It is used
to refer to the HTML ASCII caseinsensitive collation as defined in [HTML5] (section 2.5, Case sensitivity and
string comparison). It is used, for example, when matching HTML class
attribute values.
Note:
The definition of the collation is paraphrased here for convenience:
Comparing two strings in an ASCII caseinsensitive manner means comparing them exactly, codepoint for codepoint, except that the characters in the range x41 to x5A (AZ) and the corresponding characters in the range x61 to x7A (az) are considered to also match.
HTML5 defines the semantics of equality matching using this collation; it does not define rules for ordering. If the collation
is used for ordering, the results are ·implementationdefined·. The collation supports collation units and can therefore
be used with functions such as fn:contains
; each Unicode codepoint is a single collation unit.
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, a dynamic 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, a dynamic 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.
If the value of the collation argument is a relative URI reference, it is resolved against the baseURI from the static context. If it is a relative URI reference and cannot be resolved, perhaps because the baseURI property in the static context is absent, a dynamic error is raised [err:FOCH0002].
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? 
The twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations.
The threeargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and static base uri.
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.5 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? 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 expression fn:codepointequal("abcd", "abcd")
returns true()
.
The expression fn:codepointequal("abcd", "abcd ")
returns false()
.
The expression fn:codepointequal("", "")
returns true()
.
The expression fn:codepointequal("", ())
returns ()
.
The expression fn:codepointequal((), ())
returns ()
.
Given a string value and a collation, generates an internal value called a collation key, with the property that the matching and ordering of collation keys reflects the matching and ordering of strings under the specified collation.
fn:collationkey
($key
as
xs:string
) as
xs:anyAtomicType
fn:collationkey (  $key  as xs:string , 
$collation  as xs:string ) as xs:anyAtomicType 
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations.
Calling the oneargument version of this function is equivalent to calling the twoargument version supplying the default collation as the second argument.
The function returns an ·implementation dependent· value with property that,
for any two strings $K1
and $K2
:
collationkey($K1, $C) eq collationkey($K2, $C)
if and only if
compare($K1, $K2, $C) eq 0
collationkey($K1, $C) lt collationkey($K2, $C)
if and only if
compare($K1, $K2, $C) lt 0
If the collation URI is a relative reference, it is resolved against the static base URI.
An implementation is free to generate a collation key in any convenient way provided that it always generates the same collation key for two strings that are equal under the collation, and different collation keys for strings that are not equal. This holds only within a single execution scope^{FO30}; an implementation is under no obligation to generate the same collation keys during a subsequent unrelated query or transformation.
It is possible to define collations that do not have the ability to generate collation keys. Supplying such a collation will cause the function to fail. The ability to generate collation keys is an ·implementationdefined· property of the collation.
An error is raised [err:FOCH0004]^{FO30} if the specified collation does not support the generation of collation keys.
The function is provided primarily for use with maps. If a map is required where
codepoint equality is inappropriate for comparing keys, then a common technique is to
normalize the key so that equality matching becomes feasible. There are many ways
keys can be normalized, for example by use of functions such as
fn:uppercase
, fn:lowercase
,
fn:normalizespace
, or fn:normalizeunicode
, but this
function provides a way of normalizing them according to the rules of a specified
collation. For example, if the collation ignores accents, then the function will
generate the same collation key for two input strings that differ only in their use of
accents.
The result of the function can be of any atomic type that permits ordering.
For collations based on the Unicode Collation Algorithm, an algorithm for computing
collation keys is provided in [UNICODE TR10]. This algorithm generates
binary collation keys, which might be materialized as a value of type
xs:hexBinary
or xs:base64Binary
. Implementations are
not required to use this algorithm.
This specification does not mandate that collation keys should retain ordering. This is partly because the primary use case is for maps, where only equality comparisons are required, and partly to allow the use of binary data types (which are currently unordered types) for the result. The specification may be revised in a future release to specify that ordering is preserved.
The fact that collation keys are ordered can be exploited in XQuery, whose order by
clause does not allow the collation to be selected dynamically. This restriction can be circumvented
by rewriting the clause order by $e/@key collation "URI"
as order by fn:collationkey($e/@key, $collation)
,
where $collation
allows the collation to be chosen dynamically.
Note that xs:base64Binary
and xs:hexBinary
become ordered types
in XPath 3.1, making binary collation keys possible.
let $C
:=
"http://www.w3.org/2005/xpathfunctions/collations/UCA?strength=primary"
The expression map:merge((map{collationkey("A", $C):1}, map{collationkey("a",
$C):2}))(collationkey("A", $C))
returns 2
. (Given that the keys of the two entries are equal under the rules of
the chosen collation, only one of the entries can appear in the result; the one
that is chosen is the one from the last map in the input sequence.).
The expression let $M : map{collationkey("A", $C):1, collationkey("B", $C):2}
return $M(collationkey("a", $C))
returns 1
. (The strings "A" and "a" have the same collation key under this
collation.).
As the above examples illustrate, it is important that when the
collationkey
function is used to add entries to a map, then it must
also be used when retrieving entries from the map. This process can be made less
errorprone by encapsulating the map within a function: function($k)
{$M(collationkey($k, $collation)}
.
Determines whether or not any of the supplied strings, when tokenized at whitespace boundaries, contains the supplied token, under the rules of the supplied collation.
fn:containstoken
($input
as
xs:string*
, $token
as
xs:string
) as
xs:boolean
fn:containstoken (  $input  as xs:string* , 
$token  as xs:string ,  
$collation  as xs:string ) as xs:boolean 
The twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations.
The threeargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and static base uri.
If $input
is the empty sequence, the function returns false
.
Leading and trailing whitespace is trimmed from the supplied value of $token
. If the trimmed value of $token
is a zerolength string, the function returns false
.
The collation used by this function is determined according to the rules in 5.3.5 Choosing a collation.
The function returns true if and only if there is string in $input
which,
after tokenizing at whitespace boundaries, contains a token
that is equal to the trimmed value of $token
under
the rules of the selected collation.
That is, the function returns the value of the expression:
some $t in $input!fn:tokenize(.) satisfies compare($t, fn:replace($token, '^\s*\s*$', ''), $collation) eq 0)
Interior whitespace within $token
will cause the function to return false
,
unless such whitespace is ignored by the selected collation.
This function can be used for processing spaceseparated attribute values (for example, the XHTML and DITA class attribute), where one often needs to test for the presence of a single token in a spaceseparated list. The function is designed to work both when the attribute has been validated against an XSD list type, and when it appears as a single untyped string. It differs from the HTML 5 definition in that HTML 5 recognizes form feed (x0C) as a separator. To reproduce the HTML token matching behavior, the HTML ASCII caseinsensitive collation should be used: see 5.3.4 The HTML ASCII CaseInsensitive Collation.
The expression fn:containstoken("red green blue ", "red")
returns true()
.
The expression fn:containstoken(("red", "green", "blue"), " red ")
returns true()
.
The expression fn:containstoken("red, green, blue", "red")
returns false()
.
The expression fn:containstoken("red green blue", "RED", "http://www.w3.org/2005/xpathfunctions/collation/htmlasciicaseinsensitive")
returns true()
.
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.
The twoargument form of this function defines the semantics of the "" operator.
fn:concat (  $arg1  as xs:anyAtomicType? , 
$arg2  as xs:anyAtomicType? ,  
...  ) as xs:string 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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!"
.
The expression fn:concat(01, 02, 03, 04, true())
returns "1234true"
.
The expression 10  '/'  6
returns "10/6"
.
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
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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^{DM30}, a dynamic error is raised: [err:XPDY0002]^{XP30}.
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
The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 [Extensible Markup Language (XML) 1.0 (Fifth Edition)].
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^{DM30} then a dynamic error is raised: [err:XPDY0002]^{XP30}.
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 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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))
.
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 Normalization 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 Normalization 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 Normalization 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.
It is ·implementationdefined· which
version of Unicode (and therefore, of the normalization algorithms and their underlying
data) is supported by the implementation. See [Unicode Normalization Forms] for
details of the stability policy regarding changes to the normalization rules in future
versions of Unicode. If the input string contains codepoints that are unassigned in the
relevant version of Unicode, or for which no normalization rules are defined, the
fn:normalizeunicode
function leaves such codepoints unchanged. If the
implementation supports the requested normalization form then it must
be able to handle every input string without raising an error.
A dynamic error is raised [err:FOCH0003] if the
effective value of the $normalizationForm
argument is not one of the values
supported by the implementation.
Converts a string to upper case.
fn:uppercase
($arg
as
xs:string?
) as
xs:string
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 
The twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations.
The threeargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and static base uri.
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.5 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].
A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.
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 
The twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations.
The threeargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and static base uri.
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.5 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].
A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.
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 
The twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations.
The threeargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and static base uri.
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.5 Choosing a collation.
The function returns an xs:boolean
indicating whether or not the value of
$arg1
ends 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].
A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.
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 
The twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations.
The threeargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and static base uri.
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.5 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].
A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.
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 
The twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations.
The threeargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and static base uri.
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.5 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].
A dynamic error may be raised [err:FOCH0004] if the specified collation does not support collation units.
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 XSD 1.1 grammar for regular expressions uses the same
production rule, but renumbered and renamed [73] NormalChar
; it
is affected in the same way.
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  "^"  "$"
Using XSD 1.1 as the baseline the equivalent is to change the production:
[74] charClass ::= SingleCharEsc  charClassEsc  charClassExpr  WildCardEsc
to read:
[74] charClass ::= SingleCharEsc  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 '}' ) ) '?'?
(In the XSD 1.1 version of the regular expression grammar, this rule is unchanged, but is renumbered [67])
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.
Some operations associated with regular expressions (for example,
backreferences, and the fn:replace
function) allow 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.
When parentheses are used in a part of the regular expression that is matched
more than once (because it is within a construct that allows repetition), then
only the last substring that it matched will be captured. Note that this rule
is not sufficient in all cases to ensure an unambiguous result, especially in
cases where (a) the regular expression contains nested repeating constructs,
and/or (b) the repeating construct matches a zerolength string. In such cases
it is implementationdependent which substring is captured. For example given
the regular expression (a*)+
and the input string "aaaa"
, an implementation
might legitimately capture either "aaaa"
or a zero length string as the content
of the captured subgroup.
Noncapturing groups are also recognized. These are indicated
by the syntax (?:xxxx)
. The production rule for atom
in [XML Schema Part 2: Datatypes Second Edition] is changed to replace the alternative:
( '(' regExp ')' )
with:
( '(' '?:'? regExp ')' )
(For the new versions of the XSD 1.0 and XSD 1.1 production rules for
atom
, see below.)
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.
Combining this change with the introduction of noncapturing groups (see above), backreferences change the following production:
[9] atom ::= Char  charClass  ( '(' regExp ')' )
to
[9] atom ::= Char  charClass  ( '(' '?:'? regExp ')' )  backReference
[9a] backReference ::= "\" [19][09]*
With respect to the XSD 1.1 version of the regular expression grammar, the effect is to change:
[72] atom ::= NormalChar  charClass  ( '(' regExp ')' )
to
[72] atom ::= NormalChar  charClass  ( '(' '?:'? regExp ')' )  backReference
[72a] 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]
(In the XSD 1.1 version of the regular expression grammar, the production rule
for SingleCharEsc
is unchanged, but is renumbered [84])
A regular expression that uses a Unicode block name that is not defined in the version(s) of Unicode
supported by the processor (for example \p{IsBadBlockName}
) is deemed to be invalid
[err:FORX0002].
Note:
XSD 1.0 does not say how this situation should be handled; XSD 1.1 says that it should be handled by treating all characters as matching.
Note:
In [Schema 1.1 Part 2] the rules for the interpretation of hyphens within square brackets in a regular expression have been clarified; and the semantics of regular expressions are no longer tied to a specific version of Unicode.
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 a dynamic 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
) or carriage return (#x0D
)
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 (production charRange
in the XSD 1.0 grammar, replaced by productions charRange
and singleChar
in XSD 1.1) 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 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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.
A dynamic error is raised [err:FORX0002] if the value of
$pattern
is invalid according to the rules described in 5.6.1 Regular expression syntax.
A dynamic 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 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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"
A dynamic 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.
A dynamic 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.
A dynamic 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.
A dynamic 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
"\".
A dynamic 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?
) as
xs:string*
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* 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The oneargument form of this function
splits the supplied string at whitespace boundaries. More specifically, calling fn:tokenize($input)
is equivalent to calling fn:tokenize(fn:normalizespace($input), ' '))
where the second argument
is a single space character (x20).
The effect of calling the twoargument form of this function (omitting the argument
$flags
) is the same as the effect of calling the threeargument version with the
$flags
argument set to a zerolength string. Flags are defined in
5.6.1.1 Flags.
The following rules apply to the threeargument form of the function:
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.
Except with the oneargument form of the function,
if a separator occurs at the start of the $input
string, the result
sequence will start with a zerolength string. Similarly, 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", "")
A dynamic 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.
A dynamic 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.
A dynamic error is raised [err:FORX0003] if the supplied
$pattern
matches a zerolength string, that is, if fn:matches("",
$pattern, $flags)
returns true
.
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 oneargument form of the function differs has a similar effect to
the twoargument form with \s+
as the separator pattern, except that the oneargument
form strips leading and trailing whitespace, whereas the twoargument form delivers an extra
zerolength token if leading or trailing whitespace is present.
The function returns no information about the separators that were found
in the string. If this information is required, the fn:analyzestring
function
can be used instead.
The separator used by the oneargument form of the function is any sequence of tab (x09), newline (x0A), carriage return (x0D) or space (x20) characters. This is the same as the separator recognized by listvalued attributes as defined in XSD. It is not the same as the separator recognized by listvalued attributes in HTML5, which also treats formfeed (x0C) as whitespace. If it is necessary to treat formfeed as a separator, an explicit separator pattern should be used.
The expression fn:tokenize(" red green blue ")
returns ("red", "green", "blue")
.
The expression fn:tokenize("The cat sat on the mat", "\s+")
returns ("The", "cat", "sat", "on", "the", "mat")
.
The expression fn:tokenize(" red green blue ", "\s+")
returns ("", "red", "green", "blue", "")
.
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 dynamic 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) 
This function is ·nondeterministic·, ·contextindependent·, and ·focusindependent·.
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 ·implementationdependent·. 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 ·implementationdependent· whether the two calls return the same element node or distinct (but deep equal) element nodes. In this respect it is ·nondeterministic·.
The base URI of the element nodes in the result is ·implementationdependent·.
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
.
Note:
A freestanding copy of this schema can be found at analyzestring.xsd
<?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>
A dynamic 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.
A dynamic 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.
A dynamic error is raised [err:FORX0003] if the supplied
$pattern
matches a zerolength string, that is, if fn:matches("",
$pattern, $flags)
returns true
.
The declarations and definitions in the above schema are not automatically available in
the static context of the fn:analyzestring
call (or of any other
expression). The contents of the static context are hostlanguage defined, and in some
host languages are implementationdefined.
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 (with whitespace added for legibility):
<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 (with whitespace added for legibility):
<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 (with whitespace added for legibility):
<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?
The oneargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on static base uri.
The twoargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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.
The following rules apply in order:
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.
If the $base
argument is not supplied, then:
If the static base URI in the static context is not absent, it is used as the effective
value of $base
.
Otherwise, a dynamic error is raised: [err:FORG0002].
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. A dynamic error is raised [err:FONS0005] if the baseuri property is not initialized in the static
context.
A dynamic error is raised [err:FORG0002] 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.
A dynamic 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).
A dynamic error is raised [err:FORG0009] if the chosen resolution algorithm fails for any other reason.
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
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 . 
Returns the xs:boolean
value true
.
fn:true
() as
xs:boolean
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The result is equivalent to xs:boolean("1")
.
The expression fn:true()
returns xs:boolean(1)
.
Returns the xs:boolean
value false
.
fn:false
() as
xs:boolean
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The result is equivalent to xs:boolean("0")
.
The expression fn:false()
returns xs:boolean(0)
.
The following functions define the semantics of operators on boolean values in [XQuery 3.1: An XML Query Language] and [XML Path Language (XPath) 3.1]:
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 when applied to two 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 when applied to two 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 when applied to two 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 ^{XP30}.
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 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()
.
fn:boolean([])
raises a type error [err:FORG0006].
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
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 subtypes of xs:duration
, namely xs:yearMonthDuration
and xs:dayTimeDuration
, are defined in [Schema 1.1 Part 2]. These types must
be available in the data model whether or not the implementation supports other aspects of XSD 1.1.
The significance of these subtypes is that arithmetic and ordering become well defined; this is not the
case for xs:duration
values in general, because of the variable number of days in a month. For this reason, many of the functions
and operators on durations require the arguments/operands to belong to these two subtypes.
Two totally ordered subtypes of xs:duration
are defined in Section
2.7 Schema Information
^{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 a partial order rather than
a total 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 when applied to two 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 when applied to two 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 when applied to two 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 when applied to two 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 when applied to two 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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($months idiv 12)
.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($months mod 12)
.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($seconds idiv 86400)
.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($seconds mod 86400) idiv 3600
.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($seconds mod 3600) idiv 60
.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($seconds mod 60)
as an xs:decimal
.
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 when applied to two 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 when applied to two 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 when applied to an xs:yearMonthDuration
and a numeric
value.
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.
A dynamic error is raised [err:FOCA0005] if $arg2
is
NaN
.
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 when applied to an xs:yearMonthDuration
and a numeric
value.
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.
A dynamic error is raised [err:FOCA0005] if $arg2
is
NaN
.
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 when applied to two 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 when applied to two 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 when applied to two 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 when applied to an xs:dayTimeDuration
and a numeric
value.
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
.
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.
A dynamic error is raised [err:FOCA0005] if $arg2
is
NaN
.
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 when applied to two 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.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
A dynamic error is raised [err:FOCA0005] if $arg2
is
NaN
.
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 when applied to two 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 a dynamic error [err:FODT0001] in case of overflow.
As defined in Section
3.3.2 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 first five components are
xs:integer
values. 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^{DM30}.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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.
A dynamic error is raised [err:FORG0008] if the two arguments both have timezones and the timezones are different.
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 ^{XP31}, is assumed to be present as part of the value. This creates a total order for all date and time values.
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^{DM30}.
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.
Note:
In [Schema 1.1 Part 2], a new explicitTimezone
facet is available with values
optional
, required
, or prohibited
to
enable the timezone to be defined as mandatory or disallowed.
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 ordinary 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 when applied to two 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
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
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 when applied to two xs:dateTime
values. Also
used in the definition of the "ge" operator.
op:dateTimelessthan
($arg1
as
xs:dateTime
, $arg2
as
xs:dateTime
) as
xs:boolean
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
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 when applied to two xs:dateTime
values. Also
used in the definition of the "le" operator.
op:dateTimegreaterthan (  $arg1  as xs:dateTime , 
$arg2  as xs:dateTime ) as xs:boolean 
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
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 when applied to two 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
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
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 when applied to two xs:date
values. Also used in the
definition of the "ge" 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 when applied to two xs:date
values. Also used in the
definition of the "le" operator.
op:dategreaterthan
($arg1
as
xs:date
, $arg2
as
xs:date
) as
xs:boolean
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
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 when applied to two 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
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
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:00Z
.
).
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 when applied to two xs:time
values. Also used in the
definition of the "ge" operator.
op:timelessthan
($arg1
as
xs:time
, $arg2
as
xs:time
) as
xs:boolean
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
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 when applied to two xs:time
values. Also used in the
definition of the "le" operator.
op:timegreaterthan
($arg1
as
xs:time
, $arg2
as
xs:time
) as
xs:boolean
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
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 when applied to two 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 
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
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
19780301T00: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 when applied to two 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
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
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 when applied to two 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
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
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 when applied to two 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
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
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 when applied to two 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
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
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
.
fn:yearfromdateTime
($arg
as
xs:dateTime?
) as
xs:integer?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
.
fn:monthfromdateTime
($arg
as
xs:dateTime?
) as
xs:integer?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
.
fn:dayfromdateTime
($arg
as
xs:dateTime?
) as
xs:integer?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
.
fn:hoursfromdateTime
($arg
as
xs:dateTime?
) as
xs:integer?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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? 
The oneargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
The twoargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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? 
The oneargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
The twoargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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)
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? 
The oneargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
The twoargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 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 a dynamic 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 a
dynamic 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 when applied to two xs:dateTime
values.
op:subtractdateTimes (  $arg1  as xs:dateTime , 
$arg2  as xs:dateTime ) as xs:dayTimeDuration 
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
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
^{XP30}.) 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 starting instant of
$arg2
.
Defines the semantics of the "" operator
when applied to two xs:date
values.
op:subtractdates
($arg1
as
xs:date
, $arg2
as
xs:date
) as
xs:dayTimeDuration
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
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
^{XP30}.) 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
when applied to two xs:time
values.
op:subtracttimes
($arg1
as
xs:time
, $arg2
as
xs:time
) as
xs:dayTimeDuration
This function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone.
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 when applied to an xs:dateTime
and an
xs:yearMonthDuration
value.
op:addyearMonthDurationtodateTime (  $arg1  as xs:dateTime , 
$arg2  as xs:yearMonthDuration ) as xs:dateTime 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 when applied to an xs:dateTime
and an
xs:dayTimeDuration
value.
op:adddayTimeDurationtodateTime (  $arg1  as xs:dateTime , 
$arg2  as xs:dayTimeDuration ) as xs:dateTime 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 when applied to an xs:dateTime
and an
xs:yearMonthDuration
value.
op:subtractyearMonthDurationfromdateTime (  $arg1  as xs:dateTime , 
$arg2  as xs:yearMonthDuration ) as xs:dateTime 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 when applied to an xs:dateTime
an 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 when applied to an xs:date
and an
xs:yearMonthDuration
value.
op:addyearMonthDurationtodate (  $arg1  as xs:date , 
$arg2  as xs:yearMonthDuration ) as xs:date 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 when applied to an xs:date
and an
xs:dayTimeDuration
value.
op:adddayTimeDurationtodate (  $arg1  as xs:date , 
$arg2  as xs:dayTimeDuration ) as xs:date 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 when applied to an xs:date
and an
xs:yearMonthDuration
value.
op:subtractyearMonthDurationfromdate (  $arg1  as xs:date , 
$arg2  as xs:yearMonthDuration ) as xs:date 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 when applied to an xs:date
and an
xs:dayTimeDuration
.
op:subtractdayTimeDurationfromdate (  $arg1  as xs:date , 
$arg2  as xs:dayTimeDuration ) as xs:date 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 when applied to an xs:time
and an
xs:dayTimeDuration
value.
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 when applied to an xs:time
and an
xs:dayTimeDuration
value.
op:subtractdayTimeDurationfromtime (  $arg1  as xs:time , 
$arg2  as xs:dayTimeDuration ) as xs:time 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
) as
xs:string?
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? 
The twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on default calendar, and default language, and default place, and implicit timezone.
The fiveargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone, and namespaces.
Returns a string containing an xs:date
value formatted for display.
fn:formatdate
($value
as
xs:date?
, $picture
as
xs:string
) as
xs:string?
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? 
The twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on default calendar, and default language, and default place, and implicit timezone.
The fiveargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone, and namespaces.
Returns a string containing an xs:time
value formatted for display.
fn:formattime
($value
as
xs:time?
, $picture
as
xs:string
) as
xs:string?
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? 
The twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on default calendar, and default language, and default place, and implicit timezone.
The fiveargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on implicit timezone, and namespaces.
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 ([err:FOFD1340]). 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. More detailed rules are given below.
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 variable marker may be separated into its components by applying the following rules:
The component specifier is always present and is always a single letter.
The width modifier may be recognized by the presence of a comma.
The substring between the component specifier and the comma (if present) or the end of the string (if there is no comma) contains the first and second presentation modifiers, both of which are optional. If this substring contains a single character, this is interpreted as the first presentation modifier. If it contains more than one character, the last character is examined: if it is valid as a second presentation modifier then it is treated as such, and the preceding part of the substring constitutes the first presentation modifier. Otherwise, the second presentation modifier is presumed absent and the whole substring is interpreted as the first presentation modifier.
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 
A dynamic error is reported [err:FOFD1340] if the syntax of the picture is incorrect.
A dynamic 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 fn: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 fn: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 

either a or t  indicates alphabetic or traditional numbering respectively,
the default being ·implementationdefined·.
This has the same meaning as in the second argument of fn:formatinteger . 
either c or o  indicates cardinal or ordinal numbering respective, for example
7 or seven for a cardinal number, or 7th ,
seventh , or 7¬∫
for an ordinal number.
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 (see [ISO 31661]) or Olson timezone name (see [Olson Timezone Database]) 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 
[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 should 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 the default language defined in the dynamic context.
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.
The calendar value if present must be a valid EQName
(dynamic error: [err:FOFD1340]).
If it is a lexical QName
then it is expanded into an expanded QName
using the statically known namespaces; if it has no prefix then it represents an expandedQName in no namespace.
If the expanded QName is in no namespace,
then it must identify a calendar with a designator specified below
(dynamic error: [err:FOFD1340]).
If the expanded QName is in a namespace then it identifies the calendar in an ·implementationdefined· way.
If the $calendar
argument is omitted or is set to an empty sequence
then the default calendar defined in the dynamic context 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.
ISO 8601 does not define a numbering for weeks within a month. When the w
component is used, the convention to be adopted is that each MondaytoSunday week is considered to
fall within a particular month if its Thursday occurs in that month; the weeks that fall in a particular
month under this definition are numbered starting from 1. Thus, for example,
29 January 2013 falls in week 5 because the Thursday of the week (31 January 2013) is the fifth Thursday
in January, and 1 February 2013 is also in week 5 for the same reason.
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, XSD 1.1 endorses 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 $place
argument is omitted or is set
to an empty sequence, then the default place defined in the dynamic context is used.
If the value is supplied, and is not the empty sequence, then it should
either be a country code or an Olson timezone name.
If the value does not take this form, or if its value is not recognized
by the implementation, then the default place defined in the dynamic context is used.
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", ())
 ๓๑ ธันวาคม ๒๕๔๕ 
Function  Meaning 

fn:parseietfdate  Parses a string containing the date and time in IETF format, returning the corresponding
xs:dateTime value. 
A function is provided to parse dates and times expressed using syntax that is commonly encountered in internet protocols.
Parses a string containing the date and time in IETF format, returning the corresponding
xs:dateTime
value.
fn:parseietfdate
($value
as
xs:string?
) as
xs:dateTime?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The function accepts a string matching the production input
in the
following grammar:
input ::=

S? (dayname ","? S)? ((datespec S time)  asctime) S?

dayname ::=

"Mon"  "Tue"  "Wed"  "Thu"  "Fri"  "Sat"  "Sun"  "Monday  "Tuesday"
 "Wednesday"  "Thursday"  "Friday"  "Saturday"  "Sunday"

datespec ::=

daynum dsep monthname dsep year

asctime ::=

monthname dsep daynum S time S year

dsep ::=

S  (S? "" S?)

daynum ::=

digit digit?

year ::=

digit digit (digit digit)?

digit ::=

[09]

monthname ::=

"Jan"  "Feb"  "Mar"  "Apr"  "May"  "Jun"  "Jul"  "Aug"  "Sep" 
"Oct"  "Nov"  "Dec"

time ::=

hours ":" minutes (":" seconds)? (S? timezone)?

hours ::=

digit digit

minutes ::=

digit digit

seconds ::=

digit digit ("." digit+)?

timezone ::=

tzname  tzoffset (S? "(" S? tzname S? ")")?

tzname ::=

"UT"  "UTC"  "GMT"  "EST"  "EDT"  "CST"  "CDT"  "MST"  "MDT"  "PST"
 "PDT"

tzoffset ::=

("+""") digit digit ":"? (digit digit)?

S ::=

x09  x0A  x0D  x20

The input is caseinsensitive: uppercase and lowercase distinctions in the above grammar show the conventional usage, but otherwise have no significance.
The dayname
, if present, is ignored.
The daynum
, monthname
, and year
supply the day,
month, and year of the resulting xs:dateTime
value. A twodigit year
must have 1900 added to it. A year such as 0070 is to be treated
as given; negative years are not permitted.
The hours
, minutes
, and seconds
(including
fractional seconds) values supply the corresponding components of the resulting
xs:dateTime
value; if the seconds
value is absent then zero
is assumed.
If both a tzoffset
and a tzname
are supplied then the
tzname
is ignored.
If a tzoffset
is supplied then its first two digits supply the hours part
of the timezone offset, and its next two digits, if present, supply the minutes
part.
If a tzname
is supplied with no tzoffset
then it is translated
to a timezone offset as follows:
tzname  Offset 

UT, UTC, GMT  00:00 
EST  05:00 
EDT  04:00 
CST  06:00 
CDT  05:00 
MST  07:00 
MDT  06:00 
PST  08:00 
PDT  07:00 
If neither a tzoffset
nor tzname
is supplied, a timezone
offset of 00:00
is assumed.
A dynamic error is raised [err:FORG0010] if the input does not match the grammar, or if the resulting date/time value is invalid (for example, 31 February).
The parseietfdate
function attempts to interpret its input as a date
in any of the three formats specified by HTTP [RFC 2616].
These formats are used widely on the Internet to represent timestamps, and were specified in:
RFC 2616 (HTTP) officially uses a subset of those three formats restricted to GMT.
Reflecting the internet tradition of being liberal in what is accepted, the function also:
Accepts a singledigit value in place of a twodigit value with a leading zero (so "Wed 1 Jun" is acceptable in place of "Wed 01 Jun")
Accepts one or more whitespace characters (x20, x09, x0A, x0D) wherever a single space is required, and allows whitespace to be omitted where it is not required for parsing
Accepts and ignores whitespace characters (x20, x09, x0A, x0D) at the start or end of the string.
In new protocols IETF recommends the format of RFC 3339 which is based on a profile of ISO 8601 similar to that already used in XPath and XSD,but the "approximate" RFC 822 format described here is very widely used.
An RFC 1123 date can be generated approximately using fn:formatdateTime
with a picture
string of "[FNn3], [D01] [MNn3] [Y04] [H01]:[m01]:[s01] [Z0000]"
.
The expression fn:parseietfdate("Wed, 06 Jun 1994 07:29:35 GMT")
returns xs:dateTime("19940606T07:29:35Z")
.
The expression fn:parseietfdate("Wed, 6 Jun 94 07:29:35 GMT")
returns xs:dateTime("19940606T07:29:35Z")
.
The expression fn:parseietfdate("Wed Jun 06 11:54:45 EST 2013")
returns xs:dateTime("19940606T11:54:450500")
.
The expression fn:parseietfdate("Sunday, 06Nov94 08:49:37 GMT")
returns xs:dateTime("19941106T08:49:37Z")
.
The expression fn:parseietfdate("Wed, 6 Jun 94 07:29:35 +0500")
returns xs:dateTime("19940606T07:29:35+0500")
.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 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
2.1 Terminology
^{DM30}.
A dynamic error is raised [err:FOCA0002] if $qname
does
not have the correct lexical form for an instance of xs:QName
.
A dynamic error is raised [err:FONS0004] if $qname
has
a prefix and there is no namespace binding for $element
that matches this
prefix.
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
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
.
A dynamic error is raised [err:FOCA0002] if $paramQName
does not have the correct lexical form for an instance of xs:QName
.
A dynamic error is raised [err:FOCA0002] if $paramURI
is the zerolength string or the empty sequence, and the value of
$paramQName
contains a colon (:
).
A dynamic error may be raised [err:FOCA0002] if
$paramURI
is not a valid URI (XML Namespaces 1.0) or IRI (XML Namespaces
1.1).
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 when applied to two values of type xs:QName
.
op:QNameequal
($arg1
as
xs:QName
, $arg2
as
xs:QName
) as
xs:boolean
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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^{DM30}, 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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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? 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
If $element
has an inscope namespace whose namespace prefix is equal to
$prefix
, the function returns the namespace URI of that namespace.
If $element
has no inscope namespace whose namespace prefix is equal to
$prefix
, the function returns the empty sequence.
If $prefix
is the zerolength string or the empty sequence, then if
$element
has a default namespace (that is, a namespace node with no
name), the function returns the namespace URI of the default namespace. If
$element
has no default namespace, the function returns the empty
sequence.
Prefixes are equal only if their Unicode codepoints match exactly.
let $e
:=
<z:a xmlns="http://example.org/one" xmlns:z="http://example.org/two"> <b xmlns=""/> </z:a>
The expression fn:namespaceuriforprefix("z", $e)
returns "http://example.org/two"
.
The expression fn:namespaceuriforprefix("", $e)
returns "http://example.org/one"
.
The expression fn:namespaceuriforprefix((), $e)
returns "http://example.org/one"
.
The expression fn:namespaceuriforprefix("xml", $e)
returns "http://www.w3.org/XML/1998/namespace"
.
The expression fn:namespaceuriforprefix("xml", $e)
returns "http://www.w3.org/XML/1998/namespace"
.
Returns the prefixes of the inscope namespaces for an element node.
fn:inscopeprefixes
($element
as
element()
) as
xs:string*
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
19.1.6 Casting to xs:base64Binary and xs:hexBinary.
Function  Meaning 

op:hexBinaryequal  Returns true if two xs:hexBinary values contain the same octet
sequence. 
op:hexBinarylessthan  Returns true if the first argument is less than the second. 
op:hexBinarygreaterthan  Returns true if the first argument is greater than the second. 
op:base64Binaryequal  Returns true if two xs:base64Binary values contain the same octet
sequence. 
op:base64Binarylessthan  Returns true if the first argument is less than the second. 
op:base64Binarygreaterthan  Returns true if the first argument is greater than the second. 
Returns true if two xs:hexBinary
values contain the same octet
sequence.
Defines the semantics of
the "eq" and "ne" operators when applied to two 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 the first argument is less than the second.
Defines the semantics of
the "lt" operator when applied to two xs:hexBinary
values. Also used in the
definition of the "ge" operator.
op:hexBinarylessthan (  $arg1  as xs:hexBinary , 
$arg2  as xs:hexBinary ) as xs:boolean 
The function returns true
if any of the following conditions is true:
$arg1
is zerolength (contains no octets) and $arg2
is
not zerolength.
Neither argument is zerolength, and the first octet of $arg1
is less
than the first octet of $arg2
, treating the value of the octet as an
unsigned integer in the range 0 to 255.
Neither argument is zerolength, the first octet of $arg1
is equal to
the first octet of $arg2
, and the xs:hexBinary
value
formed by taking all octets of arg1
after the first is less than the
xs:hexBinary
value formed by taking all octets of
arg2
after the first.
Otherwise, the function returns false
.
Returns true if the first argument is greater than the second.
Defines the semantics of
the "gt" operator when applied to two xs:hexBinary
values. Also used in the
definition of the "le" operator.
op:hexBinarygreaterthan (  $arg1  as xs:hexBinary , 
$arg2  as xs:hexBinary ) as xs:boolean 
The function call op:hexBinarygreaterthan($A, $B)
is defined to return
the same result as op:hexBinarylessthan($B, $A)
Returns true if two xs:base64Binary
values contain the same octet
sequence.
Defines the semantics
of the "eq" and "ne" operators when applied to two 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
.
Returns true if the first argument is less than the second.
Defines the semantics
of the "lt" operator when applied to two xs:base64Binary
values. Also used in
the definition of the "ge" operator.
op:base64Binarylessthan (  $arg1  as xs:base64Binary , 
$arg2  as xs:base64Binary ) as xs:boolean 
The function returns true
if any of the following conditions is true:
$arg1
is zerolength (contains no octets) and $arg2
is
not zerolength.
Neither argument is zerolength, and the first octet of $arg1
is less
than the first octet of $arg2
, treating the value of the octet as an
unsigned integer in the range 0 to 255.
Neither argument is zerolength, the first octet of $arg1
is equal to
the first octet of $arg2
, and the xs:base64Binary
value
formed by taking all octets of arg1
after the first is less than the
xs:base64Binary
value formed by taking all octets of
arg2
after the first.
Otherwise, the function returns false
.
Returns true if the first argument is greater than the second.
Defines the semantics
of the "gt" operator when applied to two xs:base64Binary
values. Also used in
the definition of the "le" operator.
op:base64Binarygreaterthan (  $arg1  as xs:base64Binary , 
$arg2  as xs:base64Binary ) as xs:boolean 
The function call op:base64Binarygreaterthan($A, $B)
is defined to return
the same result as op:base64Binarylessthan($B, $A)
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 when applied to two 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^{DM30}, 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 6 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: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:path  Returns a path expression that can be used to select the supplied node relative to the root of its containing document. 
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
The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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^{DM30}, dynamic error [err:XPDY0002]^{XP30}
If the context item is not a node, type error [err:XPTY0004]^{XP30}.
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
The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
5.11 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^{DM30}, dynamic error [err:XPDY0002]^{XP30}
If the context item is not a node, type error [err:XPTY0004]^{XP30}.
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
The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
5.11 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
5.11 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^{DM30}, dynamic error [err:XPDY0002]^{XP30}
If the context item is not a node, type error [err:XPTY0004]^{XP30}.
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 oneargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The twoargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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).
The following errors may be raised when $arg
is omitted:
If the context item is absent^{DM30}, dynamic error [err:XPDY0002]^{XP30}
If the context item is not a node, type error [err:XPTY0004]^{XP30}.
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 when applied to two 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 when applied to two nodes.
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 2.4 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 when applied to two nodes.
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 2.4 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()?
The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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]
.
The following errors may be raised when $arg
is omitted:
If the context item is absent^{DM30}, dynamic error [err:XPDY0002]^{XP30}
If the context item is not a node, type error [err:XPTY0004]^{XP30}.
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 a path expression that can be used to select the supplied node relative to the root of its containing document.
fn:path
() as
xs:string?
fn:path
($arg
as
node()?
) as
xs:string?
The oneargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The twoargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 a document node, the function returns the string
"/"
.
Otherwise, the function constructs a string that consists of a sequence of steps, one
for each ancestororself of $arg
other than the root node. This string is
prefixed by "Q{http://www.w3.org/2005/xpathfunctions}root()"
if the root
node is not a document node. Each step consists of the character "/"
followed by a string whose form depends on the kind of node selected by that step, as
follows:
For an element node,
Q{uri}local[position]
,
where uri
is the namespace URI of the node name or the
empty string if the node is in no namespace, local
is
the local part of the node name, and position
is an
integer representing the position of the selected node among its likenamed
siblings.
For an attribute node:
if the node is in no namespace, @local
, where
local
is the local part of the node name
otherwise, @Q{uri}local
, where
uri
is the namespace URI of the node name,
and local
is the local part of the node name
For a text node: text()[position]
where
position
is an integer representing the position
of the selected node among its text node siblings
For a comment node: comment()[position]
where
position
is an integer representing the position
of the selected node among its comment node siblings
For a processinginstruction node:
processinginstruction(local)[position]
where local
is the name of the processing instruction
node and position
is an integer representing the
position of the selected node among its likenamed processinginstruction node
siblings
For a namespace node:
If the namespace node has a name:
namespace::prefix
, where
prefix
is the local part of the name of the
namespace node (which represents the namespace prefix).
If the namespace node has no name (that is, it represents the default
namespace):
namespace::*[Q{http://www.w3.org/2005/xpathfunctions}localname()=""]
let $e
:=
fn:parsexml('<?xml version="1.0"?> <p xmlns="http://example.com/one" xml:lang="de" author="Friedrich von Schiller"> Freude, schöner Götterfunken,<br/> Tochter aus Elysium,<br/> Wir betreten feuertrunken,<br/> Himmlische, dein Heiligtum.</p>')
The expression fn:path($e)
returns '/'
.
The expression fn:path($e/*:p)
returns '/Q{http://example.com/one}p[1]'
.
The expression fn:path($e/*:p/@xml:lang)
returns '/Q{http://example.com/one}p[1]/@Q{http://www.w3.org/XML/1998/namespace}lang'
.
The expression fn:path($e/*:p/@author)
returns '/Q{http://example.com/one}p[1]/@author'
.
The expression fn:path($e/*:p/*:br[2])
returns '/Q{http://example.com/one}p[1]/Q{http://example.com/one}br[2]'
.
The expression fn:path($e//text()[startswith(normalizespace(),
'Tochter')])
returns '/Q{http://example.com/one}p[1]/text()[2]'
.
let $emp
:=
<employee xml:id="ID21256"> <empnr>E21256</empnr> <first>John</first> <last>Brown</last> </employee>
The expression fn:path($emp)
returns 'Q{http://www.w3.org/2005/xpathfunctions}root()'
.
The expression fn:path($emp/@xml:id)
returns 'Q{http://www.w3.org/2005/xpathfunctions}root()/@Q{http://www.w3.org/XML/1998/namespace}id'
.
The expression fn:path($emp/empnr)
returns 'Q{http://www.w3.org/2005/xpathfunctions}root()/Q{}empnr[1]'
.
Returns true if the supplied node has one or more child nodes (of any kind).
fn:haschildren
() as
xs:boolean
fn:haschildren
($node
as
node()?
) as
xs:boolean
The zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusdependent·.
The oneargument form of this function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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.
Provided that the supplied argument $node
matches the expected type
node()?
, the result of the function call
fn:haschildren($node)
is defined to be the same as the result of the
expression fn:exists($node/child::node())
.
The following errors may be raised when $node
is omitted:
If the context item is absent^{DM30}, dynamic error [err:XPDY0002]^{XP30}
If the context item is not a node, type error [err:XPTY0004]^{XP30}.
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()*
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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()*
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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 does not have another node within the sequence as an ancestor; 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 outermost(//div)
returns those div
elements that are not contained within 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.1: An XML Query Language] and [XML Path Language (XPath) 3.1].
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 ·implementationdependent· 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 "," when applied to any two sequences.
op:concatenate
($seq1
as
item()*
, $seq2
as
item()*
) as
item()*
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The function returns a sequence consisting of all the items in $seq1
followed by all the items in $seq2
.
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
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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()?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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()*
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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()* 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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.
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()*
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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
.
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()*
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The function returns a sequence containing the items in $arg
in reverse
order.
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()* 
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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)]
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 ·implementationdependent· order.
fn:unordered
($sourceSeq
as
item()*
) as
item()*
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
The function returns the items of $sourceSeq
in an ·implementationdependent· 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, or maps with matching entries, or arrays with matching members. 
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 oneargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and implicit timezone.
The twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and static base uri, and implicit timezone.
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.5 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 ·implementationdependent·.
Which value of a set of values that compare equal is returned is ·implementationdependent·.
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 ·implementationdependent·, 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 twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and implicit timezone.
The threeargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and static base uri, and implicit timezone.
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.5 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, or maps with matching entries, or arrays with matching members.
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 twoargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and implicit timezone.
The threeargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and static base uri, and implicit timezone.
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.5 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 not, or if one is a node and the other
is not, the function returns false
.
If $i1
and $i2
are both ·maps·, the result is true
if and only if all the
following conditions apply:
Both maps have the same number of entries.
For every entry in the first map, there is an entry in the second map that:
has the ·same key· (note that the collation is not used when comparing keys), and
has the same associated value (compared using the fn:deepequal
function, under the collation supplied in the original call to
fn:deepequal
).
If $i1
and $i2
are both ·arrays·, the result is true
if and only if all
the following conditions apply:
Both arrays have the same number of members (array:size($i1) eq
array:size($i2)
.
Members in the same position of both arrays are deepequal to each other, under
the collation supplied in the original call to fn:deepequal
: that is,
every $p in 1 to array:size($i1) satisfies deepequal($i1($p), $i2($p),
$collation
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))
.
Either both nodes are both annotated as having simple content or both nodes are annotated as having complex content. For this purpose "simple content" means either a simple type or a complex type with simple content; "complex content" means a complex type whose variety is mixed, elementonly, or empty.
Note:
It is a consequence of this rule that validating a document D against a schema will usually (but not necessarily) result in a document that is not deepequal to D. The exception is when the schema allows all elements to have mixed 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 are annotated as having simple content (as defined
in 3(b) above), and the typed value of $i1
is deepequal
to the typed value of $i2
.
Both element nodes have a type annotation that is a complex type with
variety elementonly, and the sequence $i1/*
is
deepequal to the sequence $i2/*
.
Both element nodes have a type annotation that is a complex type with
variety mixed, and the sequence $i1/(*text())
is
deepequal to the sequence $i2/(*text())
.
Both element nodes have a type annotation that is a complex type with variety empty.
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.
In all other cases the result is false.
A type error is raised [err:FOTY0015] if either input sequence contains a function item that is not a map or array.
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
5.5 isid Accessor
^{DM30} and
Section
5.6 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.
Comparing items of different kind (for example, comparing an atomic value to a node, or a map to an array) returns false, it does not return an error.
Comparing a function (other than a map or array) to any other value raises a type 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 expression fn:deepequal(map{1:'a', 2:'b'}, map{2:'b', 1:'a'})
returns true()
.
The expression fn:deepequal([1, 2, 3], [1, 2, 3])
returns true()
.
The expression fn:deepequal((1, 2, 3), [1, 2, 3])
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()?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
Except in error cases, the function returns $arg
unchanged.
A dynamic 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()+
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
Except in error cases, the function returns $arg
unchanged.
A dynamic 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()
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
Except in error cases, the function returns $arg
unchanged.
A dynamic 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 when applied to two sequences of nodes.
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)
.
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 when applied to two sequences of nodes.
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)
.
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 when applied to two sequences of nodes.
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)
.
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
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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?
This function is ·deterministic·, ·contextindependent·, and ·focusindependent·.
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.
A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.
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 zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and implicit timezone.
The oneargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and static base uri, and implicit timezone.
The following conversions are applied to the input sequence $arg
, in order:
Values of type xs:untypedAtomic
in $arg
are cast to
xs:double
.
If the resulting sequence contains values that are instances of more than one primitive type (meaning the 19 primitive types defined in [Schema 1.1 Part 2]), then:
If each value is an instance of one of the types xs:string
or xs:anyURI
,
then all the values are cast to type xs:string
.
If each value is an instance of one of the types xs:decimal
or xs:float
,
then all the values are cast to type xs:float
.
If each value is an instance of one of the types xs:decimal
, xs:float
,
or xs:double
, then all the values are cast to type xs:double
.
Otherwise, a type error is raised [err:FORG0006].
Note:
The primitive type of an xs:integer
value for this purpose is xs:decimal
.
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
(as an xs:float
or xs:double
as appropriate).
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.5 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:tail($c))
evaluated with $collation
as the default collation if specified, and with
$c
as the converted sequence.
A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.
Because the rules allow the sequence to be reordered, if there are two or more items that are
"equal highest", the specific item whose value is returned is ·implementationdependent·. 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 rules for the dynamic type of the result are stricter in Version 3.1 of the specification than
in earlier versions. For example, if all the values in the input sequence belong to types derived from
xs:integer
, Version 3.0 required only that the result be an instance
of the least common supertype of the types present in the input sequence; Version 3.1
requires that the returned value retains its original type. This does not apply, however, where type promotion
is needed to convert all the values to a common primitive type.
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 zeroargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and implicit timezone.
The oneargument form of this function is ·deterministic·, ·contextdependent·, and ·focusindependent·. It depends on collations, and static base uri, and implicit timezone.
The following rules are applied to the input sequence:
Values of type xs:untypedAtomic
in $arg
are cast to
xs:double
.
If the resulting sequence contains values that are instances of more than one primitive type (meaning the 19 primitive types defined in [Schema 1.1 Part 2]), then:
If each value is an instance of one of the types xs:string
or xs:anyURI
,
then all the values are cast to type xs:string
.
If each value is an instance of one of the types xs:decimal
or xs:float
,
then all the values are cast to type xs:float
.
If each value is an instance of one of the types xs:decimal
, xs:float
,
or xs:double
, then all the values are cast to type xs:double
.
Otherwise, a type error is raised [err:FORG0006].
Note:
The primitive type of an xs:integer
value for this purpose is xs:decimal
.
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
(as an xs:float
or xs:double
as appropriate).
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.5 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:tail($c))
evaluated with $collation
as the default collation if specified, and with
$c
as the converted sequence.
A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.
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 app