XQuery 1.0 and XPath 2.0 Functions and Operators Version 1.0

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 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 and other related XML standards.

The [XQuery 1.0 and XPath 2.0 Data Model] also defines several accessors on nodes such as name(), string-value(), typed-value(), parent(), children(), and node-kind(). [XQuery 1.0: An XML Query Language] defines kind tests such as text() and node(). These functions are not included in this document.

[Issue 86: In which document do the node accessors functions and the kind tests go?]

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.

Diagram courtesy Asir Vedamuthu, webMethods

[Issue 24: What effect do facets have?]

This document includes examples of the use of a number of functions. Examples for the remaining functions are tentatively planned, but feedback is solicited on the utility of the examples for those functions for which they are supplied, as well as for those for which they are not yet supplied.

1.1 Syntax

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

In general, [XQuery 1.0: An XML Query Language] does 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.2 Notations

This document defines, among other things, a number of 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; in addition, examples are given of many constructors and functions to illustrate their use.

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

function-name(parameter-type parameter-name ... ) => return-type

In that 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 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 101: Scalar functions should accept the empty sequence.]

1.3 Namespace Prefix

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

The actual namespace (that is, the URI of the namespace) is http://www.w3.org/2001/08/xquery-operators.

[Issue 13: What is the appropriate namespace to be used?]

[Issue 33: Issues should reference the source of the issues]

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

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

[Issue 39: Should all XML Schema numeric types be supported?]

2.2 Numeric Literals

The following literals are defined on the numeric types.

Literal	Returns
`n`, `+n`, or `-n` [1]	integer
`nL`, `+nL`, or `-nL` [2]	long
`n.`, `+n.`, or `-n.` , `.n`, `+.n`, or `-.n` , `n.n`, `+n.n`, or `-n.n` (with a decimal point)	decimal
`n.nEn`, `+n.nEn`, `-n.nEn`, `n.nE+n`, `+n.nE+n`, `-n.nE+n`, `n.nE-n`, `+n.nE-n`, or `-n.nE-n` [3]	float

[Issue 49: There are several syntax problems with numeric literals]

2.3 Numeric Constructors

The following constructors are defined on the above numeric types.

Constructor	Meaning
`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.

Whitespace is not allowed as part of the string argument.

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

[Issue 40: Some numeric constructors have unexpected return types]

2.3.1 xf:decimal

2.3.1.1 Signature

xf:decimal(string $srcval) => decimal

2.3.1.2 Parameters

$srcval — static type is string

2.3.1.3 Semantics

Returns the decimal value that is represented by the characters contained in the value of $srcval.

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

2.3.1.4 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 error value, since whitespace is not allowed in the argument string.

2.3.2 xf:integer

2.3.2.1 Signature

xf:integer(string $srcval) => integer

2.3.2.2 Parameters

$srcval — static type is string

2.3.2.3 Semantics

Returns the integer value that is represented by the characters contained in the value of $srcval.

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

2.3.2.4 Examples

xf:integer('-123') returns the integer value corresponding to negative one hundred twenty three.
xf:integer('123.5') returns the an error value, since the use of a decimal point is prohibited in the constructor for the integer type.

2.3.3 xf:long

2.3.3.1 Signature

xf:long(string $srcval) => integer

2.3.3.2 Parameters

$srcval — static type is string

2.3.3.3 Semantics

Returns the long value that is represented by the characters contained in the value of $srcval.

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

2.3.3.4 Examples

xf:long('-1235') returns the long value corresponding to negative one thousand two hundred thirty five.
xf:long('10000000000000000000') returns the an error value, since ten quintillion is not a valid value for the long type.

2.3.4 xf:int

2.3.4.1 Signature

xf:int(string $srcval) => integer

2.3.4.2 Parameters

$srcval — static type is string

2.3.4.3 Semantics

Returns the int value that is represented by the characters contained in the value of $srcval.

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

2.3.4.4 Examples

xf:int('1235') returns the int value corresponding to one thousand two hundred thirty five.
xf:int('2147483648') returns an 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.

2.3.5 xf:short

2.3.5.1 Signature

xf:short(string $srcval) => integer

2.3.5.2 Parameters

$srcval — static type is string

2.3.5.3 Semantics

Returns the short value that is represented by the characters contained in the value of $srcval.

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

2.3.5.4 Examples

xf:short('1235') returns the short value corresponding to one thousand two hundred thirty five.
xf:short('32768') returns an error value, since the value thirty two thousand seven hundred sixty eight is not a valid value for the short type.

2.3.6 xf:byte

2.3.6.1 Signature

xf:byte(string $srcval) => integer

2.3.6.2 Parameters

$srcval — static type is string

2.3.6.3 Semantics

Returns the byte value that is represented by the characters contained in the value of $srcval.

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

2.3.6.4 Examples

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

2.3.7 xf:float

2.3.7.1 Signature

xf:float(string $srcval) => float

2.3.7.2 Parameters

$srcval — static type is string

2.3.7.3 Semantics

Returns the float value that is represented by the characters contained in the value of $srcval.

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 an 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 an error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

[Issue 50: Should double("ZZZ") or cast as float("ZZZ") return an error or NaN? ]

2.3.7.4 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 an error value, since the use of the letter "D" is prohibited in the constructor for the float type.

2.3.8 xf:double

2.3.8.1 Signature

xf:double(string $srcval) => double

2.3.8.2 Parameters

$srcval — static type is string

2.3.8.3 Semantics

Returns the double value that is represented by the characters contained in the value of $srcval.

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

NOTE:
In XPath 1.0, double("INF") returned the "not-a-number" 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 an error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].

[Issue 50: Should double("ZZZ") or cast as float("ZZZ") return an error or NaN? ]

2.3.8.4 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 an error value, since the use of the letter "D" is prohibited in the constructor for the double type.

2.4 Operators on Numeric Values

The following operators are defined on these numeric types:

Operator	Meaning	Source
`+`	Addition	XPath 1.0
`-`	Subtraction	XPath 1.0
`*`	Multiplication	XPath 1.0
`div`	Division	XPath 1.0
`mod`	Division modulus	XPath 1.0
`+`	Unary plus	XPath 2.0 Req 1.7 Shd.
`-`	Unary minus (negation)	XPath 1.0

The arguments and return types of all arithmetic operators are primitive numeric types: decimal, float, or double. Although arithmetic operations are defined on only a few types, a simple type promotion scheme allows these operations to be performed on all arithmetic types, including derived types.

Integers, which are primitive in most language environments, are not primitive types in XML Schema. To be efficient, most implementations will probably choose to treat integer as primitive, and define promotions from integer to decimal.

The type promotion scheme includes only two rules:

Any type may be promoted to the type of its primitive ancestor (or integer if appropriate).
integer may be promoted to decimal, decimal may be promoted to float, and float may be promoted to double.

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 result type of operations (using ¤ to represent a binary operators such as +, -, *, div, and mod, as well as unary operators such as + and -), along with their argument datatypes, is defined in the table below:

Operator	Returns
integer ¤ integer	integer
decimal ¤ decimal	decimal
float ¤ float	float
double ¤ double	double
¤ integer	integer
¤ decimal	decimal
¤ float	float
¤ double	double

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

int*double => double*double

For this operation, int must be converted to double. This can be done, since int can be promoted to decimal, its most primitive ancestor, decimal can be promoted to float, and float can be promoted to double.

[Issue 78: Type promotion rules appear to be inconsistent]

Consider another example:

byte*short => decimal*decimal

This is true because the * operator is not defined on derived types. Both byte and short must be promoted to decimal so that the operation can be performed.

[Issue 72: Effects of overflow and underflow unspecified]

[Issue 105: XPath 1.0 compatibility broken for div]

2.5 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, except in the case when one or both operands are the empty sequence. In that case, the result is the empty sequence.

Operator	Meaning	Source
`=`	Equality comparison	XPath 1.0
`<`	Less-than comparison	XPath 1.0
`>`	Greater-than comparison	XPath 1.0
`<=`	Less-than-or-equal-to comparison	XPath 1.0
`>=`	Greater-than-or-equal-to comparison	XPath 1.0
`!=`	Inequality comparison	XPath 1.0

[Issue 8: Relationships Between Some Numeric Types Should Be Reconsidered]

[Issue 87: It would be convenient to have compare functions such as compare-gte rather than just one compare function.]

[Issue 113: Need more complete numeric comparison semantics]

2.6 Functions on Numeric Values

The following functions are defined on these numeric types:

Function	Meaning	Source
xf:floor	Returns the largest integer less than or equal to the argument	XPath 1.0
xf:ceiling	Returns the smallest integer greater than or equal to the argument	XPath 1.0
xf:round	Rounds to the nearest integer	XPath 1.0

[Issue 53: Certain XPath 1.0 functions and other needed functions are not included]

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

[Issue 92: The abs() function is required.]

2.6.1 xf:floor

2.6.1.1 Signature

xf:floor(double $srcval) => integer

2.6.1.2 Parameters

$srcval — static type is double

2.6.1.3 Semantics

Returns the largest (closest to positive infinity) number that is not greater than the value of $srcvaland that is an integer.

2.6.1.4 Examples

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

2.6.2 xf:ceiling

2.6.2.1 Signature

xf:ceiling(double $srcval) => integer

2.6.2.2 Parameters

$srcval — static type is double

2.6.2.3 Semantics

Returns the smallest (closest to negative infinity) number that is not smaller than the value of $srcvaland that is an integer.

2.6.2.4 Examples

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

2.6.3 xf:round

2.6.3.1 Signature

xf:round(double $srcval) => integer

2.6.3.2 Parameters

$srcval — static type is double

2.6.3.3 Semantics

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.

2.6.3.4 Examples

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

3 Constructors, Functions, and Operators on Strings

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

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

[Issue 54: Certain constructors are not useful]

3.2 String Literals

The following literals are defined on string types and produce values of the types indicated.

Literal	Returns
`"xxx"` [4]	string
`'xxx'` [5]	string

3.3 String Constructors

The following constructors are defined on string types.

Constructor	Meaning
`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]

[Issue 90: Constructors for id and idref need a document context for validity.]

[Issue 107: Notion of document context required?]

3.3.1 xf:string

3.3.1.1 Signature

xf:string(string $srcval) => string

3.3.1.2 Parameters

$srcval — static type is string

3.3.1.3 Semantics

Returns a string value that is the value of $srcval. This constructor is correctly perceived as a "no-op", but is included for the sake of orthogonality.

3.3.1.4 Examples

xf:string('abc') returns "abc".
xf:string('Jérôme') returns "Jérôme" ("̂" is the numeric code reference for the Unicode character U+0302, called "Combining Curcumflex Accent").

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.

[Issue 106: Do function invocations expand character references?]

3.3.2 xf:normalizedString

3.3.2.1 Signature

xf:normalizedString(string $srcval) => normalizedString

3.3.2.2 Parameters

$srcval — static type is string

3.3.2.3 Semantics

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

3.3.2.4 Examples

xf:normalizedString('abc') returns "abc".
xf:normalizedString('ab
cd) returns "abcd".
xf:normalizedString('abcd) returns an error value.

[Issue 106: Do function invocations expand character references?]

3.3.3 xf:token

3.3.3.1 Signature

xf:token(string $srcval) => token

3.3.3.2 Parameters

$srcval — static type is string

3.3.3.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

[Issue 46: xf:token: Should other Unicode space characters be considered?]

3.3.4 xf:language

3.3.4.1 Signature

xf:language(string $srcval) => language

3.3.4.2 Parameters

$srcval — static type is string

3.3.4.3 Semantics

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, is not a valid language identifier), the constructor returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

3.3.5 xf:Name

3.3.5.1 Signature

xf:Name(string $srcval) => Name

3.3.5.2 Parameters

$srcval — static type is string

3.3.5.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

3.3.6 xf:NMTOKEN

3.3.6.1 Signature

xf:NMTOKEN(string $srcval) => NMTOKEN

3.3.6.2 Parameters

$srcval — static type is string

3.3.6.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

3.3.7 xf:NCName

3.3.7.1 Signature

xf:NCName(string $srcval) => NCName

3.3.7.2 Parameters

$srcval — static type is string

3.3.7.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

3.3.8 xf:ID

3.3.8.1 Signature

xf:ID(string $srcval) => ID

3.3.8.2 Parameters

$srcval — static type is string

3.3.8.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

3.3.9 xf:IDREF

3.3.9.1 Signature

xf:IDREF(string $srcval) => IDREF

3.3.9.2 Parameters

$srcval — static type is string

3.3.9.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

3.3.10 xf:ENTITY

3.3.10.1 Signature

xf:ENTITY(string $srcval) => ENTITY

3.3.10.2 Parameters

$srcval — static type is string

3.3.10.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

3.4 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. In this document, we assume that collations can be named and the collation name used as an argument to the comparison function. This document will also defines the manner in which a default collation is determined, allowing the collation argument to be optional in the functions that allow it.

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

NOTE:
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.

[Issue 45: Collations: Is there a relationship to xml:lang?]

The [Character Model for the World Wide Web 1.0] recommends that all strings be normalized 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.

Function	Meaning	Source
xf:codepoint-compare	Compares two character strings on a character-by-character basis
xf:compare	Compares two character strings; a collation may optionally be specified	XSLT 2.0, Req. 2.13 (Could)

[Issue 19: Do we need collation-sensitive comparisons and another sort?]

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

[Issue 87: It would be convenient to have compare functions such as compare-gte rather than just one compare function.]

[Issue 114: codepoint-compare versus compare with special collation]

3.4.1 xf:codepoint-compare

3.4.1.1 Signature

xf:codepoint-compare(string $comparand1, string $comparand2) => integer

3.4.1.2 Parameters

$comparand1 — static type is string
$comparand2 — static type is string

3.4.1.3 Semantics

Returns -1, 0, or 1, depending on whether the value of $comparand1 is respectively less than, equal to, or greater than the value of $comparand2, compared on a character by character basis using the Unicode values for each character.

If the value of $comparand2 is longer than the value of $comparand1 and starts with the value of $comparand1, the result is -1. If the value of $comparand1 is longer and starts with the the value of $comparand2, the result is 1.

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

3.4.1.4 Examples

xf:codepoint-compare('abc', 'abd') returns -1.
xf:codepoint-compare('abc', 'abc') returns 0.
xf:codepoint-compare('abd', 'abc') returns 1.
xf:codepoint-compare('abc', 'ab') returns 1.
xf:codepoint-compare('abc', 'xy') returns -1.

3.4.2 xf:compare

3.4.2.1 Signature

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

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

3.4.2.2 Parameters

$comparand1 — static type is string
$comparand2 — static type is string
$collation — static type is anyURI

3.4.2.3 Semantics

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 $collation is specified, then the value of $collation 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 $collation, 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.

3.4.2.4 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.)

3.5 Functions on String Values

The following functions are defined on these string types:

Function	Meaning	Source
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.
xf:ends-with	Indicates whether the value of one string ends with the characters of the value of another string.
xf:codepoint-contains	Indicates whether the value of one string contains the characters of the value of another string using the default Unicode collation.
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:codepoint-substring-before	Returns the characters of one string that precede in that string the characters in the value of another string.
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:codepoint-substring-after	Returns the characters of one string that precede in that string the characters in the value of another string.
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	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-beginning	Returns the string padded in front by copies of the third argument.	XPath 2.0 Req 2.4.2, 4.4 (Should)
xf:string-pad-end	Returns the string padded at the end by copies of the third 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 56: Some functions may be redundant]

