2.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))

> (acons 'key "datum" (list 1 2 3))

((key . "datum") 1 2 3)

(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

Examples:

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

(a 1 b 2 c 3)

> (assoc-keyword 'd (list 'a 1 '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-eq "string" 5 (list 1 2 3))

(1 2 3 ("string" . 5))

(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-eql "string" 5 (list (cons "string2" 'a)))

|Dracula program| broke the contract (->r ((x ...) (y

...)) ...) on #f; expected <eqlablep>, given: "string2"

(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))

> (put-assoc-equal 1 'a (list "not an alistp"))

("not an alistp" (1 . a))

(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.

Examples:

> (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.

Examples:

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

(a c)

> (strip-cars (list 1 2 3))

|Dracula program| broke the contract (-> (or/c "nil"

(cons/c any/c any/c)) any) on #f; expected <(or/c nil

(cons/c any/c any/c))>, given: 1

(strip-cdrs x) → t

x : (alistp x)

Returns a list containing the cdrs of all the pairs in the given association list.

Examples:

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

(b d)

> (strip-cdrs (list 1 2 3))

|Dracula program| broke the contract (-> (or/c "nil"

(cons/c any/c any/c)) any) on #f; expected <(or/c nil

(cons/c any/c any/c))>, given: 1

(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)

()