This appendix describes all of the built-in XQuery keywords and operators, listed alphabetically (symbols first) for convenient reference. When a symbol occurs only in the context of others, for example, by occurs only in order by, then its entry may be omitted.

Each expression description begins with the syntax for the expression, followed by an explanation of its behavior, including optional parts and exceptional cases. In the syntax description, user-supplied parts of the expression appear in italics, and use the sequence type syntax described in Appendix A. In some expression syntaxes, additional descriptive words may be used as expression “types,” including stringliteral, sequencetype, and characters, with the obvious meanings.

Each expression is cross-referenced to related expressions and other parts of the book.

item* != item*

The inequality operator != first atomizes its operands, turning them into sequences of atomic values. It then tests whether there exists an atomic value in the first sequence, and independently whether there exists an atomic value in the second sequence, such that the two compare unequal with the operator ne.

'a' != 'b'                   => true
                           (: depends on the default collation :)

(1, 2, 3) != 4               => true
(1, 2, 3) != (1, 2, 4)       => true
(1, 2, 3) != ()              => false
xdt:untypedAtomic("2") != 2  => false
<a/> != <b/>                 => false

As shown in Listing B.1, the != operator has some surprising effects: not($a = $b) has a different effect from $a != $b; and != applied to elements can return false even when the elements have different names and attributes (see Chapter 11 for additional examples and explanation).

When comparing pairs of atomic values, if either one has the dynamic type xdt:untypedAtomic, then it is first promoted to some other type using a rule that is slightly different from that of the ne operator itself (which always promotes xdt:untypedAtomic to xs:string). Instead, != always promotes untyped values to xs:double if the other value is numeric, xs:string if the other value is also xdt:untypedAtomic, and otherwise to the same type as the other operand.

In this way, the simple expression $a != $b is equivalent to the more complex expression in Listing B.2, where promote-general() is a user-defined function for general comparisons that performs the promotion rules just described (see Appendix A).

some $i in fn:data($a), $j in fn:data($b)
satisfies promote-general($i, $j) ne promote-general($j, $i)

declare function promote-general($expr, $type) {
    typeswitch ($expr)
      case xdt:untypedAtomic return
        typeswitch($type)
          case xs:decimal        return cast as xs:double($expr)
          case xs:double         return cast as xs:double($expr)
          case xs:float          return cast as xs:double($expr)
          case xdt:untypedAtomic return cast as xs:string($expr)
          default                return same-type($expr, $type)
      default return $expr
};

See also: Chapter 5; ne and = (equality) in this appendix; fn:compare() and fn:deep-equal() in Appendix C; the section “Atomization” in Chapter 2; and Chapter 11.

"characters"

The quote character is used around string literals and attribute content (in directly constructed attributes). Don't confuse the quotation mark (Unicode code point U+0022) with the so-called “smart-quote” characters used by some word processors (U+201C and U+201D).

In quoted strings, the quote character (") and ampersand (&) are special: the quote character because it denotes the end of the string, and the ampersand because it is used for entity references (named, hexadecimal, and decimal). If the string needs to contain the quote character, then either double it up ("") or use one of the three entity references: ", ", or ". Similarly, the ampersand can be escaped using one of the three entity references: &, &, or &.

All other characters (including new line characters, if the quoted string spans multiple lines) are part of the string value.

"abcde"
"apostrophe (') needs no escape here, but quote ("") and ampersand (&)
do"
<x y="z" />

See also: Chapter 1, and ' (apostrophe), "" (quote escape sequence), " (quote entity reference), &#x (hexadecimal character reference), &# (decimal character reference), and & (ampersand entity reference) in this appendix.

""

In a quoted string or attribute value, the quote character must be escaped or entitized to be used as a character in the string. The quote character can be escaped by doubling it ("").

"apostrophe (') needs no escape here, but quote ("") does"

See also: Chapter 1, and " (quotation mark) and " (quote entity reference) in this appendix.

$QName

Variables in XQuery always begin with the dollar sign followed by a qualified name. If the name is prefixed, then the namespace of the variable is the in-scope namespace corresponding to that prefix (an error is raised if the prefix is not in scope). If the name is unprefixed, then the variable has no namespace part.

Variables can be introduced by the following expressions: FLWOR, quantification (some and every), typeswitch, and declare variable. Additionally, variables may be introduced into scope by import module (if the module contains global variable declarations) or through an implementation's API. Also, in the definition of a user-defined function, all the parameters passed to the function are assigned to variables that are in scope for the body of the function.

Once a variable is in scope, it cannot be redefined. Consequently, variable definitions are fixed and don't change (although in some cases, such as FLWOR and quantification, the variable may take on different values during the expression's evaluation).

$yourVariable
$my:variable

See also: Chapter 1; the section “Query Prolog” in Chapter 5; and declare function, declare variable, every, FLWOR, import module, some, and typeswitch in this appendix.

&#N;

In strings and XML content, the decimal character reference can be used to represent any particular Unicode character. The character reference consists of the characters &# followed by one or more decimal digits (any of 0-9), and finally a semicolon (;). The integer value provided specifies the Unicode code point value represented by the reference.

The main reason to use character references is to conveniently represent characters that are difficult to type, or to distinguish them from other characters when the difference is not normally visible (for example, the nonbreaking space character  ).

The character represented by the character reference must still be a valid XML character; character references don't allow you to embed arbitrary binary data in XML (a common misconception). For that, you'll need to use a binary encoded type, such as xs:hexBinary or xs:base64Binary (see Appendix A).

"Hi!"

See also: Chapter 7; &#x (hexadecimal character reference), &, ', >, <, and " in this appendix; and fn:codepoints-to-string() in Appendix C.

&#xH;

In strings and XML content, hexadecimal character references can be used to represent any particular character. The character reference consists of the characters &# followed by one or more hexadecimal characters (any of 0-9, a-f, or A-F), and finally a semicolon (;). The hexadecimal number provided specifies the Unicode code point value that is represented by the character reference.

The main reason to use character references is to conveniently represent characters that are difficult to type or to distinguish them from other characters when the difference is not normally visible (for example, the nonbreaking space character  ).

The character represented by the character reference must still be a valid XML character; character references don't allow you to embed arbitrary binary data in XML (a common misconception). For that, you'll need to use a binary encoded type, such as xs:hexBinary or xs:base64Binary (see Appendix A).

"l33t?"

See also: Chapter 7; &# (decimal character reference), &, ', >, <, and " in this appendix; and fn:codepoints-to-string() in Appendix C.

&

The entity reference & is used in string literals and XML constructors to denote the ampersand character (&).

"&"
<x>&amp;</x>

See also: Chapter 7, and &# (decimal character reference), &#x (hexadecimal character reference), ', >, <, and " in this appendix.

'

The entity reference ' is used in string literals and XML constructors to denote the apostrophe character (').

"'"
<x>&apos;</x>

See also: Chapter 7, and ' (apostrophe), '' (apostrophe escape), &# (decimal character reference), &#x (hexadecimal character reference), &, >, <, and " in this appendix.

>

The entity reference > is used in string literals and XML constructors to denote the greater-than sign (>).

">"
<x>&gt;</x>

See also: Chapter 7, and > (greater-than sign), &# (decimal character reference), &#x (hexadecimal character reference), &, ', <, and " in this appendix.

<

The entity reference < is used in string literals and XML constructors to denote the less-than sign (<).

"<"
<x>&lt;</x>

See also: Chapter 7, and < (less-than sign), &# (decimal character reference), &#x (hexadecimal character reference), &, ', >, and " in this appendix.

"

The entity reference " is used in string literals and XML constructors to denote the quotation mark (").

