On this page:
acons
alistp
assoc
assoc-eq
assoc-equal
assoc-keyword
assoc-string-equal
eqlable-alistp
put-assoc-eq
put-assoc-eql
put-assoc-equal
rassoc
rassoc-eq
rassoc-equal
standard-string-alistp
strip-cars
strip-cdrs
sublis
symbol-alistp
pairlis$
1.4.9 Association Lists

An association list is a list of cons-pairs, representing a table in which the car of each pair maps to its cdr.

(acons key datum alist)  alistp
  key : t
  datum : t
  alist : (alistp alist)
For creating association lists. (acons key datum alist) = (cons (cons key datum) alist)

Examples:

> (acons "hello" 5 nil)

'(("hello" . 5))

> (acons "hello" 5 (list (cons "hello2" 6)))

'(("hello" . 5) ("hello2" . 6))

(alistp any)  t
  any : t
Reports whether x is a proper association list.

Examples:

> (alistp nil)

't

> (alistp (acons "four" 4 nil))

't

> (alistp t)

'()

(assoc x alist)  t
  x : t
  alist : (if (eqlablep x) (alistp alist) (eqlable-alistp alist))
Lookup function for association lists, using eql as test. Returns the first pair in alist whose key matches x. Otherwise returns nil.

Examples:

> (assoc 'a (list (cons 'a 'b) (cons 'c 'd)))

'(a . b)

> (assoc 'z (list (cons 'a 'b) (cons 'c 'd)))

'()

(assoc-eq x alist)  t
  x : t
  alist : (if (symbolp x) (alistp alist) (symbol-alistp alist))
Like assoc, but uses eq as the test.

Examples:

> (assoc-eq 'a (list (cons 'a 'b) (cons 'c 'd)))

'(a . b)

> (assoc-eq 'z (list (cons 'a 'b) (cons 'c 'd)))

'()

(assoc-equal x alist)  t
  x : t
  alist : (alistp alist)
Like assoc, but uses equal as the test.

Examples:

> (assoc-equal "c" (list (cons "a" "b") (cons "c" "d")))

'("c" . "d")

> (assoc-equal "z" (list (cons "a" "b") (cons "c" "d")))

'()

(assoc-keyword key l)  t
  key : t
  l : (keyword-value-listp l)
Lookup function for a keyword-value-listp

Example:

> (assoc-keyword :b (list :a 1 :b 2 :c 3))

'(:b 2 :c 3)

(assoc-string-equal str alist)  t
  str : (and (stringp str) (standard-char-listp (coerce str 'list)))
  alist : (standard-string-alistp alist)
Lookup function for association lists that have strings for keys

Examples:

> (assoc-string-equal "c" (list (cons "a" "b") (cons "c" "d")))

'("c" . "d")

> (assoc-string-equal "z" (list (cons "a" "b") (cons "c" "d")))

'()

(eqlable-alistp x)  t
  x : t
Recognizer for association lists of eqlablep items

Examples:

> (eqlable-alistp nil)

't

> (eqlable-alistp (list (cons 4 6) (cons 7 8)))

't

> (eqlable-alistp t)

'()

(put-assoc-eq name val alist)  t
  name : t
  val : t
  alist : (if (symbolp name) (alistp alist) (symbol-alistp alist))
Modify an association list by associating a value with a key. Use this function for association lists whose keys are symbols.

Examples:

> (put-assoc-eq 'a 5 nil)

'((a . 5))

> (put-assoc-eq 'a 5 (list (cons 'a 4) (cons 'b 6)))

'((a . 5) (b . 6))

(put-assoc-eql name val alist)  t
  name : t
  val : t
  alist : (if (eqlable name) (alistp alist) (eqlable-alistp alist))
Modify an association list by associating a value with a key. Use this function for association lists whose keys are numbers, symbols, or characters.

Examples:

> (put-assoc-eql 'a 5 nil)

'((a . 5))

> (put-assoc-eql 'a 5 (list (cons 'a 4) (cons 'b 6)))

'((a . 5) (b . 6))

> (put-assoc-eql "string" 5 (list (cons 1 'a)))

'((1 . a) ("string" . 5))

(put-assoc-equal name val alist)  t
  name : t
  val : t
  alist : (alistp alist)
Modify an association list by associating a value with a key.

Examples:

> (put-assoc-equal "a" 5 nil)

'(("a" . 5))

> (put-assoc-equal "a" 5 (list (cons "a" 4) (cons "b" 6)))

'(("a" . 5) ("b" . 6))

(rassoc x alist)  t
  x : t
  alist : (if (eqlablep x) (alistp alist) (r-eqlable-alistp alist))
Lookup function for association lists, using eql as test. Returns the first pair in alist whose value matches x. Otherwise returns nil. This function is similar to assoc, but whereas assoc checks for a pair whose car matches x, rassoc checks for a pair whose cdr matches.

Examples:

> (rassoc 'd (list (cons 'a 'b) (cons 'c 'd)))

'(c . d)

> (rassoc 'z (list (cons 'a 'b) (cons 'c 'd)))

'()

(rassoc-eq x lst)  t
  x : t
  lst : (if (symbolp x) (alisp lst) (r-symbol-alisp lst))
Like rassoc, but uses eq as the test.

Examples:

> (rassoc-eq 'd (list (cons 'a 'b) (cons 'c 'd)))

'(c . d)

> (rassoc-eq 'z (list (cons 'a 'b) (cons 'c 'd)))

'()

(rassoc-equal x lst)  t
  x : t
  lst : (alistp lst)
Like rassoc, but uses equal as the test.

Examples:

> (rassoc-equal "d" (list (cons "a" "b") (cons "c" "d")))

'("c" . "d")

> (rassoc-equal "z" (list (cons "a" "b") (cons "c" "d")))

'()

(standard-string-alistp x)  t
  x : t
Reports whether x is an association list of stringp elements, in which each string contains only standard-char-p characters.

Example:

> (standard-string-alistp (list (cons "abc" 1) (cons "def" 2)))

't

(strip-cars x)  t
  x : (alistp x)
Returns a list containing the cars of all the pairs in the given association list.

Example:

> (strip-cars (list (cons 'a 'b) (cons 'c 'd)))

'(a c)

(strip-cdrs x)  t
  x : (alistp x)
Returns a list containing the cdrs of all the pairs in the given association list.

Example:

> (strip-cdrs (list (cons 'a 'b) (cons 'c 'd)))

'(b d)

(sublis alst tree)  t
  alst : (eqlable-alistp alst)
  tree : t
Replaces every leaf of tree with the result of looking that leaf up in the given alist.

(symbol-alistp x)  t
  x : t
Reports whether x is an association list of symbolp elements.

Examples:

> (symbol-alistp (list (cons 'a 'b) (cons 'c 'd)))

't

> (symbol-alistp (list 'ab 'cd 'ef))

'()

(pairlis$ x y)  t
  x : (true-listp x)
  y : (true-listp y)
Zipper together two lists

Examples:

> (pairlis$ (list 'a 'b 'c) (list 1 2 3))

'((a . 1) (b . 2) (c . 3))

> (pairlis$ nil nil)

'()