[Issue 93: Must allow case-insensitive search of text. Similarly it must support case-and-accent-insensitive search. ]

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

[Issue 104: Need equality and inequality operators for strings.]

3.5.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"]

3.5.2 xf:concat

3.5.2.1 Signature

xf:concat(string $headString, string* $otherStrings) => string

3.5.2.2 Parameters

$headString — static type is string
$otherStrings — static type is string*

3.5.2.3 Semantics

Returns the string that is the concatenation of the values of its arguments. XPath allows a variable number of arguments. The resulting string might not be normalized in any Unicode or W3C normalization.

NOTE:
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.

3.5.2.4 Examples

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

3.5.3 xf:starts-with

3.5.3.1 Signature

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

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

3.5.3.2 Parameters

$operand1 — static type is string
$operand2 — static type is string
$collation — static type is anyURI

3.5.3.3 Semantics

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 no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

3.5.3.4 Examples

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

3.5.4 xf:ends-with

3.5.4.1 Signature

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

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

3.5.4.2 Parameters

$operand1 — static type is string
$operand2 — static type is string
$collation — static type is anyURI

3.5.4.3 Semantics

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 no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

3.5.4.4 Examples

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

3.5.5 xf:codepoint-contains

3.5.5.1 Signature

xf:codepoint-contains(string $operand1, string $operand2) => boolean

3.5.5.2 Parameters

$operand1 — static type is string
$operand2 — static type is string

3.5.5.3 Semantics

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 $operand2, considered on a character-by-character basis using the Unicode value of each character for comparison .

3.5.5.4 Examples

xf:codepoint-contains("now is the time", "is t") returns true.

3.5.6 xf:contains

3.5.6.1 Signature

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

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

3.5.6.2 Parameters

$operand1 — static type is string
$operand2 — static type is string
$collation — static type is anyURI

3.5.6.3 Semantics

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 no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

3.5.7 xf:substring

3.5.7.1 Signature

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

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

3.5.7.2 Parameters

$sourceString — static type is string
$startingLoc — static type is decimal. The effective value is computed as cast as unsignedInt(floor($startingLoc)).
$length — static type is decimal. The effective value is computed as cast as unsignedInt(floor($length)).

3.5.7.3 Semantics

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.

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

The value of $length can be greater than the number of characters in the value of $sourceString following the beginning position, in which case the substring identifies characters to the end of $sourceString.

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

3.5.7.4 Examples

xf:substring("motor car", 6) returns " car".
xf:substring("metadata", 4, 3) returns "ada".

3.5.8 xf:string-length

3.5.8.1 Signature

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

3.5.8.2 Parameters

$srcval — static type is string

3.5.8.3 Semantics

Returns an integer equal to the length in characters of the value of $srcval.

3.5.8.4 Examples

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

3.5.9 xf:codepoint-substring-before

3.5.9.1 Signature

xf:codepoint-substring-before(string $operand1, string $operand2) => string

3.5.9.2 Parameters

$operand1 — static type is string
$operand2 — static type is string

3.5.9.3 Semantics

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 comparing each character in turn according to its Unicode value.

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 empty string.

3.5.10 xf:substring-before

3.5.10.1 Signature

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

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

3.5.10.2 Parameters

$operand1 — static type is string
$operand2 — static type is string
$collation — static type is anyURI

3.5.10.3 Semantics

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 $operand1 does not contain a string that is equal to the value of $operand2, then the function returns the empty string.

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

3.5.10.4 Examples

xf:substring-before("abcdabcd","d") returns "abc".
xf:substring-before("abcd","") returns "abcd".

3.5.11 xf:codepoint-substring-after

3.5.11.1 Signature

xf:codepoint-substring-after(string $operand1, string $operand2) => string

3.5.11.2 Parameters

$operand1 — static type is string
$operand2 — static type is string

3.5.11.3 Semantics

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 comparing each character in turn according to its Unicode value.

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.

3.5.12 xf:substring-after

3.5.12.1 Signature

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

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

3.5.12.2 Parameters

$operand1 — static type is string
$operand2 — static type is string
$collation — static type is anyURI

3.5.12.3 Semantics

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 $operand1 does not contain a string that is equal to the value of $operand2, then the function returns the zero-length string.

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

3.5.12.4 Examples

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

3.5.13 xf:normalize-space

3.5.13.1 Signature

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

3.5.13.2 Parameters

$srcval — static type is string

3.5.13.3 Semantics

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.

3.5.13.4 Examples

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

3.5.14 xf:normalize-unicode

3.5.14.1 Signature

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

3.5.14.2 Parameters

$srcval — static type is string
$normalizationForm — static type is string. The effective value is the value returned by upper-case($normalizationForm).

3.5.14.3 Semantics

Returns the value of $srcval normalized according to the normalization criteria for a normalization form identified by the value of $normalizationForm:

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 "W3C", then the value returned by the function is the value of $srcval in W3C Normal Form.

3.5.15 xf:upper-case

3.5.15.1 Signature

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

3.5.15.2 Parameters

$srcval — static type is string

3.5.15.3 Semantics

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

3.5.15.4 Examples

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

3.5.16 xf:lower-case

3.5.16.1 Signature

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

3.5.16.2 Parameters

$srcval — static type is string

3.5.16.3 Semantics

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

3.5.16.4 Examples

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

3.5.17 xf:translate

3.5.17.1 Signature

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

3.5.17.2 Parameters

$srcval — static type is string
$mapString — static type is string
$transString — static type is string

3.5.17.3 Semantics

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.

3.5.17.4 Examples

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

3.5.18 xf:string-pad-beginning

3.5.18.1 Signature

xf:string-pad-beginning(string $srcval, decimal $padCount, string $padChar) => string

3.5.18.2 Parameters

$srcval — static type is string
$padCount — static type is decimal. The effective value is computed as cast as unsignedInt(floor($padCount)).
$padChar — static type is string.

3.5.18.3 Semantics

Returns the value of $srcval in which zero or more copies of the value of $padChar have been inserted preceding the first character of the value of $srcval. The number of copies of the value of $padChar that are inserted is equal to the value of $padCount.

If the value of string-length(padChar) is greater than 1, then the function returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

3.5.18.4 Examples

xf:string-pad-beginning("XMLQuery", 2, "*") returns "**XMLQuery".
xf:string-pad-beginning("XMLQuery", 2, "**") returns error.

3.5.19 xf:string-pad-end

3.5.19.1 Signature

xf:string-pad-end(string $srcval, decimal $padCount, string $padChar) => string

3.5.19.2 Parameters

$srcval — static type is string
$padCount — static type is decimal. The effective value is computed as cast as unsignedInt(floor(length)).
$padChar — static type is string.

3.5.19.3 Semantics

Returns the value of $srcval in which zero or more copies of the value of $padChar have been appended following the last character of the value of $srcval. The number of copies of the value of $padChar that are appended is equal to the value of $padCount.

If the value of string-length(padChar) is greater than 1, then the function returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

3.5.19.4 Examples

xf:string-pad-end("XMLQuery", 2, "*") returns "XMLQuery**".

3.5.20 xf:match

3.5.20.1 Signature

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

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

3.5.20.2 Parameters

$srcval — static type is string
$regexp — static type is string
$collation — static type is anyURI

3.5.20.3 Semantics

Returns a list of integers that identify the offsets of locations within the value of $srcval that are matched by the regular expression that is the value of $regexp. Note that this list might often be implicitly converted to a boolean and that it is probably more common to determine whether a string matches than to ask where those matches occur.

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, like in all functions, performed in the context of a collation.

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 74: Is a "match-exact()" function needed?]

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

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

3.5.20.4 Examples

match("abcabc", "[ab]") returns {1, 2, 4, 5}.
match("abcabc", "[xyz]") returns {} (the empty sequence or list).

3.5.21 xf:replace

3.5.21.1 Signature

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

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

3.5.21.2 Parameters

$srcval — static type is string
$regexp — static type is string
$repval — static type is string
$collation — static type is anyURI

3.5.21.3 Semantics

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.

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

3.5.21.4 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".

4 Constructors, Functions, and Operators on Booleans

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

4.1 Boolean Constructors

The following constructors are defined on the boolean type.

Constructor	Meaning	Source
`xf:true`	boolean	XPath 1.0
`xf:false`	boolean	XPath 1.0
`xf:boolean-from-string`	boolean

4.1.1 xf:true

4.1.1.1 Signature

xf:true() => boolean

4.1.1.2 Parameters

This function has no parameters.

4.1.1.3 Semantics

Returns the boolean value true.

4.1.1.4 Examples

xf:true() returns true.

4.1.2 xf:false

4.1.2.1 Signature

xf:false() => boolean

4.1.2.2 Parameters

This function has no parameters.

4.1.2.3 Semantics

Returns the boolean value false.

4.1.2.4 Examples

xf:false() returns false.

4.1.3 xf:boolean-from-string

4.1.3.1 Signature

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

4.1.3.2 Parameters

$srcval — static type is string. The effective value is the value returned by upper-case($srcval).

4.1.3.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

4.1.3.4 Examples

xf:boolean-from-string(True) returns true.
xf:boolean-from-string(fAlSe) returns false.

4.2 Operators on Boolean Values

The following operators are defined on these boolean types:

Operator	Meaning	Source
`and`	Logical conjunction	XPath 1.0
`or`	Logical disjunction	XPath 1.0
`=`	Equality comparison	XPath 1.0
`!=`	Inequality comparison	XPath 1.0

[Issue 57: Some boolean operators are incompletely or incorrectly specified]

4.2.1 Semantics

The arguments and return types of all boolean operators are boolean types. For and, if one of the arguments is the empty sequence, the result is the empty sequence except if the other argument is false in which case the result is false. For or, if one of the arguments is the empty sequence, the result is the empty sequence except if the other argument is true in which case the result is true. The empty seqeunce does not compare equal to any value including itself.

4.3 Functions on Boolean Values

The following functions are defined on boolean types:

Function	Meaning	Source
xf:not	Inverts the boolean value of the argument.	XPath 1.0

4.3.1 xf:not

4.3.1.1 Signature

xf:not(boolean $srcval) => boolean

4.3.1.2 Parameters

$srcval — static type is boolean

4.3.1.3 Semantics

Returns true if the value of $srcval is false and false if the value of $srcval is true. If the argument is the empty sequence the result is the empty sequence.

4.3.1.4 Examples

xf:not(xf:true()) returns false.

5 Constructors, Functions, and Operators on Dates and Times

This section discusses operators on the [XML Schema Part 2: Datatypes] date and time types.

[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]

5.1 Duration and Datetime Types

The operators described in this section are defined on the following duration and datetime types.

duration
dateTime
date
time
gYearMonth
gYear
gMonthDay
gMonth
gDay

5.2 Duration and Datetime Constructors

The following constructors are defined on duration and datetime datatypes.

