W3C

XQuery 1.0 and XPath 2.0 Functions and Operators

W3C Working Draft 30 April 2002

This version:
http://www.w3.org/TR/2002/WD-xquery-operators-20020430/
Latest version:
http://www.w3.org/TR/xquery-operators/
Previous version:
http://www.w3.org/TR/2001/WD-xquery-operators-20011220/
Editors:
Ashok Malhotra (XML Query and XSL WGs), Microsoft <ashokma@microsoft.com>
Jim Melton (XML Query WG), Oracle Corp <jim.melton@acm.org>
Jonathan Robie (XML Query WG), Software AG <Jonathan.Robie@SoftwareAG-USA.com>
Norman Walsh (XSL WG), Sun Microsystems <Norman.Walsh@Sun.COM>

Abstract

This document defines basic operators and functions on the datatypes defined in [XML Schema Part 2: Datatypes] for use in XQuery, XPath, XSLT and other related XML standards. It also discusses operators and functions on nodes and node sequences as defined in the [XQuery 1.0 and XPath 2.0 Data Model] for use in XQuery, XPath, XSLT and other related XML standards.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This is a Public Working Draft of this document for review by W3C Members and other interested parties. It is a draft document and may be updated, replaced or made obsolete by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". This is work in progress and does not imply endorsement by the W3C membership.

This document describes constructors, operators, and functions that are used in [XPath 2.0], [XQuery 1.0: An XML Query Language] and [XSLT 2.0]. The document is generally unconcerned with the specific syntax with which these constructors, operators, and functions will be used, and focuses instead on defining the semantics of them as precisely as feasible.

Perhaps the largest change from previous versions of this document appears in section 6 Constructors, Functions, and Operators on Durations, Dates and Times. The duration datatype defined in [XML Schema Part 2: Datatypes] is partially ordered. This makes it difficult to work with. In light of this the Working Groups decided to limit support for the duration datatype and define two new, totally ordered, subtypes of duration called yearMonthDuration and dayTimeDuration. These dataypes are defined in section 6.2 Two Totally Ordered Subtypes of Duration and a full complement of functions is defined on them in the following sections.

Another significant change that the Working Groups have been discussing but have not finalized is the treatment of the [XML Schema Part 2: Datatypes] date and time types: dateTime, date and time as well as gYear, gMonth, gDay, gYearMonth and gMonthDay. These types also have partial orders due to the fact that they may or may not contain time zones. (See issue 150 below.) A solution to this problem is to postulate that dateTime, date and time values that do not have a time zone are, for purposes of comparison, given an implementation defined time zone. If we adopt this solution we can define constructors, equality and comparison functions and casting on these datatypes as well as helper functions to add and remove time zones, etc. For the other five dataypes: gYear, gMonth, gDay, gYearMonth and gMonthDay we are considering adopting a similar solution but limiting the support to only constructors, equality and, possibly, casting.

There is also ongoing discussion about whether the syntax for constructors and casting can be unified. (See issue 16 below.) This has potentially wide impact and may reopen the closed issue of casting to and from derived types. For this reason section 14 Casting Functions is unchanged from the previous version of this document.

This document has been produced following the procedures set out for the W3C Process. This document was produced through the efforts of a joint task force of the W3C XML Query Working Group and the W3C XML Schema Working Group (both part of the W3C XML Activity) and a second joint task force of the W3C XML Query Working Group and the W3C XSL Working Group (part of the W3C Style Activity). It is designed to be read in conjunction with the following documents: [XQuery 1.0 and XPath 2.0 Data Model], [XPath 2.0], [XQuery 1.0: An XML Query Language] and [XSLT 2.0].

The following are identified as high priority issues. Reviewers are requested to provide feedback on these issues using the address below.

[Issue 16: Is a constructor more than a different syntax for CAST?]

[Issue 139: Need a fuller treatment of error behaviour and possibly error handling.]

[Issue 145: Need decisions and text in several of our documents detailing conformance requirements based on resource limitations.]

[Issue 150: Should we support comparisons of date/time types that return indeterminate results?]

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR/.

Comments on this document should be sent to the W3C mailing list www-xml-query-comments@w3.org (archived at http://lists.w3.org/Archives/Public/www-xml-query-comments/).

Table of Contents

1 Introduction
    1.1 Terminology
    1.2 Datatypes
    1.3 Syntax
    1.4 Notations
    1.5 Namespace Prefix
2 Accessors
    2.1 xf:node-kind
    2.2 xf:node-name
    2.3 xf:string
    2.4 xf:data
    2.5 xf:base-uri
    2.6 xf:unique-ID
3 Constructors, Functions, and Operators on Numbers
    3.1 Numeric Types
    3.2 Numeric Constructors
        3.2.1 xf:decimal
        3.2.2 xf:integer
        3.2.3 xf:long
        3.2.4 xf:int
        3.2.5 xf:short
        3.2.6 xf:byte
        3.2.7 xf:float
        3.2.8 xf:double
    3.3 Operators on Numeric Values
        3.3.1 op:numeric-add
        3.3.2 op:numeric-subtract
        3.3.3 op:numeric-multiply
        3.3.4 op:numeric-divide
        3.3.5 op:numeric-mod
        3.3.6 op:numeric-unary-plus
        3.3.7 op:numeric-unary-minus
    3.4 Comparisons of Numeric Values
        3.4.1 op:numeric-equal
        3.4.2 op:numeric-less-than
        3.4.3 op:numeric-greater-than
    3.5 Functions on Numeric Values
        3.5.1 xf:floor
        3.5.2 xf:ceiling
        3.5.3 xf:round
4 Constructors and Functions on Strings
    4.1 String Types
    4.2 String Constructors
        4.2.1 xf:string
        4.2.2 xf:normalizedString
        4.2.3 xf:token
        4.2.4 xf:language
        4.2.5 xf:Name
        4.2.6 xf:NMTOKEN
        4.2.7 xf:NCName
        4.2.8 xf:ID
        4.2.9 xf:IDREF
        4.2.10 xf:ENTITY
    4.3 Equality and Comparison of Strings
        4.3.1 xf:compare
    4.4 Functions on String Values
        4.4.1 Usage Notes
        4.4.2 xf:concat
        4.4.3 xf:starts-with
        4.4.4 xf:ends-with
        4.4.5 xf:contains
        4.4.6 xf:substring
        4.4.7 xf:string-length
        4.4.8 xf:substring-before
        4.4.9 xf:substring-after
        4.4.10 xf:normalize-space
        4.4.11 xf:normalize-unicode
        4.4.12 xf:upper-case
        4.4.13 xf:lower-case
        4.4.14 xf:translate
        4.4.15 xf:string-pad
        4.4.16 xf:match
        4.4.17 xf:replace
5 Constructors, Functions and Operators on Booleans
    5.1 Boolean Constructors
        5.1.1 xf:true
        5.1.2 xf:false
        5.1.3 xf:boolean-from-string
    5.2 Operators on Boolean Values
        5.2.1 op:boolean-equal
    5.3 Functions on Boolean Values
        5.3.1 xf:not
        5.3.2 op:boolean-less-than
        5.3.3 op:boolean-greater-than
6 Constructors, Functions, and Operators on Durations, Dates and Times
    6.1 Duration, Date and Time Types
    6.2 Two Totally Ordered Subtypes of Duration
        6.2.1 yearMonthDuration
        6.2.2 dayTimeDuration
    6.3 Duration, Date and Time Constructors
        6.3.1 xf:duration
        6.3.2 xf:dateTime
        6.3.3 xf:date
        6.3.4 xf:time
        6.3.5 xf:gYearMonth
        6.3.6 xf:gYear
        6.3.7 xf:gMonthDay
        6.3.8 xf:gMonth
        6.3.9 xf:gDay
    6.4 yearMonthDuration and dayTimeDuration Constructors
        6.4.1 xf:yearMonthDuration
        6.4.2 xf:yearMonthDuration-from-months
        6.4.3 xf:dayTimeDuration
        6.4.4 xf:dayTimeDuration-from-seconds
    6.5 Comparisons of Duration, Date and Time Values
        6.5.1 op:duration-equal
        6.5.2 op:yearMonthDuration-equal
        6.5.3 op:yearMonthDuration-less-than
        6.5.4 op:yearMonthDuration-greater-than
        6.5.5 op:dayTimeDuration-equal
        6.5.6 op:dayTimeDuration-less-than
        6.5.7 op:dayTimeDuration-greater-than
        6.5.8 op:datetime-equal
        6.5.9 op:datetime-less-than
        6.5.10 op:datetime-greater-than
    6.6 Component Extraction Functions on Duration, Date and Time Values
        6.6.1 xf:get-years-from-yearMonthDuration
        6.6.2 xf:get-months-from-yearMonthDuration
        6.6.3 xf:get-days-from-dayTimeDuration
        6.6.4 xf:get-hours-from-dayTimeDuration
        6.6.5 xf:get-minutes-from-dayTimeDuration
        6.6.6 xf:get-seconds-from-dayTimeDuration
        6.6.7 xf:get-year-from-dateTime
        6.6.8 xf:get-year-from-date
        6.6.9 xf:get-month-from-dateTime
        6.6.10 xf:get-month-from-date
        6.6.11 xf:get-day-from-dateTime
        6.6.12 xf:get-day-from-date
        6.6.13 xf:get-hours-from-dateTime
        6.6.14 xf:get-hours-from-time
        6.6.15 xf:get-minutes-from-dateTime
        6.6.16 xf:get-minutes-from-time
        6.6.17 xf:get-seconds-from-dateTime
        6.6.18 xf:get-seconds-from-time
        6.6.19 xf:get-timezone-from-dateTime
        6.6.20 xf:get-timezone-from-date
        6.6.21 xf:get-timezone-from-time
    6.7 Arithmetic Functions on yearMonthDuration and dayTimeDuration
        6.7.1 op:add-yearMonthDurations
        6.7.2 op:subtract-yearMonthDurations
        6.7.3 op:multiply-yearMonthDuration
        6.7.4 op:divide-yearMonthDuration
        6.7.5 op:add-dayTimeDurations
        6.7.6 op:subtract-dayTimeDurations
        6.7.7 op:multiply-dayTimeDuration
        6.7.8 op:divide-dayTimeDuration
    6.8 Arithmetic Functions on Dates
        6.8.1 xf:add-days
    6.9 Functions and Operators on TimePeriod Values
        6.9.1 xf:get-yearMonthDuration
        6.9.2 xf:get-dayTimeDuration
        6.9.3 op:add-yearMonthDuration-to-dateTime
        6.9.4 op:add-dayTimeDuration-to-dateTime
        6.9.5 op:subtract-yearMonthDuration-from-dateTime
        6.9.6 op:subtract-dayTimeDuration-from-dateTime
        6.9.7 op:add-yearMonthDuration-to-date
        6.9.8 op:add-dayTimeDuration-to-date
        6.9.9 op:subtract-yearMonthDuration-from-date
        6.9.10 op:subtract-dayTimeDuration-from-date
        6.9.11 op:add-dayTimeDuration-to-time
        6.9.12 op:subtract-dayTimeDuration-from-time
7 Constructors and Functions on QNames
    7.1 Constructors for QNames
        7.1.1 xf:QName-from-uri
        7.1.2 xf:QName-from-string
        7.1.3 xf:QName
    7.2 Functions on QNames
        7.2.1 op:QName-equal
        7.2.2 xf:get-local-name
        7.2.3 xf:get-namespace-uri
        7.2.4 xf:namespace-uri
8 Constructors, Functions, and Operators for anyURI
    8.1 Constructors for anyURI
        8.1.1 xf:anyURI
        8.1.2 xf:resolve-URI
    8.2 Functions on anyURI
        8.2.1 op:anyURI-equal
9 Functions and Operators on base64Binary and hexBinary
    9.1 Comparisons of base64Binary and hexBinary Values
        9.1.1 op:hex-binary-equal
        9.1.2 op:base64-binary-equal
10 Constructors, Functions, and Operators on NOTATION
    10.1 NOTATION Constructor
        10.1.1 xf:NOTATION
    10.2 Functions on NOTATION
        10.2.1 op:NOTATION-equal
11 Functions and Operators on Nodes
    11.1 Functions and Operators on Nodes
        11.1.1 xf:name
        11.1.2 xf:local-name
        11.1.3 xf:number
        11.1.4 xf:lang
        11.1.5 op:node-equal
        11.1.6 xf:deep-equal
        11.1.7 op:node-before
        11.1.8 op:node-after
        11.1.9 op:node-precedes
        11.1.10 op:node-follows
        11.1.11 xf:copy
        11.1.12 xf:shallow
        11.1.13 xf:root
    11.2 if-absent() and if-empty()
        11.2.1 xf:if-absent
        11.2.2 xf:if-empty
12 Constructors, Functions, and Operators on Sequences
    12.1 Constructors on Sequences
        12.1.1 op:to
    12.2 Functions and Operators on Sequences
        12.2.1 xf:boolean
        12.2.2 op:concatenate
        12.2.3 op:item-at
        12.2.4 xf:index-of
        12.2.5 xf:empty
        12.2.6 xf:exists
        12.2.7 xf:distinct-nodes
        12.2.8 xf:distinct-values
        12.2.9 xf:insert
        12.2.10 xf:remove
        12.2.11 xf:subsequence
    12.3 Equals, Union, Intersection and Except
        12.3.1 xf:sequence-deep-equal
        12.3.2 xf:sequence-node-equal
        12.3.3 op:union
        12.3.4 op:intersect
        12.3.5 op:except
    12.4 Aggregate Functions
        12.4.1 xf:count
        12.4.2 xf:avg
        12.4.3 xf:max
        12.4.4 xf:min
        12.4.5 xf:sum
    12.5 Functions that Generate Sequences
        12.5.1 xf:id
        12.5.2 xf:idref
        12.5.3 xf:filter
        12.5.4 xf:document
        12.5.5 xf:collection
        12.5.6 xf:input
13 Context Functions
    13.1 xf:context-item
    13.2 xf:position
    13.3 xf:last
    13.4 op:context-document
    13.5 xf:current-dateTime
        13.5.1 Examples
14 Casting Functions
    14.1 Casting to primitive types from primitive types
    14.2 Casting from derived types to primitive types
    14.3 Casting to string
    14.4 Casting to numeric types
    14.5 Casting to duration and date and time types
    14.6 Casting to boolean
    14.7 Casting to base64Binary, hexBinary
    14.8 Casting to anyURI, QName and NOTATION

Appendices

A References
    A.1 Normative
    A.2 Non-normative
B Functions and Operators Issues List (Non-Normative)
C ChangeLog (Non-Normative)
D Function and Operator Quick Reference (Non-Normative)
    D.1 Functions and Operators by Section
    D.2 Functions and Operators Alphabetically


1 Introduction

[XML Schema Part 2: Datatypes] defines a number of primitive and derived datatypes, collectively known as built-in datatypes. This document defines operations on those datatypes for use in XQuery, XPath, XSLT and related XML standards. This document also discusses operators and functions on nodes and node sequences as defined in the [XQuery 1.0 and XPath 2.0 Data Model] for use in XQuery, XPath, XSLT and other related XML standards.

1.1 Terminology

The terminology used to describe the functions and operators on [XML Schema Part 2: Datatypes] is defined in the body of this specification. The terms defined in the following list are used in building those definitions:

[Definition] for compatibility

A feature of this specification included to ensure that implementations that use this feature remain compatible with [XPath 1.0]

[Definition] may

Conforming documents and processors are permitted to but need not behave as described.

[Definition] must

Conforming documents and processors are required to behave as described; otherwise they are non-conformant or in error.

[Definition] implementation defined

Possibly differing between implementations, but specified by the implementor for each particular implementation.

[Definition] implementation dependent

Possibly differing between implementations, but not specified by this or other W3C specification, and not required to be specified by the implementor for any particular implementation.

1.2 Datatypes

The diagram below shows the built-in [XML Schema Part 2: Datatypes]. Solid lines connect a base datatype above to a derived datatype below. Dashed lines connect a datatype created as a list of an item type above.

Type hierarchy graphic

Diagram courtesy Asir Vedamuthu, webMethods

1.3 Syntax

The purpose of this document is to catalog the functions and operators required for XPath 2.0, XML Query 1.0 and XSLT 2.0. The exact syntax used to invoke these functions and operators is specified in [XPath 2.0], [XQuery 1.0: An XML Query Language] and [XSLT 2.0].

In general, the above specifications do not support function overloading. Consequently, there are no overloaded functions in this document except for legacy [XPath 1.0] functions such as string() which takes a single argument of a variety of types and concat() which takes a variable number of string arguments. This does not apply to operators such as "+" which may be overloaded. Functions with optional arguments are allowed. If optional arguments are omitted, omissions are assumed to begin from the right.

1.4 Notations

This document defines, among other things, constructors and other functions that apply to one or more data types. Each constructor and function is defined by specifying its signature, a description of each of its arguments, and its semantics. For many constructors and functions, examples are included to illustrate their use.

Each function's signature is presented in a form like this:

xf:function-name(parameter-type $parameter-name, ...) => return-type

In this notation, function-name is the name of the function whose signature is being specified. If the function takes no parameters, then the name is followed by an empty set of parentheses: (); otherwise, the name is followed by a parenthesized list of parameter declarations, each declaration specifying the static type of the parameter and a non-normative name used to reference the parameter when the function's semantics are specified. If there are two or more parameter declarations, they are separated by a comma. The return-type specifies the static type of the value returned by the function.

The function name is a QName as defined in [XML 1.0 Recommendation (Second Edition)] and must adhere to it's syntatic conventions. Following [XPath 1.0], function names are composed of English words separated by hyphens,"-". If a function name contains a [XML Schema Part 2: Datatypes] datatype name, this may have intercapitalized spelling and is used in the function name as such. For example, xf:get-timezone-from-dateTime.

As is customary, the parameter type name indicates that the function accepts arguments of that type in that position. If the parameter type name is one of the simple types defined in [XML Schema Part 2: Datatypes] the function also accepts arguments with types derived from that type. These may be one of the derived types in [XML Schema Part 2: Datatypes] or they may be user-derived types.

Some functions accept the empty sequence as an argument and some may return the empty sequence. This is indicated in the function signature by following the parameter type name with a question mark:

xf:function-name(parameter-type? $parameter-name) => return-type?

The names of constructor functions have been chosen so that their local names are "spelled the same" as the local names of the types for which they are constructors. For example, the name of the constructor function that constructs values whose type is xsd:decimal is xf:decimal. Throughout this document, we typically omit the prefix xsd: in the names of XML Schema types.

[Issue 133: Syntax for indicating that function accepts empty sequence is incorrect]

1.5 Namespace Prefix

The functions and operators discussed in this document are contained in two namespaces and referenced using a qualified name. The namespace prefix used in this document—merely for illustrative purposes—is xf: for the user functions and op: for the operator functions. The namespace prefix for these functions can vary, as long as the prefix is bound to the currect URI.

The actual namespaces (that is, the URI of the namespaces) are:

  • http://www.w3.org/2002/04/xquery-operators for operators

  • http://www.w3.org/2002/04/xquery-functions for functions.

The functions defined with a xf: prefix are callable by the user. Functions defined with the op: prefix are described here to underpin the definitions of the operators in [XPath 2.0], [XQuery 1.0: An XML Query Language] and [XSLT 2.0]. These functions are not available directly to users, and there is no requirement that implementations should actually provide these functions. For example, multiplication is generally associated with the * operator, but it is described as a function in this document. For example:

op:multiply(numeric $operand1, numeric $operand2) => numeric

2 Accessors

The [XQuery 1.0 and XPath 2.0 Data Model] describes accessors on different types of nodes and defines their semantics. Some of these accessors are exposed to the userthrough the functions described below.

FunctionAccessorAcceptsReturns
xf:node-kindnode-kindany kind of nodestring
xf:node-namenameany kind of nodezero or one QName
xf:stringstring-valuea sequence, a node of any kind, or a simple valuestring
xf:datatyped-valueany kind of nodea typed sequence of atomic values
xf:base-uribase-uriElement or Document nodezero or one anyURI
xf:unique-IDunique-IDElement nodezero or one ID

2.1 xf:node-kind

xf:node-kind(node $srcval) => string

This function returns a string value representing the node's kind: either "document", "element", "attribute", "text", "namespace", "processing-instruction", or "comment".

2.2 xf:node-name

xf:node-name(node $srcval) => QName?

This function returns an expanded QName for node kinds that can have names. For other node kinds, it returns the empty sequence. Expanded QName is defined in [XQuery 1.0 and XPath 2.0 Data Model], and consists of a namespace URI and a local name.

2.3 xf:string

xf:string() => string
xf:string(item* $srcval) => string

Returns the value of $srcval represented as a string. If no argument is supplied, $srcval defaults to the context item (.).

If $srcval is the empty sequence, the empty string is returned.

If $srcval is a node, the function returns the string value of the node, as obtained using the string-value accessor defined in the [XQuery 1.0 and XPath 2.0 Data Model].

If $srcval is a simple value, the function returns the same string as is returned by the expression cast as xs:string ($srcval), except in the cases listed below:

  • If the type of $srcval is xs:decimal, and the value is equal to an integer, then the function returns the canonical representation of that integer.

  • If the type of $srcval is xs:anyURI, the URI is converted to a string without any escaping of special characters.

NOTE: The reason for the special rule for xs:decimal is backwards compatibility with XPath 1.0. Many simple arithmetic operations such as 10 div 5 will give a decimal result. At XPath 1.0, such operations gave a result of type "number". Converting such a number to a string would display it without a decimal point if the actual value was equal to an integer.

NOTE: The reason for the special rule for xs:anyURI is that, although XML Schema strongly discourages the use of spaces within URI values, the escaping of spaces can cause problems with legacy applications (for example, this applies to spaces within fragment identifiers in many HTML browsers), and should therefore be under user control.

NOTE: The string representation of double values is not backwards-compatible with the representation of number values in XPath 1.0. Ordinary double values are now represented using scientific notation; the representations of positive and negative infinity are now INF and -INF rather than Infinity and -Infinity; and negative zero is represented as -0 rather than 0. However, most expressions that would have produced a number in XPath 1.0 will produce a decimal (or integer) in XPath 2.0, so unless there is a loss of precision caused by numeric approximation, the result of the expression will in most simple cases be the same after conversion to a string.

NOTE: If a sequence of more than one item is supplied as the argument to the function, a type exception occurs. If fallback conversion rules are in use, this means that the function is applied in effect to the first item in the supplied sequence, and remaining items are ignored.

[Issue 160: Align the string() function with 'cast as string'.]

2.4 xf:data

xf:data(node* $srcval) => value*

Returns the typed-value of each node in $srcval. Each node in $srcval is processed as follows.

The static type of the result for each node is determined by the static type of the value that is extracted.

If $srcval is not a node, returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

If $srcval is a document, namespace, comment or processing instruction node, returns the the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

If $srcval is a text node, returns the string content of the text node with type annotation xs:anySimpleType.

If $srcval is an attribute node defined to have xs:anySimpleType, or an element node with complex type and simple content defined to have xs:anySimpleType, returns its string value with type annotation xs:anySimpleType.

If $srcval is an element node defined to have xs:anyType, returns its string value with type xs:anySimpleType as obtained by concatenating the descendent text nodes in document order.

If $srcval is an element or attribute node with a simple type other than xs:anySimpleType or with a complex type with simple content other than xs:anySimpleType, returns the node's typed value which is a sequence of atomic values. For example:

  • N is an element node of type hatsizelist, which is a complex type that includes a country attribute. The content of the type hatsizelist is a sequence of items of type hatsize, which is derived from xs:decimal. In XML Schema, this content is considered to have a simple type. The typed value of N is a sequence of values of type hatsize.

  • A is an attribute of type IDREFS, a list type derived from IDREF, and its content is "bar baz faz". The typed value of A is a sequence of three atomic values of type IDREF.

If $srcval is an element node defined to have a complex type other than xs:anyType, returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

[Issue 164: For a complex type other than anyType, should data() return the string value obtained by concatenating descendant text nodes?]

2.5 xf:base-uri

xf:base-uri(node $srcval) => anyURI?

For document and element nodes this function returns the value of the base-uri property. For other kinds of node it returns the empty sequence.

2.6 xf:unique-ID

xf:unique-ID(node $srcval) => ID?

This function accepts an element node and returns the identifier (ID) which may have been assigned by the user. It corresponds to the normalized value property of the attribute information item in the attributes property that has a type ID, if one exists. If no ID attribute exists the empty sequnce is returned.

3 Constructors, Functions, and Operators on Numbers

This section discusses arithmetic operators on the numeric datatypes defined in [XML Schema Part 2: Datatypes]. It uses an approach that permits lightweight operations whenever possible.

3.1 Numeric Types

The operators described in this section are defined on the following numeric types.

decimal
integer
int
long
short
byte
float
double

They also apply to user-defined types derived by restriction from these types.

3.2 Numeric Constructors

The following constructors are defined on the above numeric types. Each constructor takes a single string literal as argument. Leading and trailing whitespace, if present, is stripped from the literal before the value is constructed.

[Issue 149: Either the constructor functions should allow dynamic expressions or the syntax should be changed so that they do not appear to be functions. ]

ConstructorMeaning
xf:decimal Produces a decimal value by parsing and interpreting a string.
xf:integer Produces an integer value by parsing and interpreting a string.
xf:long Produces a long value by parsing and interpreting a string.
xf:int Produces an int value by parsing and interpreting a string.
xf:short Produces a short value by parsing and interpreting a string.
xf:byte Produces a byte value by parsing and interpreting a string.
xf:float Produces a float value by parsing and interpreting a string.
xf:double Produces a double value by parsing and interpreting a string.

For float and double, the string argument can indicate the special values: NaN, INF, -INF, +0, and -0.

If the argument string passed to a constructor results in an error (for example, if it conatains a letter other than "E" or "e" or a string other than the special values named above), the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

3.2.1 xf:decimal

xf:decimal(string $srcval) => decimal

Returns the decimal value that is represented by the characters contained in the value of $srcval. For this constructor, $srcval must be a string literal.

If the value of $srcval is not a valid lexical representation for the decimal type as specified in [XML Schema Part 2: Datatypes], then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

If the number of characters contained in the value of $srcval that are digits is greater than the maximum number of decimal digits supported by the implementation, then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

3.2.1.1 Examples
  • xf:decimal('123.5') returns the decimal value corresponding to one hundred twenty three and one-half.

  • xf:decimal('12.5E2') returns the error value, since the use of the letter "E" is prohibited in the constructor for the decimal type.

    xf:decimal(' 12.5 ') returns the decimal value corresponding to twelve and one-half.

3.2.2 xf:integer

xf:integer(string $srcval) => integer

Returns the integer value that is represented by the characters contained in the value of $srcval. For this constructor, $srcval must be a string literal.

If the value of $srcval is not a valid lexical representation for the integer type as specified in [XML Schema Part 2: Datatypes], then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

If the number of characters contained in the value of $srcval that are digits is greater than the maximum number of digits supported by the implementation, then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

3.2.2.1 Examples
  • xf:integer('-123') returns the integer value corresponding to negative one hundred twenty three.

  • xf:integer('123.5') returns the error value, since the use of a decimal point is prohibited in the constructor for the integer type.

3.2.3 xf:long

xf:long(string $srcval) => integer

Returns the long value that is represented by the characters contained in the value of $srcval. For this constructor, $srcval must be a string literal.

If the value of $srcval is not a valid lexical representation for the long type as specified in [XML Schema Part 2: Datatypes], then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

If the value of the number corresponding to the characters contained in the value of $srcval is greater than 9,223,372,036,854,775,807 or less than -9,223,372,036,854,775,808, then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

3.2.3.1 Examples
  • xf:long('-1235') returns the long value corresponding to negative one thousand two hundred thirty five.

  • xf:long('10000000000000000000') returns the error value, since ten quintillion is not a valid value for the long type.

3.2.4 xf:int

xf:int(string $srcval) => integer

Returns the int value that is represented by the characters contained in the value of $srcval. For this constructor, $srcval must be a string literal.

If the value of $srcval is not a valid lexical representation for the int type as specified in [XML Schema Part 2: Datatypes], then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

If the value of the number corresponding to the characters contained in the value of $srcval is greater than 2,147,483,647 or less than -2,147,483,648, then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

3.2.4.1 Examples
  • xf:int('1235') returns the int value corresponding to one thousand two hundred thirty five.

  • xf:int('2147483648') returns the error value, since the value two billion, one hundred forty seven million, four hundred eighty three thousand, six hundred forty eight is not a valid value for the short type.

3.2.5 xf:short

xf:short(string $srcval) => integer

Returns the short value that is represented by the characters contained in the value of $srcval. For this constructor, $srcval must be a string literal.

If the value of $srcval is not a valid lexical representation for the short type as specified in [XML Schema Part 2: Datatypes], then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

If the value of the number corresponding to the characters contained in the value of $srcval is greater than 32,767 or less than -32,768, then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

3.2.5.1 Examples
  • xf:short('1235') returns the short value corresponding to one thousand two hundred thirty five.

  • xf:short('32768') returns the error value, since the value thirty two thousand seven hundred sixty eight is not a valid value for the short type.

3.2.6 xf:byte

xf:byte(string $srcval) => integer

Returns the byte value that is represented by the characters contained in the value of $srcval. For this constructor, $srcval must be a string literal.

If the value of $srcval is not a valid lexical representation for the byte type as specified in [XML Schema Part 2: Datatypes], then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

If the value of the number corresponding to the characters contained in the value of $srcval is greater than 127 or less than -128, then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

3.2.6.1 Examples
  • xf:byte('127') returns the byte value corresponding to one hundred twenty seven.

  • xf:byte('128') returns the error value, since the value one hundred twenty eight is not a valid value for the byte type.

3.2.7 xf:float

xf:float(string $srcval) => float

Returns the float value that is represented by the characters contained in the value of $srcval. For this constructor, $srcval must be a string literal.

If the value of $srcval is "NaN", then the constructor returns the "not-a-number" value.

If the value of $srcval is "INF" or "+INF", then the constructor returns the "positive infinity" value. If the value of $srcval is "-INF", then the constructor returns the "negative infinity" value.

If the value of $srcval is "0" or "+0", then the constructor returns the value positive zero. If the value of $srcval is "-0", then the constructor returns the value negative zero.

If the value of $srcval is not a valid lexical representation for the float type as specified in [XML Schema Part 2: Datatypes], then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

If the value of the number corresponding to the characters contained in the value of $srcval is not a valid value for the float type, then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

3.2.7.1 Examples
  • xf:float('510E2') returns the float value corresponding to fifty one thousand.

  • xf:float('15.25') returns the float value corresponding to fifteen and a quarter.

  • xf:float('51D1') returns the error value, since the use of the letter "D" is prohibited in the constructor for the float type.

3.2.8 xf:double

xf:double(string $srcval) => double

Returns the double value that is represented by the characters contained in the value of $srcval. For this constructor, $srcval must be a string literal.

If the value of $srcval is "NaN", then the constructor returns the "not-a-number" value.

If the value of $srcval is "INF" or "+INF", then the constructor returns the "positive infinity" value. If the value of $srcval is "-INF", then the constructor returns the "negative infinity" value.

If the value of $srcval is "0" or "+0", then the constructor returns the value positive zero. If the value of $srcval is "-0", then the constructor returns the value negative zero.

If the value of $srcval is not a valid lexical representation for the double type as specified in [XML Schema Part 2: Datatypes], then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

If the value of the number corresponding to the characters contained in the value of $srcval is not a valid value for the float type, then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

3.2.8.1 Examples
  • xf:double('510E2') returns the double value corresponding to fifty one thousand.

  • xf:double('15.25') returns the double value corresponding to fifteen and a quarter.

  • xf:double('51D1') returns the error value, since the use of the letter "D" is prohibited in the constructor for the double type.

3.3 Operators on Numeric Values

The arguments and return types for the arithmetic operators are the basic numeric types: decimal, float, and double and types derived from them. For simplicity, each operator is defined to operate on operands of the same datatype and to return the same datatype. If the two operands are not of the same datatype, one operand is promoted to be the type of the other operand.

The type promotion scheme includes only two rules:

  1. A derived type may be promoted its base type.

  2. decimal may be promoted to float, and float may be promoted to double.

The result type of operations depends on their argument datatypes and is defined in the following table:

OperatorReturns
op:operation(decimal, decimal)decimal
op:operation(float, float)float
op:operation(double, double)double
op:operation(decimal)decimal
op:operation(float)float
op:operation(double)double

These rules define any operation on any pair of arithmetic types. Consider the following example:

op:operation(int, double) => op:operation(double, double)

For this operation, int must be converted to double. This can be done, since by the rules above: int can be promoted to integer, integer can be promoted to decimal, decimal can be promoted to float, and float can be promoted to double. As far as possible, the promotions should be done in a single step. Specifically, when a decimal is promoted to a double, it must not be converted to a float and then to double as this will lose precision.

As another example, a user may define height as a derived type of integer with a minimum value of 20 and a maximum value of 100. He may then derive oddHeight using a pattern to restrict the value to odd integers.

op:operation(oddHeight, 2) => op:operation(decimal, decimal)

oddHeight is first promoted to it's base type height. height is promoted to its base type integer and integer to it's base type decimal.

[Issue 72: Effects of overflow and underflow unspecified]

Finally, consider some examples involving special IEEE 754 numerics.

  1. If either argument is "NaN", the result is "NaN".

  2. If neither argument is "NaN", but either argument is "INF", the result is "INF".

  3. If neither argument is "NaN" or "INF", but either argument is "-INF", the result is "-INF".

Note: In the case of multiplication and division, "INF" may become "-INF", and vice versa, as appropriate.

The functions op:numeric-add, op:numeric-subtract, op:numeric-multiply, op:numeric-divide and op:numeric-mod are each defined for three pairs of numeric operands of the same type: decimal, float and double. The functions op:numeric-unary-plus and op:numeric-unary-minus are defined for a single operand of the same three numeric types.

3.3.1 op:numeric-add

op:numeric-add(numeric $operand1, numeric $operand2) => numeric

Backs up the "+" operator and returns the arithmetic sum of its operands: ($operand1 + $operand2).

3.3.2 op:numeric-subtract

op:numeric-subtract(numeric $operand1, numeric $operand2) => numeric

Backs up the "-" operator and returns the arithmetic difference of its operands: ($operand1 - $operand2).

3.3.3 op:numeric-multiply

op:numeric-multiply(numeric $operand1, numeric $operand2) => numeric

Backs up the "*" operator and returns the arithmetic product of its operands: ($operand1 * $operand2).

3.3.4 op:numeric-divide

op:numeric-divide(numeric $operand1, numeric $operand2) => numeric

Backs up the "div" operator and returns the arithmetic quotient of its operands: ($operand1 div $operand2).

3.3.5 op:numeric-mod

op:numeric-mod(numeric $operand1, numeric $operand2) => numeric

Backs up the "mod" operator and returns the remainder after dividing the first operand by the second operand: ($operand1 mod $operand2). The result is of the same type as the operands after type promotion. The following rules apply:

  • If either operand is NaN, the result is NaN.

  • If the dividend is an infinity, or the divisor is a zero, or both, the result is NaN.

  • If not NaN, the sign of the result equals the sign of the dividend.

  • If the dividend is finite and the divisor is an infinity, the result equals the dividend.

  • If the dividend is a zero and the divisor is finite, the result is the same as the dividend.

  • In the remaining cases, where neither an infinity, nor a zero, nor NaN is involved, the float or double remainder r from a dividend n and a divisor d is defined by the mathematical relation r = n .(d * q) where q is an integer that is negative only if n/d is negative and positive only if n/d is positive, and whose magnitude is as large as possible without exceeding the magnitude of the true mathematical quotient of n and d. This is truncating division, analogous to integer division, not [IEEE 754-1985] rounding division.

Evaluation of a floating-point mod never throws a run-time exception, even if the right-hand operand is zero. Overflow, underflow, or loss of precision cannot occur.

3.3.5.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.

3.3.6 op:numeric-unary-plus

op:numeric-unary-plus(numeric $operand) => numeric

Backs up the unary "+" operator and returns its operand with the sign unchanged: (+ $operand). Semantically, this operation performs no operation.

3.3.7 op:numeric-unary-minus

op:numeric-unary-minus(numeric $operand) => numeric

Backs up the unary "-" operator and returns its operand with the sign reversed: (- $operand). If $operand is positive, its negative is returned; if it it is negative, its positive is returned.

3.4 Comparisons of Numeric Values

We define 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. Each comparison operator returns a boolean value. If either, or both, operands are "NaN", false is returned.

[Issue 113: Need more complete numeric comparison semantics]

3.4.1 op:numeric-equal

op:numeric-equal(numeric $operand1, numeric $operand2) => boolean

Returns true if and only if $operand1 is exactly equal to $operand2. This function backs up the "eq" and "ne" operators on numeric values.

3.4.2 op:numeric-less-than

op:numeric-less-than(numeric $operand1, numeric $operand2) => boolean

Returns true if and only if $operand1 is less than $operand2. This function backs up the "lt" and "ge" operators on numeric values.

3.4.3 op:numeric-greater-than

op:numeric-greater-than(numeric $operand1, numeric $operand2) => boolean

Returns true if and only if $operand1 is greater than $operand2. This function backs up the "gt" and "le" operators on numeric values.

3.5 Functions on Numeric Values

The following functions are defined on these numeric types. Each function returns an integer except:

  • If the argument is the empty sequence, the empty sequence is returned.

  • If the argument is "NaN", "NaN" is returned.

[Issue 79: How many digits of precision (etc.) are returned from certain functions?]

[Issue 142: Should floor ceiling and round return the same type as their argument? ]

3.5.1 xf:floor

xf:floor(double? $srcval) => integer?

Returns the largest (closest to positive infinity) integer that is not greater than the value of $srcval. If the argument is the empty sequence, returns the empty sequence.

3.5.1.1 Examples
  • xf:floor(10.5) returns 10.

  • xf:floor(-10.5) returns -11.

3.5.2 xf:ceiling

xf:ceiling(double? $srcval) => integer?

Returns the smallest (closest to negative infinity) number that is not smaller than the value of $srcvaland that is an integer. If the argument is the empty sequnce, returns the empty sequence.

3.5.2.1 Examples
  • xf:ceiling(10.5) returns 11.

  • xf:ceiling(-10.5) returns -10.

3.5.3 xf:round

xf:round(double? $srcval) => integer?

Returns the number that is closest to the argument and that is an integer. More formally, round(x) produces the same result as floor(x+0.5). These semantics are consistent with Java's semantics. If there are two such numbers, then the one that is closest to positive infinity is returned. If the argument is NaN, then NaN is returned. 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. If the argument is the empty sequnce, returns the empty sequence.

3.5.3.1 Examples
  • xf:round(2.5) returns 3.

  • xf:round(2.4999) returns 2.

  • xf:round(-2.5) returns -2 (not the possible alternative, -3).

4 Constructors and Functions on Strings

This section discusses functions and operators on the [XML Schema Part 2: Datatypes] string datatype and the datatypes derived from string.

4.1 String Types

The operators described in this section are defined on the following string types.

string
normalizedString
token
language
NMTOKEN
Name
NCName
ID
IDREF
ENTITY

They also apply to user-defined types derived by restriction from these types.

4.2 String Constructors

The following constructors are defined on string types. Each constructor takes a single string literal as argument.

ConstructorMeaning
xf:string Produces a string value by parsing and interpreting a supplied string.
xf:normalizedString Produces a normalizedString — the XML Schema datatype — value by parsing and interpreting a string
xf:token Produces a token value by parsing and interpreting a string.
xf:language Produces a language value by parsing and interpreting a string.
xf:Name Produces a Name value by parsing and interpreting a string.
xf:NMTOKEN Produces an NMTOKEN value by parsing and interpreting a string.
xf:NCName Produces an NCName value by parsing and interpreting a string.
xf:ID Produces an ID value by parsing and interpreting a string.
xf:IDREF Produces an IDREF value by parsing and interpreting a string.
xf:ENTITY Produces an ENTITY value by parsing and interpreting a string.

[Issue 14: Some function signatures are unclear about argument types]

4.2.1 xf:string

xf:string(string $srcval) => string

Returns a string value that is the value of $srcval. The more general function 2.3 xf:string returns the string value for several kinds of input arguments. If the input argument is a string it just returns the argument string. Thus, this constructor can be correctly perceived as a "no-op", but is included for the sake of orthogonality.

4.2.1.1 Examples
  • xf:string('abc') returns "abc".

  • If the context of an XML document, xf:string('Jéro&#x0302;me') returns "Jérôme". (The "&#x0302;" is the numeric code reference for the Unicode character U+0302, called "Combining Circumflex Accent". It is represented here with a numeric character reference that must be expanded by the XML parser; the constructors do not search for or replace numeric character references.)

    Note:

    The preceding semantic is correct if and only if this document requires the use of Unicode Normalization Form C (NFC) semantics for this constructor. [Character Model for the World Wide Web 1.0] requires normalization following certain operations, so it may be appropriate to mandate it here, too.

4.2.2 xf:normalizedString

xf:normalizedString(string $srcval) => normalizedString

Returns a normalizedString — the XML Schema datatype — value that is the value of $srcval. Every character contained in $srcval that is a line feed (#xA) is removed from the returned value.

If the argument string passed to a constructor is not a valid value in the lexical space of normalizedString as specified in [XML Schema Part 2: Datatypes], then the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model]. Note that the argument to construct a normalizedString cannot contain the carriage return (#xD) or the tab (#x9) character.

4.2.2.1 Examples
  • xf:normalizedString('abc') returns "abc".

  • In the context of an XML document, xf:normalizedString('ab&#xA;cd') returns "abcd". (The "&#xA;" is a numeric character reference that must be expanded by the XML parser.)

  • In the context of an XML document, xf:normalizedString('ab&#xD;cd') returns the error value. (The "&#xD;" is a numeric character reference that must be expanded by the XML parser.)

4.2.3 xf:token

xf:token(string $srcval) => token

Returns a token value that is the value of $srcval. Note that the argument to construct a token must not contain the line feed (#xA) nor tab (#x9) characters, have no leading or trailing spaces (#x20), and must have no internal sequences of two or more spaces. If the argument string passed to a constructor results in an error, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

4.2.4 xf:language

xf:language(string $srcval) => language

Returns a language value that is the value of $srcval. Note that the value of $srcval to construct a value of type language must be a valid language identifier as defined in the language identification section of [XML 1.0 Recommendation (Second Edition)]. If the argument string passed to a constructor results in an error (for example, xyx is not a valid language identifier), the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

4.2.5 xf:Name

xf:Name(string $srcval) => Name

Returns a Name value that is the value of $srcval. Note that the value of $srcval to construct a value of type Name must match the Name production of [XML 1.0 Recommendation (Second Edition)]. If the argument string passed to a constructor results in an error, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

4.2.6 xf:NMTOKEN

xf:NMTOKEN(string $srcval) => NMTOKEN

Returns an NMTOKEN value that is the value of $srcval. Note that the value of $srcval to construct a value of type NMTOKEN must match the Nmtoken production of [XML 1.0 Recommendation (Second Edition)]. If the argument string passed to a constructor results in an error, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

4.2.7 xf:NCName

xf:NCName(string $srcval) => NCName

Returns an NCName value that is the value of $srcval. Note that the value of $srcval to construct a value of type NCName must match the NCName production of [XML 1.0 Recommendation (Second Edition)]. If the argument string passed to a constructor results in an error, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

4.2.8 xf:ID

xf:ID(string $srcval) => ID

Returns an ID value that is the value of $srcval. Note that the value of $srcval to construct a value of type ID must match the NCName production of [XML 1.0 Recommendation (Second Edition)]. If the argument string passed to a constructor results in an error, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

The semantic correctness of ID values (that they must be unique within a given document) is not enforced by the xf:ID function.

4.2.9 xf:IDREF

xf:IDREF(string $srcval) => IDREF

Returns an IDREF value that is the value of $srcval. Note that the value of $srcval to construct a value of type IDREF must match the NCName production of [XML 1.0 Recommendation (Second Edition)]. If the argument string passed to a constructor results in an error, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

The semantic correctness of IDREF values (that there must be a corresponding ID value in the same document) is not enforced by the xf:IDREF function.

4.2.10 xf:ENTITY

xf:ENTITY(string $srcval) => ENTITY

Returns an ENTITY value that is the value of $srcval. Note that the value of $srcval to construct a value of type ENTITY must match the NCName production of [XML 1.0 Recommendation (Second Edition)]. If the argument string passed to a constructor results in an error, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

4.3 Equality and Comparison of Strings

The [Character Model for the World Wide Web 1.0] discusses the fact that strings from a particular character set may need to be collated (sorted) differently for different applications. Thus, the collation needs to be taken into account when comparing strings in any context. Several functions in this and the following section make use of a collation.

In this document, we assume that collations are named and the collation name, specified as a literal, is used as an argument to the comparison function. This document will also define the manner in which a default collation is determined, allowing the collation argument to be optional in the functions that allow it.

The value of the xml:lang attribute cannot be used to identify the default collation because such information is localized and may not be the same for both operands.

[Issue 44: Collations: URIs and URI references or short names?]

[Issue 70: How are "default" collations determined?]

Some collations can be "tailored" for various purposes. See [Unicode Collation Algorithm]. This document does not discuss tailoring. Instead, we assume that the collation argument to the various functions below is a tailored and named collation.

A specially named collation provides the ability to compare strings based on codepoint values.

A user who wishes to preserve the XPath 1.0 semantics of "<" and ">" can define a collation that converts each string to a number and then compares them numerically.

Collations can also indicate that some characters that are rendered differently are, in fact equal for collation purpose (e.g., "uve" and "uwe" are considered equivalent in some European languages). Thus, strings can be compared character-by-character or in a logical manner based on the collation.

The [Character Model for the World Wide Web 1.0] recommends that all strings be subjected to Unicode normalization early and, thus, string comparisons need only be defined on normalized strings. If this is not the case, then we may also want to compare unnormalized strings based on their normalized representations.

FunctionMeaningSource
xf:compare Compares two character strings; a collation may optionally be specifiedXSLT 2.0, Req. 2.13 (Could)

[Issue 73: Is a "between" function needed?]

4.3.1 xf:compare

xf:compare(string? $comparand1, string? $comparand2) => integer?
xf:compare(string? $comparand1, string? $comparand2, anyURI $collationLiteral) => integer?

Returns -1, 0, or 1, depending on whether the value of the $comparand1 is respectively less than, equal to, or greater than the value of $comparand2, according to the rules of the collation that is used.

If $collationLiteral is specified, then the value of $collationLiteral must identify a collation that is supported in the environment in which the function is invoked. Either an absolute URI or a relative URI may be specified. The collation identified by $collationLiteral, while effectively based on the Unicode Collation Algorithm, has implementation-defined semantics.

If no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

If the value of $comparand2 begins with a string that is equal to the value of $comparand1 (according to the collation that is used) and has additional characters following that beginning string, then the result is -1. If the value of $comparand1 begins with a string that is equal to the value of $comparand2 (according to the collation that is used) and has additional characters following that beginning string, then the result is 1.

If either argument is the empty sequence, the result is the empty sequence.

This function backs up the "eq", "ne', "gt", "lt", "le" and "ge" operators on string values.

[Issue 141: Does string equality use the codepoint collation or the default collation?]

4.3.1.1 Examples
  • xf:compare('abc', 'abc') returns 0.

  • xf: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.)

  • xf:compare('Strasse', 'Straße', anyURI('deutsch')) returns 0 if and only 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.)

  • xf:compare('Strassen', 'Straße') returns 1 if and only if the default collation includes provisions that equate "ss" and the (German) character "ß" ("sharp-s"). (Since the value of $comparand1 has an additional character, an "n", following the string that is equal to "Straße", it is greater than the value of $comparand2.)

4.4 Functions on String Values

The following functions are defined on these string types. Several of these function use a collation. See 4.3 Equality and Comparison of Strings for a discussion of collations.

FunctionMeaningSource
xf:concat Concatenates two or more character strings. XPath 1.0
xf:starts-with Indicates whether the value of one string begins with the characters of the value of another string. XPath 1.0
xf:ends-with Indicates whether the value of one string ends with the characters of the value of another string. XPath 1.0
xf:contains Indicates whether the value of one string contains the characters of the value of another string. A collation may optionally be specified. XPath 1.0
xf:substring Returns a string located at a specified place in the value of a string. XPath 1.0
xf:string-length Returns the length of the argument. XPath 1.0
xf:substring-before Returns the characters of one string that precede in that string the characters in the value of another string. A collation may optionally be specified. XPath 1.0
xf:substring-after Returns the characters of one string that precede in that string the characters in the value of another string. A collation may optionally be specified. XPath 1.0
xf:normalize-space Returns the whitespace-normalized value of the argument.XPath 1.0
xf:normalize-unicode Returns the normalized value of the first argument in the normalization form specified by the second argument.XPath 2.0 Req 2.9 (Should)
xf:upper-case Returns the upper-cased value of the argument. XPath 2.0 Req 2.4.3 (Should)
xf:lower-case Returns the lower-cased value of the argument. XPath 2.0 Req 2.4.3 (Should)
xf:translate Returns the first argument string with occurrences of characters in the second argument replaced by the character at the corresponding position in the third string. XPath 1.0
xf:string-pad Returns a string composed of as many copies of its first argument as specified in its second argument.XPath 2.0 Req 2.4.2, 4.4 (Should)
xf:match Returns a sequence of integers indicating the positions in the value of the first argument that are matched by the regular expression that is the value of the second argument. XPath 2.0 Req 3. (Must)
xf:replace Returns the first argument with every substring matched by the second argument replaced by the value of the third argument. XPath 2.0 Req 2.4.1. (Should)

[Issue 23: "Returns a copy" is not appropriate wording]

[Issue 21: What is the precise type returned by each function?]

[Issue 37: Linguistic contains required?]

[Issue 94: Must allow searching for words near other words. ]

[Issue 143: Should we add a tokenize function to break a string into tokens?]

4.4.1 Usage Notes

Note that the resulting string after operations such as concatenation or substring must be normalized. See [Character Model for the World Wide Web 1.0].

[Issue 108: Should strings always be returned in Unicode normalized form?]

Note also that when the above operators and functions are applied to datatypes derived from string, they are guaranteeed to return legal strings, but they may not return legal value for the particular subtype to which they were applied.

[Issue 20: Many uses of "character" should be "codepoint"]

4.4.2 xf:concat

xf:concat() => string
xf:concat(string? $op1) => string
xf:concat(string? $op1, string? $op2, ...) => string

Accepts zero or more strings as arguments. Returns the string that is the concatenation of the values of its arguments. The resulting string might not be normalized in any Unicode or W3C normalization. If called with no arguments, returns the zero-length string. If any of the arguments is the empty sequence it is treated as the zero-length string.

The concat() function is specified to allow an arbitrary number of string arguments that are concatenated together. This capability is retained for compatibility with [XPath 1.0] and is the only function specified in this document that has that characteristic.

[Issue 144: Should the concat function accept sequences as arguments? ]

4.4.2.1 Examples
  • xf:concat('abc', 'def') returns "abcdef".

  • xf:concat('abc') returns abc.

  • xf:concat('abc', 'def', 'ghi', 'jkl', 'mno') returns "abcdefghijklmno".

  • xf:concat(()) returns "".

4.4.3 xf:starts-with

xf:starts-with(string? $operand1, string? $operand2) => boolean?
xf:starts-with(string? $operand1, string? $operand2, anyURI $collationLiteral) => boolean?

Returns a boolean indicating whether or not the value of $operand1 starts with a string that is equal to the value of $operand2 according to the collation that is used.

If the value of $operand2 is the zero-length string, then the function returns true. If the value of $operand1 is the zero-length string and the value of $operand2 is not the zero-length string, then the function returns false.

If the value of $operand1 or $operand2 is the empty sequence, the empty sequence is returned.

If $collationLiteral is specified, then the value of $collationLiteral must identify a collation that is supported in the environment in which the function is invoked. Either an absolute URI or a relative URI may be specified. The collation identified by $collationLiteral, while effectively based on the Unicode Collation Algorithm, has implementation-defined semantics.

If no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

4.4.3.1 Examples
  • xf:starts-with("goldenrod", "gold") returns true.

  • xf:starts-with("goldenrod", "") returns true.

  • xf:starts-with("goldenrod", "rod") returns false.

4.4.4 xf:ends-with

xf:ends-with(string? $operand1, string? $operand2) => boolean?
xf:ends-with(string? $operand1, string? $operand2, anyURI $collationLiteral) => boolean?

Returns a boolean indicating whether or not the value of $operand1 ends with a string that is equal to the value of $operand2 according to the specified collation.

If the value of $operand2 is the zero-length string, then the function returns true. If the value of $operand1 is the zero-length string and the value of $operand2 is not the zero-length string, then the function returns false.

If the value of $operand1 or $operand2 is the empty sequence, the empty sequence is returned.

If $collationLiteral is specified, then the value of $collationLiteral must identify a collation that is supported in the environment in which the function is invoked. Either an absolute URI or a relative URI may be specified. The collation identified by $collationLiteral, while effectively based on the Unicode Collation Algorithm, has implementation-defined semantics.

If no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

4.4.4.1 Examples
  • xf:ends-with("goldenrod","rod") returns true.

  • xf:ends-with("", "rod") returns false.

4.4.5 xf:contains

xf:contains(string? $operand1, string? $operand2) => boolean?
xf:contains(string? $operand1, string? $operand2, anyURI $collationLiteral) => boolean?

Returns a boolean indicating whether or not the value of $operand1 contains (at the beginning, at the end, or anywhere within) a string equal to the value of $operand1 according to the collation that is used.

If the value of $operand2 is the zero-length string, then the function returns true. If the value of $operand1 is the zero-length string and the value of $operand2 is not the zero-length string, then the function returns false.

If the value of $operand1 or $operand2 is the empty sequence, the empty sequence is returned.

If $collationLiteral is specified, then the value of $collationLiteral must identify a collation that is supported in the environment in which the function is invoked. Either an absolute URI or a relative URI may be specified. The collation identified by $collationLiteral, while effectively based on the Unicode Collation Algorithm, has implementation-defined semantics.

If no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

4.4.6 xf:substring

xf:substring(string? $sourceString, decimal? $startingLoc) => string?
xf:substring(string? $sourceString, decimal? $startingLoc, decimal? $length) => string?

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. More specifically, returns the characters in $sourceString whose position $p obeys:

xf:round($startingLoc) <= $p < xf:round($startingLoc + $length)

If $length is not specified, the substring identifies characters to the end of $sourceString.

If $length is greater than the number of characters in the value of $sourceString following $startingLoc, the substring identifies characters to the end of $sourceString.

The first character of a string is located at position 1 (not position 0).

If the value of $startingLoc is negative or greater than the length of $sourceString an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model] is returned.

