XQuery 4.0: An XML Query Language

4.13.2 For Clause

A for clause is used for iteration. Each variable in a for clause iterates over a sequence, an array, or a map.

The expression following the keyword in is evaluated; we refer to the resulting sequence, array, or map generically as the binding collection, and to its items, members, or entries as the components of the collection.

• When a ForItemBinding is used (that is, when none of the keywords member, key, or value is used), the range variable is bound in turn to each item in the binding collection, which is treated as a sequence of items.

• When a ForMemberBinding is used (that is, when the keyword member is used), the range variable is bound in turn to each member of the array.

  In this case the corresponding ExprSingle must evaluate to a single array, otherwise a type error is raised [err:XPTY0141].In this case the corresponding ExprSingle must evaluate to a single array, otherwise a type error is raised [err:XPTY0141]. However, the coercion rules also allow a JNode whose ·content· is an array to be supplied.In this case the corresponding ExprSingle must evaluate to a single array, otherwise a type error is raised [err:XPTY0141]. However, the coercion rules also allow a JNode whose ·content· is an array to be supplied.

• When a ForEntryBinding is used (that is, when either or both of the keywords key and value are used), the key range variable (if present) is bound in turn to each key in the map (in entry order^DM), and the value range variable (if present) is bound to the corresponding value.

  In this case the corresponding ExprSingle must evaluate to a single map, otherwise a type error is raised [err:XPTY0141].In this case the corresponding ExprSingle must evaluate to a single map, otherwise a type error is raised [err:XPTY0141]. However, the coercion rules also allow a JNode whose ·content· is a map to be supplied.In this case the corresponding ExprSingle must evaluate to a single map, otherwise a type error is raised [err:XPTY0141]. However, the coercion rules also allow a JNode whose ·content· is a map to be supplied.

  If both the key and value variables are declared, their expanded QNames must be distinct [err:XQST0089].

If a for clause contains multiple bindings separated by commas it is semantically equivalent to multiple for clauses, each containing one of the bindings in the original for clause.

Example:

• The clause

  for $x in $expr1, $y in $expr2

  is semantically equivalent to:

  for $x in $expr1
  for $y in $expr2

• The clause

  for member $x in $expr1, member $y in $expr2

  is semantically equivalent to:

  for member $x in $expr1
  for member $y in $expr2

In the remainder of this section, we define the semantics of a for clause containing a single variable and an associated expression (following the keyword in) whose value is the binding collection for that variable.

If a single-variable for clause is the initial clause in a FLWOR expression, it iterates over its binding collection, binding the variable(s) to each component in turn. The resulting sequence of variable bindings becomes the initial tuple stream that serves as input to the next clause of the FLWOR expression. The order of tuples in the tuple stream preserves the order of the binding collection.

If the binding collection is empty, the output tuple stream depends on whether allowing empty is specified. If allowing empty is specified, the output tuple stream consists of one tuple in which the variable is bound to an empty sequence. This option is not available when the keywords member, key, or value are used. If allowing empty is not specified, the output tuple stream consists of zero tuples.

The following examples illustrates tuple streams that are generated by initial for clauses:

• Initial clause:

  for $x in (100, 200, 300)

  or (equivalently):

  for $x allowing empty in (100, 200, 300)

  Output tuple stream:

  ($x = 100)
  ($x = 200)
  ($x = 300)

• Initial clause:

  for $x in ()

  Output tuple stream contains no tuples.

• Initial clause:

  for $x allowing empty in ()

  Output tuple stream:

  ($x = ())

