source: project/wiki/eggref/5/biglists @ 37411

[[tags: egg]]
[[toc:]]

== Eager and lazy lists united

This is an attempt to unify eager and lazy list. To use this egg you
should carefully note the following

=== Rationale

* All routines start uppercase.

Hence they don't interfere with ordinary list routines.

* The order of arguments is consistent.

Procedure arguments first, list arguments last.
For example, there is no List-ref routine, use At instead.

* Most routines are defined in curried and uncurried form.

So, curried versions can be used in Map and friends.
The documentation shows both signatures, but explains only the
uncurried form.

* Biglists are either eager or lazy.

* Lazy biglists are either finite or infinite.

* All biglists are basically constructed with the macro Cons.

This macro has two arguments for eager biglists, and an additional third
argument, finite?, for lazy biglists.

* The empty lazy biglist is the eos objects. 

* The emppy eager biglist is '(), as usual.

* There are no Car and Cdr routines, but First and Rest instead.

They behave differently: First returns eos at the empty biglist, and Rest
returns itself at the empty biglist.
Hence At can access even finite biglists at any position, it would
simply return eos past the length of finite biglists.

* Pattern matching on biglists is available via the bindings egg.

To achieve that, bind-seq-db is already updated.

* List comprehensions work as well for biglists.

This is provided by the For macro.

=== Documentation

Note, that the signatures of curried and uncurried versions are listed,
but only the uncurried ones are described.

==== biglists

<procedure>(biglists)</procedure>
<procedure>(biglists sym)</procedure>

The first call returns the list of exported symbols, the second
documentation for the exported symbol sym.

==== Append

<procedure>(Append xs . xss)</procedure>

appends all argument lists, provided all but the last
are finite

==== Assoc

<procedure>(Assoc key)</procedure>
<procedure>(Assoc key xs)</procedure>

returns the biglist, whose First or car is Equal? to key

==== Assp

<procedure>(Assp ok?)</procedure>
<procedure>(Assp ok? xs)</procedure>

returns the biglist, whose First or car passes ok?

==== Assq

<procedure>(Assq key)</procedure>
<procedure>(Assq key xs)</procedure>

returns the biglist, whose First or car is Eq? to key

==== Assv

<procedure>(Assv key)</procedure>
<procedure>(Assv key xs)</procedure>

returns the biglist, whose First or car is Eqv? to key

==== At

<procedure>(At k)</procedure>
<procedure>(At k xs)</procedure>

returns the kth item of xs

==== BigList?

<procedure>(BigList? xpr)</procedure>

type predicate

==== BigList->list

<procedure>(BigList->list xs)</procedure>
<procedure>(BigList->list k xs)</procedure>

transforms a possibly infinite biglist xs into a list

==== Cons

<macro>(Cons x y finite?)</macro>
<macro>(Cons x y)</macro>

returns either a lazy or an eager biglist

==== Cycle

<procedure>(Cycle xs)</procedure>

returns an infinite biglist by appending the finite
biglist xs over and over

==== Cycle-times

<procedure>(Cycle k xs)</procedure>

returns a finite biglist by appending the finite
biglist xs k times

==== Drop

<procedure>(Drop k)</procedure>
<procedure>(Drop k xs)</procedure>

drops the first k items of xs

==== Drop-while

<procedure>(Drop-while ok?)</procedure>
<procedure>(Drop-while ok? xs)</procedure>

returns the xs whith those front items x removed
which pass ok?

==== Drop-until

<procedure>(Drop-until ok?)</procedure>
<procedure>(Drop-until ok? xs)</procedure>

returns the xs whith those front items x removed
which don't pass ok?

==== Eager?

<procedure>(Eager? xpr)</procedure>

is xpr an eager biglist, i.e. a normal list?

==== Eq?

<procedure>(Eq? xs ys)</procedure>

returns #t if both lists have same length
and corresponding items are eq?

==== Eqp?

<procedure>(Eqp? =?)</procedure>
<procedure>(Eqp? =? xs ys)</procedure>

returns #t if both lists have same length
and corresponding items are =?

==== Equal?

<procedure>(Equal? xs ys)</procedure>

