((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/srfi-40" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.")) (section 2 "SRFI 40: A Library of Streams" (toc)) (section 2 "Documentation" (p "A Chicken implementation of " (link "http://srfi.schemers.org/srfi-40/srfi-40.html" "SRFI 40") ".") (def (sig (constant "stream-null" (id stream-null))) (p (tt "stream-null") " is the distinguished nil stream, a single Scheme object distinguishable from all other objects. If the last stream-pair in a stream contains " (tt "stream-null") " in its " (tt "cdr") " field, the stream is finite and has a computable length. However, there is no need for streams to terminate.") (highlight scheme "stream-null                                 => (stream)")) (def (sig (procedure "(stream-cons object stream)" (id stream-cons))) (p (tt "stream-cons") " is the primitive constructor of streams, returning a stream with the given " (tt "object") " in its " (tt "car") " field and the given " (tt "stream") " in its " (tt "cdr") " field. The stream returned by " (tt "stream-cons") " must be different (in the sense of eqv?) from every other Scheme object. The object may be of any type, and there is no requirement that successive elements of a stream be of the same type, although it is common for them to be. It is an error if the second argument of stream-cons is not a stream.") (highlight scheme "(stream-cons 'a stream-null)                => (stream 'a)\n(stream-cons 'a (stream 'b 'c 'd))          => (stream 'a 'b 'c 'd)\n(stream-cons \"a\" (stream 'b 'c))            => (stream \"a\" 'b 'c)\n(stream-cons 'a 3)                          => error\n(stream-cons (stream 'a 'b) (stream 'c))    => (stream (stream 'a 'b) 'c)")) (def (sig (procedure "(stream? object)" (id stream?))) (p (tt "stream?") " returns " (tt "#t") " if the " (tt "object") " is a stream, and otherwise returns " (tt "#f") ". A stream object may be either the null stream or a stream pair created by " (tt "stream-cons") ".") (highlight scheme "(stream? stream-null)                       => #t\n(stream? (stream-cons 'a stream-null))      => #t\n(stream? 3)                                 => #f")) (def (sig (procedure "(stream-null? object)" (id stream-null?))) (p (tt "stream-null?") " returns " (tt "#t") " if the " (tt "object") " is the distinguished nil stream, and otherwise returns " (tt "#f")) (highlight scheme "(stream-null? stream-null) => #t\n(stream-null? (stream-cons 'a stream-null)) => #f\n(stream-null? 3) => #f")) (def (sig (procedure "(stream-pair? object)" (id stream-pair?))) (p (tt "stream-pair?") " returns " (tt "#t") " if the object is a stream pair created by " (tt "stream-cons") ", and otherwise returns " (tt "#f") ".") (highlight scheme "(stream-pair? stream-null)                  => #f\n(stream-pair? (stream-cons 'a stream-null)) => #t\n(stream-pair? 3)                            => #f")) (def (sig (procedure "(stream-car stream)" (id stream-car))) (p (tt "stream-car") " returns the object in the stream-car field of a stream-pair. It is an error to attempt to evaluate the stream-car of " (tt "stream-null") ".") (highlight scheme "(stream-car (stream 'a 'b 'c))              => a\n(stream-car stream-null)                    => error\n(stream-car 3)                              => error")) (def (sig (procedure "(stream-cdr stream)" (id stream-cdr))) (p (tt "stream-cdr") " returns the stream in the stream-cdr field of a stream-pair. It is an error to attempt to evaluate the stream-cdr of " (tt "stream-null") ".") (highlight scheme "(stream-cdr (stream 'a 'b 'c))              => (stream 'b 'c)\n(stream-cdr stream-null)                    => error\n(stream-cdr 3)                              => error")) (def (sig (procedure "(stream-delay expression)" (id stream-delay))) (p (tt "stream-delay") " is the essential mechanism for operating on streams, taking an " (tt "expression") " and returning a delayed form of the " (tt "expression") " that can be asked at some future point to evaluate the " (tt "expression") " and return the resulting value. The action of " (tt "stream-delay") " is analogous to the action of " (tt "delay") ", but it is specific to the stream data type, returning a stream instead of a promise; no corresponding stream-force is required, because each of the stream functions performs the force implicitly.") (highlight scheme "(define from0\n  (let loop ((x 0))\n    (stream-delay\n      (stream-cons x (loop (+ x 1))))))\nfrom0                                       => (stream 0 1 2 3 4 5 6 ...)")) (def (sig (procedure "(stream object ...)" (id stream))) (p (tt "stream") " returns a newly allocated finite stream of its arguments, in order.") (highlight scheme "(stream 'a (+ 3 4) 'c)                      => (stream 'a 7 'c)\n(stream)                                    => stream-null")) (def (sig (procedure "(stream-unfoldn generator seed n)" (id stream-unfoldn))) (p (tt "stream-unfoldn") " returns " (tt "n") " streams whose contents are produced by successive calls to " (tt "generator") ", which takes the current " (tt "seed") " as an arguments and returns " (tt "n") " + 1 values:") (highlight scheme "    (proc seed) -> seed result0 ... resultN") (p "where " (tt "resultI") " indicates how to produce the next element of the Ith result stream:") (dl (dt (tt "(value)")) (dd "value is the next car of this result stream") (dt (tt "#f")) (dd "no new information for this result stream") (dt (tt "()")) (dd "the end of this result stream has been reached")) (p "Note that getting the next element in any particular result stream may require multiple calls to generator.") (highlight scheme "(define (take5 s)\n  (stream-unfoldn\n    (lambda (x)\n      (let ((n (car x)) (s (cdr x)))\n        (if (zero? n)\n            (values 'dummy '())\n            (values\n              (cons (- n 1) (stream-cdr s))\n              (list (stream-car s))))))\n    (cons 5 s)\n    1))\n(take5 from0)                              => (stream 0 1 2 3 4)")) (def (sig (procedure "(stream-map function stream ...)" (id stream-map))) (p (tt "stream-map") " creates a newly allocated stream built by applying " (tt "function") " elementwise to the elements of the " (tt "stream") "s. The " (tt "function") " must take as many arguments as there are " (tt "stream") "s and return a single value (not multiple values).") (p "The stream returned by " (tt "stream-map") " is finite if the given " (tt "stream") " is finite, and infinite if the given " (tt "stream") " is infinite.") (p "If more than one stream is given, " (tt "stream-map") " terminates when any of them terminate, or is infinite if all the " (tt "stream") "s are infinite. The " (tt "stream") " elements are evaluated in order.") (highlight scheme "(stream-map (lambda (x) (+ x x)) from0)      => (stream 0 2 4 6 8 10 ...)\n(stream-map + (stream 1 2 3) (stream 4 5 6)) => (stream 5 7 9)\n(stream-map (lambda (x) (expt x x))\n  (stream 1 2 3 4 5))                        => (stream 1 4 27 256 3125)")) (def (sig (procedure "(stream-for-each procedure stream ...)" (id stream-for-each))) (p (tt "stream-for-each") " applies " (tt "procedure") " elementwise to the elements of the " (tt "stream") "s, calling the " (tt "procedure") " for its side effects rather than for its values.  The " (tt "procedure") " must take as many arguments as there are streams.  The value returned by " (tt "stream-for-each") " is unspecified. The " (tt "stream") " elements are visited in order.") (highlight scheme "(stream-for-each display from0)             => no value, prints 01234 ...")) (def (sig (procedure "(stream-filter predicate? stream)" (id stream-filter))) (p (tt "stream-filter") " applies " (tt "predicate?") " to each element of " (tt "stream") " and creates a newly allocated stream consisting of those elements of the given " (tt "stream") " for which " (tt "predicate?") " returns a non-" (tt "#f") " value. Elements of the output stream are in the same order as they were in the input stream, and are tested by " (tt "predicate?") " in order.") (highlight scheme "(stream-filter odd? stream-null)            => stream-null\n(take5 (stream-filter odd? from0))          => (stream 1 3 5 7 9)")) (section 3 "Other procedures" (p "For unclear reasons, the following procedures are also exposed:") (p "make-s:promise make-stream make-box srfi-40:eager stream-error") (p "These should probably not be used by programs."))) (section 2 "Author" (p "Philip L. Bewig, ported to hygienic CHICKEN with test suite by " (int-link "/users/klutometis" "Peter Danenberg"))) (section 2 "License" (p "Artistic license")))