4 Expressions

This section discusses each of the basic kinds of expression. Each kind of expression has a name such as PathExpr, which is introduced on the left side of the grammar production that defines the expression. Since XQuery 4.0 is a composable language, each kind of expression is defined in terms of other expressions whose operators have a higher precedence. In this way, the precedence of operators is represented explicitly in the grammar.

The order in which expressions are discussed in this document does not reflect the order of operator precedence. In general, this document introduces the simplest kinds of expressions first, followed by more complex expressions. For the complete grammar, see Appendix [A XQuery 4.0 Grammar].

[Definition: A query consists of one or more modules.] If a query is executable, one of its modules has a Query Body containing an expression whose value is the result of the query. An expression is represented in the XQuery grammar by the symbol Expr.

[44]    Expr    ::=    ExprSingle ("," ExprSingle)*
[45]    ExprSingle    ::=    WithExpr
| FLWORExpr
| QuantifiedExpr
| SwitchExpr
| TypeswitchExpr
| IfExpr
| TryCatchExpr
| TernaryConditionalExpr

The XQuery 4.0 operator that has lowest precedence is the comma operator, which is used to combine two operands to form a sequence. As shown in the grammar, a general expression (Expr) can consist of multiple ExprSingle operands, separated by commas. The name ExprSingle denotes an expression that does not contain a top-level comma operator (despite its name, an ExprSingle may evaluate to a sequence containing more than one item.)

The symbol ExprSingle is used in various places in the grammar where an expression is not allowed to contain a top-level comma. For example, each of the arguments of a function call must be an ExprSingle, because commas are used to separate the arguments of a function call.

After the comma, the expressions that have next lowest precedence are FLWORExpr, QuantifiedExpr, SwitchExpr, TypeswitchExpr, IfExpr, TryCatchExpr, and OrExpr. Each of these expressions is described in a separate section of this document.

4.1 Setting Namespace Context

[46]    WithExpr    ::=    "with" NamespaceDeclaration ("," NamespaceDeclaration)* EnclosedExpr
[47]    NamespaceDeclaration    ::=    QName "=" URILiteral
[242]    URILiteral    ::=    StringLiteral
[40]    EnclosedExpr    ::=    "{" Expr? "}"

The namespace context for an expression can be set using a construct of the form:

with xmlns="http://example.com/,
     xmlns:a="http://example.com/a" {
       /doc/a:element/b
}

The static context for the enclosed expression will be the same as the static context for the WithExpr itself, except for modifications defined below.

The QName used in a NamespaceDeclaration must be either xmlns or xmlns:prefix where prefix is some NCName.

If more than one NamespaceDeclaration specifies the same QName, all but the last of the duplicates are ignored.

If the QName is "xmlns" then:

If the QName is in the form xmlns:prefix then the URILiteral must not be zero-length; the effect is that a binding that maps the given prefix to the specified namespace URI is added to the statically known namespaces.

For example, the expression:

with xmlns="http://www.acme.com/" {a/b[c=3]}

is equivalent to the expression:

