Node: Pairs and lists, Next: , Previous: Booleans, Up: Standard Procedures



Pairs and lists

pair? obj R5RS
Pair? returns #t if obj is a pair, and otherwise returns #f.

cons obj1 obj2 R5RS
Returns a newly allocated pair whose car is obj1 and whose cdr is obj2. The pair is guaranteed to be different (in the sense of eqv?) from every existing object.
              (cons 'a '())           =>  (a)
              (cons '(a) '(b c d))    =>  ((a) b c d)
              (cons "a" '(b c))       =>  ("a" b c)
              (cons 'a 3)             =>  (a . 3)
              (cons '(a b) 'c)        =>  ((a b) . c)
          

car pair R5RS
Returns the contents of the car field of pair. Note that it is an error to take the car of the empty list.
              (car '(a b c))          =>  a
              (car '((a) b c d))      =>  (a)
              (car '(1 . 2))          =>  1
              (car '())               =>  error
          

cdr pair R5RS
Returns the contents of the cdr field of pair. Note that it is an error to take the cdr of the empty list.
              (cdr '((a) b c d))      =>  (b c d)
              (cdr '(1 . 2))          =>  2
              (cdr '())               =>  error
          

set-car! pair obj R5RS
Stores obj in the car field of pair. The value returned by set-car! is void.
             (define (f) (list 'not-a-constant-list))
             (define (g) '(constant-list))
             (set-car! (f) 3)
             (set-car! (g) 3)             =>  error
          

set-cdr! pair obj R5RS
Stores obj in the cdr field of pair. The value returned by set-cdr! is void.

caar pair R5RS
cadr pair R5RS
...
cdddar pair R5RS
cddddr pair R5RS
These procedures are compositions of car and cdr, where for example caddr could be defined by
             (define caddr (lambda (x) (car (cdr (cdr x)))))
          
Arbitrary compositions, up to four deep, are provided. There are twenty-eight of these procedures in all.

null? obj R5RS
Returns #t if obj is the empty list, otherwise returns #f.

pair-mutable? obj STKLOS Procedure
Returns #t if obj is a mutable pair, otherwise returns #f.
          (pair-mutable? '(1 . 2))    => #f
          (pair-mutable? (cons 1 2))  => #t
          (pair-mutable? 12)          => #f
          

list? obj R5RS
Returns #t if obj is a list, otherwise returns #f. By definition, all lists have finite length and are terminated by the empty list.
             (list? '(a b c))     =>  #t
             (list? '())          =>  #t
             (list? '(a . b))     =>  #f
             (let ((x (list 'a)))
               (set-cdr! x x)
               (list? x))         =>  #f
          

list obj ... R5RS
Returns a newly allocated list of its arguments.
             (list 'a (+ 3 4) 'c)            =>  (a 7 c)
             (list)                          =>  ()
          

list* obj ... STKLOS Procedure
list* is like list except that the last argument to list* is used as the cdr of the last pair constructed.
             (list* 1 2 3)        => (1 2 . 3)
             (list* 1 2 3 '(4 5)) => (1 2 3 4 5)
             (list*)              => ()
          

length list R5RS
Returns the length of list.
             (length '(a b c))               =>  3
             (length '(a (b) (c d e)))       =>  3
             (length '())                    =>  0
          

append list ... R5RS
Returns a list consisting of the elements of the first list followed by the elements of the other lists.
             (append '(x) '(y))              =>  (x y)
             (append '(a) '(b c d))          =>  (a b c d)
             (append '(a (b)) '((c)))        =>  (a (b) (c))
          

The resulting list is always newly allocated, except that it shares structure with the last list argument. The last argument may actually be any object; an improper list results if the last argument is not a proper list.

             (append '(a b) '(c . d))        =>  (a b c . d)
             (append '() 'a)                 =>  a
          

append! list ... STKLOS Procedure
Returns a list consisting of the elements of the first list followed by the elements of the other lists. Contrarily to append, the parameter lists (except the last one) are physically modified: their last pair is changed to the value of the next list in the append! formal parameter list.
          (let* ((l1 (list 1 2))
                 (l2 (list 3))
                 (l3 (list 4 5))
                 (l4 (append! l1 l2 l3)))
            (list l1 l2 l3))  => ((1 2 3 4 5) (3 4 5) (4 5))
          
An error is signaled if one of the given lists is a constant list.

reverse list R5RS
Returns a newly allocated list consisting of the elements of list in reverse order.
             (reverse '(a b c))              =>  (c b a)
             (reverse '(a (b c) d (e (f))))  =>  ((e (f)) d (b c) a)
          

reverse! list STKLOS Procedure
Returns a list consisting of the elements of list in reverse order. Contrarily to reverse, the returned value is not newly allocated but computed "in place".
          (let ((l '(a b c)))
            (list (reverse! l) l))        =>  ((c b a) (a))
          (reverse! '(a constant list))   =>  errror
          

list-tail list k R5RS
Returns the sublist of list obtained by omitting the first k elements. It is an error if list has fewer than k elements. List-tail could be defined by
             (define list-tail
                (lambda (x k)
                   (if (zero? k)
                      x
                      (list-tail (cdr x) (- k 1)))))
          

last-pair list STKLOS Procedure
Returns the last pair of list.
          (last-pair '(1 2 3))   => (3)
          (last-pair '(1 2 . 3)) => (2 . 3)
          

list-ref list k R5RS
Returns the kth element of list. (This is the same as the car of (list-tail list k).) It is an error if list has fewer than k elements.
             (list-ref '(a b c d) 2)                 =>  c
             (list-ref '(a b c d)
                       (inexact->exact (round 1.8))) =>  c
          

memq obj list R5RS
memv obj list R5RS
member obj list R5RS
These procedures return the first sublist of list whose car is obj, where the sublists of list are the non-empty lists returned by (list-tail list k) for k less than the length of list. If obj does not occur in list, then #f (not the empty list) is returned. Memq uses eq? to compare obj with the elements of list, while memv uses eqv? and member uses equal?.
             (memq 'a '(a b c))              =>  (a b c)
             (memq 'b '(a b c))              =>  (b c)
             (memq 'a '(b c d))              =>  #f
             (memq (list 'a) '(b (a) c))     =>  #f
             (member (list 'a)
                     '(b (a) c))             =>  ((a) c)
             (memv 101 '(100 101 102))       =>  (101 102)
          

assq obj alist R5RS
assv obj alist R5RS
assoc obj alist R5RS
Alist (for "association list") must be a list of pairs. These procedures find the first pair in alist whose car field is obj, and returns that pair. If no pair in alist has obj as its car, then #f (not the empty list) is returned. Assq uses eq? to compare obj with the car fields of the pairs in alist, while assv uses eqv? and assoc uses equal?.
             (define e '((a 1) (b 2) (c 3)))
             (assq 'a e)                =>  (a 1)
             (assq 'b e)                =>  (b 2)
             (assq 'd e)                =>  #f
             (assq (list 'a) '(((a)) ((b)) ((c))))
                                        =>  #f
             (assoc (list 'a) '(((a)) ((b)) ((c))))
                                        =>  ((a))
             (assv 5 '((2 3) (5 7) (11 13)))
                                        =>  (5 7)
          

Rationale: Although they are ordinarily used as predicates, memq, memv, member, assq, assv, and assoc do not have question marks in their names because they return useful values rather than just #t or #f.

copy-tree obj STKLOS Procedure
Copy-tree recursively copies trees of pairs. If obj is not a pair, it is returned; otherwise the result is a new pair whose car and cdr are obtained by calling copy-tree on the car and cdr of obj, respectively.

filter pred list STKLOS Procedure
filter! pred list STKLOS Procedure
Filter returns all the elements of list that satisfy predicate pred. The list is not disordered: elements that appear in the result list occur in the same order as they occur in the argument list. Filter! does the same job than filter by physically modifying its list argument
          (filter even? '(0 7 8 8 43 -4)) => (0 8 8 -4)
          (let* ((l1 (list 0 7 8 8 43 -4))
                 (l2 (filter! even? l1)))
             (list l1 l2))                => ((0 8 8 -4) (0 8 8 -4))
          
An error is signaled if list is a constant list.

remove pred list STKLOS Procedure
Remove returns list without the elements that satisfy predicate pred:
          (lambda (pred list) (filter (lambda (x) (not (pred x))) list))
          

The list is not disordered - elements that appear in the result list occur in the same order as they occur in the argument list. Remove! does the same job than remove by physically modifying its list argument

          (remove even? '(0 7 8 8 43 -4)) => (7 43)
          

delete x list [=] STKLOS Procedure
delete! x list [=] STKLOS Procedure
Delete uses the comparison procedure =, which defaults to equal?, to find all elements of list that are equal to x, and deletes them from list. The dynamic order in which the various applications of = are made is not specified.

The list is not disordered - elements that appear in the result list occur in the same order as they occur in the argument list.

The comparison procedure is used in this way: (= x ei). That is, x is always the first argument, and a list element is always the second argument. The comparison procedure will be used to compare each element of list exactly once; the order in which it is applied to the various ei is not specified. Thus, one can reliably remove all the numbers greater than five from a list with

          (delete 5 list <)
          

delete! is the linear-update variant of delete. It is allowed, but not required, to alter the cons cells in its argument list to construct the result.