map:find

Searches the supplied input sequence and any contained maps and arrays for a map entry with the supplied key, and returns the corresponding values.

Signature

map:find(
    $input as item()*, 
    $key as xs:anyAtomicType
) as array(*)

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

The function map:find searches the sequence supplied as $input looking for map entries whose key is the same key as $key. The associated value in any such map entry (each being in general a sequence) is returned as a member of the result array.

The search processes the $input sequence using the following recursively-defined rules (any equivalent algorithm may be used provided it delivers the same result, respecting those rules that constrain the order of the result):

  1. To process a sequence, process each of its items in order.

  2. To process an item that is an array, process each of the array's members in order (each member is, in general, a sequence).

  3. To process an item that is a map, then for each key-value entry (K, V) in the map (in implementation-dependent order) perform both of the following steps, in order:

    1. If K is the same key as $key, then add V as a new member to the end of the result array.

    2. Process V (which is, in general, a sequence).

  4. To process an item that is neither a map nor an array, do nothing. (Such items are ignored).

Notes

If $input is an empty sequence, map, or array, or if the requested $key is not found, the result will be a zero-length array.

Examples

let $responses := [map{0:'no', 1:'yes'}, map{0:'non', 1:'oui'}, 
                  map{0:'nein', 1:('ja', 'doch')}]

The expression map:find($responses, 0) returns ['no', 'non', 'nein'].

The expression map:find($responses, 1) returns ['yes', 'oui', ('ja', 'doch')].

The expression map:find($responses, 2) returns [].

let $inventory := map{"name":"car", "id":"QZ123", 
      "parts": [map{"name":"engine", "id":"YW678", "parts":[]}]}

The expression map:find($inventory, "parts") returns [[map{"name":"engine", "id":"YW678", "parts":[]}], []].