Constructor	Meaning
`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.
`xf:currentDateTime()`	Returns the current dateTime.

5.2.1 xf:duration

5.2.1.1 Signature

xf:duration(string $srcval) => duration

5.2.1.2 Parameters

$srcval — static type is string

5.2.1.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

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

5.2.2 xf:dateTime

5.2.2.1 Signature

xf:dateTime(string $srcval) => dateTime

5.2.2.2 Parameters

$srcval — static type is string

5.2.2.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

5.2.2.4 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 Eastern Standard Time, which is 5 hours behind Coordinated Universal Time (UTC).

5.2.3 xf:date

5.2.3.1 Signature

xf:date(string $srcval) => date

5.2.3.2 Parameters

$srcval — static type is string

5.2.3.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

5.2.3.4 Examples

xf:date("2001-5-31") returns a date value corresponding to the 31st of May, 2001.
xf:date("2001-4-31") returns an error.

5.2.4 xf:time

5.2.4.1 Signature

xf:time(string $srcval) => time

5.2.4.2 Parameters

$srcval — static type is string

5.2.4.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

5.2.4.4 Examples

xf:time("11:33:24") returns a time value corresponding to 33 minutes and 24 seconds past 11 AM 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 11 PM for Eastern Standard Time, which is 5 hours behind Coordinated Universal Time (UTC).

5.2.5 xf:gYearMonth

5.2.5.1 Signature

xf:gYearMonth(string $srcval) => gYearMonth

5.2.5.2 Parameters

$srcval — static type is string

5.2.5.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

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

5.2.6 xf:gYear

5.2.6.1 Signature

xf:gYear(string $srcval) => gYear

5.2.6.2 Parameters

$srcval — static type is string

5.2.6.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

5.2.6.4 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).

5.2.7 xf:gMonthDay

5.2.7.1 Signature

xf:gMonthDay(string $srcval) => gMonthDay

5.2.7.2 Parameters

$srcval — static type is string

5.2.7.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

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

5.2.8 xf:gMonth

5.2.8.1 Signature

xf:gMonth(string $srcval) => gMonth

5.2.8.2 Parameters

$srcval — static type is string

5.2.8.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

5.2.8.4 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).

5.2.9 xf:gDay

5.2.9.1 Signature

xf:gDay(string $srcval) => gDay

5.2.9.2 Parameters

$srcval — static type is string

5.2.9.3 Semantics

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

5.2.9.4 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).

5.2.10 xf:currentDateTime

5.2.10.1 Signature

xf:currentDateTime() => dateTime

5.2.10.2 Parameters

This function takes no parameters.

5.2.10.3 Semantics

Returns the dateTime that is current at some time during the evaluation of the XQuery or XPath expression in which the currentDateTime() constructor is executed. All invocations of currentDateTime() 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 when the currentDateTime() constructor's value represents is implementation-defined.

5.2.10.4 Examples

xf:currentDateTime() returns a dateTime corresponding to the current date and time.

5.3 Comparisons of Duration and Datetime Values

The following operators are defined on date and time values:

Operator	Meaning
`=`	Equality comparison
`<`	Less-than comparison
`>`	Greater-than comparison
`<=`	Less-than-or-equal-to comparison
`>=`	Greater-than-or-equal-to comparison
`!=`	Inequality comparison

These operators take two arguments of the same type. For equality and inequality, these operators return a boolean result. As discussed in [XML Schema Part 2: Datatypes], the order relation on the duration and the date and time datatypes is not a total order but, rather, a partial order. For this reason, the operators <, >, <=, and >= can return one of three values: true, false, or "indeterminate", represented by the symbol " <> ".

When comparing durations, there is no indeterminacy if either both arguments contain only years and months or both arguments contains only days, hours, minutes and seconds.

When comparing dateTime values, indeterminacy arises only in the cases when one of the arguments has a timezone and the other does not. If both arguments have timezones or if both arguments do not have timezones, an indeterminate value is never returned.

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

[Issue 38: How are indeterminate values in date/time values represented?]

[Issue 88: Should the input types to these functions be restricted so indeterminate values do not arise?]

[Issue 121: Representation of indeterminate comparison]

[Issue 123: Comparison of durations and datetimes: functions or operators?]

5.4 Component Extraction Functions on Datetime 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.

Function	Meaning
`xf:get-Century-from-dateTime`	Returns the century component of the years value of the argument.
`xf:get-Century-from-date`	Returns the century component of the years value of the argument.
`xf:get-Century-from-gYear`	Returns the century component of the years value of the argument.
`xf:get-Century-from-gYearMonth`	Returns the century component of the years value of the argument.
`xf:get-gYear-from-dateTime`	Returns the years value of the argument.
`xf:get-gYear-from-date`	Returns the years value of the argument.
`xf:get-gYear-from-gYearMonth`	Returns the years value of the argument.
`xf:get-gMonth-from-dateTime`	Returns the months value of the argument.
`xf:get-gMonth-from-date`	Returns the months value of the argument.
`xf:get-gMonth-from-gYearMonth`	Returns the months value of the argument.
`xf:get-gMonth-from-gMonthDay`	Returns the months value of the argument.
`xf:get-gDay-from-dateTime`	Returns the days value of the argument.
`xf:get-gDay-from-date`	Returns the days value of the argument.
`xf:get-gDay-from-gMonthDay`	Returns the days value of the argument.
`xf:get-hour-from-dateTime`	Returns the hours value of the argument.
`xf:get-hour-from-time`	Returns the hours value of the argument.
`xf:get-minutes-from-dateTime`	Returns the minutes value of the argument.
`xf:get-minutes-from-time`	Returns the minutes value of the argument.
`xf:get-seconds-from-dateTime`	Returns the seconds value of the argument.
`xf:get-seconds-from-time`	Returns the seconds value of the argument.
`xf:get-timezone-from-dateTime`	Returns the timezone part of the argument.
`xf:get-timezone-from-date`	Returns the timezone part of the argument.
`xf:get-timezone-from-time`	Returns the timezone part of the argument.
`xf:get-timezone-from-gYearMonth`	Returns the timezone part of the argument.
`xf:get-timezone-from-gYear`	Returns the timezone part of the argument.
`xf:get-timezone-from-gMonthDay`	Returns the timezone part of the argument.
`xf:get-timezone-from-gMonth`	Returns the timezone part of the argument.
`xf:get-timezone-from-gDay`	Returns the timezone part of the argument.

5.4.1 xf:get-Century-from-dateTime

5.4.1.1 Signature

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

5.4.1.2 Parameters

$srcval — static type is dateTime

5.4.1.3 Semantics

Returns an integer representing the century component of the year identified in the value of $srcval.

5.4.1.4 Examples

xf:get-Century-from-dateTime(xf:dateTime("1999-05-31T13:20:00-05:00")) returns 19 .

5.4.2 xf:get-Century-from-date

5.4.2.1 Signature

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

5.4.2.2 Parameters

$srcval — static type is date

5.4.2.3 Semantics

Returns an integer representing the century component of the year identified in the value of $srcval.

5.4.2.4 Examples

xf:get-Century-from-date(xf:date("1999-05-31")) returns 19 .

5.4.3 xf:get-Century-from-gYear

5.4.3.1 Signature

xf:get-Century-from-gYear(gYear $srcval) => integer

5.4.3.2 Parameters

$srcval — static type is gYear

5.4.3.3 Semantics

Returns an integer representing the century component of the year identified in the value of $srcval.

5.4.3.4 Examples

xf:get-Century-from-gYear(xf:gYear("2001")) returns 20 .

5.4.4 xf:get-Century-from-gYearMonth

5.4.4.1 Signature

xf:get-Century-from-gYearMonth(gYearMonth $srcval) => integer

5.4.4.2 Parameters

$srcval — static type is gYearMonth

5.4.4.3 Semantics

Returns an integer representing the century component of the year identified in the value of $srcval.

5.4.4.4 Examples

xf:get-Century-from-gYearMonth(xf:gYearMonth("2001-12")) returns 20 .

5.4.5 xf:get-gYear-from-dateTime

5.4.5.1 Signature

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

5.4.5.2 Parameters

$srcval — static type is dateTime

5.4.5.3 Semantics

Returns an integer representing the year identified in the value of $srcval.

5.4.5.4 Examples

xf:get-gYear-from-dateTime(xf:dateTime("1999-05-31T13:20:00-05:00")) returns 1999 .

5.4.6 xf:get-gYear-from-date

5.4.6.1 Signature

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

5.4.6.2 Parameters

$srcval — static type is date

5.4.6.3 Semantics

Returns a integer representing the year identified in the value of $srcval.

5.4.6.4 Examples

xf:get-gYear-from-date(xf:date("1999-05-31")) returns 1999 .

5.4.7 xf:get-gYear-from-gYearMonth

5.4.7.1 Signature

xf:get-Year-from-gYearMonth(gYearMonth $srcval) => integer

5.4.7.2 Parameters

$srcval — static type is gYearMonth

5.4.7.3 Semantics

Returns a integer representing the year identified in the value of $srcval.

5.4.7.4 Examples

xf:get-gYear-from-gYearMonth(xf:gYearMonth("1999-05")) returns 1999 .

5.4.8 xf:get-gMonth-from-dateTime

5.4.8.1 Signature

xf:get-gMonth-from-dateTime(dateTime $srcval) => positiveInteger (range 1 to 12)

5.4.8.2 Parameters

$srcval — static type is dateTime

5.4.8.3 Semantics

Returns a positive integer representing the month identified in the value of $srcval.

5.4.8.4 Examples

xf:get-gMonth-from-dateTime(xf:dateTime("1999-05-31T13:20:00-05:00")) returns 5 .

5.4.9 xf:get-gMonth-from-date

5.4.9.1 Signature

xf:get-gMonth-from-date(date $srcval) => positiveInteger (range 1 to 12)

5.4.9.2 Parameters

$srcval — static type is date

5.4.9.3 Semantics

Returns a positive integer representing the month identified in the value of $srcval.

5.4.9.4 Examples

xf:get-gMonth-from-date(xf:dateTime("1999-05-31")) returns 5 .

5.4.10 xf:get-gMonth-from-gYearMonth

5.4.10.1 Signature

xf:get-gMonth-from-gYearMonth(gYearMonth $srcval) => positiveInteger (range 1 to 12)

5.4.10.2 Parameters

$srcval — static type is gYearMonth

5.4.10.3 Semantics

Returns a positive integer representing the month identified in the value of $srcval.

5.4.10.4 Examples

xf:get-gMonth-from-gYearMonth(xf:gYearMonth("1999-05")) returns 5 .

5.4.11 xf:get-gMonth-from-gMonthDay

5.4.11.1 Signature

xf:get-gMonth-from-gMonthDay(gMonthDay $srcval) => positiveInteger (range 1 to 12)

5.4.11.2 Parameters

$srcval — static type is gMonthDay

5.4.11.3 Semantics

Returns a positive integer representing the month identified in the value of $srcval.

5.4.11.4 Examples

xf:get-gMonth-from-gMonthDay(xf:gMonthDay("05-31")) returns 5 .

5.4.12 xf:get-gDay-from-dateTime

5.4.12.1 Signature

xf:get-gDay-from-dateTime(dateTime $srcval) => positiveInteger (range 1 to 31)

5.4.12.2 Parameters

$srcval — static type is dateTime

5.4.12.3 Semantics

Returns a positive integer value representing the day identified in the value of $srcval.

5.4.12.4 Examples

xf:get-gDay-from-dateTime(xf:dateTime("1999-05-31T13:20:00-05:00")) returns 31 .

5.4.13 xf:get-gDay-from-date

5.4.13.1 Signature

xf:get-gDay-from-date(date $srcval) => positiveInteger (range 1 to 31)

5.4.13.2 Parameters

$srcval — static type is date

5.4.13.3 Semantics

Returns a positive integer value representing the day identified in the value of $srcval.

5.4.13.4 Examples

xf:get-gDay-from-date(xf:date("1999-05-31")) returns 31 .

5.4.14 xf:get-gDay-from-gMonthDay

5.4.14.1 Signature

xf:get-gDay-from-gMonthDay(gMonthDay $srcval) => positiveInteger (range 1 to 31)

5.4.14.2 Parameters

$srcval — static type is gMonthDay

5.4.14.3 Semantics

Returns a positive integer value representing the day identified in the value of $srcval.

5.4.14.4 Examples

xf:get-gDay-from-gMonthDay(xf:gMonthDay("05-31")) returns 31 .

5.4.15 xf:get-hour-from-dateTime

5.4.15.1 Signature

xf:get-hour-from-dateTime(dateTime $srcval) => integer (range 0 to 23)

5.4.15.2 Parameters

$srcval — static type is dateTime

5.4.15.3 Semantics

Returns an integer representing the hour identified in the value of $srcval. The hour value ranges from 0 to 23, inclusive.

5.4.15.4 Examples

xf:get-hour-from-dateTime(xf:dateTime("1999-05-31T13:20:00-05:00")) returns 13 .

5.4.16 xf:get-hour-from-time

5.4.16.1 Signature

xf:get-hour-from-time(time $srcval) => integer (range 0 to 23)

5.4.16.2 Parameters

$srcval — static type is time

5.4.16.3 Semantics

Returns an integer representing the hour identified in the value of $srcval. The hour value ranges from 0 to 23, inclusive.

5.4.16.4 Examples

xf:get-hour-from-time(xf:dateTime("11:23:00")) returns 11 .

5.4.17 xf:get-minutes-from-dateTime

5.4.17.1 Signature

xf:get-minutes-from-dateTime(dateTime $srcval) => integer (range 0 to 59)

5.4.17.2 Parameters

$srcval — static type is dateTime

5.4.17.3 Semantics

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

5.4.17.4 Examples

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

5.4.18 xf:get-minutes-from-time

5.4.18.1 Signature

xf:get-minutes-from-time(time $srcval) => integer (range 0 to 59)

5.4.18.2 Parameters

$srcval — static type is time

5.4.18.3 Semantics

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

5.4.18.4 Examples

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

5.4.19 xf:get-seconds-from-dateTime

5.4.19.1 Signature

xf:get-seconds-from-dateTime(dateTime $srcval) => decimal (range 0 to 61.9...9)

5.4.19.2 Parameters

$srcval — static type is dateTime

5.4.19.3 Semantics

Returns a decimal value representing the seconds and fractional seconds identified in the value of $srcval. The value ranges from 0 to 61.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.

5.4.19.4 Examples

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

5.4.20 xf:get-seconds-from-time

5.4.20.1 Signature

xf:get-seconds-from-time(time $srcval) => decimal (range 0 to 60.9...9)

5.4.20.2 Parameters

$srcval — static type is time

5.4.20.3 Semantics

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.

5.4.20.4 Examples

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

5.4.21 xf:get-timezone-from-dateTime

5.4.21.1 Signature

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

5.4.21.2 Parameters

$srcval — static type is dateTime

5.4.21.3 Semantics

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.

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

5.4.21.4 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" .

5.4.22 xf:get-timezone-from-date

5.4.22.1 Signature

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

5.4.22.2 Parameters

$srcval — static type is date

5.4.22.3 Semantics

5.4.22.4 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" .

5.4.23 xf:get-timezone-from-time

5.4.23.1 Signature

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

5.4.23.2 Parameters

$srcval — static type is time

5.4.23.3 Semantics

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

5.4.24 xf:get-timezone-from-gYear

5.4.24.1 Signature

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

5.4.24.2 Parameters

$srcval — static type is gYear

5.4.24.3 Semantics

5.4.24.4 Examples

xf:get-timezone-from-gYear(xf:gYear("1999-05:00")) returns "-05:00" .
xf:get-timezone-from-gYear(xf:gYear("2000Z")) returns "00:00" .

5.4.25 xf:get-timezone-from-gYearMonth

5.4.25.1 Signature

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

5.4.25.2 Parameters

$srcval — static type is gYearMonth

5.4.25.3 Semantics

5.4.25.4 Examples

xf:get-timezone-from-gYearMonth(xf:gYearMonth("1999-05-05:00")) returns "-05:00" .
xf:get-timezone-from-gYearMonth(xf:gYearMonth("2000-06")) returns the empty sequence.

5.4.26 xf:get-timezone-from-gMonth

5.4.26.1 Signature

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

5.4.26.2 Parameters

$srcval — static type is dateTime
$srcval — static type is gMonth

5.4.26.3 Semantics

5.4.26.4 Examples

xf:get-timezone-from-gMonth(xf:gMonth("05-05:00")) returns "-05:00" .
xf:get-timezone-from-gMonth(xf:gMonth("06Z")) returns "00:00" .

5.4.27 xf:get-timezone-from-gMonthDay

5.4.27.1 Signature

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

5.4.27.2 Parameters

$srcval — static type is gMonthDay

5.4.27.3 Semantics

5.4.27.4 Examples

xf:get-timezone-from-gMonthDay(xf:gMonthDay("05-31-05:00")) returns "-05:00" .
xf:get-timezone-from-gMonthDay(xf:gMonthDay("06-12")) returns the empty sequence.

5.4.28 xf:get-timezone-from-gDay

5.4.28.1 Signature

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

5.4.28.2 Parameters

$srcval — static type is gDay

5.4.28.3 Semantics

5.4.28.4 Examples

xf:get-timezone-from-gDay(xf:gDay("05-05:00")) returns "-05:00" .
xf:get-timezone-from-gDay(xf:gDay("06Z")) returns "00:00" .

5.5 Component Extraction Functions on Duration Values

The extraction functions specified below extract one component from a duration.

Function	Meaning
`xf:get-years(duration)`	Returns the years component of the argument.
`xf:get-months(duration)`	Returns the months component of the argument.
`xf:get-days(duration)`	Returns the days component of the argument.
`xf:get-hours(duration)`	Returns the hours component of the argument.
`xf:get-minutes(duration)`	Returns the minutes component of the argument.
`xf:get-seconds(duration)`	Returns the seconds component of the argument.

5.5.1 xf:get-years

5.5.1.1 Signature

xf:get-years(duration $srcval) => integer

5.5.1.2 Parameters

$srcval — static type is duration

5.5.1.3 Semantics

Returns an integer representing the years component of $srcval.

5.5.1.4 Examples

xf:get-years(xf:duration("P1Y2MT2H")) returns 1.

5.5.2 xf:get-months

5.5.2.1 Signature

xf:get-months(duration $srcval) => integer

5.5.2.2 Parameters

$srcval — static type is duration

5.5.2.3 Semantics

Returns an integer representing the monhts component of $srcval.

5.5.2.4 Examples

xf:get-months(xf:duration("P1Y2MT2H")) returns 2.

5.5.3 xf:get-days

5.5.3.1 Signature

xf:get-days(duration $srcval) => integer

5.5.3.2 Parameters

$srcval — static type is duration

5.5.3.3 Semantics

Returns an integer representing the days component of $srcval.

5.5.3.4 Examples

xf:get-days(xf:duration("P1Y2MT2H")) returns 0.

5.5.4 xf:get-hours

5.5.4.1 Signature

xf:get-hours(duration $srcval) => integer

5.5.4.2 Parameters

$srcval — static type is duration

5.5.4.3 Semantics

Returns an integer representing the hours component of $srcval.

5.5.4.4 Examples

xf:get-hours(xf:duration("P1Y2MT2H")) returns 2.

5.5.5 xf:get-minutes

5.5.5.1 Signature

xf:get-minutes(duration $srcval) => integer

5.5.5.2 Parameters

$srcval — static type is duration

5.5.5.3 Semantics

Returns an integer representing the minutes component of $srcval.

5.5.5.4 Examples

xf:get-minutes(xf:duration("P1Y2MT2H")) returns 0.

5.5.6 xf:get-seconds

5.5.6.1 Signature

xf:get-seconds(duration $srcval) => decimal

5.5.6.2 Parameters

$srcval — static type is duration

5.5.6.3 Semantics

Returns a decimal representing the seconds component of $srcval. The precision of the returned value depends on the relevant facets of $srcval.

5.5.6.4 Examples

xf:get-minutes(xf:duration("P1Y2MT2H")) returns 0.0.

5.6 Arithmetic Functions on Dates

Function	Meaning
`xf:add-days`	Adds the number of days indicated by the second argument to the first argument.
`xf:add-months`	Adds the number of months indicated by the second argument to the first argument.
`xf:add-years`	Adds the number of years indicated by the second argument to the first argument.
`xf:add-gMonth`	Adds the number of months indicated by the value of the second argument to the value of the first argument.
`xf:add-gYear`	Adds the number of years indicated by the value of the second argument to the value of the first argument.

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

5.6.1 xf:add-days

5.6.1.1 Signature

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

5.6.1.2 Parameters

$dateParam — static type is date
$incrDays — static type is decimal

5.6.1.3 Semantics

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 normlized into a correct Gregorian calendar date.

5.6.1.4 Examples

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

5.6.2 xf:add-months

5.6.2.1 Signature

xf:add-months(date $dateParam, decimal $incrMonths) => date

5.6.2.2 Parameters

$dateParam — static type is date
$incrMonths — static type is decimal

5.6.2.3 Semantics

Adds the number of months indicated by the value of $incrMonths to the value of $dateParam. The value of $incrMonths may be negative. If the value of $dateParam has a timezone, it remains unchanged. The returned value is always normlized into a correct Gregorian calendar date.

[Issue 124: add-months() and add-years() incompletely specified]

5.6.2.4 Examples

xf:add-months(xf:date("2001-03-31"), 1) returns a date value corresponding to April 30, 2001.

5.6.3 xf:add-years

5.6.3.1 Signature

xf:add-years(date $dateParam, decimal $incrYears) => date

5.6.3.2 Parameters

$dateParam — static type is date
$incrYears — static type is decimal

5.6.3.3 Semantics

Adds the number of years indicated by the value of $incrYears to the value of $dateParam. The value of $incrYears may be negative. If the value of $dateParam has a timezone, it remains unchanged. The returned value is always normlized into a correct Gregorian calendar date.

[Issue 124: add-months() and add-years() incompletely specified]

5.6.3.4 Examples

xf:add-years(xf:date("2001-02-28"), 2) returns a date value corresponding to February 28, 2003.

5.6.4 xf:add-gMonth

5.6.4.1 Signature

xf:add-gMonth(gMonth $monthParam, decimal $incrMonths) => gMonth

5.6.4.2 Parameters

$monthParam — static type is gMonth
$incrMonths — static type is decimal

5.6.4.3 Semantics

Adds the number of months indicated by the value of $incrMonths to the value of $monthParam. The value of $incrMonths may be negative. If the value of $monthParam has a timezone, it remains unchanged. The returned value is always normlized into a correct Gregorian calendar date.

5.6.4.4 Examples

xf:add-gMonth(xf:gMonth("05"), 3) returns a gMonth value corresponding to the month of August.

5.6.5 xf:add-gYear

5.6.5.1 Signature

xf:add-gYear(gYear $yearParam, decimal $incrYears) => gYear

5.6.5.2 Parameters

$yearParam — static type is gYear
$incrYears — static type is decimal

5.6.5.3 Semantics

Adds the number of years indicated by the value of $incrYears to the value of $yearParam. The value of $incrYears may be negative. If the value of $yearParam has a timezone, it remains unchanged. The returned value is always normlized into a correct Gregorian calendar date.

5.6.5.4 Examples

xf:add-gYear(xf:gYear("2001"), 2) returns a gYear value corresponding to the year 2003.

5.7 Functions 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 first three functions below take two of the properties as arguments and return the third. The last three functions test whhether a given dateTime falls within a time period.

Function	Meaning
`xf:get-duration`	Returns the difference between two dateTimes as a duration. The two arguments must both have a timezone or both have no timezone.
`xf:get-end`	Returns the end of a time period by adding the dateTime that starts the period and the duration of the period.
`xf:get-start`	Returns the beginning of a time period by substracting the duration of the period from the the dateTime that ends the period.
`xf:temporal-dateTimes-contains`	Indicates whether the time period defined by the first two arguments contain the time specified in the third argument. All three dateTime arguments must have a timezone or all three must not have a timezone.
`xf:temporal-dateTimeDuration-contains`	Indicates whether the time period defined by the first two arguments contain the time specified in the third argument. The two dateTime arguments must have a timezone or both must not have a timezone.
`xf:temporal-durationDateTimes-contains`	Indicates whether the time period defined by the first two arguments contain the time specified in the third argument. The two dateTime arguments must have a timezone or both must not have a timezone.

[Issue 25: Is a normalize function needed for duration types?]

[Issue 96: These functions on time-period values are better written using operators as in SQL.]

[Issue 111: get-end and get-start should be more unique]

5.7.1 xf:get-duration

5.7.1.1 Signature

xf:get-duration(dateTime $parameter1, dateTime $parameter2) => duration

5.7.1.2 Parameters

$parameter1 — static type is dateTime
$parameter2 — static type is dateTime

5.7.1.3 Semantics

Returns the duration that corresponds to the difference between the value of $parameter1 and the value of $parameter2. If the value of $parameter1 follows in time the value of $parameter2, then the returned value is a negative duration. The two arguments must both have a timezone or both have no timezone.

5.7.1.4 Examples

xf:get-duration(xf:dateTime("2000-10-30T11:12:00"), xf:dateTime("1999-11-28T09:00:00")) returns a duration value corresponding to 11 months, 3 days, 2 hours and 12 minutes.

5.7.2 xf:get-end

5.7.2.1 Signature

xf:get-end(dateTime $parameter1, duration $parameter2) => dateTime

5.7.2.2 Parameters

$parameter1 — static type is dateTime
$parameter2 — static type is duration

5.7.2.3 Semantics

Returns the end of a time period by adding the dateTime that starts the period ($parameter1) and the duration of the period ($parameter2). If the duration is negative, then the "end" of the period actually precedes the "start" of the period.

5.7.2.4 Examples

xf:get-end(xf:dateTime("2000-10-30T11:12:00"), xf:duration("P5DT13H10M")) returns a dateTime value corresponding to the literal 2000-11-05T00:22:00.

5.7.3 xf:get-start

5.7.3.1 Signature

xf:get-start(dateTime $parameter1, duration $parameter2) => dateTime

5.7.3.2 Parameters

$parameter1 — static type is dateTime
$parameter2 — static type is duration

5.7.3.3 Semantics

Returns the start of a time period by subtracting the duration of the period ($parameter2)from the dateTime that ends the period ($parameter1). If the duration is negative, then the "start" of the period actually follows the "end" of the period.

5.7.3.4 Examples

xf:get-start(xf:dateTime("2000-10-30T11:12:00"), xf:duration("P5DT13H10M")) returns a dateTime value corresponding to the literal 2000-10-24T22:02:00.

5.7.4 xf:temporal-dateTimes-contains

5.7.4.1 Signature

xf:temporal-dateTimes-contains(dateTime $parameter1, dateTime $parameter2, dateTime $parameter3) => boolean

5.7.4.2 Parameters

$parameter1 — static type is dateTime
$parameter2 — static type is dateTime
$parameter3 — static type is dateTime

5.7.4.3 Semantics

If the value of $parameter3 is either (1)equal to the value of $parameter1, (2)equal to the value of $parameter2, (3)greater than the value of $parameter1 and less than the value of $parameter2, or (4)less than the value of $parameter1 and greater than the value of $parameter2, then the function returns true; otherwise, the function returns false. All three dateTime arguments must have a timezone or all three must not have a timezone.

5.7.4.4 Examples

xf:temporal-dateTimes-contains(xf:dateTime("2000-10-30T11:12:00"), xf:dateTime("1999-11-28T09:00:00"), xf:dateTime("2000-01-01T12:00:00")) returns true.
xf:temporal-dateTimes-contains(xf:dateTime("2000-10-30T11:12:00Z"), xf:dateTime("2000-01-01T09:00:00"), xf:dateTime("2000-01-01T12:00:00")) returns error.

5.7.5 xf:temporal-dateTimeDuration-contains

5.7.5.1 Signature

xf:temporal-dateTimeDuration-contains(dateTime $parameter1, duration $parameter2, dateTime $parameter3) => boolean

5.7.5.2 Parameters

$parameter1 — static type is dateTime
$parameter2 — static type is duration
$parameter3 — static type is dateTime

5.7.5.3 Semantics

If the value of $parameter3 is either (1)equal to the value of $parameter1, (2)equal to the value of the dateTime value resulting from adding the value of $parameter2 to the value of $parameter1, (3)greater than the value of $parameter1 and less than the value of the dateTime value resulting from adding the value of $parameter2 to the value of $parameter1, or (4)less than the value of $parameter1 and greater than the value of the dateTime value resulting from adding the value of $parameter2 to the value of $parameter1, then the function returns true; otherwise, the function returns false. The two dateTime arguments must both have a timezone or must both not have a timezone.

5.7.5.4 Examples

xf:temporal-dateTimeDuration-contains(xf:dateTime("2000-10-30T11:12:00-05:00"), xf:duration("P1Y"), xf:dateTime("2001-01-01T12:00:00Z")) returns true.

5.7.6 xf:temporal-durationDateTime-contains

5.7.6.1 Signature

xf:temporal-durationDateTime-contains(duration $parameter1, dateTime $parameter2, dateTime $parameter3) => boolean

5.7.6.2 Parameters

$parameter1 — static type is duration
$parameter2 — static type is dateTime
$parameter3 — static type is dateTime

5.7.6.3 Semantics

If the value of $parameter3 is either (1)equal to the value of $parameter2, (2)equal to the value of the dateTime value resulting from subtracting the value of $parameter1 from the value of $parameter2, (3)greater than the value of $parameter2 and less than the value of the dateTime value resulting from subtracting the value of $parameter1 from the value of $parameter2, or (4)less than the value of $parameter1 and greater than the value of the dateTime value resulting from subtracting the value of $parameter1 from the value of $parameter2, then the function returns true; otherwise, the function returns false. The two dataTime arguments must both have a timezone both or must both not have a timezone.

5.7.6.4 Examples

xf:temporal-dateTimeDuration-contains(xf:duration("P1Y"), xf:dateTime("2000-10-30T11:12:00-05:00"), xf:dateTime("2001-01-01T12:00:00Z")) returns false.

6 Constructors, Functions, and Operators on QNames

6.1 Constructors for QNames

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

Function	Meaning	Source
`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-prefix`	Returns a QName with the namespace URI that maps to the prefix given in the first argument and the local name in the second argument. 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.

[Issue 115: QName-from-string function]

6.1.1 xf:QName-from-uri

6.1.1.1 Signature

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

6.1.1.2 Parameters

$paramURI — static type is string
$paramLocal — static type is string

6.1.1.3 Semantics

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

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

6.1.1.4 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".

6.1.2 xf:QName-from-prefix

6.1.2.1 Signature

xf:QName-from-prefix(string $paramPrefix, string $paramLocal) => QName

6.1.2.2 Parameters

$paramPrefix — static type is string
$paramLocal — static type is string

6.1.2.3 Semantics

Returns a QName with the namespace URI that maps to the prefix given in $paramPrefix and the local name in $paramLocal. The prefix to URI mapping uses the namespaces in scope.

[Issue 122: What is a "namespace in scope"?]

6.1.2.4 Examples

xf:QName-from-uri("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 an error.

6.1.3 xf:QName

6.1.3.1 Signature

xf:QName(string $paramLocal) => QName

6.1.3.2 Parameters

$paramLocal — static type is string

6.1.3.3 Semantics

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

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

6.1.3.4 Examples

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

6.2 Functions on QNames

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

Function	Meaning	Source
`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.

