scsh-0.5/scsh/lib/srfi-1.txt

The SRFI-1 list library						-*- outline -*-
Olin Shivers
98/10/16
Last Update: 99/10/3

Emacs should display this document in outline mode. Say c-h m for
instructions on how to move through it by sections (e.g., c-c c-n, c-c c-p).
During the SRFI discussion period, the current draft may be found at
    ftp://ftp.ai.mit.edu/people/shivers/srfi/srfi-1/srfi-1.txt


* Table of contents
-------------------

Abstract
Introduction
Procedure index
General discussion
  "Linear update" procedures
  Improper lists
  Errors
  Not included in this library
The procedures
  Constructors
  Predicates
  Selectors
  Miscellaneous: length, append, reverse, zip & count
  Fold, unfold & map
  Filtering & partitioning
  Searching
  Deletion
  Association lists
  Set operations on lists
  Primitive side-effects
Acknowledgements
References & links
Copyright


* Abstract
----------

R5RS Scheme has an impoverished set of list-processing utilities, which is a
problem for authors of portable code.  This SRFI proposes a coherent and
comprehensive set of list-processing procedures; it is accompanied by a
reference implementation of the spec. The reference implementation is
    - portable
    - efficient
    - completely open, public-domain source


* Introduction
--------------

The set of basic list and pair operations provided by R4RS/R5RS Scheme is far
from satisfactory. Because this set is so small and basic, most
implementations provide additional utilities, such as a list-filtering
function, or a "left fold" operator, and so forth. But, of course, this
introduces incompatibilities -- different Scheme implementations provide
different sets of procedures.

I have designed a full-featured library of procedures for list processing.
While putting this library together, I checked as many Schemes as I could get
my hands on. (I have a fair amount of experience with several of these
already.) I missed Chez -- no on-line manual that I can find -- but I hit most
of the other big, full-featured Schemes. The complete list of list-processing
systems I checked is:
    R4RS/R5RS Scheme, MIT Scheme, Gambit, RScheme, MzScheme, slib, Common
    Lisp, Bigloo, guile, T, APL and the SML standard basis
As a result, the library I am proposing is fairly rich.

Following this initial design phase, this library went through several
months of discussion on the SRFI mailing lists, and was altered in light
of the ideas and suggestions put forth during this discussion.

In parallel with designing this API, I have also written a reference
implementation. I have placed this source on the Net with an unencumbered,
"open" copyright. A few notes about the reference implementation:

  - Although I got procedure names and specs from many Schemes, I wrote this
    code myself.  Thus, there are *no* entanglements. Any Scheme implementor
    can pick this library up with no worries about copyright problems -- both
    commercial and non-commercial systems.
    
  - The code is written for portability and should be trivial to port to
    any Scheme. It has only four deviations from R4RS, clearly discussed
    in the comments:
	- Use of an ERROR procedure;
	- Use of the R5RS VALUES and a simple RECEIVE macro for producing
	  and consuming multiple return values;
	- Use of simple :OPTIONAL and LET-OPTIONALS macros for optional
	  argument parsing and defaulting;
	- Use of a simple CHECK-ARG procedure for argument checking.

  - It is written for clarity and well-commented. The current source is
    768 lines of source code and 826 lines of comments and white space.

  - It is written for efficiency. Fast paths are provided for common
    cases. Side-effecting procedures such as FILTER! avoid unnecessary,
    redundant SET-CDR!s which would thrash a generational GC's write barrier
    and the store buffers of fast processors. Functions reuse longest common
    tails from input parameters to construct their results where
    possible. Constant-space iterations are used in preference to recursions;
    local recursions are used in preference to consing temporary intermediate
    data structures.

    This is not to say that the implementation can't be tuned up for
    a specific Scheme implementation. There are notes in comments addressing
    ways implementors can tune the reference implementation for performance.

In short, I've written the reference implementation to make it as painless
as possible for an implementor -- or a regular programmer -- to adopt this
library and get good results with it.



* Procedure index
-----------------
Here is a short list of the procedures provided by the list-lib package.
"#" marks R5RS procedures; "+" marks extended R5RS procedures

Constructors
#  cons list
   xcons cons* make-list list-tabulate 
   list-copy circular-list iota

Predicates
#  pair? null? 
   proper-list? circular-list? dotted-list? 
   not-pair? null-list?
   list=

Selectors
#  car cdr ... cdddar cddddr list-ref 
   first second third fourth fifth sixth seventh eighth ninth tenth
   car+cdr
   take       drop
   take-right drop-right
   take!      drop-right! 
   split-at   split-at!
   last last-pair

Miscellaneous: length, append, concatenate, reverse, zip & count
#  length 
   length+ 
#  append  reverse
   append! reverse! 
   concatenate concatenate! 
   append-reverse append-reverse!
   zip unzip1 unzip2 unzip3 unzip4 unzip5
   count

Fold, unfold & map
+  map for-each
   fold       unfold       pair-fold       reduce
   fold-right unfold-right pair-fold-right reduce-right
   append-map append-map! 
   map! pair-for-each filter-map map-in-order

Filtering & partitioning
   filter  partition  remove
   filter! partition! remove!

Searching
+  member
#  memq memv
   find
   any every
   list-index
   take-while drop-while take-while!
   span break span! break!

Deleting
   delete  delete-duplicates
   delete! delete-duplicates!

Association lists
+  assoc
#  assq assv
   alist-cons alist-copy
   alist-delete alist-delete!

Set operations on lists
   lset<= lset= lset-adjoin
   lset-union			lset-union!
   lset-intersection		lset-intersection!
   lset-difference		lset-difference!
   lset-xor			lset-xor!
   lset-diff+intersection	lset-diff+intersection!
   
Primitive side effects
#  set-car! set-cdr! 

------
Four R4RS/R5RS list-processing procedures are extended by this library in
backwards-compatible ways:
   map for-each (Extended to take lists of unequal length)
   member assoc (Extended to take an optional comparison procedure)

The following R4RS/R5RS list- and pair-processing procedures are also part of
list-lib's exports, as defined by the R5RS report:
  cons pair? null? list length append reverse
  car cdr ... cdddar cddddr set-car! set-cdr! list-ref
  memq memv assq assv
    
The remaining two R4RS/R5RS list-processing procedures are *not* part of
this library:
  list-tail (renamed DROP)
  list? (see PROPER-LIST?, CIRCULAR-LIST? and DOTTED-LIST?)



* General discussion
--------------------

A set of general criteria guided the design of this library.

I don't require "destructive" (what I call "linear update") procedures to
alter and recycle cons cells from the argument lists. They are allowed to, but
not required to. (The reference implementations I have written *do* recycle
the argument lists.) See below for further discussion.

List-filtering procedures such as FILTER or DELETE do not disorder
lists. Elements appear in the answer list in the same order as they appear in
the argument list. This constrains implementation, but seems like a desirable
feature, since in many uses of lists, order matters.  (In particular,
disordering an alist is definitely a bad idea.)

Contrariwise, although the reference implementations of the list-filtering
procedures share longest common tails between argument and answer lists,
it not is part of the spec.

Because lists are an inherently sequential data structure (unlike, say,
vectors), list-inspection functions such as FIND, FIND-TAIL, FOR-EACH, ANY
and EVERY commit to a left-to-right traversal order of their argument list.

However, constructor functions, such as LIST-TABULATE and the mapping
procedures (APPEND-MAP, APPEND-MAP!, MAP!, PAIR-FOR-EACH, FILTER-MAP,
MAP-IN-ORDER) do *not* specify the dynamic order in which their
procedural argument is applied to its various values.

Predicates return useful true values wherever possible.  Thus ANY must return
the true value produced by its predicate, and EVERY returns the final true
value produced by applying its predicate argument to the last element of its
argument list.

Functionality is provided both in pure and linear-update (potentially
destructive) forms wherever this makes sense.

No special status accorded Scheme's built-in equality functions.
Any functionality provided in terms of EQ?, EQV?, EQUAL? is also
available using a client-provided equality function.

Proper design counts for more than backwards compatibility, but I have tried,
ceteris paribus, to be as backwards-compatible as possible with existing
list-processing libraries, in order to facilitate porting old code to run as a
client of the procedures in this library. Name choices and semantics are, for
the most part, in agreement with existing practice in many current Scheme
systems. I have indicated some incompatibilities in the following text.

These procedures are *not* "sequence generic" -- i.e., procedures that
operate on either vectors and lists. They are list-specific. I prefer to
keep the library simple and focussed.

I have named these procedures without a qualifying initial "list-"
lexeme, which is in keeping with the existing set of list-processing
utilities in Scheme. I follow the general Scheme convention
(VECTOR-LENGTH, STRING-REF) of placing the type-name before the action
when naming procedures -- so we have LIST-COPY and PAIR-FOR-EACH rather
than the perhaps more fluid, but less consistent, COPY-LIST, or
FOR-EACH-PAIR.

I have generally followed a regular and consistent naming scheme, composing
procedure names from a set of basic lexemes.


** "Linear update" procedures
=============================

Many procedures in this library have "pure" and "linear update" variants.  A
"pure" procedure has no side-effects, and in particular does not alter its
arguments in any way. A "linear update" procedure is allowed -- but *not*
required -- to side-effect its arguments in order to construct its
result. "Linear update" procedures are typically given names ending with an
exclamation point. So, for example, (APPEND! list1 list2) is allowed to
construct its result by simply using SET-CDR! to set the cdr of the last pair
of list1 to point to list2, and then returning list1 (unless list1 is the
empty list, in which case it would simply return list2). However, APPEND! may
also elect to perform a pure append operation -- this is a legal definition
of APPEND!:
    (define append! append)
