ColophonAbstractStatus of this documentTable of Contents1. Introduction1.1. Conformance1.2. Namespaces and Prefixes1.3. Function Overloading1.4. Function Signatures and Descriptions1.5. Namespace Terminology1.6. Type Hierarchy1.7. Terminology2. Accessors2.1. fn:node-name2.2. fn:nilled2.3. fn:string2.4. fn:data2.5. fn:base-uri2.6. fn:document-uri3. The Error Function3.1. Examples4. The Trace Function4.1. Examples5. Constructor Functions5.1. Constructor Functions for XML Schema Built-in Types5.2. A Special Constructor Function for xs:dateTime5.2.1. Examples5.3. Constructor Functions for xs:QName and xs:NOTATION5.4. Constructor Functions for User-Defined Types6. Functions and Operators on Numerics6.1. Numeric Types6.2. Operators on Numeric Values6.2.1. op:numeric-add6.2.2. op:numeric-subtract6.2.3. op:numeric-multiply6.2.4. op:numeric-divide6.2.5. op:numeric-integer-divide6.2.5.1. Examples6.2.6. op:numeric-mod6.2.6.1. Examples6.2.7. op:numeric-unary-plus6.2.8. op:numeric-unary-minus6.3. Comparison Operators on Numeric Values6.3.1. op:numeric-equal6.3.2. op:numeric-less-than6.3.3. op:numeric-greater-than6.4. Functions on Numeric Values6.4.1. fn:abs6.4.1.1. Examples6.4.2. fn:ceiling6.4.2.1. Examples6.4.3. fn:floor6.4.3.1. Examples6.4.4. fn:round6.4.4.1. Examples6.4.5. fn:round-half-to-even6.4.5.1. Examples7. Functions on Strings7.1. String Types7.2. Functions to Assemble and Disassemble Strings7.2.1. fn:codepoints-to-string7.2.1.1. Examples7.2.2. fn:string-to-codepoints7.2.2.1. Examples7.3. Equality and Comparison of Strings7.3.1. Collations7.3.2. fn:compare7.3.2.1. Examples7.3.3. fn:codepoint-equal7.4. Functions on String Values7.4.1. fn:concat7.4.1.1. Examples7.4.2. fn:string-join7.4.2.1. Examples7.4.3. fn:substring7.4.3.1. Examples7.4.4. fn:string-length7.4.4.1. Examples7.4.5. fn:normalize-space7.4.5.1. Examples7.4.6. fn:normalize-unicode7.4.7. fn:upper-case7.4.7.1. Examples7.4.8. fn:lower-case7.4.8.1. Examples7.4.9. fn:translate7.4.9.1. Examples7.4.10. fn:encode-for-uri7.4.10.1. Examples7.4.11. fn:iri-to-uri7.4.11.1. Examples7.4.12. fn:escape-html-uri7.4.12.1. Examples7.5. Functions Based on Substring Matching7.5.1. fn:contains7.5.1.1. Examples7.5.2. fn:starts-with7.5.2.1. Examples7.5.3. fn:ends-with7.5.3.1. Examples7.5.4. fn:substring-before7.5.4.1. Examples7.5.5. fn:substring-after7.5.5.1. Examples7.6. String Functions that Use Pattern Matching7.6.1. Regular Expression Syntax7.6.1.1. Flags7.6.2. fn:matches7.6.2.1. Examples7.6.3. fn:replace7.6.3.1. Examples7.6.4. fn:tokenize7.6.4.1. Examples8. Functions on anyURI8.1. fn:resolve-uri9. Functions and Operators on Boolean Values9.1. Additional Boolean Constructor Functions9.1.1. fn:true9.1.1.1. Examples9.1.2. fn:false9.1.2.1. Examples9.2. Operators on Boolean Values9.2.1. op:boolean-equal9.2.2. op:boolean-less-than9.2.3. op:boolean-greater-than9.3. Functions on Boolean Values9.3.1. fn:not9.3.1.1. Examples10. Functions and Operators on Durations, Dates and Times10.1. Duration, Date and Time Types10.1.1. Limits and Precision10.2. Date/time datatype values10.2.1. Examples10.3. Two Totally Ordered Subtypes of Duration10.3.1. xs:yearMonthDuration10.3.1.1. Lexical representation10.3.1.2. Calculating the value from the lexical representation10.3.1.3. Canonical representation10.3.1.4. Order relation on xs:yearMonthDuration10.3.2. xs:dayTimeDuration10.3.2.1. Lexical representation10.3.2.2. Calculating the value of a xs:dayTimeDuration from the lexical representation10.3.2.3. Canonical representation10.3.2.4. Order relation on xs:dayTimeDuration10.4. Comparison Operators on Duration, Date and Time Values10.4.1. op:yearMonthDuration-less-than10.4.2. op:yearMonthDuration-greater-than10.4.3. op:dayTimeDuration-less-than10.4.4. op:dayTimeDuration-greater-than10.4.5. op:duration-equal10.4.5.1. Examples10.4.6. op:dateTime-equal10.4.6.1. Examples10.4.7. op:dateTime-less-than10.4.8. op:dateTime-greater-than10.4.9. op:date-equal10.4.9.1. Examples10.4.10. op:date-less-than10.4.10.1. Examples10.4.11. op:date-greater-than10.4.11.1. Examples10.4.12. op:time-equal10.4.12.1. Examples10.4.13. op:time-less-than10.4.13.1. Examples10.4.14. op:time-greater-than10.4.14.1. Examples10.4.15. op:gYearMonth-equal10.4.15.1. Examples10.4.16. op:gYear-equal10.4.16.1. Examples10.4.17. op:gMonthDay-equal10.4.17.1. Examples10.4.18. op:gMonth-equal10.4.18.1. Examples10.4.19. op:gDay-equal10.4.19.1. Examples10.5. Component Extraction Functions on Durations, Dates and Times10.5.1. fn:years-from-duration10.5.1.1. Examples10.5.2. fn:months-from-duration10.5.2.1. Examples10.5.3. fn:days-from-duration10.5.3.1. Examples10.5.4. fn:hours-from-duration10.5.4.1. Examples10.5.5. fn:minutes-from-duration10.5.5.1. Examples10.5.6. fn:seconds-from-duration10.5.6.1. Examples10.5.7. fn:year-from-dateTime10.5.7.1. Examples10.5.8. fn:month-from-dateTime10.5.8.1. Examples10.5.9. fn:day-from-dateTime10.5.9.1. Examples10.5.10. fn:hours-from-dateTime10.5.10.1. Examples10.5.11. fn:minutes-from-dateTime10.5.11.1. Examples10.5.12. fn:seconds-from-dateTime10.5.12.1. Examples10.5.13. fn:timezone-from-dateTime10.5.13.1. Examples10.5.14. fn:year-from-date10.5.14.1. Examples10.5.15. fn:month-from-date10.5.15.1. Examples10.5.16. fn:day-from-date10.5.16.1. Examples10.5.17. fn:timezone-from-date10.5.17.1. Examples10.5.18. fn:hours-from-time10.5.18.1. Examples10.5.19. fn:minutes-from-time10.5.19.1. Examples10.5.20. fn:seconds-from-time10.5.20.1. Examples10.5.21. fn:timezone-from-time10.5.21.1. Examples10.6. Arithmetic Operators on Durations10.6.1. op:add-yearMonthDurations10.6.1.1. Examples10.6.2. op:subtract-yearMonthDurations10.6.2.1. Examples10.6.3. op:multiply-yearMonthDuration10.6.3.1. Examples10.6.4. op:divide-yearMonthDuration10.6.4.1. Examples10.6.5. op:divide-yearMonthDuration-by-yearMonthDuration10.6.5.1. Examples10.6.6. op:add-dayTimeDurations10.6.6.1. Examples10.6.7. op:subtract-dayTimeDurations10.6.7.1. Examples10.6.8. op:multiply-dayTimeDuration10.6.8.1. Examples10.6.9. op:divide-dayTimeDuration10.6.9.1. Examples10.6.10. op:divide-dayTimeDuration-by-dayTimeDuration10.6.10.1. Examples10.7. Timezone Adjustment Functions on Dates and Time Values10.7.1. fn:adjust-dateTime-to-timezone10.7.1.1. Examples10.7.2. fn:adjust-date-to-timezone10.7.2.1. Examples10.7.3. fn:adjust-time-to-timezone10.7.3.1. Examples10.8. Arithmetic Operators on Durations, Dates and Times10.8.1. op:subtract-dateTimes10.8.1.1. Examples10.8.2. op:subtract-dates10.8.2.1. Examples10.8.3. op:subtract-times10.8.3.1. Examples10.8.4. op:add-yearMonthDuration-to-dateTime10.8.4.1. Examples10.8.5. op:add-dayTimeDuration-to-dateTime10.8.5.1. Examples10.8.6. op:subtract-yearMonthDuration-from-dateTime10.8.6.1. Examples10.8.7. op:subtract-dayTimeDuration-from-dateTime10.8.7.1. Examples10.8.8. op:add-yearMonthDuration-to-date10.8.8.1. Examples10.8.9. op:add-dayTimeDuration-to-date10.8.9.1. Examples10.8.10. op:subtract-yearMonthDuration-from-date10.8.10.1. Examples10.8.11. op:subtract-dayTimeDuration-from-date10.8.11.1. Examples10.8.12. op:add-dayTimeDuration-to-time10.8.12.1. Examples10.8.13. op:subtract-dayTimeDuration-from-time10.8.13.1. Examples11. Functions Related to QNames11.1. Additional Constructor Functions for QNames11.1.1. fn:resolve-QName11.1.1.1. Usage Note11.1.1.2. Examples11.1.2. fn:QName11.1.2.1. Examples11.2. Functions and Operators Related to QNames11.2.1. op:QName-equal11.2.2. fn:prefix-from-QName11.2.3. fn:local-name-from-QName11.2.3.1. Examples11.2.4. fn:namespace-uri-from-QName11.2.4.1. Examples11.2.5. fn:namespace-uri-for-prefix11.2.6. fn:in-scope-prefixes12. Operators on base64Binary and hexBinary12.1. Comparisons of base64Binary and hexBinary Values12.1.1. op:hexBinary-equal12.1.2. op:base64Binary-equal13. Operators on NOTATION13.1. Operators on NOTATION13.1.1. op:NOTATION-equal14. Functions and Operators on Nodes14.1. fn:name14.2. fn:local-name14.3. fn:namespace-uri14.4. fn:number14.4.1. Examples14.5. fn:lang14.5.1. Examples14.6. op:is-same-node14.6.1. Examples14.7. op:node-before14.7.1. Examples14.8. op:node-after14.8.1. Examples14.9. fn:root14.9.1. Examples15. Functions and Operators on Sequences15.1. General Functions and Operators on Sequences15.1.1. fn:boolean15.1.1.1. Examples15.1.2. op:concatenate15.1.2.1. Examples15.1.3. fn:index-of15.1.3.1. Examples15.1.4. fn:empty15.1.4.1. Examples15.1.5. fn:exists15.1.5.1. Examples15.1.6. fn:distinct-values15.1.6.1. Examples15.1.7. fn:insert-before15.1.7.1. Examples15.1.8. fn:remove15.1.8.1. Examples15.1.9. fn:reverse15.1.9.1. Examples15.1.10. fn:subsequence15.1.10.1. Examples15.1.11. fn:unordered15.2. Functions That Test the Cardinality of Sequences15.2.1. fn:zero-or-one15.2.2. fn:one-or-more15.2.3. fn:exactly-one15.3. Equals, Union, Intersection and Except15.3.1. fn:deep-equal15.3.1.1. Examples15.3.2. op:union15.3.2.1. Examples15.3.3. op:intersect15.3.3.1. Examples15.3.4. op:except15.3.4.1. Examples15.4. Aggregate Functions15.4.1. fn:count15.4.1.1. Examples15.4.2. fn:avg15.4.2.1. Examples15.4.3. fn:max15.4.3.1. Examples15.4.4. fn:min15.4.4.1. Examples15.4.5. fn:sum15.4.5.1. Examples15.5. Functions and Operators that Generate Sequences15.5.1. op:to15.5.1.1. Examples15.5.2. fn:id15.5.3. fn:idref15.5.4. fn:doc15.5.5. fn:doc-available15.5.6. fn:collection15.5.7. fn:element-with-id16. Context Functions16.1. fn:position16.2. fn:last16.3. fn:current-dateTime16.3.1. Examples16.4. fn:current-date16.4.1. Examples16.5. fn:current-time16.5.1. Examples16.6. fn:implicit-timezone16.7. fn:default-collation16.8. fn:static-base-uri17. Casting17.1. Casting from primitive types to primitive types17.1.1. Casting from xs:string and xs:untypedAtomic17.1.2. Casting to xs:string and xs:untypedAtomic17.1.3. Casting to numeric types17.1.3.1. Casting to xs:float17.1.3.2. Casting to xs:double17.1.3.3. Casting to xs:decimal17.1.3.4. Casting to xs:integer17.1.4. Casting to duration types17.1.5. Casting to date and time types17.1.6. Casting to xs:boolean17.1.7. Casting to xs:base64Binary and xs:hexBinary17.1.8. Casting to xs:anyURI17.2. Casting to derived types17.3. Casting from derived types to parent types17.4. Casting within a branch of the type hierarchy17.4.1. Casting to xs:ENTITY17.5. Casting across the type hierarchyA. ReferencesA.1. Normative ReferencesA.2. Non-normative ReferencesB. Error SummaryC. Compatibility with XPath 1.0 (Non-Normative)D. Illustrative User-written Functions (Non-Normative)D.1. eg:if-empty and eg:if-absentD.1.1. eg:if-emptyD.1.2. eg:if-absentD.2. union, intersect and except on sequences of valuesD.2.1. eg:value-unionD.2.2. eg:value-intersectD.2.3. eg:value-exceptD.3. eg:index-of-nodeD.4. eg:string-padD.5. eg:distinct-nodes-stableE. Checklist of Implementation-Defined Features (Non-Normative)F. Changes since the First Edition (Non-Normative)XQuery 1.0 and XPath 2.0 Functions and OperatorsXQuery 1.0 and XPath 2.0 Functions and Operators
This page is intentionally left blank.
XQuery 1.0 and XPath 2.0 Functions and Operators
(REC-xpath-functions)
Table of Contents
1. Introduction 1.1. Conformance 1.2. Namespaces and Prefixes 1.3. Function Overloading 1.4. Function Signatures and Descriptions 1.5. Namespace Terminology 1.6. Type Hierarchy 1.7. Terminology 2. Accessors 2.1. fn:node-name 2.2. fn:nilled 2.3. fn:string 2.4. fn:data 2.5. fn:base-uri 2.6. fn:document-uri 3. The Error Function 3.1. Examples 4. The Trace Function 4.1. Examples 5. Constructor Functions 5.1. Constructor Functions for XML Schema Built-in Types 5.2. A Special Constructor Function for xs:dateTime 5.2.1. Examples 5.3. Constructor Functions for xs:QName and xs:NOTATION 5.4. Constructor Functions for User-Defined Types 6. Functions and Operators on Numerics 6.1. Numeric Types 6.2. Operators on Numeric Values 6.2.1. op:numeric-add 6.2.2. op:numeric-subtract 6.2.3. op:numeric-multiply 6.2.4. op:numeric-divide 6.2.5. op:numeric-integer-divide 6.2.5.1. Examples 6.2.6. op:numeric-mod 6.2.6.1. Examples 6.2.7. op:numeric-unary-plus 6.2.8. op:numeric-unary-minus 6.3. Comparison Operators on Numeric Values 6.3.1. op:numeric-equal 6.3.2. op:numeric-less-than 6.3.3. op:numeric-greater-than 6.4. Functions on Numeric Values 6.4.1. fn:abs 6.4.1.1. Examples 6.4.2. fn:ceiling 6.4.2.1. Examples 6.4.3. fn:floor 6.4.3.1. Examples 6.4.4. fn:round 6.4.4.1. Examples 6.4.5. fn:round-half-to-even 6.4.5.1. Examples 7. Functions on Strings 7.1. String Types 7.2. Functions to Assemble and Disassemble Strings 7.2.1. fn:codepoints-to-string 7.2.1.1. Examples 7.2.2. fn:string-to-codepoints 7.2.2.1. Examples 7.3. Equality and Comparison of Strings 7.3.1. Collations 7.3.2. fn:compare 7.3.2.1. Examples 7.3.3. fn:codepoint-equal 7.4. Functions on String Values 7.4.1. fn:concat 7.4.1.1. Examples 7.4.2. fn:string-join 7.4.2.1. Examples 7.4.3. fn:substring 7.4.3.1. Examples 7.4.4. fn:string-length 7.4.4.1. Examples 7.4.5. fn:normalize-space 7.4.5.1. Examples 7.4.6. fn:normalize-unicode 7.4.7. fn:upper-case 7.4.7.1. Examples 7.4.8. fn:lower-case 7.4.8.1. Examples 7.4.9. fn:translate 7.4.9.1. Examples 7.4.10. fn:encode-for-uri 7.4.10.1. Examples 7.4.11. fn:iri-to-uri 7.4.11.1. Examples 7.4.12. fn:escape-html-uri 7.4.12.1. Examples 7.5. Functions Based on Substring Matching 7.5.1. fn:contains 7.5.1.1. Examples 7.5.2. fn:starts-with 7.5.2.1. Examples 7.5.3. fn:ends-with 7.5.3.1. Examples 7.5.4. fn:substring-before 7.5.4.1. Examples 7.5.5. fn:substring-after 7.5.5.1. Examples 7.6. String Functions that Use Pattern Matching 7.6.1. Regular Expression Syntax 7.6.1.1. Flags 7.6.2. fn:matches 7.6.2.1. Examples 7.6.3. fn:replace 7.6.3.1. Examples 7.6.4. fn:tokenize 7.6.4.1. Examples 8. Functions on anyURI 8.1. fn:resolve-uri 9. Functions and Operators on Boolean Values 9.1. Additional Boolean Constructor Functions 9.1.1. fn:true 9.1.1.1. Examples 9.1.2. fn:false 9.1.2.1. Examples 9.2. Operators on Boolean Values 9.2.1. op:boolean-equal 9.2.2. op:boolean-less-than 9.2.3. op:boolean-greater-than 9.3. Functions on Boolean Values 9.3.1. fn:not 9.3.1.1. Examples 10. Functions and Operators on Durations, Dates and Times 10.1. Duration, Date and Time Types 10.1.1. Limits and Precision 10.2. Date/time datatype values 10.2.1. Examples 10.3. Two Totally Ordered Subtypes of Duration 10.3.1. xs:yearMonthDuration 10.3.1.1. Lexical representation 10.3.1.2. Calculating the value from the lexical representation 10.3.1.3. Canonical representation 10.3.1.4. Order relation on xs:yearMonthDuration 10.3.2. xs:dayTimeDuration 10.3.2.1. Lexical representation 10.3.2.2. Calculating the value of a xs:dayTimeDuration from the lexical representation 10.3.2.3. Canonical representation 10.3.2.4. Order relation on xs:dayTimeDuration 10.4. Comparison Operators on Duration, Date and Time Values 10.4.1. op:yearMonthDuration-less-than 10.4.2. op:yearMonthDuration-greater-than 10.4.3. op:dayTimeDuration-less-than 10.4.4. op:dayTimeDuration-greater-than 10.4.5. op:duration-equal 10.4.5.1. Examples 10.4.6. op:dateTime-equal 10.4.6.1. Examples 10.4.7. op:dateTime-less-than 10.4.8. op:dateTime-greater-than 10.4.9. op:date-equal 10.4.9.1. Examples 10.4.10. op:date-less-than 10.4.10.1. Examples 10.4.11. op:date-greater-than 10.4.11.1. Examples 10.4.12. op:time-equal 10.4.12.1. Examples 10.4.13. op:time-less-than 10.4.13.1. Examples 10.4.14. op:time-greater-than 10.4.14.1. Examples 10.4.15. op:gYearMonth-equal 10.4.15.1. Examples 10.4.16. op:gYear-equal 10.4.16.1. Examples 10.4.17. op:gMonthDay-equal 10.4.17.1. Examples 10.4.18. op:gMonth-equal 10.4.18.1. Examples 10.4.19. op:gDay-equal 10.4.19.1. Examples 10.5. Component Extraction Functions on Durations, Dates and Times 10.5.1. fn:years-from-duration 10.5.1.1. Examples 10.5.2. fn:months-from-duration 10.5.2.1. Examples 10.5.3. fn:days-from-duration 10.5.3.1. Examples 10.5.4. fn:hours-from-duration 10.5.4.1. Examples 10.5.5. fn:minutes-from-duration 10.5.5.1. Examples 10.5.6. fn:seconds-from-duration 10.5.6.1. Examples 10.5.7. fn:year-from-dateTime 10.5.7.1. Examples 10.5.8. fn:month-from-dateTime 10.5.8.1. Examples 10.5.9. fn:day-from-dateTime 10.5.9.1. Examples 10.5.10. fn:hours-from-dateTime 10.5.10.1. Examples 10.5.11. fn:minutes-from-dateTime 10.5.11.1. Examples 10.5.12. fn:seconds-from-dateTime 10.5.12.1. Examples 10.5.13. fn:timezone-from-dateTime 10.5.13.1. Examples 10.5.14. fn:year-from-date 10.5.14.1. Examples 10.5.15. fn:month-from-date 10.5.15.1. Examples 10.5.16. fn:day-from-date 10.5.16.1. Examples 10.5.17. fn:timezone-from-date 10.5.17.1. Examples 10.5.18. fn:hours-from-time 10.5.18.1. Examples 10.5.19. fn:minutes-from-time 10.5.19.1. Examples 10.5.20. fn:seconds-from-time 10.5.20.1. Examples 10.5.21. fn:timezone-from-time 10.5.21.1. Examples 10.6. Arithmetic Operators on Durations 10.6.1. op:add-yearMonthDurations 10.6.1.1. Examples 10.6.2. op:subtract-yearMonthDurations 10.6.2.1. Examples 10.6.3. op:multiply-yearMonthDuration 10.6.3.1. Examples 10.6.4. op:divide-yearMonthDuration 10.6.4.1. Examples 10.6.5. op:divide-yearMonthDuration-by-yearMonthDuration 10.6.5.1. Examples 10.6.6. op:add-dayTimeDurations 10.6.6.1. Examples 10.6.7. op:subtract-dayTimeDurations 10.6.7.1. Examples 10.6.8. op:multiply-dayTimeDuration 10.6.8.1. Examples 10.6.9. op:divide-dayTimeDuration 10.6.9.1. Examples 10.6.10. op:divide-dayTimeDuration-by-dayTimeDuration 10.6.10.1. Examples 10.7. Timezone Adjustment Functions on Dates and Time Values 10.7.1. fn:adjust-dateTime-to-timezone 10.7.1.1. Examples 10.7.2. fn:adjust-date-to-timezone 10.7.2.1. Examples 10.7.3. fn:adjust-time-to-timezone 10.7.3.1. Examples 10.8. Arithmetic Operators on Durations, Dates and Times 10.8.1. op:subtract-dateTimes 10.8.1.1. Examples 10.8.2. op:subtract-dates 10.8.2.1. Examples 10.8.3. op:subtract-times 10.8.3.1. Examples 10.8.4. op:add-yearMonthDuration-to-dateTime 10.8.4.1. Examples 10.8.5. op:add-dayTimeDuration-to-dateTime 10.8.5.1. Examples 10.8.6. op:subtract-yearMonthDuration-from-dateTime 10.8.6.1. Examples 10.8.7. op:subtract-dayTimeDuration-from-dateTime 10.8.7.1. Examples 10.8.8. op:add-yearMonthDuration-to-date 10.8.8.1. Examples 10.8.9. op:add-dayTimeDuration-to-date 10.8.9.1. Examples 10.8.10. op:subtract-yearMonthDuration-from-date 10.8.10.1. Examples 10.8.11. op:subtract-dayTimeDuration-from-date 10.8.11.1. Examples 10.8.12. op:add-dayTimeDuration-to-time 10.8.12.1. Examples 10.8.13. op:subtract-dayTimeDuration-from-time 10.8.13.1. Examples 11. Functions Related to QNames 11.1. Additional Constructor Functions for QNames 11.1.1. fn:resolve-QName 11.1.1.1. Usage Note 11.1.1.2. Examples 11.1.2. fn:QName 11.1.2.1. Examples 11.2. Functions and Operators Related to QNames 11.2.1. op:QName-equal 11.2.2. fn:prefix-from-QName 11.2.3. fn:local-name-from-QName 11.2.3.1. Examples 11.2.4. fn:namespace-uri-from-QName 11.2.4.1. Examples 11.2.5. fn:namespace-uri-for-prefix 11.2.6. fn:in-scope-prefixes 12. Operators on base64Binary and hexBinary 12.1. Comparisons of base64Binary and hexBinary Values 12.1.1. op:hexBinary-equal 12.1.2. op:base64Binary-equal 13. Operators on NOTATION 13.1. Operators on NOTATION 13.1.1. op:NOTATION-equal 14. Functions and Operators on Nodes 14.1. fn:name 14.2. fn:local-name 14.3. fn:namespace-uri 14.4. fn:number 14.4.1. Examples 14.5. fn:lang 14.5.1. Examples 14.6. op:is-same-node 14.6.1. Examples 14.7. op:node-before 14.7.1. Examples 14.8. op:node-after 14.8.1. Examples 14.9. fn:root 14.9.1. Examples 15. Functions and Operators on Sequences 15.1. General Functions and Operators on Sequences 15.1.1. fn:boolean 15.1.1.1. Examples 15.1.2. op:concatenate 15.1.2.1. Examples 15.1.3. fn:index-of 15.1.3.1. Examples 15.1.4. fn:empty 15.1.4.1. Examples 15.1.5. fn:exists 15.1.5.1. Examples 15.1.6. fn:distinct-values 15.1.6.1. Examples 15.1.7. fn:insert-before 15.1.7.1. Examples 15.1.8. fn:remove 15.1.8.1. Examples 15.1.9. fn:reverse 15.1.9.1. Examples 15.1.10. fn:subsequence 15.1.10.1. Examples 15.1.11. fn:unordered 15.2. Functions That Test the Cardinality of Sequences 15.2.1. fn:zero-or-one 15.2.2. fn:one-or-more 15.2.3. fn:exactly-one 15.3. Equals, Union, Intersection and Except 15.3.1. fn:deep-equal 15.3.1.1. Examples 15.3.2. op:union 15.3.2.1. Examples 15.3.3. op:intersect 15.3.3.1. Examples 15.3.4. op:except 15.3.4.1. Examples 15.4. Aggregate Functions 15.4.1. fn:count 15.4.1.1. Examples 15.4.2. fn:avg 15.4.2.1. Examples 15.4.3. fn:max 15.4.3.1. Examples 15.4.4. fn:min 15.4.4.1. Examples 15.4.5. fn:sum 15.4.5.1. Examples 15.5. Functions and Operators that Generate Sequences 15.5.1. op:to 15.5.1.1. Examples 15.5.2. fn:id 15.5.3. fn:idref 15.5.4. fn:doc 15.5.5. fn:doc-available 15.5.6. fn:collection 15.5.7. fn:element-with-id 16. Context Functions 16.1. fn:position 16.2. fn:last 16.3. fn:current-dateTime 16.3.1. Examples 16.4. fn:current-date 16.4.1. Examples 16.5. fn:current-time 16.5.1. Examples 16.6. fn:implicit-timezone 16.7. fn:default-collation 16.8. fn:static-base-uri 17. Casting 17.1. Casting from primitive types to primitive types 17.1.1. Casting from xs:string and xs:untypedAtomic 17.1.2. Casting to xs:string and xs:untypedAtomic 17.1.3. Casting to numeric types 17.1.3.1. Casting to xs:float 17.1.3.2. Casting to xs:double 17.1.3.3. Casting to xs:decimal 17.1.3.4. Casting to xs:integer 17.1.4. Casting to duration types 17.1.5. Casting to date and time types 17.1.6. Casting to xs:boolean 17.1.7. Casting to xs:base64Binary and xs:hexBinary 17.1.8. Casting to xs:anyURI 17.2. Casting to derived types 17.3. Casting from derived types to parent types 17.4. Casting within a branch of the type hierarchy 17.4.1. Casting to xs:ENTITY 17.5. Casting across the type hierarchy
Appendices
A. References A.1. Normative References A.2. Non-normative References B. Error Summary C. Compatibility with XPath 1.0 (Non-Normative) D. Illustrative User-written Functions (Non-Normative) D.1. eg:if-empty and eg:if-absent D.1.1. eg:if-empty D.1.2. eg:if-absent D.2. union, intersect and except on sequences of values D.2.1. eg:value-union D.2.2. eg:value-intersect D.2.3. eg:value-except D.3. eg:index-of-node D.4. eg:string-pad D.5. eg:distinct-nodes-stable E. Checklist of Implementation-Defined Features (Non-Normative) F. Changes since the First Edition (Non-Normative)
Page
of
Page
of XQuery 1.0 and XPath 2.0 Functions and OperatorsXQuery 1.0 and XPath 2.0 Functions and Operators
This page is intentionally left blank.
XQuery 1.0 and XPath 2.0 Functions and Operators
(REC-xpath-functions)
Introduction1. IntroductionThe purpose of this document is to catalog the functions and operators required for
XPath 2.0, XML Query 1.0 and XSLT 2.0. The exact syntax used to invoke these
functions and operators is specified in [XML Path Language (XPath) 2.0], [XQuery 1.0: An XML Query Language] and [XSL Transformations (XSLT) Version 2.0]. This document defines constructor functions and functions that take typed values as
arguments. Some of the functions define the semantics of operators discussed in
[XQuery 1.0: An XML Query Language].
[XML Schema Part 2: Datatypes Second Edition] defines a number of primitive and derived datatypes,
collectively known as built-in datatypes. This document defines functions and
operations on these datatypes as well as the datatypes defined in of the [XQuery 1.0 and XPath 2.0 Data Model].
These functions and operations are defined for use in [XML Path Language (XPath) 2.0],
[XQuery 1.0: An XML Query Language] and [XSL Transformations (XSLT) Version 2.0] and related XML standards. This
document also discusses functions and operators on nodes and node sequences as
defined in the [XQuery 1.0 and XPath 2.0 Data Model] for use in [XML Path Language (XPath) 2.0], [XQuery 1.0: An XML Query Language] and [XSL Transformations (XSLT) Version 2.0] and other related XML standards. References to specific sections of some of the above documents are indicated by
cross-document links in this document. Each such link consists of a pointer to a
specific section followed a superscript specifying the linked document. The
superscripts have the following meanings: 'XQ' [XQuery 1.0: An XML Query Language], 'XT' [XSL Transformations (XSLT) Version 2.0], 'XP' [XML Path Language (XPath) 2.0], 'DM' [XQuery 1.0 and XPath 2.0 Data Model] and 'FS'
[XQuery 1.0 and XPath 2.0 Formal Semantics].Conformance1.1. Conformance
The Functions and Operators specification is intended primarily as a
component that can be used by other specifications. Therefore, Functions
and Operators relies on specifications that use it (such as
[XML Path Language (XPath) 2.0], [XSL Transformations (XSLT) Version 2.0] and [XQuery 1.0: An XML Query Language])
to specify conformance criteria for their respective environments.
Authors of conformance criteria for the use of the Functions and
Operators should pay particular attention to the following features:•It is implementation-defined which version of Unicode is supported, but it is recommended that the most recent version of Unicode be used. •Support for XML 1.0 and XML 1.1 by the datatypes used in Functions and Operators.☞At the time of writing there is no published version of XML Schema
that references the XML 1.1 specifications. This means that
datatypes such as xs:NCName and xs:ID are
constrained by the XML
1.0 rules. Authors of conformance requirements for the use of
Functions and Operators should state clearly the implications for
conformance of any changes to the rules in later versions of XML
Schema.In this document, text labeled as an example or as a Note is provided for explanatory
purposes and is not normative.Namespaces and Prefixes1.2. Namespaces and PrefixesThe functions and operators discussed in this document are contained in one of
three namespaces (see [Namespaces in XML]) and referenced using an
xs:QName. The datatypes and constructor functions for the built-in datatypes defined
in [XML Schema Part 2: Datatypes Second Edition] and in
of [XQuery 1.0 and XPath 2.0 Data Model] and discussed in § 5 – Constructor Functions on page are in the XML Schema namespace, http://www.w3.org/2001/XMLSchema,
and named in this document using the xs prefix. The namespace
prefix used in this document for functions that are available to users is
fn. Operator functions are named with the prefix op. This document uses the prefix err to represent the namespace URI http://www.w3.org/2005/xqt-errors, which is the namespace for all XPath and XQuery error codes and messages. This namespace prefix is not predeclared and its use in this document is not normative. The namespace prefix used for the functions, datatypes and errors can vary, as
long as the prefix is bound to the correct URI.The URIs of the namespaces and the default prefixes associated with them are:•
http://www.w3.org/2001/XMLSchema for constructors --
associated with xs.
•
http://www.w3.org/2005/xpath-functions
for functions -- associated with fn. •
http://www.w3.org/2005/xqt-errors -- associated with
err. ☞The namespace URI associated with the err prefix is not
expected to change from one version of this document to another. The
contents of this namespace may be extended to allow additional errors to be returned.The functions defined with an fn prefix are callable by the user.
Functions defined with the op prefix are described here to
underpin the definitions of the operators in [XML Path Language (XPath) 2.0], [XQuery 1.0: An XML Query Language] and [XSL Transformations (XSLT) Version 2.0]. These functions are not available
directly to users, and there is no requirement that implementations should
actually provide these functions. For this reason, no namespace is associated
with the op prefix. For example, multiplication is generally
associated with the * operator, but it is described as a function
in this document:Function: numeric numeric-multiply(numeric, numeric)Function Overloading1.3. Function Overloading In general, the specifications named above do not support function overloading
in the sense that functions that have multiple signatures with the same name and
the same number of parameters are not supported. Consequently, there are no such
overloaded functions in this document except for legacy [XML Path Language (XPath) Version 1.0]
functions such as fn:string(), which accepts a single parameter of
a variety of types. In addition, it should be noted that the functions defined
in § 6 – Functions and Operators on Numerics on page that accept numeric
parameters accept arguments of type xs:integer,
xs:decimal, xs:float or xs:double. See
§ 1.4 – Function Signatures and Descriptions on page . Operators such as "+" may be overloaded.
This document does define some functions with more than one signature with the
same name and different number of parameters. User-defined functions with more
than one signature with the same name and different number of parameters are
also supported. Function Signatures and Descriptions1.4. Function Signatures and DescriptionsEach function is defined by specifying its signature, a description of the return
type and each of the parameters and its semantics. For many functions, examples
are included to illustrate their use. Each function's signature is presented in a form like this:Function: return-type function-name(parameter-type, )In this notation, function-name, in bold-face, is the name of the
function whose signature is being specified. If the function takes no
parameters, then the name is followed by an empty parameter list:
"()"; otherwise, the name is followed by a parenthesized list of
parameter declarations, each declaration specifies the static type of the
parameter, in italics, and a descriptive, but non-normative, name. If there are
two or more parameter declarations, they are separated by a comma. The
return-type
, also in italics, specifies the static type of the value returned by the
function. The dynamic type returned by the function is the same as its static
type or derived from the static type. All parameter types and return types are
specified using the SequenceType notation defined in .In some cases the word “
numeric
” is used in function signatures as a shorthand to indicate the four
numeric types: xs:integer, xs:decimal,
xs:float and xs:double. For example, a function with
the signature:Function: ... numeric-function(numeric)represents the following four function signatures:Function: ... numeric-function(xs:integer)Function: ... numeric-function(xs:decimal)Function: ... numeric-function(xs:float)Function: ... numeric-function(xs:double)For most functions there is an initial paragraph describing what the function
does followed by semantic rules. These rules are meant to be followed in the
order that they appear in this document.In some cases, the static type returned by a function depends on the type(s) of
its argument(s). These special functions are indicated by using
bold italics
for the return type. The semantic rules specifying the type of the value
returned are documented in the function definition. The rules are described more
formally in .The function name is a QName as defined in [XML Schema Part 2: Datatypes Second Edition]
and must adhere to its syntactic conventions. Following [XML Path Language (XPath) Version 1.0],
function names are composed of English words separated by hyphens,"-". If a
function name contains a [XML Schema Part 2: Datatypes Second Edition] datatype name, it may have
intercapitalized spelling and is used in the function name as such. For example, fn:timezone-from-dateTime.Rules for passing parameters to operators are described in the relevant sections
of [XQuery 1.0: An XML Query Language] and [XML Path Language (XPath) 2.0]. For example, the rules for
passing parameters to arithmetic operators are described in . 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 ). In addition, numeric type instances and
instances of type xs:anyURI can be promoted to produce an argument
of the required type. (See ).1.
Subtype Substitution: A derived type may substitute for
its base type. In particular, xs:integer may be used
where xs:decimal is expected.2.
Numeric Type Promotion: xs:decimal may be
promoted to xs:float or xs:double. Promotion to xs:double should be done directly, not via xs:float, to avoid loss of precision.
3.
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.Function: return-type function-name(parameter-type)Note that this function signature is different from a signature in which the
parameter is omitted. See, for example, the two signatures
for fn:string(). In the first signature, the parameter is omitted
and the argument defaults to the context item, referred to as “.”.
In the second signature, the argument must be present but may be the empty
sequence, referred to as “().”
Some functions accept a sequence of zero or more values as an argument. This is
indicated by following the name of type of the items in the sequence with
*. The sequence may contain zero or more items of the named type.
For example, the function below accepts a sequence of xs:double and
returns a xs:double or the empty sequence.Function: xs:double median(xs:double*)Namespace Terminology1.5. Namespace TerminologyThis document uses the phrase "namespace URI" to identify the concept identified
in [Namespaces in XML] as "namespace name", and the phrase "local name"
to identify the concept identified in [Namespaces in XML] as "local part".It also uses the term “expanded-QName” defined below.
Expanded-QName
An expanded-QName is a pair of values consisting of a namespace URI
and a local name. They belong to the value space of the [XML Schema Part 2: Datatypes Second Edition] datatype xs:QName. When this document
refers to xs:QName we always mean the value space, i.e.
a namespace URI, local name pair (and not the lexical space
referring to constructs of the form prefix:local-name).Type Hierarchy1.6. Type HierarchyThe diagram below shows the types for which functions are defined in this
document. These include the built-in types defined by [XML Schema Part 2: Datatypes Second Edition]
(shown on the right) as well as types defined in [XQuery 1.0 and XPath 2.0 Data Model]
(shown on the left). Solid lines connect a base datatype above to a derived
datatype.xs:IDREFS, xs:NMTOKENS,
xs:ENTITIES and user-defined list and union types are
special types in that these types are lists or unions rather than true subtypes.
Dashed lines connect a union type above with its component types below.The information in the above diagram is reproduced below in tabular form. For
ease of presentation the information is divided into three tables. The first
table shows the top three layers of the hierarchy starting at
xs:anyType. The second table shows the types derived from
xs:anyAtomicType. The third table shows the types defined in
[XQuery 1.0 and XPath 2.0 Data Model]
Each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.xs:anyType
user-defined complex types
xs:untyped
xs:anySimpleType
user-defined list and union types
xs:IDREFS
xs:NMTOKENS
xs:ENTITIES
xs:anyAtomicType
The table below shows the datatypes derived from xs:anyAtomicType.
This includes all the [XML Schema Part 2: Datatypes Second Edition] built-in datatypes as well as the
two totally ordered subtypes of duration defined in . Each type whose name is indented is derived from the type whose name appears
nearest above it with one less level of indentation.xs:untypedAtomic
xs:dateTime
xs:date
xs:time
xs:duration
xs:yearMonthDuration
xs:dayTimeDuration
xs:float
xs:double
xs:decimal
xs:integer
xs:nonPositiveInteger
xs:negativeInteger
xs:long
xs:int
xs:short
xs:byte
xs:nonNegativeInteger
xs:unsignedLong
xs:unsignedInt
xs:unsignedShort
xs:unsignedByte
xs:positiveInteger
xs:gYearMonth
xs:gYear
xs:gMonthDay
xs:gDay
xs:gMonth
xs:string
xs:normalizedString
xs:token
xs:language
xs:NMTOKEN
xs:Name
xs:NCName
xs:ID
xs:IDREF
xs:ENTITY
xs:boolean
xs:base64Binary
xs:hexBinary
xs:anyURI
xs:QName
xs:NOTATION
The table below shows the type hierarchy for the types introduced in [XQuery 1.0 and XPath 2.0 Data Model]. For these types, each type whose name is indented is a
component of the union type whose name appears nearest above with one less level
of indentation.item
xs:anyAtomicType
node
attribute
user-defined attribute types
comment
document
user-defined document types
element
user-defined element types
processing-instruction
text
Terminology1.7. TerminologyThe terminology used to describe the functions and operators on [XML Schema Part 2: Datatypes Second Edition] is defined in the body of this specification. The terms defined
in the following list are used in building those definitions:
for compatibility
A feature of this specification included to ensure that
implementations that use this feature remain compatible with [XML Path Language (XPath) Version 1.0]
may
Conforming documents and processors are permitted to, but need not,
behave as described.
must
Conforming documents and processors are required to behave as
described; otherwise, they are either non-conformant or else in error.
implementation-defined
Possibly differing between implementations, but specified and
documented by the implementor for each particular implementation.
implementation-dependent
Possibly differing between implementations, but not specified by this
or other W3C specification, and not required to be specified by the
implementor for any particular implementation.
execution scope
The scope over which any two calls on a function would be executed.
In XSLT, it applies to any two calls on the function executed during
the same transformation. In XQuery, it applies to any two calls
executed during the evaluation of a top-level expression i.e. an
expression not contained in any other expression. In other contexts,
the scope is specified by the host environment that invokes the
function library.
stable
Most of the functions in the core library have the property that
calling the same function twice within an execution scope with the same arguments returns the same
result: these functions are said to be stable. This
category includes a number of functions such as
fn:doc(), fn:collection(),
fn:current-dateTime(), fn:current-date and
fn:current-time() whose result depends on the external
environment. Where the function returns nodes, stability means that
the returned nodes are identical, not merely equal and are returned
in the same order.☞in the case of fn:collection() and fn:doc(), the
requirement for stability may be relaxed: see the function definitions for details. Some other functions, for example fn:position() and
fn:last(), depend on the dynamic context and may,
therefore, produce different results each time they are called.
These functions are said to be contextual.
URI and URI reference
Within this specification, the term "URI" refers to Universal Resource Identifiers as
defined in [RFC 3986] and extended in [RFC 3987] with a new name "IRI". The term "URI
Reference", unless otherwise stated, refers to a string in the lexical space of the xs:anyURI datatype as defined in [XML Schema Part 2: Datatypes Second Edition]. Note that this means, in practice, that where this specification requires a "URI Reference", an IRI as defined in [RFC 3987] will be accepted, provided that other relevant specifications also permit an IRI. The term URI has been retained in preference to IRI to avoid introducing new names for concepts such as "Base URI" that are defined or referenced across the whole family of XML specifications. Note also that the definition of xs:anyURI is a wider definition than the definition in [RFC 3987]; for example it does not require non-ASCII characters to be escaped.
Accessors2. AccessorsAccessors and their semantics are described in [XQuery 1.0 and XPath 2.0 Data Model]. Some of
these accessors are exposed to the user through the functions described below.Function
Accessor
Accepts
Returns
fn:node-name
node-name
an optional node
zero or one xs:QName
fn:nilled
nilled
a node
an optional xs:boolean
fn:string
string-value
an optional item or no argument
xs:string
fn:data
typed-value
zero or more items
a sequence of atomic values
fn:base-uri
base-uri
an optional node or no argument
zero or one xs:anyURI
fn:document-uri
document-uri
an optional node
zero or one xs:anyURI
fn:node-name2.1. fn:node-nameFunction: xs:QName node-name(node())Summary: Returns an expanded-QName for node kinds that can have names. For other
kinds of nodes it returns the empty sequence. If $arg is the empty
sequence, the empty sequence is returned.fn:nilled2.2. fn:nilledFunction: xs:boolean nilled(node())Summary: Returns an xs:boolean indicating whether the argument node
is “nilled”. If the argument is not an element node, returns the
empty sequence. If the argument is the empty sequence, returns the empty sequence.fn:string2.3. fn:stringFunction: xs:string string()Function: xs:string string(item())Summary: Returns the value of $arg represented as a
xs:string. If no argument is supplied, the context item (.) is used as the default argument. The behavior of the function if the argument is omitted is exactly the same as if the context item had been passed as the argument.If the context item is undefined, error is raised.If $arg is the empty sequence, the zero-length string is returned.If $arg is a node, the function returns the string-value of the
node, as obtained using the dm:string-value accessor defined in the
.If $arg is an atomic value, then the function returns the same
string as is returned by the expression “
$arg cast as xs:string
” (see § 17 – Casting on page ).fn:data2.4. fn:dataFunction: xs:anyAtomicType* data(item()*)Summary: fn:data takes a sequence of items and returns a sequence of
atomic values. The result of fn:data is the sequence of atomic values produced by
applying the following rules to each item in $arg:•If the item is an atomic value, it is returned.• If the item is a node:-If the node does not have a typed value an error is
raised . -Otherwise, fn:data() returns the typed value of the
node as defined by the accessor function
dm:typed-value in .fn:base-uri2.5. fn:base-uriFunction: xs:anyURI base-uri()Function: xs:anyURI base-uri(node())Summary: Returns the value of the base-uri URI property for $arg as
defined by the accessor function dm:base-uri() for that kind of
node in . If $arg is not
specified, the behavior is identical to calling the function with the context item (.) as argument. The following errors may be raised: if the context item is undefined ; if the context item is not a node
.If $arg is the empty sequence, the empty sequence is returned.Document, element and processing-instruction nodes have a base-uri property which
may be empty. The base-uri property of all other node types is the empty
sequence. The value of the base-uri property is returned if it exists and is not
empty. Otherwise, if the node has a parent, the value of
dm:base-uri() applied to its parent is returned, recursively. If the node does not have a parent, or if the recursive ascent up the ancestor chain encounters a node whose base-uri property is empty and it does not have a parent, the empty sequence is returned.See also fn:static-base-uri.fn:document-uri2.6. fn:document-uriFunction: xs:anyURI document-uri(node())Summary: Returns the value of the document-uri property for $arg as
defined by the dm:document-uri accessor function defined in
.If $arg is the empty sequence, the empty sequence is returned.Returns the empty sequence if the node is not a document node. Otherwise, returns
the value of the dm:document-uri accessor of the document node.In the case of a document node $D returned by the fn:doc function, or a document node at the root of a tree containing a node returned by the fn:collection function, it will always be true that either fn:document-uri($D) returns the empty sequence, or that the following expression is true: fn:doc(fn:document-uri($D)) is $D. It is implementation-defined whether this guarantee also holds for document nodes obtained by other means, for example a document node passed as the initial context node of a query or transformation.The Error Function3. The Error FunctionIn this document, as well as in [XQuery 1.0: An XML Query Language], [XML Path Language (XPath) 2.0], and
[XQuery 1.0 and XPath 2.0 Formal Semantics], the phrase “an error is raised”
is used. Raising an error is equivalent to invoking the fn:error
function defined in this section with the provided error code. The above phrase is normally accompanied by specification of a specific error, to
wit: “an error is raised [error code]”. Each error defined
in this document is identified by an xs:QName that is in the
http://www.w3.org/2005/xqt-errors namespace, represented in this document by the err prefix. It is this
xs:QName that is actually passed as an argument to the
fn:error function invocation. Invocation of this function raises an error. For a
more detailed treatment of error handing, see and .The fn:error function is a general function that may be invoked as above
but may also be invoked from [XQuery 1.0: An XML Query Language] or [XML Path Language (XPath) 2.0]
applications with, for example, an xs:QName argument. Function: none error()Function: none error(xs:QName)Function: none error(xs:QName, xs:string)Function: none error(xs:QName, xs:string, item()*)Summary: The fn:error function raises an error. While this function never returns a value, an
error is returned to the external processing environment as an
xs:anyURI or an xs:QName. The error xs:anyURI
is derived from the error xs:QName. An error xs:QName with
namespace URI NS and local part LP will be returned as the xs:anyURI
NS#LP. The method by which the xs:anyURI or xs:QName is
returned to the external processing environment is implementation dependent. If an invocation provides $description and $error-object,
then these values may also be returned to the external processing environment. The
method by which these values are provided to the external environment is implementation dependent. ☞
The value of the $description parameter may need to be localized.
Note that “none” is a special type defined in [XQuery 1.0 and XPath 2.0 Formal Semantics] and is not available to the user. It indicates that the
function never returns and ensures that it has the correct static type.If fn:error is invoked with no arguments, then its behavior is the same
as the invocation of the following expression: fn:error(fn:QName('http://www.w3.org/2005/xqt-errors', 'err:FOER0000')) If the first argument in the third or fourth signature is the empty sequence it is
assumed to be the xs:QName constructed by: fn:QName('http://www.w3.org/2005/xqt-errors', 'err:FOER0000')Examples3.1. Examples•
fn:error() returns
http://www.w3.org/2005/xqt-errors#FOER0000 (or the corresponding xs:QName) to the
external processing environment.•
fn:error(fn:QName('http://www.example.com/HR', 'myerr:toohighsal'),
'Does not apply because salary is too high') returns
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.The Trace Function4. The Trace FunctionFunction: item()* trace(item()*, xs:string)Summary: Provides an execution trace intended to be used in debugging
queries.The input $value is returned, unchanged, as the result of the function.
In addition, the inputs $value, converted to an xs:string,
and $label may be directed to a trace data set. The destination of the
trace output is implementation-defined. The format of the trace
output is implementation dependent. The ordering of output from
invocations of the fn:trace() function is implementation dependent.Examples4.1. Examples•Consider a situation in which a user wants to investigate the actual
value passed to a function. Assume that in a particular execution,
$v is an xs:decimal with value
124.84. Writing fn:trace($v, 'the value of $v
is:') will put the strings "124.84" and "the
value of $v is:" in the trace data set in implementation
dependent order.Constructor Functions5. Constructor FunctionsConstructor Functions for XML Schema Built-in Types5.1. Constructor Functions for XML Schema Built-in TypesEvery built-in atomic type that is defined in [XML Schema Part 2: Datatypes Second Edition], except xs:anyAtomicType and xs:NOTATION, has an
associated constructor function. xs:untypedAtomic, defined
in and the two derived types
xs:yearMonthDuration and xs:dayTimeDuration defined
in also have associated constructor functions.
A constructor function is not defined for xs:anyAtomicType as there are no atomic values with type annotation xs:anyAtomicType at runtime, although this can be a statically inferred type.
A constructor function is not defined for xs:NOTATION since it is defined as an abstract type in [XML Schema Part 2: Datatypes Second Edition]. If the static context (See ) contains a type derived from
xs:NOTATION then a constructor function is defined for it.
See § 5.4 – Constructor Functions for User-Defined Types on page .
The form of the constructor function for a type
prefix:TYPE is:Function: prefix:TYPE prefix:TYPE(xs:anyAtomicType)If $arg is the empty sequence, the empty sequence is returned. For
example, the signature of the constructor function corresponding to the
xs:unsignedInt type defined in [XML Schema Part 2: Datatypes Second Edition] is:Function: xs:unsignedInt unsignedInt(xs:anyAtomicType)Invoking the constructor function xs:unsignedInt(12) returns
the xs:unsignedInt value 12. Another invocation of that constructor
function that returns the same xs:unsignedInt value is
xs:unsignedInt("12"). The same result would also be returned if the
constructor function were to be invoked with a node that had a typed value equal
to the xs:unsignedInt 12. The standard features described in
would 'atomize' the node to
extract its typed value and then call the constructor with that value. If the
value passed to a constructor is illegal for the datatype to be constructed, an
error is raised .The semantics of the constructor function “
xs:TYPE(arg)
” are identical to the semantics of “
arg cast as xs:TYPE?
”. See § 17 – Casting on page .If the argument to a constructor function is a literal, the result of the
function may be evaluated statically; if an error is found during such
evaluation, it may be reported as a static error. Special rules apply to constructor functions for xs:QName and types derived from xs:QName and xs:NOTATION. See
§ 5.3 – Constructor Functions for xs:QName and xs:NOTATION on page .
The following constructor functions for the built-in types are supported:•Function: xs:string string(xs:anyAtomicType)•Function: xs:boolean boolean(xs:anyAtomicType)•Function: xs:decimal decimal(xs:anyAtomicType)•Function: xs:float float(xs:anyAtomicType)Implementations may return negative zero for xs:float("-0.0E0"). [XML Schema Part 2: Datatypes Second Edition] does not distinguish between the values positive zero and negative zero.
•Function: xs:double double(xs:anyAtomicType)Implementations may return negative zero for xs:double("-0.0E0"). [XML Schema Part 2: Datatypes Second Edition] does not distinguish between the values positive zero and negative zero.
•Function: xs:duration duration(xs:anyAtomicType)•Function: xs:dateTime dateTime(xs:anyAtomicType)•Function: xs:time time(xs:anyAtomicType)•Function: xs:date date(xs:anyAtomicType)•Function: xs:gYearMonth gYearMonth(xs:anyAtomicType)•Function: xs:gYear gYear(xs:anyAtomicType)•Function: xs:gMonthDay gMonthDay(xs:anyAtomicType)•Function: xs:gDay gDay(xs:anyAtomicType)•Function: xs:gMonth gMonth(xs:anyAtomicType)•Function: xs:hexBinary hexBinary(xs:anyAtomicType)•Function: xs:base64Binary base64Binary(xs:anyAtomicType)•Function: xs:anyURI anyURI(xs:anyAtomicType)•Function: xs:QName QName(xs:anyAtomicType)
See § 5.3 – Constructor Functions for xs:QName and xs:NOTATION on page for special rules.•Function: xs:normalizedString normalizedString(xs:anyAtomicType)•Function: xs:token token(xs:anyAtomicType)•Function: xs:language language(xs:anyAtomicType)•Function: xs:NMTOKEN NMTOKEN(xs:anyAtomicType)•Function: xs:Name Name(xs:anyAtomicType)•Function: xs:NCName NCName(xs:anyAtomicType)•Function: xs:ID ID(xs:anyAtomicType)•Function: xs:IDREF IDREF(xs:anyAtomicType)•Function: xs:ENTITY ENTITY(xs:anyAtomicType)See § 17.4.1 – Casting to xs:ENTITY on page for rules related to constructing values of type xs:ENTITY and types derived from it.•Function: xs:integer integer(xs:anyAtomicType)•Function: xs:nonPositiveInteger nonPositiveInteger(xs:anyAtomicType)•Function: xs:negativeInteger negativeInteger(xs:anyAtomicType)•Function: xs:long long(xs:anyAtomicType)•Function: xs:int int(xs:anyAtomicType)•Function: xs:short short(xs:anyAtomicType)•Function: xs:byte byte(xs:anyAtomicType)•Function: xs:nonNegativeInteger nonNegativeInteger(xs:anyAtomicType)•Function: xs:unsignedLong unsignedLong(xs:anyAtomicType)•Function: xs:unsignedInt unsignedInt(xs:anyAtomicType)•Function: xs:unsignedShort unsignedShort(xs:anyAtomicType)•Function: xs:unsignedByte unsignedByte(xs:anyAtomicType)•Function: xs:positiveInteger positiveInteger(xs:anyAtomicType)•Function: xs:yearMonthDuration yearMonthDuration(xs:anyAtomicType)•Function: xs:dayTimeDuration dayTimeDuration(xs:anyAtomicType)•Function: xs:untypedAtomic untypedAtomic(xs:anyAtomicType)A Special Constructor Function for xs:dateTime5.2. A Special Constructor Function for xs:dateTimeA special constructor function is provided for constructing a
xs:dateTime value from a xs:date value and a
xs:time value.Function: xs:dateTime dateTime(xs:date, xs:time)The result xs:dateTime has a date component whose value is equal to
$arg1 and a time component whose value is equal
to $arg2. The result is the empty sequence if either of the parameters is the empty sequence.
The timezone of the result is computed as follows:•If neither argument has a timezone, the result has no timezone.•If exactly one of the arguments has a timezone, or if both arguments have
the same timezone, the result has this timezone.•If the two arguments have different timezones, an error is
raised:
5.2.1. Examples•
fn:dateTime(xs:date("1999-12-31"), xs:time("12:00:00")) returns xs:dateTime("1999-12-31T12:00:00").•
fn:dateTime(xs:date("1999-12-31"), xs:time("24:00:00")) returns
xs:dateTime("1999-12-31T00:00:00") because "24:00:00" is an alternate lexical form for "00:00:00".
Constructor Functions for xs:QName and xs:NOTATION5.3. Constructor Functions for xs:QName and xs:NOTATIONSpecial rules apply to constructor functions for the types xs:QName and xs:NOTATION, for two reasons:•
The lexical representation of these types uses namespace prefixes, whose
meaning is context-dependent.•
Values cannot belong directly to the type xs:NOTATION, only to its subtypes.
These constraints result in the following restrictions:•
Conversion from an xs:string to a value of type xs:QName, a type derived from xs:QName or a type derived from xs:NOTATION is permitted only if the xs:string is written as a string literal. This applies whether the conversion is expressed using a constructor function or using the "cast as" syntax. Such a conversion can be regarded as a pseudo-function, which is always evaluated statically. It is also permitted for these constructors and casts to take a dynamically-supplied argument in the normal manner, but as the casting table (see § 17.1 – Casting from primitive types to primitive types on page ) indicates, the only
arguments that are supported in this case are values of type xs:QName or xs:NOTATION respectively.•
There is no constructor function for xs:NOTATION. Constructors are defined, however, for xs:QName, for types derived from xs:QName, and for types derived from xs:NOTATION.
When converting from an xs:string, the prefix within the lexical
xs:QName supplied
as the argument is resolved to a namespace URI using the statically known
namespaces from the static context. If the lexical xs:QName
has no prefix, the
namespace URI of the resulting expanded-QName is the default element/type
namespace from the static context. Components of the static context are
discussed in . A static error is raised
if the prefix is not bound in the static context. As described in
, the supplied prefix is retained as part of the
expanded-QName value.
Constructor Functions for User-Defined Types5.4. Constructor Functions for User-Defined Types For every atomic type in the static context (See ) that is derived from a primitive type, there is a
constructor function (whose name is the same as the name of the type) whose
effect is to create a value of that type from the supplied argument. The rules
for constructing user-defined types are defined in the same way as the rules for
constructing built-in derived types discussed in § 5.1 – Constructor Functions for XML Schema Built-in Types on page .
Special rules apply to constructor functions for types derived from xs:QName and xs:NOTATION. See § 5.3 – Constructor Functions for xs:QName and xs:NOTATION on page .Consider a situation where the static context contains a type
called hatSize defined in a schema whose target namespace is bound
to the prefix my. In such a case the constructor function:Function: my:hatSize my:hatSize(xs:anyAtomicType)is available to users. To construct an instance of an atomic type that is not in a namespace, it is
necessary to use a cast expression or undeclare the default function namespace. For example, if the user-defined type apple is derived
from xs:integer but is not in a namespace, an instance of this type
can be constructed as follows using a cast expression (this requires that the
default element/type namespace is no namespace):17 cast as apple The following shows the use of the constructor function:declare default function namespace ""; apple(17)Functions and Operators on Numerics6. Functions and Operators on NumericsThis section discusses arithmetic operators on the numeric datatypes defined in
[XML Schema Part 2: Datatypes Second Edition]. It uses an approach that permits lightweight
implementation whenever possible. Numeric Types6.1. Numeric TypesThe operators described in this section are defined on the following numeric
types. Each type whose name is indented is derived from the type whose name
appears nearest above with one less level of indentation.xs:decimal
xs:integer
xs:float
xs:double
They also apply to types derived by restriction from the above types. ☞
This specification uses [IEEE 754-1985] arithmetic for xs:float and xs:double values.
This differs from [XML Schema Part 2: Datatypes Second Edition] which defines
NaN as being equal to itself and defines only a single zero in the value space while [IEEE 754-1985] arithmetic treats NaN as unequal to all other values including itself and can produce distinct results of positive zero and negative zero. (These are two different machine representations for the same [XML Schema Part 2: Datatypes Second Edition] value.) The text accompanying several functions discusses behaviour for both positive and negative zero inputs and outputs in the interest of alignment with [IEEE 754-1985].
Operators on Numeric Values6.2. Operators on Numeric ValuesThe following functions define the semantics of operators defined in [XQuery 1.0: An XML Query Language] and [XML Path Language (XPath) 2.0] on these numeric types. Operators
Meaning
op:numeric-add
Addition
op:numeric-subtract
Subtraction
op:numeric-multiply
Multiplication
op:numeric-divide
Division
op:numeric-integer-divide
Integer division
op:numeric-mod
Modulus
op:numeric-unary-plus
Unary plus
op:numeric-unary-minus
Unary minus (negation)
The parameters and return types for the above operators are the basic numeric
types: xs:integer, xs:decimal, xs:float
and xs:double, and types derived from them. The word “numeric” in function signatures signifies these four types. For simplicity, each
operator is defined to operate on operands of the same type and return the same
type. The exceptions are op:numeric-divide, which returns
an xs:decimal if called with two xs:integer operands
and op:numeric-integer-divide which always returns an xs:integer.If the two operands are not of the same type, subtype substitution
and numeric type promotion are used to obtain two operands of the
same type. and describe the semantics of these operations in
detail. The result type of operations depends on their argument datatypes and is defined
in the following table:Operator
Returns
op:operation(xs:integer, xs:integer)
xs:integer (except for op:numeric-divide(integer,
integer), which returns xs:decimal)
op:operation(xs:decimal, xs:decimal)
xs:decimal
op:operation(xs:float, xs:float)
xs:float
op:operation(xs:double, xs:double)
xs:double
op:operation(xs:integer)
xs:integer
op:operation(xs:decimal)
xs:decimal
op:operation(xs:float)
xs:float
op:operation(xs:double)
xs:double
These rules define any operation on any pair of arithmetic types. Consider the
following example:op:operation(xs:int, xs:double) => op:operation(xs:double, xs:double)For this operation, xs:int must be converted to
xs:double. This can be done, since by the rules above:
xs:int can be substituted for xs:integer,
xs:integer can be substituted for xs:decimal,
xs:decimal can be promoted to xs:double. As far as possible, the promotions should be done in a
single step. Specifically, when an xs:decimal is promoted to an
xs:double, it should not be converted to an xs:float
and then to xs:double, as this risks loss of precision.As another example, a user may define height as a derived type of
xs:integer with a minimum value of 20 and a maximum value of 100.
He may then derive fenceHeight using an enumeration to restrict the
permitted set of values to, say, 36, 48 and 60.op:operation(fenceHeight, xs:integer) => op:operation(xs:integer, xs:integer)
fenceHeight can be substituted for its base type
height and height can be substituted for its base type
xs:integer. On overflow and underflow situations during arithmetic operations conforming
implementations must behave as follows:•For xs:float and xs:double operations, overflow
behavior must be conformant with [IEEE 754-1985]. This specification allows the following options:-Raising an error via an
overflow trap.-Returning INF or -INF.-Returning the largest (positive or negative) non-infinite number.•For xs:float and xs:double operations,
underflow behavior must be conformant with [IEEE 754-1985]. This specification allows the following options:-Raising an error via an
underflow trap.-Returning 0.0E0 or +/- 2**Emin or a
denormalized value; where Emin is the smallest
possible xs:float or xs:double exponent.•For xs:decimal operations, overflow behavior must raise an error . On
underflow, 0.0 must be returned.•For xs:integer operations, implementations that support
limited-precision integer operations must select from
the following options:- They may choose to always raise an
error .- They may provide an implementation-defined mechanism that allows users to
choose between raising an error and returning a result that is
modulo the largest representable integer value. See [ISO 10967].The functions op:numeric-add, op:numeric-subtract,
op:numeric-multiply, op:numeric-divide,
op:numeric-integer-divide and op:numeric-mod are each
defined for pairs of numeric operands, each of which has the same
type:xs:integer, xs:decimal, xs:float, or
xs:double. The functions op:numeric-unary-plus and
op:numeric-unary-minus are defined for a single operand whose type
is one of those same numeric types. For xs:float and xs:double arguments, if either
argument is NaN, the result is NaN.For xs:decimal values the number of digits of precision returned by
the numeric operators is implementation-defined. If the number
of digits in the result exceeds the number of digits that the implementation
supports, the result is truncated or rounded in an implementation-defined manner.6.2.1. op:numeric-addFunction: numeric numeric-add(numeric, numeric)Summary: Backs up the "+" operator and returns the arithmetic sum of its
operands: ($arg1 + $arg2).☞ For xs:float or xs:double values, if one of
the operands is a zero or a finite number and the other
is INF or -INF, INF or
-INF is returned. If both operands are INF,
INF is returned. If both operands are -INF,
-INF is returned. If one of the operands is
INF and the other is -INF, NaN is returned.6.2.2. op:numeric-subtractFunction: numeric numeric-subtract(numeric, numeric)Summary: Backs up the "-" operator and returns the arithmetic difference of
its operands: ($arg1 - $arg2).☞ For xs:float or xs:double values, if one of
the operands is a zero or a finite number and the other
is INF or -INF, an infinity of the appropriate
sign is returned. If both operands are INF or
-INF, NaN is returned. If one of the operands
is INF and the other is -INF, an infinity of
the appropriate sign is returned.6.2.3. op:numeric-multiplyFunction: numeric numeric-multiply(numeric, numeric)Summary: Backs up the "*" operator and returns the arithmetic product of its
operands: ($arg1 * $arg2).☞ For xs:float or xs:double values, if one of
the operands is a zero and the other is an infinity, NaN is
returned. If one of the operands is a non-zero number and the other
is an infinity, an infinity with the appropriate sign is returned.6.2.4. op:numeric-divideFunction: numeric numeric-divide(numeric, numeric)Summary: Backs up the "div" operator and returns the arithmetic quotient of
its operands: ($arg1 div $arg2).As a special case, if the types of both $arg1 and
$arg2 are xs:integer, then the return type is xs:decimal.For xs:decimal and xs:integer operands, if the
divisor is (positive or negative) zero, an error is raised .
For xs:float and xs:double operands, floating point
division is performed as specified in [IEEE 754-1985]. For xs:float or xs:double values, a positive
number divided by positive zero returns INF. A negative number
divided by positive zero returns -INF. Division by negative zero
returns -INF and INF, respectively. Positive or negative zero
divided by positive or negative zero returns NaN. Also, INF or -INF divided
by INF or -INF returns NaN.6.2.5. op:numeric-integer-divideFunction: xs:integer numeric-integer-divide(numeric, numeric)Summary: This function backs up the "idiv" operator by performing an integer
division.If $arg2 is (positive or negative) zero, then an error is raised
. If either operand is NaN or
if $arg1 is INF or -INF then
an error is raised . If $arg2 is
INF or -INF (and $arg1 is not) then the result is zero.Otherwise, subject to limits of precision and overflow/underflow conditions,
the result is the largest (furthest from zero) xs:integer value $N such that
fn:abs($N * $arg2) le fn:abs($arg1) and fn:compare($N * $arg2, 0) eq
fn:compare($arg1, 0).☞The second term in this condition ensures that the result has the correct sign.The implementation may adopt a different algorithm provided that it is
equivalent to this formulation in all cases where implementation-dependent or
implementation-defined behavior does not affect the outcome, for example, the
implementation-defined precision of the result of xs:decimal division.☞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++.6.2.5.1. Examples•
op:numeric-integer-divide(10,3) returns 3
•
op:numeric-integer-divide(3,-2) returns -1
•
op:numeric-integer-divide(-3,2) returns -1
•
op:numeric-integer-divide(-3,-2) returns 1
•
op:numeric-integer-divide(9.0,3) returns 3
•
op:numeric-integer-divide(-3.5,3) returns -1
•
op:numeric-integer-divide(3.0,4) returns 0
•
op:numeric-integer-divide(3.1E1,6) returns 5
•
op:numeric-integer-divide(3.1E1,7) returns 4
6.2.6. op:numeric-modFunction: numeric numeric-mod(numeric, numeric)Summary: Backs up the "mod" operator. Informally, this function returns the
remainder resulting from dividing $arg1, the dividend, by
$arg2, the divisor. The operation a mod b for
operands that are xs:integer or xs:decimal, or
types derived from them, produces a result such that (a idiv b)*b+(a
mod b) is equal to 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:integer and xs:decimal operands, if
$arg2 is zero, then an error is raised . 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 754-1985] rounding division i.e. additional
digits are truncated, not rounded to the required precision.6.2.6.1. Examples•
op:numeric-mod(10,3) returns 1.•
op:numeric-mod(6,-2) returns 0.•
op:numeric-mod(4.5,1.2) returns 0.9.•
op:numeric-mod(1.23E2, 0.6E1) returns 3.0E0.6.2.7. op:numeric-unary-plusFunction: numeric numeric-unary-plus(numeric)Summary: Backs up the unary "+" operator and returns its operand with the
sign unchanged: (+ $arg).The returned value is equal to $arg, and is an instance of
xs:integer, xs:decimal, xs:double, or xs:float
depending on the type of $arg.6.2.8. op:numeric-unary-minusFunction: numeric numeric-unary-minus(numeric)Summary: Backs up the unary "-" operator and returns its operand with the
sign reversed: (- $arg).The returned value is an instance of
xs:integer, xs:decimal, xs:double, or xs:float
depending on the type of $arg.For xs:integer and xs:decimal arguments,
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.Comparison Operators on Numeric Values6.3. Comparison Operators on Numeric ValuesThis specification defines the following comparison operators on numeric values.
Comparisons take two arguments of the same type. If the arguments are of
different types, one argument is promoted to the type of the other as described
above in § 6.2 – Operators on Numeric Values on page . Each comparison operator returns a boolean
value. If either, or both, operands are NaN, false is
returned. Operator
Meaning
op:numeric-equal
Equality comparison
op:numeric-less-than
Less-than comparison
op:numeric-greater-than
Greater-than comparison
6.3.1. op:numeric-equalFunction: xs:boolean numeric-equal(numeric, numeric)Summary: Returns true if and only if the value of $arg1 is equal
to the value of $arg2. For xs:float and
xs:double values, positive zero and negative zero compare
equal. INF equals INF and -INF equals
-INF. NaN does not equal itself.This function backs up the "eq", "ne", "le" and "ge" operators on numeric values.6.3.2. op:numeric-less-thanFunction: xs:boolean numeric-less-than(numeric, numeric)Summary: Returns true if and only if $arg1 is less
than $arg2. For xs:float and
xs:double values, positive infinity is greater than all other
non-NaN values; negative infinity is less than all other
non-NaN values. If $arg1 or $arg2 is
NaN, the function returns false.This function backs up the "lt" and "le" operators on numeric values.6.3.3. op:numeric-greater-thanFunction: xs:boolean numeric-greater-than(numeric, numeric)Summary: Returns true if and only if $arg1 is
greater than $arg2. For xs:float and
xs:double values, positive infinity is greater than all other
non-NaN values; negative infinity is less than all other
non-NaN values. If $arg1 or $arg2 is
NaN, the function returns false.This function backs up the "gt" and "ge" operators on numeric values.Functions on Numeric Values6.4. Functions on Numeric ValuesThe following functions are defined on numeric types. Each function returns a
value of the same type as the type of its argument.•If the argument is the empty sequence, the empty sequence is returned.•For xs:float and xs:double arguments, if the
argument is "NaN", "NaN" is returned.•Except for fn:abs(), for xs:float and
xs:double arguments, if the argument is positive or
negative infinity, positive or negative infinity is returned.Function
Meaning
fn:abs
Returns the absolute value of the argument.
fn:ceiling
Returns the smallest number with no fractional part that is greater
than or equal to the argument.
fn:floor
Returns the largest number with no fractional part that is less than
or equal to the argument.
fn:round
Rounds to the nearest number with no fractional part.
fn:round-half-to-even
Takes a number and a precision and returns a number rounded to the
given precision. If the fractional part is exactly half, the result
is the number whose least significant digit is even.
6.4.1. fn:absFunction: numeric abs(numeric)Summary: Returns the absolute value of $arg. If
$arg is negative returns -$arg otherwise returns
$arg. If type of $arg is one of the four numeric
types xs:float, xs:double, xs:decimal
or xs:integer the type of the result is the same as the type of
$arg. If the type of $arg is a type derived from
one of the numeric types, the result is an instance of the base numeric type.For xs:float and xs:double arguments, if the
argument is positive zero or negative zero, then positive zero
is returned. If the argument is positive or negative infinity, positive
infinity is returned.For detailed type semantics, see
6.4.1.1. Examples•
fn:abs(10.5) returns 10.5. •
fn:abs(-10.5) returns 10.5. 6.4.2. fn:ceilingFunction: numeric ceiling(numeric)Summary: Returns the smallest (closest to negative infinity) number with no
fractional part that is not less than the value of $arg. If
type of $arg is one of the four numeric types
xs:float, xs:double, xs:decimal or
xs:integer the type of the result is the same as the type of
$arg. If the type of $arg is a type derived from
one of the numeric types, the result is an instance of the base numeric type.For xs:float and xs:double arguments, if the
argument is positive zero, then positive zero is returned. If the
argument is negative zero, then negative zero is returned. If the
argument is less than zero and greater than -1, negative zero is returned.For detailed type semantics, see
6.4.2.1. Examples•
fn:ceiling(10.5) returns 11. •
fn:ceiling(-10.5) returns -10. 6.4.3. fn:floorFunction: numeric floor(numeric)Summary: Returns the largest (closest to positive infinity) number with no
fractional part that is not greater than the value of $arg. If
type of $arg is one of the four numeric types
xs:float, xs:double, xs:decimal or
xs:integer the type of the result is the same as the type of
$arg. If the type of $arg is a type derived from
one of the numeric types, the result is an instance of the base numeric type.For float and double arguments, if the argument is
positive zero, then positive zero is returned. If the argument is
negative zero, then negative zero is returned.For detailed type semantics, see
6.4.3.1. Examples•
fn:floor(10.5) returns 10. •
fn:floor(-10.5) returns -11. 6.4.4. fn:roundFunction: numeric round(numeric)Summary: Returns the number with no fractional part that is closest to the
argument. If there are two such numbers, then the one that is closest to
positive infinity is returned. If type of $arg is one of the
four numeric types xs:float, xs:double,
xs:decimal or xs:integer the type of the result is
the same as the type of $arg. If the type of $arg
is a type derived from one of the numeric types, the result is an instance
of the base numeric type.For xs:float and xs:double arguments, if the
argument is positive infinity, then positive infinity is returned. If the
argument is negative infinity, then negative infinity is returned. If the
argument is positive zero, then positive zero is returned. If the
argument is negative zero, then negative zero is returned. If the
argument is less than zero, but greater than or equal to -0.5, then
negative zero is returned. In the cases where positive zero or negative zero is returned, negative zero or positive zero may be returned as [XML Schema Part 2: Datatypes Second Edition] does not distinguish between the values positive zero and negative zero.For the last two cases, note that the result is not the same as fn:floor(x+0.5).For detailed type semantics, see
6.4.4.1. Examples•
fn:round(2.5) returns 3.
•
fn:round(2.4999) returns 2. •
fn:round(-2.5) returns -2 (not the
possible alternative, -3). 6.4.5. fn:round-half-to-evenFunction: numeric round-half-to-even(numeric)Function: numeric round-half-to-even(numeric, xs:integer)Summary: The value returned is the nearest (that is, numerically closest)
value to $arg that is a multiple of ten to the power of minus
$precision. If two such values are equally near (e.g. if the
fractional part in $arg is exactly .500...), the function returns the one
whose least significant digit is even.If the type of $arg is one
of the four numeric types xs:float, xs:double,
xs:decimal or xs:integer the type of the result is
the same as the type of $arg. If the type of $arg
is a type derived from one of the numeric types, the result is an instance
of the base numeric type. The first signature of this function produces the same result as the second
signature with $precision=0.For arguments of type xs:float and xs:double, if the argument is NaN, positive or negative zero, or positive or negative infinity, then the result is the same as the argument. In all other cases, the argument is cast to xs:decimal, the function is applied to this xs:decimal value, and the resulting xs:decimal is cast back to xs:float or xs:double as appropriate to form the function result. If the resulting xs:decimal value is zero, then positive or negative zero is returned according to the sign of the original argument.
Note that the process of casting to xs:decimal may result in an error .If $arg is of type xs:float
or xs:double, rounding occurs on the value of the mantissa
computed with exponent = 0.For detailed type semantics, see
☞This function is typically used in financial applications where the argument is of type xs:decimal. For arguments of type xs:float and xs:double the results may be counterintuitive. For example, consider round-half-to-even(xs:float(150.0150), 2).An implementation that supports 18 digits for xs:decimal will convert the argument to the xs:decimal 150.014999389...
which will then be rounded to the xs:decimal 150.01
which will be converted back to the xs:float whose exact value is
150.0099945068... whereas round-half-to-even(xs:decimal(150.0150), 2) will result in the xs:decimal whose exact value is 150.02.6.4.5.1. Examples•
fn:round-half-to-even(0.5) returns 0. •
fn:round-half-to-even(1.5) returns 2. •
fn:round-half-to-even(2.5) returns 2. •
fn:round-half-to-even(3.567812E+3, 2) returns 3567.81E0.
•
fn:round-half-to-even(4.7564E-3, 2) returns
0.0E0. •
fn:round-half-to-even(35612.25, -2) returns
35600. Functions on Strings7. Functions on StringsThis section discusses functions and operators on the [XML Schema Part 2: Datatypes Second Edition]
xs:string datatype and the datatypes derived from it.String Types7.1. String TypesThe operators described in this section are defined on the following types. Each
type whose name is indented is derived from the type whose name appears nearest
above with one less level of indentation.xs:string
xs:normalizedString
xs:token
xs:language
xs:NMTOKEN
xs:Name
xs:NCName
xs:ID
xs:IDREF
xs:ENTITY
They also apply to user-defined types derived by restriction from the above types. It is implementation-defined which version of [The Unicode Standard] is supported, but it is recommended that the most recent version of Unicode be used.Unless explicitly stated, the xs:string values returned by the
functions in this document are not normalized in the sense of [Character Model for the World Wide Web 1.0: Fundamentals]. This document uses the term "code point", sometimes spelt "codepoint" (also known as "character number" or "code position") to mean a non-negative integer that represents a character in some encoding. See [Character Model for the World Wide Web 1.0: Fundamentals]. The use of the word "character" in this document is in the sense of production [2] of [Extensible Markup Language (XML) 1.0 Recommendation (Third Edition)]. [The Unicode Standard], defines code points that range from #x0000 to #x10FFFF inclusive and may include code points
that have not yet been assigned to characters.In functions that involve character counting such
as fn:substring, fn:string-length and
fn:translate, what is counted is the number of XML characters
in the string (or equivalently, the number of Unicode code points). Some
implementations may represent a code point above xFFFF using two 16-bit
values known as a surrogate. A surrogate counts as one character, not two.Functions to Assemble and Disassemble Strings7.2. Functions to Assemble and Disassemble StringsFunction
Meaning
fn:codepoints-to-string
Creates an xs:string from a sequence of Unicode code points.
fn:string-to-codepoints
Returns the sequence of Unicode code points that constitute an
xs:string.
7.2.1. fn:codepoints-to-stringFunction: xs:string codepoints-to-string(xs:integer*)Summary: Creates an xs:string from a sequence of [The Unicode Standard] code points. Returns the
zero-length string if $arg is the empty sequence. If any of the
code points in $arg is not a legal XML character, an error is
raised .7.2.1.1. Examples•
fn:codepoints-to-string((2309, 2358, 2378, 2325))
returns "अशॊक"7.2.2. fn:string-to-codepointsFunction: xs:integer* string-to-codepoints(xs:string)Summary: Returns the sequence of [The Unicode Standard]
code points that constitute an
xs:string. If $arg is a zero-length string or the
empty sequence, the empty sequence is returned.7.2.2.1. Examples•
fn:string-to-codepoints("Thérèse")
returns the sequence (84, 104, 233, 114, 232, 115, 101)Equality and Comparison of Strings7.3. Equality and Comparison of Strings7.3.1. Collations A collation is a specification of the manner in which character strings are
compared and, by extension, ordered. When values whose type is
xs:string or a type derived from xs:string are
compared (or, equivalently, sorted), the comparisons are inherently
performed according to some collation (even if that collation is defined
entirely on code point values). The [Character Model for the World Wide Web 1.0: Fundamentals] observes that
some applications may require different comparison and ordering behaviors
than other applications. Similarly, some users having particular linguistic
expectations may require different behaviors than other users. Consequently,
the collation must be taken into account when comparing strings in any
context. Several functions in this and the following section make use of a
collation. Collations can indicate that two different code points are, in fact, equal
for comparison purposes (e.g., "v" and "w" are considered equivalent in
Swedish). Strings can be compared codepoint-by-codepoint or in a
linguistically appropriate manner, as defined by the collation. Some collations, especially those based on the [Unicode Collation Algorithm] can be "tailored" for various purposes. This
document does not discuss such tailoring, nor does it provide a mechanism to
perform tailoring. Instead, it assumes that the collation argument to the
various functions below is a tailored and named collation. A specific
collation with a distinguished name,
http://www.w3.org/2005/xpath-functions/collation/codepoint,
provides the ability to compare strings based on code point values. Every
implementation of XQuery/XPath must support the collation based on code
point values. In the ideal case, a collation should treat two strings as equal if the two strings are identical after Unicode normalization. Thus, the [Character Model for the World Wide Web 1.0: Normalization] recommends that all strings be subjected to early Unicode normalization and some collations will raise runtime errors if they encounter strings that are not properly normalized. However, it is not possible to guarantee that all
strings in all XML documents are, in fact, normalized, or that they are
normalized in the same manner. In order to maximize interoperability of
operations on XML documents in general, there may be collations that operate
on unnormalized strings and other collations that
implicitly normalize strings before comparing them. Applications may choose the kind of collation best suited for their needs. Note that collations based
on the Unicode collation algorithm implicitly normalize strings before comparison and produce equivalent results regardless of
a string's normalization.This specification assumes that collations are named and that the collation
name may be provided as an argument to string functions. Functions that
allow specification of a collation do so with an argument whose type is
xs:string but whose lexical form must conform to an
xs:anyURI. If the collation is specified using a relative URI,
it is assumed to be relative to the value of the base-uri property in the
static context. This specification also defines the manner in which a
default collation is determined if the collation argument is not specified
in invocations of functions that use a collation but allow it to be omitted.
This specification does not define whether or not the collation URI is
dereferenced. The collation URI may be an abstract identifier, or it may
refer to an actual resource describing the collation. If it refers to a
resource, this specification does not define the nature of that resource.
One possible candidate is that the resource is a locale description
expressed using the Locale Data Markup Language: see [Locale Data Markup Language].
Functions such as fn:compare and fn:max that
compare xs:string values use a single collation URI to identify
all aspects of the collation rules. This means that any parameters such as
the strength of the collation must be specified as part of the collation
URI. For example, suppose there is a collation “
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 . If the default collation is not specified by the
user or the system, the default collation is the Unicode code point
collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).The decision of which collation to use for a given comparison or ordering
function is determined by the following algorithm:1.If the function specifies an explicit collation, CollationA (e.g., if
the optional collation argument is specified in an invocation of the
fn:compare() function), then:•If CollationA is supported by the implementation, then
CollationA is used. •Otherwise, an error is raised . 2.If no collation is explicitly specified for the function
and the
default collation in the XQuery/XPath static context is CollationB, then:•If CollationB is supported by the implementation, then
CollationB is used. •Otherwise, an error is raised . ☞XML allows elements to specify the xml:lang attribute to
indicate the language associated with the content of such an element.
This specification does not use xml:lang to identify the
default collation
because using
xml:lang does not produce desired effects when the two
strings to be compared have different xml:lang values or
when a string is multilingual. Function
Meaning
fn:compare
Returns -1, 0, or 1, depending on whether the value of the
first argument is respectively less than, equal to, or greater
than the value of the second argument, according to the rules of
the collation that is used.
fn:codepoint-equal
Returns true if the two arguments are equal using
the Unicode code point collation.
7.3.2. fn:compareFunction: xs:integer compare(xs:string, xs:string)Function: xs:integer compare(xs:string, xs:string, xs:string)Summary: Returns -1, 0, or 1, depending on whether the value of the
$comparand1 is respectively less than, equal to, or greater
than the value of $comparand2, according to the rules of the
collation that is used. The collation used by the invocation of this function is determined according
to the rules in § 7.3.1 – Collations on page . If either argument is the empty sequence, the result is the empty sequence.This function, invoked with the first signature, backs up the "eq", "ne",
"gt", "lt", "le" and "ge" operators on string values.7.3.2.1. Examples•
fn:compare('abc', 'abc') returns 0. •
fn:compare('Strasse', 'Straße') returns 0
if and only if the default collation includes provisions that
equate “ss” and the (German) character
“ß” (“sharp-s”). (Otherwise,
the returned value depends on the semantics of the default collation.)•
fn:compare('Strasse', 'Straße', 'deutsch')
returns 0 if the collation identified by the relative URI
constructed from the string value
“deutsch” includes provisions that equate
“ss” and the (German) character
“ß” (“sharp-s”). (Otherwise,
the returned value depends on the semantics of that collation.)•
fn:compare('Strassen', 'Straße') returns 1
if the default collation includes provisions that treat
differences between “ss” and the (German) character
“ß” (“sharp-s”) with less
strength than the differences between the base characters, such
as the final “n”.
7.3.3. fn:codepoint-equalFunction: xs:boolean codepoint-equal(xs:string, xs:string)Summary: Returns true or false depending on whether
the value of $comparand1 is equal to the value of
$comparand2, according to the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).If either argument is the empty sequence, the result is the empty sequence. ☞This function allows xs:anyURI values to be compared without having to specify the Unicode code point collation.Functions on String Values7.4. Functions on String ValuesThe following functions are defined on values of type xs:string and
types derived from it.Function
Meaning
fn:concat
Concatenates two or more xs:anyAtomicType arguments
cast to xs:string.
fn:string-join
Returns the xs:string produced by concatenating a
sequence of xs:strings using an optional separator.
fn:substring
Returns the xs:string located at a specified place
within an argument xs:string.
fn:string-length
Returns the length of the argument.
fn:normalize-space
Returns the whitespace-normalized value of the argument.
fn:normalize-unicode
Returns the normalized value of the first argument in the
normalization form specified by the second argument.
fn:upper-case
Returns the upper-cased value of the argument.
fn:lower-case
Returns the lower-cased value of the argument.
fn:translate
Returns the first xs:string argument with occurrences
of characters contained in the second argument replaced by the
character at the corresponding position in the third argument.
fn:encode-for-uri
Returns the xs:string argument with certain characters escaped to enable the resulting string to be used as a path segment in a URI.
fn:iri-to-uri
Returns the xs:string argument with certain characters escaped to enable the resulting string to be used as (part of) a URI.
fn:escape-html-uri
Returns the xs:string argument with certain characters escaped in the manner that html user agents handle attribute values that expect URIs.
When the above operators and functions are applied to datatypes derived from
xs:string, they are guaranteed to return legal
xs:strings, but they might not return a legal value for the
particular subtype to which they were applied. The strings returned by fn:concat and fn:string-join are not guaranteed to be normalized. But see note in fn:concat.
7.4.1. fn:concatFunction: xs:string concat(xs:anyAtomicType, xs:anyAtomicType, )Summary: Accepts two or more xs:anyAtomicType arguments and
casts them to xs:string. Returns the xs:string
that is the concatenation of the values of its arguments after conversion.
If any of the arguments is the empty sequence, the argument is treated as
the zero-length string.The fn:concat function is specified to allow two or more
arguments, which are concatenated together. This is the only function
specified in this document that allows a variable number of arguments. This
capability is retained for compatibility with [XML Path Language (XPath) Version 1.0]. ☞As mentioned in § 7.1 – String Types on page Unicode normalization is not
automatically applied to the result of fn:concat. If a normalized result is required, fn:normalize-unicode can be applied to the xs:string returned by fn:concat. The following XQuery:let $v1 := "I plan to go to Mu"
let $v2 := "?nchen in September"
return concat($v1, $v2)where the "?" represents either the actual Unicode character COMBINING DIARESIS (Unicode codepoint U+0308) or "̈", will return:"I plan to go to Mu?nchen in September"where the "?" represents either the actual Unicode character COMBINING DIARESIS (Unicode codepoint U+0308) or "̈". It is worth noting that the returned value is not normalized in NFC; however, it is normalized in NFD.
.
However, the following XQuery:let $v1 := "I plan to go to Mu"
let $v2 := "?nchen in September"
return normalize-unicode(concat($v1, $v2))where the "?" represents either the actual Unicode character COMBINING DIARESIS (Unicode codepoint U+0308) or "̈", will return:
"I plan to go to München in September"This returned result is normalized in NFC.7.4.1.1. Examples
•
fn:concat('un', 'grateful') returns "ungrateful".
•
fn:concat('Thy ', (), 'old ', "groans", "", ' ring', '
yet', ' in', ' my', ' ancient',' ears.') returns
"Thy old groans ring yet in my ancient ears.".
•
fn:concat('Ciao!',()) returns "Ciao!".
•
fn:concat('Ingratitude, ', 'thou ', 'marble-hearted', '
fiend!') returns "Ingratitude, thou marble-hearted fiend!".
7.4.2. fn:string-joinFunction: xs:string string-join(xs:string*, xs:string)Summary: Returns a xs:string created by concatenating the
members of the $arg1 sequence using $arg2 as a
separator. If the value of $arg2 is the zero-length string,
then the members of $arg1 are concatenated without a separator. If the value of $arg1 is the empty sequence, the zero-length
string is returned.7.4.2.1. Examples
•fn:string-join(('Now', 'is', 'the', 'time', '...'), ' ')
returns "Now is the time ...".
•fn:string-join(('Blow, ', 'blow, ', 'thou ', 'winter ', 'wind!'), '')
returns "Blow, blow, thou winter wind!".
•fn:string-join((), 'separator') returns "".
•Assume a document:
<doc>
<chap>
<section>
</section>
</chap>
</doc>
with the <section> as the context node,
the [XML Path Language (XPath) 2.0] expression:
fn:string-join(for $n in ancestor-or-self::* return
name($n), '/')
returns "doc/chap/section"
7.4.3. fn:substringFunction: xs:string substring(xs:string, xs:double)Function: xs:string substring(xs:string, xs:double, xs:double)Summary: Returns the portion of the value of $sourceString
beginning at the position indicated by the value of
$startingLoc and continuing for the number of characters
indicated by the value of $length. The characters returned do
not extend beyond $sourceString. If $startingLoc
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 obeys:
fn:round($startingLoc) <= $p < fn:round($startingLoc) + fn:round($length)
The two argument version of the function assumes that $length is
infinite and returns the characters in $sourceString whose
position $p obeys:
fn:round($startingLoc) <= $p < fn:round(INF)
In the above computations, the rules for op:numeric-less-than()
and op:numeric-greater-than() apply.If the value of $sourceString is the empty sequence, the
zero-length string is returned. ☞The first character of a string is located at position 1, not position 0.7.4.3.1. Examples•
fn:substring("motor car", 6) returns " car".Characters starting at position 6 to the end of
$sourceString are selected.•
fn:substring("metadata", 4, 3) returns "ada".Characters at positions greater than or equal to 4 and less than
7 are selected.•
fn:substring("12345", 1.5, 2.6) returns "234".Characters at positions greater than or equal to 2 and less than
5 are selected.•
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.•
fn:substring("12345", 5, -3) returns "".Characters at positions greater than or equal to 5 and less than
2 are selected.•
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.•
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.•
fn:substring("12345", 1, 0 div 0E0) returns "".As above.•
fn:substring((), 1, 3) returns "".•
fn:substring("12345", -42, 1 div 0E0) returns "12345".Characters at positions greater than or equal to -42 and less
than INF are selected.•
fn:substring("12345", -1 div 0E0, 1 div 0E0)
returns "".Since -INF + INF returns NaN, no
characters are selected.7.4.4. fn:string-lengthFunction: xs:integer string-length()Function: xs:integer string-length(xs:string)Summary: Returns an xs:integer equal to the length in characters
of the value of $arg. If the value of $arg is the empty sequence, the
xs:integer 0 is returned.If no argument is supplied, $arg defaults to the string value
(calculated using fn:string()) of the context item
(.). If no argument is supplied and the context item is
undefined an error is raised: .
7.4.4.1. Examples•
fn:string-length("Harp not on that string, madam; that is
past.") returns 45. •
fn:string-length(()) returns 0. 7.4.5. fn:normalize-spaceFunction: xs:string normalize-space()Function: xs:string normalize-space(xs:string)Summary: Returns the value of $arg with whitespace normalized by
stripping leading and trailing whitespace and replacing sequences of one or
more than one whitespace character with a single space, #x20.The whitespace characters are defined in the metasymbol S (Production 3)
of [Extensible Markup Language (XML) 1.0 Recommendation (Third Edition)].☞The definition of the metasymbol S (Production 3), is unchanged
in [Extensible Markup Language (XML) 1.1 Recommendation].
If the value of
$arg is the empty sequence, returns the zero-length string.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
undefined an error is raised: .
7.4.5.1. Examples•
fn:normalize-space(" The wealthy curled darlings
of our nation. ")
returns "The wealthy curled darlings of our nation.".
•
fn:normalize-space(()) returns “”.7.4.6. fn:normalize-unicodeFunction: xs:string normalize-unicode(xs:string)Function: xs:string normalize-unicode(xs:string, xs:string)Summary: Returns the value of $arg normalized according to the
normalization criteria for a normalization form identified by the value of
$normalizationForm. The effective value of the
$normalizationForm is computed by removing leading and trailing
blanks, if present, and converting to upper case. If the value of $arg is the empty sequence, returns the
zero-length string.See [Character Model for the World Wide Web 1.0: Normalization] for a description of the normalization forms.If the $normalizationForm is absent, as in the first format
above, it shall be assumed to be "NFC"•If the effective value of $normalizationForm is
“NFC”, then the value returned by the function is the
value of $arg in Unicode Normalization Form C (NFC).•If the effective value of $normalizationForm is
“NFD”, then the value returned by the function is the
value of $arg in Unicode Normalization Form D (NFD).•If the effective value of $normalizationForm is
“NFKC”, then the value returned by the function is the
value of $arg in Unicode Normalization Form KC (NFKC).•If the effective value of $normalizationForm is
“NFKD”, then the value returned by the function is the
value of $arg in Unicode Normalization Form KD (NFKD).•If the effective value of $normalizationForm is
“FULLY-NORMALIZED”, then the value returned by the
function is the value of $arg in the fully normalized form.
•If the effective value of $normalizationForm is the
zero-length string, no normalization is performed and
$arg is returned.Conforming implementations must support normalization form
"NFC" and may support normalization forms "NFD", "NFKC",
"NFKD", "FULLY-NORMALIZED". They may also support other
normalization forms with implementation-defined semantics.
If the effective value of the $normalizationForm is other than
one of the values supported by the implementation, then an error is raised
.7.4.7. fn:upper-caseFunction: xs:string upper-case(xs:string)
Summary: Returns the value of $arg after translating every character to
its upper-case 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
locale-insensitive 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 lower-case character that does not have an upper-case correspondent,
as well as every upper-case character, is included in the returned value
in its original form.
If the value of $arg is the empty sequence, the zero-length
string is returned.☞Case mappings may change the length of a string. In general, the two
functions are not inverses of each other
fn:lower-case(fn:upper-case($arg)) is not guaranteed to
return $arg, nor
is fn:upper-case(fn:lower-case($arg)). The Latin small
letter dotless i (as used in Turkish) is perhaps the most prominent
lower-case letter which will not round-trip. The Latin capital letter i
with dot above is the most prominent upper-case letter which will not
round trip; there are others. 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. Results may violate 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.7.4.7.1. Examples•
fn:upper-case("abCd0") returns
"ABCD0". 7.4.8. fn:lower-caseFunction: xs:string lower-case(xs:string)
Summary: Returns the value of $arg after translating every character to
its lower-case 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
locale-insensitive 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 upper-case character that does not have a lower-case correspondent,
as well as every lower-case character, is included in the returned value
in its original form.
If the value of $arg is the empty sequence, the zero-length
string is returned.☞Case mappings may change the length of a string. In general, the two
functions are not inverses of each other
fn:lower-case(fn:upper-case($arg)) is not guaranteed to
return $arg, nor
is fn:upper-case(fn:lower-case($arg)). The Latin small
letter dotless i (as used in Turkish) is perhaps the most prominent
lower-case letter which will not round-trip. The Latin capital letter i
with dot above is the most prominent upper-case letter which will not
round trip; there are others. 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. Results may violate 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.7.4.8.1. Examples•
fn:lower-case("ABc!D") returns
"abc!d". 7.4.9. fn:translateFunction: xs:string translate(xs:string, xs:string, xs:string)Summary: Returns the value of $arg modified so that every
character in the value of $arg that occurs at some position
N in the value of $mapString has been replaced by
the character that occurs at position N in the value of
$transString. If the value of $arg is the empty sequence, the zero-length
string is returned.Every character in the value of $arg that does not appear in the
value of $mapString is unchanged. Every character in the value of $arg that appears at some
position M in the value of $mapString, where the
value of $transString is less than M characters in
length, is omitted from the returned value. If $mapString is
the zero-length string $arg is returned.If a character occurs more than once in $mapString, then the
first occurrence determines the replacement character. If
$transString is longer than $mapString, the excess
characters are ignored.7.4.9.1. Examples•
fn:translate("bar","abc","ABC") returns "BAr"
•
fn:translate("--aaa--","abc-","ABC") returns "AAA".•
fn:translate("abcdabc", "abc", "AB") returns
"ABdAB". 7.4.10. fn:encode-for-uriFunction: xs:string encode-for-uri(xs:string)
Summary: This function encodes reserved characters in an xs:string that is intended to be used in the path segment of a URI. It is invertible but not idempotent. This function applies the URI escaping rules defined in section 2 of [RFC 3986] to the xs:string supplied as $uri-part. The effect of the function is to escape reserved characters. Each such character in the string is replaced with its percent-encoded form as described in [RFC 3986].
If $uri-part is the empty sequence, returns the zero-length string.
All characters are escaped except those identified as "unreserved" by [RFC 3986], that is the upper- and lower-case letters A-Z, the digits 0-9, HYPHEN-MINUS ("-"), LOW LINE ("_"), FULL STOP ".", and TILDE "~".
Note that this function escapes URI delimiters and therefore cannot be used indiscriminately to encode "invalid" characters in a path segment.
Since [RFC 3986] recommends that, for consistency, URI producers and normalizers should use uppercase hexadecimal digits for all percent-encodings, this function must always generate hexadecimal values using the upper-case letters A-F.
7.4.10.1. Examples•
fn:encode-for-uri("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.
•
concat("http://www.example.com/", encode-for-uri("~bébé"))
returns "http://www.example.com/~b%C3%A9b%C3%A9".
•
concat("http://www.example.com/", encode-for-uri("100% organic"))
returns "http://www.example.com/100%25%20organic".
7.4.11. fn:iri-to-uriFunction: xs:string iri-to-uri(xs:string)
Summary: This function converts an xs:string containing an IRI into a URI according to the rules spelled out in Section 3.1 of [RFC 3987]. It is idempotent but not invertible.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 percent-encoded form as described in [RFC 3986] before the conversion is performed.
If $iri is the empty sequence, returns the zero-length string.
Since [RFC 3986] recommends that, for consistency, URI producers and normalizers should use uppercase hexadecimal digits for all percent-encodings, this function must always generate hexadecimal values using the upper-case letters A-F.
This function does not check whether $iri is a legal IRI. It treats it as an xs:string and operates on the characters in the xs: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
percent-encoded. In addition, characters outside the range x20-x7E
will be percent-encoded 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".
7.4.11.1. Examples•
fn:iri-to-uri
("http://www.example.com/00/Weather/CA/Los%20Angeles#ocean") returns "http://www.example.com/00/Weather/CA/Los%20Angeles#ocean".
•
fn:iri-to-uri
("http://www.example.com/~bébé") returns "http://www.example.com/~b%C3%A9b%C3%A9".
7.4.12. fn:escape-html-uriFunction: xs:string escape-html-uri(xs:string)Summary: This function escapes all characters except printable characters of the US-ASCII coded character set, specifically the octets ranging from 32 to 126 (decimal). The effect of the function is to escape a URI in the manner html user agents handle attribute values that expect URIs. 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 UTF-8, 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 upper-case letters A-F.
If $uri is the empty sequence, returns the zero-length string.☞The behavior of this function corresponds to the recommended handling
of non-ASCII characters in URI attribute values as described in [HTML 4.0] Appendix B.2.1.
7.4.12.1. Examples•
fn:escape-html-uri
("http://www.example.com/00/Weather/CA/Los Angeles#ocean") returns "http://www.example.com/00/Weather/CA/Los Angeles#ocean".
•
fn:escape-html-uri
("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');".
Functions Based on Substring Matching7.5. Functions Based on Substring MatchingThe 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 code point collation
is used, this simply involves determining whether $arg1 contains a
contiguous sequence of characters whose code points are the same, one for one,
with the code points 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. 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 implementation-defined property of the collation.Function
Meaning
fn:contains
Indicates whether one xs:string contains another
xs:string. A collation may be specified.
fn:starts-with
Indicates whether the value of one xs:string begins
with the collation units of another xs:string. A
collation may be specified.
fn:ends-with
Indicates whether the value of one xs:string ends with
the collation units of another xs:string. A collation
may be specified.
fn:substring-before
Returns the collation units of one xs:string that
precede in that xs:string the collation units of
another xs:string. A collation may be specified.
fn:substring-after
Returns the collation units of xs:string that follow in
that xs:string the collation units of another
xs:string. A collation may be specified.
7.5.1. fn:containsFunction: xs:boolean contains(xs:string, xs:string)Function: xs:boolean contains(xs:string, xs:string, xs:string)Summary: 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.☞"Minimal match" is defined in [Unicode Collation Algorithm]. If the value of $arg1 or $arg2 is the empty
sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.If the value of $arg2 is the zero-length string, then the
function returns true. If the value of $arg1 is the zero-length string, the function
returns false.The collation used by the invocation of this function is determined according
to the rules in § 7.3.1 – Collations on page . If the specified collation does
not support collation units an error may be raised
.7.5.1.1. ExamplesCollationA used in these examples is a collation in which both "-" and
"*" are ignorable collation units.☞"Ignorable collation unit" is equivalent to "ignorable collation
element" in [Unicode Collation Algorithm].•
fn:contains ( "tattoo", "t") returns true.•
fn:contains ( "tattoo", "ttt") returns false.•
fn:contains ( "", ()) returns true. The first rule is applied, followed by the second rule.•
fn:contains ( "abcdefghi", "-d-e-f-", "CollationA")
returns true.•
fn:contains ( "a*b*c*d*e*f*g*h*i*", "d-ef-",
"CollationA") returns true. •
fn:contains ( "abcd***e---f*--*ghi", "def",
"CollationA") returns true. •
fn:contains ( (), "--***-*---", "CollationA")
returns true. The second argument contains only
ignorable collation units and is equivalent to the zero-length string.7.5.2. fn:starts-withFunction: xs:boolean starts-with(xs:string, xs:string)Function: xs:boolean starts-with(xs:string, xs:string, xs:string)Summary: 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.☞
"Match" is defined in [Unicode Collation Algorithm].
If the value of $arg1 or $arg2 is the empty
sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.If the value of $arg2 is the zero-length string, then the
function returns true. If the value of $arg1 is
the zero-length string and the value of $arg2 is not the
zero-length string, then the function returns false.The collation used by the invocation of this function is determined according
to the rules in § 7.3.1 – Collations on page . If the specified collation does
not support collation units an error may be raised
.7.5.2.1. ExamplesCollationA used in these examples is a collation in which both "-" and
"*" are ignorable collation units.☞"Ignorable collation unit" is equivalent to "ignorable collation
element" in [Unicode Collation Algorithm].•
fn:starts-with("tattoo", "tat") returns
true. •
fn:starts-with ( "tattoo", "att") returns
false. •
fn:starts-with ((), ()) returns true. •
fn:starts-with ( "abcdefghi", "-a-b-c-",
"CollationA") returns true. •
fn:starts-with ( "a*b*c*d*e*f*g*h*i*", "a-bc-",
"CollationA") returns true. •
fn:starts-with ( "abcd***e---f*--*ghi", "abcdef",
"CollationA") returns true. •
fn:starts-with ( (), "--***-*---", "CollationA")
returns true. The second argument contains only
ignorable collation units and is equivalent to the zero-length string.
•
fn:starts-with ( "-abcdefghi", "-abc", "CollationA")
returns true.
7.5.3. fn:ends-withFunction: xs:boolean ends-with(xs:string, xs:string)Function: xs:boolean ends-with(xs:string, xs:string, xs:string)Summary: 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.☞
"Match" is defined in [Unicode Collation Algorithm].
If the value of $arg1 or $arg2 is the empty
sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.If the value of $arg2 is the zero-length string, then the
function returns true. If the value of $arg1 is
the zero-length string and the value of $arg2 is not the
zero-length string, then the function returns false.The collation used by the invocation of this function is determined according
to the rules in § 7.3.1 – Collations on page . If the specified collation does
not support collation units an error may be raised
.7.5.3.1. ExamplesCollationA used in these examples is a collation in which both "-" and
"*" are ignorable collation units.☞"Ignorable collation unit" is equivalent to "ignorable collation
element" in [Unicode Collation Algorithm].•
fn:ends-with ( "tattoo", "tattoo") returns
true. •
fn:ends-with ( "tattoo", "atto") returns
false. •
fn:ends-with ((), ()) returns true. •
fn:ends-with ( "abcdefghi", "-g-h-i-",
"CollationA") returns true. •
fn:ends-with ( "abcd***e---f*--*ghi", "defghi",
"CollationA") returns true. •
fn:ends-with ( "abcd***e---f*--*ghi", "defghi",
"CollationA") returns true. •
fn:ends-with ( (), "--***-*---", "CollationA")
returns true. The second argument contains only
ignorable collation units and is equivalent to the zero-length string.
•
fn:ends-with ( "abcdefghi", "ghi-", "CollationA")
returns true.
7.5.4. fn:substring-beforeFunction: xs:string substring-before(xs:string, xs:string)Function: xs:string substring-before(xs:string, xs:string, xs:string)Summary: 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.☞"Minimal match" is defined in [Unicode Collation Algorithm]. If the value of $arg1 or $arg2 is the empty
sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.If the value of $arg2 is the zero-length string, then the
function returns the zero-length string. If the value of $arg1 does not contain a string that is equal to
the value of $arg2, then the function returns the zero-length
string. The collation used by the invocation of this function is determined according
to the rules in § 7.3.1 – Collations on page If the specified collation does
not support collation units an error may be raised
.7.5.4.1. ExamplesCollationA used in these examples is a collation in which both "-" and
"*" are ignorable collation units.☞"Ignorable collation unit" is equivalent to "ignorable collation
element" in [Unicode Collation Algorithm].•
fn:substring-before ( "tattoo", "attoo") returns “t”. •
fn:substring-before ( "tattoo", "tatto") returns “”. •
fn:substring-before ((), ()) returns “”. •
fn:substring-before ( "abcdefghi", "--d-e-",
"CollationA") returns “abc”. •
fn:substring-before ( "abc--d-e-fghi", "--d-e-",
"CollationA") returns “abc--”. •
fn:substring-before ( "a*b*c*d*e*f*g*h*i*", "***cde",
"CollationA") returns “a*b*”. •
fn:substring-before ( "Eureka!", "--***-*---",
"CollationA") returns “”. The second argument
contains only ignorable collation units and is equivalent to the
zero-length string.7.5.5. fn:substring-afterFunction: xs:string substring-after(xs:string, xs:string)Function: xs:string substring-after(xs:string, xs:string, xs:string)Summary: 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. ☞"Minimal match" is defined in [Unicode Collation Algorithm]. If the value of $arg1 or $arg2 is the empty
sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.If the value of $arg2 is the zero-length 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 zero-length
string. The collation used by the invocation of this function is determined according
to the rules in § 7.3.1 – Collations on page If the specified collation does
not support collation units an error may be raised
.7.5.5.1. ExamplesCollationA used in these examples is a collation in which both "-" and
"*" are ignorable collation units.☞"Ignorable collation unit" is equivalent to "ignorable collation
element" in [Unicode Collation Algorithm].•
fn:substring-after("tattoo", "tat") returns “too”. •
fn:substring-after ( "tattoo", "tattoo") returns “”. •
fn:substring-after ((), ()) returns “”. •
fn:substring-after ( "abcdefghi", "--d-e-",
"CollationA") returns “fghi”.•
fn:substring-after ( "abc--d-e-fghi", "--d-e-",
"CollationA") returns “-fghi
”. •
fn:substring-after ( "a*b*c*d*e*f*g*h*i*", "***cde***",
"CollationA") returns “*f*g*h*i*”. •
fn:substring-after ( "Eureka!", "--***-*---",
"CollationA") returns “Eureka!”. The second argument contains only ignorable collation
units and is equivalent to the zero-length string.String Functions that Use Pattern Matching7.6. String Functions that Use Pattern MatchingThe 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 an xs:boolean value that indicates whether the
value of the first argument is matched by the regular expression
that is the value of the second argument.
fn:replace
Returns the value of the first argument with every substring matched
by the regular expression that is the value of the second argument
replaced by the replacement string that is the value of the third
argument.
fn:tokenize
Returns a sequence of one or more xs:strings whose
values are substrings of the value of the first argument separated
by substrings that match the regular expression that is the value of
the second argument.
7.6.1. Regular Expression SyntaxThe 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 widely-used
with languages such as Perl. This section, therefore, describes extensions
to the XML Schema regular expressions syntax that reinstate these capabilities.☞
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 meta-characters, ^ and $ are
added. By default, the meta-character ^ matches the
start of the entire string, while $ matches the end
of the entire string. In multi-line mode, ^ matches
the start of any line (that is, the start of the entire string,
and the position immediately after a newline character), while
$ matches the end of any line (that is, the end of
the entire string, and the position immediately before a newline
character). Newline here means the character #x0A only.This means that the production in [XML Schema Part 2: Datatypes Second Edition]:
[10] Char ::= [^.\?*+()|#x5B#x5D]
is modified to read:
[10] Char ::= [^.\?*+{}()|^$#x5B#x5D]
The characters #x5B and #x5D correspond
to "[" and "]" respectively.☞The definition of Char (production [10]) in [XML Schema Part 2: Datatypes Second Edition] has a known error in which it omits the left brace ("{") and right brace ("}"). That error is corrected here.The following production:
[11] charClass ::= charClassEsc | charClassExpr | WildCardEsc
is modified to read:
[11] charClass ::= charClassEsc | charClassExpr |
WildCardEsc | "^" | "$"
•
Reluctant quantifiers are supported. They are
indicated by a “
?
” following a quantifier. Specifically:-
X?? matches X, once or not at all-
X*? matches X, zero or more times-
X+? matches X, one or more times-
X{n}? matches X, exactly n times-
X{n,}? matches X, at least n times-
X{n,m}? matches X, at least n times, but
not more than m timesThe 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 '}' ) ) '?'?
☞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.•Sub-expressions (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 sub-expressions, but attaches no special
significance to them. The fn:replace() function
described below allows access to the parts of the input string
that matched a sub-expression (called captured substrings). The
sub-expressions are numbered according to the position of the
opening parenthesis in left-to-right order within the top-level
regular expression: the first opening parenthesis identifies
captured substring 1, the second identifies captured substring
2, and so on. 0 identifies the substring captured by the entire
regular expression. If a sub-expression matches more than one
substring (because it is within a construct that allows
repetition), then only the last substring that it
matched will be captured.•
Back-references are allowed
outside a character class expression.
A back-reference is an additional kind of atom.
The construct \N where
N is a single digit is always recognized as a
back-reference; if this is followed by further digits, these
digits are taken to be part of the back-reference if and only if
the resulting number NN is such that
the back-reference is preceded by NN or more unescaped opening
parentheses.
The regular expression is invalid if a back-reference refers to a
subexpression that does not exist or whose
closing right parenthesis occurs after the back-reference.
A back-reference matches the string that was
matched by the Nth capturing subexpression within the regular
expression, that is, the parenthesized subexpression whose
opening left parenthesis is the Nth 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 Nth capturing
subexpression, the back-reference is interpreted as matching
a zero-length string.
Back-references change the following production:
[9] atom ::= Char | charClass | ( '(' regExp ')' )
to
[9] atom ::= Char | charClass | ( '(' regExp ')' ) | backReference
[9a] backReference ::= "\" [1-9][0-9]*
☞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]
7.6.1.1. FlagsAll these functions provide an optional parameter, $flags,
to set options for the interpretation of the regular expression. The
parameter accepts a xs:string, in which individual letters
are used to set options. The presence of a letter within the string
indicates that the option is on; its absence indicates that the option
is off. Letters may appear in any order and may be repeated. If there
are characters present that are not defined here as flags, then an error
is raised .The following options are defined:•
s: If present, the match operates in "dot-all"
mode. (Perl calls this the single-line mode.) If the
s flag is not specified, the meta-character
. matches any character except a newline
(#x0A) character. In dot-all mode, the
meta-character . 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 dot-all mode is enabled.•
m: If present, the match operates in multi-line
mode. By default, the meta-character ^ matches the
start of the entire string, while $ matches the end of the
entire string. In multi-line 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
case-insensitive mode. The detailed rules are as follows.
In these
rules, a character C2 is considered to be a case-variant 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:lower-case(C1) eq fn:lower-case(C2) or fn:upper-case(C1) eq fn:upper-case(C2)
Note that the case-variants of a character under this definition
are always single characters.1.
When a normal character (Char) is used as an atom,
it represents
the set containing that character and all its case-variants.
For example, the regular expression "z" will match both "z" and
"Z".2.
A character range (charRange) represents the set
containing all the characters that it would match in the absence
of the "i" flag, together with their case-variants.
For example,
the regular expression "[A-Z]" will match all
the letters A-Z and all the letters a-z. It will also match
certain other characters such as #x212A (KELVIN SIGN), since
fn:lower-case("#x212A") is "k".
This rule applies also to a character range used in a character
class subtraction (charClassSub): thus [A-Z-[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 case-variants of "Q" in
Unicode).3.
A back-reference is compared using case-blind comparison:
that is, each character must either be the same as the
corresponding character of the previously matched string, or must
be a case-variant 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.4.
All other constructs are unaffected by the "i" flag.
For example,
"\p{Lu}" continues to match upper-case 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 false7.6.2. fn:matchesFunction: xs:boolean matches(xs:string, xs:string)Function: xs:boolean matches(xs:string, xs:string, xs:string)Summary: The function returns true if $input
matches the regular expression supplied as $pattern as
influenced by the value of $flags, if present; otherwise, it
returns false. 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 zero-length
string. Flags are defined in § 7.6.1.1 – Flags on page .If $input is the empty sequence, it is interpreted as the
zero-length string.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.An error is raised if the value of
$pattern is invalid according to the rules described in section
§ 7.6.1 – Regular Expression Syntax on page . An error is raised if the value of
$flags is invalid according to the rules described in section
§ 7.6.1 – Regular Expression Syntax on page . 7.6.2.1. Examples•
fn:matches("abracadabra", "bra") returns true•
fn:matches("abracadabra", "^a.*a$") returns true•
fn:matches("abracadabra", "^bra") returns falseGiven the source document:<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:•
fn:matches(., "Kaum.*krähen") returns false
•
fn:matches(., "Kaum.*krähen", "s") returns true
•
fn:matches(., "^Kaum.*gesehen,$", "m") returns true
•
fn:matches(., "^Kaum.*gesehen,$") returns false
•
fn:matches(., "kiki", "i") returns true
☞Regular expression matching is defined on the basis of Unicode code
points; it takes no account of collations.7.6.3. fn:replaceFunction: xs:string replace(xs:string, xs:string, xs:string)Function: xs:string replace(xs:string, xs:string, xs:string, xs:string)Summary: The function returns the xs:string that is obtained by
replacing each non-overlapping substring of $input that matches
the given $pattern with an occurrence of the
$replacement string.The effect of calling the first version of this function (omitting the
argument $flags) is the same as the effect of calling the
second version with the $flags argument set to a zero-length
string. Flags are defined in § 7.6.1.1 – Flags on page .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
zero-length 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.
Within the $replacement string, a variable $N may be used to refer to the substring captured by the Nth parenthesized sub-expression in the regular expression. For each match of the pattern, these variables are assigned the value of the content matched by the relevant sub-expression, 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 sub-expressions in the regular expression, and N is the decimal number formed by taking all the digits that consecutively follow the $ character:1.
If N=0, then the variable is replaced by the substring matched by the regular expression as a whole.2.
If 1<=N<=S, then the variable is replaced by the substring captured by the Nth parenthesized sub-expression. If the Nth parenthesized sub-expression was not matched, then the variable is replaced by the zero-length string.
3.
If S<N<=9, then the variable is replaced by the zero-length string.
4.
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 sub-expression, followed by the digit “3”.A literal “$” symbol must be written as “\$”.A literal “\” symbol must be written as “\\”. If two alternatives within the pattern both match at the same position in
the $input, then the match that is chosen is the one matched by
the first alternative. For example: fn:replace("abcd", "(ab)|(a)", "[1=$1][2=$2]") returns "[1=ab][2=]cd"An error is raised if the value of
$pattern is invalid according to the rules described in section
§ 7.6.1 – Regular Expression Syntax on page . An error is raised if the value of
$flags is invalid according to the rules described in section
§ 7.6.1 – Regular Expression Syntax on page . An error is raised if the pattern matches
a zero-length string, that is, if the expression fn:matches("",
$pattern, $flags) returns true. It is not an error,
however, if a captured substring is zero-length.An error is raised if the value of
$replacement contains a "$" character that is not
immediately followed by a digit 0-9 and not immediately
preceded by a "\".An error is raised if the value of
$replacement contains a "\" character that is not
part of a "\\" pair, unless it is immediately followed by a
"$" character.7.6.3.1. Examples
•
replace("abracadabra", "bra", "*") returns "a*cada*"
•
replace("abracadabra", "a.*a", "*") returns "*"
•
replace("abracadabra", "a.*?a", "*") returns "*c*bra"
•
replace("abracadabra", "a", "") returns "brcdbr"
•
replace("abracadabra", "a(.)", "a$1$1") returns "abbraccaddabbra"
•
replace("abracadabra", ".*?", "$1") raises an
error, because the pattern matches the zero-length string
•
replace("AAAA", "A+", "b") returns "b"
•
replace("AAAA", "A+?", "b") returns "bbbb"
•
replace("darted", "^(.*?)d(.*)$", "$1c$2") returns "carted".
The first d is replaced.
7.6.4. fn:tokenizeFunction: xs:string* tokenize(xs:string, xs:string)Function: xs:string* tokenize(xs:string, xs:string, xs:string)Summary: This function breaks the $input string into a sequence
of strings, treating any substring that matches $pattern as a
separator. The separators themselves are not returned.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 zero-length
string. Flags are defined in § 7.6.1.1 – Flags on page . 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 zero-length string, the result is the empty sequence.If the supplied $pattern matches a zero-length string, that is,
if fn:matches("", $pattern, $flags) returns true,
then an error is raised: . If a separator occurs at the start of the $input string, the
result sequence will start with a zero-length string. Zero-length strings
will also occur in the result sequence if a separator occurs at the end of
the $input string, or if two adjacent substrings match the
supplied $pattern. If two alternatives within the supplied $pattern both match at
the same position in the $input string, then the match that is
chosen is the first. For example: fn:tokenize("abracadabra", "(ab)|(a)") returns ("", "r", "c", "d", "r", "") An error is raised if the value of
$pattern is invalid according to the rules described in section
§ 7.6.1 – Regular Expression Syntax on page . An error is raised if the value of
$flags is invalid according to the rules described in section
§ 7.6.1 – Regular Expression Syntax on page .7.6.4.1. Examples•
fn:tokenize("The cat sat on the mat", "\s+")
returns ("The", "cat", "sat", "on", "the", "mat")
•
fn:tokenize("1, 15, 24, 50", ",\s*") returns
("1", "15", "24", "50")
•
fn:tokenize("1,15,,24,50,", ",") returns
("1", "15", "", "24", "50", "")
•
fn:tokenize("abba", ".?") raises the error
.•
fn:tokenize("Some unparsed <br> HTML
<BR> text", "\s*<br>\s*", "i")
returns ("Some unparsed", "HTML", "text")
Functions on anyURI8. Functions on anyURIThis section specifies functions that take anyURI as arguments.Function
Meaning
fn:resolve-uri
Returns an xs:anyURI representing an absolute
xs:anyURI given a base URI and a relative URI.
fn:resolve-uri8.1. fn:resolve-uriFunction: xs:anyURI resolve-uri(xs:string)Function: xs:anyURI resolve-uri(xs:string, xs:string)Summary: This function enables a relative URI reference to be resolved
against an absolute URI.The first form of
this function resolves $relative against the value of the base-uri property from the
static context. If the base-uri property is not initialized in the static
context an error is raised . If $relative is a relative URI
reference, it is resolved against $base,
or against the base-uri property from the
static context, using an algorithm such as those described in
[RFC 2396] or [RFC 3986], and the
resulting absolute URI reference is returned. If $relative is an
absolute URI reference, it is returned unchanged.If $relative is the empty sequence, the empty sequence is returned.If $relative is not a valid URI according to the rules of the
xs:anyURI data type, or if it is not a suitable relative reference to use
as input to the chosen resolution algorithm, then an error is raised
.If $base is not a valid URI according to the rules of the
xs:anyURI data type, if it is not a suitable URI to use as input
to the chosen resolution algorithm (for example, if it is a relative URI reference,
if it is a non-hierarchic URI, or if it contains a fragment identifier),
then an error is raised .If the chosen resolution algorithm fails for any other reason then an error is
raised .☞
Resolving a URI does not dereference it. This is merely a syntactic operation
on two character 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.
Functions and Operators on Boolean Values9. Functions and Operators on Boolean ValuesThis section defines functions and operators on the [XML Schema Part 2: Datatypes Second Edition] boolean datatype.Additional Boolean Constructor Functions9.1. Additional Boolean Constructor FunctionsThe following additional constructor functions are defined on the boolean type. Function
Meaning
fn:true
Constructs the xs:boolean value 'true'.
fn:false
Constructs the xs:boolean value 'false'.
9.1.1. fn:trueFunction: xs:boolean true()Summary: Returns the xs:boolean value true.
Equivalent to xs:boolean("1").9.1.1.1. Examples•
fn:true() returns true. 9.1.2. fn:falseFunction: xs:boolean false()Summary: Returns the xs:boolean value false.
Equivalent to xs:boolean("0").9.1.2.1. Examples•
fn:false() returns false. Operators on Boolean Values9.2. Operators on Boolean ValuesThe following functions define the semantics of operators on boolean values in
[XQuery 1.0: An XML Query Language] and [XML Path Language (XPath) 2.0]:Operator
Meaning
op:boolean-equal
Equality of xs:boolean values
op:boolean-less-than
A less-than operator on xs:boolean values:
false is less than true.
op:boolean-greater-than
A greater-than operator on xs:boolean values:
true is greater than false.
The ordering operators op:boolean-less-than
and op:boolean-greater-than 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.9.2.1. op:boolean-equalFunction: xs:boolean boolean-equal(xs:boolean, xs:boolean)Summary: Returns true if both arguments are true or
if both arguments are false. Returns false if one
of the arguments is true and the other argument is
false. This function backs up the "eq" operator on xs:boolean values. 9.2.2. op:boolean-less-thanFunction: xs:boolean boolean-less-than(xs:boolean, xs:boolean)Summary: Returns true if $arg1 is
false and $arg2 is true. Otherwise,
returns false.This function backs up the "lt" and "ge" operators on xs:boolean
values. 9.2.3. op:boolean-greater-thanFunction: xs:boolean boolean-greater-than(xs:boolean, xs:boolean)Summary: Returns true if $arg1 is true
and $arg2 is false. Otherwise, returns false.This function backs up the "gt" and "le" operators on xs:boolean
values. Functions on Boolean Values9.3. Functions on Boolean ValuesThe following functions are defined on boolean values:Function
Meaning
fn:not
Inverts the xs:boolean value of the argument.
9.3.1. fn:notFunction: xs:boolean not(item()*)Summary: $arg is first reduced to an effective boolean value by
applying the fn:boolean() function. Returns true
if the effective boolean value is false, and false
if the effective boolean value is true. 9.3.1.1. Examples•
fn:not(fn:true()) returns false. •
fn:not("false") returns false. Functions and Operators on Durations, Dates and Times10. Functions and Operators on Durations, Dates and TimesThis section discusses operations on the [XML Schema Part 2: Datatypes Second Edition] date and time types.
It also discusses operations on two subtypes of xs:duration that are
defined in . See § 10.3 – Two Totally Ordered Subtypes of Duration on page .
See [Working With Timezones] for a disquisition on working with date and time values with and without timezones.
Duration, Date and Time Types10.1. Duration, Date and Time TypesThe 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:gDayNote that only equality is defined on
xs:gYearMonth, xs:gYear,
xs:gMonthDay, xs:gMonth and xs:gDay values.In addition, operators are defined on:•xs:durationand on the § 10.3 – Two Totally Ordered Subtypes of Duration on page :•xs:yearMonthDuration•xs:dayTimeDurationNote that 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.10.1.1. Limits and PrecisionFor a number of the above datatypes [XML Schema Part 2: Datatypes Second Edition] extends the basic
[ISO 8601] lexical representations, such as
YYYY-MM-DDThh: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 implementation-defined 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 implementation-defined.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 § 10.8 – Arithmetic Operators on Durations, Dates and Times on page . In
these situations, the processor must return P0M or PT0S in
case of duration underflow and 00:00:00 in case of time underflow.
It must raise an error in case of overflow.The value spaces of the two totally ordered subtypes of
xs:duration described in § 10.3 – Two Totally Ordered Subtypes of Duration on page 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
§ 10.6 – Arithmetic Operators on Durations on page . In these situations the processor
must return zero in case of numeric underflow and P0M
or PT0S in case of duration underflow. It must raise an
error in case of overflow.Date/time datatype values10.2. Date/time datatype valuesAs defined in , xs:dateTime, xs:date, xs:time, xs:gYearMonth, xs:gYear, xs:gMonthDay, xs:gMonth, xs:gDay values, referred to collectively as date/time values, are represented as seven components or properties: year, month, day, hour, minute, second and timezone. The value of the first five components are xs:integers. The value of the second component is an xs:decimal and the value of the timezone component is an xs:dayTimeDuration. For all the date/time datatypes, the timezone property is optional and may or may not be present. Depending on the datatype, some of the remaining six properties must be present and some must be absent. Absent, or missing, properties are represented by the empty sequence. This value is referred to as the local value in that the value is in the given 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.10.2.1. Examples•An xs:dateTime with lexical
representation 1999-05-31T05:00:00 is represented in the datamodel by {1999, 5, 31, 5, 0, 0.0, ()}.•An xs:dateTime with lexical
representation 1999-05-31T13:20:00-05:00 is represented by {1999, 5, 31, 13, 20, 0.0, -PT5H}.•An xs:dateTime with lexical
representation 1999-12-31T24:00:00 is represented by {2000, 1, 1, 0, 0, 0.0, ()}.•An xs:date with lexical
representation 2005-02-28+8:00 is represented by {2005, 2, 28, (), (), (), PT8H}.•An xs:time with lexical
representation 24:00:00 is represented by {(), (), (), 0, 0, 0, ()}.Two Totally Ordered Subtypes of Duration10.3. Two Totally Ordered Subtypes of DurationTwo totally ordered subtypes of xs:duration are defined in
specification using the mechanisms described in [XML Schema Part 2: Datatypes Second Edition] for
defining user-defined types. Additional details about these types is given below.10.3.1. xs:yearMonthDuration [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.10.3.1.1. Lexical representationThe 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; P-1347M 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.10.3.1.2. Calculating the value from the lexical representationThe 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.10.3.1.3. Canonical representationThe 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 non-canonical
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".10.3.1.4. Order relation on xs:yearMonthDurationLet 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.10.3.2. xs:dayTimeDuration[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.10.3.2.1. Lexical representationThe 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.
P-134D is not allowed (invalid location of minus sign), although -P134D
is allowed. 10.3.2.2. Calculating the value of a xs:dayTimeDuration from the lexical representationThe 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.10.3.2.3. Canonical representationThe 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 non-canonical 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”.10.3.2.4. Order relation on xs:dayTimeDurationLet the function that calculates the value of a
xs:dayTimeDuration in the manner described above be called
V(d). Then for two xs:dayTimeDuration values
x and y, x > y if and only if V(x)
> V(y). The order relation on
xs:dayTimeDuration is a total order. Comparison Operators on Duration, Date and Time Values10.4. Comparison Operators on Duration, Date and Time ValuesOperator
Meaning
op:yearMonthDuration-less-than
Less-than comparison on xs:yearMonthDuration values
op:yearMonthDuration-greater-than
Greater-than comparison on xs:yearMonthDuration values
op:dayTimeDuration-less-than
Less-than comparison on xs:dayTimeDuration values
op:dayTimeDuration-greater-than
Greater-than comparison on xs:dayTimeDuration values
op:duration-equal
Equality comparison on xs:duration values
op:dateTime-equal
Equality comparison on xs:dateTime values
op:dateTime-less-than
Less-than comparison on xs:dateTime values
op:dateTime-greater-than
Greater-than comparison on xs:dateTime values
op:date-equal
Equality comparison on xs:date values
op:date-less-than
Less-than comparison on xs:date values
op:date-greater-than
Greater-than comparison on xs:date values
op:time-equal
Equality comparison on xs:time values
op:time-less-than
Less-than comparison on xs:time values
op:time-greater-than
Greater-than comparison on xs:time values
op:gYearMonth-equal
Equality comparison on xs:gYearMonth values
op:gYear-equal
Equality comparison on xs:gYear values
op:gMonthDay-equal
Equality comparison on xs:gMonthDay values
op:gMonth-equal
Equality comparison on xs:gMonth values
op:gDay-equal
Equality comparison on xs:gDay values
The following comparison operators are defined on the [XML Schema Part 2: Datatypes Second Edition]
date, time and duration datatypes. Each operator takes two operands of the same
type and returns an xs:boolean result. As discussed in [XML Schema Part 2: Datatypes Second Edition], the
order relation on xs:duration is
not a total order but, rather, a partial order. For this reason, only equality is defined on xs:duration. A full complement of comparison and
arithmetic functions are defined on the two subtypes of duration described in
§ 10.3 – Two Totally Ordered Subtypes of Duration on page which do have a total order.[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 , 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 or missing. Timezone is always optional. For example, for xs:date, the year, month and day components are required and hour, minute and second components must be absent; for xs:time the hour, minute and second components are required and year, month and day are missing; for xs:gDay, day is required and year, month, hour, minute and second are missing.Values of the date/time datatypes xs:time, xs:gMonthDay, xs:gMonth, and xs:gDay, can be considered to represent a sequence of recurring time instants or time periods. An xs:time occurs every day. An xs:gMonth occurs every year. Comparison operators on these datatypes compare the starting instants of equivalent occurrences in the recurring series. These xs:dateTime values are calculated as described below.Comparison operators on xs:date, xs:gYearMonth and xs:gYear compare their starting instants. These xs:dateTime values are calculated as described below.The starting instant of an occurrence of a date/time value is an xs:dateTime calculated by filling in the missing components of the local value from a reference xs:dateTime. If the value filled in for a missing day component exceeds the maximum day value for the month, the last day of the month is used. Suppose, for example, that the reference xs:dateTime is 1972-12-31T00:00:00 and the xs:date value to be compared is 1993-03-31. Filling in the time components from the reference xs:dateTime we get 1993-03-31T00:00:00 which is the starting instant of that day. Similarly, if the xs:time value 12:30:00 is to be compared, we fill in the missing components from the reference xs:dateTime and we get 1972-12-31T12:30:00 which is the time on that day. For an xs:gYearMonth value of 1976-02 we fill in the missing components, adjust for the last day in the month and get 1976-02-29T00:00:00.If the xs:time value written as
24:00:00 is to be compared, filling in the missing components gives 1972-12-31T00: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.☞This proposal uses the reference xs:dateTime 1972-12-31T00:00:00 in the description of the comparison operators. Implementations are allowed to 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.10.4.1. op:yearMonthDuration-less-thanFunction: xs:boolean yearMonthDuration-less-than(xs:yearMonthDuration, xs:yearMonthDuration)Summary: Returns true if and only if $arg1 is less
than $arg2. Returns false otherwise.This function backs up the "lt" and "le" operators on
xs:yearMonthDuration values.10.4.2. op:yearMonthDuration-greater-thanFunction: xs:boolean yearMonthDuration-greater-than(xs:yearMonthDuration, xs:yearMonthDuration)Summary: Returns true if and only if $arg1 is
greater than $arg2. Returns false otherwise.This function backs up the "gt" and "ge" operators on
xs:yearMonthDuration values.10.4.3. op:dayTimeDuration-less-thanFunction: xs:boolean dayTimeDuration-less-than(xs:dayTimeDuration, xs:dayTimeDuration)Summary: Returns true if and only if $arg1 is less
than $arg2. Returns false otherwise.This function backs up the "lt" and "le" operators on
xs:dayTimeDuration values.10.4.4. op:dayTimeDuration-greater-thanFunction: xs:boolean dayTimeDuration-greater-than(xs:dayTimeDuration, xs:dayTimeDuration)Summary: Returns true if and only if $arg1 is
greater than $arg2. Returns false otherwise.This function backs up the "gt" and "ge" operators on
xs:dayTimeDuration values.10.4.5. op:duration-equalFunction: xs:boolean duration-equal(xs:duration, xs:duration)Summary:
Returns true if and only if the
xs:yearMonthDuration and the xs:dayTimeDuration
components of $arg1 and $arg2 compare equal respectively.
Returns false otherwise.
This function backs up the "eq" and "ne" operators on
xs:duration values.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 zero-length duration, no instance of xs:dayTimeDuration can ever be equal to an instance of xs:yearMonthDuration.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.10.4.5.1. Examples•
op:duration-equal(xs:duration("P1Y"), xs:duration("P12M")) returns true.
•
op:duration-equal(xs:duration("PT24H"), xs:duration("P1D")) returns true.
•
op:duration-equal(xs:duration("P1Y"), xs:duration("P365D")) returns false.
•
op:duration-equal(xs:yearMonthDuration("P0Y"), xs:dayTimeDuration("P0D"))
returns true.
•
op:duration-equal(xs:yearMonthDuration("P1Y"), xs:dayTimeDuration("P365D"))
returns false.
•
op:duration-equal(xs:yearMonthDuration("P2Y"), xs:yearMonthDuration("P24M")) returns true.
•
op:duration-equal(xs:dayTimeDuration("P10D"), xs:dayTimeDuration("PT240H"))
returns true.
•
op:duration-equal(xs:duration("P2Y0M0DT0H0M0S"), xs:yearMonthDuration("P24M")) returns true.
•
op:duration-equal(xs:duration("P0Y0M10D"), xs:dayTimeDuration("PT240H")) returns true.
10.4.6. op:dateTime-equalFunction: xs:boolean dateTime-equal(xs:dateTime, xs:dateTime)Summary:
Returns true if and only if the value of
$arg1 is equal to the 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.
Returns false otherwise.
This function backs up the "eq", "ne", "le" and "ge" operators on
xs:dateTime values.10.4.6.1. ExamplesAssume that the dynamic context provides an implicit timezone value of -05:00.•
op:dateTime-equal(xs:dateTime("2002-04-02T12:00:00-01:00"),
xs:dateTime("2002-04-02T17:00:00+04:00")) returns true.•
op:dateTime-equal(xs:dateTime("2002-04-02T12:00:00"),
xs:dateTime("2002-04-02T23:00:00+06:00")) returns true.•
op:dateTime-equal(xs:dateTime("2002-04-02T12:00:00"),
xs:dateTime("2002-04-02T17:00:00")) returns false.•
op:dateTime-equal(xs:dateTime("2002-04-02T12:00:00"),
xs:dateTime("2002-04-02T12:00:00")) returns true.•
op:dateTime-equal(xs:dateTime("2002-04-02T23:00:00-04:00"),
xs:dateTime("2002-04-03T02:00:00-01:00")) returns true.•op:dateTime-equal(xs:dateTime("1999-12-31T24:00:00"),
xs:dateTime("2000-01-01T00:00:00")) returns true.
•op:dateTime-equal(xs:dateTime("2005-04-04T24:00:00"),
xs:dateTime("2005-04-04T00:00:00")) returns false.
10.4.7. op:dateTime-less-thanFunction: xs:boolean dateTime-less-than(xs:dateTime, xs:dateTime)Summary: Returns true if and only if the value of
$arg1 is less than the 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.
Returns false otherwise.This function backs up the "lt" and "le" operators on
xs:dateTime values.10.4.8. op:dateTime-greater-thanFunction: xs:boolean dateTime-greater-than(xs:dateTime, xs:dateTime)Summary: Returns true if and only if the value of
$arg1 is greater than the 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.
Returns false otherwise.This function backs up the "gt" and "ge" operators on
xs:dateTime values.10.4.9. op:date-equalFunction: xs:boolean date-equal(xs:date, xs:date)Summary: Returns true if and only if the starting instant of
$arg1 is equal to starting instant of $arg2.
Returns false otherwise.The starting instant of an xs:date is the xs:dateTime at time 00:00:00 on that date.
The two starting instants are compared using op:dateTime-equal.
This function backs up the "eq", "ne", "le" and "ge" operators on xs:date values.10.4.9.1. Examples•
op:date-equal(xs:date("2004-12-25Z"),
xs:date("2004-12-25+07:00")) returns false. The starting instants are xs:dateTime("2004-12-25T00:00:00Z") and xs:dateTime("2004-12-25T00:00:00+07:00"). These are normalized to xs:dateTime("2004-12-25T00:00:00Z") and xs:dateTime("2004-12-24T17:00:00Z").•
op:date-equal(xs:date("2004-12-25-12:00"),
xs:date("2004-12-26+12:00")) returns true.10.4.10. op:date-less-thanFunction: xs:boolean date-less-than(xs:date, xs:date)Summary: Returns true if and only if the starting instant of
$arg1 is less than the starting instant of $arg2.
Returns false otherwise.The starting instant of an xs:date is the xs:dateTime at time 00:00:00 on that date.
The two starting instants are compared using op:dateTime-less-than.This function backs up the "lt" and "le" operators on xs:date values.10.4.10.1. Examples•
op:date-less-than(xs:date("2004-12-25Z"),
xs:date("2004-12-25-05:00")) returns true.•
op:date-less-than(xs:date("2004-12-25-12:00"),
xs:date("2004-12-26+12:00")) returns false.10.4.11. op:date-greater-thanFunction: xs:boolean date-greater-than(xs:date, xs:date)Summary: Returns true if and only if the starting instant of
$arg1 is greater than the starting instant of $arg2. Returns false otherwise.The starting instant of an xs:date is the xs:dateTime at time 00:00:00 on that date.
The two starting instants are compared using op:dateTime-greater-than.This function backs up the "gt" and "ge" operators on xs:date values.10.4.11.1. Examples•
op:date-greater-than(xs:date("2004-12-25Z"),
xs:date("2004-12-25+07:00")) returns true.•
op:date-greater-than(xs:date("2004-12-25-12:00"),
xs:date("2004-12-26+12:00")) returns false.10.4.12. op:time-equalFunction: xs:boolean time-equal(xs:time, xs:time)Summary: Returns true if and only if the value of
$arg1 converted to an xs:dateTime using the date components from the reference xs:dateTime is equal to the value of $arg2 converted to an xs:dateTime using the date components from the same reference xs:dateTime.
Returns false otherwise.The two xs:dateTime values are compared using op:dateTime-equal.This function backs up the "eq", "ne", "le" and "ge" operators on xs:time values.10.4.12.1. ExamplesAssume that the date components from the reference xs:dateTime correspond to 1972-12-31.•
op:time-equal(xs:time("08:00:00+09:00"),
xs:time("17:00:00-06:00")) returns false. The xs:dateTimes calculated using the reference date components are 1972-12-31T08:00:00+09:00 and 1972-12-31T17:00:00-06:00.
These normalize to 1972-12-30T23:00:00Z and 1972-12-31T23:00:00.
•
op:time-equal(xs:time("21:30:00+10:30"),
xs:time("06:00:00-05:00")) returns true.•
op:time-equal(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.
10.4.13. op:time-less-thanFunction: xs:boolean time-less-than(xs:time, xs:time)Summary: Returns true if and only if the value of
$arg1 converted to an xs:dateTime using the date components from the reference xs:dateTime is less than the normalized value of $arg2 converted to an xs:dateTime using the date components from the same reference xs:dateTime.
Returns false otherwise.The two xs:dateTime values are compared using op:dateTime-less-than.This function backs up the "lt" and "le" operators on xs:time values.10.4.13.1. ExamplesAssume that the dynamic context provides an implicit timezone value of -05:00.•
op:time-less-than(xs:time("12:00:00"),
xs:time("23:00:00+06:00")) returns false.•
op:time-less-than(xs:time("11:00:00"),
xs:time("17:00:00Z")) returns true.•
op:time-less-than(xs:time("23:59:59"), xs:time("24:00:00")) returns false.10.4.14. op:time-greater-thanFunction: xs:boolean time-greater-than(xs:time, xs:time)Summary: Returns true if and only if the value of
$arg1 converted to an xs:dateTime using the date components from the reference xs:dateTime is greater than the value of
$arg2 converted to an xs:dateTime using the date components from the same reference xs:dateTime. Returns false otherwise.The two xs:dateTime values are compared using op:dateTime-greater-than.This function backs up the "gt" and "ge" operators on xs:time values.10.4.14.1. Examples•
op:time-greater-than(xs:time("08:00:00+09:00"),
xs:time("17:00:00-06:00")) returns false.10.4.15. op:gYearMonth-equalFunction: xs:boolean gYearMonth-equal(xs:gYearMonth, xs:gYearMonth)Summary: Returns true if and only if the xs:dateTimes representing the starting instants of $arg1 and $arg2 compare equal. The starting instants of $arg1 and $arg2 are calculated by adding the missing components of $arg1 and $arg2 from the xs:dateTime template xxxx-xx-ddT00:00:00 where dd represents the last day of the month component in $arg1 or $arg2. Returns false otherwise. The two xs:dateTime values representing the starting instants of $arg1 and $arg2 are compared using op:dateTime-equal.This function backs up the "eq" and "ne" operators on
xs:gYearMonth values.10.4.15.1. ExamplesAssume that the dynamic context provides an implicit timezone value of -05:00.•
op:gYearMonth-equal(xs:gYearMonth("1976-02"),
xs:gYearMonth("1976-03Z")) returns false. The starting instants are 1972-02-29T00:00:00-05:00 and 1972-03-31T00:00:00Z, respectively.•
op:gYearMonth-equal(xs:gYearMonth("1976-03"),
xs:gYearMonth("1976-03Z")) returns false.10.4.16. op:gYear-equalFunction: xs:boolean gYear-equal(xs:gYear, xs:gYear)Summary: Returns true if and only if the xs:dateTimes representing the starting instants of $arg1 and $arg2 compare equal. The starting instants of $arg1 and $arg2 are calculated by adding the missing components of $arg1 and $arg2 from a xs:dateTime template such as xxxx-01-01T00:00:00. Returns false otherwise.The two xs:dateTime values representing the starting instants of $arg1 and $arg2 are compared using op:dateTime-equal.This function backs up the "eq" and "ne" operators on xs:gYear values.10.4.16.1. ExamplesAssume that the dynamic context provides an implicit timezone value of -05:00. Assume, also, that the xs:dateTime template is xxxx-01-01T00:00:00.•
op:gYear-equal(xs:gYear("2005-12:00"),
xs:gYear("2005+12:00")) returns false.
The starting instants are 2005-01-01T00:00:00-12:00 and
2005-01-01T00:00:00+12:00, respectively, and normalize to
2005-01-01T12:00:00Z and 2004-12-31T12:00:00Z.
•
op:gYear-equal(xs:gYear("1976-05:00"),
xs:gYear("1976")) returns true.10.4.17. op:gMonthDay-equalFunction: xs:boolean gMonthDay-equal(xs:gMonthDay, xs:gMonthDay)Summary: Returns true if and only if the xs:dateTimes representing the
starting instants of equivalent occurrences of $arg1 and $arg2 compare equal.
The starting instants of equivalent occurrences of $arg1 and $arg2 are calculated
by adding the missing components of $arg1 and $arg2 from an xs:dateTime
template such as 1972-xx-xxT00:00:00. Returns false otherwise.The two xs:dateTime values representing the starting instants of equivalent occurrences of $arg1 and $arg2 are compared using op:dateTime-equal.This function backs up the "eq" and "ne" operators on
xs:gMonthDay values.10.4.17.1. ExamplesAssume that the dynamic context provides an implicit timezone value of -05:00. Assume, also, that the xs:dateTime template is 1976-xx-xxT00:00:00.•
op:gMonthDay-equal(xs:gMonthDay("--12-25-14:00"),
xs:gMonthDay("--12-26+10:00")) returns true. The starting instants are 1976-12-25T00:00:00-14:00 and 1976-12-26T00:00:00+10:00, respectively, and normalize to 1976-12-25T14:00:00Z and 1976-12-25T14:00:00Z.•
op:gMonthDay-equal(xs:gMonthDay("--12-25"),
xs:gMonthDay("--12-26Z")) returns false.10.4.18. op:gMonth-equalFunction: xs:boolean gMonth-equal(xs:gMonth, xs:gMonth)Summary: Returns true if and only if the xs:dateTimes representing the starting instants of equivalent occurrences of $arg1 and $arg2 compare equal. The starting instants of equivalent occurrences of $arg1 and $arg2 are calculated by adding the missing components of $arg1 and $arg2 from an xs:dateTime template such as 1972-xx-ddT00:00:00 where dd represents the last day of the month component in $arg1 or $arg2. Returns false otherwise.The two xs:dateTime values representing the starting instants of equivalent occurrences of $arg1 and $arg2 are compared using op:dateTime-equal.This function backs up the "eq" and "ne" operators on xs:gMonth values.10.4.18.1. ExamplesAssume that the dynamic context provides an implicit timezone value of -05:00. Assume, also, that the xs:dateTime template is 1972-xx-29T00:00:00.
•op:gMonth-equal(xs:gMonth("--12-14:00"), xs:gMonth("--12+10:00")) returns
false. The starting instants are 1972-12-29T00:00:00-14:00 and
1972-12-29T00:00:00+10:00, respectively, and normalize to
1972-12-29T14:00:00Z and 1972-12-28T14:00:00Z.
•
op:gMonth-equal(xs:gMonth("--12"),
xs:gMonth("--12Z")) returns false.10.4.19. op:gDay-equalFunction: xs:boolean gDay-equal(xs:gDay, xs:gDay)Summary: Returns true if and only if the xs:dateTimes representing the starting instants of equivalent occurrences of $arg1 and $arg2 compare equal. The starting instants of equivalent occurrences of $arg1 and $arg2 are calculated by adding the missing components of $arg1 and $arg2 from an xs:dateTime template such as 1972-12-xxT00:00:00. Returns false otherwise.The two xs:dateTime values representing the starting instants of equivalent occurrences of $arg1 and $arg2 are compared using op:dateTime-equal.This function backs up the "eq" and "ne" operators on xs:gDay values.10.4.19.1. ExamplesAssume that the dynamic context provides an implicit timezone value of -05:00. Assume, also, that the xs:dateTime template is 1976-12-xxT00:00:00.•
op:gDay-equal(xs:gDay("---25-14:00"),
xs:gDay("---25+10:00")) returns false. The starting instants are 1972-12-25T00:00:00-14:00 and 1972-12-25T00:00:00+10:00, respectively, and normalize to 1972-12-25T14:00:00Z and 1972-12-24T14:00:00Z.•
op:gDay-equal(xs:gDay("---12"),
xs:gDay("---12Z")) returns false.Component Extraction Functions on Durations, Dates and Times10.5. Component Extraction Functions on Durations, Dates and TimesThe duration, 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 duration, date or time value. For
the date/time datatypes the local value is used.
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:years-from-duration
Returns the year component of an xs:duration
value.
fn:months-from-duration
Returns the months component of an
xs:duration value.
fn:days-from-duration
Returns the days component of an xs:duration
value.
fn:hours-from-duration
Returns the hours component of an xs:duration
value.
fn:minutes-from-duration
Returns the minutes component of an xs:duration
value.
fn:seconds-from-duration
Returns the seconds component of an xs:duration
value.
fn:year-from-dateTime
Returns the year from an xs:dateTime value.
fn:month-from-dateTime
Returns the month from an xs:dateTime value.
fn:day-from-dateTime
Returns the day from an xs:dateTime value.
fn:hours-from-dateTime
Returns the hours from an xs:dateTime value.
fn:minutes-from-dateTime
Returns the minutes from an xs:dateTime value.
fn:seconds-from-dateTime
Returns the seconds from an xs:dateTime value.
fn:timezone-from-dateTime
Returns the timezone from an xs:dateTime value.
fn:year-from-date
Returns the year from an xs:date value.
fn:month-from-date
Returns the month from an xs:date value.
fn:day-from-date
Returns the day from an xs:date value.
fn:timezone-from-date
Returns the timezone from an xs:date value.
fn:hours-from-time
Returns the hours from an xs:time value.
fn:minutes-from-time
Returns the minutes from an xs:time value.
fn:seconds-from-time
Returns the seconds from an xs:time value.
fn:timezone-from-time
Returns the timezone from an xs:time value.
10.5.1. fn:years-from-durationFunction: xs:integer years-from-duration(xs:duration)Summary: Returns an xs:integer representing the years component
in the value of $arg. The result is obtained by casting $arg to an xs:yearMonthDuration (see § 17.1.4 – Casting to duration types on page ) and then computing the years component as described in § 10.3.1.3 – Canonical representation on page .The result may be negative.If $arg is an xs:dayTimeDuration returns 0.If $arg is the empty sequence, returns the empty sequence.10.5.1.1. Examples•
fn:years-from-duration(xs:yearMonthDuration("P20Y15M"))
returns 21.•
fn:years-from-duration(xs:yearMonthDuration("-P15M"))
returns -1.•
fn:years-from-duration(xs:dayTimeDuration("-P2DT15H"))
returns 0.10.5.2. fn:months-from-durationFunction: xs:integer months-from-duration(xs:duration)Summary: Returns an xs:integer representing the months component
in the value of $arg. The result is obtained by casting $arg to an xs:yearMonthDuration (see § 17.1.4 – Casting to duration types on page ) and then computing the months component as described in § 10.3.1.3 – Canonical representation on page .The result may be negative.If $arg is an xs:dayTimeDuration returns 0.If $arg is the empty sequence, returns the empty sequence.10.5.2.1. Examples•
fn:months-from-duration(xs:yearMonthDuration("P20Y15M"))
returns 3.•
fn:months-from-duration(xs:yearMonthDuration("-P20Y18M"))
returns -6.•
fn:months-from-duration(xs:dayTimeDuration("-P2DT15H0M0S"))
returns 0.10.5.3. fn:days-from-durationFunction: xs:integer days-from-duration(xs:duration)Summary: Returns an xs:integer representing the days component
in the value of $arg. The result is obtained by casting $arg to an xs:dayTimeDuration (see § 17.1.4 – Casting to duration types on page ) and then computing the days component as described in § 10.3.2.3 – Canonical representation on page .The result may be negative.If $arg is an xs:yearMonthDuration returns 0. If $arg is the empty sequence, returns the empty sequence.10.5.3.1. Examples•
fn:days-from-duration(xs:dayTimeDuration("P3DT10H"))
returns 3.•
fn:days-from-duration(xs:dayTimeDuration("P3DT55H"))
returns 5.•
fn:days-from-duration(xs:yearMonthDuration("P3Y5M"))
returns 0.10.5.4. fn:hours-from-durationFunction: xs:integer hours-from-duration(xs:duration)Summary: Returns an xs:integer representing the hours component
in the value of $arg. The result is obtained by casting $arg to an xs:dayTimeDuration (see § 17.1.4 – Casting to duration types on page ) and then computing the hours component as described in § 10.3.2.3 – Canonical representation on page .The result may be negative.If $arg is an xs:yearMonthDuration returns 0. If $arg is the empty sequence, returns the empty sequence.10.5.4.1. Examples•
fn:hours-from-duration(xs:dayTimeDuration("P3DT10H"))
returns 10.•
fn:hours-from-duration(xs:dayTimeDuration("P3DT12H32M12S"))
returns 12.•
fn:hours-from-duration(xs:dayTimeDuration("PT123H"))
returns 3.•