If the value of any of the three parameters is the empty sequence, the empty sequence is returned.

4.4.6.1 Examples
  • xf:substring("motor car", 6) returns " car".

  • xf:substring("metadata", 4, 3) returns "ada".

4.4.7 xf:string-length

xf:string-length(string? $srcval) => integer?

Returns an integer equal to the length in characters of the value of $srcval. If the value of $srcval is the empty sequence, the empty sequence is returned.

4.4.7.1 Examples
  • xf:string-length("first we kill the lawyers") returns 25.

4.4.8 xf:substring-before

xf:substring-before(string? $operand1, string? $operand2) => string?
xf:substring-before(string? $operand1, string? $operand2, anyURI $collationLiteral) => string?

Returns the substring of the value of $operand1 that precedes in the value of $operand1 the first occurrence of a string that is equal to the value of $operand2 according to the collation that is used.

If the value of $operand2 is the zero-length string, then the function returns the value of $operand1. If the value of $operand1 is the zero-length string and the value of $operand2 is the zero-length string, then the function returns the zero-length string.

If the value of $operand1 does not contain a string that is equal to the value of $operand2, then the function returns the zero-length string.

If the value of $operand1 or $operand2 is the empty sequence, returns the empty sequence.

If $collationLiteral is specified, then the value of $collationLiteral must identify a collation that is supported in the environment in which the function is invoked. Either an absolute URI or a relative URI may be specified. The collation identified by $collationLiteral, while effectively based on the Unicode Collation Algorithm, has implementation-defined semantics.

If no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

4.4.8.1 Examples
  • xf:substring-before("abcdabcd","d") returns "abc".

  • xf:substring-before("abcd","") returns "abcd".

4.4.9 xf:substring-after

xf:substring-after(string? $operand1, string? $operand2) => string?
xf:substring-after(string? $operand1, string? $operand2, anyURI $collationLiteral) => string?

Returns the substring of the value of $operand1 that follows in the value of $operand1 the first occurrence of a string that is equal to the value of $operand2 according to the collation that is used.

If the value of $operand2 is the zero-length string, then the function returns the value of $operand1. If the value of $operand1 is the zero-length string and the value of $operand2 is the zero-length string, then the function returns the zero-length string.

If the value of $operand1 does not contain a string that is equal to the value of $operand2, then the function returns the zero-length string.

If the value of $operand1 or $operand2 is the empty sequence, returns the empty sequence.

If $collationLiteral is specified, then the value of $collationLiteral must identify a collation that is supported in the environment in which the function is invoked. Either an absolute URI or a relative URI may be specified. The collation identified by $collationLiteral, while effectively based on the Unicode Collation Algorithm, has implementation-defined semantics.

If no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

4.4.9.1 Examples
  • xf:substring-after("abcdabcd","d") returns "abcd".

4.4.10 xf:normalize-space

xf:normalize-space(string? $srcval) => string?

Returns the value of the string argument with whitespace normalized by stripping leading and trailing whitespace and replacing sequences of more than one whitespace character by a single space. If the value of $srcval is the empty sequence, returns the empty sequence.

4.4.10.1 Examples
  • xf:normalize-space(" hello world ") returns "hello world".

4.4.11 xf:normalize-unicode

xf:normalize-unicode(string? $srcval) => string?
xf:normalize-unicode(string? $srcval, string $normalizationForm) => string?

Returns the value of $srcval 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 $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 $srcval 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 $srcval 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 $srcval 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 $srcval in Unicode Normalization Form KD (NFKD).

  • If the effective value of $normalizationForm is "W3C", then the value returned by the function is the value of $srcval is the fully normalized form. See [Character Model for the World Wide Web 1.0].

  • If the effective value of $normalizationForm is the zero-length string then no normalization is performed and $srcval is returned.

  • Implementations may choose to support other normalization forms in addition to the normalization forms discussed above

If the effective value of the $normalizationForm is other than one of the values supported by the implementation, returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

If the value of $srcval is the empty sequence, returns the empty sequence.

4.4.12 xf:upper-case

xf:upper-case(string? $srcval) => string?

Returns the value of $srcval after translating every lower-case letter to its upper-case correspondent. Every lower-case letter that does not have an upper-case correspondent, and every character that is not a lower-case letter, is included in the returned value in its original form.

A "lower-case letter" is a character whose Unicode General Category class includes "Ll". The corresponding upper-case letter is determined using [Unicode Case Mappings].

If the value of $srcval is the empty sequence, returns the empty sequence.

4.4.12.1 Examples
  • xf:upper-case("abCd0") returns "ABCD0".

4.4.13 xf:lower-case

xf:lower-case(string? $srcval) => string?

Returns the value of $srcval after translating every upper-case letter to its lower-case correspondent. Every upper-case letter that does not have a lower-case correspondent, and every character that is not an upper-case letter, is included in the output in its original form.

An "upper-case letter" is a character whose Unicode General Category class includes "Lu". The corresponding lower-case letter is determined using [Unicode Case Mappings].

If the value of $srcval is the empty sequence, returns the empty sequence.

4.4.13.1 Examples
  • xf:lower-case("ABc!D") returns "abc!d".

4.4.14 xf:translate

xf:translate(string? $srcval, string? $mapString, string? $transString) => string?

Returns the value of $srcval modified so that every character in the value of $srcval 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.

Every character in the value of $srcval that does not appear in the value of $mapString is unchanged.

Every character in the value of $srcval 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 the value of $srcval or $mapString or $transString is the empty sequence, returns the empty sequence.

4.4.14.1 Examples
  • xf:translate("abcdabc", "abc", "AB") returns "ABdAB".

4.4.15 xf:string-pad

xf:string-pad(string? $padString, decimal? $padCount) => string?

Returns a string consisting of $padCount copies of $padString concatenated together. Returns the empty string if $padCount is zero.

If the value of $padCount is less than zero, the function returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

If the value of $padString or $padCount is the empty sequence, returns the empty sequence.

4.4.15.1 Examples
  • xf:string-pad("XMLQuery", 2) returns "XMLQueryXMLQuery".

  • xf:string-pad(" ", 4) returns a string containing four spaces.

  • xf:string-pad(" ", 0) returns the zero-length string.

  • xf:string-pad(" ", -3) returns error.

4.4.16 xf:match

xf:match(string? $srcval, string? $regexp) => integer*

Returns a list of integers that identify the offset of the location within the value of $srcval that is matched by the regular expression that is the value of $regexp.

If there is no substring of $srcval that matches the regular expression, the empty sequence is returned. Otherwise, a sequence of two integers is returned: the first integer is the position of the start of the substring and the second integer is the length of the substring that matches.

If the value of $srcval or $regexp is the empty sequence, returns the empty sequence.

Note:

What should be done about the distinction between maximal and minimal matches?

The regular expression in the value of $regexp uses the syntax of regular expressions specified in Appendix F of [XML Schema Part 2: Datatypes].