This is why we do not call these procedures "destructive" -- because they
aren't *required* to be destructive. They are *potentially* destructive.

What this means is that you may only apply linear-update procedures to
values that you know are "dead" -- values that will never be used again
in your program. This must be so, since you can't rely on the value passed
to a linear-update procedure after that procedure has been called. It
might be unchanged; it might be altered.

The "linear" in "linear update" doesn't mean "linear time" or "linear space"
or any sort of multiple-of-n kind of meaning. It's a fancy term that type
theorists and pure functional programmers use to describe systems where you
are only allowed to have exactly one reference to each variable. This provides
a guarantee that the value bound to a variable is bound to no other
variable. So when you *use* a variable in a variable reference, you "use it
up." Knowing that no one else has a pointer to that value means the system
primitive is free to side-effect its arguments to produce what is,
observationally, a pure-functional result.
 
In the context of this library, "linear update" means you, the programmer,
know there are *no other* live references to the value passed to the
procedure -- after passing the value to one of these procedures, the
value of the old pointer is indeterminate. Basically, you are licensing
the Scheme implementation to alter the data structure if it feels like
it -- you have declared you don't care either way.

You get no help from Scheme in checking that the values you claim are "linear"
really are. So you better get it right. Or play it safe and use the non-!
procedures -- it doesn't do any good to compute quickly if you get the wrong
answer.

Why go to all this trouble to define the notion of "linear update" and use it
in a procedure spec, instead of the more common notion of a "destructive"
operation?  First, note that destructive list-processing procedures are almost
always used in a linear-update fashion. This is in part required by the
special case of operating upon the empty list, which can't be side-effected.
This means that destructive operators are not pure side-effects -- they have
to return a result. Second, note that code written using linear-update
operators can be trivially ported to a pure, functional subset of Scheme by
simply providing pure implementations of the linear-update operators. Finally,
requiring destructive side-effects ruins opportunities to parallelise these
operations -- and the places where one has taken the trouble to spell out
destructive operations are usually exactly the code one would want a
parallelising compiler to parallelise: the efficiency-critical kernels of the
algorithm.  Linear-update operations are easily parallelised. Going with a
linear-update spec doesn't close off these valuable alternative implementation
techniques. This list library is intended as a set of low-level, basic
operators, so we don't want to exclude these possible implementations.

The linear-update procedures in this library are
   take! drop-right!
   append! reverse! append-reverse!
   append-map! map!
   filter! partition! remove! 
   delete! alist-delete! delete-duplicates!
   lset-adjoin!  lset-union!  lset-intersection!  lset-difference!  lset-xor!
   lset-diff+intersection!


** Improper lists
=================

Scheme does not properly have a list type, just as C does not have a string
type. Rather, Scheme has a binary-tuple type, from which one can build binary
trees. There is an *interpretation* of Scheme values that allows one to treat
these trees as lists. Further complications ensue from the fact that Scheme
allows side-effects to these tuples, raising the possibility of lists of 
unbounded length, and trees of unbounded depth (that is, circular data
structures).

However, there is a simple view of the world of Scheme values that considers
every value to be a list of some sort. That is, every value is either
    - a "proper list" -- a finite, nil-terminated list, such as:
          (a b c) 
          () 
          (32)
    - a "dotted list" -- a finite, non-nil terminated list, such as
          (a b c . d) 
          (x . y)
          42
          george
    - or a "circular list" -- an infinite, unterminated list.
Note that the zero-length dotted lists are simply all the non-null, non-pair
values.

This view is captured by the predicates PROPER-LIST?, DOTTED-LIST?, and
CIRCULAR-LIST?. List-lib users should note that dotted lists are not commonly
used, and are considered by many Scheme programmers to be an ugly artifact of
Scheme's lack of a true list type. However, dotted lists do play a noticeable
role in the *syntax* of Scheme, in the "rest" parameters used by n-ary
lambdas: (lambda (x y . rest) ...).

Dotted lists are *not* fully supported by list-lib. Most procedures are
defined only on proper lists -- that is, finite, nil-terminated lists.  The
procedures that will also handle circular or dotted lists are specifically
marked. While this design decision restricts the domain of possible arguments
one can pass to these procedures, it has the benefit of allowing the
procedures to catch the error cases where programmers inadvertently pass
scalar values to a list procedure by accident, e.g. by switching the arguments
to a procedure call.


** Errors
=========

Note that statements of the form "it is an error" merely mean "don't
do that." They are not a guarantee that a conforming implementation will
"catch" such improper use by, for example, raising some kind of exception.
Regrettably, R5RS Scheme requires no firmer guarantee even for basic operators
such as CAR and CDR, so there's little point in requiring these procedures to 
do more.  Here is the relevant section of the R5RS report:

    When speaking of an error situation, this report uses the phrase "an
    error is signalled" to indicate that implementations must detect and
    report the error.  If such wording does not appear in the discussion
    of an error, then implementations are not required to detect or
    report the error, though they are encouraged to do so.  An error
    situation that implementations are not required to detect is usually
    referred to simply as "an error."

    For example, it is an error for a procedure to be passed an argument
    that the procedure is not explicitly specified to handle, even though
    such domain errors are seldom mentioned in this report.
    Implementations may extend a procedure's domain of definition to
    include such arguments.


** Not included in this library
===============================

The following items are not in this library:
- Sort routines
- Destructuring/pattern-matching macro
- Tree-processing routines
They should have their own SRFI specs.



* The procedures
----------------
In a Scheme system that has a module or package system, these procedures
should be contained in a module named "list-lib".

The templates given below obey the following conventions for procedure formals:
    list		A proper (finite, nil-terminated) list
    clist		A proper or circular list
    flist		A finite (proper or dotted) list
    pair		A pair
    x, y, d, a		Any value
    object, value	Any value
    n, i		A natural number (an integer >= 0)
    proc		A procedure
    pred		A procedure whose return value is treated as a boolean
    =			A boolean procedure taking two arguments

It is an error to pass a circular or dotted list to a procedure not
defined to accept such an argument.

** Constructors
===============
    
