assoc

Type:	-	function (subr)
Source:	-	xllist.c

Syntax

(assoc expr a-list [{:test | :test-not} test])

expr - the expression to find as an atom or list
a-list - the association list to search
test - optional test function (default is eql)
returns - the alist entry or NIL

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 wish 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: 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.

See the assoc function in the XLISP 2.0 manual.

  Back to Top