GNU Info

(guile.info)Adding or Setting Alist Entries

---

Next: Retrieving Alist Entries Prev: Alist Key Equality Up: Association Lists

---

Enter node , (file) or (file)node

Adding or Setting Alist Entries
...............................

`acons' adds a new entry to an association list and returns the
combined association list.  The combined alist is formed by consing the
new entry onto the head of the alist specified in the `acons' procedure
call.  So the specified alist is not modified, but its contents become
shared with the tail of the combined alist that `acons' returns.

In the most common usage of `acons', a variable holding the original
association list is updated with the combined alist:

     (set! address-list (acons name address address-list))

In such cases, it doesn't matter that the old and new values of
`address-list' share some of their contents, since the old value is
usually no longer independently accessible.

Note that `acons' adds the specified new entry regardless of whether
the alist may already contain entries with keys that are, in some
sense, the same as that of the new entry.  Thus `acons' is ideal for
building alists where there is no concept of key uniqueness.

     (set! task-list (acons 3 "pay gas bill" '()))
     task-list
     =>
     ((3 . "pay gas bill"))
     
     (set! task-list (acons 3 "tidy bedroom" task-list))
     task-list
     =>
     ((3 . "tidy bedroom") (3 . "pay gas bill"))

`assq-set!', `assv-set!' and `assoc-set!' are used to add or replace an
entry in an association list where there _is_ a concept of key
uniqueness.  If the specified association list already contains an
entry whose key is the same as that specified in the procedure call,
the existing entry is replaced by the new one.  Otherwise, the new
entry is consed onto the head of the old association list to create the
combined alist.  In all cases, these procedures return the combined
alist.

`assq-set!' and friends _may_ destructively modify the structure of the
old association list in such a way that an existing variable is
correctly updated without having to `set!' it to the value returned:

     address-list
     =>
     (("mary" . "34 Elm Road") ("james" . "16 Bow Street"))
     
     (assoc-set! address-list "james" "1a London Road")
     =>
     (("mary" . "34 Elm Road") ("james" . "1a London Road"))
     
     address-list
     =>
     (("mary" . "34 Elm Road") ("james" . "1a London Road"))

Or they may not:

     (assoc-set! address-list "bob" "11 Newington Avenue")
     =>
     (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
      ("james" . "1a London Road"))
     
     address-list
     =>
     (("mary" . "34 Elm Road") ("james" . "1a London Road"))

The only safe way to update an association list variable when adding or
replacing an entry like this is to `set!' the variable to the returned
value:

     (set! address-list
           (assoc-set! address-list "bob" "11 Newington Avenue"))
     address-list
     =>
     (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
      ("james" . "1a London Road"))

Because of this slight inconvenience, you may find it more convenient to
use hash tables to store dictionary data.  If your application will not
be modifying the contents of an alist very often, this may not make much
difference to you.

If you need to keep the old value of an association list in a form
independent from the list that results from modification by `acons',
`assq-set!', `assv-set!' or `assoc-set!', use `list-copy' to copy the
old association list before modifying it.

 - primitive: acons key value alist
     Adds a new key-value pair to ALIST.  A new pair is created whose
     car is KEY and whose cdr is VALUE, and the pair is consed onto
     ALIST, and the new list is returned.  This function is _not_
     destructive; ALIST is not modified.

 - primitive: assq-set! alist key val
 - primitive: assv-set! alist key value
 - primitive: assoc-set! alist key value
     Reassociate KEY in ALIST with VALUE: find any existing ALIST entry
     for KEY and associate it with the new VALUE.  If ALIST does not
     contain an entry for KEY, add a new one.  Return the (possibly
     new) alist.

     These functions do not attempt to verify the structure of ALIST,
     and so may cause unusual results if passed an object that is not an
     association list.