cons a d -> pair							R5RS
    The primitive constructor.  Returns a newly allocated pair whose car is A
    and whose cdr is D.  The pair is guaranteed to be different (in the sense
    of EQV?) from every existing object.
    
    (cons 'a '())                          ==>  (a)
    (cons '(a) '(b c d))                   ==>  ((a) b c d)
    (cons "a" '(b c))                      ==>  ("a" b c)
    (cons 'a 3)                            ==>  (a . 3)
    (cons '(a b) 'c)                       ==>  ((a b) . c)

list object ... -> list							R5RS
    Returns a newly allocated list of its arguments.
    
    (list 'a (+ 3 4) 'c)                   ==>  (a 7 c)
    (list)                                 ==>  ()

xcons d a -> pair
    (lambda (d a) (cons a d))
    Of utility only as a value to be conveniently passed to higher-order 
    procedures.

    (xcons '(b c) 'a) => (a b c)

    The name stands for "eXchanged CONS."

cons* elt1 elt2 ... -> object
    Like LIST, but the last argument provides the tail of the constructed
    list, returning (cons elt1 (cons elt2 (cons ... eltn))).
    This function is called LIST* in Common Lisp and about half of the
    Schemes that provide it; and CONS* in the other half.

    (cons* 1 2 3 4) => (1 2 3 . 4)
    (cons* 1) => 1

make-list n [fill] -> list
    Returns an N-element list, whose elements are all the value FILL.
    If the FILL argument is not given, the elements of the list may
    be arbitrary values.

    (make-list 4 'c) => (c c c c)
    (make-list 10) => (2 3 5 7 11 13 17 19 23 29)

list-tabulate n init-proc -> list
    Returns an N-element list. Element i of the list, where 0 <= i < N,
    is produced by (INIT-PROC i). No guarantee is made about the dynamic
    order in which INIT-PROC is applied to these indices.

    (list-tabulate 4 values) => (0 1 2 3)

list-copy flist -> flist
    Copies the "spine" of the argument.

circular-list elt1 elt2 ... -> clist
    Constructs a circular list of the elements.
    (circular-list 'z 'q) => (z q z q z q ...)

iota count [start step] -> list
    Returns a list containing the elements
	(start start+step ... start+(count-1)*step)
    The START and STEP parameters default to 0 and 1, respectively.
    This procedure takes its name from the APL primitive.

    (iota 5) => (0 1 2 3 4)
    (iota 5 0 -0.1) => (0 -0.1 -0.2 -0.3 -0.4)


** Predicates
=============

Note: the predicates PROPER-LIST?, CIRCULAR-LIST?, and DOTTED-LIST?
partition the entire universe of Scheme values.

proper-list? x -> boolean
    Returns true iff X is a proper list -- a finite, nil-terminated list.

    More carefully: The empty list is a proper list. A pair whose cdr is a 
    proper list is also a proper list:
	<proper-list> ::= ()				(Empty proper list)
		      |   (cons <x> <proper-list>)	(Proper-list pair)
    Note that this definition rules out circular lists. This
    function is required to detect this case and return false.
	
    Nil-terminated lists are called "proper" lists by R5RS and Common Lisp.
    The opposite of proper is improper.

    R5RS binds this function to the variable LIST?.

    (not (proper-list? x)) = (or (dotted-list? x) (circular-list? x))

circular-list? x -> boolean
    True if X is a circular list. A circular list is a value such that
    for every n >= 0, cdr^n(x) is a pair.

    Terminology: The opposite of circular is finite.
    (not (circular-list? x)) = (or (proper-list? x) (dotted-list? x))

dotted-list? x -> boolean
    True if X is a finite, non-nil-terminated list. That is, there exists
    an n >= 0 such that cdr^n(x) is neither a pair nor (). This includes
    non-pair, non-() values (e.g. symbols, numbers), which are considered to
    be dotted lists of length 0.

    (not (dotted-list? x)) = (or (proper-list? x) (circular-list? x))

pair? object -> boolean						R5RS
    Returns #t if OBJECT is a pair; otherwise, #f.

    (pair? '(a . b))                       ==>  #t
    (pair? '(a b c))                       ==>  #t
    (pair? '())                            ==>  #f
    (pair? '#(a b))                        ==>  #f
    (pair? 7)                              ==>  #f
    (pair? 'a)                             ==>  #f

null? object -> boolean						R5RS
    Returns #t if OBJECT is the empty list; otherwise, #f.

null-list? list -> boolean
    LIST is a proper or circular list. This procedure returns true if
    the argument is the empty list (), and false otherwise. It is an
    error to pass this procedure a value which is not a proper or
    circular list.

    This procedure is recommended as the termination condition for 
    list-processing procedures that are not defined on dotted lists.

not-pair? x -> boolean
    (lambda (x) (not (pair? x)))
    Provided as a procedure as it can be useful as the termination condition
    for list-processing procedures that wish to handle all finite lists,
    both proper and dotted.

list= elt= list1 ... -> boolean
    Determines list equality, given an element-equality procedure.
    Proper list A equals proper list B if they are of the same length,
    and their corresponding elements are equal, as determined by ELT=. 
    If the element-comparison procedure's first argument is from LISTi, 
    then its second argument is from LISTi+1, i.e. it is always called as
        (elt= a b)
    for a an element of list A, and b an element of list B.

    In the n-ary case, every LISTi is compared to LISTi+1 (as opposed,
    for example, to comparing LIST1 to every LISTi, for i>1). If there
    are no list arguments at all, LIST= simply returns true.

    It is an error to apply LIST= to anything except proper lists. While
    implementations may choose to extend it to circular lists, note that it
    cannot reasonably be extended to dotted lists, as it provides no way to
    specify an equality procedure for comparing the list terminators.

    Note that the dynamic order in which the ELT= procedure is applied to
    pairs of elements is not specified. For example, if LIST= is applied
    to three lists, A, B, and C, it may first completely compare A to B,
    then compare B to C, or it may compare the first elements of A and B,
    then the first elements of B and C, then the second elements of A and
    B, and so forth.

    The equality procedure must be consistent with EQ?. That is, 
    it must be the case that
	(eq? x y) => (elt= x y).
    Note that this implies that two lists which are EQ? are always LIST=,
    as well; implementations may exploit this fact to "short-cut" the
    element-by-element comparisons.

    (list= eq?) => #t		; Trivial cases
    (list= eq? '(a)) => #t


** Selectors
============

car pair -> value							R5RS
cdr pair -> value							R5RS
    These procedures return the contents of the car and cdr field of
    their argument, respectively.  Note that it is an error to apply
    them to the empty list.
    
    (car '(a b c))     	==>  a
    (car '((a) b c d)) 	==>  (a)
    (car '(1 . 2))     	==>  1
    (car '())          	==>  *error*
		       	
    (cdr '(a b c))     	==>  (b c)
    (cdr '((a) b c d)) 	==>  (b c d)
    (cdr '(1 . 2))     	==>  2
    (cdr '())          	==>  *error*

caar pair -> value							R5RS
cadr pair -> value
 : 
cdddar pair -> value
cddddr pair -> value
    These procedures are compositions of CAR and CDR, where for
    example CADDR could be defined by
    
    (define caddr (lambda (x) (car (cdr (cdr x))))).
    
    Arbitrary compositions, up to four deep, are provided.  There are
    twenty-eight of these procedures in all.

list-ref clist i -> value						R5RS
    Returns the Ith element of CLIST.  (This is the same as the car
    of (DROP CLIST I).) It is an error if I >= N, where N is the length
    of CLIST.
    
    (list-ref '(a b c d) 2)                 ==>  c

first second third fourth fifth 
sixth seventh eighth ninth tenth: pair -> value
    Synonyms for car, cadr, caddr, ... 
    
    (third '(a b c d e)) => c

car+cdr pair -> [x y]
    The fundamental pair deconstructor:
        (lambda (p) (values (car p) (cdr p)))
    This can, of course, be implemented more efficiently by a compiler.

take  x i -> list
drop  x i -> object
    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 -- a proper, circular, or dotted list:
        (take '(1 2 3 . d) 2) => (1 2)
        (drop '(1 2 3 . d) 2) => (3 . d)
        (take '(1 2 3 . d) 3) => (1 2 3)
        (drop '(1 2 3 . d) 3) => d
    For a legal I, TAKE and DROP partition the list in a manner which
    can be inverted with APPEND:
        (append (take x i) (drop x i)) = x

    DROP is exactly equivalent to performing I cdr operations on X;
    the returned value shares a common tail with X.

    If the argument is a list of non-zero length, TAKE is guaranteed to
    return a freshly-allocated list, even in the case where the entire
    list is taken, e.g. (TAKE LIS (LENGTH LIS)).

take-right  flist i -> object
drop-right  flist i -> list
    TAKE-RIGHT returns the last I elements of FLIST.
    DROP-RIGHT returns all but the last I elements of FLIST.

    The returned list may share a common tail with the argument list.

    (take-right '(a b c d e) 2) => (d e)
    (drop-right '(a b c d e) 2) => (a b c)

    FLIST may be any finite list, either proper or dotted:
        (take-right '(1 2 3 . d) 2) => (2 3 . d)
        (drop-right '(1 2 3 . d) 2) => (1)
        (take-right '(1 2 3 . d) 0) => d
        (drop-right '(1 2 3 . d) 0) => (1 2 3)
    For a legal I, TAKE-RIGHT and DROP-RIGHT partition the list in a manner 
    which can be inverted with APPEND:
        (append (take flist i) (drop flist i)) = flist

    TAKE-RIGHT's return value is guaranteed to share a common tail with FLIST.

    If the argument is a list of non-zero length, DROP-RIGHT is guaranteed to
    return a freshly-allocated list, even in the case where nothing is
    dropped, e.g. (DROP-RIGHT LIS 0).

take!        x     i -> list
drop-right!  flist i -> list
    TAKE! and DROP-RIGHT! are "linear-update" variants of TAKE and
    DROP-RIGHT: the procedure is allowed, but not required, to alter the
    argument list to produce the result.

    If X is circular, TAKE! may return a shorter-than-expected list:
        (take! (circular-list 1 3 5) 8) => (1 3)
        (take! (circular-list 1 3 5) 8) => (1 3 5 1 3 5 1 3)
 
split-at  x i -> [list object]
split-at! x i -> [list object]
    SPLIT-AT splits the list X at index I, returning a list of the 
    first I elements, and the remaining tail. It is equivalent
    to
        (values (take x i) (drop x i))

    SPLIT-AT! is the linear-update variant. It is allowed, but not
    required, to alter the argument list to produce the result.

    (split-at '(a b c d e f g h) 3) =>
      (a b c)
      (d e f g h)

last pair -> object
last-pair pair -> pair
    LAST returns the last element of the non-empty, finite list PAIR.
    LAST-PAIR returns the last pair in the non-empty, finite list PAIR.

    (last '(a b c)) => c
    (last-pair '(a b c)) => (c)
    (last-pair '(a b c . d)) => (c . d)


** Miscellaneous: length, append, concatenate, reverse, zip & count
===================================================================

length  list  -> integer						R5RS
length+ clist -> integer or #f
    Both LENGTH and LENGTH+ return the length of the argument.
    It is an error to pass a value to LENGTH which is not a proper
    list (finite and nil-terminated). In particular, this means an
    implementation may diverge or signal an error when LENGTH is
    applied to a circular list.
    
    LENGTH+, on the other hand, returns #F when applied to a circular
    list.
    
    The length of a proper list is a non-negative integer N such that CDR 
    applied N times to the list produces the empty list.

    (length '(a b c))                      ==>  3
    (length '(a (b) (c d e)))              ==>  3
    (length '())                           ==>  0

append  list1 ... -> value						R5RS
append! list1 ... -> value
    APPEND returns a list consisting of the elements of LIST1
    followed by the elements of the other list parameters.
    
    (append '(x) '(y))                     ==>  (x y)
    (append '(a) '(b c d))                 ==>  (a b c d)
    (append '(a (b)) '((c)))               ==>  (a (b) (c))
    
    The resulting list is always newly allocated, except that it
    shares structure with the final LISTi argument.  This last argument
    may be any value at all; an improper list results if it is not
    a proper list. All other arguments must be proper lists.
    
    (append '(a b) '(c . d))               ==>  (a b c . d)
    (append '() 'a)                        ==>  a
    (append '(x y))                        ==>  (x y)
    (append)                               ==>  ()

    APPEND! is the "linear-update" variant of APPEND -- it is allowed, but
    not required, to alter cons cells in the argument lists to construct
    the result list. The last argument is never altered; the result
    list shares structure with this parameter.

concatenate  list-of-lists -> value
concatenate! list-of-lists -> value
    These functions append the elements of their argument together.
    That is, CONCATENATE returns
        (apply append list-of-lists)
    or, equivalently,
        (reduce-right append '() list-of-lists)

    CONCATENATE! is the linear-update variant, defined in
    terms of APPEND! instead of APPEND.
    
    Note that some Scheme implementations do not support passing more than a
    certain number (e.g., 64) of arguments to an n-ary procedure.  In these
    implementations, the (APPLY APPEND ...) idiom would fail when applied to 
    long lists, but CONCATENATE would continue to function properly.

    As with APPEND and APPEND!, the last element of the input list
    may be any value at all.

reverse  list -> list							R5RS
reverse! list -> list
    REVERSE returns a newly allocated list consisting of the elements of 
    LIST in reverse order.
    
    (reverse '(a b c))                     ==>  (c b a)
    (reverse '(a (b c) d (e (f))))
              ==>  ((e (f)) d (b c) a)

    REVERSE! is the linear-update variant of REVERSE. It is permitted, 
    but not required, to alter the argument's cons cells to produce the
    reversed list.

append-reverse  rev-head tail -> value
append-reverse! rev-head tail -> value
    APPEND-REVERSE returns
	(append (reverse rev-head) tail)
    It it provided because it is a common operation -- a common
    list-processing style calls for this exact operation to transfer values
    accumulated in reverse order onto the front of another list, and because
    the implementation is significantly more efficient than the simple
    composition it replaces. (But note that this pattern of iterative 
    computation followed by a reverse can frequently be rewritten as a 
    recursion, dispensing with the REVERSE and APPEND-REVERSE steps, and 
    shifting temporary, intermediate storage from the heap to the stack, 
    which is typically a win for reasons of cache locality and eager storage 
    reclamation.)

    APPEND-REVERSE! is just the linear-update variant -- it is allowed, but
    not required, to alter REV-HEAD's cons cells to construct the result.

zip clist1 clist2 ... -> list
    (lambda lists (apply map list lists))
    If ZIP is passed N lists, it returns a list as long as the shortest
    of these lists, each element of which is an N-element list comprised
    of the corresponding elements from the parameter lists.

    (zip '(one two three) '(1 2 3) '(odd even odd even odd even odd even)) =>
       ((one 1 odd) (two 2 even) (three 3 odd))

    (zip '(1 2 3)) => ((1) (2) (3))

    At least one of the argument lists must be finite: 
        (zip '(3 1 4 1) (circular-list #f #t)) =>
            ((3 #f) (1 #t) (4 #f) (1 #t))

unzip1 list -> list
unzip2 list -> [list list]
unzip3 list -> [list list list]
unzip4 list -> [list list list list]
unzip5 list -> [list list list list list]
    UNZIP1 takes a list of lists, where every list must contain at least one
    element, and returns a list containing the initial element of each such
    list. That is, it returns (MAP CAR LISTS).  UNZIP2 takes a list of lists,
    where every list must contain at least two elements, and returns two
    values: a list of the first elements, and a list of the second
    elements. UNZIP3 does the same for the first three elements of the lists,
    and so forth.

    (unzip2 '((1 one) (2 two) (3 three))) =>
	(1 2 3) 
        (one two three)

count pred clist1 clist2 ... -> integer
    PRED is a procedure taking as many arguments as there are lists and
    returning a single value. It is applied element-wise to the elements of
    the LISTs, and a count is tallied of the number of elements that produce a
    true value. This count is returned. COUNT is "iterative" in that it is
    guaranteed to apply PRED to the LIST elements in a left-to-right order.
    The counting stops when the shortest list expires.

        (count even? '(3 1 4 1 5 9 2 5 6)) => 3
        (count < '(1 2 4 8) '(2 4 6 8 10 12 14 16)) => 3

    At least one of the argument lists must be finite:
	(count < '(3 1 4 1) (circular-list 1 10)) => 2


** Fold, unfold & map
=====================

fold kons knil clist1 clist2 ... -> value
    The fundamental list iterator. 

    First, consider the single list-parameter case. If CLIST1 = (e1 e2 ... en),
    then this procedure returns
        (kons en ... (kons e2 (kons e1 knil)) ... )
    That is, it obeys the (tail) recursion
	(fold kons knil lis) = (fold kons (kons (car lis) knil) (cdr lis))
        (fold kons knil '()) = knil

    Examples:
	(fold + 0 lis)			; Add up the elements of LIS.

	(fold cons '() lis)		; Reverse LIS.
    
	(fold cons tail rev-head)	; See APPEND-REVERSE.
    
	;; How many symbols in LIS?
	(fold (lambda (x count) (if (symbol? x) (+ count 1) count))
	      0
              lis)
    
	;; Length of the longest string in LIS:
	(fold (lambda (s max-len) (max max-len (string-length s)))
	      0
              lis)

    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:
        (fold cons* '() '(a b c) '(1 2 3 4 5)) => (c 3 b 2 a 1)

    At least one of the list arguments must be finite.

fold-right kons knil clist1 clist2 ... -> value
    The fundamental list recursion operator. 

    First, consider the single list-parameter case. If CLIST1 = (e1 e2 ... en),
    then this procedure returns
        (kons e1 (kons e2 ... (kons en knil)))
    That is, it obeys the recursion
	(fold-right kons knil lis) = (kons (car lis) (fold-right kons knil (cdr lis)))
	(fold-right kons knil '()) = knil
        
    Examples:
	(fold-right cons '() lis)		; Copy LIS.

	;; Filter the even numbers out of LIS.
	(fold-right (lambda (x l) (if (even? x) (cons x l) l)) '() lis))

    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:
        (fold-right cons* '() '(a b c) '(1 2 3 4 5)) => (a 1 b 2 c 3)

    At least one of the list arguments must be finite.

pair-fold kons knil clist1 clist2 ... -> value
    Analogous to FOLD, but KONS is applied to successive sublists of the 
    lists, rather than successive elements -- that is, KONS is applied to the
    pairs making up the lists, giving this (tail) recursion:

	(pair-fold kons knil lis) = (let ((tail (cdr lis)))
                                      (pair-fold kons (kons lis knil) tail))

	(pair-fold kons knil '()) = knil

    For finite lists, the KONS function may reliably apply SET-CDR! to the
    pairs it is given without altering the sequence of execution.

    Example:
      ;;; Destructively reverse a list.
      (pair-fold (lambda (pair tail) (set-cdr! pair tail) pair) '() lis))

    At least one of the list arguments must be finite.

pair-fold-right kons knil clist1 clist2 ... -> value
    Holds the same relationship with FOLD-RIGHT that PAIR-FOLD holds with FOLD.
    Obeys the recursion

	(pair-fold-right kons knil lis) =
            (kons lis (pair-fold-right kons knil (cdr lis)))

        (pair-fold-right kons knil '()) = knil

    Example:
	(pair-fold-right cons '() '(a b c)) => ((a b c) (b c) (c))

    At least one of the list arguments must be finite.

reduce f ridentity list -> value
    REDUCE is a variant of FOLD. 

    RIDENTITY should be a "right identity" of the procedure F -- that is, 
    for any value X acceptable to F,
	(f x ridentity) = x
    
    REDUCE has the following definition:
	If LIST = (),  return RIDENTITY.
	Otherwise,     return (fold F (car LIST) (cdr LIST)).

    ...in other words, we compute (fold F RIDENTITY LIST).
    
    Note that RIDENTITY is used *only* in the empty-list case.  You
    typically use REDUCE when applying F is expensive and you'd like
    to avoid the extra application incurred when FOLD applies F to the
    head of LIST and the identity value, redundantly producing the
    same value passed in to F. For example, if F involves searching a
    file directory or performing a database query, this can be
    significant. In general, however, FOLD is useful in many contexts
    where REDUCE is not (consider the examples given in the FOLD
    definition -- only one of the five folds uses function with a
    right identity. The other four may not be performed with REDUCE).

    Note: MIT Scheme and Haskell flip F's arg order for their REDUCE and
    FOLD functions.

    ;; Take the max of a list of non-negative integers.
    (reduce max 0 nums) ; i.e., (apply max 0 nums)

reduce-right f ridentity list -> value
    REDUCE-RIGHT is the fold-right variant of REDUCE.
    It obeys the following definition:
	(reduce-right f ridentity '()) = ridentity
	(reduce-right f ridentity '(e1)) = (f e1 ridentity) = e1
	(reduce-right f ridentity '(e1 e2 ...)) =
	    (f e1 (reduce f ridentity (e2 ...)))

    ...in other words, we compute (fold-right F RIDENTITY LIST).

    ;; Append a bunch of lists together.
    ;; I.e., (apply append list-of-lists)
    (reduce-right append '() list-of-lists)

unfold p f g seed [tail-gen]-> list
    UNFOLD is best described by its basic recursion:
	(unfold p f g seed) = (if (p seed) (tail-gen seed)
                                  (cons (f seed)
                                        (unfold p f g (g seed))))
    P: Determines when to stop unfolding.
    F: Maps each seed value to the corresponding list element.
    G: Maps each seed value to next seed value.
    SEED: The "state" value for the unfold.
    TAIL-GEN: creates the tail of the list; defaults to (lambda (x) '())

    In other words, we use G to generate a sequence of seed values
	SEED, (G SEED), (G^2 SEED), (G^3 SEED), ...
    These seed values are mapped to list elements by F, producing the
    elements of the result list in a left-to-right order. P says when to stop.

    UNFOLD is the fundamental recursive list constructor, just as FOLD-RIGHT
    is the fundamental recursive list consumer. While UNFOLD may seem a
    bit abstract to novice functional programmers, it can be used in a number
    of ways:

	(unfold (lambda (x) (> x 10))	; List of squares: 1^2 ... 10^2.
		(lambda (x) (* x x))
		(lambda (x) (+ x 1))
		1)
		
	(unfold null-list? car cdr lis)	; Copy a proper list.

	;; Read current input port into a list of values.
	(unfold eof-object? values (lambda (x) (read)) (read))

	;; Copy a possibly non-proper list:
	(unfold not-pair? car cdr lis 
                values)

	;; Append HEAD onto TAIL:
	(unfold null-list? car cdr head 
                (lambda (x) tail))

    Interested functional programmers may enjoy noting that FOLD-RIGHT and
    UNFOLD are in some sense inverses. That is, given operations KNULL?,
    KAR, KDR, KONS, and KNIL satisfying
	(kons (kar x) (kdr x)) = x  and (knull? knil) = #t
    then
	(FOLD-RIGHT kons knil (UNFOLD knull? kar kdr x)) = x
    and
	(UNFOLD knull? kar kdr (FOLD-RIGHT kons knil x)) = x.

    This combinator sometimes is called an "anamorphism;" when an
    explicit TAIL-GEN procedure is supplied, it is called an
    "apomorphism."

unfold-right p f g seed [tail] -> value
    UNFOLD constructs a list with the following loop:
        (let lp ((seed seed) (lis tail))
          (if (p seed) lis
              (lp (g seed)
                  (cons (f seed) lis))))

    P: Determines when to stop unfolding.
    F: Maps each seed value to the corresponding list element.
    G: Maps each seed value to next seed value.
    SEED: The "state" value for the unfold.
    TAIL: list terminator; defaults to '().

    In other words, we use G to generate a sequence of seed values
	SEED, (G SEED), (G^2 SEED), (G^3 SEED), ...
    These seed values are mapped to list elements by F, producing the
    elements of the result list in a right-to-left order. P says when to stop.

    UNFOLD-RIGHT is the fundamental iterative list constructor, just as FOLD
    is the fundamental iterative list consumer. While UNFOLD-RIGHT may seem a
    bit abstract to novice functional programmers, it can be used in a number
    of ways:

	(unfold-right zero?		; List of squares: 1^2 ... 10^2
		      (lambda (x) (* x x))
		      (lambda (x) (- x 1))
		      10)
		
	(unfold-right null-list? car cdr lis) ; Reverse a proper list.

	;; Read current input port into a list of values.
	(unfold-right eof-object? values (lambda (x) (read)) (read))

	;; (APPEND-REVERSE rev-head tail)
	(unfold-right null-list? car cdr rev-head tail)

    Interested functional programmers may enjoy noting that FOLD and
    UNFOLD-RIGHT are in some sense inverses. That is, given operations KNULL?,
    KAR, KDR, KONS, and KNIL satisfying
	(kons (kar x) (kdr x)) = x  and (knull? knil) = #t
    then
	(FOLD kons knil (UNFOLD-RIGHT knull? kar kdr x)) = x
    and
	(UNFOLD-RIGHT knull? kar kdr (FOLD kons knil x)) = x.

    This combinator presumably has some pretentious mathematical name;
    interested readers are invited to communicate it to the author.

map proc clist1 clist2 ... -> list					R5RS+
    
     PROC is a procedure taking as many arguments as there are list arguments
     and returning a single value.  MAP applies PROC element-wise to the
     elements of the lists and returns a list of the results, in order.  The
     dynamic order in which PROC is applied to the elements of the lists is
     unspecified.
    
     (map cadr '((a b) (d e) (g h)))
               ==>  (b e h)
     
     (map (lambda (n) (expt n n))
          '(1 2 3 4 5))
               ==>  (1 4 27 256 3125)
     
     (map + '(1 2 3) '(4 5 6))              ==>  (5 7 9)
     
     (let ((count 0))
       (map (lambda (ignored)
              (set! count (+ count 1))
              count)
            '(a b)))                        ==>  (1 2) OR (2 1)

    This procedure is extended from its R5RS specification
    to allow the arguments to be of unequal length; it terminates
    when the shortest list runs out. 

    At least one of the argument lists must be finite:
	(map + '(3 1 4 1) (circular-list 1 0)) => (4 1 5 1)

for-each proc clist1 clist2 ... -> unspecified				R5RS+
     The arguments to FOR-EACH are like the arguments to MAP, but
     FOR-EACH calls PROC for its side effects rather than for its
     values.  Unlike MAP, FOR-EACH is guaranteed to call PROC on
     the elements of the CLISTs in order from the first element(s) to
     the last, and the value returned by FOR-EACH is unspecified.

     (let ((v (make-vector 5)))
       (for-each (lambda (i)
                   (vector-set! v i (* i i)))
                 '(0 1 2 3 4))
       v)                                   ==>  #(0 1 4 9 16)
    
    This procedure is extended from its R5RS specification
    to allow the arguments to be of unequal length; it terminates
    when the shortest list runs out. 

    At least one of the argument lists must be finite.

append-map  f clist1 clist2 ... -> value
append-map! f clist1 clist2 ... -> value
    Equivalent to 
        (apply append  (map f clist1 clist2 ...))
    and
        (apply append! (map f clist1 clist2 ...))

    Map F over the elements of the lists, just as in the MAP function.
    However, the results of the applications are appended together to
    make the final result. APPEND-MAP uses APPEND to append the results
    together; APPEND-MAP! uses APPEND!.

    The dynamic order in which the various applications of F are made is
    not specified.

    Example:
	(append-map! (lambda (x) (list x (- x))) '(1 3 8))
	   => (1 -1 3 -3 8 -8)

    At least one of the list arguments must be finite.

map! f list1 clist2 ... -> list
    Linear-update variant of MAP -- MAP! is allowed, but not required, to 
    alter the cons cells of LIST1 to construct the result list.
    
    The dynamic order in which the various applications of F are made is
    not specified.
    
    In the n-ary case, CLIST2, CLIST3, ... must have at least as many
    elements as LIST1.

map-in-order f clist1 clist2 ... -> list
    A variant of the MAP procedure that guarantees to apply F across
    the elements of the LISTi arguments in a left-to-right order. This
    is useful for mapping procedures that both have side effects and
    return useful values.

    At least one of the list arguments must be finite.

pair-for-each f clist1 clist2 ... -> unspecific
    Like FOR-EACH, but F is applied to successive sublists of the argument
    lists. That is, F is applied to the cons cells of the lists, rather
    than the lists' elements. These applications occur in left-to-right
    order.

    The F procedure may reliably apply SET-CDR! to the pairs it is given
    without altering the sequence of execution.

    (pair-for-each (lambda (pair) (display pair) (newline)) '(a b c)) ==>
        (a b c)
        (b c)
        (c)
    
    At least one of the list arguments must be finite.

filter-map f clist1 clist2 ... -> list
    Like MAP, but only true values are saved.
	(filter-map (lambda (x) (and (number? x) (* x x))) '(a 1 b 3 c 7))
	    => (1 9 49)
    The dynamic order in which the various applications of F are made is
    not specified.

    At least one of the list arguments must be finite.


** Filtering & partitioning
===========================

filter pred list -> list
    Return all the elements of LIST that satisfy predicate PRED.
    The list is not disordered -- elements that appear in the result list
    occur in the same order as they occur in the argument list.
    The returned list may share a common tail with the argument list.
    The dynamic order in which the various applications of PRED are made is
    not specified.
    
    (filter even? '(0 7 8 8 43 -4)) => (0 8 8 -4)

partition pred list -> [list list]
    Partitions the elements of LIST with predicate PRED, and returns two
    values: the list of in-elements and the list of out-elements.
    The list is not disordered -- elements occur in the result lists
    in the same order as they occur in the argument list.
    The dynamic order in which the various applications of PRED are made is
    not specified. One of the returned lists may share a common tail with the
    argument list.

    (partition symbol? '(one 2 3 four five 6))
	=> (one four five)
           (2 3 6)

remove pred list -> list
    Returns LIST without the elements that satisfy predicate PRED:
    (lambda (pred list) (filter (lambda (x) (not (pred x))) list))
    The list is not disordered -- elements that appear in the result list
    occur in the same order as they occur in the argument list.
    The returned list may share a common tail with the argument list.
    The dynamic order in which the various applications of PRED are made is 
    not specified.
    
    (remove even? '(0 7 8 8 43 -4)) => (7 43)

filter!    pred list -> list
partition! pred list -> [list list]
remove!    pred list -> list
    Linear-update variants of FIND, PARTITION and REMOVE.
    These procedures are allowed, but not required, to alter the cons cells
    in the argument list to construct the result lists.

    
** Searching
============

The following procedures all search lists for a leftmost element satisfying
some criteria. This means they do not always examine the entire list; thus,
there is no efficient way for them to reliably detect and signal an error when
passed a dotted or circular list. Here are the general rules describing how
these procedures work when applied to different kinds of lists:

    Proper lists: The standard, canonical behavior happens in this case.

    Dotted lists: It is an error to pass these procedures a dotted list
                  that does not contain an element satisfying the search
                  criteria. That is, it is an error if the procedure has
                  to search all the way to the end of the dotted list.
		  However, this SRFI does *not* specify anything at all
                  about the behavior of these procedures when passed a
                  dotted list containing an element satisfying the search
                  criteria. It may finish successfully, signal an error,
                  or perform some third action. Different implementations
                  may provide different functionality in this case; code
                  which is compliant with this SRFI may not rely on any
                  particular behavior. Future SRFI's may refine SRFI-1
                  to define specific behavior in this case.

		  In brief, SRFI-1 compliant code may not pass a dotted
                  list argument to these procedures.

    Circular lists: It is an error to pass these procedures a circular list
                  that does not contain an element satisfying the search
                  criteria. Note that the procedure is not required to 
                  detect this case; it may simply diverge. It is, however,
                  acceptable to search a circular list *if the search is
                  successful* -- that is, if the list contains an element
                  satisfying the search criteria.
		  
Here are some examples, using the FIND and ANY procedures as canonical
representatives:
    ;; Proper list -- success
    (find even? '(1 2 3))	=> 2
    (any  even? '(1 2 3))	=> #t

    ;; proper list -- failure
    (find even? '(1 7 3))	=> #f
    (any  even? '(1 7 3))	=> #f

    ;; Failure is error on a dotted list.
    (find even? '(1 3 . x))	=> error
    (any  even? '(1 3 . x))	=> error

    ;; The dotted list contains an element satisfying the search.
    ;; This case is not specified -- it could be success, an error, 
    ;; or some third possibility.
    (find even? '(1 2 . x))	=> error/undefined
    (any  even? '(1 2 . x))	=> error/undefined ; success, error or other.

    ;; circular list -- success
    (find even? (circular-list 1 6 3)) => 6
    (any  even? (circular-list 1 6 3)) => #t

    ;; circular list -- failure is error. Procedure may diverge.
    (find even? (circular-list 1 3)) => error
    (any  even? (circular-list 1 3)) => error

    
find pred clist -> value
    Return the first element of CLIST that satisfies predicate PRED;
    false if no element does.

    (find even? '(3 1 4 1 5 9)) => 4

    Note that FIND has an ambiguity in its lookup semantics -- if FIND
    returns #F, you cannot tell (in general) if it found a #F element
    that satisfied PRED, or if it did not find any element at all. In
    many situations, this ambiguity cannot arise -- either the list being
    searched is known not to contain any #F elements, or the list is
    guaranteed to have an element satisfying PRED. However, in cases
    where this ambiguity can arise, you should use FIND-TAIL instead of
    FIND -- FIND-TAIL has no such ambiguity:
	(cond ((find-tail pred lis) => (lambda (pair) ...)) ; Handle (CAR PAIR)
	      (else ...)) ; Search failed.

find-tail pred clist -> pair or false
    Return the first pair of CLIST whose car satisfies PRED. If no pair does,
    return false.

    FIND-TAIL can be viewed as a general-predicate variant of the MEMBER
    function.

    Examples: 
        (find-tail even? '(3 1 37 -8 -5 0 0)) => (-8 -5 0 0)

        (find-tail even? '(3 1 37 -5)) => #f

	;; MEMBER X LIS:
	(find-tail (lambda (elt) (equal? x elt)) lis)

    In the circular-list case, this procedure "rotates" the list.
    
    FIND-TAIL is essentially DROP-WHILE, where the sense of the predicate
    is inverted: FIND-TAIL searches until it finds an element satisfying
    the predicate; DROP-WHILE searches until it finds an element that
    *doesn't* satisfy the predicate.

take-while  pred clist -> list
take-while! pred clist -> list
    Returns the longest initial prefix of CLIST whose elements all
    satisfy the predicate PRED.

    TAKE-WHILE! is the linear-update variant. It is allowed, but not
    required, to alter the argument list to produce the result.

    (take-while even? '(2 18 3 10 22 9)) => (2 18)

drop-while pred clist -> list
    Drops the longest initial prefix of LIST whose elements all
    satisfy the predicate PRED, and returns the rest of the list.

    (drop-while even? '(2 18 3 10 22 9)) => (3 10 22 9)

    The circular-list case may be viewed as "rotating" the list.

span   pred clist -> [list clist]
span!  pred list ->  [list list]
break  pred clist -> [list clist]
break! pred list ->  [list list]
    SPAN splits the list into the longest initial prefix whose elements
    all satisfy PRED, and the remaining tail. BREAK inverts the sense
    of the predicate: the tail commences with the first element of the
    input list that satisfies the predicate.

    In other words: SPAN finds the intial span of elements satisfying
    PRED, and BREAK breaks the list at the first element satisfying PRED.

    SPAN is equivalent to (VALUES (TAKE-WHILE PRED CLIST) 
                                  (DROP-WHILE PRED CLIST)).

    SPAN! and BREAK! are the linear-update variants. They are allowed, but not
    required, to alter the argument list to produce the result.

    (span even? '(2 18 3 10 22 9)) =>
      (2 18)
      (3 10 22 9)

    (break even? '(3 1 4 1 5 9)) =>
      (3 1)
      (4 1 5 9)

any pred clist1 clist2 ... -> value
    Applies the predicate across the lists, returning true if the predicate
    returns true on any application.

    If there are N list arguments CLIST1 ... CLISTn, then PRED must be a
    procedure taking N arguments and returning a boolean result.

    ANY applies PRED to the first elements of the CLISTi parameters.  If this
    application returns a true value, ANY immediately returns that value.
    Otherwise, it iterates, applying PRED to the second elements of the CLISTi
    parameters, then the third, and so forth.  The iteration stops when a true
    value is produced or one of the lists runs out of values; in the latter
    case, ANY returns #F.  The application of PRED to the last element of the
    lists is a tail call.

    Note the difference between FIND and ANY -- FIND returns the element
    that satisfied the predicate; ANY returns the true value that the
    predicate produced.

    Like EVERY, ANY's name does not end with a question mark -- this is to
    indicate that it does not return a simple boolean (#T or #F), but a
    general value.

    (any integer? '(a 3 b 2.7))   => #T
    (any integer? '(a 3.1 b 2.7)) => #F
    (any < '(3 1 4 1 5)
           '(2 7 1 8 2)) => #T

every pred clist1 clist2 ... -> value
    Applies the predicate across the lists, returning true if the predicate
    returns true on every application.

    If there are N list arguments CLIST1 ... CLISTn, then PRED must be a
    procedure taking N arguments and returning a boolean result.

    EVERY applies PRED to the first elements of the CLISTi parameters.  If
    this application returns false, EVERY immediately returns false.
    Otherwise, it iterates, applying PRED to the second elements of the CLISTi
    parameters, then the third, and so forth. The iteration stops when a false
    value is produced or one of the lists run out of values. In the latter
    case, EVERY returns the true value produced by its final application of
    PRED. The application of PRED to the last element of the lists is a tail
    call.
    
    If one of the CLISTi has no elements, EVERY simply returns #T.
    
    Like ANY, EVERY's name does not end with a question mark -- this is to
    indicate that it does not return a simple boolean (#T or #F), but a
    general value.

list-index pred clist1 clist2 ... -> integer or false
    Return the index of the leftmost element that satisfies PRED.

    If there are N list arguments CLIST1 ... CLISTn, then PRED must be a
    function taking N arguments and returning a boolean result.

    LIST-INDEX applies PRED to the first elements of the CLISTi parameters.
    If this application returns true, LIST-INDEX immediately returns zero.
    Otherwise, it iterates, applying PRED to the second elements of the
    CLISTi parameters, then the third, and so forth. When it finds a tuple of
    list elements that cause PRED to return true, it stops and returns the
    zero-based index of that position in the lists.

    The iteration stops when one of the lists runs out of values; in this
    case, LIST-INDEX returns #F.

    (list-index even? '(3 1 4 1 5 9)) => 2
    (list-index < '(3 1 4 1 5 9 2 5 6) '(2 7 1 8 2)) => 1
    (list-index = '(3 1 4 1 5 9 2 5 6) '(2 7 1 8 2)) => #f

member x list [=] -> list or #f						R5RS+
memq   x list     -> list or #f						R5RS
memv   x list     -> list or #f						R5RS
    These procedures return the first sublist of LIST whose car is
    X, where the sublists of LIST are the non-empty lists returned
    by (DROP LIST I) for I less than the length of LIST.  If X does
    not occur in LIST, then #f is returned.  MEMQ uses EQ? to compare X
    with the elements of LIST, while MEMV uses EQV? and MEMBER uses 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
    (member (list 'a)
            '(b (a) c))                    ==>  ((a) c)
    (memq 101 '(100 101 102))              ==>  *unspecified*
    (memv 101 '(100 101 102))              ==>  (101 102)

    MEMBER is extended from its R5RS definition to allow the client to pass 
    in an optional equality procedure = used to compare keys. 

    The comparison procedure is used to compare the elements Ei of LIST
    to the key X in this way:
	(= X Ei)		; list is (E1 ... En)
    That is, the first argument is always X, and the second argument is
    one of the list elements. Thus one can reliably find the first element
    of LIST that is greater than five with
	(member 5 LIST <)

    Note that fully general list searching may be performed with
    the FIND-TAIL and FIND procedures, e.g.
	(find-tail even? list) ; Find the first elt with an even key.


** Deletion
===========

delete  x list [=] -> list
delete! x list [=] -> list
    DELETE uses the comparison procedure =, which defaults to EQUAL?, to find
    all elements of LIST that are equal to X, and deletes them from LIST. The
    dynamic order in which the various applications of = are made is not
    specified.

    The list is not disordered -- elements that appear in the result list
    occur in the same order as they occur in the argument list.
    The result may share a common tail with the argument list.

    Note that fully general element deletion can be performed with the REMOVE
    and REMOVE! procedures, e.g.:
	;; Delete all the even elements from LIS:
	(remove even? lis)

    The comparison procedure is used in this way:
	(= X Ei)
    That is, X is always the first argument, and a list element is always the
    second argument. The comparison procedure will be used to compare each
    element of LIST exactly once; the order in which it is applied to the
    various Ei is not specified.  Thus, one can reliably remove all the
    numbers greater than five from a list with
	(delete 5 list <)

    DELETE! is the linear-update variant of DELETE. It is allowed, but not
    required, to alter the cons cells in its argument list to construct the
    result.

delete-duplicates  list [=] -> list
delete-duplicates! list [=] -> list
    DELETE-DUPLICATES removes duplicate elements from the list argument.
    If there are multiple equal elements in the argument 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 -- DELETE-DUPLICATES does not disorder the list (hence it is useful
    for "cleaning up" association lists).

    The = parameter is used to compare the elements of the list; it defaults
    to EQUAL?. If X comes before Y in LIST, then the comparison is performed 
	(= X Y)
    The comparison procedure will be used to compare each pair of
    elements in LIST no more than once; the order in which it is
    applied to the various pairs is not specified.
    
    Implementations of DELETE-DUPLICATE are allowed to share common tails
    between argument and result lists -- for example, if the list argument
    contains only unique elements, it may simply return exactly this list.

    Be aware that, in general, DELETE-DUPLICATES runs in time O(n^2)
    for N-element lists.  Uniquifying long lists can be accomplished
    in O(n lg n) time by sorting the list to bring equal elements
    together, then using a linear-time algorithm to remove equal
    elements. Alternatively, one can use algorithms based on
    element-marking, with linear-time results.

    DELETE-DUPLICATES! is the linear-update variant of DELETE-DUPLICATES; it
    is allowed, but not required, to alter the cons cells in its argument
    list to construct the result.

    (delete-duplicates '(a b a c a b c z)) => (a b c z)

    ;; Clean up an alist:
    (delete-duplicates '((a . 3) (b . 7) (a . 9) (c . 1))
		       (lambda (x y) (eq? (car x) (car y))))
        => ((a . 3) (b . 7) (c . 1))


** Association lists
====================

An "association list" (or "alist") is a list of pairs. The car of each pair
contains a key value, and the cdr contains the associated data value. They can
be used to construct simple look-up tables in Scheme. Note that association
lists are probably inappropriate for performance-critical use on large data;
in these cases, hash tables or some other alternative should be employed.

assoc key alist [=] -> pair or #f			     		R5RS+
assq  key alist     -> pair or #f					R5RS
assv  key alist     -> pair or #f					R5RS

    ALIST must be an association list -- a list of pairs.  These procedures
    find the first pair in ALIST whose car field is KEY, and returns that
    pair.  If no pair in ALIST has KEY as its car, then #f is returned.  ASSQ
    uses EQ? to compare KEY with the car fields of the pairs in ALIST, while
    ASSV uses EQV? and ASSOC uses EQUAL?.
    
    (define e '((a 1) (b 2) (c 3)))
    (assq 'a e)                            ==>  (a 1)
    (assq 'b e)                            ==>  (b 2)
    (assq 'd e)                            ==>  #f
    (assq (list 'a) '(((a)) ((b)) ((c))))  ==>  #f
    (assoc (list 'a) '(((a)) ((b)) ((c)))) ==>  ((a))
    (assq 5 '((2 3) (5 7) (11 13)))	    ==>  *unspecified*
    (assv 5 '((2 3) (5 7) (11 13)))	    ==>  (5 7)

    ASSOC is extended from its R5RS definition to allow the client to pass in
    an optional equality procedure = used to compare keys.

    The comparison procedure is used to compare the elements Ei of LIST
    to the KEY parameter in this way:
	(= KEY (CAR Ei))	; list is (E1 ... En)
    That is, the first argument is always KEY, and the second argument is
    one of the list elements. Thus one can reliably find the first entry
    of ALIST whose key is greater than five with
	(assoc 5 ALIST <)
     
    Note that fully general alist searching may be performed with
    the FIND-TAIL and FIND procedures, e.g.
        ;; Look up the first association in ALIST with an even key:
	(find (lambda (a) (even? (car a))) alist)

alist-cons key datum alist -> alist
    (lambda (key datum alist) (cons (cons key datum) alist))
    Cons a new alist entry mapping KEY -> DATUM onto ALIST.

alist-copy alist -> alist
    Make a fresh copy of ALIST. This means copying each pair that
    forms an association as well as the spine of the list, i.e.
    (lambda (a) (map (lambda (elt) (cons (car elt) (cdr elt))) a))

alist-delete  key alist [=] -> alist
alist-delete! key alist [=] -> alist
    ALIST-DELETE deletes all associations from ALIST with the given
    KEY, using key-comparison procedure =, which defaults to EQUAL?.
    The dynamic order in which the various applications of = are made
    is not specified.

    Return values may share common tails with the ALIST argument.
    The alist is not disordered -- elements that appear in the result alist
    occur in the same order as they occur in the argument alist.

    The comparison procedure is used to compare the element keys Ki of ALIST's
    entries to the KEY parameter in this way:
	(= KEY Ki)
    Thus, one can reliably remove all entries of ALIST whose key is greater
    than five with
	(alist-delete 5 alist <)

    ALIST-DELETE! is the linear-update variant of ALIST-DELETE. It
    is allowed, but not required, to alter the cons cells from the ALIST
    parameter to construct the result.

    
** Set operations on lists
==========================
These procedures implement operations on sets represented as lists of
elements.  They all take an = argument used to compare elements of
lists. This equality procedure is required to be consistent with
EQ?. That is, it must be the case that
	   (eq? x y) => (= x y).
Note that this implies, in turn, that two lists that are EQ? are
also set-equal by any legal comparison procedure. This allows for
constant-time determination of set operations on EQ? lists.

Be aware that these procedures typically run in time O(n * m) for N-
and M-element list arguments.  Performance-critical applications
operating upon large sets will probably wish to use other data
structures and algorithms.

lset<= = list1 ... -> boolean
    Returns true iff every LISTi is a subset of LISTi+1, using = for the
    element-equality procedure. List A is a subset of list B if every
    element in A is equal to some element of B. When performing an
    element comparison, the = procedure's first argument is an element
    of A; its second, an element of B.

    (lset<= eq? '(a) '(a b a) '(a b c c)) => #t

    (lset<= eq?) => #t		; Trivial cases
    (lset<= eq? '(a)) => #t


lset= = list1 ... -> boolean
    Returns true iff every LISTi is set-equal to LISTi+1, using = for
    the element-equality procedure. "Set-equal" simply means that
    LISTi is a subset of LISTi+1, and LISTi+1 is a subset of LISTi.

    (lset= eq? '(b e a) '(a e b) '(e e b a)) => #t

    (lset= eq?) => #t		; Trivial cases
    (lset= eq? '(a)) => #t

lset-adjoin = list elt1 ... -> list
    Adds the ELTi elements not already in the list parameter to the 
    result list. The result shares a common tail with the list parameter.
    The new elements are added to the front of the list, but no guarantees
    are made about their order. The = parameter is an equality procedure
    used to determine if an ELTi is already a member of LIST. Its first 
    argument is an element of LIST; its second is one of the ELTi.

    The list parameter is always a suffix of the result -- even if the list
    parameter contains repeated elements, these are not reduced.

    (lset-adjoin eq? '(a b c d c e) 'a 'e 'i 'o 'u) => (u o i a b c d c e)

lset-union = list1 ... -> list
    Returns the union of the lists, using = for the element-equality
    procedure. 

    The union of lists A and B is constructed as follows:
        - If A is the empty list, the answer is B (or a copy of B).
        - Otherwise, the result is initialised to be list A (or a copy of A).
	- Proceed through the elements of list B in a left-to-right order.
	  If b is such an element of B, compare every element r of the current
	  result list to b: (= r b). If all comparisons fail, b is consed
	  onto the front of the result.
    However, there is no guarantee that = will be applied to every pair
    of arguments from A and B. In particular, if A is EQ? to B, the operation
    may immediately terminate.

    In the n-ary case, the two-argument list-union operation is simply
    folded across the argument lists.

    (lset-union eq? '(a b c d e) '(a e i o u)) => (u o i a b c d e)
    
    ;; Repeated elements in LIST1 are preserved.
    (lset-union eq? '(a a c) '(x a x)) => (x a a c)

    (lset-union eq?)          => ()		; Trivial cases
    (lset-union eq? '(a b c)) => (a b c)

lset-intersection = list1 list2 ... -> list
    Returns the intersection of the lists, using = for the element-equality
    procedure. 

    The intersection of lists A and B is comprised of every element of A
    that is = to some element of B: (= a b), for a in A, and b in B.
    Note this implies that an element which appears in B and multiple times
    in list A will also appear multiple times in the result.

    The order in which elements appear in the result is the same as
    they appear in LIST1 -- that is, LSET-INTERSECTION essentially
    filters LIST1, without disarranging element order. The result may
    share a common tail with LIST1.

    In the n-ary case, the two-argument list-intersection operation is simply
    folded across the argument lists. However, the dynamic order in which the
    applications of = are made is not specified. The procedure may check an
    element of LIST1 for membership in every other list before proceeding to
    consider the next element of LIST1, or it may completely intersect LIST1
    and LIST2 before proceeding to LIST3, or it may go about its work in some
    third order.

    (lset-intersection eq? '(a b c d e) '(a e i o u)) => (a e)
    
    ;; Repeated elements in LIST1 are preserved.
    (lset-intersection eq? '(a x y a) '(x a x z)) => '(a x a)

    (lset-intersection eq? '(a b c)) => (a b c)	; Trivial case
    
lset-difference = list1 list2 ... -> list
    Returns the difference of the lists, using = for the element-equality
    procedure -- all the elements of LIST1 that are not = to any element from
    one of the other LISTi parameters. 

    The = procedure's first argument is always an element of LIST1; its second
    is an element of one of the other LISTi. Elements that are repeated
    multiple times in the LIST1 parameter will occur multiple times in the
    result.

    The order in which elements appear in the result is the same as
    they appear in LIST1 -- that is, LSET-DIFFERENCE essentially
    filters LIST1, without disarranging element order. The result may
    share a common tail with LIST1.

    The dynamic order in which the applications of = are made is not
    specified. The procedure may check an element of LIST1 for membership in
    every other list before proceeding to consider the next element of LIST1,
    or it may completely compute the difference of LIST1 and LIST2 before
    proceeding to LIST3, or it may go about its work in some third order.

    (lset-difference eq? '(a b c d e) '(a e i o u)) => (b c d)

    (lset-difference eq? '(a b c)) => (a b c) ; Trivial case

lset-xor = list1 ... -> list
    Returns the exclusive-or of the sets, using = for the element-equality
    procedure. If there are exactly two lists, this is all the elements
    that appear in exactly one of the two lists. The operation is associative,
    and thus extends to the n-ary case -- the elements that appear in an
    odd number of the lists. The result may share a common tail with any of
    the LISTi parameters.

    More precisely, for two lists A and B, A xor B is a list of
        - every element a of A such that there is no element b of B
          such that (= a b)
        - every element b of B such that there is no element a of A
          such that (= b a)
    However, an implementation is allowed to assume that = is
    symmetric -- that is, that
	(= a b) => (= b a).
    This means, for example, that if a comparison (= a b) produces
    true for some a in A and b in B, both a and b may be removed from
    inclusion in the result.

    In the n-ary case, the binary-xor operation is simply folded across
    the lists.

    (lset-xor eq? '(a b c d e) '(a e i o u)) => (d c b i o u)
    
    ;; Trivial cases.
    (lset-xor eq?) => ()
    (lset-xor eq? '(a b c d e)) => (a b c d e)

lset-diff+intersection = list1 list2 ... -> [list list]
    Returns two values -- the difference and the intersection of the lists.
    Is equivalent to 
        (values (lset-difference   = list1 list2 ...)
	        (lset-intersection = list1
                                     (lset-union = list2 ...)))
    but can be implemented more efficiently.

    The = procedure's first argument is an element of LIST1; its second is
    an element of one of the other LISTi.

    Either of the answer lists may share a common tail with LIST1.
    This operation essentially partitions LIST1.

lset-union!        	= list1 ... -> list
lset-intersection! 	= list1 list2 ... -> list
lset-difference!   	= list1 list2 ... -> list
lset-xor!          	= list1 ... -> list
lset-diff+intersection! = list1 list2 ... -> [list list]
    These are linear-update variants. They are allowed, but not required,
    to use the cons cells in their first list parameter to construct their
    answer. LSET-UNION! is permitted to recycle cons cells from *any* of its
    list arguments.


** Primitive side-effects
=========================

These two procedures are the primitive, R5RS side-effect operations on pairs.

set-car! pair object -> unspecified					R5RS
set-cdr! pair object -> unspecified					R5RS
     These procedures store OBJECT in the car and cdr field of PAIR, 
     respectively. The value returned is unspecified.

     (define (f) (list 'not-a-constant-list))
     (define (g) '(constant-list))
     (set-car! (f) 3)                       ==>  *unspecified*
     (set-car! (g) 3)                       ==>  *error*



* Acknowledgements
------------------

The design of this library benefited greatly from the feedback provided during
the SRFI discussion phase. Among those contributing thoughtful commentary and
suggestions, both on the mailing list and by private discussion, were Mike
Ashley, Darius Bacon, Alan Bawden, Phil Bewig, Jim Blandy, Dan Bornstein, Per
Bothner, Anthony Carrico, Doug Currie, Kent Dybvig, Sergei Egorov, Doug Evans,
Marc Feeley, Matthias Felleisen, Will Fitzgerald, Matthew Flatt, Dan Friedman,
Lars Thomas Hansen, Brian Harvey, Erik Hilsdale, Wolfgang Hukriede, Richard
Kelsey, Donovan Kolbly, Shriram Krishnamurthi, Dave Mason, Jussi Piitulainen,
David Pokorny, Duncan Smith, Mike Sperber, Maciej Stachowiak, Harvey J. Stein,
John David Stone, and Joerg F. Wittenberger. I am grateful to them for their
assistance.

I am also grateful the authors, implementors and documentors of all the systems
mentioned in the introduction. Aubrey Jaffer and Kent Pitman should be noted
for their work in producing Web-accessible versions of the R5RS and Common
Lisp spec, which was a tremendous aid.

This is not to imply that these individuals necessarily endorse the final
results, of course. 



* References & Links
--------------------

This document, in HTML:
    http://srfi.schemers.org/srfi-1/srfi-1.html
    ftp://ftp.ai.mit.edu/people/shivers/srfi/srfi-1/srfi-1.html (draft)

This document, in simple text format:
    http://srfi.schemers.org/srfi-1/srfi-1.txt
    ftp://ftp.ai.mit.edu/people/shivers/srfi/srfi-1/srfi-1.txt (draft)

Source code for the reference implementation:
    http://srfi.schemers.org/srfi-1/srfi-1-reference.scm
    ftp://ftp.ai.mit.edu/people/shivers/srfi/srfi-1/srfi-1-reference.scm (draft)

Archive of SRFI-1 discussion-list email:
    http://srfi.schemers.org/srfi-1/mail-archive/maillist.html

SRFI web site:
    http://srfi.schemers.org/


[CommonLisp]
    Common Lisp: the Language
    Guy L. Steele Jr. (editor).
    Digital Press, Maynard, Mass., second edition 1990.
    Available at http://www.elwood.com/alu/table/references.htm#cltl2

    The Common Lisp "HyperSpec," produced by Kent Pitman, is essentially
    the ANSI spec for Common Lisp:
    http://www.harlequin.com/education/books/HyperSpec/

[R5RS]
    Revised^5 Report on the Algorithmic Language Scheme, 
    R. Kelsey, W. Clinger, J. Rees (editors).
    Higher-Order and Symbolic Computation, Vol. 11, No. 1, September, 1998.
    and ACM SIGPLAN Notices, Vol. 33, No. 9, October, 1998.

    Available at http://www.schemers.org/Documents/Standards/
    

* Copyright
-----------

Certain portions of this document -- the specific, marked segments of text
describing the R5RS procedures -- were adapted with permission from the R5RS
report.
    
All other text is copyright (C) Olin Shivers (1998, 1999). 
All Rights Reserved. 

This document and translations of it may be copied and furnished to others,
and derivative works that comment on or otherwise explain it or assist in its
implementation may be prepared, copied, published and distributed, in whole or
in part, without restriction of any kind, provided that the above copyright
notice and this paragraph are included on all such copies and derivative
works. However, this document itself may not be modified in any way, such as
by removing the copyright notice or references to the Scheme Request For
Implementation process or editors, except as needed for the purpose of
developing SRFIs in which case the procedures for copyrights defined in the
SRFI process must be followed, or as required to translate it into languages
other than English.

The limited permissions granted above are perpetual and will not be revoked by
the authors or their successors or assigns.

This document and the information contained herein is provided on an "AS IS"
basis and THE AUTHORS AND THE SRFI EDITORS DISCLAIM ALL WARRANTIES, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.



* Ispell "buffer local" dictionary
----------------------------------

Ispell dumps "buffer local" words here. Please ignore.

 LocalWords:  RS SRFI Chez RScheme MzScheme slib Bigloo APL SML API CDR GC's Ei
 LocalWords:  EQ consing lib xcons unzip del delq delv mem lset lset xor diff lp
 LocalWords:  alist assq assv assoc cdr cdddar cddddr ref memq memv george iff
 LocalWords:  proc lis accessor ary TAIL's NCONS EQV rcons Contrariwise clist
 LocalWords:  paribus lexeme parallelise Destructuring init FP flist eof CLISTn
 LocalWords:  generalisation elt cadr caddr rev kons knil len rzero LZERO Ki Ith
 LocalWords:  arg LISTi pred cond LISTn ANY's EVERY's Uniquifying lg ridentity
 LocalWords:  eq netnews generalise Maciej Stachowiak al Bewig LocalWords ELTi
 LocalWords:  anamorphism apomorphism CLISTi ALIST's url ceteris eltn caar KNULL
 LocalWords:  deconstructor RIGHT's KAR KDR kar kdr knull HTML CLtL Clinger gen
 LocalWords:  Rees Bawden Blandy Bornstein Bothner Carrico Currie Dybvig expt
 LocalWords:  Egorov Feeley Matthias Felleisen Flatt Hilsdale Hukriede CLISTs
 LocalWords:  Kolbly Shriram Krishnamurthi Jussi Piitulainen Pokorny Joerg Todo
 LocalWords:  Sperber Wittenberger documentors Jaffer initialised consed IE
 LocalWords:  disarranging SIGPLAN CommonLisp cltl HyperSpec