6.2.1 xf:get-local-name

6.2.1.1 Signature

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

6.2.1.2 Parameters

$srcval — static type is QName

6.2.1.3 Semantics

Returns a string representing the local part of $srcval.

6.2.1.4 Examples

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

6.2.2 xf:get-namespace-uri

6.2.2.1 Signature

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

6.2.2.2 Parameters

$srcval — static type is QName

6.2.2.3 Semantics

Returns the namespace URI for $srcval. If the QName is in no namespace, then the empty sequence is returned.

[Issue 116: What should get-namespace-uri() return?]

6.2.2.4 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 Constructors, Functions, and Operators for anyURI

7.1 Constructor for anyURI

This section discusses a constructor for anyURI as defined in [XML Schema Part 2: Datatypes].

Function	Meaning	Source
`xf:anyURI`	Returns an `anyURI` with a URI reference as given in the argument.

7.1.1 xf:anyURI

7.1.1.1 Signature

xf:anyURI(string $srcval) => anyURI

7.1.1.2 Parameters

$srcval — static type is string

7.1.1.3 Semantics

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

[Issue 10: Do we need functions to decompose and resolve URIs?]

8 Functions and Operators on base64Binary and hexBinary

8.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 comparison operator returns a boolean value.

The comparison is bit by bit. So, for base64Binary, "A" < "B" < "a". If the two operands are of different lengths and the second operand starts with the first operand, then the first operand < second operand.

Operator	Meaning
`=`	Equality comparison
`<`	Less-than comparison
`>`	Greater-than comparison
`<=`	Less-than-or-equal-to comparison
`>=`	Greater-than-or-equal-to comparison
`!=`	Inequality comparison

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

[Issue 125: Do comparisons on base64Binary and hexBinary make sense?]

9 Constructors, Functions, and Operators on NOTATION

9.1 NOTATION Constructor

This section discusses a constructor for NOTATION as defined in [XML Schema Part 2: Datatypes].

Function	Meaning	Source
`xf:NOTATION`	Returns a NOTATION with the value given in the argument.

9.1.1 xf:NOTATION

9.1.1.1 Signature

xf:NOTATION(string $srcval) => NOTATION

9.1.1.2 Parameters

$srcval — static type is string

9.1.1.3 Semantics

Returns a NOTATION with the value given in $srcval.

10 Functions and Operators on Nodes

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

[Issue 86: In which document do the node accessors functions and the kind tests go?]

10.1 Operators on Nodes

The following operators are defined on sequences.

Operator	Meaning
`==`	Tests if two nodes have the same identity.
`!==`	Tests if two nodes do not have the same identity.
`=>`	The left-operand is an element or attribute with a value of type IDREF or IDREFS. The right-operand is a node test. The operator dereferences value and returns the referenced nodes that satisfy the node test. See also 11.7 Functions that Generate Sequences

10.2 Functions on Nodes

