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.

sublis

sublis

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(sublis <a-list>  [ { :test | :test-not }  ] )
        <expr>          -       the expression to substitute within - an atom 
                                or list
        <a-list>        -       the association list to search
        <test>          -       optional test function (default is EQL)

DESCRIPTION

SUBLIS searches through an <expr> and replaces each of the elements in the <expr> that match the CAR of the elements of the association list <a-list> with the CDR of elements of the <a-list>. The <expr> with the substitutions (if any) is returned. You may specify your own test with the :TEST and :TEST-NOT keywords followed by the test you which to perform. The SUBLIS function is normally used with a dotted pair (A . B) association list. It is possible to use a normal list pair (A B) or a list of the form (A (B C)).

EXAMPLES

(sublis '( (a . b))   '(a a))           ; returns (B B)
(sublis '( (a b))     '(a a))           ; returns ((B) (B))
(sublis '( (a (b c))) '(a a))           ; returns (((B C)) ((B C)))
                                        ;
(setq newlist '( (a . 1)                ; set up an association list
                 (b . 2)                ;
                 (c . 3) ))             ;
(sublis newlist '(a b c d e f b a c))   ; returns (1 2 3 D E F 2 1 3)
(sublis newlist 'a)                     ; returns 1
                                        ;
(setq mylist '((a my-a) (b his-b)       ; set up a non-dotted pair
               (c her-c) (d end)))      ;   assoc list
(sublis mylist '(a b c d e f g))        ; returns ((MY-A) (HIS-B) 
                                        ;          (HER-C) (END) E F G)
(sublis mylist 'a)                      ; returns (MY-A)
                                        ;
(setq numlist '((1 . a) (2 . b)) )      ; set up a new assoc list
(defun mytest (x y) (princ ": ")        ; set up my own test function
                    (princ x)           ;   with 2 parameters
                    (princ " ")         ;   to see what SUBLIS does
                    (princ y) (terpri)  ;
                    T)                  ;   always return TRUE
(sublis numlist '(3 1) :test mytest)    ; prints        : (3 1) 1
                                        ;   returns A
                                        ;   because the entire list
                                        ;   succeeds with the test
                                        ;   and so (1 . A) produces
                                        ;   the returned value
(sublis numlist '(1) :test-not mytest)  ; prints        : (1) 1
                                        ;               : (1) 2
                                        ;               : 1 1
                                        ;               : 1 2
                                        ;               : NIL 1
                                        ;               : NIL 2
                                        ;   returns (1)
                                        ;   because SUBLIS tried to
                                        ;   match every list/sublist
                                        ;   against each entry in the
                                        ;   assoc. list and failed
                                        ;   because of the :TEST-NOT
                                        ;   and so returned the 
                                        ;   original list unaltered

NOTE: The SUBLIS 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.