Structural Informatics Group (SIG) logo
Home | Projects | Demos | Downloads | Publications | Local Info | About Us | New site
Go to the first, previous, next, last section, table of contents.

assoc

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.


Go to the first, previous, next, last section, table of contents.