Function	Meaning	Source
`xf:local-name`	Returns the local name of the context node or the specified node as a QName.	XPath 1.0 modified
`xf:namespace-uri`	Returns the namespace URI for the name of the specified node.	XPath 1.0
`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:node-equal`	Returns true if the two arguments have the same identity.	Data Model
`xf:value-equal`	Returns true if the two arguments have the same value.	Data Model
`xf:node-before`	Indicates whether one node appears before another node in document order.	Data Model
`xf:node-after`	Indicates whether one node appears before another node in document order.	Data Model
`xf:copy`	Returns a deep copy of a node.	Data Model
`xf:shallow`	Returns a shallow copy of a node.	Data Model
`xf:boolean`	Casts a node to a boolean. See 12.5 Miscellaneous casting functions.	XPath 1.0

[Issue 59: Recommend = operator for value-equal and "is" for node-equal.]

[Issue 95: Need if-absent and if-empty functions to handle missing and unknown data.]

[Issue 97: We need a deep-equals function for nodes.]

[Issue 103: Need operators for BEFORE and AFTER.]

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.

10.2.1 xf:local-name

10.2.1.1 Signature

xf:local-name() => string

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

10.2.1.2 Parameters

$srcval — static type is node

10.2.1.3 Semantics

Returns a string whose value corresponds to the local name of the specified node (or, if no node is provided, the context node) as a string.

10.2.2 xf:namespace-uri

10.2.2.1 Signature

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

10.2.2.2 Parameters

$srcval — static type is node

10.2.2.3 Semantics

Returns the namespace URI for the name of the node identified by $srcval.

Returns the empty sequence if the name of the node has no namespace or if the node has no name.

10.2.3 xf:number

10.2.3.1 Signature

xf:number() => double

xf:number(node $srcval) => double

10.2.3.2 Parameters

$srcval — static type is node

10.2.3.3 Semantics

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 an error value as specified in [XQuery 1.0 and XPath 2.0 Data Model].

10.2.3.4 Examples

xf:number($item1/quantity) returns 5.
xf:number($item2) returns error.

10.2.4 xf:node-equal

10.2.4.1 Signature

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

10.2.4.2 Parameters

$parameter1 — static type is node
$parameter2 — static type is node

10.2.4.3 Semantics

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.

10.2.4.4 Examples

xf:node-equal($item1, $item1) returns true.
xf:node-equal($item1, $item2) returns false.

10.2.5 xf:value-equal

10.2.5.1 Signature

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

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

10.2.5.2 Parameters

$parameter1 — static type is node
$parameter2 — static type is node
$collation — static type is anyURI

10.2.5.3 Semantics

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 the value-equality as follows. We assume value 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:value-equal(a1,a2), if and only if xf:value-equal(name(a1), name(a2)) and xf:value-equal(value(a1), value(a2)).
Given elements e1 and e2, xf:value-equal(e1, e2), if and only if xf:value-equal(name(e1), name(e2)) and xf:value-equal(attributes(e1), attributes(e2)) and xf:value-equal(children(e1), children(e2)).
Given two sequences (u₁, ..., u_j) and (v₁, ..., v_k), xf:value-equal((u₁, ..., u_j), (v₁, ..., v_k)) holds if and only if j = k and xf:value-equal(u_i, v_i) holds for all 1 <= i <= n.

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

10.2.5.4 Examples

xf:value-equal($item1, $item2) returns false.
xf:value-equal($item1, $item1) returns true .

10.2.6 xf:node-before

10.2.6.1 Signature

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

10.2.6.2 Parameters

$parameter1 — static type is node
$parameter2 — static type is node

10.2.6.3 Semantics

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, the function returns false. The rules determining "document order" can be found in [XQuery 1.0 and XPath 2.0 Data Model].

If the nodes identified by the values of the two arguments are from different documents, the result is implementation-dependent.

[Issue 117: Data model defines document order for multiple documents]

10.2.6.4 Examples

xf:node-before($item1, $item2) returns true.
xf:node-before($item1, $item1) returns false.

10.2.7 xf:node-after

10.2.7.1 Signature

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

10.2.7.2 Parameters

$parameter1 — static type is node
$parameter2 — static type is node

10.2.7.3 Semantics

If the node identified by the value of $parameter1 occurs in document order after the node identified by the value of $parameter2, this function returns true; otherwise, the function returns false. The rules determining "document order" can be found in [XQuery 1.0 and XPath 2.0 Data Model].

If the nodes identified by the values of the two arguments are from different documents, the result is implementation-dependent.

[Issue 117: Data model defines document order for multiple documents]

10.2.7.4 Examples

xf:node-after($item1, $item2) returns false.
xf:node-after($item1, $item1) returns false.

10.2.8 xf:copy

10.2.8.1 Signature

xf:copy(node $srcval) => node

10.2.8.2 Parameters

$srcval — static type is node

10.2.8.3 Semantics

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.

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

10.2.8.4 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>

10.2.9 xf:shallow

10.2.9.1 Signature

xf:shallow(node $srcval) => node

10.2.9.2 Parameters

$srcval — static type is node

10.2.9.3 Semantics

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.

10.2.9.4 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'/>

10.2.10 xf:boolean

10.2.10.1 Signature

xf:boolean(node $srcval) => boolean

10.2.10.2 Parameters

$srcval — static type is node

10.2.10.3 Semantics

Casts a node to a boolean. See 12.5 Miscellaneous casting functions.

[Issue 126: Which boolean conversions make sense?]

11 Constructors, Functions, and Operators on Sequences

[XML Schema Part 2: Datatypes] allows users to define datatypes that consist of space separated lists of values. The values must be of a specified datatype, called the itemType, which must be an atomic datatype but may be a union type. In addition, it defines three legacy XML datatypes as lists: NMTOKENS, IDREFS and ENTITIES.

[XQuery 1.0 and XPath 2.0 Data Model] defines node sets, now renamed sequences, consisting of lists of nodes. There is a significant semantic difference between lists and sequences as defined in these two specifications: a list with a single value is still a list; a sequence with a single value is equivalent to the single value by itself.

For the purpose of this section, lists and sequences as defined above are referred to as sequences.

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

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

11.1 Sequences

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

Node sequences
User-defined list types
NMTOKENS
IDREFS
ENTITIES

[Issue 61: Some cited types of sequences do not exist]

[Issue 62: Is NMTOKENS not required in this section?]

11.2 Constructors on Sequences

The following constructors are defined for sequences.

Operator	Meaning
`TO`	Returns the sequence containing every integer between the values of the operands. (Implemented as an infix operator.)

11.2.1 TO

11.2.1.1 Usage

$firstval TO $lastval => integer*

11.2.1.2 Operands

$startval — static type is decimal. The effective value is computed as cast as unsignedInt(floor($startval)).
$endval — static type is decimal. The effective value is computed as cast as unsignedInt(floor($endval)).

11.2.1.3 Semantics

Converts both its operands to integers and returns the sequence containing every integer whose value is greater than or equal to the effective value of firstval and less than or equal to the effective value of lastval, in monotonically increasing order.

11.3 Operators on Sequences

The following operators are defined on sequences.

Operator	Meaning
`,`	Infix operator. Concatenates two sequences.

11.4 Functions on Sequences

The following functions are defined on sequences.

