[ < ]  [ > ]  [ << ]  [ Up ]  [ >> ]  [Top]  [Contents]  [Index]  [ ? ] 
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 srfi1
 List library and
util.combinations
 Combination library.
See also gauche.collection
 Collection framework and
gauche.sequence
 Sequence framework for generic collection/sequence
operations.
6.6.1 Pair and null class  
6.6.2 List predicates  
6.6.3 List constructors  
6.6.4 List accessors and modifiers  
6.6.5 Walking over lists  
6.6.6 Other list procedures  
6.6.7 Association lists 
[ < ]  [ > ]  [ << ]  [ Up ]  [ >> ]  [Top]  [Contents]  [Index]  [ ? ] 
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 srfi1) (list? (circularlist 1 2)) ⇒ #f (isa? (circularlist 1 2) <list>) ⇒ #t 
A class of empty list. ()
is the only instance.
A class of pairs.
[ < ]  [ > ]  [ << ]  [ Up ]  [ >> ]  [Top]  [Contents]  [Index]  [ ? ] 
[R5RS]
Returns #t
if obj is a pair, #f
otherwise.
[R5RS]
Returns #t
if obj is an empty list, #f
otherwise.
[SRFI1]
Returns #t
if obj is an empty list,
#f if obj
is a pair. If obj is neither
a pair nor an empty list, an error is signaled.
This can be used instead of null?
to check the endoflist
condition when you want to be more picky about nonproper lists.
[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 properlist?
, circularlist?
and
dottedlist?
below.
[SRFI1] Returns #t
if x is a proper list.
[SRFI1] Returns #t
if x is a circular list.
[SRFI1] Returns #t
if x is a finite, nonnilterminated list.
This includes nonpair, non() values (e.g. symbols, numbers),
which are considered to be dotted lists of length 0.
[ < ]  [ > ]  [ << ]  [ Up ]  [ >> ]  [Top]  [Contents]  [Index]  [ ? ] 
[R5RS] Constructs a pair of obj1 and obj2 and returns it.
(cons 'a 'b) ⇒ (a . b) 
[SRFI1] Makes a proper list of length len. If optional argument fill is provided, each element is initialized by it. Otherwise each element is undefined.
(makelist 5 #t) ⇒ (#t #t #t #t #t) 
[R5RS] Makes a list, whose elements are obj ….
(list 1 2 3) ⇒ (1 2 3) (list) ⇒ () 
[SRFI1]
Like list
, but the last argument becomes cdr of the last pair.
Two procedures are exactly the same. Gauche originally had list*
,
and SRFI1 defines cons*
.
(list* 1 2 3) ⇒ (1 2 . 3) (list* 1) ⇒ 1 
[SRFI1] Shallow copies list. If list is circular, this function diverges.
[SRFI1] Returns a list of numbers, starting from start, increasing by step.
(iota 5) ⇒ (0 1 2 3 4) (iota 5 0 0.1) ⇒ (0 0.1 0.2 0.3 0.4) 
This creates a list eagerly. If the list is short it is fast
enough, but if you want to count tens of thousands of numbers,
you may want to do so lazily. See liota
(See section Lazy sequences).
Construct a list by conditionally adding entries. Each clause has a test and expressions. When its test yields true, the result of associated expression is used to construct the resulting list. When the test yields false, nothing is inserted.
Clause must be either one of the following form:
(test expr …)
Test is evaluated, and when it is true, expr … are evaluated, and the return value becomes a part of the result. If no expr is given, the result of test is used if it is not false.
(test => proc)
Test is evaluated, and when it is true, proc is called with the value, and the return value is used to construct the result.
(test @ expr …)
Like (test expr …)
, except that the result of
the last expr must be a list, and it is spliced into
the resulting list, like unquotesplicing.
(test => @ proc)
Like (test => proc)
, except that the result of
proc must be a list, and and it is spliced into
the resulting list, like unquotesplicing.
(let ((alist '((x 3) (y 1) (z 6)))) (condlist ((assoc 'x alist) 'havex) ((assoc 'w alist) 'havew) ((assoc 'z alist) => cadr))) ⇒ (havex 6) (let ((x 2) (y #f) (z 5)) (condlist (x @ `(:x ,x)) (y @ `(:y ,y)) (z @ `(:z ,z)))) ⇒ (:x 2 :z 5) 
[ < ]  [ > ]  [ << ]  [ Up ]  [ >> ]  [Top]  [Contents]  [Index]  [ ? ] 
[R5RS] Returns car and cdr of pair, respectively.
[R5RS] Modifies car and cdr of pair, by obj, respectively.
Note: (setter car)
≡ setcar!
, and
(setter cdr)
≡ setcdr!
.
…
[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) 
[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.
[SRFI1]
If x is a proper list, returns its length.
For all other x, including a circular list,
it returns #f
.
[SRFI1]
take
returns the first i elements of list x.
drop
returns all but the first i elements of list x.
(take '(a b c d e) 2) => (a b) (drop '(a b c d e) 2) => (c d e) 
x may be any value:
(take '(1 2 3 . d) 2) => (1 2) (drop '(1 2 3 . d) 2) => (3 . d) (drop '(1 2 3 . d) 3) => d 
drop
is exactly equivalent to performing i cdr operations
on x. The returned value shares a common tail with x.
On the other hand, take always allocates a new list
for result if the argument is a list of nonzero length.
An error is signalled if i is past the end of list x.
See take*
and drop*
below for more tolerant version.
For generic subsequence extraction from any sequence, see subseq
in Slicing sequence.
More tolerant version of take
and drop
.
They won’t raise an error even if k is larger than the size
of the given list.
If the list is shorter than k elements,
take*
returns a copy of list
by default. If fill? is true, padding is added
to the result to make its length k.
On the other hand, drop*
just returns an empty list
when the input list is shorter than k elements.
(take* '(a b c d) 3) ⇒ (a b c) (take* '(a b c d) 6) ⇒ (a b c d) (take* '(a b c d) 6 #t) ⇒ (a b c d #f #f) (take* '(a b c d) 6 #t 'z) ⇒ (a b c d z z) (drop* '(a b c d) 3) ⇒ (d) (drop* '(a b c d) 5) ⇒ () 
Note: For generic subsequence extraction from any sequence,
see subseq
in Slicing sequence.
[SRFI1]
takeright
returns the last k elements of lis.
dropright
returns all but the last k elements of lis.
(takeright '(a b c d e) 2) => (d e) (dropright '(a b c d e) 2) => (a b c) 
lis may be any finite list.
(takeright '(1 2 3 . d) 2) => (2 3 . d) (dropright '(1 2 3 . d) 2) => (1) (takeright '(1 2 3 . d) 0) => d (dropright '(1 2 3 . d) 0) => (1 2 3) 
takeright
’s return value always shares a common
tail with lis.
dropright
always allocates a new list
if the argument is a list of nonzero length.
An error is signalled if k is larger than the length of lis.
See takeright*
and dropright*
below, for more tolerant
version.
Like take*
and drop*
, but counts from right of list.
If list is shorter than k elements, they won’t raise
an error. Instead, dropright*
just returns an empty list,
and takeright*
returns list itself by default.
If fill? is true for takeright*
,
padding is added on the left of the result to make its length k.
The result still shares the list.
[SRFI1] Linear update variants of take and dropright. Those procedures may destructively modifies lis.
If lis is circular, take!
may return a list
shorter than expected.
[R5RS]
Returns kth 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.
[R5RS+] Returns kth element of list. list can be a proper, dotted or circular list.
By default, listref
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.
[SRFI1] Returns the last pair of list. list can be a proper or dotted list.
(lastpair '(1 2 3)) ⇒ (3) (lastpair '(1 2 . 3)) ⇒ (2 . 3) (lastpair 1) ⇒ error 
[SRFI1]
Returns the last element of the nonempty, finite list pair.
It is equivalent to (car (lastpair pair))
.
(last '(1 2 3)) ⇒ 3 (lastpair '(1 2 . 3)) ⇒ 2 
[SRFI1]
splitat
splits the list x at index i,
returning a list of the first i elements, and the remaining tail.
(splitat '(a b c d e) 2) ⇒ (a b) (c d e) 
splitat!
is the linearupdate variant. It may destructively
modifies x to produce the result.
More tolerant version of splitat
.
Returns the results of take*
and drop*.
(splitat* '(a b c d) 6 #t 'z)
⇒ (a b c d z z) and ()

Splits list into the sublists (slices) where the length of
each slice is k.
If the length of list is not a multiple of k,
the last slice is dealt in the same way as take*
; that is,
it is shorter than k by default, or added padding if
fill? is true.
(slices '(a b c d e f g) 3) ⇒ ((a b c) (d e f) (g)) (slices '(a b c d e f g) 3 #t 'z) ⇒ ((a b c) (d e f) (g z z)) 
Inserts item between elements in the list. (The order of arguments is taken from Haskell’s intersperse).
(intersperse '+ '(1 2 3)) ⇒ (1 + 2 + 3) (intersperse '+ '(1)) ⇒ (1) (intersperse '+ '()) ⇒ () 
[ < ]  [ > ]  [ << ]  [ Up ]  [ >> ]  [Top]  [Contents]  [Index]  [ ? ] 
[R5RS+]
Applies proc for each element(s) of given list(s),
and returns a list of the results. R5RS doesn’t specify
the application order of map
, but Gauche guarantees
proc is always applied in order of the list(s).
Gauche’s map
also terminates as soon as one of
the list is exhausted.
(map car '((a b) (c d) (e f))) ⇒ (a c e) (map cons '(a b c) '(d e f)) ⇒ ((a . d) (b . e) (c . f)) 
Note that the gauche.collection
module (See section gauche.collection
 Collection framework)
extends map
to work on any type of collection.
Like map
, except that tailproc is applied to the cdr
of the last pair in the argument(s) to get the cdr
of
the last pair of the result list. This procedure allows improper
list to appear in the arguments. If a single list is given,
tailproc always receives a nonpair object.
(map*  / '(1 2 3 . 4)) ⇒ (1 2 3 . 1/4) (define (proper lis) (map* values (lambda (p) (if (null? p) '() (list p))) lis)) (proper '(1 2 3)) ⇒ (1 2 3) (proper '(1 2 3 . 4)) ⇒ (1 2 3 4) 
If more than one list are given, the shortest one determines
how tailproc is called. When map*
reaches the
last pair of the shortest list, tailproc is called with
cdrs of the current pairs.
(map* + vector '(1 2 3 4) '(1 2 . 3)) ⇒ (3 6 . #((3 4) 3)) 
Note: The name map*
is along the line of
list*
/cons*
that can produce improper list
(See section List constructors, See section List utilities).
[R5RS]
Applies proc for each element(s) of given list(s) in order.
The results of proc are discarded. The return value of
foreach
is undefined. When more than one list is given,
foreach
terminates as soon as one of the list is exhausted.
Note that the gauche.collection
module (See section gauche.collection
 Collection framework)
extends foreach
to work on any type of collection.
[SRFI1] The fundamental list iterator. When it is given a single list clist1 = (e1 e2 … en), then this procedure returns
(kons en … (kons e2 (kons e1 knil)) … ) 
If n list arguments are provided, then the kons function must take n+1 parameters: one element from each list, and the "seed" or fold state, which is initially knil. The fold operation terminates when the shortest list runs out of values. At least one of the list arguments must be finite.
Examples:
(fold + 0 '(3 1 4 1 5 9)) ⇒ 23 ;sum up the elements (fold cons '() '(a b c d e)) ⇒ (e d c b a) ;reverse (fold cons* '() '(a b c) '(1 2 3 4 5)) ⇒ (c 3 b 2 a 1) ;nary case 
[SRFI1] The fundamental list recursion operator. When it is given a single list clist1 = (e1 e2 … en), then this procedure returns
(kons e1 (kons e2 … (kons en knil))) 
If n list arguments are provided, then the kons function must take n+1 parameters: one element from each list, and the "seed" or fold state, which is initially knil. The fold operation terminates when the shortest list runs out of values. At least one of the list arguments must be finite.
Examples:
(foldright cons '() '(a b c d e)) ⇒ (a b c d e) ;copy list (foldright cons* '() '(a b c) '(1 2 3 4 5)) ⇒ (a 1 b 2 c 3) ;nary case 
[R6RS] This is another variation of leftassociative folding. When it is given a single list clist1 = (e1 e2 … en), then this procedure returns:
(snok (… (snok (snok knil e1) e2) …) en) 
Compare this with fold
above; association is the same, but the order
of arguments passed to the procedure snok is reversed from the way
arguments are passed to kons in fold
. If snok is
commutative, fold
and foldleft
produces the same result.
(foldleft + 0 '(1 2 3 4 5) ⇒ 15 (foldleft cons 'z '(a b c d)) ⇒ ((((z . a) . b) . c) . d) (foldleft (^[a b] (cons b a)) 'z '(a b c d)) ⇒ (a b c d z) 
If more than one lists are given, snok is called with
the current seed value knil and each corresponding
element of the input lists
clist1
clist2
….
(foldleft list 'z '(a b c) '(A B C)) ⇒ (((z a A) b B) c C) 
Note: Most functional languages have left and right associative
fold operations, which correspond to foldleft
and foldright
,
respectively.
(e.g. Haskell’s foldl
and foldr
). In Scheme, SRFI1
first introduced fold
and foldright
. R6RS introduced
foldleft
. (However, in R6RS the behavior is undefined if the lengths of
clist1
clist2
… aren’t the same, while in Gauche
foldleft
terminates as soon as any one of the lists terminates.)
[SRFI1] A procedure pred is applied on each element of list, and a list of elements that pred returned true on it is returned.
(filter odd? '(3 1 4 5 9 2 6)) ⇒ (3 1 5 9) 
filter!
is the linearupdate variant. It may destructively
modifies list to produce the result.
[SRFI1]
Like map
, but only true values are saved.
At least one of the list arguments must be finite.
(filtermap (lambda (x) (and (number? x) (* x x))) '(a 1 b 3 c 7)) ⇒ (1 9 49) 
[SRFI1] A procedure pred is applied on each element of list, and a list of elements that pred returned false on it is returned.
(remove odd? '(3 1 4 5 9 2 6)) ⇒ (4 2 6) 
remove!
is the linearupdate variant. It may destructively
modifies list to produce the result.
[SRFI1]
Applies pred for each element of clist, from
left to right, and returns the first element that pred returns
true on. If no element satisfies pred, #f
is returned.
[SRFI1]
Applies pred for each element of clist, from left to right,
and when pred returns a true value, returns the pair whose car
is the element. If no element satisfies pred, #f
is returned.
[SRFI1]
Applies pred across each element of clists, and
returns as soon as pred returns a nonfalse value.
The return value of any
is the nonfalse value pred returned.
If clists are exhausted before pred returns a nonfalse
value, #f
is returned.
[SRFI1]
Applies pred across each element of clists, and
returns #f
as soon as pred returns #f
.
If all application of pred return a nonfalse value,
every
returns the last result of the applications.
[SRFI1] Equivalent to
(remove (lambda (y) (elt= x y)) list) (remove! (lambda (y) (elt= x y)) list) 
The comparison procedure, elt=, defaults to equal?
.
[SRFI1]
Removes duplicate elements from list.
If there are multiple equal elements in list,
the result list only contains the first or leftmost of these
elements in the result. The order of these surviving elements
is the same as in the original list.
The comparison procedure, elt=, defaults to equal?
.
[ < ]  [ > ]  [ << ]  [ Up ]  [ >> ]  [Top]  [Contents]  [Index]  [ ? ] 
[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.
[SRFI1] 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.
[R5RS+, SRFI1+]
Returns a list consisting of the elements of list
in the reverse order.
While reverse
always returns
a newly allocated list, reverse!
may reuse the cells
of list. Even list is destructively modified
by reverse!
, you should use its return value, for
the first cell of list may not be the first cell
of the returned list.
If an optional argument tail is given, it becomes the tail of the returned list (tail isn’t copied). It is useful in the idiom to prepend the processed results on top of already existing results.
(reverse '(1 2 3 4 5)) ⇒ (5 4 3 2 1) (reverse '(1 2 3) '(a b)) ⇒ (3 2 1 a b) 
The tail argument isn’t in the traditional Scheme’s reverse
.
The rationale is the following correspondence:
(reverse xs) ≡ (fold cons xs '()) (reverse xs tail) ≡ (fold cons xs tail) 
[R5RS][SRFI1]
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
),
(listtail list n)
is returned.
Otherwise, #f
is returned.
The optional obj= argument of member
is SRFI1’s
extension to R5RS. If given, it is used as a equivalence predicate
instead of 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 (memv 101 '(100 101 102)) ⇒ (101 102) 
[ < ]  [ > ]  [ << ]  [ Up ]  [ >> ]  [Top]  [Contents]  [Index]  [ ? ] 
Returns (cons (cons obj1 obj2) obj3)
.
Useful to put an entry at the head of an associative list.
(This procedure is defined in SRFI1 as alistcons
; See section srfi1
 List library).
(acons 'a 'b '((c . d))) ⇒ ((a . b) (c . d)) 
[SRFI1] Returns a fresh copy of alist. The spine of alist and each cell that points a key and a value is copied.
(define a (list (cons 'a 'b) (cons 'c 'd))) a ⇒ ((a . b) (c . d)) (define b (alistcopy a)) b ⇒ ((a . b) (c . d)) (setcdr! (car a) 'z) a ⇒ ((a . z) (c . d)) b ⇒ ((a . b) (c . d)) 
[R5RS][SRFI1]
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
.
The optional argument of ascoc
is an extension defined
in SRFI1. If given, it is called instead of equal?
to check the equivalence of obj and each key.
[SRFI1]
Deletes all cells in alist whose key is the same as key.
Comparison is done by a procedure key=. The default is eqv?
.
The linearupdate version alistdelete!
may or may not modify
alist.
Reverse associations—given key is matched to the cdr
of each element in alist, instead of the car.
Handy to realize bidirectional associative list.
Rassoc
takes an optional comparison function, whose default is
equal?
. Rassq
and rassv
uses eq? and eqv?.
These procedures provide the access to the assoc list
symmetric with other *ref
procedures.
(Note that the argument order is different from assoc
, assq
and assv
– *ref
procedures take a container first,
and an item second.)
This captures the common pattern of alist access:
(assocref alist key default eqfn) ≡ (cond [(assoc key alist eqfn) => cdr] [else default]))) 
If default is omitted, #f
is used.
Assocref
takes an optional comparison function eqfn,
whose default is equal?
. Assqref
and assvref
uses eq?
and eqv?
, respectively.
Reverse association version of assocref
.
(rassocref alist key default eqfn) ≡ (cond ((rassoc key alist eqfn) => car) (else default)))) 
The meanings of optional arguments are the same as assocref
.
Returns an alist who has (key . val)
pair added to the alist
.
If alist
already has an element with key, the element’s
cdr is destructively modified for val.
If alist doesn’t have an element with key, a new pair
is created and appended in front of alist; so you should use
the return value to guarantee keyval pair is added.
Assocset!
takes optional comparison function eqfn,
whose default is equal?
. Assqset!
and assvset!
uses eq?
and eqv?
, respectively.
[ < ]  [ > ]  [ << ]  [ Up ]  [ >> ] 
This document was generated by Shiro Kawai on May 28, 2012 using texi2html 1.82.