Elisp: Association List

What is Association List

Association List (aka alist) is a List , where each element is a Cons Pair , like this

(cons key val)

• In each cons pair, the key and value can be any value type.
• Items in Association List can have duplicate keys, and order is maintained.

Difference Between Association List and Hash Table

• Association List is ordered. Hash Table is not.
• Association List can have duplicate keys. Hash Table keys are unique.
• Association List access time is proportional to number of items. Hash Table is constant time to access any item regardless of number of items.
• Association List entries are hard to modify. As a list, it's designed to only add or drop first item of the list. Hash Table entries are designed to be modified, or added or deleted.

Difference Between List of Pairs and Association List

• Elisp: Difference Between Association List vs List of Pairs

Dot Notation for Cons

when creating a association list, For example

if you do not need to evaluate the items, you can write it as

'( (k1 . v1) (k2 . v2) )

〔see Elisp: Quote and Dot Notation〕

Create a Alist

Using string as key:

;; example of association list
(setq
 xx
 (list
  (cons "aa" 23)
  (cons "bb" 24)
  (cons "cc" 33)))

;; dot notation
(setq
 xx
 '(("aa" . 23)
   ("bb" . 24)
   ("cc" . 33)))

Using Symbol as key:

;; example of association list
;; where keys are symbols, values are numbers

(setq
 xx
 (list
  (cons 'aa 23)
  (cons 'bb 24)
  (cons 'cc 33)))

;; dot notation
(setq
 xx
 '((aa . 23)
   (bb . 24)
   (cc . 33)))

Symbol Key vs String Key

Usually, Symbol is used for key. eq tests if 2 symbols are equal.

You can also use String as key. To compare if 2 string is equal, equal works.

Some functions for alist use eq to test existence of key, and others use equal. Some lets you specify a function for equality test.

So, it is important to know:

• What datatype you are using as key in your alist
• Which equality test is used by a specific alist function.

〔see Elisp: Equality Test〕

Get Value by Key

alist-get

(alist-get key alist &optional default remove testfn)

Find the first key, return its value. If no exist, return default. Default to nil.

The remove should be nil. (it is used in advanced situation with Place Expression . You shouldn't use that for beginning lisp.)

key existence is checked by testfn (must be a symbol of function). Default to eq. 〔see Elisp: Equality Test〕

(setq xx
      '(("aa" . 23)
        ("bb" . 24)
        ("cc" . 33)))

;; get the value with key "bb". if not found, return 999. use string-equal for comparison
(alist-get "bb" xx 999 nil 'string-equal)
;; 24

(alist-get "dd" xx 999 nil 'string-equal)
;; 999

(setq xx
      '((aa . 23)
        (bb . 24)
        (cc . 33)))

;; get the value with symbol key bb. if not found, return 999
(alist-get 'bb xx 999)
;; 24

(alist-get 'dd xx 999)
;; 999

Get Cons Cell by Key

assoc

(assoc key alist)

• Return the first cons cell with the key.
• If no exist, return nil.
• Key existence is checked by equal. 〔see Elisp: Equality Test〕

(setq xx
      '(("aa" . 23)
        ("bb" . 24)
        ("cc" . 33)))

;; get the cons cell with key "bb"
(assoc "bb" xx)
; return ("bb" . 24)

assq

(assq key alist)

• similar to assoc except key is checked by eq.
• Use this if all keys are Symbols 〔see Elisp: Equality Test〕

(setq xx
      '((aa . 23)
        (bb . 24)
        (cc . 33)))

(assq 'aa xx)

Check If a Key Exist

Use assoc or assq.

Get Cons Cell by Value

You can search alist by value.

rassoc

(rassoc val alist)

• Return the first cons cell that has specific value.
• Else return nil.
• Test is done by equal. 〔see Elisp: Equality Test〕

(setq xx
      '(("aa" . 23)
        ("bb" . 24)
        ("cc" . 33)))

;; get the cons cell with value 24
(rassoc 24 xx)
; return ("bb" . 24)

rassq

(rassq value alist)

similar to rassoc except value is compared using eq. 〔see Elisp: Equality Test〕

Add a Element

Add a Cons Cell to Front

Add a element to the front. Use push

(setq xx
      '(("aa" . 23)
        ("bb" . 24)
        ))

;; add a element
(push '("cc" . 33) xx)

Add a Cons Cell If Key No Exist

(setq xx
      '(("aa" . 23)
        ("bb" . 24)
        ))

(when (not (assoc "cc" xx))
  (push '("cc" . 33) xx))

Delete Cons Cells by Key

assoc-delete-all

(assoc-delete-all KEY ALIST &optional TEST)

• Delete all elements that has key KEY.
• Keys are checkd by TEST. Defaults to equal.
• Return the modified alist.
• Elements of ALIST that are not conses are ignored.

(setq xx
      '(("aa" . 23)
        ("bb" . 24)
        ))

(setq xx (assoc-delete-all "bb" xx))

assq-delete-all

similar to assoc-delete-all but uses eq for testing key.

More Alist Functions

Note, Association List is a List , any function that works on list also works on Association List.

〔see Elisp: Sequence Functions〕

There are many more specialized function for alist. See

Association Lists (ELISP Manual)