Node:Adding or Setting Alist Entries, Next:Retrieving Alist Entries, Previous:Alist Key Equality, Up:Association Lists
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
procedure call. So the specified alist is not modified, but its
contents become shared with the tail of the combined alist that
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.
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
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"))
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
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
(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
list-copy to copy the old association list before modifying
|acons key value alist||Scheme Procedure|
|scm_acons (key, value, alist)||C Function|
|Add 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.|
|assq-set! alist key val||Scheme Procedure|
|assv-set! alist key value||Scheme Procedure|
|assoc-set! alist key value||Scheme Procedure|
|scm_assq_set_x (alist, key, val)||C Function|
|scm_assv_set_x (alist, key, val)||C Function|
|scm_assoc_set_x (alist, key, val)||C Function|
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.