"""
<x>&quot;</x>

See also: Chapter 7, and " (quotation mark), "" (quote escape), &# (decimal character reference), &#x (hexadecimal character reference), &, ', >, and < in this appendix.

'characters'

The apostrophe character is used around string literals and attribute content (in directly constructed attributes). Do not confuse the apostrophe (Unicode code point U+0027) with the so-called “smart quote” characters used by some word processors (U+2018 and U+2019).

In apostrophed strings, the apostrophe character (') and ampersand (&) are special: the apostrophe character because it denotes the end of the string, and the ampersand because it is used for entity references (named, hexadecimal, and decimal). If the string needs to contain the apostrophe character, then either double it up ('') or use one of the three entity references: ', ', or '. Similarly, the ampersand can be escaped using one of the three entity references: &, &, or &.

All other characters (including new line characters, if the string spans multiple lines) are part of the string value.

'abcde'
'quote (") needs no escape here, but apostrophe ('') and ampersand (&) do'
<x y='z' />

See also: Chapter 1, and " (quotation mark), '' (apostrophe escape sequence), and ' (apostrophe entity reference) in this appendix.

''

Inside an apostrophe-delimited string or attribute value, the apostrophe character must be doubled-up to be used as a character in the string.

'quote (") needs no escape here, but apostrophe ('') does'

See also: Chapter 1, and ' (apostrophe) and ' (apostrophe entity reference) in this appendix.

( expr )

Parentheses are used in XQuery for several purposes. The empty parentheses () denote the empty sequence. Parentheses can be used as grouping operators to express the order in which expressions should be evaluated.

Parentheses are required by some expressions, such as if and typeswitch. Parentheses are also used in function definitions and invocations as a wrapper around the function arguments. And finally, parentheses are used in some node kind tests and sequence types, like node() and item(), which look like functions but are not.

()
(1 + 2) * (3 + 4)
if ($done) then () else repeat()
subsequence( (1,2,3), 2 )

See also: Chapter 1; declare function, if, typeswitch, and validate in this appendix; and the section “Operator Precedence” in Appendix E.

(:characters:)

XQuery comments may appear anywhere that ignorable whitespace may appear, and also within element content (i.e., everywhere except inside literals, entity references, wildcards, and direct XML constructors other than elements). The entire comment is removed from the query during processing, and so contributes nothing to the query.

Comments are useful both for documentation purposes and for temporarily commenting out parts of your code during development. Comments may contain any character sequence except :) (which terminates the comment). Comments may also be nested to any depth.

XQuery comments should not be confused with XML comments, which are a kind of XML node.

(: code is read by people; use comments wisely :)
((:this is an empty sequence (: containing nested comments :):))
<x a="(:not a comment:)">(:a comment:)<!--(:not a comment:)--></x>

See also: Chapter 1, and (:: (pragma/extension) and <!-- (XML comment constructor) in this appendix.

(:: pragma QName characters ::)
(:: extension QName characters ::)

Pragmas are ignorable instructions to an XQuery implementation. If the implementation doesn't support the pragma, then it must ignore the pragma (except for parsing it). If the implementation does support the pragma, then the pragma will have whatever meaning the implementation has assigned to it. In contrast, if an implementation doesn't support an extension used by the query, then it must raise an error.

The distinction allows porting queries to other implementations; features the query requires should be extensions, while features that are optional should be pragmas. Pragmas are typically used for debugging and tracing, while extensions are typically used for function libraries and extended operators (such as DML and full-text search).

(::pragma once::)
(:: pragma warn-level 4 ::)
(:: extension full-text ::)

See also: Chapter 5 and Chapter 14.

singletype*

The asterisk character (*) has several uses in XQuery (see also wildcard and multiplication). One use is in type names. When a type name is followed by an asterisk, it represents a sequence of zero or more values of the given type.

declare function example($x as xs:integer*) { 2*3 };

See also: Chapter 2, Appendix A, and * (wildcard), * (multiplication), ? (question mark), and + (plus sign) in this appendix.

*
NCName:*
*:NCName

In paths (and element and attribute type tests), the wildcard (*) can be used as a name test. There are three variations of the wildcard: * matches any name, NCName:* matches names with any local part and the namespace corresponding to the given prefix, and *:NCName matches names with the given local part in any namespace.

When used in a path, the wildcard name test matches element nodes in all axes except the attribute axis, where it matches attribute nodes.

//*
x:*/*:y

See also: Chapter 3 and node() in Appendix A.

expr * expr

When used as a binary operator, the asterisk multiplies two expressions. Like all arithmetic operators, it first atomizes both operands. If either sequence of atomic values is empty, then it returns the empty sequence. If either sequence contains more than one value, then it raises an error.

Otherwise, if either operand is type xdt:untypedAtomic, it is converted to xs:double. If both operands are numeric, then they are promoted to a common type (see Appendix A). No other type conversions are performed; the two operands must support multiplication or an error is raised.

1 * 1                         => 1
1 * xdt:untypedAtomic("2")    => 2.0E0
1 * "2"                       => error
xs:dayTimeDuration("P3D") * 3 => xs:dayTimeDuration("P9D")

Multiplication is symmetrical. In the list below, the types may appear in either order. The pairs of types that support multiplication are:

See also: Chapter 5; + (addition), - (subtraction), div, idiv, mod, * (asterisk), and * (wildcard) in this appendix; and the section “Atomization” in Chapter 2.

singletype+

The plus sign (+) has several uses in XQuery (see also unary plus and addition). One use is in type names. When a type name is followed by a plus sign, it represents a sequence of one or more values of the given type.

declare function example($x as xs:integer+) { 2+3 };

See also: Chapter 5; Appendix A; + (unary plus), + (addition), e notation, * (asterisk), and ? (question mark) in this appendix; and fn:one-or-more() in Appendix C.

+ expr

When used as a unary operator, the plus sign has the following effects: First, it atomizes its operand, turning it into a sequence of atomic values. If the sequence is empty, then it results in the empty sequence. Otherwise, if the sequence has length greater than one, an error is raised.

If the value has dynamic type xdt:untypedAtomic, it is converted to xs:double. Otherwise, if the value is not numeric (i.e., not xs:decimal, xs:double, xs:float, or a subtype of these), then an error is raised.

+1                      => 1
+xdt:untypedAtomic("2") => 2.0E0
+"2"                    => error (: operand is not numeric :)
+current-time()         => error (: operand is not numeric :)

Unary plus can be a convenient way to force the static type of an expression to be numeric without writing treat as. Otherwise, it has no real purpose except symmetry with the unary minus operator (-).

See also: Chapter 5; - (unary minus), + (plus sign), and + (addition) in this appendix; and the section “Atomization” in Chapter 2.

expr + expr

When used as a binary operator, the plus sign adds two expressions. Like all arithmetic operators, it first atomizes both operands. If either sequence of atomic values is empty, then it returns the empty sequence. If either sequence contains more than one value, then it raises an error.

Otherwise, if either operand is type xdt:untypedAtomic, it is converted to xs:double. If both operands are numeric, then they are promoted to a common type (see Appendix A). No other type conversions are performed; the two operands must support addition or an error is raised.

1+1                      => 2
1+xdt:untypedAtomic("2") => 3.0E0
1+"2"                    => error (: operand is not numeric :)

xs:date("2004-05-13") + xs:dayTimeDuration("P17D")
=> xs:date("2004-05-30")

Addition is symmetrical. In the list below, the types may appear in either order. The pairs of types that support addition are:

Note that in XQuery, + does not perform string concatenation as it does in many other languages. For that purpose, use either the fn:concat() or fn:string-join() function.

See also: Chapter 5; - (subtraction), * (multiplication), div, idiv, mod, + (plus sign), and + (unary plus) in this appendix; and the section “Atomization” in Chapter 2.

expr , expr

XQuery uses the comma (,) symbol in two ways. One use is as a separator between items in a sequence. Because comma has the lowest precedence among all XQuery operators, you may need to enclose the sequence in parentheses.

Also, certain expressions, such as FLWOR, quantification (some, every), function invocation, and function definitions use commas to separate variable declarations and parameters. When used in this way, the items aren't actually in a sequence.

1, 2, 4                  (: used to separate items in a sequence :)
concat("a", "b")         (: used to separate parameters :)
subsequence((1, 2), 3)   (: used in both ways :)

See also: Chapter 1 and the section “Operator Precedence” in Appendix E.

- expr

When used as an unary operator, the minus sign has the following effects: First, it atomizes its operand, turning it into a sequence of atomic values. If the sequence is empty, then it results in the empty sequence. Otherwise, if the sequence has length greater than one, an error is raised.

If the value has dynamic type xdt:untypedAtomic, it is converted to xs:double. Otherwise, if the value isn't numeric (i.e., not xs:decimal, xs:double, xs:float, or a subtype of these), then an error is raised.

Finally, it negates the value.

-1                      => -1
-xdt:untypedAtomic("2") => -2.0E0
-"2"                    => error (: operand is not numeric :)
-current-time()         => error (: operand is not numeric :)

See also: Chapter 5; + (unary plus), - (hyphen), and - (subtraction) in this appendix; and the section “Atomization” in Chapter 2.

expr – expr

When used as a binary operator, the minus sign subtracts two expressions. Like all arithmetic operators, it first atomizes both operands. If either sequence of atomic values is empty, then it returns the empty sequence. If either sequence contains more than one value, then it raises an error.

Otherwise, if either operand is type xdt:untypedAtomic, it is converted to xs:double. If both operands are numeric, then they are promoted to a common type (see Appendix A). No other type conversions are performed; the two operands must support subtraction or an error is raised.

1-1                      => 0
1-xdt:untypedAtomic("2") => -1.0E0
1-"2"                    => error (: operand is not numeric :)

xs:date("2004-05-30") - xs:dayTimeDuration("P17D")
=> xs:date("2004-05-13")

Subtraction is asymmetrical. In the list below, the operand types must occur in order. The pairs of types that support subtraction are:

To subtract two xs:dateTime values and get an xdt:yearMonthDuration, use the built-in function fn:subtract-dateTimes-yielding-yearMonthDuration().

See also: Chapter 5; + (addition), * (multiplication), div, idiv, mod, - (hyphen), and - (unary minus) in this appendix; the section “Atomization” in Chapter 2; and fn:subtract-dateTimes-yielding-dayTimeDuration() and fn:subtract-dateTimes-yielding-yearMonthDuration() in Appendix C.

.

In XPath 1.0, the dot operator (.) selected the current context node. In XQuery, its behavior is similar, except that the current context item can be an atomic value or the empty sequence (when the context sequence is empty).

The current context item is perhaps most useful in predicates, where it can be used to compare the value of the current node or pass it to a function. Be aware that the predicate [.] will filter by position when the current context item is numeric.

a[. = "x"]
a[contains(., "x")]
(1, "x", 4)[.]

See also: Chapter 3 and .. (navigation operator) in this appendix.

..

As in XPath 1.0, the .. operator is just an abbreviation for parent::node(). It navigates to the parent of the current context node. If the current context item isn't a node, then it raises an error.

Note that the path x/y/.. is not equivalent to the path x (a common misconception). Instead, the path is equivalent to the path x[y], because it selects x only when it has at least one y child element.

a[.. = "x"]
node()[.. and not(../..)]   (: matches only nodes at the top :)

See also: Chapter 3, and . (current context item) and parent (axis) in this appendix.

step / step
/ step
/

The slash operator (/) by itself or at the start of a path navigates to the root node of the fragment to which the current context node belongs, exactly like a call to the built-in fn:root() function. If the current context item is not a node, it raises an error. So, the path / is equivalent to fn:root(.), while the path /step is equivalent to fn:root(.)/step. Otherwise, the / operator has no real meaning except to separate steps in a path.

/
/top
/comment()
a/b/c
a[@b = "x"]/c/@d

See also: Chapter 3 and fn:root() in Appendix C.

step // step
// step

The double slash (//) operator is similar to the slash (/) operator in that it can begin a path or separate steps in a path. However, // is actually an abbreviation for /descendant-or-self::node()/, so, for example, a//b means a/descendant-or-self::node()/b. Unlike /, // must always have a step expression following it.

The path a//b is equivalent to a/descendant-or-self::node()/b, which is equivalent to a/descendant::b.

//x      (: this selects every x element in document order :)
x//y     (: this selects every y element descendant of x :)

Although // is easy to write, it's also easy to misuse. In some implementations, //a is much slower than directly seeking to the a element (when you know the path in advance). On other implementations, the converse is true. (In still other implementations, both queries perform equally well when schema information is provided.) The path a//b is almost always slower than directly seeking to the b element (when you know the path in advance).

Also, // has some surprises, such as the difference between //x[1] and (//x)[1]. See Chapter 11 for additional examples and discussion.

//x[1]   (: this selects the first x child element of each node :)
(//x)[1] (: this selects the first x element overall :)

See also: Chapter 3; / (slash), descendant, and descendant-or-self in this appendix; and Chapter 11.

axis::nodetest

The axis separator isn't really an operator. It exists to syntactically separate the axis name from the node test (which may also be a name). Whitespace is allowed between the separator and the axis and/or node test.

child::w/descendant::x:y / attribute :: z

See also: Chapter 3, and attribute (axis), child, descendant, descendant-or-self, parent, and self in this appendix.

item* < item*

The less-than operator, <, first atomizes its operands, turning them into sequences of atomic values. It then tests whether there exists an atomic value in the first sequence, and independently whether there exists an atomic value in the second sequence, such that the first compares less than the second using the value comparison operator lt.

Because < is also used for other purposes (including element constructors), it is parsed differently depending on the character following it. For example, <a><<b/> is a parse error because << parses as the node comparison operator, while <a/>< <b/> (with a space between the two < characters) parses as expected.

'a' < 'b'                   => true
                            (: depends on the default collation :)
(1, 2, 3) < 4               => true
(1, 2, 3) < (1, 2, 4)       => true
(1, 2, 3) < ()              => false
xdt:untypedAtomic("2") < 2  => false
<a/> < <b/>                 => false

As shown in Listing B.1, the < operator has some surprising effects, especially with the empty sequence (see Chapter 11 for additional surprises and explanations).

When comparing pairs of atomic values, if either one has the dynamic type xdt:untypedAtomic, then it is first promoted to some other type using a rule that is slightly different from that of the lt operator itself (which always promotes xdt:untypedAtomic to xs:string). Instead, < always promotes untyped values to xs:double if the other value is numeric, to xs:string if the other value is also xdt:untypedAtomic, and otherwise to the same type as the other operand.

In this way, the simple expression $a < $b is equivalent to the more complex expression in Listing B.2, where promote-general() is a hypothetical user-defined function that performs the general comparison promotion rules just described.

some $i in fn:data($a), $j in fn:data($b)
satisfies promote-general($i, $j) lt promote-general($j, $i)

See also: Chapter 5; lt and <= (less than or equal to) in this appendix; fn:compare() and fn:deep-equal() in Appendix C; the section “Atomization” in Chapter 2; and Chapter 11.

<qname attributes/>
<qname attributes>content</qname>

XQuery uses almost the same syntax for constructing XML elements as XML does, with one exception: the curly brace characters, { and } , have special meaning for XQuery. They indicate that an XQuery compiler should parse the enclosed expression as an XQuery expression instead of as character content for the XML node. To use these characters as content, double them up.

In XQuery, the XML element syntax is called direct element constructor to distinguish it from the computed element constructor syntax that uses the element keyword. The computed syntax is capable of computing not only the element content, but also its name. The direct constructor syntax is equivalent to the computed syntax with a constant name.

Space characters in constructed XML elements may be stripped or preserved, depending on the xmlspace policy.

<x y="1">z</x>           => <x y="1">z</x>
<x y="1+1">1+1</x>       => <x y="1+1">1+1</x>
<x y="{1+1}">{1+1}</x>   => <x y="2">2</x>

See also: Chapter 7, and { (left curly brace), {{ (left curly brace escape sequence), }} (right curly brace escape sequence ), declare xmlspace, and element (constructor) in this appendix.

<!--chars-->

XQuery uses the same syntax for constructing XML comments as XML does. Unfortunately, XQuery doesn't provide any way to construct a comment node with computed content.

XML comments shouldn't be confused with XQuery comments. XML comments construct nodes; XQuery comments are ignored by the compiler.

<!---->
<!-- this is an XML comment -->

See also: Chapter 7, and < (XML element constructor), <? (XML processing instruction constructor), <![CDATA[ (CDATA section constructor), and (: (XQuery comment) in this appendix.

<![CDATA[chars]]>

XQuery uses the same syntax for constructing XML CDATA sections as XML does. Unfortunately, XQuery doesn't provide any way to construct a CDATA section with computed content.

XML CDATA sections exist only to allow you to avoid using lots of entity and character references. They cannot contain characters that are invalid for XML, and they cannot contain the sequence ]]> because that is used to signify the end of a CDATA section. One way to overcome the second limitation is to use two CDATA sections: <![CDATA[]]]]><![CDATA[>]]>.

<x><![CDATA[Special characters like &, <, and > do not require escaping in CDATA 
sections]]></x>

See also: Chapter 7 and text (constructor) in this appendix.

expr << expr

The node comparison operator << (“before”) takes two arguments, which must be either singleton nodes or the empty sequence. If either operand is empty, then << returns the empty sequence. Otherwise, it returns true if the first node appears before the second in document order, and false otherwise.

doc("foo.xml") << doc("foo.xml")  => false

See also: Chapter 5 and >> (after) in this appendix.

item* <= item*

The less-than-equals operator, <=, first atomizes its operands, turning them into sequences of atomic values. It then tests whether there exists an atomic value in the first sequence, and independently whether there exists an atomic value in the second sequence, such that the first compares less than or equal to the second using the value comparison operator le.

'a' <= 'b'                   => true
                             (: depends on the default collation :)

(1, 2, 3) <= 4               => true
(1, 2, 3) <= (1, 2, 4)       => true
(1, 2, 3) <= ()              => false
xdt:untypedAtomic("2") <= 2  => true
<a/> <= <b/>                 => false

As shown in Listing B.1, the <= operator has some surprising effects, especially with the empty sequence (see Chapter 11 for additional surprises and explanations).

When comparing pairs of atomic values, if either one has the dynamic type xdt:untypedAtomic, then it is first promoted to some other type using a rule that is slightly different from that of the le operator itself (which always promotes xdt:untypedAtomic to xs:string). Instead, <= always promotes untyped values to xs:double if the other value is numeric, to xs:string if the other value is also xdt:untypedAtomic, and otherwise to the same type as the other operand.

In this way, the simple expression $a <= $b is equivalent to the more complex expression in Listing B.2, where promote-general() is a user-defined function for general comparisons that performs the promotion rules just described (see Appendix A).

some $i in fn:data($a), $j in fn:data($b)
satisfies promote-general($i, $j) le promote-general($j, $i)

See also: Chapter 5; le and < (less-than) in this appendix; fn:compare() and fn:deep-equal() in Appendix C; the section “Atomization” in Chapter 2; and Chapter 11.

<?chars?>

XQuery uses the same syntax for constructing XML processing instructions as XML does. Unfortunately, XQuery doesn't provide any way to construct a processing instruction node with computed content.

<? example ?>
<?process this?>

See also: Chapter 7, and < (XML element constructor) and <!-- (XML comment constructor) in this appendix.

item* = item*

The equality operator = first atomizes its operands, turning them into sequences of atomic values. It then tests whether there exists an atomic value in the first sequence, and independently whether there exists an atomic value in the second sequence, such that the first compares equal to the second using the value comparison operator eq.

'a' = 'b'                   => false
                            (: depends on the default collation :)

(1, 2, 3) = 4               => false
(1, 2, 3) = (1, 2, 4)       => true
(1, 2, 3) = ()              => false
xdt:untypedAtomic("2") = 2  => true
<a/> = <b/>                 => false

As shown in Listing B.1, the = operator has some surprising effects, especially with the empty sequence (see Chapter 11 for additional surprises and explanations).

When comparing pairs of atomic values, if either one has the dynamic type xdt:untypedAtomic, then it is first promoted to some other type using a rule that is slightly different from that of the eq operator itself (which always promotes xdt:untypedAtomic to xs:string). Instead, = always promotes untyped values to xs:double if the other value is numeric, to xs:string if the other value is also xdt:untypedAtomic, and otherwise to the same type as the other operand.

In this way, the simple expression $a = $b is equivalent to the more complex expression in Listing B.2, where promote-general() is a user-defined function for general comparisons that performs the promotion rules just described (see Appendix A).

some $i in fn:data($a), $j in fn:data($b)
satisfies promote-general($i, $j) eq promote-general($j, $i)

See also: Chapter 5; eq and != (inequality) in this appendix; fn:compare() and fn:deep-equal() in Appendix C; the section “Atomization” in Chapter 2; and Chapter 11.

item* > item*

The greater-than operator, >, first atomizes its operands, turning them into sequences of atomic values. It then tests whether there exists an atomic value in the first sequence, and independently whether there exists an atomic value in the second sequence, such that the first compares greater than the second using the value comparison operator gt.

'a' > 'b'                   => false
                             (: depends on the default collation :)

(1, 2, 3) > 4               => false
(1, 2, 3) > (1, 2, 4)       => true
(1, 2, 3) > ()              => false
xdt:untypedAtomic("2") > 2  => false
<a/> > <b/>                 => false

As shown in Listing B.1, the > operator has some surprising effects, especially with the empty sequence (see Chapter 11 for additional surprises and explanations).

When comparing pairs of atomic values, if either one has the dynamic type xdt:untypedAtomic, then it is first promoted to some other type using a rule that is slightly different from that of the gt operator itself (which always promotes xdt:untypedAtomic to xs:string). Instead, > always promotes untyped values to xs:double if the other value is numeric, to xs:string if the other value is also xdt:untypedAtomic, and otherwise to the same type as the other operand.

In this way, the simple expression $a > $b is equivalent to the more complex expression in Listing B.2, where promote-general() is a hypothetical user-defined function that performs the general comparison promotion rules just described.

some $i in fn:data($a), $j in fn:data($b)
satisfies promote-general($i, $j) gt promote-general($j, $i)

See also: Chapter 5; gt and >= (greater-than or equal to) in this appendix; fn:compare() and fn:deep-equal() in Appendix C; the section “Atomization” in Chapter 2; and Chapter 11.

node? >> node?

The node comparison operator >> (“after”) takes two arguments, which must be either singleton nodes or the empty sequence. If either operand is empty, then >> returns the empty sequence. Otherwise, it returns true if the first node appears after the second in document order, and false otherwise.

doc("foo.xml") >> doc("foo.xml")  => false

See also: Chapter 5, << (before) in this appendix, and Chapter 2.

item* >= item*

The greater-than-equals operator, >=, first atomizes its operands, turning them into sequences of atomic values. It then tests whether there exists an atomic value in the first sequence, and independently whether there exists an atomic value in the second sequence, such that the first compares greater than or equal to the second using the value comparison operator ge.

'a' >= 'b'                   => false
                             (: depends on the default collation :)

(1, 2, 3) >= 4               => false
(1, 2, 3) >= (1, 2, 4)       => true
(1, 2, 3) >= ()              => false
xdt:untypedAtomic("2") >= 2  => true
<a/> >= <b/>                 => false

As shown in Listing B.1, the >= operator has some surprising effects, especially with the empty sequence (see Chapter 11 for additional surprises and explanations).

When comparing pairs of atomic values, if either one has the dynamic type xdt:untypedAtomic, then it is first promoted to some other type using a rule that is slightly different from that of the ge operator itself (which always promotes xdt:untypedAtomic to xs:string). Instead, >= always promotes untyped values to xs:double if the other value is numeric, to xs:string if the other value is also xdt:untypedAtomic, and otherwise to the same type as the other operand.

In this way, the simple expression $a >= $b is equivalent to the more complex expression in Listing B.2, where promote-general() is a user-defined function for general comparisons that performs the promotion rules just described (see Appendix A).

some $i in fn:data($a), $j in fn:data($b)
satisfies promote-general($i, $j) ge promote-general($j, $i)

See also: Chapter 5; ge and > (greater-than sign) in this appendix; fn:compare() and fn:deep-equal() in Appendix C; the section “Atomization” in Chapter 2; and Chapter 11.

singletype?

When a type name is followed by a question mark, it represents a sequence of zero or one values of the given type.

Note that in a function, a parameter that occurs zero or one times must still occur; it isn't an optional parameter. For example, the function in Listing B.49 must still be passed two parameters, even if they are both empty.

The question mark also appears in XML processing instruction constructors, for example, <?pi?>.

declare function example($x as xs:integer?) external;
$y cast as xs:string?

See also: Chapter 2; * (asterisk), + (plus sign), and <? and ?> (XML processing instruction constructors) in this appendix; and fn:zero-or-one() in Appendix C.

@nodetest

The @ symbol is most commonly used as a convenient abbreviation for the attribute axis. It also appears in front of names in the attribute() type test, to emphasize that it matches attributes.

a[@b = 1]/@c

See also: Chapter 3, attribute (axis) in this appendix, and attribute() type test in Appendix A.

step [ expr ]

XQuery, like XPath, uses square brackets to enclose predicate expressions. The predicate is a postfix operator, applied after an expression (the sequence to be filtered) and containing an expression (the predicate expression).

The predicate expression is evaluated for each item in the sequence to be filtered, using that item as the current context item (and deriving the rest of the focus from it, including the context position). If the predicate evaluates to true, then the item is kept in the result; otherwise, it is omitted.

If the predicate evaluates to a numeric value, then it is true if the context position is equal to that number. Otherwise, the predicate is converted to boolean exactly like the fn:boolean() function.

("a", "b", "c")[2]       => "b"
("a", "b", "c")[2.5]     => ()
("a", "b", "c")[false()] => ()
("a", "b", "c")[true()]  => ("a", "b", "c")

x[y]    (: selects x if it has a child element y :)
x[@y=1] (: selects x if it has an attribute y equal to 1 :)

When the entire predicate is the current context item and the sequence to be filtered contains atomic values, “surprising” results can occur, as shown in Listing B.52. Numbers are compared to the context position, and all other values are converted to boolean.

(1, 5, 3, 4, 2)[.]      => (1, 3, 4)
("a", "", "b")[.]       => ("a", "b")
(true(), false(), 3)[.] => (true(), 3)

See also: Chapter 3, and . (current context item) in this appendix.

{ expr }

Curly braces are used in the following expressions: declare variable, declare function, and validate, and the computed node constructors (attribute, document, element, and text).

The most important use of curly braces is inside element and attribute content to denote that the enclosed expression should be evaluated as an XQuery expression, instead of just treated as ordinary characters. To use a curly brace as an ordinary character in element or attribute content, double it up (or use a character escape).

<x y="{1 div 2}">{ 1 + 1 }</x> => <x y="0.5">2</x>
<x y="{{">}}</x>               => <x y="{">}</x>

See also: Chapter 7; {{ (left curly brace escape sequence), }} (right curly brace escape sequence), < (XML element constructor) , attribute (constructor), declare function, declare variable, document (constructor), element (constructor), text (constructor), and validate in this appendix.

{{

In direct element constructors, the curly brace characters are used to enclose XQuery expressions. Consequently, if the element needs to contain a curly brace character itself, it must be escaped. There's no named entity reference for the curly braces, and it's difficult to remember their decimal or hexadecimal character references, so XQuery allows these characters to be escaped by doubling them.

<x>{{</x>        => <x>{</x>
<x>{1}{{{2}</x>  => <x>1{2</x>

See also: Chapter 7, and }} (right curly brace escape sequence), { (left curly brace), and < (XML element constructor) in this appendix.

}}

In direct element constructors, the curly brace characters are used to enclose XQuery expressions. Consequently, if the element needs to contain a curly brace character itself, it must be escaped. There's no named entity reference for the curly braces, and it's difficult to remember their decimal or hexadecimal character references, so XQuery allows these characters to be escaped by doubling them.

<x>}}</x>        => <x>}</x>
<x>{1}}}{2}</x>  => <x>1}2</x>

See also: Chapter 7, and {{ (left curly brace escape sequence), } (right curly brace), and < (XML element constructor) in this appendix.

ancestor::nodetest

The ancestor axis matches all ancestors of the current context node. The node test can be used to filter the ancestors further, for example, matching only those with a particular name or node kind.

XQuery implementations aren't required to support the ancestor axis; Chapter 10 provides a workaround.

count(ancestor::*)
x[ancestor::y]/ancestor::z

See also: Chapter 3, Chapter 10, and ancestor-or-self and parent in this appendix.

ancestor-or-self::nodetest

The ancestor-or-self axis matches all ancestors of the current context node, as well as the node itself. XQuery implementations aren't required to support the ancestor-or-self axis; Chapter 10 provides a workaround.

ancestor-or-self::foo/bar
count(ancestor-or-self::*)

See also: Chapter 3, Chapter 10, and ancestor and parent in this appendix.

expr and expr

The and operator first converts both of its operands to boolean using the fn:boolean() function (also known as the Effective Boolean Value). If either operand is true, then and returns true, otherwise it returns false.

true() and false()        => false
"" and 0.0                => false
"x" and 1.0               => true
() and (true(), true())   => false

The order in which the and operator evaluates its arguments is implementation-dependent, and implementations are also allowed (and encouraged) to “short-circuit” this operator (evaluating only one of its operands if that is enough to determine the overall result). Consequently, expressions like error() and false() and false() and error() may raise an error or may return false, depending on the implementation.

See also: Chapter 5, and fn:boolean()and fn:not() in Appendix C.

attribute::nodetest

The attribute axis matches all attributes of the current context node. The node test can be used to filter the attributes further, for example, matching only those with a particular name.

It's common practice to use @ as an abbreviation instead of writing attribute. When using the abbreviation, no axis separator is required.

count(attribute::*)
x[attribute::y = 1 or attribute::z]
x[@y = 1 or @z]

See also: Chapter 3, and @ (at sign), child, descendant, descendant-or-self, parent, and self in this appendix.

attribute name { expr }
attribute { expr } { expr }

The computed attribute constructor takes two arguments, the name and the content. The name expression can be an ordinary name, or an expression (enclosed in curly braces) that computes the name. Attributes with constant names can be constructed using the ordinary XML syntax, so the computed name case is the more interesting of the two.

When the name is computed, the name expression must result in either an xs:QName value or else an xs:string value which is then parsed into a QName using the in scope namespaces. If the name cannot be parsed or isn't a QName, then an error is raised. Otherwise, the resulting QName value is the name of the attribute.

The content expression is first atomized, and then each item in the (possibly empty) sequence of atomic values is converted to string and then concate nated together with spaces separating them. In other words, attribute name { $x } is equivalent to attribute name { string-join(" ", data($x)) }.

The type of the constructed attribute is xdt:untypedAtomic, regardless of the type of its content expression, and the attribute isn't validated (unless it is used in an expression such as element construction or validate).

<x>{ attribute foo { () } }</x>         => <x foo="" />
<x>{ attribute { "ab" } { "c", "d", 3 } => <x ab="c d 3" />

See also: Chapter 7; document (constructor), element (constructor), and text (constructor) in this appendix; and the section “Atomization” in Chapter 2.

expr cast as singletype

The cast as operator takes two arguments: an expression and a single type (the target type).

It first atomizes the expression. If the result contains more than one atomic value, then an error is raised. If the atomized sequence is empty, then the cast succeeds (and results in the empty sequence) only if the single type is followed by the ? occurrence indicator. Otherwise, cast as attempts to convert this single value to the target type, and either succeeds (resulting in a value with that type) or else raises an error using one of the following three rules:

These conversion steps can result in an error. For example, converting "2.0" into an xs:integer will fail because the decimal point isn't allowed in the lexical format for xs:integer. Converting "2004-02-30" into xs:date will fail because although the string satisfies the lexical constraints for xs:date, it isn't a valid xs:date value (the second month never has 30 days).

xs:string("2.0") cast as xs:decimal => 2.0
xs:string("2.0") cast as xs:integer => error
xs:string("2") cast as xs:decimal   => 2.0
xs:string("2") cast as xs:integer   => 2

See also: Chapter 9; castable as, treat as, and validate in this appendix; Chapter 11; and section A.4 in Appendix A.

expr castable as singletype

The castable as operator takes two arguments, an expression and a single type. It returns true if the expression can be cast into that type (by the cast as operator), otherwise it returns false.

This operator is mainly used to avoid conversion errors by first testing whether an expression can be converted.

1.0 castable as xs:integer => true
1.5 castable as xs:integer => false

See also: Chapter 9, cast as in this appendix, and Chapter 2.

child::nodetest

The child axis matches all children (element, text, comment, and processing-instruction nodes) of the current context node. The node test can be used to filter the children further, for example, matching only those with a particular name or node kind.

It's common practice to omit the child axis, because it is the default axis. When using the abbreviation, no axis separator is required.

count(child::*)
count(child::comment())
x[child::y]/child::z
x[y]/z

See also: Chapter 3, and / (slash), attribute, descendant, descendant-or-self, parent, and self in this appendix.

comment { expr }

The computed comment constructor takes one argument, which becomes the content of the comment node. The content is first atomized. If the resulting sequence is empty, then the content is the empty string. Otherwise, each atomic value is cast to xs:string, concatenated together with a space character in between each consecutive pair, and the final result becomes the content of the constructed comment node.

comment { "foo" }  => <!--foo-->
comment { (1, 2) } => <!--1 2-->

See also: Chapter 7, and attribute (constructor), document (constructor), element (constructor), namespace (constructor), pi (constructor), and text (constructor) in this appendix.

declare base-uri stringliteral;

The base URI declaration sets the base-uri value of the static context, which is used by functions such as base-uri() and doc().

See also: Chapter 5, and base-uri() in Appendix C.

declare default collation stringliteral;

The query prolog may contain a default collation declaration, which specifies the default collation to be used in the query (for comparing strings). The value must be a string literal naming a collation supported by the implementation, or else an error is raised. At most one default collation declaration may be used.

When no default collation declaration is used, the default collation is implementation-defined. Many implementations will use the Unicode code point collation as their default; its URI is http://www.w3.org/2003/11/xpath-functions/collation/codepoint. The Unicode code point collation is the only collation implementations are required to support.

declare default collation "http://www.unicode.org/lang/en-us";

See also: Chapter 8, and fn:default-collation()in Appendix C.

declare default element namespace stringliteral;

The query prolog may contain a default element namespace declaration, which specifies the default namespace to be used for all element names (including constructors and paths) and type names (in cast as and other expressions).

At most one default element namespace declaration may appear in the prolog. Element constructors may override the default namespace using xmlns.

declare default element namespace "http://www.w3c.org";
<x>
  <y xmlns="http://www.w3c.org" />
</x>

Unlike ordinary namespace declarations, the namespace string may be the empty string (which is also the default value), in which case the default element namespace is no namespace at all. Otherwise, the namespace must be a valid namespace URI.

See also: Chapter 5, and declare default function namespace and declare namespace in this appendix.

declare default function namespace stringliteral;

The query prolog may contain a default function namespace declaration, which specifies the default namespace to be used for all function names (function invocations and definitions) in the module. At most one default function namespace declaration may be used in the prolog.

declare default function namespace "http://www.w3c.org";
foo("xyz")

Unlike ordinary namespace declarations, the namespace string may be the empty string, in which case the default function namespace is no namespace at all. Otherwise, the namespace must be a valid namespace URI.

If a default function namespace declaration isn't provided, then in the main module the default namespace is the same one that is bound to the built-in fn prefix (http://www.w3.org/2003/11/xpath-functions). In library modules, the default is the target namespace of the module.

The default function namespace must not cause two functions to have the same (unprefixed) name and number of arguments, or else an error is raised (duplicate function declaration).

See also: Chapter 5, and declare default element namespace, declare namespace, and module in this appendix.

declare function qname ( params ) { expr };
declare function qname ( params ) as sequencetype { expr };
declare function qname ( params ) external;
declare function qname ( params ) as sequencetype external;

$varname

$varname as sequencetype

Function definitions are specified after the query prolog but before the query body, using the declare function keyword.

Functions are defined by name. If the name doesn't have a prefix, then it isn't in a namespace; otherwise, it is in the namespace corresponding to that prefix. User-defined functions may not be overloaded (i.e., only one definition per name), may not override built-in functions, and always take a fixed number of arguments. In contrast, many built-in functions are overloaded (e.g., compare()) and one (concat()) takes a variable number of arguments.

User-defined functions declare zero or more parameters, which are then in scope for the entire function body. Untyped parameters have the most generic type (item*). All parameters must have different names.

User-defined functions have a return type. If omitted, then the return type of the function is the most generic type (item*). The function body must match (according to sequence type matching) its declared type or an error is raised.

(: Compute $b raised to the $exp power :)
declare function pow($b as xs:integer,
                     $exp as xs:integer) as xs:integer {
  if ($exp > 1)
    then $b * pow($b, $exp – 1)
  else if ($expr = 1)
    then $b
  else
    1
};

To allow interoperability with other languages, XQuery allows you to declare externally defined functions by using the external keyword instead of a function body. It's up to implementations whether and how to handle externally defined functions (including translating XQuery types into other languages' types and vice versa).

See also: Chapter 4, and declare variable in this appendix.

declare namespace NCName = stringliteral;

The namespace declaration introduces a namespace prefix into scope, binding it to the given namespace URI. The string literal must be a valid, non-empty URI. Every namespace declaration in the prolog must use a different prefix, although elements may override prefix bindings using xmlns or the namespace constructor.

The namespace URI must not be the empty string. To define the default namespace, use declare default element namespace or declare default function namespace, depending on the desired effect.

declare namespace p = "http://www.w3c.org";
<p:x>
  <p:y xmlns:p="http://www.aw.com" />
</p:x>

XQuery predefines the five namespaces listed in Table B.1. The first two of these are tied to the current version of the XQuery drafts in progress; the other three are final. All of these except for the xml prefix may be redefined using declare namespace.

See also: Chapter 5, declare default element namespace and declare default function namespace in this appendix, and fn:get-inscope-namespace-prefixes() in Appendix C.

declare validation mode;

The validation declaration specifies the default validation mode to be used with the validate operator and element constructors. The mode must be one of lax, skip, or strict. If no validation declaration is used, then the default validation mode is lax.

declare validation lax;
declare validation skip;
declare validation strict;

See also: Chapter 9, and validate and < (XML element constructor) in this appendix.

declare variable $varName { expr };
declare variable $varName as sequenceType { expr };
declare variable $varName external;
declare variable $varName as sequenceType external;

Global variable declarations introduce a variable name into global scope. Optionally, the variable declaration may be typed. Then the variable is either assigned a value, or else declared to be an external parameter whose value is provided at runtime. These are called global variables and global (external) parameters, respectively. The name “variable” is somewhat misleading, because the value doesn't vary.

If the type is omitted for a global variable, then its static type is the static type of its value. This type must be compatible with the type of the expression used for the variable value. If the type is omitted for a global parameter, then its static type is xs:anyType.

How external parameter values are supplied to the query depends entirely on the implementation, but an error is raised if a value isn't supplied or its type is incompatible with the static type.

declare variable $meaningOfLife as xs:integer { 42 };
declare variable $my:zero { 0 };
declare variable $unknown external;
declare variable $userID as xs:string external;

See also: Chapter 5, and declare function and $ (variable) in this appendix.

declare xmlspace mode;

The xmlspace declaration specifies how boundary whitespace characters in XML element and attribute constructors are handled. The mode must be either preserve or strip (strip is the default), meaning preserve or remove boundary whitespace, respectively.

declare xmlspace strip;
declare xmlspace preserve;

See also: Chapter 7 and < (element constructor) in this appendix.

descendant::nodetest

The descendant axis matches all descendants (element, text, comment, and processing-instruction nodes) of the current context node. The node test can be used to filter the descendants further (for example, matching only those with a particular name or node kind).

Note that the descendant axis excludes the current node itself; to include the current node, use the descendant-or-self axis. The descendant axis itself doesn't have an abbreviation, although often the // abbreviation ends up having that meaning; for example, a//b is equivalent to a/descendant::b (but only because its actual expansion, a/descendant-or-self::node()/b, happens to reduce to that).

count(descendant::*)
count(descendant::comment())
x[descendant::y]/descendant::z

The descendant axis can have surprising results when it matches nodes contained in other matched nodes. In this case, both the containing node (including all its content) and the contained node are selected. The contained node will thus appear more than once in the output (once in the selection, and once in each other selected node that contains it).

(<a><b id="1"><b id="2"/></b></a>)/descendant::b
=>
<b id="1"><b id="2"/></b><b id="2"/>

See also: Chapter 3, and // (navigation operator), attribute, child, descendant-or-self, parent, and self in this appendix.

descendant-or-self::nodetest

The descendant-or-self axis matches all descendants (element, text, comment, and processing-instruction nodes) of the current context node, and also the node itself. The node test can be used to filter this selection further, for example, matching only those with a particular name or node kind. Note that the descendant-or-self axis includes the current node itself; to exclude it, use the descendant axis.

The descendant-or-self axis itself can be abbreviated using //, which actually stands for /descendant-or-self::node()/. Because this abbreviation involves multiple steps, predicates applied to the step after it may not have the meaning you expect. For example, //x selects every x element in the current document. However, //x[1] doesn't select the first x element in the current document. Instead, //x[1] expands to /descendant-or-self::node()/x[1], which first matches every node in the current document (including the document node itself) and then for each one selects the first child element named x. Depending on the document, this can result in a single x element or many. To select the first x element in the entire document, you would need to use (//x)[1].

count(//*)
count(//comment())
x[.//y]//z
x[descendant-or-self::node()/y]/descendant-or-self::node()/z

Like the descendant axis, the descendant-or-self axis can have surprising results when it matches nodes contained in other matched nodes. In this case, both the containing node (including all its content) and the contained node are selected. The contained node will thus appear more than once in the serialized output (once in the selection, and once in each other selected node that contains it). For example, the query in Listing B.76 selects the outer b element with id="1" followed by the inner b element with id="2". The inner element also appears a second time in the output, as the child of the outer element.

(<a><b id="1"><b id="2"/></b></a>)//b
=>
<b id="1"><b id="2"/></b><b id="2"/>

See also: Chapter 3; // (navigation operator); attribute, child, descendant, parent, and self in this appendix; and Chapter 11.

expr div expr

In XQuery, like XPath 1.0, division is expressed using the div keyword, not slash (/). Slash is used for paths.

Like all arithmetic operators, div first atomizes both operands. If either sequence of atomic values is empty, then it returns the empty sequence. If either sequence contains more than one value, then it raises an error. Otherwise, if either operand is type xdt:untypedAtomic, it is converted to xs:double. If both operands are numeric, then they are promoted to a common type (see Appendix A). No other type conversions are performed; the two operands must support division or an error is raised.

On numeric types, the result of division is always xs:double. To perform integer division, either use the idiv operator or else one of the rounding functions (floor(), ceiling(), round(), and round-to-even()).

Note that when using floating-point types, division by zero doesn't result in an error. Instead, it results in a special double value (positive infinity, negative infinity, or not-a-number).

1 div 2                      => 0.5
1E0 div 2                    => 5E-1
1 div 0                      => error (: division by zero :)
1E0 div 0                    => INF
1 div xdt:untypedAtomic("2") => 5E-1
1 div "2"                    => error (: operand is not numeric :)

Division is asymmetrical. In the list below, the operand types must occur in the order given (left to right). The pairs of types that support division are:

All others raise an error.

See also: Chapter 5; idiv, mod, * (multiplication), - (subtraction), + (addition), and / (slash) in this appendix; and the section “Atomization” in Chapter 2.

document { expr }

XQuery provides only one way to construct a document node in the query: The document constructor, which takes a single argument, the content of the document node.

Each item in the content sequence is processed as follows:

The resulting sequence of items (possibly empty) is the content of the constructed document node. The document constructor does not enforce XML well-formedness rules (such as that the document must contain exactly one element node), although some implementations may enforce them anyway (during serialization, or before).

document { () }
document { <root>{ doc("foo.xml") } </root> }

The document constructor is most useful in situations where you want to change the schema types of nodes, or when you want to create an entire XML document (as if by the doc() function). Use the validate operator to apply more specific types to the constructed document.

See also: Chapter 7, and attribute (constructor), element (constructor), text (constructor), and validate in this appendix.

decimalEinteger
decimalE+integer
decimalE-integer

XQuery uses “scientific E-notation” to indicate that a number is a double-precision floating-point number (instead of an integer or decimal).

E notation can be written using either a lowercase or uppercase E followed by an exponent (which can be positive or negative; if no sign is provided, then the exponent is positive). The result is the number in front of the E times ten raised to the exponent power. For example, 1.0e2 is 100, while 1.0E-2 is one one-hundredth (.01).

1.0e2
1.0e+2
1.0E+2
2.34e+0
56E-2

See also: Chapter 1, and xs:double in Appendix A.

element name { expr }
element { expr } { expr }

The computed element constructor takes two arguments: the name and the content. The name expression can be an ordinary name, or an expression (enclosed in curly braces) that computes the name. Elements with constant names can be constructed using the ordinary XML syntax (<name>{content}</name>), so the computed name case is the one that more commonly uses the computed element constructor.

When the name is computed, the name expression must result in either an xs:QName value or else an xs:string value, which is then parsed into a QName using the in-scope namespaces. If the name cannot be parsed or isn't a QName, then an error is raised. Otherwise, the resulting QName value is the name of the element.

Each item in the (possibly empty) content expression is handled as follows:

The resulting sequence of items (possibly empty) is the content of the constructed element node.

Unlike the computed document constructor, the computed element constructor implicitly validates its content (and therefore also enforces XML well-formedness rules), using the current validation mode and validation context. When the element name is constant, it is added to the validation context; otherwise, the validation context is set to global. If there aren't any types in scope, then the constructed element type is xs:anyType.

element foo { () }                           => <foo/>
element { concat("a", "b") } { "c", "d", 3 } => <ab>c d 3</ab>

See also: Chapter 7, and attribute (constructor), comment (constructor), declare validation, document (constructor), namespace (constructor), pi (constructor), and text (constructor) in this appendix.

expr eq expr

The eq operator takes two operands, which can be arbitrary expressions. It first atomizes both operands; an error is raised if the atomized operands aren't single atomic values. If either atomized operand is type xdt:untypedAtomic, then it is cast to xs:string.

Then eq returns true if the first operand is equal to the second. If the two operands aren't comparable types, then an error is raised. See Chapter 5 for details.

2 eq 1.0              => false
2 eq 2.0              => true
"10" eq 2             => error
"10" eq "2"           => false (: depends on default collation :)

See also: Chapter 5; the section “Atomization” in Chapter 2; and = (equals sign), ne, is, gt, ge, lt, and le in this appendix.

every $var in expr satisfies expr
every $var in expr, $var2 in expr2, ... satisfies expr

The every operator performs universal quantification; that is, it tests whether every item satisfies a condition. It takes one or more variable clauses separated by commas. Each of these introduces a variable into scope for the remainder of the every expression, and causes that variable to range over some sequence. The condition expression is specified after the keyword satisfies at the end of the expression. The result is true if every variable assignment causes the condition expression to evaluate to true.

every $i in (1, 2, 3) satisfies $i >= 4                 => false
every $i in (1, 2, 3) satisfies $i < 4                  => true
every $i in (1, 2), $j in (3, 4) satisfies $i * $j = 10 => false
every $i in (1, 2), $j in (3, 4) satisfies $i * $j = 8  => false

The every operator can be expressed less conveniently using exists() and FLWOR. For example, every $var1 in $expr1, $var2 in $expr2, ... satisfies $condition is equivalent to the double-negated expression not(exists(for $var1 in $expr1, $var2 in $expr2, ... where not($condition) return 1)).

See also: Chapter 6, and FLOWR and some in this appendix.

node* except node*

The except operator takes two operands, which must be node sequences (possibly empty). It returns all the nodes that are in the first sequence but not in the second (using node identity to determine equality), and sorts the resulting node sequence by document order.

let $a := <a/>, $b := <b/>, $c := <c/>
return ($a, $b) except ($b, $c)
=>
  $a

Unlike the set intersection and union operators, the set difference operator is asymmetric. The symmetric set difference (all the nodes that are in one of the two sets but not in both) can be computed using either of the two expressions in Listing B.84.

($a except $b) union ($b except $a)
($a union $b) except ($a intersect $b)

See also: Chapter 5, and intersect and union in this appendix.

for $var1 in $expr1 at $pos1, $var2 in $expr2, ...
let $v1 := $e1, $v2:= $e2, ...
where condition
stable? order by sortkey1 modifier1, sortkey2 modifier2, ...
return expr

(ascending | descending)?
(empty (greatest | least))?
(collation stringliteral)?

The FLWOR (“flower”) expression is the most complex, but also the most important, expression in XQuery. It is the only way to construct a sequence sorted in any order other than document order. It is also the most convenient way to introduce variables into scope or to join a sequence with others (or itself).

FLWOR uses one or more for and let clauses (in any order), an optional where clause, an optional order by clause, and a return clause. FLWOR gets its name from the first letters of these clauses (for, let, where, order by, return).

The for and let clauses construct what is known as a tuple space, which can be visualized as a matrix of columns and rows. Each variable introduced by a for or let is a column in the matrix. The where clause filters that tuple space, the order by clause sorts it, and then the return clause returns an item for each row remaining in the tuple space. The overall result is this filtered, sorted sequence of items.

for $i in (1, 2), $j in (3, 4, 5)
for $k in (6, 7)
return ($i, $j, $k)
=>
(1, 3, 6, 1, 3, 7, 1, 4, 6, 1, 4, 7, 1, 5, 6, 1, 5, 7,
 2, 3, 6, 2, 3, 7, 2, 4, 6, 2, 4, 7, 2, 5, 6, 2, 5, 7)

for $i in ("a", "b", "c") at $pos
return ($i, $pos)
=>
("a", 1, "b", 2, "c", 3)

let $i := ("x", "y", "z")
return count($i)
=>
3

for $i in ("x", "y", "z")
return count($i)
=>
(1, 1, 1)

let $x := <x/>   (: constructs one node :)
return $x is $x
=>
true

<x/> is <x/>     (: constructs two nodes :)
=>
false

for $i in (1, 2, 3) at $p
let $j := $i * $p
for $k in ($i, $j)
return $k
=>
(1, 1, 2, 4, 3, 9)

for $i in ("a", "b", "c", "d") at $p
where $p > 2
return $i
=>
("c", "d")

for $i in ("a", "b"¸ "c", "d") at $pos
for $j in (6, 3, 1, 2)
where $pos = $j
return $i
=>
"c", "a", "b"

for $i in ("a", "b", "c", "d") at $p
where $p > 2
order by $p descending  (: sorting occurs after filtering :)
return $i
=>
("d", "c")

for $i in ("a", "b", "c", "d")
for $j in (4, 1, 3, 2, 4)
where $i = $j
return <x y="{$i}"/>
=>
<x y="d"/>
<x y="a"/>
<x y="c"/>
<x y="b"/>
<x y="d"/>

following::nodetest

count(following::*)
x[following::y]/following::z

following-sibling::nodetest

following-sibling::foo/bar
count(following-sibling::*)

expr ge expr

2 ge 1.0              => true
2 ge 2.0              => true
"10" ge 2             => error
"10" ge "2"           => false (: depends on default collation :)

expr gt expr

2 gt 1.0              => true
2 gt 2.0              => false
"10" gt 2             => error
"10" gt "2"           => false (: depends on default collation :)

expr idiv expr

1 idiv 2                      => 0
1E0 idiv 2                    => error (: operand not integer :)
1 idiv 0                      => error (: division by zero :)
1 idiv xdt:untypedAtomic("2") => 0
1 idiv "2"                    => error (: operand not integer :)

if ( expr ) then expr else expr

if (true()) then "1" else 1.0          => "1"
if (1 < 2 and 2 < 3) then "x" else "y" => "x"

if ($x) then 1
else if ($y) then 2
else if ($z) then 3
else 0

import module target;
import module target at locationHint;
import module namespace NCName = target;
import module namespace NCName = target at locationHint;

import module "urn:foo";
import module x = "urn:bar";

import schema uri;
import schema uri at string;
import schema namespace prefix = uri;
import schema namespace prefix = uri at string;
import schema default element namespace uri;
import schema default element namespace uri at string;

import schema "urn:foo";
import schema "urn:foo" at "http://www.w3c.org/foo.xsd";
import schema x = "urn:foo" at "http://www.w3c.org/foo.xsd";
import schema default element namespace "urn:foo";

expr instance of sequencetype

<x/> instance of element()        => true
<x/> instance of xs:integer       => false
(1, 2, 3) instance of xs:integer* => true
() instance of xs:integer*        => true
() instance of xs:integer+        => false

node* intersect node*

let $a := <a/>, $b := <b/>, $c := <c/>
return ($a, $b) intersect ($b, $c)
=>
  $b

node? is node?

() is ()                         => ()
doc("foo.xml") is doc("foo.xml") => true
<x/> is <x/>                     => false
let $x := <x/> return $x is $x   => true

expr le expr

2 le 1.0              => false
2 le 2.0              => true
"10" le 2             => error
"10" le "2"           => true (: depends on default collation :)

expr lt expr

2 lt 1.0              => false
2 lt 2.0              => false
"10" lt 2             => error
"10" lt "2"           => true (: depends on default collation :)

expr mod expr

4 mod 3                      => 1
4 mod 3.0                    => 1.0
4E0 mod 3                    => 1E0
4E0 mod 0                    => NaN
4 mod xdt:untypedAtomic("3") => 1E0
4 mod "3"                    => error (: operand not numeric :)

module namespace prefix = "targetNamespace";

module namespace foo = "urn:bar";

namespace prefix { expr }

namespace foo { "urn:bar" }  => xmlns:foo="urn:bar"

expr ne expr

2 ne 1.0              => true
2 ne 2.0              => false
"10" ne 2             => error
"10" ne "2"           => true (: depends on default collation :)

expr or expr

true() or false()        => true
"" or 0.0                => false
"x" or 1.0               => true
() or (false(), false()) => true

parent::nodetest

count(parent::node())
x/parent::node()
x/..

processing-instruction { "foo" }           => <? foo?>
processing-instruction { "foo" } { "bar" } => <?foo bar?>

preceding::nodetest

count(preceding::*)
x[preceding::y]/preceding::z

preceding-sibling::nodetest

preceding-sibling::foo/bar
count(preceding-sibling::*)

processing-instruction { expr }
processing-instruction { expr } { expr }

self::nodetest

x[.//y] (: .//y is a relative path, starting from the current node :)
x[//y]  (: //y is an absolute path, starting from the root :)
x[data(.) = 1]
self::comment()

some $var in expr satisfies expr
some $var in expr, $var2 in expr2, ... satisfies expr

some $i in (1, 2, 3) satisfies $i >= 4                 => false
some $i in (1, 2, 3) satisfies $i < 4                  => true
some $i in (1, 2), $j in (3, 4) satisfies $i * $j = 10 => false
some $i in (1, 2), $j in (3, 4) satisfies $i * $j = 8  => true

text { expr? }

if (empty($X)) then ()
else text { string-join(" ", for $i in data($X) return string($i) }

text { }                        => ()
text { () }                     => ()
text { 1, 2, 3 }                => text { "1 2 3" }
<x>{ <y/>, text { "zzz" } }</x> => <x><y/>zzz</x>

expr to expr

1 to 3 => (1, 2, 3)
3 to 1 => ()
3 to 3 => 3
xdt:untypedAtomic("-1") to xs:long(2) => (-1, 0, 1, 2)

expr treat as sequencetype

2 treat as xs:decimal   => 2
2.0 treat as xs:integer => error

2 cast as xs:decimal    => 2.0
2.0 cast as xs:integer  => 2

typeswitch (expr) caseClause+ defaultClause

   case sequencetype return expr
case $var as sequencetype return expr

    defaultClause return expr
defaultClause $var return expr

typeswitch (<hello/>)
  case $a as attribute return concat("a:", local-name($a))
  case $e as element return concat("e:", local-name($e))
  default return "x"
=>
"e:hello"

for $i in (1, <x/>, "2")
return typeswitch ($i)
         case xs:integer return "integer"
         case xs:decimal return "decimal"
         case xs:string  return "string"
         case node()     return "node"
         default         return error("unknown type")
=>
("integer", "node", "string")

declare function sequence-type-of($expr) as xs:string {
    if (count($expr) > 1) then concat(single-type-of($expr), "+")
    else single-type-of($expr)
};

declare function single-type-of($expr) as xs:string {
    typeswitch ($expr)
        case empty()                   return "empty()"
        case element()*                return "element()"
        case attribute()*              return "attribute()"
        case text()*                   return "text()"
        case comment()*                return "comment()"
        case document-node()*          return "document-node()"
        case processing-instruction()* return "processing-instruction()"
        case node()*                   return "node()"
        case xdt:untypedAtomic*        return "xdt:untypedAtomic"
        case xs:unsignedByte*          return "xs:unsignedByte"
        case xs:unsignedShort*         return "xs:unsignedShort"
        case xs:unsignedInt*           return "xs:unsignedInt"
        case xs:unsignedLong*          return "xs:unsignedLong"
        case xs:positiveInteger*       return "xs:positiveInteger"
        case xs:nonNegativeInteger*    return "xs:nonNegativeInteger"
        case xs:byte*                  return "xs:byte"
        case xs:short*                 return "xs:short"
        case xs:int*                   return "xs:int"
        case xs:long*                  return "xs:long"
        case xs:negativeInteger*       return "xs:negativeInteger"
        case xs:nonPositiveInteger*    return "xs:nonPositiveInteger"
        case xs:integer*               return "xs:integer"
        case xs:decimal*               return "xs:decimal"
        case xs:ENTITY*                return "xs:ENTITY"
        case xs:IDREF*                 return "xs:IDREF"
        case xs:ID*                    return "xs:ID"
        case xs:NCName*                return "xs:NCName"
        case xs:Name*                  return "xs:Name"
        case xs:NMTOKEN*               return "xs:NMTOKEN"
        case xs:language*              return "xs:language"
        case xs:token*                 return "xs:token"
        case xs:normalizedString*      return "xs:normalizedString"
        case xs:string*                return "xs:string"
        case xdt:dayTimeDuration*      return "xdt:dayTimeDuration"
        case xdt:yearMonthDuration*    return "xdt:yearMonthDuration"
        case xs:duration*              return "xs:duration"
        case xs:NOTATION*              return "xs:NOTATION"
        case xs:QName*                 return "xs:QName"
        case xs:anyURI*                return "xs:anyURI"
        case xs:double*                return "xs:double"
        case xs:float*                 return "xs:float"
        case xs:hexBinary*             return "xs:hexBinary"
        case xs:base64Binary*          return "xs:base64Binary"
        case xs:boolean*               return "xs:boolean"
        case xs:date*                  return "xs:date"
        case xs:time*                  return "xs:time"
        case xs:dateTime*              return "xs:dateTime"
        case xs:gMonth*                return "xs:gMonth"
        case xs:gDay*                  return "xs:gDay"
        case xs:gMonthDay*             return "xs:gMonthDay"
        case xs:gYear*                 return "xs:gYear"
        case xs:gYearMonth*            return "xs:gYearMonth"
        case xdt:anyAtomicType*        return "xdt:anyAtomicType"
        case xs:anySimpleType*         return "xs:anySimpleType"
        case xs:anyType*               return "xs:anyType"
        default                        return "item()"
};

node* union node*

let $a := <a/>, $b := <b/>, $c := <c/>
return ($a, $b) union ($b, $c)
=>
  ($a, $b, $c)


() | () => ()

validate mode context { node }

validate { <x>12</x> }
validate strict { <x>12</x> }
validate strict type(y)/z { <x>12</x> }

xquery version stringliteral;

xquery version "1.0";