returns #t if both lists have same length
and corresponding items are equal?

==== Eqv?

<procedure>(Eqv? xs ys)</procedure>

returns #t if both lists have same length
and corresponding items are eqv?

==== Every?

<procedure>(Every? ok?)</procedure>
<procedure>(Every? ok? xs)</procedure>

returns #t if every item of the finite biglist xs
passes the ok? test

==== Filter

<procedure>(Filter ok?)</procedure>
<procedure>(Filter ok? xs)</procedure>

removes all items from the biglist xs which
do not pass the ok? test

==== Fold-left

<procedure>(Fold-left op init)</procedure>
<procedure>(Fold-left op init . xss)</procedure>

folds the finite biglists xss from the left

==== Fold-left0

<procedure>(Fold-left0 op)</procedure>
<procedure>(Fold-left0 op . xss)</procedure>

folds the finite biglists<procedure>(map Rest xss) from the left
with init<procedure>(map First xss)</procedure>

==== Fold-right

<procedure>(Fold-right op init)</procedure>
<procedure>(Fold-right op init . xss)</procedure>

folds the finite biglists xss from the right

==== Fold-right0

<procedure>(Fold-right0 op)</procedure>
<procedure>(Fold-right0 op . xss)</procedure>

folds the finite biglists<procedure>(map Rest xss) from the right
with init<procedure>(map First xss)</procedure>

==== For

<macro>(For ((var xs ok? ...) ....) item)</macro>

creates a new list by binding var to each element
of the list xs in sequence, and if it passes the checks,
ok? ..., inserts item into the result list.
The qualifieres, (var xs ok? ...), are processed
sequentially from left to right, so that filters of a
qualifier have access to the variables of qualifiers
to its left.

==== For-each

<procedure>(For-each fn)</procedure>
<procedure>(For-each fn . xss)</procedure>

applies the procedure fn to each list of items
of xss at each commeon index

==== First

<procedure>(First xs)</procedure>

returns the front item of xs, which might be eos,
if xs is empty

==== Index

<procedure>(Index ok?)</procedure>
<procedure>(Index ok? xs)</procedure>

returns the index of the first item of the biglist xs,
which passes the ok? test

==== Iterate

<procedure>(Iterate fn)</procedure>
<procedure>(Iterate fn x)</procedure>

returns an infinite list by iteratively
applying fn to x

==== Iterate-times

<procedure>(Iterate-times fn times)</procedure>
<procedure>(Iterate-times fn times x)</procedure>

returns a finite list of lentgh times by
iteratively applying fn to x

==== Iterate-until

<procedure>(Iterate-until fn ok?)</procedure>
<procedure>(Iterate-until fn ok? x)</procedure>

returns a finite list by iteratively applying
fn to x until ok? returns #t on the result

==== Iterate-while

<procedure>(Iterate-while fn ok?)</procedure>

returns a finite list by iteratively applying
fn to x as long as ok? returns #t on the result

==== Lazy?

<procedure>(Lazy? xpr)</procedure>

is xpr a lazy biglist?

==== Length

<procedure>(Length xs)</procedure>

retuns the length of a finite biglist or #f
of an infinite one

==== List

<procedure>(List . args)</procedure>

creates a lazy finite biglist with items args

==== List?

<procedure>(List? xpr)</procedure>

is xpr a finite biglist?

==== List-of?

<procedure>(List-of? . oks?)</procedure>
<procedure>(List-of? k . oks?)</procedure>

returs a predicate on a biglist, which checks,
if every item<procedure>(or Take k item) is a finite biglist

==== Map

<procedure>(Map fn)</procedure>
<procedure>(Map fn . xss)</procedure>

maps every list of of items at fixed index of xss
with function fn

==== Member

<procedure>(Member x)</procedure>
<procedure>(Member x xs)</procedure>

returns the first tail af the biglist xs
whose first item is equal? to x

==== Memp

<procedure>(Memp ok?)</procedure>
<procedure>(Memp ok? xs)</procedure>

returns the first tail af the biglist xs
which passes the ok? test

==== Memq

<procedure>(Memq x)</procedure>
<procedure>(Memq x xs)</procedure>