Comparisons of characters and character strings are compared on a character by character basis using the Unicode values for each character.

[Issue 74: Is a "match-exact()" function needed?]

[Issue 75: The semantics of match() and replace() are incompletely specified]

[Issue 81: What are the precise semantics of regular expressions?]

4.4.16.1 Examples
  • match("abcabc", "[ab]") returns {1, 2}.

  • match("abcabc", "[xyz]") returns the empty sequence.

4.4.17 xf:replace

xf:replace(string? $srcval, string? $regexp, string? $repval) => string?

Returns the value of $srcval in which every substring of the value of $srcval that is matched by the regular expression that is the value of $regexp, has been replaced by a copy of the value of $repval.

Ordinary regular expression semantics are used. Among other characteristics, if the value of $regexp is an ordinary character string without any of the "special characters" that give regular expressions their semantics, then the phrase "matched by the regular expression" is equivalent in meaning to "equal to the string".

The value of $repval may use the standard regular expression syntax of "$N" (where N is some integer) to represent the N-th part of the matched pattern indicated by parentheses in the value of $regexp.

Comparisons of characters and character strings are compared on a character by character basis using the Unicode values for each character.

If the value of $srcval or $regexp or $repval is the empty sequence, returns the empty sequence.

[Issue 75: The semantics of match() and replace() are incompletely specified]

4.4.17.1 Examples
  • replace("abcabc", "[ab]", "x") returns "xxcxxc".

  • replace("aFOOa aBARa", "a(.*)a", "b$1b") would retain the characters matched by the first parenthesized component ($1) of the regular expression and replace the remaining portion as indicated, returning "bFOOb bBARb".

5 Constructors, Functions and Operators on Booleans

This section discusses operators on the [XML Schema Part 2: Datatypes] boolean datatype.

5.1 Boolean Constructors

The following constructors are defined on the boolean type.

ConstructorMeaningSource
xf:true booleanXPath 1.0
xf:false booleanXPath 1.0
xf:boolean-from-string boolean

5.1.1 xf:true

xf:true() => boolean

Returns the boolean value true.

5.1.1.1 Examples
  • xf:true() returns true.

5.1.2 xf:false

xf:false() => boolean

Returns the boolean value false.

5.1.2.1 Examples
  • xf:false() returns false.

5.1.3 xf:boolean-from-string

xf:boolean-from-string(string $srcval) => boolean

Takes a single string literal as argument. Leading and trailing whitespace, if present, is stripped from the literal and it is converted to upper case before the value is constructed. This is it's effective value. If the effective value of $srcval is "TRUE", then this constructor returns the boolean value true; if the effective value of $srcval is "FALSE", then this constructor returns the boolean value false.

If the effective value of $srcval is any value other than "TRUE" or "FALSE", the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

[Issue 157: boolean-from-string should accept only 1, 0, true, false.]

5.1.3.1 Examples
  • xf:boolean-from-string("True") returns true.

  • xf:boolean-from-string("fAlSe") returns false.

5.2 Operators on Boolean Values

The following operators are defined on boolean values:

5.2.1 op:boolean-equal

op:boolean-equal(boolean? $value1, boolean? $value2) => boolean?

The arguments and return type are all boolean. The result is true if both arguments are true or if both arguments are false. The result is false if one of the arguments is true and the other argument is false. Otherwise, returns the empty sequence.

This function backs up the "eq" operator on boolean values.

5.3 Functions on Boolean Values

The following functions are defined on boolean values:

FunctionMeaningSource
xf:not Inverts the boolean value of the argument. A () argument returns true.XPath 1.0
op:boolean-less-than A less-than operator for boolean vales: false is less-than true.XPath 1.0
op:boolean-greater-than A greater-than operator for boolean vales: true is greater-than false.XPath 1.0

5.3.1 xf:not

xf:not(item* $srcval) => boolean

$srcval is first reduced to an effective boolean value by applying the following rules:

  • If $srcval is the empty sequence, its effective boolean value is false.

  • If $srcval is a single boolean value, it serves as its own effective boolean value.

  • If $srcval is a sequence that contains at least one node, its effective boolean value is true.

  • In any other case, a type exception is invoked.

Returns true if the effective boolean value is false, and false if the effective boolean value is true.

5.3.1.1 Examples
  • xf:not(xf:true()) returns false.

5.3.2 op:boolean-less-than

op:boolean-less-than(boolean $srcval1, boolean $srcval2) => boolean

Returns true if $srcval1 is false and $srcval2 is true. Otherwise returns false.

This function backs up the "lt" operator on boolean values.

5.3.3 op:boolean-greater-than

op:boolean-greater-than(boolean $srcval1, boolean $srcval2) => boolean

Returns true if $srcval1 is true and $srcval2 is false. Otherwise returns false.

This function backs up the "gt" operator on boolean values.

6 Constructors, Functions, and Operators on Durations, Dates and Times

This section discusses operations on the [XML Schema Part 2: Datatypes] duration, date and time types. In addition, it discusses operations on two subtypes of the duration datatype that are defined in 6.2 Two Totally Ordered Subtypes of Duration.

[Issue 47: Should the design of the date (and time) functions be such that they could be generalized to full I18N support and what level of I18N support should be included in version 1.0? ]

[Issue 109: Calendar context allows for non-Gregorian calendars]

[Issue 136: Should we allow casting a date/time from one timezone to another?]

6.1 Duration, Date and Time Types

The operators described in this section are defined on the following duration date and time types:

  • duration

  • dateTime

  • date

  • time

  • gYearMonth

  • gYear

  • gMonthDay

  • gMonth

  • gDay

In addition, they are defined on the 6.2 Two Totally Ordered Subtypes of Duration:

  • yearMonthDuration

  • dayTimeDuration

CONFORMANCE NOTE

For a number of the above datatypes [XML Schema Part 2: Datatypes] extends the basic [ISO 8601] lexical representations, such as YYYY-MM-DDThh:mm:ss.s for dateTime, by allowing more than four digits to represent the year field -- no maximum is specified -- and an unlimited number of digits for fractional seconds.

For this specification, all minimally conforming processors must support year values with a minimum of 4 digits (i.e., YYYY) and a minimum fractional second precision of 100 nanoseconds or seven digits (i.e. s.sssssss). However, conforming processors may set larger application-defined limits on the maximum number of digits they support in these two situations, in which case those application-defined maximum numbers must be clearly documented.

[Issue 159: For fractional seconds precision use 6 digits to match SQL TIMESTAMP.]

6.2 Two Totally Ordered Subtypes of Duration

These two totally ordered subtypes of duration are defined in this specification using the mechanisms described in [XML Schema Part 2: Datatypes] for defining user-defined types. They are available in the namespace http://www.w3.org/2002/04/xquery-functions.

The W3C XML Query Working Group has requested the W3C XML Schema Working Group that these two subtypes of duration be included in the built-in datatypes described in [XML Schema Part 2: Datatypes]. If the W3C XML Schema Working Group agrees to this request, these two datatypes will be removed from the above name space and moved into the XML Schema namespace http://www.w3.org/2001/XMLSchema.

6.2.1 yearMonthDuration

[Definition:] yearMonthDuration is derived from duration by restricting its lexical representation to contain only the year and month components. The value space of yearMonthDuration is the set of integer month values. The year and month components of yearMonthDuration correspond to the Gregorian year and month components defined in section 5.5.3.2 of [ISO 8601], respectively.

yearMonthDuration is derived from duration as follows:

<simpleType name='yearMonthDuration'>
    <restriction base='duration'>
        <xsd:pattern value="[-]?P\p{Nd}+(Y(\p{Nd}+M)?|M)"/>
    </restriction>
</simpleType>
6.2.1.1 Lexical representation

The lexical representation for 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 positive 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 yearMonthDuration of 1 year, 2 months, one would write: P1Y2M. One could also indicate a 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, 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 all allowed; P-1347M is not allowed although -P1347M is allowed. P1Y2MT is not allowed.

6.2.1.2 Calculating the value from the lexical representation

The value of a yearMonthDuration lexical form is obtained by multiplying the value of the year component by 12 and adding the value of the month component. The value is positive or negative depending on the preceding sign.

6.2.1.3 Canonical representation

The canonical representation of yearMonthDuration restricts the value of the months component to 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 integer number of 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. If the value is 0 months, the canonical form is "P0M".

6.2.1.4 Order relation on yearMonthDuration

Let the function that calculates the value of an yearMonthDuration in the manner described above be called V(d). Then for two yearMonthDuration values x and y, x > y iff V(x) > V(y). The order relation on yearMonthDuration is a total order.

6.2.2 dayTimeDuration

[Definition:] dayTimeDuration is derived from duration by restricting its lexical representation to contain only the day, hour, minute, and second components. The value space of dayTimeDuration is the set of fractional second values. The components of dayTimeDuration correspond to the day, hour, minute and second components defined in Section 5.5.3.2 of [ISO 8601], respectively. dayTimeDuration is derived from duration as follows:

<simpleType name='dayTimeDuration'>
    <restriction base='duration'>
     		 <xsd:pattern value="[-]?P((\p{Nd}D(T\p{Nd}+(H(\p{Nd}+M(\p{Nd}+([.]\p{Nd}+)?S)?)?|M(\p{Nd}+([.]\p{Nd}+)?S)?|(([.]\p{Nd}+)?S)))?)|T\p{Nd}+(H(\p{Nd}+M(\p{Nd}+([.]\p{Nd}+)?S)?)?|M(\p{Nd}+([.]\p{Nd}+)?S)?|(([.]\p{Nd}
+)?S)))"/>
    </restriction>
</simpleType>
6.2.2.1 Lexical representation

The lexical representation for 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 positive integer. Similarly, the value of the seconds component allows an arbitrary positive decimal number. An optional preceding minus sign ('-') is allowed, to indicate a negative duration. If the sign is omitted a positive duration is indicated. 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, 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 all of the time items are absent. The designator 'P' must always be present.

For example, P13D, PT47H and P3DT2H are all allowed. P-1347D is not allowed although -P134D is allowed.

6.2.2.2 Calculating the value of a dayTimeDuration from the lexical representation

The value of a dayTimeDuration lexical form in fractional seconds is obtained by converting the day, hour minutes and seconds value to fractional seconds using the rules 24 hours = 1 day, 60 minutes = 1 hour and 60 seconds = 1 minute.

6.2.2.3 Canonical representation

The canonical representation of dayTimeDuration restricts the value of the hours component to integer values between 0 and 23, both inclusive; the value of the minutes component to integer values between 0 and 59; both inclusive; and the value of the seconds component to decimal valued from 0.0 to 59.999... To convert from a non-canonical representation to the canonical representation, we first calculate the value of the lexical form in fractional seconds in the manner described above. We then calculate the value of the days component in the canonical form by dividing the value by 24*60*60. The remainder is in fractional seconds. The value of the hours component in the canonical form is calculated by dividing this remained by 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 remaineder in fractional seconds is the value of the seconds component in the canonical form. If all the components of the lexical form are zero the canonical form is PT0S.

6.2.2.4 Order relation on dayTimeDuration

Let the function that calculates the value of a dayTimeDuration in the manner described above be called V(d). Then for two dayTimeDuration values x and y, x > y iff V(x) > V(y). The order relation on dayTimeDuration is a total order.

6.3 Duration, Date and Time Constructors

The following constructors are defined on duration, date and time datatypes. Each constructor takes a single string literal as argument. Leading and trailing whitespace, if present, is stripped from the literal before the value is constructed.

ConstructorMeaning
xf:duration Returns a duration type derived by parsing and interpreting a string value.
xf:dateTime Returns a dateTime type derived by parsing and interpreting a string value.
xf:date Returns a date type derived by parsing and interpreting a string value.
xf:time Returns a time type derived by parsing and interpreting a string value.
xf:gYearMonth Returns a gYearMonth type derived by parsing and interpreting a string value.
xf:gYear Returns a gYear type derived by parsing and interpreting a string value.
xf:gMonthDay Returns a gMonthDay type derived by parsing and interpreting a string value.
xf:gMonth Returns a gMonth type derived by parsing and interpreting a string value.
xf:gDay Returns a gDay type derived by parsing and interpreting a string value.

6.3.1 xf:duration

xf:duration(string $srcval) => duration

If the value of $srcval conforms to the lexical representation of a duration as defined in [XML Schema Part 2: Datatypes], the constructor returns the duration corresponding to that representation. Otherwise, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

6.3.1.1 Examples
  • xf:duration("P1Y") returns the duration value corresponding to one year.

  • xf:duration("P1Y2MT2H") returns the duration value corresponding to one year, two months and two hours.

6.3.2 xf:dateTime

xf:dateTime(string $srcval) => dateTime

If the value of $srcval conforms to the lexical representation of a dateTime as defined in [XML Schema Part 2: Datatypes], the constructor returns the dateTime corresponding to that representation. Otherwise, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

6.3.2.1 Examples
  • xf:dateTime("1999-05-31T05:00:00") returns a dateTime value corresponding to the 31st. of May, 1999 at 5:00 AM in an unspecified timezone.

  • xf:dateTime("1999-05-31T13:20:00-05:00") returns a dateTime value corresponding to 1:20 pm on May the 31st, 1999 for a timezone which is 5 hours behind Coordinated Universal Time (UTC).

6.3.3 xf:date

xf:date(string $srcval) => date

If the value of $srcval conforms to the lexical representation of a date as defined in [XML Schema Part 2: Datatypes], the constructor returns the date corresponding to that representation. Otherwise, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

6.3.3.1 Examples
  • xf:date("2001-05-31") returns a date value corresponding to the 31st of May, 2001.

  • xf:date("2001-04-31") returns an error.

6.3.4 xf:time

xf:time(string $srcval) => time

If the value of $srcval conforms to the lexical representation of a time as defined in [XML Schema Part 2: Datatypes], the constructor returns the time corresponding to that representation. Otherwise, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

6.3.4.1 Examples
  • xf:time("11:33:24") returns a time value corresponding to 33 minutes and 24 seconds past 11 O'Clock in an unspecified timezone.

  • xf:time("23:33:24.35-05:00") returns a time value corresponding to 33 minutes and 24.35 seconds past 23 O'Clock for a timezone which is 5 hours behind Coordinated Universal Time (UTC).

6.3.5 xf:gYearMonth

xf:gYearMonth(string $srcval) => gYearMonth

If the value of $srcval conforms to the lexical representation of a gYearMonth as defined in [XML Schema Part 2: Datatypes], the constructor returns the gYearMonth corresponding to that representation. Otherwise, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

6.3.5.1 Examples
  • xf:gYearMonth("2001-4") returns a gYearMonth corresponding to April in the year 2001 in an unspecified timezone.

  • xf:gYearMonth("2001-4Z") returns a gYearMonth corresponding to April in the year 2001 in the Coordinated Universal Time (UTC) timezone.

6.3.6 xf:gYear

xf:gYear(string $srcval) => gYear

If the value of $srcval conforms to the lexical representation of a gYear as defined in [XML Schema Part 2: Datatypes], the constructor returns the gYear corresponding to that representation. Otherwise, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

6.3.6.1 Examples
  • xf:gYear("2001") returns a gYear corresponding the year 2001 in an unspecified timezone.

  • xf:gYear("2001-08:00") returns a gYear corresponding the year 2001 in a timezone that is 8 hours behind Coordinated Universal Time (UTC).

6.3.7 xf:gMonthDay

xf:gMonthDay(string $srcval) => gMonthDay

If the value of $srcval conforms to the lexical representation of a gMonthDay as defined in [XML Schema Part 2: Datatypes], the constructor returns the gMonthDay corresponding to that representation. Otherwise, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

6.3.7.1 Examples
  • xf:gMonthDay("12-25) returns a gMonthDay corresponding to the 25th. of December in an unspecified timezone.

  • xf:gMonthDay("12-25Z") returns a gMonthDay corresponding to the 25th. of December in the Coordinated Universal Time (UTC) timezone.

6.3.8 xf:gMonth

xf:gMonth(string $srcval) => gMonth

If the value of $srcval conforms to the lexical representation of a gMonth as defined in [XML Schema Part 2: Datatypes], the constructor returns the gMonth corresponding to that representation. Otherwise, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

6.3.8.1 Examples
  • xf:gMonth("10") returns a gMonth corresponding to October (the tenth month) in an unspecified timezone.

  • xf:gMonth("10+02:00") returns a gMonth corresponding to October (the tenth month) in a timezone that is 2 hours ahead of Coordinated Universal Time (UTC).

6.3.9 xf:gDay

xf:gDay(string $srcval) => gDay

If the value of $srcval conforms to the lexical representation of a gDay as defined in [XML Schema Part 2: Datatypes], the constructor returns the gDay corresponding to that representation. Otherwise, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

6.3.9.1 Examples
  • xf:gDay("13") returns a gDay corresponding to the thirteenth day in an unspecified month and year in an unspecified timezone.

  • xf:gDay("14+02:30") returns a gDay corresponding to the fourteenth day in an unspecified month and year in a timezone that is 2.5 hours ahead of Coordinated Universal Time (UTC).

6.4 yearMonthDuration and dayTimeDuration Constructors

The following constructors are defined on yearMonthDuration and dayTimeDuration datatypes.

ConstructorMeaning
xf:yearMonthDuration Returns a yearMonthDuration value derived by parsing and interpreting a string value.
xf:yearMonthDuration-from-months Returns a yearMonthDuration value equal to a given number of integer months.
xf:dayTimeDuration Returns a dayTimeDuration value derived by parsing and interpreting a string value.
xf:dayTimeDuration-from-seconds Returns a dayTimeDuration value equal to a given number of decimal seconds.

6.4.1 xf:yearMonthDuration

xf:yearMonthDuration(string $srcval) => yearMonthDuration

If the value of $srcval conforms to the lexical representation of a yearMonthDuration as defined in 6.2.1 yearMonthDuration, the constructor returns the yearMonthDuration corresponding to that representation. Otherwise, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model]. Leading and trailing whitespace, if present, is stripped from the literal before the value is constructed.

6.4.1.1 Examples
  • xf:yearMonthDuration("P3Y") returns the yearMonthDuration value corresponding to three years.

  • xf:yearMonthDuration("P1Y2M") returns the yearMonthDuration value corresponding to one year and two months.

6.4.2 xf:yearMonthDuration-from-months

xf:yearMonthDuration-from-months(integer $srcval) => yearMonthDuration

Returns a yearMonthDuration with value equal to $srcval.

6.4.2.1 Examples
  • xf:yearMonthDuration-from-months(13) returns the yearMonthDuration value corresponding to 1 yearand 1 month.

  • xf:yearMonthDuration-from-months(-29) returns the yearMonthDuration value corresponding to negative 2 years and 5 months.

6.4.3 xf:dayTimeDuration

xf:dayTimeDuration(string $srcval) => dayTimeDuration

If the value of $srcval conforms to the lexical representation of a dayTimeDuration as defined in 6.2.2 dayTimeDuration, the constructor returns the dayTimeDuration corresponding to that representation. Otherwise, the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model]. Leading and trailing whitespace, if present, is stripped from the literal before the value is constructed.

6.4.3.1 Examples
  • xf:dayTimeDuration("P2DT2H") returns a dayTimeDuration value corresponding to 2 days and 2 hours.

  • xf:dayTimeDuration("PT2H20M10.5S") returns a dayTimeDuration value corresponding to 2 hours, 20 minutes and 10.5 seconds.

6.4.4 xf:dayTimeDuration-from-seconds

xf:dayTimeDuration-from-seconds(decimal $srcval) => dayTimeDuration

Returns a dayTimeDuration with value equal to $srcval.

6.4.4.1 Examples
  • xf:dayTimeDuration-from-seconds(5) returns a dayTimeDuration value corresponding to 5 seconds.

  • xf:dayTimeDuration-from-seconds(-75.5) returns a dayTimeDuration value corresponding to negative 1 minute and 15.5 seconds.

6.5 Comparisons of Duration, Date and Time Values

The following operators are defined on date, time and duration values. Each operator takes two operands of the same kind and returns a boolean result. As discussed in [XML Schema Part 2: Datatypes], the order relation on the duration and some of the date and time datatypes is not a total order but, rather, a partial order. For this reason, only the equality function is defined on duration and operands to the comparison operators on date and time types are restricted as defined below to return a boolean result. Comparison and arithmetic functions are defined on the two subtypes of duration described in 6.2 Two Totally Ordered Subtypes of Duration.

For the purpose of the operators defined in this section, two kinds of dateTimes are defined: those that have timezones and those that do not have timezones. If comparisons are restricted to like kinds dateTimes. For the operators below, attempting to compare durations or dates of differenyt kinds is an error.

If one or more operands is the empty sequence, the result is the empty sequence.

[Issue 151: Do we need comparison functions on other date and time types?]

6.5.1 op:duration-equal

op:duration-equal(duration $operand1, duration $operand2) => boolean

Returns true if and only if $operand1 is exactly equal to $operand2. Returns false otherwise.

This function backs up the "eq" and "ne" operators on duration values.

6.5.2 op:yearMonthDuration-equal

op:yearMonthDuration-equal(yearMonthDuration $operand1, yearMonthDuration $operand2) => boolean

Returns true if and only if $operand1 is exactly equal to $operand2. Returns false otherwise.

This function backs up the "eq" and "ne" operators on yearMonthDuration values.

6.5.3 op:yearMonthDuration-less-than

op:yearMonthDuration-less-than(yearMonthDuration $operand1, yearMonthDuration $operand2) => boolean

Returns true if and only if $operand1 is less than $operand2. Returns false otherwise.

This function backs up the "lt" and "ge" operators on yearMonthDuration values.

6.5.4 op:yearMonthDuration-greater-than

op:yearMonthDuration-greater-than(yearMonthDuration $operand1, yearMonthDuration $operand2) => boolean

Returns true if and only if $operand1 is greater than $operand2. Returns false otherwise.

This function backs up the "gt" and "le" operators on yearMonthDuration values.

6.5.5 op:dayTimeDuration-equal

op:dayTimeDuration-equal(dayTimeDuration $operand1, dayTimeDuration $operand2) => boolean

Returns true if and only if $operand1 is exactly equal to $operand2. Returns false otherwise.

This function backs up the "eq" and "ne" operators on dayTimeDuration values.

6.5.6 op:dayTimeDuration-less-than

op:dayTimeDuration-less-than(dayTimeDuration $operand1, dayTimeDuration $operand2) => boolean

Returns true if and only if $operand1 is less than $operand2. Returns false otherwise.

This function backs up the "lt" and "ge" operators on dayTimeDuration values.

6.5.7 op:dayTimeDuration-greater-than

op:dayTimeDuration-greater-than(dayTimeDuration $operand1, dayTimeDuration $operand2) => boolean

Returns true if and only if $operand1 is greater than $operand2. Returns false otherwise.

This function backs up the "gt" and "le" operators on dayTimeDuration values.

6.5.8 op:datetime-equal

op:datetime-equal(dateTime $operand1, dateTime $operand2) => boolean

Returns true if and only if $operand1 is exactly equal to $operand2. Returns false otherwise.

This function backs up the "eq" and "ne" operators on dateTime values.

6.5.9 op:datetime-less-than

op:datetime-less-than(dateTime $operand1, dateTime $operand2) => boolean

Returns true if and only if $operand1 is less than $operand2. Returns false otherwise.

This function backs up the "lt" and "ge" operators on dateTime values.

6.5.10 op:datetime-greater-than

op:datetime-greater-than(dateTime $operand1, dateTime $operand2) => boolean

Returns true if and only if $operand1 is greater than $operand2. Returns false otherwise.

This function backs up the "gt" and "le" operators on dateTime values.

6.6 Component Extraction Functions on Duration, Date and Time Values

The date and time datatypes may be considered to be composite datatypes in that they contain distinct components. The extraction functions specified below extract one component from a date or time value.

[Issue 152: Create a single extraction function for each datatype that takes as a parameter the field it extracts. ]

6.6.1 xf:get-years-from-yearMonthDuration

xf:get-years-from-yearMonthDuration(yearMonthDuration? $srcval) => integer?

Returns an integer representing the years component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

6.6.1.1 Examples
  • xf:get-years-from-yearMonthDuration(xf:dateTime("P20Y15M")) returns 20.

6.6.2 xf:get-months-from-yearMonthDuration

xf:get-months-from-yearMonthDuration(yearMonthDuration? $srcval) => integer?

Returns an integer representing the months component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

6.6.2.1 Examples
  • xf:get-months-from-yearMonthDuration(xf:dateTime("P20Y15M")) returns 15.

6.6.3 xf:get-days-from-dayTimeDuration

xf:get-days-from-dayTimeDuration(dayTimeDuration? $srcval) => integer?

Returns an integer representing the days component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

6.6.3.1 Examples
  • xf:get-days-from-dayTimeDuration(xf:dateTime("P3DT10H")) returns 3.

6.6.4 xf:get-hours-from-dayTimeDuration

xf:get-hours-from-dayTimeDuration(dayTimeDuration? $srcval) => integer?

Returns an integer representing the hours component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

6.6.4.1 Examples
  • xf:get-hours-from-dayTimeDuration(xf:dateTime("P3DT10H")) returns 10.

6.6.5 xf:get-minutes-from-dayTimeDuration

xf:get-minutes-from-dayTimeDuration(dayTimeDuration? $srcval) => integer?

Returns an integer representing the minutes component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

6.6.5.1 Examples
  • xf:get-minutes-from-dayTimeDuration(xf:dateTime("P3DT10H")) returns 0.

6.6.6 xf:get-seconds-from-dayTimeDuration

xf:get-seconds-from-dayTimeDuration(dayTimeDuration? $srcval) => integer?

Returns a decimal number representing the seconds component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

6.6.6.1 Examples
  • xf:get-seconds-from-dayTimeDuration(xf:dateTime("P3DT10H12.5S")) returns 12.5.

6.6.7 xf:get-year-from-dateTime

xf:get-year-from-dateTime(dateTime? $srcval) => integer?

Returns an integer representing the year component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

6.6.7.1 Examples
  • xf:get-year-from-dateTime(xf:dateTime("1999-05-31T13:20:00-05:00")) returns 1999.

6.6.8 xf:get-year-from-date

xf:get-year-from-date(date? $srcval) => integer?

Returns an integer representing the year in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

6.6.8.1 Examples
  • xf:get-year-from-date(xf:date("1999-05-31")) returns 1999 .

6.6.9 xf:get-month-from-dateTime

xf:get-month-from-dateTime(dateTime? $srcval) => integer?

Returns an integer representing the month component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

6.6.9.1 Examples
  • xf:get-month-from-dateTime(xf:dateTime("1999-05-31T13:20:00-05:00")) returns 5 .

6.6.10 xf:get-month-from-date

xf:get-month-from-date(date? $srcval) => integer?

Returns an integer representing the month component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

6.6.10.1 Examples
  • xf:get-month-from-date(xf:dateTime("1999-05-31-05:00")) returns 5 .

6.6.11 xf:get-day-from-dateTime

xf:get-day-from-dateTime(dateTime? $srcval) => integer?

Returns an integer representing the day component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

6.6.11.1 Examples
  • xf:get-year-from-dateTime(xf:dateTime("1999-05-31T13:20:00-05:00")) returns 31 .

6.6.12 xf:get-day-from-date

xf:get-day-from-date(date? $srcval) => integer?

Returns an integer representing the day component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

6.6.12.1 Examples
  • xf:get-year-from-dateTime(xf:dateTime("1999-05-31-05:00")) returns 31.

6.6.13 xf:get-hours-from-dateTime

xf:get-hours-from-dateTime(dateTime? $srcval) => integer?

Returns an integer representing the hours value identified in the value of $srcval. The hours value ranges from 0 to 23, inclusive. If $srcval is the empty sequence, returns the empty sequence.

6.6.13.1 Examples
  • xf:get-hours-from-dateTime(xf:dateTime("1999-05-31T13:20:00-05:00")) returns 13 .

6.6.14 xf:get-hours-from-time

xf:get-hours-from-time(time? $srcval) => integer?

Returns an integer representing the hours value identified in the value of $srcval. The hours value ranges from 0 to 23, inclusive. If $srcval is the empty sequence, returns the empty sequence.

6.6.14.1 Examples
  • xf:get-hours-from-time(xf:dateTime("11:23:00")) returns 11 .

6.6.15 xf:get-minutes-from-dateTime

xf:get-minutes-from-dateTime(dateTime? $srcval) => integer?

Returns an integer value representing the minute identified in the value of $srcval. The minute value ranges from 0 to 59, inclusive. If $srcval is the empty sequence, returns the empty sequence.

6.6.15.1 Examples
  • xf:get-minutes-from-dateTime(xf:dateTime("1999-05-31T13:20:00-05:00")) returns 20 .

6.6.16 xf:get-minutes-from-time

xf:get-minutes-from-time(time? $srcval) => integer?

Returns an integer value representing the minute identified in the value of $srcval. The minute value ranges from 0 to 59, inclusive. If $srcval is the empty sequence, returns the empty sequence.

6.6.16.1 Examples
  • xf:get-minutes-from-time(xf:time("13:00:00Z")) returns 0 .

6.6.17 xf:get-seconds-from-dateTime

xf:get-seconds-from-dateTime(dateTime? $srcval) => decimal?

Returns a decimal value representing the seconds and fractional seconds identified in the value of $srcval. The value ranges from 0 to 60.999..., inclusive. The number of digits of fractional seconds precision is determined by the relevant facet of the argument. Note that the value can be greater than 60 seconds to accomodate occassional leap seconds used to keep human time synchronized with the rotation of the planet. If $srcval is the empty sequence, returns the empty sequence.

6.6.17.1 Examples
  • xf:get-seconds-from-dateTime(xf:dateTime("1999-05-31T13:20:00-05:00")) returns 0 .

6.6.18 xf:get-seconds-from-time

xf:get-seconds-from-time(time? $srcval) => decimal?

Returns a decimal value representing the seconds and fractional seconds identified in the value of $srcval. The value ranges from 0 to 60.999..., inclusive. The number of digits of fractional seconds precision is determined by the relevant facet of the argument. Note that the value can be greater than 60 seconds to accomodate occassional leap seconds used to keep human time synchronized with the rotation of the planet. If $srcval is the empty sequence, returns the empty sequence.

6.6.18.1 Examples
  • xf:get-seconds-from-time(xf:time("13:20:10.5")) returns 10.5 .

6.6.19 xf:get-timezone-from-dateTime

xf:get-timezone-from-dateTime(dateTime? $srcval) => string?

Returns a string representing the timezone component of $srcval. The result is a duration in "hh:mm" format with an optional leading minus (-) sign, indicating the deviation from GMT (UTC). If $srcval does not contain a timezone, the result is the empty sequence. If $srcval is the empty sequence, returns the empty sequence.

[Issue 110: No timezone: Empty sequence or empty string?]

[Issue 137: Should functions that return timezones return a duration?]

