saxon:map-search

Searches recursively through a structure of nested maps and arrays.

map-search($input as item()*, $key as xs:anyAtomicType) ➔ map(*)*

Arguments

 

$input

item()*

The input sequence to be searched

 

$key

xs:anyAtomicType

The key value to be found

Result

map(*)*

map-search($input as item()*, $key as xs:anyAtomicType, $condition as function(item()) as xs:boolean) ➔ map(*)*

Arguments

 

$input

item()*

The input sequence to be searched

 

$key

xs:anyAtomicType

The key value to be found

 

$condition

function(item()) as xs:boolean

Predicate that the found entry must satisfy

Result

map(*)*

Namespace

http://saxon.sf.net/

Saxon availability

Requires Saxon-PE or Saxon-EE. Implemented since Saxon 9.9.

Notes on the Saxon implementation

Available since Saxon 9.9.

Details

The function saxon:map-search is similar to map:find, in that it searches recursively through nested maps and arrays, but is more versatile. It differs from map:find in two main respects:

  1. Whereas map:find only takes as input the key value to look for, saxon:map-search also takes a function that can be used to test the associated value.
  2. Whereas map:find returns the value associated with the specified key, saxon:map-search returns much more information about where the match was found.

In more detail:

The function saxon:map-search searches the sequence supplied as $input looking for map entries whose key is the same key as $key. When such an entry is found, the associated value is passed to the supplied $condition function. If the $condition function returns true, or if there is no $condition, then an item is added to the returned value of the function: so the returned value is a sequence containing one item for each search "hit". The actual item representing a hit is a map with the following entries:

  • key: the actual key of the entry (this may differ in minor ways from the supplied input $key, for example it may be a different numeric type)

  • value: the associated value of the entry

  • map: the map containing this entry. This map will have a pedigree, rooted at the item in $input that was being searched. The pedigree can be used to trace the search path up to the root, using the saxon:pedigree() function.

The search processes the $input sequence using the following recursively-defined rules:

  • To process a sequence, process each of its items in order.
  • Each array or map in the $input sequence is marked as a pedigree root.
  • To process an item that is an array, then process each of the array's members in order (each member is, in general, a sequence).
  • 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:
    • If K is the same key as $key, then add a new map to the result sequence (with entries "key", "value", and "map" as described above).
    • Process V (which is, in general, a sequence).
  • To process an item that is neither a map nor an array, do nothing. (Such items are ignored).

See also:

saxon:pedigree()

saxon:with-pedigree()