Next: , Previous: Adding or Setting Alist Entries, Up: Association Lists


22.7.2.3 Retrieving Alist Entries

assq, assv and assoc take an alist and a key as arguments and return the entry for that key if an entry exists, or #f if there is no entry for that key. Note that, in the cases where an entry exists, these procedures return the complete entry, that is (KEY . VALUE), not just the value.

— Scheme Procedure: assq key alist
— Scheme Procedure: assv key alist
— Scheme Procedure: assoc key alist
— C Function: scm_assq (key, alist)
— C Function: scm_assv (key, alist)
— C Function: scm_assoc (key, alist)

Fetch the entry in alist that is associated with key. To decide whether the argument key matches a particular entry in alist, assq compares keys with eq?, assv uses eqv? and assoc uses equal?. If key cannot be found in alist (according to whichever equality predicate is in use), then return #f. These functions return the entire alist entry found (i.e. both the key and the value).

assq-ref, assv-ref and assoc-ref, on the other hand, take an alist and a key and return just the value for that key, if an entry exists. If there is no entry for the specified key, these procedures return #f.

This creates an ambiguity: if the return value is #f, it means either that there is no entry with the specified key, or that there is an entry for the specified key, with value #f. Consequently, assq-ref and friends should only be used where it is known that an entry exists, or where the ambiguity doesn't matter for some other reason.

— Scheme Procedure: assq-ref alist key
— Scheme Procedure: assv-ref alist key
— Scheme Procedure: assoc-ref alist key
— C Function: scm_assq_ref (alist, key)
— C Function: scm_assv_ref (alist, key)
— C Function: scm_assoc_ref (alist, key)

Like assq, assv and assoc, except that only the value associated with key in alist is returned. These functions are equivalent to

          (let ((ent (associator key alist)))
            (and ent (cdr ent)))

where associator is one of assq, assv or assoc.