6.6.19.1 Examples
  • xf:get-timezone-from-dateTime(xf:dateTime("1999-05-31T13:20:00-05:00")) returns "-05:00" .

  • xf:get-timezone-from-dateTime(xf:dateTime("2000-06-12T13:20:00Z")) returns "00:00" .

6.6.20 xf:get-timezone-from-date

xf:get-timezone-from-date(date? $srcval) => string?

Returns a string representing the timezone component of $srcval. The result is a duration in "hh:mm" format with an optional leading minus (-) sign, indicating the deviation from GMT (UTC). If $srcval does not contain a timezone, the result is the empty sequence. If $srcval is the empty sequence, returns the empty sequence.

6.6.20.1 Examples
  • xf:get-timezone-from-date(xf:date("1999-05-31-05:00")) returns "-05:00" .

  • xf:get-timezone-from-date(xf:date("2000-06-12Z")) returns "00:00" .

6.6.21 xf:get-timezone-from-time

xf:get-timezone-from-time(time? $srcval) => string?

Returns a string representing the timezone component of $srcval. The result is a duration in "hh:mm" format with an optional leading minus (-) sign, indicating the deviation from GMT (UTC). If $srcval does not contain a timezone, the result is the empty sequence. If $srcval is the empty sequence, returns the empty sequence.

6.6.21.1 Examples
  • xf:get-timezone-from-time(xf:time("13:20:00-05:00")) returns "-05:00" .

  • xf:get-timezone-from-time(xf:time("13:20:00")) returns the empty sequence .

6.7 Arithmetic Functions on yearMonthDuration and dayTimeDuration

FunctionMeaning
xf:add-yearMonthDurations Adds two yearMonthDurations. Returns a yearMonthDuration.
xf:subtract-yearMonthDurations Subtracts one yearMonthDuration from another. Returns a yearMonthDuration.
xf:multiply-yearMonthDuration Multiply a yearMonthDuration by a decimal. Returns a yearMonthDuration.
xf:divide-yearMonthDuration Divide a yearMonthDuration by a decimal. Returns a yearMonthDuration.
xf:add-dayTimeDurations Adds two dayTimeDurations. Returns a dayTimeDuration.
xf:subtract-dayTimeDurations Subtracts one dayTimeDuration from another. Returns a dayTimeDuration.
xf:multiply-dayTimeDuration Multiply a dayTimeDuration by a decimal. Returns a dayTimeDuration.
xf:divide-dayTimeDuration Divide a dayTimeDuration by a decimal. Returns a dayTimeDuration.

6.7.1 op:add-yearMonthDurations

op:add-yearMonthDurations(yearMonthDuration $srcval1, yearMonthDuration $srcval2) => yearMonthDuration

Returns the result of adding the value of $srcval1 to the value of $srcval2. Backs up the "+" operator on yearMonthDuration values.

6.7.1.1 Examples
  • xf:add-yearMonthDurations(xf:yearMonthDuration("P2Y11M"), xf:yearMonthDuration("P3Y3M")) returns a yearMonthDuration value corresponding to 6 years and 2 months.

6.7.2 op:subtract-yearMonthDurations

op:subtract-yearMonthDurations(yearMonthDuration $srcval1, yearMonthDuration $srcval2) => yearMonthDuration

Returns the result of subtracting the value of $srcval2 from the value of $srcval2. Backs up the "-" operator on yearMonthDuration values.

6.7.2.1 Examples
  • xf:subtract-yearMonthDurations(xf:yearMonthDuration("P2Y11M"), xf:yearMonthDuration("P3Y3M")) returns a yearMonthDuration value corresponding to negative 4 months.

6.7.3 op:multiply-yearMonthDuration

op:multiply-yearMonthDuration(yearMonthDuration $srcval1, decimal $srcval2) => yearMonthDuration

Returns the result of multiplying the value of $srcval1 by $srcval2. The result is rounded to the nearest month. For a value v, 0 <= v < 0.5 rounds to 0; 0.5 <= v < 1.0 rounds to 1.

Backs up the "*" operator on yearMonthDuration values.

6.7.3.1 Examples
  • xf:multiply-yearMonthDuration(xf:yearMonthDuration("P2Y11M"), 2.3) returns a yearMonthDuration value corresponding to 6 years and 9 months.

6.7.4 op:divide-yearMonthDuration

op:divide-yearMonthDuration(yearMonthDuration $srcval1, decimal $srcval2) => yearMonthDuration

Returns the result of dividing the value of $srcval1 by $srcval2. The result is rounded to the nearest month. For a value v, 0 <= v < 0.5 rounds to 0; 0.5 <= v < 1.0 rounds to 1.

Backs up the "div" operator on yearMonthDuration values.

6.7.4.1 Examples
  • xf:divide-yearMonthDuration(xf:yearMonthDuration("P2Y11M"), 1.5) returns a yearMonthDuration value corresponding to 1 year and 11 months.

6.7.5 op:add-dayTimeDurations

op:add-dayTimeDurations(dayTimeDuration $srcval1, dayTimeDuration $srcval2) => dayTimeDuration

Returns the result of adding the value of $srcval1 to the value of $srcval2. Backs up the "+" operator on dayTimeDuration values.

6.7.5.1 Examples
  • xf:add-dayTimeDurations(xf:dayTimeDuration("P2DT12H5M"), xf:dayTimeDuration("P5DT12H")) returns a dayTimeDuration value corresponding to 8 days and 5 minutes.

6.7.6 op:subtract-dayTimeDurations

op:subtract-dayTimeDurations(dayTimeDuration $srcval1, dayTimeDuration $srcval2) => dayTimeDuration

Returns the result of subtracting the value of $srcval2 from the value of $srcval2. Backs up the "-" operator on dayTimeDuration values.

6.7.6.1 Examples
  • xf:subtract-dayTimeDurations(xf:dayTimeDuration("P2DT12H"), xf:dayTimeDuration("P1DT10H30M")) returns a dayTimeDuration value corresponding to 1 day and 1.5 hours.

6.7.7 op:multiply-dayTimeDuration

op:multiply-dayTimeDuration(dayTimeDuration $srcval1, decimal $srcval2) => dayTimeDuration

Returns the result of multiplying the value of $srcval1 by $srcval2. Backs up the "*" operator on dayTimeDuration values.

6.7.7.1 Examples
  • xf:multiply-dayTimeDuration(xf:dayTimeDuration("PT2H10M"), 2.1) returns a dayTimeDuration value corresponding to 4 hours and 23 minutes.

6.7.8 op:divide-dayTimeDuration

op:divide-dayTimeDuration(dayTimeDuration $srcval1, decimal $srcval2) => yearMonthDuration

Returns the result of dividing the value of $srcval1 by $srcval2. The result is rounded to the nearest month. Backs up the "div" operator on dayTimeDuration values.

6.7.8.1 Examples
  • xf:divide-dayTimeDuration(xf:yearMonthDuration("P1DT2H30M10.5S"), 1.5) returns a dayTimeDuration value corresponding to 17 hours, 40 minutes and 2 seconds.

6.8 Arithmetic Functions on Dates

FunctionMeaning
xf:add-days Adds the number of days indicated by the second argument to the first argument.

6.8.1 xf:add-days

xf:add-days(date? $dateParam, decimal? $incrDays) => date?

Adds the number of days indicated by the value of $incrDays to the value of $dateParam. The value of $incrDays may be negative. If the value of $dateparam has a timezone, it remains unchanged. The returned value is always normalized into a correct Gregorian calendar date. If either parameter is the empty sequence, returns the empty sequence.

6.8.1.1 Examples
  • xf:add-days(xf:date("2001-02-28"), 2) returns a date value corresponding to March 2, 2001.

6.9 Functions and Operators on TimePeriod Values

Let us define a time period as an interval or duration of time with a fixed start and end. Thus, time periods have three properties, two of which are independent. The three functions below take two of the properties as arguments and return the third.

These functions require add or subtracting a duration to or from a date. Appendix E of [XML Schema Part 2: Datatypes] describes an algorithm for adding durations to dates.

FunctionMeaning
xf:get-yearMonthDuration Returns the difference between two dateTimes as a yearMonthDuration.
xf:get-dayTimeDuration Returns the difference between two dateTimes as a dayTimeDuration.
op:add-yearMonthDuration-to-dateTime Returns the end of a time period by adding a yearMonthDuration to the dateTime that starts the period.
op:add-dayTimeDuration-to-dateTime Returns the end of a time period by adding a dayTimeDuration to the the dateTime that starts the period.
op:subtract-yearMonthDuration-from-dateTime Returns the beginning of a time period by subtracting a yearMonthDuration from the the dateTime that ends the period.
op:subtract-dayTimeDuration-from-dateTime Returns the beginning of a time period by subtracting a dayTimeDuration from the the dateTime that ends the period.
op:add-yearMonthDuration-to-date Returns the end of a time period by adding a yearMonthDuration to the date that starts the period.
op:add-dayTimeDuration-to-date Returns the end of a time period by adding a dayTimeDuration to the the date that starts the period.
op:subtract-yearMonthDuration-from-date Returns the beginning of a time period by subtracting a yearMonthDuration from the the date that ends the period.
op:subtract-dayTimeDuration-from-date Returns the beginning of a time period by subtracting a dayTimeDuration from the the date that ends the period.
op:add-dayTimeDuration-to-time Adds the value of the hours, minutes and seconds components of a dayTimeDuration to a time value.
op:subtract-dayTimeDuration-from-time Subtracts the value of the hours, minutes and seconds components of a dayTimeDuration to a time value.

6.9.1 xf:get-yearMonthDuration

xf:get-yearMonthDuration(dateTime $srcval1, dateTime $srcval2) => yearMonthDuration

Returns the yearMonthDuration that corresponds to the difference between the value of $srcval1 and the value of $srcval2. If the value of $srcval1 follows in time the value of $srcval2, then the returned value is a negative duration. If one or both arguments do not have a timezone they are assigned an implicit ·implementation-defined· timezone. If either argument is the empty sequence, returns the empty sequence.

In general, the difference between two dateTime values will be a duration that contains years and months as well as days, hours, etc. In fact, it can be looked at as a yearMonthDuration plus a dayTimeDuration. This function returns the result rounded to contain only years and months. The calculation is as follows: first the duration is calculated as the value of a dayTimeDuration in seconds. Then, starting from $srcval2, the maximum number of months in the duration are calculated. The remainder r is is rounded and added to the number of months. If 0 <= r < 15.5 days, r rounds to 0 months; if 15.5 days <= r, r rounds to 1 month.

6.9.1.1 Examples
  • xfy:get-yearMonthDuration(xf:dateTime("2000-10-30T11:12:00"), xf:dateTime("1999-11-28T09:00:00")) returns a yearMonthDuration value corresponding to 11 months.

6.9.2 xf:get-dayTimeDuration

xf:get-dayTimeDuration(dateTime $srcval1, dateTime $srcval2) => dayTimeDuration

Returns the dayTimeDuration that corresponds to the difference between the value of $srcval1 and the value of $srcval2. If the value of $srcval1 follows in time the value of $srcval2, then the returned value is a negative duration. If one or both arguments do not have a timezone they are assigned an implicit ·implementation-defined· timezone. If either argument is the empty sequence, returns the empty sequence.

This function returns the value of a dayTimeDuration in seconds. Note that the number of days in this value can be greater than 31.

6.9.2.1 Examples
  • xf:get-dayTimeDuration(xf:dateTime("2000-10-30T11:12:00"), xf:dateTime("1999-11-28T09:00:00")) returns a dayTimeDuration value corresponding to 337 days, 2 hours and 12 minutes. .

6.9.3 op:add-yearMonthDuration-to-dateTime

op:add-yearMonthDuration-to-dateTime(dateTime $srcval1, yearMonthDuration $srcval2) => dateTime

Returns the end of a time period by adding a yearMonthDuration ($srcval2) to the dateTime that starts the period ($srcval1). If the duration is negative, then the "end" of the period precedes the "start" of the period.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "+" operator on dateTime and yearMonthDuration.

6.9.3.1 Examples
  • op:add-yearMonthDuration-to-dateTime(xf:dateTime("2000-10-30T11:12:00"), xf:yearMonthDuration("P1Y2M")) returns a dateTime value corresponding to the lexical representation "2001-12-30T11:12:00". .

6.9.4 op:add-dayTimeDuration-to-dateTime

op:add-dayTimeDuration-to-dateTime(dateTime $srcval1, dayTimeDuration $srcval2) => dateTime

Returns the end of a time period by adding a dayTimeDuration ($srcval2) to the dateTime that starts the period ($srcval1). If the duration is negative, then the "end" of the period precedes the "start" of the period.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "+" operator on dateTime and dayTimeDuration.

6.9.4.1 Examples
  • op:add-dayTimeDuration-to-dateTime(xf:dateTime("2000-10-30T11:12:00"), xf:dayTimeDuration("P3DT1H15M")) returns a dateTime value corresponding to the lexical representation "2000-11-02T12:27:00". .

6.9.5 op:subtract-yearMonthDuration-from-dateTime

op:subtract-yearMonthDuration-from-dateTime(dateTime $srcval1, yearMonthDuration $srcval2) => dateTime

Returns the start of a time period by subtracting a yearMonthDuration ($srcval2) from the dateTime that ends the period ($srcval1). If the duration is negative, then the "start" of the period precedes the "end" of the period.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "-" operator on dateTime and yearMonthDuration.

6.9.5.1 Examples
  • op:subtract-yearMonthDuration-from-dateTime(xf:dateTime("2000-10-30T11:12:00"), xf:yearMonthDuration("P1Y2M")) returns a dateTime value corresponding to the lexical representation "1999-08-30T11:12:00". .

6.9.6 op:subtract-dayTimeDuration-from-dateTime

op:subtract-dayTimeDuration-from-dateTime(dateTime $srcval1, dayTimeDuration $srcval2) => dateTime

Returns the start of a time period by subtracting a dayTimeDuration ($srcval2) from the dateTime that ends the period ($srcval1). If the duration is negative, then the "start" of the period precedes the "end" of the period.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "-" operator on dateTime and dayTimeDuration.

6.9.6.1 Examples
  • op:subtract-dayTimeDuration-from-dateTime(xf:dateTime("2000-10-30T11:12:00"), xf:dayTimeDuration("P3DT1H15M")) returns a dateTime value corresponding to the lexical representation "2000-10-28T09:57:00". .

6.9.7 op:add-yearMonthDuration-to-date

op:add-yearMonthDuration-to-date(date $srcval1, yearMonthDuration $srcval2) => date

Returns the date computed by adding the yearMonthDuration in $srcval2 to the date in $srcval1. If the duration is negative, then the result date precedes $srcval1.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "+" operator on date and yearMonthDuration.

6.9.7.1 Examples
  • op:add-yearMonthDuration-to-date(xf:date("2000-10-30"), xf:yearMonthDuration("P1Y2M")) returns the date whose value is December 30, 2001. .

6.9.8 op:add-dayTimeDuration-to-date

op:add-dayTimeDuration-to-date(date $srcval1, dayTimeDuration $srcval2) => dateTime

Returns the date computed by adding the days component of the canonical representation of the dayTimeDuration in $srcval2 to the date in $srcval1.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "+" operator on date and dayTimeDuration.

6.9.8.1 Examples
  • op:add-dayTimeDuration-to-date(xf:date("2000-10-30"), xf:dayTimeDuration("P2DT2H30M0S")) returns the date whose value is November 1, 2000". .

6.9.9 op:subtract-yearMonthDuration-from-date

op:subtract-yearMonthDuration-from-date(date $srcval1, yearMonthDuration $srcval2) => date

Returns the date computed by subtracting the yearMonthDuration in $srcval2 from the date in $srcval. If the duration is negative, then the result date follows $srcval1.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "-" operator on date and yearMonthDuration.

6.9.9.1 Examples
  • op:subtract-yearMonthDuration-from-date(xf:dateTime("2000-10-30"), xf:yearMonthDuration("P1Y2M")) returns thedate whose value is August 30, 1999.". .

6.9.10 op:subtract-dayTimeDuration-from-date

op:subtract-dayTimeDuration-from-date(date $srcval1, dayTimeDuration $srcval2) => date

Returns the date computed by subtracting the days component of the canonical representation of the dayTimeDuration in $srcval2 from the date in $srcval1. If the duration is negative, then the result date follows $srcval1

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "-" operator on date and dayTimeDuration.

6.9.10.1 Examples
  • op:subtract-dayTimeDuration-from-date(xf:date("2000-10-30"), xf:dayTimeDuration("P3DT1H15M")) returns a date whose value is October 28, 2000. .

6.9.11 op:add-dayTimeDuration-to-time

op:add-dayTimeDuration-to-time(time $srcval1, dayTimeDuration $srcval2) => time

First, the days component of $srcval2 is set to zero and the value of the resulting duration is calculated. This value is added to $parameter1 and the result returned.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "+" operator on time and dayTimeDuration.

6.9.11.1 Examples
  • op:add-dayTimeDuration-to-time(xf:time("11:12:00"), xf:dayTimeDuration("P3DT1H15M")) returns a time value corresponding to the lexical representation "12:27:00". .

6.9.12 op:subtract-dayTimeDuration-from-time

op:subtract-dayTimeDuration-from-time(time $srcval1, dayTimeDuration $srcval2) => time

First, the days component of $srcval2 is set to zero and the value of the resulting duration is calculated. This value is subtracted from $srcval1 and the result returned.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "-" operator on time and dayTimeDuration.

6.9.12.1 Examples
  • op:subtract-dayTimeDuration-from-time(xf:time("11:12:00"), xf:dayTimeDuration("P3DT1H15M")) returns a time value corresponding to the lexical representation "10:57:00". .

7 Constructors and Functions on QNames

7.1 Constructors for QNames

This section discusses constructors for QNames as defined in [XML Schema Part 2: Datatypes]. Each constructor takes one or more single string literals as arguments. Leading and trailing whitespace, if present, is stripped from the literal before the value is constructed.

FunctionMeaningSource
xf:QName-from-uri Returns a QName with the namespace URI given in the first argument and the local name in the second argument.
xf:QName-from-string Accepts a string with a single embedded colon and returns a QName with the namespace URI that maps to the substring in the argument before the colon and the local name in the substring following the colon. The prefix-to-URI mapping uses the namespaces in scope.
xf:QName Returns a QName in no namespace with the local name given in the argument.

7.1.1 xf:QName-from-uri

xf:QName-from-uri(string $paramURI, string $paramLocal) => QName

Returns a QName with the namespace URI given in $paramURI and the local name in $paramLocal.

[Issue 112: QName-from-uri needs context]

7.1.1.1 Examples
  • xf:QName-from-uri("http://www.ashokmalhotra.com/example", "person") returns a QName with namespace URI = "http://www.ashokmalhotra.com/example" and local name = "person".

7.1.2 xf:QName-from-string

xf:QName-from-string(string $param) => QName

Accepts an argument which is a string containing a single colon. The substring before the colon indicates the prefix and the substring following the colon indicates the local name. The two substrings must obey the lexical constraints for prefix and local name, respectively. Returns a QName with the namespace URI that maps to the prefix and the local name. The prefix to URI mapping uses the namespaces in scope.

7.1.2.1 Examples
  • xf:QName-from-string("ashok:person") returns a QName with the namespace URI bound to the prefix "ashok" and local name = "person", provided the namespace URI is in scope. If the namespace URI is not in scope, then the function returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

7.1.3 xf:QName

xf:QName(string $paramLocal) => QName

Returns a QName in no namespace with the local name given in $paramLocal.

[Issue 112: QName-from-uri needs context]

7.1.3.1 Examples
  • xf:QName("person") returns a QName with no namespace URI and local name = "person".

7.2 Functions on QNames

This section discusses functions on QNames as defined in [XML Schema Part 2: Datatypes].

FunctionMeaningSource
op:QName-equal Returns true if the local names and namespace URIs of the two arguments are equal.
xf:get-local-name Returns a string representing the local part of the QName argument.
xf:get-namespace-uri Returns the namespace URI for the QName argument. This may be the empty sequence if the QName is in no namespace.
xf:namespace-uri Returns the namespace URI as a string for the QName of the argument node or the context node if the argument is omitted. This may be the zero-length string if the QName is in no namespace.

7.2.1 op:QName-equal

op:QName-equal(QName $srcval1, QName $srcval2) => boolean

Returns true if the namespace names of $srcval1 and $srcval2 are equal and the local-name parts of $srcval1 and $srcval2 are identical on a codepoint-by-codepoint basis. Otherwise returns false. Two namespace names are considered equal if they are either both absent or both present and identical on a codepoint-by-codepoint basis.

Backs up the "eq" and "ne" operators on values of type QName.

If either namespace name is a relative URI, it is undefined whether it will compare equal to any other namespace name.

7.2.2 xf:get-local-name

xf:get-local-name(QName? $srcval) => string?

Returns a string representing the local part of $srcval. If $srcval is the empty sequence, returns the empty sequence.

7.2.2.1 Examples
  • xf:get-local-name(xf:QName-from-uri("http://www.ashokmalhotra.com/example", "person")) returns "person".

7.2.3 xf:get-namespace-uri

xf:get-namespace-uri(QName? $srcval) => anyURI?

Returns the namespace URI for $srcval. If $srcval is in no namespace the function returns the empty sequence.

If $srcval is the empty sequence, the empty sequence is returned.

7.2.3.1 Examples
  • xf:get-namespace-uri(xf:QName-from-uri("http://www.ashokmalhotra.com/example", "person")) returns the namespace URI corresponding to "http://www.ashokmalhotra.com/example".

7.2.4 xf:namespace-uri

xf:namespace-uri() => string
xf:namespace-uri(node* $srcval) => string

Returns the namespace URI of the QName of $srcval as a string. If the argument is omitted, it defaults to the context node. If there is no context node (that is, if the context item is not a node), the function returns the zero-length string. If $srcval is the empty sequence, the zero-length string is returned.

If the $srcval is neither an element nor an attribute node, or if it is an element or attribute node which has no QName or whose expanded QName (as determined by the name accessor in the data model) is in no namespace, then the function returns the zero-length string.

In other cases, a type exception occurs. The required type for this function is node. If fallback conversion is enabled and $srcval is a node sequence, the first node in the sequence is used as the argument.

8 Constructors, Functions, and Operators for anyURI

8.1 Constructors for anyURI

This section discusses a constructor for anyURI as defined in [XML Schema Part 2: Datatypes]. The constructor takes a single string literal as argument.

FunctionMeaningSource
xf:anyURI Returns an anyURI with a URI reference as given in the argument.
xf:resolve-URI Returns an absolute anyURI given a base URI and a relative URI.

8.1.1 xf:anyURI

xf:anyURI(string $srcval) => anyURI

Returns an anyURI value with a URI reference specified as the value of $srcval.

8.1.1.1 Examples
  • xf:anyURI("gopher://spinaltap.micro.umn.edu/00/Weather/California/Los%20Angeles") returns the URI with value "gopher://spinaltap.micro.umn.edu/00/Weather/California/Los%20Angeles"

  • xf:anyURI('myCollation') returns the relative URI with value "myCollation".

8.1.2 xf:resolve-URI

xf:resolve-URI(anyURI $base, anyURI $relative) => anyURI

This functions expects $base to be an absolute URI and $relative to be a relative URI. It resolves the relative URI $relative against the base URI $base and returns an absolute URI. Returns relative if it is an absolute URI. Returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model] if base is a relative URI.

8.2 Functions on anyURI

This section discusses functions that take anyURI as arguments.

FunctionMeaningSource
op:anyURI-equal Returns true if the two arguments are equal.

8.2.1 op:anyURI-equal

op:anyURI-equal(anyURI $srcval1, anyURI $srcval2) => boolean

Returns true if $srcval1 and $srcval2 compare equal on a codepoint by codepoint basis. Else returns false. This function backs up the "eq" and "ne" operators on anyURI.

