assoc
type: function (subr) location: built-in source file: xllist.c Common LISP compatible: similar supported on: all machines
SYNTAX
(assoc <expr>[ { :test | :test-not } ] ) <expr> - the expression to find - an atom or list <a-list> - the association list to search <test> - optional test function (default is EQL)
DESCRIPTION
An association list is a collection of list pairs of the form ( (key1 item1) (key2 item2) ... (keyN itemN) ). ASSOC searches through an association list <a-list> looking for the key (a CAR in an association pair) that matches the search <expr>. If a match is found, that association pair (keyN itemN) is returned as the result. If no match is found, a NIL is returned. You may specify your own test with the :TEST and :TEST-NOT keywords followed by the test you which to perform.
EXAMPLES
(setq mylist '((a . my-a) (b . his-b) ; set up an association
(c . her-c) (d . end))) ; list
(assoc 'a mylist) ; returns (A . MY-A)
(assoc 'b mylist) ; returns (B . HIS-B)
(assoc 1 mylist) ; returns NIL
(setq agelist '((1 (bill bob)) ; set up another
(2 (jane jill)) ; association list
(3 (tim tom)) ;
(5 (larry daryl daryl)) ;
)) ;
(assoc 1 agelist) ; returns (1 (BILL BOB))
(assoc 3 agelist :test '>=) ; returns (1 (BILL BOB))
(assoc 3 agelist :test '<) ; returns (5 (LARRY DARYL DARYL))
(assoc 3 agelist :test '<=) ; returns (3 (TIM TOM))
(assoc 3 agelist :test-not '>=) ; returns (5 (LARRY DARYL DARYL))
(assoc '(a b) '( ((c d) e) ((a b) x) ) ; use a list as the search
:test 'equal) ; note the use of EQUAL
; returns ((A B) X)
NOTE: The ASSOC function can work with a list or string as the <expr>. However, the default EQL test does not work with lists or strings, only symbols and numbers. To make this work, you need to use the :TEST keyword along with EQUAL for <test>.
COMMON LISP COMPATIBILITY: Common LISP supports the use of the :KEY keyword which specifies a function that is applied to each element of <a-list> before it is tested. XLISP does not support this.