sublis

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

Syntax

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

expr - the expression to substitute within, an atom
a-list - the association list to search
test - optional test function, default is eql
returns - the expression with substitutions

Description

The 'sublis' function 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 wish 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 assoc list
               (c her-c) (d end)))

(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 with 2 parameters
                    (princ x)           ; to see what SUBLIS does
                    (princ " ")
                    (princ y) (terpri)
                    t)                  ; always return T

(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: 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 sublis function in the XLISP 2.0 manual.

  Back to Top