Function	Meaning	Source
`xf:position`	Returns an unsignedInt indicating the position of the given item in the given sequence. See also [Issue 100: Reconcile the definitions of these functions with XPath. ]	XPath 1.0
`xf:last`	Returns an unsignedInt indicating the last position in the given sequence. [Issue 100: Reconcile the definitions of these functions with XPath. ]	XPath 1.0
`xf: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:identity-distinct`	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:value-distinct`	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:sort`	Sorts into ascending order the elements in the provided sequence according to the values of the elements.	XPath 2.0 Req 4.4 (Should)
`xf:reverse-sort`	Sorts into descending order the elements in the provided sequence according to the values of the elements.	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:sublist-before`	Returns the part of the first sequence that occurs before the first occurrence of the second sequence.	XPath 2.0 Req 4.4 (Should)
`xf:sublist-after`	Returns the part of the first sequence that occurs after the last occurrence of the second sequence.	XPath 2.0 Req 4.4 (Should)
`xf:sublist`	Returns a sequence located at a specified place in the value of a given sequence.	XPath 2.0 Req 4.4 (Should)
`xf:sequence-pad-beginning`	Returns the sequence padded in front by copies of the third argument.	XPath 2.0 Req 2.4.2, 4.4 (Should)
`xf:sequence-pad-end`	Returns the sequence padded at the end by copies of the third argument.	XPath 2.0 Req 2.4.2, 4.4 (Should)
`xf:truncate-beginning`	Truncates the beginning of the sequence, resulting in a sequence whose number of elements equals the second argument.	XPath 2.0 Req 2.4, 4.4 (Should)
`xf:truncate-end`	Truncates the beginning of the sequence, resulting in a sequence whose number of elements equals the second argument.	XPath 2.0 Req 2.4, 4.4 (Should)
`xf:resize-beginning`	Truncates the beginning of a sequence, or pads a sequence at the beginning with the third argument, so that the sequence has a number of elements equal to the second argument.	XPath 2.0 Req 2.4, 4.4 (Should)
`xf:resize-end`	Truncates the end of a sequence, or pads a sequence at the end with the third argument, so that the sequence has a number of elements equal to the second argument.	XPath 2.0 Req 2.4, 4.4 (Should)
`xf:unordered`	This function provides a hint to the query optimizer that the order of the argument sequence is not important and can be ignored.	XQuery

[Issue 63: Do we need variations of index-of for values and identity?]

[Issue 65: Are certain sequence functions both adequate and required?]

[Issue 66: A function to reorder a sequence into document order is needed]

[Issue 98: Need head() and tail() functions on sequences.]

[Issue 99: Remove sort and reverse-sort-functions. Covered by SORTBY operator in the language.]

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.

11.4.1 xf:position

11.4.1.1 Signature

xf:position(anyType* $seqParam, anyType $itemParam) => unsignedInt

11.4.1.2 Parameters

$seqParam — static type is anyType*
$itemParam — static type is anyType.

11.4.1.3 Semantics

Returns an unsignedInt indicating the position of the $itemParam in the $seqParam.

If the $itemParam is not contained in $seqParam, then the function returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

[Issue 130: Several functions might become second-order functions]

11.4.1.4 Examples

xf:position(xf:item-at($seq, $item2) returns 2.

11.4.2 xf:last

11.4.2.1 Signature

xf:last(anyType* $seqParam) => unsignedInt

11.4.2.2 Parameters

$seqParam — static type is anyType*

11.4.2.3 Semantics

Returns an unsignedInt indicating the last position in the sequence i.e. the number of items in the sequence.

11.4.3 xf:item-at

11.4.3.1 Signature

xf:item-at(anyType* $seqParam, decimal $posParam) => anyType

11.4.3.2 Parameters

$seqParam — static type is anyType*
$posParam — static type is decimal. The effective value is floor($posParam).

11.4.3.3 Semantics

Returns the item in the sequence that is the value of $seqParam that is located at the index that is the value of $posParam.

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

11.4.3.4 Examples

xf:node-equal(xf:item-at($seq, 1), $item1) returns true.

11.4.4 xf:index-of

11.4.4.1 Signature

xf:index-of(anyType* $seqParam, anyType $srchParam) => unsignedInt*

xf:index-of(anyType* $seqParam, anyType $srchParam, anyURI $collation) => unsignedInt*

11.4.4.2 Parameters

$seqParam — static type is anyType*
$srchParam — static type is anyType
$collation — static type is anyURI

11.4.4.3 Semantics

If the value of $seqParam contains simple values (that is, not nodes), then the function returns a sequence of values 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 values 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 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. If the sequence contains both simple values and nodes, then the function returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

If the value of $seqParam is an empty sequence, then the returned value is an empty sequence.

The index is 1-based (not 0-based).

11.4.4.4 Examples

xf:index-of($seq, $item2) returns 2.

11.4.5 xf:empty

11.4.5.1 Signature

xf:empty(anyType* $srcval) => boolean

11.4.5.2 Parameters

$srcval — static type is anyType*

11.4.5.3 Semantics

If the the value of $srcval is an empty sequence, then the function returns true; otherwise, the function returns false.

11.4.5.4 Examples

xf:empty($seq) returns false.

11.4.6 xf:exists

11.4.6.1 Signature

xf:exists(anyType* $srcval) => boolean

11.4.6.2 Parameters

$srcval — static type is anyType*

11.4.6.3 Semantics

If the the value of $srcval is not an empty sequence, then the function returns true; otherwise, the function returns false.

11.4.6.4 Examples

xf:empty($seq) returns true.

11.4.7 xf:identity-distinct

11.4.7.1 Signature

xf:identity-distinct(anyType* $srcval) => anyType*

11.4.7.2 Parameters

$srcval — static type is anyType*

11.4.7.3 Semantics

Returns the sequence that results from removing from $srcval all but the first of a set of nodes that have the same identity as one other, based on node identity (that is, using node-equal()).

[Issue 128: doc-order() function needed?]

11.4.7.4 Examples

xf:identity-distinct($seq) returns $seq.

11.4.8 xf:value-distinct

11.4.8.1 Signature

xf:value-distinct(anyType* $srcval) => anyType*

xf:value-distinct(anyType* $srcval, anyURI $collation) => anyType*

11.4.8.2 Parameters

$srcval — static type is anyType*
$collation — static type is anyURI

11.4.8.3 Semantics

Returns the sequence that results from removing from $srcval all but the first of a set of nodes that are equal to one other, based on the nodes' values (that is, using value-equal()). If the sequence is a sequence of nodes, then the typed values of the nodes are used for the comparison. The specific node in a collection of nodes having equal values that is retained in implementation-dependent. Equality of string values are determined according to the collation that is used.

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 127: value-distinct() versus distinct()]

11.4.8.4 Examples

xf:value-distinct($seq) returns $seq.

11.4.9 xf:sort

11.4.9.1 Signature

xf:sort(anyType* $srcval, anyURI $collation) => anyType*

11.4.9.2 Parameters

$srcval — static type is anyType*
$collation — static type is anyURI

11.4.9.3 Semantics

Sorts into ascending order the sequence that is the value of $srcval using the typed values of the elements of the sequence.

The sequence must be a sequence of comparable objects.

If the sequence contains any two items that are not comparable with one another, then an error value is returned as defined in [XQuery 1.0 and XPath 2.0 Data Model].

If the value of $srcval is a sequence of string values, or if the value of $srcval is a sequence of nodes that are compared according to their string values, then the ordering is performed based on the collation that is used.

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 129: sort and reverse-sort or SORTBY]

11.4.10 xf:reverse-sort

11.4.10.1 Signature

xf:reverse-sort(anyType* $srcval, anyURI $collation) => anyType*

11.4.10.2 Parameters

$srcval — static type is anyType*
$collation — static type is anyURI

11.4.10.3 Semantics

Sorts into descending order the sequence that is the value of $srcval using the typed values of the elements of the sequence.

The sequence must be a sequence of comparable objects.

If the sequence contains any two items that are not comparable with one another, then an error value is returned as defined in [XQuery 1.0 and XPath 2.0 Data Model].

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 64: Should reverse-sort be replaced by generic reverse?]

[Issue 129: sort and reverse-sort or SORTBY]

11.4.11 xf:insert

11.4.11.1 Signature

xf:insert(anyType* $target, decimal $position, anyType* $inserts) => anyType*

11.4.11.2 Parameters

$target — static type is anyType*
$position — static type is decimal. The effective value is computed as floor($position).
$inserts — static type is anyType*

11.4.11.3 Semantics

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.

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.

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.

[Issue 131: Is the insert() function required?]

11.4.12 xf:sublist-before

11.4.12.1 Signature

xf:sublist-before(anyType* $parameter1, anyType* $parameter2) => anyType*

xf:sublist-before(anyType* $parameter1, anyType* $parameter2, anyURI $collation) => anyType*

11.4.12.2 Parameters

$parameter1 — static type is anyType*
$parameter2 — static type is anyType*
$collation — static type is anyURI

11.4.12.3 Semantics

If there is at least one contiguous sequence of elements in the value of $parameter1 that are, taken in order, equal to the elements of the value of $parameter2, then the function returns a sequence constructed of every element of the value of $parameter1, taken in order, that occur before the first such contiguous sequence of elements in the value of $parameter1. In sequences of simple values, elements are compared for equality by value. In sequences of nodes, they are compared by identity.

If the value of $operand1 does not contain such a contiguous sequence of elements, then the function returns the empty sequence.

If the values of $parameter1 and $parameter2 are sequences of string values, or if the values of $parameter1 and $parameter2 are a sequences of nodes that are compared according to their string values, then the ordering is performed based on the collation that is used.

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 130: Several functions might become second-order functions]

11.4.12.4 Examples

xf:sublist-before($seq, $item3) returns [$item1 $item2].

11.4.13 xf:sublist-after

11.4.13.1 Signature

xf:sublist-after(anyType* $parameter1, anyType* $parameter2) => anyType*

xf:sublist-after(anyType* $parameter1, anyType* $parameter2, anyURI $collation) => anyType*

11.4.13.2 Parameters

$parameter1 — static type is anyType*
$parameter2 — static type is anyType*
$collation — static type is anyURI

11.4.13.3 Semantics

If there is at least one contiguous sequence of elements in the value of $parameter1 that are, taken in order, equal to the elements of the value of $parameter2, then the function returns a sequence constructed of every element of the value of $parameter1, taken in order, that occur after the last such contiguous sequence of elements in the value of $parameter1. In sequences of simple values, elements are compared for equality by value. In sequences of nodes, they are compared by identity.

If the value of $operand1 does not contain such a contiguous sequence of elements, then the function returns the empty sequence.

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 130: Several functions might become second-order functions]

11.4.13.4 Examples

xf:sublist-after($seq, $item3) returns [$item4 $item5 ...]

11.4.14 xf:sublist

11.4.14.1 Signature

xf:sublist(anyType* $sourceSeq, decimal $startingLoc) => anyType*

xf:sublist(anyType* $sourceSeq, decimal $startingLoc, decimal $length) => anyType*

11.4.14.2 Parameters

$sourceSeq — static type is anyType*
$startingLoc — static type is decimal. The effective value is computed as floor($startingLoc).
$length — static type is decimal. The effective value is computed as floor($length).

11.4.14.3 Semantics

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 sublist identifies 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 sublist identifies items to the end of $length.

The first item of a sequence is located at position 1 (not position 0).

11.4.14.4 Examples

xf:sublist($seq, 4) returns [$item4 $item5 ...]
xf:sublist($seq, 4, 2) returns [$item4 $item5]

11.4.15 xf:sequence-pad-beginning

11.4.15.1 Signature

xf:sequence-pad-beginning(anyType* $srcval, decimal $padCount, anyType $padItem) => anyType*

11.4.15.2 Parameters

$srcval — static type is anyType*
$padCount — static type is decimal. The effective value is computed as cast as unsignedInt(floor($padCount)).
$padItem — static type is anyType

11.4.15.3 Semantics

Returns a new sequence constructed from the value of $srcval in which zero or more copies of the value of $padItem have been inserted preceding the first item in the value of $srcval. The number of copies of the value of $padItem that are inserted is equal to the value of $padCount.

If the value of $padItem has a type that is not the type of the items in the value of $srcval, then the function returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

[Issue 130: Several functions might become second-order functions]

11.4.15.4 Examples

xf:sequence-pad-beginning($seq, 1, $item1) returns [$item1, $item1, $item2, $item3, ...] .
xf:sequence-pad-beginning($seq, 2, 4) returns error.

11.4.16 xf:sequence-pad-end

11.4.16.1 Signature

xf:sequence-pad-end(anyType* $srcval, decimal $padCount, anyType $padItem) => anyType*

11.4.16.2 Parameters

$srcval — static type is anyType*
$padCount — static type is decimal. The effective value is computed as cast as unsignedInt(floor($padCount)).
$padItem — static type is anyType

11.4.16.3 Semantics

Returns a new sequence constructed from the value of $srcval in which zero or more copies of the value of $padItem have been inserted following the last item in the value of $srcval. The number of copies of the value of $padItem that are inserted is equal to the value of $padCount.

If the value of $padItem has a type that is not the type of the items in the value of $srcval, then the function returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

[Issue 130: Several functions might become second-order functions]

11.4.17 xf:truncate-beginning

11.4.17.1 Signature

xf:truncate-beginning(anyType* $srcval, decimal $length) => anyType*

11.4.17.2 Parameters

$srcval — static type is anyType*
$length — static type is decimal. The effective value is computed as cast as unsignedInt(floor($length)).

11.4.17.3 Semantics

Returns a sequence constructed from the sequence that is the value of $srcval, removing elements from the beginning of the sequence until the number of remaining elements is equal to the effective value of $length.

If the number of elements in the sequence that is the value of $srcval is less than or equal to the value of $length, then the returned sequence is the value of $srcval.

[Issue 130: Several functions might become second-order functions]

11.4.17.4 Examples

Assume $seq had five items. xf:truncate-beginning($seq, 3) returns [$item3, $item4, $item5].

11.4.18 xf:truncate-end

11.4.18.1 Signature

xf:truncate-end(anyType* $srcval, decimal $length) => anyType*

11.4.18.2 Parameters

$srcval — static type is anyType*
$length — static type is decimal. The effective value is computed as cast as unsignedInt(floor($length)).

11.4.18.3 Semantics

Returns a sequence constructed from the sequence that is the value of $srcval, removing elements from the end of the sequence until the number of remaining elements is equal to the effective value of $length.

If the number of elements in the sequence that is the value of $srcval is less than or equal to the value of $length, then the returned sequence is the value of $srcval.

[Issue 130: Several functions might become second-order functions]

11.4.18.4 Examples

Assume $seq had five items. xf:truncate-end($seq, 3) returns [$item1, $item2, $item3].

11.4.19 xf:resize-beginning

11.4.19.1 Signature

xf:resize-beginning(anyType* $srcval, decimal $finalLength, anyType $padItem) => anyType*

11.4.19.2 Parameters

$srcval — static type is anyType*
$finalLength — static type is decimal. The effective value is computed as cast as unsignedInt(floor($finalLength)).
$padItem — static type is anyType

11.4.19.3 Semantics

Returns a sequence constructed from the sequence that is the value of $srcval.

If the number of elements in the value of $srcval is greater than the value of $finalLength, then elements are removed from the beginning of the value of $srcval until the number of remaining elements is equal to the value of $finalLength.

If the number of elements in the value of $srcval is equal to the value of $finalLength, then the returned sequence is the value of $srcval.

If the number of elements in the value of $srcval is less than the value of $finalLength, then the returned sequence is modified by adding instances of the value of $padItem at the beginning of the returned sequence until the number of elements of the returned sequence is equal to the value of $finalLength.

[Issue 130: Several functions might become second-order functions]

NOTE:
This is a "convenience function" that effectively performs a pad-beginning or a truncate-beginning as required to fulfil the $finalLength criterion.

11.4.19.4 Examples

Assume $seq had five items. xf:resize-beginning($seq, 3, $item1) sets $seq to [$item3 $item4 $item5].
Assume $seq had five items. xf:resize-beginning($seq, 6, $item1) sets $seq to [$item1 $item1 $item2 $item3 $item4 $item5].

11.4.20 xf:resize-end

11.4.20.1 Signature

xf:resize-end(anyType* $srcval, decimal $finalLength, anyType $padItem) => anyType*

11.4.20.2 Parameters

$srcval — static type is anyType*
$finalLength — static type is decimal. The effective value is computed as cast as unsignedInt(floor($finalLength)).
$padItem — static type is anyType

11.4.20.3 Semantics

Returns a sequence constructed from the sequence that is the value of $srcval.

If the number of elements in the value of $srcval is greater than the value of $finalLength, then elements are removed from the end of the value of $srcval until the number of remaining elements is equal to the value of $finalLength.

If the number of elements in the value of $srcval is equal to the value of $finalLength, then the returned sequence is the value of $srcval.

If the number of elements in the value of $srcval is less than the value of $finalLength, then the returned sequence is modified by appending instances of the value of $padItem at the end of the returned sequence until the number of elements of the returned sequence is equal to the value of $finalLength.

[Issue 130: Several functions might become second-order functions]

NOTE:
This is a "convenience function" that effectively performs a pad-end or a truncate-end as required to fulfil the $finalLength criterion.

11.4.20.4 Examples

Assume $seq had five items. xf:resize-end($seq, 3, $item1) sets $seq to [$item1 $item2 $item3].
Assume $seq had five items. xf:resize-end($seq, 6, $item1) sets $seq to [$item1 $item2 $item3 $item4 $item5 $item1].

11.4.21 xf:unordered

11.4.21.1 Signature

xf:unordered(anyType* $srcval) => anyType*

11.4.21.2 Parameters

$srcval — static type is anyType*

11.4.21.3 Semantics

This function provides a hint to the query optimizer that the order of the argument sequence is not important and can be ignored.

11.5 Equals, Union, Intersection and Except

Function	Meaning	Source
`xf:sequence-value-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
`xf:union`	Returns the union of the two sequence arguments, eliminating duplicates.	XPath 2.0 Req 1.5 (Should)
`xf:union-all`	Returns the union of the two sequence arguments without eliminating duplicates.
`xf:intersect`	Returns the intersection of the two sequence arguments, eliminating duplicates. XPath uses "&" for this.	XPath 2.0 Req 1.5 (Should)
`xf:intersect-all`	Returns the intersection of the two sequence arguments without eliminating duplicates.
`xf:except`	Returns the difference of the two sequence arguments, eliminating duplicates.	XPath 2.0 Req 1.5 (Should)
`xf:except-all`	Returns the difference of the two sequence arguments without eliminating duplicates.

[Issue 91: Need value-based functions for Union, Intersect and Except.]

[Issue 102: Need operators for UNION, INTERSECT and EXCEPT.]

[Issue 132: union(), intersect(), and except(): only for simple values?]

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.

11.5.1 xf:sequence-value-equal

11.5.1.1 Signature

xf:sequence-value-equal(anyType* $parameter1, anyType* $parameter2) => boolean

xf:sequence-value-equal(anyType* $parameter1, anyType* $parameter2, anyURI $collation) => boolean

11.5.1.2 Parameters

$parameter1 — static type is anyType*
$parameter2 — static type is anyType*
$collation — static type is anyURI

11.5.1.3 Semantics

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 are value-equal), 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 no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

11.5.2 xf:sequence-node-equal

11.5.2.1 Signature

xf:sequence-node-equal(anyType* $parameter1, anyType* $parameter2) => boolean

11.5.2.2 Parameters

$parameter1 — static type is anyType*
$parameter2 — static type is anyType*

11.5.2.3 Semantics

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.

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

11.5.3 xf:union

11.5.3.1 Signature

xf:union(anyType* $parameter1, anyType* $parameter2) => anyType*

11.5.3.2 Parameters

$parameter1 — static type is anyType*
$parameter2 — static type is anyType*

11.5.3.3 Semantics

Constructs a sequence containing every element that occurs in the values of $parameter1 or of $parameter2, eliminating redundant duplicate elements. The specific element in a collection of redundant duplicate elements that is retained in implementation-dependent.

Elements are compared using xf:node-equal().

The returned sequence is a sequence of nodes (that is, not of the values of the nodes) in document order, as defined in [XQuery 1.0 and XPath 2.0 Data Model].

Note: XPath uses "|" for union().

11.5.3.4 Examples

Assume $seq1 = [$item1 $item2], $seq2 = [$item1 $item2] and $seq3 = [$item2 $item3].

xf:union($seq1, $seq1) returns a sequence consisting of $item1 and $item2.
xf:union($seq2, $seq3) returns a sequence consisting of $item1, $item2 and $item3.

11.5.4 xf:union-all

11.5.4.1 Signature

xf:union-all(anyType* $parameter1, anyType* $parameter2) => anyType*

11.5.4.2 Parameters

$parameter1 — static type is anyType*
$parameter2 — static type is anyType*

11.5.4.3 Semantics

Constructs a sequence containing every element that occurs in the values of $parameter1 or of $parameter2, retaining redundant duplicate elements (that is, duplicates are not eliminated).

Elements are compared using xf:node-equal().

The returned sequence is in document order, as defined in [XQuery 1.0 and XPath 2.0 Data Model].

[Issue 120: union-all, intersect-all, and except-all: implementation-defined order and retain duplicates]

11.5.4.4 Examples

Assume $seq1 = [$item1 $item2], $seq2 = [$item1 $item2] and $seq3 = [$item2 $item3].

xf:union-all($seq1, $seq1) returns a sequence consisting of $item1, $item2, $item1 and $item2.
xf:union-all($seq2, $seq3) returns a sequence consisting of $item1, $item2, $item2 and $item3.

11.5.5 xf:intersect

11.5.5.1 Signature

xf:intersect(anyType* $parameter1, anyType* $parameter2) => anyType*

11.5.5.2 Parameters

$parameter1 — static type is anyType*
$parameter2 — static type is anyType*

11.5.5.3 Semantics

Constructs a sequence containing every element that occurs in the values of both $parameter1 and $parameter2, eliminating redundant duplicate elements. The specific element in a collection of redundant duplicate elements that is retained in implementation-dependent.

Elements are compared using xf:node-equal().

The returned sequence is in document order, as defined in [XQuery 1.0 and XPath 2.0 Data Model].

11.5.5.4 Examples

Assume $seq1 = [$item1 $item2], $seq2 = [$item1 $item2] and $seq3 = [$item2 $item3].

xf:intersect($seq1, $seq1) returns the sequence [$item1 $item2].
xf:intersect($seq2, $seq3) returns a sequence consisting of the single member $item2.

11.5.6 xf:intersect-all

11.5.6.1 Signature

xf:intersect-all(anyType* $parameter1, anyType* $parameter2) => anyType*

11.5.6.2 Parameters

$parameter1 — static type is anyType*
$parameter2 — static type is anyType*

11.5.6.3 Semantics

Constructs a sequence containing every element that occurs in the values of both $parameter1 and $parameter2, retaining redundant duplicate elements (that is, duplicates are not eliminated).

The number of each redundant duplicate element that is included in the result is the minimum of the number of occurrences of the element in $parameter1 and the number of occurrences of the element in $parameter2.

