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].

   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.

   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

4.12.2 Let Expressions

XPath allows a variable to be declared and bound to a value using a let expression.

A let expression is evaluated as follows:

1. If the let expression uses multiple variables, it is first expanded to a set of nested let expressions, each of which uses only one variable. Specifically, any separating comma is replaced by let.

   Example:

   The expression:

   let $x := 4, $y := 3 return $x + $y

   is expanded to:

   let $x := 4 let $y := 3 return $x + $y

2. In a LetValueBinding such as let $V as T := EXPR:

   1. The variable V is called the range variable.

   2. The sequence type T is called the declared type. If there is no declared type, then item()* is assumed.

   3. The expression EXPR is evaluated, and its value is converted to the declared type by applying the coercion rules. The resulting value is called the binding sequence.

3. In a LetSequenceBinding such as let $( $A1 as T1, $A2 as T2, ... , $An as Tn ) as ST := EXPR:

   1. The sequence type ST is called the declared sequence type. If there is no declared sequence type, then item()* is assumed.

   2. The expression EXPR is evaluated, and its value is converted to the declared sequence type ST by applying the coercion rules. Call the resulting (coerced) value V.

   3. Each variable A_i (for i in 1 to n) is effectively replaced by a LetValueBinding of the form let Ai as Ti := items-at(V, i). That is, a range variable named A_i is declared, whose binding sequence is the item V[ i ], after coercion to the type T_i if specified. If T_i is absent, no further coercion takes place (the default is effectively item()?).

      Note:

      If i exceeds the length of the sequence V, then A_i is bound to an empty sequence. This will cause a type error if type T_i does not permit an empty sequence.

      Note:

      It is permissible to bind several variables with the same name; all but the last are shadowed. A useful convention is therefore to bind items in the sequence that are of no interest to the variable $_: for example let $( $_, $_, $x ) := EXPR effectively binds $x to the third item in the sequence and causes the first two items to be ignored.It is permissible to bind several variables with the same name; all but the last are occluded. A useful convention is therefore to bind items in the sequence that are of no interest to the variable $_: for example let $( $_, $_, $x ) := EXPR effectively binds $x to the third item in the sequence and causes the first two items to be ignored.It is permissible to bind several variables with the same name; all but the last are shadowedoccluded. A useful convention is therefore to bind items in the sequence that are of no interest to the variable $_: for example let $( $_, $_, $x ) := EXPR effectively binds $x to the third item in the sequence and causes the first two items to be ignored.

      Example:

      The expression:

      let $( $a, $b as xs:integer, $local:c ) := (2, 4, 6)
      return $a + $b + $local:c

      is expanded to:

      let $temp := (2, 4, 6)
      let $a := fn:items-at($temp, 1)
      let $b as xs:integer := fn:items-at($temp, 2)
      let $local:c := fn:items-at($temp, 3)
      return $a + $b + $local:c

      where $temp is some variable name that is otherwise unused.

       

      Example:

      Consider the element $E := <e A="p q r" B="x y z"/>, where $E has been validated against a schema that defines both attributes A and B as being lists of strings.

      Then the expression:

      let $( $a as xs:string*, $b as xs:string* ) := $E/(@A, @B)

      binds $a to the sequence ("p", "q", "r") and $b to the sequence ("x", "y", "z"). The evaluation of the expression $E/(@A, @B) returns a sequence of two attribute nodes; the value of $a is formed by atomizing the first of these nodes, while $b is formed by atomizing the second.

