XQuery 1.0 and XPath 2.0 Functions and Operators

1.2 Namespaces and Prefixes

The functions and operators discussed in this document are contained in one of four namespaces (see [Namespaces in XML]) and referenced using a xs:QName. Constructor functions for the built-in datatypes defined in [XML Schema Part 2: Datatypes Second Edition] discussed in 5 Constructor Functions are in the XML Schema namespace, http://www.w3.org/2001/XMLSchema, and named in this document using the xs prefix. The namespace prefix used in this document for functions that are available to users is fn. Operator functions are named with the prefix op.

The datatypes described in Section 2.6 Types^DM of the Data Model and 10.3 Two Totally Ordered Subtypes of Duration in this document are contained in a separate namespace and are named using the prefix xdt.

This document uses the prefix err to represent the namespace URI http://www.w3.org/2005/xqt-errors, which is the namespace for all XPath and XQuery error codes and messages. This namespace prefix is not predeclared and its use in this document is not normative.

The namespace prefix used for the functions, datatypes and errors can vary, as long as the prefix is bound to the correct URI.

The URIs of the namespaces and the default prefixes associated with them are:

• http://www.w3.org/2001/XMLSchema for constructors -- associated with xs.

• http://www.w3.org/2005/xpath-functions for functions -- associated with fn.

• http://www.w3.org/2005/xpath-datatypes for the datatypes -- associated with xdt.

• http://www.w3.org/2005/xqt-errors -- associated with err.

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

1.3 Function Overloading

In general, the specifications named above do not support function overloading in the sense that functions that have multiple signatures with the same name and the same number of parameters are not supported. Consequently, there are no such overloaded functions in this document except for legacy [XML Path Language (XPath) Version 1.0] functions such as fn:string(), which accepts a single parameter of a variety of types. In addition, it should be noted that the functions defined in 6 Functions and Operators on Numerics that accept numeric parameters accept arguments of type xs:integer, xs:decimal, xs:float or xs:double. See 1.4 Function Signatures and Descriptions. Operators such as "+" may be overloaded. This document does define some functions with more than one signature with the same name and different number of parameters. User-defined functions with more than one signature with the same name and different number of parameters are also supported.

1.4 Function Signatures and Descriptions

Each function is defined by specifying its signature, a description of the return type and each of the parameters and its semantics. For many functions, examples are included to illustrate their use.

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

In this notation, function-name, in bold-face, is the name of the function whose signature is being specified. If the function takes no parameters, then the name is followed by an empty parameter list: "()"; otherwise, the name is followed by a parenthesized list of parameter declarations, each declaration specifies the static type of the parameter, in italics, and a descriptive, but non-normative, name. If there are two or more parameter declarations, they are separated by a comma. The return-type , also in italics, specifies the static type of the value returned by the function. The dynamic type returned by the function is the same as its static type or derived from the static type. All parameter types and return types are specified using the SequenceType notation defined in Section 2.5.3 SequenceType Syntax^XP.

In some cases the word " numeric " is used in function signatures as a shorthand to indicate the four numeric types: xs:integer, xs:decimal, xs:float and xs:double. For example, a function with the signature

For most functions there is an initial paragraph describing what the function does followed by semantic rules. These rules are meant to be followed in the order that they appear in this document.

In some cases, the static type returned by a function depends on the type(s) of its argument(s). These special functions are indicated by using bold italics for the return type. The semantic rules specifying the type of the value returned are documented in the function definition. The rules are described more formally in Section 7.2 Standard functions with specific typing rules^FS.

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

Rules for passing parameters to operators are described in the relevant sections of [XQuery 1.0: An XML Query Language] and [XML Path Language (XPath) 2.0]. For example, the rules for passing parameters to arithmetic operators are described in Section 3.4 Arithmetic Expressions^XP. Specifically, rules for parameters of type xdt:untypedAtomic and the empty sequence are specified in this section.

As is customary, the parameter type name indicates that the function or operator accepts arguments of that type, or types derived from it, in that position. This is called subtype substitution (See Section 2.5.4 SequenceType Matching^XP). In addition, numeric type instances and instances of type xs:anyURI can be promoted to produce an argument of the required type. (See Section B.1 Type Promotion^XP).

1. Subtype Substitution: A derived type may substitute for its base type. In particular, xs:integer may be used where xs:decimal is expected.

