GNU Info

(guile.info)Retrieving Alist Entries

---

Next: Removing Alist Entries Prev: Adding or Setting Alist Entries Up: Association Lists

---

Enter node , (file) or (file)node

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.

 - primitive: assq key alist
 - primitive: assv key alist
 - primitive: assoc key alist
     Fetches 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 `#f' is returned.
     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.

 - primitive: assq-ref alist key
 - primitive: assv-ref alist key
 - primitive: 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'.