• Initial clause:

  for member $x in [ 1, 2, (5 to 10) ]

  Output tuple stream:

  ($x = (1))
  ($x = (2))
  ($x = (5, 6, 7, 8, 9, 10)

• Initial clause:

  for member $x in []

  Output tuple stream contains no tuples.

• Initial clause:

  for key $k value $v in { 'x': 1, 'y': 2 }

  Output tuple stream:

  ($k = 'x', $v = 1)
  ($k = 'y', $v = 2)

[Definition: A positional variable is a variable that is preceded by the keyword at.] A positional variable may be associated with the range variable(s) that are bound in a for clause. In this case, as the main range variable(s) iterate over the components of its binding collection, the positional variable iterates over the integers that represent the ordinal numbers of these component in the binding collection, starting with one. Each tuple in the output tuple stream contains bindings for both the main variable and the positional variable. If the binding collection is empty and allowing empty is specified, the positional variable in the output tuple is bound to the integer zero. Positional variables have the implied type xs:integer.

The expanded QName of a positional variable must be distinct from the expanded QName of the main variable with which it is associated [err:XQST0089].

The following examples illustrate how a positional variable would have affected the results of the previous examples that generated tuples:

• Initial clause:

  for $x at $i in (100, 200, 300)

  Output tuple stream:

  ($x = 100, $i = 1)
  ($x = 200, $i = 2)
  ($x = 300, $i = 3)

• Initial clause:

  for $x at $i in [1 to 3, 11 to 13, 21 to 23

  Output tuple stream:

  ($x = (1, 2, 3), $i = 1)
  ($x = (11, 12, 13), $i = 2)
  ($x = (21, 22, 23), $i = 3)

• Initial clause:

  for $x allowing empty at $i in ()

  Output tuple stream:

  ($x = (), $i = 0)

If a single-variable for clause is an intermediate clause in a FLWOR expression, its binding collection is evaluated for each input tuple, given the bindings in that input tuple. Each input tuple generates zero or more tuples in the output tuple stream. Each of these output tuples consists of the original variable bindings of the input tuple plus a binding of the new variable to one of the items in its binding collecction.

For a given input tuple, if the binding collection for the new variable in the for clause is empty (that is, it is an empty sequence or an empty array^DM depending on whether member is specified), and if allowing empty is not specified, the input tuple generates zero output tuples (it is not represented in the output tuple stream.)

The allowing empty option is available only when processing sequences, not when processing arrays or maps. The effect is that if the binding collection is an empty sequence, the input tuple generates one output tuple, with the original variable bindings plus a binding of the new variable to an empty sequence.

If the new variable introduced by a for clause has an associated positional variable, the output tuples generated by the for clause also contain bindings for the positional variable. In this case, as the new variable is bound to each item in its binding collection, the positional variable is bound to the ordinal position of that item within the binding collection, starting with one. Note that, since the positional variable represents a position within a binding collection, the output tuples corresponding to each input tuple are independently numbered, starting with one. For a given input tuple, if the binding collection is empty and allowing empty is specified, the positional variable in the output tuple is bound to the integer zero.

The tuples in the output tuple stream are ordered primarily by the order of the input tuples from which they are derived, and secondarily by the order of the binding sequence for the new variable; otherwise the order of the output tuple stream is implementation-dependent.

The following examples illustrates the effects of intermediate for clauses:

• Input tuple stream:

  ($x = 1)
  ($x = 2)
  ($x = 3)
  ($x = 4)

  Intermediate for clause:

  for $y in ($x to 3)

  Output tuple stream:

  ($x = 1, $y = 1)
  ($x = 1, $y = 2)
  ($x = 1, $y = 3)
  ($x = 2, $y = 2)
  ($x = 2, $y = 3)
  ($x = 3, $y = 3)

  Note:

  In this example, there is no output tuple that corresponds to the input tuple ($x = 4) because, when the for clause is evaluated with the bindings in this input tuple, the resulting binding collection for $y is empty.

• This example shows how the previous example would have been affected by a positional variable (assuming the same input tuple stream):

  for $y at $j in ($x to 3)

  Output tuple stream:

  ($x = 1, $y = 1, $j = 1)
  ($x = 1, $y = 2, $j = 2)
  ($x = 1, $y = 3, $j = 3)
  ($x = 2, $y = 2, $j = 1)
  ($x = 2, $y = 3, $j = 2)
  ($x = 3, $y = 3, $j = 1)

• This example shows how the previous example would have been affected by allowing empty. Note that allowing empty causes the input tuple ($x = 4) to be represented in the output tuple stream, even though the binding sequence for $y contains no items for this input tuple. This example illustrates that allowing empty in a for clause serves a purpose similar to that of an “outer join” in a relational database query. (Assume the same input tuple stream as in the previous example.)

  for $y allowing empty at $j in ($x to 3)

  Output tuple stream:

  ($x = 1, $y = 1, $j = 1)
  ($x = 1, $y = 2, $j = 2)
  ($x = 1, $y = 3, $j = 3)
  ($x = 2, $y = 2, $j = 1)
  ($x = 2, $y = 3, $j = 2)
  ($x = 3, $y = 3, $j = 1)
  ($x = 4, $y = (), $j = 0)

• This example illustrates processing of arrays:

  Input tuple stream:

  ($x = 1)
  ($x = 2)
  ($x = 3)

  Intermediate for clause:

  for member $y in [[$x+1, $x+2], [[$x+3, $x+4]]

  Output tuple stream:

  ($x = 1, $y = [ 2, 3 ])
  ($x = 1, $y = [ 4, 5 ])
  ($x = 2, $y = [ 3, 4 ])
  ($x = 2, $y = [ 5, 6 ])
  ($x = 3, $y = [ 4, 5 ])
  ($x = 3, $y = [ 6, 7 ])

• This example shows how a for clause that binds two variables is semantically equivalent to two for clauses that bind one variable each. We assume that this for clause occurs at the beginning of a FLWOR expression. It is equivalent to an initial single-variable for clause that provides an input tuple stream to an intermediate single-variable for clause.

  for $x in (1, 2, 3, 4), $y in ($x to 3)

  Output tuple stream:

  ($x = 1, $y = 1)
  ($x = 1, $y = 2)
  ($x = 1, $y = 3)
  ($x = 2, $y = 2)
  ($x = 2, $y = 3)
  ($x = 3, $y = 3)

A for clause may contain one or more type declarations, identified by the keyword as. The semantics of type declarations are defined in 4.13.1 Variable Bindings.