2. Numeric Type Promotion: xs:decimal may be promoted to xs:float or xs:double. Promotion to xs:double should be done directly, not via xs:float, to avoid loss of precision.

3. anyURI Type Promotion: A value of type xs:anyURI can be promoted to the type xs:string.

Some functions accept a single value or the empty sequence as an argument and some may return a single value or the empty sequence. This is indicated in the function signature by following the parameter or return type name with a question mark: "?", indicating that either a single value or the empty sequence must appear. See below.

Note that this function signature is different from a signature in which the parameter is omitted. See, for example, the two signatures for fn:string(). In the first signature, the parameter is omitted and the argument defaults to the context item, referred to as ".". In the second signature, the argument must be present but may be the empty sequence, referred to as "()."

Some functions accept a sequence of zero or more values as an argument. This is indicated by following the name of type of the items in the sequence with *. The sequence may contain zero or more items of the named type. For example, the function below accepts a sequence of xs:double and returns a xs:double or the empty sequence.

1.5 Namespace Terminology

This document uses the phrase "namespace URI" to identify the concept identified in [Namespaces in XML] as "namespace name", and the phrase "local name" to identify the concept identified in [Namespaces in XML] as "local part".

It also uses the term "expanded-QName" defined below.

[Definition] Expanded-QName

An expanded-QName is a pair of values consisting of a namespace URI and a local name. They belong to the value space of the [XML Schema Part 2: Datatypes Second Edition] datatype xs:QName. When this document refers to xs:QName we always mean the value space, i.e. a namespace URI, local name pair (and not the lexical space referring to constructs of the form prefix:local-name).

1.6 Type Hierarchy

The diagram below shows the types for which functions are defined in this document. These include the built-in types defined by [XML Schema Part 2: Datatypes Second Edition] (shown on the right) as well as types defined in [XQuery 1.0 and XPath 2.0 Data Model] (shown on the left). Solid lines connect a base datatype above to a derived datatype.xs:IDREFS, xs:NMTOKENS, xs:ENTITIES and user-defined list and union types are special types in that these types are lists or unions rather than true subtypes. Dashed lines connect a union type above with its component types below.

The information in the above diagram is reproduced below in tabular form. For ease of presentation the information is divided into three tables. The first table shows the top three layers of the hierarchy starting at xs:anyType. The second table shows the types derived from xdt:anyAtomicType. The third table shows the types defined in [XQuery 1.0 and XPath 2.0 Data Model]

Each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.

The table below shows the datatypes derived from xdt:anyAtomicType. This includes all the [XML Schema Part 2: Datatypes Second Edition] built-in datatypes as well as the two totally ordered subtypes of duration defined 10.3 Two Totally Ordered Subtypes of Duration.

Each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.

The table below shows the type hierarchy for the types introduced in [XQuery 1.0 and XPath 2.0 Data Model]. For these types, each type whose name is indented is a component of the union type whose name appears nearest above with one less level of indentation.

1.7 Terminology