4. In a LetArrayBinding such as let $[ $A1 as T1, $A2 as T2, ... , $An as Tn ] as AT := EXPR:

   1. The sequence type AT is called the declared array type. If there is no declared array type, then array(*) is assumed.

   2. The expression EXPR is evaluated, and its value is converted to the declared array type AT by applying the coercion rules. A type error [err:XPTY0004] is raised if the result is not a singleton array. Call the resulting (coerced) value V.

   3. Each variable A_i (for i in 1 to n) is effectively replaced by a LetValueBinding of the form let Ai as Ti := array:get(V, i, ()). That is, a range variable named A_i is declared, whose binding sequence is the array member V ? i, after coercion to the type T_i if specified. If T_i is absent, no further coercion takes place (the default is effectively item()*).

      Note:

      If i exceeds the length of the array V, then A_i is bound to an empty sequence. This will cause a type error if type T_i does not permit an empty sequence.

      Note:

      It is permissible to bind several variables with the same name; all but the last are shadowed. A useful convention is therefore to bind items in the sequence that are of no interest to the variable $_: for example let $( $_, $_, $x ) := EXPR effectively binds $x to the third item in the sequence and causes the first two items to be ignored.It is permissible to bind several variables with the same name; all but the last are occluded. A useful convention is therefore to bind items in the sequence that are of no interest to the variable $_: for example let $( $_, $_, $x ) := EXPR effectively binds $x to the third item in the sequence and causes the first two items to be ignored.It is permissible to bind several variables with the same name; all but the last are shadowedoccluded. A useful convention is therefore to bind items in the sequence that are of no interest to the variable $_: for example let $( $_, $_, $x ) := EXPR effectively binds $x to the third item in the sequence and causes the first two items to be ignored.

      Example:

      The expression:

      let $[ $a, $b as xs:integer, $local:c ] := [ 2, 4, 6 ]
      return $a + $b + $local:c

      is expanded to:

      let $temp := [ 2, 4, 6 ]
      let $a := array:get($temp, 1, ())
      let $b as xs:integer := array:get($temp, 2, ())
      let $local:c := array:get($temp, 3, ())
      return $a + $b + $local:c

      where $temp is some variable name that is otherwise unused.

5. In a LetMapBinding such as let ${ $A1 as T1, $A2 as T2, ... , $An as Tn } as MT := EXPR:

   1. The sequence type MT is called the declared map type. If there is no declared map type, then map(*) is assumed.

   2. The expression EXPR is evaluated, and its value is converted to the declared map type MT by applying the coercion rules. A type error [err:XPTY0004] is raised if the result is not a singleton map. Call the resulting (coerced) value V.

   3. Each variable A_i (for i in 1 to n) is effectively replaced by a LetValueBinding of the form let Ai as Ti := map:get(V, "Ni", ()), where N_i is the local part of the name of the variable A_i. That is, a range variable named A_i is declared, whose binding sequence is the value of the map entry in V whose key is xs:string (or xs:anyURI or xs:untypedAtomic) equal to the local part of the variable name, after coercion to the type T_i if specified. If T_i is absent, no further coercion takes place (the default is effectively item()*).Each variable A_i (for i in 1 to n) is effectively replaced by a LetValueBinding of the form let Ai as Ti := map:get(V, "Ni", ()), where N_i is the local part of the name of the variable A_i. That is, a range variable named A_i is declared, whose binding sequence is the value of the map entry in V whose key is an xs:string (or xs:anyURI or xs:untypedAtomic) equal to the local part of the variable name, after coercion to the type T_i if specified. If T_i is absent, no further coercion takes place (the default is effectively item()*).Each variable A_i (for i in 1 to n) is effectively replaced by a LetValueBinding of the form let Ai as Ti := map:get(V, "Ni", ()), where N_i is the local part of the name of the variable A_i. That is, a range variable named A_i is declared, whose binding sequence is the value of the map entry in V whose key is an xs:string (or xs:anyURI or xs:untypedAtomic) equal to the local part of the variable name, after coercion to the type T_i if specified. If T_i is absent, no further coercion takes place (the default is effectively item()*).

      Note:

      If there is no entry in the map with a key corresponding to the variable name, then the variable A_i is bound to an empty sequence. This will cause a type error if type T_i does not permit an empty sequence.

      Note:

      It is not possible to use this mechanism to bind variables to values in a map unless the keys in the map are strings in the form of NCNames.

      Example:

      The expression:

      let ${ $a, $b as xs:integer, $local:c } := { "a": 2, "b": 4, "c": 6, "d": 8 }
      return $a + $b + $local:c

      is expanded to:

      let $temp := { "a": 2, "b": 4, "c": 6 }
      let $a := map:get($temp, "a", ())
      let $b as xs:integer := map:get($temp, "b", ())
      let $local:c := map:get($temp, "c", ())
      return $a + $b + $local:c

      where $temp is some variable name that is otherwise unused.

6. 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. The result of the let expression is obtained by evaluating the return expression with a dynamic context in which each range variable is bound to the corresponding binding sequence.

The scope of a variable bound in a let 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 let expression:

let $x := doc('a.xml')/*, $y := $x//*
return $y[@value gt $x/@min]

let $x := "[A fine romance]"
let $x := substring-after($x, "[")
let $x := substring-before($x, "]")
return upper-case($x)