Q{http://www.acme.com/}a/Q{http://www.acme.com/}b[Q{http://www.acme.com/}c=3]

4.2 Comments

[256]    Comment    ::=    "(:" (CommentContents | Comment)* ":)" /* ws: explicit */
/* gn: comments */
[264]    CommentContents    ::=    (Char+ - (Char* ('(:' | ':)') Char*))

Comments may be used to provide information relevant to programmers who read a query, either in the Prolog or in the Query Body . Comments are lexical constructs only, and do not affect query processing.

Comments are strings, delimited by the symbols (: and :). Comments may be nested.

A comment may be used anywhere ignorable whitespace is allowed (see A.2.4.1 Default Whitespace Handling).

The following is an example of a comment:

(: Houston, we have a problem :)

4.3 Primary Expressions

[Definition: Primary expressions are the basic primitives of the language. They include literals, variable references, context item expressions, constructors, and function calls. A primary expression may also be created by enclosing any expression in parentheses, which is sometimes helpful in controlling the precedence of operators.] Node Constructors are described in 4.12 Node Constructors.Map and Array Constructors are described in 4.14 Maps and Arrays. String Constructors are described in 4.13 String Constructors.

[147]    PrimaryExpr    ::=    Literal
| VarRef
| ParenthesizedExpr
| ContextItemExpr
| FunctionCall
| OrderedExpr
| UnorderedExpr
| NodeConstructor
| FunctionItemExpr
| MapConstructor
| ArrayConstructor
| StringConstructor
| UnaryLookup
[186]    FunctionItemExpr    ::=    NamedFunctionRef | InlineFunctionExpr

4.3.1 Literals

[Definition: A literal is a direct syntactic representation of an atomic value.] XQuery 4.0 supports two kinds of literals: numeric literals and string literals.

[148]    Literal    ::=    NumericLiteral | StringLiteral
[149]    NumericLiteral    ::=    IntegerLiteral | DecimalLiteral | DoubleLiteral
[244]    IntegerLiteral    ::=    Digits
[245]    DecimalLiteral    ::=    ("." Digits) | (Digits "." [0-9]*) /* ws: explicit */
[246]    DoubleLiteral    ::=    (("." Digits) | (Digits ("." [0-9]*)?)) [eE] [+-]? Digits /* ws: explicit */
[247]    StringLiteral    ::=    ('"' (PredefinedEntityRef | CharRef | EscapeQuot | [^"&])* '"') | ("'" (PredefinedEntityRef | CharRef | EscapeApos | [^'&])* "'") /* ws: explicit */
[250]    PredefinedEntityRef    ::=    "&" ("lt" | "gt" | "amp" | "quot" | "apos") ";" /* ws: explicit */
[251]    EscapeQuot    ::=    '""'
[252]    EscapeApos    ::=    "''"
[263]    Digits    ::=    [0-9]+

The value of a numeric literal containing no "." and no e or E character is an atomic value of type xs:integer. The value of a numeric literal containing "." but no e or E character is an atomic value of type xs:decimal. The value of a numeric literal containing an e or E character is an atomic value of type xs:double. The value of the numeric literal is determined by casting it to the appropriate type according to the rules for casting from xs:untypedAtomic to a numeric type as specified in Section 19.2 Casting from xs:string and xs:untypedAtomic FO31.

Note:

The effect of the above rule is that in the case of an integer or decimal literal, a dynamic error [err:FOAR0002]FO31 will generally be raised if the literal is outside the range of values supported by the implementation (other options are available: see Section 4.2 Arithmetic operators on numeric values FO31 for details.)

The limits of numeric datatypes are specified in 6.3 Data Model Conformance.

The value of a string literal is an atomic value whose type is xs:string and whose value is the string denoted by the characters between the delimiting apostrophes or quotation marks. If the literal is delimited by apostrophes, two adjacent apostrophes within the literal are interpreted as a single apostrophe. Similarly, if the literal is delimited by quotation marks, two adjacent quotation marks within the literal are interpreted as one quotation mark.

A string literal may contain a predefined entity reference. [Definition: A predefined entity reference is a short sequence of characters, beginning with an ampersand, that represents a single character that might otherwise have syntactic significance.] Each predefined entity reference is replaced by the character it represents when the string literal is processed. The predefined entity references recognized by XQuery are as follows:

Entity Reference Character Represented
&lt; <
&gt; >
&amp; &
&quot; "
&apos; '

A string literal may also contain a character reference. [Definition: A character reference is an XML-style reference to a [Unicode] character, identified by its decimal or hexadecimal codepoint.] For example, the Euro symbol (€) can be represented by the character reference &#8364;. Character references are normatively defined in Section 4.1 of the XML specification (it is implementation-defined whether the rules in [XML 1.0] or [XML 1.1] apply.) A static error [err:XQST0090] is raised if a character reference does not identify a valid character in the version of XML that is in use.

Here are some examples of literal expressions:

  • "12.5" denotes the string containing the characters '1', '2', '.', and '5'.

  • 12 denotes the xs:integer value twelve.

  • 12.5 denotes the xs:decimal value twelve and one half.

  • 125E2 denotes the xs:double value twelve thousand, five hundred.

  • "He said, ""I don't like it.""" denotes a string containing two quotation marks and one apostrophe.

  • "Ben &amp; Jerry&apos;s" denotes the xs:string value "Ben & Jerry's".

  • "&#8364;99.50" denotes the xs:string value "€99.50".

The xs:boolean values true and false can be constructed by calls to the built-in functions fn:true() and fn:false(), respectively.

Values of other simple types can be constructed by calling the constructor function for the given type. The constructor functions for XML Schema built-in types are defined in Section 18.1 Constructor functions for XML Schema built-in atomic types FO31. In general, the name of a constructor function for a given type is the same as the name of the type (including its namespace). For example:

  • xs:integer("12") returns the integer value twelve.

  • xs:date("2001-08-25") returns an item whose type is xs:date and whose value represents the date 25th August 2001.

  • xs:dayTimeDuration("PT5H") returns an item whose type is xs:dayTimeDuration and whose value represents a duration of five hours.

Constructor functions can also be used to create special values that have no literal representation, as in the following examples:

  • xs:float("NaN") returns the special floating-point value, "Not a Number."

  • xs:double("INF") returns the special double-precision value, "positive infinity."

Constructor functions are available for all simple types, including union types. For example, if my:dt is a user-defined union type whose member types are xs:date, xs:time, and xs:dateTime, then the expression my:dt("2011-01-10") creates an atomic value of type xs:date. The rules follow XML Schema validation rules for union types: the effect is to choose the first member type that accepts the given string in its lexical space.

It is also possible to construct values of various types by using a cast expression. For example:

  • 9 cast as hatsize returns the atomic value 9 whose type is hatsize.

4.3.2 Variable References

[150]    VarRef    ::=    "$" VarName
[151]    VarName    ::=    EQName

[Definition: A variable reference is an EQName preceded by a $-sign.] An unprefixed variable reference is in no namespace. Two variable references are equivalent if their expanded QNames are equal (as defined by the eq operator). The scope of a variable binding is defined separately for each kind of expression that can bind variables.

Every variable reference must match a name in the in-scope variables.

Every variable binding has a static scope. The scope defines where references to the variable can validly occur. It is a static error [err:XPST0008] to reference a variable that is not in scope. If a variable is bound in the static context for an expression, that variable is in scope for the entire expression except where it is occluded by another binding that uses the same name within that scope.

A reference to a variable that was declared external, but was not bound to a value by the external environment, raises a dynamic error [err:XPDY0002].

At evaluation time, the value of a variable reference is the value to which the relevant variable is bound.

4.3.3 Parenthesized Expressions

[152]    ParenthesizedExpr    ::=    "(" Expr? ")"

Parentheses may be used to override the precedence rules. For example, the expression (2 + 4) * 5 evaluates to thirty, since the parenthesized expression (2 + 4) is evaluated first and its result is multiplied by five. Without parentheses, the expression 2 + 4 * 5 evaluates to twenty-two, because the multiplication operator has higher precedence than the addition operator.

Empty parentheses are used to denote an empty sequence, as described in 4.7.1 Sequence Concatenation.

4.3.4 Context Item Expression

[153]    ContextItemExpr    ::=    "."

A context item expression evaluates to the context item, which may be either a node (as in the expression fn:doc("bib.xml")/books/book[fn:count(./author)>1]), or an atomic value or function (as in the expression (1 to 100)[. mod 5 eq 0]).

If the context item is absentDM31, a context item expression raises a dynamic error [err:XPDY0002].

4.3.5 Enclosed Expressions

[40]    EnclosedExpr    ::=    "{" Expr? "}"

[Definition: An enclosed expression is an instance of the EnclosedExpr production, which allows an optional expression within curly braces.] [Definition: In an enclosed expression, the optional expression enclosed in curly braces is called the content expression.] If the content expression is not provided explicitly, the content expression is ().

Note:

Despite the name, an enclosed expression is not actually an expression in its own right; rather it is a construct that is used in the grammar of many other expressions.

4.4 Functions

Functions in XQuery 4.0 arise in two ways:

The functions defined by a statically known function definition can be invoked using a static function call. Function items corresponding to these definitions can also be obtained, as dynamic values, by evaluating a named function reference. Function items can also be obtained using the fn:function-lookup function: in this case the function name and arity do not need to be known statically, and the function definition need not be present in the static context, so long as it is in the dynamic context.

The mechanisms for making function calls by reference to function definitions and function items are described in the following sections.

4.4.1 Function Definitions

The static context for an expression includes a set of statically known function definitions. Every function definition in the static context has a name (which is an expanded QName) and an arity range, which is a range of permitted arities for calls on that function. Two function definitions having the same name must not have overlapping arity ranges. This means that for a given static function call, it is possible to identify the target function definition in the static context unambiguously from knowledge of the function name and the number of supplied arguments.

A static function call is bound to a function definition in the static context by matching the name and arity. If the function call has P positional arguments followed by K keyword arguments, then the required arity is P+K, and the static context must include a function definition whose name matches the expanded QName in the function call, and whose arity range includes this required arity. This is the function chosen to be called. The result of the function is obtained by evaluating the expression that forms its implementation, with a dynamic context that provides values for all the declared parameters, initialized as described in 4.4.1.2 Evaluating Static Function Calls below.

Similarly, a function reference of the form f#N binds to a function in the static context whose name matches f where MinP ≤ N and MaxP ≥ N. The result of evaluating a function reference is a (dynamic) function which can be called using a dynamic function call. Dynamic functions are never variadic and their arguments are always supplied positionally. For example, the function reference fn:concat#3 returns a function with arity 3, which is always called by supplying three positional arguments, and whose effect is the same as a static call on fn:concat with three positional arguments.

The detailed rules for evaluating static function calls and function references are defined in subsequent sections.

4.4.1.1 Static Function Call Syntax
[156]    FunctionCall    ::=    EQName ArgumentList /* xgc: reserved-function-names */
/* gn: parens */
[136]    ArgumentList    ::=    "(" ((PositionalArguments ("," KeywordArguments)?) | KeywordArguments)? ")"
[138]    PositionalArguments    ::=    Argument ("," Argument)*
[157]    Argument    ::=    ExprSingle | ArgumentPlaceholder
[158]    ArgumentPlaceholder    ::=    "?"
[139]    KeywordArguments    ::=    KeywordArgument ("," KeywordArgument)*
[140]    KeywordArgument    ::=    EQName ":=" Argument

[Definition: A static function call consists of an EQName followed by a parenthesized list of zero or more arguments.]

The argument list consists of zero or more positional arguments, followed by zero or more keyword arguments.

[Definition: An argument to a function call is either an argument expression or an ArgumentPlaceholder (?); in both cases it may either be supplied positionally, or identified by a name (called a keyword).]

This section is concerned with static function calls in which none of the arguments are ArgumentPlaceholders. Calls using one or more ArgumentPlaceholders are covered in the section 4.4.2.2 Partial Function Application.

If the function name supplied in a static function call is an unprefixed lexical QName, it is expanded using the default function namespace in the static context.

The expanded QName used as the function name, and the number of arguments in the static function call (the required arity) must match the name and arity range of a function definition in the static context using the rules defined in the previous section; if there is no match, a static error is raised [err:XPST0017].

Evaluation of static function calls is described in 4.4.1.2 Evaluating Static Function Calls .

Since the arguments of a function call are separated by commas, any argument expression that contains a top-level comma operator must be enclosed in parentheses. Here are some illustrative examples of static function calls:

  • my:three-argument-function(1, 2, 3) denotes a static function call with three positional arguments. The corresponding function declaration must define at least three parameters, and may define more, provided they are optional.

  • my:two-argument-function((1,2), 3) denotes a static function call with two arguments, the first of which is a sequence of two values. The corresponding function declaration must define at least two parameters, and may define more, provided they are optional.

  • my:two-argument-function(1, ()) denotes a static function call with two arguments, the second of which is an empty sequence.

  • my:one-argument-function((1, 2, 3)) denotes a static function call with one argument that is a sequence of three values.

  • my:one-argument-function(( )) denotes a static function call with one argument that is an empty sequence.

  • my:zero-argument-function( ) denotes a static function call with zero arguments.

  • fn:lang(node:=$n, language:='de') is a static function call with two keyword arguments. The corresponding function declaration defines two parameters, a required parameter language and an optional parameter node. This call supplies values for both parameters. It is equivalent to the call fn:lang('de', $n). Note that the keyword arguments are in a different order from the parameter declarations.

  • fn:sort(//employee, key := ->{xs:decimal(salary)}) is a static function call with one positional argument and one keyword argument. The corresponding function declaration defines three parameters, a required parameter $input, an optional parameter $collation, and an optional parameter $key This call supplies values for the first and third parameters, leaving the second parameter ($collation) to take its default value. The default value of the $collation parameter is given as fn:default-collation(), so the value supplied to the function is the default collation from the dynamic context of the caller. It is equivalent to the call fn:sort(//employee, fn:default-collation(), ->{xs:decimal(salary)}).

An EQName in a KeywordArgument is expanded to a QName value; if there is no prefix, then the name is in no namespace (otherwise the prefix is resolved in the usual way). The keywords used in a function call (after expansion to QNames) must be distinct [err:XPST0141]; [err:XPST0142].

4.4.1.2 Evaluating Static Function Calls

This section applies to static function calls where none of the arguments is an ArgumentPlaceholder. For function calls involving placeholders, see 4.4.2.2 Partial Function Application.

When a static function call FC is evaluated with respect to a static context SC and a dynamic context DC, the result is obtained as follows:

  1. The function definition FD to be used is found in >the statically known function definitions of SC.

    The required arity is the total number of arguments in the function call, including both positional and keyword arguments.

    There can be at most one function definition FD in the statically known function definitions component of SC whose function name matches the expanded QName in FC and whose arity range includes the arity of FC's ArgumentList.

    If there is no such function definition, a static error [err:XPST0017] is raised.

  2. Each parameter in the function definition FD is matched to an argument expression as follows:

    1. If there are N positional arguments in the function call, the corresponding argument expressions are matched pairwise to the first N parameters in the declaration. For this purpose the required parameters and optional parameters in FD are concatenated into a single list, in order.

    2. Any keyword arguments in FC are then matched to parameters (whether required or optional) in FD by comparing the keyword used in FC with the paramater name declared in FD. Each keyword must match the name of a declared parameter [err:XPST0142], and this must be one that has not already been matched to a positional argument. [err:XPST0141].

    3. If any required parameter has not been matched to any argument in FC by applying the above rules, a static error is reported [err:XPST0141]

    4. If any optional parameter has not been matched to any argument in FC by applying the above rules, then the parameter is matched to the default value expression for that parameter in FD.

  3. Each argument expression established by the above rules is evaluated with respect to DC. The order of argument evaluation is implementation dependent and it is not required that an argument be evaluated if the function body can be evaluated without evaluating that argument.

    Note:

    All argument expressions, including default value expressions, are evaluated in the dynamic context of the function call. It is therefore possible to use a default value expression such as ., or /, or fn:current-dateTime(), whose value depends on the dynamic context of the function call.

    If the expression used for the default value of a parameter has no dependencies on the dynamic context, then an implementation may choose to reuse the same value on repeated function calls rather than re-evaluating it on each function call.

    Note:

    This is relevant, for example, if the expression constructs new nodes.

  4. The result of evaluating the argument expression is converted to the required type (the declared type associated with the corresponding parameter in the function declaration, defaulting to item()*) by applying the coercion rules.

  5. The result of the function call is obtained as follows:

    • FD's implementation is invoked in an implementation-dependent way. The processor makes the following information available to that invocation:

      • The converted argument values;

      • An empty set of nonlocal variable bindings; and

      • A static context and dynamic context. If FD's implementation is associated with a static and a dynamic context, then these are supplied, otherwise SC and DC are supplied.

      How this information is used is implementation-defined. An API used to call external functions must state how the static and dynamic contexts are provided to a function that is called. The F&O specification states how the static and dynamic contexts are used in each function that it defines.

    • The result is converted to the required type (the declared return type in the function declaration, defaulting to item()*) by applying the coercion rules.

      The result of applying the coercion rules is either an instance of FD's return type or a dynamic error. This result is then the result of evaluating FC.

      Note:

      A host language may define alternative rules for processing the result, especially in the case of external functions implemented using a non-XDM type system.

    • Errors raised by built-in functions are defined in [XQuery and XPath Functions and Operators 4.0].

    • Errors raised by external functions are implementation-defined (see 2.3.5 Consistency Constraints).

    Example: A Built-in Function

    The following function call uses the function Section 2.5 fn:base-uri FO31. Use of SC and DC and errors raised by this function are all defined in [XQuery and XPath Functions and Operators 4.0].

    fn:base-uri()

4.4.2 Function Items

A function item is an XDM value that can be bound to a variable, or manipulated in various ways by XQuery 4.0 expressions. The most significant such expression is a dynamic function call, which supplies values of arguments and evaluates the function to produce a result.

The syntax of dynamic function calls is defined in 4.5.2 Dynamic Function Calls.

A number of constructs can be used to produce a function item, notably:

  • A named function reference (see 4.4.2.3 Named Function References) constructs a function item by reference to function definitions in the static context: for example fn:node-name#1 returns a function whose effect is to call the static fn:node-name function with one argument.

  • An inline function (see 4.4.2.4 Inline Function Expressions) constructs a function whose implementation is defined locally. For example the construct ->($x){$x+1} returns a function whose effect is to increment the value of the supplied argument.

  • A partial function application (see 4.4.2.2 Partial Function Application) derives one function from another by supplying the values of some of its arguments. For example, fn:ends-with(?, ".txt") returns a function with one argument that tests whether the supplied string ends with the substring ".txt".

  • Maps and arrays are also functions. See 4.14.1.1 Map Constructors and 4.14.2.1 Array Constructors.

  • The fn:function-lookup function can be called to discover functions that are present in the dynamic context.

  • The fn:load-xquery-module function can be called to load functions dynamically from an external XQuery library module.

  • Some built-in functions such as fn:random-number-generator and fn:op return a function item as their result.

These constructs are described in detail in the following sections, or in [XQuery and XPath Functions and Operators 4.0].

4.4.2.1 Evaluating Dynamic Function Calls

This section applies to dynamic function calls whose arguments do not include an ArgumentPlaceholder. For function calls that include a placeholder, see 4.4.2.2 Partial Function Application.

[Definition: A dynamic function call is an expression that is evaluated by calling a function item, which is typically obtained dynamically.]

When a dynamic function call FC is evaluated, the result is obtained as follows:

  1. The function item F to be called is obtained by evaluating the base expression of the function call. If this yields a sequence consisting of a single function whose arity matches the number of arguments in the ArgumentList, let F denote that function. Otherwise, a type error is raised [err:XPTY0004].

    Note:

    Keyword arguments are not allowed in a dynamic function call.

  2. Argument expressions are evaluated, producing argument values. The order of argument evaluation is implementation-dependent and an argument need not be evaluated if the function body can be evaluated without evaluating that argument.

  3. Each argument value is converted to the corresponding parameter type in F's signature by applying the coercion rules, resulting in a converted argument value .

  4. If F is a map, it is evaluated as described in 4.14.1.2 Map Lookup using Function Call Syntax.

  5. If F is an array, it is evaluated as described in 4.14.2.2 Array Lookup using Function Call Syntax.

  6. If F's implementation is an XQuery 4.0 expression (for example, if F is a user-defined function or an anonymous function, or a partial application of such a function):

    1. F's implementation is evaluated. The static context for this evaluation is the static context of the XQuery 4.0 expression. The dynamic context for this evaluation is obtained by taking the dynamic context of the module that contains the FunctionBody, and making the following changes:

      • The focus (context item, context position, and context size) is absentDM31.

      • In the variable values component of the dynamic context, each converted argument value is bound to the corresponding parameter name.

        When this is done, the converted argument values retain their dynamic types, even where these are subtypes of the declared parameter types. For example, a function with a parameter $p of type xs:decimal can be called with an argument of type xs:integer, which is derived from xs:decimal. During the processing of this function call, the value of $p inside the body of the function retains its dynamic type of xs:integer.

      • F's nonlocal variable bindings are also added to the variable values. (Note that the names of the nonlocal variables are by definition disjoint from the parameter names, so there can be no conflict.)

    2. The value returned by evaluating the function body is then converted to the declared return type of F by applying the coercion rules. The result is then the result of evaluating FC.

      As with argument values, the value returned by a function retains its dynamic type, which may be a subtype of the declared return type of F. For example, a function that has a declared return type of xs:decimal may in fact return a value of dynamic type xs:integer.

    Example: Derived Types and Nonlocal Variable Bindings

    $incr is a nonlocal variable that is available within the function because its variable binding has been added to the variable values of the function.. Even though the parameter and return type of this function are both xs:decimal, the more specific type xs:integer is preserved in both cases.

    let $incr := 1,
        $f := function ($i as xs:decimal) as xs:decimal { $i + $incr }
    return $f(5)                      

     

    Example: Using the Context Item in an Anonymous Function

    The following example will raise a dynamic error [err:XPDY0002]:

    let $vat := function() { @vat + @price }
    return shop/article/$vat()

    Instead, the context item can be used as an argument to the anonymous function:

    let $vat := function($art) { $art/@vat + $art/@price }
    return shop/article/$vat(.)

    Or, the value can be referenced as a nonlocal variable binding:

    let $ctx := shop/article,
    $vat := function() { for $a in $ctx return $a/@vat + $a/@price }
    return $vat()
    
  7. If F's implementation is not an XQuery 4.0 expression (e.g., F is a built-in function or an external function, the implementation of the function is evaluated, and the result is converted to the declared return type, in the same way as for a static function call (see 4.4.1.1 Static Function Call Syntax).

    Errors may be raised in the same way.

4.4.2.2 Partial Function Application

[Definition: A static or dynamic function call is a partial function application if one or more arguments is an ArgumentPlaceholder.]

The result of a partial function application is a function item, whose arity is equal to the number of placeholders in the call.

The result is obtained as follows:

  1. The function F to be partially applied is determined in the same way as for a (static or dynamic) function call without placeholders, as described in the preceding sections. For this purpose an ArgumentPlaceholder contributes to the count of arguments.

  2. Arguments other than placeholders are evaluated, mapped to corresponding parameters in the function signature of F, and converted to the required type of the parameter, using the rules for static and dynamic function calls as appropriate. In the case of static function calls, this includes optional parameters for which no argument expression or placeholder is supplied in the call.

  3. The result of the partial function application is a new function, which is a partially applied function. [Definition: A partially applied function is a function created by partial function application.] [Definition: In a partial function application, a supplied parameter is any parameter other than one for which the ArgumentList includes a placeholder.] A partial function application need not have any supplied parameters. A partially applied function has the following properties (which are defined in Section 2.8.1 Functions DM31):

    • name: Absent.

    • parameter names: The parameter names of F, removing the names of supplied parameters. (So the function's arity is the arity of F minus the number of fixed positions.)

    • signature: The signature of F, removing the types of supplied parameters. An implementation which can determine a more specific signature (for example, through use of type analysis) is permitted to do so.

    • implementation: The implementation of F. If this is not an XQuery 4.0 expression then the new function's implementation is associated with a static context and a dynamic context in one of two ways: if F's implementation is already associated with contexts, then those are used; otherwise, SC and DC are used.

    • nonlocal variable bindings: The nonlocal variable bindings of F, plus, for each supplied parameter, a binding of the converted argument value to the corresponding parameter name.

    Example: Partial Application of an Anonymous Function

    In the following example, $f is an anonymous function, and $paf is a partially applied function created from $f.

    let $f := function ($seq, $delim) { fn:fold-left($seq, "", fn:concat(?, $delim, ?)) },
        $paf := $f(?, ".")
    return $paf(1 to 5)
    

    $paf is also an anonymous function. It has one parameter, named $delim, which is taken from the corresponding parameter in $f (the other parameter is fixed). The implementation of $paf is the implementation of $f, which is fn:fold-left($seq, "", fn:concat(?, $delim, ?)). This implementation is associated with the SC and DC of the original expression in $f. The nonlocal bindings associate the value "." with the parameter $delim.

     

    Example: Partial Application of a Built-In Function

    The following partial function application creates a function that computes the sum of squares of a sequence.

    let $sum-of-squares := fn:fold-right(?, 0, function($a, $b) { $a*$a + $b })
    return $sum-of-squares(1 to 3)

    $sum-of-squares is an anonymous function. It has one parameter, named $seq, which is taken from the corresponding parameter in fn:fold-right (the other two parameters are fixed). The implementation is the implementation of fn:fold-right, which is a built-in context-independent function. The nonlocal bindings contain the fixed bindings for the second and third parameters of fn:fold-right.

    Partial function application never returns a map or an array. If $F is a map or an array, then $F(?) is a partial function application that returns a function, but the function it returns is not a map nor an array.

    Example: Partial Application of a Map

    The following partial function application converts a map to an equivalent function that is not a map.

    let $a := map {"A": 1, "B": 2}(?)
    return $a("A")
4.4.2.3 Named Function References
[187]    NamedFunctionRef    ::=    EQName "#" IntegerLiteral /* xgc: reserved-function-names */
[243]    EQName    ::=    QName | URIQualifiedName

[Definition: A named function reference is an expression (written name#arity) which evaluates to a function item.]

The name and arity of the required function are known statically.

If the EQName is a lexical QName, it is expanded using the default function namespace in the static context.

The expanded QName and arity must correspond to a function definition present in the static context. More specifically, for a named function reference F#N, there must be a function definition in the statically known function definitions whose name matches F, and whose arity range includes N . Call this function definition FD.

If the function is context dependent, then the returned function is associated with the static context of the named function reference and the dynamic context in which the named function reference is evaluated.

Example: A Context-Dependent Named Function Reference

Consider:

let $f := <foo/>/fn:name#0 return <bar>/$f()

The function fn:name(), with no arguments, returns the name of the context node. The function item delivered by evaluating the expression fn:name#0 returns the name of the element that was the context node at the point where the function reference was evaluated (that is, the <foo> element). This expression therefore returns "foo", not "bar".

If the expanded QName and arity in a named function reference do not match the name and arity range of a function definition in the static context, a static error is raised [err:XPST0017].

The value of a NamedFunctionRef is a function item FI obtained from FD as follows:

  • The name of FI is the name of FD.

  • The parameter names of FI are the first A parameter names of FD, where A is the required arity.

  • The signature of FI is formed from the required types of the first A parameters of FD, and the function result type of FD.

  • The implementation of FI is the implementation of FD.

  • The nonlocal variable bindings of FI comprise bindings of the names of parameters of FD beyond the A'th parameter, to their respective default values. The evaluation of the expressions that define these default values occurs in the dynamic context of the named function reference.

Note:

Consider the built-in function fn:format-date which has an arity range of 2 to 5. The named function reference fn:format-date#3 returns a function item whose three parameters correspond to the first three parameters of fn:format-date; the remaining two arguments will take their default values. To obtain an arity-3 function that binds to arguments 1, 2, and 5 of fn:format-date, use the partial function application format-date(?, ?, place:?).

Furthermore, if the function returned by the evaluation of a NamedFunctionRef has an implementation-dependent implementation, then the implementation of this function is associated with the static context of this NamedFunctionRef expression and with the dynamic context in which the NamedFunctionRef is evaluated.

The following are examples of named function references:

  • fn:abs#1 references the fn:abs function which takes a single argument.

  • fn:concat#5 references the fn:concat function which takes 5 arguments.

  • local:myfunc#2 references a function named local:myfunc which takes 2 arguments.

Note:

Function items, as values in the data model, have a fixed arity, and a dynamic function call always supplies the arguments positionally. Although the base function referred to may be variadic, the result of evaluating the function reference is a function that has fixed arity. In effect, the result of evaluating my:func#3 is the same as the result of evaluating the inline function expression function($x, $y, $z){my:func($x, $y, $z)}, except that the returned function has a name (it retains the name my:func).

4.4.2.4 Inline Function Expressions
[188]    InlineFunctionExpr    ::=    Annotation* (("function" FunctionSignature) | ("->" FunctionSignature?)) FunctionBody
[27]    Annotation    ::=    "%" EQName ("(" Literal ("," Literal)* ")")?
[34]    FunctionSignature    ::=    "(" ParamList? ")" TypeDeclaration?
[37]    ParamList    ::=    Param ("," Param)*
[38]    Param    ::=    "$" EQName TypeDeclaration?

[Definition: An inline function expression creates an anonymous function defined directly in the inline function expression.] An inline function expression specifies the names and SequenceTypes of the parameters to the function, the SequenceType of the result, and the body of the function.

[Definition: An anonymous function is a function item with no name. Anonymous functions may be created, for example, by evaluating an inline function expression or by partial function application.]

Note:

A more concise notation is introduced for simple functions in XQuery 4.0 because it can improve the readability of code by reducing visual clutter. For example, a sort operation previously written as sort(//employee, (), function($emp as element(employee)) as xs:string { $emp/@dateOfBirth }) can now be written sort(//employee, (), ->{@dateOfBirth}).

The use of the notation ->{expr} mirrors the use of -> as an arrow operator.

The full inline function syntax allows the names and types of the function argument to be declared, along with the type of the result:

function($x as xs:integer, $y as xs:integer) as xs:integer {$x + $y}

The types can be omitted:

function($x, $y) {$x + $y}

For brevity, the keyword function can be replaced by the symbol ->:

->($x, $y) {$x + $y}

This avoids visual clutter when a function is used as an argument to another function:

fn:for-each-pair($A, $B, ->($a, $b) {$a + $b})

The common case where a function accepts a single argument of type item() can be further abbreviated to ->{EXPR}. This is equivalent to the expanded syntax function($x as item()} as item()* {$x -> {EXPR}}, where x is a system-allocated name that does not conflict with any user-defined variables. That is, it defines an anonymous arity-one function, accepting any single item as its argument value, and returns the result of evaluating the supplied expression with that item as the singleton focus. For example, the following function call returns the sequence (2, 3, 4, 5, 6).

fn:for-each(1 to 5, ->{.+1})

A zero-arity function can be written as, for example, ->(){current-date()}.

If a function parameter is declared using a name but no type, its default type is item()*. If the result type is omitted, its default result type is item()*.

The parameters of an inline function expression are considered to be variables whose scope is the function body. It is a static error [err:XQST0039] for an inline function expression to have more than one parameter with the same name.

An inline function expression may have annotations. XQuery 4.0 does not define annotations that apply to inline function expressions, in particular it is a static error [err:XQST0125] if an inline function expression is annotated as %public or %private. An implementation can define annotations, in its own namespace, to support functionality beyond the scope of this specification.

The static context for the function body is inherited from the location of the inline function expression, with the exception of the static type of the context item which is initially absentDM31.

The variables in scope for the function body include all variables representing the function parameters, as well as all variables that are in scope for the inline function expression.

Note:

Function parameter names can mask variables that would otherwise be in scope for the function body.

The result of an inline function expression is a single function with the following properties (as defined in Section 2.8.1 Functions DM31):

  • name: An absent name. Absent.

  • parameter names: The parameter names in the InlineFunctionExpr's ParamList.

  • signature: A FunctionTest constructed from the Annotations and SequenceTypes in the InlineFunctionExpr. An implementation which can determine a more specific signature (for example, through use of type analysis of the function's body) is permitted to do so.

  • implementation: The InlineFunctionExpr's FunctionBody.

  • nonlocal variable bindings: For each nonlocal variable, a binding of it to its value in the variable values component of the dynamic context of the InlineFunctionExpr.

The following are examples of some inline function expressions:

  • This example creates a function that takes no arguments and returns a sequence of the first 6 primes:

    function() as xs:integer+ { 2, 3, 5, 7, 11, 13 }
  • This example creates a function that takes two xs:double arguments and returns their product:

    function($a as xs:double, $b as xs:double) as xs:double { $a * $b }
  • This example creates a function that prepends "$" to a supplied value:

    ->{"$" || .}

    It is equivalent to the function concat("$", ?).

  • This example creates a function that returns the name attribute of a supplied element node:

    ->{@name}

    It is equivalent to the function function($x as item()) as item()* {$x ! @name}.

4.4.3 Coercion Rules

[Definition: The coercion rules are rules used to convert a supplied value to a required type, for example when converting an argument of a function call to the declared type of the function parameter. ] The required type is expressed as a sequence type. The effect of the coercion rules may be to accept the value as supplied, to convert it to a value that matches the required type, or to reject it with a type error.

This section defines how the coercion rules operate; the situations in which the rules apply are defined elsewhere, by reference to this section.

Note:

In previous versions of this specification, the coercion rules were referred to as the function conversion rules. The terminology has changed because the rules are not exclusively associated with functions or function calling.

The coercion rules are applied to a supplied value V and a required sequence type T as follows:

  • If T is a SequenceType whose ItemType is a generalized atomic type other than an enumeration type, (possibly with an occurrence indicator *, +, or ?), then the following conversions are applied, in order:

    TODO: coercion for enumeration types needs further work.

    1. Atomization is applied to the given value, resulting in a sequence of atomic values.

    2. Each item in the atomic sequence that is of type xs:untypedAtomic is cast to the expected atomic type. If the expected atomic type is an EnumerationType, the value is cast to xs:string . If the item is of type xs:untypedAtomic and the expected type is namespace-sensitive, a type error [err:XPTY0117] is raised.

    3. For each numeric item in the atomic sequence that can be promoted to the expected atomic type using numeric promotion as described in B.1 Type Promotion, the promotion is done.

      Note:

      Numeric promotion is performed only when the required type is xs:double or xs:float (perhaps with an occurrence indicator). It is not performed when the required type is derived from xs:double or xs:float.

    4. For each item of type xs:anyURI in the atomic sequence that can be promoted to the expected atomic type using URI promotion as described in B.1 Type Promotion, the promotion is done.

      Note:

      Promotion of xs:anyURI values is performed only when the required type is xs:string (perhaps with an occurrence indicator). It is not performed when the required type is derived from xs:string.

    5. If T is a sequence type whose item type is an atomic type D, where D is derived from some primitive type P, then any atomic value A in the atomic sequence is relabeled as an instance of D if it satisfies all the following conditions:

      1. A is an instance of P.

      2. A is not an instance of D.

      3. The datumDM40 of A is within the value space of D.

      Relabeling an atomic value changes the type annotation but not the datumDM40. For example, the xs:integer value 3 can be relabeled as an instance of xs:unsignedByte, because the datum is within the value space of xs:unsignedByte.

      Note:

      Relabeling is not the same as casting. For example, the xs:decimal value 10.1 can be cast to xs:integer, but it cannot be relabeled as xs:integer, because its datum not within the value space of xs:integer.

      Note:

      The effect of this rule is that if, for example, a function parameter is declared with an expected type of xs:positiveInteger, then a call that supplies the literal value 3 will succeed, whereas a call that supplies -3 will fail.

      Note:

      This differs from previous versions of this specification, where both these calls would fail.

      This change allows the arguments of existing functions to be defined with a more precise type. For example, the $position argument of array:get can be defined as xs:positiveInteger rather than xs:integer. To enable this to be done without breaking backwards compatibility in respect of error behavior, built-in functions in many cases define custom error codes to be raised where relabeling of argument values fails.

      Note:

      Numeric promotion and xs:anyURI promotion occur only when T is a primitive type (xs:double, xs:float, or xs:string). Relabeling occurs only when T is a derived type. Promotion and relabeling are therefore never combined.

  • If T is a RecordTest (possibly with an occurrence indicator *, +, or ?), then V must be a map or sequence of maps, and the values of any entries in these maps whose keys correspond to field declarations in the RecordTest are converted to the required type defined by that field declaration, by applying these rules recursively (but with XPath 1.0 compatibility mode treated as false).

    For example, if the required type is record(longitude as xs:double, latitude as xs:double) and the supplied value is map{"longitude": 0, "latitude":53.2}, then the map is converted to map{"longitude": 0.0e0, "latitude": 53.2e0}.

  • If the expected type is a TypedFunctionTest (possibly with an occurrence indicator *, +, or ?), function coercion is applied to each function in the given value.

    Note:

    Maps and arrays are functions, so function coercion applies to them as well.

  • If, after the above conversions, the resulting value does not match the expected type T according to the rules for SequenceType Matching, a type error is raised [err:XPTY0004].

4.4.4 Function Coercion

Function coercion is a transformation applied to function items during application of the coercion rules. [Definition: Function coercion wraps a function item in a new function whose signature is the same as the expected type. This effectively delays the checking of the argument and return types until the function is called.]

Given a function F, and an expected function type, function coercion proceeds as follows:

  1. If F has higher arity than the expected type, a type error is raised [err:XPTY0004]

  2. If F has lower arity than the expected type, then F is wrapped in a new function that declares and ignores the additional argument; the following steps are then applied to this new function.

    For example, if the expected type is function(node(), xs:boolean) as xs:string, and the supplied function is fn:name#1, then the supplied function is effectively replaced by function($n as node(), $b as xs:boolean) as xs:string {fn:name($n)}

    Note:

    This mechanism makes it easier to design versatile and extensible higher-order functions. For example, in previous versions of this specification, the second argument of the fn:filter function expected an argument of type function (item()) as xs:boolean. This has now been extended to function (item(), xs:integer) as xs:boolean, but existing code continues to work, because callback functions that are not interested in the value of the second argument simply ignore it.

    TODO: this change to fn:filter has not yet been made.

  3. Function coercion then returns a new function item with the following properties (as defined in Section 2.8.1 Functions DM31):

    • name: The name of F (if not absent).

    • parameter names: The parameter names of F.

    • signature: Annotations is set to the annotations of F. TypedFunctionTest is set to the expected type.

    • implementation: In effect, a FunctionBody that calls F, passing it the parameters of this new function, in order.

    • nonlocal variable bindings: An empty mapping.

If the result of invoking the new function would necessarily result in a type error, that error may be raised during function coercion. It is implementation dependent whether this happens or not.

These rules have the following consequences:

  • SequenceType matching of the function's arguments and result are delayed until that function is called.

  • The coercion rules rules applied to the function's arguments and result are defined by the SequenceType it has most recently been coerced to. Additional coercion rules could apply when the wrapped function is called.

  • If an implementation has static type information about a function, that can be used to type check the function's argument and return types during static analysis.

For instance, consider the following query:

declare function local:filter($s as item()*, $p as function(xs:string) as xs:boolean) as item()*
{
  $s[$p(.)]
};

let $f := function($a) { starts-with($a, "E") }
return
  local:filter(("Ethel", "Enid", "Gertrude"), $f)
      

The function $f has a static type of function(item()*) as item()*. When the local:filter() function is called, the following occurs to the function:

  1. The coercion rules result in applying function coercion to $f, wrapping $f in a new function ($p) with the signature function(xs:string) as xs:boolean.

  2. $p is matched against the SequenceType of function(xs:string) as xs:boolean, and succeeds.

  3. When $p is called inside the predicate, coercion and SequenceType matching rules are applied to the context item argument, resulting in an xs:string value or a type error.

  4. $f is called with the xs:string, which returns an xs:boolean.

  5. $p applies coercion rules to the result sequence from $f, which already matches its declared return type of xs:boolean.

  6. The xs:boolean is returned as the result of $p.

Note:

Although the semantics of function coercion are specified in terms of wrapping the functions, static typing will often be able to reduce the number of places where this is actually necessary.

Since maps and arrays are also functions in XQuery 4.0, function coercion applies to them as well. For instance, consider the following expression:

let $m := map {
  "Monday" : true(),
  "Wednesday" : true(),
  "Friday" : true(),
  "Saturday" : false(),
  "Sunday" : false()
},
$days := ("Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday")
return fn:filter($days,$m)
      

The map $m has a function signature of function(xs:anyAtomicType) as item()*. When the fn:filter() function is called, the following occurs to the map:

  1. The map $m is treated as function ($f), equivalent to map:get($m,?).

  2. The coercion rules result in applying function coercion to $f, wrapping $f in a new function ($p) with the signature function(item()) as xs:boolean.

  3. $p is matched against the SequenceType function(item()) as xs:boolean, and succeeds.

  4. When $p is called by fn:filter(), coercion and SequenceType matching rules are applied to the argument, resulting in an item() value ($a) or a type error.

  5. $f is called with $a, which returns an xs:boolean or the empty sequence.

  6. $p applies coercion rule and SequenceType matching to the result sequence from $f. When the result is an xs:boolean the SequenceType matching succeeds. When it is an empty sequence (such as when $m does not contain a key for "Tuesday"), SequenceType matching results in a type error [err:XPTY0004], since the expected type is xs:boolean and the actual type is an empty sequence.

Consider the following expression:

let $m := map {
   "Monday" : true(),
   "Tuesday" : false(),
   "Wednesday" : true(),
   "Thursday" : false(),
   "Friday" : true(),
   "Saturday" : false(),
   "Sunday" : false()
}
let $days := ("Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday")
return fn:filter($days,$m)
      

The result of the expression is the sequence ("Monday", "Wednesday", "Friday")

4.5 Postfix Expressions

[135]    PostfixExpr    ::=    PrimaryExpr (Predicate | PositionalArgumentList | Lookup)*
[142]    Predicate    ::=    "[" Expr "]"
[137]    PositionalArgumentList    ::=    "(" PositionalArguments? ")"
[138]    PositionalArguments    ::=    Argument ("," Argument)*
[157]    Argument    ::=    ExprSingle | ArgumentPlaceholder

[Definition: An expression followed by a predicate (that is, E1[E2]) is referred to as a filter expression: its effect is to return those items from the value of E1 that satisfy the predicate in E2.] Filter expressions are described in 4.5.1 Filter Expressions

An expression (other than a raw EQName) followed by an argument list in parentheses (that is, E1(E2, E3, ...)) is referred to as a dynamic function call. Its effect is to evaluate E1 to obtain a function, and then call that function, with E2, E3, ... as arguments. Dynamic function calls are described in 4.5.2 Dynamic Function Calls.

4.5.1 Filter Expressions

[135]    PostfixExpr    ::=    PrimaryExpr (Predicate | PositionalArgumentList | Lookup)*
[142]    Predicate    ::=    "[" Expr "]"

A filter expression consists of a base expression followed by a predicate, which is an expression written in square brackets. The result of the filter expression consists of the items returned by the base expression, filtered by applying the predicate to each item in turn. The ordering of the items returned by a filter expression is the same as their order in the result of the primary expression.

Note:

Where the expression before the square brackets is a ReverseStep or ForwardStep, the expression is technically not a filter expression but an AxisStep. There are minor differences in the semantics: see 4.6.3 Predicates within Steps

Here are some examples of filter expressions:

  • Given a sequence of products in a variable, return only those products whose price is greater than 100.

    $products[price gt 100]
  • List all the integers from 1 to 100 that are divisible by 5. (See 4.7.1 Sequence Concatenation for an explanation of the to operator.)

    (1 to 100)[. mod 5 eq 0]
  • The result of the following expression is the integer 25:

    (21 to 29)[5]
  • The following example returns the fifth through ninth items in the sequence bound to variable $orders.

    $orders[fn:position() = (5 to 9)]
  • The following example illustrates the use of a filter expression as a step in a path expression. It returns the last chapter or appendix within the book bound to variable $book:

    $book/(chapter | appendix)[fn:last()]

For each item in the input sequence, the predicate expression is evaluated using an inner focus, defined as follows: The context item is the item currently being tested against the predicate. The context size is the number of items in the input sequence. The context position is the position of the context item within the input sequence.

For each item in the input sequence, the result of the predicate expression is coerced to an xs:boolean value, called the predicate truth value, as described below. Those items for which the predicate truth value is true are retained, and those for which the predicate truth value is false are discarded.

The predicate truth value is derived by applying the following rules, in order:

  1. If the value of the predicate expression is a singleton atomic value of a numeric type or derived from a numeric type, the predicate truth value is true if the value of the predicate expression is equal (by the eq operator) to the context position, and is false otherwise. [Definition: A predicate whose predicate expression returns a numeric type is called a numeric predicate.]

    Note:

    In a region of a query where ordering mode is unordered, the result of a numeric predicate is implementation-dependent , as explained in 4.16 Ordered and Unordered Expressions.

  2. Otherwise, the predicate truth value is the effective boolean value of the predicate expression.

4.5.2 Dynamic Function Calls

[135]    PostfixExpr    ::=    PrimaryExpr (Predicate | PositionalArgumentList | Lookup)*
[136]    ArgumentList    ::=    "(" ((PositionalArguments ("," KeywordArguments)?) | KeywordArguments)? ")"
[138]    PositionalArguments    ::=    Argument ("," Argument)*
[157]    Argument    ::=    ExprSingle | ArgumentPlaceholder
[158]    ArgumentPlaceholder    ::=    "?"
[139]    KeywordArguments    ::=    KeywordArgument ("," KeywordArgument)*
[140]    KeywordArgument    ::=    EQName ":=" Argument

[Definition: A dynamic function call consists of a base expression that returns the function and a parenthesized list of zero or more arguments (argument expressions or ArgumentPlaceholders).]

A dynamic function call is evaluated as described in 4.4.2.1 Evaluating Dynamic Function Calls.

The following are examples of some dynamic function calls:

  • This example calls the function contained in $f, passing the arguments 2 and 3:

    $f(2, 3)
  • This example fetches the second item from sequence $f, treats it as a function and calls it, passing an xs:string argument:

    $f[2]("Hi there")
  • This example calls the function $f passing no arguments, and filters the result with a positional predicate:

    $f()[2]

Note:

Arguments in a dynamic function call are always supplied positionally.

4.6 Path Expressions

[122]    PathExpr    ::=    ("/" RelativePathExpr?)
| ("//" RelativePathExpr)
| RelativePathExpr
/* xgc: leading-lone-slash */
[123]    RelativePathExpr    ::=    StepExpr (("/" | "//") StepExpr)*

[Definition: A path expression can be used to locate nodes within trees. A path expression consists of a series of one or more steps, separated by "/" or "//", and optionally beginning with "/" or "//".] An initial "/" or "//" is an abbreviation for one or more initial steps that are implicitly added to the beginning of the path expression, as described below.

A path expression consisting of a single step is evaluated as described in 4.6.2 Steps.

A "/" at the beginning of a path expression is an abbreviation for the initial step (fn:root(self::node()) treat as document-node())/ (however, if the "/" is the entire path expression, the trailing "/" is omitted from the expansion.) The effect of this initial step is to begin the path at the root node of the tree that contains the context node. If the context item is not a node, a type error is raised [err:XPTY0020]. At evaluation time, if the root node of the context node is not a document node, a dynamic error is raised [err:XPDY0050].

A "//" at the beginning of a path expression is an abbreviation for the initial steps (fn:root(self::node()) treat as document-node())/descendant-or-self::node()/ (however, "//" by itself is not a valid path expression [err:XPST0003].) The effect of these initial steps is to establish an initial node sequence that contains the root of the tree in which the context node is found, plus all nodes descended from this root. This node sequence is used as the input to subsequent steps in the path expression. If the context item is not a node, a type error is raised [err:XPTY0020]. At evaluation time, if the root node of the context node is not a document node, a dynamic error is raised [err:XPDY0050].

Note:

The descendants of a node do not include attribute nodes.

A path expression that starts with "/" or "//" selects nodes starting from the root of the tree containing the context item; it is often referred to as an absolute path expression.

4.6.1 Relative Path Expressions

[123]    RelativePathExpr    ::=    StepExpr (("/" | "//") StepExpr)*

A relative path expression is a path expression that selects nodes within a tree by following a series of steps starting at the context node (which, unlike an absolute path expression, may be any node in a tree).

Each non-initial occurrence of "//" in a path expression is expanded as described in 4.6.5 Abbreviated Syntax, leaving a sequence of steps separated by "/". This sequence of steps is then evaluated from left to right. So a path such as E1/E2/E3/E4 is evaluated as ((E1/E2)/E3)/E4. The semantics of a path expression are thus defined by the semantics of the binary "/" operator, which is defined in 4.6.1.1 Path operator (/).

Note:

Although the semantics describe the evaluation of a path with more than two steps as proceeding from left to right, the "/" operator is in most cases associative, so evaluation from right to left usually delivers the same result. The cases where "/" is not associative arise when the functions fn:position() and fn:last() are used: A/B/position() delivers a sequence of integers from 1 to the size of (A/B), whereas A/(B/position()) restarts the counting at each B element.

The following example illustrates the use of relative path expressions.

  • child::div1/child::para

    Selects the para element children of the div1 element children of the context node; that is, the para element grandchildren of the context node that have div1 parents.

Note:

Since each step in a path provides context nodes for the following step, in effect, only the last step in a path is allowed to return a sequence of non-nodes.

Note:

The "/" character can be used either as a complete path expression or as the beginning of a longer path expression such as "/*". Also, "*" is both the multiply operator and a wildcard in path expressions. This can cause parsing difficulties when "/" appears on the left-hand side of "*". This is resolved using the leading-lone-slash constraint. For example, "/*" and "/ *" are valid path expressions containing wildcards, but "/*5" and "/ * 5" raise syntax errors. Parentheses must be used when "/" is used on the left-hand side of an operator, as in "(/) * 5". Similarly, "4 + / * 5" raises a syntax error, but "4 + (/) * 5" is a valid expression. The expression "4 + /" is also valid, because / does not occur on the left-hand side of the operator.

Similarly, in the expression / union /*, "union" is interpreted as an element name rather than an operator. For it to be parsed as an operator, the expression should be written (/) union /*.

4.6.1.1 Path operator (/)

The path operator "/" is used to build expressions for locating nodes within trees. Its left-hand side expression must return a sequence of nodes. The operator returns either a sequence of nodes, in which case it additionally performs document ordering and duplicate elimination, or a sequence of non-nodes.

Each operation E1/E2 is evaluated as follows: Expression E1 is evaluated, and if the result is not a (possibly empty) sequence S of nodes, a type error is raised [err:XPTY0019]. Each node in S then serves in turn to provide an inner focus (the node as the context item, its position in S as the context position, the length of S as the context size) for an evaluation of E2, as described in 2.2.2 Dynamic Context. The sequences resulting from all the evaluations of E2 are combined as follows:

  1. If every evaluation of E2 returns a (possibly empty) sequence of nodes, these sequences are combined, and duplicate nodes are eliminated based on node identity. If ordering mode is ordered, the resulting node sequence is returned in document order; otherwise it is returned in implementation-dependent order.

  2. If every evaluation of E2 returns a (possibly empty) sequence of non-nodes, these sequences are concatenated and returned. If ordering mode is ordered, the returned sequence preserves the orderings within and among the subsequences generated by the evaluations of E2 ; otherwise the order of the returned sequence is implementation-dependent.

  3. If the multiple evaluations of E2 return at least one node and at least one non-node, a type error is raised [err:XPTY0018].

Note:

The semantics of the path operator can also be defined using the simple map operator as follows (forming the union with an empty sequence ($R | ()) has the effect of eliminating duplicates and sorting nodes into document order):

E1/E2 ::= let $R := E1!E2
  return
    if (every $r in $R satisfies $r instance of node())
    then ($R|())
    else if (every $r in $R satisfies not($r instance of node()))
    then $R
    else error()

4.6.2 Steps

[124]    StepExpr    ::=    PostfixExpr | AxisStep
[125]    AxisStep    ::=    (ReverseStep | ForwardStep) PredicateList
[126]    ForwardStep    ::=    (ForwardAxis NodeTest) | AbbrevForwardStep
[129]    ReverseStep    ::=    (ReverseAxis NodeTest) | AbbrevReverseStep
[141]    PredicateList    ::=    Predicate*

[Definition: A step is a part of a path expression that generates a sequence of items and then filters the sequence by zero or more predicates. The value of the step consists of those items that satisfy the predicates, working from left to right. A step may be either an axis step or a postfix expression.] Postfix expressions are described in 4.5 Postfix Expressions.

[Definition: An axis step returns a sequence of nodes that are reachable from the context node via a specified axis. Such a step has two parts: an axis, which defines the "direction of movement" for the step, and a node test, which selects nodes based on their kind, name, and/or type annotation.] If the context item is a node, an axis step returns a sequence of zero or more nodes; otherwise, a type error is raised [err:XPTY0020]. If ordering mode is ordered, the resulting node sequence is returned in document order; otherwise it is returned in implementation-dependent order. An axis step may be either a forward step or a reverse step, followed by zero or more predicates.

In the abbreviated syntax for a step, the axis can be omitted and other shorthand notations can be used as described in 4.6.5 Abbreviated Syntax.

The unabbreviated syntax for an axis step consists of the axis name and node test separated by a double colon. The result of the step consists of the nodes reachable from the context node via the specified axis that have the node kind, name, and/or type annotation specified by the node test. For example, the step child::para selects the para element children of the context node: child is the name of the axis, and para is the name of the element nodes to be selected on this axis. The available axes are described in 4.6.2.1 Axes. The available node tests are described in 4.6.2.2 Node Tests. Examples of steps are provided in 4.6.4 Unabbreviated Syntax and 4.6.5 Abbreviated Syntax.

4.6.2.1 Axes
[127]    ForwardAxis    ::=    ("child" "::")
| ("descendant" "::")
| ("attribute" "::")
| ("self" "::")
| ("descendant-or-self" "::")
| ("following-sibling" "::")
| ("following" "::")
[130]    ReverseAxis    ::=    ("parent" "::")
| ("ancestor" "::")
| ("preceding-sibling" "::")
| ("preceding" "::")
| ("ancestor-or-self" "::")

XQuery supports the following axes:

  • The child axis contains the children of the context node, which are the nodes returned by the Section 5.3 children Accessor DM31.

    Note:

    Only document nodes and element nodes have children. If the context node is any other kind of node, or if the context node is an empty document or element node, then the child axis is an empty sequence. The children of a document node or element node may be element, processing instruction, comment, or text nodes. Attribute and document nodes can never appear as children.

  • the descendant axis is defined as the transitive closure of the child axis; it contains the descendants of the context node (the children, the children of the children, and so on)

  • the parent axis contains the sequence returned by the Section 5.11 parent Accessor DM31, which returns the parent of the context node, or an empty sequence if the context node has no parent

    Note:

    An attribute node may have an element node as its parent, even though the attribute node is not a child of the element node.

  • the ancestor axis is defined as the transitive closure of the parent axis; it contains the ancestors of the context node (the parent, the parent of the parent, and so on)

    Note:

    The ancestor axis includes the root node of the tree in which the context node is found, unless the context node is the root node.

  • the following-sibling axis contains the context node's following siblings, those children of the context node's parent that occur after the context node in document order; if the context node is an attribute node, the following-sibling axis is empty

  • the preceding-sibling axis contains the context node's preceding siblings, those children of the context node's parent that occur before the context node in document order; if the context node is an attribute node, the preceding-sibling axis is empty

  • the following axis contains all nodes that are descendants of the root of the tree in which the context node is found, are not descendants of the context node, and occur after the context node in document order

  • the preceding axis contains all nodes that are descendants of the root of the tree in which the context node is found, are not ancestors of the context node, and occur before the context node in document order

  • the attribute axis contains the attributes of the context node, which are the nodes returned by the Section 5.1 attributes Accessor DM31 ; the axis will be empty unless the context node is an element

  • the self axis contains just the context node itself

  • the descendant-or-self axis contains the context node and the descendants of the context node

  • the ancestor-or-self axis contains the context node and the ancestors of the context node; thus, the ancestor-or-self axis will always include the root node

Axes can be categorized as forward axes and reverse axes. An axis that only ever contains the context node or nodes that are after the context node in document order is a forward axis. An axis that only ever contains the context node or nodes that are before the context node in document order is a reverse axis.

The parent, ancestor, ancestor-or-self, preceding, and preceding-sibling axes are reverse axes; all other axes are forward axes. The ancestor, descendant, following, preceding and self axes partition a document (ignoring attribute nodes): they do not overlap and together they contain all the nodes in the document.

[Definition: Every axis has a principal node kind. If an axis can contain elements, then the principal node kind is element; otherwise, it is the kind of nodes that the axis can contain.] Thus:

  • For the attribute axis, the principal node kind is attribute.

  • For all other axes, the principal node kind is element.

4.6.2.2 Node Tests

[Definition: A node test is a condition on the name, kind (element, attribute, text, document, comment, or processing instruction), and/or type annotation of a node. A node test determines which nodes contained by an axis are selected by a step.]

[132]    NodeTest    ::=    KindTest | NameTest
[133]    NameTest    ::=    EQName | Wildcard
[134]    Wildcard    ::=    "*"
| (NCName ":*")
| ("*:" NCName)
| (BracedURILiteral "*")
/* ws: explicit */
[243]    EQName    ::=    QName | URIQualifiedName

[Definition: A node test that consists only of an EQName or a Wildcard is called a name test.] A name test that consists of an EQName is true if and only if the kind of the node is the principal node kind for the step axis and the expanded QName of the node is equal (as defined by the eq operator) to the expanded QName specified by the name test. For example, child::para selects the para element children of the context node; if the context node has no para children, it selects an empty set of nodes. attribute::abc:href selects the attribute of the context node with the QName abc:href; if the context node has no such attribute, it selects an empty set of nodes.

If the EQName is a lexical QName, it is resolved into an expanded QName using the statically known namespaces in the expression context. It is a static error [err:XPST0081] if the QName has a prefix that does not correspond to any statically known namespace. An unprefixed QName, when used as a name test on an axis whose principal node kind is element, has the namespace URI of the default element namespace in the expression context; otherwise, it has no namespace URI.

A name test is not satisfied by an element node whose name does not match the expanded QName of the name test, even if it is in a substitution group whose head is the named element.

A node test * is true for any node of the principal node kind of the step axis. For example, child::* will select all element children of the context node, and attribute::* will select all attributes of the context node.

A node test can have the form NCName:*. In this case, the prefix is expanded in the same way as with a lexical QName, using the statically known namespaces in the static context. If the prefix is not found in the statically known namespaces, a static error is raised [err:XPST0081]. The node test is true for any node of the principal node kind of the step axis whose expanded QName has the namespace URI to which the prefix is bound, regardless of the local part of the name.

A node test can contain a BracedURILiteral, e.g. Q{http://example.com/msg}* Such a node test is true for any node of the principal node kind of the step axis whose expanded QName has the namespace URI specified in the BracedURILiteral, regardless of the local part of the name.

A node test can also have the form *:NCName. In this case, the node test is true for any node of the principal node kind of the step axis whose local name matches the given NCName, regardless of its namespace or lack of a namespace.

[Definition: An alternative form of a node test called a kind test can select nodes based on their kind, name, and type annotation.] The syntax and semantics of a kind test are described in 3.4 Sequence Types and 3.5 Sequence Type Matching. When a kind test is used in a node test, only those nodes on the designated axis that match the kind test are selected. Shown below are several examples of kind tests that might be used in path expressions:

  • node() matches any node.

  • text() matches any text node.

  • comment() matches any comment node.

  • namespace-node() matches any namespace node.

  • element() matches any element node.

  • schema-element(person) matches any element node whose name is person (or is in the substitution group headed by person), and whose type annotation is the same as (or is derived from) the declared type of the person element in the in-scope element declarations.

  • element(person) matches any element node whose name is person, regardless of its type annotation.

  • element(person, surgeon) matches any non-nilled element node whose name is person, and whose type annotation is surgeon or is derived from surgeon.

  • element(*, surgeon) matches any non-nilled element node whose type annotation is surgeon (or is derived from surgeon), regardless of its name.

  • attribute() matches any attribute node.

  • attribute(price) matches any attribute whose name is price, regardless of its type annotation.

  • attribute(*, xs:decimal) matches any attribute whose type annotation is xs:decimal (or is derived from xs:decimal), regardless of its name.

  • document-node() matches any document node.

  • document-node(element(book)) matches any document node whose content consists of a single element node that satisfies the kind test element(book), interleaved with zero or more comments and processing instructions.

4.6.3 Predicates within Steps

[125]    AxisStep    ::=    (ReverseStep | ForwardStep) PredicateList
[141]    PredicateList    ::=    Predicate*
[142]    Predicate    ::=    "[" Expr "]"

A predicate within a Step has similar syntax and semantics to a predicate within a filter expression. The only difference is in the way the context position is set for evaluation of the predicate.

For the purpose of evaluating the context position within a predicate, the input sequence is considered to be sorted as follows: into document order if the predicate is in a forward-axis step, into reverse document order if the predicate is in a reverse-axis step, or in its original order if the predicate is not in a step.

Here are some examples of axis steps that contain predicates:

  • This example selects the second chapter element that is a child of the context node:

    child::chapter[2]
  • This example selects all the descendants of the context node that are elements named "toy" and whose color attribute has the value "red":

    descendant::toy[attribute::color = "red"]
  • This example selects all the employee children of the context node that have both a secretary child element and an assistant child element:

    child::employee[secretary][assistant]

Note:

When using predicates with a sequence of nodes selected using a reverse axis, it is important to remember that the context positions for such a sequence are assigned in reverse document order. For example, preceding::foo[1] returns the first qualifying foo element in reverse document order, because the predicate is part of an axis step using a reverse axis. By contrast, (preceding::foo)[1] returns the first qualifying foo element in document order, because the parentheses cause (preceding::foo) to be parsed as a primary expression in which context positions are assigned in document order. Similarly, ancestor::*[1] returns the nearest ancestor element, because the ancestor axis is a reverse axis, whereas (ancestor::*)[1] returns the root element (first ancestor in document order).

The fact that a reverse-axis step assigns context positions in reverse document order for the purpose of evaluating predicates does not alter the fact that the final result of the step (when in ordered mode) is always in document order.

4.6.4 Unabbreviated Syntax

This section provides a number of examples of path expressions in which the axis is explicitly specified in each step. The syntax used in these examples is called the unabbreviated syntax. In many common cases, it is possible to write path expressions more concisely using an abbreviated syntax, as explained in 4.6.5 Abbreviated Syntax.

  • child::para selects the para element children of the context node

  • child::* selects all element children of the context node

  • child::text() selects all text node children of the context node

  • child::node() selects all the children of the context node. Note that no attribute nodes are returned, because attributes are not children.

  • attribute::name selects the name attribute of the context node

  • attribute::* selects all the attributes of the context node

  • parent::node() selects the parent of the context node. If the context node is an attribute node, this expression returns the element node (if any) to which the attribute node is attached.

  • descendant::para selects the para element descendants of the context node

  • ancestor::div selects all div ancestors of the context node

  • ancestor-or-self::div selects the div ancestors of the context node and, if the context node is a div element, the context node as well

  • descendant-or-self::para selects the para element descendants of the context node and, if the context node is a para element, the context node as well

  • self::para selects the context node if it is a para element, and otherwise returns an empty sequence

  • child::chapter/descendant::para selects the para element descendants of the chapter element children of the context node

  • child::*/child::para selects all para grandchildren of the context node

  • / selects the root of the tree that contains the context node, but raises a dynamic error if this root is not a document node

  • /descendant::para selects all the para elements in the same document as the context node

  • /descendant::list/child::member selects all the member elements that have a list parent and that are in the same document as the context node

  • child::para[fn:position() = 1] selects the first para child of the context node

  • child::para[fn:position() = fn:last()] selects the last para child of the context node

  • child::para[fn:position() = fn:last()-1] selects the last but one para child of the context node

  • child::para[fn:position() > 1] selects all the para children of the context node other than the first para child of the context node

  • following-sibling::chapter[fn:position() = 1] selects the next chapter sibling of the context node

  • preceding-sibling::chapter[fn:position() = 1] selects the previous chapter sibling of the context node

  • /descendant::figure[fn:position() = 42] selects the forty-second figure element in the document containing the context node

  • /child::book/child::chapter[fn:position() = 5]/child::section[fn:position() = 2] selects the second section of the fifth chapter of the book whose parent is the document node that contains the context node

  • child::para[attribute::type eq "warning"] selects all para children of the context node that have a type attribute with value warning

  • child::para[attribute::type eq 'warning'][fn:position() = 5] selects the fifth para child of the context node that has a type attribute with value warning

  • child::para[fn:position() = 5][attribute::type eq "warning"] selects the fifth para child of the context node if that child has a type attribute with value warning

  • child::chapter[child::title = 'Introduction'] selects the chapter children of the context node that have one or more title children whose typed value is equal to the string Introduction

  • child::chapter[child::title] selects the chapter children of the context node that have one or more title children

  • child::*[self::chapter or self::appendix] selects the chapter and appendix children of the context node

  • child::*[self::chapter or self::appendix][fn:position() = fn:last()] selects the last chapter or appendix child of the context node

4.6.5 Abbreviated Syntax

[128]    AbbrevForwardStep    ::=    "@"? NodeTest
[131]    AbbrevReverseStep    ::=    ".."

The abbreviated syntax permits the following abbreviations:

  1. The attribute axis attribute:: can be abbreviated by @. For example, a path expression para[@type="warning"] is short for child::para[attribute::type="warning"] and so selects para children with a type attribute with value equal to warning.

  2. If the axis name is omitted from an axis step, the default axis is child, with two exceptions: (1) if the NodeTest in an axis step contains an AttributeTest or SchemaAttributeTest then the default axis is attribute; (2) if the NodeTest in an axis step is a NamespaceNodeTest then a static error is raised [err:XQST0134].

    Note:

    The namespace axis is deprecated as of XPath 2.0, but required in some languages that use XPath, including XSLT.

    For example, the path expression section/para is an abbreviation for child::section/child::para, and the path expression section/@id is an abbreviation for child::section/attribute::id. Similarly, section/attribute(id) is an abbreviation for child::section/attribute::attribute(id). Note that the latter expression contains both an axis specification and a node test.

  3. Each non-initial occurrence of // is effectively replaced by /descendant-or-self::node()/ during processing of a path expression. For example, div1//para is short for child::div1/descendant-or-self::node()/child::para and so will select all para descendants of div1 children.

    Note:

    The path expression //para[1] does not mean the same as the path expression /descendant::para[1]. The latter selects the first descendant para element; the former selects all descendant para elements that are the first para children of their respective parents.

  4. A step consisting of .. is short for parent::node(). For example, ../title is short for parent::node()/child::title and so will select the title children of the parent of the context node.

    Note:

    The expression ., known as a context item expression, is a primary expression, and is described in 4.3.4 Context Item Expression.

Here are some examples of path expressions that use the abbreviated syntax:

  • para selects the para element children of the context node

  • * selects all element children of the context node

  • text() selects all text node children of the context node

  • @name selects the name attribute of the context node

  • @* selects all the attributes of the context node

  • para[1] selects the first para child of the context node

  • para[fn:last()] selects the last para child of the context node

  • */para selects all para grandchildren of the context node

  • /book/chapter[5]/section[2] selects the second section of the fifth chapter of the book whose parent is the document node that contains the context node

  • chapter//para selects the para element descendants of the chapter element children of the context node

  • //para selects all the para descendants of the root document node and thus selects all para elements in the same document as the context node

  • //@version selects all the version attribute nodes that are in the same document as the context node

  • //list/member selects all the member elements in the same document as the context node that have a list parent

  • .//para selects the para element descendants of the context node

  • .. selects the parent of the context node

  • ../@lang selects the lang attribute of the parent of the context node

  • para[@type="warning"] selects all para children of the context node that have a type attribute with value warning

  • para[@type="warning"][5] selects the fifth para child of the context node that has a type attribute with value warning

  • para[5][@type="warning"] selects the fifth para child of the context node if that child has a type attribute with value warning

  • chapter[title="Introduction"] selects the chapter children of the context node that have one or more title children whose typed value is equal to the string Introduction

  • chapter[title] selects the chapter children of the context node that have one or more title children

  • employee[@secretary and @assistant] selects all the employee children of the context node that have both a secretary attribute and an assistant attribute

  • book/(chapter|appendix)/section selects every section element that has a parent that is either a chapter or an appendix element, that in turn is a child of a book element that is a child of the context node.

  • If E is any expression that returns a sequence of nodes, then the expression E/. returns the same nodes in document order, with duplicates eliminated based on node identity.

4.7 Sequence Expressions

XQuery 4.0 supports operators to construct, filter, and combine sequences of items. Sequences are never nested—for example, combining the values 1, (2, 3), and ( ) into a single sequence results in the sequence (1, 2, 3).

4.7.1 Sequence Concatenation

[44]    Expr    ::=    ExprSingle ("," ExprSingle)*

[Definition: One way to construct a sequence is by using the comma operator, which evaluates each of its operands and concatenates the resulting sequences, in order, into a single result sequence.] Empty parentheses can be used to denote an empty sequence.

A sequence may contain duplicate items, but a sequence is never an item in another sequence. When a new sequence is created by concatenating two or more input sequences, the new sequence contains all the items of the input sequences and its length is the sum of the lengths of the input sequences.

Note:

In places where the grammar calls for ExprSingle, such as the arguments of a function call, any expression that contains a top-level comma operator must be enclosed in parentheses.

Here are some examples of expressions that construct sequences:

  • The result of this expression is a sequence of five integers:

    (10, 1, 2, 3, 4)
  • This expression combines four sequences of length one, two, zero, and two, respectively, into a single sequence of length five. The result of this expression is the sequence 10, 1, 2, 3, 4.

    (10, (1, 2), (), (3, 4))
  • The result of this expression is a sequence containing all salary children of the context node followed by all bonus children.

    (salary, bonus)
  • Assuming that $price is bound to the value 10.50, the result of this expression is the sequence 10.50, 10.50.

    ($price, $price)

4.7.2 Range Expressions

[98]    RangeExpr    ::=    AdditiveExpr ( "to" AdditiveExpr )?

A RangeExpression can be used to construct a sequence of integers. Each of the operands is converted as though it was an argument of a function with the expected parameter type xs:integer?. If either operand is an empty sequence, or if the integer derived from the first operand is greater than the integer derived from the second operand, the result of the range expression is an empty sequence. If the two operands convert to the same integer, the result of the range expression is that integer. Otherwise, the result is a sequence containing the two integer operands and every integer between the two operands, in increasing order.

The following examples illustrate the semantics:

  • 1 to 4 returns the sequence 1, 2, 3, 4

  • 10 to 10 returns the singleton sequence 10

  • 10 to 1 returns the empty sequence

  • -13 to -10 returns the sequence -13, -12, -11, -10

More formally, a RangeExpression is evaluated as follows:

  1. Each of the operands of the to operator is converted as though it was an argument of a function with the expected parameter type xs:integer?.

  2. If either operand is an empty sequence, or if the integer derived from the first operand is greater than the integer derived from the second operand, the result of the range expression is an empty sequence.

  3. If the two operands convert to the same integer, the result of the range expression is that integer.

  4. Otherwise, the result is a sequence containing the two integer operands and every integer between the two operands, in increasing order.

The following examples illustrate the use of RangeExpressions .

This example uses a range expression as one operand in constructing a sequence. It evaluates to the sequence 10, 1, 2, 3, 4.

(10, 1 to 4)

This example selects the first four items from an input sequence:

$input[position() = 1 to 4]

This example returns the sequence (0, 0.1, 0.2, 0.3, 0.5):

$x = (1 to 5)!.*0.1

This example constructs a sequence of length one containing the single integer 10.

10 to 10

The result of this example is a sequence of length zero.

15 to 10

This example uses the fn:reverse function to construct a sequence of six integers in decreasing order. It evaluates to the sequence 15, 14, 13, 12, 11, 10.

fn:reverse(10 to 15)

4.7.3 Combining Node Sequences

[102]    UnionExpr    ::=    IntersectExceptExpr ( ("union" | "|") IntersectExceptExpr )*
[103]    IntersectExceptExpr    ::=    InstanceofExpr ( ("intersect" | "except") InstanceofExpr )*

XQuery 4.0 provides the following operators for combining sequences of nodes:

  • The union and | operators are equivalent. They take two node sequences as operands and return a sequence containing all the nodes that occur in either of the operands.

  • The intersect operator takes two node sequences as operands and returns a sequence containing all the nodes that occur in both operands.

  • The except operator takes two node sequences as operands and returns a sequence containing all the nodes that occur in the first operand but not in the second operand.

All these operators eliminate duplicate nodes from their result sequences based on node identity. If ordering mode is ordered, the resulting sequence is returned in document order; otherwise it is returned in implementation-dependent order.

If an operand of union, intersect, or except contains an item that is not a node, a type error is raised [err:XPTY0004].

If an IntersectExceptExpr contains more than two InstanceofExprs, they are grouped from left to right. With a UnionExpr, it makes no difference how operands are grouped, the results are the same.

Here are some examples of expressions that combine sequences. Assume the existence of three element nodes that we will refer to by symbolic names A, B, and C. Assume that ordering mode is ordered. Assume that the variables $seq1, $seq2 and $seq3 are bound to the following sequences of these nodes:

  • $seq1 is bound to (A, B)

  • $seq2 is bound to (A, B)

  • $seq3 is bound to (B, C)

Then:

  • $seq1 union $seq2 evaluates to the sequence (A, B).

  • $seq2 union $seq3 evaluates to the sequence (A, B, C).

  • $seq1 intersect $seq2 evaluates to the sequence (A, B).

  • $seq2 intersect $seq3 evaluates to the sequence containing B only.

  • $seq1 except $seq2 evaluates to the empty sequence.

  • $seq2 except $seq3 evaluates to the sequence containing A only.

In addition to the sequence operators described here, see Section 14 Functions and operators on sequences FO31 for functions defined on sequences.

4.8 Arithmetic Expressions

XQuery 4.0 provides arithmetic operators for addition, subtraction, multiplication, division, and modulus, in their usual binary and unary forms.

[99]    AdditiveExpr    ::=    MultiplicativeExpr ( ("+" | "-") MultiplicativeExpr )*
[100]    MultiplicativeExpr    ::=    OtherwiseExpr ( ("*" | "div" | "idiv" | "mod") OtherwiseExpr )*
[109]    UnaryExpr    ::=    ("-" | "+")* ValueExpr
[110]    ValueExpr    ::=    ValidateExpr | ExtensionExpr | SimpleMapExpr

A subtraction operator must be preceded by whitespace if it could otherwise be interpreted as part of the previous token. For example, a-b will be interpreted as a name, but a - b and a -b will be interpreted as arithmetic expressions. (See A.2.4 Whitespace Rules for further details on whitespace handling.)

If an AdditiveExpr contains more than two MultiplicativeExprs, they are grouped from left to right. So, for instance,

A - B + C - D

is equivalent to

((A - B) + C) - D

Similarly, the operands of a MultiplicativeExpr are grouped from left to right.

The first step in evaluating an arithmetic expression is to evaluate its operands. The order in which the operands are evaluated is implementation-dependent.

Each operand is evaluated by applying the following steps, in order:

  1. Atomization is applied to the operand. The result of this operation is called the atomized operand.

  2. If the atomized operand is an empty sequence, the result of the arithmetic expression is an empty sequence, and the implementation need not evaluate the other operand or apply the operator. However, an implementation may choose to evaluate the other operand in order to determine whether it raises an error.

  3. If the atomized operand is a sequence of length greater than one, a type error is raised [err:XPTY0004].

  4. If the atomized operand is of type xs:untypedAtomic, it is cast to xs:double. If the cast fails, a dynamic error is raised. [err:FORG0001]FO31

After evaluation of the operands, if the types of the operands are a valid combination for the given arithmetic operator, the operator is applied to the operands, resulting in an atomic value or a dynamic error (for example, an error might result from dividing by zero.) The combinations of atomic types that are accepted by the various arithmetic operators, and their respective result types, are listed in B.2 Operator Mapping together with the operator functions that define the semantics of the operator for each type combination, including the dynamic errors that can be raised by the operator. The definitions of the operator functions are found in [XQuery and XPath Functions and Operators 4.0].

If the types of the operands, after evaluation, are not a valid combination for the given operator, according to the rules in B.2 Operator Mapping, a type error is raised [err:XPTY0004].

XQuery 4.0 supports two division operators named div and idiv. Each of these operators accepts two operands of any numeric type. The semantics of div are defined in Section 4.2.5 op:numeric-integer-divide FO31. The semantics of idiv are defined in Section 4.2.4 op:numeric-divide FO31.

Here are some examples of arithmetic expressions:

Note:

Multiple consecutive unary arithmetic operators are permitted.

4.9 String Concatenation Expressions

[97]    StringConcatExpr    ::=    RangeExpr ( "||" RangeExpr )*

String concatenation expressions allow the string representations of values to be concatenated. In XQuery 4.0, $a || $b is equivalent to fn:concat($a, $b). The following expression evaluates to the string concatenate:

"con" || "cat" || "enate"

4.10 Comparison Expressions

Comparison expressions allow two values to be compared. XQuery 4.0 provides three kinds of comparison expressions, called value comparisons, general comparisons, and node comparisons.

[96]    ComparisonExpr    ::=    StringConcatExpr ( (ValueComp
| GeneralComp
| NodeComp) StringConcatExpr )?
[114]    ValueComp    ::=    "eq" | "ne" | "lt" | "le" | "gt" | "ge"
[113]    GeneralComp    ::=    "=" | "!=" | "<" | "<=" | ">" | ">="
[115]    NodeComp    ::=    "is" | "<<" | ">>"

4.10.1 Value Comparisons

The value comparison operators are eq, ne, lt, le, gt, and ge. Value comparisons are used for comparing single values.

The first step in evaluating a value comparison is to evaluate its operands. The order in which the operands are evaluated is implementation-dependent. Each operand is evaluated by applying the following steps, in order:

  1. Atomization is applied to each operand. The result of this operation is called the atomized operand.

  2. If an atomized operand is an empty sequence, the result of the value comparison is an empty sequence, and the implementation need not evaluate the other operand or apply the operator. However, an implementation may choose to evaluate the other operand in order to determine whether it raises an error.

  3. If an atomized operand is a sequence of length greater than one, a type error is raised [err:XPTY0004].

  4. If an atomized operand is of type xs:untypedAtomic, it is cast to xs:string.

    Note:

    The purpose of this rule is to make value comparisons transitive. Users should be aware that the general comparison operators have a different rule for casting of xs:untypedAtomic operands. Users should also be aware that transitivity of value comparisons may be compromised by loss of precision during type conversion (for example, two xs:integer values that differ slightly may both be considered equal to the same xs:float value because xs:float has less precision than xs:integer).

  5. If the two operands are instances of different primitive types (meaning the 19 primitive types defined in Section 3.2 Primitive datatypesXS2), then:

    1. If each operand is an instance of one of the types xs:string or xs:anyURI, then both operands are cast to type xs:string.

    2. If each operand is an instance of one of the types xs:decimal or xs:float, then both operands are cast to type xs:float.

    3. If each operand is an instance of one of the types xs:decimal, xs:float, or xs:double, then both operands are cast to type xs:double.

    4. Otherwise, a type error is raised [err:XPTY0004].

      Note:

      The primitive type of an xs:integer value for this purpose is xs:decimal.

  6. Finally, if the types of the operands are a valid combination for the given operator, the operator is applied to the operands.

The combinations of atomic types that are accepted by the various value comparison operators, and their respective result types, are listed in B.2 Operator Mapping together with the operator functions that define the semantics of the operator for each type combination. The definitions of the operator functions are found in [XQuery and XPath Functions and Operators 4.0].

Informally, if both atomized operands consist of exactly one atomic value, then the result of the comparison is true if the value of the first operand is (equal, not equal, less than, less than or equal, greater than, greater than or equal) to the value of the second operand; otherwise the result of the comparison is false.

If the types of the operands, after evaluation, are not a valid combination for the given operator, according to the rules in B.2 Operator Mapping, a type error is raised [err:XPTY0004].

Here are some examples of value comparisons:

  • The following comparison atomizes the node(s) that are returned by the expression $book/author. The comparison is true only if the result of atomization is the value "Kennedy" as an instance of xs:string or xs:untypedAtomic. If the result of atomization is an empty sequence, the result of the comparison is an empty sequence. If the result of atomization is a sequence containing more than one value, a type error is raised [err:XPTY0004].

    $book1/author eq "Kennedy"
  • The following comparison is true because atomization converts an array to its member sequence:

    [ "Kennedy" ] eq "Kennedy"
  • The following path expression contains a predicate that selects products whose weight is greater than 100. For any product that does not have a weight subelement, the value of the predicate is the empty sequence, and the product is not selected. This example assumes that weight is a validated element with a numeric type.

    //product[weight gt 100]
  • The following comparisons are true because, in each case, the two constructed nodes have the same value after atomization, even though they have different identities and/or names:

    &lt;a&gt;5&lt;/a&gt; eq &lt;a&gt;5&lt;/a&gt;
    &lt;a&gt;5&lt;/a&gt; eq &lt;b&gt;5&lt;/b&gt;
  • The following comparison is true if my:hatsize and my:shoesize are both user-defined types that are derived by restriction from a primitive numeric type:

    my:hatsize(5) eq my:shoesize(5)
  • The following comparison is true. The eq operator compares two QNames by performing codepoint-comparisons of their namespace URIs and their local names, ignoring their namespace prefixes.

    fn:QName("http://example.com/ns1", "this:color") eq fn:QName("http://example.com/ns1", "that:color")

4.10.2 General Comparisons

The general comparison operators are =, !=, <, <=, >, and >=. General comparisons are existentially quantified comparisons that may be applied to operand sequences of any length. The result of a general comparison that does not raise an error is always true or false.

A general comparison is evaluated by applying the following rules, in order:

  1. Atomization is applied to each operand. After atomization, each operand is a sequence of atomic values.

  2. The result of the comparison is true if and only if there is a pair of atomic values, one in the first operand sequence and the other in the second operand sequence, that have the required magnitude relationship. Otherwise the result of the comparison is false or an error. The magnitude relationship between two atomic values is determined by applying the following rules. If a cast operation called for by these rules is not successful, a dynamic error is raised. [err:FORG0001]FO31

    Note:

    The purpose of these rules is to preserve compatibility with XPath 1.0, in which (for example) x < 17 is a numeric comparison if x is an untyped value. Users should be aware that the value comparison operators have different rules for casting of xs:untypedAtomic operands.

    1. If both atomic values are instances of xs:untypedAtomic, then the values are cast to the type xs:string.

    2. If exactly one of the atomic values is an instance of xs:untypedAtomic, it is cast to a type depending on the other value's dynamic type T according to the following rules, in which V denotes the value to be cast:

      1. If T is a numeric type or is derived from a numeric type, then V is cast to xs:double.

      2. If T is xs:dayTimeDuration or is derived from xs:dayTimeDuration, then V is cast to xs:dayTimeDuration.

      3. If T is xs:yearMonthDuration or is derived from xs:yearMonthDuration, then V is cast to xs:yearMonthDuration.

      4. In all other cases, V is cast to the primitive base type of T.

      Note:

      The special treatment of the duration types is required to avoid errors that may arise when comparing the primitive type xs:duration with any duration type.

    3. After performing the conversions described above, the atomic values are compared using one of the value comparison operators eq, ne, lt, le, gt, or ge, depending on whether the general comparison operator was =, !=, <, <=, >, or >=. The values have the required magnitude relationship if and only if the result of this value comparison is true.

When evaluating a general comparison in which either operand is a sequence of items, an implementation may return true as soon as it finds an item in the first operand and an item in the second operand that have the required magnitude relationship. Similarly, a general comparison may raise a dynamic error as soon as it encounters an error in evaluating either operand, or in comparing a pair of items from the two operands. As a result of these rules, the result of a general comparison is not deterministic in the presence of errors.

Here are some examples of general comparisons:

  • The following comparison is true if the typed value of any author subelement of $book1 is "Kennedy" as an instance of xs:string or xs:untypedAtomic:

    $book1/author = "Kennedy"
  • The following comparison is true because atomization converts an array to its member sequence:

    [ "Obama", "Nixon", "Kennedy" ] = "Kennedy"
  • The following example contains three general comparisons. The value of the first two comparisons is true, and the value of the third comparison is false. This example illustrates the fact that general comparisons are not transitive.

    (1, 2) = (2, 3)
    (2, 3) = (3, 4)
    (1, 2) = (3, 4)
  • The following example contains two general comparisons, both of which are true. This example illustrates the fact that the = and != operators are not inverses of each other.

    (1, 2) = (2, 3)
    (1, 2) != (2, 3)
  • Suppose that $a, $b, and $c are bound to element nodes with type annotation xs:untypedAtomic, with string values "1", "2", and "2.0" respectively. Then ($a, $b) = ($c, 3.0) returns false, because $b and $c are compared as strings. However, ($a, $b) = ($c, 2.0) returns true, because $b and 2.0 are compared as numbers.

4.10.3 Node Comparisons

Node comparisons are used to compare two nodes, by their identity or by their document order. The result of a node comparison is defined by the following rules:

  1. The operands of a node comparison are evaluated in implementation-dependent order.

  2. If either operand is an empty sequence, the result of the comparison is an empty sequence, and the implementation need not evaluate the other operand or apply the operator. However, an implementation may choose to evaluate the other operand in order to determine whether it raises an error.

  3. Each operand must be either a single node or an empty sequence; otherwise a type error is raised [err:XPTY0004].

  4. A comparison with the is operator is true if the two operand nodes are the same node; otherwise it is false. See [XQuery and XPath Data Model (XDM) 3.1] for the definition of node identity.

  5. A comparison with the << operator returns true if the left operand node precedes the right operand node in document order; otherwise it returns false.

  6. A comparison with the >> operator returns true if the left operand node follows the right operand node in document order; otherwise it returns false.

Here are some examples of node comparisons:

  • The following comparison is true only if the left and right sides each evaluate to exactly the same single node:

    /books/book[isbn="1558604820"] is /books/book[call="QA76.9 C3845"]
  • The following comparison is false because each constructed node has its own identity:

    &lt;a&gt;5&lt;/a&gt; is &lt;a&gt;5&lt;/a&gt;
  • The following comparison is true only if the node identified by the left side occurs before the node identified by the right side in document order:

    /transactions/purchase[parcel="28-451"] &lt;&lt; /transactions/sale[parcel="33-870"]

4.11 Logical Expressions

A logical expression is either an and-expression or an or-expression. If a logical expression does not raise an error, its value is always one of the boolean values true or false.

[94]    OrExpr    ::=    AndExpr ( "or" AndExpr )*
[95]    AndExpr    ::=    ComparisonExpr ( "and" ComparisonExpr )*

The first step in evaluating a logical expression is to find the effective boolean value of each of its operands (see 2.5.3 Effective Boolean Value).

The value of an and-expression is determined by the effective boolean values (EBV's) of its operands, as shown in the following table:

AND: EBV2 = true EBV2 = false error in EBV2
EBV1 = true true false error
EBV1 = false false false either false or error
error in EBV1 error either false or error error

The value of an or-expression is determined by the effective boolean values (EBV's) of its operands, as shown in the following table:

OR: EBV2 = true EBV2 = false error in EBV2
EBV1 = true true true either true or error
EBV1 = false true false error
error in EBV1 either true or error error error

The order in which the operands of a logical expression are evaluated is implementation-dependent. The tables above are defined in such a way that an or-expression can return true if the first expression evaluated is true, and it can raise an error if evaluation of the first expression raises an error. Similarly, an and-expression can return false if the first expression evaluated is false, and it can raise an error if evaluation of the first expression raises an error. As a result of these rules, a logical expression is not deterministic in the presence of errors, as illustrated in the examples below.

Here are some examples of logical expressions:

In addition to and- and or-expressions, XQuery 4.0 provides a function named fn:not that takes a general sequence as parameter and returns a boolean value. The fn:not function is defined in [XQuery and XPath Functions and Operators 4.0]. The fn:not function reduces its parameter to an effective boolean value. It then returns true if the effective boolean value of its parameter is false, and false if the effective boolean value of its parameter is true. If an error is encountered in finding the effective boolean value of its operand, fn:not raises the same error.

4.12 Node Constructors

XQuery provides node constructors that can create XML nodes within a query.

[159]    NodeConstructor    ::=    DirectConstructor
| ComputedConstructor
[160]    DirectConstructor    ::=    DirElemConstructor
| DirCommentConstructor
| DirPIConstructor
[161]    DirElemConstructor    ::=    "<" QName DirAttributeList ("/>" | (">" DirElemContent* "</" QName S? ">")) /* ws: explicit */
[166]    DirElemContent    ::=    DirectConstructor
| CDataSection
| CommonContent
| ElementContentChar
[253]    ElementContentChar    ::=    (Char - [{}<&])
[167]    CommonContent    ::=    PredefinedEntityRef | CharRef | "{{" | "}}" | EnclosedExpr
[172]    CDataSection    ::=    "<![CDATA[" CDataSectionContents "]]>" /* ws: explicit */
[173]    CDataSectionContents    ::=    (Char* - (Char* ']]>' Char*)) /* ws: explicit */
[162]    DirAttributeList    ::=    (S (QName S? "=" S? DirAttributeValue)?)* /* ws: explicit */
[163]    DirAttributeValue    ::=    ('"' (EscapeQuot | QuotAttrValueContent)* '"')
| ("'" (EscapeApos | AposAttrValueContent)* "'")
/* ws: explicit */
[164]    QuotAttrValueContent    ::=    QuotAttrContentChar
| CommonContent
[165]    AposAttrValueContent    ::=    AposAttrContentChar
| CommonContent
[254]    QuotAttrContentChar    ::=    (Char - ["{}<&])
[255]    AposAttrContentChar    ::=    (Char - ['{}<&])
[251]    EscapeQuot    ::=    '""'
[252]    EscapeApos    ::=    "''"
[40]    EnclosedExpr    ::=    "{" Expr? "}"

Constructors are provided for element, attribute, document, text, comment, and processing instruction nodes. Two kinds of constructors are provided: direct constructors, which use an XML-like notation that can incorporate enclosed expressions, and computed constructors, which use a notation based on enclosed expressions.

The rest of this section contains a conceptual description of the semantics of various kinds of constructor expressions. An XQuery implementation is free to use any implementation technique that produces the same result as the processing steps described here.

4.12.1 Direct Element Constructors

An element constructor creates an element node. [Definition: A direct element constructor is a form of element constructor in which the name of the constructed element is a constant.] Direct element constructors are based on standard XML notation. For example, the following expression is a direct element constructor that creates a book element containing an attribute and some nested elements:

<book isbn="isbn-0060229357">
    <title>Harold and the Purple Crayon</title>
    <author>
        <first>Crockett</first>
        <last>Johnson</last>
    </author>
</book>

If the element name in a direct element constructor has a namespace prefix, the namespace prefix is resolved to a namespace URI using the statically known namespaces. If the element name has no namespace prefix, it is implicitly qualified by the namespace bound to the zero-length prefix in the statically known namespaces: if there is no such binding, then the expanded name of the element will be in no namespace.

Note:

Both the statically known namespaces and the default element namespace may be affected by namespace declaration attributes found inside the element constructor.

The namespace prefix of the element name is retained after expansion of the lexical QName, as described in [XQuery and XPath Data Model (XDM) 3.1]. The resulting expanded QName becomes the node-name property of the constructed element node.

In a direct element constructor, the name used in the end tag must exactly match the name used in the corresponding start tag, including its prefix or absence of a prefix [err:XQST0118].

In a direct element constructor, curly braces { } delimit enclosed expressions, distinguishing them from literal text. Enclosed expressions are evaluated and replaced by their value, as illustrated by the following example:

<example>
   <p> Here is a query. </p>
   <eg> $b/title </eg>
   <p> Here is the result of the query. </p>
   <eg>{ $b/title }</eg>
</example>

The above query might generate the following result (whitespace has been added for readability to this result and other result examples in this document):

<example>
  <p> Here is a query. </p>
  <eg> $b/title </eg>
  <p> Here is the result of the query. </p>
  <eg><title>Harold and the Purple Crayon</title></eg>
</example>

Since XQuery uses curly braces to denote enclosed expressions, some convention is needed to denote a curly brace used as an ordinary character. For this purpose, a pair of identical curly brace characters within the content of an element or attribute are interpreted by XQuery as a single curly brace character (that is, the pair "{{" represents the character "{" and the pair "}}" represents the character "}".) Alternatively, the character references &#x7b; and &#x7d; can be used to denote curly brace characters. A single left curly brace ("{") is interpreted as the beginning delimiter for an enclosed expression. A single right curly brace ("}") without a matching left curly brace is treated as a static error [err:XPST0003].

The result of an element constructor is a new element node, with its own node identity. All the attribute and descendant nodes of the new element node are also new nodes with their own identities, even if they are copies of existing nodes.

4.12.1.1 Attributes

The start tag of a direct element constructor may contain one or more attributes. As in XML, each attribute is specified by a name and a value. In a direct element constructor, the name of each attribute is specified by a constant lexical QName, and the value of the attribute is specified by a string of characters enclosed in single or double quotes. As in the main content of the element constructor, an attribute value may contain enclosed expressions, which are evaluated and replaced by their value during processing of the element constructor.

Each attribute in a direct element constructor creates a new attribute node, with its own node identity, whose parent is the constructed element node. However, note that namespace declaration attributes (see 4.12.1.2 Namespace Declaration Attributes) do not create attribute nodes.

If an attribute name has a namespace prefix, the prefix is resolved to a namespace URI using the statically known namespaces. If the attribute name has no namespace prefix, the attribute is in no namespace. Note that the statically known namespaces used in resolving an attribute name may be affected by namespace declaration attributes that are found inside the same element constructor. The namespace prefix of the attribute name is retained after expansion of the lexical QName, as described in [XQuery and XPath Data Model (XDM) 3.1]. The resulting expanded QName becomes the node-name property of the constructed attribute node.

If the attributes in a direct element constructor do not have distinct expanded QNames as their respective node-name properties, a static error is raised [err:XQST0040].

Conceptually, an attribute (other than a namespace declaration attribute) in a direct element constructor is processed by the following steps:

  1. Each consecutive sequence of literal characters in the attribute content is processed as a string literal containing those characters, with the following exceptions:

    1. Each occurrence of two consecutive { characters is replaced by a single { character.

    2. Each occurrence of two consecutive } characters is replaced by a single } character.

    3. Each occurrence of EscapeQuot is replaced by a single " character.

    4. Each occurrence of EscapeApos is replaced by a single ' character.

    Attribute value normalization is then applied to normalize whitespace and expand character references and predefined entity references. The rules for attribute value normalization are the rules from Section 3.3.3 of [XML 1.0] or Section 3.3.3 of [XML 1.1] (it is implementation-defined which version is used). The rules are applied as though the type of the attribute were CDATA (leading and trailing whitespace characters are not stripped.)

  2. Each enclosed expression is converted to a string as follows:

    1. Atomization is applied to the value of the enclosed expression, converting it to a sequence of atomic values.

    2. If the result of atomization is an empty sequence, the result is the zero-length string. Otherwise, each atomic value in the atomized sequence is cast into a string.

    3. The individual strings resulting from the previous step are merged into a single string by concatenating them with a single space character between each pair.

  3. Adjacent strings resulting from the above steps are concatenated with no intervening blanks. The resulting string becomes the string-value property of the attribute node. The attribute node is given a type annotation of xs:untypedAtomic (this type annotation may change if the parent element is validated). The typed-value property of the attribute node is the same as its string-value, as an instance of xs:untypedAtomic.

  4. The parent property of the attribute node is set to the element node constructed by the direct element constructor that contains this attribute.

  5. If the attribute name is xml:id, then xml:id processing is performed as defined in [XML ID]. This ensures that the attribute has the type xs:ID and that its value is properly normalized. If an error is encountered during xml:id processing, an implementation may raise a dynamic error [err:XQDY0091].

  6. If the attribute name is xml:id, the is-id property of the resulting attribute node is set to true; otherwise the is-id property is set to false. The is-idrefs property of the attribute node is unconditionally set to false.

  • Example:

    &lt;shoe size="7"/&gt;

    The string value of the size attribute is "7".

  • Example:

    &lt;shoe size="{7}"/&gt;

    The string value of the size attribute is "7".

  • Example:

    &lt;shoe size="{()}"/&gt;

    The string value of the size attribute is the zero-length string.

  • Example:

    &lt;chapter ref="[{1, 5 to 7, 9}]"/&gt;

    The string value of the ref attribute is "[1 5 6 7 9]".

  • Example:

    &lt;shoe size="As big as {$hat/@size}"/&gt;

    The string value of the size attribute is the string "As big as ", concatenated with the string value of the node denoted by the expression $hat/@size.

4.12.1.2 Namespace Declaration Attributes

The names of a constructed element and its attributes may be lexical QNames that include namespace prefixes. Namespace prefixes can be bound to namespaces in the Prolog or by namespace declaration attributes. It is a static error to use a namespace prefix that has not been bound to a namespace [err:XPST0081].

[Definition: A namespace declaration attribute is used inside a direct element constructor. Its purpose is to bind a namespace prefix (including the zero-length prefix) for the constructed element node, including its attributes.] Syntactically, a namespace declaration attribute has the form of an attribute with namespace prefix xmlns, or with name xmlns and no namespace prefix. All the namespace declaration attributes of a given element must have distinct names [err:XQST0071]. Each namespace declaration attribute is processed as follows:

  • The value of the namespace declaration attribute (a DirAttributeValue) is processed as follows. If the DirAttributeValue contains an EnclosedExpr, a static error is raised [err:XQST0022]. Otherwise, it is processed as described in rule 1 of 4.12.1.1 Attributes. An implementation may raise a static error [err:XQST0046] if the resulting value is of nonzero length and is neither an absolute URI nor a relative URI. The resulting value is used as the namespace URI in the following rules.

  • If the prefix of the attribute name is xmlns, then the local part of the attribute name is interpreted as a namespace prefix. This prefix and the namespace URI are added to the statically known namespaces of the constructor expression (overriding any existing binding of the given prefix), and are also added as a namespace binding to the in-scope namespaces of the constructed element. If the namespace URI is a zero-length string and the implementation supports [XML Names 1.1], any existing namespace binding for the given prefix is removed from the in-scope namespaces of the constructed element and from the statically known namespaces of the constructor expression. If the namespace URI is a zero-length string and the implementation does not support [XML Names 1.1], a static error is raised [err:XQST0085]. It is implementation-defined whether an implementation supports [XML Names] or [XML Names 1.1].

  • If the name of the namespace declaration attribute is xmlns with no prefix, then a binding of the zero-length prefix to the namespace URI is added to the statically known namespaces of the constructor expression (overriding any existing binding of the zero-length prefix), and is also added (with no prefix) to the in-scope namespaces of the constructed element (overriding any existing namespace binding with no prefix). If the namespace URI is a zero-length string then any no-prefix namespace binding is removed from the in-scope namespaces of the constructed element.

    For backwards compatibility reasons, if the query prolog does not contain an explicit default type namespace declaration, then the default element namespace and default type namespace of the constructor expression are set to absentDM31.

    Note:

    In earlier versions of XQuery, given the expression <output xmlns="">{$x/input}</output>, both the unprefixed names output and input were interpreted as no-namespace names. Furthermore, the xmlns="" declaration would affect the interpretation of any unprefixed type names (though in practice, unprefixed type names were rarely used.) This behavior is retained in XQuery 4.0 for compatibility reasons. However, the behavior can be changed by adding a declaration such as declare default type namespace "http://www.w3.org/2001/XMLSchema" to the query prolog. If a default type namespace is declared, then the attribute xmlns="" only affects the output namespace, not the input namespace; it also has no effect on unprefixed type names.

    The same applies to a default namespace declaration such as xmlns="http://www.w3.org/1999/xhtml/. If a default type namespace is declared, the default namespace declaration only affects names used in element constructors, it no longer affects the interpretation of names in path expressions. This removes a usability problem that otherwise arises when the input is no-namespace XML and the output is XHTML.

  • It is a static error [err:XQST0070] if a namespace declaration attribute attempts to do any of the following:

    • Bind the prefix xml to some namespace URI other than http://www.w3.org/XML/1998/namespace.

    • Bind a prefix other than xml to the namespace URI http://www.w3.org/XML/1998/namespace.

    • Bind the prefix xmlns to any namespace URI.

    • Bind a prefix to the namespace URI http://www.w3.org/2000/xmlns/.

A namespace declaration attribute does not cause an attribute node to be created.

The following examples illustrate namespace declaration attributes:

  • In this element constructor, a namespace declaration attribute is used to set the default element namespace and default type namespace to http://example.org/animals:

    <cat xmlns = "http://example.org/animals">
      <breed>Persian</breed>
    </cat>
  • In this element constructor, namespace declaration attributes are used to bind the namespace prefixes metric and english:

    <box xmlns:metric = "http://example.org/metric/units"
         xmlns:english = "http://example.org/english/units">
      <height> <metric:meters>3</metric:meters> </height>
      <width> <english:feet>6</english:feet> </width>
      <depth> <english:inches>18</english:inches> </depth>
    </box>
4.12.1.3 Content

The part of a direct element constructor between the start tag and the end tag is called the content of the element constructor. This content may consist of text characters (parsed as ElementContentChar), nested direct constructors, CDataSections, character and predefined entity references, and enclosed expressions. In general, the value of an enclosed expression may be any sequence of nodes and/or atomic values. Enclosed expressions can be used in the content of an element constructor to compute both the content and the attributes of the constructed node.

Conceptually, the content of an element constructor is processed as follows:

  1. The content is evaluated to produce a sequence of nodes called the content sequence, as follows:

    1. If the boundary-space policy in the static context is strip, boundary whitespace is identified and deleted (see 4.12.1.4 Boundary Whitespace for the definition of boundary whitespace.)

    2. Predefined entity references and character references are expanded into their referenced strings, as described in 4.3.1 Literals. Characters inside a CDataSection, including special characters such as < and &, are treated as literal characters rather than as markup characters (except for the sequence ]]>, which terminates the CDataSection).

    3. Each consecutive sequence of literal characters evaluates to a single text node containing the characters.

    4. Each nested direct constructor is evaluated according to the rules in 4.12.1 Direct Element Constructors or 4.12.2 Other Direct Constructors, resulting in a new element, comment, or processing instruction node. Then:

      1. The parent property of the resulting node is then set to the newly constructed element node.

      2. The base-uri property of the resulting node, and of each of its descendants, is set to be the same as that of its new parent, unless it (the child node) has an xml:base attribute, in which case its base-uri property is set to the value of that attribute, resolved (if it is relative) against the base-uri property of its new parent node.

    5. Enclosed expressions are evaluated as follows:

      1. Each array returned by the enclosed expression is flattened by calling the function array:flatten() before the steps that follow.

      2. If an enclosed expression returns a function item, a type error is raised [err:XQTY0105].

      3. For each adjacent sequence of one or more atomic values returned by an enclosed expression, a new text node is constructed, containing the result of casting each atomic value to a string, with a single space character inserted between adjacent values.

        Note:

        The insertion of blank characters between adjacent values applies even if one or both of the values is a zero-length string.

      4. For each node returned by an enclosed expression, a new copy is made of the given node and all nodes that have the given node as an ancestor, collectively referred to as copied nodes. The properties of the copied nodes are as follows:

        1. Each copied node receives a new node identity.

        2. The parent, children, and attributes properties of the copied nodes are set so as to preserve their inter-node relationships. For the topmost node (the node directly returned by the enclosed expression), the parent property is set to the node constructed by this constructor.

        3. If construction mode in the static context is strip:

          1. If the copied node is an element node, its type annotation is set to xs:untyped. Its nilled, is-id, and is-idrefs properties are set to false.

          2. If the copied node is an attribute node, its type-name property is set to xs:untypedAtomic. Its is-idrefs property is set to false. Its is-id property is set to true if the qualified name of the attribute node is xml:id; otherwise it is set to false.

          3. The string-value of each copied element and attribute node remains unchanged, and its typed-value becomes equal to its string-value as an instance of xs:untypedAtomic.

            Note:

            Implementations that store only the typed value of a node are required at this point to convert the typed value to a string form.

          On the other hand, if construction mode in the static context is preserve, the type-name, nilled, string-value, typed-value, is-id, and is-idrefs properties of the copied nodes are preserved.

        4. The in-scope-namespaces property of a copied element node is determined by the following rules. In applying these rules, the default namespace or absence of a default namespace is treated like any other namespace binding:

          1. If copy-namespaces mode specifies preserve, all in-scope-namespaces of the original element are retained in the new copy. If copy-namespaces mode specifies no-preserve, the new copy retains only those in-scope namespaces of the original element that are used in the names of the element and its attributes.

          2. If copy-namespaces mode specifies inherit, the copied node inherits all the in-scope namespaces of the constructed node, augmented and overridden by the in-scope namespaces of the original element that were preserved by the preceding rule. If copy-namespaces mode specifies no-inherit, the copied node does not inherit any in-scope namespaces from the constructed node.

        5. An enclosed expression in the content of an element constructor may cause one or more existing nodes to be copied. Type error [err:XQTY0086] is raised in the following cases:

          1. An element node is copied, and the typed value of the element node or one of its attributes is namespace-sensitive, and construction mode is preserve, and copy-namespaces mode is no-preserve.

          2. An attribute node is copied but its parent element node is not copied, and the typed value of the copied attribute node is namespace-sensitive, and construction mode is preserve.

          Note:

          The rationale for error [err:XQTY0086] is as follows: It is not possible to preserve the type of a QName without also preserving the namespace binding that defines the prefix of the QName.

        6. When an element or processing instruction node is copied, its base-uri property is set to be the same as that of its new parent, with the following exception: if a copied element node has an xml:base attribute, its base-uri property is set to the value of that attribute, resolved (if it is relative) against the base-uri property of the new parent node.

        7. All other properties of the copied nodes are preserved.

  2. If the content sequence contains a document node, the document node is replaced in the content sequence by its children.

  3. Adjacent text nodes in the content sequence are merged into a single text node by concatenating their contents, with no intervening blanks. After concatenation, any text node whose content is a zero-length string is deleted from the content sequence.

  4. If the content sequence contains an attribute node or a namespace node following a node that is not an attribute node or a namespace node, a type error is raised [err:XQTY0024].

  5. The properties of the newly constructed element node are determined as follows:

    1. node-name is the expanded QName resulting from resolving the element name in the start tag, including its original namespace prefix (if any), as described in 4.12.1 Direct Element Constructors.

    2. parent is set to empty.

    3. attributes consist of all the attributes specified in the start tag as described in 4.12.1.1 Attributes, together with all the attribute nodes in the content sequence, in implementation-dependent order. Note that the parent property of each of these attribute nodes has been set to the newly constructed element node. If two or more attributes have the same node-name, a dynamic error is raised [err:XQDY0025]. If an attribute named xml:space has a value other than preserve or default, a dynamic error may be raised [err:XQDY0092].

    4. children consist of all the element, text, comment, and processing instruction nodes in the content sequence. Note that the parent property of each of these nodes has been set to the newly constructed element node.

    5. base-uri is set to the following value:

      1. If the constructed node has an attribute named xml:base, then the value of this attribute, resolved (if it is relative) against the Static Base URI, as described in 2.5.6 Resolving a Relative URI Reference.

      2. Otherwise, the Static Base URI.

    6. in-scope-namespaces consist of all the namespace bindings resulting from namespace declaration attributes as described in 4.12.1.2 Namespace Declaration Attributes, and possibly additional namespace bindings as described in 4.12.4 In-scope Namespaces of a Constructed Element.

    7. The nilled property is false.

    8. The string-value property is equal to the concatenated contents of the text-node descendants in document order. If there are no text-node descendants, the string-value property is a zero-length string.

    9. The typed-value property is equal to the string-value property, as an instance of xs:untypedAtomic.

    10. If construction mode in the static context is strip, the type-name property is xs:untyped. On the other hand, if construction mode is preserve, the type-name property is xs:anyType.

    11. The is-id and is-idrefs properties are set to false.

  • Example:

    &lt;a&gt;{1}&lt;/a&gt;

    The constructed element node has one child, a text node containing the value "1".

  • Example:

    &lt;a&gt;{1, 2, 3}&lt;/a&gt;

    The constructed element node has one child, a text node containing the value "1 2 3".

  • Example:

    &lt;c&gt;{1}{2}{3}&lt;/c&gt;

    The constructed element node has one child, a text node containing the value "123".

  • Example:

    &lt;b&gt;{1, "2", "3"}&lt;/b&gt;

    The constructed element node has one child, a text node containing the value "1 2 3".

  • Example:

    &lt;fact&gt;I saw 8 cats.&lt;/fact&gt;

    The constructed element node has one child, a text node containing the value "I saw 8 cats.".

  • Example:

    &lt;fact&gt;I saw {5 + 3} cats.&lt;/fact&gt;

    The constructed element node has one child, a text node containing the value "I saw 8 cats.".

  • Example:

    &lt;fact&gt;I saw &lt;howmany&gt;{5 + 3}&lt;/howmany&gt; cats.&lt;/fact&gt;

    The constructed element node has three children: a text node containing "I saw ", a child element node named howmany, and a text node containing " cats.". The child element node in turn has a single text node child containing the value "8".

4.12.1.4 Boundary Whitespace

In a direct element constructor, whitespace characters may appear in the content of the constructed element. In some cases, enclosed expressions and/or nested elements may be separated only by whitespace characters. For example, in the expression below, the end-tag </title> and the start-tag <author> are separated by a newline character and four space characters:

<book isbn="isbn-0060229357">
    <title>Harold and the Purple Crayon</title>
    <author>
        <first>Crockett</first>
        <last>Johnson</last>
    </author>
</book>

[Definition: Boundary whitespace is a sequence of consecutive whitespace characters within the content of a direct element constructor, that is delimited at each end either by the start or end of the content, or by a DirectConstructor, or by an EnclosedExpr. For this purpose, characters generated by character references such as &#x20; or by CDataSections are not considered to be whitespace characters.]

The boundary-space policy in the static context controls whether boundary whitespace is preserved by element constructors. If boundary-space policy is strip, boundary whitespace is not considered significant and is discarded. On the other hand, if boundary-space policy is preserve, boundary whitespace is considered significant and is preserved.

  • Example:

    &lt;cat&gt;
       &lt;breed&gt;{$b}&lt;/breed&gt;
       &lt;color&gt;{$c}&lt;/color&gt;
    &lt;/cat&gt;

    The constructed cat element node has two child element nodes named breed and color. Whitespace surrounding the child elements will be stripped away by the element constructor if boundary-space policy is strip.

  • Example:

    &lt;a&gt;  {"abc"}  &lt;/a&gt;

    If boundary-space policy is strip, this example is equivalent to <a>abc</a>. However, if boundary-space policy is preserve, this example is equivalent to <a>  abc  </a>.

  • Example:

    &lt;a&gt; z {"abc"}&lt;/a&gt;

    Since the whitespace surrounding the z is not boundary whitespace, it is always preserved. This example is equivalent to <a> z abc</a>.

  • Example:

    &lt;a&gt;&amp;#x20;{"abc"}&lt;/a&gt;

    This example is equivalent to <a> abc</a>, regardless of the boundary-space policy, because the space generated by the character reference is not treated as a whitespace character.

  • Example:

    &lt;a&gt;{"  "}&lt;/a&gt;

    This example constructs an element containing two space characters, regardless of the boundary-space policy, because whitespace inside an enclosed expression is never considered to be boundary whitespace.

  • Example:

    &lt;a&gt;{ [ "one", "little", "fish" ] }&lt;/a&gt;

    This example constructs an element containing the text one little fish, because the array is flattened, and the resulting sequence of atomic values is converted to a text node with a single blank between values.

Note:

Element constructors treat attributes named xml:space as ordinary attributes. An xml:space attribute does not affect the handling of whitespace by an element constructor.

4.12.2 Other Direct Constructors

XQuery allows an expression to generate a processing instruction node or a comment node. This can be accomplished by using a direct processing instruction constructor or a direct comment constructor. In each case, the syntax of the constructor expression is based on the syntax of a similar construct in XML.

[170]    DirPIConstructor    ::=    "<?" PITarget (S DirPIContents)? "?>" /* ws: explicit */
[171]    DirPIContents    ::=    (Char* - (Char* '?>' Char*)) /* ws: explicit */
[168]    DirCommentConstructor    ::=    "<!--" DirCommentContents "-->" /* ws: explicit */
[169]    DirCommentContents    ::=    ((Char - '-') | ('-' (Char - '-')))* /* ws: explicit */

A direct processing instruction constructor creates a processing instruction node whose target property is PITarget and whose content property is DirPIContents. The base-uri property of the node is empty. The parent property of the node is empty.

The PITarget of a processing instruction must not consist of the characters "XML" in any combination of upper and lower case, and must not contain a colon. The DirPIContents of a processing instruction must not contain the string "?>".

The following example illustrates a direct processing instruction constructor:

&lt;?format role="output" ?&gt;

A direct comment constructor creates a comment node whose content property is DirCommentContents. Its parent property is empty.

The DirCommentContents of a comment must not contain two consecutive hyphens or end with a hyphen. These rules are syntactically enforced by the grammar shown above.

The following example illustrates a direct comment constructor:

&lt;!-- Tags are ignored in the following section --&gt;

Note:

A direct comment constructor is different from a comment, since a direct comment constructor actually constructs a comment node, whereas a comment is simply used in documenting a query and is not evaluated.

4.12.3 Computed Constructors

[174]    ComputedConstructor    ::=    CompDocConstructor
| CompElemConstructor
| CompAttrConstructor
| CompNamespaceConstructor
| CompTextConstructor
| CompCommentConstructor
| CompPIConstructor

An alternative way to create nodes is by using a computed constructor. A computed constructor begins with a keyword that identifies the type of node to be created: element, attribute, document, text, processing-instruction, comment, or namespace.

For those kinds of nodes that have names (element, attribute, and processing instruction nodes), the keyword that specifies the node kind is followed by the name of the node to be created. This name may be specified either as an EQName or as an expression enclosed in braces. [Definition: When an expression is used to specify the name of a constructed node, that expression is called the name expression of the constructor.]

The following example illustrates the use of computed element and attribute constructors in a simple case where the names of the constructed nodes are constants. This example generates exactly the same result as the first example in 4.12.1 Direct Element Constructors:

element book {
   attribute isbn {"isbn-0060229357" },
   element title { "Harold and the Purple Crayon"},
   element author {
      element first { "Crockett" },
      element last {"Johnson" }
   }
}
4.12.3.1 Computed Element Constructors
[176]    CompElemConstructor    ::=    "element" (EQName | ("{" Expr "}")) EnclosedContentExpr
[243]    EQName    ::=    QName | URIQualifiedName
[177]    EnclosedContentExpr    ::=    EnclosedExpr
[40]    EnclosedExpr    ::=    "{" Expr? "}"

[Definition: A computed element constructor creates an element node, allowing both the name and the content of the node to be computed.]

If the keyword element is followed by an EQName, it is expanded to an expanded QName as follows: if the EQName has a BracedURILiteral it is expanded using the specified URI; if the EQName is a lexical QName with a namespace prefix it is expanded using the statically known namespaces; if the EQName is a lexical QName without a prefix it is implicitly qualified by the namespace URI that is bound to the zero-length prefix in the statically known namespaces; if there is no such binding, the expanded name will be in no namespace. . The resulting expanded QName is used as the node-name property of the constructed element node. If expansion of the QName is not successful, a static error is raised [err:XPST0081].

If the keyword element is followed by a name expression, the name expression is processed as follows:

  1. Atomization is applied to the value of the name expression. If the result of atomization is not a single atomic value of type xs:QName, xs:string, or xs:untypedAtomic, a type error is raised [err:XPTY0004].

  2. If the atomized value of the name expression is of type xs:QName, that expanded QName is used as the node-name property of the constructed element, retaining the prefix part of the QName.

  3. If the atomized value of the name expression is of type xs:string or xs:untypedAtomic, that value is converted to an expanded QName as follows:

    1. Leading and trailing whitespace is removed.

    2. If the value is an unprefixed NCName, it is treated as a local name in the default element namespace.

    3. If the value is a lexical QName with a prefix, that prefix is resolved to a namespace URI using the statically known namespaces.

    4. If the value is a URI-qualified name (Q{uri}local), it is converted to an expanded QName with the supplied namespace URI and local name, and with no prefix.

    Note:

    This was under-specified in XQuery 3.1.

    The resulting expanded QName is used as the node-name property of the constructed element, retaining the prefix part of the QName (or its absence). If conversion of the atomized name expression to an expanded QName is not successful, a dynamic error is raised [err:XQDY0074].

A dynamic error is raised [err:XQDY0096] if the node-name of the constructed element node has any of the following properties:

  • Its namespace prefix is xmlns.

  • Its namespace URI is http://www.w3.org/2000/xmlns/.

  • Its namespace prefix is xml and its namespace URI is not http://www.w3.org/XML/1998/namespace.

  • Its namespace prefix is other than xml and its namespace URI is http://www.w3.org/XML/1998/namespace.

The content expression of a computed element constructor (if present) is processed in exactly the same way as an enclosed expression in the content of a direct element constructor, as described in Step 1e of 4.12.1.3 Content. The result of processing the content expression is a sequence of nodes called the content sequence. If the content expression is absent, the content sequence is an empty sequence.

Processing of the computed element constructor proceeds as follows:

  1. If the content sequence contains a document node, the document node is replaced in the content sequence by its children.

  2. Adjacent text nodes in the content sequence are merged into a single text node by concatenating their contents, with no intervening blanks. After concatenation, any text node whose content is a zero-length string is deleted from the content sequence.

  3. If the content sequence contains an attribute node or a namespace node following a node that is not an attribute node or a namespace node, a type error is raised [err:XQTY0024].

  4. The properties of the newly constructed element node are determined as follows:

    1. node-name is the expanded QName resulting from processing the specified lexical QName or name expression, as described above.

    2. parent is empty.

    3. attributes consist of all the attribute nodes in the content sequence, in implementation-dependent order. Note that the parent property of each of these attribute nodes has been set to the newly constructed element node. If two or more attributes have the same node-name, a dynamic error is raised [err:XQDY0025]. If an attribute named xml:space has a value other than preserve or default, a dynamic error may be raised [err:XQDY0092].

    4. children consist of all the element, text, comment, and processing instruction nodes in the content sequence. Note that the parent property of each of these nodes has been set to the newly constructed element node.

    5. base-uri is set to the following value:

      1. If the constructed node has an attribute named xml:base, then the value of this attribute, resolved (if it is relative) against the Static Base URI, as described in 2.5.6 Resolving a Relative URI Reference.

      2. Otherwise, the Static Base URI.

    6. in-scope-namespaces are computed as described in 4.12.4 In-scope Namespaces of a Constructed Element.

    7. The nilled property is false.

    8. The string-value property is equal to the concatenated contents of the text-node descendants in document order.

    9. The typed-value property is equal to the string-value property, as an instance of xs:untypedAtomic.

    10. If construction mode in the static context is strip, the type-name property is xs:untyped. On the other hand, if construction mode is preserve, the type-name property is xs:anyType.

    11. The is-id and is-idrefs properties are set to false.

A computed element constructor might be used to make a modified copy of an existing element. For example, if the variable $e is bound to an element with numeric content, the following constructor might be used to create a new element with the same name and attributes as $e and with numeric content equal to twice the value of $e:

element {fn:node-name($e)}
   {$e/@*, 2 * fn:data($e)}

In this example, if $e is bound by the expression let $e := <length units="inches">{5}</length>, then the result of the example expression is the element <length units="inches">10</length>.

Note:

The static type of the expression fn:node-name($e) is xs:QName?, denoting zero or one QName. Therefore, if the Static Typing Feature is in effect, the above example raises a static type error, since the name expression in a computed element constructor is required to return exactly one string or QName. In order to avoid the static type error, the name expression fn:node-name($e) could be rewritten as fn:exactly-one(fn:node-name($e)). If the Static Typing Feature is not in effect, the example can be successfully evaluated as written, provided that $e is bound to exactly one element node with numeric content.

One important purpose of computed constructors is to allow the name of a node to be computed. We will illustrate this feature by an expression that translates the name of an element from one language to another. Suppose that the variable $dict is bound to a dictionary element containing a sequence of entry elements, each of which encodes translations for a specific word. Here is an example entry that encodes the German and Italian variants of the word "address":

<entry word="address">
   <variant xml:lang="de">Adresse</variant>
   <variant xml:lang="it">indirizzo</variant>
</entry>

Suppose further that the variable $e is bound to the following element:

<address>123 Roosevelt Ave. Flushing, NY 11368</address>

Then the following expression generates a new element in which the name of $e has been translated into Italian and the content of $e (including its attributes, if any) has been preserved. The first enclosed expression after the element keyword generates the name of the element, and the second enclosed expression generates the content and attributes:

  element
    {$dict/entry[@word=name($e)]/variant[@xml:lang="it"]}
    {$e/@*, $e/node()}

The result of this expression is as follows:

<indirizzo>123 Roosevelt Ave. Flushing, NY 11368</indirizzo>

Note:

As in the previous example, if the Static Typing Feature is in effect, the enclosed expression that computes the element name in the above computed element constructor must be wrapped in a call to the fn:exactly-one function in order to avoid a static type error.

Additional examples of computed element constructors can be found in I.3 Recursive Transformations.

4.12.3.2 Computed Attribute Constructors
[178]    CompAttrConstructor    ::=    "attribute" (EQName | ("{" Expr "}")) EnclosedExpr
[243]    EQName    ::=    QName | URIQualifiedName
[40]    EnclosedExpr    ::=    "{" Expr? "}"

A computed attribute constructor creates a new attribute node, with its own node identity.

Attributes have no default namespace. The rules that expand attribute names create an implementation-dependent prefix if an attribute name has a namespace URI but no prefix is provided.

If the keyword attribute is followed by an EQName, it is expanded to an expanded QName as follows:

The resulting expanded QName (including its prefix) is used as the node-name property of the constructed attribute node. If expansion of the QName is not successful, a static error is raised [err:XPST0081].

If the keyword attribute is followed by a name expression, the name expression is processed as follows:

  1. Atomization is applied to the result of the name expression. If the result of atomization is not a single atomic value of type xs:QName, xs:string, or xs:untypedAtomic, a type error is raised [err:XPTY0004].

  2. If the atomized value of the name expression is of type xs:QName:

    1. If the expanded QName returned by the atomized name expression has a namespace URI but has no prefix, it is given an implementation-dependent prefix.

    2. The resulting expanded QName (including its prefix) is used as the node-name property of the constructed attribute node.

  3. If the atomized value of the name expression is of type xs:string or xs:untypedAtomic, that value is converted to an expanded QName as follows:

    1. Leading and trailing whitespace is removed.

    2. If the value is an unprefixed NCName, it is treated as a local name in no namespace.

    3. If the value is a lexical QName with a prefix, that prefix is resolved to a namespace URI using the statically known namespaces.

    4. If the value is a URI-qualified name (Q{uri}local), it is converted to an expanded QName with the supplied namespace URI and local name, and with an implementation dependent prefix.

    Note:

    This was under-specified in XQuery 3.1.

    The resulting expanded QName (including its prefix) is used as the node-name property of the constructed attribute. If conversion of the atomized name expression to an expanded QName is not successful, a dynamic error is raised [err:XQDY0074].

A dynamic error is raised [err:XQDY0044] if the node-name of the constructed attribute node has any of the following properties:

  • Its namespace prefix is xmlns.

  • It has no namespace prefix and its local name is xmlns.

  • Its namespace URI is http://www.w3.org/2000/xmlns/.

  • Its namespace prefix is xml and its namespace URI is not http://www.w3.org/XML/1998/namespace.

  • Its namespace prefix is other than xml and its namespace URI is http://www.w3.org/XML/1998/namespace.

The content expression of a computed attribute constructor is processed as follows:

  1. Atomization is applied to the result of the content expression, converting it to a sequence of atomic values. (If the content expression is absent, the result of this step is an empty sequence.)

  2. If the result of atomization is an empty sequence, the value of the attribute is the zero-length string. Otherwise, each atomic value in the atomized sequence is cast into a string.

  3. The individual strings resulting from the previous step are merged into a single string by concatenating them with a single space character between each pair. The resulting string becomes the string-value property of the new attribute node. The type annotation (type-name property) of the new attribute node is xs:untypedAtomic. The typed-value property of the attribute node is the same as its string-value, as an instance of xs:untypedAtomic.

  4. The parent property of the attribute node is set to empty.

  5. If the attribute name is xml:id, then xml:id processing is performed as defined in [XML ID]. This ensures that the attribute node has the type xs:ID and that its value is properly normalized. If an error is encountered during xml:id processing, an implementation may raise a dynamic error [err:XQDY0091].

  6. If the attribute name is xml:id, the is-id property of the resulting attribute node is set to true; otherwise the is-id property is set to false. The is-idrefs property of the attribute node is unconditionally set to false.

  7. If the attribute name is xml:space and the attribute value is other than preserve or default, a dynamic error may be raised [err:XQDY0092].

  • Example:

    attribute size {4 + 3}

    The string value of the size attribute is "7" and its type is xs:untypedAtomic.

  • Example:

    attribute
       { if ($sex = "M") then "husband" else "wife" }
       { &lt;a&gt;Hello&lt;/a&gt;, 1 to 3, &lt;b&gt;Goodbye&lt;/b&gt; }
    

    The name of the constructed attribute is either husband or wife. Its string value is "Hello 1 2 3 Goodbye".

4.12.3.3 Document Node Constructors
[175]    CompDocConstructor    ::=    "document" EnclosedExpr
[40]    EnclosedExpr    ::=    "{" Expr? "}"

All document node constructors are computed constructors. The result of a document node constructor is a new document node, with its own node identity.

A document node constructor is useful when the result of a query is to be a document in its own right. The following example illustrates a query that returns an XML document containing a root element named author-list:

document
  {
      &lt;author-list&gt;
         {fn:doc("bib.xml")/bib/book/author}
      &lt;/author-list&gt;
  }

The content expression of a document node constructor is processed in exactly the same way as an enclosed expression in the content of a direct element constructor, as described in Step 1e of 4.12.1.3 Content. The result of processing the content expression is a sequence of nodes called the content sequence. Processing of the document node constructor then proceeds as follows:

  1. If the content sequence contains a document node, the document node is replaced in the content sequence by its children.

  2. Adjacent text nodes in the content sequence are merged into a single text node by concatenating their contents, with no intervening blanks. After concatenation, any text node whose content is a zero-length string is deleted from the content sequence.

  3. If the content sequence contains an attribute node, a type error is raised [err:XPTY0004].

  4. If the content sequence contains a namespace node, a type error is raised [err:XPTY0004].

  5. The properties of the newly constructed document node are determined as follows:

    1. base-uri is set to the Static Base URI.

    2. children consist of all the element, text, comment, and processing instruction nodes in the content sequence. Note that the parent property of each of these nodes has been set to the newly constructed document node.

    3. The unparsed-entities and document-uri properties are empty.

    4. The string-value property is equal to the concatenated contents of the text-node descendants in document order.

    5. The typed-value property is equal to the string-value property, as an instance of xs:untypedAtomic.

No validation is performed on the constructed document node. The [XML 1.0] rules that govern the structure of an XML document (for example, the document node must have exactly one child that is an element node) are not enforced by the XQuery document node constructor.

4.12.3.4 Text Node Constructors
[183]    CompTextConstructor    ::=    "text" EnclosedExpr
[40]    EnclosedExpr    ::=    "{" Expr? "}"

All text node constructors are computed constructors. The result of a text node constructor is a new text node, with its own node identity.

The content expression of a text node constructor is processed as follows:

  1. Atomization is applied to the value of the content expression, converting it to a sequence of atomic values.

  2. If the result of atomization is an empty sequence, no text node is constructed. Otherwise, each atomic value in the atomized sequence is cast into a string.

  3. The individual strings resulting from the previous step are merged into a single string by concatenating them with a single space character between each pair. The resulting string becomes the content property of the constructed text node.

The parent property of the constructed text node is set to empty.

Note:

It is possible for a text node constructor to construct a text node containing a zero-length string. However, if used in the content of a constructed element or document node, such a text node will be deleted or merged with another text node.

The following example illustrates a text node constructor:

text {"Hello"}
4.12.3.5 Computed Processing Instruction Constructors
[185]    CompPIConstructor    ::=    "processing-instruction" (NCName | ("{" Expr "}")) EnclosedExpr
[40]    EnclosedExpr    ::=    "{" Expr? "}"

A computed processing instruction constructor (CompPIConstructor) constructs a new processing instruction node with its own node identity.

If the keyword processing-instruction is followed by an NCName, that NCName is used as the target property of the constructed node. If the keyword processing-instruction is followed by a name expression, the name expression is processed as follows:

  1. Atomization is applied to the value of the name expression. If the result of atomization is not a single atomic value of type xs:NCName, xs:string, or xs:untypedAtomic, a type error is raised [err:XPTY0004].

  2. If the atomized value of the name expression is of type xs:string or xs:untypedAtomic, that value is cast to the type xs:NCName. If the value cannot be cast to xs:NCName, a dynamic error is raised [err:XQDY0041].

  3. The resulting NCName is then used as the target property of the newly constructed processing instruction node. However, a dynamic error is raised if the NCName is equal to "XML" (in any combination of upper and lower case) [err:XQDY0064].

The content expression of a computed processing instruction constructor is processed as follows:

  1. Atomization is applied to the value of the content expression, converting it to a sequence of atomic values. (If the content expression is absent, the result of this step is an empty sequence.)

  2. If the result of atomization is an empty sequence, it is replaced by a zero-length string. Otherwise, each atomic value in the atomized sequence is cast into a string. If any of the resulting strings contains the string "?>", a dynamic error [err:XQDY0026] is raised.

  3. The individual strings resulting from the previous step are merged into a single string by concatenating them with a single space character between each pair. Leading whitespace is removed from the resulting string. The resulting string then becomes the content property of the constructed processing instruction node.

The remaining properties of the new processing instruction node are determined as follows:

  1. The parent property is empty.

  2. The base-uri property is empty.

The following example illustrates a computed processing instruction constructor:

let $target := "audio-output",
    $content := "beep"
return processing-instruction {$target} {$content}

The processing instruction node constructed by this example might be serialized as follows:

&lt;?audio-output beep?&gt;
4.12.3.6 Computed Comment Constructors
[184]    CompCommentConstructor    ::=    "comment" EnclosedExpr
[40]    EnclosedExpr    ::=    "{" Expr? "}"

A computed comment constructor (CompCommentConstructor) constructs a new comment node with its own node identity. The content expression of a computed comment constructor is processed as follows:

  1. Atomization is applied to the value of the content expression, converting it to a sequence of atomic values.

  2. If the result of atomization is an empty sequence, it is replaced by a zero-length string. Otherwise, each atomic value in the atomized sequence is cast into a string.

  3. The individual strings resulting from the previous step are merged into a single string by concatenating them with a single space character between each pair. The resulting string becomes the content property of the constructed comment node.

  4. It is a dynamic error [err:XQDY0072] if the result of the content expression of a computed comment constructor contains two adjacent hyphens or ends with a hyphen.

The parent property of the constructed comment node is set to empty.

The following example illustrates a computed comment constructor:

let $homebase := "Houston"
return comment {fn:concat($homebase, ", we have a problem.")}

The comment node constructed by this example might be serialized as follows:

&lt;!--Houston, we have a problem.--&gt;
4.12.3.7 Computed Namespace Constructors
[179]    CompNamespaceConstructor    ::=    "namespace" (Prefix | EnclosedPrefixExpr) EnclosedURIExpr
[180]    Prefix    ::=    NCName
[181]    EnclosedPrefixExpr    ::=    EnclosedExpr
[182]    EnclosedURIExpr    ::=    EnclosedExpr
[40]    EnclosedExpr    ::=    "{" Expr? "}"

A computed namespace constructor creates a new namespace node, with its own node identity. The parent of the newly created namespace node is empty.

If the constructor specifies a Prefix, it is used as the prefix for the namespace node.

If the constructor specifies a PrefixExpr, the prefix expression is evaluated as follows:

  1. Atomization is applied to the result of the PrefixExpr.

  2. If the result of atomization is an empty sequence or a single atomic value of type xs:string or xs:untypedAtomic, then the following rules are applied in order:

    1. If the result is castable to xs:NCName, then it is used as the local name of the newly constructed namespace node. (The local name of a namespace node represents the prefix part of the namespace binding.)

    2. If the result is the empty sequence or a zero-length xs:string or xs:untypedAtomic value, the new namespace node has no name (such a namespace node represents a binding for the default namespace).

    3. Otherwise, a dynamic error is raised [err:XQDY0074].

  3. If the result of atomization is not an empty sequence or a single atomic value of type xs:string or xs:untypedAtomic, a type error is raised [err:XPTY0004].

The content expression is evaluated, and the result is cast to xs:anyURI to create the URI property for the newly created node. An implementation may raise a dynamic error [err:XQDY0074] if the URIExpr of a computed namespace constructor is not a valid instance of xs:anyURI.

An error [err:XQDY0101] is raised if a computed namespace constructor attempts to do any of the following:

  • Bind the prefix xml to some namespace URI other than http://www.w3.org/XML/1998/namespace.

  • Bind a prefix other than xml to the namespace URI http://www.w3.org/XML/1998/namespace.

  • Bind the prefix xmlns to any namespace URI.

  • Bind a prefix to the namespace URI http://www.w3.org/2000/xmlns/.

  • Bind any prefix (including the empty prefix) to a zero-length namespace URI.

By itself, a computed namespace constructor has no effect on in-scope namespaces, but if an element constructor's content sequence contains a namespace node, the namespace binding it represents is added to the element's in-scope namespaces.

A computed namespace constructor has no effect on the statically known namespaces.

Note:

The newly created namespace node has all properties defined for a namespace node in the data model. As defined in the data model, the name of the node is the prefix, the string value of the node is the URI, the relative order of nodes that share no common ancestor is implementation dependent, and the relative order of namespace nodes that share a parent is also implementation dependent.

Examples:

  • A computed namespace constructor with a prefix:

    namespace a {"http://a.example.com" }
  • A computed namespace constructor with a prefix expression:

    namespace {"a"} {"http://a.example.com" }
  • A computed namespace constructor with an empty prefix:

    namespace { "" } {"http://a.example.com" }

Computed namespace constructors are generally used to add to the in-scope namespaces of elements created with element constructors:

<age xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> {
  namespace xs {"http://www.w3.org/2001/XMLSchema"},
  attribute xsi:type {"xs:integer"},
  23
}</age>

In the above example, note that the xsi namespace binding is created for the element because it is used in an attribute name. The attribute's content is simply character data, and has no effect on namespace bindings. The computed namespace constructor ensures that the xs binding is created.

Computed namespace constructors have no effect on the statically known namespaces. If the prefix a is not already defined in the statically known namespaces, the following expression results in a static error [err:XPST0081].

<a:form>
 {
  namespace a { "http://a.example.com" }
 }
</a:form>

4.12.4 In-scope Namespaces of a Constructed Element

An element node constructed by a direct or computed element constructor has an in-scope namespaces property that consists of a set of namespace bindings. The in-scope namespaces of an element node may affect the way the node is serialized (see 2.3.4 Serialization), and may also affect the behavior of certain functions that operate on nodes, such as fn:name. Note the difference between in-scope namespaces, which is a dynamic property of an element node, and statically known namespaces, which is a static property of an expression. Also note that one of the namespace bindings in the in-scope namespaces may have no prefix (denoting the default namespace for the given element). The in-scope namespaces of a constructed element node consist of the following namespace bindings:

  • A namespace binding is created for each namespace declared in the current element constructor by a namespace declaration attribute.

  • A namespace binding is created for each namespace node in the content sequence of the current element constructor.

  • A namespace binding is created for each namespace that is declared in a namespace declaration attribute of an enclosing direct element constructor and not overridden by the current element constructor or an intermediate constructor.

  • A namespace binding is always created to bind the prefix xml to the namespace URI http://www.w3.org/XML/1998/namespace.

  • For each prefix used in the name of the constructed element or in the names of its attributes, a namespace binding must exist. If a namespace binding does not already exist for one of these prefixes, a new namespace binding is created for it. If this would result in a conflict, because it would require two different bindings of the same prefix, then the prefix used in the node name is changed to an arbitrary implementation-dependent prefix that does not cause such a conflict, and a namespace binding is created for this new prefix. If there is an in-scope default namespace, then a binding is created between the empty prefix and that URI.

Note:

Copy-namespaces mode does not affect the namespace bindings of a newly constructed element node. It applies only to existing nodes that are copied by a constructor expression.

In an element constructor, if two or more namespace bindings in the in-scope bindings would have the same prefix, then an error is raised if they have different URIs [err:XQDY0102]; if they would have the same prefix and URI, duplicate bindings are ignored. If the name of an element in an element constructor is in no namespace, creating a default namespace for that element using a computed namespace constructor is an error [err:XQDY0102]. For instance, the following computed constructor raises an error because the element's name is not in a namespace, but a default namespace is defined.

element e { namespace {''} {'u'} }

The following query illustrates the in-scope namespaces of a constructed element:

declare namespace p="http://example.com/ns/p";
declare namespace q="http://example.com/ns/q";
declare namespace f="http://example.com/ns/f";

&lt;p:a q:b="{f:func(2)}" xmlns:r="http://example.com/ns/r"/&gt;

The in-scope namespaces of the resulting p:a element consists of the following namespace bindings:

  • p = "http://example.com/ns/p"

  • q = "http://example.com/ns/q"

  • r = "http://example.com/ns/r"

  • xml = "http://www.w3.org/XML/1998/namespace"

The namespace bindings for p and q are added to the result element because their respective namespaces are used in the names of the element and its attributes. The namespace binding r="http://example.com/ns/r" is added to the in-scope namespaces of the constructed element because it is defined by a namespace declaration attribute, even though it is not used in a name.

No namespace binding corresponding to f="http://example.com/ns/f" is created, because the namespace prefix f appears only in the query prolog and is not used in an element or attribute name of the constructed node. This namespace binding does not appear in the query result, even though it is present in the statically known namespaces and is available for use during processing of the query.

Note that the following constructed element, if nested within a validate expression, cannot be validated:

&lt;p xsi:type="xs:integer"&gt;3&lt;/p&gt;

The constructed element will have namespace bindings for the prefixes xsi (because it is used in a name) and xml (because it is defined for every constructed element node). During validation of the constructed element, the validator will be unable to interpret the namespace prefix xs because it is has no namespace binding. Validation of this constructed element could be made possible by providing a namespace declaration attribute, as in the following example:

&lt;p xmlns:xs="http://www.w3.org/2001/XMLSchema"
   xsi:type="xs:integer"&gt;3&lt;/p&gt;

4.13 String Constructors

[Definition: A String Constructor creates a string from literal text and interpolated expressions. ]

The syntax of a string constructor is convenient for generating JSON, JavaScript, CSS, SPARQL, XQuery, XPath, or other languages that use curly brackets, quotation marks, or other strings that are delimiters in XQuery 4.0.

[196]    StringConstructor    ::=    "``[" StringConstructorContent "]``" /* ws: explicit */
[197]    StringConstructorContent    ::=    StringConstructorChars (StringConstructorInterpolation StringConstructorChars)* /* ws: explicit */
[198]    StringConstructorChars    ::=    (Char* - (Char* ('`{' | ']``') Char*)) /* ws: explicit */
[199]    StringConstructorInterpolation    ::=    "`{" Expr? "}`"

In a string constructor, adjacent string constructor characters are treated as literal text. Line endings are processed as elsewhere in XQuery; no other processing is performed on this text. To evaluate a string constructor, each sequence of adjacent string constructor characters is converted to a string containing the same characters, and each string constructor interpolation $i is evaluated, then converted to a string using the expression string-join($i, ' '). A string constructor interpolation that does not contain an expression (`{ }`) is ignored. The strings created from string constructor characters and the strings created from string constructor interpolations are then concatenated, in order.

For instance, the following expression:

for $s in ("one", "two", "red", "blue")
return ``[`{$s}` fish]``

evaluates to the sequence ("one fish", "two fish", "red fish", "blue fish").

Note:

Character entities are not expanded in string constructor content. Thus, ``[&lt;]`` evaluates to the string "&lt;", not the string "<".

Interpolations can contain string constructors. For instance, consider the following expression:

``[`{ $i, ``[literal text]``, $j, ``[more literal text]`` }`]``

Assuming the values $i := 1 and $j := 2, this evaluates to the string "1 literal text 2 more literal text".

The following examples are based on an example taken from the documentation of [Moustache], a JavaScript template library. Each function takes a map, containing values like these:

map {
  "name": "Chris",
  "value": 10000,
  "taxed_value": 10000 - (10000 * 0.4),
  "in_ca": true
}

This function creates a simple string.

declare function local:prize-message($a) as xs:string
{
``[Hello `{$a?name}`
You have just won `{$a?value}` dollars!
`{ 
   if ($a?in_ca) 
   then ``[Well, `{$a?taxed_value}` dollars, after taxes.]``
   else ""
}`]``
};

This is the output of the above function :

Hello Chris
You have just won 10000 dollars!
Well, 6000 dollars, after taxes.

This function creates a similar string in HTML syntax.

declare function local:prize-message($a) as xs:string
{
``[<div>
  <h1>Hello `{$a?name}`</h1>
  <p>You have just won `{$a?value}` dollars!</p>
    `{ 
      if ($a?in_ca) 
      then ``[  <p>Well, `{$a?taxed_value}` dollars, after taxes.</p> ]``
      else ""
    }`
</div>]``
};

This is the output of the above function :

&lt;div&gt;
  &lt;h1&gt;Hello Chris&lt;/h1&gt;
  &lt;p&gt;You have just won 10000 dollars!&lt;/p&gt;
  &lt;p&gt;Well, 6000 dollars, after taxes.&lt;/p&gt; 
&lt;/div&gt;

This function creates a similar string in JSON syntax.

declare function local:prize-message($a) as xs:string
{
``[{ 
  "name" : `{ $a?name }`
  "value" : `{ $a?value }`
  `{
  if ($a?in_ca) 
  then 
  ``[, 
  "taxed_value" : `{ $a?taxed_value }`]``  
  else ""
  }`
}]`` 
};

This is the output of the above function :

{ 
  "name" : "Chris",
  "value" : 10000,
  "taxed_value" : 6000
}

4.14 Maps and Arrays

Most modern programming languages have support for collections of key/value pairs, which may be called maps, dictionaries, associative arrays, hash tables, keyed lists, or objects (these are not the same thing as objects in object-oriented systems). In XQuery 4.0, we call these maps. Most modern programming languages also support ordered lists of values, which may be called arrays, vectors, or sequences. In XQuery 4.0, we have both sequences and arrays. Unlike sequences, an array is an item, and can appear as an item in a sequence.

Note:

The XQuery 4.0 specification focuses on syntax provided for maps and arrays, especially constructors and lookup.

Some of the functionality typically needed for maps and arrays is provided by functions defined in Section 17 Maps and Arrays FO31, including functions used to read JSON to create maps and arrays, serialize maps and arrays to JSON, combine maps to create a new map, remove map entries to create a new map, iterate over the keys of a map, convert an array to create a sequence, combine arrays to form a new array, and iterate over arrays in various ways.

4.14.1 Maps

[Definition: A map is a function that associates a set of keys with values, resulting in a collection of key / value pairs.] [Definition: Each key / value pair in a map is called an entry.] [Definition: The value associated with a given key is called the associated value of the key.]

4.14.1.1 Map Constructors

A Map is created using a MapConstructor.

[189]    MapConstructor    ::=    "map" "{" (MapConstructorEntry ("," MapConstructorEntry)*)? "}"
[190]    MapConstructorEntry    ::=    MapKeyExpr ":" MapValueExpr
[191]    MapKeyExpr    ::=    ExprSingle
[192]    MapValueExpr    ::=    ExprSingle

Note:

In some circumstances, it is necessary to include whitespace before or after the colon of a MapConstructorEntry to ensure that it is parsed as intended.

For instance, consider the expression map{a:b}. Although it matches the EBNF for MapConstructor (with a matching MapKeyExpr and b matching MapValueExpr), the "longest possible match" rule requires that a:b be parsed as a QName, which results in a syntax error. Changing the expression to map{a :b} or map{a: b} will prevent this, resulting in the intended parse.

Similarly, consider these three expressions:

    map{a:b:c}
    map{a:*:c}
    map{*:b:c}

In each case, the expression matches the EBNF in two different ways, but the "longest possible match" rule forces the parse in which the MapKeyExpr is a:b, a:*, or *:b (respectively) and the MapValueExpr is c. To achieve the alternative parse (in which the MapKeyExpr is merely a or *), insert whitespace before and/or after the first colon.

See A.2 Lexical structure.

The value of the expression is a map whose entries correspond to the key-value pairs obtained by evaluating the successive MapKeyExpr and MapValueExpr expressions.

Each MapKeyExpr expression is evaluated and atomized; a type error [err:XPTY0004] occurs if the result is not a single atomic value. The associated value is the result of evaluating the corresponding MapValueExpr. If the MapValueExpr evaluates to a node, the associated value is the node itself, not a new node with the same values. [Definition: Two atomic values K1 and K2 have the same key value if op:same-key(K1, K2) returns true, as specified in Section 17.1.1 op:same-key FO31 ] If two or more entries have the same key value then a dynamic error is raised [err:XQDY0137].

Example:

The following expression constructs a map with seven entries:

map {
  "Su" : "Sunday",
  "Mo" : "Monday",
  "Tu" : "Tuesday",
  "We" : "Wednesday",
  "Th" : "Thursday",
  "Fr" : "Friday",
  "Sa" : "Saturday"
}

Maps can nest, and can contain any XDM value. Here is an example of a nested map with values that can be string values, numeric values, or arrays:

map {
    "book": map {
        "title": "Data on the Web",
        "year": 2000,
        "author": [
            map {
                "last": "Abiteboul",
                "first": "Serge"
            },
            map {
                "last": "Buneman",
                "first": "Peter"
            },
            map {
                "last": "Suciu",
                "first": "Dan"
            }
        ],
        "publisher": "Morgan Kaufmann Publishers",
        "price": 39.95
    }
}
    
4.14.1.2 Map Lookup using Function Call Syntax

Maps are function items, and a dynamic function call can be used to look up the value associated with a key in a map. If $map is a map and $key is a key, then $map($key) is equivalent to map:get($map, $key). The semantics of such a function call are formally defined in Section 17.1.6 map:get FO31.

Examples:

Note:

XQuery 4.0 also provides an alternate syntax for map and array lookup that is more terse, supports wildcards, and allows lookup to iterate over a sequence of maps or arrays. See 4.14.3 The Lookup Operator ("?") for Maps and Arrays for details.

Map lookups can be chained.

Examples: (These examples assume that $b is bound to the books map from the previous section)

  • The expression $b("book")("title") returns the string Data on the Web.

  • The expression $b("book")("author") returns the array of authors.

  • The expression $b("book")("author")(1)("last") returns the string Abiteboul.

    (This example combines 4.14.2.2 Array Lookup using Function Call Syntax with map lookups.)

4.14.2 Arrays

4.14.2.1 Array Constructors

[Definition: An array is a function item that associates a set of positions, represented as positive integer keys, with values.] The first position in an array is associated with the integer 1. [Definition: The values of an array are called its members.] In the type hierarchy, array has a distinct type, which is derived from function. Atomization converts arrays to sequences (see Atomization).

An array is created using an ArrayConstructor.

[193]    ArrayConstructor    ::=    SquareArrayConstructor | CurlyArrayConstructor
[194]    SquareArrayConstructor    ::=    "[" (ExprSingle ("," ExprSingle)*)? "]"
[195]    CurlyArrayConstructor    ::=    "array" EnclosedExpr

If a member of an array is a node, its node identity is preserved. In both forms of an ArrayConstructor, if a member expression evaluates to a node, the associated value is the node itself, not a new node with the same values. If the member expression evaluates to a map or array, the associated value is a new map or array with the same values.

A SquareArrayConstructor consists of a comma-delimited set of argument expressions. It returns an array in which each member contains the value of the corresponding argument expression.

Examples:

  • [ 1, 2, 5, 7 ] creates an array with four members: 1, 2, 5, and 7.

  • [ (), (27, 17, 0)] creates an array with two members: () and the sequence (27, 17, 0).

  • [ $x, local:items(), <tautology>It is what it is.</tautology> ] creates an array with three members: the value of $x, the result of evaluating the function call, and a tautology element.

A CurlyArrayConstructor can use any expression to create its members. It evaluates its operand expression to obtain a sequence of items and creates an array with these items as members. Unlike a SquareArrayConstructor, a comma in a CurlyArrayConstructor is the comma operator, not a delimiter.

Examples:

  • array { $x } creates an array with one member for each item in the sequence to which $x is bound.

  • array { local:items() } creates an array with one member for each item in the sequence to which local:items() evaluates.

  • array { 1, 2, 5, 7 } creates an array with four members: 1, 2, 5, and 7.

  • array { (), (27, 17, 0) } creates an array with three members: 27, 17, and 0.

  • array{ $x, local:items(), <tautology>It is what it is.</tautology> } creates an array with the following members: the items to which $x is bound, followed by the items to which local:items() evaluates, followed by a tautology element.

Note:

XQuery 4.0 does not provide explicit support for sparse arrays. Use integer-valued maps to represent sparse arrays, e.g. map { 27 : -1, 153 : 17 } .

4.14.2.2 Array Lookup using Function Call Syntax

Arrays are function items, and a dynamic function call can be used to look up the value associated with position in an array. If $array is an array and $index is an integer corresponding to a position in the array, then $array($key) is equivalent to array:get($array, $key). The semantics of such a function call are formally defined in Section 17.3.2 array:get FO31.

Examples:

  • [ 1, 2, 5, 7 ](4) evaluates to 7.

  • [ [1, 2, 3], [4, 5, 6]](2) evaluates to [4, 5, 6].

  • [ [1, 2, 3], [4, 5, 6]](2)(2) evaluates to 5.

  • [ 'a', 123, <name>Robert Johnson</name> ](3) evaluates to <name>Robert Johnson</name>.

  • array { (), (27, 17, 0) }(1) evaluates to 27.

  • array { (), (27, 17, 0) }(2) evaluates to 17.

  • array { "licorice", "ginger" }(20) raises a dynamic error [err:FOAY0001]FO31.

Note:

XQuery 4.0 also provides an alternate syntax for map and array lookup that is more terse, supports wildcards, and allows lookup to iterate over a sequence of maps or arrays. See 4.14.3 The Lookup Operator ("?") for Maps and Arrays for details.

4.14.3 The Lookup Operator ("?") for Maps and Arrays

XQuery 4.0 provides a lookup operator for maps and arrays that is more convenient for some common cases. It provides a terse syntax for simple strings as keys in maps or integers as keys in arrays, supports wildcards, and iterates over sequences of maps and arrays.

4.14.3.1 Unary Lookup
[200]    UnaryLookup    ::=    "?" KeySpecifier
[144]    KeySpecifier    ::=    NCName | IntegerLiteral | StringLiteral | VarRef | ParenthesizedExpr | "*"

Unary lookup is used in predicates (e.g. $map[?name='Mike'] or with the simple map operator (e.g. $maps ! ?name='Mike'). See 4.14.3.2 Postfix Lookup for the postfix lookup operator.

UnaryLookup returns a sequence of values selected from the context item, which must be a map or array. If the context item is not a map or an array, a type error is raised [err:XPTY0004].

If the context item is a map:

  1. If the KeySpecifier is an NCName or a StringLiteral , the UnaryLookup operator is equivalent to .(KS), where KS is the value of the NCName or StringLiteral.

  2. If the KeySpecifier is an IntegerLiteral, the UnaryLookup operator is equivalent to .(KS), where KS is the value of the IntegerLiteral.

  3. If the KeySpecifier is a ParenthesizedExpr or a VarRef the UnaryLookup operator is equivalent to the following expression, where KS is the value of the ParenthesizedExpr or VarRef :

    for $k in fn:data(KS)
    return .($k)  
    
  4. If the KeySpecifier is a wildcard ("*"), the UnaryLookup operator is equivalent to the following expression:

    for $k in map:keys(.)
    return .($k)
    

    Note:

    The order of keys in map:keys() is implementation-dependent, so the order of values in the result sequence is also implementation-dependent.

If the context item is an array:

  1. If the KeySpecifier is an IntegerLiteral, the UnaryLookup operator is equivalent to .(KS), where KS is the value of the IntegerLiteral.

  2. If the KeySpecifier is an NCName or StringLiteral , the UnaryLookup operator raises a type error [err:XPTY0004].

  3. If the KeySpecifier is a ParenthesizedExpr or a VarRef , the UnaryLookup operator is equivalent to the following expression, where KS is the value of the ParenthesizedExpr or VarRef :

    for $k in fn:data(KS)
    return .($k)  
    
  4. If the KeySpecifier is a wildcard ("*"), the UnaryLookup operator is equivalent to the following expression:

    for $k in 1 to array:size(.)
    return .($k)
    

    Note:

    Note that array items are returned in order.

Examples:

  • ?name is equivalent to .("name"), an appropriate lookup for a map.

  • ?2 is equivalent to .(2), an appropriate lookup for an array or an integer-valued map.

  • ?"first name" is equivalent to .("first name")

  • ?("$funky / <looking @string") is equivalent to .("$funky / <looking @string"), an appropriate lookup for a map with rather odd conventions for keys.

  • ?($a) and ?$a are equivalent to for $k in $a return .($k), allowing keys for an array or map to be passed using a variable.

  • ?(2 to 4) is equivalent to for $k in (2,3,4) return .($k), a convenient way to return a range of values from an array.

  • ?(3.5) raises a type error if the context item is an array because the parameter must be an integer.

  • If the context item is an array, let $x:= <node i="3"/> return ?($x/@i) does not raise a type error because the attribute is untyped.

    But let $x:= <node i="3"/> return ?($x/@i+1) does raise a type error because the + operator with an untyped operand returns a double.

  • ([1,2,3], [1,2,5], [1,2])[?3 = 5] raises an error because ?3 on one of the items in the sequence fails.

  • If $m is bound to the weekdays map described in 4.14.1 Maps, then $m?* returns the values ("Sunday","Monday","Tuesday","Wednesday", "Thursday", "Friday","Saturday"), in implementation-dependent order.

  • [1, 2, 5, 7]?* evaluates to (1, 2, 5, 7).

  • [[1, 2, 3], [4, 5, 6]]?* evaluates to ([1, 2, 3], [4, 5, 6])

4.14.3.2 Postfix Lookup
[143]    Lookup    ::=    "?" KeySpecifier

The semantics of a Postfix Lookup expression depend on the form of the KeySpecifier, as follows:

  • If the KeySpecifier is an NCName, StringLiteral, VarRef, IntegerLiteral, or Wildcard ("*"), then the expression E?S is equivalent to E!?S. (That is, the semantics of the postfix lookup operator are defined in terms of the unary lookup operator).

  • If the KeySpecifier is a ParenthesizedExpr, then the expression E?(S) is equivalent to

    for $e in E, $s in fn:data(S) return $e($s)

    Note:

    The focus for evaluating S is the same as the focus for the Lookup expression itself.

Examples:

  • map { "first" : "Jenna", "last" : "Scott" }?first evaluates to "Jenna"

  • map { "first name" : "Jenna", "last name" : "Scott" }?"first name" evaluates to "Jenna"

  • [4, 5, 6]?2 evaluates to 5.

  • (map {"first": "Tom"}, map {"first": "Dick"}, map {"first": "Harry"})?first evaluates to the sequence ("Tom", "Dick", "Harry").

  • ([1,2,3], [4,5,6])?2 evaluates to the sequence (2, 5).

  • ["a","b"]?3 raises a dynamic error [err:FOAY0001]FO31

4.15 FLWOR Expressions

XQuery provides a versatile expression called a FLWOR expression that may contain multiple clauses. The FLWOR expression can be used for many purposes, including iterating over sequences, joining multiple documents, and performing grouping and aggregation. The name FLWOR, pronounced "flower", is suggested by the keywords for, let, where, order by, and return, which introduce some of the clauses used in FLWOR expressions (but this is not a complete list of such clauses.)

The complete syntax of a FLWOR expression is shown here, and relevant parts of the syntax are repeated in subsequent sections of this document.

[49]    FLWORExpr    ::=    InitialClause IntermediateClause* ReturnClause
[50]    InitialClause    ::=    ForClause | ForMemberClause | LetClause | WindowClause
[51]    IntermediateClause    ::=    InitialClause | WhereClause | GroupByClause | OrderByClause | CountClause
[52]    ForClause    ::=    "for" ForBinding ("," ForBinding)*
[53]    ForBinding    ::=    "$" VarName TypeDeclaration? AllowingEmpty? PositionalVar? "in" ExprSingle
[58]    LetClause    ::=    "let" LetBinding ("," LetBinding)*
[59]    LetBinding    ::=    "$" VarName TypeDeclaration? ":=" ExprSingle
[202]    TypeDeclaration    ::=    "as" SequenceType
[54]    AllowingEmpty    ::=    "allowing" "empty"
[57]    PositionalVar    ::=    "at" "$" VarName
[60]    WindowClause    ::=    "for" (TumblingWindowClause | SlidingWindowClause)
[61]    TumblingWindowClause    ::=    "tumbling" "window" "$" VarName TypeDeclaration? "in" ExprSingle WindowStartCondition WindowEndCondition?
[62]    SlidingWindowClause    ::=    "sliding" "window" "$" VarName TypeDeclaration? "in" ExprSingle WindowStartCondition WindowEndCondition
[63]    WindowStartCondition    ::=    "start" WindowVars "when" ExprSingle
[64]    WindowEndCondition    ::=    "only"? "end" WindowVars "when" ExprSingle
[65]    WindowVars    ::=    ("$" CurrentItem)? PositionalVar? ("previous" "$" PreviousItem)? ("next" "$" NextItem)?
[66]    CurrentItem    ::=    EQName
[67]    PreviousItem    ::=    EQName
[68]    NextItem    ::=    EQName
[69]    CountClause    ::=    "count" "$" VarName
[70]    WhereClause    ::=    "where" ExprSingle
[71]    GroupByClause    ::=    "group" "by" GroupingSpecList
[72]    GroupingSpecList    ::=    GroupingSpec ("," GroupingSpec)*
[73]    GroupingSpec    ::=    GroupingVariable (TypeDeclaration? ":=" ExprSingle)? ("collation" URILiteral)?
[74]    GroupingVariable    ::=    "$" VarName
[75]    OrderByClause    ::=    (("order" "by") | ("stable" "order" "by")) OrderSpecList
[76]    OrderSpecList    ::=    OrderSpec ("," OrderSpec)*
[77]    OrderSpec    ::=    ExprSingle OrderModifier
[78]    OrderModifier    ::=    ("ascending" | "descending")? ("empty" ("greatest" | "least"))? ("collation" URILiteral)?
[79]    ReturnClause    ::=    "return" ExprSingle

The semantics of FLWOR expressions are based on a concept called a tuple stream. [Definition: A tuple stream is an ordered sequence of zero or more tuples.] [Definition: A tuple is a set of zero or more named variables, each of which is bound to a value that is an XDM instance.] Each tuple stream is homogeneous in the sense that all its tuples contain variables with the same names and the same static types. The following example illustrates a tuple stream consisting of four tuples, each containing three variables named $x, $y, and $z:

($x = 1003, $y = "Fred", $z = &lt;age&gt;21&lt;/age&gt;)
($x = 1017, $y = "Mary", $z = &lt;age&gt;35&lt;/age&gt;)
($x = 1020, $y = "Bill", $z = &lt;age&gt;18&lt;/age&gt;)
($x = 1024, $y = "John", $z = &lt;age&gt;29&lt;/age&gt;)

Note:

In this section, tuple streams are represented as shown in the above example. Each tuple is on a separate line and is enclosed in parentheses, and the variable bindings inside each tuple are separated by commas. This notation does not represent XQuery syntax, but is simply a representation of a tuple stream for the purpose of defining the semantics of FLWOR expressions.

Tuples and tuple streams are not part of the data model. They exist only as conceptual intermediate results during the processing of a FLWOR expression.

Conceptually, the first clause generates a tuple stream. Each clause between the first clause and the return clause takes the tuple stream generated by the previous clause as input and generates a (possibly different) tuple stream as output. The return clause takes a tuple stream as input and, for each tuple in this tuple stream, generates an XDM instance; the final result of the FLWOR expression is the ordered concatenation of these XDM instances.

The initial clause in a FLWOR expression may be a for, let, or window clause. Intermediate clauses may be for, let, window, count, where, group by, or order by clauses. These intermediate clauses may be repeated as many times as desired, in any order. The final clause of the FLWOR expression must be a return clause. The semantics of the various clauses are described in the following sections.

4.15.1 Variable Bindings

The following clauses in FLWOR expressions bind values to variables: for, let, window, count, and group by. The binding of variables for for, let, and count is governed by the following rules (the binding of variables in group by is discussed in 4.15.7 Group By Clause, the binding of variables in window clauses is discussed in 4.15.4 Window Clause):

  1. The scope of a bound variable includes all subexpressions of the containing FLWOR that appear after the variable binding. The scope does not include the expression to which the variable is bound. The following code fragment, containing two let clauses, illustrates how variable bindings may reference variables that were bound in earlier clauses, or in earlier bindings in the same clause:

    let $x := 47, $y := f($x)
    let $z := g($x, $y)
  2. A given variable may be bound more than once in a FLWOR expression, or even within one clause of a FLWOR expression. In such a case, each new binding occludes the previous one, which becomes inaccessible in the remainder of the FLWOR expression.

  3. [Definition: A variable binding may be accompanied by a type declaration, which consists of the keyword as followed by the static type of the variable, declared using the syntax in 3.4 Sequence Types.] The type declaration defines a required type for the value. At run-time, the supplied value for the variable is converted to the required type by applying the coercion rules. If conversion is not possible, a type error is raised [err:XPTY0004]. For example, the following let clause raises a type error because the variable $salary has a type declaration that is not satisfied by the value that is bound to it:

    let $salary as xs:decimal :=  "cat"

    The following let clause, however, succeeds, because the coercion rules allow an xs:decimal to be supplied where an xs:double is required:

    let $temperature as xs:double := 32.5

    In applying the coercion rules, XPath 1.0 compatibility mode does not apply.

  4. [Definition: In a for clause, when an expression is preceded by the keyword in, the value of that expression is called a binding collection.] The collection may be either a sequence or an array. The for clause iterates over its binding collection, producing multiple bindings for one or more variables. Details on how binding collections are used in for clauses are described in the following sections.

  5. [Definition: In a window clause, when an expression is preceded by the keyword in, the value of that expression is called a binding sequence.] The window clause iterates over its binding sequence, producing multiple bindings for one or more variables. Details on how binding sequences are used in for and window clauses are described in the following sections.

4.15.2 For Clause

[52]    ForClause    ::=    "for" ForBinding ("," ForBinding)*
[55]    ForMemberClause    ::=    "for" "member" ForMemberBinding ("," ForMemberBinding)*
[53]    ForBinding    ::=    "$" VarName TypeDeclaration? AllowingEmpty? PositionalVar? "in" ExprSingle
[56]    ForMemberBinding    ::=    "$" VarName TypeDeclaration? PositionalVar? "in" ExprSingle
[202]    TypeDeclaration    ::=    "as" SequenceType
[54]    AllowingEmpty    ::=    "allowing" "empty"
[57]    PositionalVar    ::=    "at" "$" VarName

A for clause is used for iteration. Each variable in a for clause iterates over a sequence or array and is bound in turn to each item in the sequence, or to each member in the array.

If a for clause contains multiple variables, it is semantically equivalent to multiple for clauses, each containing one of the variables in the original for clause.

Example:

  • The clause

    for $x in $expr1, $y in $expr2

    is semantically equivalent to:

    for $x in $expr1
    for $y in $expr2
  • The clause

    for member $x in $expr1, member $y in $expr2

    is semantically equivalent to:

    for member $x in $expr1
    for member $y in $expr2

Without the member keyword, the expression iterates over the items in a sequence. With the member keyword, it iterates over the members of an array. We refer to the sequence or array generically as the binding collection, and to its items or members as the components of the collection.

If member is specified, then the corresponding ExprSingle must evaluate to a single array, otherwise a type error is raised [err:XPTY0004]

In the remainder of this section, we define the semantics of a for clause containing a single variable and an associated expression (following the keyword in) whose value is the binding collection for that variable.

If a single-variable for clause is the initial clause in a FLWOR expression, it iterates over its binding collection, binding the variable to each component in turn. The resulting sequence of variable bindings becomes the initial tuple stream that serves as input to the next clause of the FLWOR expression. If ordering mode is ordered, the order of tuples in the tuple stream preserves the order of the binding collection; otherwise the order of the tuple stream is implementation-dependent.

If the binding collection is empty, the output tuple stream depends on whether allowing empty is specified. If allowing empty is specified, the output tuple stream consists of one tuple in which the variable is bound to an empty sequence. If allowing empty is not specified, the output tuple stream consists of zero tuples.

The following examples illustrates tuple streams that are generated by initial for clauses:

  • Initial clause:

    for $x in (100, 200, 300)

    or (equivalently):

    for $x allowing empty in (100, 200, 300)

    Output tuple stream:

    ($x = 100)
    ($x = 200)
    ($x = 300)
  • Initial clause:

    for $x in ()

    Output tuple stream contains no tuples.

  • Initial clause:

    for $x allowing empty in ()

    Output tuple stream:

    ($x = ())
  • Initial clause:

    for member $x in [1, 2, (5 to 10)

    Output tuple stream:

    ($x = (1))
    ($x = (2))
    ($x = (5, 6, 7, 8, 9, 10)
  • Initial clause:

    for member $x in []

    Output tuple stream contains no tuples.

  • Initial clause:

    for member $x allowing empty in [] 

    Output tuple stream:

    ($x = ())

[Definition: A positional variable is a variable that is preceded by the keyword at.] A positional variable may be associated with a variable that is bound in a for clause. In this case, as the main variable iterates over the components of its binding collection, the positional variable iterates over the integers that represent the ordinal numbers of these component in the binding collection, starting with one. Each tuple in the output tuple stream contains bindings for both the main variable and the positional variable. If the binding collection is empty and allowing empty is specified, the positional variable in the output tuple is bound to the integer zero. Positional variables always have the implied type xs:integer.

The expanded QName of a positional variable must be distinct from the expanded QName of the main variable with which it is associated [err:XQST0089].

The following examples illustrate how a positional variable would have affected the results of the previous examples that generated tuples:

  • Initial clause:

    for $x at $i in (100, 200, 300)

    Output tuple stream:

    ($x = 100, $i = 1)
    ($x = 200, $i = 2)
    ($x = 300, $i = 3)
  • Initial clause:

    for $x at $i in [1 to 3, 11 to 13, 21 to 23

    Output tuple stream:

    ($x = (1, 2, 3), $i = 1)
    ($x = (11, 12, 13), $i = 2)
    ($x = (21, 22, 23), $i = 3)
  • Initial clause:

    for $x allowing empty at $i in ()

    Output tuple stream:

    ($x = (), $i = 0)

If a single-variable for clause is an intermediate clause in a FLWOR expression, its binding collection is evaluated for each input tuple, given the bindings in that input tuple. Each input tuple generates zero or more tuples in the output tuple stream. Each of these output tuples consists of the original variable bindings of the input tuple plus a binding of the new variable to one of the items in its binding collecction.

Note:

Although the binding collection is conceptually evaluated independently for each input tuple, an optimized implementation may sometimes be able to avoid re-evaluating the binding collection if it can show that the variables that the binding collection depends on have the same values as in a previous evaluation.

For a given input tuple, if the binding collection for the new variable in the for clause is empty (that is, it is an empty sequence or an empty array depending on whether member is specified), the result depends on whether allowing empty is specified. If allowing empty is specified, the input tuple generates one output tuple, with the original variable bindings plus a binding of the new variable to an empty sequence. If allowing empty is not specified, the input tuple generates zero output tuples (it is not represented in the output tuple stream.)

If the new variable introduced by a for clause has an associated positional variable, the output tuples generated by the for clause also contain bindings for the positional variable. In this case, as the new variable is bound to each item in its binding collection, the positional variable is bound to the ordinal position of that item within the binding collection, starting with one. Note that, since the positional variable represents a position within a binding collection, the output tuples corresponding to each input tuple are independently numbered, starting with one. For a given input tuple, if the binding collection is empty and allowing empty is specified, the positional variable in the output tuple is bound to the integer zero.

If ordering mode is ordered, the tuples in the output tuple stream are ordered primarily by the order of the input tuples from which they are derived, and secondarily by the order of the binding sequence for the new variable; otherwise the order of the output tuple stream is implementation-dependent.

The following examples illustrates the effects of intermediate for clauses:

  • Input tuple stream:

    ($x = 1)
    ($x = 2)
    ($x = 3)
    ($x = 4)

    Intermediate for clause:

    for $y in ($x to 3)

    Output tuple stream (assuming ordering mode is ordered):

    ($x = 1, $y = 1)
    ($x = 1, $y = 2)
    ($x = 1, $y = 3)
    ($x = 2, $y = 2)
    ($x = 2, $y = 3)
    ($x = 3, $y = 3)
    

    Note:

    In this example, there is no output tuple that corresponds to the input tuple ($x = 4) because, when the for clause is evaluated with the bindings in this input tuple, the resulting binding collection for $y is empty.

  • This example shows how the previous example would have been affected by a positional variable (assuming the same input tuple stream):

    for $y at $j in ($x to 3)

    Output tuple stream (assuming ordering mode is ordered):

    ($x = 1, $y = 1, $j = 1)
    ($x = 1, $y = 2, $j = 2)
    ($x = 1, $y = 3, $j = 3)
    ($x = 2, $y = 2, $j = 1)
    ($x = 2, $y = 3, $j = 2)
    ($x = 3, $y = 3, $j = 1)
    
  • This example shows how the previous example would have been affected by allowing empty. Note that allowing empty causes the input tuple ($x = 4) to be represented in the output tuple stream, even though the binding sequence for $y contains no items for this input tuple. This example illustrates that allowing empty in a for clause serves a purpose similar to that of an "outer join" in a relational database query. (Assume the same input tuple stream as in the previous example.)

    for $y allowing empty at $j in ($x to 3)

    Output tuple stream (assuming ordering mode is ordered):

    ($x = 1, $y = 1, $j = 1)
    ($x = 1, $y = 2, $j = 2)
    ($x = 1, $y = 3, $j = 3)
    ($x = 2, $y = 2, $j = 1)
    ($x = 2, $y = 3, $j = 2)
    ($x = 3, $y = 3, $j = 1)
    ($x = 4, $y = (), $j = 0)
    
  • This example illustrates processing of arrays:

    Input tuple stream:

    ($x = 1)
    ($x = 2)
    ($x = 3)

    Intermediate for clause:

    for member $y in [[$x+1, $x+2], [[$x+3, $x+4]] 

    Output tuple stream (assuming ordering mode is ordered):

    ($x = 1, $y = [2, 3])
    ($x = 1, $y = [4, 5])
    ($x = 2, $y = [3, 4])
    ($x = 2, $y = [5, 6])
    ($x = 3, $y = [4, 5])
    ($x = 3, $y = [6, 7])
    
  • This example shows how a for clause that binds two variables is semantically equivalent to two for clauses that bind one variable each. We assume that this for clause occurs at the beginning of a FLWOR expression. It is equivalent to an initial single-variable for clause that provides an input tuple stream to an intermediate single-variable for clause.

    for $x in (1, 2, 3, 4), $y in ($x to 3)

    Output tuple stream (assuming ordering mode is ordered):

    ($x = 1, $y = 1)
    ($x = 1, $y = 2)
    ($x = 1, $y = 3)
    ($x = 2, $y = 2)
    ($x = 2, $y = 3)
    ($x = 3, $y = 3)
    

In the above examples, if ordering mode had been unordered, the output tuple streams would have consisted of the same tuples, with the same values for the positional variables, but the ordering of the tuples would have been implementation-dependent.

A for clause may contain one or more type declarations, identified by the keyword as. The semantics of type declarations are defined in 4.15.1 Variable Bindings.

4.15.3 Let Clause

[58]    LetClause    ::=    "let" LetBinding ("," LetBinding)*
[59]    LetBinding    ::=    "$" VarName TypeDeclaration? ":=" ExprSingle
[202]    TypeDeclaration    ::=    "as" SequenceType

The purpose of a let clause is to bind values to one or more variables. Each variable is bound to the result of evaluating an expression.

If a let clause contains multiple variables, it is semantically equivalent to multiple let clauses, each containing a single variable. For example, the clause

let $x := $expr1, $y := $expr2

is semantically equivalent to the following sequence of clauses:

let $x := $expr1
let $y := $expr2

In the remainder of this section, we define the semantics of a let clause containing a single variable V and an associated expression E.

If a single-variable let clause is the initial clause in a FLWOR expression, it simply binds the variable V to the result of the expression E. The result of the let clause is a tuple stream consisting of one tuple with a single binding that binds V to the result of E. This tuple stream serves as input to the next clause in the FLWOR expression.

If a single-variable let clause is an intermediate clause in a FLWOR expression, it adds a new binding for variable V to each tuple in the input tuple stream. For each input tuple, the value bound to V is the result of evaluating expression E, given the bindings that are already present in that input tuple. The resulting tuples become the output tuple stream of the let clause.

The number of tuples in the output tuple stream of an intermediate let clause is the same as the number of tuples in the input tuple stream. The number of bindings in the output tuples is one more than the number of bindings in the input tuples, unless the input tuples already contain bindings for V; in this case, the new binding for V occludes (replaces) the earlier binding for V, and the number of bindings is unchanged.

A let clause may contain one or more type declarations, identified by the keyword as. The semantics of type declarations are defined in 4.15.1 Variable Bindings.

The following code fragment illustrates how a for clause and a let clause can be used together. The for clause produces an initial tuple stream containing a binding for variable $d to each department number found in a given input document. The let clause adds an additional binding to each tuple, binding variable $e to a sequence of employees whose department number matches the value of $d in that tuple.

for $d in fn:doc("depts.xml")/depts/deptno
let $e := fn:doc("emps.xml")/emps/emp[deptno eq $d]

4.15.4 Window Clause

[60]    WindowClause    ::=    "for" (TumblingWindowClause | SlidingWindowClause)
[61]    TumblingWindowClause    ::=    "tumbling" "window" "$" VarName TypeDeclaration? "in" ExprSingle WindowStartCondition WindowEndCondition?
[62]    SlidingWindowClause    ::=    "sliding" "window" "$" VarName TypeDeclaration? "in" ExprSingle WindowStartCondition WindowEndCondition
[63]    WindowStartCondition    ::=    "start" WindowVars "when" ExprSingle
[64]    WindowEndCondition    ::=    "only"? "end" WindowVars "when" ExprSingle
[65]    WindowVars    ::=    ("$" CurrentItem)? PositionalVar? ("previous" "$" PreviousItem)? ("next" "$" NextItem)?
[66]    CurrentItem    ::=    EQName
[57]    PositionalVar    ::=    "at" "$" VarName
[67]    PreviousItem    ::=    EQName
[68]    NextItem    ::=    EQName

Like a for clause, a window clause iterates over its binding sequence and generates a sequence of tuples. In the case of a window clause, each tuple represents a window. [Definition: A window is a sequence of consecutive items drawn from the binding sequence.] Each window is represented by at least one and at most nine bound variables. The variables have user-specified names, but their roles are as follows:

  • Window-variable: Bound to the sequence of items from the binding sequence that comprise the window.

  • Start-item: (Optional) Bound to the first item in the window.

  • Start-item-position: (Optional) Bound to the ordinal position of the first window item in the binding sequence. Start-item-position is a positional variable; hence, its type is xs:integer

  • Start-previous-item: (Optional) Bound to the item in the binding sequence that precedes the first item in the window (empty sequence if none).

  • Start-next-item: (Optional) Bound to the item in the binding sequence that follows the first item in the window (empty sequence if none).

  • End-item: (Optional) Bound to the last item in the window.

  • End-item-position: (Optional) Bound to the ordinal position of the last window item in the binding sequence. End-item-position is a positional variable; hence, its type is xs:integer

  • End-previous-item: (Optional) Bound to the item in the binding sequence that precedes the last item in the window (empty sequence if none).

  • End-next-item: (Optional) Bound to the item in the binding sequence that follows the last item in the window (empty sequence if none).

All variables in a window clause must have distinct names; otherwise a static error is raised [err:XQST0103].

The following is an example of a window clause that binds nine variables to the roles listed above. In this example, the variables are named $w, $s, $spos, $sprev, $snext, $e, $epos, $eprev, and $enext respectively. A window clause always binds the window variable, but typically binds only a subset of the other variables.

for tumbling window $w in (2, 4, 6, 8, 10)
    start $s at $spos previous $sprev next $snext when true() 
    end $e at $epos previous $eprev next $enext when true()

Windows are created by iterating over the items in the binding sequence, in order, identifying the start item and the end item of each window by evaluating the WindowStartCondition and the WindowEndCondition. Each of these conditions is satisfied if the effective boolean value of the expression following the when keyword is true. The start item of the window is an item that satisfies the WindowStartCondition (see 4.15.4.1 Tumbling Windows and 4.15.4.2 Sliding Windows for a more complete explanation.) The end item of the window is the first item in the binding sequence, beginning with the start item, that satisfies the WindowEndCondition (again, see 4.15.4.1 Tumbling Windows and 4.15.4.2 Sliding Windows for more details.) Each window contains its start item, its end item, and all items that occur between them in the binding sequence. If the end item is the start item, then the window contains only one item. If a start item is identified, but no following item in the binding sequence satisfies the WindowEndCondition, then the only keyword determines whether a window is generated: if only end is specified, then no window is generated; otherwise, the end item is set to the last item in the binding sequence and a window is generated.

In the above example, the WindowStartCondition and WindowEndCondition are both true, which causes each item in the binding sequence to be in a separate window. Typically, the WindowStartCondition and WindowEndCondition are expressed in terms of bound variables. For example, the following WindowStartCondition might be used to start a new window for every item in the binding sequence that is larger than both the previous item and the following item:

start $s previous $sprev next $snext
   when $s &gt; $sprev and $s &gt; $snext

The scoping rules for the variables bound by a window clause are as follows:

  • In the when-expression of the WindowStartCondition, the following variables (identified here by their roles) are in scope (if bound): start-item, start-item-position, start-previous-item, start-next-item.

  • In the when-expression of the WindowEndCondition, the following variables (identified here by their roles) are in scope (if bound): start-item, start-item-position, start-previous-item, start-next-item, end-item, end-item-position, end-previous-item, end-next-item.

  • In the clauses of the FLWOR expression that follow the window clause, all nine of the variables bound by the window clause (including window-variable) are in scope (if bound).

In a window clause, the keyword tumbling or sliding determines the way in which the starting item of each window is identified, as explained in the following sections.

4.15.4.1 Tumbling Windows

If the window type is tumbling, then windows never overlap. The search for the start of the first window begins at the beginning of the binding sequence. After each window is generated, the search for the start of the next window begins with the item in the binding sequence that occurs after the ending item of the last generated window. Thus, no item that occurs in one window can occur in another window drawn from the same binding sequence (unless the sequence contains the same item more than once). In a tumbling window clause, the end clause is optional; if it is omitted, the start clause is applied to identify all potential starting items in the binding sequence, and a window is constructed for each starting item, including all items from that starting item up to the item before the next window's starting item, or the end of the binding sequence, whichever comes first.

The following examples illustrate the use of tumbling windows.

  • Show non-overlapping windows of three items.

    for tumbling window $w in (2, 4, 6, 8, 10, 12, 14)
        start at $s when fn:true()
        only end at $e when $e - $s eq 2
    return <window>{ $w }</window>

    Result of the above query:

    <window>2 4 6</window>
    <window>8 10 12</window>
  • Show averages of non-overlapping three-item windows.

    for tumbling window $w in (2, 4, 6, 8, 10, 12, 14)
        start at $s when fn:true()
        only end at $e when $e - $s eq 2
    return avg($w)

    Result of the above query:

    4 10
  • Show first and last items in each window of three items.

    for tumbling window $w in (2, 4, 6, 8, 10, 12, 14)
        start $first at $s when fn:true()
        only end $last at $e when $e - $s eq 2
    return <window>{ $first, $last }</window>

    Result of the above query:

    <window>2 6</window>
    <window>8 12</window>
  • Show non-overlapping windows of up to three items (illustrates end clause without the only keyword).

    for tumbling window $w in (2, 4, 6, 8, 10, 12, 14)
        start at $s when fn:true()
        end at $e when $e - $s eq 2
    return <window>{ $w }</window>

    Result of the above query:

    <window>2 4 6</window>
    <window>8 10 12</window>
    <window>14</window>
  • Show non-overlapping windows of up to three items (illustrates use of start without explicit end).

    for tumbling window $w in (2, 4, 6, 8, 10, 12, 14)
        start at $s when $s mod 3 = 1
    return <window>{ $w }</window>

    Result of the above query:

    <window>2 4 6</window>
    <window>8 10 12</window>
    <window>14</window>
  • Show non-overlapping sequences starting with a number divisible by 3.

    for tumbling window $w in (2, 4, 6, 8, 10, 12, 14)
        start $first when $first mod 3 = 0
    return <window>{ $w }</window>

    Result of the above query:

    <window>6 8 10</window>
    <window>12 14</window>
4.15.4.2 Sliding Windows

If the window type is sliding window, then windows may overlap. Every item in the binding sequence that satisfies the WindowStartCondition is the starting item of a new window. Thus, a given item may be found in multiple windows drawn from the same binding sequence.

The following examples illustrate the use of sliding windows.

  • Show windows of three items.

    for sliding window $w in (2, 4, 6, 8, 10, 12, 14)
        start at $s when fn:true()
        only end at $e when $e - $s eq 2
    return <window>{ $w }</window>

    Result of the above query:

    <window>2 4 6</window>
    <window>4 6 8</window>
    <window>6 8 10</window>
    <window>8 10 12</window>
    <window>10 12 14</window>
  • Show moving averages of three items.

    for sliding window $w in (2, 4, 6, 8, 10, 12, 14)
        start at $s when fn:true()
        only end at $e when $e - $s eq 2
    return avg($w)

    Result of the above query:

    4 6 8 10 12
  • Show overlapping windows of up to three items (illustrates end clause without the only keyword).

    for sliding window $w in (2, 4, 6, 8, 10, 12, 14)
        start at $s when fn:true()
        end at $e when $e - $s eq 2
    return <window>{ $w }</window>

    Result of the above query:

    <window>2 4 6</window>
    <window>4 6 8</window>
    <window>6 8 10</window>
    <window>8 10 12</window>
    <window>10 12 14</window>
    <window>12 14</window>
    <window>14</window>
4.15.4.3 Effects of Window Clauses on the Tuple Stream

The effects of a window clause on the tuple stream are similar to the effects of a for clause. As described in 4.15.4 Window Clause, a window clause generates zero or more windows, each of which is represented by at least one and at most nine bound variables.

If the window clause is the initial clause in a FLWOR expression, the bound variables that describe each window become an output tuple. These tuples form the initial tuple stream that serves as input to the next clause of the FLWOR expression. If ordering mode is ordered, the order of tuples in the tuple stream is the order in which their start items appear in the binding sequence; otherwise the order of the tuple stream is implementation-dependent. The cardinality of the tuple stream is equal to the number of windows.

If a window clause is an intermediate clause in a FLWOR expression, each input tuple generates zero or more output tuples, each consisting of the original bound variables of the input tuple plus the new bound variables that represent one of the generated windows. For each tuple T in the input tuple stream, the output tuple stream will contain NT tuples, where NT is the number of windows generated by the window clause, given the bindings in the input tuple T. Input tuples for which no windows are generated are not represented in the output tuple stream. If ordering mode is ordered, the order of tuples in the output stream is determined primarily by the order of the input tuples from which they were derived, and secondarily by the order in which their start items appear in the binding sequence. If ordering mode is unordered, the order of tuples in the output stream is implementation-dependent.

The following example illustrates a window clause that is the initial clause in a FLWOR expression. The example is based on input data that consists of a sequence of closing stock prices for a specific company. For this example we assume the following input data (assume that the price elements have a validated type of xs:decimal):

<stock>
  <closing> <date>2008-01-01</date> <price>105</price> </closing>
  <closing> <date>2008-01-02</date> <price>101</price> </closing>
  <closing> <date>2008-01-03</date> <price>102</price> </closing>
  <closing> <date>2008-01-04</date> <price>103</price> </closing>
  <closing> <date>2008-01-05</date> <price>102</price> </closing>
  <closing> <date>2008-01-06</date> <price>104</price> </closing>
</stock>

A user wishes to find "run-ups," which are defined as sequences of dates that begin with a "low" and end with a "high" price (that is, the stock price begins to rise on the first day of the run-up, and continues to rise or remain even through the last day of the run-up.) The following query uses a tumbling window to find run-ups in the input data:

for tumbling window $w in //closing
   start $first next $second when $first/price &lt; $second/price
   end $last next $beyond when $last/price &gt; $beyond/price
return
   &lt;run-up&gt;
      &lt;start-date&gt;{fn:data($first/date)}&lt;/start-date&gt;
      &lt;start-price&gt;{fn:data($first/price)}&lt;/start-price&gt;
      &lt;end-date&gt;{fn:data($last/date)}&lt;/end-date&gt;
      &lt;end-price&gt;{fn:data($last/price)}&lt;/end-price&gt;
   &lt;/run-up&gt;

For our sample input data, this tumbling window clause generates a tuple stream consisting of two tuples, each representing a window and containing five bound variables named $w, $first, $second, $last, and $beyond. The return clause is evaluated for each of these tuples, generating the following query result:

&lt;run-up&gt;
   &lt;start-date&gt;2008-01-02&lt;/start-date&gt;
   &lt;start-price&gt;101&lt;/start-price&gt;
   &lt;end-date&gt;2008-01-04&lt;/end-date&gt;
   &lt;end-price&gt;103&lt;/end-price&gt;
&lt;/run-up&gt;
&lt;run-up&gt;
   &lt;start-date&gt;2008-01-05&lt;/start-date&gt;
   &lt;start-price&gt;102&lt;/start-price&gt;
   &lt;end-date&gt;2008-01-06&lt;/end-date&gt;
   &lt;end-price&gt;104&lt;/end-price&gt;
&lt;/run-up&gt;

The following example illustrates a window clause that is an intermediate clause in a FLWOR expression. In this example, the input data contains closing stock prices for several different companies, each identified by a three-letter symbol. We assume the following input data (again assuming that the type of the price element is xs:decimal):

<stocks>
  <closing> <symbol>ABC</symbol> <date>2008-01-01</date> <price>105</price> </closing>
  <closing> <symbol>DEF</symbol> <date>2008-01-01</date> <price>057</price> </closing>
  <closing> <symbol>ABC</symbol> <date>2008-01-02</date> <price>101</price> </closing>
  <closing> <symbol>DEF</symbol> <date>2008-01-02</date> <price>054</price> </closing>
  <closing> <symbol>ABC</symbol> <date>2008-01-03</date> <price>102</price> </closing>
  <closing> <symbol>DEF</symbol> <date>2008-01-03</date> <price>056</price> </closing>
  <closing> <symbol>ABC</symbol> <date>2008-01-04</date> <price>103</price> </closing>
  <closing> <symbol>DEF</symbol> <date>2008-01-04</date> <price>052</price> </closing>
  <closing> <symbol>ABC</symbol> <date>2008-01-05</date> <price>101</price> </closing>
  <closing> <symbol>DEF</symbol> <date>2008-01-05</date> <price>055</price> </closing>
  <closing> <symbol>ABC</symbol> <date>2008-01-06</date> <price>104</price> </closing>
  <closing> <symbol>DEF</symbol> <date>2008-01-06</date> <price>059</price> </closing>
</stocks>

As in the previous example, we want to find "run-ups," which are defined as sequences of dates that begin with a "low" and end with a "high" price for a specific company. In this example, however, the input data consists of stock prices for multiple companies. Therefore it is necessary to isolate the stock prices of each company before forming windows. This can be accomplished by an initial for and let clause, followed by a window clause, as follows:

for $symbol in fn:distinct-values(//symbol)
let $closings := //closing[symbol = $symbol]
for tumbling window $w in $closings
   start $first next $second when $first/price &lt; $second/price
   end $last next $beyond when $last/price &gt; $beyond/price
return
   &lt;run-up symbol="{$symbol}"&gt;
      &lt;start-date&gt;{fn:data($first/date)}&lt;/start-date&gt;
      &lt;start-price&gt;{fn:data($first/price)}&lt;/start-price&gt;
      &lt;end-date&gt;{fn:data($last/date)}&lt;/end-date&gt;
      &lt;end-price&gt;{fn:data($last/price)}&lt;/end-price&gt;
   &lt;/run-up&gt;

Note:

In the above example, the for and let clauses could be rewritten as follows:

for $closings in //closing
let $symbol := $closings/symbol
group by $symbol

The group by clause is described in 4.15.7 Group By Clause.

The for and let clauses in this query generate an initial tuple stream consisting of two tuples. In the first tuple, $symbol is bound to "ABC" and $closings is bound to the sequence of closing elements for company ABC. In the second tuple, $symbol is bound to "DEF" and $closings is bound to the sequence of closing elements for company DEF.

The window clause operates on this initial tuple stream, generating two windows for the first tuple and two windows for the second tuple. The result is a tuple stream consisting of four tuples, each with the following bound variables: $symbol, $closings, $w, $first, $second, $last, and $beyond. The return clause is then evaluated for each of these tuples, generating the following query result:

&lt;run-up symbol="ABC"&gt;
   &lt;start-date&gt;2008-01-02&lt;/start-date&gt;
   &lt;start-price&gt;101&lt;/start-price&gt;
   &lt;end-date&gt;2008-01-04&lt;/end-date&gt;
   &lt;end-price&gt;103&lt;/end-price&gt;
&lt;/run-up&gt;
&lt;run-up symbol="ABC"&gt;
   &lt;start-date&gt;2008-01-05&lt;/start-date&gt;
   &lt;start-price&gt;101&lt;/start-price&gt;
   &lt;end-date&gt;2008-01-06&lt;/end-date&gt;
   &lt;end-price&gt;104&lt;/end-price&gt;
&lt;/run-up&gt;
&lt;run-up symbol="DEF"&gt;
   &lt;start-date&gt;2008-01-02&lt;/start-date&gt;
   &lt;start-price&gt;054&lt;/start-price&gt;
   &lt;end-date&gt;2008-01-03&lt;/end-date&gt;
   &lt;end-price&gt;056&lt;/end-price&gt;
&lt;/run-up&gt;
&lt;run-up symbol="DEF"&gt;
   &lt;start-date&gt;2008-01-04&lt;/start-date&gt;
   &lt;start-price&gt;052&lt;/start-price&gt;
   &lt;end-date&gt;2008-01-06&lt;/end-date&gt;
   &lt;end-price&gt;059&lt;/end-price&gt;
&lt;/run-up&gt;

4.15.5 Where Clause

[70]    WhereClause    ::=    "where" ExprSingle

A where clause serves as a filter for the tuples in its input tuple stream. The expression in the where clause, called the where-expression, is evaluated once for each of these tuples. If the effective boolean value of the where-expression is true, the tuple is retained in the output tuple stream; otherwise the tuple is discarded.

Examples:

  • This example illustrates the effect of a where clause on a tuple stream:

    Input tuple stream:

    ($a = 5, $b = 11)
    ($a = 91, $b = 42)
    ($a = 17, $b = 30)
    ($a = 85, $b = 63)

    where clause:

    where $a &gt; $b

    Output tuple stream:

    ($a = 91, $b = 42)
    ($a = 85, $b = 63)
  • The following query illustrates how a where clause might be used with a positional variable to perform sampling on an input sequence. The query returns one value out of each one hundred input values.

                         for $x at $i in $inputvalues
    where $i mod 100 = 0
    return $x
                      

4.15.6 Count Clause

[69]    CountClause    ::=    "count" "$" VarName

The purpose of a count clause is to enhance the tuple stream with a new variable that is bound, in each tuple, to the ordinal position of that tuple in the tuple stream. The name of the new variable is specified in the count clause.

The output tuple stream of a count clause is the same as its input tuple stream, with each tuple enhanced by one additional variable that is bound to the ordinal position of that tuple in the tuple stream. However, if the name of the new variable is the same as the name of an existing variable in the input tuple stream, the new variable occludes (replaces) the existing variable of the same name, and the number of bound variables in each tuple is unchanged.

The following examples illustrate uses of the count clause:

  • This example illustrates the effect of a count clause on an input tuple stream:

    Input tuple stream:

    ($name = "Bob", $age = 21)
    ($name = "Carol", $age = 19)
    ($name = "Ted", $age = 20)
    ($name = "Alice", $age = 22)

    count clause:

    count $counter

    Output tuple stream:

    ($name = "Bob", $age = 21, $counter = 1)
    ($name = "Carol", $age = 19, $counter = 2)
    ($name = "Ted", $age = 20, $counter = 3)
    ($name = "Alice", $age = 22, $counter = 4)
  • This example illustrates how a counter might be used to filter the result of a query. The query ranks products in order by decreasing sales, and returns the three products with the highest sales. Assume that the variable $products is bound to a sequence of product elements, each of which has name and sales child-elements.

    for $p in $products
    order by $p/sales descending
    count $rank
    where $rank &lt;= 3
    return
       &lt;product rank="{$rank}"&gt;
          {$p/name, $p/sales}
       &lt;/product&gt;

    The result of this query has the following structure:

    &lt;product rank="1"&gt;
       &lt;name&gt;Toaster&lt;/name&gt;
       &lt;sales&gt;968&lt;/sales&gt;
    &lt;/product&gt;
    &lt;product rank="2"&gt;
       &lt;name&gt;Blender&lt;/name&gt;
       &lt;sales&gt;520&lt;/sales&gt;
    &lt;/product&gt;
    &lt;product rank="3"&gt;
       &lt;name&gt;Can Opener&lt;/name&gt;
       &lt;sales&gt;475&lt;/sales&gt;
    &lt;/product&gt;

4.15.7 Group By Clause

[71]    GroupByClause    ::=    "group" "by" GroupingSpecList
[72]    GroupingSpecList    ::=    GroupingSpec ("," GroupingSpec)*
[73]    GroupingSpec    ::=    GroupingVariable (TypeDeclaration? ":=" ExprSingle)? ("collation" URILiteral)?
[74]    GroupingVariable    ::=    "$" VarName

A group by clause generates an output tuple stream in which each tuple represents a group of tuples from the input tuple stream that have equivalent grouping keys. We will refer to the tuples in the input tuple stream as pre-grouping tuples, and the tuples in the output tuple stream as post-grouping tuples.

The group by clause assigns each pre-grouping tuple to a group, and generates one post-grouping tuple for each group. In the post-grouping tuple for a group, each grouping key is represented by a variable that was specified in a GroupingSpec, and every variable that appears in the pre-grouping tuples that were assigned to that group is represented by a variable of the same name, bound to a sequence of all values bound to the variable in any of these pre-grouping tuples. Subsequent clauses in the FLWOR expression see only the variable bindings in the post-grouping tuples; they no longer have access to the variable bindings in the pre-grouping tuples. The number of post-grouping tuples is less than or equal to the number of pre-grouping tuples.

A group by clause contains one or more grouping specifications, as shown in the grammar. [Definition: Each grouping specification specifies one grouping variable, which refers to variable bindings in the pre-grouping tuples. The values of the grouping variables are used to assign pre-grouping tuples to groups.] Each grouping specification may optionally provide an expression to which its grouping variable is bound. If no expression is provided, the grouping variable name must be equal (by the eq operator on expanded QNames) to the name of a variable in the input tuple stream, and it refers to that variable; otherwise a static error is raised [err:XQST0094]. For each grouping specification that contains a binding expression, a let binding is created in the pre-grouping tuples, and the grouping variable refers to that let binding. For example, the clause:

group by $g1, $g2 := $expr1, $g3 := $expr2 collation "Spanish"

is semantically equivalent to the following sequence of clauses:

let $g2 := $expr1
let $g3 := $expr2
group by $g1, $g2, $g3 collation "Spanish"

The process of group formation proceeds as follows:

  1. [Definition: The atomized value of a grouping variable is called a grouping key.] For each pre-grouping tuple, the grouping keys are created by atomizing the values of the grouping variables (in the post-grouping tuples, each grouping variable is set to the value of the corresponding grouping key, as discussed below). If the value of any grouping variable consists of more than one item, a type error is raised [err:XPTY0004]. If a type declaration is present and the resulting atomized value is not an instance of the specified type, a type error is raised [err:XPTY0004].

  2. The input tuple stream is partitioned into groups of tuples whose grouping keys are equivalent. [Definition: Two tuples T1 and T2 have equivalent grouping keys if and only if, for each grouping variable GV, the atomized value of GV in T1 is deep-equal to the atomized value of GV in T2, as defined by applying the function fn:deep-equal using the appropriate collation.] If these values are of different numeric types, and differ from each other by small amounts, then the deep-equal relationship is not transitive, because of rounding effects occurring during type promotion. When comparing three values A, B, and C such that A eq B, B eq C, but A ne C, then the number of items in the result of the function (as well as the choice of which items are returned) is implementation-dependent, subject only to the constraints that (a) no two items in the result sequence compare equal to each other, and (b) every input item that does not appear in the result sequence compares equal to some item that does appear in the result sequence. See Section 14.2.1 fn:distinct-values FO31 for further discussion of this issue in a different context.

    Note:

    The atomized grouping key will always be either an empty sequence or a single atomic value. Defining equivalence by reference to the fn:deep-equal function ensures that the empty sequence is equivalent only to the empty sequence, that NaN is equivalent to NaN, that untypedAtomic values are compared as strings, and that values for which the eq operator is not defined are considered non-equivalent.

  3. The appropriate collation for comparing two grouping keys is the collation specified in the pertinent GroupingSpec if present, or the default collation from the static context otherwise. If the collation is specified by a relative URI, that relative URI is resolved to an absolute URI using the Static Base URI. If the specified collation is not found in statically known collations, a static error is raised [err:XQST0076].

Each group of tuples produced by the above process results in one post-grouping tuple. The pre-grouping tuples from which the group is derived have equivalent grouping keys, but these keys are not necessarily identical (for example, the strings "Frog" and "frog" might be equivalent according to the collation in use.) In the post-grouping tuple, each grouping variable is bound to the value of the corresponding grouping key.

In the post-grouping tuple generated for a given group, each non-grouping variable is bound to a sequence containing the concatenated values of that variable in all the pre-grouping tuples that were assigned to that group. If ordering mode is ordered, the values derived from individual tuples are concatenated in a way that preserves the order of the pre-grouping tuple stream; otherwise the ordering of these values is implementation-dependent.

Note:

This behavior may be surprising to SQL programmers, since SQL reduces the equivalent of a non-grouping variable to one representative value. Consider the following query:

let $x := 64000
for $c in //customer
where $c/salary > $x
group by $d := $c/department
return
<department name="{$d}">
   Number of employees earning more than ${$x} is {count($c)}
</department>

If there are three qualifying customers in the sales department this evaluates to:

<department name="sales">
  Number of employees earning more than $64000 64000 64000 is 3
</department>

In XQuery, each group is a sequence of items that match the group by criteria—in a tree-structured language like XQuery, this is convenient, because further structures can be built based on the items in this sequence. Because there are three items in the group, $x evaluates to a sequence of three items. To reduce this to one item, use fn:distinct-values():

let $x := 64000
for $c in //customer
let $d := $c/department
where $c/salary > $x
group by $d
return
 <department name="{$d}">
  Number of employees earning more than ${distinct-values($x)} is {count($c)}
 </department>

Note:

In general, the static type of a variable in a post-grouping tuple is different from the static type of the variable with the same name in the pre-grouping tuples.

The order in which tuples appear in the post-grouping tuple stream is implementation-dependent.

Note:

An order by clause can be used to impose a value-based ordering on the post-grouping tuple stream. Similarly, if it is desired to impose a value-based ordering within a group (i.e., on the sequence of items bound to a non-grouping variable), this can be accomplished by a nested FLWOR expression that iterates over these items and applies an order by clause. In some cases, a value-based ordering within groups can be accomplished by applying an order by clause on a non-grouping variable before applying the group by clause.

A group by clause rebinds all the variables in the input tuple stream. The scopes of these variables are not affected by the group by clause, but in post-grouping tuples the values of the variables represent group properties rather than properties of individual pre-grouping tuples.

Examples:

  • This example illustrates the effect of a group by clause on a tuple stream.

    Input tuple stream:

    ($storeno = &lt;storeno&gt;S101&lt;/storeno&gt;, $itemno = &lt;itemno&gt;P78395&lt;/itemno&gt;)
    ($storeno = &lt;storeno&gt;S102&lt;/storeno&gt;, $itemno = &lt;itemno&gt;P94738&lt;/itemno&gt;)
    ($storeno = &lt;storeno&gt;S101&lt;/storeno&gt;, $itemno = &lt;itemno&gt;P41653&lt;/itemno&gt;)
    ($storeno = &lt;storeno&gt;S102&lt;/storeno&gt;, $itemno = &lt;itemno&gt;P70421&lt;/itemno&gt;)
    

    group by clause:

    group by $storeno

    Output tuple stream:

    ($storeno = S101, $itemno = (&lt;itemno&gt;P78395&lt;/itemno&gt;, &lt;itemno&gt;P41653&lt;/itemno&gt;))
    ($storeno = S102, $itemno = (&lt;itemno&gt;P94738&lt;/itemno&gt;, &lt;itemno&gt;P70421&lt;/itemno&gt;))
  • This example and the ones that follow are based on two separate sequences of elements, named $sales and $products. We assume that the variable $sales is bound to a sequence of elements with the following structure:

    &lt;sales&gt;
       &lt;storeno&gt;S101&lt;/storeno&gt;
       &lt;itemno&gt;P78395&lt;/itemno&gt;
       &lt;qty&gt;125&lt;/qty&gt;
    &lt;/sales&gt;

    We also assume that the variable $products is bound to a sequence of elements with the following structure:

    &lt;product&gt;
       &lt;itemno&gt;P78395&lt;/itemno&gt;
       &lt;price&gt;25.00&lt;/price&gt;
       &lt;category&gt;Men's Wear&lt;/category&gt;
    &lt;/product&gt;

    The simplest kind of grouping query has a single grouping variable. The query in this example finds the total quantity of items sold by each store:

    for $s in $sales
    let $storeno := $s/storeno
    group by $storeno
    return &lt;store number="{$storeno}" total-qty="{sum($s/qty)}"/&gt;

    The result of this query is a sequence of elements with the following structure:

    &lt;store number="S101" total-qty="1550" /&gt;
    &lt;store number="S102" total-qty="2125" /&gt;
  • In a more realistic example, a user might be interested in the total revenue generated by each store for each product category. Revenue depends on both the quantity sold of various items and the price of each item. The following query joins the two input sequences and groups the resulting tuples by two grouping variables:

    for $s in $sales,
        $p in $products[itemno = $s/itemno]
    let $revenue := $s/qty * $p/price
    group by $storeno := $s/storeno, 
        $category := $p/category
    return
        &lt;summary storeno="{$storeno}"
                  category="{$category}"
                  revenue="{sum($revenue)}"/>
    

    The result of this query is a sequence of elements with the following structure:

    &lt;summary storeno="S101" category="Men's Wear" revenue="10185"/&gt;
    &lt;summary storeno="S101" category="Stationery" revenue="4520"/&gt;
    &lt;summary storeno="S102" category="Men's Wear" revenue="9750"/&gt;
    &lt;summary storeno="S102" category="Appliances" revenue="22650"/&gt;
    &lt;summary storeno="S102" category="Jewelry" revenue="30750"/&gt;
  • The result of the previous example was a "flat" list of elements. A user might prefer the query result to be presented in the form of a hierarchical report, grouped primarily by store (in order by store number) and secondarily by product category. Within each store, the user might want to see only those product categories whose total revenue exceeds $10,000, presented in descending order by their total revenue. This report is generated by the following query:

    for $s1 in $sales
    let $storeno := $s1/storeno
    group by $storeno
    order by $storeno
    return
      &lt;store storeno="{$storeno}"&gt;
        {for $s2 in $s1,
             $p in $products[itemno = $s2/itemno]
         let $category := $p/category,
             $revenue := $s2/qty * $p/price
         group by $category
         let $group-revenue := sum($revenue)
         where $group-revenue &gt; 10000
         order by $group-revenue descending
         return &lt;category name="{$category}" revenue="{$group-revenue}"/&gt;
        }
      &lt;/store&gt;
    

    The result of this example query has the following structure:

    &lt;store storeno="S101"&gt;
       &lt;category name="Men's Wear" revenue="10185"/&gt;
    &lt;/store&gt;
    &lt;store storeno="S102"&gt;
       &lt;category name="Jewelry" revenue="30750"/&gt;
       &lt;category name="Appliances" revenue="22650"/&gt;
    &lt;/store&gt;
  • The following example illustrates how to avoid a possible pitfall in writing grouping queries.

    In each post-grouping tuple, all variables except for the grouping variable are bound to sequences of items derived from all the pre-grouping tuples from which the group was formed. For instance, in the following query, $high-price is bound to a sequence of items in the post-grouping tuple.

    let $high-price := 1000
    for $p in $products[price &gt; $high-price]
    let $category := $p/category
    group by $category
    return
       &lt;category name="{$category}"&gt;
          {fn:count($p)} products have price greater than {$high-price}.
       &lt;/category&gt;

    If three products in the "Men's Wear" category have prices greater than 1000, the result of this query might look (in part) like this:

    &lt;category name="Men's Wear"&gt;
       3 products have price greater than 1000 1000 1000.
    &lt;/category&gt;

    The repetition of "1000" in this query result is due to the fact that $high-price is not a grouping variable. One way to avoid this repetition is to move the binding of $high-price to an outer-level FLWOR expression, as follows:

    let $high-price := 1000
    return
       for $p in $products[price &gt; $high-price]
       let $category := $p/category
       group by $category
       return
          &lt;category name="{$category}"&gt;
             {fn:count($p)} products have price greater than {$high-price}.
          &lt;/category&gt;

    The result of the revised query might contain the following element:

    &lt;category name="Men's Wear"&gt;
       3 products have price greater than 1000.
    &lt;/category&gt;

4.15.8 Order By Clause

[75]    OrderByClause    ::=    (("order" "by") | ("stable" "order" "by")) OrderSpecList
[76]    OrderSpecList    ::=    OrderSpec ("," OrderSpec)*
[77]    OrderSpec    ::=    ExprSingle OrderModifier
[78]    OrderModifier    ::=    ("ascending" | "descending")? ("empty" ("greatest" | "least"))? ("collation" URILiteral)?

The purpose of an order by clause is to impose a value-based ordering on the tuples in the tuple stream. The output tuple stream of the order by clause contains the same tuples as its input tuple stream, but the tuples may be in a different order.

An order by clause contains one or more ordering specifications, called orderspecs, as shown in the grammar. For each tuple in the input tuple stream, the orderspecs are evaluated, using the variable bindings in that tuple. The relative order of two tuples is determined by comparing the values of their orderspecs, working from left to right until a pair of unequal values is encountered. If an orderspec specifies a collation, that collation is used in comparing values of type xs:string, xs:anyURI, or types derived from them (otherwise, the default collation is used in comparing values of these types). If an orderspec specifies a collation by a relative URI, that relative URI is resolved to an absolute URI using the Static Base URI. If an orderspec specifies a collation that is not found in statically known collations, an error is raised [err:XQST0076].

The process of evaluating and comparing the orderspecs is based on the following rules:

  • Atomization is applied to the result of the expression in each orderspec. If the result of atomization is neither a single atomic value nor an empty sequence, a type error is raised [err:XPTY0004].

  • If the value of an orderspec has the dynamic type xs:untypedAtomic (such as character data in a schemaless document), it is cast to the type xs:string.

    Note:

    Consistently treating untyped values as strings enables the sorting process to begin without complete knowledge of the types of all the values to be sorted.

  • If the resulting sequence contains values that are instances of more than one primitive type (meaning the 19 primitive types defined in Section 3.2 Primitive datatypesXS2, then:

    1. If each value is an instance of one of the types xs:string or xs:anyURI, then all values are cast to type xs:string.

    2. If each value is an instance of one of the types xs:decimal or xs:float, then all values are cast to type xs:float.

    3. If each value is an instance of one of the types xs:decimal, xs:float, or xs:double, then all values are cast to type xs:double.

    4. Otherwise, a type error is raised [err:XPTY0004].

      Note:

      The primitive type of an xs:integer value for this purpose is xs:decimal.

For the purpose of determining their relative position in the ordering sequence, the greater-than relationship between two orderspec values W and V is defined as follows:

  • When the orderspec specifies empty least, the following rules are applied in order:

    1. If V is an empty sequence and W is not an empty sequence, then W greater-than V is true.

    2. If V is NaN and W is neither NaN nor an empty sequence, then W greater-than V is true.

    3. If a specific collation C is specified, and V and W are both of type xs:string or are convertible to xs:string by subtype substitution and/or type promotion, then:

      If fn:compare(V, W, C) is less than zero, then W greater-than V is true; otherwise W greater-than V is false.

    4. If none of the above rules apply, then:

      If W gt V is true, then W greater-than V is true; otherwise W greater-than V is false.

  • When the orderspec specifies empty greatest, the following rules are applied in order:

    1. If W is an empty sequence and V is not an empty sequence, then W greater-than V is true.

    2. If W is NaN and V is neither NaN nor an empty sequence, then W greater-than V is true.

    3. If a specific collation C is specified, and V and W are both of type xs:string or are convertible to xs:string by subtype substitution and/or type promotion, then:

      If fn:compare(V, W, C) is less than zero, then W greater-than V is true; otherwise W greater-than V is false.

    4. If none of the above rules apply, then:

      If W gt V is true, then W greater-than V is true; otherwise W greater-than V is false.

  • When the orderspec specifies neither empty least nor empty greatest, the default order for empty sequences in the static context determines whether the rules for empty least or empty greatest are used.

If T1 and T2 are two tuples in the input tuple stream, and V1 and V2 are the first pair of values encountered when evaluating their orderspecs from left to right for which one value is greater-than the other (as defined above), then:

  1. If V1 is greater-than V2: If the orderspec specifies descending, then T1 precedes T2 in the output tuple stream; otherwise, T2 precedes T1 in the output tuple stream.

  2. If V2 is greater-than V1: If the orderspec specifies descending, then T2 precedes T1 in the output tuple stream; otherwise, T1 precedes T2 in the output tuple stream.

If neither V1 nor V2 is greater-than the other for any pair of orderspecs for tuples T1 and T2, the following rules apply.

  1. If stable is specified, the original order of T1 and T2 is preserved in the output tuple stream.

  2. If stable is not specified, the order of T1 and T2 in the output tuple stream is implementation-dependent.

Note:

If two orderspecs return the special floating-point values positive and negative zero, neither of these values is greater-than the other, since +0.0 gt -0.0 and -0.0 gt +0.0 are both false.

Examples:

  • This example illustrates the effect of an order by clause on a tuple stream. The keyword stable indicates that, when two tuples have equal sort keys, their order in the input tuple stream is preserved.

    Input tuple stream:

    ($license = "PFQ519", $make = "Ford",  $value = 16500)
    ($license = "HAJ865", $make = "Honda", $value = 22750)
    ($license = "NKV473", $make = "Ford",  $value = 21650)
    ($license = "RCM922", $make = "Dodge", $value = 11400)
    ($license = "ZBX240", $make = "Ford",  $value = 16500)
    ($license = "KLM030", $make = "Dodge", $value = () )

    order by clause:

    stable order by $make,
       $value descending empty least

    Output tuple stream:

    ($license = "RCM922", $make = "Dodge", $value = 11400)
    ($license = "KLM030", $make = "Dodge", $value = () )
    ($license = "NKV473", $make = "Ford",  $value = 21650)
    ($license = "PFQ519", $make = "Ford",  $value = 16500)
    ($license = "ZBX240", $make = "Ford",  $value = 16500)
    ($license = "HAJ865", $make = "Honda", $value = 22750)
  • The following example shows how an order by clause can be used to sort the result of a query, even if the sort key is not included in the query result. This query returns employee names in descending order by salary, without returning the actual salaries:

    for $e in $employees
    order by $e/salary descending
    return $e/name

Note:

An alternative way of sorting is available from XQuery 3.1 using the fn:sort function. In previous versions of the language, a set of books might be sorted into alphabetic order by title using the FLWOR expression:

for $b in $books/book[price &lt; 100]
order by $b/title
return $b

In XQuery 3.1 the same effect can be achieved using the expression:

sort(
  $books/book[price &lt; 100],
  function($book){ $book/title }
)

4.15.9 Return Clause

[79]    ReturnClause    ::=    "return" ExprSingle

The return clause is the final clause of a FLWOR expression. The return clause is evaluated once for each tuple in its input tuple stream, using the variable bindings in the respective tuples, in the order in which these tuples appear in the input tuple stream. The results of these evaluations are concatenated, as if by the comma operator, to form the result of the FLWOR expression.

The following example illustrates a FLWOR expression containing several clauses. The for clause iterates over all the departments in an input document named depts.xml, binding the variable $d to each department in turn. For each binding of $d, the let clause binds variable $e to all the employees in the given department, selected from another input document named emps.xml (the relationship between employees and departments is represented by matching their deptno values). Each tuple in the resulting tuple stream contains a pair of bindings for $d and $e ($d is bound to a department and $e is bound to a set of employees in that department). The where clause filters the tuple stream, retaining only those tuples that represent departments having at least ten employees. The order by clause orders the surviving tuples in descending order by the average salary of the employees in the department. The return clause constructs a new big-dept element for each surviving tuple, containing the department number, headcount, and average salary.

for $d in fn:doc("depts.xml")//dept
let $e := fn:doc("emps.xml")//emp[deptno eq $d/deptno]
where fn:count($e) >= 10
order by fn:avg($e/salary) descending
return
   <big-dept>
      {
      $d/deptno,
      <headcount>{fn:count($e)}</headcount>,
      <avgsal>{fn:avg($e/salary)}</avgsal>
      }
   </big-dept>

Notes:

  • The order in which items appear in the result of a FLWOR expression depends on the ordering of the input tuple stream to the return clause, which in turn is influenced by order by clauses and by ordering mode. For example, consider the following query, which is based on the same two input documents as the previous example:

    for $d in fn:doc("depts.xml")//dept
    order by $d/deptno
    for $e in fn:doc("emps.xml")//emp[deptno eq $d/deptno]
    return
       &lt;assignment&gt;
          {$d/deptno, $e/name}
       &lt;/assignment&gt;

    The result of this query is a sequence of assignment elements, each containing a deptno element and a name element. The sequence will be ordered primarily by the deptno values because of the order by clause. If ordering mode is ordered, subsequences of assignment elements with equal deptno values will be ordered by the document order of their name elements within the emps.xml document; otherwise the ordering of these subsequences will be implementation-dependent.

  • Parentheses are helpful in return clauses that contain comma operators, since FLWOR expressions have a higher precedence than the comma operator. For example, the following query raises an error because after the comma, $j is no longer within the FLWOR expression, and is an undefined variable:

    let $i := 5,
        $j := 20 * $i
    return $i, $j

    Parentheses can be used to bring $j into the return clause of the FLWOR expression, as the programmer probably intended:

    let $i := 5,
        $j := 20 * $i
    return ($i, $j)

4.16 Ordered and Unordered Expressions

[154]    OrderedExpr    ::=    "ordered" EnclosedExpr
[155]    UnorderedExpr    ::=    "unordered" EnclosedExpr
[40]    EnclosedExpr    ::=    "{" Expr? "}"

The purpose of ordered and unordered expressions is to set the ordering mode in the static context to ordered or unordered for the content expression. For expressions where the ordering of the result is not significant, a performance advantage may be realized by setting the ordering mode to unordered, thereby granting the system flexibility to return the result in the order that it finds most efficient.

Ordering mode affects the behavior of path expressions that include a "/" or "//" operator or an axis step; union, intersect, and except expressions; the fn:id, fn:element-with-id, and fn:idref functions; and certain clauses within a FLWOR expression. If ordering mode is ordered, node sequences returned by path expressions, union, intersect, and except expressions, and the fn:id and fn:idref functions are in document order; otherwise the order of these return sequences is implementation-dependent. The effect of ordering mode on FLWOR expressions is described in 4.15.2 For Clause, 4.15.4.3 Effects of Window Clauses on the Tuple Stream, and 4.15.7 Group By Clause. Ordering mode has no effect on duplicate elimination.

Note:

In a region of a query where ordering mode is unordered, the result of an expression is implementation-dependent if the expression calls certain functions that are affected by the ordering of node sequences. These functions include fn:position, fn:last, fn:index-of, fn:insert-before, fn:remove, fn:reverse, and fn:subsequence. The functions fn:boolean and fn:not are implementation-dependent if ordering mode is unordered and the argument contains at least one node and at least one atomic value (see 2.5.3 Effective Boolean Value). Also, within a path expression in an unordered region, numeric predicates are implementation-dependent. For example, in an ordered region, the path expression (//a/b)[5] will return the fifth qualifying b-element in document order. In an unordered region, the same expression will return an implementation-dependent qualifying b-element.

Note:

The fn:id and fn:idref functions are described in [XQuery and XPath Functions and Operators 4.0] as returning their results in document order. Since ordering mode is a feature of XQuery, relaxation of the ordering requirement for function results when ordering mode is unordered is a feature of XQuery rather than of the functions themselves.

The use of an unordered expression is illustrated by the following example, which joins together two documents named parts.xml and suppliers.xml. The example returns the part numbers of red parts, paired with the supplier numbers of suppliers who supply these parts. If an unordered expression were not used, the resulting list of (part number, supplier number) pairs would be required to have an ordering that is controlled primarily by the document order of parts.xml and secondarily by the document order of suppliers.xml. However, this might not be the most efficient way to process the query if the ordering of the result is not important. An XQuery implementation might be able to process the query more efficiently by using an index to find the red parts, or by using suppliers.xml rather than parts.xml to control the primary ordering of the result. The unordered expression gives the query evaluator freedom to make these kinds of optimizations.

unordered {
  for $p in fn:doc("parts.xml")/parts/part[color = "Red"],
      $s in fn:doc("suppliers.xml")/suppliers/supplier
  where $p/suppno = $s/suppno
  return
    <ps>
       { $p/partno, $s/suppno }
    </ps>
}

In addition to ordered and unordered expressions, XQuery provides a function named fn:unordered that operates on any sequence of items and returns the same sequence in an implementation-defined order. A call to the fn:unordered function may be thought of as giving permission for the argument expression to be materialized in whatever order the system finds most efficient. The fn:unordered function relaxes ordering only for the sequence that is its immediate operand, whereas an unordered expression sets the ordering mode for its operand expression and all nested expressions.

4.17 Conditional Expressions

XQuery 4.0 provides a conditional expression based on the keywords if, then, and else.

In addition, it provides a more concise syntax as a ternary expression using the operators ?? and !!

[88]    IfExpr    ::=    "if" "(" Expr ")" "then" ExprSingle "else" ExprSingle
[48]    TernaryConditionalExpr    ::=    OrExpr ("??" TernaryConditionalExpr "!!" TernaryConditionalExpr)?

Both constructs have the same semantics. There are three expressions, called the test expression, the then-expression, and the the else-expression.

With the keyword syntax, the format is:

if (test-expression) then then-expression else else-expression

With the ternary operator syntax, the format is:

test-expression ?? then-expression !! else-expression

Note:

The ternary operator syntax is borrowed from Perl6.

The first step in processing a conditional expression is to find the effective boolean value of the test expression, as defined in 2.5.3 Effective Boolean Value.

The value of a conditional expression is defined as follows: If the effective boolean value of the test expression is true, the value of the then-expression is returned. If the effective boolean value of the test expression is false, the value of the else-expression is returned.

Conditional expressions have a special rule for propagating dynamic errors: the then and else expressions are guarded, as described in 2.4.5 Guarded Expressions, to prevent spurious dynamic errors.

Here are some examples of conditional expressions:

4.18 Otherwise Expression

[101]    OtherwiseExpr    ::=    UnionExpr ( "otherwise" UnionExpr )*

The otherwise expression returns the value of its first operand, unless this is an empty sequence, in which case it returns the value of its second operand.

For example, @price - (@discount otherwise 0) returns the value of @price - @discount, if the attribute @discount exists, or the value of @price if the @discount attribute is absent.

To prevent spurious errors, the right hand operand is guarded: it cannot throw any dynamic error unless the left-hand operand returns an empty sequence.

Note:

The operator is associative (even under error conditions): A otherwise (B otherwise C) returns the same result as (A otherwise B) otherwise C.

4.19 Switch Expression

[82]    SwitchExpr    ::=    "switch" "(" Expr ")" SwitchCaseClause+ "default" "return" ExprSingle
[83]    SwitchCaseClause    ::=    ("case" SwitchCaseOperand)+ "return" ExprSingle
[84]    SwitchCaseOperand    ::=    ExprSingle

The switch expression chooses one of several expressions to evaluate based on the input value.

In a switch expression, the switch keyword is followed by an expression enclosed in parentheses, called the switch operand expression. This is the expression whose value is being compared. The remainder of the switch expression consists of one or more case clauses, with one or more case operand expressions each, and a default clause.

The first step in evaluating a switch expression is to apply atomization to the value of the switch operand expression. If the result is a sequence of length greater than one, a type error is raised [err:XPTY0004].

The resulting value is matched against each SwitchCaseOperand in turn until a match is found or the list is exhausted. The matching is performed as follows:

  1. The SwitchCaseOperand is evaluated.

  2. The resulting value is atomized.

  3. If the atomized sequence has length greater than one, a type error is raised [err:XPTY0004].

  4. The atomized value of the switch operand expression is compared with the atomized value of the SwitchCaseOperand using the fn:deep-equal function, with the default collation from the static context.

[Definition: The effective case of a switch expression is the first case clause that matches, using the rules given above, or the default clause if no such case clause exists.] The value of the switch expression is the value of the return expression in the effective case.

Switch expressions have rules regarding the propagation of dynamic errors: see 2.4.5 Guarded Expressions. These rules mean that the return clauses of a switch expression must not raise any dynamic errors except in the effective case. Dynamic errors raised in the operand expressions of the switch or the case clauses are propagated; however, an implementation must not raise dynamic errors in the operand expressions of case clauses that occur after the effective case. An implementation is permitted to raise dynamic errors in the operand expressions of case clauses that occur before the effective case, but not required to do so.

The following example shows how a switch expression might be used:

switch ($animal)
   case "Cow" return "Moo"
   case "Cat" return "Meow"
   case "Duck" return "Quack"
   default return "What's that odd noise?"
 

4.20 Quantified Expressions

Quantified expressions support existential and universal quantification. The value of a quantified expression is always true or false.

[80]    QuantifiedExpr    ::=    ("some" | "every") QuantifierBinding ("," QuantifierBinding)* "satisfies" ExprSingle
[81]    QuantifierBinding    ::=    "$" VarName TypeDeclaration? "in" ExprSingle
[202]    TypeDeclaration    ::=    "as" SequenceType

A quantified expression begins with a quantifier, which is the keyword some or every, followed by one or more in-clauses that are used to bind variables, followed by the keyword satisfies and a test expression. Each in-clause associates a variable with an expression that returns a sequence of items, called the binding sequence for that variable. The value of the quantified expression is defined by the following rules:

  1. If the QuantifiedExpr contains more than one QuantifierBinding, then it is equivalent to the expression obtained by replacing each comma with satisfies some or satisfies every respectively. For example, the expression some $x in X, $y in Y satisfies $x = $y is equivalent to some $x in X satisfies some $y in Y satisfies $x = $y, while the expression every $x in X, $y in Y satisfies $x lt $y is equivalent to every $x in X satisfies every $y in Y satisfies $x lt $y

  2. If the quantifier is some, the QuantifiedExpr returns true if at least one evaluation of the test expression has the effective boolean value true; otherwise it returns false. In consequence, if the binding sequence is empty, the result of the QuantifiedExpr is false.

  3. If the quantifier is every, the QuantifiedExpr returns true if every evaluation of the test expression has the effective boolean value true; otherwise it returns false. In consequence, if the binding sequence is empty, the result of the QuantifiedExpr is true.

The scope of a variable bound in a quantified expression comprises all subexpressions of the quantified expression that appear after the variable binding. The scope does not include the expression to which the variable is bound.

Each variable bound in an in-clause of a quantified expression may have an optional type declaration. If the type of a value bound to the variable does not match the declared type according to the rules for SequenceType matching, a type error is raised [err:XPTY0004].

The order in which test expressions are evaluated for the various binding tuples is implementation-dependent. If the quantifier is some, an implementation may return true as soon as it finds one binding tuple for which the test expression has an effective boolean value of true, and it may raise a dynamic error as soon as it finds one binding tuple for which the test expression raises an error. Similarly, if the quantifier is every, an implementation may return false as soon as it finds one binding tuple for which the test expression has an effective boolean value of false, and it may raise a dynamic error as soon as it finds one binding tuple for which the test expression raises an error. As a result of these rules, the value of a quantified expression is not deterministic in the presence of errors, as illustrated in the examples below.

Here are some examples of quantified expressions:

4.21 Try/Catch Expressions

The try/catch expression provides error handling for dynamic errors and type errors raised during dynamic evaluation, including errors raised by the XQuery implementation and errors explicitly raised in a query using the fn:error() function.

[89]    TryCatchExpr    ::=    TryClause CatchClause+
[90]    TryClause    ::=    "try" EnclosedTryTargetExpr
[91]    EnclosedTryTargetExpr    ::=    EnclosedExpr
[92]    CatchClause    ::=    "catch" CatchErrorList EnclosedExpr
[93]    CatchErrorList    ::=    NameTest ("|" NameTest)*
[40]    EnclosedExpr    ::=    "{" Expr? "}"

A try/catch expression catches dynamic errors and type errors raised by the evaluation of the target expression of the try clause. If the the content expression of the try clause does not raise a dynamic error or a type error, the result of the try/catch expression is the result of the content expression.

If the target expression raises a dynamic error or a type error, the result of the try/catch expression is obtained by evaluating the first catch clause that "matches" the error value, as described below. If no catch clause "matches" the error value, then the try/catch expression raises the error that was raised by the target expression. A catch clause with one or more NameTests matches any error whose error code matches one of these NameTests. For instance, if the error code is err:FOER0000, then it matches a catch clause whose ErrorList is err:FOER0000 | err:FOER0001. Wildcards may be used in NameTests; thus, the error code err:FOER0000 also matches a catch clause whose ErrorList is err:* or *:FOER0000 or *.

Within the scope of the catch clause, a number of variables are implicitly declared, giving information about the error that occurred. These variables are initialized as described in the following table:

Variable Type Value
err:code xs:QName The error code
err:description xs:string? A description of the error condition; an empty sequence if no description is available (for example, if the error function was called with one argument).
err:value item()* Value associated with the error. For an error raised by calling the error function, this is the value of the third argument (if supplied).
err:module xs:string? The URI (or system ID) of the module containing the expression where the error occurred, or an empty sequence if the information is not available.
err:line-number xs:integer? The line number within the module where the error occurred, or an empty sequence if the information is not available. The value may be approximate.
err:column-number xs:integer? The column number within the module where the error occurred, or an empty sequence if the information is not available. The value may be approximate.
err:additional item()* Implementation-defined. This variable must be bound so that a query can reference it without raising an error. The purpose of this variable is to allow implementations to provide any additional information that might be useful.

Try/catch expressions have a special rule for propagating dynamic errors. The try/catch expression ignores any dynamic errors encountered in catch clauses other than the first catch clause that matches an error raised by the try clause, and these catch clause expressions need not be evaluated.

Static errors are not caught by the try/catch expression.

If a function call occurs within a try clause, errors raised by evaluating the corresponding function are caught by the try/catch expression. If a variable reference is used in a try clause, errors raised by binding a value to the variable are not caught unless the binding expression occurs within the try clause.

Note:

The presence of a try/catch expression does not prevent an implementation from using a lazy evaluation strategy, nor does it prevent an optimizer performing expression rewrites. However, if the evaluation of an expression inside a try/catch is rewritten or deferred in this way, it must take its try/catch context with it. Similarly, expressions that were written outside the try/catch expression may be evaluated inside the try/catch, but only if they retain their original try/catch behavior. The presence of a try/catch does not change the rules that allow the processor to evaluate expressions in such a way that may avoid the detection of some errors.

Here are some examples of try/catch expressions.

4.22 Expressions on SequenceTypes

The instance of, cast, castable, and treat expressions are used to test whether a value conforms to a given type or to convert it to an instance of a given type.

4.22.1 Instance Of

[104]    InstanceofExpr    ::=    TreatExpr ( "instance" "of" SequenceType )?

The boolean operator instance of returns true if the value of its first operand matches the SequenceType in its second operand, according to the rules for SequenceType matching; otherwise it returns false. For example:

  • 5 instance of xs:integer

    This example returns true because the given value is an instance of the given type.

  • 5 instance of xs:decimal

    This example returns true because the given value is an integer literal, and xs:integer is derived by restriction from xs:decimal.

  • <a>{5}</a> instance of xs:integer

    This example returns false because the given value is an element rather than an integer.

  • (5, 6) instance of xs:integer+

    This example returns true because the given sequence contains two integers, and is a valid instance of the specified type.

  • . instance of element()

    This example returns true if the context item is an element node or false if the context item is defined but is not an element node. If the context item is absentDM31, a dynamic error is raised [err:XPDY0002].

4.22.2 Typeswitch

[85]    TypeswitchExpr    ::=    "typeswitch" "(" Expr ")" CaseClause+ "default" ("$" VarName)? "return" ExprSingle
[86]    CaseClause    ::=    "case" ("$" VarName "as")? SequenceTypeUnion "return" ExprSingle
[87]    SequenceTypeUnion    ::=    SequenceType ("|" SequenceType)*

The typeswitch expression chooses one of several expressions to evaluate based on the dynamic type of an input value.

In a typeswitch expression, the typeswitch keyword is followed by an expression enclosed in parentheses, called the operand expression. This is the expression whose type is being tested. The remainder of the typeswitch expression consists of one or more case clauses and a default clause.

Each case clause specifies one or more SequenceTypes followed by a return expression. [Definition: The effective case in a typeswitch expression is the first case clause in which the value of the operand expression matches a SequenceType in the SequenceTypeUnion of the case clause, using the rules of SequenceType matching. ] The value of the typeswitch expression is the value of the return expression in the effective case. If the value of the operand expression does not match any SequenceType named in a case clause, the value of the typeswitch expression is the value of the return expression in the default clause.

In a case or default clause, if the value to be returned depends on the value of the operand expression, the clause must specify a variable name. Within the return expression of the case or default clause, this variable name is bound to the value of the operand expression. Inside a case clause, the static type of the variable is the union of the SequenceTypes named in the SequenceTypeUnion. Inside a default clause, the static type of the variable is the same as the static type of the operand expression. If the value to be returned by a case or default clause does not depend on the value of the operand expression, the clause need not specify a variable.

The scope of a variable binding in a case or default clause comprises that clause. It is not an error for more than one case or default clause in the same typeswitch expression to bind variables with the same name.

Typeswitch expressions have rules regarding the propagation of dynamic errors: see 2.4.5 Guarded Expressions. These rules mean that a typeswitch expression ignores (does not raise) any dynamic errors encountered in case clauses other than the effective case. Dynamic errors encountered in the default clause are raised only if there is no effective case. An implementation is permitted to raise dynamic errors in the operand expressions of case clauses that occur before the effective case, but not required to do so.

The following example shows how a typeswitch expression might be used to process an expression in a way that depends on its dynamic type.

typeswitch($customer/billing-address)
   case $a as element(*, USAddress) return $a/state
   case $a as element(*, CanadaAddress) return $a/province
   case $a as element(*, JapanAddress) return $a/prefecture
   default return "unknown"

The following example shows a union of sequence types in a single case:

typeswitch($customer/billing-address)
   case $a as element(*, USAddress)
            | element(*, AustraliaAddress)
            | element(*, MexicoAddress)
     return $a/state
   case $a as element(*, CanadaAddress)
     return $a/province
   case $a as element(*, JapanAddress)
     return $a/prefecture
   default
     return "unknown"

4.22.3 Cast

[107]    CastExpr    ::=    ArrowExpr ( "cast" "as" SingleType )?
[201]    SingleType    ::=    SimpleTypeName "?"?
[223]    SimpleTypeName    ::=    TypeName | LocalUnionType
[224]    TypeName    ::=    EQName
[236]    LocalUnionType    ::=    "union" "(" ItemType ("," ItemType)* ")"

Sometimes it is necessary to convert a value to a specific datatype. For this purpose, XQuery 4.0 provides a cast expression that creates a new value of a specific type based on an existing value. A cast expression takes two operands: an input expression and a target type. The type of the atomized value of the input expression is called the input type. The target type must be either of:

  • The name of a type defined in the in-scope schema types, which must be a simple type [err:XQST0052]. In addition, the target type cannot be xs:NOTATION, xs:anySimpleType, or xs:anyAtomicType

  • A LocalUnionType such as union(xs:date, xs:dateTime).

[err:XPST0080]. The optional occurrence indicator "?" denotes that an empty sequence is permitted. If the target type is a lexical QName that has no namespace prefix, it is considered to be in the default type namespace.

Casting a node to xs:QName can cause surprises because it uses the static context of the cast expression to provide the namespace bindings for this operation. Instead of casting to xs:QName, it is generally preferable to use the fn:QName function, which allows the namespace context to be taken from the document containing the QName.

The semantics of the cast expression are as follows:

  1. The input expression is evaluated.

  2. The result of the first step is atomized.

  3. If the result of atomization is a sequence of more than one atomic value, a type error is raised [err:XPTY0004].

  4. If the result of atomization is an empty sequence:

    1. If ? is specified after the target type, the result of the cast expression is an empty sequence.

    2. If ? is not specified after the target type, a type error is raised [err:XPTY0004].

  5. If the result of atomization is a single atomic value, the result of the cast expression is determined by casting to the target type as described in Section 19 Casting FO31. When casting, an implementation may need to determine whether one type is derived by restriction from another. An implementation can determine this either by examining the in-scope schema definitions or by using an alternative, implementation-dependent mechanism such as a data dictionary. The result of a cast expression is one of the following:

    1. A value of the target type (or, in the case of list types, a sequence of values that are instances of the item type of the list type).

    2. A type error, if casting from the source type to the target type is not supported (for example attempting to convert an integer to a date).

    3. A dynamic error, if the particular input value cannot be converted to the target type (for example, attempting to convert the string "three" to an integer).

4.22.4 Castable

[106]    CastableExpr    ::=    CastExpr ( "castable" "as" SingleType )?
[201]    SingleType    ::=    SimpleTypeName "?"?
[236]    LocalUnionType    ::=    "union" "(" ItemType ("," ItemType)* ")"
[223]    SimpleTypeName    ::=    TypeName | LocalUnionType
[224]    TypeName    ::=    EQName
[236]    LocalUnionType    ::=    "union" "(" ItemType ("," ItemType)* ")"

XQuery 4.0 provides an expression that tests whether a given value is castable into a given target type. The target type must be either of:

  • The name of a type defined in the in-scope schema types, which must be a simple type [err:XQST0052]. In addition, the target type cannot be xs:NOTATION, xs:anySimpleType, or xs:anyAtomicType

  • A LocalUnionType such as union(xs:date, xs:dateTime).

The expression E castable as T returns true if the result of evaluating E can be successfully cast into the target type T by using a cast expression; otherwise it returns false. If evaluation of E fails with a dynamic error or if the value of E cannot be atomized, the castable expression as a whole fails. The castable expression can be used as a predicate to avoid errors at evaluation time. It can also be used to select an appropriate type for processing of a given value, as illustrated in the following example:

if ($x castable as hatsize)
   then $x cast as hatsize
   else if ($x castable as IQ)
   then $x cast as IQ
   else $x cast as xs:string

4.22.5 Constructor Functions

For every simple type in the in-scope schema types (except xs:NOTATION and xs:anyAtomicType, and xs:anySimpleType, which are not instantiable), a constructor function is implicitly defined. In each case, the name of the constructor function is the same as the name of its target type (including namespace). The signature of the constructor function for a given type depends on the type that is being constructed, and can be found in Section 18 Constructor functions FO31.

[Definition: The constructor function for a given type is used to convert instances of other simple types into the given type. The semantics of the constructor function call T($arg) are defined to be equivalent to the expression (($arg) cast as T?).]

The following examples illustrate the use of constructor functions:

  • This example is equivalent to ("2000-01-01" cast as xs:date?).

    xs:date("2000-01-01")
  • This example is equivalent to (($floatvalue * 0.2E-5) cast as xs:decimal?).

    xs:decimal($floatvalue * 0.2E-5)
  • This example returns an xs:dayTimeDuration value equal to 21 days. It is equivalent to ("P21D" cast as xs:dayTimeDuration?).

    xs:dayTimeDuration("P21D")
  • If usa:zipcode is a user-defined atomic type in the in-scope schema types, then the following expression is equivalent to the expression ("12345" cast as usa:zipcode?).

    usa:zipcode("12345")

Note:

An instance of an atomic type that is not in a namespace can be constructed by using a URIQualifiedName in either a cast expression or a constructor function call. Examples:

17 cast as Q{}apple
Q{}apple(17)

In either context, using an unqualified NCName might not work: in a cast expression, an unqualified name is resolved using the default type namespace, while an unqualified name in a constructor function call is resolved using the default function namespace which will often be inappropriate.

4.22.6 Treat

[105]    TreatExpr    ::=    CastableExpr ( "treat" "as" SequenceType )?

XQuery 4.0 provides an expression called treat that can be used to modify the static type of its operand.

Like cast, the treat expression takes two operands: an expression and a SequenceType. Unlike cast, however, treat does not change the dynamic type or value of its operand. Instead, the purpose of treat is to ensure that an expression has an expected dynamic type at evaluation time.

The semantics of expr1 treat as type1 are as follows:

  • During static analysis:

    The static type of the treat expression is type1 . This enables the expression to be used as an argument of a function that requires a parameter of type1 .

  • During expression evaluation:

    If expr1 matches type1 , using the rules for SequenceType matching, the treat expression returns the value of expr1 ; otherwise, it raises a dynamic error [err:XPDY0050]. If the value of expr1 is returned, the identity of any nodes in the value is preserved. The treat expression ensures that the value of its expression operand conforms to the expected type at run-time.

  • Example:

    $myaddress treat as element(*, USAddress)

    The static type of $myaddress may be element(*, Address), a less specific type than element(*, USAddress). However, at run-time, the value of $myaddress must match the type element(*, USAddress) using rules for SequenceType matching; otherwise a dynamic error is raised [err:XPDY0050].

4.23 Simple map operator (!)

[121]    SimpleMapExpr    ::=    PathExpr ("!" PathExpr)*

A mapping expression S!E evaluates the expression E once for every item in the sequence obtained by evaluating S. The simple mapping operator "!" can be applied to any sequence, regardless of the types of its items, and it can deliver a mixed sequence of nodes, atomic values, and functions. Unlike the similar "/" operator, it does not sort nodes into document order or eliminate duplicates.

Each operation E1!E2 is evaluated as follows: Expression E1 is evaluated to a sequence S. Each item in S then serves in turn to provide an inner focus (the item as the context item, its position in S as the context position, the length of S as the context size) for an evaluation of E2 in the dynamic context. The sequences resulting from all the evaluations of E2 are combined as follows: Every evaluation of E2 returns a (possibly empty) sequence of items. These sequences are concatenated and returned. If ordering mode is ordered, the returned sequence preserves the orderings within and among the subsequences generated by the evaluations of E2 ; otherwise the order of the returned sequence is implementation-dependent.

Simple map operators have functionality similar to 4.6.1.1 Path operator (/). The following table summarizes the differences between these two operators

Operator Path operator (E1 / E2) Simple map operator (E1 ! E2)
E1 Any sequence of nodes Any sequence of items
E2 Either a sequence of nodes or a sequence of non-node items A sequence of items
Additional processing Duplicate elimination and document ordering Simple sequence concatenation

The following examples illustrate the use of simple map operators combined with path expressions.

  • child::div1 / child::para / string() ! concat("id-", .)

    Selects the para element children of the div1 element children of the context node; that is, the para element grandchildren of the context node that have div1 parents. It then outputs the strings obtained by prepending "id-" to each of the string values of these grandchildren.

  • $emp ! (@first, @middle, @last)

    Returns the values of the attributes first, middle, and last for element $emp, in the order given. (The / operator here returns the attributes in an unpredictable order.)

  • $docs ! ( //employee)

    Returns all the employees within all the documents identified by the variable docs, in document order within each document, but retaining the order of documents.

  • avg( //employee / salary ! translate(., '$', '') ! number(.))

    Returns the average salary of the employees, having converted the salary to a number by removing any $ sign and then converting to a number. (The second occurrence of ! could not be written as / because the left-hand operand of / cannot be an atomic value.)

  • fn:string-join((1 to $n)!"*")

    Returns a string containing $n asterisks.

  • $values!(.*.) => fn:sum()

    Returns the sum of the squares of a sequence of numbers.

  • string-join(ancestor::*!name(), '/')

    Returns a path containing the names of the ancestors of an element, separated by "/" characters.

4.24 Arrow Expressions

[108]    ArrowExpr    ::=    UnaryExpr ( (FatArrowTarget | ThinArrowTarget) )*
[111]    FatArrowTarget    ::=    "=>" ((ArrowStaticFunction ArgumentList) | (ArrowDynamicFunction PositionalArgumentList))
[112]    ThinArrowTarget    ::=    "->" ((ArrowStaticFunction ArgumentList) | (ArrowDynamicFunction PositionalArgumentList) | EnclosedExpr)
[145]    ArrowStaticFunction    ::=    EQName
[146]    ArrowDynamicFunction    ::=    VarRef | ParenthesizedExpr
[136]    ArgumentList    ::=    "(" ((PositionalArguments ("," KeywordArguments)?) | KeywordArguments)? ")"
[137]    PositionalArgumentList    ::=    "(" PositionalArguments? ")"

[Definition: An arrow operator applies a function to the value of an expression, using the value as the first argument to the function.]

The fat arrow operator => is defined as follows:

The thin arrow operator -> is defined as follows:

The fat arrow operator thus applies the supplied function to the result of the left-hand operand as a whole, while the thin arrow operator applies the function (or enclosed expression) to each item in the value of the left-hand operand individually. In the case where the result of the left-hand operand is a single item, the two operators have almost the same effect; the only difference is that the thin arrow binds the focus.

This syntax is particularly helpful when applying multiple functions to a value in turn. For example, the following expression invites syntax errors due to misplaced parentheses:

tokenize((normalize-unicode(upper-case($string))),"\s+")

In the following reformulation, it is easier to see that the parentheses are balanced:

$string -> upper-case() -> normalize-unicode() -> tokenize("\s+")

Assuming that $string is a single string, the above example could equally be written:

$string => upper-case() => normalize-unicode() => tokenize("\s+")

The difference between the two operators is seen when the left-hand operand evaluates to a sequence:

"The cat sat on the mat" => tokenize() -> concat(".") -> upper-case() => string-join(" ")

which returns "THE. CAT. SAT. ON. THE. MAT.". The first arrow could be written either as => or -> because the operand is a singleton; the next two arrows have to be -> because the function is applied to each item in the tokenized sequence individually; the final arrow must be => because the string-join function applies to the sequence as a whole.

Note:

It may be useful to think of this as a map/reduce pipeline. The functions introduced by -> are mapping operations; the function introduced by => is a reduce operation.

The following example introduces an enclosed expression to the pipeline:

(1 to 5) -> xs:double() -> math:sqrt() -> {.+1} => sum()

This is equivalent to sum((1 to 5) ! (math:sqrt(xs:double(.))+1)).

Note:

The ArgumentList may include PlaceHolders, though this is not especially useful. For example, the expression "$" -> concat(?) is equivalent to concat("$", ?): its value is a function that prepends a supplied string with a "$" symbol.

Note:

The ArgumentList may include keyword arguments if the function is identified statically (that is, by name). For example, the following is valid: $xml => xml-to-json(indent:=true()) => parse-json(escape:=false()).

4.25 Validate Expressions

[116]    ValidateExpr    ::=    "validate" (ValidationMode | ("type" TypeName))? "{" Expr "}"
[117]    ValidationMode    ::=    "lax" | "strict"
[40]    EnclosedExpr    ::=    "{" Expr? "}"

A validate expression can be used to validate a document node or an element node with respect to the in-scope schema definitions, using the schema validation process defined in [XML Schema 1.0] or [XML Schema 1.1]. If the operand of a validate expression does not evaluate to exactly one document or element node, a type error is raised [err:XQTY0030]. In this specification, the node that is the operand of a validate expression is called the operand node.

A validate expression returns a new node with its own identity and with no parent. The new node and its descendants are given type annotation that are generated by applying a validation process to the operand node. In some cases, default values may also be generated by the validation process.

A validate expression may optionally specify a validation mode. The default validation mode (applicable when no type name is provided) is strict.

A validate expression may optionally specify a TypeName. This type name must be found in the in-scope schema definitions; if it is not, a static error is raised [err:XQST0104]. If the type name is unprefixed, it is interpreted as a name in the default namespace for elements and types.

The result of a validate expression is defined by the following rules.

  1. If the operand node is a document node, its children must consist of exactly one element node and zero or more comment and processing instruction nodes, in any order; otherwise, a dynamic error [err:XQDY0061] is raised.

  2. The operand node is converted to an XML Information Set ([XML Infoset]) according to the "Infoset Mapping" rules defined in [XQuery and XPath Data Model (XDM) 3.1]. Note that this process discards any existing type annotations. Validity assessment is carried out on the root element information item of the resulting Infoset, using the in-scope schema definitions as the effective schema. The process of validation applies recursively to contained elements and attributes to the extent required by the effective schema.

  3. If a type name is provided, and the type name is xs:untyped, all elements receive the type annotation xs:untyped, and all attributes receive the type annotation xs:untypedAtomic. If the type name is xs:untypedAtomic, the node receives the type annotation xs:untypedAtomic; a type error [err:XPTY0004] is raised if the node has element children. Otherwise, schema-validity assessment is carried out according to the rules defined in [XML Schema 1.0] or [XML Schema 1.1] Part 1, section 3.3.4 "Element Declaration Validation Rules", "Validation Rule: Schema-Validity Assessment (Element)", clauses 1.2 and 2, using this type definition as the "processor-stipulated type definition" for validation.

    If the instance being validated contains an xml:id attribute, both lax and strict validation cause this attribute to be subjected to [xml:id] processing: that is, the attribute is checked for uniqueness, and is typed as xs:ID, and the containing element is therefore eligible as a target for the id() function.

  4. When no type name is provided:

    1. If validation mode is strict, then there must be a top-level element declaration in the in-scope element declarations that matches the root element information item in the Infoset, and schema-validity assessment is carried out using that declaration in accordance with [XML Schema 1.0] Part 1, section 5.2, "Assessing Schema-Validity", item 2, or [XML Schema 1.1] Part 1, section 5.2, "Assessing Schema-Validity", "element-driven validation". If there is no such element declaration, a dynamic error is raised [err:XQDY0084].

    2. If validation mode is lax, then schema-validity assessment is carried out in accordance with [XML Schema 1.0] Part 1, section 5.2, "Assessing Schema-Validity", item 3, or [XML Schema 1.1] Part 1, section 5.2, "Assessing Schema-Validity", "lax wildcard validation".

      If validation mode is lax and the root element information item has neither a top-level element declaration nor an xsi:type attribute, [XML Schema 1.0] defines the recursive checking of children and attributes as optional. During processing of an XQuery validate expression, this recursive checking is required.

    3. If the operand node is an element node, the validation rules named "Validation Root Valid (ID/IDREF)" are not applied. This means that document-level constraints relating to uniqueness and referential integrity are not enforced.

    4. There is no check that the document contains unparsed entities whose names match the values of nodes of type xs:ENTITY or xs:ENTITIES.

    Note:

    Validity assessment is affected by the presence or absence of xsi:type attributes on the elements being validated, and may generate new information items such as default attributes.

  5. The outcome of the validation expression depends on the validity property of the root element information item in the PSVI that results from the validation process.

    1. If the validity property of the root element information item is valid, or if validation mode is lax and the validity property of the root element information item is notKnown, the PSVI is converted back into an XDM instance as described in [XQuery and XPath Data Model (XDM) 3.1] Section 3.3, "Construction from a PSVI". The resulting node (a new node of the same kind as the operand node) is returned as the result of the validate expression.

    2. Otherwise, a dynamic error is raised [err:XQDY0027].

Note:

The effect of these rules is as follows, where the validated element means either the operand node or (if the operand node is a document node) its element child.:

  • If validation mode is strict, the validated element must have a top-level element declaration in the effective schema, and must conform to this declaration.

  • If validation mode is lax, the validated element must conform to its top-level element declaration if such a declaration exists in the effective schema. If validation mode is lax and there is no top-level element declaration for the element, and the element has an xsi:type attribute, then the xsi:type attribute must name a top-level type definition in the effective schema, and the element must conform to that type.

  • If a type name is specified in the validate expression, no attempt is made to locate an element declaration matching the name of the validated element; the element can have any name, and its content is validated against the named type.

Note:

During conversion of the PSVI into an XDM instance after validation, any element information items whose validity property is notKnown are converted into element nodes with type annotation xs:anyType, and any attribute information items whose validity property is notKnown are converted into attribute nodes with type annotation xs:untypedAtomic, as described in Section 3.3.1.1 Element and Attribute Node Types DM31.

4.26 Extension Expressions

[Definition: An extension expression is an expression whose semantics are implementation-defined.] Typically a particular extension will be recognized by some implementations and not by others. The syntax is designed so that extension expressions can be successfully parsed by all implementations, and so that fallback behavior can be defined for implementations that do not recognize a particular extension.

[118]    ExtensionExpr    ::=    Pragma+ "{" Expr? "}"
[119]    Pragma    ::=    "(#" S? EQName (S PragmaContents)? "#)" /* ws: explicit */
[120]    PragmaContents    ::=    (Char* - (Char* '#)' Char*))

An extension expression consists of one or more pragmas, followed by an optional expression (the associated expression). [Definition: A pragma is denoted by the delimiters (# and #), and consists of an identifying EQName followed by implementation-defined content.] The content of a pragma may consist of any string of characters that does not contain the ending delimiter #). If the EQName of a pragma is a lexical QName, it must resolve to a namespace URI and local name, using the statically known namespaces [err:XPST0081]. If the EQName is an unprefixed NCName, it is interpreted as a name in no namespace (and the pragma is therefore ignored).

Each implementation recognizes an implementation-defined set of namespace URIs used to denote pragmas.

If the namespace URI of a pragma's expanded QName is not recognized by the implementation as a pragma namespace, or if the name is in no namespace, then the pragma is ignored. If all the pragmas in an ExtensionExpr are ignored, then the value of the ExtensionExpr is the value of the associated expression; if no associated expression is provided, a static error is raised [err:XQST0079].

If an implementation recognizes the namespace of one or more pragmas in an ExtensionExpr, then the value of the ExtensionExpr, including its error behavior, is implementation-defined. For example, an implementation that recognizes the namespace of a pragma's expanded QName, but does not recognize the local part of the name, might choose either to raise an error or to ignore the pragma.

It is a static error [err:XQST0013] if an implementation recognizes a pragma but determines that its content is invalid.

If an implementation recognizes a pragma, it must report any static errors in the following expression even if it will not evaluate that expression (however, static type errors are raised only if the Static Typing Feature is in effect.)

Note:

The following examples illustrate three ways in which extension expressions might be used.

  • A pragma can be used to furnish a hint for how to evaluate the following expression, without actually changing the result. For example:

    declare namespace exq = "http://example.org/XQueryImplementation";
       (# exq:use-index #)
          { $bib/book/author[name='Berners-Lee'] }
    

    An implementation that recognizes the exq:use-index pragma might use an index to evaluate the expression that follows. An implementation that does not recognize this pragma would evaluate the expression in its normal way.

  • A pragma might be used to modify the semantics of the following expression in ways that would not (in the absence of the pragma) be conformant with this specification. For example, a pragma might be used to permit comparison of xs:duration values using implementation-defined semantics (this would normally be an error). Such changes to the language semantics must be scoped to the enclosed expression following the pragma.

  • A pragma might contain syntactic constructs that are evaluated in place of the following expression. In this case, the following expression itself (if it is present) provides a fallback for use by implementations that do not recognize the pragma. For example:

    declare namespace exq = "http://example.org/XQueryImplementation";
       for $x in
          (# exq:distinct //city by @country #)
          { //city[not(@country = preceding::city/@country)] }
       return f:show-city($x)
    

    Here an implementation that recognizes the pragma will return the result of evaluating the proprietary syntax exq:distinct //city by @country, while an implementation that does not recognize the pragma will instead return the result of the expression //city[not(@country = preceding::city/@country)]. If no fallback expression is required, or if none is feasible, then the expression between the curly braces may be omitted, in which case implementations that do not recognize the pragma will raise a static error.