- mapping-search mapping key failure successprocedure
The mapping mapping is searched in order (that is in the order of the stored keys) for an association with key key. If it is not found, then the failure procedure is tail-called with two continuation arguments, insert and ignore, and is expected to tail-call one of them. If an association with key key is found, then the success procedure is tail-called with the matching key of mapping, the associated value, and two continuations, update and remove, and is expected to tail-call one of them.
The hashmap-search procedure exported by (srfi 146 hash) searches in an arbitrary order.
It is an error if the continuation arguments are invoked, but not in tail position in the failure and success procedures. It is also an error if the failure and success procedures return to their implicit continuation without invoking one of their continuation arguments.
The effects of the continuations are as follows (where obj is any Scheme object):
- Invoking (insert value obj) causes a mapping to be newly allocated that uses the same comparator as the mapping mapping and contains all the associations of mapping, and in addition a new association mapping key to value.
- Invoking (ignore obj) has no effects; in particular, no new mapping is allocated (but see below).
- Invoking (update new-key new-value obj) causes a mapping to be newly allocated that uses the same comparator as the mapping and contains all the associations of mapping, except for the association with key key, which is replaced by a new association mapping new-key to new-value.
- Invoking (remove obj) causes a mapping to be newly allocated that uses the same comparator as the mapping and contains all the associations of mapping, except for the association with key key.
In all cases, two values are returned: the possibly newly allocated mapping and obj.