XML Path Language (XPath) 4.0 WG Review Draft

4.12.1 For Expressions

XPath provides an iteration facility called a for expression. It can be used to iterate over the items of a sequence, the members of an array, or the entries in a map.

A for expression is evaluated as follows:

1. If the ForClause includes multiple ForBindings with a comma separator, the forexpression is first expanded to a set of nested for expressions, each of which contains a single ForBinding. More specifically, every separating comma is replaced by for.

   Example:

   The expression:

   for $x in X, $y in Y return $x + $y

   is expanded to:

   for $x in X for $y in Y return $x + $y

2. Having performed this expansion, variables bound in the ForClause are called the range variables, the variable named in the PositionalVar (if present) is called the position variable, the expression that follows the in keyword is called the binding expression, and the expression in the ForLetReturn part (that is, the following LetExpr or ForExpr, or the ExprSingle that follows the return keyword) is called the return expression.

   [Definition: The result of evaluating the binding expression in a for expression is called the binding collection ].

3. If a position variable is declared, its type is implicitly xs:integer. Its name (as an expanded QName) must be different from the name of a range variable declared in the same ForBinding. [err:XQST0089].

4. When a ForItemBinding is used (that is, when none of the keywords member, key, or value is used), the expression iterates over the items in a sequence:

   1. If a TypeDeclaration is present then each item in the binding collection is converted to the specified type by applying the coercion rules.

   2. The return expression is evaluated once for each item in the binding collection, with a dynamic context in which the range variable is bound to that item, and the position variable (if present) is bound to the one-based position of that item in the binding collection, as an instance of type xs:integer.

   3. The result of the for expression is the sequence concatenation of the results of the successive evaluations of the return expression.

5. When the member keyword is present:

   1. The value of the binding collection must be a single array. Otherwise, a type error is raised: [err:XPTY0141]. The value of the binding collection must be 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. The value of the binding collection must be 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.

   2. If a TypeDeclaration is present then each member of the binding collection array is converted to the specified type by applying the coercion rules. (Recall that this can be any sequence, not necessarily a single item).

   3. The result of the single-variable for member expression is obtained by evaluating the return expression once for each member of that array, with the range variable bound to that member

   4. The return expression is evaluated once for each member of the binding collection array, with a dynamic context in which the range variable is bound to that member, and the position variable (if present) is bound to the one-based position of that member in the binding collection.

   5. The result of the for expression is the sequence concatenation of the results of the successive evaluations of the return expression.

      Note that the result is a sequence, not an array.

6. When the key and/or value keywords are present:

   1. The value of the binding collection must be a single map. Otherwise, a type error is raised: [err:XPTY0141]. The map is treated as a sequence of key/value pairs, in implementation dependent order. The value of the binding collection must be 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. The map is treated as a sequence of key/value pairs, in implementation dependent order. The value of the binding collection must be 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. The map is treated as a sequence of key/value pairs, in implementation dependent order.

   2. If the key keyword is present, then the corresponding variable is bound to the key part of the key/value pair.

   3. If the value keyword is present, then the corresponding variable is bound to the value part of the key/value pair.

   4. If both the key and value keywords are present, then the corresponding variables must have distinct names. [err:XQST0089].

   5. If a TypeDeclaration is present for the key, then each key is converted to the specified type by applying the coercion rules.

   6. If a TypeDeclaration is present for the value, then each value is converted to the specified type by applying the coercion rules.

   7. The result of the single-variable for key/value expression is obtained by evaluating the return expression once for each entry in the map, with the range variables bound to that entry as described.

   8. The return expression is evaluated once for each entry of the binding collection map, with a dynamic context in which the keyrange variable (if present) is bound to the key part of that entry, the valuerange variable (if present) is bound to the value part of that entry, and the position variable (if present) is bound to the one-based position of that entry in the implementation dependent ordering of the binding collection.

   9. The result of the for expression is the sequence concatenation of the results of the successive evaluations of the return expression.

      Note that the result is a sequence, not a map.

The following example illustrates the use of a for expression in restructuring an input document. The example is based on the following input:

<bib>
  <book>
    <title>TCP/IP Illustrated</title>
    <author>Stevens</author>
    <publisher>Addison-Wesley</publisher>
  </book>
  <book>
    <title>Advanced Programming in the Unix Environment</title>
    <author>Stevens</author>
    <publisher>Addison-Wesley</publisher>
  </book>
  <book>
    <title>Data on the Web</title>
    <author>Abiteboul</author>
    <author>Buneman</author>
    <author>Suciu</author>
  </book>
</bib>

The following example transforms the input document into a list in which each author’s name appears only once, followed by a list of titles of books written by that author. This example assumes that the context value is the bib element in the input document.

for $a in distinct-values(book/author)
return ((book/author[. = $a])[1], book[author = $a]/title)

The result of the above expression consists of the following sequence of elements. The titles of books written by a given author are listed after the name of the author. The ordering of author elements in the result is implementation-dependent due to the semantics of the fn:distinct-values function.

<author>Stevens</author>
<title>TCP/IP Illustrated</title>
<title>Advanced Programming in the Unix environment</title>
<author>Abiteboul</author>
<title>Data on the Web</title>
<author>Buneman</author>
<title>Data on the Web</title>
<author>Suciu</author>
<title>Data on the Web</title>

The following example illustrates a for expression containing more than one variable:

for $i in (10, 20),
    $j in (1, 2)
return ($i + $j)

The result of the above expression, expressed as a sequence of numbers, is as follows: 11, 12, 21, 22

The scope of a variable bound in a for expression is the return expression. The scope does not include the expression to which the variable is bound. The following example illustrates how a variable binding may reference another variable bound earlier in the same for expression:

for $x in $z, $y in f($x)
return g($x, $y)

The following example illustrates processing of an array.

for member $map in parse-json('[{ "x": 1, "y": 2 }, { "x": 10, "y": 20 }]') 
return $map ! (?x + ?y)

The result is the sequence (3, 30).

The following example illustrates processing of a map.

for key $key value $value in { "x": 1, "y": 2, "z: 3 }
return `{$key}={$value}`

The result is the sequence ("x=1", "y=2", "z=3") (but not necessarily in that order).

sum(for $i in order-item return @price * @qty)

sum(for $i in order-item return $i!(@price * @qty))

for $order in //orders
for $line in $order/order-line
return $line/value