The operator "?", known as the lookup operator, returns values found in the operand map or array.
A postfix Lookup has two parts: the left hand operand selects maps or arrays to be searched, and the KeySelector defines the search criteria.
First a simple example: given an array $array of maps:
[ { "John": 3, "Jill": 5}, {"Peter": 8, "Mary": 6} ]$array?1?John returns 3
$array?2?Mary returns 6
$array?*?* returns (3, 5, 8, 6)
$array?2?* returns (8, 6)
$array?*?Peter returns 8
'Peter' -> $array?*?. returns 8
The value of the left-hand operand must be a sequence of maps or arrays (but if it includes JNodes, these will be coerced to maps or arrays by extracting the ·content· property of the JNode). The lookup operation is applied independently to each of these maps or arrays, and the final expression result is the sequence concatenation of the individual results.
The semantics of a postfix lookup expression E?KS are defined by the following rules:
E is evaluated to produce a value $V.
If $V is not a singleton (that is if count($V) ne 1), then the result (by recursive application of these rules) is the value of for $v in $V return $v?KS.
If $V is a JNode then it is coerced to the required type (map(*)|array(*)): see coercion rules.
If $V (after coercion) is a singleton array item (that is, if $V instance of array(*)) then:
If the KeySpecifierKS is either a Literal, a ContextValueRef, a VarRef, or a ParenthesizedExpr, then it is evaluated as an expression to produce a value $K and the result is:
data($K) ! array:get($V, .)
Note:
The focus for evaluating the key specifier expression is the same as the focus for the Lookup expression itself.
The order of items in the result reflects the order of subscripts in $K: [10, 20, 30]?(3, 1) returns (30, 10).
This rule implies that a type error ([err:XPTY0004]) is raised if an item in the atomized value of $K cannot be coerced to the type xs:integer.
This rule also implies that a dynamic error ([err:FOAY0001]FO40) is raised if an integer in the atomized value of $K is outside the range 1 to array:size($V).
If the KeySpecifierKS is an NCName then it is evaluated in the same way as if the NCName were written in quotation marks as a StringLiteral: in consequence, the expression raises a type error [err:XPTY0004].
If the KeySpecifierKS is a wildcard (*), the result is the same as $V?(1 to array:size($V)):
Note:
Note that array items are returned in order.
If $V is a singleton map item (that is, if $V instance of map(*)) then:
If the KeySpecifierKS is either a Literal, a ContextValueRef, a VarRef, or a ParenthesizedExpr, then it is evaluated as an expression to produce a value $K and the result is:
data($K) ! map:get($V, .)
Note:
The focus for evaluating the key specifier expression is the same as the focus for the Lookup expression itself.
The order of items in the result reflects the order of keys in $K: {'a':10, 'b':20, 'c':30}?('c', 'a') returns (30, 10).
There is no error when $K includes a key that is not present in the map.
If the KeySpecifierKS is an NCName, then the result is the same as if it were written in quotes as a StringLiteral: for example $map?name returns the same result as map?"name".
If the KeySpecifierKS is a wildcard (*), the result is the same as $V?(map:keys($V)).
Note:
The order of entries in the result sequence reflects the entry orderDM of the map.
Otherwise (that is, if $V is neither a map nor an array) a type error is raised [err:XPTY0004].
Examples:
[ 1, 2, 5, 7 ]?* evaluates to (1, 2, 5, 7).
[ [ 1, 2, 3 ], [ 4, 5, 6 ] ]?* evaluates to ([ 1, 2, 3 ], [ 4, 5, 6 ])
[ [ 1, 2, 3 ], 4, 5 ]?*[. instance of array(xs:integer)] evaluates to ([ 1, 2, 3 ])
[ [ 1, 2, 3 ], [ 4, 5, 6 ], 7 ]?*[. instance of array(*)]?2 evaluates to (2, 5)
[ [ 1, 2, 3 ], 4, 5 ]?*[. instance of xs:integer] evaluates to (4, 5).
Unary lookup is most commonly used in predicates (for example, $map[?name = 'Mike']) or with the simple map operator (for example, avg($maps ! (?price - ?discount))).
The unary lookup expression ?KS is defined to be equivalent to the postfix lookup expression .?KS, which has the context value (.) as the implicit first operand. See 4.13.3.1 Postfix Lookup Expressions for the postfix lookup operator.
Note:
Although the grammar allows the key specifier to be a context value expression, this is of no practical use with a unary lookup. The expression [1, 2, 3] -> ?. expands to [1, 2, 3]?(1, 2, 3) which returns (1, 2, 3); but a more likely result is a type error or array bounds error.
Examples:
?name is equivalent to .("name"), an appropriate lookup for a map.
?2 is equivalent to .(2), an appropriate lookup for an array or an integer-valued map.
?"first name" is equivalent to .("first name")
?#code is equivalent to .(#code)
?($a) and ?$a are equivalent to for $k in $a return .($k), allowing keys for an array or map to be passed using a variable.
?(3e0) and ?3e0 return the same result as ?3, because xs:double(3e0) and xs:integer(3) compare equal under the rules of the atomic-equal function.
?(2 to 4) is equivalent to for $k in (2, 3, 4) return .($k), a convenient way to return a range of values from an array.
([ 1, 2, 3 ], [ 1, 2, 5 ], [ 1, 2 ])[?3 = 5] raises an error, because ?3 applied to one of the items in the sequence fails.
If $m is bound to the weekdays map described in 4.13.1 Maps, then $m?* returns the values ("Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"), in implementation-dependent order.
If $m is bound to the weekdays map described in 4.13.1 Maps, then $m?* returns the values ("Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"), in implementation-dependent order.
Lookup expressions are retained in this specification with only minor changes from the previous version 3.1. They remain a convenient solution for simple lookups of entries in maps and arrays.
For more complex queries into trees of maps and arrays, XPath 4.0 introduces a generalization of path expressions (see 4.6 Path Expressions) which can now handle JTrees as well as XTrees.
For simple expressions, the capabilities of the two constructs overlap. For example, if $m is a map, then the expressions $m?code = 3 and $m/code = 3 have the same effect. Path expressions, however, have more power, and with it, more complexity. The expression $m/code = 3 (unless simplified by an optimizer) effectively expands the expression to (jtree($m)/child::get("code") => jnode-value()) = 3: that is, the supplied map is wrapped in a JNode, the child axis returns a sequence of JNodes, and the ·content· properties of these JNodes are compared with the supplied value 3.
Whereas simple lookups of specific entries in maps and arrays work well, experience has shown that the ?* wildcard lookup can be problematic. This is because of the flattening effect: for example, given the array let $A := [(1,2), (3,4), (), 5] the result of the expression $A?* is the sequence (1, 2, 3, 4, 5) which loses information that might be needed for further processing. By contrast, the path expression $A/* (or $A/child::*) returns a sequence of four JNodes, whose ·content· properties are respectively (1,2), (3,4), (), and 5.
The result of a lookup expression is a simple value (the value of an entry in a map or a member of an array, or the sequence concatenation of several such values). By contrast, the result of a path expression applied to maps or arrays is always a sequence of JNodes. These JNodes can be used for further navigation. If only the ·content· properties of the JNodes are needed, these will usually be extracted automatically by virtue of the coercion rules: for example if the value is used in an arithmetic expression or a value comparison, atomization of the JNode automatically extracts its ·content·. In other cases the value can be extracted explicitly by a call of the jnode-value function.
Lookup expressions on arrays result in a dynamic error if the subscript is out of bounds, whereas the equivalent path expression succeeds, returning an empty sequence. For example array{1 to 5}?10 raises [err:FOAY0001]FO40, whereas array{1 to 5}/get(10) returns a empty sequence.