From 306942a604d69beefa5522d8623060ce1a83b57c Mon Sep 17 00:00:00 2001
Message-Id: <306942a604d69beefa5522d8623060ce1a83b57c.1260078974.git.zbigniewsz@gmail.com>
In-Reply-To: <cover.1260078974.git.zbigniewsz@gmail.com>
References: <cover.1260078974.git.zbigniewsz@gmail.com>
From: zbigniew <zbigniewsz@gmail.com>
Date: Sat, 5 Dec 2009 23:34:34 -0600
Subject: Sync changes from wiki manual to core: SVN 16552-16559 (R5RS standard)
Status: O


Signed-off-by: zbigniew <zbigniewsz@gmail.com>
---
 manual/Supported language |    1 +
 manual/The R5RS standard  | 3060 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 3061 insertions(+), 0 deletions(-)
 create mode 100644 manual/The R5RS standard

diff --git a/manual/Supported language b/manual/Supported language
index 8f546a1..4ffdd9d 100644
--- a/manual/Supported language	
+++ b/manual/Supported language	
@@ -2,6 +2,7 @@
 
 == Supported language
 
+* [[The R5RS standard]]
 * [[Deviations from the standard]]  
 * [[Extensions to the standard]]  
 * [[Non-standard read syntax]]    
diff --git a/manual/The R5RS standard b/manual/The R5RS standard
new file mode 100644
index 0000000..adb4091
--- /dev/null
+++ b/manual/The R5RS standard	
@@ -0,0 +1,3060 @@
+This document describes Chicken's R5RS support, with a heavy emphasis
+on syntax and procedures.  It is based directly on the
+''Revised^5 Report on the Algorithmic Language Scheme''.
+[[toc:]]
+== Overview of Scheme
+== Lexical conventions
+== Basic concepts
+== Expressions
+
+Expression types are categorized as primitive or derived. Primitive
+expression types include variables and procedure calls. Derived
+expression types are not semantically primitive, but can instead be
+defined as macros. With the exception of quasiquote, whose macro
+definition is complex, the derived expressions are classified as
+library features. Suitable definitions are given in section 7.3.
+
+=== Primitive expression types
+
+==== Variable references
+
+<macro><variable></macro><br>
+
+An expression consisting of a variable (section 3.1) is a variable
+reference. The value of the variable reference is the value stored in
+the location to which the variable is bound. It is an error to
+reference an unbound variable.
+
+ (define x 28)
+ x           ===>  28
+
+==== Literal expressions
+
+<macro>(quote <datum>)</macro><br>
+<macro>'<datum></macro><br>
+<macro><constant></macro><br>
+
+(quote <datum>) evaluates to <datum>. <Datum> may be any external
+representation of a Scheme object (see section 3.3). This notation is
+used to include literal constants in Scheme code.
+
+ (quote a)                    ===>  a
+ (quote #(a b c))             ===>  #(a b c)
+ (quote (+ 1 2))              ===>  (+ 1 2)
+
+(quote <datum>) may be abbreviated as '<datum>. The two notations are
+equivalent in all respects.
+
+ 'a                           ===>  a
+ '#(a b c)                    ===>  #(a b c)
+ '()                          ===>  ()
+ '(+ 1 2)                     ===>  (+ 1 2)
+ '(quote a)                   ===>  (quote a)
+ "a                           ===>  (quote a)
+
+Numerical constants, string constants, character constants, and boolean
+constants evaluate "to themselves"; they need not be quoted.
+
+ '"abc"             ===>  "abc"
+ "abc"              ===>  "abc"
+ '145932            ===>  145932
+ 145932             ===>  145932
+ '#t                ===>  #t
+ #t                 ===>  #t
+
+As noted in section 3.4, it is an error to alter a constant (i.e. the
+value of a literal expression) using a mutation procedure like set-car!
+or string-set!.
+
+==== Procedure calls
+
+<macro>(<operator> <operand[1]> ...)</macro><br>
+
+A procedure call is written by simply enclosing in parentheses
+expressions for the procedure to be called and the arguments to be
+passed to it. The operator and operand expressions are evaluated (in an
+unspecified order) and the resulting procedure is passed the resulting
+arguments.
+
+ (+ 3 4)                           ===>  7
+ ((if #f + *) 3 4)                 ===>  12
+
+A number of procedures are available as the values of variables in the
+initial environment; for example, the addition and multiplication
+procedures in the above examples are the values of the variables + and *.
+New procedures are created by evaluating lambda expressions (see
+section 4.1.4). Procedure calls may return any number of values (see
+values in section 6.4). With the exception of values the procedures
+available in the initial environment return one value or, for
+procedures such as apply, pass on the values returned by a call to one
+of their arguments.
+
+Procedure calls are also called combinations.
+
+Note:   In contrast to other dialects of Lisp, the order of
+evaluation is unspecified, and the operator expression and the
+operand expressions are always evaluated with the same evaluation
+rules.
+
+Note:   Although the order of evaluation is otherwise unspecified,
+the effect of any concurrent evaluation of the operator and operand
+expressions is constrained to be consistent with some sequential
+order of evaluation. The order of evaluation may be chosen
+differently for each procedure call.
+
+Note:   In many dialects of Lisp, the empty combination, (), is a
+legitimate expression. In Scheme, combinations must have at least
+one subexpression, so () is not a syntactically valid expression.
+
+==== Procedures
+
+<macro>(lambda <formals> <body>)</macro><br>
+
+Syntax: <Formals> should be a formal arguments list as described below,
+and <body> should be a sequence of one or more expressions.
+
+Semantics: A lambda expression evaluates to a procedure. The
+environment in effect when the lambda expression was evaluated is
+remembered as part of the procedure. When the procedure is later called
+with some actual arguments, the environment in which the lambda
+expression was evaluated will be extended by binding the variables in
+the formal argument list to fresh locations, the corresponding actual
+argument values will be stored in those locations, and the expressions
+in the body of the lambda expression will be evaluated sequentially in
+the extended environment. The result(s) of the last expression in the
+body will be returned as the result(s) of the procedure call.
+
+ (lambda (x) (+ x x))              ===>  a procedure
+ ((lambda (x) (+ x x)) 4)          ===>  8
+ 
+ (define reverse-subtract
+   (lambda (x y) (- y x)))
+ (reverse-subtract 7 10)           ===>  3
+ 
+ (define add4
+   (let ((x 4))
+     (lambda (y) (+ x y))))
+ (add4 6)                          ===>  10
+
+<Formals> should have one of the following forms:
+
+*   (<variable[1]> ...): The procedure takes a fixed number of
+    arguments; when the procedure is called, the arguments will be
+    stored in the bindings of the corresponding variables.
+
+*   <variable>: The procedure takes any number of arguments; when the
+    procedure is called, the sequence of actual arguments is converted
+    into a newly allocated list, and the list is stored in the binding
+    of the <variable>.
+
+*   (<variable[1]> ... <variable[n]> . <variable[n+1]>): If a
+    space-delimited period precedes the last variable, then the
+    procedure takes n or more arguments, where n is the number of
+    formal arguments before the period (there must be at least one).
+    The value stored in the binding of the last variable will be a
+    newly allocated list of the actual arguments left over after all
+    the other actual arguments have been matched up against the other
+    formal arguments.
+
+It is an error for a <variable> to appear more than once in <formals>.
+
+ ((lambda x x) 3 4 5 6)                  ===>  (3 4 5 6)
+ ((lambda (x y . z) z)
+  3 4 5 6)                               ===>  (5 6)
+
+Each procedure created as the result of evaluating a lambda expression
+is (conceptually) tagged with a storage location, in order to make eqv?
+and eq? work on procedures (see section 6.1).
+
+==== Conditionals
+
+<macro>(if <test> <consequent> <alternate>)</macro><br>
+<macro>(if <test> <consequent>)</macro><br>
+
+Syntax: <Test>, <consequent>, and <alternate> may be arbitrary
+expressions.
+
+Semantics: An if expression is evaluated as follows: first, <test> is
+evaluated. If it yields a true value (see section 6.3.1), then
+<consequent> is evaluated and its value(s) is(are) returned. Otherwise
+<alternate> is evaluated and its value(s) is(are) returned. If <test>
+yields a false value and no <alternate> is specified, then the result
+of the expression is unspecified.
+
+ (if (> 3 2) 'yes 'no)                   ===>  yes
+ (if (> 2 3) 'yes 'no)                   ===>  no
+ (if (> 3 2)
+     (- 3 2)
+     (+ 3 2))                            ===>  1
+
+==== Assignments
+
+<macro>(set! <variable> <expression>)</macro><br>
+
+<Expression> is evaluated, and the resulting value is stored in the
+location to which <variable> is bound. <Variable> must be bound either
+in some region enclosing the set! expression or at top level. The
+result of the set! expression is unspecified.
+
+ (define x 2)
+ (+ x 1)                         ===>  3
+ (set! x 4)                      ===>  unspecified
+ (+ x 1)                         ===>  5
+
+=== Derived expression types
+
+The constructs in this section are hygienic, as discussed in section 
+4.3. For reference purposes, section 7.3 gives macro definitions that
+will convert most of the constructs described in this section into the
+primitive constructs described in the previous section.
+
+==== Conditionals
+
+<macro>(cond <clause[1]> <clause[2]> ...)</macro><br>
+
+Syntax: Each <clause> should be of the form
+
+ (<test> <expression[1]> ...)
+
+where <test> is any expression. Alternatively, a <clause> may be of the
+form
+
+ (<test> => <expression>)
+
+The last <clause> may be an "else clause," which has the form
+
+ (else <expression[1]> <expression[2]> ...).
+
+Semantics: A cond expression is evaluated by evaluating the <test>
+expressions of successive <clause>s in order until one of them
+evaluates to a true value (see section 6.3.1). When a <test> evaluates
+to a true value, then the remaining <expression>s in its <clause> are
+evaluated in order, and the result(s) of the last <expression> in the
+<clause> is(are) returned as the result(s) of the entire cond
+expression. If the selected <clause> contains only the <test> and no
+<expression>s, then the value of the <test> is returned as the result.
+If the selected <clause> uses the => alternate form, then the
+<expression> is evaluated. Its value must be a procedure that accepts
+one argument; this procedure is then called on the value of the <test>
+and the value(s) returned by this procedure is(are) returned by the
+cond expression. If all <test>s evaluate to false values, and there is
+no else clause, then the result of the conditional expression is
+unspecified; if there is an else clause, then its <expression>s are
+evaluated, and the value(s) of the last one is(are) returned.
+
+ (cond ((> 3 2) 'greater)
+       ((< 3 2) 'less))           ===>  greater
+ (cond ((> 3 3) 'greater)
+       ((< 3 3) 'less)
+       (else 'equal))             ===>  equal
+ (cond ((assv 'b '((a 1) (b 2))) => cadr)
+       (else #f))                 ===>  2
+
+<macro>(case <key> <clause[1]> <clause[2]> ...)</macro><br>
+
+Syntax: <Key> may be any expression. Each <clause> should have the form
+
+ ((<datum[1]> ...) <expression[1]> <expression[2]> ...),
+
+where each <datum> is an external representation of some object. All
+the <datum>s must be distinct. The last <clause> may be an "else
+clause," which has the form
+
+ (else <expression[1]> <expression[2]> ...).
+
+Semantics: A case expression is evaluated as follows. <Key> is
+evaluated and its result is compared against each <datum>. If the
+result of evaluating <key> is equivalent (in the sense of eqv?; see
+section 6.1) to a <datum>, then the expressions in the corresponding
+<clause> are evaluated from left to right and the result(s) of the last
+expression in the <clause> is(are) returned as the result(s) of the
+case expression. If the result of evaluating <key> is different from
+every <datum>, then if there is an else clause its expressions are
+evaluated and the result(s) of the last is(are) the result(s) of the
+case expression; otherwise the result of the case expression is
+unspecified.
+
+ (case (* 2 3)
+   ((2 3 5 7) 'prime)
+   ((1 4 6 8 9) 'composite))             ===>  composite
+ (case (car '(c d))
+   ((a) 'a)
+   ((b) 'b))                             ===>  unspecified
+ (case (car '(c d))
+   ((a e i o u) 'vowel)
+   ((w y) 'semivowel)
+   (else 'consonant))                    ===>  consonant
+
+<macro>(and <test[1]> ...)</macro><br>
+
+The <test> expressions are evaluated from left to right, and the value
+of the first expression that evaluates to a false value (see section 
+6.3.1) is returned. Any remaining expressions are not evaluated. If all
+the expressions evaluate to true values, the value of the last
+expression is returned. If there are no expressions then #t is
+returned.
+
+ (and (= 2 2) (> 2 1))                   ===>  #t
+ (and (= 2 2) (< 2 1))                   ===>  #f
+ (and 1 2 'c '(f g))                     ===>  (f g)
+ (and)                                   ===>  #t
+
+<macro>(or <test[1]> ...)</macro><br>
+
+The <test> expressions are evaluated from left to right, and the value
+of the first expression that evaluates to a true value (see section 
+6.3.1) is returned. Any remaining expressions are not evaluated. If all
+expressions evaluate to false values, the value of the last expression
+is returned. If there are no expressions then #f is returned.
+
+ (or (= 2 2) (> 2 1))                    ===>  #t
+ (or (= 2 2) (< 2 1))                    ===>  #t
+ (or #f #f #f)         ===>  #f
+ (or (memq 'b '(a b c)) 
+     (/ 3 0))                            ===>  (b c)
+
+==== Binding constructs
+
+The three binding constructs let, let*, and letrec give Scheme a block
+structure, like Algol 60. The syntax of the three constructs is
+identical, but they differ in the regions they establish for their
+variable bindings. In a let expression, the initial values are computed
+before any of the variables become bound; in a let* expression, the
+bindings and evaluations are performed sequentially; while in a letrec
+expression, all the bindings are in effect while their initial values
+are being computed, thus allowing mutually recursive definitions.
+
+<macro>(let <bindings> <body>)</macro><br>
+
+Syntax: <Bindings> should have the form
+
+ ((<variable[1]> <init[1]>) ...),
+
+where each <init> is an expression, and <body> should be a sequence of
+one or more expressions. It is an error for a <variable> to appear more
+than once in the list of variables being bound.
+
+Semantics: The <init>s are evaluated in the current environment (in
+some unspecified order), the <variable>s are bound to fresh locations
+holding the results, the <body> is evaluated in the extended
+environment, and the value(s) of the last expression of <body> is(are)
+returned. Each binding of a <variable> has <body> as its region.
+
+ (let ((x 2) (y 3))
+   (* x y))                              ===>  6
+ 
+ (let ((x 2) (y 3))
+   (let ((x 7)
+         (z (+ x y)))
+     (* z x)))                           ===>  35
+
+See also named let, section 4.2.4.
+
+<macro>(let* <bindings> <body>)</macro><br>
+
+Syntax: <Bindings> should have the form
+
+ ((<variable[1]> <init[1]>) ...),
+
+and <body> should be a sequence of one or more expressions.
+
+Semantics: Let* is similar to let, but the bindings are performed
+sequentially from left to right, and the region of a binding indicated
+by (<variable> <init>) is that part of the let* expression to the right
+of the binding. Thus the second binding is done in an environment in
+which the first binding is visible, and so on.
+
+ (let ((x 2) (y 3))
+   (let* ((x 7)
+          (z (+ x y)))
+     (* z x)))                     ===>  70
+
+<macro>(letrec <bindings> <body>)</macro><br>
+
+Syntax: <Bindings> should have the form
+
+ ((<variable[1]> <init[1]>) ...),
+
+and <body> should be a sequence of one or more expressions. It is an
+error for a <variable> to appear more than once in the list of
+variables being bound.
+
+Semantics: The <variable>s are bound to fresh locations holding
+undefined values, the <init>s are evaluated in the resulting
+environment (in some unspecified order), each <variable> is assigned to
+the result of the corresponding <init>, the <body> is evaluated in the
+resulting environment, and the value(s) of the last expression in
+<body> is(are) returned. Each binding of a <variable> has the entire
+letrec expression as its region, making it possible to define mutually
+recursive procedures.
+
+ (letrec ((even?
+           (lambda (n)
+             (if (zero? n)
+                 #t
+                 (odd? (- n 1)))))
+          (odd?
+           (lambda (n)
+             (if (zero? n)
+                 #f
+                 (even? (- n 1))))))
+   (even? 88))
+                         ===>  #t
+
+One restriction on letrec is very important: it must be possible to
+evaluate each <init> without assigning or referring to the value of any
+<variable>. If this restriction is violated, then it is an error. The
+restriction is necessary because Scheme passes arguments by value
+rather than by name. In the most common uses of letrec, all the <init>s
+are lambda expressions and the restriction is satisfied automatically.
+
+==== Sequencing
+
+<macro>(begin <expression[1]> <expression[2]> ...)</macro><br>
+
+The <expression>s are evaluated sequentially from left to right, and
+the value(s) of the last <expression> is(are) returned. This expression
+type is used to sequence side effects such as input and output.
+
+ (define x 0)
+ 
+ (begin (set! x 5)
+        (+ x 1))                          ===>  6
+ 
+ (begin (display "4 plus 1 equals ")
+        (display (+ 4 1)))                ===>  unspecified
+   and prints  4 plus 1 equals 5
+
+==== Iteration
+
+<macro>(do ((<variable[1]> <init[1]> <step[1]>) ...) (<test> <expression> ...) <command> ...)</macro><br>
+
+Do is an iteration construct. It specifies a set of variables to be
+bound, how they are to be initialized at the start, and how they are to
+be updated on each iteration. When a termination condition is met, the
+loop exits after evaluating the <expression>s.
+
+Do expressions are evaluated as follows: The <init> expressions are
+evaluated (in some unspecified order), the <variable>s are bound to
+fresh locations, the results of the <init> expressions are stored in
+the bindings of the <variable>s, and then the iteration phase begins.
+
+Each iteration begins by evaluating <test>; if the result is false (see
+section 6.3.1), then the <command> expressions are evaluated in order
+for effect, the <step> expressions are evaluated in some unspecified
+order, the <variable>s are bound to fresh locations, the results of the
+<step>s are stored in the bindings of the <variable>s, and the next
+iteration begins.
+
+If <test> evaluates to a true value, then the <expression>s are
+evaluated from left to right and the value(s) of the last <expression>
+is(are) returned. If no <expression>s are present, then the value of
+the do expression is unspecified.
+
+The region of the binding of a <variable> consists of the entire do
+expression except for the <init>s. It is an error for a <variable> to
+appear more than once in the list of do variables.
+
+A <step> may be omitted, in which case the effect is the same as if
+(<variable> <init> <variable>) had been written instead of (<variable>
+<init>).
+
+ (do ((vec (make-vector 5))
+      (i 0 (+ i 1)))
+     ((= i 5) vec)
+   (vector-set! vec i i))                    ===>  #(0 1 2 3 4)
+ 
+ (let ((x '(1 3 5 7 9)))
+   (do ((x x (cdr x))
+        (sum 0 (+ sum (car x))))
+       ((null? x) sum)))                     ===>  25
+
+<macro>(let <variable> <bindings> <body>)</macro><br>
+
+"Named let" is a variant on the syntax of let which provides a more
+general looping construct than do and may also be used to express
+recursions. It has the same syntax and semantics as ordinary let except
+that <variable> is bound within <body> to a procedure whose formal
+arguments are the bound variables and whose body is <body>. Thus the
+execution of <body> may be repeated by invoking the procedure named by
+<variable>.
+
+ (let loop ((numbers '(3 -2 1 6 -5))
+            (nonneg '())
+            (neg '()))
+   (cond ((null? numbers) (list nonneg neg))
+         ((>= (car numbers) 0)
+          (loop (cdr numbers)
+                (cons (car numbers) nonneg)
+                neg))
+         ((< (car numbers) 0)
+          (loop (cdr numbers)
+                nonneg
+                (cons (car numbers) neg)))))
+                 ===>  ((6 1 3) (-5 -2))
+
+==== Delayed evaluation
+
+<macro>(delay <expression>)</macro><br>
+
+The delay construct is used together with the procedure force to
+implement lazy evaluation or call by need. (delay <expression>) returns
+an object called a promise which at some point in the future may be
+asked (by the force procedure) to evaluate <expression>, and deliver
+the resulting value. The effect of <expression> returning multiple
+values is unspecified.
+
+See the description of force (section 6.4) for a more complete
+description of delay.
+
+==== Quasiquotation
+
+<macro>(quasiquote <qq template>)</macro><br>
+<macro>`<qq template></macro><br>
+
+"Backquote" or "quasiquote" expressions are useful for constructing
+a list or vector structure when most but not all of the desired
+structure is known in advance. If no commas appear within the <qq
+template>, the result of evaluating `<qq template> is equivalent to the
+result of evaluating '<qq template>. If a comma appears within the <qq
+template>, however, the expression following the comma is evaluated
+("unquoted") and its result is inserted into the structure instead of
+the comma and the expression. If a comma appears followed immediately
+by an at-sign (@), then the following expression must evaluate to a
+list; the opening and closing parentheses of the list are then
+"stripped away" and the elements of the list are inserted in place of
+the comma at-sign expression sequence. A comma at-sign should only
+appear within a list or vector <qq template>.
+
+ `(list ,(+ 1 2) 4)          ===>  (list 3 4)
+ (let ((name 'a)) `(list ,name ',name))           
+                 ===>  (list a (quote a))
+ `(a ,(+ 1 2) ,@(map abs '(4 -5 6)) b)           
+                 ===>  (a 3 4 5 6 b)
+ `(( foo ,(- 10 3)) ,@(cdr '(c)) . ,(car '(cons)))           
+                 ===>  ((foo 7) . cons)
+ `#(10 5 ,(sqrt 4) ,@(map sqrt '(16 9)) 8)           
+                 ===>  #(10 5 2 4 3 8)
+
+Quasiquote forms may be nested. Substitutions are made only for
+unquoted components appearing at the same nesting level as the
+outermost backquote. The nesting level increases by one inside each
+successive quasiquotation, and decreases by one inside each
+unquotation.
+
+ `(a `(b ,(+ 1 2) ,(foo ,(+ 1 3) d) e) f)           
+                 ===>  (a `(b ,(+ 1 2) ,(foo 4 d) e) f)
+ (let ((name1 'x)
+       (name2 'y))
+   `(a `(b ,,name1 ,',name2 d) e))           
+                 ===>  (a `(b ,x ,'y d) e)
+
+The two notations `<qq template> and (quasiquote <qq template>) are
+identical in all respects. ,<expression> is identical to (unquote
+<expression>), and ,@<expression> is identical to (unquote-splicing
+<expression>). The external syntax generated by write for two-element
+lists whose car is one of these symbols may vary between
+implementations.
+
+ (quasiquote (list (unquote (+ 1 2)) 4))           
+                 ===>  (list 3 4)
+ '(quasiquote (list (unquote (+ 1 2)) 4))           
+                 ===>  `(list ,(+ 1 2) 4)
+      i.e., (quasiquote (list (unquote (+ 1 2)) 4))
+
+Unpredictable behavior can result if any of the symbols quasiquote,
+unquote, or unquote-splicing appear in positions within a <qq template>
+otherwise than as described above.
+
+=== Macros
+
+Scheme programs can define and use new derived expression types, called
+macros. Program-defined expression types have the syntax
+
+ (<keyword> <datum> ...)
+
+where <keyword> is an identifier that uniquely determines the
+expression type. This identifier is called the syntactic keyword, or
+simply keyword, of the macro. The number of the <datum>s, and their
+syntax, depends on the expression type.
+
+Each instance of a macro is called a use of the macro. The set of rules
+that specifies how a use of a macro is transcribed into a more
+primitive expression is called the transformer of the macro.
+
+The macro definition facility consists of two parts:
+
+*   A set of expressions used to establish that certain identifiers are
+    macro keywords, associate them with macro transformers, and control
+    the scope within which a macro is defined, and
+
+*   a pattern language for specifying macro transformers.
+
+The syntactic keyword of a macro may shadow variable bindings, and
+local variable bindings may shadow keyword bindings. All macros defined
+using the pattern language are "hygienic" and "referentially
+transparent" and thus preserve Scheme's lexical scoping:
+
+*   If a macro transformer inserts a binding for an identifier
+    (variable or keyword), the identifier will in effect be renamed
+    throughout its scope to avoid conflicts with other identifiers.
+    Note that a define at top level may or may not introduce a binding;
+    see section 5.2.
+
+*   If a macro transformer inserts a free reference to an identifier,
+    the reference refers to the binding that was visible where the
+    transformer was specified, regardless of any local bindings that
+    may surround the use of the macro.
+
+==== Binding constructs for syntactic keywords
+
+Let-syntax and letrec-syntax are analogous to let and letrec, but they
+bind syntactic keywords to macro transformers instead of binding
+variables to locations that contain values. Syntactic keywords may also
+be bound at top level; see section 5.3.
+
+<macro>(let-syntax <bindings> <body>)</macro><br>
+
+Syntax: <Bindings> should have the form
+
+ ((<keyword> <transformer spec>) ...)
+
+Each <keyword> is an identifier, each <transformer spec> is an instance
+of syntax-rules, and <body> should be a sequence of one or more
+expressions. It is an error for a <keyword> to appear more than once in
+the list of keywords being bound.
+
+Semantics: The <body> is expanded in the syntactic environment obtained
+by extending the syntactic environment of the let-syntax expression
+with macros whose keywords are the <keyword>s, bound to the specified
+transformers. Each binding of a <keyword> has <body> as its region.
+
+ (let-syntax ((when (syntax-rules ()
+                      ((when test stmt1 stmt2 ...)
+                       (if test
+                           (begin stmt1
+                                  stmt2 ...))))))
+   (let ((if #t))
+     (when if (set! if 'now))
+     if))                                   ===>  now
+ 
+ (let ((x 'outer))
+   (let-syntax ((m (syntax-rules () ((m) x))))
+     (let ((x 'inner))
+       (m))))                               ===>  outer
+
+<macro>(letrec-syntax <bindings> <body>)</macro><br>
+
+Syntax: Same as for let-syntax.
+
+Semantics: The <body> is expanded in the syntactic environment obtained
+by extending the syntactic environment of the letrec-syntax expression
+with macros whose keywords are the <keyword>s, bound to the specified
+transformers. Each binding of a <keyword> has the <bindings> as well as
+the <body> within its region, so the transformers can transcribe
+expressions into uses of the macros introduced by the letrec-syntax
+expression.
+
+ (letrec-syntax
+   ((my-or (syntax-rules ()
+             ((my-or) #f)
+             ((my-or e) e)
+             ((my-or e1 e2 ...)
+              (let ((temp e1))
+                (if temp
+                    temp
+                    (my-or e2 ...)))))))
+   (let ((x #f)
+         (y 7)
+         (temp 8)
+         (let odd?)
+         (if even?))
+     (my-or x
+            (let temp)
+            (if y)
+            y)))                ===>  7
+
+==== Pattern language
+
+A <transformer spec> has the following form:
+
+ (syntax-rules <literals> <syntax rule> ...)
+
+Syntax: <Literals> is a list of identifiers and each <syntax rule>
+should be of the form
+
+ (<pattern> <template>)
+
+The <pattern> in a <syntax rule> is a list <pattern> that begins with
+the keyword for the macro.
+
+A <pattern> is either an identifier, a constant, or one of the
+following
+
+ (<pattern> ...)
+ (<pattern> <pattern> ... . <pattern>)
+ (<pattern> ... <pattern> <ellipsis>)
+ #(<pattern> ...)
+ #(<pattern> ... <pattern> <ellipsis>)
+
+and a template is either an identifier, a constant, or one of the
+following
+
+ (<element> ...)
+ (<element> <element> ... . <template>)
+ #(<element> ...)
+
+where an <element> is a <template> optionally followed by an <ellipsis>
+and an <ellipsis> is the identifier "..." (which cannot be used as an
+identifier in either a template or a pattern).
+
+Semantics: An instance of syntax-rules produces a new macro transformer
+by specifying a sequence of hygienic rewrite rules. A use of a macro
+whose keyword is associated with a transformer specified by
+syntax-rules is matched against the patterns contained in the <syntax
+rule>s, beginning with the leftmost <syntax rule>. When a match is
+found, the macro use is transcribed hygienically according to the
+template.
+
+An identifier that appears in the pattern of a <syntax rule> is a
+pattern variable, unless it is the keyword that begins the pattern, is
+listed in <literals>, or is the identifier "...". Pattern variables
+match arbitrary input elements and are used to refer to elements of the
+input in the template. It is an error for the same pattern variable to
+appear more than once in a <pattern>.
+
+The keyword at the beginning of the pattern in a <syntax rule> is not
+involved in the matching and is not considered a pattern variable or
+literal identifier.
+
+Rationale:   The scope of the keyword is determined by the
+expression or syntax definition that binds it to the associated
+macro transformer. If the keyword were a pattern variable or
+literal identifier, then the template that follows the pattern
+would be within its scope regardless of whether the keyword were
+bound by let-syntax or by letrec-syntax.
+
+Identifiers that appear in <literals> are interpreted as literal
+identifiers to be matched against corresponding subforms of the input.
+A subform in the input matches a literal identifier if and only if it
+is an identifier and either both its occurrence in the macro expression
+and its occurrence in the macro definition have the same lexical
+binding, or the two identifiers are equal and both have no lexical
+binding.
+
+A subpattern followed by ... can match zero or more elements of the
+input. It is an error for ... to appear in <literals>. Within a pattern
+the identifier ... must follow the last element of a nonempty sequence
+of subpatterns.
+
+More formally, an input form F matches a pattern P if and only if:
+
+*   P is a non-literal identifier; or
+
+*   P is a literal identifier and F is an identifier with the same
+    binding; or
+
+*   P is a list (P[1] ... P[n]) and F is a list of n forms that match P
+    [1] through P[n], respectively; or
+
+*   P is an improper list (P[1] P[2] ... P[n] . P[n+1]) and F is a list
+    or improper list of n or more forms that match P[1] through P[n],
+    respectively, and whose nth "cdr" matches P[n+1]; or
+
+*   P is of the form (P[1] ... P[n] P[n+1] <ellipsis>) where <ellipsis>
+    is the identifier ... and F is a proper list of at least n forms,
+    the first n of which match P[1] through P[n], respectively, and
+    each remaining element of F matches P[n+1]; or
+
+*   P is a vector of the form #(P[1] ... P[n]) and F is a vector of n
+    forms that match P[1] through P[n]; or
+
+*   P is of the form #(P[1] ... P[n] P[n+1] <ellipsis>) where
+    <ellipsis> is the identifier ... and F is a vector of n or more
+    forms the first n of which match P[1] through P[n], respectively,
+    and each remaining element of F matches P[n+1]; or
+
+*   P is a datum and F is equal to P in the sense of the equal?
+    procedure.
+
+It is an error to use a macro keyword, within the scope of its binding,
+in an expression that does not match any of the patterns.
+
+When a macro use is transcribed according to the template of the
+matching <syntax rule>, pattern variables that occur in the template
+are replaced by the subforms they match in the input. Pattern variables
+that occur in subpatterns followed by one or more instances of the
+identifier ... are allowed only in subtemplates that are followed by as
+many instances of .... They are replaced in the output by all of the
+subforms they match in the input, distributed as indicated. It is an
+error if the output cannot be built up as specified.
+
+Identifiers that appear in the template but are not pattern variables
+or the identifier ... are inserted into the output as literal
+identifiers. If a literal identifier is inserted as a free identifier
+then it refers to the binding of that identifier within whose scope the
+instance of syntax-rules appears. If a literal identifier is inserted
+as a bound identifier then it is in effect renamed to prevent
+inadvertent captures of free identifiers.
+
+As an example, if let and cond are defined as in section 7.3 then they
+are hygienic (as required) and the following is not an error.
+
+ (let ((=> #f))
+   (cond (#t => 'ok)))                   ===> ok
+
+The macro transformer for cond recognizes => as a local variable, and
+hence an expression, and not as the top-level identifier =>, which the
+macro transformer treats as a syntactic keyword. Thus the example
+expands into
+
+ (let ((=> #f))
+   (if #t (begin => 'ok)))
+
+instead of
+
+ (let ((=> #f))
+   (let ((temp #t))
+     (if temp ('ok temp))))
+
+which would result in an invalid procedure call.
+
+== Program structure
+
+== Standard procedures
+
+This chapter describes Scheme's built-in procedures. The initial (or
+"top level") Scheme environment starts out with a number of variables
+bound to locations containing useful values, most of which are
+primitive procedures that manipulate data. For example, the variable
+abs is bound to (a location initially containing) a procedure of one
+argument that computes the absolute value of a number, and the variable
++ is bound to a procedure that computes sums. Built-in procedures that
+can easily be written in terms of other built-in procedures are
+identified as "library procedures".
+
+A program may use a top-level definition to bind any variable. It may
+subsequently alter any such binding by an assignment (see 4.1.6). These
+operations do not modify the behavior of Scheme's built-in procedures.
+Altering any top-level binding that has not been introduced by a
+definition has an unspecified effect on the behavior of the built-in
+procedures.
+
+=== Equivalence predicates
+
+A predicate is a procedure that always returns a boolean value (#t or #f).
+An equivalence predicate is the computational analogue of a
+mathematical equivalence relation (it is symmetric, reflexive, and
+transitive). Of the equivalence predicates described in this section,
+eq? is the finest or most discriminating, and equal? is the coarsest.
+eqv? is slightly less discriminating than eq?.
+
+<procedure>(eqv? obj[1] obj[2])</procedure><br>
+
+The eqv? procedure defines a useful equivalence relation on objects.
+Briefly, it returns #t if obj[1] and obj[2] should normally be regarded
+as the same object. This relation is left slightly open to
+interpretation, but the following partial specification of eqv? holds
+for all implementations of Scheme.
+
+The eqv? procedure returns #t if:
+
+*   obj[1] and obj[2] are both #t or both #f.
+
+*   obj[1] and obj[2] are both symbols and
+
+    (string=? (symbol->string obj1)
+              (symbol->string obj2))
+                ===>  #t
+
+Note:  This assumes that neither obj[1] nor obj[2] is an
+"uninterned symbol" as alluded to in section 6.3.3. This
+report does not presume to specify the behavior of eqv? on
+implementation-dependent extensions.
+
+*   obj[1] and obj[2] are both numbers, are numerically equal (see =,
+    section 6.2), and are either both exact or both inexact.
+
+*   obj[1] and obj[2] are both characters and are the same character
+    according to the char=? procedure (section 6.3.4).
+
+*   both obj[1] and obj[2] are the empty list.
+
+*   obj[1] and obj[2] are pairs, vectors, or strings that denote the
+    same locations in the store (section 3.4).
+
+*   obj[1] and obj[2] are procedures whose location tags are equal
+    (section 4.1.4).
+
+The eqv? procedure returns #f if:
+
+*   obj[1] and obj[2] are of different types (section 3.2).
+
+*   one of obj[1] and obj[2] is #t but the other is #f.
+
+*   obj[1] and obj[2] are symbols but
+
+    (string=? (symbol->string obj[1])
+              (symbol->string obj[2]))
+                ===>  #f
+
+*   one of obj[1] and obj[2] is an exact number but the other is an
+    inexact number.
+
+*   obj[1] and obj[2] are numbers for which the = procedure returns #f.
+
+*   obj[1] and obj[2] are characters for which the char=? procedure
+    returns #f.
+
+*   one of obj[1] and obj[2] is the empty list but the other is not.
+
+*   obj[1] and obj[2] are pairs, vectors, or strings that denote
+    distinct locations.
+
+*   obj[1] and obj[2] are procedures that would behave differently
+    (return different value(s) or have different side effects) for some
+    arguments.
+
+ (eqv? 'a 'a)                             ===>  #t
+ (eqv? 'a 'b)                             ===>  #f
+ (eqv? 2 2)                               ===>  #t
+ (eqv? '() '())                           ===>  #t
+ (eqv? 100000000 100000000)               ===>  #t
+ (eqv? (cons 1 2) (cons 1 2))             ===>  #f
+ (eqv? (lambda () 1)
+       (lambda () 2))                     ===>  #f
+ (eqv? #f 'nil)                           ===>  #f
+ (let ((p (lambda (x) x)))
+   (eqv? p p))                            ===>  #t
+
+The following examples illustrate cases in which the above rules do not
+fully specify the behavior of eqv?. All that can be said about such
+cases is that the value returned by eqv? must be a boolean.
+
+ (eqv? "" "")                     ===>  unspecified
+ (eqv? '#() '#())                 ===>  unspecified
+ (eqv? (lambda (x) x)
+       (lambda (x) x))            ===>  unspecified
+ (eqv? (lambda (x) x)
+       (lambda (y) y))            ===>  unspecified
+
+The next set of examples shows the use of eqv? with procedures that
+have local state. Gen-counter must return a distinct procedure every
+time, since each procedure has its own internal counter. Gen-loser,
+however, returns equivalent procedures each time, since the local state
+does not affect the value or side effects of the procedures.
+
+ (define gen-counter
+   (lambda ()
+     (let ((n 0))
+       (lambda () (set! n (+ n 1)) n))))
+ (let ((g (gen-counter)))
+   (eqv? g g))                   ===>  #t
+ (eqv? (gen-counter) (gen-counter))
+                                 ===>  #f
+ (define gen-loser
+   (lambda ()
+     (let ((n 0))
+       (lambda () (set! n (+ n 1)) 27))))
+ (let ((g (gen-loser)))
+   (eqv? g g))                   ===>  #t
+ (eqv? (gen-loser) (gen-loser))
+                                 ===>  unspecified
+ 
+ (letrec ((f (lambda () (if (eqv? f g) 'both 'f)))
+          (g (lambda () (if (eqv? f g) 'both 'g))))
+   (eqv? f g))
+                                 ===>  unspecified
+ 
+ (letrec ((f (lambda () (if (eqv? f g) 'f 'both)))
+          (g (lambda () (if (eqv? f g) 'g 'both))))
+   (eqv? f g))
+                                 ===>  #f
+
+Since it is an error to modify constant objects (those returned by
+literal expressions), implementations are permitted, though not
+required, to share structure between constants where appropriate. Thus
+the value of eqv? on constants is sometimes implementation-dependent.
+
+ (eqv? '(a) '(a))                         ===>  unspecified
+ (eqv? "a" "a")                           ===>  unspecified
+ (eqv? '(b) (cdr '(a b)))                 ===>  unspecified
+ (let ((x '(a)))
+   (eqv? x x))                            ===>  #t
+
+Rationale:   The above definition of eqv? allows implementations
+latitude in their treatment of procedures and literals:
+implementations are free either to detect or to fail to detect that
+two procedures or two literals are equivalent to each other, and
+can decide whether or not to merge representations of equivalent
+objects by using the same pointer or bit pattern to represent both.
+
+<procedure>(eq? obj[1] obj[2])</procedure><br>
+
+Eq? is similar to eqv? except that in some cases it is capable of
+discerning distinctions finer than those detectable by eqv?.
+
+Eq? and eqv? are guaranteed to have the same behavior on symbols,
+booleans, the empty list, pairs, procedures, and non-empty strings and
+vectors. Eq?'s behavior on numbers and characters is
+implementation-dependent, but it will always return either true or
+false, and will return true only when eqv? would also return true. Eq?
+may also behave differently from eqv? on empty vectors and empty
+strings.
+
+ (eq? 'a 'a)                             ===>  #t
+ (eq? '(a) '(a))                         ===>  unspecified
+ (eq? (list 'a) (list 'a))               ===>  #f
+ (eq? "a" "a")                           ===>  unspecified
+ (eq? "" "")                             ===>  unspecified
+ (eq? '() '())                           ===>  #t
+ (eq? 2 2)                               ===>  unspecified
+ (eq? #\A #\A)                           ===>  unspecified
+ (eq? car car)                           ===>  #t
+ (let ((n (+ 2 3)))
+   (eq? n n))              ===>  unspecified
+ (let ((x '(a)))
+   (eq? x x))              ===>  #t
+ (let ((x '#()))
+   (eq? x x))              ===>  #t
+ (let ((p (lambda (x) x)))
+   (eq? p p))              ===>  #t
+
+Rationale:   It will usually be possible to implement eq? much more
+efficiently than eqv?, for example, as a simple pointer comparison
+instead of as some more complicated operation. One reason is that
+it may not be possible to compute eqv? of two numbers in constant
+time, whereas eq? implemented as pointer comparison will always
+finish in constant time. Eq? may be used like eqv? in applications
+using procedures to implement objects with state since it obeys the
+same constraints as eqv?.
+
+<procedure>(equal? obj[1] obj[2])</procedure><br>
+
+Equal? recursively compares the contents of pairs, vectors, and
+strings, applying eqv? on other objects such as numbers and symbols. A
+rule of thumb is that objects are generally equal? if they print the
+same. Equal? may fail to terminate if its arguments are circular data
+structures.
+
+ (equal? 'a 'a)                          ===>  #t
+ (equal? '(a) '(a))                      ===>  #t
+ (equal? '(a (b) c)
+         '(a (b) c))                     ===>  #t
+ (equal? "abc" "abc")                    ===>  #t
+ (equal? 2 2)                            ===>  #t
+ (equal? (make-vector 5 'a)
+         (make-vector 5 'a))             ===>  #t
+ (equal? (lambda (x) x)
+         (lambda (y) y))          ===>  unspecified
+
+=== Numbers
+
+Numerical computation has traditionally been neglected by the Lisp
+community. Until Common Lisp there was no carefully thought out
+strategy for organizing numerical computation, and with the exception
+of the MacLisp system [20] little effort was made to execute numerical
+code efficiently. This report recognizes the excellent work of the
+Common Lisp committee and accepts many of their recommendations. In
+some ways this report simplifies and generalizes their proposals in a
+manner consistent with the purposes of Scheme.
+
+It is important to distinguish between the mathematical numbers, the
+Scheme numbers that attempt to model them, the machine representations
+used to implement the Scheme numbers, and notations used to write
+numbers. This report uses the types number, complex, real, rational,
+and integer to refer to both mathematical numbers and Scheme numbers.
+Machine representations such as fixed point and floating point are
+referred to by names such as fixnum and flonum.
+
+==== Numerical types
+
+Mathematically, numbers may be arranged into a tower of subtypes in
+which each level is a subset of the level above it:
+
+    number
+    complex
+    real
+    rational
+    integer
+
+For example, 3 is an integer. Therefore 3 is also a rational, a real,
+and a complex. The same is true of the Scheme numbers that model 3. For
+Scheme numbers, these types are defined by the predicates number?,
+complex?, real?, rational?, and integer?.
+
+There is no simple relationship between a number's type and its
+representation inside a computer. Although most implementations of
+Scheme will offer at least two different representations of 3, these
+different representations denote the same integer.
+
+Scheme's numerical operations treat numbers as abstract data, as
+independent of their representation as possible. Although an
+implementation of Scheme may use fixnum, flonum, and perhaps other
+representations for numbers, this should not be apparent to a casual
+programmer writing simple programs.
+
+It is necessary, however, to distinguish between numbers that are
+represented exactly and those that may not be. For example, indexes
+into data structures must be known exactly, as must some polynomial
+coefficients in a symbolic algebra system. On the other hand, the
+results of measurements are inherently inexact, and irrational numbers
+may be approximated by rational and therefore inexact approximations.
+In order to catch uses of inexact numbers where exact numbers are
+required, Scheme explicitly distinguishes exact from inexact numbers.
+This distinction is orthogonal to the dimension of type.
+
+==== Exactness
+
+Scheme numbers are either exact or inexact. A number is exact if it was
+written as an exact constant or was derived from exact numbers using
+only exact operations. A number is inexact if it was written as an
+inexact constant, if it was derived using inexact ingredients, or if it
+was derived using inexact operations. Thus inexactness is a contagious
+property of a number. If two implementations produce exact results for
+a computation that did not involve inexact intermediate results, the
+two ultimate results will be mathematically equivalent. This is
+generally not true of computations involving inexact numbers since
+approximate methods such as floating point arithmetic may be used, but
+it is the duty of each implementation to make the result as close as
+practical to the mathematically ideal result.
+
+Rational operations such as + should always produce exact results when
+given exact arguments. If the operation is unable to produce an exact
+result, then it may either report the violation of an implementation
+restriction or it may silently coerce its result to an inexact value.
+See section 6.2.3.
+
+With the exception of inexact->exact, the operations described in this
+section must generally return inexact results when given any inexact
+arguments. An operation may, however, return an exact result if it can
+prove that the value of the result is unaffected by the inexactness of
+its arguments. For example, multiplication of any number by an exact
+zero may produce an exact zero result, even if the other argument is
+inexact.
+
+==== Implementation restrictions
+
+Implementations of Scheme are not required to implement the whole tower
+of subtypes given in section 6.2.1, but they must implement a coherent
+subset consistent with both the purposes of the implementation and the
+spirit of the Scheme language. For example, an implementation in which
+all numbers are real may still be quite useful.
+
+Implementations may also support only a limited range of numbers of any
+type, subject to the requirements of this section. The supported range
+for exact numbers of any type may be different from the supported range
+for inexact numbers of that type. For example, an implementation that
+uses flonums to represent all its inexact real numbers may support a
+practically unbounded range of exact integers and rationals while
+limiting the range of inexact reals (and therefore the range of inexact
+integers and rationals) to the dynamic range of the flonum format.
+Furthermore the gaps between the representable inexact integers and
+rationals are likely to be very large in such an implementation as the
+limits of this range are approached.
+
+An implementation of Scheme must support exact integers throughout the
+range of numbers that may be used for indexes of lists, vectors, and
+strings or that may result from computing the length of a list, vector,
+or string. The length, vector-length, and string-length procedures must
+return an exact integer, and it is an error to use anything but an
+exact integer as an index. Furthermore any integer constant within the
+index range, if expressed by an exact integer syntax, will indeed be
+read as an exact integer, regardless of any implementation restrictions
+that may apply outside this range. Finally, the procedures listed below
+will always return an exact integer result provided all their arguments
+are exact integers and the mathematically expected result is
+representable as an exact integer within the implementation:
+
+ +            -             *
+ quotient     remainder     modulo
+ max          min           abs
+ numerator    denominator   gcd
+ lcm          floor         ceiling
+ truncate     round         rationalize
+ expt
+
+Implementations are encouraged, but not required, to support exact
+integers and exact rationals of practically unlimited size and
+precision, and to implement the above procedures and the / procedure in
+such a way that they always return exact results when given exact
+arguments. If one of these procedures is unable to deliver an exact
+result when given exact arguments, then it may either report a
+violation of an implementation restriction or it may silently coerce
+its result to an inexact number. Such a coercion may cause an error
+later.
+
+An implementation may use floating point and other approximate
+representation strategies for inexact numbers. This report recommends,
+but does not require, that the IEEE 32-bit and 64-bit floating point
+standards be followed by implementations that use flonum
+representations, and that implementations using other representations
+should match or exceed the precision achievable using these floating
+point standards [12].
+
+In particular, implementations that use flonum representations must
+follow these rules: A flonum result must be represented with at least
+as much precision as is used to express any of the inexact arguments to
+that operation. It is desirable (but not required) for potentially
+inexact operations such as sqrt, when applied to exact arguments, to
+produce exact answers whenever possible (for example the square root of
+an exact 4 ought to be an exact 2). If, however, an exact number is
+operated upon so as to produce an inexact result (as by sqrt), and if
+the result is represented as a flonum, then the most precise flonum
+format available must be used; but if the result is represented in some
+other way then the representation must have at least as much precision
+as the most precise flonum format available.
+
+Although Scheme allows a variety of written notations for numbers, any
+particular implementation may support only some of them. For example,
+an implementation in which all numbers are real need not support the
+rectangular and polar notations for complex numbers. If an
+implementation encounters an exact numerical constant that it cannot
+represent as an exact number, then it may either report a violation of
+an implementation restriction or it may silently represent the constant
+by an inexact number.
+
+==== Syntax of numerical constants
+
+The syntax of the written representations for numbers is described
+formally in section 7.1.1. Note that case is not significant in
+numerical constants.
+
+A number may be written in binary, octal, decimal, or hexadecimal by
+the use of a radix prefix. The radix prefixes are #b (binary), #o
+(octal), #d (decimal), and #x (hexadecimal). With no radix prefix, a
+number is assumed to be expressed in decimal.
+
+A numerical constant may be specified to be either exact or inexact by
+a prefix. The prefixes are #e for exact, and #i for inexact. An
+exactness prefix may appear before or after any radix prefix that is
+used. If the written representation of a number has no exactness
+prefix, the constant may be either inexact or exact. It is inexact if
+it contains a decimal point, an exponent, or a "#" character in the
+place of a digit, otherwise it is exact. In systems with inexact
+numbers of varying precisions it may be useful to specify the precision
+of a constant. For this purpose, numerical constants may be written
+with an exponent marker that indicates the desired precision of the
+inexact representation. The letters s, f, d, and l specify the use of
+short, single, double, and long precision, respectively. (When fewer
+than four internal inexact representations exist, the four size
+specifications are mapped onto those available. For example, an
+implementation with two internal representations may map short and
+single together and long and double together.) In addition, the
+exponent marker e specifies the default precision for the
+implementation. The default precision has at least as much precision as
+double, but implementations may wish to allow this default to be set by
+the user.
+
+ 3.14159265358979F0
+         Round to single --- 3.141593
+ 0.6L0
+         Extend to long --- .600000000000000
+
+==== Numerical operations
+
+The reader is referred to section 1.3.3 for a summary of the naming
+conventions used to specify restrictions on the types of arguments to
+numerical routines. The examples used in this section assume that any
+numerical constant written using an exact notation is indeed
+represented as an exact number. Some examples also assume that certain
+numerical constants written using an inexact notation can be
+represented without loss of accuracy; the inexact constants were chosen
+so that this is likely to be true in implementations that use flonums
+to represent inexact numbers.
+
+<procedure>(number? obj)</procedure><br>
+<procedure>(complex? obj)</procedure><br>
+<procedure>(real? obj)</procedure><br>
+<procedure>(rational? obj)</procedure><br>
+<procedure>(integer? obj)</procedure><br>
+
+These numerical type predicates can be applied to any kind of argument,
+including non-numbers. They return #t if the object is of the named
+type, and otherwise they return #f. In general, if a type predicate is
+true of a number then all higher type predicates are also true of that
+number. Consequently, if a type predicate is false of a number, then
+all lower type predicates are also false of that number. If z is an
+inexact complex number, then (real? z) is true if and only if (zero?
+(imag-part z)) is true. If x is an inexact real number, then (integer?
+x) is true if and only if (= x (round x)).
+
+ (complex? 3+4i)                 ===>  #t
+ (complex? 3)                    ===>  #t
+ (real? 3)                       ===>  #t
+ (real? -2.5+0.0i)               ===>  #t
+ (real? #e1e10)                  ===>  #t
+ (rational? 6/10)                ===>  #t
+ (rational? 6/3)                 ===>  #t
+ (integer? 3+0i)                 ===>  #t
+ (integer? 3.0)                  ===>  #t
+ (integer? 8/4)                  ===>  #t
+
+Note:   The behavior of these type predicates on inexact numbers is
+unreliable, since any inaccuracy may affect the result.
+
+Note:   In many implementations the rational? procedure will be the
+same as real?, and the complex? procedure will be the same as
+number?, but unusual implementations may be able to represent some
+irrational numbers exactly or may extend the number system to
+support some kind of non-complex numbers.
+
+<procedure>(exact? z)</procedure><br>
+<procedure>(inexact? z)</procedure><br>
+
+These numerical predicates provide tests for the exactness of a
+quantity. For any Scheme number, precisely one of these predicates is
+true.
+
+<procedure>(= z[1] z[2] z[3] ...)</procedure><br>
+<procedure>(< x[1] x[2] x[3] ...)</procedure><br>
+<procedure>(> x[1] x[2] x[3] ...)</procedure><br>
+<procedure>(<= x[1] x[2] x[3] ...)</procedure><br>
+<procedure>(>= x[1] x[2] x[3] ...)</procedure><br>
+
+These procedures return #t if their arguments are (respectively):
+equal, monotonically increasing, monotonically decreasing,
+monotonically nondecreasing, or monotonically nonincreasing.
+
+These predicates are required to be transitive.
+
+Note:   The traditional implementations of these predicates in
+Lisp-like languages are not transitive.
+
+Note:   While it is not an error to compare inexact numbers using
+these predicates, the results may be unreliable because a small
+inaccuracy may affect the result; this is especially true of = and
+zero?. When in doubt, consult a numerical analyst.
+
+<procedure>(zero? z)</procedure><br>
+<procedure>(positive? x)</procedure><br>
+<procedure>(negative? x)</procedure><br>
+<procedure>(odd? n)</procedure><br>
+<procedure>(even? n)</procedure><br>
+
+These numerical predicates test a number for a particular property,
+returning #t or #f. See note above.
+
+<procedure>(max x[1] x[2] ...)</procedure><br>
+<procedure>(min x[1] x[2] ...)</procedure><br>
+
+These procedures return the maximum or minimum of their arguments.
+
+ (max 3 4)                      ===>  4    ; exact
+ (max 3.9 4)                    ===>  4.0  ; inexact
+
+Note:   If any argument is inexact, then the result will also be
+inexact (unless the procedure can prove that the inaccuracy is not
+large enough to affect the result, which is possible only in
+unusual implementations). If min or max is used to compare numbers
+of mixed exactness, and the numerical value of the result cannot be
+represented as an inexact number without loss of accuracy, then the
+procedure may report a violation of an implementation restriction.
+
+<procedure>(+ z[1] ...)</procedure><br>
+<procedure>(* z[1] ...)</procedure><br>
+
+These procedures return the sum or product of their arguments.
+
+ (+ 3 4)                         ===>  7
+ (+ 3)                           ===>  3
+ (+)                             ===>  0
+ (* 4)                           ===>  4
+ (*)                             ===>  1
+
+<procedure>(- z[1] z[2])</procedure><br>
+<procedure>(- z)</procedure><br>
+<procedure>(- z[1] z[2] ...)</procedure><br>
+<procedure>(/ z[1] z[2])</procedure><br>
+<procedure>(/ z)</procedure><br>
+<procedure>(/ z[1] z[2] ...)</procedure><br>
+
+With two or more arguments, these procedures return the difference or
+quotient of their arguments, associating to the left. With one
+argument, however, they return the additive or multiplicative inverse
+of their argument.
+
+ (- 3 4)                         ===>  -1
+ (- 3 4 5)                       ===>  -6
+ (- 3)                           ===>  -3
+ (/ 3 4 5)                       ===>  3/20
+ (/ 3)                           ===>  1/3
+
+<procedure>(abs x)</procedure><br>
+
+Abs returns the absolute value of its argument.
+
+ (abs -7)                        ===>  7
+
+<procedure>(quotient n[1] n[2])</procedure><br>
+<procedure>(remainder n[1] n[2])</procedure><br>
+<procedure>(modulo n[1] n[2])</procedure><br>
+
+These procedures implement number-theoretic (integer) division. n[2]
+should be non-zero. All three procedures return integers. If n[1]/n[2]
+is an integer:
+
+    (quotient n[1] n[2])           ===> n[1]/n[2]
+    (remainder n[1] n[2])          ===> 0
+    (modulo n[1] n[2])             ===> 0
+
+If n[1]/n[2] is not an integer:
+
+    (quotient n[1] n[2])           ===> n[q]
+    (remainder n[1] n[2])          ===> n[r]
+    (modulo n[1] n[2])             ===> n[m]
+
+where n[q] is n[1]/n[2] rounded towards zero, 0 < |n[r]| < |n[2]|, 0 <
+|n[m]| < |n[2]|, n[r] and n[m] differ from n[1] by a multiple of n[2],
+n[r] has the same sign as n[1], and n[m] has the same sign as n[2].
+
+From this we can conclude that for integers n[1] and n[2] with n[2] not
+equal to 0,
+
+     (= n[1] (+ (* n[2] (quotient n[1] n[2]))
+           (remainder n[1] n[2])))
+                                         ===>  #t
+
+provided all numbers involved in that computation are exact.
+
+ (modulo 13 4)                   ===>  1
+ (remainder 13 4)                ===>  1
+ 
+ (modulo -13 4)                  ===>  3
+ (remainder -13 4)               ===>  -1
+ 
+ (modulo 13 -4)                  ===>  -3
+ (remainder 13 -4)               ===>  1
+ 
+ (modulo -13 -4)                 ===>  -1
+ (remainder -13 -4)              ===>  -1
+ 
+ (remainder -13 -4.0)            ===>  -1.0  ; inexact
+
+<procedure>(gcd n[1] ...)</procedure><br>
+<procedure>(lcm n[1] ...)</procedure><br>
+
+These procedures return the greatest common divisor or least common
+multiple of their arguments. The result is always non-negative.
+
+ (gcd 32 -36)                    ===>  4
+ (gcd)                           ===>  0
+ (lcm 32 -36)                    ===>  288
+ (lcm 32.0 -36)                  ===>  288.0  ; inexact
+ (lcm)                           ===>  1
+
+<procedure>(numerator q)</procedure><br>
+<procedure>(denominator q)</procedure><br>
+
+These procedures return the numerator or denominator of their argument;
+the result is computed as if the argument was represented as a fraction
+in lowest terms. The denominator is always positive. The denominator of
+0 is defined to be 1.
+
+ (numerator (/ 6 4))            ===>  3
+ (denominator (/ 6 4))          ===>  2
+ (denominator
+   (exact->inexact (/ 6 4)))    ===> 2.0
+
+<procedure>(floor x)</procedure><br>
+<procedure>(ceiling x)</procedure><br>
+<procedure>(truncate x)</procedure><br>
+<procedure>(round x)</procedure><br>
+
+These procedures return integers. Floor returns the largest integer not
+larger than x. Ceiling returns the smallest integer not smaller than x.
+Truncate returns the integer closest to x whose absolute value is not
+larger than the absolute value of x. Round returns the closest integer
+to x, rounding to even when x is halfway between two integers.
+
+Rationale:   Round rounds to even for consistency with the default
+rounding mode specified by the IEEE floating point standard.
+
+Note:   If the argument to one of these procedures is inexact, then
+the result will also be inexact. If an exact value is needed, the
+result should be passed to the inexact->exact procedure.
+
+ (floor -4.3)                  ===>  -5.0
+ (ceiling -4.3)                ===>  -4.0
+ (truncate -4.3)               ===>  -4.0
+ (round -4.3)                  ===>  -4.0
+ 
+ (floor 3.5)                   ===>  3.0
+ (ceiling 3.5)                 ===>  4.0
+ (truncate 3.5)                ===>  3.0
+ (round 3.5)                   ===>  4.0  ; inexact
+ 
+ (round 7/2)                   ===>  4    ; exact
+ (round 7)                     ===>  7
+
+<procedure>(rationalize x y)</procedure><br>
+
+Rationalize returns the simplest rational number differing from x by no
+more than y. A rational number r[1] is simpler than another rational
+number r[2] if r[1] = p[1]/q[1] and r[2] = p[2]/q[2] (in lowest terms)
+and |p[1]| < |p[2]| and |q[1]| < |q[2]|. Thus 3/5 is simpler than 4/7.
+Although not all rationals are comparable in this ordering (consider 2/
+7 and 3/5) any interval contains a rational number that is simpler than
+every other rational number in that interval (the simpler 2/5 lies
+between 2/7 and 3/5). Note that 0 = 0/1 is the simplest rational of
+all.
+
+ (rationalize
+   (inexact->exact .3) 1/10)          ===> 1/3    ; exact
+ (rationalize .3 1/10)                ===> #i1/3  ; inexact
+
+<procedure>(exp z)</procedure><br>
+<procedure>(log z)</procedure><br>
+<procedure>(sin z)</procedure><br>
+<procedure>(cos z)</procedure><br>
+<procedure>(tan z)</procedure><br>
+<procedure>(asin z)</procedure><br>
+<procedure>(acos z)</procedure><br>
+<procedure>(atan z)</procedure><br>
+<procedure>(atan y x)</procedure><br>
+
+These procedures are part of every implementation that supports general
+real numbers; they compute the usual transcendental functions. Log
+computes the natural logarithm of z (not the base ten logarithm). Asin,
+acos, and atan compute arcsine (sin^-1), arccosine (cos^-1), and
+arctangent (tan^-1), respectively. The two-argument variant of atan
+computes (angle (make-rectangular x y)) (see below), even in
+implementations that don't support general complex numbers.
+
+In general, the mathematical functions log, arcsine, arccosine, and
+arctangent are multiply defined. The value of log z is defined to be
+the one whose imaginary part lies in the range from -pi
+(exclusive) to pi (inclusive). log 0 is undefined. With log
+defined this way, the values of sin^-1 z, cos^-1 z, and tan^-1 z are
+according to the following formulae:
+
+ sin^-1 z = - i log (i z + (1 - z^2)^1/2)
+ 
+ cos^-1 z = pi / 2 - sin^-1 z
+ 
+ tan^-1 z = (log (1 + i z) - log (1 - i z)) / (2 i)
+
+The above specification follows [27], which in turn cites [19]; refer
+to these sources for more detailed discussion of branch cuts, boundary
+conditions, and implementation of these functions. When it is possible
+these procedures produce a real result from a real argument.
+
+<procedure>(sqrt z)</procedure><br>
+
+Returns the principal square root of z. The result will have either
+positive real part, or zero real part and non-negative imaginary part.
+
+<procedure>(expt z[1] z[2])</procedure><br>
+
+Returns z[1] raised to the power z[2]. For z[1] != 0
+
+ z[1]^z[2] = e^z[2] log z[1]
+
+0^z is 1 if z = 0 and 0 otherwise.
+
+<procedure>(make-rectangular x[1] x[2])</procedure><br>
+<procedure>(make-polar x[3] x[4])</procedure><br>
+<procedure>(real-part z)</procedure><br>
+<procedure>(imag-part z)</procedure><br>
+<procedure>(magnitude z)</procedure><br>
+<procedure>(angle z)</procedure><br>
+
+These procedures are part of every implementation that supports general
+complex numbers. Suppose x[1], x[2], x[3], and x[4] are real numbers
+and z is a complex number such that
+
+ z = x[1] + x[2]i = x[3] . e^i x[4]
+
+Then
+
+ (make-rectangular x[1] x[2])         ===> z
+ (make-polar x[3] x[4])             ===> z
+ (real-part z)                          ===> x[1]
+ (imag-part z)                          ===> x[2]
+ (magnitude z)                          ===> |x[3]|
+ (angle z)                              ===> x[angle]
+
+where - pi < x[angle] < pi with x[angle] = x[4] + 2 pi n
+for some integer n.
+
+Rationale:   Magnitude is the same as abs for a real argument, but
+abs must be present in all implementations, whereas magnitude need
+only be present in implementations that support general complex
+numbers.
+
+<procedure>(exact->inexact z)</procedure><br>
+<procedure>(inexact->exact z)</procedure><br>
+
+Exact->inexact returns an inexact representation of z. The value
+returned is the inexact number that is numerically closest to the
+argument. If an exact argument has no reasonably close inexact
+equivalent, then a violation of an implementation restriction may be
+reported.
+
+Inexact->exact returns an exact representation of z. The value returned
+is the exact number that is numerically closest to the argument. If an
+inexact argument has no reasonably close exact equivalent, then a
+violation of an implementation restriction may be reported.
+
+These procedures implement the natural one-to-one correspondence
+between exact and inexact integers throughout an
+implementation-dependent range. See section 6.2.3.
+
+==== Numerical input and output
+
+<procedure>(number->string z)</procedure><br>
+<procedure>(number->string z radix)</procedure><br>
+
+Radix must be an exact integer, either 2, 8, 10, or 16. If omitted, radix
+defaults to 10. The procedure number->string takes a number and a
+radix and returns as a string an external representation of the given
+number in the given radix such that
+
+ (let ((number number)
+       (radix radix))
+   (eqv? number
+         (string->number (number->string number
+                                         radix)
+                         radix)))
+
+is true. It is an error if no possible result makes this expression
+true.
+
+If z is inexact, the radix is 10, and the above expression can be
+satisfied by a result that contains a decimal point, then the result
+contains a decimal point and is expressed using the minimum number of
+digits (exclusive of exponent and trailing zeroes) needed to make the
+above expression true [3, 5]; otherwise the format of the result is
+unspecified.
+
+The result returned by number->string never contains an explicit radix
+prefix.
+
+Note:   The error case can occur only when z is not a complex
+number or is a complex number with a non-rational real or imaginary
+part.
+
+Rationale:   If z is an inexact number represented using flonums,
+and the radix is 10, then the above expression is normally
+satisfied by a result containing a decimal point. The unspecified
+case allows for infinities, NaNs, and non-flonum representations.
+
+<procedure>(string->number string)</procedure><br>
+<procedure>(string->number string radix)</procedure><br>
+
+Returns a number of the maximally precise representation expressed by
+the given string. Radix must be an exact integer, either 2, 8, 10, or
+16. If supplied, radix is a default radix that may be overridden by an
+explicit radix prefix in string (e.g. "#o177"). If radix is not
+supplied, then the default radix is 10. If string is not a
+syntactically valid notation for a number, then string->number 
+returns #f.
+
+ (string->number "100")                ===>  100
+ (string->number "100" 16)             ===>  256
+ (string->number "1e2")                ===>  100.0
+ (string->number "15##")               ===>  1500.0
+
+Note:   The domain of string->number may be restricted by
+implementations in the following ways. String->number is permitted
+to return #f whenever string contains an explicit radix prefix. If
+all numbers supported by an implementation are real, then string->
+number is permitted to return #f whenever string uses the polar or
+rectangular notations for complex numbers. If all numbers are
+integers, then string->number may return #f whenever the fractional
+notation is used. If all numbers are exact, then string->number may
+return #f whenever an exponent marker or explicit exactness prefix
+is used, or if a # appears in place of a digit. If all inexact
+numbers are integers, then string->number may return #f whenever a
+decimal point is used.
+
+=== Other data types
+
+This section describes operations on some of Scheme's non-numeric data
+types: booleans, pairs, lists, symbols, characters, strings and
+vectors.
+
+==== Booleans
+
+The standard boolean objects for true and false are written as #t and #f.
+What really matters, though, are the objects that the Scheme
+conditional expressions (if, cond, and, or, do) treat as true or false.
+The phrase "a true value" (or sometimes just "true") means any
+object treated as true by the conditional expressions, and the phrase
+"a false value" (or "false") means any object treated as false by
+the conditional expressions.
+
+Of all the standard Scheme values, only #f counts as false in
+conditional expressions. Except for #f, all standard Scheme values,
+including #t, pairs, the empty list, symbols, numbers, strings,
+vectors, and procedures, count as true.
+
+Note:   Programmers accustomed to other dialects of Lisp should be
+aware that Scheme distinguishes both #f and the empty list from the
+symbol nil.
+
+Boolean constants evaluate to themselves, so they do not need to be
+quoted in programs.
+
+ #t                ===>  #t
+ #f                ===>  #f
+ '#f               ===>  #f
+
+<procedure>(not obj)</procedure><br>
+
+Not returns #t if obj is false, and returns #f otherwise.
+
+ (not #t)           ===>  #f
+ (not 3)            ===>  #f
+ (not (list 3))     ===>  #f
+ (not #f)           ===>  #t
+ (not '())          ===>  #f
+ (not (list))       ===>  #f
+ (not 'nil)         ===>  #f
+
+<procedure>(boolean? obj)</procedure><br>
+
+Boolean? returns #t if obj is either #t or #f and returns #f otherwise.
+
+ (boolean? #f)                 ===>  #t
+ (boolean? 0)                  ===>  #f
+ (boolean? '())                ===>  #f
+
+==== Pairs and lists
+
+A pair (sometimes called a dotted pair) is a record structure with two
+fields called the car and cdr fields (for historical reasons). Pairs
+are created by the procedure cons. The car and cdr fields are accessed
+by the procedures car and cdr. The car and cdr fields are assigned by
+the procedures set-car! and set-cdr!.
+
+Pairs are used primarily to represent lists. A list can be defined
+recursively as either the empty list or a pair whose cdr is a list.
+More precisely, the set of lists is defined as the smallest set X such
+that
+
+*   The empty list is in X.
+*   If list is in X, then any pair whose cdr field contains list is
+    also in X.
+
+The objects in the car fields of successive pairs of a list are the
+elements of the list. For example, a two-element list is a pair whose
+car is the first element and whose cdr is a pair whose car is the
+second element and whose cdr is the empty list. The length of a list is
+the number of elements, which is the same as the number of pairs.
+
+The empty list is a special object of its own type (it is not a pair);
+it has no elements and its length is zero.
+
+Note:   The above definitions imply that all lists have finite
+length and are terminated by the empty list.
+
+The most general notation (external representation) for Scheme pairs is
+the "dotted" notation (c[1] . c[2]) where c[1] is the value of the
+car field and c[2] is the value of the cdr field. For example (4 . 5)
+is a pair whose car is 4 and whose cdr is 5. Note that (4 . 5) is the
+external representation of a pair, not an expression that evaluates to
+a pair.
+
+A more streamlined notation can be used for lists: the elements of the
+list are simply enclosed in parentheses and separated by spaces. The
+empty list is written () . For example,
+
+ (a b c d e)
+
+and
+
+ (a . (b . (c . (d . (e . ())))))
+
+are equivalent notations for a list of symbols.
+
+A chain of pairs not ending in the empty list is called an improper
+list. Note that an improper list is not a list. The list and dotted
+notations can be combined to represent improper lists:
+
+ (a b c . d)
+
+is equivalent to
+
+ (a . (b . (c . d)))
+
+Whether a given pair is a list depends upon what is stored in the cdr
+field. When the set-cdr! procedure is used, an object can be a list one
+moment and not the next:
+
+ (define x (list 'a 'b 'c))
+ (define y x)
+ y                               ===>  (a b c)
+ (list? y)                       ===>  #t
+ (set-cdr! x 4)                  ===>  unspecified
+ x                               ===>  (a . 4)
+ (eqv? x y)                      ===>  #t
+ y                               ===>  (a . 4)
+ (list? y)                       ===>  #f
+ (set-cdr! x x)                  ===>  unspecified
+ (list? x)                       ===>  #f
+
+Within literal expressions and representations of objects read by the
+read procedure, the forms '<datum>, `<datum>, ,<datum>, and ,@<datum>
+denote two-element lists whose first elements are the symbols quote,
+quasiquote, unquote, and unquote-splicing, respectively. The second
+element in each case is <datum>. This convention is supported so that
+arbitrary Scheme programs may be represented as lists. That is,
+according to Scheme's grammar, every <expression> is also a <datum>
+(see section 7.1.2). Among other things, this permits the use of the
+read procedure to parse Scheme programs. See section 3.3.
+
+<procedure>(pair? obj)</procedure><br>
+
+Pair? returns #t if obj is a pair, and otherwise returns #f.
+
+ (pair? '(a . b))                ===>  #t
+ (pair? '(a b c))                ===>  #t
+ (pair? '())                     ===>  #f
+ (pair? '#(a b))                 ===>  #f
+
+<procedure>(cons obj[1] obj[2])</procedure><br>
+
+Returns a newly allocated pair whose car is obj[1] and whose cdr is
+obj[2]. 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)
+
+<procedure>(car pair)</procedure><br>
+
+Returns the contents of the car field of pair. Note that it is an error
+to take the car of the empty list.
+
+ (car '(a b c))                  ===>  a
+ (car '((a) b c d))              ===>  (a)
+ (car '(1 . 2))                  ===>  1
+ (car '())                       ===>  error
+
+<procedure>(cdr pair)</procedure><br>
+
+Returns the contents of the cdr field of pair. Note that it is an error
+to take the cdr of the empty list.
+
+ (cdr '((a) b c d))              ===>  (b c d)
+ (cdr '(1 . 2))                  ===>  2
+ (cdr '())                       ===>  error
+
+<procedure>(set-car! pair obj)</procedure><br>
+
+Stores obj in the car field of pair. The value returned by set-car! is
+unspecified.
+
+ (define (f) (list 'not-a-constant-list))
+ (define (g) '(constant-list))
+ (set-car! (f) 3)                     ===>  unspecified
+ (set-car! (g) 3)                     ===>  error
+
+<procedure>(set-cdr! pair obj)</procedure><br>
+
+Stores obj in the cdr field of pair. The value returned by set-cdr! is
+unspecified.
+
+<procedure>(caar pair)</procedure><br>
+<procedure>(cadr pair)</procedure><br>
+<procedure>(cdddar pair)</procedure><br>
+<procedure>(cddddr pair)</procedure><br>
+
+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.
+
+<procedure>(null? obj)</procedure><br>
+
+Returns #t if obj is the empty list, otherwise returns #f.
+
+<procedure>(list? obj)</procedure><br>
+
+Returns #t if obj is a list, otherwise returns #f. By definition, all
+lists have finite length and are terminated by the empty list.
+
+ (list? '(a b c))             ===>  #t
+ (list? '())                  ===>  #t
+ (list? '(a . b))             ===>  #f
+ (let ((x (list 'a)))
+   (set-cdr! x x)
+   (list? x))                 ===>  #f
+
+<procedure>(list obj ...)</procedure><br>
+
+Returns a newly allocated list of its arguments.
+
+ (list 'a (+ 3 4) 'c)                    ===>  (a 7 c)
+ (list)                                  ===>  ()
+
+<procedure>(length list)</procedure><br>
+
+Returns the length of list.
+
+ (length '(a b c))                       ===>  3
+ (length '(a (b) (c d e)))               ===>  3
+ (length '())                            ===>  0
+
+<procedure>(append list ...)</procedure><br>
+
+Returns a list consisting of the elements of the first list followed by
+the elements of the other lists.
+
+ (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 last list argument. The last argument may actually
+be any object; an improper list results if the last argument is not a
+proper list.
+
+ (append '(a b) '(c . d))                ===>  (a b c . d)
+ (append '() 'a)                         ===>  a
+
+<procedure>(reverse list)</procedure><br>
+
+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)
+
+<procedure>(list-tail list k)</procedure><br>
+
+Returns the sublist of list obtained by omitting the first k elements.
+It is an error if list has fewer than k elements. List-tail could be
+defined by
+
+ (define list-tail
+   (lambda (x k)
+     (if (zero? k)
+         x
+         (list-tail (cdr x) (- k 1)))))
+
+<procedure>(list-ref list k)</procedure><br>
+
+Returns the kth element of list. (This is the same as the car of
+(list-tail list k).) It is an error if list has fewer than k elements.
+
+ (list-ref '(a b c d) 2)                ===>  c
+ (list-ref '(a b c d)
+           (inexact->exact (round 1.8))) 
+                 ===>  c
+
+<procedure>(memq obj list)</procedure><br>
+<procedure>(memv obj list)</procedure><br>
+<procedure>(member obj list)</procedure><br>
+
+These procedures return the first sublist of list whose car is obj,
+where the sublists of list are the non-empty lists returned by
+(list-tail list k) for k less than the length of list. If obj does not
+occur in list, then #f (not the empty list) is returned. Memq uses eq?
+to compare obj 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)
+
+<procedure>(assq obj alist)</procedure><br>
+<procedure>(assv obj alist)</procedure><br>
+<procedure>(assoc obj alist)</procedure><br>
+
+Alist (for "association list") must be a list of pairs. These
+procedures find the first pair in alist whose car field is obj, and
+returns that pair. If no pair in alist has obj as its car, then #f (not
+the empty list) is returned. Assq uses eq? to compare obj 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)
+
+Rationale:   Although they are ordinarily used as predicates, memq,
+memv, member, assq, assv, and assoc do not have question marks in
+their names because they return useful values rather than just #t
+or #f.
+
+==== Symbols
+
+Symbols are objects whose usefulness rests on the fact that two symbols
+are identical (in the sense of eqv?) if and only if their names are
+spelled the same way. This is exactly the property needed to represent
+identifiers in programs, and so most implementations of Scheme use them
+internally for that purpose. Symbols are useful for many other
+applications; for instance, they may be used the way enumerated values
+are used in Pascal.
+
+The rules for writing a symbol are exactly the same as the rules for
+writing an identifier; see sections 2.1 and 7.1.1.
+
+It is guaranteed that any symbol that has been returned as part of a
+literal expression, or read using the read procedure, and subsequently
+written out using the write procedure, will read back in as the
+identical symbol (in the sense of eqv?). The string->symbol procedure,
+however, can create symbols for which this write/read invariance may
+not hold because their names contain special characters or letters in
+the non-standard case.
+
+Note:   Some implementations of Scheme have a feature known as
+"slashification" in order to guarantee write/read invariance for
+all symbols, but historically the most important use of this
+feature has been to compensate for the lack of a string data type.
+
+Some implementations also have "uninterned symbols", which defeat
+write/read invariance even in implementations with slashification,
+and also generate exceptions to the rule that two symbols are the
+same if and only if their names are spelled the same.
+
+<procedure>(symbol? obj)</procedure><br>
+
+Returns #t if obj is a symbol, otherwise returns #f.
+
+ (symbol? 'foo)                  ===>  #t
+ (symbol? (car '(a b)))          ===>  #t
+ (symbol? "bar")                 ===>  #f
+ (symbol? 'nil)                  ===>  #t
+ (symbol? '())                   ===>  #f
+ (symbol? #f)                    ===>  #f
+
+<procedure>(symbol->string symbol)</procedure><br>
+
+Returns the name of symbol as a string. If the symbol was part of an
+object returned as the value of a literal expression (section 4.1.2) or
+by a call to the read procedure, and its name contains alphabetic
+characters, then the string returned will contain characters in the
+implementation's preferred standard case -- some implementations will
+prefer upper case, others lower case. If the symbol was returned by
+string->symbol, the case of characters in the string returned will be
+the same as the case in the string that was passed to string->symbol.
+It is an error to apply mutation procedures like string-set! to strings
+returned by this procedure.
+
+The following examples assume that the implementation's standard case
+is lower case:
+
+ (symbol->string 'flying-fish)     
+                                           ===>  "flying-fish"
+ (symbol->string 'Martin)                  ===>  "martin"
+ (symbol->string
+    (string->symbol "Malvina"))     
+                                           ===>  "Malvina"
+
+<procedure>(string->symbol string)</procedure><br>
+
+Returns the symbol whose name is string. This procedure can create
+symbols with names containing special characters or letters in the
+non-standard case, but it is usually a bad idea to create such symbols
+because in some implementations of Scheme they cannot be read as
+themselves. See symbol->string.
+
+The following examples assume that the implementation's standard case
+is lower case:
+
+ (eq? 'mISSISSIppi 'mississippi)  
+                 ===>  #t
+ (string->symbol "mISSISSIppi")  
+                 ===>  the symbol with name "mISSISSIppi"
+ (eq? 'bitBlt (string->symbol "bitBlt"))     
+                 ===>  #f
+ (eq? 'JollyWog
+      (string->symbol
+        (symbol->string 'JollyWog)))  
+                 ===>  #t
+ (string=? "K. Harper, M.D."
+           (symbol->string
+             (string->symbol "K. Harper, M.D.")))  
+                 ===>  #t
+
+==== Characters
+
+Characters are objects that represent printed characters such as
+letters and digits. Characters are written using the notation #\
+<character> or #\<character name>. For example:
+
+ #\a       ; lower case letter
+ #\A       ; upper case letter
+ #\(       ; left parenthesis
+ #\        ; the space character
+ #\space   ; the preferred way to write a space
+ #\newline ; the newline character
+
+Case is significant in #\<character>, but not in #\<character name>. If
+<character> in #\<character> is alphabetic, then the character
+following <character> must be a delimiter character such as a space or
+parenthesis. This rule resolves the ambiguous case where, for example,
+the sequence of characters "#\space" could be taken to be either a
+representation of the space character or a representation of the
+character "#\s" followed by a representation of the symbol "pace."
+
+Characters written in the #\ notation are self-evaluating. That is,
+they do not have to be quoted in programs. Some of the procedures that
+operate on characters ignore the difference between upper case and
+lower case. The procedures that ignore case have "-ci" (for "case
+insensitive") embedded in their names.
+
+<procedure>(char? obj)</procedure><br>
+
+Returns #t if obj is a character, otherwise returns #f.
+
+<procedure>(char=? char[1] char[2])</procedure><br>
+<procedure>(char<? char[1] char[2])</procedure><br>
+<procedure>(char>? char[1] char[2])</procedure><br>
+<procedure>(char<=? char[1] char[2])</procedure><br>
+<procedure>(char>=? char[1] char[2])</procedure><br>
+
+These procedures impose a total ordering on the set of characters. It
+is guaranteed that under this ordering:
+
+*   The upper case characters are in order. For example, (char<? #\A #\
+    B) returns #t.
+*   The lower case characters are in order. For example, (char<? #\a #\
+    b) returns #t.
+*   The digits are in order. For example, (char<? #\0 #\9) returns #t.
+*   Either all the digits precede all the upper case letters, or vice
+    versa.
+*   Either all the digits precede all the lower case letters, or vice
+    versa.
+
+Some implementations may generalize these procedures to take more than
+two arguments, as with the corresponding numerical predicates.
+
+<procedure>(char-ci=? char[1] char[2])</procedure><br>
+<procedure>(char-ci<? char[1] char[2])</procedure><br>
+<procedure>(char-ci>? char[1] char[2])</procedure><br>
+<procedure>(char-ci<=? char[1] char[2])</procedure><br>
+<procedure>(char-ci>=? char[1] char[2])</procedure><br>
+
+These procedures are similar to char=? et cetera, but they treat upper
+case and lower case letters as the same. For example, (char-ci=? #\A #\
+a) returns #t. Some implementations may generalize these procedures to
+take more than two arguments, as with the corresponding numerical
+predicates.
+
+<procedure>(char-alphabetic? char)</procedure><br>
+<procedure>(char-numeric? char)</procedure><br>
+<procedure>(char-whitespace? char)</procedure><br>
+<procedure>(char-upper-case? letter)</procedure><br>
+<procedure>(char-lower-case? letter)</procedure><br>
+
+These procedures return #t if their arguments are alphabetic, numeric,
+whitespace, upper case, or lower case characters, respectively,
+otherwise they return #f. The following remarks, which are specific to
+the ASCII character set, are intended only as a guide: The alphabetic
+characters are the 52 upper and lower case letters. The numeric
+characters are the ten decimal digits. The whitespace characters are
+space, tab, line feed, form feed, and carriage return.
+
+<procedure>(char->integer char)</procedure><br>
+<procedure>(integer->char n)</procedure><br>
+
+Given a character, char->integer returns an exact integer
+representation of the character. Given an exact integer that is the
+image of a character under char->integer, integer->char returns that
+character. These procedures implement order-preserving isomorphisms
+between the set of characters under the char<=? ordering and some
+subset of the integers under the <= ordering. That is, if
+
+ (char<=? a b) ===> #t  and  (<= x y) ===> #t
+
+and x and y are in the domain of integer->char, then
+
+ (<= (char->integer a)
+     (char->integer b))                  ===>  #t
+ 
+ (char<=? (integer->char x)
+          (integer->char y))             ===>  #t
+
+<procedure>(char-upcase char)</procedure><br>
+<procedure>(char-downcase char)</procedure><br>
+
+These procedures return a character char[2] such that (char-ci=? char
+char[2]). In addition, if char is alphabetic, then the result of
+char-upcase is upper case and the result of char-downcase is lower
+case.
+
+==== Strings
+
+Strings are sequences of characters. Strings are written as sequences
+of characters enclosed within doublequotes ("). A doublequote can be
+written inside a string only by escaping it with a backslash (\), as in
+
+"The word \"recursion\" has many meanings."
+
+A backslash can be written inside a string only by escaping it with
+another backslash. Scheme does not specify the effect of a backslash
+within a string that is not followed by a doublequote or backslash.
+
+A string constant may continue from one line to the next, but the exact
+contents of such a string are unspecified. The length of a string is
+the number of characters that it contains. This number is an exact,
+non-negative integer that is fixed when the string is created. The 
+valid indexes of a string are the exact non-negative integers less than
+the length of the string. The first character of a string has index 0,
+the second has index 1, and so on.
+
+In phrases such as "the characters of string beginning with index
+start and ending with index end," it is understood that the index
+start is inclusive and the index end is exclusive. Thus if start and
+end are the same index, a null substring is referred to, and if start
+is zero and end is the length of string, then the entire string is
+referred to.
+
+Some of the procedures that operate on strings ignore the difference
+between upper and lower case. The versions that ignore case have
+"-ci" (for "case insensitive") embedded in their names.
+
+<procedure>(string? obj)</procedure><br>
+
+Returns #t if obj is a string, otherwise returns #f.
+
+<procedure>(make-string k)</procedure><br>
+<procedure>(make-string k char)</procedure><br>
+
+Make-string returns a newly allocated string of length k. If char is
+given, then all elements of the string are initialized to char,
+otherwise the contents of the string are unspecified.
+
+<procedure>(string char ...)</procedure><br>
+
+Returns a newly allocated string composed of the arguments.
+
+<procedure>(string-length string)</procedure><br>
+
+Returns the number of characters in the given string.
+
+<procedure>(string-ref string k)</procedure><br>
+
+k must be a valid index of string. String-ref returns character k of
+string using zero-origin indexing.
+
+<procedure>(string-set! string k char)</procedure><br>
+
+k must be a valid index of string. String-set! stores char in element k
+of string and returns an unspecified value.
+
+ (define (f) (make-string 3 #\*))
+ (define (g) "***")
+ (string-set! (f) 0 #\?)          ===>  unspecified
+ (string-set! (g) 0 #\?)          ===>  error
+ (string-set! (symbol->string 'immutable)
+              0
+              #\?)          ===>  error
+
+<procedure>(string=? string[1] string[2])</procedure><br>
+<procedure>(string-ci=? string[1] string[2])</procedure><br>
+
+Returns #t if the two strings are the same length and contain the same
+characters in the same positions, otherwise returns #f. String-ci=?
+treats upper and lower case letters as though they were the same
+character, but string=? treats upper and lower case as distinct
+characters.
+
+<procedure>(string<? string[1] string[2])</procedure><br>
+<procedure>(string>? string[1] string[2])</procedure><br>
+<procedure>(string<=? string[1] string[2])</procedure><br>
+<procedure>(string>=? string[1] string[2])</procedure><br>
+<procedure>(string-ci<? string[1] string[2])</procedure><br>
+<procedure>(string-ci>? string[1] string[2])</procedure><br>
+<procedure>(string-ci<=? string[1] string[2])</procedure><br>
+<procedure>(string-ci>=? string[1] string[2])</procedure><br>
+
+These procedures are the lexicographic extensions to strings of the
+corresponding orderings on characters. For example, string<? is the
+lexicographic ordering on strings induced by the ordering char<? on
+characters. If two strings differ in length but are the same up to the
+length of the shorter string, the shorter string is considered to be
+lexicographically less than the longer string.
+
+Implementations may generalize these and the string=? and string-ci=?
+procedures to take more than two arguments, as with the corresponding
+numerical predicates.
+
+<procedure>(substring string start end)</procedure><br>
+
+String must be a string, and start and end must be exact integers
+satisfying
+
+ 0 < start < end < (string-length string)
+
+Substring returns a newly allocated string formed from the characters
+of string beginning with index start (inclusive) and ending with index
+end (exclusive).
+
+<procedure>(string-append string ...)</procedure><br>
+
+Returns a newly allocated string whose characters form the
+concatenation of the given strings.
+
+<procedure>(string->list string)</procedure><br>
+<procedure>(list->string list)</procedure><br>
+
+String->list returns a newly allocated list of the characters that make
+up the given string. List->string returns a newly allocated string
+formed from the characters in the list list, which must be a list of
+characters. String->list and list->string are inverses so far as equal?
+is concerned.
+
+<procedure>(string-copy string)</procedure><br>
+
+Returns a newly allocated copy of the given string.
+
+<procedure>(string-fill! string char)</procedure><br>
+
+Stores char in every element of the given string and returns an
+unspecified value.
+
+==== Vectors
+
+Vectors are heterogenous structures whose elements are indexed by
+integers. A vector typically occupies less space than a list of the
+same length, and the average time required to access a randomly chosen
+element is typically less for the vector than for the list.
+
+The length of a vector is the number of elements that it contains. This
+number is a non-negative integer that is fixed when the vector is
+created. The valid indexes of a vector are the exact non-negative
+integers less than the length of the vector. The first element in a
+vector is indexed by zero, and the last element is indexed by one less
+than the length of the vector.
+
+Vectors are written using the notation #(obj ...). For example, a
+vector of length 3 containing the number zero in element 0, the list (2
+2 2 2) in element 1, and the string "Anna" in element 2 can be written
+as following:
+
+ #(0 (2 2 2 2) "Anna")
+
+Note that this is the external representation of a vector, not an
+expression evaluating to a vector. Like list constants, vector
+constants must be quoted:
+
+ '#(0 (2 2 2 2) "Anna")  
+                 ===>  #(0 (2 2 2 2) "Anna")
+
+<procedure>(vector? obj)</procedure><br>
+
+Returns #t if obj is a vector, otherwise returns #f.
+
+<procedure>(make-vector k)</procedure><br>
+<procedure>(make-vector k fill)</procedure><br>
+
+Returns a newly allocated vector of k elements. If a second argument is
+given, then each element is initialized to fill. Otherwise the initial
+contents of each element is unspecified.
+
+<procedure>(vector obj ...)</procedure><br>
+
+Returns a newly allocated vector whose elements contain the given
+arguments. Analogous to list.
+
+ (vector 'a 'b 'c)                       ===>  #(a b c)
+
+<procedure>(vector-length vector)</procedure><br>
+
+Returns the number of elements in vector as an exact integer.
+
+<procedure>(vector-ref vector k)</procedure><br>
+
+k must be a valid index of vector. Vector-ref returns the contents of
+element k of vector.
+
+ (vector-ref '#(1 1 2 3 5 8 13 21)
+             5)  
+                 ===>  8
+ (vector-ref '#(1 1 2 3 5 8 13 21)
+             (let ((i (round (* 2 (acos -1)))))
+               (if (inexact? i)
+                   (inexact->exact i)
+                   i))) 
+                 ===> 13
+
+<procedure>(vector-set! vector k obj)</procedure><br>
+
+k must be a valid index of vector. Vector-set! stores obj in element k
+of vector. The value returned by vector-set! is unspecified.
+
+ (let ((vec (vector 0 '(2 2 2 2) "Anna")))
+   (vector-set! vec 1 '("Sue" "Sue"))
+   vec)      
+                 ===>  #(0 ("Sue" "Sue") "Anna")
+ 
+ (vector-set! '#(0 1 2) 1 "doe")  
+                 ===>  error  ; constant vector
+
+<procedure>(vector->list vector)</procedure><br>
+<procedure>(list->vector list)</procedure><br>
+
+Vector->list returns a newly allocated list of the objects contained in
+the elements of vector. List->vector returns a newly created vector
+initialized to the elements of the list list.
+
+ (vector->list '#(dah dah didah))  
+                 ===>  (dah dah didah)
+ (list->vector '(dididit dah))   
+                 ===>  #(dididit dah)
+
+<procedure>(vector-fill! vector fill)</procedure><br>
+
+Stores fill in every element of vector. The value returned by
+vector-fill! is unspecified.
+
+=== Control features
+
+This chapter describes various primitive procedures which control the
+flow of program execution in special ways. The procedure? predicate is
+also described here.
+
+<procedure>(procedure? obj)</procedure><br>
+
+Returns #t if obj is a procedure, otherwise returns #f.
+
+ (procedure? car)                    ===>  #t
+ (procedure? 'car)                   ===>  #f
+ (procedure? (lambda (x) (* x x)))   
+                                     ===>  #t
+ (procedure? '(lambda (x) (* x x)))  
+                                     ===>  #f
+ (call-with-current-continuation procedure?)
+                                     ===>  #t
+
+<procedure>(apply proc arg[1] ... args)</procedure><br>
+
+Proc must be a procedure and args must be a list. Calls proc with the
+elements of the list (append (list arg[1] ...) args) as the actual
+arguments.
+
+ (apply + (list 3 4))                      ===>  7
+ 
+ (define compose
+   (lambda (f g)
+     (lambda args
+       (f (apply g args)))))
+ 
+ ((compose sqrt *) 12 75)                      ===>  30
+
+<procedure>(map proc list[1] list[2] ...)</procedure><br>
+
+The lists must be lists, and proc must be a procedure taking as many
+arguments as there are lists and returning a single value. If more than
+one list is given, then they must all be the same length. 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)
+
+<procedure>(for-each proc list[1] list[2] ...)</procedure><br>
+
+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 lists 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)
+
+<procedure>(force promise)</procedure><br>
+
+Forces the value of promise (see delay, section 4.2.5). If no value has
+been computed for the promise, then a value is computed and returned.
+The value of the promise is cached (or "memoized") so that if it is
+forced a second time, the previously computed value is returned.
+
+ (force (delay (+ 1 2)))           ===>  3
+ (let ((p (delay (+ 1 2))))
+   (list (force p) (force p)))  
+                                        ===>  (3 3)
+ 
+ (define a-stream
+   (letrec ((next
+             (lambda (n)
+               (cons n (delay (next (+ n 1)))))))
+     (next 0)))
+ (define head car)
+ (define tail
+   (lambda (stream) (force (cdr stream))))
+ 
+ (head (tail (tail a-stream)))  
+                                        ===>  2
+
+Force and delay are mainly intended for programs written in functional
+style. The following examples should not be considered to illustrate
+good programming style, but they illustrate the property that only one
+value is computed for a promise, no matter how many times it is forced.
+
+ (define count 0)
+ (define p
+   (delay (begin (set! count (+ count 1))
+                 (if (> count x)
+                     count
+                     (force p)))))
+ (define x 5)
+ p                             ===>  a promise
+ (force p)                     ===>  6
+ p                             ===>  a promise, still
+ (begin (set! x 10)
+        (force p))             ===>  6
+
+Here is a possible implementation of delay and force. Promises are
+implemented here as procedures of no arguments, and force simply calls
+its argument:
+
+ (define force
+   (lambda (object)
+     (object)))
+
+We define the expression
+
+ (delay <expression>)
+
+to have the same meaning as the procedure call
+
+ (make-promise (lambda () <expression>))
+
+as follows
+
+ (define-syntax delay
+   (syntax-rules ()
+     ((delay expression)
+      (make-promise (lambda () expression))))),
+
+where make-promise is defined as follows:
+
+ (define make-promise
+   (lambda (proc)
+     (let ((result-ready? #f)
+           (result #f))
+       (lambda ()
+         (if result-ready?
+             result
+             (let ((x (proc)))
+               (if result-ready?
+                   result
+                   (begin (set! result-ready? #t)
+                          (set! result x)
+                          result))))))))
+
+Rationale:   A promise may refer to its own value, as in the last
+example above. Forcing such a promise may cause the promise to be
+forced a second time before the value of the first force has been
+computed. This complicates the definition of make-promise.
+
+Various extensions to this semantics of delay and force are supported
+in some implementations:
+
+*   Calling force on an object that is not a promise may simply return
+    the object.
+
+*   It may be the case that there is no means by which a promise can be
+    operationally distinguished from its forced value. That is,
+    expressions like the following may evaluate to either #t or to #f,
+    depending on the implementation:
+
+    (eqv? (delay 1) 1)                  ===>  unspecified
+    (pair? (delay (cons 1 2)))          ===>  unspecified
+
+*   Some implementations may implement "implicit forcing," where the
+    value of a promise is forced by primitive procedures like cdr and
+    +:
+
+    (+ (delay (* 3 7)) 13)          ===>  34
+
+<procedure>(call-with-current-continuation proc)</procedure><br>
+
+Proc must be a procedure of one argument. The procedure
+call-with-current-continuation packages up the current continuation
+(see the rationale below) as an "escape procedure" and passes it as
+an argument to proc. The escape procedure is a Scheme procedure that,
+if it is later called, will abandon whatever continuation is in effect
+at that later time and will instead use the continuation that was in
+effect when the escape procedure was created. Calling the escape
+procedure may cause the invocation of before and after thunks installed
+using dynamic-wind.
+
+The escape procedure accepts the same number of arguments as the
+continuation to the original call to call-with-current-continuation.
+Except for continuations created by the call-with-values procedure, all
+continuations take exactly one value. The effect of passing no value or
+more than one value to continuations that were not created by
+call-with-values is unspecified.
+
+The escape procedure that is passed to proc has unlimited extent just
+like any other procedure in Scheme. It may be stored in variables or
+data structures and may be called as many times as desired.
+
+The following examples show only the most common ways in which
+call-with-current-continuation is used. If all real uses were as simple
+as these examples, there would be no need for a procedure with the
+power of call-with-current-continuation.
+
+ (call-with-current-continuation
+   (lambda (exit)
+     (for-each (lambda (x)
+                 (if (negative? x)
+                     (exit x)))
+               '(54 0 37 -3 245 19))
+     #t))                                ===>  -3
+ 
+ (define list-length
+   (lambda (obj)
+     (call-with-current-continuation
+       (lambda (return)
+         (letrec ((r
+                   (lambda (obj)
+                     (cond ((null? obj) 0)
+                           ((pair? obj)
+                            (+ (r (cdr obj)) 1))
+                           (else (return #f))))))
+           (r obj))))))
+ 
+ (list-length '(1 2 3 4))                    ===>  4
+ 
+ (list-length '(a b . c))                    ===>  #f
+
+Rationale:
+
+A common use of call-with-current-continuation is for structured,
+non-local exits from loops or procedure bodies, but in fact
+call-with-current-continuation is extremely useful for implementing
+a wide variety of advanced control structures.
+
+Whenever a Scheme expression is evaluated there is a continuation
+wanting the result of the expression. The continuation represents
+an entire (default) future for the computation. If the expression
+is evaluated at top level, for example, then the continuation might
+take the result, print it on the screen, prompt for the next input,
+evaluate it, and so on forever. Most of the time the continuation
+includes actions specified by user code, as in a continuation that
+will take the result, multiply it by the value stored in a local
+variable, add seven, and give the answer to the top level
+continuation to be printed. Normally these ubiquitous continuations
+are hidden behind the scenes and programmers do not think much
+about them. On rare occasions, however, a programmer may need to
+deal with continuations explicitly. Call-with-current-continuation
+allows Scheme programmers to do that by creating a procedure that
+acts just like the current continuation.
+
+Most programming languages incorporate one or more special-purpose
+escape constructs with names like exit, return, or even goto. In
+1965, however, Peter Landin [16] invented a general purpose escape
+operator called the J-operator. John Reynolds [24] described a
+simpler but equally powerful construct in 1972. The catch special
+form described by Sussman and Steele in the 1975 report on Scheme
+is exactly the same as Reynolds's construct, though its name came
+from a less general construct in MacLisp. Several Scheme
+implementors noticed that the full power of the catch construct
+could be provided by a procedure instead of by a special syntactic
+construct, and the name call-with-current-continuation was coined
+in 1982. This name is descriptive, but opinions differ on the
+merits of such a long name, and some people use the name call/cc
+instead.
+
+<procedure>(values obj ...)</procedure><br>
+
+Delivers all of its arguments to its continuation. Except for
+continuations created by the call-with-values procedure, all
+continuations take exactly one value. Values might be defined as
+follows:
+
+ (define (values . things)
+   (call-with-current-continuation 
+     (lambda (cont) (apply cont things))))
+
+<procedure>(call-with-values producer consumer)</procedure><br>
+
+Calls its producer argument with no values and a continuation that,
+when passed some values, calls the consumer procedure with those values
+as arguments. The continuation for the call to consumer is the
+continuation of the call to call-with-values.
+
+ (call-with-values (lambda () (values 4 5))
+                   (lambda (a b) b))
+                                                            ===>  5
+ 
+ (call-with-values * -)                                     ===>  -1
+
+<procedure>(dynamic-wind before thunk after)</procedure><br>
+
+Calls thunk without arguments, returning the result(s) of this call.
+Before and after are called, also without arguments, as required by the
+following rules (note that in the absence of calls to continuations
+captured using call-with-current-continuation the three arguments are
+called once each, in order). Before is called whenever execution enters
+the dynamic extent of the call to thunk and after is called whenever it
+exits that dynamic extent. The dynamic extent of a procedure call is
+the period between when the call is initiated and when it returns. In
+Scheme, because of call-with-current-continuation, the dynamic extent
+of a call may not be a single, connected time period. It is defined as
+follows:
+
+*   The dynamic extent is entered when execution of the body of the
+    called procedure begins.
+
+*   The dynamic extent is also entered when execution is not within the
+    dynamic extent and a continuation is invoked that was captured
+    (using call-with-current-continuation) during the dynamic extent.
+
+*   It is exited when the called procedure returns.
+
+*   It is also exited when execution is within the dynamic extent and a
+    continuation is invoked that was captured while not within the
+    dynamic extent.
+
+If a second call to dynamic-wind occurs within the dynamic extent of
+the call to thunk and then a continuation is invoked in such a way that
+the afters from these two invocations of dynamic-wind are both to be
+called, then the after associated with the second (inner) call to
+dynamic-wind is called first.
+
+If a second call to dynamic-wind occurs within the dynamic extent of
+the call to thunk and then a continuation is invoked in such a way that
+the befores from these two invocations of dynamic-wind are both to be
+called, then the before associated with the first (outer) call to
+dynamic-wind is called first.
+
+If invoking a continuation requires calling the before from one call to
+dynamic-wind and the after from another, then the after is called
+first.
+
+The effect of using a captured continuation to enter or exit the
+dynamic extent of a call to before or after is undefined.
+
+ (let ((path '())
+       (c #f))
+   (let ((add (lambda (s)
+                (set! path (cons s path)))))
+     (dynamic-wind
+       (lambda () (add 'connect))
+       (lambda ()
+         (add (call-with-current-continuation
+                (lambda (c0)
+                  (set! c c0)
+                  'talk1))))
+       (lambda () (add 'disconnect)))
+     (if (< (length path) 4)
+         (c 'talk2)
+         (reverse path))))
+ 
+                 ===> (connect talk1 disconnect
+                       connect talk2 disconnect)
+
+=== Eval
+
+<procedure>(eval expression environment-specifier)</procedure><br>
+
+Evaluates expression in the specified environment and returns its
+value. Expression must be a valid Scheme expression represented as
+data, and environment-specifier must be a value returned by one of the
+three procedures described below. Implementations may extend eval to
+allow non-expression programs (definitions) as the first argument and
+to allow other values as environments, with the restriction that eval
+is not allowed to create new bindings in the environments associated
+with null-environment or scheme-report-environment.
+
+ (eval '(* 7 3) (scheme-report-environment 5))
+                                                            ===>  21
+ 
+ (let ((f (eval '(lambda (f x) (f x x))
+                (null-environment 5))))
+   (f + 10))
+                                                            ===>  20
+
+<procedure>(scheme-report-environment version)</procedure><br>
+<procedure>(null-environment version)</procedure><br>
+
+Version must be the exact integer 5, corresponding to this revision of
+the Scheme report (the Revised^5 Report on Scheme).
+Scheme-report-environment returns a specifier for an environment that
+is empty except for all bindings defined in this report that are either
+required or both optional and supported by the implementation.
+Null-environment returns a specifier for an environment that is empty
+except for the (syntactic) bindings for all syntactic keywords defined
+in this report that are either required or both optional and supported
+by the implementation.
+
+Other values of version can be used to specify environments matching
+past revisions of this report, but their support is not required. An
+implementation will signal an error if version is neither 5 nor another
+value supported by the implementation.
+
+The effect of assigning (through the use of eval) a variable bound in a
+scheme-report-environment (for example car) is unspecified. Thus the
+environments specified by scheme-report-environment may be immutable.
+
+<procedure>(interaction-environment)</procedure><br>
+
+This procedure returns a specifier for the environment that contains
+implementation-defined bindings, typically a superset of those listed
+in the report. The intent is that this procedure will return the
+environment in which the implementation would evaluate expressions
+dynamically typed by the user.
+
+=== Input and output
+
+==== Ports
+
+Ports represent input and output devices. To Scheme, an input port is a
+Scheme object that can deliver characters upon command, while an output
+port is a Scheme object that can accept characters.
+
+<procedure>(call-with-input-file string proc)</procedure><br>
+<procedure>(call-with-output-file string proc)</procedure><br>
+
+String should be a string naming a file, and proc should be a procedure
+that accepts one argument. For call-with-input-file, the file should
+already exist; for call-with-output-file, the effect is unspecified if
+the file already exists. These procedures call proc with one argument:
+the port obtained by opening the named file for input or output. If the
+file cannot be opened, an error is signalled. If proc returns, then the
+port is closed automatically and the value(s) yielded by the proc is
+(are) returned. If proc does not return, then the port will not be
+closed automatically unless it is possible to prove that the port will
+never again be used for a read or write operation.
+
+Rationale:   Because Scheme's escape procedures have unlimited
+extent, it is possible to escape from the current continuation but
+later to escape back in. If implementations were permitted to close
+the port on any escape from the current continuation, then it would
+be impossible to write portable code using both
+call-with-current-continuation and call-with-input-file or
+call-with-output-file.
+
+<procedure>(input-port? obj)</procedure><br>
+<procedure>(output-port? obj)</procedure><br>
+
+Returns #t if obj is an input port or output port respectively,
+otherwise returns #f.
+
+<procedure>(current-input-port)</procedure><br>
+<procedure>(current-output-port)</procedure><br>
+
+Returns the current default input or output port.
+
+<procedure>(with-input-from-file string thunk)</procedure><br>
+<procedure>(with-output-to-file string thunk)</procedure><br>
+
+String should be a string naming a file, and proc should be a procedure
+of no arguments. For with-input-from-file, the file should already
+exist; for with-output-to-file, the effect is unspecified if the file
+already exists. The file is opened for input or output, an input or
+output port connected to it is made the default value returned by
+current-input-port or current-output-port (and is used by (read),
+(write obj), and so forth), and the thunk is called with no arguments.
+When the thunk returns, the port is closed and the previous default is
+restored. With-input-from-file and with-output-to-file return(s) the
+value(s) yielded by thunk. If an escape procedure is used to escape
+from the continuation of these procedures, their behavior is
+implementation dependent.
+
+<procedure>(open-input-file filename)</procedure><br>
+
+Takes a string naming an existing file and returns an input port
+capable of delivering characters from the file. If the file cannot be
+opened, an error is signalled.
+
+<procedure>(open-output-file filename)</procedure><br>
+
+Takes a string naming an output file to be created and returns an
+output port capable of writing characters to a new file by that name.
+If the file cannot be opened, an error is signalled. If a file with the
+given name already exists, the effect is unspecified.
+
+<procedure>(close-input-port port)</procedure><br>
+<procedure>(close-output-port port)</procedure><br>
+
+Closes the file associated with port, rendering the port incapable of
+delivering or accepting characters. These routines have no effect if
+the file has already been closed. The value returned is unspecified.
+
+==== Input
+
+<procedure>(read)</procedure><br>
+<procedure>(read port)</procedure><br>
+
+Read converts external representations of Scheme objects into the
+objects themselves. That is, it is a parser for the nonterminal <datum>
+(see sections 7.1.2 and 6.3.2). Read returns the next object parsable
+from the given input port, updating port to point to the first
+character past the end of the external representation of the object.
+
+If an end of file is encountered in the input before any characters are
+found that can begin an object, then an end of file object is returned.
+The port remains open, and further attempts to read will also return an
+end of file object. If an end of file is encountered after the
+beginning of an object's external representation, but the external
+representation is incomplete and therefore not parsable, an error is
+signalled.
+
+The port argument may be omitted, in which case it defaults to the
+value returned by current-input-port. It is an error to read from a
+closed port.
+
+<procedure>(read-char)</procedure><br>
+<procedure>(read-char port)</procedure><br>
+
+Returns the next character available from the input port, updating the
+port to point to the following character. If no more characters are
+available, an end of file object is returned. Port may be omitted, in
+which case it defaults to the value returned by current-input-port.
+
+<procedure>(peek-char)</procedure><br>
+<procedure>(peek-char port)</procedure><br>
+
+Returns the next character available from the input port, without
+updating the port to point to the following character. If no more
+characters are available, an end of file object is returned. Port may
+be omitted, in which case it defaults to the value returned by
+current-input-port.
+
+Note:   The value returned by a call to peek-char is the same as
+the value that would have been returned by a call to read-char with
+the same port. The only difference is that the very next call to
+read-char or peek-char on that port will return the value returned
+by the preceding call to peek-char. In particular, a call to
+peek-char on an interactive port will hang waiting for input
+whenever a call to read-char would have hung.
+
+<procedure>(eof-object? obj)</procedure><br>
+
+Returns #t if obj is an end of file object, otherwise returns #f. The
+precise set of end of file objects will vary among implementations, but
+in any case no end of file object will ever be an object that can be
+read in using read.
+
+<procedure>(char-ready?)</procedure><br>
+<procedure>(char-ready? port)</procedure><br>
+
+Returns #t if a character is ready on the input port and returns #f
+otherwise. If char-ready returns #t then the next read-char operation
+on the given port is guaranteed not to hang. If the port is at end of
+file then char-ready? returns #t. Port may be omitted, in which case it
+defaults to the value returned by current-input-port.
+
+Rationale:   Char-ready? exists to make it possible for a program
+to accept characters from interactive ports without getting stuck
+waiting for input. Any input editors associated with such ports
+must ensure that characters whose existence has been asserted by
+char-ready? cannot be rubbed out. If char-ready? were to return #f
+at end of file, a port at end of file would be indistinguishable
+from an interactive port that has no ready characters.
+
+==== Output
+
+<procedure>(write obj)</procedure><br>
+<procedure>(write obj port)</procedure><br>
+
+Writes a written representation of obj to the given port. Strings that
+appear in the written representation are enclosed in doublequotes, and
+within those strings backslash and doublequote characters are escaped
+by backslashes. Character objects are written using the #\ notation.
+Write returns an unspecified value. The port argument may be omitted,
+in which case it defaults to the value returned by current-output-port.
+
+<procedure>(display obj)</procedure><br>
+<procedure>(display obj port)</procedure><br>
+
+Writes a representation of obj to the given port. Strings that appear
+in the written representation are not enclosed in doublequotes, and no
+characters are escaped within those strings. Character objects appear
+in the representation as if written by write-char instead of by write.
+Display returns an unspecified value. The port argument may be omitted,
+in which case it defaults to the value returned by current-output-port.
+
+Rationale:   Write is intended for producing machine-readable
+output and display is for producing human-readable output.
+Implementations that allow "slashification" within symbols will
+probably want write but not display to slashify funny characters in
+symbols.
+
+<procedure>(newline)</procedure><br>
+<procedure>(newline port)</procedure><br>
+
+Writes an end of line to port. Exactly how this is done differs from
+one operating system to another. Returns an unspecified value. The port
+argument may be omitted, in which case it defaults to the value
+returned by current-output-port.
+
+<procedure>(write-char char)</procedure><br>
+<procedure>(write-char char port)</procedure><br>
+
+Writes the character char (not an external representation of the
+character) to the given port and returns an unspecified value. The port
+argument may be omitted, in which case it defaults to the value
+returned by current-output-port.
+
+==== System interface
+
+Questions of system interface generally fall outside of the domain of
+this report. However, the following operations are important enough to
+deserve description here.
+
+<procedure>(load filename)</procedure><br>
+
+Filename should be a string naming an existing file containing Scheme
+source code. The load procedure reads expressions and definitions from
+the file and evaluates them sequentially. It is unspecified whether the
+results of the expressions are printed. The load procedure does not
+affect the values returned by current-input-port and
+current-output-port. Load returns an unspecified value.
+
+Rationale:   For portability, load must operate on source files.
+Its operation on other kinds of files necessarily varies among
+implementations.
+
+<procedure>(transcript-on filename)</procedure><br>
+<procedure>(transcript-off)</procedure><br>
+
+(These procedures are not implemented in Chicken.)
+
+Filename must be a string naming an output file to be created. The
+effect of transcript-on is to open the named file for output, and to
+cause a transcript of subsequent interaction between the user and the
+Scheme system to be written to the file. The transcript is ended by a
+call to transcript-off, which closes the transcript file. Only one
+transcript may be in progress at any time, though some implementations
+may relax this restriction. The values returned by these procedures are
+unspecified.
+
-- 
1.6.5.2


From a4d5e7089fe1d919e795a904e22b4e65b41e744c Mon Sep 17 00:00:00 2001
Message-Id: <a4d5e7089fe1d919e795a904e22b4e65b41e744c.1260078974.git.zbigniewsz@gmail.com>
In-Reply-To: <cover.1260078974.git.zbigniewsz@gmail.com>
References: <cover.1260078974.git.zbigniewsz@gmail.com>
From: zbigniew <zbigniewsz@gmail.com>
Date: Sat, 5 Dec 2009 23:37:11 -0600
Subject: Sync changes from wiki manual to core: SVN 16559-16579 (SRFI-1 import)
Status: O


Signed-off-by: zbigniew <zbigniewsz@gmail.com>
---
 manual/Unit srfi-1 | 1354 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 1349 insertions(+), 5 deletions(-)

diff --git a/manual/Unit srfi-1 b/manual/Unit srfi-1
index 6881a6d..b601f73 100644
--- a/manual/Unit srfi-1	
+++ b/manual/Unit srfi-1	
@@ -2,10 +2,1354 @@
 
 == Unit srfi-1
 
-List library, see the documentation for
-[[http://srfi.schemers.org/srfi-1/srfi-1.html|SRFI-1]]
+SRFI 1 (List Library) procedures.   For more information, see the
+[[http://srfi.schemers.org/srfi-1/srfi-1.html|SRFI 1]] document.
 
----
-Previous: [[Unit regex]]
+[[toc:]]
+=== Constructors
 
-Next: [[Unit srfi-4]]
+<procedure>(xcons d a) -> pair</procedure><br>
+
+ (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."
+
+<procedure>(cons* elt[1] elt[2] ...) -> object</procedure><br>
+
+Like list, but the last argument provides the tail of the
+constructed list, returning
+ (cons elt[1] (cons elt[2] (cons ... elt[n])))
+
+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
+
+<procedure>(make-list n [fill]) -> list</procedure><br>
+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)
+
+<procedure>(list-tabulate n init-proc) -> list</procedure><br>
+
+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)
+
+<procedure>(list-copy flist) -> flist</procedure><br>
+
+Copies the spine of the argument.
+
+<procedure>(circular-list elt[1] elt[2] ...) -> list</procedure><br>
+
+Constructs a circular list of the elements.
+
+ (circular-list 'z 'q) => (z q z q z q ...)
+
+<procedure>(iota count [start step]) -> list</procedure><br>
+
+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.
+
+<procedure>(proper-list? x) -> boolean</procedure><br>
+
+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))
+
+<procedure>(circular-list? x) -> boolean</procedure><br>
+
+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))
+
+<procedure>(dotted-list? x) -> boolean</procedure><br>
+
+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))
+
+<procedure>(not-pair? x) -> boolean</procedure><br>
+
+ (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.
+
+<procedure>(list= elt= list[1] ...) -> boolean</procedure><br>
+
+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 list
+[i], then its second argument is from list[i+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 list[i] is compared to list[i+1] (as
+opposed, for example, to comparing list[1] to every list[i], 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
+
+<procedure>(first   pair) -> object</procedure><br>
+<procedure>(second  pair) -> object</procedure><br>
+<procedure>(third   pair) -> object</procedure><br>
+<procedure>(fourth  pair) -> object</procedure><br>
+<procedure>(fifth   pair) -> object</procedure><br>
+<procedure>(sixth   pair) -> object</procedure><br>
+<procedure>(seventh pair) -> object</procedure><br>
+<procedure>(eighth  pair) -> object</procedure><br>
+<procedure>(ninth   pair) -> object</procedure><br>
+<procedure>(tenth   pair) -> object</procedure><br>
+
+Synonyms for car, cadr, caddr, ...
+
+ (third '(a b c d e)) => c
+
+<procedure>(car+cdr pair) -> [x y]</procedure><br>
+
+The fundamental pair deconstructor:
+
+ (lambda (p) (values (car p) (cdr p)))
+
+This can, of course, be implemented more efficiently by a compiler.
+
+<procedure>(take x i) -> list</procedure><br>
+<procedure>(drop x i) -> object</procedure><br>
+
+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)).
+
+<procedure>(take-right flist i) -> object</procedure><br>
+<procedure>(drop-right flist i) -> list</procedure><br>
+
+take-right returns the last i elements of flist.
+drop-right returns all but the last i elements of flist.
+
+ (take-right '(a b c d e) 2) => (d e)
+ (drop-right '(a b c d e) 2) => (a b c)
+
+The returned list may share a common tail with the argument list.
+
+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).
+
+<procedure>(take! x i) -> list</procedure><br>
+<procedure>(drop-right! flist i) -> list</procedure><br>
+
+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)
+
+<procedure>(split-at  x i) -> [list object]</procedure><br>
+<procedure>(split-at! x i) -> [list object]</procedure><br>
+
+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)
+
+<procedure>(last pair) -> object</procedure><br>
+<procedure>(last-pair pair) -> pair</procedure><br>
+
+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)
+
+=== Miscellaneous
+
+<procedure>(length  list) -> integer</procedure><br>
+<procedure>(length+ clist) -> integer or #f</procedure><br>
+
+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.
+
+<procedure>(append! list[1] ...) -> list</procedure><br>
+
+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.
+
+<procedure>(concatenate  list-of-lists) -> value</procedure><br>
+<procedure>(concatenate! list-of-lists) -> value</procedure><br>
+
+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.
+
+<procedure>(reverse! list) -> list</procedure><br>
+
+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.
+
+<procedure>(append-reverse  rev-head tail) -> list</procedure><br>
+<procedure>(append-reverse! rev-head tail) -> list</procedure><br>
+
+append-reverse returns (append (reverse rev-head) tail). It is
+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.
+
+<procedure>(zip clist[1] clist[2] ...) -> list</procedure><br>
+
+ (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))
+
+<procedure>(unzip1 list) -> list</procedure><br>
+<procedure>(unzip2 list) -> [list list]</procedure><br>
+<procedure>(unzip3 list) -> [list list list]</procedure><br>
+<procedure>(unzip4 list) -> [list list list list]</procedure><br>
+<procedure>(unzip5 list) -> [list list list list list]</procedure><br>
+
+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)
+
+<procedure>(count pred clist[1] clist[2]) -> integer</procedure><br>
+
+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
+
+<procedure>(fold kons knil clist[1] clist[2] ...) -> value</procedure><br>
+
+The fundamental list iterator.
+
+First, consider the single list-parameter case. If 
+clist[1] = (e[1] e[2] ... e[n]), then this procedure returns
+
+ (kons e[n] ... (kons e[2] (kons e[1] 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.
+
+<procedure>(fold-right kons knil clist[1] clist[2] ...) -> value</procedure><br>
+
+The fundamental list recursion operator.
+
+First, consider the single list-parameter case. If 
+clist[1] = (e[1] e[2] ... e[n]), then this procedure returns
+
+ (kons e[1] (kons e[2] ... (kons e[n] 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.
+
+<procedure>(pair-fold kons knil clist[1] clist[2] ...) -> value</procedure><br>
+
+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.
+
+<procedure>(pair-fold-right kons knil clist[1] clist[2] ...) -> value</procedure><br>
+
+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.
+
+<procedure>(reduce f ridentity list) -> value</procedure><br>
+
+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 a 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)
+
+<procedure>(reduce-right f ridentity list) -> value</procedure><br>
+
+reduce-right is the fold-right variant of reduce. It obeys the
+following definition:
+
+ (reduce-right f ridentity '()) = ridentity
+ (reduce-right f ridentity '(e[1])) = (f e[1] ridentity) = e[1]
+ (reduce-right f ridentity '(e[1] e[2] ...)) =
+ (f e[1] (reduce f ridentity (e[2] ...)))
+
+...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)
+
+<procedure>(unfold p f g seed [tail-gen]) -> list</procedure><br>
+
+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:
+
+ ;; List of squares: 1^2 ... 10^2
+ (unfold (lambda (x) (> x 10))
+    (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."
+
+<procedure>(unfold-right p f g seed [tail]) -> list</procedure><br>
+
+unfold-right 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:
+
+ ;; List of squares: 1^2 ... 10^2
+ (unfold-right zero?
+          (lambda (x) (* x x))
+          (lambda (x) (- x 1))
+          10)
+ 
+ ;; Reverse a proper list.
+ (unfold-right null-list? car cdr lis)
+ 
+ ;; 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.
+
+<procedure>(map proc clist[1] clist[2] ...) -> list</procedure><br>
+
+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)
+
+<procedure>(for-each proc clist[1] clist[2] ...) -> unspecified</procedure><br>
+
+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.
+
+<procedure>(append-map  f clist[1] clist[2] ...) -> value</procedure><br>
+<procedure>(append-map! f clist[1] clist[2] ...) -> value</procedure><br>
+
+Equivalent to
+ (apply append (map f clist[1] clist[2] ...))
+and
+ (apply append! (map f clist[1] clist[2] ...))
+
+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.
+
+<procedure>(map! f list[1] clist[2] ...) -> list</procedure><br>
+
+Linear-update variant of map -- map! is allowed, but not required,
+to alter the cons cells of list[1] 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, clist[2], clist[3], ... must
+have at least as many elements as list[1].
+
+<procedure>(map-in-order f clist[1] clist[2] ...) -> list</procedure><br>
+
+A variant of the map procedure that guarantees to apply f across
+the elements of the list[i] 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.
+
+<procedure>(pair-for-each f clist[1] clist[2] ...) -> unspecific</procedure><br>
+
+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.
+
+<procedure>(filter-map f clist[1] clist[2] ...) -> list</procedure><br>
+
+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
+
+<procedure>(filter pred list) -> list</procedure><br>
+
+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)
+
+<procedure>(partition pred list) -> [list list]</procedure><br>
+
+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)
+
+<procedure>(remove pred list) -> list</procedure><br>
+
+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)
+
+<procedure>(filter!    pred list) -> list</procedure><br>
+<procedure>(partition! pred list) -> [list list]</procedure><br>
+<procedure>(remove!    pred list) -> list</procedure><br>
+
+Linear-update variants of filter, 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
+
+<procedure>(find pred clist) -> value</procedure><br>
+
+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.
+
+<procedure>(find-tail pred clist) -> pair or false</procedure><br>
+
+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.
+
+<procedure>(take-while  pred clist) -> list</procedure><br>
+<procedure>(take-while! pred clist) -> list</procedure><br>
+
+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)
+
+<procedure>(drop-while pred clist) -> list</procedure><br>
+
+Drops the longest initial prefix of clist 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.
+
+<procedure>(span   pred clist) -> [list clist]</procedure><br>
+<procedure>(span!  pred list ) -> [list list]</procedure><br>
+<procedure>(break  pred clist) -> [list clist]</procedure><br>
+<procedure>(break! pred list ) -> [list list]</procedure><br>
+
+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)
+
+<procedure>(any pred clist[1] clist[2] ...) -> value</procedure><br>
+
+Applies the predicate across the lists, returning true if the
+predicate returns true on any application.
+
+If there are n list arguments clist[1] ... clist[n], then pred must
+be a procedure taking n arguments and returning a boolean result.
+
+any applies pred to the first elements of the clist[i] parameters.
+If this application returns a true value, any immediately returns
+that value. Otherwise, it iterates, applying pred to the second
+elements of the clist[i] 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
+
+<procedure>(every pred clist[1] clist[2] ...) -> value</procedure><br>
+
+Applies the predicate across the lists, returning true if the
+predicate returns true on every application.
+
+If there are n list arguments clist[1] ... clist[n], then pred must
+be a procedure taking n arguments and returning a boolean result.
+
+every applies pred to the first elements of the clist[i]
+parameters. If this application returns false, every immediately
+returns false. Otherwise, it iterates, applying pred to the second
+elements of the clist[i] parameters, then the third, and so forth.
+The iteration stops when a false value is produced or one of the
+lists runs 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 clist[i] 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.
+
+<procedure>(list-index pred clist[1] clist[2] ...) -> integer or false</procedure><br>
+
+Return the index of the leftmost element that satisfies pred.
+
+If there are n list arguments clist[1] ... clist[n], then pred must
+be a function taking n arguments and returning a boolean result.
+
+list-index applies pred to the first elements of the clist[i]
+parameters. If this application returns true, list-index
+immediately returns zero. Otherwise, it iterates, applying pred to
+the second elements of the clist[i] 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
+
+<procedure>(member x list [=]) -> list</procedure><br>
+
+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 e[i] of
+list to the key x in this way:
+ (= x e[i]) ; 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
+
+<procedure>(delete  x list [=]) -> list</procedure><br>
+<procedure>(delete! x list [=]) -> list</procedure><br>
+
+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 e[i]). 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 e[i] 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.
+
+<procedure>(delete-duplicates  list [=]) -> list</procedure><br>
+<procedure>(delete-duplicates! list [=]) -> list</procedure><br>
+
+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-duplicates 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.
+
+<procedure>(assoc key alist [=]) -> pair or #f</procedure><br>
+
+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 e[i] of
+list to the key parameter in this way:
+ (= key (car e[i])) ; 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)
+
+<procedure>(alist-cons key datum alist) -> alist</procedure><br>
+
+ (lambda (key datum alist) (cons (cons key datum) alist))
+
+Cons a new alist entry mapping key -> datum onto alist.
+<procedure>(alist-copy alist) -> alist</procedure><br>
+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))
+
+<procedure>(alist-delete  key alist [=]) -> alist</procedure><br>
+<procedure>(alist-delete! key alist [=]) -> alist</procedure><br>
+
+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 k[i]
+of alist's entries to the key parameter in this way: (= key k[i]).
+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 cons cells from the alist
+parameter to construct the result.
+
+=== Set operations on 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.
+
+<procedure>(lset<= = list[1] ...) -> boolean</procedure><br>
+
+Returns true iff every list[i] is a subset of list[i+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
+
+<procedure>(lset= = list[1] list[2] ...) -> boolean</procedure><br>
+
+Returns true iff every list[i] is set-equal to list[i+1], using =
+for the element-equality procedure. "Set-equal" simply means that
+list[i] is a subset of list[i+1], and list[i+1] is a subset of list
+[i]. The = procedure's first argument is an element of list[i]; its
+second is an element of list[i+1].
+
+ (lset= eq? '(b e a) '(a e b) '(e e b a)) => #t
+ (lset= eq?) => #t               ; Trivial cases
+ (lset= eq? '(a)) => #t
+
+<procedure>(lset-adjoin = list elt[1] ...) -> list</procedure><br>
+
+Adds the elt[i] 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 elt[i] is already a
+member of list. Its first argument is an element of list; its
+second is one of the elt[i].
+
+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)
+
+<procedure>(lset-union = list[1] ...) -> list</procedure><br>
+
+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)
+ 
+ ;; Trivial cases
+ (lset-union eq?) => ()
+ (lset-union eq? '(a b c)) => (a b c)
+
+<procedure>(lset-intersection = list[1] list[2] ...) -> list</procedure><br>
+
+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 list[1] -- that is, lset-intersection essentially
+filters list[1], without disarranging element order. The result may
+share a common tail with list[1].
+
+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 list[1] for membership in every
+other list before proceeding to consider the next element of list
+[1], or it may completely intersect list[1] and list[2] before
+proceeding to list[3], 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
+
+<procedure>(lset-difference = list[1] list[2] ...) -> list</procedure><br>
+
+Returns the difference of the lists, using = for the
+element-equality procedure -- all the elements of list[1] that are
+not = to any element from one of the other list[i] parameters.
+
+The = procedure's first argument is always an element of list[1];
+its second is an element of one of the other list[i]. Elements that
+are repeated multiple times in the list[1] parameter will occur
+multiple times in the result. The order in which elements appear in
+the result is the same as they appear in list[1] -- that is,
+lset-difference essentially filters list[1], without disarranging
+element order. The result may share a common tail with list[1]. The
+dynamic order in which the applications of = are made is not
+specified. The procedure may check an element of list[1] for
+membership in every other list before proceeding to consider the
+next element of list[1], or it may completely compute the
+difference of list[1] and list[2] before proceeding to list[3], 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
+
+<procedure>(lset-xor = list[1] ...) -> list</procedure><br>
+
+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 list[i] 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), and
+* 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)
+
+<procedure>(lset-diff+intersection = list[1] list[2] ...) -> [list list]</procedure><br>
+
+Returns two values -- the difference and the intersection of the
+lists. Is equivalent to
+
+ (values (lset-difference = list[1] list[2] ...)
+    (lset-intersection = list[1]
+                         (lset-union = list[2] ...)))
+
+but can be implemented more efficiently.
+
+The = procedure's first argument is an element of list[1]; its
+second is an element of one of the other list[i].
+
+Either of the answer lists may share a common tail with list[1].
+This operation essentially partitions list[1].
+
+<procedure>(lset-union!             = list[1] ...) -> list</procedure><br>
+<procedure>(lset-intersection!      = list[1] list[2] ...) -> list</procedure><br>
+<procedure>(lset-difference!        = list[1] list[2] ...) -> list</procedure><br>
+<procedure>(lset-xor!               = list[1] ...) -> list</procedure><br>
+<procedure>(lset-diff+intersection! = list[1] list[2] ...) -> [list list]</procedure><br>
+
+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.
+
+=== Author
+
+[[http://www.ai.mit.edu/~shivers/|Olin Shivers]]
+
+== License
+
+ Copyright (C) Olin Shivers (1998, 1999). All Rights Reserved.
+ 
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+ 
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+ 
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+ CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-- 
1.6.5.2


