@c This file is part of the MIT/GNU Scheme Reference Manual.
-@c $Id: lists.texi,v 1.1 2003/04/15 03:29:50 cph Exp $
+@c $Id: lists.texi,v 1.2 2006/06/14 04:26:50 cph Exp $
@c Copyright 1991,1992,1993,1994,1995 Massachusetts Institute of Technology
@c Copyright 1996,1997,1999,2000,2001 Massachusetts Institute of Technology
-@c Copyright 2002,2003 Massachusetts Institute of Technology
+@c Copyright 2002,2003,2006 Massachusetts Institute of Technology
@c See file scheme.texinfo for copying conditions.
@node Lists, Vectors, Strings, Top
@group
(define x (list 'a 'b 'c))
(define y x)
-y @result{} (a b c)
-(list? y) @result{} #t
-(set-cdr! x 4) @result{} @r{unspecified}
-x @result{} (a . 4)
-(eqv? x y) @result{} #t
-y @result{} (a . 4)
-(list? y) @result{} #f
-(set-cdr! x x) @result{} @r{unspecified}
-(list? y) @result{} #f
+y @result{} (a b c)
+(list? y) @result{} #t
+(set-cdr! x 4) @result{} @r{unspecified}
+x @result{} (a . 4)
+(eqv? x y) @result{} #t
+y @result{} (a . 4)
+(list? y) @result{} #f
+(set-cdr! x x) @result{} @r{unspecified}
+(list? y) @result{} #f
@end group
@end example
@example
@group
-(pair? '(a . b)) @result{} #t
-(pair? '(a b c)) @result{} #t
-(pair? '()) @result{} #f
-(pair? '#(a b)) @result{} #f
+(pair? '(a . b)) @result{} #t
+(pair? '(a b c)) @result{} #t
+(pair? '()) @result{} #f
+(pair? '#(a b)) @result{} #f
@end group
@end example
@end deffn
@example
@group
-(cons 'a '()) @result{} (a)
-(cons '(a) '(b c d)) @result{} ((a) b c d)
-(cons "a" '(b c)) @result{} ("a" b c)
-(cons 'a 3) @result{} (a . 3)
-(cons '(a b) 'c) @result{} ((a b) . c)
+(cons 'a '()) @result{} (a)
+(cons '(a) '(b c d)) @result{} ((a) b c d)
+(cons "a" '(b c)) @result{} ("a" b c)
+(cons 'a 3) @result{} (a . 3)
+(cons '(a b) 'c) @result{} ((a b) . c)
@end group
@end example
@end deffn
+@deffn procedure xcons obj1 obj2
+(@acronym{SRFI} 1) Returns a newly allocated pair whose car is
+@var{obj2} and whose cdr is @var{obj1}.
+
+@example
+(xcons '(b c) 'a) @result{} (a b c)
+@end example
+@end deffn
+
@deffn procedure car pair
@cindex selection, of pair component
@cindex component selection, of pair
@example
@group
-(car '(a b c)) @result{} a
-(car '((a) b c d)) @result{} (a)
-(car '(1 . 2)) @result{} 1
+(car '(a b c)) @result{} a
+(car '((a) b c d)) @result{} (a)
+(car '(1 . 2)) @result{} 1
(car '()) @error{} Illegal datum
@end group
@end example
@example
@group
-(cdr '((a) b c d)) @result{} (b c d)
-(cdr '(1 . 2)) @result{} 2
+(cdr '((a) b c d)) @result{} (b c d)
+(cdr '(1 . 2)) @result{} 2
(cdr '()) @error{} Illegal datum
@end group
@end example
@end deffn
+@deffn procedure car+cdr pair
+(@acronym{SRFI} 1) The fundamental pair deconstructor:
+
+@example
+(lambda (p) (values (car p) (cdr p)))
+@end example
+
+@example
+@group
+(receive (a b) (car+cdr (cons 1 2))
+ (write-line a)
+ (write-line b))
+@print{} 1
+@print{} 2
+@end group
+@end example
+@end deffn
+
@deffn procedure set-car! pair object
Stores @var{object} in the car field of @var{pair}. The value returned
by @code{set-car!} is unspecified.
@group
(define (f) (list 'not-a-constant-list))
(define (g) '(constant-list))
-(set-car! (f) 3) @result{} @r{unspecified}
+(set-car! (f) 3) @result{} @r{unspecified}
(set-car! (g) 3) @error{} Illegal datum
@end group
@end example
@deffn procedure tree-copy tree
@cindex copying, of tree
@cindex tree, copying
-This copies an arbitrary @var{tree} constructed from pairs, copying both
-the car and cdr elements of every pair. This could have been defined by
+(@acronym{SRFI} 1) This copies an arbitrary @var{tree} constructed
+from pairs, copying both the car and cdr elements of every pair. This
+could have been defined by
@example
@group
@example
@group
-(list 'a (+ 3 4) 'c) @result{} (a 7 c)
-(list) @result{} ()
+(list 'a (+ 3 4) 'c) @result{} (a 7 c)
+(list) @result{} ()
@end group
@end example
@end deffn
@deffn procedure make-list k [element]
-This procedure returns a newly allocated list of length @var{k},
-whose elements are all @var{element}. If @var{element} is not supplied,
-it defaults to the empty list.
+(@acronym{SRFI} 1) This procedure returns a newly allocated list of
+length @var{k}, whose elements are all @var{element}. If
+@var{element} is not supplied, it defaults to the empty list.
+
+@example
+(make-list 4 'c) @result{} (c c c c)
+@end example
@end deffn
@deffn procedure cons* object object @dots{}
@findex list
-@code{cons*} is similar to @code{list}, except that @code{cons*} conses
-together the last two arguments rather than consing the last argument
-with the empty list. If the last argument is not a list the result is
-an improper list. If the last argument is a list, the result is a list
-consisting of the initial arguments and all of the items in the final
-argument. If there is only one argument, the result is the argument.
+(@acronym{SRFI} 1) @code{cons*} is similar to @code{list}, except that
+@code{cons*} conses together the last two arguments rather than
+consing the last argument with the empty list. If the last argument
+is not a list the result is an improper list. If the last argument is
+a list, the result is a list consisting of the initial arguments and
+all of the items in the final argument. If there is only one
+argument, the result is the argument.
@example
@group
-(cons* 'a 'b 'c) @result{} (a b . c)
-(cons* 'a 'b '(c d)) @result{} (a b c d)
-(cons* 'a) @result{} a
+(cons* 'a 'b 'c) @result{} (a b . c)
+(cons* 'a 'b '(c d)) @result{} (a b c d)
+(cons* 'a) @result{} a
@end group
@end example
@end example
@end deffn
+@deffn procedure list-tabulate k init-proc
+@deffnx procedure make-initialized-list k init-proc
+Returns a @var{k}-element list. Element @var{i} of the list, where 0
+<= @var{i} < @var{k}, is produced by (@var{init-proc} @var{i}). No
+guarantee is made about the dynamic order in which @var{init-proc} is
+applied to these indices.
+
+@example
+(list-tabulate 4 values) => (0 1 2 3)
+@end example
+
+@code{list-tabulate} is defined by @acronym{SRFI} 1.
+@end deffn
+
@deffn procedure list-copy list
-Returns a newly allocated copy of @var{list}. This copies each of the
-pairs comprising @var{list}. This could have been defined by
+(@acronym{SRFI} 1) Returns a newly allocated copy of @var{list}. This
+copies each of the pairs comprising @var{list}. This could have been
+defined by
@example
@group
@end example
@end deffn
+@deffn procedure iota count [start [step]]
+(@acronym{SRFI} 1) Returns a list containing the elements
+
+@example
+(@var{start} @var{start}+@var{step} @dots{} @var{start}+(@var{count}-1)*@var{step})
+@end example
+
+@var{Count} must be an exact non-negative integer, while @var{start}
+and @var{step} can be any numbers. The @var{start} and @var{step}
+parameters default to 0 and 1, respectively.
+
+@example
+@group
+(iota 5) @result{} (0 1 2 3 4)
+(iota 5 0 -0.1) @result{} (0 -0.1 -0.2 -0.3 -0.4)
+@end group
+@end example
+@end deffn
+
@deffn procedure vector->list vector
@deffnx procedure subvector->list vector start end
@cindex vector, converting to list
is @code{list->vector}.
@example
-(vector->list '#(dah dah didah)) @result{} (dah dah didah)
+(vector->list '#(dah dah didah)) @result{} (dah dah didah)
@end example
@end deffn
-@deffn {procedure} string->list string
-@deffnx {procedure} substring->list string start end
+@deffn procedure string->list string
+@deffnx procedure substring->list string start end
@cindex string, converting to list
@findex list->string
@code{string->list} returns a newly allocated list of the character
@example
@group
-(string->list "abcd") @result{} (#\a #\b #\c #\d)
-(substring->list "abcdef" 1 3) @result{} (#\b #\c)
+(string->list "abcd") @result{} (#\a #\b #\c #\d)
+(substring->list "abcdef" 1 3) @result{} (#\b #\c)
@end group
@end example
@end deffn
@example
@group
-(list? '(a b c)) @result{} #t
-(list? '()) @result{} #t
-(list? '(a . b)) @result{} #f
+(list? '(a b c)) @result{} #t
+(list? '()) @result{} #t
+(list? '(a . b)) @result{} #f
(let ((x (list 'a)))
(set-cdr! x x)
- (list? x)) @result{} #f
+ (list? x)) @result{} #f
+@end group
+@end example
+@end deffn
+
+@deffn procedure circular-list? object
+(@acronym{SRFI} 1) Returns @code{#t} if @var{object} is a circular
+list, otherwise returns @code{#f}.
+
+@example
+@group
+(dotted-list? (list 'a 'b 'c)) @result{} #f
+(dotted-list? (cons* 'a 'b 'c)) @result{} #t
+(dotted-list? (circular-list 'a 'b 'c)) @result{} #f
+@end group
+@end example
+@end deffn
+
+@deffn procedure dotted-list? object
+(@acronym{SRFI} 1) Returns @code{#t} if @var{object} is an improper
+list, otherwise returns @code{#f}.
+
+@example
+@group
+(circular-list? (list 'a 'b 'c)) @result{} #f
+(circular-list? (cons* 'a 'b 'c)) @result{} #f
+(circular-list? (circular-list 'a 'b 'c)) @result{} #t
@end group
@end example
@end deffn
@example
@group
-(length '(a b c)) @result{} 3
-(length '(a (b) (c d e))) @result{} 3
-(length '()) @result{} 0
+(length '(a b c)) @result{} 3
+(length '(a (b) (c d e))) @result{} 3
+(length '()) @result{} 0
+(length (circular-list 'a 'b 'c)) @error{}
+@end group
+@end example
+@end deffn
+
+@deffn procedure length+ clist
+(@acronym{SRFI} 1) Returns the length of @var{clist}, if it is a proper
+list. Returns @code{#f} if @var{clist} is a circular list. Otherwise
+signals an error.
+
+@example
+@group
+(length+ (list 'a 'b 'c)) @result{} 3
+(length+ (cons* 'a 'b 'c)) @error{}
+(length+ (circular-list 'a 'b 'c)) @result{} #f
@end group
@end example
@end deffn
@example
@group
-(null? '(a . b)) @result{} #f
-(null? '(a b c)) @result{} #f
-(null? '()) @result{} #t
+(null? '(a . b)) @result{} #f
+(null? '(a b c)) @result{} #f
+(null? '()) @result{} #t
@end group
@end example
@end deffn
@example
@group
-(list-ref '(a b c d) 2) @result{} c
+(list-ref '(a b c d) 2) @result{} c
(list-ref '(a b c d)
(inexact->exact (round 1.8)))
- @result{} c
+ @result{} c
@end group
@end example
@var{list}.
@end deffn
-@deffn {procedure} append list @dots{}
+@deffn procedure append list @dots{}
@cindex appending, of lists
Returns a list consisting of the elements of the first @var{list}
followed by the elements of the other @var{list}s.
@example
@group
-(append '(x) '(y)) @result{} (x y)
-(append '(a) '(b c d)) @result{} (a b c d)
-(append '(a (b)) '((c))) @result{} (a (b) (c))
-(append) @result{} ()
+(append '(x) '(y)) @result{} (x y)
+(append '(a) '(b c d)) @result{} (a b c d)
+(append '(a (b)) '((c))) @result{} (a (b) (c))
+(append) @result{} ()
@end group
@end example
@example
@group
-(append '(a b) '(c . d)) @result{} (a b c . d)
-(append '() 'a) @result{} a
+(append '(a b) '(c . d)) @result{} (a b c . d)
+(append '() 'a) @result{} a
@end group
@end example
@end deffn
(define x '(a b c))
(define y '(d e f))
(define z '(g h))
-(append! x y z) @result{} (a b c d e f g h)
-x @result{} (a b c d e f g h)
-y @result{} (d e f g h)
-z @result{} (g h)
+(append! x y z) @result{} (a b c d e f g h)
+x @result{} (a b c d e f g h)
+y @result{} (d e f g h)
+z @result{} (g h)
@end group
@end example
@end deffn
@example
@group
(define x '(a b c b))
-(delete 'b x) @result{} (a c)
-x @result{} (a b c b)
+(delete 'b x) @result{} (a c)
+x @result{} (a b c b)
(define x '(a b c b))
-(delete! 'b x) @result{} (a c)
-x @result{} (a c)
+(delete! 'b x) @result{} (a c)
+x @result{} (a c)
@r{;; Returns correct result:}
-(delete! 'a x) @result{} (c)
+(delete! 'a x) @result{} (c)
@r{;; Didn't modify what x points to:}
-x @result{} (a c)
+x @result{} (a c)
@end group
@end example
@end deffn
@example
@group
-(memq 'a '(a b c)) @result{} (a b c)
-(memq 'b '(a b c)) @result{} (b c)
-(memq 'a '(b c d)) @result{} #f
-(memq (list 'a) '(b (a) c)) @result{} #f
-(member (list 'a) '(b (a) c)) @result{} ((a) c)
-(memq 101 '(100 101 102)) @result{} @r{unspecified}
-(memv 101 '(100 101 102)) @result{} (101 102)
+(memq 'a '(a b c)) @result{} (a b c)
+(memq 'b '(a b c)) @result{} (b c)
+(memq 'a '(b c d)) @result{} #f
+(memq (list 'a) '(b (a) c)) @result{} #f
+(member (list 'a) '(b (a) c)) @result{} ((a) c)
+(memq 101 '(100 101 102)) @result{} @r{unspecified}
+(memv 101 '(100 101 102)) @result{} (101 102)
@end group
@end example
@end deffn
@section Mapping of Lists
@cindex mapping, of list
-@deffn {procedure} map procedure list list @dots{}
+@deffn procedure map procedure list list @dots{}
@var{Procedure} must be a procedure taking as many arguments as there
are @var{list}s. If more than one @var{list} is given, then they must
all be the same length. @code{map} applies @var{procedure} element-wise
@example
@group
-(map cadr '((a b) (d e) (g h))) @result{} (b e h)
-(map (lambda (n) (expt n n)) '(1 2 3 4)) @result{} (1 4 27 256)
-(map + '(1 2 3) '(4 5 6)) @result{} (5 7 9)
+(map cadr '((a b) (d e) (g h))) @result{} (b e h)
+(map (lambda (n) (expt n n)) '(1 2 3 4)) @result{} (1 4 27 256)
+(map + '(1 2 3) '(4 5 6)) @result{} (5 7 9)
(let ((count 0))
(map (lambda (ignored)
(set! count (+ count 1))
count)
- '(a b c))) @result{} @r{unspecified}
+ '(a b c))) @result{} @r{unspecified}
@end group
@end example
@end deffn
@end example
@end deffn
-@deffn {procedure} for-each procedure list list @dots{}
+@deffn procedure for-each procedure list list @dots{}
The arguments to @code{for-each} are like the arguments to @code{map},
but @code{for-each} calls @var{procedure} for its side effects rather
than for its values. Unlike @code{map}, @code{for-each} is guaranteed
(for-each (lambda (i)
(vector-set! v i (* i i)))
'(0 1 2 3 4))
- v) @result{} #(0 1 4 9 16)
+ v) @result{} #(0 1 4 9 16)
@end group
@end example
@end deffn
@example
@group
-(reduce + 0 '(1 2 3 4)) @result{} 10
-(reduce + 0 '(1 2)) @result{} 3
-(reduce + 0 '(1)) @result{} 1
-(reduce + 0 '()) @result{} 0
-(reduce + 0 '(foo)) @result{} foo
-(reduce list '() '(1 2 3 4)) @result{} (((1 2) 3) 4)
+(reduce + 0 '(1 2 3 4)) @result{} 10
+(reduce + 0 '(1 2)) @result{} 3
+(reduce + 0 '(1)) @result{} 1
+(reduce + 0 '()) @result{} 0
+(reduce + 0 '(foo)) @result{} foo
+(reduce list '() '(1 2 3 4)) @result{} (((1 2) 3) 4)
@end group
@end example
@end deffn
Like @code{reduce} except that it is right-associative.
@example
-(reduce-right list '() '(1 2 3 4)) @result{} (1 (2 (3 4)))
+(reduce-right list '() '(1 2 3 4)) @result{} (1 (2 (3 4)))
@end example
@end deffn
@example
@group
-(fold-right + 0 '(1 2 3 4)) @result{} 10
+(fold-right + 0 '(1 2 3 4)) @result{} 10
(fold-right + 0 '(foo)) @error{} Illegal datum
-(fold-right list '() '(1 2 3 4)) @result{} (1 (2 (3 (4 ()))))
+(fold-right list '() '(1 2 3 4)) @result{} (1 (2 (3 (4 ()))))
@end group
@end example
@example
@group
-(fold-left list '() '(1 2 3 4)) @result{} ((((() 1) 2) 3) 4)
+(fold-left list '() '(1 2 3 4)) @result{} ((((() 1) 2) 3) 4)
(define (length list)
(fold-left (lambda (sum element) (+ sum 1)) 0 list))
(append! objects objects))
@end group
@end example
+
+@code{circular-list} is compatible with @acronym{SRFI} 1, but extended
+so that it can be called with no arguments.
@end deffn
@deffn procedure reverse list
@example
@group
-(reverse '(a b c)) @result{} (c b a)
-(reverse '(a (b c) d (e (f)))) @result{} ((e (f)) d (b c) a)
+(reverse '(a b c)) @result{} (c b a)
+(reverse '(a (b c) d (e (f)))) @result{} ((e (f)) d (b c) a)
@end group
@end example
@end deffn
@group
(and (@var{procedure} @var{x} @var{y})
(@var{procedure} @var{y} @var{x}))
- @result{} #f
+ @result{} #f
@end group
@end example
@example
@group
(@var{procedure} @var{y} @var{x})
- @result{} #f
+ @result{} #f
@end group
@end example
projects / mit-scheme.git / commitdiff