Elements are compared using xf:node-equal().

The returned sequence is in document order, as defined in [XQuery 1.0 and XPath 2.0 Data Model].

[Issue 120: union-all, intersect-all, and except-all: implementation-defined order and retain duplicates]

11.5.6.4 Examples

Assume $seq1 = [$item1 $item2], $seq2 = [$item1 $item2 $item2].

xf:intersect-all($seq1, $seq2) returns a sequence consisting of $item1 and $item2.

11.5.7 xf:except

11.5.7.1 Signature

xf:except(anyType* $parameter1, anyType* $parameter2) => anyType*

11.5.7.2 Parameters

$parameter1 — static type is anyType*
$parameter2 — static type is anyType*

11.5.7.3 Semantics

Constructs a sequence containing every element that occurs in the values of $parameter1, but not in the value of $parameter2, eliminating redundant duplicate elements. The specific element in a collection of redundant duplicate elements that is retained in implementation-dependent.

Elements are compared using xf:node-equal().

The returned sequence is in document order, as defined in [XQuery 1.0 and XPath 2.0 Data Model].

11.5.7.4 Examples

Assume $seq1 = [$item1 $item2], $seq2 = [$item1 $item2] and $seq3 = [$item2 $item3].

xf:except($seq1, $seq2) returns the empty sequence.
xf:except($seq2, $seq3) returns a sequence consisting of the single member $item1.

11.5.8 xf:except-all

11.5.8.1 Signature

xf:except-all(anyType* $parameter1, anyType* $parameter2) => anyType*

11.5.8.2 Parameters

$parameter1 — static type is anyType*
$parameter2 — static type is anyType*

11.5.8.3 Semantics

Constructs a sequence containing every element that occurs in the values of $parameter1, but not in the value of $parameter2, retaining redundant duplicate elements (that is, duplicates are not eliminated).

The number of each redundant duplicate element that is included in the result is the difference between the number of occurrences of the element in $parameter1 and the number of occurrences of the element in $parameter2.

Elements are compared using xf:node-equal().

The returned sequence is in document order, as defined in [XQuery 1.0 and XPath 2.0 Data Model].

[Issue 120: union-all, intersect-all, and except-all: implementation-defined order and retain duplicates]

11.5.8.4 Examples

Assume $seq1 = [$item1 $item2 $item1], and $seq3 = [$item2 $item3]

xf:difference-all($seq1, $seq3) returns a sequence consisting of $item1 and $item1.

11.6 Aggregate Functions

