they are not directly related to annotations. If an implementation
defines the annotation blue
and uses it in function
declarations, there is no guarantee that it will also define a
function assertion blue
, or that a function assertion
named blue
matches a function declared with the
annotation blue
. Of course, an implementation that
does so may be more intuitive to users.
Implementations must not define function assertions in the following reserved namespaces; it is an error for users to create function assertions in the following reserved namespaces [err:XQST0045]:
http://www.w3.org/XML/1998/namespace
http://www.w3.org/2001/XMLSchema
http://www.w3.org/2001/XMLSchema-instance
http://www.w3.org/2005/xpath-functions
http://www.w3.org/2005/xpath-functions/math
http://www.w3.org/2012/xquery
Here are some examples of FunctionTests:
function(*)
matches any functionDM30.
%assertion function(*)
matches any functionDM30
if the implementation-defined function assertion
%assertion
is satisfied.
function(int, int) as int
matches any functionDM30
with the function signature function(int, int) as
int
.
%assertion function(int, int) as int
matches any
functionDM30
with the function signature function(int, int) as int
if the implementation-defined function assertion
%assertion
is satisfied.
A TypedFunctionTest matches an item if it is a functionDM30, and the function's type signature (as defined in Section 2.8.1 Functions DM30) is a subtype of the TypedFunctionTest.
Given two sequence types, it is possible to determine
if one is a subtype of the other. [Definition: A sequence type
A
is a subtype of a sequence type
B
if the judgement subtype(A, B)
is
true.] When the judgement subtype(A, B)
is true, it is
always the case that for any value V
, (V
instance of A)
implies (V instance of B)
.
Note:
The converse is not necessarily true: for example every instance
of union(P, Q)
is also an instance of union(P,
Q, R)
, but there is no subtype relationship between these
two types.
subtype(A,
B)
The judgement subtype(A, B)
determines if the
sequence type
A
is a subtype of the sequence type B
.
A
can either be empty-sequence()
or an
ItemType, Ai
,
possibly followed by an occurrence indicator. Similarly
B
can either be empty-sequence()
or an
ItemType, Bi
,
possibly followed by an occurrence indicator. The result of the
subtype(A, B)
judgement can be determined from the
table below, which makes use of the auxiliary judgement
subtype-itemtype(Ai, Bi)
defined in <IP_ADDRESS> The judgement
subtype-itemtype(Ai, Bi) .
Sequence type B |
||||||
|---|---|---|---|---|---|---|
empty-sequence() |
Bi? |
Bi* |
Bi |
Bi+ |
||
Sequence type A |
empty-sequence() |
true | true | true | false | false |
Ai? |
false | subtype-itemtype(Ai, Bi) |
subtype-itemtype(Ai, Bi) |
false | false | |
Ai* |
false | false | subtype-itemtype(Ai, Bi) |
false | false | |
Ai |
false | subtype-itemtype(Ai, Bi) |
subtype-itemtype(Ai, Bi) |
subtype-itemtype(Ai, Bi) |
subtype-itemtype(Ai, Bi) |
|
Ai+ |
false | false | subtype-itemtype(Ai, Bi) |
false | subtype-itemtype(Ai, Bi) |
subtype-itemtype(Ai, Bi)
The judgement subtype-itemtype(Ai, Bi)
determines
if the ItemType
Ai
is a subtype of the ItemType Bi
.
Ai
is a subtype of Bi
if and only if at
least one of the following conditions applies:
Ai
and Bi
are AtomicOrUnionTypes, and
derives-from(Ai, Bi)
returns true
.
Ai
and Bi
are both pure union types,
and every type t
in the transitive membership of
Ai
is also in the transitive membership of
Bi
.
Bi
is item()
.
Bi
is node()
, and Ai
is a
KindTest.
Bi
is text()
and Ai
is
also text()
.
Bi
is comment()
and Ai
is
also comment()
.
Bi
is namespace-node()
and
Ai
is also namespace-node()
.
Bi
is processing-instruction()
and
Ai
is either processing-instruction()
or
processing-instruction(N)
for any name N.
Bi
is processing-instruction(Bn)
, and
Ai
is also
processing-instruction(Bn)
.
Bi
is document-node()
and
Ai
is either document-node()
or
document-node(E)
for any ElementTest E.
Bi
is document-node(Be)
and
Ai
is document-node(Ae)
, and
subtype-itemtype(Ae, Be)
.
Bi
is either element()
or
element(*)
, and Ai
is an ElementTest.
Bi
is either element(Bn)
or
element(Bn, xs:anyType?)
, the expanded QName of
An
equals the expanded QName of Bn
, and
Ai
is either element(An)
, or
element(An, T?)
for any type T.
Bi
is element(Bn, Bt)
, the expanded QName of
An
equals the expanded QName of Bn
,
Ai
is element(An, At)
, and
derives-from(At, Bt)
returns true
.
Bi
is element(Bn, Bt?)
, the expanded QName of
An
equals the expanded QName of Bn
,
Ai
is either element(An, At)
or
element(An, At?)
, and derives-from(At,
Bt)
returns true
.
Bi
is element(*, Bt)
, Ai
is either element(*, At)
or element(N,
At)
for any name N, and derives-from(At, Bt)
returns true
.
Bi
is element(*, Bt?)
, Ai
is either element(*, At)
, element(*,
At?)
, element(N, At)
, or element(N,
At?)
for any name N, and derives-from(At, Bt)
returns true
.
Bi
is schema-element(Bn)
,
Ai
is schema-element(An)
, and every
element declaration that is an actual member of the substitution
group of An
is also an actual member of the
substitution group of Bn
.
Note:
The fact that P
is a member of the substitution
group of Q
does not mean that every element
declaration in the substitution group of P
is also in
the substitution group of Q
. For example,
Q
might block substitution of elements whose type is
derived by extension, while P
does not.
Bi
is either attribute()
or
attribute(*)
, and Ai
is an AttributeTest.
Bi
is either attribute(Bn)
or
attribute(Bn, xs:anyType)
, the expanded QName of
An
equals the expanded QName of Bn
, and
Ai
is either attribute(An)
, or
attribute(An, T)
for any type T.
Bi
is attribute(Bn, Bt)
, the expanded QName of
An
equals the expanded QName of Bn
,
Ai
is attribute(An, At)
, and
derives-from(At, Bt)
returns true
.
Bi
is attribute(*, Bt)
,
Ai
is either attribute(*, At)
, or
attribute(N, At)
for any name N, and
derives-from(At, Bt)
returns true
.
Bi
is schema-attribute(Bn)
, the
expanded
QName of An
equals the expanded QName of Bn
,
and Ai
is schema-attribute(An)
.
Bi
is [AnnotationsB] function(*)
, Ai
is a FunctionTest with annotations
[AnnotationsA]
, and
subtype-assertions(AnnotationsA, AnnotationsB)
,
where [AnnotationsB]
and [AnnotationsA]
are optional lists of one or more annotations .
Bi
is AnnotationsB function(Ba_1, Ba_2, ... Ba_N) as
Br
, Ai
is AnnotationsA function(Aa_1, Aa_2, ... Aa_M) as
Ar
, where [AnnotationsB]
and [AnnotationsA]
are optional lists of one or more
annotations; N
(arity of Bi) equals
M
(arity of Ai); subtype(Ar, Br)
; for
values of I
between 1 and N
,
subtype(Ba_I, Aa_I)
; and
subtype-assertions(AnnotationsA, AnnotationsB)
.
Note:
Function return types are covariant because this rule invokes subtype(Ar, Br) for return types. Function arguments are contravariant because this rule invokes subtype(Ba_I, Aa_I) for arguments.
subtype-assertions(AnnotationsA, AnnotationsB)
The judgement subtype-assertions(AnnotationsA,
AnnotationsB)
determines if AnnotationsA
is a
subtype of AnnotationsB
, where
AnnotationsA
and AnnotationsB
are
annotation lists from two FunctionTests. It is defined to ignore
annotation assertions in namespaces not understood by the XQuery
implementation. For assertions that are understood, their effect on
the result of subtype-assertions()
is implementation
defined.
The following examples are some possible ways to define
subtype-assertions()
for some implementation defined
assertions in the local
namespace. These examples
assume that some implementation uses annotations to label functions
as deterministic or nondeterministic, and treats deterministic
functions as a subset of nondeterministic functions. In this
implementation, nondeterministic functions are not a subset of
deterministic functions.
AnnotationsA is
%local:inline
It has no influence on the outcome of
subtype-assertions()
.
AnnotationsA is
%local:deterministic
AnnotationsB is
%local:nondeterministic
Since deterministic functions are a subset of nondeterministic
functions, subtype-assertions()
is true.
AnnotationsA contains
%local:nondeterministic
AnnotationsB is empty. If FunctionTests without the
%local:nondeterministic
annotation only match
deterministic functions, subtype-assertions()
must be
false.
| [209] | Comment |
::= | "(:" (CommentContents | Comment)* ":)" |
| [217] | 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 :)
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 3.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 3.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.
| [39] | Expr |
::= | ExprSingle (","
ExprSingle)* |
| [40] | ExprSingle |
::= | FLWORExpr |
The XQuery 3.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.
[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.] Constructors are described in 3.9 Constructors.
| [124] | PrimaryExpr |
::= | Literal |
| [163] | FunctionItemExpr |
::= | NamedFunctionRef | InlineFunctionExpr |
[Definition: A literal is a direct syntactic representation of an atomic value.] XQuery 3.0 supports two kinds of literals: numeric literals and string literals.
| [125] | Literal |
::= | NumericLiteral
| StringLiteral |
| [126] | NumericLiteral |
::= | IntegerLiteral
| DecimalLiteral |
DoubleLiteral |
| [197] | IntegerLiteral |
::= | Digits |
| [198] | DecimalLiteral |
::= | ("." Digits) |
(Digits "." [0-9]*) |
| [199] | DoubleLiteral |
::= | (("." Digits) |
(Digits ("." [0-9]*)?)) [eE]
[+-]? Digits |
| [200] | StringLiteral |
::= | ('"' (PredefinedEntityRef |
CharRef | EscapeQuot | [^"&])* '"') | ("'"
(PredefinedEntityRef |
CharRef | EscapeApos | [^'&])*
"'") |
| [203] | PredefinedEntityRef |
::= | "&" ("lt" | "gt" | "amp" | "quot" | "apos")
";" |
| [204] | EscapeQuot |
::= | '""' |
| [205] | EscapeApos |
::= | "''" |
| [216] | 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
18.2 Casting from xs:string and xs:untypedAtomic
FO30.
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 |
< |
< |
> |
> |
& |
& |
" |
" |
' |
' |
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 €
. 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 & Jerry's"
denotes the
xs:string
value "Ben & Jerry's
".
"€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 atomic 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 [XQuery and XPath Functions and Operators 3.0]. 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 Generalized atomic 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
.
| [127] | VarRef |
::= | "$" VarName |
| [128] | 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.
| [129] | 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 3.4.1 Constructing Sequences.
| [130] | 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 absentDM30, a context item expression raises a dynamic error [err:XPDY0002].
[Definition: The built-in functions supported by XQuery 3.0 are defined in [XQuery and XPath Functions and Operators 3.0].] Additional functions may be declared in a Prolog, imported from a library module, or provided by the external environment as part of the static context.
| [133] | FunctionCall |
::= | EQName ArgumentList |
| [121] | ArgumentList |
::= | "(" (Argument (","
Argument)*)? ")" |
| [134] | Argument |
::= | ExprSingle |
ArgumentPlaceholder |
| [135] | ArgumentPlaceholder |
::= | "?" |
[Definition: A static function call consists of an EQName followed by a parenthesized list of zero or more arguments.] [Definition: An argument to a function call is either an argument expression or an ArgumentPlaceholder ("?").] If the EQName in a static function call is a lexical QName that has no namespace prefix, it is considered to be in the default function namespace.
If the expanded QName and number of arguments in a static function call do not match the name and arity of a function signature in the static context, a static error is raised [err:XPST0017].
[Definition: A static or dynamic function call is a partial function application if one or more arguments is an ArgumentPlaceholder. ]
Evaluation of function calls is described in <IP_ADDRESS> Evaluating Static and Dynamic 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 arguments.
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.
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.
When a static or dynamic function call FC is evaluated with respect to a static context SC and a dynamic context DC, the result is obtained as follows:
[Definition: The number of Argument
s
in an ArgumentList
is its arity. ]
The function to be called or partially applied (call it F) is obtained as follows:
If FC is a static function call: Using the expanded
QName corresponding to FC's EQName
, and the
arity of FC's ArgumentList
, the
corresponding function is looked up in the named functions
component of DC. Let F denote the function
obtained.
If FC is a dynamic function call: FC's
base expression is evaluated with respect to SC
and DC. If this yields a sequence consisting of a
single function with the same arity as the arity of the
ArgumentList
, let F denote that function.
Otherwise, a type error is raised [err:XPTY0004].
[Definition: Argument expressions are evaluated with respect to DC , producing argument values.] The order of argument evaluation is implementation-dependent and a function need not evaluate an argument if the function can evaluate its body without evaluating that argument.
Each argument value is converted to the corresponding parameter type in F's signature by applying the function conversion rules, resulting in a converted argument value.
The remainder depends on whether or not FC is a partial function application.
If FC is a partial function application:
[Definition: In a partial function application,
a fixed position is an argument/parameter position for which
the ArgumentList
has an argument expression (as
opposed to an ArgumentPlaceholder
). ] (Note that a
partial function application need not have any fixed
positions.)
A new function is returned (as the value of FC), with the following properties (as defined in Section 2.8.1 Functions DM30):
name: Absent.
parameter names: The parameter names of F, removing the parameter names at the fixed positions. (So the function's arity is the arity of F minus the number of fixed positions.)
signature: The signature of F, removing the parameter type at each of the fixed positions.
implementation: The implementation of F , associated with the same contexts as in F. If these contexts are absent in F, it is associated with SC and DC.
nonlocal variable bindings: The nonlocal variable bindings of F, plus, for each fixed position, a binding of the converted argument value to the corresponding parameter name.
If FC is not a partial function application:
If F's implementation is implementation-dependent (e.g., it is a built-in function or external function , or a partial application of such a function):
F's implementation is invoked with the converted argument values using the contexts it is associated with in F. If these contexts are absent in F, it is associated with SC and DC.
The result is either an instance of F's return type or a dynamic error. This result is then the result of evaluating FC.
Errors raised by built-in functions are defined in [XQuery and XPath Functions and Operators 3.0].
Errors raised by external functions are implementation-defined (see 2.2.5 Consistency Constraints).
If F's implementation is a
FunctionBody
:
The FunctionBody
's static and dynamic
contexts are augmented as follows:
The focus (context item, context position, and context size) is absentDM30.
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 value retains its most specific dynamic type, even though this type may
be derived from the type of the formal parameter. For example, a
function with a parameter $p
of type
xs:decimal
can be invoked with an argument of type
xs:integer
, which is derived from
xs:decimal
. During the processing of this function
call, the dynamic type of $p
inside the
body of the function is considered to be
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.)
The value returned by evaluating the function body is then converted to the declared return type of F by applying the function conversion rules. The result is then the result of evaluating FC.
As with argument values, the value returned by a
function retains its most specific type, which may be derived from
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
.
[Definition: The function conversion rules are used to convert an argument value or a return value to its expected type; that is, to the declared type of the function parameter or return. ] The expected type is expressed as a sequence type. The function conversion rules are applied to a given value as follows:
If the expected type is a sequence of a generalized atomic type (possibly
with an occurrence indicator *
, +
, or
?
), the following conversions are applied:
Atomization is applied to the given value, resulting in a sequence of atomic values.
Each item in the atomic sequence that is of type
xs:untypedAtomic
is cast to the expected
generalized atomic type. For built-in
functions where the expected type is specified as numeric, arguments of type
xs:untypedAtomic
are cast to xs:double
.
If the item is of type xs:untypedAtomic
and the
expected type is namespace-sensitive, a type error [err:XPTY0117] is
raised.
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.
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.
If the expected type is a TypedFunctionTest (possibly
with an occurrence indicator *
, +
, or
?
), function coercion is applied to
each function in the given value.
If, after the above conversions, the resulting value does not match the expected type according to the rules for SequenceType Matching, a type error is raised [err:XPTY0004]. If the function call takes place in a module other than the module in which the function is defined, this rule must be satisfied in both the module where the function is called and the module where the function is defined (the test is repeated because the two modules may have different in-scope schema definitions.) Note that the rules for SequenceType Matching permit a value of a derived type to be substituted for a value of its base type.
Function coercion is a transformation applied to functionsDM30 during application of the function conversion rules. [Definition: Function coercion wraps a functionDM30 in a new function with signature the same as the expected type. This effectively delays the checking of the argument and return types until the function is invoked.]
Function coercion is only defined to operate on functionsDM30. Given a function F , and an expected function type, function coercion proceeds as follows: If F and the expected type have different arity, a type error is raised [err:XPTY0004]. Otherwise, coercion returns a new function with the following properties (as defined in Section 2.8.1 Functions DM30):
name: The name of F .
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 invoked.
The function conversion rules applied to the function's arguments and result are defined by the SequenceType it has most recently been coerced to. Additional function conversion rules could apply when the wrapped function is invoked.
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:
The function conversion rules result in applying function
coercion to $f
, wrapping $f in a new function ($p)
with the signature function(xs:string) as
xs:boolean
.
$p is matched against the SequenceType of
function(xs:string) as xs:boolean
, and succeeds.
When $p is invoked inside the predicate, function conversion and
SequenceType matching rules are applied to the context item
argument, resulting in an xs:string
value or a type
error.
$f is invoked with the xs:string
, which returns an
xs:boolean
.
$p applies function conversion rules to the result sequence from
$f, which already matches its declared return type of
xs:boolean
.
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.
| [164] | NamedFunctionRef |
::= | EQName "#" IntegerLiteral |
| [196] | EQName |
::= | QName | URIQualifiedName |
[Definition: A named function reference denotes a named function.] [Definition: A named function is a function defined in the static context for the query. To uniquely identify a particular named function, both its name as an expanded QName and its arity are required.]
If the EQName is a lexical QName that has no namespace prefix, it is considered to be in the default function namespace.
If the expanded QName and arity in a named function reference do not match the name and arity of a function signature in the static context, a static error is raised [err:XPST0017].
The value of a NamedFunctionRef
is the function
obtained by looking up the expanded QName and arity in the
named
functions component of the dynamic context.
Furthermore, if the function referenced by a
NamedFunctionRef
has an implementation-dependent
implementation, then the implementation of the function returned by
the NamedFunctionRef
is associated with the static
context of this NamedFunctionRef
expression and to the
dynamic context in which it is currently being evaluated.
Certain functions in the [XQuery and XPath Functions and Operators 3.0] specification are defined to be polymorphic. These are denoted as accepting parameters of "numeric" type, or returning "numeric" type. Here "numeric" is a pseudonym for the four primitive numeric types xs:decimal, xs:integer, xs:float, and xs:double. For the purposes of named function references, these functions are regarded as taking arguments and producing results of type xs:anyAtomicType, with a type error raised at runtime if the argument value provided is not of the correct numeric type.
Note:
The above way of modeling polymorphic functions is semantically backwards compatible with XQuery 1.0. An implementation that supports static typing can choose to model the types of these functions more accurately if desired.
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.
| [165] | InlineFunctionExpr |
::= | Annotation*
"function" "(" ParamList? ")"
("as" SequenceType)?
FunctionBody |
[Definition: An inline function expression creates an anonymous functionDM30 defined directly in the inline function expression itself.] 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.
If a function parameter is declared using a name but no type, its default type is item()*. If the result type is omitted from an inline function expression, 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 3.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 absentDM30.
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 DM30):
name: Absent.
parameter names: The parameter names in the
InlineFunctionExpr
's ParamList
.
signature: A FunctionTest
constructed from the Annotation
s
and SequenceType
s in the
InlineFunctionExpr
.
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 returns its item()* argument:
function($a) { $a }
This example creates a sequence of functions each of which returns a different node from the default collection.
collection()/(let $a := . return function() { $a })
| [120] | PostfixExpr |
::= | PrimaryExpr
(Predicate | ArgumentList)* |
| [123] | Predicate |
::= | "[" Expr "]" |
| [121] | ArgumentList |
::= | "(" (Argument (","
Argument)*)? ")" |
[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 3.2.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 3.2.2 Dynamic Function
Call .
| [120] | PostfixExpr |
::= | PrimaryExpr
(Predicate | ArgumentList)* |
| [123] | 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 3.3.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 3.4.1 Constructing
Sequences 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:
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 3.11 Ordered
and Unordered Expressions.
Otherwise, the predicate truth value is the effective boolean value of the predicate expression.
| [120] | PostfixExpr |
::= | PrimaryExpr
(Predicate | ArgumentList)* |
| [121] | ArgumentList |
::= | "(" (Argument (","
Argument)*)? ")" |
| [134] | Argument |
::= | ExprSingle |
ArgumentPlaceholder |
| [135] | ArgumentPlaceholder |
::= | "?" |
[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 <IP_ADDRESS> Evaluating Static and Dynamic Function Calls .
The following are examples of some dynamic function calls:
This example invokes 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 invokes it, passing an xs:string
argument:
$f[2]("Hi there")
This example invokes the function $f passing no arguments, and filters the result with a positional predicate:
$f()[2]
| [107] | PathExpr |
::= | ("/" RelativePathExpr?) |
| [108] | 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 3.3.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 above 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 above 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.
| [108] | RelativePathExpr |
::= | StepExpr (("/" |
"//") StepExpr)* |
Relative path expressions are binary operators on step
expressions, which are named E1
and E2
in
this section.
Each non-initial occurrence of "//
" in a path
expression is expanded as described in 3.3.5
Abbreviated Syntax, leaving a sequence of steps separated
by "/
" . This sequence of steps is then evaluated from
left to right. Each item produced by the evaluation of
E1
is used as the context item to evaluate E2
;
the sequences resulting from all the evaluations of E2
are combined to produce a result.
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 /*
.
/
)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.1.2 Dynamic Context. The
sequences resulting from all the evaluations of E2
are
combined as follows:
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.
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.
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 mapping 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()
| [109] | StepExpr |
::= | PostfixExpr |
AxisStep |
| [110] | AxisStep |
::= | (ReverseStep |
ForwardStep) PredicateList |
| [111] | ForwardStep |
::= | (ForwardAxis
NodeTest) | AbbrevForwardStep |
| [114] | ReverseStep |
::= | (ReverseAxis
NodeTest) | AbbrevReverseStep |
| [122] | 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 3.2 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 3.3.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 <IP_ADDRESS> Axes. The available node tests are
described in <IP_ADDRESS> Node Tests.
Examples of steps are provided in 3.3.4
Unabbreviated Syntax and 3.3.5
Abbreviated Syntax.
| [112] | ForwardAxis |
::= | ("child" "::") |
| [115] | ReverseAxis |
::= | ("parent" "::") |
XQuery supports the following axes:
The child
axis contains the children of the context
node, which are the nodes returned by the dm:children
accessor in [XQuery and XPath Data
Model (XDM) 3.0].
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 dm:parent
accessor in [XQuery and XPath Data Model (XDM) 3.0],
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
dm:attributes
accessor in [XQuery and XPath Data Model (XDM) 3.0];
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.
[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.]
| [117] | NodeTest |
::= | KindTest | NameTest |
| [118] | NameTest |
::= | EQName | Wildcard |
| [119] | Wildcard |
::= | "*" |
| [196] | EQName |
::= | QName | URIQualifiedName |
[Definition: A node test that consists only of an
EQName or a Wildcard is called a name test.] A name test 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/type 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 2.5.4 SequenceType Syntax and 2.5.5 SequenceType 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.
| [110] | AxisStep |
::= | (ReverseStep |
ForwardStep) PredicateList |
| [122] | PredicateList |
::= | Predicate* |
| [123] | 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.
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 3.3.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
| [113] | AbbrevForwardStep |
::= | "@"? NodeTest |
| [116] | AbbrevReverseStep |
::= | ".." |
The abbreviated syntax permits the following abbreviations:
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
.
If the axis name is omitted from an axis step, the default axis is
child
, with two exceptions: if the axis step contains
an AttributeTest or
SchemaAttributeTest
then the default axis is attribute
; if the axis step
contains namespace-node()
then the default axis is
namespace
.
Note:
In an implementation that does not support the namespace axis, an attempt to access it always raises an error. Thus, an XQuery implementation will always raise an error in this case, since XQuery does not support the namespace axis. 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.
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.
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 3.1.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.
XQuery 3.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)
.
| [39] | Expr |
::= | ExprSingle (","
ExprSingle)* |
| [87] | RangeExpr |
::= | AdditiveExpr (
"to" AdditiveExpr
)? |
[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)
A range expression can be used to construct a sequence of
consecutive integers. 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?
. 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.
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 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)
| [90] | UnionExpr |
::= | IntersectExceptExpr (
("union" | "|") IntersectExceptExpr
)* |
| [91] | IntersectExceptExpr |
::= | InstanceofExpr
( ("intersect" | "except") InstanceofExpr )* |
XQuery 3.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, [XQuery and XPath Functions and Operators 3.0] includes functions for indexed access to items or sub-sequences of a sequence, for indexed insertion or removal of items in a sequence, and for removing duplicate items from a sequence.
XQuery 3.0 provides arithmetic operators for addition, subtraction, multiplication, division, and modulus, in their usual binary and unary forms.
| [88] | AdditiveExpr |
::= | MultiplicativeExpr ( ("+" |
"-") MultiplicativeExpr
)* |
| [89] | MultiplicativeExpr |
::= | UnionExpr ( ("*" |
"div" | "idiv" | "mod") UnionExpr )* |
| [96] | UnaryExpr |
::= | ("-" | "+")* ValueExpr |
| [97] | 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:
Atomization is applied to the operand. The result of this operation is called the atomized operand.
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.
If the atomized operand is a sequence of length greater than one, a type error is raised [err:XPTY0004].
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]
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 3.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 3.0 supports two division operators named
div
and idiv
. Each of these operators
accepts two operands of any numeric type. As described in [XQuery and XPath Functions and Operators
3.0], $arg1 idiv $arg2
is equivalent to
($arg1 div $arg2) cast as xs:integer?
except for error
cases.
Here are some examples of arithmetic expressions:
The first expression below returns the xs:decimal
value -1.5
, and the second expression returns the
xs:integer
value -1
:
-3 div 2 -3 idiv 2
Subtraction of two date values results in a value of type
xs:dayTimeDuration
:
$emp/hiredate - $emp/birthdate
This example illustrates the difference between a subtraction operator and a hyphen:
$unit-price - $unit-discount
Unary operators have higher precedence than binary operators, subject of course to the use of parentheses. Therefore, the following two examples have different meanings:
-$bellcost + $whistlecost -($bellcost + $whistlecost)
Note:
Multiple consecutive unary arithmetic operators are permitted by XQuery 3.0 for compatibility with [XML Path Language (XPath) Version 1.0].
| [86] | StringConcatExpr |
::= | RangeExpr ( "||"
RangeExpr )* |
String concatenation expressions allow the string
representations of values to be concatenated. In XQuery 3.0,
$a || $b
is equivalent to fn:concat($a,
$b)
. The following expression evaluates to the string
concatenate
:
"con" || "cat" || "enate"
Comparison expressions allow two values to be compared. XQuery 3.0 provides three kinds of comparison expressions, called value comparisons, general comparisons, and node comparisons.
| [85] | ComparisonExpr |
::= | StringConcatExpr ( (ValueComp |
| [99] | ValueComp |
::= | "eq" | "ne" | "lt" | "le" | "gt" | "ge" |
| [98] | GeneralComp |
::= | "=" | "!=" | "<" | "<=" | ">" |
">=" |
| [100] | NodeComp |
::= | "is" | "<<" | ">>" |
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:
Atomization is applied to the operand. The result of this operation is called the atomized operand.
If the 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.
If the atomized operand is a sequence of length greater than one, a type error is raised [err:XPTY0004].
If the 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
).
Next, if possible, the two operands are converted to their least
common type by a combination of type promotion and subtype
substitution. For example, if the operands are of type
hatsize
(derived from xs:integer
) and
shoesize
(derived from xs:float
), their
least common type is xs:float
.
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 3.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 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:
<a>5</a> eq <a>5</a>
<a>5</a> eq <b>5</b>
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")
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:
Atomization is applied to each operand. After atomization, each operand is a sequence of atomic values.
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
. 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]
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.
If both atomic values are instances of
xs:untypedAtomic
, then the values are cast to the type
xs:string
.
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:
If T is a numeric type or is derived from a numeric type, then V
is cast to xs:double
.
If T is xs:dayTimeDuration
or is derived from
xs:dayTimeDuration
, then V is cast to
xs:dayTimeDuration
.
If T is xs:yearMonthDuration
or is derived from
xs:yearMonthDuration
, then V is cast to
xs:yearMonthDuration
.
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.
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 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.
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:
The operands of a node comparison are evaluated in implementation-dependent order.
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.
Each operand must be either a single node or an empty sequence; otherwise a type error is raised [err:XPTY0004].
A comparison with the is
operator is
true
if the two operand nodes have the same identity,
and are thus the same node; otherwise it is false
. See
[XQuery and XPath Data Model (XDM)
3.0] for a definition of node identity.
A comparison with the <<
operator returns
true
if the left operand node precedes the right
operand node in document order; otherwise it returns
false
.
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:
<a>5</a> is <a>5</a>
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"] << /transactions/sale[parcel="33-870"]
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
.
| [83] | OrExpr |
::= | AndExpr ( "or"
AndExpr )* |
| [84] | 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.4.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:
The following expressions return true
:
1 eq 1 and 2 eq 2
1 eq 1 or 2 eq 3
The following expression may return either false
or
raise a dynamic
error:
1 eq 2 and 3 idiv 0 = 1
The following expression may return either true
or
raise a dynamic
error:
1 eq 1 or 3 idiv 0 = 1
The following expression must raise a dynamic error:
1 eq 1 and 3 idiv 0 = 1
In addition to and- and or-expressions, XQuery 3.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 3.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.
XQuery provides constructors that can create XML structures within a query. 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, and computed constructors, which use a notation based on enclosed expressions.
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 in this section.
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 default element/type namespace. Note that
both the statically known namespaces and the default element/type
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.0]. 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 {
and }
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.
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 expressions enclosed in curly braces, 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 <IP_ADDRESS> 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.0]. 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:
Each consecutive sequence of literal characters in the attribute content is processed as a string literal containing those characters, with the following exceptions:
Each occurrence of two consecutive {
characters is
replaced by a single {
character.
Each occurrence of two consecutive }
characters is
replaced by a single }
character.
Each occurrence of EscapeQuot is replaced by a single
"
character.
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.)
Each enclosed expression is converted to a string as follows:
Atomization is applied to the value of the enclosed expression, converting it to a sequence of atomic values.
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.
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.
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
.
The parent
property of the attribute node is set to
the element node constructed by the direct element constructor that
contains this attribute.
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].
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:
<shoe size="7"/>
The string value of the size
attribute is
"7
".
Example:
<shoe size="{7}"/>
The string value of the size
attribute is
"7
".
Example:
<shoe size="{()}"/>
The string value of the size
attribute is the
zero-length string.
Example:
<chapter ref="[{1, 5 to 7, 9}]"/>
The string value of the ref
attribute is "[1
5 6 7 9]
".
Example:
<shoe size="As big as {$hat/@size}"/>
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
.
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 or
to set the default element/type namespace 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 <IP_ADDRESS> 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 the namespace URI specifies
the default element/type namespace of the
constructor expression (overriding any existing default), and is
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, the
default element/type namespace of the
constructor expression is set to absentDM30,
and any no-prefix namespace binding is removed from the in-scope
namespaces of the constructed element.
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/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>
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 expressions enclosed in curly braces. 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:
The content is evaluated to produce a sequence of nodes called the content sequence, as follows:
If the boundary-space policy in the
static
context is strip
, boundary whitespace is
identified and deleted (see <IP_ADDRESS>
Boundary Whitespace for a definition of boundary
whitespace.)
Predefined entity references
and character references are expanded
into their referenced strings, as described in 3.1.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).
Each consecutive sequence of literal characters evaluates to a single text node containing the characters.
Each nested direct constructor is evaluated according to the rules in 3.9.1 Direct Element Constructors or 3.9.2 Other Direct Constructors, resulting in a new element, comment, or processing instruction node. Then:
The parent
property of the resulting node is then
set to the newly constructed element node.
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.
Enclosed expressions are evaluated as follows:
If an enclosed expression returns a functionDM30, a type error is raised [err:XQTY0105].
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.
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:
Each copied node receives a new node identity.
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.
If construction mode in the static context is
strip
:
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
.
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
.
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.
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:
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.
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.
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:
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
.
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.
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.
All other properties of the copied nodes are preserved.
If the content sequence contains a document node, the document node is replaced in the content sequence by its children.
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.
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].
The properties of the newly constructed element node are determined as follows:
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 3.9.1 Direct Element
Constructors.
parent
is set to empty.
attributes
consist of all the attributes specified
in the start tag as described in <IP_ADDRESS> 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].
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.
base-uri
is set to the following value:
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.4.6 Resolving a Relative URI
Reference.
Otherwise, the Static Base URI.
in-scope-namespaces
consist of all the namespace
bindings resulting from namespace declaration attributes as
described in <IP_ADDRESS> Namespace
Declaration Attributes, and possibly additional namespace
bindings as described in 3.9.4 In-scope Namespaces of a
Constructed Element.
The nilled
property is false
.
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.
The typed-value
property is equal to the
string-value
property, as an instance of
xs:untypedAtomic
.
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
.
The is-id
and is-idrefs
properties are
set to false
.
Example:
<a>{1}</a>
The constructed element node has one child, a text node
containing the value "1
".
Example:
<a>{1, 2, 3}</a>
The constructed element node has one child, a text node
containing the value "1 2 3
".
Example:
<c>{1}{2}{3}</c>
The constructed element node has one child, a text node
containing the value "123
".
Example:
<b>{1, "2", "3"}</b>
The constructed element node has one child, a text node
containing the value "1 2 3
".
Example:
<fact>I saw 8 cats.</fact>
The constructed element node has one child, a text node
containing the value "I saw 8 cats.
".
Example:
<fact>I saw {5 + 3} cats.</fact>
The constructed element node has one child, a text node
containing the value "I saw 8 cats.
".
Example:
<fact>I saw <howmany>{5 + 3}</howmany> cats.</fact>
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
".
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

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:
<cat> <breed>{$b}</breed> <color>{$c}</color> </cat>
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:
<a> {"abc"} </a>
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:
<a> z {"abc"}</a>
Since the whitespace surrounding the z
is not
boundary whitespace, it is always preserved. This example is
equivalent to <a> z abc</a>
.
Example:
<a> {"abc"}</a>
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:
<a>{" "}</a>
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.
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.
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.
| [147] | DirPIConstructor |
::= | "<?" PITarget
(S DirPIContents)?
"?>" |
| [148] | DirPIContents |
::= | (Char* - (Char* '?>'
Char*)) |
| [145] | DirCommentConstructor |
::= | "<!--" DirCommentContents
"-->" |
| [146] | DirCommentContents |
::= | ((Char - '-') | ('-'
(Char - '-')))* |
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. The DirPIContents of a processing
instruction must not contain the string "?>
".
The following example illustrates a direct processing instruction constructor:
<?format role="output" ?>
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:
<!-- Tags are ignored in the following section -->
| [151] | ComputedConstructor |
::= | CompDocConstructor |
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.]
[Definition: The final part of a computed constructor is an expression enclosed in braces, called the content expression of the constructor, that generates the content of the node.]
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 3.9.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" } } }
| [153] | CompElemConstructor |
::= | "element" (EQName |
("{" Expr "}")) "{" ContentExpr? "}" |
| [196] | EQName |
::= | QName | URIQualifiedName |
| [154] | ContentExpr |
::= | 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
default element/type 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:
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].
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.
If the atomized value of the name expression is of type
xs:string
or xs:untypedAtomic
, that value
is converted to an expanded QName. If the string value
contains a namespace prefix, that prefix is resolved to a namespace URI
using the statically known namespaces. If the
string value contains no namespace prefix, it is treated as a local
name in the default element/type namespace. The
resulting expanded QName is used as the
node-name
property of the constructed element,
retaining the prefix part of the QName. 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 <IP_ADDRESS> 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:
If the content sequence contains a document node, the document node is replaced in the content sequence by its children.
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.
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].
The properties of the newly constructed element node are determined as follows:
node-name
is the expanded QName resulting from processing
the specified lexical
QName or name expression, as described above.
parent
is empty.
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].
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.
base-uri
is set to the following value:
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.4.6 Resolving a Relative URI
Reference .
Otherwise, the Static Base URI.
in-scope-namespaces
are computed as described in
3.9.4 In-scope Namespaces of
a Constructed Element.
The nilled
property is false
.
The string-value
property is equal to the
concatenated contents of the text-node descendants in document
order.
The typed-value
property is equal to the
string-value
property, as an instance of
xs:untypedAtomic
.
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
.
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.
| [155] | CompAttrConstructor |
::= | "attribute" (EQName |
("{" Expr "}")) "{" Expr? "}" |
| [196] | EQName |
::= | QName | URIQualifiedName |
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:
If the EQName has a BracedURILiteral it is expanded using the specified URI to create an expanded QName; the name of the attribute is constructed using the namespace URI and local name of the expanded QName and an implementation-dependent prefix.
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, the expanded QName is in no namespace.
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:
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].
If the atomized value of the name expression is of type
xs:QName