8.2.1.1 Examples
  • op:anyURI-equal(anyURI("gopher://spinaltap.micro.umn.edu/00/Weather/California/Los%20Angeles"), anyURI("gopher://spinaltap.micro.umn.edu)) returns false

9 Functions and Operators on base64Binary and hexBinary

9.1 Comparisons of base64Binary and hexBinary Values

We define the following comparison operators on base64Binary and hexBinary values. Comparisons take two operands of the same type i.e both operands must be base64Binary or hexBinary. Each returns a boolean value.

9.1.1 op:hex-binary-equal

op:hex-binary-equal(hexBinary $value1, hexBinary $value2) => boolean

Returns true if $value1 and value2 are of the same length and contain the same code-points. Otherwise returns false.

This function backs up the "eq" and "ne" operators on hexBinary values.

9.1.2 op:base64-binary-equal

op:base64-binary-equal(base64Binary $value1, base64Binary $value2) => boolean

Returns true if $value1 and value2 are of the same length and contain the same code-points. Otherwise returns false.

This function backs up the "eq" and "ne" operators on base64Binary values.

10 Constructors, Functions, and Operators on NOTATION

10.1 NOTATION Constructor

This section discusses a constructor for NOTATION as defined in [XML Schema Part 2: Datatypes]. The constructor takes a single string literal as argument.

FunctionMeaningSource
xf:NOTATION Returns a NOTATION with the value given in the argument.

10.1.1 xf:NOTATION

xf:NOTATION(string $srcval) => NOTATION

Returns a NOTATION with the value given in $srcval.

10.2 Functions on NOTATION

This section discusses functions that take NOTATION as arguments.

FunctionMeaningSource
op:NOTATION-equal Returns true if the two arguments are equal.

10.2.1 op:NOTATION-equal

op:NOTATION-equal(NOTATION $srcval1, NOTATION $srcval2) => boolean

Returns true if $srcval1 and $srcval2 compare equal on a codepoint by codepoint basis. Else returns false. This function backs up the "eq" and "ne" operators on NOTATION.

11 Functions and Operators on Nodes

This section discusses functions and operators on nodes. Nodes are formally defined in [XQuery 1.0 and XPath 2.0 Data Model].

11.1 Functions and Operators on Nodes

FunctionMeaningSource
xf:name Returns the name of the context node or the specified node as a string. XPath 1.0 modified
xf:local-name Returns the local name of the context node or the specified node as a QName. XPath 1.0 modified
xf:number Returns the value of the context node or the specified node converted to a number. XPath 2.0 req 1.5 (Could)
xf:lang Returns true or false depending on whether the language of the context node, as defined using the xml:lang attribute, is the same as, or a sublanguage of, the language specified by the argument. XPath 1.0
op:node-equal Returns true if the two arguments have the same identity. Data Model
xf:deep-equal Returns true if the two arguments have the same value. Data Model
op:node-before Indicates whether one node appears before another node in document order. Data Model
op:node-after Indicates whether one node appears after another node in document order. Data Model
op:node-precedes Indicates whether one node precedes another node.
op:node-follows Indicates whether one node follows another node.
xf:copy Returns a deep copy of a node. Not supported in XSLT.Data Model
xf:shallow Returns a shallow copy of a node. Not supported in XSLT.Data Model
xf:root Returns the root of the tree to which the node argument belongs.Data Model

For the illustrative examples below, assume an XQuery operating on a Purchase Order document containing a number of item elements. Each item has child elements called description, quantity, etc. Quantity has simple content of type decimal. Further assume that variables $item1, $item2, etc. are bound to the nodes for the item elements in the document in sequence.

11.1.1 xf:name

xf:name() => string
xf:name(node* $srcval) => string

Returns the name of a node, as a string that will either be empty, or will have the lexical form of a QName.

If the argument is omitted, it defaults to the context node. If there is no context node (that is, if the context item is not a node), the function returns the zero-length string.

If the argument is supplied and is the empty sequence, the function returns the zero-length string.

In other cases, a type exception occurs. The required type is "node". If fallback conversion is enabled, a node sequence will be handled by discarding all nodes after the first. If the target node has no name (that is, if it is a document node, a comment, or a text node), the function returns the zero-length string.

Otherwise, the value returned will be a string whose lexical form is a QName.

If $srcval is a processing instruction or a namespace node, or if it is an element or attribute node whose expanded QName (as determined by the name accessor in the data model) is in no namespace, then the function returns the local part of the expanded QName.

If $srcval is an element or attribute whose expanded QName is in a namespace, then a prefix is determined by searching the namespace nodes for that element, or in the case of an attribute, the namespace nodes for the element that is the parent of the attribute. There will always be at least one such namespace node whose namespace URI matches the namespace URI of the node's expanded QName. The prefix is taken from one of these namespace nodes; if there are several, then the implementation may choose one of them arbitrarily (implementations have the option to record the original namespace prefix as part of the data associated with a node, but they are not required to do so). This prefix is then combined with the local part of the node's expanded QName to form a string which will take one of the forms "prefix:local-part" (if the prefix is non-empty) or "local-part" (if the prefix is empty).

11.1.2 xf:local-name

xf:local-name() => string
xf:local-name(node $srcval) => string

Returns the local part of the name of $srcval as a string that will either be empty, or will have the lexical form of an NCName.

If the argument is omitted, it defaults to the context node. If there is no context node (that is, if the context item is not a node), the function returns the zero-length string.

If the argument is supplied and is the empty sequence, the function returns the zero-length string.

In other cases, a type exception occurs. The required type is "node". If fallback conversion is enabled, a node sequence will be handled by discarding all nodes after the first.

If the target node has no name (that is, if it is a document node, a comment, or a text node), the function returns the zero-length string.

Otherwise, the value returned will be the local part of the expanded QName of the target node (as determined by the name accessor in the data model). This will be a string whose lexical form is an NCName.

Returns the value of the node indicated by $srcval or, if $srcval is not specified, the context node, converted to a double. If the value of the node is not a valid lexical representation of a numeric simple type as defined in [XML Schema Part 2: Datatypes], then the function returns the error value as specified in [XQuery 1.0 and XPath 2.0 Data Model].

11.1.3 xf:number

xf:number() => anySimpleType
xf:number(node $srcval) => anySimpleType

Returns the value of the node indicated by $srcval or, if $srcval is not specified, the context node, converted to a double. If the value of the node is not a valid lexical representation of a numeric simple type as defined in [XML Schema Part 2: Datatypes], then the function returns the error value as specified in [XQuery 1.0 and XPath 2.0 Data Model].

11.1.3.1 Examples
  • xf:number($item1/quantity) returns 5.

  • xf:number($item2) returns error.

11.1.4 xf:lang

xf:lang(string $testlang) => boolean

Returns true or false depending on whether the language of the context node, as defined using the xml:lang attribute, is the same as, or a sublanguage of, the language specified by $testlang.

The relevant xml:lang attribute is determined by the value of the XPath expression:

(ancestor-or-self::*/@xml:lang)[last()]

If this expression returns an empty sequence, the function returns false.

Otherwise, the function returns true if and only if the string-value of the relevant xml:lang attribute is equal to $testlang ignoring case, or if the string-value of the relevant testlang attribute contains some hyphen (-) such that the part of the string-value preceding that hyphen is equal to $testlang, ignoring case.

11.1.4.1 Examples
  • For example, the expression xf:lang("en") would return true if the context node were any of the following five elements:

    • <para xml:lang="en"/>

    • <div xml:lang="en"><para></div>

    • <para xml:lang="EN"/>

    • <para xml:lang="en-us"/>

11.1.5 op:node-equal

op:node-equal(node $parameter1, node $parameter2) => boolean

If the node identified by the value of $parameter1 is the same node as the node identified by the value of $parameter2 (that is, the two nodes have the same identity), then the function returns true; otherwise, the function returns false. This function backs up the "==" and "!==" operators on nodes.

11.1.5.1 Examples
  • op:node-equal($item1, $item1) returns true.

  • op:node-equal($item1, $item2) returns false.

11.1.6 xf:deep-equal

xf:deep-equal(node $parameter1, node $parameter2) => boolean
xf:deep-equal(node $parameter1, node $parameter2, anyURI $collation) => boolean

If the node identified by the value of $parameter1 has the same value as the node identified by the value of $parameter2, then the function returns true; otherwise, the function returns false.

We define deep-equality as follows. We assume equality over simple values is defined. Equality of string values is determined according to the collation that is used. Equality over all other data model values is defined recursively.

  • Given attributes a1 and a2, xf:deep-equal(a1,a2), if and only if xf:node-name(a1) eq node-name(a2) and xf:deep-equal(data(a1), data(a2)).

  • Given elements e1 and e2, xf:deep-equal(e1, e2), if and only if xf:node-name(e1) eq node-name(e2) and

    • for each attribute a1i and a2i in e1 and e2, in order, xf:deep-equal(a1i, a2i)

    and, if e1 and e2 have complex content
    • for each child c1i and c2i in e1 and e2, in order, xf:deep-equal(c1i, c2i)

    and, if e1 and e2 have simple content
    • xf:deep-equal(data(e1), data(e2))

If $collationLiteral is specified, then the value of $collationLiteral must identify a collation that is supported in the environment in which the function is invoked. Either an absolute URI or a relative URI may be specified. The collation identified by $collationLiteral, while effectively based on the Unicode Collation Algorithm, has implementation-defined semantics.

If no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

[Issue 158: We need equality functions for all simple datatypes. See also, issue 151.]

11.1.6.1 Examples
  • xf:deep-equal($item1, $item2) returns false.

  • xf:deep-equal($item1, $item1) returns true .

11.1.7 op:node-before

op:node-before(node $parameter1, node $parameter2) => boolean

If the node identified by the value of $parameter1 occurs in document order before the node identified by the value of $parameter2, this function returns true; otherwise, it returns false. The rules determining the order of nodes within a single document and in different documents can be found in [XQuery 1.0 and XPath 2.0 Data Model]. This function backs up the "<<" operator.

11.1.7.1 Examples
  • op:node-before($item1, $item2) returns true.

  • op:node-before($item1, $item1) returns false.

11.1.8 op:node-after

op:node-after(node $parameter1, node $parameter2) => boolean

If the node identified by the value of $parameter1 occurs in document after the node identified by the value of $parameter2, this function returns true; otherwise, it returns false. The rules determining the order of nodes within a single document and in different documents can be found in [XQuery 1.0 and XPath 2.0 Data Model]. This function backs up the ">>" operator.

11.1.8.1 Examples
  • op:node-after($item1, $item2) returns false.

  • op:node-after($item1, $item1) returns false.

11.1.9 op:node-precedes

op:node-precedes(node $srcval1, node $srcval2) => boolean

Returns true if the node identified by $srcval1 occurs before the node identified by $srcval2 in document order, but is not an ancestor of the node identified by $srcval2. Otherwise returns false. This function backs up the "precedes" operator on nodes.

11.1.10 op:node-follows

op:node-follows(node $srvcal1, node $srcval2) => boolean

Returns true if the node identified by $srcval1 occurs after the node identified by $srcval2 in document order, but is not a descendant of the node identified by $srcval2. Otherwise returns false. This function backs up the "follows" operator on nodes.

11.1.11 xf:copy

xf:copy(node? $srcval) => node?

Returns a copy of the node that is the value of $srcval including all its attributes and descendants; the copy has a different identity than the node indicated by the value of $srcval.

Note:

XSLT will not support this function.

[Issue 60: What are the precise semantics of the copy() function?]

11.1.11.1 Examples

$var = xf:copy($item1) creates a node that is a copy of the value of $item1, including its attributes and descendants, gives it a different identity, and sets the value of $var equal to it. Assume that the value of $item1 was the element node:

   <family name='green'>
      <father>peter</father>
      <mother>mary<mother>
      <child>joseph</child>
   </family>

The value of $var would be

   <family name='green'>
      <father>peter</father>
      <mother>mary<mother>
      <child>joseph</child>
   </family>

11.1.12 xf:shallow

xf:shallow(node? $srcval) => node?

Returns a copy of the node that is the value of $srcval including all its attributes but not its descendants; the copy has a different identity than the node indicated by the value of $srcval.

Note:

XSLT will not support this function.

11.1.12.1 Examples

$var = xf:copy($item1) creates a node that is a copy of $item1, including only its attributes and not its descendants, gives it a different identity, and sets the value of $varequal to it. Assume that the value of $item1 was the element node:

   <family name='green'>
      <father>peter</father>
      <mother>mary<mother>
      <child>joseph</child>
   </family>

The value of $var would be

<family name='green'/>

11.1.13 xf:root

xf:root(node $srcval) => node

Returns the root of the tree to which $srcval belongs. This will usually, but not necessarily, be a document node. If $srcval is a document node it is returned.

[Issue 162: Can we omit the node argument to root() and use the context item if it is omitted.]

11.2 if-absent() and if-empty()

FunctionMeaningSource
xf:if-absent If first argument is the empty sequence, returns second argument; otherwise returns content of first argument. XQuery
xf:if-empty If first argument is the empty sequence or an element node with empty content, returns second argument; otherwise returns content of first argument. XQuery

It is sometimes desirable to write arithmetic expressions in which absent data will be replaced by a default value. For example, it might be desirable for the expression emp/(salary + bonus) to return the salary in the case where an employee has no bonus. The + operator will return the empty sequence in this case. The above functions address this problem.

11.2.1 xf:if-absent

xf:if-absent((elementNode | attributeNode)? $node, anySimpleType $value) => (elementNode | attributeNode | anySimpleType)?

If the first argument is the empty sequence, if-absent() returns the second argument; otherwise it returns the content of the first argument.

11.2.1.1 Examples
  • xf:if-absent(bonus, 0) returns the content of the bonus element or 0 if there is no bonus element.

11.2.2 xf:if-empty

xf:if-empty((elementNode | attributeNode)? $node, anySimpleType $value) => (elementNode | attributeNode | anySimpleType)

If the first argument is the empty sequence or an element with empty content, if-empty() returns the second argument; otherwise it returns the content of the first argument.

[Issue 155: The term 'empty content' should be changed or, at least, be carefully defined.]

11.2.2.1 Examples
  • xf:if-empty(bonus, 0) returns the content of the bonus element or 0 if there is no bonus element or if the bonus element is empty.

12 Constructors, Functions, and Operators on Sequences

A sequence is an ordered collection of zero or more items. An item is either a node or an atomic value. The terms sequence and item are defined formally in [XQuery 1.0: An XML Query Language] and [XPath 2.0].

[Issue 82: Clarify distinction between node sets, lists, and sequences]

[Issue 89: Functions that have anyType in their return are problematic.]

12.1 Constructors on Sequences

The following constructors are defined for sequences.

OperatorMeaning
op:to Returns the sequence containing every integer between the values of the operands.

12.1.1 op:to

op:to(decimal $firstval, decimal $lastval) => sequence

The effective values of $firstval and $lastval are computed as cast as integer(floor($firstval)) and cast as integer(floor($lastval)).

Converts both its operands to integers and returns the sequence containing every integer whose value is between the effective value of $firstval (inclusive) and the effective value of $lastval (inclusive), in monotonic order. If the effective value of the first operand is less than the effective value of the second, the sequence is in increasing order, otherwise it is in decreasing order. If the effective value of the two operands is equal, a sequence containing a single integer equal to the effective value is returned.

This function backs up the "to" operator.

12.2 Functions and Operators on Sequences

The following functions are defined on sequences.

FunctionMeaningSource
xf:boolean Casts a sequence to a boolean. See also 14.6 Casting to boolean .XPath 1.0
op:concatenate Concatenates two sequences. XPath 1.0
op:item-at Returns the item at given index. XPath 2.0 Req 4.4 (Should)
xf:index-of Returns a sequence of unsignedInts, each of which is the index of a member of the specified sequence that is equal to the simple value or node that is the value of the second argument. If no members of the specified sequence are equal to the value of the second argument, the function returns an empty sequence. XPath 2.0 Req 4.4 (Should)
xf:empty Indicates whether or not the provided sequence is empty. XPath 2.0 Req 4.4 (Should)
xf:exists Indicates whether or not the provided sequence is not empty.
xf:distinct-nodes Returns a sequence in which all redundant duplicate elements, based on node identity, have been deleted. The specific node in a collection of redundant duplicate nodes that is retained in implementation-dependent. XPath 2.0 Req 4.4 (Should)
xf:distinct-values Returns a sequence in which all redundant duplicate elements, based on value equality, have been deleted. The specific node in a collection of redundant duplicate nodes that is retained in implementation-dependent. XPath 2.0 Req 4.4 (Should)
xf:insert Inserts an element or sequence of elements into a specified position of a sequence. XPath 2.0 Req 2.4, 4.4 (Should)
xf:subsequence Returns the subsequence of a given sequence identified by location. XPath 2.0 Req 4.4 (Should)

[Issue 63: Do we need variations of index-of for values and identity?]

[Issue 66: A function to reorder a sequence into document order is needed]

As in the previous section, for the illustrative examples below, assume an XQuery operating on a Purchase Order document containing a number of item elements. The variable $seq is bound to the sequence of item nodes in document order. The variables $item1, $item2, etc. are bound to individual item nodes in the sequence.

12.2.1 xf:boolean

xf:boolean(item* $srcval) => boolean

If $srcval is the empty sequence, returns false. If $srcval is a sequence containing more than one item, a type exception is thrown. A sequence with a single item is equivalent to the single item. If this is an untyped node a type exception is thrown, otherwise its typed-value is accessed. The value is then converted to boolean as defined in 14.6 Casting to boolean .

[Issue 156: How should the boolean function be defined? Legacy XPath 1.0 function? ]

12.2.2 op:concatenate

op:concatenate(item* $seq1, item* $seq2) => item*

Returns a sequence consisting of the items in $seq1 followed by the items in $seq2. This function backs up the infix operator ",". If either sequence is the empty sequence, the other operand is returned.

12.2.2.1 Examples
  • op:concatenate((1 2 3), (4 5)) returns (1 2 3 4 5).

  • op:concatenate((), ()) returns ().

12.2.3 op:item-at

op:item-at(item* $seqParam, decimal $posParam) => item?

Returns the item in $seqParam that is located at the index that is the value of $posParam.

If $seqParam is the empty sequence, returns the empty sequence.

If the value of $posParam is greater than the number of items in the sequence, or is less than or equal to zero, then the function returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

This function is used in the definition of the formal semantics of filter expressions, that is, expressions of the form expression-1[expression-2]

12.2.3.1 Examples
  • xf:node-equal(xf:item-at($seq, 1), $item1) returns true.

12.2.4 xf:index-of

xf:index-of(item* $seqParam, item $srchParam) => unsignedInt?
xf:index-of(item* $seqParam, item $srchParam, anyURI $collationLiteral) => unsignedInt?

If the value of $seqParam contains only simple values, then the function returns a sequence of unsigned integers indicating the indexes (positions) of items in the value of $seqParam that are equal to the simple value of $srchParam. If the data types of the simple values are strings, then equality is determined according to the collation that is used.

If the value of $seqParam contains nodes, then the function returns a sequence of unsigned integers indicating the indexes (positions) of nodes whose string values are equal to the string value of the node in the second argument. Equality of string values is determined according to the collation that is used.

If $collationLiteral is specified, then the value of $collationLiteral must identify a collation that is supported in the environment in which the function is invoked. Either an absolute URI or a relative URI may be specified. The collation identified by $collationLiteral, while effectively based on the Unicode Collation Algorithm, has implementation-defined semantics.

If no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

The sequence must contain either simple values or nodes, not both. In addition, if the sequence contains simple values $srchParam must be a simple value and if the sequence contains nodes $srchParam must be a node. If the above conditions are violated, the function returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

If the value of $seqParam is the empty sequence, the empty sequence is returned.

The index is 1-based, not 0-based.

12.2.4.1 Examples
  • xf:index-of($seq, $item2) returns 2.

12.2.5 xf:empty

xf:empty(item* $srcval) => boolean

If the the value of $srcval is the empty sequence, the function returns true; otherwise, the function returns false.

12.2.5.1 Examples
  • xf:empty($seq) returns false.

12.2.6 xf:exists

xf:exists(item* $srcval) => boolean

If the the value of $srcval is not the empty sequence, the function returns true; otherwise, the function returns false.

12.2.6.1 Examples
  • xf:empty($seq) returns true.

12.2.7 xf:distinct-nodes

xf:distinct-nodes(node* $srcval) => node*

Returns the sequence that results from removing from $srcval all but one of a set of nodes that have the same identity as one another, based on node identity (that is, using node-equal()). The specific occurrence in a collection of identical nodes that is retained is implementation-dependent. If $srcval is the empty sequence, returns the empty sequence.

If the sequence contains one or more simple values, then the function returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

[Issue 154: Should we define a second order distinct function?]

12.2.7.1 Examples
  • xf:distinct-nodes($seq) returns $seq.

12.2.8 xf:distinct-values

xf:distinct-values(item* $srcval) => item*
xf:distinct-values(item* $srcval, anyURI $collationLiteral) => item*

$srcval must contain either simple values or nodes, not both. If the sequence contains both simple values and nodes, then the function returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

If $srcval contains only nodes, returns the sequence that results from removing from $srcval all but one of a set of nodes that are equal to one other, based on the nodes' values (that is, using deep-equal()). The specific node in a collection of nodes having equal values that is retained is implementation-dependent.

If $srcval contains only values, returns the sequence that results from removing from $srcval all but one of a set of values that are eq to one other. Values of the same type must have a total order: date/time values must either all contain a timezone or all not contain a timezone; duration values must all contain either only years and months or only days, hours, minutes and seconds. If this condition is not satisfied, the function returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model]. Equality of string values are determined according to the collation that is used. The specific node in a collection of values having equal values that is retained is implementation-dependent.

If $srcval is the empty sequence, returns the empty sequence.

If $collationLiteral is specified, then the value of $collationLiteral must identify a collation that is supported in the environment in which the function is invoked. Either an absolute URI or a relative URI may be specified. The collation identified by $collationLiteral, while effectively based on the Unicode Collation Algorithm, has implementation-defined semantics.

If no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

12.2.8.1 Examples
  • xf:distinct-values($seq) returns $seq.

12.2.9 xf:insert

xf:insert(item* $target, decimal $position, item* $inserts) => item*

Returns a new sequence constructed from the value of $target with the value of $inserts inserted at the position specified by the value of $position. (The value of $target is not affected by the sequence construction.)

Let the effective value of $position be N computed as cast as unsignedInt(floor($position)).

If N is less than zero, the effective value of N is zero. If N is greater than the number of items in $target, then the effective value of N is equal to the number of items in $target plus 1.

The value returned by the function consists of all items of $target whose index is less than or equal to N, followed by all items of $inserts, followed by the remaining elements of $target, in that sequence.

If $target is the empty sequence, a copy of $inserts is returned. If $inserts is the empty sequence, a copy of $target is returned.

12.2.10 xf:remove

xf:remove(item* $target, decimal $position) => item*

Returns a new sequence constructed from the value of $target with the item at the position specified by the value of $position removed.

Let the effective value of $position be N computed as cast as unsignedInt(floor($position)).

If N is less than 1 or greater than the number of items in $target, no action is taken. Otherwise, the value returned by the function consists of all items of $target whose index is less than N, followed by all items of $target whose index is greater than N. If $target is the empty sequence, the empty sequence is returned.

12.2.11 xf:subsequence

xf:subsequence(item* $sourceSeq, decimal $startingLoc) => item*
xf:subsequence(item* $sourceSeq, decimal $startingLoc, decimal $length) => item*

Returns the contiguous sequence of items in the value of $sourceSeq beginning at the position indicated by the value of $startingLoc and continuing for the number of items indicated by the value of $length.

If $length is not specified, then the subsequence includes items to the end of $sourceSeq.

The value of $length can be greater than the number of items in the value of $sourceSeq following the beginning position, in which case the subsequence includes items to the end of $length.

The first item of a sequence is located at position 1, not position 0.

If $sourceSeq is the empty sequence, returns the empty sequence.

12.2.11.1 Examples
  • xf:subsequence($seq, 4) returns ($item4, $item5, ...)

  • xf:subsequence($seq, 4, 2) returns ($item4, $item5)

12.3 Equals, Union, Intersection and Except

FunctionMeaningSource
xf:sequence-deep-equal Returns true if the two arguments have the same value. Data Model
xf:sequence-node-equal Returns true if the two arguments have the same nodes. Data Model
op:union Returns the union of the two sequence arguments, eliminating duplicates. XPath 2.0 Req 1.5 (Should)
op:intersect Returns the intersection of the two sequence arguments, eliminating duplicates. XPath 2.0 Req 1.5 (Should)
op:except Returns the difference of the two sequence arguments, eliminating duplicates. XPath 2.0 Req 1.5 (Should)

As in the previous sections, for the illustrative examples below, assume a XQuery operating on a Purchase Order document containing a number of item elements. The variables $item1, $item2, etc. are bound to individual item nodes in the sequence. We shall use sequences of these nodes in the examples below.

12.3.1 xf:sequence-deep-equal

xf:sequence-deep-equal(item* $parameter1, item* $parameter2) => boolean?
xf:sequence-deep-equal(item* $parameter1, item* $parameter2, anyURI $collationLiteral) => boolean?

If the sequences that are the values of $parameter1 and $parameter2 have the same values (that is, they have the same number of items and items in corresponding positions in the two sequences compare equal if they are values and deep-equal() if they are nodes.), then the function returns true; otherwise, the function returns false. Returns the empty sequence if one or both of its arguments is the empty sequence.

String values are compared according to the collation that is used.

If $collationLiteral is specified, then the value of $collationLiteral must identify a collation that is supported in the environment in which the function is invoked. Either an absolute URI or a relative URI may be specified. The collation identified by $collationLiteral, while effectively based on the Unicode Collation Algorithm, has implementation-defined semantics.

If no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

12.3.2 xf:sequence-node-equal

xf:sequence-node-equal(item*? $parameter1, item*? $parameter2) => boolean?

If the sequences that are the values of $parameter1 and $parameter2 have the same nodes as content (that is, they have the same number of items and items in corresponding positions in the two sequences are the identical nodes), then the function returns true; otherwise, the function returns false. Returns the empty sequence if one or both of its arguments is the empty sequence.

The sequences must contain only nodes. If either sequence contains both simple values and nodes, then the function returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

12.3.2.1 Examples

Assume $seq1 = ($item1, $item2), $seq2 = ($item1, $item2) and $seq3 = ($item2, $item3).

  • xf:sequence-node-equal($seq1, $seq2) returns true.

  • xf:sequence-node-equal($seq2, $seq3) returns false.

12.3.3 op:union

op:union(node* $parameter1, node* $parameter2) => node*

Constructs a sequence containing every node that occurs in the values of $parameter1 or $parameter2, eliminating duplicate nodes. Nodes are returned in document order. Two nodes are equal if they are xf:node-equal().

This function backs up the "union" or "|" operator.

12.3.3.1 Examples

Assume $seq1 = ($item1, $item2), $seq2 = ($item1, $item2) and $seq3 = ($item2, $item3).

  • op:union($seq1, $seq1) returns the sequence ($item1, $item2).

  • op:union($seq2, $seq3) returns the sequence consisting of ($item1, $item2, $item3).

12.3.4 op:intersect

op:intersect(node* $parameter1, node* $parameter2) => node*

Constructs a sequence containing every node that occurs in the values of both $parameter1 and $parameter2, eliminating duplicate nodes. Nodes are returned in document order.

If either operand is the empty sequence, the empty sequence is returned.

Two nodes are equal if they are xf:node-equal().

This function backs up the "intersect" operator.

12.3.4.1 Examples

Assume $seq1 = ($item1, $item2), $seq2 = ($item1, $item2) and $seq3 = ($item2, $item3).

  • op:intersect($seq1, $seq1) returns the sequence ($item1, $item2).

  • op:intersect($seq2, $seq3) returns the sequence ($item2).

12.3.5 op:except

op:except(node* $parameter1, node* $parameter2) => node*

Constructs a sequence containing every node that occurs in the values of $parameter1, but not in the value of $parameter2, eliminating duplicate nodes. Nodes are returned in document order.

If $parameter1 is the empty sequence, the empty sequence is returned. If $parameter2 is the empty sequence, a copy of $parameter1 is returned.

Two nodes are equal if they are xf:node-equal().

This function backs up the "except" operator.

12.3.5.1 Examples

Assume $seq1 = ($item1, $item2), $seq2 = ($item1, $item2) and $seq3 = ($item2, $item3).

  • op:except($seq1, $seq2) returns the empty sequence.

  • op:except($seq2, $seq3) returns the sequence ($item1).

This function backs up the except operator.

12.4 Aggregate Functions

Aggregate functions take a sequence as argument and return a single value computed from values in the sequence. Except for xf:count, if the sequence contains nodes, the value is extracted from the node and used in the computation.

FunctionMeaningSource
xf:count Returns the number of items in the sequence. XPath 1.0
xf:avg Returns the average of a sequence of numbers. XSLT 2.0 Req. 1.4 (Must)
xf:max Returns the object with maximum value from a collection of comparable objects. XSLT 2.0 Req. 1.4 (Must)
xf:min Returns the object with minimum value from a collection of comparable objects. XSLT 2.0 Req. 1.4 (Must)
xf:sum Returns the sum of a sequence of numbers. XSLT 1.0

12.4.1 xf:count

xf:count(item* $srcval) => unsignedInt

Returns the number of items in the value of $srcval. Returns 0 if $srcval is the empty sequence.

[Issue 67: Should duplicates be eliminated for count() and sum()?]

12.4.1.1 Examples

Assume $seq1 = ($item1, $item2) and $seq3 = (), the empty sequence.

  • xf:count($seq1) returns 2.

  • xf:count($seq3) returns 0.

12.4.2 xf:avg

xf:avg(item* $srcval) => double?

If $srcval contains nodes, the value of each node is extracted using the xf:data() function. Values that equal the empty sequence are discarded. If after this, $srcval contains only numbers, xf:avg() returns the average of the numbers (computed as sum($srcval) div count($srcval)). If $srcval is the empty sequence, the empty sequence is returned.

If, after extracting the values from nodes, $srcval does not contain only numbers, the function returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

12.4.2.1 Examples

Assume $seq1 = ($item1, $item2) and $seq3 = (3, 4, 5).

  • xf:avg($seq3) returns 4.0.

  • xf:avg($seq1) returns an error.

12.4.3 xf:max

xf:max(item* $srcval) => anySimpleType?
xf:max(item* $srcval, anyURI $collationLiteral) => anySimpleType?

If $srcval contains nodes, the value of each node is extracted using the xf:data() function. Values that equal the empty sequence are discarded. If, after this, $srcval is the empty sequence, the empty sequence is returned. After extracting the values from nodes, $srcval must contain only values of a single type. (For numeric values, the type promotion rules defined in 3.3 Operators on Numeric Values can be used to promote them to a single type.) In addition, the values in the sequence must have a total order: date/time values must either all contain a timezone or all not contain a timezone; duration values must all contain either only years and months or only days, hours, minutes and seconds. If either of these conditions is not true, the function returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

xf:max returns the item in the value of $srcval whose value is greater than the value of every other item in the value of $srcval. If there are two or more such items, then the specific item whose value is returned is implementation-dependent.

If the items in the value of $srcval are strings, then the determination of the greatest item is made according to the collation that is used.

If $collationLiteral is specified, then the value of $collationLiteral must identify a collation that is supported in the environment in which the function is invoked. Either an absolute URI or a relative URI may be specified. The collation identified by $collationLiteral, while effectively based on the Unicode Collation Algorithm, has implementation-defined semantics.

If no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

12.4.3.1 Examples

Assume $seq1 = (3, 4, 5).

  • xf:max($seq1) returns 5.

12.4.4 xf:min

xf:min(item* $srcval) => anySimpleType?
xf:min(item* $srcval, anyURI $collationLiteral) => anySimpleType?

If $srcval contains nodes, the value of each node is extracted using the xf:data() function. Values that equal the empty sequence are discarded. If, after this, $srcval is the empty sequence, the empty sequence is returned. After extracting the values from nodes, $srcval must contain only values of a single type. (For numeric values, the type promotion rules defined in 3.3 Operators on Numeric Values can be used to promote them to a single type.) In addition, the values in the sequence must have a total order: date/time values must either all contain a timezone or all not contain a timezone; duration values must all contain either only years and months or only days, hours, minutes and seconds. If either of these conditions is not true, the function returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

xf:min returns the item in the value of $srcval whose value is less than the value of every other item in the value of $srcval. If there are two or more such items, then the specific item whose value is returned is implementation-dependent.

If the items in the value of $srcval are strings, then the determination of the least item is made according to the collation that is used.

If $collationLiteral is specified, then the value of $collationLiteral must identify a collation that is supported in the environment in which the function is invoked. Either an absolute URI or a relative URI may be specified. The collation identified by $collationLiteral, while effectively based on the Unicode Collation Algorithm, has implementation-defined semantics.

If no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

12.4.4.1 Examples

Assume $seq1 = (3, 4, 5).

  • xf:min($seq1) returns 3.

12.4.5 xf:sum

xf:sum(item* $srcval) => double

If $srcval contains nodes, the value of each node is extracted using the xf:data() function. Values that equal the empty sequence are discarded. If, after this, $srcval contains only numbers, xf:sum() returns the sum of the numbers. If it is the empty sequence, 0.0 is returned.

If, after extracting the values from nodes, $srcval does not contain only numbers, the function returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

[Issue 67: Should duplicates be eliminated for count() and sum()?]

12.4.5.1 Examples

Assume $seq1 = ($item1, $item2) and $seq3 = (3, 4, 5).

  • xf:sum($seq1) returns an error.

  • xf:sum($seq3) returns 12.0.

12.5 Functions that Generate Sequences

FunctionMeaningSource
xf:id Returns the sequence of nodes having unique IDs that match the IDREFs represented by the argument sequence. XPath 1.0
xf:idref Returns the sequence of nodes with IDREFs matching the items in the argument sequence. XSLT 2.0 Req. 2.11 (Could)
xf:filter Returns a shallow copy of the nodes that are selected by the expression argument, preserving any relationships that exist among these nodes.XQuery
xf:document Returns a sequence of document nodes retrieved using the URIs specified in its arguments.XSLT 1.0
xf:collection Returns a sequence of document nodes retrieved using the URI specified as its argument.
xf:input Returns the input sequence.

12.5.1 xf:id

xf:id(IDREF* $srcval) => elementNode*

Returns the sequence of element nodes with ID values matching the value of one of the IDREFs in the sequence argument. If the value of $srcval is a single IDREF, it behaves as though a sequence of length one was supplied.

The nodes that are returned all belong to the context document. See 13.4 op:context-document. If the context document is not specified the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model] is returned. If the context document is the empty sequence, returns the empty sequnce.

[Issue 168: For compatibility with the XPath 1.0 function of the same name, xf:id() should accept a list of strings.]

12.5.2 xf:idref

xf:idref(string* $srcval) => elementNode*

Returns the sequence of element nodes with an IDREF value matching the value of one of the items in the sequence argument or an IDREFS value containing an IDREF matching the value of one of the items in the sequence argument. If the value of $srcval is a single string, it behaves as though a sequence of length one of strings was supplied. This function allows reverse navigation from IDs to IDREFs.

The nodes that are returned all belong to the context document. See 13.4 op:context-document. If the context document is not specified the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model] is returned. If the context document is the empty sequence, returns the empty sequence.

12.5.3 xf:filter

xf:filter(expression $srcval) => node*

The filter function returns a sequence of nodes containing shallow copies of the nodes that are selected by expression that is the value of $srcval, preserving any relationships that exist among these nodes.

[Issue 167: Semantics of xf:filter are underspecified and, perhaps, incorrect.]

12.5.3.1 Examples
  • Suppose that the argument to filter is a path expression that selects nodes X, Y, and Z from some document. Suppose that, in the original document, nodes Y and Z are descendants (at any level) of node X. Then the result of filter is a copy of node X, with copies of nodes Y and Z as its immediate children. Any other intervening nodes from the original document are not includeed in the result. The name filter suggests a function that operates on a document to extract the parts that are of interest and discard the remainder, while retaining the structure of the original document.

12.5.4 xf:document

xf:document(anyURI* $srcval1) => node*
xf:document(anyURI* $srcval1, node* $srcval2) => node*

It is a dynamic error if $srcval2 is the empty sequence, or a sequence whose first item is not a node, unless all the URIs in $srcval1 are absolute URIs. If $srcval2 is a sequence of more than one node, the effect is as if only the first node in the sequence were supplied.

The result of the document function can be explained in terms of an internal primitive function one-doc which takes a requested URI and a base URI as arguments, and returns a node sequence as its result. The result of the document function is the union of the node sequences obtained by calling one-doc once for each member of $srcval1.

The one-doc function retrieves a document using a request URI R and a base URI B.

For a member of $srcval1 that is a node N, the one-doc function is called with the string-value of N as the request URI, and with a base URI that is the base URI of $srcval2 if $srcval2 is supplied, or the base URI of N otherwise.

For a member of the $srcval1 that is a simple value, the one-doc function is called using a request URI obtained by converting that simple value to a string as if by using the string function, and a base URI that is the base URI of arg2 if arg2 was supplied, or the base URI of the stylesheet element containing the call to the document function otherwise.

The internal one-doc function operates as follows.

The resource identified by the URI is retrieved. The data resulting from the retrieval action is parsed as an XML document and a tree is constructed in accordance with the [XQuery 1.0 and XPath 2.0 Data Model]. An error retrieving the resource , is classed as a dynamic error. The processor must either signal the error, or must recover by returning an empty sequence. One possible kind of retrieval error is that the implementation does not support the URI scheme used by the URI. An implementation is not required to support any particular URI schemes. The documentation for an implementation should specify which URI schemes the implementation supports.

