* streams.scm (stream-for-each-many): Correction, should recurse into
        itself, not stream-for-each-one.

I started some words about streams too.  stream-filter and stream-ref
from sicp would be nice additions.


3.1.6 Streams
-------------

Streams represent a sequence of values, each of which is calculated
only when required.  This allows large or even infinite sequences to be
represented, and manipulated with familiar operations like "car",
"cdr", "map" or "fold".  In such manipulations only as much as needed
is actually held in memory at any one time.  The functions in this
section are available from

     (use-modules (ice-9 streams))

   Streams are implemented using promises (*note Delayed Evaluation::),
this is how the underlying calculation of values is made only when
needed, and the values thereafter retained so the calculation is not
repeated.

Here is a simple example producing a stream of all odd numbers,

     (define odds (make-stream (lambda (state)
                                 (cons state (+ state 2)))
                               1))
     (stream-car odds)              => 1
     (stream-car (stream-cdr odds)) => 3

`stream-map' could be used to derive a stream of odd squares,

     (define (square n) (* n n))
     (define oddsquares (stream-map square odds))

   These are infinite sequences, so it's not possible to convert them to
a list, but they could be printed (infinitely) with for example

     (stream-for-each (lambda (n nsq)
                        (format #t "~a squared is ~a\n" n nsq))
                      odds oddsquares)
     -|
     1 squared is 1
     3 squared is 9
     5 squared is 25
     7 squared is 49
     ...


 -- Function: make-stream proc initial-state
     Return a new stream which is the results of calling PROC
     successively.

     Each call is `(PROC state)', it should return a pair, the `car'
     being the value for the stream, and the `cdr' being the new STATE
     for the next call.  For the first call the STATE is the given
     INITIAL-STATE.  At the end of the stream, PROC should return
     something other than a pair.

 -- Function: stream-car stream
     Return the first element from STREAM.  STREAM must not be empty.

 -- Function: stream-cdr stream
     Return a stream which is the second and subsequent elements of
     STREAM.  STREAM must not be empty.

 -- Function: stream-null? stream
     Return true if STREAM is empty.

 -- Function: list->stream list
 -- Function: vector->stream vector
     Return a stream with the contents of LIST or VECTOR.

     LIST or VECTOR should not be modified subsequently, it's
     unspecified whether changes there will be reflected in the stream
     returned.

 -- Function: port->stream port readproc
     Return a stream which gives the values obtained by reading from
     PORT using READPROC.  Each read call made is `(READPROC PORT)', it
     should return an EOF object (*note Reading::) at the end of input.

     For example a stream of characters from a file,

          (port->stream (open-input-file "/foo/bar.txt") read-char)

 -- Function: stream->list stream
     Return a list which is the entire contents of STREAM.

 -- Function: stream->reversed-list stream
     Return a list which is the entire contents of STREAM, but in
     reverse order.

 -- Function: stream->list&length stream
     Return two values (*note Multiple Values::) being a list which is
     the entire contents of STREAM, and the number of elements in that
     list.

 -- Function: stream->reversed-list&length stream
     Return two values (*note Multiple Values::) being a list which is
     the entire contents of STREAM, but in reverse order, and the number
     of elements in that list.

 -- Function: stream->vector stream
     Return a vector which is the entire contents of STREAM.

 -- Function: stream-fold proc init stream0 ... streamN
     Apply PROC successively over the elements of the given streams,
     from first to last.  Return the result from the last PROC call.

     Each call is `(PROC elem0 ... elemN prev)', where each ELEM is
     from the corresponding STREAM.  PREV is the return from the
     previous PROC call, or the given INIT for the first call.

 -- Function: stream-for-each proc stream0 ... streamN
     Call PROC on the elements from the given STREAMs.  The return
     value is unspecified.

     Each call is `(PROC elem0 ... elemN)', where each ELEM is from the
     corresponding STREAM.  `stream-for-each' stops when it reaches the
     end of any of the STREAMs.

 -- Function: stream-map proc stream0 ... streamN
     Return a new stream which is the results of applying PROC to the
     elements of the given STREAMs.

     Each call is `(PROC elem0 ... elemN)', where each ELEM is from the
     corresponding STREAM.  The new stream ends when the end of any of
     the given STREAMs is reached.