Emacs Lisp: Association List

By Xah Lee. Date: . Last updated: .

Association List (aka alist) is a value type in Emacs Lisp.

Association List is a List , where each element is a cons pair, like this (key . val) .

[see Emacs Lisp: Cons Pair]

What is the Difference Between Association List and Hash Table?

[see Emacs Lisp: Hash Table]

Create a Alist

Using string as key:

(setq x
      '(("mary" . 23)
        ("john" . 24)
        ("smith" . 33)))

Using symbol as key:

(setq x
      '((mary . 23)
        (john . 24)
        (smith . 33)))

Symbol Key vs String Key

Usually, symbol (e.g. 'xyz) is used for key. eq tests if 2 symbols are equal.

[see Emacs Lisp: Symbol]

You can also use string (e.g. "xyz") as key. To compare if 2 string is equal, you must use string-equal or equal.

eq is faster than string-equal and equal. This is important if your alist is very long.

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:

[see Emacs Lisp: Test Equality]

Get Pair by Key

assoc
(assoc key alist)
Return the first pair with the key. If no exist, return nil. (key existence is checked by equal. [see Emacs Lisp: Test Equality] )
(setq x
      '(("mary" . 23)
        ("john" . 24)
        ("smith" . 33)))

;; get the pair with key "john"
(assoc "john" x)
; returns ("john" . 24)
assq
(assq key alist)
same as assoc except key is checked by eq. Use this if all keys are Symbols [see Emacs Lisp: Test Equality]
(setq x
      '((mary . 23)
        (john . 24)
        (smith . 33)))

(assq 'mary x)

Check If a Key Exist

Use assoc or assq.

Get Pair by Value

You can search alist by value.

rassoc
(rassoc val alist)
Return the first pair that has specific value. Else return nil. Test is done by equal. [see Emacs Lisp: Test Equality]
(setq x
      '(("mary" . 23)
        ("john" . 24)
        ("smith" . 33)))

;; get the pair with value 24
(rassoc 24 x)
; returns ("john" . 24)

rassq
(rassq value alist)
same as rassoc except value is compared using eq. [see Emacs Lisp: Test Equality]

Add a Element

Add a Pair to Front

Add a element to the front. Use push

(setq x
      '(("mary" . 23)
        ("john" . 24)
        ))

;; add a element
(push '("smith" . 33) x)

Add a Pair If Key No Exist

(setq x
      '(("mary" . 23)
        ("john" . 24)
        ))

(when (not (assoc "smith" x))
  (push '("smith" . 33) x))

Add a Pair If Pair No Exist

(defun xah-add-asso-if-pair-no-exist (ConsPair Alist)
  "Add ConsPair to Alist if the ConsPair not exist.
Both key and value of ConsPair are checked. With `equal'.
Returns Alist.
Version 2021-12-03"
  (interactive)
  (let* (($key (car ConsPair))
         ($val (cdr ConsPair))
         ($result (assoc $key Alist)))
    (if (and $result (equal $val (cdr $result)))
        nil
      (push ConsPair Alist))
    Alist
    ))

;; sample usage

(xah-add-asso-if-pair-no-exist
 '("mary" . 23)
 '(("mary" . 23)
   ("john" . 24)))
;; not added

(xah-add-asso-if-pair-no-exist
 '("mary" . 99)
 '(("mary" . 23)
   ("john" . 24)))
;; added

Delete Pairs 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.
assq-delete-all
same as assoc-delete-all but uses eq for testing key.
(setq x
      '(("mary" . 23)
        ("john" . 24)
        ))

(setq x (assoc-delete-all "john" x))

More Alist Functions

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

[see Emacs Lisp: Sequence Functions]

There are many more specialized function for alist. See

(info "(elisp) Association Lists")

Lisp Data Structure

ErgoEmacs mascot-s276x226
Buy Xah Emacs Tutorial

Lisp Basics

Basics

Lisp Data Structure

Function

Lisp Symbol

Lisp Misc

Working with Elisp