If the URI reference does not contain a fragment identifier, then the document node of the document is returned. If the URI reference does contain a fragment identifier, the function returns a node sequence containing the nodes in the tree identified by the fragment identifier of the URI reference. The semantics of the fragment identifier are dependent on the media type of the result of retrieving the URI. An error in processing the fragment identifier is classed as a dynamic error; The processor must either signal the error, or must recover by returning an empty sequence. Possible errors include:

  • The fragment identifier identifies something that cannot be represented by a node sequence (such as a range of characters within a text node).

  • The implementation does not support fragment identifiers for the media-type of the retrieval result. An implementation is not required to support any particular media types. The documentation for an implementation should specify for which media types the implementation supports fragment identifiers.

The data resulting from the retrieval action is parsed as an XML document regardless of the media type of the retrieval result; if the top-level media type is text, then it is parsed in the same way as if the media type were text/xml; otherwise, it is parsed in the same way as if the media type were application/xml.

12.5.5 xf:collection

xf:collection(string $srcval) => node*

Takes a string as argument and returns a sequence of nodes obtained by casting $srcval to anyURI and resolving it. Returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model] if $srcval is not in the lexical space of anyURI or if the value, after casting, does not resolve to a collection.

12.5.6 xf:input

xf:input() => node*

Returns the input sequence. Returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model] if no input sequence has been assigned. The means by which an input sequence is assigned depends on the environment.

13 Context Functions

The following functions are defined to obtain information from the evaluation context.

FunctionMeaningSource
xf:context-item Returns the context item.XPath 1.0
xf:position Returns the position of the context item within the sequence of items currently being processed.XPath 1.0
xf:last Returns the number of items in the sequence of items currently being processed.XPath 1.0
op:context-document Returns the source document currently being processed.XPath 1.0
xf:current-dateTime Returns the current dateTime.XPath 1.0

13.1 xf:context-item

xf:context-item() => item

Returns the context item i.e. the item currently being processed.

13.2 xf:position

xf:position() => unsignedInt

Returns an unsignedInt indicating the position of the context item within the sequence of items currently being processed.

13.3 xf:last

xf:last() => unsignedInt

Returns an unsignedInt indicating the number of items in the sequence of items currently being processed.

13.4 op:context-document

op:context-document() => DocumentNode

Returns a document node indicating the source document being processed. If the context document is not specified, returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model]. If the context document is the empty sequence, returns the empty sequence. This function backs up the "/" operator.

13.5 xf:current-dateTime

xf:current-dateTime() => dateTime

Returns the dateTime that is current at some time during the evaluation of the XQuery or XPath expression in which current-dateTime() is executed. All invocations of current-dateTime() that are executed during the course of a single outermost XQuery or XPath expression return the same value. The precise instant during that XQuery or Xpath expression's evaluation represented by the value of current-dateTime() is implementation-defined.

[Issue 165: What timezone should be returned by the current-dateTime function?]

[Issue 166: Do we need convenience functions to supplement current-dateTime?]

13.5.1 Examples

  • xf:current-dateTime() returns a dateTime corresponding to the current date and time.

14 Casting Functions

Cast functions or cast operators take an expression as their argument and return a value of a given type. There are two basic differences from constructor: casting takes an expression rather than a literal as argument, and validity checking is done at run time rather than at compile time.

This specification starts by defining casting between the 19 primitive types defined in [XML Schema Part 2: Datatypes]. The type conversions that are supported are indicated in the table below. In this table, there is a row for each primitive with that type as the source of the conversion and there is a column for each primitive type as the target of the conversion. The intersections of rows and columns contain one of three characters: "Y" indicates that a conversion from values of the type to which the row applies to the type to which the column applies is supported; "N" indicates that there are no supported conversions from values of the type to which the row applies to the type to which the column applies; and "M" indicates that a conversion from values of the type to which the row applies to the type to which the column applies may be supported, subject to restrictions dicsussed in this section.

In the following tables, the columns and rows are identified by short codes that identify simple types as follows:

aURI = anyURI
b64 = base64Binary
bool = boolean
dat = date
Day = gDay
dbl = double
dec = decimal
dT = dateTime
dur = duration
flt = float
hxB = hexBinary
MD = gMonthDay
Mon = gMonth
NOT = NOTATION
QN = Qname
str = string
tim = time
YM = gYearMonth
Yr = gYear

In each of the following tables, the notation "S\T" indicates that the source ("S") of the conversion is indicated in the column below the notation and that the target ("T") is indicated in the row to the right of the notation.

14.1 Casting to primitive types from primitive types

The following table covers casting from primitive types to primitive types.

S\TstrfltdbldecdurdTtimdatYMYrMDDayMonBoolb64hxBaURIQNNOT
strYMMMMMMMMMMMMMNNMMN
fltYYYMNNNNNNNNNMNNNNN
dblYYYMNNNNNNNNNMNNNNN
decYYYYNNNNNNNNNMNNNNN
durYNNNYNNNNNNNNNNNNNN
dTYNNNNYNNNNNNNNNNNNN
timYNNNNNYNNNNNNNNNNNN
datYNNNNNNYYNNNNNNNNNN
YMYNNNNNNNYNNNNNNNNNN
YrYNNNNNNNNYNNNNNNNNN
MDYNNNNNNNNNYNNNNNNNN
DayYNNNNNNNNNNYNNNNNNN
MonYNNNNNNNNNNNYNNNNNN
boolYYYYNNNNNNNNNYNNNNN
b64YNNNNNNNNNNNNMYNNNN
hxBYMMMNNNNNNNNNMNYMNN
aURIYNNNNNNNNNNNNNNNYNN
QNYNNNNNNNNNNNNNNNNYN
NOTYNNNNNNNNNNNNNNNNNY

14.2 Casting from derived types to primitive types

Casting from a derived type to its base type is always permitted. No other casting from a derived type is supported.

14.3 Casting to string

Casting is permitted from any primitive to the primitive type string.

  1. When a value of any simple type is cast to string, the derivation of the string value TV depends on the source type ST and on the source value SV, as follows.

    • If ST is string, TV is SV.

    • If ST is float, double, or decimal then TV is the canonical representation of SV, as defined by [XML Schema Part 2: Datatypes].

    • If ST is duration, then TV is the lexical representation of SV, as defined by [XML Schema Part 2: Datatypes], in which each integer and decimal component is expressed in its canonical representation.

    • If ST is dateTime or time, then TV is the canonical representation of SV, as defined by [XML Schema Part 2: Datatypes].

    • If ST is date, gYearMonth, gYear, gMonthDay, gDay, or gMonth, then TV is the lexical representation of SV, as defined by [XML Schema Part 2: Datatypes].

    • If ST is boolean, then TV is "true" if SV is true and "false" if SV is false.

    • If ST is hexBinary, then TV is the canonical representation of SV, as defined by [XML Schema Part 2: Datatypes].

    • If ST is anyURI, then TV is the lexical representation of SV, as defined in [XML Schema Part 2: Datatypes], with each space replaced by the sequence "%20".

    • If ST is QName or NOTATION, then TV is SV.

14.4 Casting to numeric types