Function	Meaning	Source
`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

11.6.1 xf:count

11.6.1.1 Signature

xf:count(anyType* $srcval) => unsignedInt

11.6.1.2 Parameters

$srcval — static type is anyType*

11.6.1.3 Semantics

Returns the number of items in the value of $srcval.

[Issue 67: Should duplicates be eliminated for count() and sum()?]

11.6.1.4 Examples

Assume $seq1 = [$item1 $item2] and $seq3 = [], the empty sequence.

xf:count($seq1) returns 2.
xf:count($seq3) returns 0.

11.6.2 xf:avg

11.6.2.1 Signature

xf:avg(anyType* $srcval) => double

11.6.2.2 Parameters

$srcval — static type is anyType*

11.6.2.3 Semantics

If every item in the value of $srcval is a number, then the function returns the average of the numbers (computed as sum($srcval) div count($srcval)).

Otherwise, the function returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

11.6.2.4 Examples

Assume $seq1 = [$item1 $item2] and $seq3 = [3 4 5].

xf:avg($seq3) returns 4.0.
xf:avg($seq1) returns an error.

11.6.3 xf:max

11.6.3.1 Signature

xf:max(anyType* $srcval) => anyType

xf:max(anyType* $srcval, anyURI $collation) => anyType

11.6.3.2 Parameters

$srcval — static type is anyType*
$collation — static type is anyURI

11.6.3.3 Semantics

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 no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

11.6.3.4 Examples

Assume $seq1 = [3 4 5].

xf:max($seq1) returns 5.

11.6.4 xf:min

11.6.4.1 Signature

xf:max(anyType* $srcval) => anyType

xf:min(anyType* $srcval, anyURI $collation) => anyType

11.6.4.2 Parameters

$srcval — static type is anyType*
$collation — static type is anyURI

11.6.4.3 Semantics

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 no collation is specified, then the default collation is used. The default collation is determined according to the rules in TO BE DETERMINED.

11.6.4.4 Examples

Assume $seq1 = [3 4 5].

xf:min($seq1) returns 3.

11.6.5 xf:sum

11.6.5.1 Signature

xf:sum(anyType* $srcval) => double

11.6.5.2 Parameters

$srcval — static type is anyType*

11.6.5.3 Semantics

If every item in the value of $srcval is a number, then the function returns the sum of those numbers.

Otherwise, the function returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].

[Issue 67: Should duplicates be eliminated for count() and sum()?]

11.6.5.4 Examples

Assume $seq1 = [$item1 $item2] and $seq3 = [3 4 5].

xf:sum($seq1) returns an error.
xf:sum($seq3) returns 12.0.

11.7 Functions that Generate Sequences

Function	Meaning	Source
`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`	Treats its string argument as a URI Reference and returns the root node of the referenced document.	XSLT 1.0

[Issue 43: Are function names ID/id and IDREF/idref confusing?]

[Issue 68: The id-nodes() and id-NMTOKENS() functions must specify result documents]

11.7.1 xf:id

11.7.1.1 Signature

xf:id(IDREF* $srcval) => node*

11.7.1.2 Parameters

$srcval — static type is IDREF*

11.7.1.3 Semantics

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 of was supplied.

11.7.2 xf:idref

11.7.2.1 Signature

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

11.7.2.2 Parameters

$srcval — static type is string*

11.7.2.3 Semantics

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.

11.7.3 xf:filter

11.7.3.1 Signature

xf:filter(node $srcval) => node*

11.7.3.2 Parameters

$srcval — static type is node

11.7.3.3 Semantics

The filter function returns a shallow copy of the nodes that are selected by expression that is the value of $srcval, preserving any relationships that exist among these nodes.

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

11.7.4 xf:document

11.7.4.1 Signature

xf:document(string $srcval) => node

11.7.4.2 Parameters

$srcval — static type is string

11.7.4.3 Semantics

Treats the string value of $srcval as a URI reference and returns the root node of the referenced document. Returns an error if the document cannot be accessed. [XSLT 1.0] allows many other kinds of arguments and returns a sequence of nodes.

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

[Issue 17: Is CAST a function/operator for this document?]

In this specification, casting is available for conversions between certain combinations of the primitive and derived types defined by [XML Schema Part 2: Datatypes]. The type conversions that are supported are indicated in the following tables. In these tables, there is a row for each primitive and derived type for which a conversion is defined with that type as the source of the conversion. In addition, there is a column for each primitive and derived type for which a conversion is defined with that 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 given in this section of this specification. (Temporarily, while this specification is under development, there may be table entries containing "?", indicating that it has not yet been determined whether or not a conversion is provided.)

In the following tables, the columns and rows are identified by short codes that identify simple (both primitive and derived) types as follows:

aURI = anyURI
b64 = base64Binary
bool = boolean
byt = byte
dat = date
Day = gDay
dbl = double
dec = decimal
dT = dateTime
dur = duration
ENS = ENTITIES
ENT = ENTITY
flt = float
hxB = hexBinary
ID = ID
IDR = IDREF
IDS = IDREFS
int = int
itg = integer
lan = language
lng = long
MD = gMonthDay
Mon = gMonth
Nam = Name
NC = NCNAME
nI = negativeInteger
NMS = NMTOKENS
NMT = NMTOKEN
nNI = nonNegativeInteger
NOT = NOTATION
nPI = nonPositiveInteger
nStr = normalizedString
pI = positiveInteger
QN = Qname
sh = short
str = string
tim = time
tok = token
uB = unsignedByte
uI = unsignedInt
uL = unsignedLong
uS = unsignedShort
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.

[Issue 83: Are the cast tables appropriately structured and ordered?]

12.1 Casting to string and its derived types

The following table covers conversions to string and its derived types.

S\T	str	nStr	tok	lan	Nam	NC	ID	IDR	IDS	ENT	ENS	NMT	NMS
str	Y	Y	Y	M	M	M	N	N	N	N	N	M	M
nStr	Y	Y	Y	M	M	M	N	N	N	N	N	M	M
tok	Y	Y	Y	M	M	M	N	N	N	N	N	M	M
lan	Y	Y	Y	Y	Y	Y	N	N	N	N	N	Y	Y
Nam	Y	Y	Y	Y	Y	Y	N	N	N	N	N	Y	Y
NC	Y	Y	Y	M	M	Y	N	N	N	N	N	Y	Y
ID	Y	Y	Y	M	Y	Y	N	N	N	N	N	Y	Y
IDR	Y	Y	Y	M	Y	Y	N	N	N	N	N	Y	Y
IDS	Y	Y	Y	M	M	M	N	N	N	N	N	M	Y
ENT	Y	Y	Y	M	Y	Y	N	N	N	N	N	Y	Y
ENS	Y	Y	Y	M	M	M	N	N	N	N	N	M	Y
NMT	Y	Y	Y	M	Y	Y	N	N	N	N	N	Y	Y
NMS	Y	Y	Y	M	M	M	N	N	N	N	N	M	Y
flt	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
dbl	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
dec	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
itg	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
nPI	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
nI	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
lng	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
int	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
sh	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
byt	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
nNI	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
uL	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
uI	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
uS	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
uB	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
pI	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
dur	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
dT	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
tim	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
dat	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
YM	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
Yr	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
MD	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
Day	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
Mon	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
bool	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
b64	Y	Y	Y	M	M	M	M	M	M	M	M	M	M
hxB	Y	Y	Y	M	M	M	M	M	M	M	M	M	M
aURI	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
QN	Y	Y	Y	N	N	N	N	N	N	N	N	N	N
NOT	Y	Y	Y	M	M	M	M	M	M	M	M	M	M

As specified in the preceding table, casting is supported from almost every data type (the exception is base64Binary) into the primitive type string and into its derived types normalizedString and token. Conversion to other types derived from string depends on factors considered below. (If the entry in the preceding table is "N", then no cast is supported; consequently, the following specifications do not discuss those conversions.)

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, normalizedString, token, language, Name, NCName, ID, IDREF, IDREFS, ENTITY, ENTITIES, NMTOKEN, or NMTOKENS, then TV is SV.
- If ST is float, double, decimal, integer, nonPositiveInteger, negativeInteger, long, int, short, byte, nonNegativeInteger, unsignedLong, unsignedInt, unsignedShort, unsignedByte, or positiveInteger, 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.
When a value of any simple type is cast to normalizedString, the normalizedString value TV is derived from the source type ST and the source value SV> as follows:
- SV is converted to an intermediate value IV of type string.
- IV is converted to normalizedString by removing from it all carriage return codes (#xD), all line feed codes (#xA), and all tab characters (#x9).
When a value of any simple type is cast to token, the token value TV is derived from the source type ST and the source value SV> as follows:
- SV is converted to an intermediate value IV of type string.
- IV is converted to token by removing from it all all line feed codes (#xA) and all tab characters (#x9), then removing all spaces (#x20) that precede all non-space characters (leading spaces) and all spaces that follow all non-space characters (trailing spaces), and then replacing all sequences of two or more spaces (#x20) with a single space.
  
  [Issue 84: When casting to token, are linefeed/tab converted to space?]
When a value of any simple type is cast to language, the language value TV is derived from the source type ST and the source value SV as follows:
- If ST is language, then TV is SV and the conversion is complete.
- SV is converted to an intermediate value IV of type NMTOKEN.
- If IV is not a valid value for language as defined in [XML Schema Part 2: Datatypes], then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- Otherwise, TV is IV.
When a value of any simple type is cast to Name, the Name value TV is derived from the source type ST and the source value SV as follows:
- If ST is name, then TV is SV and the conversion is complete.
- SV is converted to an intermediate value IV of type string.
- If IV is not a valid value for Name as defined in [XML Schema Part 2: Datatypes], then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- Otherwise, TV is IV.
When a value of any simple type is cast to NCName, the NCName value TV is derived from the source type ST and the source value SV as follows:
- If ST is NCName, ID, or IDREF, then TV is SV and the conversion is complete.
- SV is converted to an intermediate value IV of type string.
- If IV is not a valid value for NCName as defined in [Namespaces in XML], then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- Otherwise, TV is IV.
When a value of any simple type is cast to NMTOKEN, the NMTOKEN value TV is derived from the source type ST and the source value SV as follows:
- If ST is NMTOKEN, then TV is SV and the conversion is complete.
- SV is converted to an intermediate value IV of type string.
- If IV is not a valid value for NMTOKEN as defined in [XML Schema Part 2: Datatypes], then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- Otherwise, TV is IV.
When a value of any simple type is cast to NMTOKENS, the NMTOKENS value TV is derived from the source type ST and the source value SV as follows:
- If ST is NMTOKEN or NMTOKENS, then TV is SV and the conversion is complete.
- SV is converted to an intermediate value IV of type string.
- If IV is not a valid value for NMTOKENS as defined in [XML Schema Part 2: Datatypes], then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- Otherwise, TV is IV.

12.2 Casting to numeric types

The following table covers conversions to float and to double, and to decimal and its derived types.

S\T	flt	dbl	dec	itg	nPI	nI	lng	int	sh	byt	nNI	uL	uI	uS	uB	pI
str	M	M	M	M	M	M	M	M	M	M	M	M	M	M	M	M
nStr	M	M	M	M	M	M	M	M	M	M	M	M	M	M	M	M
tok	M	M	M	M	M	M	M	M	M	M	M	M	M	M	M	M
lan	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
Nam	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
NC	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
ID	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
IDR	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
IDS	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
ENT	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
ENS	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
NMT	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
NMS	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
flt	Y	Y	M	M	M	M	M	M	M	M	M	M	M	M	M	M
dbl	M	Y	M	M	M	M	M	M	M	M	M	M	M	M	M	M
dec	Y	Y	Y	M	M	M	M	M	M	M	M	M	M	M	M	M
itg	Y	Y	Y	Y	M	M	M	M	M	M	M	M	M	M	M	M
nPI	Y	Y	Y	Y	Y	M	M	M	M	M	M	M	M	M	M	N
nI	Y	Y	Y	Y	Y	Y	M	M	M	M	N	N	N	N	N	N
lng	Y	Y	Y	Y	M	M	Y	M	M	M	M	M	M	M	M	M
int	Y	Y	Y	Y	M	M	Y	Y	M	M	M	M	M	M	M	M
sh	Y	Y	Y	Y	M	M	Y	Y	Y	M	M	M	M	M	M	M
byt	Y	Y	Y	Y	M	M	Y	Y	Y	Y	M	M	M	M	M	M
nNI	Y	Y	Y	Y	M	N	M	M	M	M	Y	M	M	M	M	M
uL	Y	Y	Y	Y	M	N	M	M	M	M	Y	Y	M	M	M	M
uI	Y	Y	Y	Y	M	N	Y	M	M	M	Y	Y	Y	M	M	M
uS	Y	Y	Y	Y	M	N	Y	Y	M	M	Y	Y	Y	Y	M	M
uB	Y	Y	Y	Y	M	N	Y	Y	Y	M	Y	Y	Y	Y	Y	M
pI	Y	Y	Y	Y	N	N	M	M	M	M	M	M	M	M	M	Y
dur	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
dT	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
tim	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
dat	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
YM	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
Yr	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
MD	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
Day	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
Mon	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
bool	Y	Y	Y	Y	M	N	Y	Y	Y	Y	Y	Y	Y	Y	Y	M
b64	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
hxB	M	M	M	M	M	M	M	M	M	M	M	M	M	M	M	M
aURI	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
QN	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N
NOT	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N	N

As specified in the preceding table, conversion from various simple types to the various numeric types (that is, float, double, decimal, and types derived from decimal) depends on factors considered below. (If the entry in the preceding table is "N", then no cast is supported; consequently, the following specifications do not discuss those conversions.)

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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- 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, integer, nonPositiveInteger, negativeInteger, long, int, short, byte, nonNegativeInteger, unsignedLong, unsignedInt, unsignedShort, unsignedByte, or positiveInteger, then TV is xf:float(cast as string( SV )) and the conversion is complete.
- SV is converted to an intermediate value IV of type token.
- If the value of xf:upper( 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 an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
  
  [Issue 50: Should double("ZZZ") or cast as float("ZZZ") return an error or NaN? ]
- Otherwise, let NL be a NumericLiteral comprising the same sequence of characters as IV. TV is xf:float( NL ).
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, decimal, integer, nonPositiveInteger, negativeInteger, long, int, short, byte, nonNegativeInteger, unsignedLong, unsignedInt, unsignedShort, unsignedByte, or positiveInteger, then TV is xf:double(cast as string( SV )) and the conversion is complete.
- SV is converted to an intermediate value IV of type token.
- If the value of xf:upper( 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 an 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 ).
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, then TV is SV and the conversion is complete.
- If ST is integer, nonPositiveInteger, negativeInteger, long, int, short, byte, nonNegativeInteger, unsignedLong, unsignedInt, unsignedShort, unsignedByte, or positiveInteger, 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.
- 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 an 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 ))).
When a value of any simple type is cast to integer, the integer value TV is derived from the source type ST and the source value SV as follows:
- If ST is integer, nonPositiveInteger, negativeInteger, long, int, short, byte, nonNegativeInteger, unsignedLong, unsignedInt, unsignedShort, unsignedByte, or positiveInteger, then TV is integer(cast as string( SV )) and the conversion is complete.
- If ST is decimal, float or double, then TV is integer(cast as string(xf:round( SV ))) 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 an 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 integer(cast as string(xf:round( NL ))).
When a value of any simple type is cast to nonPositiveInteger, the nonPositiveInteger value TV is derived from the source type ST and the source value SV as follows:
- SV is converted to an intermediate value IV of type integer.
- If IV is greater than zero, then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- Otherwise, TV is IV.
When a value of any simple type is cast to negativeInteger, the negativeInteger value TV is derived from the source type ST and the source value SV as follows:
- SV is converted to an intermediate value IV of type integer.
- If IV is greater than or equal to zero, then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- Otherwise, TV is IV.
When a value of any simple type is cast to long, int, short, or byte, the long, int, short, or byte, respectively, value TV is derived from the source type ST and the source value SV as follows:
- SV is converted to an intermediate value IV of type integer.
- If IV is greater than the value of maxInclusive for long, int, short, or byte, respectively, or less than the value of minInclusive for long, int, short, or byte, respectively, as specified in [XML Schema Part 2: Datatypes], then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- Otherwise, TV is IV.
When a value of any simple type is cast to nonNegativeInteger, the nonNegativeInteger value TV is derived from the source type ST and the source value SV as follows:
- SV is converted to an intermediate value IV of type integer.
- If IV is less than zero, then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- Otherwise, TV is IV.
When a value of any simple type is cast to unsignedLong, unsignedInt, unsignedShort, or unsignedByte, the unsignedLong, unsignedInt, unsignedShort, or unsignedByte, respectively, value TV is derived from the source type ST and the source value SV as follows:
- SV is converted to an intermediate value IV of type integer.
- If IV is greater than the value of maxInclusive for unsignedLong, unsignedInt, unsignedShort, or unsignedByte, respectively, as specified in [XML Schema Part 2: Datatypes], then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- Otherwise, TV is IV.
When a value of any simple type is cast to positiveInteger, the positiveInteger value TV is derived from the source type ST and the source value SV as follows:
- SV is converted to an intermediate value IV of type integer.
- If IV is less than or equal to zero, then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- Otherwise, TV is IV.

12.3 Casting to datetime and duration types

The following table covers conversions to datetime and duration types.

S\T	dur	dT	tim	dat	YM	Yr	MD	Day	Mon
str	M	M	M	M	M	M	M	M	M
nStr	M	M	M	M	M	M	M	M	M
tok	N	N	N	N	N	N	N	N	N
lan	N	N	N	N	N	N	N	N	N
Nam	N	N	N	N	N	N	N	N	N
NC	N	N	N	N	N	N	N	N	N
ID	N	N	N	N	N	N	N	N	N
IDR	N	N	N	N	N	N	N	N	N
IDS	N	N	N	N	N	N	N	N	N
ENT	N	N	N	N	N	N	N	N	N
ENS	N	N	N	N	N	N	N	N	N
NMT	N	N	N	N	N	N	N	N	N
NMS	N	N	N	N	N	N	N	N	N
flt	N	N	N	N	N	N	N	N	N
dbl	N	N	N	N	N	N	N	N	N
dec	N	N	N	N	N	N	N	N	N
itg	N	N	N	N	N	N	N	N	N
nPI	N	N	N	N	N	N	N	N	N
nI	N	N	N	N	N	N	N	N	N
lng	N	N	N	N	N	N	N	N	N
int	N	N	N	N	N	N	N	N	N
sh	N	N	N	N	N	N	N	N	N
byt	N	N	N	N	N	N	N	N	N
nNI	N	N	N	N	N	N	N	N	N
uL	N	N	N	N	N	N	N	N	N
uI	N	N	N	N	N	N	N	N	N
uS	N	N	N	N	N	N	N	N	N
uB	N	N	N	N	N	N	N	N	N
pI	N	N	N	N	N	N	N	N	N
dur	Y	N	N	N	N	N	N	N	N
dT	N	Y	Y	Y	Y	Y	Y	Y	Y
tim	N	Y	Y	N	N	N	N	N	N
dat	N	Y	N	Y	Y	Y	Y	Y	Y
YM	N	Y	N	Y	Y	Y	Y	N	Y
Yr	N	Y	N	Y	Y	Y	N	N	N
MD	N	Y	N	Y	Y	N	Y	Y	Y
Day	N	Y	N	Y	N	N	Y	Y	N
Mon	N	Y	N	Y	Y	N	Y	N	Y
bool	N	N	N	N	N	N	N	N	N
b64	N	N	N	N	N	N	N	N	N
hxB	N	N	N	N	N	N	N	N	N
aURI	N	N	N	N	N	N	N	N	N
QN	N	N	N	N	N	N	N	N	N
NOT	N	N	N	N	N	N	N	N	N

As specified in the preceding table, conversion from various simple types to the various duration- and time-related types depends on factors considered below. (If the entry in the preceding table is "N", then no cast is supported; consequently, the following specifications do not discuss those conversions.)

When a value of any simple 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.
  
  Editorial note
  It is unclear what effects the pattern facet of either the source or target duration items should have on this conversion.
- If ST is string or normalizedString, then TV is xf:duration(cast as string( SV )).
When a value of any simple 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() ) ).
When a value of any simple 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 normalizedString and SV is not a valid lexical representation for dateTime as specified in [XML Schema Part 2: Datatypes], then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- If ST is string or normalizedString and SV is a valid lexical representation for dateTime as specified in [XML Schema Part 2: Datatypes], then TV is xf:dateTime( SV ).
When a value of any simple 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 normalizedString and SV is a valid lexical representation for time as specified in [XML Schema Part 2: Datatypes], then TV is xf:time( SV ).
When a value of any simple 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 normalizedString and SV is not a valid lexical representation for date as specified in [XML Schema Part 2: Datatypes], then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- If ST is string or normalizedString and SV is a valid lexical representation for date as specified in [XML Schema Part 2: Datatypes], then TV is xf:date( SV ).
When a value of any simple 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 normalizedString and SV is not a valid lexical representation for gYearMonth as specified in [XML Schema Part 2: Datatypes], then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- If ST is string or normalizedString and SV is a valid lexical representation for gYearMonth as specified in [XML Schema Part 2: Datatypes], then TV is xf:date( SV ).
When a value of any simple 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 normalizedString and SV is not a valid lexical representation for gYear as specified in [XML Schema Part 2: Datatypes], then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- If ST is string or normalizedString and SV is a valid lexical representation for gYear as specified in [XML Schema Part 2: Datatypes], then TV is xf:date( SV ).
When a value of any simple 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 normalizedString and SV is not a valid lexical representation for gMonthDay as specified in [XML Schema Part 2: Datatypes], then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- If ST is string or normalizedString and SV is a valid lexical representation for gMonthDay as specified in [XML Schema Part 2: Datatypes], then TV is xf:date( SV ).
When a value of any simple 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 normalizedString and SV is not a valid lexical representation for gDay as specified in [XML Schema Part 2: Datatypes], then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- If ST is string or normalizedString and SV is a valid lexical representation for gDay as specified in [XML Schema Part 2: Datatypes], then TV is xf:date( SV ).
When a value of any simple 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 normalizedString and SV is not a valid lexical representation for gMonth as specified in [XML Schema Part 2: Datatypes], then the cast returns an error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
- If ST is string or normalizedString and SV is a valid lexical representation for gMonth as specified in [XML Schema Part 2: Datatypes], then TV is xf:date( SV ).

12.4 Casting to all other simple types

The following table covers conversions to all other simple types.

S\T	bool	b64	hxB	aURI	QN	NOT
str	M	Y	M	M	M	N
nStr	M	Y	M	M	M	N
tok	N	Y	M	N	N	N
lan	N	Y	N	N	N	N
Nam	N	Y	N	N	N	N
NC	N	Y	N	N	N	N
ID	N	Y	N	N	N	N
IDR	N	Y	N	N	N	N
IDS	N	Y	N	N	N	N
ENT	N	Y	N	N	N	N
ENS	N	Y	N	N	N	N
NMT	N	Y	N	N	N	N
NMS	N	Y	N	N	N	N
flt	M	Y	N	N	N	N
dbl	M	Y	N	N	N	N
dec	M	Y	N	N	N	N
itg	M	Y	N	N	N	N
nPI	M	Y	N	N	N	N
nI	M	Y	N	N	N	N
lng	M	Y	N	N	N	N
int	M	Y	N	N	N	N
sh	M	Y	N	N	N	N
byt	M	Y	N	N	N	N
nNI	M	Y	N	N	N	N
uL	M	Y	N	N	N	N
uI	M	Y	N	N	N	N
uS	M	Y	N	N	N	N
uB	M	Y	N	N	N	N
pI	M	Y	N	N	N	N
dur	N	Y	N	N	N	N
dT	N	Y	N	N	N	N
tim	N	Y	N	N	N	N
dat	N	Y	N	N	N	N
YM	N	Y	N	N	N	N
Yr	N	Y	N	N	N	N
MD	N	Y	N	N	N	N
Day	N	Y	N	N	N	N
Mon	N	Y	N	N	N	N
bool	Y	Y	N	N	N	N
b64	M	Y	M	N	N	N
hxB	M	Y	Y	N	N	N
aURI	N	N	N	Y	N	N
QN	N	N	N	N	Y	N
NOT	N	N	N	N	N	N

As specified in the preceding table, casting from most simple types to base64Binary and to hexBinary is possible, but sometimes depends on factors considered below; by contrast, casting to anyURI, or QName is possible only from the same type or possibly from string or normalizedString. (If the entry in the preceding table is "N", then no cast is supported; consequently, the following specifications do not discuss those conversions.)

When a value of any simple 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 or normalizedString and xf:upper( SV ) is " TRUE " or " 1 ", then TV is true; if ST is string or normalizedString and xf:upper( SV ) is " FALSE " or " 0 ", then TV is false.
- If ST is float, double, decimal, integer, long, int, short, byte, nonNegativeInteger, unsignedLong, unsignedInt, unsignedShort, unsignedByte, or positiveInteger and SV is 1, then TV is true.
- If ST is float, double, decimal, integer, nonPositiveInteger, long, int, short, byte, nonNegativeInteger, unsignedLong, unsignedInt, unsignedShort, or unsignedByte and SV is 0, then TV is false.
- If ST</

Editorial note
It is unclear what effects the `pattern` facet of either the source or target `duration` items should have on this conversion.

XQuery 1.0 and XPath 2.0 Functions and Operators Version 1.0

W3C Working Draft 27 August 2001

Abstract

Status of this Document

Table of Contents

Appendices

1 Introduction

1.1 Syntax

1.2 Notations

1.3 Namespace Prefix

2 Constructors, Functions, and Operators on Numbers

2.1 Numeric Types

2.2 Numeric Literals

2.3 Numeric Constructors

2.3.1 xf:decimal

2.3.1.1 Signature

2.3.1.2 Parameters

2.3.1.3 Semantics

2.3.1.4 Examples

2.3.2 xf:integer

2.3.2.1 Signature

2.3.2.2 Parameters

2.3.2.3 Semantics

2.3.2.4 Examples

2.3.3 xf:long

2.3.3.1 Signature

2.3.3.2 Parameters

2.3.3.3 Semantics

2.3.3.4 Examples

2.3.4 xf:int

2.3.4.1 Signature

2.3.4.2 Parameters

2.3.4.3 Semantics

2.3.4.4 Examples

2.3.5 xf:short

2.3.5.1 Signature

2.3.5.2 Parameters

2.3.5.3 Semantics

2.3.5.4 Examples

2.3.6 xf:byte

2.3.6.1 Signature

2.3.6.2 Parameters

2.3.6.3 Semantics

2.3.6.4 Examples

2.3.7 xf:float

2.3.7.1 Signature

2.3.7.2 Parameters

2.3.7.3 Semantics

2.3.7.4 Examples

2.3.8 xf:double

2.3.8.1 Signature

2.3.8.2 Parameters

2.3.8.3 Semantics

2.3.8.4 Examples

2.4 Operators on Numeric Values

2.5 Comparisons of Numeric Values

2.6 Functions on Numeric Values

2.6.1 xf:floor

2.6.1.1 Signature

2.6.1.2 Parameters

2.6.1.3 Semantics

2.6.1.4 Examples

2.6.2 xf:ceiling

2.6.2.1 Signature

2.6.2.2 Parameters

2.6.2.3 Semantics

2.6.2.4 Examples

2.6.3 xf:round

2.6.3.1 Signature

2.6.3.2 Parameters

2.6.3.3 Semantics

2.6.3.4 Examples

3 Constructors, Functions, and Operators on Strings

3.1 String Types

3.2 String Literals

3.3 String Constructors

3.3.1 xf:string

3.3.1.1 Signature

3.3.1.2 Parameters

3.3.1.3 Semantics