returns the first tail af the biglist xs
whose first item is eqv? to x

==== Memv

<procedure>(Memv x)</procedure>
<procedure>(Memv x xs)</procedure>

returns the first tail af the biglist xs
whose first item is eqv? to x

==== Merge

<procedure>(Merge <? xs ys)</procedure>

merges two finite finite biglists xs and ys,
both lazy or both eager, with respect to <?

==== Null?

<procedure>(Null? xs)</procedure>

is the biglist xs empty?

==== Print

<procedure>(Print k xs)</procedure>
<procedure>(Print xs)</procedure>

print the items of a finite biglist,
or the first k items of an infinite one

==== Range

<procedure>(Range upto)</procedure>
<procedure>(Range from upto)</procedure>
<procedure>(Range from upto step)</procedure>

creates a list of numbers with given limits
from defaults to 0
step defaults to 1
the list is infinite, if utpo is #f

==== Read-forever

<procedure>(Read-forever)</procedure>

creates an infinite biglist of prompted
read procedures

==== Remove

<procedure>(Remove x)</procedure>
<procedure>(Remove x xs)</procedure>

removes all items of the biglist xs, which
are equal? to x

==== Remp

<procedure>(Remp ok?)</procedure>
<procedure>(Remp ok? xs)</procedure>

removes all items of the biglist xs, which
pass the ok? test

==== Remq

<procedure>(Remp x)</procedure>
<procedure>(Remp x xs)</procedure>

removes all items of the biglist xs, which
are eq? to x

==== Remv

<procedure>(Remp x)</procedure>
<procedure>(Remp x xs)</procedure>

removes all items of the biglist xs, which
are eqv? to x

==== Repeat

<procedure>(Repeat x)</procedure>

returns an infinite biglist with all items x

==== Repeat-times

<procedure>(Repeat-times k x)</procedure>

returns a finite biglist of length k with all items x

==== Rest

<procedure>(Rest xs)</procedure>

returns the rest of the biglist except the front item
which might be xs itself, if empty

==== Reverse

<procedure>(Reverse xs)</procedure>
<procedure>(Reversee xs ys)</procedure>

Append the reverse of xs to ys
xs must be finite

==== Reverse*

<procedure>(Reverse* xs)</procedure>

retrurns the list of reverses of
of all finite takes

==== Scan-left

<procedure>(Scan-left op init)</procedure>
<procedure>(Scan-left op init . xss)</procedure>

returns a biglist, whose item at index k
is the left fold of (map (Take k) xss)

==== Scan-right

<procedure>(Scan-right op init)</procedure>
<procedure>(Scan-right op init . xss)</procedure>

returns a biglist, whose item at index k
is the right fold of (map (Take k) xss)

==== Some?

<procedure>(Some? ok?)</procedure>
<procedure>(Some? ok? xs)</procedure>

returns #t if some item of the finite biglist xs
passes the ok? test

==== Sort

<procedure>(Sort <?)</procedure>
<procedure>(Sort <? xs)</procedure>

sorts the finite biglist xs with respect to <?

==== Sorted?

<procedure>(Sorted? <?)</procedure>
<procedure>(Sorted? <? xs)</procedure>

is the biglist xs finite and sorted?

==== Take

<procedure>(Take k)</procedure>
<procedure>(Take k xs)</procedure>

returns the finite biglist of the first
k items of the biglist xs

==== Take-until

<procedure>(Take-until ok?)</procedure>
<procedure>(Take-until ok? xs)</procedure>

returns the finite biglist of the first
items of the biglist xs, which do not pass
the ok? test

==== Take-while

<procedure>(Take-while ok?)</procedure>
<procedure>(Take-while ok? xs)</procedure>

returns the finite biglist of the first
items of the biglist xs, which do pass
the ok? test

==== Unzip

<procedure>(Unzip xs)</procedure>

returns two values, the sublists of biglist xs
of even or uneven index

==== Zip

<procedure>(Zip xs ys)</procedure>

merges the biglists xs and ys by alternatively
Consing (First xs) or (First ys) to the result
biglist. Works for unfinite biglists as well.