As specified in the preceding table, conversion from various simple types to the various numeric types (that is, float, double and decimal depends on factors considered below.

  1. When a value of any simple type is cast to float, the float value TV is derived from the source type ST and the source value SV as follows:

    • If ST is float, then TV is SV and the conversion is complete.

    • If ST is double and SV cannot be represented in the value space of float as defined in [XML Schema Part 2: Datatypes], then the cast returns NaN..

    • If ST is double and SV can be represented in the value space of float as defined in [XML Schema Part 2: Datatypes], then TV is SV and the conversion is complete.

    • If ST is decimal or a type derived from decimal, then TV is xf:float(cast as string( SV )) and the conversion is complete.

    • If ST is boolean, SV is converted to 1.0 if SV is 1 or true and 0.0 if SV is 0 or false and the conversion is complete.

    • SV is converted to an intermediate value IV of type token.

    • If the value of xf:upper-case( IV ) is INF, -INF, or NAN, then TV is positive infinity, negative infinity, or not-a-number, respectively, and the conversion is complete.

    • If IV does not match the lexical structure of NumericLiteral as defined in [XQuery 1.0: An XML Query Language], then the cast returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

    • Otherwise, let NL be a NumericLiteral comprising the same sequence of characters as IV. TV is xf:float( NL ).

  2. When a value of any simple type is cast to double, the double value TV is derived from the source type ST and the source value SV as follows:

    • If ST is double, then TV is SV and the conversion is complete.

    • If ST is float or decimal or types derived from them, then TV is xf:double(cast as string( SV )) and the conversion is complete.

    • If ST is boolean, SV is converted to 1.0 if SV is 1 or true and 0.0 if SV is 0 or false and the conversion is complete.

    • SV is converted to an intermediate value IV of type token.

    • If the value of xf:upper-case( IV ) is INF, -INF, or NAN, then TV is positive infinity, negative infinity, or not-a-number, respectively, and the conversion is complete.

    • If IV does not match the lexical structure of NumericLiteral as defined in [XQuery 1.0: An XML Query Language], then the cast returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

    • Otherwise, let NL be a NumericLiteral comprising the same sequence of characters as IV. TV is xf:double( NL ).

  3. When a value of any simple type is cast to decimal, the decimal value TV is derived from the source type ST and the source value SV as follows:

    • If ST is decimal, or a type derived from decimal, then TV is decimal(cast as string( SV )) and the conversion is complete.

    • If ST is float or double, then TV is decimal(cast as string(xf:round( SV ))) and the conversion is complete.

    • If ST is boolean, SV is converted to 1.0 if SV is 1 or true and 0.0 if SV is 0 or false and the conversion is complete.

    • SV is converted to an intermediate value IV of type token.

    • If IV does not match the lexical structure of NumericLiteral as defined in [XQuery 1.0: An XML Query Language], then the cast returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

    • Otherwise, let NL be a NumericLiteral comprising the same sequence of characters as IV. TV is decimal(cast as string(xf:round( NL ))).

14.5 Casting to duration and date and time types

Conversion from primitive types to duration and date and time types depends on factors considered below.

  1. When a value of any primitive type is cast to duration, the duration value TV is derived from the source type ST and the source value SV as follows:

    • If ST is duration, then TV is SV.

    • If ST is string or a type derived from string, then TV is xf:duration(cast as string( SV )).

  2. When a value of any primitive type is cast to dateTime, time, date, gYearMonth, gYear, gMonthDay, gDay, or gMonth, let CYR be cast as string( xf:get-Year( xf:currentDateTime() ) ), let CMO be cast as string( xf:get-month( xf:currentDateTime() ) ), and let CDA be cast as string( xf:get-day( xf:currentDateTime() ) ).

  3. When a value of any primitive type is cast to dateTime, the dateTime value TV is derived from the source type ST and the source value SV as follows:

    • If ST is dateTime, then TV is SV.

    • If ST is time, then let SHR be cast as string( xf:get-hour( SV ) ), let SMI be cast as string( xf:get-minute( SV ) ), and let SSE be cast as string( xf:get-second( SV ) ); TV is xf:dateTime( xf:concat( CYR , '-', CMO , '-', CDA , 'T', SHR , ':', SMI , ':', SSE ) ).

    • If ST is date, then let SYR be cast as string( xf:get-Year( SV ) ), let SMO be cast as string( xf:get-month( SV ) ), and let SDA be cast as string( xf:get-day( SV ) ); TV is xf:dateTime( xf:concat( SYR , '-', SMO , '-', SDA , 'T00:00:00') ).

    • If ST is gYearMonth, then let SYR be cast as string( xf:get-Year( SV ) ) and let SMO be cast as string( xf:get-month( SV ) ); TV is xf:dateTime( xf:concat( SYR , '-', SMO , '-01T00:00:00') ).

    • If ST is gYear, then let SYR be cast as string( xf:get-Year( SV ) ); TV is xf:dateTime( xf:concat( SYR , '-01-01T00:00:00') ).

    • If ST is gMonthDay, then let SMO be cast as string( xf:get-month( SV ) ) and let SDA be cast as string( xf:get-day( SV ) ); TV is xf:dateTime( xf:concat( CYR , '-', SMO , '-', SDA , 'T00:00:00') ).

    • If ST is gDay, then let SDA be cast as string( SV ); TV is xf:dateTime( xf:concat( CYR , '-', CMO , '-', SDA , 'T00:00:00') ).

    • If ST is gMonth, then let SMO be cast as string( SV ); TV is xf:dateTime( xf:concat( CYR , '-', SMO , '-01T00:00:00') ).

    • If ST is string or a type derived from string and SV is not a valid lexical representation for dateTime as specified in [XML Schema Part 2: Datatypes], then the cast returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

    • If ST is string or a type derived from string and SV is a valid lexical representation for dateTime as specified in [XML Schema Part 2: Datatypes], then TV is xf:dateTime( SV ).

  4. When a value of any primitive type is cast to time, the time value TV is derived from the source type ST and the source value SV as follows:

    • If ST is time, then TV is SV.

    • If ST is dateTime, then TV is xf:time( xf:concat( cast as string( xf:get-hour( SV ) ), ':', cast as string( xf:get-minute( SV ) ), ':', cast as string( xf:get-second( SV ) ) ) ).

    • If ST is string or a type derived from string and SV is a valid lexical representation for time as specified in [XML Schema Part 2: Datatypes], then TV is xf:time( SV ).

  5. When a value of any primitive type is cast to date, the date value TV is derived from the source type ST and the source value SV as follows:

    • If ST is dateTime, then let SYR be cast as string( xf:get-Year( SV ) ), let SMO be cast as string( xf:get-month( SV ) ), and let SDA be cast as string( xf:get-day( SV ) ); TV is xf:dateTime( xf:concat( SYR , '-', SMO , '-', SDA ) ).

    • If ST is date, then TV is SV.

    • If ST is gYearMonth, then let SYR be cast as string( xf:get-Year( SV ) ) and let SMO be cast as string(xf:get-month( SV ) ); TV is xf:dateTime( xf:concat( SYR , '-', SMO , '-01') ).

    • If ST is gYear, then let SYR be cast as string( xf:get-Year( SV ) ); TV is xf:dateTime( xf:concat( SYR , '-01-01') ).

    • If ST is gMonthDay, then let SMO be cast as string( xf:get-month( SV ) ) and let SDA be cast as string( xf:get-day( SV ) ); TV is xf:dateTime( xf:concat( CYR , '-', SMO , '-', SDA ) ).

    • If ST is gDay, then let SDA be cast as string( SV ); TV is xf:dateTime( xf:concat( CYR , '-', CMO , '-', SDA ) ).

    • If ST is gMonth, then let SMO be cast as string ( SV ); TV is xf:dateTime( xf:concat( CYR , '-', SMO , '-01') ).

    • If ST is string or a type derived from string and SV is not a valid lexical representation for date as specified in [XML Schema Part 2: Datatypes], then the cast returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

    • If ST is string or a type derived from string and SV is a valid lexical representation for date as specified in [XML Schema Part 2: Datatypes], then TV is xf:date( SV ).

  6. When a value of any primitive type is cast to gYearMonth, the gYearMonth value TV is derived from the source type ST and the source value SV as follows:

    • If ST is dateTime or date, then let SMO be cast as string( xf:get-month( SV ) ) and let SDA be cast as string( xf:get-day( SV ) ); TV is xf:gYearMonth( xf:concat( SMO , '-', SDA ) ).

    • If ST is gYearMonth, then TV is SV.

    • If ST is gYear, then let SYR be cast as string( xf:get-Year( SV ) ); TV is xf:dateTime( xf:concat( SYR , '-01') ).

    • If ST is gMonthDay or gMonth, then let SMO be cast as string( xf:get-month( SV ) ); TV is xf:dateTime( xf:concat( CYR , '-', SMO ) ).

    • If ST is string or a type derived from string and SV is not a valid lexical representation for gYearMonth as specified in [XML Schema Part 2: Datatypes], then the cast returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

    • If ST is string or a type derived from string and SV is a valid lexical representation for gYearMonth as specified in [XML Schema Part 2: Datatypes], then TV is xf:date( SV ).

  7. When a value of any primitive type is cast to gYear, the gYear value TV is derived from the source type ST and the source value SV as follows:

    • If ST is dateTime, date, or gYearMonththen let SYR be cast as string( xf:get-Year( SV ) ); TV is xf:gYear( SYR ).

    • If ST is gYearMonth, then TV is SV.

    • If ST is string or a type derived from string and SV is not a valid lexical representation for gYear as specified in [XML Schema Part 2: Datatypes], then the cast returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

    • If ST is string or a type derived from string and SV is a valid lexical representation for gYear as specified in [XML Schema Part 2: Datatypes], then TV is xf:date( SV ).

  8. When a value of any primitive type is cast to gMonthDay, the gMonthDay value TV is derived from the source type ST and the source value SV as follows:

    • If ST is dateTime or date, then let SMO be cast as string( xf:get-month( SV ) ) and let SDA be cast as string( xf:get-day( SV ) ); TV is xf:gYearMonth( xf:concat( SMO , '-', SDA ) ).

    • If ST is gYearMonth, then let SMO be cast as string( xf:get-month( SV ) ); TV is xf:dateTime( xf:concat( SMO , '-01') ).

    • If ST is gMonthDay, then TV is SV.

    • If ST is gDay, then let SDA be cast as string( xf:get-day( SV ) ); TV is xf:dateTime( xf:concat( CMO , CDA ) ).

    • If ST is gMonth, then let SMO be cast as string( xf:get-month( SV ) ); TV is xf:dateTime( xf:concat( SMO , '-01') ).

    • If ST is string or a type derived from string and SV is not a valid lexical representation for gMonthDay as specified in [XML Schema Part 2: Datatypes], then the cast returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

    • If ST is string or a type derived from string and SV is a valid lexical representation for gMonthDay as specified in [XML Schema Part 2: Datatypes], then TV is xf:date( SV ).

  9. When a value of any primitive type is cast to gDay, the gDay value TV is derived from the source type ST and the source value SV as follows:

    • If ST is dateTime, date, or gMonthDay, then let SDA be cast as string( xf:get-day( SV ) ); TV is xf:gDay( SDA ).

    • If ST is gDay, then TV is SV.

    • If ST is string or a type derived from string and SV is not a valid lexical representation for gDay as specified in [XML Schema Part 2: Datatypes], then the cast returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

    • If ST is string or a type derived from string and SV is a valid lexical representation for gDay as specified in [XML Schema Part 2: Datatypes], then TV is xf:date( SV ).

  10. When a value of any primitive type is cast to gMonth, the gMonth value TV is derived from the source type ST and the source value SV as follows:

    • If ST is dateTime, date, gYearMonth, or gMonthDay, then let SMO be cast as string( xf:get-month( SV ) ); TV is xf:gMonth( SMO ).

    • If ST is gMonth, then TV is SV.

    • If ST is string or a type derived from string and SV is not a valid lexical representation for gMonth as specified in [XML Schema Part 2: Datatypes], then the cast returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

    • If ST is string or a type derived from string and SV is a valid lexical representation for gMonth as specified in [XML Schema Part 2: Datatypes], then TV is xf:date( SV ).

14.6 Casting to boolean

When a value of any primitive type is cast to boolean, the boolean value TV is derived from the source type ST and the source value SV as follows:

  • If ST is string and xf:upper-case( SV ) is " TRUE " or " 1 ", then TV is true; if ST is string and xf:upper-case( SV ) is " FALSE " or " 0 ", then TV is false.

  • If ST is float, double, decimal and SV is 0, +0, -0 or NaN then TV is false.

  • If ST is float, double, decimal and SV is not one of the above values then TV is true.

  • If ST is boolean, then TV is SV.

  • If ST is base64Binary or hexBinary and SV is " 1 ", then TV is true; if ST is base64Binary or hexBinary and SV is " 0 ", then TV is false.

  • Otherwise, the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

14.7 Casting to base64Binary, hexBinary

Casting from any other simple type to base64Binary and hexBinary is not supported.

14.8 Casting to anyURI, QName and NOTATION

Casting to anyURI, or QName is possible only from the same type or possibly from string.

  1. When a value of any primitive type is cast to anyURI, the anyURI value TV is derived from the source type ST and the source value SV as follows:

  2. When a value of any primitive type is cast to QName, the QName value TV is derived from the source type ST and the source value SV as follows:

  3. It is not possible to cast values of any other type to NOTATION because the validity of a NOTATION value is context dependent and cannot, in general, be determined.

A References

A.1 Normative

IEEE 754-1985
IEEE. IEEE Standard for Binary Floating-Point Arithmetic. See http://standards.ieee.org/reading/ieee/std_public/description/busarch/754-1985_desc.html
Character Model for the World Wide Web 1.0
Character Model for the World Wide Web 1.0. Available at: http://www.w3.org/TR/charmod/
SQL
ISO (International Organization for Standardization). ISO/IEC 9075-2:1999, Information technology --- Database languages --- SQL --- Part 2: Foundation (SQL/Foundation). [Geneva]: International Organization for Standardization, 1999. See http://www.iso.ch/cate/d26197.html
Unicode Case Mappings
Unicode Technical Standard #21, Unicode Case Mappings. Available at: http://www.unicode.org/unicode/reports/tr21/
Unicode Collation Algorithm
Unicode Technical Standard #10, Unicode Collation Algorithm Available at: http://www.unicode.org/unicode/reports/tr10/
XML Information Set
World Wide Web Consortium. XML Information Set. Available at: http://www.w3.org/TR/xml-infoset/
XML Pointer Language
World Wide Web Consortium. XML Pointer Language (XPointer). Available at: http://www.w3.org/TR/xptr/
XML 1.0 Recommendation (Second Edition)
World Wide Web Consortium. Extensible Markup Language (XML) 1.0, Second Edition. Available at: http://www.w3.org/TR/2000/WD-xml-2e-20000814
XPath 1.0
World Wide Web Consortium. XML Path Language (XPath) Version 1.0. Available at: http://www.w3.org/TR/xpath
XPath 2.0
World Wide Web Consortium. XML Path Language (XPath) Version 2.0. Available at: http://www.w3.org/TR/xpath20
XSLT 1.0
World Wide Web Consortium. XSL Transformations Version 1.0. Available at: http://www.w3.org/TR/xslt
XSLT 2.0
World Wide Web Consortium. XSL Transformations Version 2.0. Available at: http://www.w3.org/TR/xslt20
XQuery 1.0 and XPath 2.0 Data Model
World Wide Web Consortium. XQuery 1.0 and XPath 2.0 Data Model. Available at: http://www.w3.org/TR/query-datamodel/
XQuery 1.0 Formal Semantics
World Wide Web Consortium. XQuery 1.0 Formal Semantics. Available at: http://www.w3.org/TR/query-semantics/
XQuery 1.0: An XML Query Language
World Wide Web Consortium. XQuery 1.0: An XML Query Language. Available at: http://www.w3.org/TR/xquery/
XML Schema Part 1: Structures
XML Schema Part 1: Structures. Available at: http://www.w3.org/TR/xmlschema-1/
XML Schema Part 2: Datatypes
XML Schema Part 2: Datatypes. Available at: http://www.w3.org/TR/xmlschema-2/
Namespaces in XML
Namespaces in XML. Available at: http://www.w3.org/TR/1999/REC-xml-names-19990114/

A.2 Non-normative

ISO 8601
ISO (International Organization for Standardization). Representations of dates and times, 2000-08-03. Available from: http://www.iso.ch/

B Functions and Operators Issues List (Non-Normative)

This section contains the current issues related to the operators specification.

Issue 14: Some function signatures are unclear about argument types (operator-function-signatures)

Originator: Operators Task Force F2F 2001-03-21
Locus: Syntax

Description:

A function signature like "make_string(string)" is misleading since it implies that the argument might have to be of most specific type "string" as opposed to IDREF. This document must make it clear that other types (e.g., subtypes of "string", or derived types derived from "string", such as "token" are acceptable. Question arose about whether there should also be a version of "make-string" with a "number" argument, as opposed (or in addition to) to explicit and/or implicit "cast" functions. The intent is to have "make-string(string)" only for symmetry, not to allow for subtypes.

Resolution:

None recorded.

This issue occurs in 4.2 String Constructors

Issue 16: Is a constructor more than a different syntax for CAST? (operator-constructor-value)

Originator: Operators Task Force F2F 2001-03-21. Reopened due to Michael Rys (member-only message)
Locus: Syntax

Description:

Several participants feel that there are three sorts of ways to "create" values of various types: (1)literals, (2)constructors, and (3)casting. There seems to be broad agreement on (1) and (3), but there are questions about the "meaning" of (2).

In particular, are constructors really functions, or do they use functional notation without actually being functions? If they are actual functions, it would appear that their function bodies are unlikely to be much more than a CAST. That sheds some doubt on the requirement to have constructor functions.

Resolution:

There is much similarity between constructors and casting, but there appears to be sufficient value in distinguishing them. Therefore, the constructors will be retained. See for more information.

This issue occurs in

Issue 20: Many uses of "character" should be "codepoint" (operator-codepoint-vs-character)

Originator: Operators Task Force F2F 2001-03-21
Locus: Syntax

Description:

Many uses of the word "character" in this specification would probably be better if changed to "codepoint" to make it clear precisely what Unicode concept is meant.

Resolution:

None recorded.

This issue occurs in 4.4.1 Usage Notes

Issue 21: What is the precise type returned by each function? (operator-function-return-types)

Originator: Operators Task Force F2F 2001-03-21
Locus: Syntax

Description:

What is the precise type returned by various functions? Is the specific type of the argument the returned type, or does it get "upcast" to "string"? Some operations might not be able to keep the most specific type (e.g., SUBSTRING(NCNAME,2) may not be a NCNAME!)

Resolution:

None recorded.

This issue occurs in 4.4 Functions on String Values

Issue 23: "Returns a copy" is not appropriate wording (operator-copy-returns)

Originator: Operators Task Force F2F 2001-03-21
Locus: Syntax

Description:

Currently, the specification uses the phrase "...returns a copy" in several locations. That phrase is not appropriate and the wording should be changed to accurately describe the intended semantics.

Resolution:

None recorded.

This issue occurs in 4.4 Functions on String Values

Issue 37: Linguistic contains required? (semantic-contains)

Originator: Michael Kay (member only message)
Locus: Syntax

Description:

Perhaps we need a "linguistic contains" as in free text searching, e.g. contains-word(., "England"). Would we then want to define the word-breaking, stemming, and matching rules, or leave it to the implementor? See also the Library of Congress Use Cases in e-mail: (member-only message)

Resolution:

None recorded.

This issue occurs in 4.4 Functions on String Values

Issue 44: Collations: URIs and URI references or short names? (operator-collation-specification)

Originator: Michael Sperberg-McQueen
Locus: Syntax

Description:

In a presentation at the July, 2001 F2F, it was said that collations would be referred to by URI references. Michael Rys said one rationale is to allow relative URI(-reference)s so one can refer to "French" rather than http://www.example.com/i18n/collation-sequences/case-sensitive/French, and so on. There may be negative impacts on the interoperability results caused by allowing relative URI referneces for this function. It is tempting to suggest requiring collation names to be absolute URIs without fragment identifiers. If brevity is really important, perhaps we should invent a way to assign short names to collations. See, also, issue 70.

Issue resulted from e-mail: Michael Sperberg-McQueen (member-only message)

Resolution:

None recorded.

This issue occurs in 4.3 Equality and Comparison of Strings

Issue 47: Should the design of the date (and time) functions be such that they could be generalized to full I18N support and what level of I18N support should be included in version 1.0? (operator-datetime-internationalization)

Originator: Anders Berglund
Locus: Syntax

Description:

The requirement is to have an underlying design that permits (either in version 1.0, or at least permits a natural extension to) supporting:

  • Converting a "date" to a string in a non-Gregorian calendar.

  • Converting a string, in an appropriate format for a non Gregorian calendar, to a "date".

  • Comparisons of "dates" where the XML has these expressed in non-Gregorian calendar(s).

  • The range of supported calendars should probably be left to the implementation.

A possible design approach could be to:

  • Keep the schema/ISO-8601 date as the "hub" datatype.

  • Change some of the existing constructors by adding a "calendar" parameter, which would default to Gregorian.

  • Add some "date" to string functions for presenting non-Gregorian calendar dates.

A comparison of, say, two BE years would be achieved by

-- Year("2544", "BE") > Year("2540", "BE")

Naturally there is no requirement that the two calendars match, so a comparison

-- Year("2544", "BE") > Year("1374", "AH")

would be perfectly reasonable.

There are some issues that need solving/clear definition. These include:

  • What to do if the calendars do not match, for example a year in a lunar calendar (where a year is shorter than a Gregorian year) typically corresponds to two Gregorian years and arithmetic can become very interesting and certain functions may well need to be changed to accomodate this. This applies to calendars in use today.

  • Should country and date variations be taken into account? For example in some countries using the Julian calendar the year started September 1st (many of these countries changed it later to January 1st). This applies to "historic" dates.

  • Should "calendar change over" effects be taken into account? For example if a country had a "Gregorian April" with more than 30 days the year a switch from Julian to Gregorian calendar took place should this be reflected in the conversion? This applies to "historic" dates.

Issue resulted from member-only e-mail: Anders Berglund (member-only message) and subsequently amended by(member-only message)

Resolution:

None recorded.

This issue occurs in 6 Constructors, Functions, and Operators on Durations, Dates and Times

Issue 48: Timezone facility does not support areas using "sun time" (operator-datetime-suntime)

Originator: Anders Berglund
Locus: Syntax

Description:

The various get-timezone-from-*() functions will not really work for those areas that still use "sun time" (Saudi Arabia at least used to). Thus better to have "get-timezone" return a string and e.g. get-timezone-difference-from-GMT give a duration, which for sun time would vary.

Issue resulted from e-mail: Anders Berglund (member-only message)

Resolution:

None recorded.

This issue is not referenced!

Issue 60: What are the precise semantics of the copy() function? (operator-copy-semantics)

Originator: Michael Kay
Locus: Syntax

Description:

We need to specify which aspects of the newly constructed node are the same as the original. E.g. does it have the same name? string-value? namespaces? parent? children? This is the only function in this document with side-effects, so it needs special care. How does it relate to the node-construction functions defined in the data model?

Issue resulted from e-mail: Michael Kay (member-only message)

Resolution:

None recorded.

This issue occurs in 11.1.11 xf:copy

Issue 63: Do we need variations of index-of for values and identity? (operator-augment-index-of)

Originator: Michael Kay
Locus: Syntax

Description:

index-of. Need find-by-value and find-by-identity. Currently index-of takes a sequence of nodes *or* valies. Do we need to change this?

Issue resulted from e-mail: Michael Kay (member-only message)

Resolution:

None recorded.

This issue occurs in 12.2 Functions and Operators on Sequences

Issue 64: Should reverse-sort be replaced by generic reverse? (operator-generic-reverse)

Originator: Michael Kay
Locus: Syntax

Description:

reverse-sort() looks like a composite function that could and should be defined in terms of reverse() and sort(): so replace it with a new primitive function reverse().

If there were an xf:reverse() function, would xf:reverse(xf:sort(x,y)) = xf:reverse-sort(x,y)?

Issue resulted from e-mail: Michael Kay (member-only message)

Resolution:

Sort and reverse-sort are removed but there is still no reverse() function.

This issue is not referenced!

Issue 66: A function to reorder a sequence into document order is needed (operator-docorder-function)

Originator: Michael Kay (member-only message).
Locus: Syntax

Description:

Need a simple function to sort a sequence in document order (equivalent to union( (), $x )). See also item 20 in member-only e-mail from Don Chamberlin: http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2001Aug/0216.html

Resolution:

None recorded.

This issue occurs in 12.2 Functions and Operators on Sequences,

Issue 67: Should duplicates be eliminated for count() and sum()? (operator-remove-dupes)

Originator: Michael Kay
Locus: Syntax

Description:

I think it may be important for 1.0 compatibility for count() and sum() to remove duplicate nodes first. This depends on the decision we make on the "/" operator.

Issue resulted from e-mail: Michael Kay (member-only message)

Resolution:

None recorded.

This issue occurs in 12.4.1 xf:count, 12.4.5 xf:sum

Issue 70: How are "default" collations determined? (operator-collation-defaulting)

Originator: Steve Zilles and F2F 2001-07-17
Locus: Syntax

Description:

The binary comparison operations determine a "default" collation to use. These operators (and related string "operations" such as sort) must specify how the default collation is determined.

The rules for default collation should specify how "locale" information is taken into account in determining the default.

The rules for default collation should specify how any collation information associated with the data is merged with any other default collation specifications.

The F2F on 2001-07-17 agreed that it should be desirable to specify a default collation in a query (XQuery, at least) preamble, but that explicit specification of a collation in a function invocation overrides that default. The F2F also agreed that the Schema WG should be requested to reconsider whether it should be possible to specify default collations on schema and element (and type) definitions in an XML Schema; those default collations would be used in the absence of a query-level or a function invocation-level specification of a collation. The F2F further agreed that the "ultimate fallback" for a default collation must always be the Unicode Collation Algorithm. Finally, the Function and Operators F2F recognizes the value of allowing collations to be specified (or implied) by a client locale in many instances, but also firmly believes that many data-management situations preclude absolute dependence on locale as the governing factor for ordering decisions.

Issue resulted from e-mail: Steve Zilles (member-only message)

Resolution:

None recorded.

This issue occurs in 4.3 Equality and Comparison of Strings,

Issue 72: Effects of overflow and underflow unspecified (operator-numeric-overflow)

Originator: Andrew Eisenberg
Locus: Syntax

Description:

I believe that we need to say something about numeric overflow and underflow in this section. In section 6, we may need to say something about overflow on date/time operations as years are restricted to 4 digits and fractional seconds to 8 digits.

Issue resulted from e-mail: Andrew Eisenberg (member-only message)

Resolution:

None recorded.

This issue occurs in 3.3 Operators on Numeric Values

Issue 73: Is a "between" function needed? (operator-compare-between)

Originator: Andrew Eisenberg
Locus: Syntax

Description:

I believe that we should have an xf:compare-between function (analogous to SQL's BETWEEN predicate, allowing quick determination of whether one value lies between two other values).

Issue resulted from e-mail: Andrew Eisenberg (member-only message)

Resolution:

None recorded.

This issue occurs in 4.3 Equality and Comparison of Strings

Issue 74: Is a "match-exact()" function needed? (operator-match-exact-required)

Originator: Andrew Eisenberg
Locus: Syntax

Description:

I was surprised that match is defined to see that match returns a list of offsets where a pattern is found.

Let's suppose that I'd like to know whether $x is a phone number (for which I have some pattern defined). If I test for xf:match ($x, $phone) = 1, then $x may have many extraneous trailing characters.

If we retain xf:match as it is specified, then I suggest an xf:exact-match function as well. Similar comment for xf:replace.

Issue resulted from e-mail: Andrew Eisenberg (member-only message)

Resolution:

None recorded.

This issue occurs in 4.4.16 xf:match,

Issue 75: The semantics of match() and replace() are incompletely specified (operator-match-semantics-imprecise)

Originator: Andrew Eisenberg
Locus: Syntax

Description:

This definition includes the following: "... that is the value of the second argument, or is matched by the regular expression that is the second argument, ...".

This seems ill-defined; perhaps two functions are needed.

It seems necessary to say something about the matching that is going on here.

xf:replace ("acadae", "a(.*)a", "b$1b") => "bcbdae" or "bcadbe"

The match could be to the shortest string that qualifies, or the longest string that qualifies.

It seems like I will need a special ("escape") mechanism to be able to include "$1" as actual replacement text in the third argument.

Issue resulted from e-mail: Andrew Eisenberg (member-only message)

Resolution:

None recorded.

This issue occurs in 4.4.16 xf:match, 4.4.17 xf:replace,

Issue 77: Should there be a function to convert characters to strings? (operator-string-from-char)

Originator: Mary Fernandez
Locus: Syntax

Description:

Jerome and I are working on the mapping from XQuery to the core. We want to know whether there should be any operators defined on individual characters or whether all operators are on strings. At a minimum, we think we need a constructor that takes an individual character and returns a string.

Issue resulted from e-mail: Mary Fernandez (member-only message)

Resolution:

None recorded.

This issue is not referenced!

Issue 79: How many digits of precision (etc.) are returned from certain functions? (operator-returned-precision)

Originator: Steve Tolkin
Locus: Syntax

Description:

The xf:numeric-mod() function, the div operator, and others do not specify what the required number of digits of precision is in the result.

Issue resulted from marked-up copy of Version 0.6.

Resolution:

None recorded.

This issue occurs in 3.5 Functions on Numeric Values

Issue 81: What are the precise semantics of regular expressions? (operator-regexp-semantics)

Originator: Paul Biron
Locus: Syntax

Description:

The precise semantics of regular expressions are not clear. The definition of regular expressions in XML Schema are somewhat ambiguous and, in addition, it is not completely clear what semantics would best benefit XQuery. One issue (just as an example): XML Schema's regular expressions do not support "$n" placeholders, even though the examples in this document depend on them.

Another example: Although the XML Schema definition of regular expressions provides a "greedy" algorithm that attempts to match the longest possible strings, the use cases for defining a subset of a datatype's lexical space, on the one hand, and on matching a string against a pattern, on the other hand, are different...and one might want different behavior. Meaning that one might want a variation that is not as "greedy".

See also [Issue 74: Is a "match-exact()" function needed?] and [Issue 75: The semantics of match() and replace() are incompletely specified].

Issue resulted from private e-mail exchange.

Resolution:

None recorded.

This issue occurs in 4.4.16 xf:match

Issue 82: Clarify distinction between node sets, lists, and sequences (operator-nodeset-list-sequence)

Originator: Steve Tolkin
Locus: Syntax

Description:

This document must properly align with [XQuery 1.0 and XPath 2.0 Data Model] when dealing with node sets (which are defined in [XPath 1.0]), lists, and sequences. The current wording in this document is sometimes confused about the distinctions.

Issue resulted from marked-up copy of Version 0.6.

Resolution:

None recorded.

This issue occurs in 12 Constructors, Functions, and Operators on Sequences

Issue 83: Are the cast tables appropriately structured and ordered? (operator-cast-table-structure)

Originator: Steve Tolkin
Locus: Syntax

Description:

The tables would be much more useful if these names grouped by "family" (e.g., all numeric types started with the letter "n", all date and time types with "d", string-like types with "s", and binary types with "b"). (Of course, boolean could go either in with the numeric types or in with the binary types.) Then the tables could be sorted alphabetically. There is already a system: the types cast to in the next few sections.

Issue resulted from marked-up copy of Version 0.6.

Resolution:

None recorded.

This issue is not referenced!

Issue 84: When casting to token, are linefeed/tab converted to space? (operator-cast-to-token)

Originator: Steve Tolkin
Locus: Syntax

Description:

The current definition of casting to token states that all line feed codes and all tab characters are removed, after which leading and trailing spaces are deleted and multiple spaces are replaced with a single space. Shouldn't line feed codes and tabs be converted to spaces instead of simply deleted?

Issue resulted from marked-up copy of Version 0.6.

Resolution:

None recorded.

This issue is not referenced!

Issue 89: Functions that have anyType in their return are problematic. (functions-on-anyType-problematic)

Originator: Phil Wadler (member-only message)
Locus: Syntax

Description:

Functions with AnyType in the return are problematic for two reasons. To be concrete, I discuss the following.

-- xf:item-at(anyType* $seqParam, decimal $posParam) => anyType

(1) Note that the types anyType* and anyType are equivalent, which suggests that the typing here is not quite right. We should define

-- define group AnyItem = AnyElement | AnyAttribute | AnySimpleType

and then give the above the type

-- xf:item-at(anyItem* $seqParam, decimal $posParam) => anyItem

(2) Even having made the above change, the type is too broad to be useful, and one will almost always have to cast the result of calling xf:item-at (and similarly for other functions with anyItem or anyType in the result).

Instead, we should allow parametric polymorphism when specifying the signatures of built-in functions.

-- xf:item-at($anyItem* $seqParam, decimal $posParam) => $anyItem

Here $anyItem is a type variable which ranges over any group $anyItem such that $anyItem <: AnyItem. (Recall that s <: t if the extent of type s is a subset of the extent of type t, where the extent of a type is the set of values that have that type.)

Here are two examples of functions written with the current signature.

-- define function second-integer (integer* $integer-sequence) integer { treat as integer (xf:item($integer-sequence, 2)) }

-- define function third-book (Book* $book-sequence) book { treat as Book (xf:item($book-sequence, 3)) }

Here are two examples of functions that would type check under this scheme.

-- define function second-integer (integer* $integer-sequence) integer { xf:item($integer-sequence, 2) }

-- define function third-book (Book* $book-sequence) book { xf:item($book-sequence, 3) }

The definitions are easier to write and more efficient to execute (since no "treat as" needs to check the structure of the result).

Parametric polymorphism would also be useful for user-defined functions, it were clear how to define it for user-defined functions in general. But at the very least, we should allow parametric polymorphism for the built-in functions defined in the functions and operators document.

Resolution:

This issue occurs in 12 Constructors, Functions, and Operators on Sequences

Issue 94: Must allow searching for words near other words. (operator-within-window)

Originator: Steve Tolkin (member-only message).
Locus: Syntax

Description:

Systems that search text often provide a function to search for several terms that are near one another. Often this function is named NEAR and allows an argument to specify the maximum distance allowed between the terms. (Generally it only allow two terms, but sometimes it allows more).

XQuery should provide a standard function to achieve this. To avoid the difficult problem of deciding what is a word boundary etc. it should be defined instead on a sequence of nodes, and search their content.

One possible signature would be within-window(node* node-sequence, int size, string* strings, boolean order-matters)

The last argument order-matters is optional and if true the strings arguments would have to match in the order given.

A function like this could be used to answering the Library of Congress use cases at http://lcweb.loc.gov/crsinfo/xml/lc_usecases.html

It also could be used to answer the question of how to search for the sequence of pitches: C, D, E, C. as discussed in the memeber-only e-mail http://list3.w3.org/Archives/Member/w3c-xml-query-wg/2001Jul/0085.html

First the user would remove the extraneous ancestor nodes caused by the measures, leaving a sequence of note nodes. Then the essence of the query is simply: within-window(note-sequence, 4, make-list-of-strings("C","D","E","C"), true) where the 3rd argument is hypothetical syntax for constructing a list of strings.

Issue resulted from member-only e-mail http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2001Jul/0127.html

Resolution:

This issue occurs in 4.4 Functions on String Values

Issue 108: Should strings always be returned in Unicode normalized form? (operators-always-normalize)

Originator: Norm Walsh (member-only message)
Locus: Syntax

Description:

When does it make sense for a function to return a string that is in a form other than some Unicode normalized form?

Resolution:

This issue occurs in 4.4.1 Usage Notes

Issue 109: Calendar context allows for non-Gregorian calendars (operators-calendar-context)

Originator: Norm Walsh (member-only message)
Locus: Syntax

Description:

Some sort of (defaulted) calendar context is required for all these functions to allow for future support of non-Gregorian calendars.

Resolution:

This issue occurs in 6 Constructors, Functions, and Operators on Durations, Dates and Times

Issue 110: No timezone: Empty sequence or empty string? (operators-timezone-empty-sequence)

Originator: Norm Walsh (member-only message)
Locus: Syntax

Description:

"...does not contain a timezone, the result is the empty sequence" should be "...does not contain a timezone, the result is the empty string". Whatever we do, the result should be consistent with other such decisions e.g. what does the name accessor return if the node has no name.

Resolution:

This issue occurs in 6.6.19 xf:get-timezone-from-dateTime

Issue 112: QName-from-uri needs context (operators-qname-from-uri-context)

Originator: Norm Walsh (member-only message)
Locus: Syntax

Description:

How can QName-from-uri operate without some sort of context?

What is a QName in no namespace?

Resolution:

This issue occurs in 7.1.1 xf:QName-from-uri, 7.1.3 xf:QName

Issue 113: Need more complete numeric comparison semantics (operators-numeric-comparison-semantics)

Originator: Mike Kay (member-only message)
Locus: Syntax

Description:

The document does not specify the complete semantics of numeric comparisons. For example, is -0.0e1 equal to +0.0e1? Is NaN equal to Nan?

Resolution:

This issue occurs in 3.4 Comparisons of Numeric Values

Issue 118: Should xf:string(node) return error if argument not scalar? (operators-string-nonscalar-error)

Originator: Don Chamberlin (member-only message)
Locus: Syntax

Description:

string(node) contains the XPath 1.0 definition of the string() function. This definition is based on the type system of XPath 1.0, which has only four types, and it should be reconsidered for XQuery. For example, the definition says that a sequence is converted to a string by returning the string-value of the first item in the sequence. This conflicts with our general policy of raising an error if a scalar function is called with a sequence of length greater than one.

Resolution:

This issue is not referenced!

Issue 122: What is a "namespace in scope"? (operators-namespaces-in-scope)

Originator: Don Chamberlin (member-only message)
Locus: Syntax

Description:

Section 6.1.2.4 refers to namespace URI's as being "in scope". I do not understand what this means. XQuery has a concept of a scope for namespace prefixes, but as far as I know we have not defined the concept of scope for URI's.

Resolution:

This issue is not referenced!

Issue 133: Syntax for indicating that function accepts empty sequence is incorrect (syntax-for-function-takes-empty-sequence)

Originator: (member-only message) Minutes of 10/31 Query telcon.
Locus: Syntax

Description:

The ? is used in the XML EBNF to indicate that a token is optional. Using the ? after a type name in a function signature to indicate that the empty sequence is allowed uses the ? to indicate a quite different semantic. This may be confusing to users.

Resolution:

This issue occurs in 1.4 Notations

Issue 136: Should we allow casting a date/time from one timezone to another? (function-datetime-timezone-conversion)

Originator: (member-only message) Anders Berglund.
Locus: Syntax

Description:

Should we have functions that convert a date/time time value from one timezone to another? If the original value has no timezone, the timezone is added. If it hasa timezone, the value is changed to conform to the specified timezone. Perhaps an alternate signature takes a timezone delta.

Resolution:

This issue occurs in 6 Constructors, Functions, and Operators on Durations, Dates and Times

Issue 137: Should functions that return timezones return a duration? (operators-timezone-return-duration)

Originator: Andrew Eisenberg. (member-only message)
Locus: Syntax

Description:

"Should the functions that return timezones return a duration rather than a string?"

Resolution:

This issue occurs in 6.6.19 xf:get-timezone-from-dateTime

Issue 139: Need a fuller treatment of error behaviour and possibly error handling. (need-fuller-definition-of-error-behavior-and-handling)

Originator: (member-only message) Minutes of December 5, 2001 meeting.
Locus: Syntax

Description:

The documents talk vaguely about throwing errors, type errors, an error object; MFF suggested an error function. We need a comprehensive treatment of error behaviour and possibly error handling."

Resolution:

This issue occurs in

Issue 141: Does string equality use the codepoint collation or the default collation? (does-string-equality-use-codepoint-or-default-collation)

Originator: (member-only message) Minutes of December 5, 2001 meeting.
Locus: Syntax

Description:

Does string equality use the codepoint collation or the default collation. Note that we decided that codepoint comparisons would be done via a special collation.

Resolution:

This issue occurs in 4.3.1 xf:compare

Issue 142: Should floor ceiling and round return the same type as their argument? (what-should-floor-ceiling-round-return)

Originator: (member-only message) Minutes of December 5, 2001 meeting.
Locus: Syntax

Description:

What do floor, ceiling and round return? The document says integer. But NaN and the empty sequnce are allowed. Should they return the same type as their operand (without a fractional part)? This allows them to operate on numbers larger than a decimal or integer can accomodate.

Resolution:

This issue occurs in 3.5 Functions on Numeric Values

Issue 143: Should we add a tokenize function to break a string into tokens? (need-tokenize-function)

Originator: (member-only message) Minutes of December 5, 2001 meeting.
Locus: Syntax

Description:

Should we add a function to tokenize a string, breaking on a specified character?"

Resolution:

This issue occurs in 4.4 Functions on String Values

Issue 144: Should the concat function accept sequences as arguments? (should-concat-accept-sequence-arguments)

Originator: (member-only message) Minutes of December 5, 2001 meeting.
Locus: Syntax

Description:

Should the concat function accept sequences as arguments? Should sequences of strings be flattened? Should string-values be used if the items in the sequence are not strings?

Resolution:

This issue occurs in 4.4.2 xf:concat

Issue 145: Need decisions and text in several of our documents detailing conformance requirements based on resource limitations. (need-to-specify-resource-limits)

Originator: (member-only message) Minutes of December 5, 2001 meeting.
Locus: Syntax

Description:

We need to specify minimum conformance requirements based on resource limitations such as the maximum number of nodes in a sequence, number of text nodes in a document, etc."

Resolution:

This issue occurs in

Issue 149: Either the constructor functions should allow dynamic expressions or the syntax should be changed so that they do not appear to be functions. (should-constructors-accept-only-literals)

Originator: (member-only message) Minutes of December 5, 2001 meeting.
Locus: Syntax

Description:

Either the constructor functions should allow dynamic expressions or the syntax should be changed so that they do not appear to be functions.

Resolution:

This issue occurs in 3.2 Numeric Constructors

Issue 150: Should we support comparisons of date/time types that return indeterminate results? (should-comparison-that-return-indeterminate-results-be-supported)

Originator: (member-only message) Minutes of December 5, 2001 meeting.
Locus: Syntax

Description:

Comparisons of durations that contain both months and days can return indeteriminate results as defined by XML Schema. Similarly, date/time times that may or may not have a timezone specified return indeterminate results. Should such comparisons be supported?

Resolution:

This issue occurs in

Issue 151: Do we need comparison functions on other date and time types? (comparison-functions-for-other-date-and-time-types)

Originator: (member-only message) Minutes of December 5, 2001 meeting.
Locus: Syntax

Description:

We document currently defines comparison functions on durations and dateTime. Do we need comparison functions for other date/time types. See also, issue 150.

Resolution:

This issue occurs in 6.5 Comparisons of Duration, Date and Time Values

Issue 152: Create a single extraction function for each datatype that takes as a parameter the field it extracts. (parameterized-extraction-functions-for-date-and-times)

Originator: (member-only message) Minutes of December 5, 2001 meeting.
Locus: Syntax

Description:

The document will be made more complete and smaller by having a single extraction function for each date/time datatype that takes as a parameter the name of the bfield it extracts. Break timezone into timezone hours and timezone minutes or extract as) duration.

Resolution:

This issue occurs in 6.6 Component Extraction Functions on Duration, Date and Time Values

Issue 154: Should we define a second order distinct function? (second-order-distinct-function)

Originator: (member-only message) Minutes of December 5, 2001 meeting.
Locus: Syntax

Description:

Should we define a second order distinct function where the comparison function is passed as an argument? Mike Kay to write a proposal.

Resolution:

This issue occurs in 12.2.7 xf:distinct-nodes

Issue 155: The term 'empty content' should be changed or, at least, be carefully defined. (define-if-empty)

Originator: (member-only message) Minutes of December 5, 2001 meeting.
Locus: Syntax

Description:

The term 'empty content' should be changed or, at least, be carefully defined. Is an attribute node with the value of the empty string empty content?

Resolution:

This issue occurs in 11.2.2 xf:if-empty

Issue 156: How should the boolean function be defined? Legacy XPath 1.0 function? (operators-boolean-function)

Originator: (member-only message) Minutes of December 5, 2001 meeting.
Locus: Syntax

Description:

Why is the definition of boolean() different from the rules for converting a sequence into a boolean? One possibility is to consider this a legacy function that performs the XPath 1.0 test. Should this function be moved into the XSLT document in that case? This needs to be synchronized with the fallback conversions for boolean in XPath 2.0.

Resolution:

This issue occurs in 12.2.1 xf:boolean

Issue 157: boolean-from-string should accept only 1, 0, true, false. (boolean-from-string-legal-literals)

Originator: Andrew Eisenberg. (member-only message)
Locus: Syntax

Description:

boolean-from-string should accept only 1, 0, true, false. This is what XML Schema allows and that's all we need.

Resolution:

This issue occurs in 5.1.3 xf:boolean-from-string

Issue 158: We need equality functions for all simple datatypes. See also, issue 151. (need-equality-functions-for-all-datatypes)

Originator: Don Chamberlin. (member-only message)
Locus: Syntax

Description:

We need equality functions for all datatypes. Currently, we are lacking equality functions for some date and time types (Issue 151), QNames, URI and NOTATION.

Resolution:

This issue occurs in 11.1.6 xf:deep-equal

Issue 159: For fractional seconds precision use 6 digits to match SQL TIMESTAMP. (minimum-conformance-for-fractional-seconds)

Originator: Andrew Eisenberg. (member-only message)
Locus: Syntax

Description:

For fractional seconds precision we should choose a limit that matched SQL's TIMESTAMP data type, which is 6 digits of fractional seconds precision.

Resolution:

This issue occurs in 6.1 Duration, Date and Time Types

Issue 160: Align the string() function with 'cast as string'. (align-string-function-with-cast)

Originator: Michael Kay (member-only message)
Locus: Syntax

Description:

Consider changing the rules for casting to string so they are the same as the rules given here for the string function.

Resolution:

This issue occurs in 2.3 xf:string

Issue 162: Can we omit the node argument to root() and use the context item if it is omitted. (can-the-node-parameter-to-root-be-omitted)

Originator: Jonathan Robie. (member-only message)
Locus: Syntax

Description:

Currently the root() function requires a mandatory node as argument. Should we allow that this argument may be omitted and, if it is omitted, the context item used as argument. If the context item argument is not a node, the function returns the empty sequence or it should return an error.

Resolution:

This issue occurs in 11.1.13 xf:root

Issue 164: For a complex type other than anyType, should data() return the string value obtained by concatenating descendant text nodes? (for-complex-types-what-should-data-return)

Originator: Paul Cotton. (member-only message)
Locus: Syntax

Description:

Currently the data() function returns an error if the argument is a complex type other than anyType. Should this be changed to return the string value obtained by concatenating the descendant text nodes?

Resolution:

This issue occurs in 2.4 xf:data

Issue 165: What timezone should be returned by the current-dateTime function? (current-dateTime-timezone)

Originator: Minutes of Cambridge meeting.9644 (member-only message)
Locus: Syntax

Description:

What timezone should the current-dateTime function return? Suggestions were Z, local time zone and implementation defined.

Resolution:

This issue occurs in 13.5 xf:current-dateTime

Issue 166: Do we need convenience functions to supplement current-dateTime? (current-dateTime-convenience-functions)

Originator: Minutes of Cambridge meeting. (member-only message)
Locus: Syntax

Description:

Do we need convenience functions for supplement current-dateTime such as current-date and current-time?

Resolution:

This issue occurs in 13.5 xf:current-dateTime

Issue 167: Semantics of xf:filter are underspecified and, perhaps, incorrect. (semantics-of-filter)

Originator: Michael Kay (member-only message)
Locus: Syntax

Description:

xf:filter is grossly underspecified, and that it requires an argument of type Expression that isn't a type in our type system.

Resolution:

This issue occurs in 12.5.3 xf:filter

Issue 168: For compatibility with the XPath 1.0 function of the same name, xf:id() should accept a list of strings. (should-id-take-a-list-of-strings)

Originator: Minutes of Cambridge meeting. (member-only message) and subsequent discussion with Michael Kay on xf:id().
Locus: Syntax

Description:

For compatibility with the XPath 1.0 function of the same name, xf:id() should accept a list of strings as argument. A possible resolution is to allow fallback conversions from string to IDREF.

Resolution:

This issue occurs in 12.5.1 xf:id

C ChangeLog (Non-Normative)

This appendix tracks gross changes in the document; it is not intended to provide a fine-grained revision history.

08 Oct 2001 (ndw): Removed xf:get-Century-from-gYear, xf:get-Century-from-gYearMonth, xf:get-gYear-from-dateTime, xf:get-gYear-from-date, xf:get-gYear-from-gYearMonth, xf:get-gMonth-from-dateTime, xf:get-gMonth-from-date, xf:get-gMonth-from-gYearMonth, xf:get-gMonth-from-gMonthDay, xf:get-gDay-from-dateTime, xf:get-gDay-from-date, xf:get-gDay-from-gMonthDay, xf:get-timezone-from-gYear, xf:get-timezone-from-gYearMonth, xf:get-timezone-from-gMonth, xf:get-timezone-from-gMonthDay, xf:get-timezone-from-gDay, xf:add-months, xf:add-years, xf:add-gMonth, xf:add-gYear, xf:sublist-before, xf:sublist-after, xf:sequence-pad-beginning, xf:sequence-pad-end, xf:truncate-beginning, xf:truncate-end, xf:resize-beginning, xf:resize-end, xf:unordered, xf:union-all, xf:intersect-all, and xf:except-all.

09 Oct 2001 (ndw): Replaced string-pad-beginning and string-pad-end with string-pad.

09 Oct 2001 (ndw): Reworked definition for xf:match.

09 Oct 2001 (ndw): Removed references to functions we've removed.

09 Oct 2001 (ndw): Added experimental "operators as functions" syntax.

26-Oct-2001 (AM) Added section showing exposed functions from accessors and kind tests.

26-Oct-2001 (AM) Changed comparison functions on dateTime and duration to accept only those arguments that would return a determinate result. Closed issues on indeterminate results.

26-Oct-2001 (AM) Added NOT3 function. Added issue on name of this function.

26-Oct-2001 (AM) Added if-absent() and if-empty() functions.

31Oct-2001 (AM) Added issue on syntax used to indicate that a function accepts a empty sequence.

31-Oct-2001 (AM) Added section with four context functions.

31-Oct-2001 (AM) Changed section on functions on sequences to discuss heterogeneous sequences. Changed aggregate function definitions accordingly.

31-Oct-2001 (AM) Added wording to say that constructors accept only literals as per Reston minutes.

1-Nov-2001 (AM) Rewrote notations section to add note on derived types.

1-Nov-2001 (AM) Rewrote match and replace functions to remove optional collation argument and use codepoint comparisons.

1-Nov-2001 (AM) Removed operators on nodes.

1-Nov-2001 (AM) Changed operators on hexBinary and base64Binary to functions.

2-Nov-2001 (AM) Changed operators on boolean to functions.

21-Nov-2001 (AM) Added issue on whether casting to derived types should be permitted.

25-Nov-2001 (AM) Added material on which functions back up which operators.

10-Dec-2001 (AM) Removed get-QName-from-prefix.

10-Dec-2001 (AM) Removed xf:temporal-dateTimes-contains, xf:temporal-dateTimeDuration-contains and xf:temporal-durationDateTimes-contains.

10-Dec-2001 (AM) Added issues, normal and high priority, as recorded in minutes of the 12/5 meeting: http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2001Dec/0023.html

4-Mar-2002 (AM) Removed boolean-and and boolean-or functions

4-Mar-2002 (AM) Removed numeric-greater-than-or-equal, numeric-less-than-or-equal and numeric-not-equal functions

4-Mar-2002 (AM) Removed duration-greater-than-or-equal, duration-less-than-or-equal and duration-not-equal functions

4-Mar-2002 (AM) Removed dateTime-greater-than-or-equal, dateTime-less-than-or-equal and dateTime-not-equal functions

4-Mar-2002 (AM) Rewrote the not() function to take an item*

4-Mar-2002 (AM) Removed not3 function

4-Mar-2002 (AM) Rewrote union, intersect and except to work with node sequences only. Closed issue 132.

4-Mar-2002 (AM) Added legacy function namespace-uri that takes a node sequence as argument.

4-Mar-2002 (AM) Added equals operators on QName, anyURI and NOTATION.

5-Mar-2002 (AM) Rewrote document() function to align with XSLT.

5-Mar-2002 (AM) Changed name of xf:name() to xf:node-name. Maps to name accessor.

5-Mar-2002 (AM) Rewrote legacy functions in accordance with Mike Kay's note 0004 in Feb 2002 to the xsl-wg. Added issue to align string function with "cast as string".

6-Mar-2002 (AM) Added (and closed) issue on need for function to return in-scope language (from Andrew Eisenberg).

6-Mar-2002 (AM) Changed xf:sum to return 0.0 if argument is (). Minutes of XQuery call 3/6/2002

8-Mar-2002 (AM) Added functions boolean-less-than and boolean-greater-than based on note from Don Chamberlin 3/7/2002.

8-Mar-2002 (AM) Added functions node-precedes and node-follows based on note from Don Chamberlin 3/7/2002.

13-Mar-2002 (AM) Added collection(), input(), root() and resolve-URI() functions based on notes from Mike Kay and Jonathan Robie 3/13/2002.

16-Mar-2002 (AM) Changed definitions of node-precedes() and node-follows() based on Don C's note of 3/14.

20-Mar-2002 (AM) Changed definition of data() based on Query WG decision on telcon on 3/20/2002.

04-Apr-2002 (AM) Removed gt, lt functions on duration.

04-Apr-2002 (AM) Removed note from double constructor saying double(INF) returns NaN. As per note from MHK 3/28/2002.

04-Apr-2002 (AM) Closed issue 105 (operator-div-compatibilty). As per note from MHK 3/28/2002.

15-Apr-2002 (AM) Closed issues 25, 103, 104, 140 as per minutes of Cambridge meeting http://lists.w3.org/Archives/Member/w3c-query-operators/2002Apr/0055.html.

15-Apr-2002 (AM) Reworded the deep-equal function as per minutes of Cambridge meeting http://lists.w3.org/Archives/Member/w3c-query-operators/2002Apr/0055.html.

15-Apr-2002 (AM) Added the functions and datatype required for the duration proposal. See http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2002Mar/0477.html

15-Apr-2002 (AM) Added two issues on current-dateTime as per minutes of Cambridge meeting http://lists.w3.org/Archives/Member/w3c-query-operators/2002Apr/0055.html.

15-Apr-2002 (AM) Reopened issue 16 as requested in minutes of Cambridge meeting http://lists.w3.org/Archives/Member/w3c-query-operators/2002Apr/0055.html.

15-Apr-2002 (AM) Added words to the id() and idref() functions to say that the nodes returned come from the context document. See minutes of Cambridge meeting http://lists.w3.org/Archives/Member/w3c-query-operators/2002Apr/0055.html. Closed issue 68.

15-Apr-2002 (AM) Closed issue 54. See minutes of Cambridge meeting http://lists.w3.org/Archives/Member/w3c-query-operators/2002Apr/0055.html.

17-Apr-2002 (AM) Added issue on semantics of xf:filter().

17-Apr-2002 (AM) Added issue on whether xf:id() should accept a list of strings.

17-Apr-2002 (AM) Rewrote status section in preparation for publication.

23-Apr-2002 (AM) Rewrote xf:substring() to account for non-integer arguments based on input from Mike Kay and Andrew Eisenberg.

D Function and Operator Quick Reference (Non-Normative)

D.1 Functions and Operators by Section

Accessors
xf:node-kind
xf:node-kind(node $srcval) => string
xf:node-name
xf:node-name(node $srcval) => QName?
xf:string
xf:string() => string
xf:string(item* $srcval) => string
xf:data
xf:data(node* $srcval) => value*
xf:base-uri
xf:base-uri(node $srcval) => anyURI?
xf:unique-ID
xf:unique-ID(node $srcval) => ID?
Constructors, Functions, and Operators on Numbers
Numeric Constructors
xf:decimal(string $srcval) => decimal
xf:integer(string $srcval) => integer
xf:long(string $srcval) => integer
xf:int(string $srcval) => integer
xf:short(string $srcval) => integer
xf:byte(string $srcval) => integer
xf:float(string $srcval) => float
xf:double(string $srcval) => double
Operators on Numeric Values
op:numeric-add(numeric $operand1, numeric $operand2) => numeric
op:numeric-subtract(numeric $operand1, numeric $operand2) => numeric
op:numeric-multiply(numeric $operand1, numeric $operand2) => numeric
op:numeric-divide(numeric $operand1, numeric $operand2) => numeric
op:numeric-mod(numeric $operand1, numeric $operand2) => numeric
op:numeric-unary-plus(numeric $operand) => numeric
op:numeric-unary-minus(numeric $operand) => numeric
Comparisons of Numeric Values
op:numeric-equal(numeric $operand1, numeric $operand2) => boolean
op:numeric-less-than(numeric $operand1, numeric $operand2) => boolean
op:numeric-greater-than(numeric $operand1, numeric $operand2) => boolean
Functions on Numeric Values
xf:floor(double? $srcval) => integer?
xf:ceiling(double? $srcval) => integer?
xf:round(double? $srcval) => integer?
Constructors and Functions on Strings
String Constructors
xf:string(string $srcval) => string
xf:normalizedString(string $srcval) => normalizedString
xf:token(string $srcval) => token
xf:language(string $srcval) => language
xf:Name(string $srcval) => Name
xf:NMTOKEN(string $srcval) => NMTOKEN
xf:NCName(string $srcval) => NCName
xf:ID(string $srcval) => ID
xf:IDREF(string $srcval) => IDREF
xf:ENTITY(string $srcval) => ENTITY
Equality and Comparison of Strings
xf:compare(string? $comparand1, string? $comparand2) => integer?
xf:compare(string? $comparand1, string? $comparand2, anyURI $collationLiteral) => integer?
Functions on String Values
xf:concat() => string
xf:concat(string? $op1) => string
xf:concat(string? $op1, string? $op2, ...) => string
xf:starts-with(string? $operand1, string? $operand2) => boolean?
xf:starts-with(string? $operand1, string? $operand2, anyURI $collationLiteral) => boolean?
xf:ends-with(string? $operand1, string? $operand2) => boolean?
xf:ends-with(string? $operand1, string? $operand2, anyURI $collationLiteral) => boolean?
xf:contains(string? $operand1, string? $operand2) => boolean?
xf:contains(string? $operand1, string? $operand2, anyURI $collationLiteral) => boolean?
xf:substring(string? $sourceString, decimal? $startingLoc) => string?
xf:substring(string? $sourceString, decimal? $startingLoc, decimal? $length) => string?
xf:string-length(string? $srcval) => integer?
xf:substring-before(string? $operand1, string? $operand2) => string?
xf:substring-before(string? $operand1, string? $operand2, anyURI $collationLiteral) => string?
xf:substring-after(string? $operand1, string? $operand2) => string?
xf:substring-after(string? $operand1, string? $operand2, anyURI $collationLiteral) => string?
xf:normalize-space(string? $srcval) => string?
xf:normalize-unicode(string? $srcval) => string?
xf:normalize-unicode(string? $srcval, string $normalizationForm) => string?
xf:upper-case(string? $srcval) => string?
xf:lower-case(string? $srcval) => string?
xf:translate(string? $srcval, string? $mapString, string? $transString) => string?
xf:string-pad(string? $padString, decimal? $padCount) => string?
xf:match(string? $srcval, string? $regexp) => integer*
xf:replace(string? $srcval, string? $regexp, string? $repval) => string?
Constructors, Functions and Operators on Booleans
Boolean Constructors
xf:true() => boolean
xf:false() => boolean
xf:boolean-from-string(string $srcval) => boolean
Operators on Boolean Values
op:boolean-equal(boolean? $value1, boolean? $value2) => boolean?
Functions on Boolean Values
xf:not(item* $srcval) => boolean
op:boolean-less-than(boolean $srcval1, boolean $srcval2) => boolean
op:boolean-greater-than(boolean $srcval1, boolean $srcval2) => boolean
Constructors, Functions, and Operators on Durations, Dates and Times
Duration, Date and Time Constructors
xf:duration(string $srcval) => duration
xf:dateTime(string $srcval) => dateTime
xf:date(string $srcval) => date
xf:time(string $srcval) => time
xf:gYearMonth(string $srcval) => gYearMonth
xf:gYear(string $srcval) => gYear
xf:gMonthDay(string $srcval) => gMonthDay
xf:gMonth(string $srcval) => gMonth
xf:gDay(string $srcval) => gDay
yearMonthDuration and dayTimeDuration Constructors
xf:yearMonthDuration(string $srcval) => yearMonthDuration
xf:yearMonthDuration-from-months(integer $srcval) => yearMonthDuration
xf:dayTimeDuration(string $srcval) => dayTimeDuration
xf:dayTimeDuration-from-seconds(decimal $srcval) => dayTimeDuration
Comparisons of Duration, Date and Time Values
op:duration-equal(duration $operand1, duration $operand2) => boolean
op:yearMonthDuration-equal(yearMonthDuration $operand1, yearMonthDuration $operand2) => boolean
op:yearMonthDuration-less-than(yearMonthDuration $operand1, yearMonthDuration $operand2) => boolean
op:yearMonthDuration-greater-than(yearMonthDuration $operand1, yearMonthDuration $operand2) => boolean
op:dayTimeDuration-equal(dayTimeDuration $operand1, dayTimeDuration $operand2) => boolean
op:dayTimeDuration-less-than(dayTimeDuration $operand1, dayTimeDuration $operand2) => boolean
op:dayTimeDuration-greater-than(dayTimeDuration $operand1, dayTimeDuration $operand2) => boolean
op:datetime-equal(dateTime $operand1, dateTime $operand2) => boolean
op:datetime-less-than(dateTime $operand1, dateTime $operand2) => boolean
op:datetime-greater-than(dateTime $operand1, dateTime $operand2) => boolean
Component Extraction Functions on Duration, Date and Time Values
xf:get-years-from-yearMonthDuration(yearMonthDuration? $srcval) => integer?
xf:get-months-from-yearMonthDuration(yearMonthDuration? $srcval) => integer?
xf:get-days-from-dayTimeDuration(dayTimeDuration? $srcval) => integer?
xf:get-hours-from-dayTimeDuration(dayTimeDuration? $srcval) => integer?
xf:get-minutes-from-dayTimeDuration(dayTimeDuration? $srcval) => integer?
xf:get-seconds-from-dayTimeDuration(dayTimeDuration? $srcval) => integer?
xf:get-year-from-dateTime(dateTime? $srcval) => integer?
xf:get-year-from-date(date? $srcval) => integer?
xf:get-month-from-dateTime(dateTime? $srcval) => integer?
xf:get-month-from-date(date? $srcval) => integer?
xf:get-day-from-dateTime(dateTime? $srcval) => integer?
xf:get-day-from-date(date? $srcval) => integer?
xf:get-hours-from-dateTime(dateTime? $srcval) => integer?
xf:get-hours-from-time(time? $srcval) => integer?
xf:get-minutes-from-dateTime(dateTime? $srcval) => integer?
xf:get-minutes-from-time(time? $srcval) => integer?
xf:get-seconds-from-dateTime(dateTime? $srcval) => decimal?
xf:get-seconds-from-time(time? $srcval) => decimal?
xf:get-timezone-from-dateTime(dateTime? $srcval) => string?
xf:get-timezone-from-date(date? $srcval) => string?
xf:get-timezone-from-time(time? $srcval) => string?
Arithmetic Functions on yearMonthDuration and dayTimeDuration
op:add-yearMonthDurations(yearMonthDuration $srcval1, yearMonthDuration $srcval2) => yearMonthDuration
op:subtract-yearMonthDurations(yearMonthDuration $srcval1, yearMonthDuration $srcval2) => yearMonthDuration
op:multiply-yearMonthDuration(yearMonthDuration $srcval1, decimal $srcval2) => yearMonthDuration
op:divide-yearMonthDuration(yearMonthDuration $srcval1, decimal $srcval2) => yearMonthDuration
op:add-dayTimeDurations(dayTimeDuration $srcval1, dayTimeDuration $srcval2) => dayTimeDuration
op:subtract-dayTimeDurations(dayTimeDuration $srcval1, dayTimeDuration $srcval2) => dayTimeDuration
op:multiply-dayTimeDuration(dayTimeDuration $srcval1, decimal $srcval2) => dayTimeDuration
op:divide-dayTimeDuration(dayTimeDuration $srcval1, decimal $srcval2) => yearMonthDuration
Arithmetic Functions on Dates
xf:add-days(date? $dateParam, decimal? $incrDays) => date?
Functions and Operators on TimePeriod Values
xf:get-yearMonthDuration(dateTime $srcval1, dateTime $srcval2) => yearMonthDuration
xf:get-dayTimeDuration(dateTime $srcval1, dateTime $srcval2) => dayTimeDuration
op:add-yearMonthDuration-to-dateTime(dateTime $srcval1, yearMonthDuration $srcval2) => dateTime
op:add-dayTimeDuration-to-dateTime(dateTime $srcval1, dayTimeDuration $srcval2) => dateTime
op:subtract-yearMonthDuration-from-dateTime(dateTime $srcval1, yearMonthDuration $srcval2) => dateTime
op:subtract-dayTimeDuration-from-dateTime(dateTime $srcval1, dayTimeDuration $srcval2) => dateTime
op:add-yearMonthDuration-to-date(date $srcval1, yearMonthDuration $srcval2) => date
op:add-dayTimeDuration-to-date(date $srcval1, dayTimeDuration $srcval2) => dateTime
op:subtract-yearMonthDuration-from-date(date $srcval1, yearMonthDuration $srcval2) => date
op:subtract-dayTimeDuration-from-date(date $srcval1, dayTimeDuration $srcval2) => date
op:add-dayTimeDuration-to-time(time $srcval1, dayTimeDuration $srcval2) => time
op:subtract-dayTimeDuration-from-time(time $srcval1, dayTimeDuration $srcval2) => time
Constructors and Functions on QNames
Constructors for QNames
xf:QName-from-uri(string $paramURI, string $paramLocal) => QName
xf:QName-from-string(string $param) => QName
xf:QName(string $paramLocal) => QName
Functions on QNames
op:QName-equal(QName $srcval1, QName $srcval2) => boolean
xf:get-local-name(QName? $srcval) => string?
xf:get-namespace-uri(QName? $srcval) => anyURI?
xf:namespace-uri() => string
xf:namespace-uri(node* $srcval) => string
Constructors, Functions, and Operators for anyURI
Constructors for anyURI
xf:anyURI(string $srcval) => anyURI
xf:resolve-URI(anyURI $base, anyURI $relative) => anyURI
Functions on anyURI
op:anyURI-equal(anyURI $srcval1, anyURI $srcval2) => boolean
Functions and Operators on base64Binary and hexBinary
Comparisons of base64Binary and hexBinary Values
op:hex-binary-equal(hexBinary $value1, hexBinary $value2) => boolean
op:base64-binary-equal(base64Binary $value1, base64Binary $value2) => boolean
Constructors, Functions, and Operators on NOTATION
NOTATION Constructor
xf:NOTATION(string $srcval) => NOTATION
Functions on NOTATION
op:NOTATION-equal(NOTATION $srcval1, NOTATION $srcval2) => boolean
Functions and Operators on Nodes
Functions and Operators on Nodes
xf:name() => string
xf:name(node* $srcval) => string
xf:local-name() => string
xf:local-name(node $srcval) => string
xf:number() => anySimpleType
xf:number(node $srcval) => anySimpleType
xf:lang(string $testlang) => boolean
op:node-equal(node $parameter1, node $parameter2) => boolean
xf:deep-equal(node $parameter1, node $parameter2) => boolean
xf:deep-equal(node $parameter1, node $parameter2, anyURI $collation) => boolean
op:node-before(node $parameter1, node $parameter2) => boolean
op:node-after(node $parameter1, node $parameter2) => boolean
op:node-precedes(node $srcval1, node $srcval2) => boolean
op:node-follows(node $srvcal1, node $srcval2) => boolean
xf:copy(node? $srcval) => node?
xf:shallow(node? $srcval) => node?
xf:root(node $srcval) => node
if-absent() and if-empty()
xf:if-absent((elementNode | attributeNode)? $node, anySimpleType $value) => (elementNode | attributeNode | anySimpleType)?
xf:if-empty((elementNode | attributeNode)? $node, anySimpleType $value) => (elementNode | attributeNode | anySimpleType)
Constructors, Functions, and Operators on Sequences
Constructors on Sequences
op:to(decimal $firstval, decimal $lastval) => sequence
Functions and Operators on Sequences
xf:boolean(item* $srcval) => boolean
op:concatenate(item* $seq1, item* $seq2) => item*
op:item-at(item* $seqParam, decimal $posParam) => item?
xf:index-of(item* $seqParam, item $srchParam) => unsignedInt?
xf:index-of(item* $seqParam, item $srchParam, anyURI $collationLiteral) => unsignedInt?
xf:empty(item* $srcval) => boolean
xf:exists(item* $srcval) => boolean
xf:distinct-nodes(node* $srcval) => node*
xf:distinct-values(item* $srcval) => item*
xf:distinct-values(item* $srcval, anyURI $collationLiteral) => item*
xf:insert(item* $target, decimal $position, item* $inserts) => item*
xf:remove(item* $target, decimal $position) => item*
xf:subsequence(item* $sourceSeq, decimal $startingLoc) => item*
xf:subsequence(item* $sourceSeq, decimal $startingLoc, decimal $length) => item*
Equals, Union, Intersection and Except
xf:sequence-deep-equal(item* $parameter1, item* $parameter2) => boolean?
xf:sequence-deep-equal(item* $parameter1, item* $parameter2, anyURI $collationLiteral) => boolean?
xf:sequence-node-equal(item*? $parameter1, item*? $parameter2) => boolean?
op:union(node* $parameter1, node* $parameter2) => node*
op:intersect(node* $parameter1, node* $parameter2) => node*
op:except(node* $parameter1, node* $parameter2) => node*
Aggregate Functions
xf:count(item* $srcval) => unsignedInt
xf:avg(item* $srcval) => double?
xf:max(item* $srcval) => anySimpleType?
xf:max(item* $srcval, anyURI $collationLiteral) => anySimpleType?
xf:min(item* $srcval) => anySimpleType?
xf:min(item* $srcval, anyURI $collationLiteral) => anySimpleType?
xf:sum(item* $srcval) => double
Functions that Generate Sequences
xf:id(IDREF* $srcval) => elementNode*
xf:idref(string* $srcval) => elementNode*
xf:filter(expression $srcval) => node*
xf:document(anyURI* $srcval1) => node*
xf:document(anyURI* $srcval1, node* $srcval2) => node*
xf:collection(string $srcval) => node*
xf:input() => node*
Context Functions
xf:context-item
xf:context-item() => item
xf:position
xf:position() => unsignedInt
xf:last
xf:last() => unsignedInt
op:context-document
op:context-document() => DocumentNode
xf:current-dateTime

D.2 Functions and Operators Alphabetically

xf:add-days(date? $dateParam, decimal? $incrDays) => date?
op:add-dayTimeDuration-to-date(date $srcval1, dayTimeDuration $srcval2) => dateTime
op:add-dayTimeDuration-to-dateTime(dateTime $srcval1, dayTimeDuration $srcval2) => dateTime
op:add-dayTimeDuration-to-time(time $srcval1, dayTimeDuration $srcval2) => time
op:add-dayTimeDurations(dayTimeDuration $srcval1, dayTimeDuration $srcval2) => dayTimeDuration
op:add-yearMonthDuration-to-date(date $srcval1, yearMonthDuration $srcval2) => date
op:add-yearMonthDuration-to-dateTime(dateTime $srcval1, yearMonthDuration $srcval2) => dateTime
op:add-yearMonthDurations(yearMonthDuration $srcval1, yearMonthDuration $srcval2) => yearMonthDuration
xf:anyURI(string $srcval) => anyURI
op:anyURI-equal(anyURI $srcval1, anyURI $srcval2) => boolean
xf:avg(item* $srcval) => double?
xf:base-uri(node $srcval) => anyURI?
op:base64-binary-equal(base64Binary $value1, base64Binary $value2) => boolean
xf:boolean(item* $srcval) => boolean
op:boolean-equal(boolean? $value1, boolean? $value2) => boolean?
xf:boolean-from-string(string $srcval) => boolean
op:boolean-greater-than(boolean $srcval1, boolean $srcval2) => boolean
op:boolean-less-than(boolean $srcval1, boolean $srcval2) => boolean
xf:byte(string $srcval) => integer
xf:ceiling(double? $srcval) => integer?
xf:collection(string $srcval) => node*
xf:compare(string? $comparand1, string? $comparand2) => integer?
xf:compare(string? $comparand1, string? $comparand2, anyURI $collationLiteral) => integer?
xf:concat() => string
xf:concat(string? $op1) => string
xf:concat(string? $op1, string? $op2, ...) => string
op:concatenate(item* $seq1, item* $seq2) => item*
xf:contains(string? $operand1, string? $operand2) => boolean?
xf:contains(string? $operand1, string? $operand2, anyURI $collationLiteral) => boolean?
op:context-document() => DocumentNode
xf:context-item() => item
xf:copy(node? $srcval) => node?
xf:count(item* $srcval) => unsignedInt
xf:current-dateTime() => dateTime
xf:data(node* $srcval) => value*
xf:date(string $srcval) => date
xf:dateTime(string $srcval) => dateTime
op:datetime-equal(dateTime $operand1, dateTime $operand2) => boolean
op:datetime-greater-than(dateTime $operand1, dateTime $operand2) => boolean
op:datetime-less-than(dateTime $operand1, dateTime $operand2) => boolean
xf:dayTimeDuration(string $srcval) => dayTimeDuration
op:dayTimeDuration-equal(dayTimeDuration $operand1, dayTimeDuration $operand2) => boolean
xf:dayTimeDuration-from-seconds(decimal $srcval) => dayTimeDuration
op:dayTimeDuration-greater-than(dayTimeDuration $operand1, dayTimeDuration $operand2) => boolean
op:dayTimeDuration-less-than(dayTimeDuration $operand1, dayTimeDuration $operand2) => boolean
xf:decimal(string $srcval) => decimal
xf:deep-equal(node $parameter1, node $parameter2) => boolean
xf:deep-equal(node $parameter1, node $parameter2, anyURI $collation) => boolean
xf:distinct-nodes(node* $srcval) => node*
xf:distinct-values(item* $srcval) => item*
xf:distinct-values(item* $srcval, anyURI $collationLiteral) => item*
op:divide-dayTimeDuration(dayTimeDuration $srcval1, decimal $srcval2) => yearMonthDuration
op:divide-yearMonthDuration(yearMonthDuration $srcval1, decimal $srcval2) => yearMonthDuration
xf:document(anyURI* $srcval1) => node*
xf:document(anyURI* $srcval1, node* $srcval2) => node*
xf:double(string $srcval) => double
xf:duration(string $srcval) => duration
op:duration-equal(duration $operand1, duration $operand2) => boolean
xf:empty(item* $srcval) => boolean
xf:ends-with(string? $operand1, string? $operand2) => boolean?
xf:ends-with(string? $operand1, string? $operand2, anyURI $collationLiteral) => boolean?
xf:ENTITY(string $srcval) => ENTITY
op:except(node* $parameter1, node* $parameter2) => node*
xf:exists(item* $srcval) => boolean
xf:false() => boolean
xf:filter(expression $srcval) => node*
xf:float(string $srcval) => float
xf:floor(double? $srcval) => integer?
xf:gDay(string $srcval) => gDay
xf:get-day-from-date(date? $srcval) => integer?
xf:get-day-from-dateTime(dateTime? $srcval) => integer?
xf:get-days-from-dayTimeDuration(dayTimeDuration? $srcval) => integer?
xf:get-dayTimeDuration(dateTime $srcval1, dateTime $srcval2) => dayTimeDuration
xf:get-hours-from-dateTime(dateTime? $srcval) => integer?
xf:get-hours-from-dayTimeDuration(dayTimeDuration? $srcval) => integer?
xf:get-hours-from-time(time? $srcval) => integer?
xf:get-local-name(QName? $srcval) => string?
xf:get-minutes-from-dateTime(dateTime? $srcval) => integer?
xf:get-minutes-from-dayTimeDuration(dayTimeDuration? $srcval) => integer?
xf:get-minutes-from-time(time? $srcval) => integer?
xf:get-month-from-date(date? $srcval) => integer?
xf:get-month-from-dateTime(dateTime? $srcval) => integer?
xf:get-months-from-yearMonthDuration(yearMonthDuration? $srcval) => integer?
xf:get-namespace-uri(QName? $srcval) => anyURI?
xf:get-seconds-from-dateTime(dateTime? $srcval) => decimal?
xf:get-seconds-from-dayTimeDuration(dayTimeDuration? $srcval) => integer?
xf:get-seconds-from-time(time? $srcval) => decimal?
xf:get-timezone-from-date(date? $srcval) => string?
xf:get-timezone-from-dateTime(dateTime? $srcval) => string?
xf:get-timezone-from-time(time? $srcval) => string?
xf:get-year-from-date(date? $srcval) => integer?
xf:get-year-from-dateTime(dateTime? $srcval) => integer?
xf:get-yearMonthDuration(dateTime $srcval1, dateTime $srcval2) => yearMonthDuration
xf:get-years-from-yearMonthDuration(yearMonthDuration? $srcval) => integer?
xf:gMonth(string $srcval) => gMonth
xf:gMonthDay(string $srcval) => gMonthDay
xf:gYear(string $srcval) => gYear
xf:gYearMonth(string $srcval) => gYearMonth
op:hex-binary-equal(hexBinary $value1, hexBinary $value2) => boolean
xf:ID(string $srcval) => ID
xf:id(IDREF* $srcval) => elementNode*
xf:IDREF(string $srcval) => IDREF
xf:idref(string* $srcval) => elementNode*
xf:if-absent((elementNode | attributeNode)? $node, anySimpleType $value) => (elementNode | attributeNode | anySimpleType)?
xf:if-empty((elementNode | attributeNode)? $node, anySimpleType $value) => (elementNode | attributeNode | anySimpleType)
xf:index-of(item* $seqParam, item $srchParam) => unsignedInt?
xf:index-of(item* $seqParam, item $srchParam, anyURI $collationLiteral) => unsignedInt?
xf:input() => node*
xf:insert(item* $target, decimal $position, item* $inserts) => item*
xf:int(string $srcval) => integer
xf:integer(string $srcval) => integer
op:intersect(node* $parameter1, node* $parameter2) => node*
op:item-at(item* $seqParam, decimal $posParam) => item?
xf:lang(string $testlang) => boolean
xf:language(string $srcval) => language
xf:last() => unsignedInt
xf:local-name() => string
xf:local-name(node $srcval) => string
xf:long(string $srcval) => integer
xf:lower-case(string? $srcval) => string?
xf:match(string? $srcval, string? $regexp) => integer*
xf:max(item* $srcval) => anySimpleType?
xf:max(item* $srcval, anyURI $collationLiteral) => anySimpleType?
xf:min(item* $srcval) => anySimpleType?
xf:min(item* $srcval, anyURI $collationLiteral) => anySimpleType?
op:multiply-dayTimeDuration(dayTimeDuration $srcval1, decimal $srcval2) => dayTimeDuration
op:multiply-yearMonthDuration(yearMonthDuration $srcval1, decimal $srcval2) => yearMonthDuration
xf:Name(string $srcval) => Name
xf:name() => string
xf:name(node* $srcval) => string
xf:namespace-uri() => string
xf:namespace-uri(node* $srcval) => string
xf:NCName(string $srcval) => NCName
xf:NMTOKEN(string $srcval) => NMTOKEN
op:node-after(node $parameter1, node $parameter2) => boolean
op:node-before(node $parameter1, node $parameter2) => boolean
op:node-equal(node $parameter1, node $parameter2) => boolean
op:node-follows(node $srvcal1, node $srcval2) => boolean
xf:node-kind(node $srcval) => string
xf:node-name(node $srcval) => QName?
op:node-precedes(node $srcval1, node $srcval2) => boolean
xf:normalize-space(string? $srcval) => string?
xf:normalize-unicode(string? $srcval) => string?
xf:normalize-unicode(string? $srcval, string $normalizationForm) => string?
xf:normalizedString(string $srcval) => normalizedString
xf:not(item* $srcval) => boolean
xf:NOTATION(string $srcval) => NOTATION
op:NOTATION-equal(NOTATION $srcval1, NOTATION $srcval2) => boolean
xf:number() => anySimpleType
xf:number(node $srcval) => anySimpleType
op:numeric-add(numeric $operand1, numeric $operand2) => numeric
op:numeric-divide(numeric $operand1, numeric $operand2) => numeric
op:numeric-equal(numeric $operand1, numeric $operand2) => boolean
op:numeric-greater-than(numeric $operand1, numeric $operand2) => boolean
op:numeric-less-than(numeric $operand1, numeric $operand2) => boolean
op:numeric-mod(numeric $operand1, numeric $operand2) => numeric
op:numeric-multiply(numeric $operand1, numeric $operand2) => numeric
op:numeric-subtract(numeric $operand1, numeric $operand2) => numeric
op:numeric-unary-minus(numeric $operand) => numeric
op:numeric-unary-plus(numeric $operand) => numeric
xf:position() => unsignedInt
xf:QName(string $paramLocal) => QName
op:QName-equal(QName $srcval1, QName $srcval2) => boolean
xf:QName-from-string(string $param) => QName
xf:QName-from-uri(string $paramURI, string $paramLocal) => QName
xf:remove(item* $target, decimal $position) => item*
xf:replace(string? $srcval, string? $regexp, string? $repval) => string?
xf:resolve-URI(anyURI $base, anyURI $relative) => anyURI
xf:root(node $srcval) => node
xf:round(double? $srcval) => integer?
xf:sequence-deep-equal(item* $parameter1, item* $parameter2) => boolean?
xf:sequence-deep-equal(item* $parameter1, item* $parameter2, anyURI $collationLiteral) => boolean?
xf:sequence-node-equal(item*? $parameter1, item*? $parameter2) => boolean?
xf:shallow(node? $srcval) => node?
xf:short(string $srcval) => integer
xf:starts-with(string? $operand1, string? $operand2) => boolean?
xf:starts-with(string? $operand1, string? $operand2, anyURI $collationLiteral) => boolean?
xf:string() => string
xf:string(item* $srcval) => string
xf:string(string $srcval) => string
xf:string-length(string? $srcval) => integer?
xf:string-pad(string? $padString, decimal? $padCount) => string?
xf:subsequence(item* $sourceSeq, decimal $startingLoc) => item*
xf:subsequence(item* $sourceSeq, decimal $startingLoc, decimal $length) => item*
xf:substring(string? $sourceString, decimal? $startingLoc) => string?
xf:substring(string? $sourceString, decimal? $startingLoc, decimal? $length) => string?
xf:substring-after(string? $operand1, string? $operand2) => string?
xf:substring-after(string? $operand1, string? $operand2, anyURI $collationLiteral) => string?
xf:substring-before(string? $operand1, string? $operand2) => string?
xf:substring-before(string? $operand1, string? $operand2, anyURI $collationLiteral) => string?
op:subtract-dayTimeDuration-from-date(date $srcval1, dayTimeDuration $srcval2) => date
op:subtract-dayTimeDuration-from-dateTime(dateTime $srcval1, dayTimeDuration $srcval2) => dateTime
op:subtract-dayTimeDuration-from-time(time $srcval1, dayTimeDuration $srcval2) => time
op:subtract-dayTimeDurations(dayTimeDuration $srcval1, dayTimeDuration $srcval2) => dayTimeDuration
op:subtract-yearMonthDuration-from-date(date $srcval1, yearMonthDuration $srcval2) => date
op:subtract-yearMonthDuration-from-dateTime(dateTime $srcval1, yearMonthDuration $srcval2) => dateTime
op:subtract-yearMonthDurations(yearMonthDuration $srcval1, yearMonthDuration $srcval2) => yearMonthDuration
xf:sum(item* $srcval) => double
xf:time(string $srcval) => time
op:to(decimal $firstval, decimal $lastval) => sequence
xf:token(string $srcval) => token
xf:translate(string? $srcval, string? $mapString, string? $transString) => string?
xf:true() => boolean
op:union(node* $parameter1, node* $parameter2) => node*
xf:unique-ID(node $srcval) => ID?
xf:upper-case(string? $srcval) => string?
xf:yearMonthDuration(string $srcval) => yearMonthDuration
op:yearMonthDuration-equal(yearMonthDuration $operand1, yearMonthDuration $operand2) => boolean
xf:yearMonthDuration-from-months(integer $srcval) => yearMonthDuration
op:yearMonthDuration-greater-than(yearMonthDuration $operand1, yearMonthDuration $operand2) => boolean
op:yearMonthDuration-less-than(yearMonthDuration $operand1, yearMonthDuration $operand2) => boolean