XLISP assoc

Nyquist / XLISP 2.0 - Contents | Tutorials | Examples | Reference

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

The 'assoc' function 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 is returned as the result. If no match is found, 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)
                   (c . her-c)
                   (d . end)))

    (assoc 'a mylist)  => (A . MY-A)
    (assoc 'b mylist)  => (B . HIS-B)
    (assoc  1 mylist)  => NIL

    (setq agelist '((1 (bill bob))
                    (2 (jane jill))
                    (3 (tim tom))
                    (5 (larry daryl daryl))))

    (assoc 1 agelist)                 => (1 (BILL BOB))
    (assoc 3 agelist :test #'>=)      => (1 (BILL BOB))
    (assoc 3 agelist :test #'<)       => (5 (LARRY DARYL DARYL))
    (assoc 3 agelist :test #'<=)      => (3 (TIM TOM))
    (assoc 3 agelist :test-not #'>=)  => (5 (LARRY DARYL DARYL))

Using a list as key, tested with equal:

    > (assoc '(a b) '(((c d) e) ((a b) x)) :test #'equal)
    ((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'.

See also:

- Contents → List Functions

Back to Top

Nyquist / XLISP 2.0 - Contents | Tutorials | Examples | Reference