The terminology used to describe the functions and operators on [XML Schema Part 2: Datatypes Second Edition] is defined in the body of this specification. The terms defined in 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 [XML Path Language (XPath) Version 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 either non-conformant or else in error.

[Definition] implementation-defined

Possibly differing between implementations, but specified and documented 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.

[Definition] execution scope

The scope over which any two calls on a function would be executed. In XSLT, it applies to any two calls on the function executed during the same transformation. In XQuery, it applies to any two calls executed during the evaluation of a top-level expression i.e. an expression not contained in any other expression. In other contexts, the scope is specified by the host environment that invokes the function library.

[Definition] stable

Most of the functions in the core library have the property that calling the same function twice within an ·execution scope· with the same arguments returns the same result: these functions are said to to be stable. This category includes a number of functions such as fn:doc(), fn:collection(), fn:current-dateTime(), fn:current-date and fn:current-time() whose result depends on the external environment. Where the function returns nodes, stability means that the returned nodes are identical, not merely equal and are returned in the same order.. Some other functions, for example fn:position() and fn:last(), depend on the dynamic context and may, therefore, produce different results each time they are called. These functions are said to be contextual.

Some other functions, for example fn:position() and fn:last(), depend on the dynamic context and may, therefore, produce different results each time they are called. These functions are said to be contextual.

[Definition] URI and URI reference

Within this specification, the term "URI" refers to Universal Resource Identifiers as defined in [RFC 3986] and extended in [RFC 3987] with a new name "IRI". The term "URI Reference", unless otherwise stated, refers to a string in the lexical space of the xs:anyURI datatype as defined in [XML Schema Part 2: Datatypes Second Edition]. Note that this means, in practice, that where this specification requires a "URI Reference", an IRI as defined in [RFC 3987] will be accepted, provided that other relevant specifications also permit an IRI. The term URI has been retained in preference to IRI to avoid introducing new names for concepts such as "Base URI" that are defined or referenced across the whole family of XML specifications. Note also that the definition of xs:anyURI is a wider definition than the definition in [RFC 3987]; for example it does not require non-ASCII characters to be escaped.

2.1 fn:node-name

Summary: Returns an expanded-QName for node kinds that can have names. For other kinds of nodes it returns the empty sequence. If $arg is the empty sequence, the empty sequence is returned.

2.2 fn:nilled

Summary: Returns an xs:boolean indicating whether the argument node is "nilled". If the argument is not an element node, returns the empty sequence. If the argument is the empty sequence, returns the empty sequence.

2.3 fn:string

Summary: Returns the value of $arg represented as a xs:string. If no argument is supplied, this function returns the string value of the context item (.).

If no argument is supplied and the context item is undefined, an error is raised:

If $arg is the empty sequence, the zero-length string is returned.

If $arg is a node, the function returns the string-value of the node, as obtained using the dm:string-value accessor defined in the Section 5.13 string-value Accessor^DM.

If $arg is an atomic value, then the function returns the same string as is returned by the expression " $arg cast as xs:string " (see 17 Casting).

2.4 fn:data

Summary: fn:data takes a sequence of items and returns a sequence of atomic values.

The result of fn:data is the sequence of atomic values produced by applying the following rules to each item in $arg:

• If the item is an atomic value, it is returned.

• If the item is a node:

  • If the node does not have a typed value an error is raised

    [err:FOTY0012]
    .

  • Otherwise, fn:data() returns the typed value of the node as defined by the accessor function dm:typed-value in Section 5.15 typed-value Accessor^DM.

2.5 fn:base-uri

Summary: Returns the value of the base-uri property for $arg as defined by the accessor function dm:base-uri() for that kind of node in Section 5.2 base-uri Accessor^DM. If $arg is not specified, returns the value of the base-uri property of the context item (.) with the above semantics. If the context item is not a node, an error is raised:

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

Document, element and processing-instruction nodes have a base-uri property which may be empty. The base-uri property of all other node types is the empty sequence. The value of the base-uri property is returned if it exists and is not empty. Otherwise, if the node has a parent, the value of dm:base-uri() applied to its parent is returned, recursively. If the node does not have a parent, or if the recursive ascent up the ancestor chain encounters a node whose base-uri property is empty and it does not have a parent, the empty sequence is returned.

See also fn:static-base-uri.

2.6 fn:document-uri

Summary: Returns the value of the document-uri property for $arg as defined by the dm:document-uri accessor function defined in Section 6.1.2 Accessors^DM.

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

Returns the empty sequence if the node is not a document node. Otherwise, returns the value of the dm:document-uri accessor of the document node.

If fn:document-uri($arg) does not return the empty sequence, then the following expression always holds:

 fn:doc(fn:document-uri($arg)) is $arg

3.1 Examples

• fn:error() returns http://www.w3.org/2005/xqt-errors#FOER0000 to the external processing environment.

• fn:error(fn:QName('http://www.example.com/HR', 'myerr:toohighsal'), 'Does not apply because salary is too high') returns http://www.example.com/HR#toohighsal and the xs:string "Does not apply because salary is too high" to the external processing environment.

4.1 Examples

• Consider a situation in which a user wants to investigate the actual value passed to a function. Assume that in a particular execution, $v is an xs:decimal with value 124.84. Writing fn:trace($v, 'the value of $v is:') will put the strings "124.84" and "the value of $v is:" in the trace data set in implementation dependent order.

5.1 Constructor Functions for XML Schema Built-in Types

Every built-in atomic type that is defined in [XML Schema Part 2: Datatypes Second Edition], except xs:NOTATION, has an associated constructor function; as do xdt:untypedAtomic, defined in Section 2.6 Types^DM and the two derived types xdt:yearMonthDuration and xdt:dayTimeDuration defined in 10.3 Two Totally Ordered Subtypes of Duration. A constructor function is not defined for xs:NOTATION since it is defined as an abstract type in [XML Schema Part 2: Datatypes Second Edition]. If the static context (See Section 2.1.1 Static Context^XP) contains a type derived from xs:NOTATION then a constructor function is defined for it. See 5.3 Constructor Functions for User-Defined Types.

The form of the constructor function for a type prefix:TYPE is:

If $arg is the empty sequence, the empty sequence is returned. For example, the signature of the constructor function corresponding to the xs:unsignedInt type defined in [XML Schema Part 2: Datatypes Second Edition] is:

Invoking the constructor function xs:unsignedInt(12) returns the xs:unsignedInt value 12. Another invocation of that constructor function that returns the same xs:unsignedInt value is xs:unsignedInt("12"). The same result would also be returned if the constructor function were to be invoked with a node that had a typed value equal to the xs:unsignedInt 12. The standard features described in Section 2.4.2 Atomization^XP would 'atomize' the node to extract its typed value and then call the constructor with that value. If the value passed to a constructor is illegal for the datatype to be constructed, an error is raised

The semantics of the constructor function " xs:TYPE(arg) " are identical to the semantics of " arg cast as xs:TYPE? ", except for constructors for xs:QName and types derived from xs:NOTATION which are identical to "cast as xs:TYPE ". See 17 Casting.

If the argument to a constructor function is a literal, the result of the function may be evaluated statically; if an error is found during such evaluation, it may be reported as a static error.

Constructor functions for xs:QName and types derived from xs:QName and xs:NOTATION, are constrained to take a xs:string literal as their argument. (This means that they are actually pseudo-functions: they can always be evaluated statically). A static error is raised [err:XPST0083]^XP if the argument to a constructor function for xs:QName or a type derived from xs:QName or xs:NOTATION is not an xs:string literal.

The prefix within the lexical xs:QName supplied as the argument is resolved to a namespace URI using the statically known namespaces from the static context. If the lexical xs:QName has no prefix, the namespace URI of the resulting expanded-QName is the default element/type namespace from the static context. Components of the static context are discussed in Section C.1 Static Context Components^XP. A static error is raised

The following constructor functions for the built-in types are supported:

• xs:string($arg as xdt:anyAtomicType?) as xs:string?
• xs:boolean($arg as xdt:anyAtomicType?) as xs:boolean?
• xs:decimal($arg as xdt:anyAtomicType?) as xs:decimal?
• xs:float($arg as xdt:anyAtomicType?) as xs:float?

  Implementations ·may· return negative zero for xs:float("-0.0E0"). [XML Schema Part 2: Datatypes Second Edition] does not distinguish between the values positive zero and negative zero.

• xs:double($arg as xdt:anyAtomicType?) as xs:double?

  Implementations ·may· return negative zero for xs:double("-0.0E0"). [XML Schema Part 2: Datatypes Second Edition] does not distinguish between the values positive zero and negative zero.

• xs:duration($arg as xdt:anyAtomicType?) as xs:duration?
• xs:dateTime($arg as xdt:anyAtomicType?) as xs:dateTime?
• xs:time($arg as xdt:anyAtomicType?) as xs:time?
• xs:date($arg as xdt:anyAtomicType?) as xs:date?
• xs:gYearMonth($arg as xdt:anyAtomicType?) as xs:gYearMonth?
• xs:gYear($arg as xdt:anyAtomicType?) as xs:gYear?
• xs:gMonthDay($arg as xdt:anyAtomicType?) as xs:gMonthDay?
• xs:gDay($arg as xdt:anyAtomicType?) as xs:gDay?
• xs:gMonth($arg as xdt:anyAtomicType?) as xs:gMonth?
• xs:hexBinary($arg as xdt:anyAtomicType?) as xs:hexBinary?
• xs:base64Binary($arg as xdt:anyAtomicType?) as xs:base64Binary?
• xs:anyURI($arg as xdt:anyAtomicType?) as xs:anyURI?
• xs:QName($arg as xs:string) as xs:QName

  $arg must be a xs:string literal.

• xs:normalizedString($arg as xdt:anyAtomicType?) as xs:normalizedString?
• xs:token($arg as xdt:anyAtomicType?) as xs:token?
• xs:language($arg as xdt:anyAtomicType?) as xs:language?
• xs:NMTOKEN($arg as xdt:anyAtomicType?) as xs:NMTOKEN?
• xs:Name($arg as xdt:anyAtomicType?) as xs:Name?
• xs:NCName($arg as xdt:anyAtomicType?) as xs:NCName?
• xs:ID($arg as xdt:anyAtomicType?) as xs:ID?
• xs:IDREF($arg as xdt:anyAtomicType?) as xs:IDREF?
• xs:ENTITY($arg as xdt:anyAtomicType?) as xs:ENTITY?

  See 17.4.1 Casting to xs:ENTITY for rules related to constructing values of type xs:ENTITY and types derived from it.

• xs:integer($arg as xdt:anyAtomicType?) as xs:integer?
• xs:nonPositiveInteger($arg as xdt:anyAtomicType?) as xs:nonPositiveInteger?
• xs:negativeInteger($arg as xdt:anyAtomicType?) as xs:negativeInteger?
• xs:long($arg as xdt:anyAtomicType?) as xs:long?
• xs:int($arg as xdt:anyAtomicType?) as xs:int?
• xs:short($arg as xdt:anyAtomicType?) as xs:short?
• xs:byte($arg as xdt:anyAtomicType?) as xs:byte?
• xs:nonNegativeInteger($arg as xdt:anyAtomicType?) as xs:nonNegativeInteger?
• xs:unsignedLong($arg as xdt:anyAtomicType?) as xs:unsignedLong?
• xs:unsignedInt($arg as xdt:anyAtomicType?) as xs:unsignedInt?
• xs:unsignedShort($arg as xdt:anyAtomicType?) as xs:unsignedShort?
• xs:unsignedByte($arg as xdt:anyAtomicType?) as xs:unsignedByte?
• xs:positiveInteger($arg as xdt:anyAtomicType?) as xs:positiveInteger?

• xdt:yearMonthDuration($arg as xdt:anyAtomicType?) as xdt:yearMonthDuration?
• xdt:dayTimeDuration($arg as xdt:anyAtomicType?) as xdt:dayTimeDuration?
• xdt:untypedAtomic($arg as xdt:anyAtomicType?) as xdt:untypedAtomic?

5.2 A Special Constructor Function for xs:dateTime

A special constructor function is provided for constructing a xs:dateTime value from a xs:date value and a xs:time value.

The result xs:dateTime has a date component whose value is equal to $arg1 and a time component whose value is equal to $arg2. The timezone of the result is computed as follows:

• If neither argument has a timezone, the result has no timezone.

• If exactly one of the arguments has a timezone, or if both arguments have the same timezone, the result has this timezone.

• If the two arguments have different timezones, an error is raised:

  [err:FORG0008]

5.3 Constructor Functions for User-Defined Types

For every atomic type in the static context (See Section 2.1.1 Static Context^XP) that is derived from a primitive type, there is a constructor function (whose name is the same as the name of the type) whose effect is to create a value of that type from the supplied argument. The rules for constructing user-defined types are defined in the same way as the rules for constructing built-in derived types discussed in 5.1 Constructor Functions for XML Schema Built-in Types.

Consider a situation where the static context contains a type called hatSize defined in a schema whose target namespace is bound to the prefix my. In such a case the constructor function:

is available to users.

To construct an instance of an atomic type that is not in a namespace, it is necessary to use a cast expression or undeclare the default function namespace. For example, if the user-defined type apple is derived from xs:integer but is not in a namespace, an instance of this type can be constructed as follows using a cast expression (this requires that the default element/type namespace is no namespace):

17 cast as apple

The following shows the use of the constructor function:

declare default function namespace ""; apple(17)

6.1 Numeric Types

The operators described in this section are defined on the following numeric types. Each type whose name is indented is derived from the type whose name appears nearest above with one less level of indentation.

They also apply to types derived by restriction from the above types.

6.2 Operators on Numeric Values

The following functions define the semantics of operators defined in [XQuery 1.0: An XML Query Language] and [XML Path Language (XPath) 2.0] on these numeric types.

The parameters and return types for the above operators are the basic numeric types: xs:integer, xs:decimal, xs:float and xs:double, and types derived from them. The word " numeric " in function signatures signifies these four types. For simplicity, each operator is defined to operate on operands of the same type and return the same type. The exceptions are op:numeric-divide, which returns an xs:decimal if called with two xs:integer operands and op:numeric-integer-divide which always returns an xs:integer.

If the two operands are not of the same type, subtype substitution and numeric type promotion are used to obtain two operands of the same type. Section B.1 Type Promotion^XP and Section B.2 Operator Mapping^XP describe the semantics of these operations in detail.

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