6.4 Pairs and Lists

Pairs and lists are one of the most fundamental data structure in Scheme. Gauche core provides all standard list procedures, plus some useful procedures that are commonly supported in lots of implementations. If they are not enough, you can find more procedures in the modules described in srfi-1 - List library, util.list - Additional list library, and util.combinations - Combination library. See also gauche.collection - Collection framework and gauche.sequence - Sequence framework for generic collection/sequence operations.

6.4.1 Pair and null class

Builtin Class: <list>

An abstract class represents lists. A parent class of <null> and <pair>. Inherits <sequence>.

Note that a circular list is also an instance of the <list> class, while R5RS procedure list? returns false on the circular lists and dotted lists.

(use srfi-1) (list? (circular-list 1 2)) ⇒ #f (is-a? (circular-list 1 2) <list>) ⇒ #t

Builtin Class: <null>

A class of empty list. () is the only instance.

Builtin Class: <pair>

A class of pairs.

6.4.2 List predicates

Function: pair? obj

[R5RS] Returns #t if obj is a pair, #f otherwise.

Function: null? obj

[R5RS] Returns #t if obj is an empty list, #f otherwise.

Function: list? obj

[R5RS] Returns #t if obj is a proper list, #f otherwise. This function returns #f if obj is a dotted or circular list.

See also proper-list?, circular-list? and dotted-list? in List predicates.

6.4.3 List constructors

Function: cons obj1 obj2

[R5RS] Constructs a pair of obj1 and obj2 and returns it.

(cons 'a 'b) ⇒ (a . b)

Function: acons obj1 obj2 obj3

Returns (cons (cons obj1 obj2) obj3). Useful to put an entry at the head of an associative list.

(acons 'a 'b '((c . d))) ⇒ ((a . b) (c . d))

Function: make-list len &optional fill

[SRFI-1] Makes a proper list of length len. If optional argument fill is provided, each element is initialized by it. Otherwise each element is undefined.

(make-list 5 #t) ⇒ (#t #t #t #t #t)

Function: list obj …

[R5RS] Makes a list, whose elements are obj ….

(list 1 2 3) ⇒ (1 2 3) (list) ⇒ ()

Function: list* obj1 obj2 …

Like list, but the last argument becomes cdr of the last pair. SRFI-1 defines the same function with the name cons*.

(list* 1 2 3) ⇒ (1 2 . 3) (list* 1) ⇒ 1

Function: list-copy list

[SRFI-1] Shallow copies list. If list is circular, this function diverges.

6.4.4 List accessors and modifiers

Function: car pair

Function: cdr pair

[R5RS] Returns car and cdr of pair, respectively.

Function: set-car! pair obj

Function: set-cdr! pair obj

[R5RS] Modifies car and cdr of pair, by obj, respectively.

Note: (setter car) ≡ set-car!, and (setter cdr) ≡ set-cdr!.

Function: caar pair

Function: cadr pair

…

Function: cdddar pair

Function: cddddr pair

[R5RS] caar ≡ (car (car x)), cadr ≡ (car (cdr x)), and so on.

The corresponding setters are also defined.

(let ((x (list 1 2 3 4 5))) (set! (caddr x) -1) x) ⇒ (1 2 -1 4 5)

Function: length list

[R5RS] Returns the length of a proper list list. If list is a dotted list, an error is signalled. If list is a circular list, this function diverges.

If you want to handle circular lists as well, See length+ in List miscellaneous routines.

Function: list-tail list k &optional fallback

[R5RS] Returns k-th cdr of list. list can be a proper, dotted or circular list. (If list is a dotted list, its last cdr is simply ignored).

If k is negative or larger than the length of list, the behavior depends on whether the optional fallback argument is given or not. If fallback is given, it is returned. Otherwise, an error is signalled.

Function: list-ref list k &optional fallback

[R5RS+] Returns k-th element of list. list can be a proper, dotted or circular list.

By default, list-ref signals an error if k is negative, or greater than or equal to the length of list. However, if an optional argument fallback is given, it is returned for such case. This is an extension of Gauche.

Function: last-pair list

[SRFI-1] Returns the last pair of list. list can be a proper or dotted list.

6.4.5 Other list procedures

Function: append list …

[R5RS] Returns a list consisting of the elements of the first list followed by the elements of the other lists. 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.

Function: append! list …

[SRFI-1] Returns a list consisting of the elements of the first list followed by the elements of the other lists. The cells in the lists except the last one may be reused to construct the result. The last argument may be any object.

Function: reverse list

[R5RS] Returns a newly allocated list consisting of the elements of list in reverse order.

Function: reverse! list

[SRFI-1] Returns a list consisting of the elements of list in reverse order. The cells of list may be reused to construct the returned list.

Function: memq obj list

Function: memv obj list

Function: member obj list

[R5RS] Searches obj in the list. If n-th element of list equals to obj (in the sense of eq? for memq, eqv? for memv, and equal? for member), (list-tail list n) is returned. Otherwise, #f is returned.

If you use SRFI-1 (See section srfi-1 - List library), member is extended to take optional argument for a equality procedure.

(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 (memv 101 '(100 101 102)) ⇒ (101 102)

Function: assq obj list

Function: assv obj list

Function: assoc obj list

[R5RS] Each element in list must be a pair. These procedures search a pair whose car matches obj (in the sense of eq? for assq, eqv? for assv, and equal? for assoc) from left to right, and return the leftmost matched pair if any. If no pair matches, these return #f.

If you use SRFI-1 (See section srfi-1 - List library), assoc is extended to take optional argument for a equality procedure.

This document was generated by Shiro Kawai on October, 7 2008 using texi2html 1.78.