==== eos

end-of-sequence indicator

=== Dependencies

bindings

=== Examples

<enscript highlight=scheme>

(import biglists bindings)

(define ones (Cons 1 ones #f))

(First eos) ;-> eos

(At 2 '(0 1 2 3 4)) ;-> 2

(At 3 (List 0 1 2 3 4) ;-> 3

(List? (List 0 1 2 3 4) ;-> #t

(List? '(0 1 2 3 4)) ;-> #t

(BigList->list (Take 4 integers)) ;-> '(0 1 2 3)

(First (Drop 4 integers)) ;-> 4

(BigList->list (Reverse (List 0 1 2 3))) ;-> '(3 2 1 0)

(Fold-right + 0 (List 1 2 3)) ;-> 6

(Fold-left + 0 '(1 2 3)) ;-> 6

(Length  (Scan-right + 0 four four)) ;-> 4

(BigList->list 12 (Zip (List 0 1 2 3) integers))
  ;-> '(0 0 1 1 2 2 3 3 4 5 6 7)

(BigList->list 10 (nth-value 0 (Unzip integers)))
  ;-> '(0 2 4 6 8 10 12 14 16 18)

(BigList->list 10 (nth-value 1 (Unzip integers)))
  ;-> '(1 3 5 7 9 11 13 15 17 19)

(Merge <= '(0 1 2 3 4) '(0 1 2 3 4))
  ;-> '(0 0 1 1 2 2 3 3 4 4)

(BigList->list (Sort <= (Append (List 0 1 2 3) (List 0 1 2 3))))
  ;-> '(0 0 1 1 2 2 3 3)

(BigList->list 10 (Memv 3 integers))
  ;-> '(3 4 5 6 7 8 9 10 11 12)

(BigList->list (Assp odd? (List (List 0 5) (List 1 6) (List 2 7))))
  ;-> '(1 6)

(BigList->list 5 (Range #f)) ;-> '(0 1 2 3 4)

(BigList->list (Iterate-times add1 5 1))
  ;-> '(1 2 3 4 5)

(bind (x . xs) integers (list x (BigList->list 5 xs)))
  ;-> '(0 (1 2 3 4 5))

(bind (x (y . ys) z) (List 1 integers 3)
  (list x y z (BigList->list 5 ys)))
  ;-> '(1 0 3 (1 2 3 4 5))

(BigList->list (For ((x (List 0 1 2 3)) (add1 x))) ;  map
  ;-> '(1 2 3 4))

(BigList->list (For ((x (List 0 1 2 3 4 5 6) (odd? x))) x)) ; filter
  ;-> '(1 3 5))

(BigList->list (For ((n (List 0 1 2 3 4 5 6) (positive? n) (even? n)))
                 (* 10 n)))
  ;-> '(20 40 60))

(BigList->list (For ((c (List 'A 'B 'C)) ;lazy
                     (k '(1 2 3 4))) ;eager
                 (list c k)))
  ;-> '((A 1) (A 2) (A 3) (A 4)
  ;     (B 1) (B 2) (B 3) (B 4)
  ;     (C 1) (C 2) (C 3) (C 4))

(For ((c '(A B C)) ;eager
      (k (List 1 2 3 4))) ;lazy
  (list c k))
  ;-> '((A 1) (A 2) (A 3) (A 4)
  ;     (B 1) (B 2) (B 3) (B 4)
  ;     (C 1) (C 2) (C 3) (C 4))

</enscript>

== Last update

Mar 17, 2019

== Author

[[/users/juergen-lorenz|Juergen Lorenz]]

== License

 Copyright (c) 2014-2019, Juergen Lorenz
 All rights reserved.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are
 met:
 
 Redistributions of source code must retain the above copyright
 notice, this list of conditions and the following disclaimer.
 
 Redistributions in binary form must reproduce the above copyright
 notice, this list of conditions and the following disclaimer in the
 documentation and/or other materials provided with the distribution.
 Neither the name of the author nor the names of its contributors may be
 used to endorse or promote products derived from this software without
 specific prior written permission. 
   
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

== Version History

; 0.1 : initial import