This file documents the MIT Scheme system.

Copyright © 1988-93 Massachusetts Institute of Technology

This material was developed by the Scheme project at the Massachusetts Institute of Technology, Department of Electrical Engineering and Computer Science.  Permission to copy this document, to redistribute it, and to use it for any purpose is granted, subject to the following restrictions and understandings.

 1. Any copy made of this document must include this copyright notice in full.

 2. Users of this document agree to make their best efforts (a) to return to the MIT Scheme project any improvements or extensions that they make, so that these may be included in future releases; and (b) to inform MIT of noteworthy uses of this document.

 3. All materials developed as a consequence of the use of this document shall duly acknowledge such use, in accordance with the usual standards of acknowledging credit in academic research.

 4. MIT has made no warrantee or representation that the contents of this document will be error-free, and MIT is under no obligation to provide any services, by way of maintenance, update, or otherwise.

 5. In conjunction with products arising from the use of this material, there shall be no use of the name of the Massachusetts Institute of Technology nor of any adaptation thereof in any advertising, promotional, or sales literature without prior written consent from MIT in each case.

Scheme is the UnCommon Lisp.  This Info file is the programmer reference document for the MIT implementation of Scheme.  It describes the facilities available for developing programs in MIT Scheme, and the ``public'' parts of the implementation.

Acknowledgements
****************

While "a cast of thousands" may be an overstatement, it is certainly the case that this document represents the work of many people.  First and foremost, thanks go to the authors of the Revised^4 Report on the Algorithmic Language Scheme, from which much of this document is derived.  Thanks also to BBN Advanced Computers Inc. for the use of parts of their Butterfly Scheme Reference, and to Margaret O'Connell for translating it from BBN's text-formatting language to ours.

Special thanks to Richard Stallman, Bob Chassell, and Brian Fox, all of the Free Software Foundation, for creating and maintaining the Texinfo formatting language in which this document is written.

This report describes research done at the Artificial Intelligence Laboratory and the Laboratory for Computer Science, both of the Massachusetts Institute of Technology.  Support for this research is provided in part by the Advanced Research Projects Agency of the Department of Defense under Office of Naval Research contract N00014-92-J-4097 and by the National Science Foundation under grant number MIP-9001651.

Overview
********

This manual is a detailed description of the MIT Scheme runtime system. It is intended to be a reference document for programmers.  It does not describe how to run Scheme or how to interact with it --- that is the subject of the MIT Scheme User's Manual.

This chapter summarizes the semantics of Scheme, briefly describes the MIT Scheme programming environment, and explains the syntactic and lexical conventions of the language.  Subsequent chapters describe special forms, numerous data abstractions, and facilities for input and output.

Throughout this manual, we will make frequent references to standard Scheme, which is the language defined by the document Revised^4 Report on the Algorithmic Language Scheme, by William Clinger, Jonathan Rees, et al., or by IEEE Std. 1178-1990, IEEE Standard for the Scheme Programming Language (in fact, several parts of this document are copied from the Revised Report).  MIT Scheme is an extension of standard Scheme.

These are the significant semantic characteristics of the Scheme language:

Variables are statically scoped
     Scheme is a statically scoped programming language, which means that each use of a variable is associated with a lexically apparent binding of that variable.  Algol is another statically scoped language.

Types are latent
     Scheme has latent types as opposed to manifest types, which means that Scheme associates types with values (or objects) rather than with variables.  Other languages with latent types (also referred to as weakly typed or dynamically typed languages) include APL, Snobol, and other dialects of Lisp.  Languages with manifest types (sometimes referred to as strongly typed or statically typed languages) include Algol 60, Pascal, and C.

Objects have unlimited extent
     All objects created during a Scheme computation, including procedures and continuations, have unlimited extent; no Scheme object is ever destroyed.  The system doesn't run out of memory because the garbage collector reclaims the storage occupied by an object when the object cannot possibly be needed by a future computation.  Other languages in which most objects have unlimited extent include APL and other Lisp dialects.

Proper tail recursion
     Scheme is properly tail-recursive, which means that iterative computation can occur in constant space, even if the iterative computation is described by a syntactically recursive procedure.  With a tail-recursive implementation, you can express iteration using the ordinary procedure-call mechanics; special iteration expressions are provided only for syntactic convenience.

Procedures are objects
     Scheme procedures are objects, which means that you can create them dynamically, store them in data structures, return them as the results of other procedures, and so on.  Other languages with such procedure objects include Common Lisp and ML.

Continuations are explicit
     In most other languages, continuations operate behind the scenes.  In Scheme, continuations are objects; you can use continuations for implementing a variety of advanced control constructs, including non-local exits, backtracking, and coroutines.

Arguments are passed by value
     Arguments to Scheme procedures are passed by value, which means that Scheme evaluates the argument expressions before the procedure gains control, whether or not the procedure needs the result of the evaluations.  ML, C, and APL are three other languages that pass arguments by value.  In languages such as SASL and Algol 60, argument expressions are not evaluated unless the values are needed by the procedure.

Scheme uses a parenthesized-list Polish notation to describe programs and (other) data.  The syntax of Scheme, like that of most Lisp dialects, provides for great expressive power, largely due to its simplicity.  An important consequence of this simplicity is the susceptibility of Scheme programs and data to uniform treatment by other Scheme programs.  As with other Lisp dialects, the read primitive parses its input; that is, it performs syntactic as well as lexical decomposition of what it reads.

Notational Conventions
======================

This section details the notational conventions used throughout the rest of this document.

Errors
------

When this manual uses the phrase ``an error will be signalled,'' it means that Scheme will call error, which normally halts execution of the program and prints an error message.

When this manual uses the phrase ``it is an error,'' it means that the specified action is not valid in Scheme, but the system may or may not signal the error.  When this manual says that something ``must be,'' it means that violating the requirement is an error.

Examples
--------

This manual gives many examples showing the evaluation of expressions. The examples have a common format that shows the expression being evaluated on the left hand side, an ``arrow'' in the middle, and the value of the expression written on the right.  For example:

     (+ 1 2)          =>  3

Sometimes the arrow and value will be moved under the expression, due to lack of space.  Occasionally we will not care what the value is, in which case both the arrow and the value are omitted.

If an example shows an evaluation that results in an error, an error message is shown, prefaced by error-->:

     (+ 1 'foo)                      error--> Illegal datum

An example that shows printed output marks it with -|:

     (begin (write 'foo) 'bar)
          -| foo
          => bar

When this manual indicates that the value returned by some expression is unspecified, it means that the expression will evaluate to some object without signalling an error, but that programs should not depend on the value in any way.

Entry Format
------------

Each description of an MIT Scheme variable, special form, or procedure begins with one or more header lines in this format:

     * CATEGORY: TEMPLATE

where CATEGORY specifies the kind of item (``variable'', ``special form'', or ``procedure''), and how the item conforms to standard Scheme, as follows:

CATEGORY
     CATEGORY, with no extra marking, indicates that the item is described in the Revised^4 Report on the Algorithmic Language Scheme.

CATEGORY+
     A plus sign after CATEGORY indicates that the item is an MIT Scheme extension.

The form of TEMPLATE is interpreted depending on CATEGORY.

Variable
     TEMPLATE consists of the variable's name.

Special Form
     TEMPLATE starts with the syntactic keyword of the special form, followed by a description of the special form's syntax.  The description is written using the following conventions.

     Named components are italicized in the printed manual, and uppercase in the Info file.  ``Noise'' keywords, such as the else keyword in the cond special form, are set in a fixed width font in the printed manual; in the Info file they are not distinguished. Parentheses indicate themselves.

     A horizontal ellipsis (...) is describes repeated components. Specifically,

          THING ...

     indicates zero or more occurrences of THING, while

          THING THING ...

     indicates one or more occurrences of THING.

     Brackets, [ ], enclose optional components.

     Several special forms (e.g. lambda) have an internal component consisting of a series of expressions; usually these expressions are evaluated sequentially under conditions that are specified in the description of the special form.  This sequence of expressions is commonly referred to as the body of the special form.

Procedure
     TEMPLATE starts with the name of the variable to which the procedure is bound, followed by a description of the procedure's arguments.  The arguments are described using ``lambda list'' notation (see Lambda Expressions), except that brackets are used to denote optional arguments, and ellipses are used to denote ``rest'' arguments.

     The names of the procedure's arguments are italicized in the printed manual, and uppercase in the Info file.

     When an argument names a Scheme data type, it indicates that the argument must be that type of data object.  For example,

          * procedure: cdr PAIR

     indicates that the standard Scheme procedure cdr takes one argument, which must be a pair.

     Many procedures signal an error when an argument is of the wrong type; usually this error is a condition of type condition-type:wrong-type-argument.

     In addition to the standard data-type names (PAIR, LIST, BOOLEAN, STRING, etc.), the following names as arguments also imply type restrictions:

       * OBJECT: any object

       * THUNK: a procedure of no arguments

       * X, Y: real numbers

       * Q, N: integers

       * K: an exact non-negative integer

Some examples:

     * procedure: list OBJECT ...

indicates that the standard Scheme procedure list takes zero or more arguments, each of which may be any Scheme object.

     * procedure: write-char CHAR [OUTPUT-PORT]

indicates that the standard Scheme procedure write-char must be called with a character, CHAR, and may also be called with a character and an output port.

Scheme Concepts
===============

Variable Bindings
-----------------

Any identifier that is not a syntactic keyword may be used as a variable (see Identifiers).  A variable may name a location where a value can be stored.  A variable that does so is said to be bound to the location.  The value stored in the location to which a variable is bound is called the variable's value.  (The variable is sometimes said to name the value or to be bound to the value.)

A variable may be bound but still not have a value; such a variable is said to be unassigned.  Referencing an unassigned variable is an error.  When this error is signalled, it is a condition of type condition-type:unassigned-variable; sometimes the compiler does not generate code to signal the error.  Unassigned variables are useful only in combination with side effects (see Assignments).

Environment Concepts
--------------------

An environment is a set of variable bindings.  If an environment has no binding for a variable, that variable is said to be unbound in that environment.  Referencing an unbound variable signals a condition of type condition-type:unbound-variable.

A new environment can be created by extending an existing environment with a set of new bindings.  Note that ``extending an environment'' does not modify the environment; rather, it creates a new environment that contains the new bindings and the old ones.  The new bindings shadow the old ones; that is, if an environment that contains a binding for x is extended with a new binding for x, then only the new binding is seen when x is looked up in the extended environment.  Sometimes we say that the original environment is the parent of the new one, or that the new environment is a child of the old one, or that the new environment inherits the bindings in the old one.

Procedure calls extend an environment, as do let, let*, letrec, and do expressions.  Internal definitions (see Internal Definitions) also extend an environment.  (Actually, all the constructs that extend environments can be expressed in terms of procedure calls, so there is really just one fundamental mechanism for environment extension.) A top-level definition (see Top-Level Definitions) may add a binding to an existing environment.

Initial and Current Environments
--------------------------------

MIT Scheme provides an initial environment that contains all of the variable bindings described in this manual.  Most environments are ultimately extensions of this initial environment.  In Scheme, the environment in which your programs execute is actually a child (extension) of the environment containing the system's bindings.  Thus, system names are visible to your programs, but your names do not interfere with system programs.

The environment in effect at some point in a program is called the current environment at that point.  In particular, every REP loop has a current environment.  (REP stands for ``read-eval-print''; the REP loop is the Scheme program that reads your input, evaluates it, and prints the result.)  The environment of the top-level REP loop (the one you are in when Scheme starts up) starts as user-initial-environment, although it can be changed by the ge procedure.  When a new REP loop is created, its environment is determined by the program that creates it.

Static Scoping
--------------

Scheme is a statically scoped language with block structure.  In this respect, it is like Algol and Pascal, and unlike most other dialects of Lisp except for Common Lisp.

The fact that Scheme is statically scoped (rather than dynamically bound) means that the environment that is extended (and becomes current) when a procedure is called is the environment in which the procedure was created (i.e. in which the procedure's defining lambda expression was evaluated), not the environment in which the procedure is called.  Because all the other Scheme binding expressions can be expressed in terms of procedures, this determines how all bindings behave.

Consider the following definitions, made at the top-level REP loop (in the initial environment):

     (define x 1)
     (define (f x) (g 2))
     (define (g y) (+ x y))
     (f 5)                                       =>  3 ; not 7

Here f and g are bound to procedures created in the initial environment.  Because Scheme is statically scoped, the call to g from f extends the initial environment (the one in which g was created) with a binding of y to 2.  In this extended environment, y is 2 and x is 1. (In a dynamically bound Lisp, the call to g would extend the environment in effect during the call to f, in which x is bound to 5 by the call to f, and the answer would be 7.)

Note that with static scoping, you can tell what binding a variable reference refers to just from looking at the text of the program; the referenced binding cannot depend on how the program is used.  That is, the nesting of environments (their parent-child relationship) corresponds to the nesting of binding expressions in program text. (Because of this connection to the text of the program, static scoping is also called lexical scoping.)  For each place where a variable is bound in a program there is a corresponding region of the program text within which the binding is effective.  For example, the region of a binding established by a lambda expression is the entire body of the lambda expression.  The documentation of each binding expression explains what the region of the bindings it makes is. A use of a variable (that is, a reference to or assignment of a variable) refers to the innermost binding of that variable whose region contains the variable use.  If there is no such region, the use refers to the binding of the variable in the global environment (which is an ancestor of all other environments, and can be thought of as a region in which all your programs are contained).

True and False
--------------

In Scheme, the boolean values true and false are denoted by #t and #f.  However, any Scheme value can be treated as a boolean for the purpose of a conditional test.  This manual uses the word true to refer to any Scheme value that counts as true, and the word false to refer to any Scheme value that counts as false.  In conditional tests, all values count as true except for #f, which counts as false (see Conditionals).

Implementation note: In MIT Scheme, #f and the empty list are the same object, and the printed representation of #f is always ().  As this contradicts the Scheme standard, MIT Scheme will soon be changed to make #f and the empty list different objects.

External Representations
------------------------

An important concept in Scheme is that of the external representation of an object as a sequence of characters. For example, an external representation of the integer 28 is the sequence of characters 28, and an external representation of a list consisting of the integers 8 and 13 is the sequence of characters (8 13).

The external representation of an object is not necessarily unique.  The integer 28 also has representations #e28.000 and #x1c, and the list in the previous paragraph also has the representations ( 08 13 ) and (8 . (13 . ( ))).

Many objects have standard external representations, but some, such as procedures and circular data structures, do not have standard representations (although particular implementations may define representations for them).

An external representation may be written in a program to obtain the corresponding object (see Quoting).

External representations can also be used for input and output.  The procedure read parses external representations, and the procedure write generates them.  Together, they provide an elegant and powerful input/output facility.

Note that the sequence of characters (+ 2 6) is not an external representation of the integer 8, even though it is an expression that evaluates to the integer 8; rather, it is an external representation of a three-element list, the elements of which are the symbol + and the integers 2 and 6.  Scheme's syntax has the property that any sequence of characters that is an expression is also the external representation of some object.  This can lead to confusion, since it may not be obvious out of context whether a given sequence of characters is intended to denote data or program, but it is also a source of power, since it facilitates writing programs such as interpreters and compilers that treat programs as data or data as programs.

Disjointness of Types
---------------------

Every object satisfies at most one of the following predicates (but see True and False, for an exception):

     bit-string?     environment?    pathname?       string?
     boolean?        null?           port?           symbol?
     cell?           number?         procedure?      vector?
     char?           pair?           promise?        weak-pair?
     condition?

Storage Model
-------------

This section describes a model that can be used to understand Scheme's use of storage.

Variables and objects such as pairs, vectors, and strings implicitly denote locations or sequences of locations.  A string, for example, denotes as many locations as there are characters in the string.  (These locations need not correspond to a full machine word.)  A new value may be stored into one of these locations using the string-set! procedure, but the string continues to denote the same locations as before.

An object fetched from a location, by a variable reference or by a procedure such as car, vector-ref, or string-ref, is equivalent in the sense of eqv? to the object last stored in the location before the fetch.

Every location is marked to show whether it is in use.  No variable or object ever refers to a location that is not in use.  Whenever this document speaks of storage being allocated for a variable or object, what is meant is that an appropriate number of locations are chosen from the set of locations that are not in use, and the chosen locations are marked to indicate that they are now in use before the variable or object is made to denote them.

In many systems it is desirable for constants (i.e. the values of literal expressions) to reside in read-only memory.  To express this, it is convenient to imagine that every object that denotes locations is associated with a flag telling whether that object is mutable or immutable.  The constants and the strings returned by symbol->string are then the immutable objects, while all objects created by other procedures are mutable.  It is an error to attempt to store a new value into a location that is denoted by an immutable object.  Note that the MIT Scheme compiler takes advantage of this property to share constants, but that these constants are not immutable. Instead, two constants that are equal? may be eq? in compiled code.

Lexical Conventions
===================

This section describes Scheme's lexical conventions.

Whitespace
----------

Whitespace characters are spaces, newlines, tabs, and page breaks. Whitespace is used to improve the readability of your programs and to separate tokens from each other, when necessary.  (A token is an indivisible lexical unit such as an identifier or number.)  Whitespace is otherwise insignificant.  Whitespace may occur between any two tokens, but not within a token.  Whitespace may also occur inside a string, where it is significant.

Delimiters
----------

All whitespace characters are delimiters.  In addition, the following characters act as delimiters:

     (  )  ;  "  '  `  |

Finally, these next characters act as delimiters, despite the fact that Scheme does not define any special meaning for them:

     [  ]  {  }

For example, if the value of the variable name is "max":

     (list"Hi"name(+ 1 2))                   =>  ("Hi" "max" 3)

Identifiers
-----------

An identifier is a sequence of one or more non-delimiter characters.  Identifiers are used in several ways in Scheme programs:

  * Certain identifiers are reserved for use as syntactic keywords; they should not be used as variables (for a list of the initial syntactic keywords, see Special Form Syntax).

  * Any identifier that is not a syntactic keyword can be used as a variable.

  * When an identifier appears as a literal or within a literal, it denotes a symbol.

Scheme accepts most of the identifiers that other programming languages allow.  MIT Scheme allows all of the identifiers that standard Scheme does, plus many more.

MIT Scheme defines a potential identifier to be a sequence of non-delimiter characters that does not begin with either of the characters # or ,.  Any such sequence of characters that is not a syntactically valid number (see Numbers) is considered to be a valid identifier.  Note that, although it is legal for # and , to appear in an identifier (other than in the first character position), it is poor programming practice.

Here are some examples of identifiers:

     lambda             q
     list->vector       soup
     +                  V17a
     <=?                a34kTMNs
     the-word-recursion-has-many-meanings

Uppercase and Lowercase
-----------------------

Scheme doesn't distinguish uppercase and lowercase forms of a letter except within character and string constants; in other words, Scheme is case-insensitive.  For example, Foo is the same identifier as FOO, and #x1AB is the same number as #X1ab.  But #\a and #\A are different characters.

Naming Conventions
------------------

A predicate is a procedure that always returns a boolean value (#t or #f).  By convention, predicates usually have names that end in ?.

A mutation procedure is a procedure that alters a data structure. By convention, mutation procedures usually have names that end in !.

Comments
--------

The beginning of a comment is indicated with a semicolon (;). Scheme ignores everything on a line in which a semicolon appears, from the semicolon until the end of the line.  The entire comment, including the newline character that terminates it, is treated as whitespace.

An alternative form of comment (sometimes called an extended comment) begins with the characters #| and ends with the characters |#.  This alternative form is an MIT Scheme extension. As with ordinary comments, all of the characters in an extended comment, including the leading #| and trailing |#, are treated as whitespace.  Comments of this form may extend over multiple lines, and additionally may be nested (unlike the comments of the programming language C, which have a similar syntax).

     ;;; This is a comment about the FACT procedure.  Scheme
     ;;; ignores all of this comment.  The FACT procedure computes
     ;;; the factorial of a non-negative integer.

     #|
     This is an extended comment.
     Such comments are useful for commenting out code fragments.
     |#

     (define fact
       (lambda (n)
         (if (= n 0)                      ;This is another comment:
             1                            ;Base case: return 1
             (* n (fact (- n 1))))))

Additional Notations
--------------------

The following list describes additional notations used in Scheme. See Numbers for a description of the notations used for numbers.

+ - .
     The plus sign, minus sign, and period are used in numbers, and may also occur in an identifier.  A delimited period (not occurring within a number or identifier) is used in the notation for pairs and to indicate a ``rest'' parameter in a formal parameter list (see Lambda Expressions).

( )
     Parentheses are used for grouping and to notate lists (see Lists).

"
     The double quote delimits strings (see Strings).

\
     The backslash is used in the syntax for character constants (see Characters) and as an escape character within string constants (see Strings).

;
     The semicolon starts a comment.

'
     The single quote indicates literal data; it suppresses evaluation (see Quoting).

`
     The backquote indicates almost-constant data (see Quoting).

,
     The comma is used in conjunction with the backquote (see Quoting).

,@
     A comma followed by an at-sign is used in conjunction with the backquote (see Quoting).

#
     The sharp (or pound) sign has different uses, depending on the character that immediately follows it:

#t #f
     These character sequences denote the boolean constants (see Booleans).

#\
     This character sequence introduces a character constant (see Characters).

#(
     This character sequence introduces a vector constant (see Vectors). A close parenthesis, ), terminates a vector constant.

#e #i #b #o #d #x
     These character sequences are used in the notation for numbers (see Numbers).

#|
     This character sequence introduces an extended comment.  The comment is terminated by the sequence |#.  This notation is an MIT Scheme extension.

#!
     This character sequence is used to denote a small set of named constants.  Currently there are only two of these, #!optional and #!rest, both of which are used in the lambda special form to mark certain parameters as being ``optional'' or ``rest'' parameters. This notation is an MIT Scheme extension.

#*
     This character sequence introduces a bit string (see Bit Strings). This notation is an MIT Scheme extension.

Expressions
===========

A Scheme expression is a construct that returns a value.  An expression may be a literal, a variable reference, a special form, or a procedure call.

Literal Expressions
-------------------

Literal constants may be written by using an external representation of the data.  In general, the external representation must be quoted (see Quoting); but some external representations can be used without quotation.

     "abc"                                   =>  "abc"
     145932                                  =>  145932
     #t                                      =>  #t
     #\a                                     =>  #\a

The external representation of numeric constants, string constants, character constants, and boolean constants evaluate to the constants themselves.  Symbols, pairs, lists, and vectors require quoting.

Variable References
-------------------

An expression consisting of an identifier (see Identifiers) is a variable reference; the identifier is the name of the variable being referenced.  The value of the variable reference is the value stored in the location to which the variable is bound.  An error is signalled if the referenced variable is unbound or unassigned.

     (define x 28)
     x                                       =>  28

Special Form Syntax
-------------------

     (KEYWORD COMPONENT ...)

A parenthesized expression that starts with a syntactic keyword is a special form.  Each special form has its own syntax, which is described later in the manual.  The following list contains all of the syntactic keywords that are defined when MIT Scheme is initialized:

     access                  define-syntax           macro
     and                     delay                   make-environment
     begin                   do                      named-lambda
     bkpt                    fluid-let               or
     case                    if                      quasiquote
     cond                    in-package              quote
     cons-stream             lambda                  scode-quote
     declare                 let                     sequence
     default-object?         let*                    set!
     define                  let-syntax              the-environment
     define-integrable       letrec                  unassigned?
     define-macro            local-declare           using-syntax
     define-structure

Procedure Call Syntax
---------------------

     (OPERATOR OPERAND ...)

A procedure call is written by simply enclosing in parentheses expressions for the procedure to be called (the operator) and the arguments to be passed to it (the operands).  The OPERATOR and OPERAND expressions are evaluated and the resulting procedure is passed the resulting arguments.  See Lambda Expressions, for a more complete description of this.

Another name for the procedure call expression is combination. This word is more specific in that it always refers to the expression; ``procedure call'' sometimes refers to the process of calling a procedure.

Unlike some other dialects of Lisp, Scheme always evaluates the operator expression and the operand expressions with the same evaluation rules, and the order of evaluation is unspecified.

     (+ 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.

If the OPERATOR is a syntactic keyword, then the expression is not treated as a procedure call: it is a special form.  Thus you should not use syntactic keywords as procedure names.  If you were to bind one of these keywords to a procedure, you would have to use apply to call the procedure.  MIT Scheme signals an error when such a binding is attempted.

Special Forms
*************

A special form is an expression that follows special evaluation rules. This chapter describes the basic Scheme special forms.

Lambda Expressions
==================

 -- special form: lambda formals expression expression ...
     A lambda expression evaluates to a procedure.  The environment in effect when the lambda expression is evaluated is remembered as part of the procedure; it is called the closing environment.  When the procedure is later called with some arguments, the closing environment is extended by binding the variables in the formal parameter list to fresh locations, and the locations are filled with the arguments according to rules about to be given.  The new environment created by this process is referred to as the invocation environment.

     Once the invocation environment has been constructed, the EXPRESSIONs in the body of the lambda expression are evaluated sequentially in it.  This means that the region of the variables bound by the lambda expression is all of the EXPRESSIONs in the body.  The result of evaluating the last EXPRESSION in the body is returned as the result of the procedure call.

     FORMALS, the formal parameter list, is often referred to as a lambda list.

     The process of matching up formal parameters with arguments is somewhat involved.  There are three types of parameters, and the matching treats each in sequence:

     Required
          All of the required parameters are matched against the arguments first.  If there are fewer arguments than required parameters, an error of type condition-type:wrong-number-of-arguments is signalled; this error is also signalled if there are more arguments than required parameters and there are no further parameters.

     Optional
          Once the required parameters have all been matched, the optional parameters are matched against the remaining arguments.  If there are fewer arguments than optional parameters, the unmatched parameters are bound to special objects called default objects.  If there are more arguments than optional parameters, and there are no further parameters, an error of type condition-type:wrong-number-of-arguments is signalled.

          The predicate default-object?, which is true only of default objects, can be used to determine which optional parameters were supplied, and which were defaulted.

     Rest
          Finally, if there is a rest parameter (there can only be one), any remaining arguments are made into a list, and the list is bound to the rest parameter.  (If there are no remaining arguments, the rest parameter is bound to the empty list.)

          In Scheme, unlike some other Lisp implementations, the list to which a rest parameter is bound is always freshly allocated.  It has infinite extent and may be modified without affecting the procedure's caller.

     Specially recognized keywords divide the FORMALS parameters into these three classes.  The keywords used here are #!optional, ., and #!rest.  Note that only . is defined by standard Scheme --- the other keywords are MIT Scheme extensions. #!rest has the same meaning as . in FORMALS.

     The use of these keywords is best explained by means of examples.  The following are typical lambda lists, followed by descriptions of which parameters are required, optional, and rest.  We will use #!rest in these examples, but anywhere it appears . could be used instead.

     (a b c)
          a, b, and c are all required.  The procedure must be passed exactly three arguments.

     (a b #!optional c)
          a and b are required, c is optional.  The procedure may be passed either two or three arguments.

     (#!optional a b c)
          a, b, and c are all optional.  The procedure may be passed any number of arguments between zero and three, inclusive.

     a
     (#!rest a)
          These two examples are equivalent.  a is a rest parameter.  The procedure may be passed any number of arguments.  Note: this is the only case in which . cannot be used in place of #!rest.

     (a b #!optional c d #!rest e)
          a and b are required, c and d are optional, and e is rest.  The procedure may be passed two or more arguments.

     Some examples of lambda expressions:

          (lambda (x) (+ x x))            =>  #[compound-procedure 53]

          ((lambda (x) (+ x x)) 4)                =>  8

          (define reverse-subtract
            (lambda (x y)
              (- y x)))
          (reverse-subtract 7 10)                 =>  3

          (define foo
            (let ((x 4))
              (lambda (y) (+ x y))))
          (foo 6)                                 =>  10

 -- special form+: named-lambda formals expression expression ...
     The named-lambda special form is similar to lambda, except that the first ``required parameter'' in FORMALS is not a parameter but the name of the resulting procedure; thus FORMALS must have at least one required parameter.  This name has no semantic meaning, but is included in the external representation of the procedure, making it useful for debugging.  In MIT Scheme, lambda is implemented as named-lambda, with a special name that means ``unnamed''.

          (named-lambda (f x) (+ x x))    =>  #[compound-procedure 53 f]
          ((named-lambda (f x) (+ x x)) 4)        =>  8

Lexical Binding
===============

The three binding constructs let, let*, and letrec, give Scheme block structure.  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 evaluations and bindings are sequentially interleaved. And in a letrec expression, all the bindings are in effect while the initial values are being computed (thus allowing mutually recursive definitions).

 -- special form: let ((VARIABLE INIT) ...) expression expression ...
     The INITs are evaluated in the current environment (in some unspecified order), the VARIABLEs are bound to fresh locations holding the results, the EXPRESSIONs are evaluated sequentially in the extended environment, and the value of the last EXPRESSION is returned.  Each binding of a VARIABLE has the EXPRESSIONs as its region.

     MIT Scheme allows any of the INITs to be omitted, in which case the corresponding VARIABLEs are unassigned.

     Note that the following are equivalent:

          (let ((VARIABLE INIT) ...) EXPRESSION EXPRESSION ...)
          ((lambda (VARIABLE ...) EXPRESSION EXPRESSION ...) INIT ...)

     Some examples:

          (let ((x 2) (y 3))
            (* x y))                              =>  6

          (let ((x 2) (y 3))
            (let ((foo (lambda (z) (+ x y z)))
                  (x 7))
              (foo 4)))                           =>  9

     See Iteration, for information on ``named let''.

 -- special form: let* ((VARIABLE INIT) ...) expression expression ...
     let* is similar to let, but the bindings are performed sequentially from left to right, and the region of a binding 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.

     Note that the following are equivalent:

          (let* ((VARIABLE1 INIT1)
                 (VARIABLE2 INIT2)
                 ...
                 (VARIABLEN INITN))
             EXPRESSION
             EXPRESSION ...)

          (let ((VARIABLE1 INIT1))
            (let ((VARIABLE2 INIT2))
              ...
                (let ((VARIABLEN INITN))
                  EXPRESSION
                  EXPRESSION ...)
              ...))

     An example:

          (let ((x 2) (y 3))
            (let* ((x 7)
                   (z (+ x y)))
              (* z x)))                           =>  70

 -- special form: letrec ((VARIABLE INIT) ...) expression expression ...
     The VARIABLEs are bound to fresh locations holding unassigned values, the INITs are evaluated in the extended environment (in some unspecified order), each VARIABLE is assigned to the result of the corresponding INIT, the EXPRESSIONs are evaluated sequentially in the extended environment, and the value of the last EXPRESSION is returned.  Each binding of a VARIABLE has the entire letrec expression as its region, making it possible to define mutually recursive procedures.

     MIT Scheme allows any of the INITs to be omitted, in which case the corresponding VARIABLEs are unassigned.

          (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 shall be possible to evaluated 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 INITs are lambda or delay expressions and the restriction is satisfied automatically.

Fluid Binding
=============

 -- special form+: fluid-let ((VARIABLE INIT) ...) expression expression ...
     The INITs are evaluated in the current environment (in some unspecified order), the current values of the VARIABLEs are saved, the results are assigned to the VARIABLEs, the EXPRESSIONs are evaluated sequentially in the current environment, the VARIABLEs are restored to their original values, and the value of the last EXPRESSION is returned.

     The syntax of this special form is similar to that of let, but fluid-let temporarily rebinds existing variables.  Unlike let, fluid-let creates no new bindings; instead it assigns the values of each INIT to the binding (determined by the rules of lexical scoping) of its corresponding VARIABLE.

     MIT Scheme allows any of the INITs to be omitted, in which case the corresponding VARIABLEs are temporarily unassigned.

     An error of type condition-type:unbound-variable is signalled if any of the VARIABLEs are unbound.  However, because fluid-let operates by means of side effects, it is valid for any VARIABLE to be unassigned when the form is entered.

     Here is an example showing the difference between fluid-let and let.  First see how let affects the binding of a variable:

          (define variable #t)
          (define (access-variable) variable)
          variable                                =>  #t
          (let ((variable #f))
            (access-variable))                    =>  #t
          variable                                =>  #t

     access-variable returns #t in this case because it is defined in an environment with variable bound to #t.  fluid-let, on the other hand, temporarily reuses an existing variable:

          variable                                =>  #t
          (fluid-let ((variable #f))              ;reuses old binding
            (access-variable))                    =>  #f
          variable                                =>  #t

     The extent of a dynamic binding is defined to be the time period during which the variable contains the new value.  Normally this time period begins when the body is entered and ends when it is exited; on a sequential machine it is normally a contiguous time period.  However, because Scheme has first-class continuations, it is possible to leave the body and then reenter it, as many times as desired.  In this situation, the extent becomes non-contiguous.

     When the body is exited by invoking a continuation, the new value is saved, and the variable is set to the old value.  Then, if the body is reentered by invoking a continuation, the old value is saved, and the variable is set to the new value.  In addition, side effects to the variable that occur both inside and outside of body are preserved, even if continuations are used to jump in and out of body repeatedly.

     Here is a complicated example that shows the interaction between dynamic binding and continuations:

          (define (complicated-fluid-binding)
            (let ((variable 1)
                  (inside-continuation))
              (write-line variable)
              (call-with-current-continuation
               (lambda (outside-continuation)
                 (fluid-let ((variable 2))
                   (write-line variable)
                   (set! variable 3)
                   (call-with-current-continuation
                    (lambda (k)
                      (set! inside-continuation k)
                      (outside-continuation #t)))
                   (write-line variable)
                   (set! inside-continuation #f))))
              (write-line variable)
              (if inside-continuation
                  (begin
                    (set! variable 4)
                    (inside-continuation #f)))))

     Evaluating (complicated-fluid-binding) writes the following on the console:

          1
          2
          1
          3
          4

     Commentary: the first two values written are the initial binding of variable and its new binding after the fluid-let's body is entered.  Immediately after they are written, variable is set to 3, and then outside-continuation is invoked, causing us to exit the body.  At this point, 1 is written, demonstrating that the original value of variable has been restored, because we have left the body.  Then we set variable to 4 and reenter the body by invoking inside-continuation.  At this point, 3 is written, indicating that the side effect that previously occurred within the body has been preserved.  Finally, we exit body normally, and write 4, demonstrating that the side effect that occurred outside of the body was also preserved.

Definitions
===========

 -- special form: define variable [expression]
 -- special form: define FORMALS expression expression ...
     Definitions are valid in some but not all contexts where expressions are allowed.  Definitions may only occur at the top level of a program and at the beginning of a lambda body (that is, the body of a lambda, let, let*, letrec, fluid-let, or ``procedure define'' expression).  A definition that occurs at the top level of a program is called a top-level definition, and a definition that occurs at the beginning of a body is called an internal definition.

     In the second form of define (called ``procedure define''), the component FORMALS is identical to the component of the same name in a named-lambda expression.  In fact, these two expressions are equivalent:

          (define (NAME1 NAME2 ...)
            EXPRESSION
            EXPRESSION ...)

          (define NAME1
            (named-lambda (NAME1 NAME2 ...)
              EXPRESSION
              EXPRESSION ...))

Top-Level Definitions
---------------------

A top-level definition,

     (define VARIABLE EXPRESSION)

has essentially the same effect as this assignment expression, if VARIABLE is bound:

     (set! VARIABLE EXPRESSION)

If VARIABLE is not bound, however, define binds VARIABLE to a new location in the current environment before performing the assignment (it is an error to perform a set! on an unbound variable).  If you omit EXPRESSION, the variable becomes unassigned; an attempt to reference such a variable is an error.

     (define add3
        (lambda (x) (+ x 3)))                =>  unspecified
     (add3 3)                                =>  6

     (define first car)                      =>  unspecified
     (first '(1 2))                          =>  1

     (define bar)                            =>  unspecified
     bar                                     error--> Unassigned variable

Internal Definitions
--------------------

An internal definition is a definition that occurs at the beginning of a BODY (that is, the body of a lambda, let, let*, letrec, fluid-let, or ``procedure define'' expression), rather than at the top level of a program. The variable defined by an internal definition is local to the BODY.  That is, VARIABLE is bound rather than assigned, and the region of the binding is the entire BODY.  For example,

     (let ((x 5))
       (define foo (lambda (y) (bar x y)))
       (define bar (lambda (a b) (+ (* a b) a)))
       (foo (+ x 3)))                        =>  45

A BODY containing internal definitions can always be converted into a completely equivalent letrec expression.  For example, the let expression in the above example is equivalent to

     (let ((x 5))
       (letrec ((foo (lambda (y) (bar x y)))
                (bar (lambda (a b) (+ (* a b) a))))
         (foo (+ x 3))))

Assignments
===========

 -- special form: set! variable [expression]
     If EXPRESSION is specified, evaluates EXPRESSION and stores the resulting value in the location to which VARIABLE is bound. If EXPRESSION is omitted, VARIABLE is altered to be unassigned; a subsequent reference to such a VARIABLE is an error. In either case, the value of the set! expression is unspecified.

     VARIABLE must be bound either in some region enclosing the set! expression, or at the top level.  However, VARIABLE is permitted to be unassigned when the set! form is entered.

          (define x 2)                            =>  unspecified
          (+ x 1)                                 =>  3
          (set! x 4)                              =>  unspecified
          (+ x 1)                                 =>  5

     VARIABLE may be an access expression (see Environments).  This allows you to assign variables in an arbitrary environment.  For example,

          (define x (let ((y 0)) (the-environment)))
          (define y 'a)
          y                                       =>  a
          (access y x)                            =>  0
          (set! (access y x) 1)                   =>  unspecified
          y                                       =>  a
          (access y x)                            =>  1

Quoting
=======

This section describes the expressions that are used to modify or prevent the evaluation of objects.

 -- special form: quote datum
     (quote DATUM) evaluates to DATUM.  DATUM may be any external representation of a Scheme object (see External Representations). Use quote 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)                              =>  'a
          ''a                                     =>  'a

     Numeric constants, string constants, character constants, and boolean constants evaluate to themselves, so they don't need to be quoted.

          '"abc"                                  =>  "abc"
          "abc"                                   =>  "abc"
          '145932                                 =>  145932
          145932                                  =>  145932
          '#t                                     =>  #t
          #t                                      =>  #t
          '#\a                                    =>  #\a
          #\a                                     =>  #\a

 -- special form: quasiquote template
     ``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 TEMPLATE, the result of evaluating `TEMPLATE is equivalent (in the sense of equal?) to the result of evaluating 'TEMPLATE.  If a comma appears within the 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 shall 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.

          `(list ,(+ 1 2) 4)                           =>  (list 3 4)

          (let ((name 'a)) `(list ,name ',name))       =>  (list a '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)

          `,(+ 2 3)                                    =>  5

     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 notations `TEMPLATE and (quasiquote TEMPLATE) are identical in all respects. ,EXPRESSION is identical to (unquote EXPRESSION) and ,@EXPRESSION is identical to (unquote-splicing EXPRESSION).

          (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 a TEMPLATE in ways otherwise than as described above.

Conditionals
============

The behavior of the conditional expressions is determined by whether objects are true or false.  The conditional expressions count only #f as false.  They count everything else, including #t, pairs, symbols, numbers, strings, vectors, and procedures as true (but see True and False).

In the descriptions that follow, we say that an object has ``a true value'' or ``is true'' when the conditional expressions treat it as true, and we say that an object has ``a false value'' or ``is false'' when the conditional expressions treat it as false.

 -- special form: if predicate consequent [alternative]
     PREDICATE, CONSEQUENT, and ALTERNATIVE are expressions.  An if expression is evaluated as follows: first, PREDICATE is evaluated.  If it yields a true value, then CONSEQUENT is evaluated and its value is returned.  Otherwise ALTERNATIVE is evaluated and its value is returned.  If PREDICATE yields a false value and no ALTERNATIVE is specified, then the result of the expression is unspecified.

     An if expression evaluates either CONSEQUENT or ALTERNATIVE, never both.  Programs should not depend on the value of an if expression that has no ALTERNATIVE.

          (if (> 3 2) 'yes 'no)                   =>  yes
          (if (> 2 3) 'yes 'no)                   =>  no
          (if (> 3 2)
              (- 3 2)
              (+ 3 2))                            =>  1

 -- special form: cond clause clause ...
     Each CLAUSE has this form:

          (PREDICATE EXPRESSION ...)

     where PREDICATE is any expression.  The last CLAUSE may be an else clause, which has the form:

          (else EXPRESSION EXPRESSION ...)

     A cond expression does the following:

      1. Evaluates the PREDICATE expressions of successive CLAUSEs in order, until one of the PREDICATEs evaluates to a true value.

      2. When a PREDICATE evaluates to a true value, cond evaluates the EXPRESSIONs in the associated CLAUSE in left to right order, and returns the result of evaluating the last EXPRESSION in the CLAUSE as the result of the entire cond expression.

          If the selected CLAUSE contains only the PREDICATE and no EXPRESSIONs, cond returns the value of the PREDICATE as the result.

      3. If all PREDICATEs evaluate to false values, and there is no else clause, the result of the conditional expression is unspecified; if there is an else clause, cond evaluates its EXPRESSIONs (left to right) and returns the value of the last one.

          (cond ((> 3 2) 'greater)
                ((< 3 2) 'less))                  =>  greater

          (cond ((> 3 3) 'greater)
                ((< 3 3) 'less)
                (else 'equal))                    =>  equal

     Normally, programs should not depend on the value of a cond expression that has no else clause.  However, some Scheme programmers prefer to write cond expressions in which at least one of the PREDICATEs is always true.  In this style, the final CLAUSE is equivalent to an else clause.

     Scheme supports an alternative CLAUSE syntax:

          (PREDICATE => RECIPIENT)

     where RECIPIENT is an expression.  If PREDICATE evaluates to a true value, then RECIPIENT is evaluated.  Its value must be a procedure of one argument; this procedure is then invoked on the value of the PREDICATE.

          (cond ((assv 'b '((a 1) (b 2))) => cadr)
                (else #f))                        =>  2

 -- special form: case key clause clause ...
     KEY may be any expression.  Each CLAUSE has this form:

          ((OBJECT ...) EXPRESSION EXPRESSION ...)

     No OBJECT is evaluated, and all the OBJECTs must be distinct.  The last CLAUSE may be an else clause, which has the form:

          (else EXPRESSION EXPRESSION ...)

     A case expression does the following:

      1. Evaluates KEY and compares the result with each OBJECT.

      2. If the result of evaluating KEY is equivalent (in the sense of eqv?; see Equivalence Predicates) to an OBJECT, case evaluates the EXPRESSIONs in the corresponding CLAUSE from left to right and returns the result of evaluating the last EXPRESSION in the CLAUSE as the result of the case expression.

      3. If the result of evaluating KEY is different from every OBJECT, and if there's an else clause, case evaluates its EXPRESSIONs and returns the result of the last one as the result of the case expression.  If there's no else clause, case returns an unspecified result.  Programs should not depend on the value of a case expression that has no else clause.

     For example,

          (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

 -- special form: and expression ...
     The EXPRESSIONs are evaluated from left to right, and the value of the first EXPRESSION that evaluates to a false value 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

 -- special form: or expression ...
     The EXPRESSIONs are evaluated from left to right, and the value of the first EXPRESSION that evaluates to a true value 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)

Sequencing
==========

 -- special form: begin expression expression ...
     The EXPRESSIONs are evaluated sequentially from left to right, and the value of the last EXPRESSION is 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)))
                                          -|  4 plus 1 equals 5
                                          =>  unspecified

     Often the use of begin is unnecessary, because many special forms already support sequences of expressions (that is, they have an implicit begin).  Some of these special forms are:

          case
          cond
          define          ;``procedure define'' only
          do
          fluid-let
          lambda
          let
          let*
          letrec
          named-lambda

     The obsolete special form sequence is identical to begin. It should not be used in new code.

Iteration
=========

The iteration expressions are: ``named let'' and do. They are also binding expressions, but are more commonly referred to as iteration expressions.  Because Scheme is properly tail-recursive, you don't need to use these special forms to express iteration; you can simply use appropriately written ``recursive'' procedure calls.

 -- special form: let name ((VARIABLE INIT) ...) expression expression ...
     MIT Scheme permits a variant on the syntax of let called ``named let'' which provides a more general looping construct than do, and may also be used to express recursions.

     Named let has the same syntax and semantics as ordinary let except that NAME is bound within the EXPRESSIONs to a procedure whose formal arguments are the VARIABLEs and whose body is the EXPRESSIONs.  Thus the execution of the EXPRESSIONs may be repeated by invoking the procedure named by NAME.

     MIT Scheme allows any of the INITs to be omitted, in which case the corresponding VARIABLEs are unassigned.

     Note: the following expressions are equivalent:

          (let NAME ((VARIABLE INIT) ...)
            EXPRESSION
            EXPRESSION ...)

          ((letrec ((NAME
                     (named-lambda (NAME VARIABLE ...)
                       EXPRESSION
                       EXPRESSION ...)))
             NAME)
           INIT ...)

     Here is an example:

          (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))
                  (else
                   (loop (cdr numbers)
                         nonneg
                         (cons (car numbers) neg)))))

               =>  ((6 1 3) (-5 -2))

 -- special form: do ((VARIABLE INIT STEP) ...) (TEST EXPRESSION ...) command ...
     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 with a specified result value.

     do expressions are evaluated as follows: The INIT expressions are evaluated (in some unspecified order), the VARIABLEs are bound to fresh locations, the results of the INIT expressions are stored in the bindings of the VARIABLEs, and then the iteration phase begins.

     Each iteration begins by evaluating TEST; if the result is false, then the COMMAND expressions are evaluated in order for effect, the STEP expressions are evaluated in some unspecified order, the VARIABLEs are bound to fresh locations, the results of the STEPs are stored in the bindings of the VARIABLEs, and the next iteration begins.

     If TEST evaluates to a true value, then the EXPRESSIONs are evaluated from left to right and the value of the last EXPRESSION is returned as the value of the do expression.  If no EXPRESSIONs are present, then the value of the do expression is unspecified in standard Scheme; in MIT Scheme, the value of TEST is returned.

     The region of the binding of a VARIABLE consists of the entire do expression except for the INITs.  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

Structure Definitions
=====================

This section provides examples and describes the options and syntax of define-structure, an MIT Scheme macro that is very similar to defstruct in Common Lisp.  The differences between them are summarized at the end of this section.  For more information, see Steele's Common Lisp book.

 -- special form+: define-structure (name structure-option ...) slot-description ...
     Each SLOT-DESCRIPTION takes one of the following forms:

          SLOT-NAME
          (SLOT-NAME DEFAULT-INIT [SLOT-OPTION VALUE]*)

     The fields NAME and SLOT-NAME must both be symbols.  The field DEFAULT-INIT is an expression for the initial value of the slot.  It is evaluated each time a new instance is constructed.  If it is not specified, the initial content of the slot is undefined.  Default values are only useful with a BOA constructor with argument list or a keyword constructor (see below).

     Evaluation of a define-structure expression defines a structure descriptor and a set of procedures to manipulate instances of the structure.  These instances are represented as records by default (see Records) but may alternately be lists or vectors.  The accessors and modifiers are marked with compiler declarations so that calls to them are automatically transformed into appropriate references. Often, no options are required, so a simple call to define-structure looks like:

          (define-structure foo a b c)

     This defines a type descriptor foo, a constructor make-foo, a predicate foo?, accessors foo-a, foo-b, and foo-c, and modifiers set-foo-a!, set-foo-b!, and set-foo-c!.

     In general, if no options are specified, define-structure defines the following (using the simple call above as an example):

     type descriptor
          The name of the type descriptor is the same as the name of the structure, e.g. foo.  The type descriptor satisfies the predicate record-type?.

     constructor
          The name of the constructor is "make-" followed by the name of the structure, e.g. make-foo.  The number of arguments accepted by the constructor is the same as the number of slots; the arguments are the initial values for the slots, and the order of the arguments matches the order of the slot definitions.

     predicate
          The name of the predicate is the name of the structure followed by "?", e.g. foo?.  The predicate is a procedure of one argument, which returns #t if its argument is a record of the type defined by this structure definition, and #f otherwise.

     accessors
          For each slot, an accessor is defined.  The name of the accessor is formed by appending the name of the structure, a hyphen, and the name of the slot, e.g. foo-a.  The accessor is a procedure of one argument, which must be a record of the type defined by this structure definition.  The accessor extracts the contents of the corresponding slot in that record and returns it.

     modifiers
          For each slot, a modifier is defined.  The name of the modifier is formed by appending "set-", the name of the accessor, and "!", e.g. set-foo-a!.  The modifier is a procedure of two arguments, the first of which must be a record of the type defined by this structure definition, and the second of which may be any object. The modifier modifies the contents of the corresponding slot in that record to be that object, and returns an unspecified value.

     When options are not supplied, (NAME) may be abbreviated to NAME.  This convention holds equally for STRUCTURE-OPTIONS and SLOT-OPTIONS.  Hence, these are equivalent:

          (define-structure foo a b c)
          (define-structure (foo) (a) b (c))

     as are

          (define-structure (foo keyword-constructor) a b c)
          (define-structure (foo (keyword-constructor)) a b c)

     When specified as option values, false and nil are equivalent to #f, and true and t are equivalent to #t.

Possible SLOT-OPTIONS are:

 -- slot option: read-only value
     When given a VALUE other than #f, this specifies that no modifier should be created for the slot.

 -- slot option: type type-descriptor
     This is accepted but not presently used.

Possible STRUCTURE-OPTIONS are:

 -- structure option: predicate [name]
     This option controls the definition of a predicate procedure for the structure.  If NAME is not given, the predicate is defined with the default name (see above).  If NAME is #f, the predicate is not defined at all.  Otherwise, NAME must be a symbol, and the predicate is defined with that symbol as its name.

 -- structure option: copier [name]
     This option controls the definition of a procedure to copy instances of the structure.  This is a procedure of one argument, a structure instance, that makes a newly allocated copy of the structure and returns it.  If NAME is not given, the copier is defined, and the name of the copier is "copy-" followed by the structure name (e.g. copy-foo).  If NAME is #f, the copier is not defined.  Otherwise, NAME must be a symbol, and the copier is defined with that symbol as its name.

 -- structure option: print-procedure expression
     Evaluating EXPRESSION must yield a procedure of two arguments, which is used to print instances of the structure.  The procedure is an unparser method (see Custom Output).  If the structure instances are records, this option has the same effect as calling set-record-type-unparser-method!.

 -- structure option: constructor [name [argument-list]]
     This option controls the definition of constructor procedures.  These constructor procedures are called ``BOA constructors'', for ``By Order of Arguments'', because the arguments to the constructor specify the initial contents the structure's slots by the order in which they are given.  This is as opposed to ``keyword constructors'', which specify the initial contents using keywords, and in which the order of arguments is irrelevant.

     If NAME is not given, a constructor is defined with the default name and arguments (see above).  If NAME is #f, no constructor is defined; ARGUMENT-LIST may not be specified in this case.  Otherwise, NAME must be a symbol, and a constructor is defined with that symbol as its name.  If NAME is a symbol, ARGUMENT-LIST is optionally allowed; if it is omitted, the constructor accepts one argument for each slot in the structure definition, in the same order in which the slots appear in the definition.  Otherwise, ARGUMENT-LIST must be a lambda list (see Lambda Expressions), and each of the parameters of the lambda list must be the name of a slot in the structure.  The arguments accepted by the constructor are defined by this lambda list.  Any slot that is not specified by the lambda list is initialized to the DEFAULT-INIT as specified above; likewise for any slot specified as an optional parameter when the corresponding argument is not supplied.

     If the constructor option is specified, the default constructor is not defined.  Additionally, the constructor option may be specified multiple times to define multiple constructors with different names and argument lists.

          (define-structure (foo (constructor make-foo (#!optional a b)))
            (a 6 read-only #t)
            (b 9))

 -- structure option: keyword-constructor [name]
     This option controls the definition of keyword constructor procedures. A keyword constructor is a procedure that accepts arguments that are alternating slot names and values.  If NAME is omitted, a keyword constructor is defined, and the name of the constructor is "make-" followed by the name of the structure (e.g. make-foo).  Otherwise, NAME must be a symbol, and a keyword constructor is defined with this symbol as its name.

     If the keyword-constructor option is specified, the default constructor is not defined.  Additionally, the keyword-constructor option may be specified multiple times to define multiple keyword constructors; this is usually not done since such constructors would all be equivalent.

          (define-structure (foo (keyword-constructor make-bar)) a b)
          (foo-a (make-bar 'b 20 'a 19))         => 19

 -- structure option: conc-name [name]
     By default, the prefix for naming accessors and modifiers is the name of the structure followed by a hyphen.  The conc-name option can be used to specify an alternative.  If NAME is not given, the prefix is the name of the structure followed by a hyphen (the default).  If NAME is #f, the slot names are used directly, without prefix.  Otherwise, NAME must a symbol, and that symbol is used as the prefix.

          (define-structure (foo (conc-name moby/)) a b)

     defines accessors moby/a and moby/b, and modifiers set-moby/a! and set-moby/b!.

          (define-structure (foo (conc-name #f)) a b)

     defines accessors a and b, and modifiers set-a! and set-b!.

 -- structure option: type representation-type
     By default, structures are implemented as records.  The type option overrides this default, allowing the programmer to specify that the structure be implemented using another data type.  The option value REPRESENTATION-TYPE specifies the alternate data type; it is allowed to be one of the symbols vector or list, and the data type used is the one corresponding to the symbol.

     If this option is given, and the named option is not specified, the representation will not be tagged, and neither a predicate nor a type descriptor will be defined; also, the print-procedure option may not be given.

          (define-structure (foo (type list)) a b)
          (make-foo 1 2)                          => (1 2)

 -- structure option: named [expression]
     This is valid only in conjunction with the type option and specifies that the structure instances be tagged to make them identifiable as instances of this structure type.  In the usual case, where EXPRESSION is not given, the named option causes a type descriptor and predicate to be defined for the structure (recall that the type option without named suppresses their definition), and also defines a default unparser method for the structure instances (which can be overridden by the print-procedure option).  The type descriptor is a unique object, not a record type, that describes the structure instances and is additionally stored in the structure instances to identify them: if the representation type is vector, the type descriptor is stored in the zero-th slot of the vector, and if the representation type is list, it is stored as the first element of the list.

          (define-structure (foo (type vector) named) a b c)
          (vector-ref (make-foo 1 2 3) 0) => #[structure-type 52]

     If EXPRESSION is specified, it is an expression that is evaluated to yield a tag object.  The EXPRESSION is evaluated once when the structure definition is evaluated (to specify the unparser method), and again whenever a predicate or constructor is called.  Because of this, EXPRESSION is normally a variable reference or a constant.  The value yielded by EXPRESSION may be any object at all.  That object is stored in the structure instances in the same place that the type descriptor is normally stored, as described above.  If EXPRESSION is specified, no type descriptor is defined, only a predicate.

          (define-structure (foo (type vector) (named 'foo)) a b c)
          (vector-ref (make-foo 1 2 3) 0) => foo

 -- structure option: initial-offset offset
     This is valid only in conjunction with the type option. OFFSET must be an exact non-negative integer and specifies the number of slots to leave open at the beginning of the structure instance before the specified slots are allocated.  Specifying an OFFSET of zero is equivalent to omitting the initial-offset option.

     If the named option is specified, the structure tag appears in the first slot, followed by the ``offset'' slots, and then the regular slots.  Otherwise, the ``offset'' slots come first, followed by the regular slots.

          (define-structure (foo (type vector) (initial-offset 3)) a b c)
          (make-foo 1 2 3)                => #(() () () 1 2 3)

The essential differences between MIT Scheme's define-structure and Common Lisp's defstruct are:

  * The default constructor procedure takes positional arguments, in the same order as specified in the definition of the structure.  A keyword constructor may be specified by giving the option keyword-constructor.

  * BOA constructors are described using Scheme lambda lists.  Since there is nothing corresponding to &aux in Scheme lambda lists, this functionality is not implemented.

  * By default, no copier procedure is defined.

  * The side-effect procedure corresponding to the accessor foo is given the name set-foo!.

  * Keywords are ordinary symbols -- use foo instead of :foo.

  * The option values false, nil, true, and t are treated as if the appropriate boolean constant had been specified instead.

  * The print-function option is named print-procedure.  Its argument is a procedure of two arguments (the unparser state and the structure instance) rather than three as in Common Lisp.

  * By default, named structures are tagged with a unique object of some kind.  In Common Lisp, the structures are tagged with symbols.  This depends on the Common Lisp package system to help generate unique tags; MIT Scheme has no such way to generate unique symbols.

  * The named option may optionally take an argument, which is normally the name of a variable (any expression may be used, but it is evaluated whenever the tag name is needed).  If used, structure instances will be tagged with that variable's value.  The variable must be defined when define-structure is evaluated.

  * The type option is restricted to the values vector and list.

  * The include option is not implemented.

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? obj1 obj2
     The eqv? procedure defines a useful equivalence relation on objects.  Briefly, it returns #t if OBJ1 and OBJ2 should normally be regarded as the same object.

     The eqv? procedure returns #t if:

       * OBJ1 and OBJ2 are both #t or both #f.

       * OBJ1 and OBJ2 are both interned symbols and

               (string=? (symbol->string OBJ1)
                         (symbol->string OBJ2))
                    => #t

       * OBJ1 and OBJ2 are both numbers, are numerically equal according to the = procedure, and are either both exact or both inexact (see Numbers).

       * OBJ1 and OBJ2 are both characters and are the same character according to the char=? procedure (see Characters).

       * both OBJ1 and OBJ2 are the empty list.

       * OBJ1 and OBJ2 are procedures whose location tags are equal.

       * OBJ1 and OBJ2 are pairs, vectors, strings, bit strings, records, cells, or weak pairs that denote the same locations in the store.

     The eqv? procedure returns #f if:

       * OBJ1 and OBJ2 are of different types.

       * one of OBJ1 and OBJ2 is #t but the other is #f.

       * OBJ1 and OBJ2 are symbols but

               (string=? (symbol->string OBJ1)
                         (symbol->string OBJ2))
                    => #f

       * one of OBJ1 and OBJ2 is an exact number but the other is an inexact number.

       * OBJ1 and OBJ2 are numbers for which the = procedure returns #f.

       * OBJ1 and OBJ2 are characters for which the char=? procedure returns #f.

       * one of OBJ1 and OBJ2 is the empty list but the other is not.

       * OBJ1 and OBJ2 are procedures that would behave differently (return a different value or have different side effects) for some arguments.

       * OBJ1 and OBJ2 are pairs, vectors, strings, bit strings, records, cells, or weak pairs that denote distinct locations.

     Some examples:

          (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

     Objects of distinct types must never be regarded as the same object.

     Since it is an error to modify constant objects (those returned by literal expressions), the implementation may share structure between constants where appropriate.  Thus the value of eqv? on constants is sometimes unspecified.

          (let ((x '(a)))
            (eqv? x x))                    =>  #t
          (eqv? '(a) '(a))                 =>  unspecified
          (eqv? "a" "a")                   =>  unspecified
          (eqv? '(b) (cdr '(a b)))         =>  unspecified

     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? obj1 obj2
     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, records, 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? obj1 obj2
     equal? recursively compares the contents of pairs, vectors, and strings, applying eqv? on other objects such as numbers, symbols, and records.  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
*******

(This section is largely taken from the Revised^4 Report on the Algorithmic Language Scheme.)

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 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 Implementation restrictions.

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 (see Numerical types), 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. (MIT Scheme implements the whole tower of numerical types.  It has unlimited-precision exact integers and exact rationals.  Flonums are used to implement all inexact reals; on machines that support IEEE floating-point arithmetic these are double-precision floating-point numbers.)

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:

     *                gcd                modulo
     +                imag-part          numerator
     -                inexact->exact     quotient
     abs              lcm                rationalize
     angle            magnitude          real-part
     ceiling          make-polar         remainder
     denominator      make-rectangular   round
     expt             max                truncate
     floor            min

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.

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. (MIT Scheme implements all of the written notations for numbers.) 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
=============================

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
====================

See Entry Format 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? object
 -- procedure: complex? object
 -- procedure: real? object
 -- procedure: rational? object
 -- procedure: integer? object
     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. (In MIT Scheme the rational? procedure is the same as real?, and the complex? procedure is the same as 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.

 -- procedure: exact? z
 -- procedure: inexact? z
     These numerical predicates provide tests for the exactness of a quantity.  For any Scheme number, precisely one of these predicates is true.

 -- procedure+: exact-integer? object
 -- procedure+: exact-nonnegative-integer? object
 -- procedure+: exact-rational? object
     These procedures test for some very common types of numbers.  These tests could be written in terms of simpler predicates, but are more efficient.

 -- procedure: = z1 z2 z3 ...
 -- procedure: < x1 x2 x3 ...
 -- procedure: > x1 x2 x3 ...
 -- procedure: <= x1 x2 x3 ...
 -- procedure: >= x1 x2 x3 ...
     These procedures return #t if their arguments are (respectively): equal, monotonically increasing, monotonically decreasing, monotonically nondecreasing, or monotonically nonincreasing.

     These predicates are transitive.  Note that 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: positive? x
 -- procedure: negative? x
 -- procedure: odd? x
 -- procedure: even? x
     These numerical predicates test a number for a particular property, returning #t or #f.  See note above regarding inexact numbers.

 -- procedure: max x1 x2 ...
 -- procedure: min x1 x2 ...
     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. (MIT Scheme signals an error of type condition-type:bad-range-argument in this case.)

 -- procedure: + z1 ...
 -- procedure: * z1 ...
     These procedures return the sum or product of their arguments.

          (+ 3 4)                 =>  7
          (+ 3)                   =>  3
          (+)                     =>  0
          (* 4)                   =>  4
          (*)                     =>  1

 -- procedure: - z1 z2 ...
 -- procedure: / z1 z2 ...
     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+: 1+ z
 -- procedure+: -1+ z
     (1+ z) is equivalent to (+ z 1); (-1+ z) is equivalent to (- z 1).

 -- procedure: abs x
     abs returns the magnitude of its argument.

          (abs -7)                =>  7

 -- procedure: quotient n1 n2
 -- procedure: remainder n1 n2
 -- procedure: modulo n1 n2
     These procedures implement number-theoretic (integer) division: for positive integers N1 and N2, if N3 and N4 are integers such that

          N1 = (N2 * N3) + N4

          0 <= N4 < N2

     then

          (quotient N1 N2)        =>  N3
          (remainder N1 N2)       =>  N4
          (modulo N1 N2)          =>  N4

     For integers N1 and N2 with N2 not equal to 0,

          (= N1
             (+ (* N2 (quotient N1 N2))
                (remainder N1 N2)))
                                              =>  #t

     provided all numbers involved in that computation are exact.

     The value returned by quotient always has the sign of the product of its arguments.  remainder and modulo differ on negative arguments --- the remainder always has the sign of the dividend, the modulo always has the sign of the divisor:

          (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

     Note that quotient is the same as integer-truncate.

 -- procedure+: integer-floor n1 n2
 -- procedure+: integer-ceiling n1 n2
 -- procedure+: integer-truncate n1 n2
 -- procedure+: integer-round n1 n2
     These procedures combine integer division with rounding.  For example, the following are equivalent:

          (integer-floor N1 N2)
          (floor (/ N1 N2))

     However, the former is faster and does not produce an intermediate result.

     Note that integer-truncate is the same as quotient.

 -- procedure+: integer-divide n1 n2
 -- procedure+: integer-divide-quotient qr
 -- procedure+: integer-divide-remainder qr
     integer-divide is equivalent to performing both quotient and remainder at once.  The result of integer-divide is an object with two components; the procedures integer-divide-quotient and integer-divide-remainder select those components.  These procedures are useful when both the quotient and remainder are needed; often computing both of these numbers simultaneously is much faster than computing them separately.

     For example, the following are equivalent:

          (lambda (n d)
            (cons (quotient n d)
                  (remainder n d)))

          (lambda (n d)
            (let ((qr (integer-divide n d)))
              (cons (integer-divide-quotient qr)
                    (integer-divide-remainder qr))))

 -- procedure: gcd n1 ...
 -- procedure: lcm n1 ...
     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: denominator q
     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: ceiling x
 -- procedure: truncate x
 -- procedure: round x
     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 rounding modes required 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 (or use one of the procedures below).

          (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+: floor->exact x
 -- procedure+: ceiling->exact x
 -- procedure+: truncate->exact x
 -- procedure+: round->exact x
     These procedures are similar to the preceding procedures except that they always return an exact result.  For example, the following are equivalent

          (floor->exact x)
          (inexact->exact (floor x))

     except that the former is faster and has fewer range restrictions.

 -- procedure: rationalize x y
 -- procedure+: rationalize->exact x y
     rationalize returns the simplest rational number differing from X by no more than Y.  A rational number R1 is simpler than another rational number R2 if R1=P1/Q1 and R2=P2/Q2 (both in lowest terms) and |P1|<=|P2| and |Q1|<=|Q2|.  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

     rationalize->exact is similar to rationalize except that it always returns an exact result.

 -- procedure+: simplest-rational x y
 -- procedure+: simplest-exact-rational x y
     simplest-rational returns the simplest rational number between X and Y inclusive; simplest-exact-rational is similar except that it always returns an exact result.

     These procedures implement the same functionality as rationalize and rationalize->exact, except that they specify the input range by its endpoints; rationalize specifies the range by its center point and its (half-) width.

 -- procedure: exp z
 -- procedure: log z
 -- procedure: sin z
 -- procedure: cos z
 -- procedure: tan z
 -- procedure: asin z
 -- procedure: acos z
 -- procedure: atan z
 -- procedure: atan y x
     These procedures compute the usual transcendental functions.  log computes the natural logarithm of Z (not the base ten logarithm). asin, acos, and atan compute arcsine, arccosine, and arctangent, respectively.  The two-argument variant of atan computes (angle (make-rectangular X Y)) (see below).

     In general, the mathematical functions log, arcsine, arccosine, and arctangent are multiply defined.  For nonzero real X, the value of log X is defined to be the one whose imaginary part lies in the range minus PI (exclusive) to PI (inclusive).  log 0 is undefined.  The value of log Z when Z is complex is defined according to the formula

          log Z = log magnitude(Z) + i angle(Z)

     With log defined this way, the values of arcsine, arccosine, and arctangent are according to the following formulae:

          arcsin(Z) = -i log(i Z + sqrt(1 - Z^2))
          arccos(Z) = pi/2 - arcsin(Z)
          arctan(Z) = (log(1 + i Z) + log(1 - i Z)) / (2 i)

     The above specification follows Common Lisp: the Language, which in turn cites Principal Values and Branch Cuts in Complex APL; 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
     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 z1 z2
     Returns Z1 raised to the power Z2:

          Z1^Z2 = e^(Z2 log Z1)

     0^0 is defined to be equal to 1.

 -- procedure: make-rectangular x1 x2
 -- procedure: make-polar x3 x4
 -- procedure: real-part z
 -- procedure: imag-part z
 -- procedure: magnitude z
 -- procedure: angle z
 -- procedure+: conjugate z
     Suppose X1, X2, X3, and X4 are real numbers and Z is a complex number such that

          Z = X1 + X2 i = X3 e^(i X4)

     Then make-rectangular and make-polar return Z, real-part returns X1, imag-part returns X2, magnitude returns X3, and angle returns X4. In the case of angle, whose value is not uniquely determined by the preceding rule, the value returned will be the one in the range minus PI (exclusive) to PI (inclusive).

     conjugate returns the complex conjugate of Z.

 -- procedure: exact->inexact z
 -- procedure: inexact->exact z
     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; MIT Scheme signals an error of type condition-type:bad-range-argument in this case.

     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; in MIT Scheme this case does not occur because all inexact numbers are representable as exact numbers.

     These procedures implement the natural one-to-one correspondence between exact and inexact integers throughout an implementation-dependent range. See Implementation restrictions.

Numerical input and output
==========================

 -- procedure: number->string number [radix]
     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 NUMBER 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; 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 NUMBER is not a complex number or is a complex number with an non-rational real or imaginary part.

     Rationale: If NUMBER 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.

 -- variable+: flonum-unparser-cutoff
     This variable controls the action of number->string when NUMBER is a flonum (and consequently controls all printing of flonums); it can have the following values:

       * The symbol normal, which is the initial value of this variable, causes flonums to be printed with full precision.  number->string uses as many digits as are necessary to display all of the information in the flonum.  This value may also be specified as a list (normal N) where N is an exact integer; N is ignored.

       * The list (relative N), where N is an exact positive integer, constrains number->string to represent the flonum using at most N significant digits.  number->string rounds the result so that it is as accurate as possible.  For example:

               (number->string (* 4 (atan 1 1)))
                                                   => "3.141592653589793"
               (fluid-let ((flonum-unparser-cutoff '(relative 5)))
                 (number->string (* 4 (atan 1 1))))
                                                   => "3.1416"
               (fluid-let ((flonum-unparser-cutoff '(relative 5)))
                 (number->string (* 4000 (atan 1 1))))
                                                   => "3141.6"

       * The list (absolute N), where N is an exact integer, constrains number->string to represent the flonum by rounding it at the Nth digit to the right of the decimal point; if N is negative, the number is rounded (- N) digits to the left of the decimal point.  For example:

               (fluid-let ((flonum-unparser-cutoff '(absolute 5)))
                 (number->string (* 4 (atan 1 1))))
                                                   => "3.14159"
               (fluid-let ((flonum-unparser-cutoff '(absolute 5)))
                 (number->string (* 4000 (atan 1 1))))
                                                   => "3141.59265"
               (fluid-let ((flonum-unparser-cutoff '(absolute -4)))
                 (number->string (* 4e10 (atan 1 1))))
                                                   => "31415930000."
               (fluid-let ((flonum-unparser-cutoff '(absolute -5)))
                 (number->string (* 4e10 (atan 1 1))))
                                                   => "31415900000."

     If flonum-unparser-cutoff is bound to a value different from those described here, number->string issues a warning and acts as though it had been bound to normal.

 -- procedure: string->number string [radix]
     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 that a numeric representation using a decimal point or an exponent marker is not recognized unless RADIX is 10.

Fixnum and Flonum Operations
============================

This section describes numerical operations that are restricted forms of the operations described above.  These operations are useful because they compile very efficiently.  However, care should be exercised: if used improperly, these operations can return incorrect answers, or even malformed objects that confuse the garbage collector.

Fixnum Operations
-----------------

A fixnum is an exact integer that is small enough to fit in a machine word.  In MIT Scheme, fixnums are typically 24 or 26 bits, depending on the machine; it is reasonable to assume that fixnums are at least 24 bits.  Fixnums are signed; they are encoded using 2's complement.

All exact integers that are small enough to be encoded as fixnums are always encoded as fixnums --- in other words, any exact integer that is not a fixnum is too big to be encoded as such.  For this reason, small constants such as 0 or 1 are guaranteed to be fixnums.

 -- procedure+: fix:fixnum? object
     Returns #t if OBJECT is a fixnum; otherwise returns #f.

Here is an expression that determines the largest fixnum:

     (let loop ((n 0))
       (let ((m (+ n 1)))
         (if (fix:fixnum? m)
             (loop m)
             n)))

A similar expression determines the smallest fixnum.

 -- procedure+: fix:= fixnum fixnum
 -- procedure+: fix:< fixnum fixnum
 -- procedure+: fix:> fixnum fixnum
 -- procedure+: fix:<= fixnum fixnum
 -- procedure+: fix:>= fixnum fixnum
     These are the standard order and equality predicates on fixnums.  When compiled, they do not check the types of their arguments.

 -- procedure+: fix:zero? fixnum
 -- procedure+: fix:positive? fixnum
 -- procedure+: fix:negative? fixnum
     These procedures compare their argument to zero.  When compiled, they do not check the type of their argument.  The code produced by the following expressions is identical:

          (fix:zero? FIXNUM)
          (fix:= FIXNUM 0)

     Similarly, fix:positive? and fix:negative? produce code identical to equivalent expressions using fix:> and fix:<.

 -- procedure+: fix:+ fixnum fixnum
 -- procedure+: fix:- fixnum fixnum
 -- procedure+: fix:* fixnum fixnum
 -- procedure+: fix:quotient fixnum fixnum
 -- procedure+: fix:remainder fixnum fixnum
 -- procedure+: fix:gcd fixnum fixnum
 -- procedure+: fix:1+ fixnum
 -- procedure+: fix:-1+ fixnum
     These procedures are the standard arithmetic operations on fixnums. When compiled, they do not check the types of their arguments. Furthermore, they do not check to see if the result can be encoded as a fixnum.  If the result is too large to be encoded as a fixnum, a malformed object is returned, with potentially disastrous effect on the garbage collector.

 -- procedure+: fix:divide fixnum fixnum
     This procedure is like integer-divide, except that its arguments and its results must be fixnums.  It should be used in conjunction with integer-divide-quotient and integer-divide-remainder.

The following are bitwise-logical operations on fixnums.

 -- procedure+: fix:not fixnum
     This returns the bitwise-logical inverse of its argument.  When compiled, it does not check the type of its argument.

          (fix:not 0)                             =>  -1
          (fix:not -1)                            =>  0
          (fix:not 1)                             =>  -2
          (fix:not -34)                           =>  33

 -- procedure+: fix:and fixnum fixnum
     This returns the bitwise-logical ``and'' of its arguments.  When compiled, it does not check the types of its arguments.

          (fix:and #x43 #x0f)                     =>  3
          (fix:and #x43 #xf0)                     =>  #x40

 -- procedure+: fix:andc fixnum fixnum
     Returns the bitwise-logical ``and'' of the first argument with the bitwise-logical inverse of the second argument.  When compiled, it does not check the types of its arguments.

          (fix:andc #x43 #x0f)                    =>  #x40
          (fix:andc #x43 #xf0)                    =>  3

 -- procedure+: fix:or fixnum fixnum
     This returns the bitwise-logical ``inclusive or'' of its arguments. When compiled, it does not check the types of its arguments.

          (fix:or #x40 3)                         => #x43
          (fix:or #x41 3)                         => #x43

 -- procedure+: fix:xor fixnum fixnum
     This returns the bitwise-logical ``exclusive or'' of its arguments. When compiled, it does not check the types of its arguments.

          (fix:xor #x40 3)                        => #x43
          (fix:xor #x41 3)                        => #x42

 -- procedure+: fix:lsh fixnum1 fixnum2
     This procedure returns the result of logically shifting FIXNUM1 by FIXNUM2 bits.  If FIXNUM2 is positive, FIXNUM1 is shifted left; if negative, it is shifted right.  When compiled, it does not check the types of its arguments, nor the validity of its result.

          (fix:lsh 1 10)                          =>  #x400
          (fix:lsh #x432 -10)                     =>  1
          (fix:lsh -1 3)                          =>  -8
          (fix:lsh -128 -4)                       =>  #x3FFFF8

Flonum Operations
-----------------

A flonum is an inexact real number that is implemented as a floating-point number.  In MIT Scheme, all inexact real numbers are flonums.  For this reason, constants such as 0. and 2.3 are guaranteed to be flonums.

 -- procedure+: flo:flonum? object
     Returns #t if OBJECT is a flonum; otherwise returns #f.

 -- procedure+: flo:= flonum1 flonum2
 -- procedure+: flo:< flonum1 flonum2
 -- procedure+: flo:> flonum1 flonum2
     These procedures are the standard order and equality predicates on flonums.  When compiled, they do not check the types of their arguments.

 -- procedure+: flo:zero? flonum
 -- procedure+: flo:positive? flonum
 -- procedure+: flo:negative? flonum
     Each of these procedures compares its argument to zero.  When compiled, they do not check the type of their argument.

 -- procedure+: flo:+ flonum1 flonum2
 -- procedure+: flo:- flonum1 flonum2
 -- procedure+: flo:* flonum1 flonum2
 -- procedure+: flo:/ flonum1 flonum2
     These procedures are the standard arithmetic operations on flonums. When compiled, they do not check the types of their arguments.

 -- procedure+: flo:negate flonum
     This procedure returns the negation of its argument.  When compiled, it does not check the type of its argument.  Equivalent to (flo:- 0. FLONUM).

 -- procedure+: flo:abs flonum
 -- procedure+: flo:exp flonum
 -- procedure+: flo:log flonum
 -- procedure+: flo:sin flonum
 -- procedure+: flo:cos flonum
 -- procedure+: flo:tan flonum
 -- procedure+: flo:asin flonum
 -- procedure+: flo:acos flonum
 -- procedure+: flo:atan flonum
 -- procedure+: flo:sqrt flonum
 -- procedure+: flo:expt flonum1 flonum2
 -- procedure+: flo:floor flonum
 -- procedure+: flo:ceiling flonum
 -- procedure+: flo:truncate flonum
 -- procedure+: flo:round flonum
 -- procedure+: flo:floor->exact flonum
 -- procedure+: flo:ceiling->exact flonum
 -- procedure+: flo:truncate->exact flonum
 -- procedure+: flo:round->exact flonum
     These procedures are flonum versions of the corresponding procedures. When compiled, they do not check the types of their arguments.

 -- procedure+: flo:atan2 flonum1 flonum2
     This is the flonum version of atan with two arguments.  When compiled, it does not check the types of its arguments.

Random Numbers
==============

MIT Scheme provides a facility for generating pseudo-random numbers. The current implementation is a ``subtract-with-carry'' random-number generator, based on the algorithm from A New Class of Random Number Generators, George Marsaglia and Arif Zaman, The Annals of Applied Probability, Vol. 1, No. 3, 1991.  At the time it was implemented, this was a good algorithm for general purposes, but the state of the art in random-number generation is constantly changing.  If necessary, the implementation will be updated to use a new algorithm while retaining the same interface.

The interface described here is essentially identical to that of Common Lisp.

 -- procedure+: random modulus [state]
     MODULUS must be a positive real number.  random returns a pseudo-random number between zero (inclusive) and MODULUS (exclusive).  The exactness of the returned number is the same as the exactness of MODULUS.  Additionally, if MODULUS is an exact integer, the returned number will be also.  Usually, MODULUS is either an exact integer or an inexact real; the current implementation has been tuned to make these two cases fast.

     If STATE is given and not #f, it must be a random-state object; otherwise, it defaults to the value of the variable *random-state*.  This object is used to maintain the state of the pseudo-random-number generator and is altered as a side effect of the random procedure.

          (random 1.0)    => .32744744667719056
          (random 1.0)    => .01668326768172354
          (random 10)     => 3
          (random 10)     => 8
          (random 100)    => 38
          (random 100)    => 63
          (random 100/3)  => 130501475769920525/6755399441055744
          (random 100/3)  => 170571694016427575/13510798882111488

 -- variable+: *random-state*
     This variable holds a data structure, a random-state object, that encodes the internal state of the random-number generator that random uses by default.  A call to random will perform a side effect on this data structure.  This variable may be changed, using set! or fluid-let, to hold a new random-state object.

 -- procedure+: make-random-state [state]
     This procedure returns a new random-state object, suitable for use as the value of the variable *random-state*, or as the STATE argument to random.  If STATE is not given or #f, make-random-state returns a copy of the current random-number state object (the value of the variable *random-state*).  If STATE is a random-state object, a copy of that object is returned.  If STATE is #t, then a new random-state object is returned that has been ``randomly'' initialized by some means (such as by a time-of-day clock).

 -- procedure+: random-state? object
     Returns #t if OBJECT is a random-state object, otherwise returns #f.

Characters
**********

Characters are objects that represent printed characters, such as letters and digits. (Some of the details in this section depend on the fact that the underlying operating system uses the ASCII character set.  This may change when someone ports MIT Scheme to a non-ASCII operating system.)

External Representation of Characters
=====================================

Characters are written using the notation #\CHARACTER or #\CHARACTER-NAME.  For example:

     #\a                     ; lowercase letter
     #\A                     ; uppercase letter
     #\(                     ; left parenthesis
     #\space                 ; the space character
     #\newline               ; the newline character

Case is significant in #\CHARACTER, but not in #\CHARACTER-NAME.  If CHARACTER in #\CHARACTER is a letter, CHARACTER must be followed by a delimiter character such as a space or parenthesis.  Characters written in the #\ notation are self-evaluating; you don't need to quote them.

A character name may include one or more bucky bit prefixes to indicate that the character includes one or more of the keyboard shift keys Control, Meta, Super, Hyper, or Top (note that the Control bucky bit prefix is not the same as the ASCII control key).  The bucky bit prefixes and their meanings are as follows (case is not significant):

     Key             Bucky bit prefix        Bucky bit
     ---             ----------------        ---------

     Meta            M- or Meta-                 1
     Control         C- or Control-              2
     Super           S- or Super-                4
     Hyper           H- or Hyper-                8
     Top             T- or Top-                 16

For example,

     #\c-a                   ; Control-a
     #\meta-b                ; Meta-b
     #\c-s-m-h-a             ; Control-Meta-Super-Hyper-A

The following CHARACTER-NAMEs are supported, shown here with their ASCII equivalents:

     Character Name          ASCII Name
     --------------          ----------

     altmode                 ESC
     backnext                US
     backspace               BS
     call                    SUB
     linefeed                LF
     page                    FF
     return                  CR
     rubout                  DEL
     space
     tab                     HT

In addition, #\newline is either #\linefeed or #\return, depending on the operating system that Scheme is running under.  All of the standard ASCII names for non-printing characters are supported:

     NUL     SOH     STX     ETX     EOT     ENQ     ACK     BEL
     BS      HT      LF      VT      FF      CR      SO      SI
     DLE     DC1     DC2     DC3     DC4     NAK     SYN     ETB
     CAN     EM      SUB     ESC     FS      GS      RS      US
     DEL

 -- procedure+: char->name char [slashify?]
     Returns a string corresponding to the printed representation of CHAR.  This is the CHARACTER or CHARACTER-NAME component of the external representation, combined with the appropriate bucky bit prefixes.

          (char->name #\a)                        =>  "a"
          (char->name #\space)                    =>  "Space"
          (char->name #\c-a)                      =>  "C-a"
          (char->name #\control-a)                =>  "C-a"

     SLASHIFY?, if specified and true, says to insert the necessary backslash characters in the result so that read will parse it correctly.  In other words, the following generates the external representation of CHAR:

          (string-append "#\\" (char->name CHAR #t))

     If SLASHIFY? is not specified, it defaults to #f.

 -- procedure+: name->char string
     Converts a string that names a character into the character specified. If STRING does not name any character, name->char signals an error.

          (name->char "a")                        =>  #\a
          (name->char "space")                    =>  #\Space
          (name->char "c-a")                      =>  #\C-a
          (name->char "control-a")                =>  #\C-a

Comparison of Characters
========================

 -- procedure: char=? char1 char2
 -- procedure: char<? char1 char2
 -- procedure: char>? char1 char2
 -- procedure: char<=? char1 char2
 -- procedure: char>=? char1 char2
 -- procedure: char-ci=? char1 char2
 -- procedure: char-ci<? char1 char2
 -- procedure: char-ci>? char1 char2
 -- procedure: char-ci<=? char1 char2
 -- procedure: char-ci>=? char1 char2
     Returns #t if the specified characters are have the appropriate order relationship to one another; otherwise returns #f.  The -ci procedures don't distinguish uppercase and lowercase letters.

     Character ordering follows these rules:

       * The digits are in order; for example, (char<? #\0 #\9) returns #t.

       * The uppercase characters are in order; for example, (char<? #\A #\B) returns #t.

       * The lowercase characters are in order; for example, (char<? #\a #\b) returns #t.

     In addition, MIT Scheme orders those characters that satisfy char-standard? the same way that ASCII does.  Specifically, all the digits precede all the uppercase letters, and all the upper-case letters precede all the lowercase letters.

     Characters are ordered by first comparing their bucky bits part and then their code part.  In particular, characters without bucky bits come before characters with bucky bits.

Miscellaneous Character Operations
==================================

 -- procedure: char? object
     Returns #t if OBJECT is a character; otherwise returns #f.

 -- procedure: char-upcase char
 -- procedure: char-downcase char
     Returns the uppercase or lowercase equivalent of CHAR if CHAR is a letter; otherwise returns CHAR.  These procedures return a character CHAR2 such that (char-ci=? CHAR CHAR2).

 -- procedure+: char->digit char [radix]
     If CHAR is a character representing a digit in the given RADIX, returns the corresponding integer value.  If you specify RADIX (which must be an exact integer between 2 and 36 inclusive), the conversion is done in that base, otherwise it is done in base 10. If CHAR doesn't represent a digit in base RADIX, char->digit returns #f.

     Note that this procedure is insensitive to the alphabetic case of CHAR.

          (char->digit #\8)                       =>  8
          (char->digit #\e 16)                    =>  14
          (char->digit #\e)                       =>  #f

 -- procedure+: digit->char digit [radix]
     Returns a character that represents DIGIT in the radix given by RADIX.  RADIX must be an exact integer between 2 and 36 (inclusive), and defaults to 10.  DIGIT, which must be an exact non-negative integer, should be less than RADIX; if DIGIT is greater than or equal to RADIX, digit->char returns #f.

          (digit->char 8)                         =>  #\8
          (digit->char 14 16)                     =>  #\E

Internal Representation of Characters
=====================================

An MIT Scheme character consists of a code part and a bucky bits part.  The MIT Scheme set of characters can represent more characters than ASCII can; it includes characters with Super, Hyper, and Top bucky bits, as well as Control and Meta.  Every ASCII character corresponds to some MIT Scheme character, but not vice versa. (Note that the Control bucky bit is different from the ASCII control key.  This means that #\SOH (ASCII ctrl-A) is different from #\C-A.  In fact, the Control bucky bit is completely orthogonal to the ASCII control key, making possible such characters as #\C-SOH.)

MIT Scheme uses a 7-bit ASCII character code with 5 bucky bits.  The least significant bucky bit, Meta, is stored adjacent to the MSB of the character code, allowing the least significant 8 bits of a character object to be interpreted as ordinary ASCII with a meta bit.  This is compatible with standard practice for 8-bit characters when meta bits are employed.

 -- procedure+: make-char code bucky-bits
     Builds a character from CODE and BUCKY-BITS.  Both CODE and BUCKY-BITS must be exact non-negative integers in the appropriate range.  Use char-code and char-bits to extract the code and bucky bits from the character.  If 0 is specified for BUCKY-BITS, make-char produces an ordinary character; otherwise, the appropriate bits are turned on as follows:

          1               Meta
          2               Control
          4               Super
          8               Hyper
          16              Top

     For example,

          (make-char 97 0)                        =>  #\a
          (make-char 97 1)                        =>  #\M-a
          (make-char 97 2)                        =>  #\C-a
          (make-char 97 3)                        =>  #\C-M-a

 -- procedure+: char-bits char
     Returns the exact integer representation of CHAR's bucky bits. For example,

          (char-bits #\a)                         =>  0
          (char-bits #\m-a)                       =>  1
          (char-bits #\c-a)                       =>  2
          (char-bits #\c-m-a)                     =>  3

 -- procedure+: char-code char
     Returns the character code of CHAR, an exact integer.  For example,

          (char-code #\a)                         =>  97
          (char-code #\c-a)                       =>  97

 -- variable+: char-code-limit
 -- variable+: char-bits-limit
     These variables define the (exclusive) upper limits for the character code and bucky bits (respectively).  The character code and bucky bits are always exact non-negative integers, and are strictly less than the value of their respective limit variable.

 -- procedure: char->integer char
 -- procedure: integer->char k
     char->integer returns the character code representation for CHAR.  integer->char returns the character whose character code representation is K.

     In MIT Scheme, if (char-ascii? CHAR) is true, then

          (eqv? (char->ascii CHAR) (char->integer CHAR))

     However, this behavior is not required by the Scheme standard, and code that depends on it is not portable to other implementations.

     These procedures implement order 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 range of char->integer, then

          (<= (char->integer a)
              (char->integer b))                  =>  #t
          (char<=? (integer->char x)
                   (integer->char y))             =>  #t

 -- variable+: char-integer-limit
     The range of char->integer is defined to be the exact non-negative integers that are less than the value of this variable (exclusive).

ASCII Characters
================

MIT Scheme internally uses ASCII codes for I/O, and stores character objects in a fashion that makes it convenient to convert between ASCII codes and characters.  Also, character strings are implemented as byte vectors whose elements are ASCII codes; these codes are converted to character objects when accessed.  For these reasons it is sometimes desirable to be able to convert between ASCII codes and characters.

Not all characters can be represented as ASCII codes.  A character that has an equivalent ASCII representation is called an ASCII character.

 -- procedure+: char-ascii? char
     Returns the ASCII code for CHAR if CHAR has an ASCII representation; otherwise returns #f.

     In the current implementation, the characters that satisfy this predicate are those in which the Control, Super, Hyper, and Top bucky bits are turned off.  All characters for which the char-bits procedure returns 0 or 1 (i.e. no bucky bits, or just Meta) count as legal ASCII characters.

 -- procedure+: char->ascii char
     Returns the ASCII code for CHAR.  An error condition-type:bad-range-argument is signalled if CHAR doesn't have an ASCII representation.

 -- procedure+: ascii->char code
     CODE must be the exact integer representation of an ASCII code.  This procedure returns the character corresponding to CODE.

Character Sets
==============

MIT Scheme's character-set abstraction is used to represent groups of characters, such as the letters or digits.  Character sets may contain only ASCII characters; in the future this may be changed to allow the full range of characters.

There is no meaningful external representation for character sets; use char-set-members to examine their contents.  There is (at present) no specific equivalence predicate for character sets; use equal? for this purpose.

 -- procedure+: char-set? object
     Returns #t if OBJECT is a character set; otherwise returns #f. (Because character sets are implemented as strings, string? returns #t for character set objects.  However, string operations aren't meaningful with character sets.)

 -- variable+: char-set:upper-case
 -- variable+: char-set:lower-case
 -- variable+: char-set:alphabetic
 -- variable+: char-set:numeric
 -- variable+: char-set:alphanumeric
 -- variable+: char-set:whitespace
 -- variable+: char-set:not-whitespace
 -- variable+: char-set:graphic
 -- variable+: char-set:not-graphic
 -- variable+: char-set:standard
     These variables contain predefined character sets. To see the contents of one of these sets, use char-set-members.

     Alphabetic characters are the 52 upper and lower case letters. Numeric characters are the 10 decimal digits.  Alphanumeric characters are those in the union of these two sets.  Whitespace characters are #\space, #\tab, #\page, #\linefeed, and #\return.  GRAPHIC characters are the printing characters and #\space.  STANDARD characters are the printing characters, #\space, and #\newline. These are the printing characters:

          ! " # $ % & ' ( ) * + , - . /
          0 1 2 3 4 5 6 7 8 9
          : ; < = > ? @
          A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
          [ \ ] ^ _ `
          a b c d e f g h i j k l m n o p q r s t u v w x y z
          { | } ~

 -- procedure: char-upper-case? char
 -- procedure: char-lower-case? char
 -- procedure: char-alphabetic? char
 -- procedure: char-numeric? char
 -- procedure+: char-alphanumeric? char
 -- procedure: char-whitespace? char
 -- procedure+: char-graphic? char
 -- procedure+: char-standard? object
     These predicates are defined in terms of the respective character sets defined above.

 -- procedure+: char-set-members char-set
     Returns a newly allocated list of the characters in CHAR-SET.

 -- procedure+: char-set-member? char-set char
     Returns #t if the CHAR is in CHAR-SET; otherwise returns #f.

 -- procedure+: char-set char ...
     Returns a character set consisting of the specified ASCII characters.  With no arguments, char-set returns an empty character set.

 -- procedure+: chars->char-set chars
     Returns a character set consisting of CHARS, which must be a list of ASCII characters.  This is equivalent to (apply char-set CHARS).

 -- procedure+: ascii-range->char-set lower upper
     LOWER and UPPER must be exact non-negative integers representing ASCII character codes, and LOWER must be less than or equal to UPPER.  This procedure creates and returns a new character set consisting of the characters whose ASCII codes are between LOWER (inclusive) and UPPER (exclusive).

 -- procedure+: predicate->char-set predicate
     PREDICATE must be a procedure of one argument. predicate->char-set creates and returns a character set consisting of the ASCII characters for which PREDICATE is true.

 -- procedure+: char-set-difference char-set1 char-set2
     Returns a character set consisting of the characters that are in CHAR-SET1 but aren't in CHAR-SET2.

 -- procedure+: char-set-intersection char-set1 char-set2
     Returns a character set consisting of the characters that are in both CHAR-SET1 and CHAR-SET2.

 -- procedure+: char-set-union char-set1 char-set2
     Returns a character set consisting of the characters that are in one or both of CHAR-SET1 and CHAR-SET2.

 -- procedure+: char-set-invert char-set
     Returns a character set consisting of the ASCII characters that are not in CHAR-SET.

Strings
*******

A string is a mutable sequence of characters.  In the current implementation of MIT Scheme, the elements of a string must all satisfy the predicate char-ascii?; if someone ports MIT Scheme to a non-ASCII operating system this requirement will change.

A string is written as a sequence of characters enclosed within double quotes " ".  To include a double quote inside a string, precede the double quote with a backslash \ (escape it), as in

     "The word \"recursion\" has many meanings."

The printed representation of this string is

     The word "recursion" has many meanings.

To include a backslash inside a string, precede it with another backslash; for example,

     "Use #\\Control-q to quit."

The printed representation of this string is

     Use #\Control-q to quit.

The effect of a backslash that doesn't precede a double quote or backslash is unspecified in standard Scheme, but MIT Scheme specifies the effect for three other characters: \t, \n, and \f.  These escape sequences are respectively translated into the following characters: #\tab, #\newline, and #\page.  Finally, a backslash followed by exactly three octal digits is translated into the character whose ASCII code is those digits.

If a string literal is continued from one line to another, the string will contain the newline character (#\newline) at the line break. Standard Scheme does not specify what appears in a string literal at a line break.

The length of a string is the number of characters that it contains.  This number is an exact non-negative integer that is established when the string is created (but see Variable-Length Strings). Each character in a string has an index, which is a number that indicates the character's position in the string.  The index of the first (leftmost) character in a string is 0, and the index of the last character is one less than the length of the string.  The valid indexes of a string are the exact non-negative integers less than the length of the string.

A number of the string procedures operate on substrings.  A substring is a segment of a STRING, which is specified by two integers START and END satisfying these relationships:

     0 <= START <= END <= (string-length STRING)

START is the index of the first character in the substring, and END is one greater than the index of the last character in the substring.  Thus if START and END are equal, they refer to an empty substring, and if START is zero and END is the length of STRING, they refer to all of STRING.

Some of the procedures that operate on strings ignore the difference between uppercase and lowercase.  The versions that ignore case include -ci (for ``case insensitive'') in their names.

Construction of Strings
=======================

 -- procedure: make-string k [char]
     Returns a newly allocated string of length K.  If you specify CHAR, all elements of the string are initialized to CHAR, otherwise the contents of the string are unspecified.  CHAR must satisfy the predicate char-ascii?.

          (make-string 10 #\x)              =>  "xxxxxxxxxx"

 -- procedure+: string char ...
     Returns a newly allocated string consisting of the specified characters. The arguments must all satisfy char-ascii?.

          (string #\a)                                =>  "a"
          (string #\a #\b #\c)                        =>  "abc"
          (string #\a #\space #\b #\space #\c)        =>  "a b c"
          (string)                                    =>  ""

     For compatibility with old code, char->string is a synonym for this procedure.

 -- procedure: list->string char-list
     CHAR-LIST must be a list of ASCII characters. list->string returns a newly allocated string formed from the elements of CHAR-LIST.  This is equivalent to (apply string CHAR-LIST).  The inverse of this operation is string->list.

          (list->string '(#\a #\b))               =>  "ab"
          (string->list "Hello")                  =>  (#\H #\e #\l #\l #\o)

 -- procedure: string-copy string
     Returns a newly allocated copy of STRING.

     Note regarding variable-length strings: the maximum length of the result depends only on the length of STRING, not its maximum length.  If you wish to copy a string and preserve its maximum length, do the following:

          (define (string-copy-preserving-max-length string)
            (let ((length))
              (dynamic-wind
               (lambda ()
                 (set! length (string-length string))
                 (set-string-length! string (string-maximum-length string)))
               (lambda ()
                 (string-copy string))
               (lambda ()
                 (set-string-length! string length)))))

Selecting String Components
===========================

 -- procedure: string? object
     Returns #t if OBJECT is a string; otherwise returns #f.

          (string? "Hi")                  =>  #t
          (string? 'Hi)                   =>  #f

 -- procedure: string-length string
     Returns the length of STRING as an exact non-negative integer.

          (string-length "")              =>  0
          (string-length "The length")    =>  10

 -- procedure: string-null? string
     Returns #t if STRING has zero length; otherwise returns #f.

          (string-null? "")               =>  #t
          (string-null? "Hi")             =>  #f

 -- procedure: string-ref string k
     Returns character K of STRING.  K must be a valid index of STRING.

          (string-ref "Hello" 1)          =>  #\e
          (string-ref "Hello" 5)          error--> 5 not in correct range

 -- procedure: string-set! string k char
     Stores CHAR in element K of STRING and returns an unspecified value.  K must be a valid index of STRING, and CHAR must satisfy the predicate char-ascii?.

          (define str "Dog")              =>  unspecified
          (string-set! str 0 #\L)         =>  unspecified
          str                             =>  "Log"
          (string-set! str 3 #\t)         error--> 3 not in correct range

Comparison of Strings
=====================

 -- procedure: string=? string1 string2
 -- procedure+: substring=? string1 start end string2 start end
 -- procedure: string-ci=? string1 string2
 -- procedure+: substring-ci=? string1 start end string2 start end
     Returns #t if the two strings (substrings) are the same length and contain the same characters in the same (relative) positions; otherwise returns #f.  string-ci=? and substring-ci=? don't distinguish uppercase and lowercase letters, but string=? and substring=? do.

          (string=? "PIE" "PIE")                  =>  #t
          (string=? "PIE" "pie")                  =>  #f
          (string-ci=? "PIE" "pie")               =>  #t
          (substring=? "Alamo" 1 3 "cola" 2 4)    =>  #t ; compares "la"

 -- procedure: string<? string1 string2
 -- procedure+: substring<? string1 start1 end1 string2 start2 end2
 -- procedure: string>? string1 string2
 -- procedure: string<=? string1 string2
 -- procedure: string>=? string1 string2
 -- procedure: string-ci<? string1 string2
 -- procedure+: substring-ci<? string1 start1 end1 string2 start2 end2
 -- procedure: string-ci>? string1 string2
 -- procedure: string-ci<=? string1 string2
 -- procedure: string-ci>=? string1 string2
     These procedures compare strings (substrings) according to the order of the characters they contain (also see Comparison of Characters). The arguments are compared using a lexicographic (or dictionary) order. 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 less than the longer string.

          (string<? "cat" "dog")          =>  #t
          (string<? "cat" "DOG")          =>  #f
          (string-ci<? "cat" "DOG")       =>  #t
          (string>? "catkin" "cat")       =>  #t ; shorter is lesser

 -- procedure+: string-compare string1 string2 if-eq if-lt if-gt
 -- procedure+: string-compare-ci string1 string2 if-eq if-lt if-gt
     IF-EQ, IF-LT, and IF-GT are procedures of no arguments (thunks).  The two strings are compared; if they are equal, IF-EQ is applied, if STRING1 is less than STRING2, IF-LT is applied, else if STRING1 is greater than STRING2, IF-GT is applied.  The value of the procedure is the value of the thunk that is applied.

     string-compare distinguishes uppercase and lowercase letters; string-compare-ci does not.

          (define (cheer) (display "Hooray!"))
          (define (boo)   (display "Boo-hiss!"))
          (string-compare "a" "b"  cheer  (lambda() 'ignore)  boo)
                  -|  Hooray!
                  =>  unspecified

 -- procedure+: string-hash string
 -- procedure+: string-hash-mod string k
     string-hash returns an exact non-negative integer that can be used for storing the specified STRING in a hash table.  Equal strings (in the sense of string=?) return equal (=) hash codes, and non-equal but similar strings are usually mapped to distinct hash codes.

     string-hash-mod is like string-hash, except that it limits the result to a particular range based on the exact non-negative integer K.  The following are equivalent:

          (string-hash-mod STRING K)
          (modulo (string-hash STRING) K)

Alphabetic Case in Strings
==========================

 -- procedure+: string-capitalized? string
 -- procedure+: substring-capitalized? string start end
     These procedures return #t if the first word in the string (substring) is capitalized, and any subsequent words are either lower case or capitalized.  Otherwise, they return #f.  A word is defined as a non-null contiguous sequence of alphabetic characters, delimited by non-alphabetic characters or the limits of the string (substring).  A word is capitalized if its first letter is upper case and all its remaining letters are lower case.

          (map string-capitalized? '(""    "A"    "art"  "Art"  "ART"))
                                 => (#f    #t     #f     #t     #f)

 -- procedure+: string-upper-case? string
 -- procedure+: substring-upper-case? string start end
 -- procedure+: string-lower-case? string
 -- procedure+: substring-lower-case? string start end
     These procedures return #t if all the letters in the string (substring) are of the correct case, otherwise they return #f. The string (substring) must contain at least one letter or the procedures return #f.

          (map string-upper-case?  '(""    "A"    "art"  "Art"  "ART"))
                                 => (#f    #t     #f     #f     #t)

 -- procedure+: string-capitalize string
 -- procedure+: string-capitalize! string
 -- procedure+: substring-capitalize! string start end
     string-capitalize returns a newly allocated copy of STRING in which the first alphabetic character is uppercase and the remaining alphabetic characters are lowercase.  For example, "abcDEF" becomes "Abcdef".  string-capitalize! is the destructive version of string-capitalize: it alters STRING and returns an unspecified value.  substring-capitalize! destructively capitalizes the specified part of STRING.

 -- procedure+: string-downcase string
 -- procedure+: string-downcase! string
 -- procedure+: substring-downcase! string start end
     string-downcase returns a newly allocated copy of STRING in which all uppercase letters are changed to lowercase. string-downcase! is the destructive version of string-downcase: it alters STRING and returns an unspecified value.  substring-downcase! destructively changes the case of the specified part of STRING.

          (define str "ABCDEFG")          =>  unspecified
          (substring-downcase! str 3 5)   =>  unspecified
          str                             =>  "ABCdeFG"

 -- procedure+: string-upcase string
 -- procedure+: string-upcase! string
 -- procedure+: substring-upcase! string start end
     string-upcase returns a newly allocated copy of STRING in which all lowercase letters are changed to uppercase. string-upcase! is the destructive version of string-upcase: it alters STRING and returns an unspecified value.  substring-upcase! destructively changes the case of the specified part of STRING.

Cutting and Pasting Strings
===========================

 -- procedure: string-append string ...
     Returns a newly allocated string made from the concatenation of the given strings.  With no arguments, string-append returns the empty string ("").

          (string-append)                         =>  ""
          (string-append "*" "ace" "*")           =>  "*ace*"
          (string-append "" "" "")                =>  ""
          (eq? str (string-append str))           =>  #f ; newly allocated

 -- procedure: substring string start end
     Returns a newly allocated string formed from the characters of STRING beginning with index START (inclusive) and ending with END (exclusive).

          (substring "" 0 0)              => ""
          (substring "arduous" 2 5)       => "duo"
          (substring "arduous" 2 8)       error--> 8 not in correct range

          (define (string-copy s)
            (substring s 0 (string-length s)))

 -- procedure+: string-head string end
     Returns a newly allocated copy of the initial substring of STRING, up to but excluding END.  It could have been defined by:

          (define (string-head string end)
            (substring string 0 end))

 -- procedure+: string-tail string start
     Returns a newly allocated copy of the final substring of STRING, starting at index START and going to the end of STRING.  It could have been defined by:

          (define (string-tail string start)
            (substring string start (string-length string)))

          (string-tail "uncommon" 2)      =>  "common"

 -- procedure+: string-pad-left string k [char]
 -- procedure+: string-pad-right string k [char]
     These procedures return a newly allocated string created by padding STRING out to length K, using CHAR.  If CHAR is not given, it defaults to #\space.  If K is less than the length of STRING, the resulting string is a truncated form of STRING.  string-pad-left adds padding characters or truncates from the beginning of the string (lowest indices), while string-pad-right does so at the end of the string (highest indices).

          (string-pad-left "hello" 4)             =>  "ello"
          (string-pad-left "hello" 8)             =>  "   hello"
          (string-pad-left "hello" 8 #\*)         =>  "***hello"
          (string-pad-right "hello" 4)            =>  "hell"
          (string-pad-right "hello" 8)            =>  "hello   "

 -- procedure+: string-trim string [char-set]
 -- procedure+: string-trim-left string [char-set]
 -- procedure+: string-trim-right string [char-set]
     Returns a newly allocated string created by removing all characters that are not in CHAR-SET from: (string-trim) both ends of STRING; (string-trim-left) the beginning of STRING; or (string-trim-right) the end of STRING.  CHAR-SET defaults to char-set:not-whitespace.

          (string-trim "  in the end  ")          =>  "in the end"
          (string-trim "              ")          =>  ""
          (string-trim "100th" char-set:numeric)  =>  "100"
          (string-trim-left "-.-+-=-" (char-set #\+))
                                                  =>  "+-=-"
          (string-trim "but (+ x y) is" (char-set #\( #\)))
                                                  =>  "(+ x y)"

Searching Strings
=================

 -- procedure+: substring? pattern string
     Searches STRING to see if it contains the substring PATTERN. Returns the index of the first substring of STRING that is equal to PATTERN; or #f if STRING does not contain PATTERN.

          (substring? "rat" "pirate")             =>  2
          (substring? "rat" "outrage")            =>  #f
          (substring? "" any-string)              =>  0
          (if (substring "moon" text)
              (process-lunar text)
              'no-moon)

 -- procedure+: string-find-next-char string char
 -- procedure+: substring-find-next-char string start end char
 -- procedure+: string-find-next-char-ci string char
 -- procedure+: substring-find-next-char-ci string start end char
     Returns the index of the first occurrence of CHAR in the string (substring); returns #f if CHAR does not appear in the string.  For the substring procedures, the index returned is relative to the entire string, not just the substring.  The -ci procedures don't distinguish uppercase and lowercase letters.

          (string-find-next-char "Adam" #\A)              =>  0
          (substring-find-next-char "Adam" 1 4 #\A)       =>  #f
          (substring-find-next-char-ci "Adam" 1 4 #\A)    =>  2

 -- procedure+: string-find-next-char-in-set string char-set
 -- procedure+: substring-find-next-char-in-set string start end char-set
     Returns the index of the first character in the string (or substring) that is also in CHAR-SET, or returns #f if none of the characters in CHAR-SET occur in STRING. For the substring procedure, only the substring is searched, but the index returned is relative to the entire string, not just the substring.

          (string-find-next-char-in-set my-string char-set:alphabetic)
                          =>  start position of the first word in my-string
          ; Can be used as a predicate:
          (if (string-find-next-char-in-set my-string (char-set #\( #\) ))
              'contains-parentheses
              'no-parentheses)

 -- procedure+: string-find-previous-char string char
 -- procedure+: substring-find-previous-char string start end char
 -- procedure+: string-find-previous-char-ci string char
 -- procedure+: substring-find-previous-char-ci string start end char
     Returns the index of the last occurrence of CHAR in the string (substring); returns #f if CHAR doesn't appear in the string.  For the substring procedures, the index returned is relative to the entire string, not just the substring.  The -ci procedures don't distinguish uppercase and lowercase letters.

 -- procedure+: string-find-previous-char-in-set string char-set
 -- procedure+: substring-find-previous-char-in-set string start end char-set
     Returns the index of the last character in the string (substring) that is also in CHAR-SET.  For the substring procedure, the index returned is relative to the entire string, not just the substring.

Matching Strings
================

 -- procedure+: string-match-forward string1 string2
 -- procedure+: substring-match-forward string1 start end string2 start end
 -- procedure+: string-match-forward-ci string1 string2
 -- procedure+: substring-match-forward-ci string1 start end string2 start end
     Compares the two strings (substrings), starting from the beginning, and returns the number of characters that are the same.  If the two strings (substrings) start differently, returns 0.  The -ci procedures don't distinguish uppercase and lowercase letters.

          (string-match-forward "mirror" "micro") =>  2  ; matches "mi"
          (string-match-forward "a" "b")          =>  0  ; no match

 -- procedure+: string-match-backward string1 string2
 -- procedure+: substring-match-backward string1 start end string2 start end
 -- procedure+: string-match-backward-ci string1 string2
 -- procedure+: substring-match-backward-ci string1 start end string2 start end
     Compares the two strings (substrings), starting from the end and matching toward the front, returning the number of characters that are the same.  If the two strings (substrings) end differently, returns 0. The -ci procedures don't distinguish uppercase and lowercase letters.

          (string-match-backward-ci "BULBOUS" "fractious")
                                                  =>  3  ; matches "ous"

 -- procedure+: string-prefix? string1 string2
 -- procedure+: substring-prefix? string1 start1 end1 string2 start2 end2
 -- procedure+: string-prefix-ci? string1 string2
 -- procedure+: substring-prefix-ci? string1 start1 end1 string2 start2 end2
     These procedures return #t if the first string (substring) forms the prefix of the second; otherwise returns #f.  The -ci procedures don't distinguish uppercase and lowercase letters.

          (string-prefix? "abc" "abcdef")         =>  #t
          (string-prefix? "" any-string)          =>  #t

 -- procedure+: string-suffix? string1 string2
 -- procedure+: substring-suffix? string1 start1 end1 string2 start2 end2
 -- procedure+: string-suffix-ci? string1 string2
 -- procedure+: substring-suffix-ci? string1 start1 end1 string2 start2 end2
     These procedures return #t if the first string (substring) forms the suffix of the second; otherwise returns #f.  The -ci procedures don't distinguish uppercase and lowercase letters.

          (string-suffix? "ous" "bulbous")        =>  #t
          (string-suffix? "" any-string)          =>  #t

Modification of Strings
=======================

 -- procedure+: string-replace string char1 char2
 -- procedure+: substring-replace string start end char1 char2
 -- procedure+: string-replace! string char1 char2
 -- procedure+: substring-replace! string start end char1 char2
     These procedures replace all occurrences of CHAR1 with CHAR2 in the original string (substring).  string-replace and substring-replace return a newly allocated string containing the result.  string-replace! and substring-replace! destructively modify STRING and return an unspecified value.

          (define str "a few words")              =>  unspecified
          (string-replace str #\space #\-)        =>  "a-few-words"
          (substring-replace str 2 9 #\space #\-) =>  "a few-words"
          str                                     =>  "a few words"
          (string-replace! str #\space #\-)       =>  unspecified
          str                                     =>  "a-few-words"

 -- procedure: string-fill! string char
     Stores CHAR in every element of STRING and returns an unspecified value.

 -- procedure+: substring-fill! string start end char
     Stores CHAR in elements START (inclusive) to END (exclusive) of STRING and returns an unspecified value.

          (define s (make-string 10 #\space))     =>  unspecified
          (substring-fill! s 2 8 #\*)             =>  unspecified
          s                                       =>  "  ******  "

 -- procedure+: substring-move-left! string1 start1 end1 string2 start2
 -- procedure+: substring-move-right! string1 start1 end1 string2 start2
     Copies the characters from START1 to END1 of STRING1 into STRING2 at the START2-th position.  The characters are copied as follows (note that this is only important when STRING1 and STRING2 are eqv?):

     substring-move-left!
          The copy starts at the left end and moves toward the right (from smaller indices to larger).  Thus if STRING1 and STRING2 are the same, this procedure moves the characters toward the left inside the string.

     substring-move-right!
          The copy starts at the right end and moves toward the left (from larger indices to smaller).  Thus if STRING1 and STRING2 are the same, this procedure moves the characters toward the right inside the string.

     The following example shows how these procedures can be used to build up a string (it would have been easier to use string-append):

          (define answer (make-string 9 #\*))             =>  unspecified
          answer                                          =>  "*********"
          (substring-move-left! "start" 0 5 answer 0)     =>  unspecified
          answer                                          =>  "start****"
          (substring-move-left! "-end" 0 4 answer 5)      =>  unspecified
          answer                                          =>  "start-end"

Variable-Length Strings
=======================

MIT Scheme allows the length of a string to be dynamically adjusted in a limited way.  This feature works as follows.  When a new string is allocated, by whatever method, it has a specific length.  At the time of allocation, it is also given a maximum length, which is guaranteed to be at least as large as the string's length.  (Sometimes the maximum length will be slightly larger than the length, but it is a bad idea to count on this.  Programs should assume that the maximum length is the same as the length at the time of the string's allocation.)  After the string is allocated, the operation set-string-length! can be used to alter the string's length to any value between 0 and the string's maximum length, inclusive.

 -- procedure+: string-maximum-length string
     Returns the maximum length of STRING.  The following is guaranteed:

          (<= (string-length string)
              (string-maximum-length string))     =>  #t

     The maximum length of a string never changes.

 -- procedure+: set-string-length! string k
     Alters the length of STRING to be K, and returns an unspecified value.  K must be less than or equal to the maximum length of STRING.  set-string-length! does not change the maximum length of STRING.

Byte Vectors
============

MIT Scheme implements strings as packed vectors of 8-bit ASCII bytes.  Most of the string operations, such as string-ref, coerce these 8-bit codes into character objects.  However, some lower-level operations are made available for use.

 -- procedure+: vector-8b-ref string k
     Returns character K of STRING as an ASCII code. K must be a valid index of STRING.

          (vector-8b-ref "abcde" 2)               =>  99 ; ascii for `c'

 -- procedure+: vector-8b-set! string k ascii
     Stores ASCII in element K of STRING and returns an unspecified value.  K must be a valid index of STRING, and ASCII must be a valid ASCII code.

 -- procedure+: vector-8b-fill! string start end ascii
     Stores ASCII in elements START (inclusive) to END (exclusive) of STRING and returns an unspecified value. ASCII must be a valid ASCII code.

 -- procedure+: vector-8b-find-next-char string start end ascii
 -- procedure+: vector-8b-find-next-char-ci string start end ascii
     Returns the index of the first occurrence of ASCII in the given substring; returns #f if ASCII does not appear.  The index returned is relative to the entire string, not just the substring. ASCII must be a valid ASCII code.

     vector-8b-find-next-char-ci doesn't distinguish uppercase and lowercase letters.

 -- procedure+: vector-8b-find-previous-char string start end ascii
 -- procedure+: vector-8b-find-previous-char-ci string start end ascii
     Returns the index of the last occurrence of ASCII in the given substring; returns #f if ASCII does not appear.  The index returned is relative to the entire string, not just the substring. ASCII must be a valid ASCII code.

     vector-8b-find-previous-char-ci doesn't distinguish uppercase and lowercase letters.

Lists
*****

A pair (sometimes called a dotted pair) is a data 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. (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 (C1 . C2) where C1 is the value of the car field and C2 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, the following are equivalent notations for a list of symbols:

     (a b c d e)
     (a . (b . (c . (d . (e . ())))))

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? y)                               =>  #f

A chain of pairs that doesn't end 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, as the following equivalent notations show:

     (a b c . d)
     (a . (b . (c . d)))

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.  Among other things, this permits the use of the read procedure to parse Scheme programs.

Pairs
=====

This section describes the simple operations that are available for constructing and manipulating arbitrary graphs constructed from pairs.

 -- procedure: pair? object
     Returns #t if OBJECT is a pair; otherwise returns #f.

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

 -- procedure: cons obj1 obj2
     Returns a newly allocated pair whose car is OBJ1 and whose cdr is OBJ2.  The pair is guaranteed to be different (in the sense of eqv?) from every previously 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
     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--> Illegal datum

 -- procedure: cdr pair
     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--> Illegal datum

 -- procedure: set-car! pair object
     Stores OBJECT 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--> Illegal datum

 -- procedure: set-cdr! pair object
     Stores OBJECT in the cdr field of PAIR.  The value returned by set-cdr! is unspecified.

 -- procedure: caar pair
 -- procedure: cadr pair
 -- procedure: cdar pair
 -- procedure: cddr pair
 -- procedure: caaar pair
 -- procedure: caadr pair
 -- procedure: cadar pair
 -- procedure: caddr pair
 -- procedure: cdaar pair
 -- procedure: cdadr pair
 -- procedure: cddar pair
 -- procedure: cdddr pair
 -- procedure: caaaar pair
 -- procedure: caaadr pair
 -- procedure: caadar pair
 -- procedure: caaddr pair
 -- procedure: cadaar pair
 -- procedure: cadadr pair
 -- procedure: caddar pair
 -- procedure: cadddr pair
 -- procedure: cdaaar pair
 -- procedure: cdaadr pair
 -- procedure: cdadar pair
 -- procedure: cdaddr pair
 -- procedure: cddaar pair
 -- procedure: cddadr pair
 -- procedure: cdddar pair
 -- procedure: cddddr pair
     These procedures are compositions of car and cdr; for example, caddr could be defined by

          (define caddr (lambda (x) (car (cdr (cdr x)))))

 -- procedure+: general-car-cdr object path
     This procedure is a generalization of car and cdr. PATH encodes a particular sequence of car and cdr operations, which general-car-cdr executes on OBJECT. PATH is an exact non-negative integer that encodes the operations in a bitwise fashion: a zero bit represents a cdr operation, and a one bit represents a car.  The bits are executed LSB to MSB, and the most significant one bit, rather than being interpreted as an operation, signals the end of the sequence. (Note that PATH is restricted to a machine-dependent range, usually the size of a machine word.  On many machines, this means that the maximum length of PATH will be 30 operations (32 bits, less the sign bit and the ``end-of-sequence'' bit).)

     For example, the following are equivalent:

          (general-car-cdr OBJECT #b1011)
          (cdr (car (car OBJECT)))

     Here is a partial table of path/operation equivalents:

          #b10    cdr
          #b11    car
          #b100   cddr
          #b101   cdar
          #b110   cadr
          #b111   caar
          #b1000  cdddr

 -- procedure+: tree-copy tree
     This copies an arbitrary TREE constructed from pairs, copying both the car and cdr elements of every pair.  This could have been defined by

          (define (tree-copy tree)
            (let loop ((tree tree))
              (if (pair? tree)
                  (cons (loop (car tree)) (loop (cdr tree)))
                  tree)))

Construction of Lists
=====================

 -- procedure: list object ...
     Returns a list of its arguments.

          (list 'a (+ 3 4) 'c)                    =>  (a 7 c)
          (list)                                  =>  ()

     These expressions are equivalent:

          (list OBJ1 OBJ2 ... OBJN)
          (cons OBJ1 (cons OBJ2 ... (cons OBJN '()) ...))

 -- procedure+: make-list k [element]
     This procedure returns a newly allocated list of length K, whose elements are all ELEMENT.  If ELEMENT is not supplied, it defaults to the empty list.

 -- procedure+: cons* object object ...
     cons* is similar to list, except that cons* conses together the last two arguments rather than consing the last argument with the empty list.  If the last argument is not a list the result is an improper list.  If the last argument is a list, the result is a list consisting of the initial arguments and all of the items in the final argument.  If there is only one argument, the result is the argument.

          (cons* 'a 'b 'c)                        =>  (a b . c)
          (cons* 'a 'b '(c d))                    =>  (a b c d)
          (cons* 'a)                              =>  a

     These expressions are equivalent:

          (cons* OBJ1 OBJ2 ... OBJN-1 OBJN)
          (cons OBJ1 (cons OBJ2 ... (cons OBJN-1 OBJN) ...))

 -- procedure+: list-copy list
     Returns a newly allocated copy of LIST.  This copies each of the pairs comprising LIST.  This could have been defined by

          (define (list-copy list)
            (if (null? list)
                '()
                (cons (car list)
                      (list-copy (cdr list)))))

 -- procedure: vector->list vector
 -- procedure+: subvector->list vector start end
     vector->list returns a newly allocated list of the elements of VECTOR.  subvector->list returns a newly allocated list of the elements of the given subvector.  The inverse of vector->list is list->vector.

          (vector->list '#(dah dah didah))        =>  (dah dah didah)

 -- procedure: string->list string
 -- procedure: substring->list string start end
     string->list returns a newly allocated list of the character elements of STRING.

     substring->list returns a newly allocated list of the character elements of the given substring.  The inverse of string->list is list->string.

          (string->list "abcd")                   =>  (#\a #\b #\c #\d)
          (substring->list "abcdef" 1 3)          =>  (#\b #\c)

Selecting List Components
=========================

 -- procedure+: list? object
     Returns #t if OBJECT is a list, otherwise returns #f.  By definition, all lists have finite length and are terminated by the empty list.  This procedure returns an answer even for circular structures.

     Any OBJECT satisfying this predicate will also satisfy exactly one of pair? or null?.

          (list? '(a b c))                        =>  #t
          (list? '())                             =>  #t
          (list? '(a . b))                        =>  #f
          (let ((x (list 'a)))
            (set-cdr! x x)
            (list? x))                            =>  #f

 -- procedure: length list
     Returns the length of LIST.

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

 -- procedure: null? object
     Returns #t if OBJECT is the empty list; otherwise returns #f (but see True and False).

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

 -- procedure: list-ref list k
     Returns the Kth element of LIST, using zero-origin indexing. The valid indexes of a list are the exact non-negative integers less than the length of the list.  The first element of a list has index 0, the second has index 1, and so on.

          (list-ref '(a b c d) 2)                 =>  c
          (list-ref '(a b c d)
                    (inexact->exact (round 1.8)))
               =>  c

     (list-ref LIST K) is equivalent to (car (list-tail LIST K)).

 -- procedure+: first list
 -- procedure+: second list
 -- procedure+: third list
 -- procedure+: fourth list
 -- procedure+: fifth list
 -- procedure+: sixth list
 -- procedure+: seventh list
 -- procedure+: eighth list
 -- procedure+: ninth list
 -- procedure+: tenth list
     Returns the specified element of LIST.  It is an error if LIST is not long enough to contain the specified element (for example, if the argument to seventh is a list that contains only six elements).

Cutting and Pasting Lists
=========================

 -- procedure+: sublist list start end
     START and END must be exact integers satisfying

          0 <= START <= END <= (length LIST)

     sublist returns a newly allocated list formed from the elements of LIST beginning at index START (inclusive) and ending at END (exclusive).

 -- procedure+: list-head list k
     Returns a newly allocated list consisting of the first K elements of LIST.  K must not be greater than the length of LIST.

     We could have defined list-head this way:

          (define (list-head list k)
            (sublist list 0 k))

 -- procedure: list-tail list k
     Returns the sublist of LIST obtained by omitting the first K elements.  The result, if it is not the empty list, shares structure with LIST.  K must not be greater than the length of LIST.

 -- procedure: append list ...
     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))
          (append)                                =>  ()

     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+: append! list ...
     Returns a list that is the argument LISTs concatenated together. The arguments are changed rather than copied.  (Compare this with append, which copies arguments rather than destroying them.)  For example:

          (define x '(a b c))
          (define y '(d e f))
          (define z '(g h))
          (append! x y z)                         =>  (a b c d e f g h)
          x                                       =>  (a b c d e f g h)
          y                                       =>  (d e f g h)
          z                                       =>  (g h)

Filtering Lists
===============

 -- procedure+: list-transform-positive list predicate
 -- procedure+: list-transform-negative list predicate
     These procedures return a newly allocated copy of LIST containing only the elements for which PREDICATE is (respectively) true or false.  PREDICATE must be a procedure of one argument.

          (list-transform-positive '(1 2 3 4 5) odd?) => (1 3 5)
          (list-transform-negative '(1 2 3 4 5) odd?) => (2 4)

 -- procedure+: delq element list
 -- procedure+: delv element list
 -- procedure+: delete element list
     Returns a newly allocated copy of LIST with all entries equal to ELEMENT removed.  delq uses eq? to compare ELEMENT with the entries in LIST, delv uses eqv?, and delete uses equal?.

 -- procedure+: delq! element list
 -- procedure+: delv! element list
 -- procedure+: delete! element list
     Returns a list consisting of the top-level elements of LIST with all entries equal to ELEMENT removed.  These procedures are like delq, delv, and delete except that they destructively modify LIST.  delq! uses eq? to compare element with the entries in LIST, delv! uses eqv?, and delete! uses equal?.  Because the result may not be eq? to LIST, it is desirable to do something like (set! x (delete! x)).

          (define x '(a b c b))
          (delete 'b x)                           =>  (a c)
          x                                       =>  (a b c b)

          (define x '(a b c b))
          (delete! 'b x)                          =>  (a c)
          x                                       =>  (a c)
          ;; Returns correct result:
          (delete! 'a x)                          =>  (c)

          ;; Didn't modify what x points to:
          x                                       =>  (a c)

 -- procedure+: delete-member-procedure deletor predicate
     Returns a deletion procedure similar to delv or delete!. DELETOR should be one of the procedures list-deletor or list-deletor!.  PREDICATE must be an equivalence predicate. The returned procedure accepts exactly two arguments: first, an object to be deleted, and second, a list of objects from which it is to be deleted.  If DELETOR is list-deletor, the procedure returns a newly allocated copy of the given list in which all entries equal to the given object have been removed.  If DELETOR is list-deletor!, the procedure returns a list consisting of the top-level elements of the given list with all entries equal to the given object removed; the given list is destructively modified to produce the result.  In either case PREDICATE is used to compare the given object to the elements of the given list.

     Here are some examples that demonstrate how delete-member-procedure could have been used to implement delv and delete!:

          (define delv (delete-member-procedure list-deletor eqv?))
          (define delete! (delete-member-procedure list-deletor! equal?))

 -- procedure+: list-deletor predicate
 -- procedure+: list-deletor! predicate
     These procedures each return a procedure that deletes elements from lists.  PREDICATE must be a procedure of one argument.  The returned procedure accepts exactly one argument, which must be a proper list, and applies PREDICATE to each of the elements of the argument, deleting those for which it is true.

     The procedure returned by list-deletor deletes elements non-destructively, by returning a newly allocated copy of the argument with the appropriate elements removed.  The procedure returned by list-deletor! performs a destructive deletion.

Searching Lists
===============

 -- procedure+: list-search-positive list predicate
 -- procedure+: list-search-negative list predicate
     Returns the first element in LIST for which PREDICATE is (respectively) true or false; returns #f if it doesn't find such an element.  (This means that if PREDICATE is true (false) for #f, it may be impossible to distinguish a successful result from an unsuccessful one.)  PREDICATE must be a procedure of one argument.

 -- procedure: memq object list
 -- procedure: memv object list
 -- procedure: member object list
     These procedures return the first pair of LIST whose car is OBJECT; the returned pair is always one from which LIST is composed.  If OBJECT does not occur in LIST, #f (n.b.: not the empty list) is returned.  memq uses eq? to compare OBJECT with the elements of LIST, while memv uses eqv? and member uses equal?. (Although they are often used as predicates, memq, memv, and member do not have question marks in their names because they return useful values rather than just #t or #f.)

          (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+: member-procedure predicate
     Returns a procedure similar to memq, except that PREDICATE, which must be an equivalence predicate, is used instead of eq?. This could be used to define memv as follows:

          (define memv (member-procedure eqv?))

Mapping of Lists
================

 -- procedure: map procedure list list ...
     PROCEDURE must be a procedure taking as many arguments as there are LISTs.  If more than one LIST is given, then they must all be the same length.  map applies PROCEDURE element-wise to the elements of the LISTs and returns a list of the results, in order from left to right.  The dynamic order in which PROCEDURE is applied to the elements of the LISTs is unspecified; use for-each to sequence side effects.

          (map cadr '((a b) (d e) (g h)))           =>  (b e h)
          (map (lambda (n) (expt n n)) '(1 2 3 4))  =>  (1 4 27 256)
          (map + '(1 2 3) '(4 5 6))                 =>  (5 7 9)
          (let ((count 0))
            (map (lambda (ignored)
                   (set! count (+ count 1))
                   count)
                 '(a b c)))                         =>  unspecified

 -- procedure+: map* initial-value procedure list1 list2 ...
     Similar to map, except that the resulting list is terminated by INITIAL-VALUE rather than the empty list.  The following are equivalent:

          (map PROCEDURE LIST LIST ...)
          (map* '() PROCEDURE LIST LIST ...)

 -- procedure+: append-map procedure list list ...
 -- procedure+: append-map* initial-value procedure list list ...
     Similar to map and map*, respectively, except that the results of applying PROCEDURE to the elements of LISTs are concatenated together by append rather than by cons.  The following are equivalent, except that the former is more efficient:

          (append-map PROCEDURE LIST LIST ...)
          (apply append (map PROCEDURE LIST LIST ...))

 -- procedure+: append-map! procedure list list ...
 -- procedure+: append-map*! initial-value procedure list list ...
     Similar to map and map*, respectively, except that the results of applying PROCEDURE to the elements of LISTs are concatenated together by append! rather than by cons.  The following are equivalent, except that the former is more efficient:

          (append-map! PROCEDURE LIST LIST ...)
          (apply append! (map PROCEDURE LIST LIST ...))

 -- procedure: for-each procedure list list ...
     The arguments to for-each are like the arguments to map, but for-each calls PROCEDURE for its side effects rather than for its values.  Unlike map, for-each is guaranteed to call PROCEDURE on the elements of the LISTs in order from the first element 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)

Reduction of Lists
==================

 -- procedure+: reduce procedure initial list
     Combines all the elements of LIST using the binary operation PROCEDURE.  For example, using + one can add up all the elements:

          (reduce + 0 list-of-numbers)

     The argument INITIAL is used only if LIST is empty; in this case INITIAL is the result of the call to reduce.  If LIST has a single argument, it is returned.  Otherwise, the arguments are reduced in a left-associative fashion.  For example:

          (reduce + 0 '(1 2 3 4))                 =>  10
          (reduce + 0 '(1 2))                     =>  3
          (reduce + 0 '(1))                       =>  1
          (reduce + 0 '())                        =>  0
          (reduce + 0 '(foo))                     =>  foo
          (reduce list '() '(1 2 3 4))            =>  (((1 2) 3) 4)

 -- procedure+: reduce-right procedure initial list
     Like reduce except that it is right-associative.

          (reduce-right list '() '(1 2 3 4))      =>  (1 (2 (3 4)))

 -- procedure+: fold-right procedure initial list
     Combines all of the elements of LIST using the binary operation PROCEDURE.  Unlike reduce and reduce-right, INITIAL is always used:

          (fold-right + 0 '(1 2 3 4))             =>  10
          (fold-right + 0 '(foo))                 error--> Illegal datum
          (fold-right list '() '(1 2 3 4))        =>  (1 (2 (3 (4 ()))))

     Fold-right has interesting properties because it establishes a homomorphism between (cons, ()) and (PROCEDURE, INITIAL).  It can be thought of as replacing the pairs in the spine of the list with PROCEDURE and replacing the () at the end with INITIAL.  Many of the classical list processing procedures can be expressed in terms of fold-right, at least for the simple versions that take a fixed number of arguments:

          (define (copy-list list)
            (fold-right cons '() list))

          (define (append list1 list2)
            (fold-right cons list2 list1))

          (define (map p list)
            (fold-right (lambda (x r) (cons (p x) r)) '() list))

          (define (reverse items)
            (fold-right (lambda (x r) (append r (list x))) '() items))

 -- procedure+: fold-left procedure initial list
     Combines all the elements of LIST using the binary operation PROCEDURE.  Elements are combined starting with INITIAL and then the elements of LIST from left to right.  Whereas fold-right is recursive in nature, capturing the essence of cdr-ing down a list and then computing a result, FOLD-LEFT is iterative in nature, combining the elements as the list is traversed.

          (fold-left list '() '(1 2 3 4))         =>  ((((() 1) 2) 3) 4)

          (define (length list)
            (fold-left 1+ 0 list))

          (define (reverse items)
            (fold-left (lambda (x y) (cons y x)) () items))

 -- procedure+: there-exists? list predicate
     PREDICATE must be a procedure of one argument.  Applies PREDICATE to each element of LIST, in order from left to right.  If PREDICATE is true for any element of LIST, the value yielded by PREDICATE is immediately returned as the value of there-exists?; PREDICATE will not be applied to the remaining elements of LIST.  If PREDICATE returns #f for all of the elements of LIST, then #f is returned.

 -- procedure+: for-all? list predicate
     PREDICATE must be a procedure of one argument.  Applies PREDICATE to each element of LIST, in order from left to right.  If PREDICATE returns #f for any element of LIST, #f is immediately returned as the value of for-all?; PREDICATE will not be applied to the remaining elements of LIST.  If PREDICATE is true for all of the elements of LIST, then #t is returned.

Miscellaneous List Operations
=============================

 -- procedure+: circular-list object ...
 -- procedure+: make-circular-list k [element]
     These procedures are like list and make-list, respectively, except that the returned lists are circular. circular-list could have been defined like this:

          (define (circular-list . objects)
            (append! objects objects))

 -- procedure: reverse list
     Returns a newly allocated list consisting of the top-level 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+: reverse! list
     Returns a list consisting of the top-level elements of LIST in reverse order.  reverse! is like reverse, except that it destructively modifies LIST.  Because the result may not be eqv? to LIST, it is desirable to do something like (set! x (reverse! x)).

 -- procedure+: last-pair list
     Returns the last pair in LIST, which may be an improper list. last-pair could have been defined this way:

          (define last-pair
            (lambda (x)
              (if (pair? (cdr x))
                  (last-pair (cdr x))
                  x)))

 -- procedure+: except-last-pair list
 -- procedure+: except-last-pair! list
     These procedures remove the last pair from LIST.  LIST may be an improper list, except that it must consist of at least one pair. except-last-pair returns a newly allocated copy of LIST that omits the last pair.  except-last-pair! destructively removes the last pair from LIST and returns LIST.  If the cdr of LIST is not a pair, the empty list is returned by either procedure.

 -- procedure+: sort list procedure
     PROCEDURE must be a procedure of two arguments that defines a total ordering on the elements of LIST.  In other words, if X and Y are two distinct elements of LIST, then it must be the case that

          (and (PROCEDURE X Y)
               (PROCEDURE Y X))
               =>  #f

     sort returns a newly allocated list whose elements are the elements of LIST, except that the elements are rearranged so that they are sorted in the order defined by PROCEDURE.  So, for example, if the elements of LIST are numbers, and PROCEDURE is <, then the resulting list is sorted in monotonically nondecreasing order.  Likewise, if PROCEDURE is >, the resulting list is sorted in monotonically nonincreasing order.  To be precise, if X and Y are any two adjacent elements in the resulting list, where X precedes Y, it is the case that

          (PROCEDURE Y X)
               =>  #f

Vectors
*******

Vectors are heterogenous structures whose elements are indexed by exact non-negative 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 an exact 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 #(OBJECT ...). 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

     #(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")

A number of the vector procedures operate on subvectors.  A subvector is a segment of a vector that is specified by two exact non-negative integers, START and END.  START is the index of the first element that is included in the subvector, and END is one greater than the index of the last element that is included in the subvector.  Thus if START and END are the same, they refer to a null subvector, and if START is zero and END is the length of the vector, they refer to the entire vector. The valid indexes of a subvector are the exact integers between START inclusive and END exclusive.

Construction of Vectors
=======================

 -- procedure: make-vector k [object]
     Returns a newly allocated vector of K elements.  If OBJECT is specified, make-vector initializes each element of the vector to OBJECT.  Otherwise the initial elements of the result are unspecified.

 -- procedure: vector object ...
     Returns a newly allocated vector whose elements are the given arguments. vector is analogous to list.

          (vector 'a 'b 'c)                       =>  #(a b c)

 -- procedure+: vector-copy vector
     Returns a newly allocated vector that is a copy of VECTOR.

 -- procedure: list->vector list
     Returns a newly allocated vector initialized to the elements of LIST.  The inverse of list->vector is vector->list.

          (list->vector '(dididit dah))           =>  #(dididit dah)

 -- procedure+: make-initialized-vector k initialization
     Similar to make-vector, except that the elements of the result are determined by calling the procedure INITIALIZATION on the indices.  For example:

          (make-initialized-vector 5 (lambda (x) (* x x)))
               =>  #(0 1 4 9 16)

 -- procedure+: vector-grow vector k
     K must be greater than or equal to the length of VECTOR. Returns a newly allocated vector of length K.  The first (vector-length VECTOR) elements of the result are initialized from the corresponding elements of VECTOR.  The remaining elements of the result are unspecified.

Selecting Vector Components
===========================

 -- procedure: vector? object
     Returns #t if OBJECT is a vector; otherwise returns #f.

 -- procedure: vector-length vector
     Returns the number of elements in VECTOR.

 -- procedure: vector-ref vector k
     Returns the contents of element K of VECTOR.  K must be a valid index of VECTOR.

          (vector-ref '#(1 1 2 3 5 8 13 21) 5)    =>  8

 -- procedure: vector-set! vector k object
     Stores OBJECT in element K of VECTOR and returns an unspecified value.  K must be a valid index of VECTOR.

          (let ((vec (vector 0 '(2 2 2 2) "Anna")))
            (vector-set! vec 1 '("Sue" "Sue"))
            vec)
               =>  #(0 ("Sue" "Sue") "Anna")

 -- procedure+: vector-first vector
 -- procedure+: vector-second vector
 -- procedure+: vector-third vector
 -- procedure+: vector-fourth vector
 -- procedure+: vector-fifth vector
 -- procedure+: vector-sixth vector
 -- procedure+: vector-seventh vector
 -- procedure+: vector-eighth vector
     These procedures access the first several elements of VECTOR in the obvious way.  It is an error if the implicit index of one of these procedurs is not a valid index of VECTOR.

Cutting Vectors
===============

 -- procedure+: subvector vector start end
     Returns a newly allocated vector that contains the elements of VECTOR between index START (inclusive) and END (exclusive).

 -- procedure+: vector-head vector end
     Equivalent to

          (subvector VECTOR 0 END)

 -- procedure+: vector-tail vector start
     Equivalent to

          (subvector VECTOR START (vector-length VECTOR))

Modifying Vectors
=================

 -- procedure: vector-fill! vector object
 -- procedure+: subvector-fill! vector start end object
     Stores OBJECT in every element of the vector (subvector) and returns an unspecified value.

 -- procedure+: subvector-move-left! vector1 start1 end1 vector2 start2
 -- procedure+: subvector-move-right! vector1 start1 end1 vector2 start2
     Destructively copies the elements of VECTOR1, starting with index START1 (inclusive) and ending with END1 (exclusive), into VECTOR2 starting at index START2 (inclusive). VECTOR1, START1, and END1 must specify a valid subvector, and START2 must be a valid index for VECTOR2. The length of the source subvector must not exceed the length of VECTOR2 minus the index START2.

     The elements are copied as follows (note that this is only important when VECTOR1 and VECTOR2 are eqv?):

     subvector-move-left!
          The copy starts at the left end and moves toward the right (from smaller indices to larger).  Thus if VECTOR1 and VECTOR2 are the same, this procedure moves the elements toward the left inside the vector.

     subvector-move-right!
          The copy starts at the right end and moves toward the left (from larger indices to smaller).  Thus if VECTOR1 and VECTOR2 are the same, this procedure moves the elements toward the right inside the vector.

Bit Strings
***********

A bit string is a sequence of bits.  Bit strings can be used to represent sets or to manipulate binary data.  The elements of a bit string are numbered from zero up to the number of bits in the string less one, in right to left order, (the rightmost bit is numbered zero).  When you convert from a bit string to an integer, the zero-th bit is associated with the zero-th power of two, the first bit is associated with the first power, and so on.

Bit strings are encoded very densely in memory.  Each bit occupies exactly one bit of storage, and the overhead for the entire bit string is bounded by a small constant.  However, accessing a bit in a bit string is slow compared to accessing an element of a vector or character string.  If performance is of overriding concern, it is better to use character strings to store sets of boolean values even though they occupy more space.

The length of a bit string is the number of bits that it contains. This number is an exact non-negative integer that is fixed when the bit string is created.  The valid indexes of a bit string are the exact non-negative integers less than the length of the bit string.

Bit strings may contain zero or more bits.  They are not limited by the length of a machine word.  In the printed representation of a bit string, the contents of the bit string are preceded by #*.  The contents are printed starting with the most significant bit (highest index).

Note that the external representation of bit strings uses a bit ordering that is the reverse of the representation for bit strings in Common Lisp.  It is likely that MIT Scheme's representation will be changed in the future, to be compatible with Common Lisp.  For the time being this representation should be considered a convenience for viewing bit strings rather than a means of entering them as data.

     #*11111
     #*1010
     #*00000000
     #*

All of the bit-string procedures are MIT Scheme extensions.

Construction of Bit Strings
===========================

 -- procedure+: make-bit-string k initialization
     Returns a newly allocated bit string of length K.  If INITIALIZATION is #f, the bit string is filled with 0 bits; otherwise, the bit string is filled with 1 bits.

          (make-bit-string 7 #f)                  =>  #*0000000

 -- procedure+: bit-string-allocate k
     Returns a newly allocated bit string of length K, but does not initialize it.

 -- procedure+: bit-string-copy bit-string
     Returns a newly allocated copy of BIT-STRING.

Selecting Bit String Components
===============================

 -- procedure+: bit-string? object
     Returns #t if OBJECT is a bit string; otherwise returns #f.

 -- procedure+: bit-string-length bit-string
     Returns the length of BIT-STRING.

 -- procedure+: bit-string-ref bit-string k
     Returns #t if the Kth bit is 1; otherwise returns #f.  K must be a valid index of BIT-STRING.

 -- procedure+: bit-string-set! bit-string k
     Sets the Kth bit in BIT-STRING to 1 and returns an unspecified value.  K must be a valid index of BIT-STRING.

 -- procedure+: bit-string-clear! bit-string k
     Sets the Kth bit in BIT-STRING to 0 and returns an unspecified value.  K must be a valid index of BIT-STRING.

Cutting and Pasting Bit Strings
===============================

 -- procedure+: bit-string-append bit-string-1 bit-string-2
     Appends the two bit string arguments, returning a newly allocated bit string as its result.  In the result, the bits copied from BIT-STRING-1 are less significant (smaller indices) than those copied from BIT-STRING-2.

 -- procedure+: bit-substring bit-string start end
     Returns a newly allocated bit string whose bits are copied from BIT-STRING, starting at index START (inclusive) and ending at END (exclusive).

Bitwise Operations on Bit Strings
=================================

 -- procedure+: bit-string-zero? bit-string
     Returns #t if BIT-STRING contains only 0 bits; otherwise returns #f.

 -- procedure+: bit-string=? bit-string-1 bit-string-2
     Compares the two bit string arguments and returns #t if they are the same length and contain the same bits; otherwise returns #f.

 -- procedure+: bit-string-not bit-string
     Returns a newly allocated bit string that is the bitwise-logical negation of BIT-STRING.

 -- procedure+: bit-string-movec! target-bit-string bit-string
     The destructive version of bit-string-not.  The arguments TARGET-BIT-STRING and BIT-STRING must be bit strings of the same length.  The bitwise-logical negation of BIT-STRING is computed and the result placed in TARGET-BIT-STRING.  The value of this procedure is unspecified.

 -- procedure+: bit-string-and bit-string-1 bit-string-2
     Returns a newly allocated bit string that is the bitwise-logical ``and'' of the arguments.  The arguments must be bit strings of identical length.

 -- procedure+: bit-string-andc bit-string-1 bit-string-2
     Returns a newly allocated bit string that is the bitwise-logical ``and'' of BIT-STRING-1 with the bitwise-logical negation of BIT-STRING-2.  The arguments must be bit strings of identical length.

 -- procedure+: bit-string-or bit-string-1 bit-string-2
     Returns a newly allocated bit string that is the bitwise-logical ``inclusive or'' of the arguments.  The arguments must be bit strings of identical length.

 -- procedure+: bit-string-xor bit-string-1 bit-string-2
     Returns a newly allocated bit string that is the bitwise-logical ``exclusive or'' of the arguments.  The arguments must be bit strings of identical length.

 -- procedure+: bit-string-and! target-bit-string bit-string
 -- procedure+: bit-string-or! target-bit-string bit-string
 -- procedure+: bit-string-xor! target-bit-string bit-string
 -- procedure+: bit-string-andc! target-bit-string bit-string
     These are destructive versions of the above operations.  The arguments TARGET-BIT-STRING and BIT-STRING must be bit strings of the same length.  Each of these procedures performs the corresponding bitwise-logical operation on its arguments, places the result into TARGET-BIT-STRING, and returns an unspecified result.

Modification of Bit Strings
===========================

 -- procedure+: bit-string-fill! bit-string initialization
     Fills BIT-STRING with zeroes if INITIALIZATION is #f; otherwise fills BIT-STRING with ones.  Returns an unspecified value.

 -- procedure+: bit-string-move! target-bit-string bit-string
     Moves the contents of BIT-STRING into TARGET-BIT-STRING.  Both arguments must be bit strings of the same length.  The results of the operation are undefined if the arguments are the same bit string.

 -- procedure+: bit-substring-move-right! bit-string-1 start1 end1 bit-string-2 start2
     Destructively copies the bits of BIT-STRING-1, starting at index START1 (inclusive) and ending at END1 (exclusive), into BIT-STRING-2 starting at index START2 (inclusive). START1 and END1 must be valid substring indices for BIT-STRING-1, and START2 must be a valid index for BIT-STRING-2.  The length of the source substring must not exceed the length of BIT-STRING-2 minus the index START2.

     The bits are copied starting from the MSB and working towards the LSB; the direction of copying only matters when BIT-STRING-1 and BIT-STRING-2 are eqv?.

Integer Conversions of Bit Strings
==================================

 -- procedure+: unsigned-integer->bit-string length integer
     Both LENGTH and INTEGER must be exact non-negative integers. Converts INTEGER into a newly allocated bit string of LENGTH bits.  Signals an error of type condition-type:bad-range-argument if INTEGER is too large to be represented in LENGTH bits.

 -- procedure+: signed-integer->bit-string length integer
     LENGTH must be an exact non-negative integer, and INTEGER may be any exact integer.  Converts INTEGER into a newly allocated bit string of LENGTH bits, using two's complement encoding for negative numbers.  Signals an error of type condition-type:bad-range-argument if INTEGER is too large to be represented in LENGTH bits.

 -- procedure+: bit-string->unsigned-integer bit-string
 -- procedure+: bit-string->signed-integer bit-string
     Converts BIT-STRING into an exact integer. bit-string->signed-integer regards BIT-STRING as a two's complement representation of a signed integer, and produces an integer of like sign and absolute value.  bit-string->unsigned-integer regards BIT-STRING as an unsigned quantity and converts to an integer accordingly.

Miscellaneous Datatypes
***********************

Booleans
========

The boolean objects are true and false.  The boolean constant true is written as #t, and the boolean constant false is written as #f.

The primary use for boolean objects is in the conditional expressions if, cond, and, and or; the behavior of these expressions is determined by whether objects are true or false.  These expressions count only #f as false.  They count everything else, including #t, pairs, symbols, numbers, strings, vectors, and procedures as true (but see True and False).

Programmers accustomed to other dialects of Lisp should note that Scheme distinguishes #f and the empty list from the symbol nil. Similarly, #t is distinguished from the symbol t.  In fact, the boolean objects (and the empty list) are not symbols at all.

Boolean constants evaluate to themselves, so you don't need to quote them.

     #t                                      =>  #t
     #f                                      =>  #f
     '#f                                     =>  #f
     t                                       error--> Unbound variable

 -- variable+: false
 -- variable+: true
     These variables are bound to the objects #f and #t respectively.  The compiler, given some standard declarations, replaces references to these variables with their respective values.

     Note that the symbol true is not equivalent to #t, and the symbol false is not equivalent to #f.

 -- procedure: boolean? object
     Returns #t if OBJECT is either #t or #f; otherwise returns #f.

          (boolean? #f)                           =>  #t
          (boolean? 0)                            =>  #f

 -- procedure: not object
 -- procedure+: false? object
     These procedures return #t if OBJECT is false; otherwise they return #f.  In other words they invert boolean values.  These two procedures have identical semantics; their names are different to give different connotations to the test.

          (not #t)                                =>  #f
          (not 3)                                 =>  #f
          (not (list 3))                          =>  #f
          (not #f)                                =>  #t

 -- procedure+: boolean=? obj1 obj2
     This predicate is true iff OBJ1 and OBJ2 are either both true or both false.

 -- procedure+: boolean/and object ...
     This procedure returns #t if none of its arguments are #f. Otherwise it returns #f.

 -- procedure+: boolean/or object ...
     This procedure returns #f if all of its arguments are #f. Otherwise it returns #t.

Symbols
=======

MIT Scheme provides two types of symbols: interned and uninterned.  Interned symbols are far more common than uninterned symbols, and there are more ways to create them.  Interned symbols have an external representation that is recognized by the procedure read; uninterned symbols do not. (In older dialects of Lisp, uninterned symbols were fairly important.  This was true because symbols were complicated data structures: in addition to having value cells (and sometimes, function cells), these structures contained property lists.  Because of this, uninterned symbols were often used merely for their property lists --- sometimes an uninterned symbol used this way was referred to as a disembodied property list.  In MIT Scheme, symbols do not have property lists, or any other components besides their names.  There is a different data structure similar to disembodied property lists: one-dimensional tables (see 1D Tables). For these reasons, uninterned symbols are not very useful in MIT Scheme. In fact, their primary purpose is to simplify the generation of unique variable names in programs that generate Scheme code.)

Interned symbols have an extremely useful property: any two interned symbols whose names are the same, in the sense of string=?, are the same object (i.e. they are eqv? to one another).  The term interned refers to the process of interning by which this is accomplished.  Uninterned symbols do not share this property.

The names of interned symbols are not distinguished by their alphabetic case.  Because of this, MIT Scheme converts all alphabetic characters in the name of an interned symbol to a specific case (lower case) when the symbol is created.  When the name of an interned symbol is referenced (using symbol->string) or written (using write) it appears in this case.  It is a bad idea to depend on the name being lower case.  In fact, it is preferable to take this one step further: don't depend on the name of a symbol being in a uniform case.

The rules for writing an interned symbol are the same as the rules for writing an identifier (see Identifiers).  Any interned 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?).

Usually it is also true that reading in an interned symbol that was previously written out produces the same symbol.  An exception are symbols created by the procedures string->symbol and intern; they can create symbols for which this write/read invariance may not hold because the symbols' names contain special characters or letters in the non-standard case. (MIT Scheme reserves a specific set of interned symbols for its own use.  If you use these reserved symbols it is possible that you could break specific pieces of software that depend on them.  The reserved symbols all have names beginning with the characters #[ and ending with the character ]; thus none of these symbols can be read by the procedure read and hence are not likely to be used by accident. For example, (intern "#[unnamed-procedure]") produces a reserved symbol.)

The external representation for uninterned symbols is special, to distinguish them from interned symbols and prevent them from being recognized by the read procedure:

     (string->uninterned-symbol "foo")
          =>  #[uninterned-symbol 30 foo]

In this section, the procedures that return symbols as values will either always return interned symbols, or always return uninterned symbols.  The procedures that accept symbols as arguments will always accept either interned or uninterned symbols, and do not distinguish the two.

 -- procedure: symbol? object
     Returns #t if OBJECT is a symbol, otherwise returns #f.

          (symbol? 'foo)                                  =>  #t
          (symbol? (car '(a b)))                          =>  #t
          (symbol? "bar")                                 =>  #f

 -- procedure: symbol->string symbol
     Returns the name of SYMBOL as a string.  If SYMBOL was returned by string->symbol, the value of this procedure will be identical (in the sense of string=?) to the string that was passed to string->symbol.  It is an error to apply mutation procedures such as string-set! to strings returned by this procedure.

          (symbol->string 'flying-fish)           =>  "flying-fish"
          (symbol->string 'Martin)                =>  "martin"
          (symbol->string (string->symbol "Malvina"))
                                                  =>  "Malvina"

     Note that two distinct uninterned symbols can have the same name.

 -- procedure+: intern string
     Returns the interned symbol whose name is STRING.  Converts STRING to the standard alphabetic case before generating the symbol.  This is the preferred way to create interned symbols, as it guarantees the following independent of which case the implementation uses for symbols' names:

          (eq? 'bitBlt (intern "bitBlt")) =>     #t

     The user should take care that STRING obeys the rules for identifiers (see Identifiers), otherwise the resulting symbol cannot be read as itself.

 -- procedure: string->symbol string
     Returns the interned symbol whose name is STRING.  Although you can use this procedure to create symbols with names containing special characters or lowercase letters, it's usually a bad idea to create such symbols because they cannot be read as themselves.  See symbol->string.

          (eq? 'mISSISSIppi 'mississippi)         =>  #t
          (string->symbol "mISSISSIppi")
               =>  the symbol with the 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

 -- procedure+: string->uninterned-symbol string
     Returns a newly allocated uninterned symbol whose name is STRING. It is unimportant what case or characters are used in STRING.

     Note: this is the fastest way to make a symbol.

 -- procedure+: generate-uninterned-symbol [object]
     Returns a newly allocated uninterned symbol that is guaranteed not to be eqv? to any other object in the Scheme system.  The symbol's name consists of a string (initially "G") followed by an integer that is incremented on every call (the integer is initially 0).  The optional OBJECT can be an integer or a symbol.  If OBJECT is a symbol, the string prefix of all subsequently generated symbol names will be that symbol's name.  If OBJECT is an integer, the integer suffix of all subsequently generated symbol names will start counting from that value.

          (generate-uninterned-symbol)
               =>  #[uninterned-symbol 31 g0]
          (generate-uninterned-symbol)
               =>  #[uninterned-symbol 32 g1]
          (generate-uninterned-symbol 'this)
               =>  #[uninterned-symbol 33 this2]
          (generate-uninterned-symbol)
               =>  #[uninterned-symbol 34 this3]
          (generate-uninterned-symbol 100)
               =>  #[uninterned-symbol 35 this100]
          (generate-uninterned-symbol)
               =>  #[uninterned-symbol 36 this101]

 -- procedure+: symbol-append symbol ...
     Returns the interned symbol whose name is formed by concatenating the names of the given symbols.  This procedure preserves the case of the names of its arguments, so if one or more of the arguments' names has non-standard case, the result will also have non-standard case.

          (symbol-append 'foo- 'bar)              =>  foo-bar
          ;; the arguments may be uninterned:
          (symbol-append 'foo- (string->uninterned-symbol "baz"))
                                                  =>  foo-baz
          ;; the result has the same case as the arguments:
          (symbol-append 'foo- (string->symbol "BAZ"))    =>  foo-BAZ

 -- procedure+: symbol-hash symbol
     Returns a hash number for SYMBOL, which is computed by calling string-hash on SYMBOL's name.

Cells
=====

Cells are data structures similar to pairs except that they have only one element.  They are useful for managing state.

 -- procedure+: cell? object
     Returns #t if OBJECT is a cell; otherwise returns #f.

 -- procedure+: make-cell object
     Returns a newly allocated cell whose contents is OBJECT.

 -- procedure+: cell-contents cell
     Returns the current contents of CELL.

 -- procedure+: set-cell-contents! cell object
     Alters the contents of CELL to be OBJECT.  Returns an unspecified value.

 -- procedure+: bind-cell-contents! cell object thunk
     Alters the contents of CELL to be OBJECT, calls THUNK with no arguments, then restores the original contents of CELL and returns the value returned by THUNK.  This is completely equivalent to fluid binding of a variable, including the behavior when continuations are used (see Fluid Binding).

Records
=======

MIT Scheme provides a record abstraction, which is a simple and flexible mechanism for building structures with named components. Records can be defined and accessed using the procedures defined in this section.  A less flexible but more concise way to manipulate records is to use the define-structure special form (see Structure Definitions).

 -- procedure+: make-record-type type-name field-names
     Returns a record-type descriptor, a value representing a new data type, disjoint from all others.  The TYPE-NAME argument must be a string, but is only used for debugging purposes (such as the printed representation of a record of the new type).  The FIELD-NAMES argument is a list of symbols naming the fields of a record of the new type.  It is an error if the list contains any duplicates.  It is unspecified how record-type descriptors are represented.

 -- procedure+: record-constructor record-type [field-names]
     Returns a procedure for constructing new members of the type represented by RECORD-TYPE.  The returned procedure accepts exactly as many arguments as there are symbols in the given list, FIELD-NAMES; these are used, in order, as the initial values of those fields in a new record, which is returned by the constructor procedure.  The values of any fields not named in the list of FIELD-NAMES are unspecified. The FIELD-NAMES argument defaults to the list of field-names in the call to make-record-type that created the type represented by RECORD-TYPE; if the FIELD-NAMES argument is provided, it is an error if it contains any duplicates or any symbols not in the default list.

 -- procedure+: record-predicate record-type
     Returns a procedure for testing membership in the type represented by RECORD-TYPE.  The returned procedure accepts exactly one argument and returns #t if the argument is a member of the indicated record type; it returns #f otherwise.

 -- procedure+: record-accessor record-type field-name
     Returns a procedure for reading the value of a particular field of a member of the type represented by RECORD-TYPE.  The returned procedure accepts exactly one argument which must be a record of the appropriate type; it returns the current value of the field named by the symbol FIELD-NAME in that record.  The symbol FIELD-NAME must be a member of the list of field names in the call to make-record-type that created the type represented by RECORD-TYPE.

 -- procedure+: record-modifier record-type field-name
     Returns a procedure for writing the value of a particular field of a member of the type represented by RECORD-TYPE.  The returned procedure accepts exactly two arguments: first, a record of the appropriate type, and second, an arbitrary Scheme value; it modifies the field named by the symbol FIELD-NAME in that record to contain the given value.  The returned value of the modifier procedure is unspecified.  The symbol FIELD-NAME must be a member of the list of field names in the call to make-record-type that created the type represented by RECORD-TYPE.

     For compatibility with old code, record-updater is a synonym for this procedure.

 -- procedure+: record? object
     Returns #t if OBJECT is a record of any type and #f otherwise.  Note that record? may be true of any Scheme value; of course, if it returns #t for some particular value, then record-type-descriptor is applicable to that value and returns an appropriate descriptor.

 -- procedure+: record-type-descriptor record
     Returns the record-type descriptor representing the type of RECORD.  That is, for example, if the returned descriptor were passed to record-predicate, the resulting predicate would return #t when passed RECORD.  Note that it is not necessarily the case that the returned descriptor is the one that was passed to record-constructor in the call that created the constructor procedure that created RECORD.

 -- procedure+: record-type? object
     Returns #t if OBJECT is a record-type descriptor; otherwise returns #f.

 -- procedure+: record-type-name record-type
     Returns the type name associated with the type represented by RECORD-TYPE.  The returned value is eqv? to the TYPE-NAME argument given in the call to make-record-type that created the type represented by RECORD-TYPE.

 -- procedure+: record-type-field-names record-type
     Returns a list of the symbols naming the fields in members of the type represented by RECORD-TYPE.  The returned value is equal? to the FIELD-NAMES argument given in the call to make-record-type that created the type represented by RECORD-TYPE. (In MIT Scheme, the returned list is always newly allocated.)

Promises
========

 -- special form: delay expression
     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.

 -- procedure: force promise
     Forces the value of promise.  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 without any recomputation.

          (force (delay (+ 1 2)))                 =>  3

          (let ((p (delay (+ 1 2))))
            (list (force p) (force p)))           =>  (3 3)

          (define head car)

          (define tail
            (lambda (stream)
              (force (cdr stream))))

          (define a-stream
            (letrec ((next
                      (lambda (n)
                        (cons n (delay (next (+ n 1)))))))
              (next 0)))

          (head (tail (tail a-stream)))           =>  2

 -- procedure+: promise? object
     Returns #t if OBJECT is a promise; otherwise returns #f.

 -- procedure+: promise-forced? promise
     Returns #t if PROMISE has been forced and its value cached; otherwise returns #f.

 -- procedure+: promise-value promise
     If PROMISE has been forced and its value cached, this procedure returns the cached value.  Otherwise, an error is signalled.

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 the value of a promise is computed at most once.

     (define count 0)

     (define p
       (delay
        (begin
          (set! count (+ count 1))
          (* x 3))))

     (define x 5)

     count                                   =>  0
     p                                       =>  #[promise 54]
     (force p)                               =>  15
     p                                       =>  #[promise 54]
     count                                   =>  1
     (force p)                               =>  15
     count                                   =>  1

Here is a possible implementation of delay and force.  We define the expression

     (delay EXPRESSION)

to have the same meaning as the procedure call

     (make-promise (lambda () EXPRESSION))

where make-promise is defined as follows:

     (define make-promise
       (lambda (proc)
         (let ((already-run? #f)
               (result #f))
           (lambda ()
             (cond ((not already-run?)
                    (set! result (proc))
                    (set! already-run? #t)))
             result))))

Promises are implemented here as procedures of no arguments, and force simply calls its argument.

     (define force
       (lambda (promise)
         (promise)))

Various extensions to this semantics of delay and force are supported in some implementations (none of these are currently supported in MIT Scheme):

  * 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 #f, depending on the implementation:

          (eqv? (delay 1) 1)              =>  unspecified
          (pair? (delay (cons 1 2)))      =>  unspecified

  * Some implementations will implement ``implicit forcing'', where the value of a promise is forced by primitive procedures like car and +:

          (+ (delay (* 3 7)) 13)          =>  34

Streams
=======

In addition to promises, MIT Scheme supports a higher-level abstraction called streams.  Streams are similar to lists, except that the tail of a stream is not computed until it is referred to. This allows streams to be used to represent infinitely long lists.

 -- procedure+: stream object ...
     Returns a newly allocated stream whose elements are the arguments.  Note that the expression (stream) returns the empty stream, or end-of-stream marker. (The variable the-empty-stream, which is bound to the end-of-stream marker, is provided for compatibility with old code; use (stream) in new code.)

 -- procedure+: list->stream list
     Returns a newly allocated stream whose elements are the elements of LIST.  Equivalent to (apply stream LIST).

 -- procedure+: stream->list stream
     Returns a newly allocated list whose elements are the elements of STREAM.  If STREAM has infinite length this procedure will not terminate.  This could have been defined by

          (define (stream->list stream)
            (if (stream-null? stream)
                '()
                (cons (stream-car stream)
                      (stream->list (stream-cdr stream)))))

 -- special form+: cons-stream object expression
     Returns a newly allocated stream pair.  Equivalent to (cons OBJECT (delay EXPRESSION)).

 -- procedure+: stream-pair? object
     Returns #t if OBJECT is a pair whose cdr contains a promise.  Otherwise returns #f.  This could have been defined by

          (define (stream-pair? object)
            (and (pair? object)
                 (promise? (cdr object))))

 -- procedure+: stream-car stream
 -- procedure+: stream-first stream
     Returns the first element in STREAM.  stream-car is equivalent to car. (head, a synonym for stream-car, is provided for compatibility with old code; use stream-car in new code.)  stream-first is a synonym for stream-car.

 -- procedure+: stream-cdr stream
 -- procedure+: stream-rest stream
     Returns the first tail of STREAM.  Equivalent to (force (cdr STREAM)). (tail, a synonym for stream-cdr, is provided for compatibility with old code; use stream-cdr in new code.)  stream-rest is a synonym for stream-cdr.

 -- procedure+: stream-null? stream
     Returns #t if STREAM is the end-of-stream marker; otherwise returns #f.  This is equivalent to null?, but should be used whenever testing for the end of a stream. (empty-stream?, a synonym for stream-null?, is provided for compatibility with old code; use stream-null? in new code.)

 -- procedure+: stream-length stream
     Returns the number of elements in STREAM.  If STREAM has an infinite number of elements this procedure will not terminate.  Note that this procedure forces all of the promises that comprise STREAM.

 -- procedure+: stream-ref stream k
     Returns the element of STREAM that is indexed by K; that is, the Kth element.  K must be an exact non-negative integer strictly less than the length of STREAM.

 -- procedure+: stream-tail stream k
     Returns the tail of STREAM that is indexed by K; that is, the Kth tail.  This is equivalent to performing stream-cdr K times.  K must be an exact non-negative integer strictly less than the length of STREAM.

 -- procedure+: stream-map stream procedure
     Returns a newly allocated stream, each element being the result of invoking PROCEDURE with the corresponding element of STREAM as its argument.  PROCEDURE must be a procedure of one argument.

Weak Pairs
==========

Weak pairs are a mechanism for building data structures that point at objects without protecting them from garbage collection.  The car of a weak pair holds its pointer weakly, while the cdr holds its pointer in the normal way.  If the object in the car of a weak pair is not held normally by any other data structure, it will be garbage-collected.

Note: weak pairs are not pairs; that is, they do not satisfy the predicate pair?.

 -- procedure+: weak-pair? object
     Returns #t if OBJECT is a weak pair; otherwise returns #f.

 -- procedure+: weak-cons car cdr
     Allocates and returns a new weak pair, with components CAR and CDR.  The CAR component is held weakly.

 -- procedure+: weak-pair/car? weak-pair
     This predicate returns #f if the car of WEAK-PAIR has been garbage-collected; otherwise returns #t.  In other words, it is true if WEAK-PAIR has a valid car component.

 -- procedure+: weak-car weak-pair
     Returns the car component of WEAK-PAIR.  If the car component has been garbage-collected, this operation returns #f, but it can also return #f if that is the value that was stored in the car.

Normally, weak-pair/car? is used to determine if weak-car would return a valid value.  An obvious way of doing this would be:

     (if (weak-pair/car? x)
         (weak-car x)
         ...)

However, since a garbage collection could occur between the call to weak-pair/car? and weak-car, this would not always work correctly.  Instead, the following should be used, which always works:

     (or (weak-car x)
         (and (not (weak-pair/car? x))
              ...))

The reason that the latter expression works is that weak-car returns #f in just two instances: when the car component is #f, and when the car component has been garbage-collected.  In the former case, if a garbage collection happens between the two calls, it won't matter, because #f will never be garbage-collected.  And in the latter case, it also won't matter, because the car component no longer exists and cannot be affected by the garbage collector.

 -- procedure+: weak-set-car! weak-pair object
     Sets the car component of WEAK-PAIR to OBJECT and returns an unspecified result.

 -- procedure+: weak-cdr weak-pair
     Returns the cdr component of WEAK-CDR.

 -- procedure+: weak-set-cdr! weak-pair object
     Sets the cdr component of WEAK-PAIR to OBJECT and returns an unspecified result.

Associations
************

MIT Scheme provides several mechanisms for associating objects with one another.  Each of these mechanisms creates a link between one or more objects, called keys, and some other object, called a datum.  Beyond this common idea, however, each of the mechanisms has various different properties that make it appropriate in different situations:

  * Association lists are one of Lisp's oldest association mechanisms. Because they are made from ordinary pairs, they are easy to build and manipulate, and very flexible in use.  However, the average lookup time for an association list is linear in the number of associations.

  * 1D tables have a very simple interface, making them easy to use, and offer the feature that they do not prevent their keys from being reclaimed by the garbage collector.  Like association lists, their average lookup time is linear in the number of associations; but 1D tables aren't as flexible.

  * The association table is MIT Scheme's equivalent to the property lists of Lisp.  It has the advantages that the keys may be any type of object and that it does not prevent the keys from being reclaimed by the garbage collector.  However, two linear-time lookups must be performed, one for each key, whereas for traditional property lists only one is lookup required for both keys.

  * Hash tables are a powerful mechanism with constant-time access to large amounts of data.  Hash tables are not as flexible as association lists, but because their access times are independent of the number of associations in the table, for most applications they are the mechanism of choice.

  * Balanced binary trees are another association mechanism that is useful for applications in which the keys are ordered.  Binary trees have access times that are proportional to the logarithm of the number of associations in the tree.  While they aren't as fast as hash tables, they offer the advantage that the contents of the tree can be converted to a sorted alist in linear time.  Additionally, two trees can be compared for equality in worst-case linear time.

  * Red-Black trees are a kind of balanced binary tree.  The implementation supports destructive insertion and deletion operations with a good constant factor.

  * Weight-Balanced trees are a kind of balanced binary trees.  The implementation provides non-destructive operations.  There is a comprehensive set of operations including a constant time size operation, many high-level operations such as the set operations union, intersection and difference, and indexing of elements by position.

Association Lists
=================

An association list, or alist, is a data structure used very frequently in Scheme.  An alist is a list of pairs, each of which is called an association.  The car of an association is called the key.

An advantage of the alist representation is that an alist can be incrementally augmented simply by adding new entries to the front. Moreover, because the searching procedures assv et al. search the alist in order, new entries can ``shadow'' old entries.  If an alist is viewed as a mapping from keys to data, then the mapping can be not only augmented but also altered in a non-destructive manner by adding new entries to the front of the alist. (This introduction is taken from Common Lisp, The Language, second edition, p. 431.)

 -- procedure+: alist? object
     Returns #t if OBJECT is an association list (including the empty list); otherwise returns #f.  Any OBJECT satisfying this predicate also satisfies list?.

 -- procedure: assq object alist
 -- procedure: assv object alist
 -- procedure: assoc object alist
     These procedures find the first pair in ALIST whose car field is OBJECT, and return that pair; the returned pair is always an element of ALIST, not one of the pairs from which ALIST is composed.  If no pair in ALIST has OBJECT as its car, #f (n.b.: not the empty list) is returned.  assq uses eq? to compare OBJECT with the car fields of the pairs in ALIST, while assv uses eqv? and assoc uses equal?. (Although they are often used as predicates, assq, assv, and assoc do not have question marks in their names because they return useful values rather than just #t or #f.)

          (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)

 -- procedure+: association-procedure predicate selector
     Returns an association procedure that is similar to assv, except that SELECTOR (a procedure of one argument) is used to select the key from the association, and PREDICATE (an equivalence predicate) is used to compare the key to the given item.  This can be used to make association lists whose elements are, say, vectors instead of pairs (also see Searching Lists).

     For example, here is how assv could be implemented:

          (define assv (association-procedure eqv? car))

     Another example is a ``reverse association'' procedure:

          (define rassv (association-procedure eqv? cdr))

 -- procedure+: del-assq object alist
 -- procedure+: del-assv object alist
 -- procedure+: del-assoc object alist
     These procedures return a newly allocated copy of ALIST in which all associations with keys equal to OBJECT have been removed. Note that while the returned copy is a newly allocated list, the association pairs that are the elements of the list are shared with ALIST, not copied.  del-assq uses eq? to compare OBJECT with the keys, while del-assv uses eqv? and del-assoc uses equal?.

          (define a
            '((butcher . "231 e22nd St.")
              (baker . "515 w23rd St.")
              (hardware . "988 Lexington Ave.")))

          (del-assq 'baker a)
               =>
               ((butcher . "231 e22nd St.")
                (hardware . "988 Lexington Ave."))

 -- procedure+: del-assq! object alist
 -- procedure+: del-assv! object alist
 -- procedure+: del-assoc! object alist
     These procedures remove from ALIST all associations with keys equal to OBJECT.  They return the resulting list. del-assq! uses eq? to compare OBJECT with the keys, while del-assv! uses eqv? and del-assoc! uses equal?.  These procedures are like del-assq, del-assv, and del-assoc, respectively, except that they destructively modify ALIST.

 -- procedure+: delete-association-procedure deletor predicate selector
     This returns a deletion procedure similar to del-assv or del-assq!.  The PREDICATE and SELECTOR arguments are the same as those for association-procedure, while the DELETOR argument should be either the procedure list-deletor (for non-destructive deletions), or the procedure list-deletor! (for destructive deletions).

     For example, here is a possible implementation of del-assv:

          (define del-assv
            (delete-association-procedure list-deletor eqv? car))

 -- procedure+: alist-copy alist
     Returns a newly allocated copy of ALIST.  This is similar to list-copy except that the ``association'' pairs, i.e. the elements of the list ALIST, are also copied.  alist-copy could have been implemented like this:

          (define (alist-copy alist)
            (if (null? alist)
                '()
                (cons (cons (car (car alist)) (cdr (car alist)))
                      (alist-copy (cdr alist)))))

1D Tables
=========

1D tables (``one-dimensional'' tables) are similar to association lists.  In a 1D table, unlike an association list, the keys of the table are held weakly: if a key is garbage-collected, its associated value in the table is removed.  1D tables compare their keys for equality using eq?.

1D tables can often be used as a higher-performance alternative to the two-dimensional association table (see The Association Table).  If one of the keys being associated is a compound object such as a vector, a 1D table can be stored in one of the vector's slots.  Under these circumstances, accessing items in a 1D table will be comparable in performance to using a property list in a conventional Lisp.

 -- procedure+: make-1d-table
     Returns a newly allocated empty 1D table.

 -- procedure+: 1d-table? object
     Returns #t if OBJECT is a 1D table, otherwise returns #f.  Any object that satisfies this predicate also satisfies list?.

 -- procedure+: 1d-table/put! 1d-table key datum
     Creates an association between KEY and DATUM in 1D-TABLE.  Returns an unspecified value.

 -- procedure+: 1d-table/remove! 1d-table key
     Removes any association for KEY in 1D-TABLE and returns an unspecified value.

 -- procedure+: 1d-table/get 1d-table key default
     Returns the DATUM associated with KEY in 1D-TABLE.  If there is no association for KEY, DEFAULT is returned.

 -- procedure+: 1d-table/lookup 1d-table key if-found if-not-found
     IF-FOUND must be a procedure of one argument, and IF-NOT-FOUND must be a procedure of no arguments.  If 1D-TABLE contains an association for KEY, IF-FOUND is invoked on the DATUM of the association.  Otherwise, IF-NOT-FOUND is invoked with no arguments.  In either case, the result of the invoked procedure is returned as the result of 1d-table/lookup.

 -- procedure+: 1d-table/alist 1d-table
     Returns a newly allocated association list that contains the same information as 1D-TABLE.

The Association Table
=====================

MIT Scheme provides a generalization of the property-list mechanism found in most other implementations of Lisp: a global two-dimensional association table.  This table is indexed by two keys, called X-KEY and Y-KEY in the following procedure descriptions. These keys and the datum associated with them can be arbitrary objects. eq? is used to discriminate keys.

Think of the association table as a matrix: a single datum can be accessed using both keys, a column using X-KEY only, and a row using Y-KEY only.

 -- procedure+: 2d-put! x-key y-key datum
     Makes an entry in the association table that associates DATUM with X-KEY and Y-KEY.  Returns an unspecified result.

 -- procedure+: 2d-remove! x-key y-key
     If the association table has an entry for X-KEY and Y-KEY, it is removed.  Returns an unspecified result.

 -- procedure+: 2d-get x-key y-key
     Returns the DATUM associated with X-KEY and Y-KEY. Returns #f if no such association exists.

 -- procedure+: 2d-get-alist-x x-key
     Returns an association list of all entries in the association table that are associated with X-KEY.  The result is a list of (Y-KEY . DATUM) pairs.  Returns the empty list if no entries for X-KEY exist.

          (2d-put! 'foo 'bar 5)
          (2d-put! 'foo 'baz 6)
          (2d-get-alist-x 'foo)                   =>  ((baz . 6) (bar . 5))

 -- procedure+: 2d-get-alist-y y-key
     Returns an association list of all entries in the association table that are associated with Y-KEY.  The result is a list of (X-KEY . DATUM) pairs.  Returns the empty list if no entries for Y-KEY exist.

          (2d-put! 'bar 'foo 5)
          (2d-put! 'baz 'foo 6)
          (2d-get-alist-y 'foo)                   =>  ((baz . 6) (bar . 5))

Hash Tables
===========

Hash tables are a fast, powerful mechanism for storing large numbers of associations.  MIT Scheme's hash tables feature automatic resizing, customizable growth parameters, and customizable hash procedures.

The average times for the insertion, deletion, and lookup operations on a hash table are bounded by a constant.  The space required by the table is proportional to the number of associations in the table; the constant of proportionality is described below (see Resizing of Hash Tables).

The hash-table implementation is a run-time-loadable option.  To use hash tables, execute

     (load-option 'hash-table)

once before calling any of the procedures defined here.

Construction of Hash Tables
---------------------------

The next few procedures are hash-table constructors.  All hash table constructors are procedures that accept one optional argument, INITIAL-SIZE, and return a newly allocated hash table.  If INITIAL-SIZE is given, it must be an exact non-negative integer or #f.  The meaning of INITIAL-SIZE is discussed below (see Resizing of Hash Tables).

Hash tables are normally characterized by two things: the equivalence predicate that is used to compare keys, and whether or not the table allows its keys to be reclaimed by the garbage collector.  If a table prevents its keys from being reclaimed by the garbage collector, it is said to hold its keys strongly; otherwise it holds its keys weakly (see Weak Pairs).

 -- procedure+: make-eq-hash-table [initial-size]
     Returns a newly allocated hash table that accepts arbitrary objects as keys, and compares those keys with eq?.  The keys are held weakly.  These are the fastest of the standard hash tables.

     For compatibility with old code, make-symbol-hash-table is a synonym for this procedure.

 -- procedure+: make-eqv-hash-table [initial-size]
     Returns a newly allocated hash table that accepts arbitrary objects as keys, and compares those keys with eqv?.  The keys are held weakly, except that booleans, characters, and numbers are held strongly. These hash tables are a little slower than those made by make-eq-hash-table.

     For compatibility with old code, make-object-hash-table is a synonym for this procedure.

 -- procedure+: make-equal-hash-table [initial-size]
     Returns a newly allocated hash table that accepts arbitrary objects as keys, and compares those keys with equal?.  The keys are held strongly.  These hash tables are quite a bit slower than those made by make-eq-hash-table.

 -- procedure+: make-string-hash-table [initial-size]
     Returns a newly allocated hash table that accepts character strings as keys, and compares them with string=?.  The keys are held strongly.

The next two procedures are used to create new hash-table constructors. All of the above hash table constructors, with the exception of make-eqv-hash-table, could have been created by calls to these ``constructor-constructors''; see the examples below.

 -- procedure+: strong-hash-table/constructor key-hash key=? [rehash-after-gc?]
 -- procedure+: weak-hash-table/constructor key-hash key=? [rehash-after-gc?]
     Each of these procedures accepts two arguments and returns a hash-table constructor.  The KEY=? argument is an equivalence predicate for the keys of the hash table.  The KEY-HASH argument is a procedure that computes a hash number.  Specifically, KEY-HASH accepts two arguments, a key and an exact positive integer (the modulus), and returns an exact non-negative integer that is less than the modulus.

     The optional argument REHASH-AFTER-GC?, if true, says that the values returned by KEY-HASH might change after a garbage collection.  If so, the hash-table implementation arranges for the table to be rehashed when necessary.  (see Address Hashing, for information about hash procedures that have this property.)  Otherwise, it is assumed that KEY-HASH always returns the same value for the same arguments.  The default value of this argument is #f.

     The constructors returned by strong-hash-table/constructor make hash tables that hold their keys strongly.  The constructors returned by weak-hash-table/constructor make hash tables that hold their keys weakly.

Some examples showing how some standard hash-table constructors could have been defined:

     (define make-eq-hash-table
       (weak-hash-table/constructor eq-hash-mod eq? #t))

     (define make-equal-hash-table
       (strong-hash-table/constructor equal-hash-mod equal? #t))

     (define make-string-hash-table
       (strong-hash-table/constructor string-hash-mod string=? #f))

The following procedure is sometimes useful in conjunction with weak hash tables.  Normally it is not needed, because such hash tables clean themselves automatically as they are used.

 -- procedure+: hash-table/clean! hash-table
     If HASH-TABLE is a type of hash table that holds its KEYs weakly, this procedure recovers any space that was being used to record associations for objects that have been reclaimed by the garbage collector.  Otherwise, this procedure does nothing.  In either case, it returns an unspecified result.

Basic Hash Table Operations
---------------------------

The procedures described in this section are the basic operations on hash tables.  They provide the functionality most often needed by programmers.  Subsequent sections describe other operations that provide additional functionality needed by some applications.

 -- procedure+: hash-table? object
     Returns #t if OBJECT is a hash table, otherwise returns #f.

 -- procedure+: hash-table/put! hash-table key datum
     Associates DATUM with KEY in HASH-TABLE and returns an unspecified result.  The average time required by this operation is bounded by a constant.

 -- procedure+: hash-table/get hash-table key default
     Returns the datum associated with KEY in HASH-TABLE.  If there is no association for KEY, DEFAULT is returned.  The average time required by this operation is bounded by a constant.

 -- procedure+: hash-table/remove! hash-table key
     If HASH-TABLE has an association for KEY, removes it. Returns an unspecified result.  The average time required by this operation is bounded by a constant.

 -- procedure+: hash-table/clear! hash-table
     Removes all associations in HASH-TABLE and returns an unspecified result.  The average and worst-case times required by this operation are bounded by a constant.

 -- procedure+: hash-table/count hash-table
     Returns the number of associations in HASH-TABLE as an exact non-negative integer.  If HASH-TABLE holds its keys weakly, this is a conservative upper bound that may count some associations whose keys have recently been reclaimed by the garbage collector.  The average and worst-case times required by this operation are bounded by a constant.

 -- procedure+: hash-table->alist hash-table
     Returns the contents of HASH-TABLE as a newly allocated alist. Each element of the alist is a pair (KEY . DATUM) where KEY is one of the keys of HASH-TABLE, and DATUM is its associated datum.  The average and worst-case times required by this operation are linear in the number of associations in the table.

 -- procedure+: hash-table/key-list hash-table
     Returns a newly allocated list of the keys in HASH-TABLE.  The average and worst-case times required by this operation are proportional to the number of associations in the table.

 -- procedure+: hash-table/datum-list hash-table
     Returns a newly allocated list of the datums in HASH-TABLE.  Each element of the list corresponds to one of the associations in HASH-TABLE; if the table contains multiple associations with the same datum, so will this list.  The average and worst-case times required by this operation are proportional to the number of associations in the table.

 -- procedure+: hash-table/for-each hash-table procedure
     PROCEDURE must be a procedure of two arguments.  Invokes PROCEDURE once for each association in HASH-TABLE, passing the association's KEY and DATUM as arguments, in that order. Returns an unspecified result.  PROCEDURE must not modify HASH-TABLE, with one exception: it is permitted to call hash-table/remove! to remove the association being processed.

The following procedure is an alternate form of hash-table/get that is useful in some situations.  Usually, hash-table/get is preferable because it is faster.

 -- procedure+: hash-table/lookup hash-table key if-found if-not-found
     IF-FOUND must be a procedure of one argument, and IF-NOT-FOUND must be a procedure of no arguments.  If HASH-TABLE contains an association for KEY, IF-FOUND is invoked on the datum of the association.  Otherwise, IF-NOT-FOUND is invoked with no arguments.  In either case, the result yielded by the invoked procedure is returned as the result of hash-table/lookup (hash-table/lookup reduces into the invoked procedure, i.e. calls it tail-recursively).  The average time required by this operation is bounded by a constant.

Resizing of Hash Tables
-----------------------

Normally, hash tables automatically resize themselves according to need. Because of this, the programmer need not be concerned with management of the table's size.  However, some limited control over the table's size is provided, which will be discussed below.  This discussion involves two concepts, usable size and physical size, which we will now define.

The usable size of a hash table is the number of associations that the table can hold at a given time.  If the number of associations in the table exceeds the usable size, the table will automatically grow, increasing the usable size to a new value that is sufficient to hold the associations.

The physical size is an abstract measure of a hash table that specifies how much space is allocated to hold the associations of the table.  The physical size is always greater than or equal to the usable size.  The physical size is not interesting in itself; it is interesting only for its effect on the performance of the hash table.  While the average performance of a hash-table lookup is bounded by a constant, the worst-case performance is not.  For a table containing a given number of associations, increasing the physical size of the table decreases the probability that worse-than-average performance will occur.

The physical size of a hash table is statistically related to the number of associations.  However, it is possible to place bounds on the physical size, and from this to estimate the amount of space used by the table:

     (define (hash-table-space-bounds count rehash-size rehash-threshold)
       (let ((tf (/ 1 rehash-threshold)))
         (values (if (exact-integer? rehash-size)
                     (- (* count (+ 4 tf))
                        (* tf (+ rehash-size rehash-size)))
                     (* count (+ 4 (/ tf (* rehash-size rehash-size)))))
                 (* count (+ 4 tf)))))

What this formula shows is that, for a ``normal'' rehash size (that is, not an exact integer), the amount of space used by the hash table is proportional to the number of associations in the table.  The constant of proportionality varies statistically, with the low bound being

     (+ 4 (/ (/ 1 rehash-threshold) (* rehash-size rehash-size)))

and the high bound being

     (+ 4 (/ 1 rehash-threshold))

which, for the default values of these parameters, are 4.25 and 5, respectively.  Reducing the rehash size will tighten these bounds, but increases the amount of time spent resizing, so you can see that the rehash size gives some control over the time-space tradeoff of the table.

The programmer can control the size of a hash table by means of three parameters:

  * Each table's INITIAL-SIZE may be specified when the table is created.

  * Each table has a rehash size that specifies how the size of the table is changed when it is necessary to grow or shrink the table.

  * Each table has a rehash threshold that specifies the relationship of the table's physical size to its usable size.

If the programmer knows that the table will initially contain a specific number of items, INITIAL-SIZE can be given when the table is created.  If INITIAL-SIZE is an exact non-negative integer, it specifies the initial usable size of the hash table; the table will not change size until the number of items in the table exceeds INITIAL-SIZE, after which automatic resizing is enabled and INITIAL-SIZE no longer has any effect.  Otherwise, if INITIAL-SIZE is not given or is #f, the table is initialized to an unspecified size and automatic resizing is immediately enabled.

The rehash size specifies how much to increase the usable size of the hash table when it becomes full.  It is either an exact positive integer, or a real number greater than one.  If it is an integer, the new size is the sum of the old size and the rehash size.  Otherwise, it is a real number, and the new size is the product of the old size and the rehash size.  Increasing the rehash size decreases the average cost of an insertion, but increases the average amount of space used by the table.  The rehash size of a table may be altered dynamically by the application in order to optimize the resizing of the table; for example, if the table will grow quickly for a known period and afterwards will not change size, performance might be improved by using a large rehash size during the growth phase and a small one during the static phase. The default rehash size of a newly constructed hash table is 2.0.

Note well: The use of an exact positive integer for a rehash size is almost always undesirable; this option is provided solely for compatibility with the Common Lisp hash-table mechanism.  The reason for this has to do with the time penalty for resizing the hash table.  The time needed to resize a hash table is proportional to the number of associations in the table.  This resizing cost is amortized across the insertions required to fill the table to the point where it needs to grow again.  If the table grows by an amount proportional to the number of associations, then the cost of resizing and the increase in size are both proportional to the number of associations, so the amortized cost of an insertion operation is still bounded by a constant.  However, if the table grows by a constant amount, this is not true: the amortized cost of an insertion is not bounded by a constant.  Thus, using a constant rehash size means that the average cost of an insertion increases proportionally to the number of associations in the hash table.

The rehash threshold is a real number, between zero exclusive and one inclusive, that specifies the ratio between a hash table's usable size and its physical size.  Decreasing the rehash threshold decreases the probability of worse-than-average insertion, deletion, and lookup times, but increases the physical size of the table for a given usable size.  The default rehash threshold of a newly constructed hash table is 1.

 -- procedure+: hash-table/size hash-table
     Returns the usable size of HASH-TABLE as an exact positive integer.  This is the number of associations that HASH-TABLE can hold before it will grow.

 -- procedure+: hash-table/rehash-size hash-table
     Returns the rehash size of HASH-TABLE.

 -- procedure+: set-hash-table/rehash-size! hash-table x
     X must be either an exact positive integer, or a real number that is greater than one.  Sets the rehash size of HASH-TABLE to X and returns an unspecified result.  This operation adjusts the ``shrink threshold'' of the table; the table might shrink if the number of associations is less than the new threshold.

 -- procedure+: hash-table/rehash-threshold hash-table
     Returns the rehash threshold of HASH-TABLE.

 -- procedure+: set-hash-table/rehash-threshold! hash-table x
     X must be a real number between zero exclusive and one inclusive. Sets the rehash threshold of HASH-TABLE to X and returns an unspecified result.  This operation does not change the usable size of the table, but it usually changes the physical size of the table, which causes the table to be rehashed.

Address Hashing
---------------

The procedures described in this section may be used to make very efficient key-hashing procedures for arbitrary objects.  All of these procedures are based on address hashing, which uses the address of an object as its hash number.  The great advantage of address hashing is that converting an arbitrary object to a hash number is extremely fast and takes the same amount of time for any object.

The disadvantage of address hashing is that the garbage collector changes the addresses of most objects.  The hash-table implementation compensates for this disadvantage by automatically rehashing tables that use address hashing when garbage collections occur.  Thus, in order to use these procedures for key hashing, it is necessary to tell the hash-table implementation (by means of the REHASH-AFTER-GC? argument to the ``constructor-constructor'' procedure) that the hash numbers computed by your key-hashing procedure must be recomputed after a garbage collection.

 -- procedure+: eq-hash object
     This procedure returns a hash number for OBJECT.  The result is always a non-negative fixnum (and therefore an exact non-negative integer).  Two objects that are eq? to one another map to the same hash number, provided that the garbage collector does not run during or between the two calls to eq-hash.

The following procedures are the key-hashing procedures used by the standard address-hash-based hash tables.

 -- procedure+: eq-hash-mod object modulus
     This procedure is the key-hashing procedure used by make-eq-hash-table.

 -- procedure+: eqv-hash-mod object modulus
     This procedure is the key-hashing procedure used by make-eqv-hash-table.

 -- procedure+: equal-hash-mod object modulus
     This procedure is the key-hashing procedure used by make-equal-hash-table.

Low-Level Hash Table Operations
-------------------------------

The procedures in this section allow the programmer to control some of the internal structure of a hash table.  Normally, hash tables maintain associations between keys and datums using pairs or weak pairs.  These procedures allow the programmer to specify the use of some other data structure to maintain the association.  In this section, the data structure that represents an association in a hash table is called an entry.

 -- procedure+: hash-table/constructor key-hash key=? make-entry entry-valid? entry-key entry-datum set-entry-datum! [rehash-after-gc?]
     Creates and returns a hash-table constructor procedure (see Construction of Hash Tables).  The arguments to hash-table/constructor define the characteristics of the hash table as follows:

     key-hash
          The hashing procedure.  A procedure that accepts two arguments, a key and an exact positive integer (the modulus), and returns an exact non-negative integer that is less than the modulus.

     key=?
          A equivalence predicate that accepts two keys and is true iff they are the same key.  If this predicate is true of two keys, then KEY-HASH must return the same value for each of these keys (given the same modulus in both cases).

     make-entry
          A procedure that accepts a key and a datum as arguments and returns a newly allocated entry.

     entry-valid?
          A procedure that accepts an entry and returns #f iff the entry's key has been reclaimed by the garbage collector.  Instead of a procedure, this may be #t, which is equivalent to (lambda (entry) #t).

     entry-key
          A procedure that accepts an entry as an argument and returns the entry's key.

     entry-datum
          A procedure that accepts an entry as an argument and returns the entry's datum.

     set-entry-datum!
          A procedure that accepts an entry and an object as arguments, modifies the entry's datum to be the object, and returns an unspecified result.

     rehash-after-gc?
          An optional argument that, if true, says the values returned by KEY-HASH might change after a garbage collection.  If so, the hash-table implementation arranges for the table to be rehashed when necessary.  (see Address Hashing, for information about hash procedures that have this property.)  Otherwise, it is assumed that KEY-HASH always returns the same value for the same arguments. The default value of this argument is #f.

     For example, here is how the constructors for ordinary hash tables could be defined:

          (define (strong-hash-table/constructor key-hash key=?
                                                 #!optional rehash-after-gc?)
            (hash-table/constructor key-hash key=? cons #t car cdr set-cdr!
                                    (if (default-object? rehash-after-gc?)
                                        #f
                                        rehash-after-gc?)))

          (define (weak-hash-table/constructor key-hash key=?
                                               #!optional rehash-after-gc?)
            (hash-table/constructor key-hash key=? weak-cons weak-pair/car?
                                    weak-car weak-cdr weak-set-cdr!
                                    (if (default-object? rehash-after-gc?)
                                        #f
                                        rehash-after-gc?)))

 -- procedure+: hash-table/key-hash hash-table
 -- procedure+: hash-table/key=? hash-table
 -- procedure+: hash-table/make-entry hash-table
 -- procedure+: hash-table/entry-valid? hash-table
 -- procedure+: hash-table/entry-key hash-table
 -- procedure+: hash-table/entry-datum hash-table
 -- procedure+: hash-table/set-entry-datum! hash-table
     Each of these procedures corresponds to an argument of hash-table/constructor.  When called, each procedure returns the value of the corresponding argument that was used to construct HASH-TABLE.

The following procedures return the contents of a hash table as a collection of entries.  While the data structure holding the entries is newly allocated, the entries themselves are not copied.  Since hash table operations can modify these entries, the entries should be copied if it is desired to keep them while continuing to modify the table.

 -- procedure+: hash-table/entries-list hash-table
     Returns a newly allocated list of the entries in HASH-TABLE.

 -- procedure+: hash-table/entries-vector hash-table
     Returns a newly allocated vector of the entries in HASH-TABLE. Equivalent to

          (list->vector (hash-table/entries-list HASH-TABLE))

Object Hashing
==============

The MIT Scheme object-hashing facility provides a mechanism for generating a unique hash number for an arbitrary object.  This hash number, unlike an object's address, is unchanged by garbage collection. The object-hashing facility is useful in conjunction with hash tables, but it may be used for other things as well.  In particular, it is used in the generation of the written representation for some objects (see Custom Output).

All of these procedures accept an optional argument called TABLE; this table contains the object-integer associations.  If given, this argument must be an object-hash table as constructed by hash-table/make (see below).  If not given, a default table is used.

 -- procedure+: hash object [table]
     hash associates an exact non-negative integer with OBJECT and returns that integer.  If hash was previously called with OBJECT as its argument, the integer returned is the same as was returned by the previous call.  hash guarantees that distinct objects (in the sense of eq?) are associated with distinct integers.

 -- procedure+: unhash k [table]
     unhash takes an exact non-negative integer K and returns the object associated with that integer.  If there is no object associated with K, or if the object previously associated with K has been reclaimed by the garbage collector, an error of type condition-type:bad-range-argument is signalled.  In other words, if hash previously returned K for some object, and that object has not been reclaimed, it is the value of the call to unhash.

An object that is passed to hash as an argument is not protected from being reclaimed by the garbage collector.  If all other references to that object are eliminated, the object will be reclaimed. Subsequently calling unhash with the hash number of the (now reclaimed) object will signal an error.

     (define x (cons 0 0))           =>  unspecified
     (hash x)                        =>  77
     (eqv? (hash x) (hash x))        =>  #t
     (define x 0)                    =>  unspecified
     (gc-flip)                       ;force a garbage collection
     (unhash 77)                     error-->

 -- procedure+: object-hashed? object [table]
     This predicate is true if OBJECT has an associated hash number. Otherwise it is false.

 -- procedure+: valid-hash-number? k [table]
     This predicate is true if K is the hash number associated with some object.  Otherwise it is false.

The following two procedures provide a lower-level interface to the object-hashing mechanism.

 -- procedure+: object-hash object [table [insert?]]
     object-hash is like hash, except that it accepts an additional optional argument, INSERT?.  If INSERT? is supplied and is #f, object-hash will return an integer for OBJECT only if there is already an association in the table; otherwise, it will return #f.  If INSERT? is not supplied, or is not #f, object-hash always returns an integer, creating an association in the table if necessary.

     object-hash additionally treats #f differently than does hash.  Calling object-hash with #f as its argument will return an integer that, when passed to unhash, will signal an error rather than returning #f.  Likewise, valid-hash-number? will return #f for this integer.

 -- procedure+: object-unhash k [table]
     object-unhash is like unhash, except that when K is not associated with any object or was previously associated with an object that has been reclaimed, object-unhash returns #f. This means that there is an ambiguity in the value returned by object-unhash: if #f is returned, there is no way to tell if K is associated with #f or is not associated with any object at all.

Finally, this procedure makes new object-hash tables:

 -- procedure+: hash-table/make
     This procedure creates and returns a new, empty object-hash table that is suitable for use as the optional TABLE argument to the above procedures.  The returned table contains no associations.

Red-Black Trees
===============

Balanced binary trees are a useful data structure for maintaining large sets of associations whose keys are ordered.  While most applications involving large association sets should use hash tables, some applications can benefit from the use of binary trees.  Binary trees have two advantages over hash tables:

  * The contents of a binary tree can be converted to an alist, sorted by key, in time proportional to the number of associations in the tree.  A hash table can be converted into an unsorted alist in linear time; sorting it requires additional time.

  * Two binary trees can be compared for equality in linear time.  Hash tables, on the other hand, cannot be compared at all; they must be converted to alists before comparison can be done, and alist comparison is quadratic unless the alists are sorted.

MIT Scheme provides an implementation of red-black trees.  The red-black tree-balancing algorithm provides generally good performance because it doesn't try to keep the tree very closely balanced.  At any given node in the tree, one side of the node can be twice as high as the other in the worst case.  With typical data the tree will remain fairly well balanced anyway.

A red-black tree takes space that is proportional to the number of associations in the tree.  For the current implementation, the constant of proportionality is eight words per association.

Red-black trees hold their keys strongly.  In other words, if a red-black tree contains an association for a given key, that key cannot be reclaimed by the garbage collector.

The red-black tree implementation is a run-time-loadable option.  To use red-black trees, execute

     (load-option 'rb-tree)

once before calling any of the procedures defined here.

 -- procedure+: make-rb-tree key=? key<?
     This procedure creates and returns a newly allocated red-black tree. The tree contains no associations.  KEY=? and KEY<? are predicates that compare two keys and determine whether they are equal to or less than one another, respectively.  For any two keys, at most one of these predicates is true.

 -- procedure+: rb-tree? object
     Returns #t if OBJECT is a red-black tree, otherwise returns #f.

 -- procedure+: rb-tree/insert! rb-tree key datum
     Associates DATUM with KEY in RB-TREE and returns an unspecified value.  If RB-TREE already has an association for KEY, that association is replaced.  The average and worst-case times required by this operation are proportional to the logarithm of the number of assocations in RB-TREE.

 -- procedure+: rb-tree/lookup rb-tree key default
     Returns the datum associated with KEY in RB-TREE.  If RB-TREE doesn't contain an association for KEY, DEFAULT is returned.  The average and worst-case times required by this operation are proportional to the logarithm of the number of assocations in RB-TREE.

 -- procedure+: rb-tree/delete! rb-tree key
     If RB-TREE contains an association for KEY, removes it. Returns an unspecified value.  The average and worst-case times required by this operation are proportional to the logarithm of the number of assocations in RB-TREE.

 -- procedure+: rb-tree->alist rb-tree
     Returns the contents of RB-TREE as a newly allocated alist.  Each element of the alist is a pair (KEY . DATUM) where KEY is one of the keys of RB-TREE, and DATUM is its associated datum.  The alist is sorted by key according to the KEY<? argument used to construct RB-TREE.  The time required by this operation is proportional to the number of associations in the tree.

 -- procedure+: rb-tree/key-list rb-tree
     Returns a newly allocated list of the keys in RB-TREE.  The list is sorted by key according to the KEY<? argument used to construct RB-TREE.  The time required by this operation is proportional to the number of associations in the tree.

 -- procedure+: rb-tree/datum-list rb-tree
     Returns a newly allocated list of the datums in RB-TREE.  Each element of the list corresponds to one of the associations in RB-TREE, so if the tree contains multiple associations with the same datum, so will this list.  The list is sorted by the keys of the associations, even though they do not appear in the result.  The time required by this operation is proportional to the number of associations in the tree.

     This procedure is equivalent to:

          (lambda (rb-tree) (map cdr (rb-tree->alist rb-tree)))

 -- procedure+: rb-tree/equal? rb-tree-1 rb-tree-2 datum=?
     Compares RB-TREE-1 and RB-TREE-2 for equality, returning #t iff they are equal and #f otherwise.  The trees must have been constructed with the same equality and order predicates (same in the sense of eq?).  The keys of the trees are compared using the KEY=? predicate used to build the trees, while the datums of the trees are compared using the equivalence predicate DATUM=?. The worst-case time required by this operation is proportional to the number of associations in the tree.

 -- procedure+: rb-tree/empty? rb-tree
     Returns #t iff RB-TREE contains no associations.  Otherwise returns #f.

 -- procedure+: rb-tree/size rb-tree
     Returns the number of associations in RB-TREE, an exact non-negative integer.  The average and worst-case times required by this operation are proportional to the number of associations in the tree.

 -- procedure+: rb-tree/height rb-tree
     Returns the height of RB-TREE, an exact non-negative integer. This is the length of the longest path from a leaf of the tree to the root.  The average and worst-case times required by this operation are proportional to the number of associations in the tree.

     The returned value satisfies the following:

          (lambda (rb-tree)
            (let ((size (rb-tree/size rb-tree))
                  (lg (lambda (x) (/ (log x) (log 2)))))
              (<= (lg size)
                  (rb-tree/height rb-tree)
                  (* 2 (lg (+ size 1))))))

 -- procedure+: rb-tree/copy rb-tree
     Returns a newly allocated copy of RB-TREE.  The copy is identical to RB-TREE in all respects, except that changes to RB-TREE do not affect the copy, and vice versa.  The time required by this operation is proportional to the number of associations in the tree.

 -- procedure+: alist->rb-tree alist key=? key<?
     Returns a newly allocated red-black tree that contains the same associations as ALIST.  This procedure is equivalent to:

          (lambda (alist key=? key<?)
            (let ((tree (make-rb-tree key=? key<?)))
              (for-each (lambda (association)
                          (rb-tree/insert! tree
                                           (car association)
                                           (cdr association)))
                        alist)
              tree))

Weight-Balanced Trees
=====================

Balanced binary trees are a useful data structure for maintaining large sets of ordered objects or sets of associations whose keys are ordered. MIT Scheme has an comprehensive implementation of weight-balanced binary trees which has several advantages over the other data structures for large aggregates:

  * In addition to the usual element-level operations like insertion, deletion and lookup, there is a full complement of collection-level operations, like set intersection, set union and subset test, all of which are implemented with good orders of growth in time and space. This makes weight balanced trees ideal for rapid prototyping of functionally derived specifications.

  * An element in a tree may be indexed by its position under the ordering of the keys, and the ordinal position of an element may be determined, both with reasonable efficiency.

  * Operations to find and remove minimum element make weight balanced trees simple to use for priority queues.

  * The implementation is functional rather than imperative. This means that operations like `inserting' an association in a tree do not destroy the old tree, in much the same way that (+ 1 x) modifies neither the constant 1 nor the value bound to x.  The trees are referentially transparent thus the programmer need not worry about copying the trees.  Referential transparency allows space efficiency to be achieved by sharing subtrees.

These features make weight-balanced trees suitable for a wide range of applications, especially those that require large numbers of sets or discrete maps.  Applications that have a few global databases and/or concentrate on element-level operations like insertion and lookup are probably better off using hash-tables or red-black trees.

The size of a tree is the number of associations that it contains.  Weight balanced binary trees are balanced to keep the sizes of the subtrees of each node within a constant factor of each other. This ensures logarithmic times for single-path operations (like lookup and insertion).  A weight balanced tree takes space that is proportional to the number of associations in the tree.  For the current implementation, the constant of proportionality is six words per association.

Weight balanced trees can be used as an implementation for either discrete sets or discrete maps (associations).  Sets are implemented by ignoring the datum that is associated with the key.  Under this scheme if an associations exists in the tree this indicates that the key of the association is a member of the set.  Typically a value such as (), #t or #f is associated with the key.

Many operations can be viewed as computing a result that, depending on whether the tree arguments are thought of as sets or maps, is known by two different names. An example is wt-tree/member?, which, when regarding the tree argument as a set, computes the set membership operation, but, when regarding the tree as a discrete map, wt-tree/member? is the predicate testing if the map is defined at an element in its domain. Most names in this package have been chosen based on interpreting the trees as sets, hence the name wt-tree/member? rather than wt-tree/defined-at?.

The weight balanced tree implementation is a run-time-loadable option. To use weight balanced trees, execute

     (load-option 'wt-tree)

once before calling any of the procedures defined here.

Construction of Weight-Balanced Trees
-------------------------------------

Binary trees require there to be a total order on the keys used to arrange the elements in the tree.  Weight balanced trees are organized by types, where the type is an object encapsulating the ordering relation.  Creating a tree is a two-stage process.  First a tree type must be created from the predicate which gives the ordering.  The tree type is then used for making trees, either empty or singleton trees or trees from other aggregate structures like association lists.  Once created, a tree `knows' its type and the type is used to test compatibility between trees in operations taking two trees.  Usually a small number of tree types are created at the beginning of a program and used many times throughout the program's execution.

 -- procedure+: make-wt-tree-type key<?
     This procedure creates and returns a new tree type based on the ordering predicate KEY<?. KEY<? must be a total ordering, having the property that for all key values a, b and c:

          (key<? a a)                         => #f
          (and (key<? a b) (key<? b a))       => #f
          (if (and (key<? a b) (key<? b c))
              (key<? a c)
              #t)                             => #t

     Two key values are assumed to be equal if neither is less than the other by KEY<?.

     Each call to make-wt-tree-type returns a distinct value, and trees are only compatible if their tree types are eq?. A consequence is that trees that are intended to be used in binary tree operations must all be created with a tree type originating from the same call to make-wt-tree-type.

 -- variable+: number-wt-type
     A standard tree type for trees with numeric keys.  Number-wt-type could have been defined by

          (define number-wt-type (make-wt-tree-type  <))

 -- variable+: string-wt-type
     A standard tree type for trees with string keys.  String-wt-type could have been defined by

          (define string-wt-type (make-wt-tree-type  string<?))

 -- procedure+: make-wt-tree wt-tree-type
     This procedure creates and returns a newly allocated weight balanced tree.  The tree is empty, i.e. it contains no associations. WT-TREE-TYPE is a weight balanced tree type obtained by calling make-wt-tree-type; the returned tree has this type.

 -- procedure+: singleton-wt-tree wt-tree-type key datum
     This procedure creates and returns a newly allocated weight balanced tree.  The tree contains a single association, that of DATUM with KEY.  WT-TREE-TYPE is a weight balanced tree type obtained by calling make-wt-tree-type; the returned tree has this type.

 -- procedure+: alist->wt-tree tree-type alist
     Returns a newly allocated weight-balanced tree that contains the same associations as ALIST.  This procedure is equivalent to:

          (lambda (type alist)
            (let ((tree (make-wt-tree type)))
              (for-each (lambda (association)
                          (wt-tree/add! tree
                                        (car association)
                                        (cdr association)))
                        alist)
              tree))

Basic Operations on Weight-Balanced Trees
-----------------------------------------

This section describes the basic tree operations on weight balanced trees.  These operations are the usual tree operations for insertion, deletion and lookup, some predicates and a procedure for determining the number of associations in a tree.

 -- procedure+: wt-tree? object
     Returns #t if OBJECT is a weight-balanced tree, otherwise returns #f.

 -- procedure+: wt-tree/empty? wt-tree
     Returns #t if WT-TREE contains no associations, otherwise returns #f.

 -- procedure+: wt-tree/size wt-tree
     Returns the number of associations in WT-TREE, an exact non-negative integer.  This operation takes constant time.

 -- procedure+: wt-tree/add wt-tree key datum
     Returns a new tree containing all the associations in WT-TREE and the association of DATUM with KEY.  If WT-TREE already had an association for KEY, the new association overrides the old. The average and worst-case times required by this operation are proportional to the logarithm of the number of associations in WT-TREE.

 -- procedure+: wt-tree/add! wt-tree key datum
     Associates DATUM with KEY in WT-TREE and returns an unspecified value.  If WT-TREE already has an association for KEY, that association is replaced.  The average and worst-case times required by this operation are proportional to the logarithm of the number of associations in WT-TREE.

 -- procedure+: wt-tree/member? key wt-tree
     Returns #t if WT-TREE contains an association for KEY, otherwise returns #f.  The average and worst-case times required by this operation are proportional to the logarithm of the number of associations in WT-TREE.

 -- procedure+: wt-tree/lookup wt-tree key default
     Returns the datum associated with KEY in WT-TREE.  If WT-TREE doesn't contain an association for KEY, DEFAULT is returned.  The average and worst-case times required by this operation are proportional to the logarithm of the number of associations in WT-TREE.

 -- procedure+: wt-tree/delete wt-tree key
     Returns a new tree containing all the associations in WT-TREE, except that if WT-TREE contains an association for KEY, it is removed from the result.  The average and worst-case times required by this operation are proportional to the logarithm of the number of associations in WT-TREE.

 -- procedure+: wt-tree/delete! wt-tree key
     If WT-TREE contains an association for KEY the association is removed.  Returns an unspecified value.  The average and worst-case times required by this operation are proportional to the logarithm of the number of associations in WT-TREE.

Advanced Operations on Weight-Balanced Trees
--------------------------------------------

In the following the size of a tree is the number of associations that the tree contains, and a smaller tree contains fewer associations.

 -- procedure+: wt-tree/split< wt-tree bound
     Returns a new tree containing all and only the associations in WT-TREE which have a key that is less than BOUND in the ordering relation of the tree type of WT-TREE.  The average and worst-case times required by this operation are proportional to the logarithm of the size of WT-TREE.

 -- procedure+: wt-tree/split> wt-tree bound
     Returns a new tree containing all and only the associations in WT-TREE which have a key that is greater than BOUND in the ordering relation of the tree type of WT-TREE.  The average and worst-case times required by this operation are proportional to the logarithm of size of WT-TREE.

 -- procedure+: wt-tree/union wt-tree-1 wt-tree-2
     Returns a new tree containing all the associations from both trees. This operation is asymmetric: when both trees have an association for the same key, the returned tree associates the datum from WT-TREE-2 with the key.  Thus if the trees are viewed as discrete maps then wt-tree/union computes the map override of WT-TREE-1 by WT-TREE-2.  If the trees are viewed as sets the result is the set union of the arguments. The worst-case time required by this operation is proportional to the sum of the sizes of both trees. If the minimum key of one tree is greater than the maximum key of the other tree then the time required is at worst proportional to the logarithm of the size of the larger tree.

 -- procedure+: wt-tree/intersection wt-tree-1 wt-tree-2
     Returns a new tree containing all and only those associations from WT-TREE-1 which have keys appearing as the key of an association in WT-TREE-2.  Thus the associated data in the result are those from WT-TREE-1.  If the trees are being used as sets the result is the set intersection of the arguments.  As a discrete map operation, wt-tree/intersection computes the domain restriction of WT-TREE-1 to (the domain of) WT-TREE-2. The time required by this operation is never worse that proportional to the sum of the sizes of the trees.

 -- procedure+: wt-tree/difference wt-tree-1 wt-tree-2
     Returns a new tree containing all and only those associations from WT-TREE-1 which have keys that do not appear as the key of an association in WT-TREE-2.  If the trees are viewed as sets the result is the asymmetric set difference of the arguments.  As a discrete map operation, it computes the domain restriction of WT-TREE-1 to the complement of (the domain of) WT-TREE-2. The time required by this operation is never worse that proportional to the sum of the sizes of the trees.

 -- procedure+: wt-tree/subset? wt-tree-1 wt-tree-2
     Returns #t iff the key of each association in WT-TREE-1 is the key of some association in WT-TREE-2, otherwise returns #f. Viewed as a set operation, wt-tree/subset? is the improper subset predicate. A proper subset predicate can be constructed:

          (define (proper-subset? s1 s2)
            (and (wt-tree/subset? s1 s2)
                 (< (wt-tree/size s1) (wt-tree/size s2))))

     As a discrete map operation, wt-tree/subset? is the subset test on the domain(s) of the map(s).  In the worst-case the time required by this operation is proportional to the size of WT-TREE-1.

 -- procedure+: wt-tree/set-equal? wt-tree-1 wt-tree-2
     Returns #t iff for every association in WT-TREE-1 there is an association in WT-TREE-2 that has the same key, and vice versa.

     Viewing the arguments as sets wt-tree/set-equal? is the set equality predicate.  As a map operation it determines if two maps are defined on the same domain.

     This procedure is equivalent to

          (lambda (wt-tree-1 wt-tree-2)
            (and (wt-tree/subset? wt-tree-1 wt-tree-2
                 (wt-tree/subset? wt-tree-2 wt-tree-1)))

     In the worst-case the time required by this operation is proportional to the size of the smaller tree.

 -- procedure+: wt-tree/fold combiner initial wt-tree
     This procedure reduces WT-TREE by combining all the associations, using an reverse in-order traversal, so the associations are visited in reverse order.  COMBINER is a procedure of three arguments: a key, a datum and the accumulated result so far.  Provided COMBINER takes time bounded by a constant, wt-tree/fold takes time proportional to the size of WT-TREE.

     A sorted association list can be derived simply:

          (wt-tree/fold  (lambda (key datum list)
                           (cons (cons key datum) list))
                         '()
                         WT-TREE))

     The data in the associations can be summed like this:

          (wt-tree/fold  (lambda (key datum sum) (+ sum datum))
                         0
                         WT-TREE)

 -- procedure+: wt-tree/for-each action wt-tree
     This procedure traverses the tree in-order, applying ACTION to each association. The associations are processed in increasing order of their keys. ACTION is a procedure of two arguments which take the key and datum respectively of the association. Provided ACTION takes time bounded by a constant, wt-tree/for-each takes time proportional to in the size of WT-TREE. The example prints the tree:

          (wt-tree/for-each (lambda (key value)
                              (display (list key value)))
                            WT-TREE))

Indexing Operations on Weight-Balanced Trees
--------------------------------------------

Weight balanced trees support operations that view the tree as sorted sequence of associations.  Elements of the sequence can be accessed by position, and the position of an element in the sequence can be determined, both in logarthmic time.

 -- procedure+: wt-tree/index wt-tree index
 -- procedure+: wt-tree/index-datum wt-tree index
 -- procedure+: wt-tree/index-pair wt-tree index
     Returns the 0-based INDEXth association of WT-TREE in the sorted sequence under the tree's ordering relation on the keys. wt-tree/index returns the INDEXth key, wt-tree/index-datum returns the datum associated with the INDEXth key and wt-tree/index-pair returns a new pair (KEY . DATUM) which is the cons of the INDEXth key and its datum.  The average and worst-case times required by this operation are proportional to the logarithm of the number of associations in the tree.

     These operations signal an error if the tree is empty, if INDEX<0, or if INDEX is greater than or equal to the number of associations in the tree.

     Indexing can be used to find the median and maximum keys in the tree as follows:

          median:   (wt-tree/index WT-TREE (quotient (wt-tree/size WT-TREE) 2))

          maximum:  (wt-tree/index WT-TREE (-1+ (wt-tree/size WT-TREE)))

 -- procedure+: wt-tree/rank wt-tree key
     Determines the 0-based position of KEY in the sorted sequence of the keys under the tree's ordering relation, or #f if the tree has no association with for KEY.  This procedure returns either an exact non-negative integer or #f.  The average and worst-case times required by this operation are proportional to the logarithm of the number of associations in the tree.

 -- procedure+: wt-tree/min wt-tree index
 -- procedure+: wt-tree/min-datum wt-tree index
 -- procedure+: wt-tree/min-pair wt-tree index
     Returns the association of WT-TREE that has the least key under the tree's ordering relation. wt-tree/min returns the least key, wt-tree/min-datum returns the datum associated with the least key and wt-tree/min-pair returns a new pair (key . datum) which is the cons of the minimum key and its datum. The average and worst-case times required by this operation are proportional to the logarithm of the number of associations in the tree.

     These operations signal an error if the tree is empty. They could be written

          (define (wt-tree/min tree)        (wt-tree/index tree 0))
          (define (wt-tree/min-datum tree)  (wt-tree/index-datum tree 0))
          (define (wt-tree/min-pair tree)   (wt-tree/index-pair tree 0))

 -- procedure+: wt-tree/delete-min wt-tree
     Returns a new tree containing all of the associations in WT-TREE except the association with the least key under the WT-TREE's ordering relation.  An error is signalled if the tree is empty.  The average and worst-case times required by this operation are proportional to the logarithm of the number of associations in the tree.  This operation is equivalent to

          (wt-tree/delete WT-TREE (wt-tree/min WT-TREE))

 -- procedure+: wt-tree/delete-min! wt-tree
     Removes the association with the least key under the WT-TREE's ordering relation.  An error is signalled if the tree is empty.  The average and worst-case times required by this operation are proportional to the logarithm of the number of associations in the tree.  This operation is equivalent to

          (wt-tree/delete! WT-TREE (wt-tree/min WT-TREE))

Procedures
**********

Procedures are created by evaluating lambda expressions (see Lambda Expressions); the lambda may either be explicit or may be implicit as in a ``procedure define'' (see Definitions).  Also there are special built-in procedures, called primitive procedures, such as car; these procedures are not written in Scheme but in the language used to implement the Scheme system.  MIT Scheme also provides application hooks, which support the construction of data structures that act like procedures.

In MIT Scheme, the written representation of a procedure tells you the type of the procedure (compiled, interpreted, or primitive):

     pp
          =>  #[compiled-procedure 56 ("pp" #x2) #x10 #x307578]
     (lambda (x) x)
          =>  #[compound-procedure 57]
     (define (foo x) x)
     foo
          =>  #[compound-procedure 58 foo]
     car
          =>  #[primitive-procedure car]
     (call-with-current-continuation (lambda (x) x))
          =>  #[continuation 59]

Note that interpreted procedures are called ``compound'' procedures (strictly speaking, compiled procedures are also compound procedures). The written representation makes this distinction for historical reasons, and may eventually change.

Procedure Operations
====================

 -- procedure: apply procedure object object ...
     Calls PROCEDURE with the elements of the following list as arguments:

          (cons* OBJECT OBJECT ...)

     The initial OBJECTs may be any objects, but the last OBJECT (there must be at least one OBJECT) must be a list.

          (apply + (list 3 4 5 6))                =>  18
          (apply + 3 4 '(5 6))                    =>  18

          (define compose
            (lambda (f g)
              (lambda args
                (f (apply g args)))))
          ((compose sqrt *) 12 75)                =>  30

 -- procedure+: procedure? object
     Returns #t if OBJECT is a procedure; otherwise returns #f.  If #t is returned, exactly one of the following predicates is satisfied by OBJECT: compiled-procedure?, compound-procedure?, or primitive-procedure?.

 -- procedure+: compiled-procedure? object
     Returns #t if OBJECT is a compiled procedure; otherwise returns #f.

 -- procedure+: compound-procedure? object
     Returns #t if OBJECT is a compound (i.e. interpreted) procedure; otherwise returns #f.

 -- procedure+: primitive-procedure? object
     Returns #t if OBJECT is a primitive procedure; otherwise returns #f.

The following two procedures test the arity of a procedure, that is, the number of arguments that the procedure accepts.  The results of the test may be less restrictive than the effect of calling the procedure.  In other words, these procedures may indicate that the procedure will accept a given number of arguments, but if you call the procedure it may signal a condition-type:wrong-number-of-arguments error.  This is because these procedures examine the apparent arity of a procedure.  For example, here is a procedure that appears to accept any number of arguments, but when called will signal an error if the number of arguments is not one:

     (lambda arguments (apply car arguments))

 -- procedure+: procedure-arity-valid? procedure k
     Returns #t if PROCEDURE accepts K arguments; otherwise returns #f.

 -- procedure+: procedure-arity procedure
     Returns a description of the number of arguments that PROCEDURE accepts.  The result is a newly allocated pair whose car field is the minimum number of arguments, and whose cdr field is the maximum number of arguments.  The minimum is an exact non-negative integer.  The maximum is either an exact non-negative integer, or #f meaning that the procedure has no maximum number of arguments.

          (procedure-arity (lambda () 3))         =>  (0 . 0)
          (procedure-arity (lambda (x) x))        =>  (1 . 1)
          (procedure-arity car)                   =>  (1 . 1)
          (procedure-arity (lambda x x))          =>  (0 . #f)
          (procedure-arity (lambda (x . y) x))    =>  (1 . #f)
          (procedure-arity (lambda (x #!optional y) x))
                                                  =>  (1 . 2)

 -- procedure+: procedure-environment procedure
     Returns the closing environment of PROCEDURE.  Signals an error if PROCEDURE is a primitive procedure, or if PROCEDURE is a compiled procedure for which the debugging information is unavailable.

Primitive Procedures
====================

 -- procedure+: make-primitive-procedure name [arity]
     NAME must be a symbol.  ARITY must be an exact non-negative integer, -1, #f, or #t; if not supplied it defaults to #f.  Returns the primitive procedure called NAME.  May perform further actions depending on ARITY:

     #f
          If the primitive procedure is not implemented, signals an error.

     #t
          If the primitive procedure is not implemented, returns #f.

     integer
          If the primitive procedure is implemented, signals an error if its arity is not equal to ARITY.  If the primitive procedure is not implemented, returns an unimplemented primitive procedure object that accepts ARITY arguments.  An ARITY of -1 means it accepts any number of arguments.

 -- procedure+: primitive-procedure-name primitive-procedure
     Returns the name of PRIMITIVE-PROCEDURE, a symbol.

          (primitive-procedure-name car)          =>  car

 -- procedure+: implemented-primitive-procedure? primitive-procedure
     Returns #t if PRIMITIVE-PROCEDURE is implemented; otherwise returns #f.  Useful because the code that implements a particular primitive procedure is not necessarily linked into the executable Scheme program.

Continuations
=============

 -- procedure: call-with-current-continuation procedure
     PROCEDURE must be a procedure of one argument.  Packages up the current continuation (see below) as an escape procedure and passes it as an argument to PROCEDURE.  The escape procedure is a Scheme procedure of one argument that, if it is later passed a value, will ignore whatever continuation is in effect at that later time and will give the value instead to the continuation that was in effect when the escape procedure was created.  The escape procedure created by call-with-current-continuation 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 uses of this procedure. If all real programs 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

     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 quite useful for implementing a wide variety of advanced control structures.

     Whenever a Scheme expression is evaluated a continuation exists that wants 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, the continuation will 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 don't think much about them.  On the rare occasions that you may need to deal explicitly with continuations, call-with-current-continuation lets you do so by creating a procedure that acts just like the current continuation.

 -- procedure+: continuation? object
     Returns #t if OBJECT is a continuation; otherwise returns #f.

 -- procedure+: within-continuation continuation thunk
     CONTINUATION must be a continuation produced by call-with-current-continuation. THUNK must be a procedure of no arguments. Conceptually, within-continuation invokes continuation on the result of invoking thunk, but thunk is executed in the dynamic context of continuation.  In other words, the ``current'' continuation is abandoned before thunk is invoked.

 -- procedure+: dynamic-wind before-thunk action-thunk after-thunk
     This facility is a generalization of Common Lisp unwind-protect, designed to take into account the fact that continuations produced by call-with-current-continuation may be reentered.  The arguments BEFORE-THUNK, ACTION-THUNK, and AFTER-THUNK must all be procedures of no arguments (thunks).

     dynamic-wind behaves as follows.  First BEFORE-THUNK is called.  Then ACTION-THUNK is called.  Finally, AFTER-THUNK is called.  The value returned by ACTION-THUNK is returned as the result of dynamic-wind.  AFTER-THUNK is also called if ACTION-THUNK escapes from its continuation.  If ACTION-THUNK captures its continuation as an escape procedure, escapes from it, then escapes back to it, AFTER-THUNK is invoked when escaping away, and BEFORE-THUNK is invoked when escaping back.

     dynamic-wind is useful, for example, for ensuring the proper maintenance of locks: locking would occur in the BEFORE-THUNK, protected code would appear in the ACTION-THUNK, and unlocking would occur in the AFTER-THUNK.

The following two procedures support multiple values.  A future revision of the Scheme standard will support a facility similar to, but almost certainly different from, this one.

 -- procedure+: call-with-values thunk procedure
     THUNK must be a procedure of no arguments, and PROCEDURE must be a procedure.  THUNK is invoked with a continuation that expects to receive multiple values; specifically, the continuation expects to receive the same number of values that PROCEDURE accepts as arguments.  THUNK must return multiple values using the values procedure.  Then PROCEDURE is called with the multiple values as its arguments.  The result yielded by PROCEDURE is returned as the result of call-with-values.

 -- procedure+: values object ...
     Returns multiple values.  The continuation in effect when this procedure is called must be a multiple-value continuation that was created by call-with-values.  Furthermore it must accept as many values as there are OBJECTs.

Application Hooks
=================

Application hooks are objects that can be applied like procedures. Each application hook has two parts: a procedure that specifies what to do when the application hook is applied, and an arbitrary object, called extra.  Often the procedure uses the extra object to determine what to do.

There are two kinds of application hooks, which differ in what arguments are passed to the procedure.  When an apply hook is applied, the procedure is passed exactly the same arguments that were passed to the apply hook.  When an entity is applied, the entity itself is passed as the first argument, followed by the other arguments that were passed to the entity.

Both apply hooks and entities satisfy the predicate procedure?. Each satisfies either compiled-procedure?, compound-procedure?, or primitive-procedure?, depending on its procedure component.  An apply hook is considered to accept the same number of arguments as its procedure, while an entity is considered to accept one less argument than its procedure.

 -- procedure+: make-apply-hook procedure object
     Returns a newly allocated apply hook with a procedure component of PROCEDURE and an extra component of OBJECT.

 -- procedure+: apply-hook? object
     Returns #t if OBJECT is an apply hook; otherwise returns #f.

 -- procedure+: apply-hook-procedure apply-hook
     Returns the procedure component of APPLY-HOOK.

 -- procedure+: set-apply-hook-procedure! apply-hook procedure
     Changes the procedure component of APPLY-HOOK to be PROCEDURE.  Returns an unspecified value.

 -- procedure+: apply-hook-extra apply-hook
     Returns the extra component of APPLY-HOOK.

 -- procedure+: set-apply-hook-extra! apply-hook object
     Changes the extra component of APPLY-HOOK to be OBJECT. Returns an unspecified value.

 -- procedure+: make-entity procedure object
     Returns a newly allocated entity with a procedure component of PROCEDURE and an extra component of OBJECT.

 -- procedure+: entity? object
     Returns #t if OBJECT is an entity; otherwise returns #f.

 -- procedure+: entity-procedure entity
     Returns the procedure component of ENTITY.

 -- procedure+: set-entity-procedure! entity procedure
     Changes the procedure component of ENTITY to be PROCEDURE. Returns an unspecified value.

 -- procedure+: entity-extra entity
     Returns the extra component of ENTITY.

 -- procedure+: set-entity-extra! entity object
     Changes the extra component of ENTITY to be OBJECT.  Returns an unspecified value.

Environments
************

Environment Operations
======================

Environments are first-class objects in MIT Scheme.  An environment consists of some bindings and possibly a parent environment, from which other bindings are inherited.  The operations in this section reveal the frame-like structure of environments by permitting you to examine the bindings of a particular environment separately from those of its parent.

 -- procedure+: environment? object
     Returns #t if OBJECT is an environment; otherwise returns #f.

 -- procedure+: environment-has-parent? environment
     Returns #t if ENVIRONMENT has a parent environment; otherwise returns #f.

 -- procedure+: environment-parent environment
     Returns the parent environment of ENVIRONMENT.  It is an error if ENVIRONMENT has no parent.

 -- procedure+: environment-bound-names environment
     Returns a newly allocated list of the names (symbols) that are bound by ENVIRONMENT.  This does not include the names that are bound by the parent environment of ENVIRONMENT.

 -- procedure+: environment-bindings environment
     Returns a newly allocated list of the bindings of ENVIRONMENT; does not include the bindings of the parent environment. Each element of this list takes one of two forms: (NAME) indicates that NAME is bound but unassigned, while (NAME OBJECT) indicates that NAME is bound, and its value is OBJECT.

 -- procedure+: environment-bound? environment symbol
     Returns #t if SYMBOL is bound in ENVIRONMENT or one of its ancestor environments; otherwise returns #f.

 -- procedure+: environment-lookup environment symbol
     SYMBOL must be bound in ENVIRONMENT or one of its ancestor environments.  Returns the value to which it is bound.

 -- procedure+: environment-assignable? environment symbol
     SYMBOL must be bound in ENVIRONMENT or one of its ancestor environments.  Returns #t if the binding may be modified by side effect.

 -- procedure+: environment-assign! environment symbol object
     SYMBOL must be bound in ENVIRONMENT or one of its ancestor environments, and must be assignable.  Modifies the binding to have OBJECT as its value, and returns an unspecified result.

 -- procedure+: eval expression environment
     Evaluates EXPRESSION, a list-structure representation (sometimes called s-expression representation) of a Scheme expression, in ENVIRONMENT.  You rarely need eval in ordinary programs; it is useful mostly for evaluating expressions that have been created ``on the fly'' by a program.  eval is relatively expensive because it must convert EXPRESSION to an internal form before it is executed.

          (define foo (list '+ 1 2))
          (eval foo (the-environment))            =>  3

Environment Variables
=====================

The user-initial-environment is where the top-level read-eval-print (REP) loop evaluates expressions and stores definitions.  It is a child of the system-global-environment, which is where all of the Scheme system definitions are stored.  All of the bindings in system-global-environment are available when the current environment is user-initial-environment.  However, any new bindings that you create in the REP loop (with define forms or by loading files containing define forms) occur in user-initial-environment.

 -- variable+: system-global-environment
     The variable system-global-environment is bound to the environment that's the parent of the user-initial-environment. Primitives and system procedures are bound (and sometimes closed) in this environment.

 -- variable+: user-initial-environment
     The variable user-initial-environment is bound to the default environment in which typed expressions are evaluated by the top-level REP loop.

     Although all bindings in system-global-environment are visible to the REP loop, definitions that are typed at, or loaded by, the REP loop occur in the user-initial-environment.  This is partly a safety measure: if you enter a definition that happens to have the same name as a critical system procedure, your definition will be visible only to the procedures you define in the user-initial-environment; the MIT Scheme system procedures, which are defined in the system-global-environment, will continue to see the original definition.

REPL Environment
================

 -- procedure+: nearest-repl/environment
     Returns the current REP loop environment (i.e. the current environment of the closest enclosing REP loop).  When Scheme first starts up, this is the same as user-initial-environment.

 -- procedure+: ge environment
     Changes the current REP loop environment to ENVIRONMENT. ENVIRONMENT can be either an environment or a procedure object. If it's a procedure, the environment in which that procedure was closed is the new environment.

Interpreter Environments
========================

The operations in this section return environments that are constructed by the interpreter.  These operations should only be used at the top level of a file; they are not supported in any other place.  In particular, they force the current environment to be represented in a form suitable for use by the interpreter.  This prevents the compiler from performing many useful optimizations on such environments, and forces the use of the interpreter for variable references in them. However, because all top-level environments (such as user-initial-environment) are already interpreter environments, it does no harm to use such operations on them.

 -- special form+: make-environment expression ...
     Produces a new environment that is a child of the environment in which it is executed, evaluates the EXPRESSIONs sequentially in the new environment, and returns the new environment.  Note that

          (make-environment EXPRESSION ...)

     is equivalent to:

          (let ()
            EXPRESSION ...
            (the-environment))

 -- special form+: the-environment
     Returns the current environment.

 -- procedure+: interpreter-environment? object
     Returns #t if OBJECT is an interpreter environment; otherwise returns #f.

Input/Output
************

This chapter describes the procedures that are used for input and output (I/O).  The chapter first describes ports and how they are manipulated, then describes the I/O operations.  Finally, some low-level procedures are described that permit the implementation of custom ports and high-performance I/O.

Ports
=====

Scheme uses ports for I/O.  A port, which can be treated like any other Scheme object, serves as a source or sink for data.  A port must be open before it can be read from or written to.  The standard I/O port, console-i/o-port, is opened automatically when you start Scheme.  When you use a file for input or output, you need to explicitly open and close a port to the file (with procedures described in this chapter).  Additional procedures let you open ports to strings.

Many input procedures, such as read-char and read, read data from the current input port by default, or from a port that you specify.  The current input port is initially console-i/o-port, but Scheme provides procedures that let you change the current input port to be a file or string.

Similarly, many output procedures, such as write-char and display, write data to the current output port by default, or to a port that you specify.  The current output port is initially console-i/o-port, but Scheme provides procedures that let you change the current output port to be a file or string.

All ports read or write only ASCII characters.

Every port is either an input port, an output port, or both.  The following predicates distinguish all of the possible cases.

 -- procedure+: port? object
     Returns #t if OBJECT is a port, otherwise returns #f.

 -- procedure: input-port? object
     Returns #t if OBJECT is an input port, otherwise returns #f.  Any object satisfying this predicate also satisfies port?.

 -- procedure: output-port? object
     Returns #t if OBJECT is an output port, otherwise returns #f.  Any object satisfying this predicate also satisfies port?.

 -- procedure+: i/o-port? object
     Returns #t if OBJECT is both an input port and an output port, otherwise returns #f.  Any object satisfying this predicate also satisfies port?, input-port?, and output-port?.

 -- procedure+: guarantee-input-port object
 -- procedure+: guarantee-output-port object
 -- procedure+: guarantee-i/o-port object
     These procedures check the type of OBJECT, signalling an error of type condition-type:wrong-type-argument if it is not an input port, output port, or I/O port, respectively.  Otherwise they return OBJECT.

The next five procedures return the runtime system's standard ports.  All of the standard ports are dynamically bound by the REP loop; this means that when a new REP loop is started, for example by an error, each of these ports is dynamically bound to the I/O port of the REP loop.  When the REP loop exits, the ports revert to their original values.

 -- procedure: current-input-port
     Returns the current input port.  This is the default port used by many input procedures.  Initially, current-input-port returns the value of console-i/o-port.

 -- procedure: current-output-port
     Returns the current output port.  This is the default port used by many output procedures.  Initially, current-output-port returns the value of console-i/o-port.

 -- procedure+: notification-output-port
     Returns an output port suitable for generating ``notifications'', that is, messages to the user that supply interesting information about the execution of a program.  For example, the load procedure writes messages to this port informing the user that a file is being loaded. Initially, notification-output-port returns the value of console-i/o-port.

 -- procedure+: trace-output-port
     Returns an output port suitable for generating ``tracing'' information about a program's execution.  The output generated by the trace procedure is sent to this port.  Initially, trace-output-port returns the value of console-i/o-port.

 -- procedure+: interaction-i/o-port
     Returns an I/O port suitable for querying or prompting the user. The standard prompting procedures use this port by default (see Prompting).  Initially, interaction-i/o-port returns the value of console-i/o-port.

 -- procedure+: with-input-from-port input-port thunk
 -- procedure+: with-output-to-port output-port thunk
 -- procedure+: with-notification-output-port output-port thunk
 -- procedure+: with-trace-output-port output-port thunk
 -- procedure+: with-interaction-i/o-port i/o-port thunk
     THUNK must be a procedure of no arguments.  Each of these procedures binds one of the standard ports to its first argument, calls THUNK with no arguments, restores the port to its original value, and returns the result that was yielded by THUNK.  This temporary binding is performed the same way as fluid binding of a variable, including the behavior in the presence of continuations (see Fluid Binding).

     with-input-from-port binds the current input port, with-output-to-port binds the current output port, with-notification-output-port binds the ``notification'' output port, with-trace-output-port binds the ``trace'' output port, and with-interaction-i/o-port binds the ``interaction'' I/O port.

 -- procedure+: set-current-input-port! input-port
 -- procedure+: set-current-output-port! output-port
 -- procedure+: set-notification-output-port! output-port
 -- procedure+: set-trace-output-port! output-port
 -- procedure+: set-interaction-i/o-port! i/o-port
     Each of these procedures alters the binding of one of the standard ports and returns an unspecified value.  The binding that is modified corresponds to the name of the procedure.

 -- variable+: console-i/o-port
     console-i/o-port is an I/O port that communicates with the ``console''.  Under unix, the console is the controlling terminal of the Scheme process.  Under MS-DOS, the console is a combination of the keyboard and the display.  Under Windows, the console is the window that is created when Scheme starts up.

     This variable is rarely used; instead programs should use one of the standard ports defined above.  This variable should not be modified.

     For compatibility with old code, console-input-port and console-output-port are synonyms for this variable.

 -- procedure+: close-port port
 -- procedure: close-input-port port
 -- procedure: close-output-port port
     Closes PORT and returns an unspecified value.  If PORT is a file port, the file is closed.  close-input-port and close-output-port are synonyms for close-port that are defined for compatibility with standard Scheme.

File Ports
==========

Before Scheme can access a file for reading or writing, it is necessary to open a port to the file.  This section describes procedures used to open ports to files.  Such ports are closed (like any other port) by close-port.  File ports are automatically closed if and when they are reclaimed by the garbage collector.

Before opening a file for input or output, by whatever method, the FILENAME argument is converted to canonical form by calling the procedure merge-pathnames with FILENAME as its sole argument.  Thus, FILENAME can be either a string or a pathname, and it is merged with the current pathname defaults to produce the pathname that is then opened.

Any file can be opened in one of two modes, normal or binary.  Normal mode is for accessing text files, and binary mode is for accessing other files.  Some operating systems, e.g. unix, do not distinguish these modes.  MS-DOS is an example of an operating system that does distinguish these modes: in normal mode, MS-DOS file ports perform newline translation, mapping between the carriage-return/linefeed sequence that terminates text lines in files, and the #\newline that terminates lines in Scheme.  In binary mode, MS-DOS ports do not perform newline translation.  Unless otherwise mentioned, the procedures in this section open files in normal mode.

 -- procedure: open-input-file filename
     Takes a filename referring to an existing file and returns an input port capable of delivering characters from the file.  If the file cannot be opened, an error of type condition-type:file-operation-error is signalled.

 -- procedure: open-output-file filename [append?]
     Takes a filename referring to 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 of type condition-type:file-operation-error is signalled.

     The optional argument APPEND? is an MIT Scheme extension.  If APPEND? is given and not #f, the file is opened in append mode.  In this mode, the contents of the file are not overwritten; instead any characters written to the file are appended to the end of the existing contents.  If the file does not exist, append mode creates the file and writes to it in the normal way.

 -- procedure+: open-i/o-file filename
     Takes a filename referring to an existing file and returns an I/O port capable of both reading and writing the file.  If the file cannot be opened, an error of type condition-type:file-operation-error is signalled.

     This procedure is often used to open special files.  For example, under unix this procedure can be used to open terminal device files, PTY device files, and named pipes.

 -- procedure+: open-binary-input-file filename
 -- procedure+: open-binary-output-file filename [append?]
 -- procedure+: open-binary-i/o-file filename
     These procedures open files in binary mode.  In all other respects they are identical to open-input-file, open-output-file, and open-i/o-file, respectively.

 -- procedure+: close-all-open-files
     This procedure closes all file ports that are open at the time that it is called, and returns an unspecified value.

 -- procedure: call-with-input-file filename procedure
 -- procedure: call-with-output-file filename procedure
     These procedures call PROCEDURE with one argument: the port obtained by opening the named file for input or output, respectively. If the file cannot be opened, an error of type condition-type:file-operation-error is signalled.  If PROCEDURE returns, then the port is closed automatically and the value yielded by PROCEDURE is returned.  If PROCEDURE does not return, then the port will not be closed automatically unless it is reclaimed by the garbage collector. (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+: call-with-binary-input-file filename procedure
 -- procedure+: call-with-binary-output-file filename procedure
     These procedures open files in binary mode.  In all other respects they are identical to call-with-input-file and call-with-output-file, respectively.

 -- procedure: with-input-from-file filename thunk
 -- procedure: with-output-to-file filename thunk
     THUNK must be a procedure of no arguments. 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 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 the value yielded by THUNK.  If an escape procedure is used to escape from the continuation of these procedures, their behavior is implementation-dependent; in that situation MIT Scheme leaves the files open.

 -- procedure+: with-input-from-binary-file filename thunk
 -- procedure+: with-output-to-binary-file filename thunk
     These procedures open files in binary mode.  In all other respects they are identical to with-input-from-file and with-output-to-file, respectively.

String Ports
============

This section describes the simplest kinds of ports: input ports that read their input from given strings, and output ports that accumulate their output and return it as a string.  It also describes ``truncating'' output ports, which can limit the length of the resulting string to a given value.

 -- procedure+: string->input-port string [start [end]]
     Returns a new string port that delivers characters from STRING. The optional arguments START and END may be used to specify that the string port delivers characters from a substring of STRING; if not given, START defaults to 0 and END defaults to (string-length STRING).

 -- procedure+: with-input-from-string string thunk
     THUNK must be a procedure of no arguments. with-input-from-string creates a new input port that reads from STRING, makes that port the current input port, and calls THUNK.  When THUNK returns, with-input-from-string restores the previous current input port and returns the result yielded by THUNK.

          (with-input-from-string "(a b c) (d e f)" read)  =>  (a b c)

     Note: this procedure is equivalent to:

          (with-input-from-port (string->input-port STRING) THUNK)

 -- procedure+: with-string-output-port procedure
     PROCEDURE is called with one argument, an output port.  The value yielded by PROCEDURE is ignored.  When PROCEDURE returns, with-string-output-port returns the accumulated output to the port as a newly allocated string.

 -- procedure+: with-output-to-string thunk
     THUNK must be a procedure of no arguments. with-output-to-string creates a new output port that accumulates output, makes that port the default value returned by current-output-port, and calls THUNK with no arguments. When THUNK returns, with-output-to-string restores the previous default and returns the accumulated output as a newly allocated string.

          (with-output-to-string
            (lambda ()
              (write 'abc)))                    =>  "abc"

     Note: this procedure is equivalent to:

          (with-string-output-port
           (lambda (port)
             (with-output-to-port port THUNK)))

 -- procedure+: with-output-to-truncated-string k thunk
     Similar to with-output-to-string, except that the output is limited to K characters.  If THUNK attempts to write more than K characters, it will be aborted by invoking an escape procedure that returns from with-output-to-truncated-string.

     The value of this procedure is a pair; the car of the pair is #t if THUNK attempted to write more than K characters, and #f otherwise.  The cdr of the pair is a newly allocated string containing the accumulated output.

     This procedure is helpful for displaying circular lists, as shown in this example:

          (define inf (list 'inf))
          (with-output-to-truncated-string 40
            (lambda ()
              (write inf)))                       =>  (#f . "(inf)")
          (set-cdr! inf inf)
          (with-output-to-truncated-string 40
            (lambda ()
              (write inf)))
                  =>  (#t . "(inf inf inf inf inf inf inf inf inf inf")

 -- procedure+: write-to-string object [k]
     Writes OBJECT to a string output port, and returns the resulting newly allocated string.  If K is supplied and not #f, this procedure is equivalent to

          (with-output-to-truncated-string K
            (lambda ()
              (write OBJECT)))

     otherwise it is equivalent to

          (with-output-to-string
           (lambda ()
             (write OBJECT)))

Input Procedures
================

This section describes the procedures that read input.  Input procedures can read either from the current input port or from a given port. Remember that to read from a file, you must first open a port to the file.

Input ports can be divided into two types, called interactive and non-interactive.  Interactive input ports are ports that read input from a source that is time-dependent; for example, a port that reads input from a terminal or from another program.  Non-interactive input ports read input from a time-independent source, such as an ordinary file or a character string.

All optional arguments called INPUT-PORT, if not supplied, default to the current input port.

 -- procedure: read-char [input-port]
     Returns the next character available from INPUT-PORT, updating INPUT-PORT to point to the following character.  If no more characters are available, an end-of-file object is returned.

     In MIT Scheme, if INPUT-PORT is an interactive input port and no characters are immediately available, read-char will hang waiting for input.

 -- procedure: peek-char [input-port]
     Returns the next character available from INPUT-PORT, without updating INPUT-PORT to point to the following character.  If no more characters are available, an end-of-file object is returned. (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 on the same port.  The only difference is that the very next call to read-char or peek-char on that INPUT-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.)

     In MIT Scheme, if INPUT-PORT is an interactive input port and no characters are immediately available, peek-char will hang waiting for input.

 -- procedure: char-ready? [input-port]
     Returns #t if a character is ready on INPUT-PORT and returns #f otherwise.  If char-ready? returns #t then the next read-char operation on INPUT-PORT is guaranteed not to hang.  If INPUT-PORT is a file port at end of file then char-ready? returns #t. (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 make sure 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.)

 -- procedure: read [input-port]
     Converts external representations of Scheme objects into the objects themselves.  read returns the next object parsable from INPUT-PORT, updating INPUT-PORT to point to the first character past the end of the written representation of the object.  If an end of file is encountered in the input before any characters are found that can begin an object, read returns an end-of-file object.  The INPUT-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 written representation, but the written representation is incomplete and therefore not parsable, an error is signalled.

 -- procedure: eof-object? object
     Returns #t if OBJECT is an end-of-file object; otherwise returns #f.

 -- procedure+: read-char-no-hang [input-port]
     If INPUT-PORT can deliver a character without blocking, this procedure acts exactly like read-char, immediately returning that character.  Otherwise, #f is returned, unless INPUT-PORT is a file port at end of file, in which case an end-of-file object is returned.  In no case will this procedure block waiting for input.

 -- procedure+: read-string char-set [input-port]
     Reads characters from INPUT-PORT until it finds a terminating character that is a member of CHAR-SET (see Character Sets) or encounters end of file.  The port is updated to point to the terminating character, or to end of file if no terminating character was found. read-string returns the characters, up to but excluding the terminating character, as a newly allocated string.  However, if end of file was encountered before any characters were read, read-string returns an end-of-file object.

     On many input ports, this operation is significantly faster than the following equivalent code using peek-char and read-char:

          (define (read-string char-set input-port)
            (let ((char (peek-char input-port)))
              (if (eof-object? char)
                  char
                  (list->string
                   (let loop ((char char))
                     (if (or (eof-object? char)
                             (char-set-member? char-set char))
                         '()
                         (begin
                           (read-char input-port)
                           (cons char (loop (peek-char input-port))))))))))

Output Procedures
=================

Output ports may or may not support buffering of output, in which output characters are collected together in a buffer and then sent to the output device all at once.  (Most of the output ports implemented by the runtime system support buffering.)  Sending all of the characters in the buffer to the output device is called flushing the buffer.  In general, output procedures do not flush the buffer of an output port unless the buffer is full.

However, the standard output procedures described in this section perform what is called discretionary flushing of the buffer. Discretionary output flushing works as follows.  After a procedure performs its output (writing characters to the output buffer), it checks to see if the port implements an operation called discretionary-output-flush.  If so, then that operation is invoked to flush the buffer.  At present, only the console port defines discretionary-output-flush; this is used to guarantee that output to the console appears immediately after it is written, without requiring calls to flush-output.

All optional arguments called OUTPUT-PORT, if not supplied, default to the current output port.

 -- procedure+: flush-output [output-port]
     If OUTPUT-PORT is buffered, this causes the contents of its buffer to be written to the output device.  Otherwise it has no effect. Returns an unspecified value.

 -- procedure: write-char char [output-port]
     Writes CHAR (the character itself, not a written representation of the character) to OUTPUT-PORT, performs discretionary output flushing, and returns an unspecified value.

 -- procedure+: write-string string [output-port]
     Writes STRING to OUTPUT-PORT, performs discretionary output flushing, and returns an unspecified value.  This is equivalent to writing the contents of string, one character at a time using write-char, except that it is usually much faster.

 -- procedure: write object [output-port]
     Writes a written representation of OBJECT to OUTPUT-PORT, and returns an unspecified value.  If OBJECT has a standard external representation, then the written representation generated by write shall be parsable by read into an equivalent object. Thus strings that appear in the written representation are enclosed in doublequotes, and within those strings backslash and doublequote are escaped by backslashes.  write performs discretionary output flushing and returns an unspecified value.

 -- procedure: display object [output-port]
     Writes a representation of OBJECT to OUTPUT-PORT.  Strings appear in the written representation as if written by write-string instead of by write.  Character objects appear in the representation as if written by write-char instead of by write.  display performs discretionary output flushing and returns an unspecified value. (write is intended for producing machine-readable output and display is for producing human-readable output.)

 -- procedure: newline [output-port]
     Writes an end-of-line to OUTPUT-PORT, performs discretionary output flushing, and returns an unspecified value.  Equivalent to (write-char #\newline OUTPUT-PORT).

 -- procedure+: fresh-line [output-port]
     Some output ports are able to tell whether or not they are at the beginning of a line of output.  If OUTPUT-PORT is such a port, this procedure writes an end-of-line to the port only if the port is not already at the beginning of a line.  If OUTPUT-PORT is not such a port, this procedure is identical to newline.  In either case, fresh-line performs discretionary output flushing and returns an unspecified value.

 -- procedure+: write-line object [output-port]
     Like write, except that it writes an end-of-line to OUTPUT-PORT before writing OBJECT's representation.  This procedure performs discretionary output flushing and returns an unspecified value.

 -- procedure+: beep [output-port]
     Performs a ``beep'' operation on OUTPUT-PORT, performs discretionary output flushing, and returns an unspecified value.  On the console port, this usually causes the console bell to beep, but more sophisticated interactive ports may take other actions, such as flashing the screen.  On most output ports, e.g. file and string output ports, this does nothing.

 -- procedure+: clear [output-port]
     ``Clears the screen'' of OUTPUT-PORT, performs discretionary output flushing, and returns an unspecified value.  On a terminal or window, this has a well-defined effect.  On other output ports, e.g. file and string output ports, this does nothing.

 -- procedure+: pp object [output-port [as-code?]]
     pp prints OBJECT in a visually appealing and structurally revealing manner on OUTPUT-PORT.  If object is a procedure, pp attempts to print the source text.  If the optional argument AS-CODE? is true, pp prints lists as Scheme code, providing appropriate indentation; by default this argument is false.  pp performs discretionary output flushing and returns an unspecified value.

The following variables may be dynamically bound to change the behavior of the write and display procedures.

 -- variable+: *unparser-radix*
     This variable specifies the default radix used to print numbers.  Its value must be one of the exact integers 2, 8, 10, or 16; the default is 10.  If *unparser-radix* is not 10, numbers are prefixed to indicate their radix.

 -- variable+: *unparser-list-breadth-limit*
     This variable specifies a limit on the length of the printed representation of a list or vector; for example, if the limit is 4, only the first four elements of any list are printed, followed by ellipses to indicate any additional elements.  The value of this variable must be an exact non-negative integer, or #f meaning no limit; the default is #f.

          (fluid-let ((*unparser-list-breadth-limit* 4))
            (write-to-string '(a b c d)))
                                          => "(a b c d)"
          (fluid-let ((*unparser-list-breadth-limit* 4))
            (write-to-string '(a b c d e)))
                                          => "(a b c d ...)"

 -- variable+: *unparser-list-depth-limit*
     This variable specifies a limit on the nesting of lists and vectors in the printed representation.  If lists (or vectors) are more deeply nested than the limit, the part of the representation that exceeds the limit is replaced by ellipses.  The value of this variable must be an exact non-negative integer, or #f meaning no limit; the default is #f.

          (fluid-let ((*unparser-list-depth-limit* 4))
            (write-to-string '((((a))) b c d)))
                                          => "((((a))) b c d)"
          (fluid-let ((*unparser-list-depth-limit* 4))
            (write-to-string '(((((a)))) b c d)))
                                          => "((((...))) b c d)"

 -- variable+: *unparser-string-length-limit*
     This variable specifies a limit on the length of the printed representation of strings.  If a string's length exceeds this limit, the part of the printed representation for the characters exceeding the limit is replaced by ellipses.  The value of this variable must be an exact non-negative integer, or #f meaning no limit; the default is #f.

          (fluid-let ((*unparser-string-length-limit* 4))
            (write-to-string "abcd"))
                                          => "\"abcd\""
          (fluid-let ((*unparser-string-length-limit* 4))
            (write-to-string "abcde"))
                                          => "\"abcd...\""

 -- variable+: *unparse-with-maximum-readability?*
     This variable, which takes a boolean value, tells the printer to use a special printed representation for objects that normally print in a form that cannot be recognized by read.  These objects are printed using the representation #@N, where N is the result of calling hash on the object to be printed.  The reader recognizes this syntax, calling unhash on N to get back the original object.  Note that this printed representation can only be recognized by the Scheme program in which it was generated, because these hash numbers are different for each invocation of Scheme.

Format
======

The procedure format is very useful for producing nicely formatted text, producing good-looking messages, and so on.  MIT Scheme's implementation of format is similar to that of Common Lisp, except that Common Lisp defines many more directives. (This description of format is adapted from Common Lisp, The Language, second edition, section 22.3.3.)

format is a run-time-loadable option.  To use it, execute

     (load-option 'format)

once before calling it.

 -- procedure+: format destination control-string argument ...
     Writes the characters of CONTROL-STRING to DESTINATION, except that a tilde (~) introduces a format directive.  The character after the tilde, possibly preceded by prefix parameters and modifiers, specifies what kind of formatting is desired.  Most directives use one or more ARGUMENTs to create their output; the typical directive puts the next ARGUMENT into the output, formatted in some special way.  It is an error if no argument remains for a directive requiring an argument, but it is not an error if one or more arguments remain unprocessed by a directive.

     The output is sent to DESTINATION.  If DESTINATION is #f, a string is created that contains the output; this string is returned as the value of the call to format.  In all other cases format returns an unspecified value.  If DESTINATION is #t, the output is sent to the current output port.  Otherwise, DESTINATION must be an output port, and the output is sent there.

     This procedure performs discretionary output flushing (see Output Procedures).

     A format directive consists of a tilde (~), optional prefix parameters separated by commas, optional colon (:) and at-sign (@) modifiers, and a single character indicating what kind of directive this is.  The alphabetic case of the directive character is ignored.  The prefix parameters are generally integers, notated as optionally signed decimal numbers.  If both the colon and at-sign modifiers are given, they may appear in either order.

     In place of a prefix parameter to a directive, you can put the letter V (or v), which takes an ARGUMENT for use as a parameter to the directive.  Normally this should be an exact integer. This feature allows variable-width fields and the like.  You can also use the character # in place of a parameter; it represents the number of arguments remaining to be processed.

     It is an error to give a format directive more parameters than it is described here as accepting.  It is also an error to give colon or at-sign modifiers to a directive in a combination not specifically described here as being meaningful.

     ~A
          The next ARGUMENT, which may be any object, is printed as if by display.  ~MINCOLA inserts spaces on the right, if necessary, to make the width at least MINCOL columns.  The @ modifier causes the spaces to be inserted on the left rather than the right.

     ~S
          The next ARGUMENT, which may be any object, is printed as if by write.  ~MINCOLS inserts spaces on the right, if necessary, to make the width at least MINCOL columns.  The @ modifier causes the spaces to be inserted on the left rather than the right.

     ~%
          This outputs a #\newline character.  ~N% outputs N newlines.  No ARGUMENT is used.  Simply putting a newline in CONTROL-STRING would work, but ~% is often used because it make the control string look nicer in the middle of a program.

     ~~
          This outputs a tilde.  ~N~ outputs N tildes.

     ~NEWLINE
          Tilde immediately followed by a newline ignores the newline and any following non-newline whitespace characters.  With an @, the newline is left in place, but any following whitespace is ignored.  This directive is typically used when CONTROL-STRING is too long to fit nicely into one line of the program:

               (define (type-clash-error procedure arg spec actual)
                 (format #t
                         "~%Procedure ~S~%requires its %A argument ~
                          to be of type ~S,~%but it was called with ~
                          an argument of type ~S.~%"
                         procedure arg spec actual))

          (type-clash-error 'vector-ref "first" 'integer 'vector) prints:

               Procedure vector-ref
               requires its first argument to be of type integer,
               but it was called with an argument of type vector.

          Note that in this example newlines appear in the output only as specified by the ~% directives; the actual newline characters in the control string are suppressed because each is preceded by a tilde.

Custom Output
=============

MIT Scheme provides hooks for specifying that certain kinds of objects have special written representations.  There are no restrictions on the written representations, but only a few kinds of objects may have custom representation specified for them, specifically: records (see Records), vectors that have special tags in their zero-th elements (see Vectors), and pairs that have special tags in their car fields (see Lists).  There is a different procedure for specifying the written representation of each of these types.

 -- procedure+: set-record-type-unparser-method! record-type unparser-method
     Changes the unparser method of the type represented by RECORD-TYPE to be UNPARSER-METHOD, and returns an unspecified value. Subsequently, when the unparser encounters a record of this type, it will invoke UNPARSER-METHOD to generate the written representation.

 -- procedure+: unparser/set-tagged-vector-method! tag unparser-method
     Changes the unparser method of the vector type represented by TAG to be UNPARSER-METHOD, and returns an unspecified value. Subsequently, when the unparser encounters a vector with TAG as its zero-th element, it will invoke UNPARSER-METHOD to generate the written representation.

 -- procedure+: unparser/set-tagged-pair-method! tag unparser-method
     Changes the unparser method of the pair type represented by TAG to be UNPARSER-METHOD, and returns an unspecified value. Subsequently, when the unparser encounters a pair with TAG in its car field, it will invoke UNPARSER-METHOD to generate the written representation.

An unparser method is a procedure that is invoked with two arguments: an unparser state and an object.  An unparser method generates a written representation for the object, writing it to the output port specified by the unparser state.  The value yielded by an unparser method is ignored.  Note that an unparser state is not an output port, rather it is an object that contains an output port as one of its components.  Application programs generally do not construct or examine unparser state objects, but just pass them along.

There are two ways to create an unparser method (which is then registered by one of the above procedures).  The first, and easiest, is to use standard-unparser-method.  The second is to define your own method using the procedure with-current-unparser-state.  We encourage the use of the first method, as it results in a more uniform appearance for objects.  Many predefined datatypes, for example procedures and environments, already have this appearance.

 -- procedure+: standard-unparser-method name procedure
     Returns a standard unparser method.  NAME may be any object, and is used as the name of the type with which the unparser method is associated; NAME is usually a symbol.  PROCEDURE must be #f or a procedure of two arguments.

     If PROCEDURE is #f, the returned method generates an external representation of this form:

          #[NAME HASH]

     Here NAME is the external representation of the argument NAME, as generated by write, (Except that if the argument NAME is a string, its external representation is generated by write-string.) and HASH is the external representation of an exact non-negative integer unique to the object being printed (specifically, it is the result of calling hash on the object).  Subsequently, the expression

          #@HASH

     is notation for the object.

     If PROCEDURE is supplied, the returned method generates a slightly different external representation:

          #[NAME HASH OUTPUT]

     Here NAME and HASH are as above, and OUTPUT is the output generated by PROCEDURE.  The representation is constructed in three stages:

      1. The first part of the format (up to OUTPUT) is written to the output port specified by the unparser state.  This is "#[", NAME, " ", and HASH.

      2. PROCEDURE is invoked on two arguments: the object and an output port.

      3. The closing bracket is written to the output port.

The following procedure is useful for writing more general kinds of unparser methods.

 -- procedure+: with-current-unparser-state unparser-state procedure
     This procedure calls PROCEDURE with one argument, the output port from UNPARSER-STATE.  Additionally, it arranges for the remaining components of UNPARSER-STATE to be given to the printer when they are needed.  The PROCEDURE generates some output by writing to the output port using the usual output operations, and the value yielded by PROCEDURE is returned from with-current-unparser-state.

     The port passed to PROCEDURE should only be used within the dynamic extent of PROCEDURE.

Prompting
=========

This section describes procedures that prompt the user for input.  Why should the programmer use these procedures when it is possible to do prompting using ordinary input and output procedures?  One reason is that the prompting procedures are more succinct.  However, a second and better reason is that the prompting procedures can be separately customized for each user interface, providing more natural interaction. The interfaces for Edwin and for GNU Emacs have already been customized in this fashion; because Edwin and Emacs are very similar editors, their customizations provide very similar behavior.

Each of these procedure accepts an optional argument called PORT, which must be an I/O port if given.  If not given, this port defaults to the value of (interaction-i/o-port); this is initially the console I/O port.

The required argument PROMPT must be a string.

 -- procedure+: prompt-for-command-expression prompt [port]
     Prompts the user for an expression that is to be executed as a command. This is the procedure called by the REP loop to read the user's expressions.

     The prompt string is formed by appending a space to PROMPT, unless PROMPT already ends in a space or is an empty string.

     The default behavior of this procedure is to print two newlines, the current REP loop ``level number'', a space, and the prompt string; flush the output buffer; then read an object and return it.

     Under Edwin and Emacs, before the object is read, the interaction buffer is put into a mode that allows expressions to be edited and submitted for input using specific editor commands.  The first expression that is submitted is returned as the value of this procedure.

 -- procedure+: prompt-for-command-char prompt [port]
     Prompts the user for a single character that is to be executed as a command; the returned character is guaranteed to satisfy char-graphic?.  If at all possible, the character is read from the user interface using a mode that reads the character as a single keystroke; in other words, it should not be necessary for the user to follow the character with a carriage return or similar rubbish.

     This is the procedure called by debug and where to read the user's commands.

     The prompt string is formed by appending a space to PROMPT, unless PROMPT already ends in a space or is an empty string.

     The default behavior of this procedure is to print two newlines, the current REP loop ``level number'', a space, and the prompt string; flush the output buffer; read a character in raw mode, echo that character, and return it.

     Under Edwin and Emacs, instead of reading a character, the interaction buffer is put into a mode in which graphic characters submit themselves as input.  After this mode change, the first such character submitted is returned as the value of this procedure.

 -- procedure+: prompt-for-expression prompt [port]
     Prompts the user for an expression.

     The prompt string is formed by appending a colon and a space to PROMPT, unless PROMPT already ends in a space.

     The default behavior of this procedure is to print two newlines and the prompt string; flush the output buffer; then read an object and return it.

     Under Edwin and Emacs, the expression is read in the minibuffer.

 -- procedure+: prompt-for-evaluated-expression prompt [environment [port]]
     Prompts the user for an evaluated expression.  Calls prompt-for-expression to read an expression, then evaluates the expression using ENVIRONMENT; if ENVIRONMENT is not given, the REP loop environment is used.

 -- procedure+: prompt-for-confirmation prompt [port]
     Prompts the user for confirmation.  The result yielded by this procedure is a boolean.

     The prompt string is formed by appending the string " (y or n)? " to PROMPT, unless PROMPT already ends in a space.

     The default behavior of this procedure is to print two newlines and the prompt string; flush the output buffer; then read a character in raw mode.  If the character is #\y, #\Y, or #\space, the procedure returns #t; If the character is #\n, #\N, or #\rubout, the procedure returns #f. Otherwise the prompt is repeated.

     Under Edwin or Emacs, the confirmation is read in the minibuffer.

Port Primitives
===============

This section describes the low-level operations that can be used to build and manipulate I/O ports.

The purpose of these operations is twofold: to allow programmers to construct new kinds of I/O ports, and to provide faster I/O operations than those supplied by the standard high level procedures. The latter is useful because the standard I/O operations provide defaulting and error checking, and sometimes other features, which are often unnecessary.  This interface provides the means to bypass such features, thus improving performance.

The abstract model of an I/O port, as implemented here, is a combination of a set of named operations and a state.  The state is an arbitrary object, the meaning of which is determined by the operations. The operations are defined by a mapping from names to procedures. Typically the names are symbols, but any object that can be discriminated by eq? may be used.

The operations are divided into two classes:

Standard operations
     There is a specific set of standard operations for input ports, and a different set for output ports.  Applications can assume that the standard input operations are implemented for all input ports, and likewise the standard output operations are implemented for all output ports.

Custom operations
     Some ports support additional operations.  For example, ports that implement output to terminals (or windows) may define an operation named y-size that returns the height of the terminal in characters. Because only some ports will implement these operations, programs that use custom operations must test each port for their existence, and be prepared to deal with ports that do not implement them.

Constructors and Accessors for Ports
------------------------------------

The procedures in this section provide means for constructing ports with custom operations, accessing their operations, and manipulating their internal state.

 -- procedure+: make-input-port operations object
 -- procedure+: make-output-port operations object
 -- procedure+: make-i/o-port operations object
     Operations must be a list; each element is a list of two elements, the name of the operation and the procedure that implements it.  A new port is returned with the given operations and a state component of OBJECT.

     OPERATIONS need not contain definitions for all of the standard operations; the procedure will provide defaults for any standard operations that are not defined.  At a minimum, the following operations must be defined: for input ports, read-char, peek-char, and char-ready?; for output ports, either write-char or write-substring; I/O ports must supply the minimum operations for both input and output.

 -- procedure+: port/copy port object
     Returns a new copy of PORT, identical to the original except that its state component is OBJECT.  PORT is not modified.

     port/copy is normally used to speed up creation of ports.  This is done by creating a template using one of the port constructors make-input-port, make-output-port, or make-i/o-port, as appropriate; a dummy state component is supplied for the template.  Then port/copy is used to make a copy of the template, supplying the copy with the correct state.  This is useful because the port constructors are somewhat slow, as they must parse the OPERATIONS list, provide defaulting for missing operations, etc.

     For compatibility with old code, input-port/copy and output-port/copy are synonyms for this procedure.

 -- procedure+: port/state port
     Returns the state component of PORT.

     For compatibility with old code, input-port/state and output-port/state are synonyms for this procedure.

 -- procedure+: set-port/state! port object
     Changes the state component of PORT to be OBJECT. Returns an unspecified value.

     For compatibility with old code, set-input-port/state! and set-output-port/state! are synonyms for this procedure.

 -- procedure+: port/operation port object
     Returns the operation named OBJECT in PORT.  If PORT has no such operation, returns #f.

     For compatibility with old code, input-port/operation and output-port/operation are similar to port/operation.  They differ in that they translate certain old operation names to new equivalents before calling port/operation. input-port/custom-operation and output-port/custom-operation are synonyms for input-port/operation and output-port/operation, respectively.

 -- procedure+: port/operation-names port
     Returns a list whose elements are the names of the operations supported by port.  The list is not newly allocated and must not be modified.

     For compatibility with old code, input-port/operation-names and output-port/operation-names are synonyms for this procedure.

 -- procedure+: make-eof-object input-port
     Returns an object that satisfies the predicate eof-object?.  This is sometimes useful when building input ports.

Blocking Mode
-------------

An interactive port is always in one of two modes: blocking or non-blocking.  This mode is independent of the terminal mode: each can be changed independent of the other.  Furthermore, if it is an interactive I/O port, there are separate blocking modes for input and for output.

If an input port is in blocking mode, attempting to read from it when no input is available will cause Scheme to ``block'', i.e. suspend itself, until input is available.  If an input port is in non-blocking mode, attempting to read from it when no input is available will cause the reading procedure to return immediately, indicating the lack of input in some way (exactly how this situation is indicated is separately specified for each procedure or operation).

An output port in blocking mode will block if the output device is not ready to accept output.  In non-blocking mode it will return immediately after performing as much output as the device will allow (again, each procedure or operation reports this situation in its own way).

Interactive ports are initially in blocking mode; this can be changed at any time with the procedures defined in this section.

These procedures represent blocking mode by the symbol blocking, and non-blocking mode by the symbol nonblocking.  An argument called MODE must be one of these symbols.  A PORT argument to any of these procedures may be any port, even if that port does not support blocking mode; in that case, the port is not modified in any way.

 -- procedure+: port/input-blocking-mode port
     Returns the input blocking mode of PORT.

 -- procedure+: port/set-input-blocking-mode port mode
     Changes the input blocking mode of PORT to be MODE.  Returns an unspecified value.

 -- procedure+: port/with-input-blocking-mode port mode thunk
     THUNK must be a procedure of no arguments. port/with-input-blocking-mode binds the input blocking mode of PORT to be MODE, executes THUNK, restores the input blocking mode of PORT to what it was when port/with-input-blocking-mode was called, and returns the value that was yielded by THUNK.  This binding is performed by dynamic-wind, which guarantees that the input blocking mode is restored if THUNK escapes from its continuation.

 -- procedure+: port/output-blocking-mode port
     Returns the output blocking mode of PORT.

 -- procedure+: port/set-output-blocking-mode port mode
     Changes the output blocking mode of PORT to be MODE. Returns an unspecified value.

 -- procedure+: port/with-output-blocking-mode port mode thunk
     THUNK must be a procedure of no arguments. port/with-output-blocking-mode binds the output blocking mode of PORT to be MODE, executes THUNK, restores the output blocking mode of PORT to what it was when port/with-output-blocking-mode was called, and returns the value that was yielded by THUNK.  This binding is performed by dynamic-wind, which guarantees that the output blocking mode is restored if THUNK escapes from its continuation.

Terminal Mode
-------------

A port that reads from or writes to a terminal has a terminal mode; this is either cooked or raw.  This mode is independent of the blocking mode: each can be changed independent of the other.  Furthermore, a terminal I/O port has independent terminal modes both for input and for output.

A terminal port in cooked mode provides some standard processing to make the terminal easy to communicate with.  For example, under unix, cooked mode on input reads from the terminal a line at a time and provides rubout processing within the line, while cooked mode on output might translate linefeeds to carriage-return/linefeed pairs.  In general, the precise meaning of cooked mode is operating-system dependent, and furthermore might be customizable by means of operating system utilities.  The basic idea is that cooked mode does whatever is necessary to make the terminal handle all of the usual user-interface conventions for the operating system, while keeping the program's interaction with the port as normal as possible.

A terminal port in raw mode disables all of that processing.  In raw mode, characters are directly read from and written to the device without any translation or interpretation by the operating system.  On input, characters are available as soon as they are typed, and are not echoed on the terminal by the operating system.  In general, programs that put ports in raw mode have to know the details of interacting with the terminal.  In particular, raw mode is used for writing programs such as text editors.

Terminal ports are initially in cooked mode; this can be changed at any time with the procedures defined in this section.

These procedures represent cooked mode by the symbol cooked, and raw mode by the symbol raw.  Additionally, the value #f represents ``no mode''; it is the terminal mode of a port that is not a terminal.  An argument called MODE must be one of these three values.  A PORT argument to any of these procedures may be any port, even if that port does not support terminal mode; in that case, the port is not modified in any way.

 -- procedure+: port/input-terminal-mode port
     Returns the input terminal mode of PORT.

 -- procedure+: port/set-input-terminal-mode port mode
     Changes the input terminal mode of PORT to be MODE. Returns an unspecified value.

 -- procedure+: port/with-input-terminal-mode port mode thunk
     THUNK must be a procedure of no arguments. port/with-input-terminal-mode binds the input terminal mode of PORT to be MODE, executes THUNK, restores the input terminal mode of PORT to what it was when port/with-input-terminal-mode was called, and returns the value that was yielded by THUNK.  This binding is performed by dynamic-wind, which guarantees that the input terminal mode is restored if THUNK escapes from its continuation.

 -- procedure+: port/output-terminal-mode port
     Returns the output terminal mode of PORT.

 -- procedure+: port/set-output-terminal-mode port mode
     Changes the output terminal mode of PORT to be MODE. Returns an unspecified value.

 -- procedure+: port/with-output-terminal-mode port mode thunk
     THUNK must be a procedure of no arguments. port/with-output-terminal-mode binds the output terminal mode of PORT to be MODE, executes THUNK, restores the output terminal mode of PORT to what it was when port/with-output-terminal-mode was called, and returns the value that was yielded by THUNK.  This binding is performed by dynamic-wind, which guarantees that the output terminal mode is restored if THUNK escapes from its continuation.

Input Port Operations
---------------------

This section describes the standard operations on input ports.

 -- operation+ on input port: read-char input-port
     Removes the next character available from INPUT-PORT and returns it.  If INPUT-PORT has no more characters and will never have any (e.g. at the end of an input file), this operation returns an end-of-file object.  If INPUT-PORT has no more characters but will eventually have some more (e.g. a terminal where nothing has been typed recently), and it is in non-blocking mode, #f is returned; otherwise the operation hangs until input is available.

 -- operation+ on input port: peek-char input-port
     Reads the next character available from INPUT-PORT and returns it. The character is not removed from INPUT-PORT, and a subsequent attempt to read from the port will get that character again. In other respects this operation behaves like read-char.

 -- operation+ on input port: discard-char input-port
     Discards the next character available from INPUT-PORT and returns an unspecified value.  In other respects this operation behaves like read-char.

 -- operation+ on input port: char-ready? input-port k
     char-ready? returns #t if at least one character is available to be read from INPUT-PORT.  If no characters are available, the operation waits up to K milliseconds before returning #f, returning immediately if any characters become available while it is waiting.

 -- operation+ on input port: read-string input-port char-set
 -- operation+ on input port: discard-chars input-port char-set
     These operations are like read-char and discard-char, except that they read or discard multiple characters at once.  This can have a marked performance improvement on buffered input ports.  All characters up to, but excluding, the first character in CHAR-SET (or end of file) are read from INPUT-PORT.  read-string returns these characters as a newly allocated string, while discard-chars discards them and returns an unspecified value. These operations hang until sufficient input is available, even if INPUT-PORT is in non-blocking mode.  If end of file is encountered before any input characters, read-string returns an end-of-file object.

 -- procedure+: input-port/operation/read-char input-port
 -- procedure+: input-port/operation/peek-char input-port
 -- procedure+: input-port/operation/discard-char input-port
 -- procedure+: input-port/operation/char-ready? input-port
 -- procedure+: input-port/operation/read-string input-port
 -- procedure+: input-port/operation/discard-chars input-port
     Each of these procedures returns the procedure that implements the respective operation for INPUT-PORT.  Each is equivalent to, but faster than, input-port/operation on the respective operation name:

          (input-port/operation/read-char INPUT-PORT)
          (input-port/operation INPUT-PORT 'read-char)

 -- procedure+: input-port/read-char input-port
 -- procedure+: input-port/peek-char input-port
 -- procedure+: input-port/discard-char input-port
 -- procedure+: input-port/char-ready? input-port k
 -- procedure+: input-port/read-string input-port char-set
 -- procedure+: input-port/discard-chars input-port char-set
     Each of these procedures invokes the respective operation on INPUT-PORT.  For example, the following are equivalent:

          (input-port/read-string INPUT-PORT CHAR-SET)
          ((input-port/operation/read-string INPUT-PORT) INPUT-PORT CHAR-SET)

Output Port Operations
----------------------

This section describes the standard operations on output ports. Following that, some useful custom operations are described.

 -- operation+ on output port: write-char output-port char
     Writes CHAR to OUTPUT-PORT and returns an unspecified value.

 -- operation+ on output port: write-substring output-port string start end
     Writes the substring specified by STRING, START, and END to OUTPUT-PORT and returns an unspecified value. Equivalent to writing the characters of the substring, one by one, to OUTPUT-PORT, but is often implemented more efficiently.

 -- operation+ on output port: write-string output-port string
     Writes STRING to OUTPUT-PORT and returns an unspecified value.

 -- operation+ on output port: flush-output output-port
     If OUTPUT-PORT is buffered, this causes its buffer to be written out.  Otherwise it has no effect.  Returns an unspecified value.

 -- operation+ on output port: discretionary-flush-output output-port
     If OUTPUT-PORT is buffered, this causes its buffer to be written out.  Otherwise it has no effect.  Returns an unspecified value.

     This operation, if defined, is normally identical to flush-output.  However, it is not normally defined, and even when it is, it is invoked at different times (see Output Procedures).

 -- procedure+: output-port/operation/write-char output-port
 -- procedure+: output-port/operation/write-substring output-port
 -- procedure+: output-port/operation/write-string output-port
 -- procedure+: output-port/operation/flush-output output-port
 -- procedure+: output-port/operation/discretionary-flush-output output-port
     Each of these procedures returns the procedure that implements the respective operation for OUTPUT-PORT.  Each is equivalent to, but faster than, output-port/operation on the respective operation name:

          (output-port/operation/write-char OUTPUT-PORT)
          (output-port/operation OUTPUT-PORT 'write-char)

 -- procedure+: output-port/write-char output-port char
 -- procedure+: output-port/write-substring output-port string start end
 -- procedure+: output-port/write-string output-port string
 -- procedure+: output-port/flush-output output-port
 -- procedure+: output-port/discretionary-flush-output output-port
     Each of these procedures invokes the respective operation on OUTPUT-PORT.  For example, the following are equivalent:

          (output-port/write-char OUTPUT-PORT CHAR)
          ((output-port/operation/write-char OUTPUT-PORT) OUTPUT-PORT CHAR)

The following custom operations are generally useful.

 -- operation+ on output port: x-size output-port
     Returns an exact positive integer that is the width of OUTPUT-PORT in characters.  If OUTPUT-PORT has no natural width, e.g. if it is a file port, #f is returned.

 -- operation+ on output port: y-size output-port
     Returns an exact positive integer that is the height of OUTPUT-PORT in characters.  If OUTPUT-PORT has no natural height, e.g. if it is a file port, #f is returned.

 -- procedure+: output-port/x-size output-port
     This procedure invokes the custom operation whose name is the symbol x-size, if it exists.  If the x-size operation is both defined and returns a value other than #f, that value is returned as the result of this procedure.  Otherwise, output-port/x-size returns a default value (currently 79).

     output-port/x-size is useful for programs that tailor their output to the width of the display (a fairly common practice).  If the output device is not a display, such programs normally want some reasonable default width to work with, and this procedure provides exactly that.

 -- procedure+: output-port/y-size output-port
     This procedure invokes the custom operation whose name is the symbol y-size, if it exists.  If the y-size operation is defined, the value it returns is returned as the result of this procedure; otherwise, #f is returned.

File-System Interface
*********************

The Scheme standard provides a simple mechanism for reading and writing files: file ports.  MIT Scheme provides additional tools for dealing with other aspects of the file system:

  * Pathnames are a reasonably operating system independent tool for manipulating the component parts of file names.  This can be useful for implementing defaulting of file name components.

  * Control over the current working directory: the place in the file system from which relative file names are interpreted.

  * Procedures that rename, copy, delete, and test for the existence of files.  Also, procedures that return detailed information about a particular file, such as its type (directory, link, etc.) or length.

  * A facility for reading the contents of a directory.

Pathnames
=========

MIT Scheme programs need to use names to designate files.  The main difficulty in dealing with names of files is that different file systems have different naming formats for files.  For example, here is a table of several file systems (actually, operating systems that provide file systems) and what equivalent file names might look like for each one:

     System          File Name
     ------          ---------
     TOPS-20         <LISPIO>FORMAT.FASL.13
     TOPS-10         FORMAT.FAS[1,4]
     ITS             LISPIO;FORMAT FASL
     MULTICS         >udd>LispIO>format.fasl
     TENEX           <LISPIO>FORMAT.FASL;13
     VAX/VMS         [LISPIO]FORMAT.FAS;13
     UNIX            /usr/lispio/format.fasl
     MS-DOS          C:\USR\LISPIO\FORMAT.FAS

It would be impossible for each program that deals with file names to know about each different file name format that exists; a new operating system to which Scheme was ported might use a format different from any of its predecessors.  Therefore, MIT Scheme provides two ways to represent file names: filenames (also called namestrings), which are strings in the implementation-dependent form customary for the file system, and pathnames, which are special abstract data objects that represent file names in an implementation-independent way. Procedures are provided to convert between these two representations, and all manipulations of files can be expressed in machine-independent terms by using pathnames.

In order to allow MIT Scheme programs to operate in a network environment that may have more than one kind of file system, the pathname facility allows a file name to specify which file system is to be used.  In this context, each file system is called a host, in keeping with the usual networking terminology. (This introduction is adapted from Common Lisp, The Language, second edition, section 23.1.)

Note that the examples given in this section are specific to unix pathnames.  Pathnames for other operating systems have different external representations.

Filenames and Pathnames
-----------------------

Pathname objects are usually created by parsing filenames (character strings) into component parts.  MIT Scheme provides operations that convert filenames into pathnames and vice versa.

 -- procedure+: ->pathname object
     Returns a pathname that is the equivalent of OBJECT.  OBJECT must be a pathname or a string.  If OBJECT is a pathname, it is returned.  If OBJECT is a string, this procedure returns the pathname that corresponds to the string; in this case it is equivalent to (parse-namestring OBJECT #f #f).

          (->pathname "foo")              =>  #[pathname 65 "foo"]
          (->pathname "/usr/morris")      =>  #[pathname 66 "/usr/morris"]

 -- procedure+: parse-namestring thing [host [defaults]]
     This turns THING into a pathname. THING must be a pathname or a string. If THING is a pathname, it is returned.  If THING is a string, this procedure returns the pathname that corresponds to the string, parsed according to the syntax of the file system specified by HOST.

     This procedure does not do defaulting of pathname components.

     The optional arguments are used to determine what syntax should be used for parsing the string.  In general this is only really useful if your implementation of MIT Scheme supports more than one file system, otherwise you would use ->pathname.  If given, HOST must be a host object or #f, and DEFAULTS must be a pathname. HOST specifies the syntax used to parse the string.  If HOST is not given or #f, the host component from DEFAULTS is used instead; if DEFAULTS is not given, the host component from *default-pathname-defaults* is used.

 -- procedure+: ->namestring pathname
     ->namestring returns a newly allocated string that is the filename corresponding to PATHNAME.

          (->namestring (->pathname "/usr/morris/minor.van"))
               =>  "/usr/morris/minor.van"

 -- procedure+: pathname-simplify pathname
     Returns a pathname that locates the same file or directory as PATHNAME, but is in some sense simpler.  Note that pathname-simplify might not always be able to simplify the pathname, e.g. on unix with symbolic links the directory /usr/morris/../ need not be the same as /usr/.  In cases of uncertainty the behavior is conservative, returning the original or a partly simplified pathname.

          (pathname-simplify "/usr/morris/../morris/dance")
               =>  #[pathname "/usr/morris/dance"]

Components of Pathnames
-----------------------

A pathname object always has six components, described below.  These components are the common interface that allows programs to work the same way with different file systems; the mapping of the pathname components into the concepts peculiar to each file system is taken care of by the Scheme implementation.

host
     The name of the file system on which the file resides.

device
     Corresponds to the ``device'' or ``file structure'' concept in many host file systems: the name of a (logical or physical) device containing files.

directory
     Corresponds to the ``directory'' concept in many host file systems: the name of a group of related files (typically those belonging to a single user or project).

name
     The name of a group of files that can be thought of as conceptually the ``same'' file.

type
     Corresponds to the ``filetype'' or ``extension'' concept in many host file systems.  This says what kind of file this is.  Files with the same name but different type are usually related in some specific way, such as one being a source file, another the compiled form of that source, and a third the listing of error messages from the compiler.

version
     Corresponds to the ``version number'' concept in many host file systems. Typically this is a number that is incremented every time the file is modified.

Note that a pathname is not necessarily the name of a specific file. Rather, it is a specification (possibly only a partial specification) of how to access a file.  A pathname need not correspond to any file that actually exists, and more than one pathname can refer to the same file. For example, the pathname with a version of newest may refer to the same file as a pathname with the same components except a certain number as the version.  Indeed, a pathname with version newest may refer to different files as time passes, because the meaning of such a pathname depends on the state of the file system.  In file systems with such facilities as ``links'', multiple file names, logical devices, and so on, two pathnames that look quite different may turn out to address the same file.  To access a file given a pathname, one must do a file-system operation such as open-input-file.

Two important operations involving pathnames are parsing and merging.  Parsing is the conversion of a filename (which might be something supplied interactively  by the users when asked to supply the name of a file) into a pathname object.  This operation is implementation-dependent, because the format of filenames is implementation-dependent.  Merging takes a pathname with missing components and supplies values for those components from a source of default values.

Not all of the components of a pathname need to be specified.  If a component of a pathname is missing, its value is #f. Before the file system interface can do anything interesting with a file, such as opening the file, all the missing components of a pathname must be filled in.  Pathnames with missing components are used internally for various purposes; in particular, parsing a namestring that does not specify certain components will result in a pathname with missing components.

Any component of a pathname may be the symbol unspecific, meaning that the component simply does not exist, for file systems in which such a value makes no sense.  For example, unix and MS-DOS file systems usually do not support version numbers, so the version component for a unix or MS-DOS host might be unspecific. (This description is adapted from Common Lisp, The Language, second edition, section 23.1.1.)

Each component in a pathname is typically one of the following (with some exceptions that will be described below):

a string
     This is a literal component.  It is considered to be fully specified.

#f
     This is a missing component.  It is considered to be unspecified.

wild
     This is a wildcard component.  It is useful only when the pathname is being used with the directory reader, where it means that the pathname component matches anything.

unspecific
     This is an unspecifiable component.  It is treated the same as a missing component except that it is not considered to be missing for purposes of merging or defaulting components.

The host, directory, and version pathname components are exceptions to these rules in that they may never be strings, although the values #f, wild, and unspecific are allowed with their usual meanings.  Here are the other values allowed for these components:

  * The host component is of an implementation defined type which may be tested for using the host? predicate.

  * A directory, if it is not one of the above values, must be a non-empty list, which represents a directory path: a sequence of directories, each of which has a name in the previous directory, the last of which is the directory specified by the entire path.  Each element in such a path specifies the name of the directory relative to the directory specified by the elements to its left. The first element of the list is either the symbol absolute or the symbol relative.  If the first element in the list is the symbol absolute, then the directory component (and subsequently the pathname) is absolute; the first component in the sequence is to be found at the ``root'' of the file system.  If the directory is relative then the first component is to be found in some as yet unspecified directory; typically this is later specified to be the current working directory.

     Aside from absolute and relative, which may only appear as the first element of the list, each subsequent element in the list is either a string or the symbol wild (each with the same meaning as described above), or up, which means the next directory is the ``parent'' of the previous one.  up corresponds to the file .. in unix file systems.

     In file systems that do not have ``hierarchical'' structure, a specified directory component will always be a list whose first element is absolute.  If the system does not support directories other than a single global directory, the list will have no other elements.  If the system supports ``flat'' directories, i.e. a global set of directories with no subdirectories, then the list will contain a second element, which is either a string or wild.  In other words, a non-hierarchical file system is treated as if it were hierarchical, but the hierarchical features are unused.  This representation is somewhat inconvenient for such file systems, but it discourages programmers from making code depend on the lack of a file hierarchy.  Fortunately few such file systems are in common use today.

  * A version component may take the following values: an exact positive integer, which is a literal component; the symbol newest, which means to choose the largest available version number for that file; or the symbol oldest, which means to choose the smallest version number.  In the future some other possible values may be added, e.g. installed.  Note that in the current implementation there are no file systems that support version numbers; thus this component is not used and should be specified as #f.

 -- procedure+: make-pathname host device directory name type version
     Returns a pathname object whose components are the respective arguments. Each argument must satisfy the restrictions for the corresponding component, which were outlined above.

          (make-pathname #f #f '(absolute "usr" "morris") "foo" "scm" #f)
               =>  #[pathname 67 "/usr/morris/foo.scm"]

 -- procedure+: pathname-host pathname
 -- procedure+: pathname-device pathname
 -- procedure+: pathname-directory pathname
 -- procedure+: pathname-name pathname
 -- procedure+: pathname-type pathname
 -- procedure+: pathname-version pathname
     Returns a particular component of PATHNAME.

          (define x (->pathname "/usr/morris/foo.scm"))
          (pathname-host x)       =>  #[host 1]
          (pathname-device x)     =>  unspecific
          (pathname-directory x)  =>  (absolute "usr" "morris")
          (pathname-name x)       =>  "foo"
          (pathname-type x)       =>  "scm"
          (pathname-version x)    =>  unspecific

 -- procedure+: pathname-new-device pathname device
 -- procedure+: pathname-new-directory pathname directory
 -- procedure+: pathname-new-name pathname name
 -- procedure+: pathname-new-type pathname type
 -- procedure+: pathname-new-version pathname version
     Returns a new copy of PATHNAME with the respective component replaced by the second argument.  PATHNAME is unchanged. Portable programs should not explicitly replace a component with unspecific because this might not be permitted in some situations.

          (define p (->pathname "/usr/blisp/rel15"))
          p
               =>  #[pathname 71 "/usr/blisp/rel15"]
          (pathname-new-name p "rel100")
               =>  #[pathname 72 "/usr/blisp/rel100"]
          (pathname-new-directory p '(relative "test" "morris"))
               =>  #[pathname 73 "test/morris/rel15"]
          p
               =>  #[pathname 71 "/usr/blisp/rel15"]

 -- procedure+: pathname-default-device pathname device
 -- procedure+: pathname-default-directory pathname directory
 -- procedure+: pathname-default-name pathname name
 -- procedure+: pathname-default-type pathname type
 -- procedure+: pathname-default-version pathname version
     These operations are similar to the pathname-new-COMPONENT operations, except that they only change the specified COMPONENT if it has the value #f in PATHNAME.

Operations on Pathnames
-----------------------

 -- procedure+: pathname? object
     Returns #t if OBJECT is a pathname; otherwise returns #f.

 -- procedure+: pathname=? pathname1 pathname2
     Returns #t if PATHNAME1 is equivalent to PATHNAME2; otherwise returns #f. Pathnames are equivalent if all of their components are equivalent, hence two pathnames that are equivalent must identify the same file or equivalent partial pathnames. However, the converse is not true: non-equivalent pathnames may specify the same file (e.g. via absolute and relative directory components), and pathnames that specify no file at all (e.g. name and directory components unspecified) may be equivalent.

 -- procedure+: pathname-absolute? pathname
     Returns #t if PATHNAME is an absolute rather than relative pathname object; otherwise returns #f.  All pathnames are either absolute or relative, so if this procedure returns #f, the argument is a relative pathname.

 -- procedure+: pathname-wild? pathname
     Returns #t if PATHNAME contains any wildcard components; otherwise returns #f.

 -- procedure+: merge-pathnames pathname [defaults [default-version]]
     Returns a pathname whose components are obtained by combining those of PATHNAME and DEFAULTS.  DEFAULTS defaults to the value of *default-pathname-defaults* and DEFAULT-VERSION defaults to newest.

     The pathnames are combined by components: if PATHNAME has a non-missing component, that is the resulting component, otherwise the component from DEFAULTS is used. The default version can be #f to preserve the information that the component was missing from PATHNAME. The directory component is handled specially: if both pathnames have directory components that are lists, and the directory component from PATHNAME is relative (i.e. starts with relative), then the resulting directory component is formed by appending PATHNAME's component to DEFAULTS's component. For example:

          (define path1 (->pathname "scheme/foo.scm"))
          (define path2 (->pathname "/usr/morris"))
          path1
               =>  #[pathname 74 "scheme/foo.scm"]
          path2
               =>  #[pathname 75 "/usr/morris"]
          (merge-pathnames path1 path2)
               =>  #[pathname 76 "/usr/scheme/foo.scm"]
          (merge-pathnames path2 path1)
               =>  #[pathname 77 "/usr/morris.scm"]

     The merging rules for the version are more complex and depend on whether PATHNAME specifies a name.  If PATHNAME does not specify a name, then the version, if not provided, will come from DEFAULTS. However, if PATHNAME does specify a name then the version is not affected by DEFAULTS.  The reason is that the version ``belongs to'' some other file name and is unlikely to have anything to do with the new one.  Finally, if this process leaves the version missing, then DEFAULT-VERSION is used.

     The net effect is that if the user supplies just a name, then the host, device, directory and type will come from DEFAULTS, but the version will come from DEFAULT-VERSION.  If the user supplies nothing, or just a directory, the name, type and version will come over from DEFAULTS together.

 -- variable+: *default-pathname-defaults*
     This is the default pathname-defaults pathname; if any pathname primitive that needs a set of defaults is not given one, it uses this one.  set-working-directory-pathname! sets this variable to a new value, computed by merging the new working directory with the variable's old value.

 -- procedure+: pathname-default pathname device directory name type version
     This procedure defaults all of the components of PATHNAME simultaneously.  It could have been defined by:

          (define (pathname-default pathname
                                    device directory name type version)
            (make-pathname (pathname-host pathname)
                           (or (pathname-device pathname) device)
                           (or (pathname-directory pathname) directory)
                           (or (pathname-name pathname) name)
                           (or (pathname-type pathname) type)
                           (or (pathname-version pathname) version)))

 -- procedure+: file-namestring pathname
 -- procedure+: directory-namestring pathname
 -- procedure+: host-namestring pathname
 -- procedure+: enough-namestring pathname [defaults]
     These procedures return a string corresponding to a subset of the PATHNAME information.  file-namestring returns a string representing just the NAME, TYPE and VERSION components of PATHNAME; the result of directory-namestring represents just the HOST, DEVICE, and DIRECTORY components; and host-namestring returns a string for just the HOST portion.

     enough-namestring takes another argument, DEFAULTS. It returns an abbreviated namestring that is just sufficient to identify the file named by PATHNAME when considered relative to the DEFAULTS (which defaults to *default-pathname-defaults*).

          (file-namestring "/usr/morris/minor.van")
               =>  "minor.van"
          (directory-namestring "/usr/morris/minor.van")
               =>  "/usr/morris/"
          (enough-namestring "/usr/morris/men")
               =>  "men"      ;perhaps

 -- procedure+: file-pathname pathname
 -- procedure+: directory-pathname pathname
 -- procedure+: enough-pathname pathname [defaults]
     These procedures return a pathname corresponding to a subset of the PATHNAME information. file-pathname returns a pathname with just the NAME, TYPE and VERSION components of PATHNAME. The result of directory-pathname is a pathname containing the HOST, DEVICE and DIRECTORY components of PATHNAME.

     enough-pathname takes another argument, DEFAULTS. It returns an abbreviated pathname that is just sufficient to identify the file named by PATHNAME when considered relative to the DEFAULTS (which defaults to *default-pathname-defaults*).

     These procedures are similar to file-namestring, directory-namestring and enough-namestring, but they return pathnames instead of strings.

 -- procedure+: directory-pathname-as-file pathname
     Returns a pathname that is equivalent to PATHNAME, but in which the directory component is represented as a file. The last directory is removed from the directory component and converted into name and type components. This is the inverse operation to pathname-as-directory.

          (directory-pathname-as-file (->pathname "/usr/blisp/"))
               =>  #[pathname "/usr/blisp"]

 -- procedure+: pathname-as-directory pathname
     Returns a pathname that is equivalent to PATHNAME, but in which any file components have been converted to a directory component.  If PATHNAME does not have name, type, or version components, it is returned without modification.  Otherwise, these file components are converted into a string, and the string is added to the end of the list of directory components.  This is the inverse operation to directory-pathname-as-file.

          (pathname-as-directory (->pathname "/usr/blisp/rel5"))
               =>  #[pathname "/usr/blisp/rel5/"]

Miscellaneous Pathname Procedures
---------------------------------

This section gives some standard operations on host objects, and some procedures that return some useful pathnames.

 -- variable+: local-host
     This variable has as its value the host object that describes the local host's file system.

 -- procedure+: host? object
     Returns #t if OBJECT is a pathname host; otherwise returns #f.

 -- procedure+: host=? host1 host2
     Returns #t if HOST1 and HOST2 denote the same pathname host; otherwise returns #f.

 -- procedure+: init-file-pathname [host]
     Returns a pathname for the user's initialization file on HOST. The HOST argument defaults to the value of local-host.  If the initialization file does not exist this procedure returns #f.

 -- procedure+: user-homedir-pathname [host]
     Returns a pathname for the user's ``home directory'' on HOST.  The HOST argument defaults to the value of local-host.  The concept of a ``home directory'' is itself somewhat implementation-dependent, but it should be the place where the user keeps personal files, such as initialization files and mail.  For example, on unix this is the user's unix home directory, whereas on MS-DOS the home directory is determined from the HOME, USER and USERDIR environment variables.

 -- procedure+: system-library-pathname pathname
     Locates PATHNAME in MIT Scheme's system library directory.  An error of type condition-type:file-operation-error is signalled if PATHNAME cannot be located on the library search path.

          (system-library-pathname "compiler.com")
               => #[pathname 45 "/usr/local/lib/mit-scheme/compiler.com"]

 -- procedure+: system-library-directory-pathname pathname
     Locates the pathname of a MIT Scheme system library directory.  An error of type condition-type:file-operation-error is signalled if PATHNAME cannot be located on the library search path.

          (system-library-directory-pathname "options")
               => #[pathname 44 "/usr/local/lib/mit-scheme/options/"]

Working Directory
=================

When MIT Scheme is started, the current working directory (or simply, working directory) is initialized in an operating-system dependent manner; usually, it is the directory in which Scheme was invoked.  The working directory can be determined from within Scheme by calling the pwd procedure, and changed by calling the cd procedure.  Each REP loop has its own working directory, and inferior REP loops initialize their working directory from the value in effect in their superior at the time they are created.

 -- procedure+: working-directory-pathname
 -- procedure+: pwd
     Returns the current working directory as a pathname that has no name, type, or version components, just host, device, and directory components.  pwd is an alias for working-directory-pathname; the long name is intended for programs and the short name for interactive use.

 -- procedure+: set-working-directory-pathname! filename
 -- procedure+: cd filename
     Makes FILENAME the current working directory and returns the new current working directory as a pathname.  FILENAME is coerced to a pathname using pathname-as-directory.  cd is an alias for set-working-directory-pathname!; the long name is intended for programs and the short name for interactive use.

     Additionally, set-working-directory-pathname! modifies the value of *default-pathname-defaults* by merging the new working directory into it.

     In the unix implementation, when this procedure is executed in the top-level REP loop, it changes the working directory of the running Scheme executable.

          (set-working-directory-pathname! "/usr/morris/blisp")
               =>  #[pathname "/usr/morris/blisp/"]
          (set-working-directory-pathname! "~")
               =>  #[pathname "/usr/morris/"]

     This procedure signals an error if FILENAME does not refer to an existing directory.

     If FILENAME describes a relative rather than absolute pathname, this procedure interprets it as relative to the current working directory, before changing the working directory.

          (working-directory-pathname)
               =>  #[pathname "/usr/morris/"]
          (set-working-directory-pathname! "foo")
               =>  #[pathname "/usr/morris/foo/"]

 -- procedure+: with-working-directory-pathname filename thunk
     This procedure temporarily rebinds the current working directory to FILENAME, invokes THUNK (a procedure of no arguments), then restores the previous working directory and returns the value yielded by THUNK.  FILENAME is coerced to a pathname using pathname-as-directory.  In addition to binding the working directory, with-working-directory-pathname also binds the variable *default-pathname-defaults*, merging the old value of that variable with the new working directory pathname.  Both bindings are performed in exactly the same way as fluid binding of a variable (see Fluid Binding).

File Manipulation
=================

This section describes procedures that manipulate files and directories. Any of these procedures can signal a number of errors for many reasons. The specifics of these errors are much too operating-system dependent to document here.  However, if such an error is signalled by one of these procedures, it will be of type condition-type:file-operation-error.

 -- procedure+: file-exists? filename
     Returns #t if FILENAME is an existing file or directory; otherwise returns #f.  In operating systems that support symbolic links, if the file is a symbolic link, this procedure tests the existence of the file linked to, not the link itself.

 -- procedure+: copy-file source-filename target-filename
     Makes a copy of the file named by SOURCE-FILENAME.  The copy is performed by creating a new file called TARGET-FILENAME, and filling it with the same data as SOURCE-FILENAME.  If TARGET-FILENAME exists prior to this procedure's invocation, it is deleted before the new output file is created.

 -- procedure+: rename-file source-filename target-filename
     Changes the name of SOURCE-FILENAME to be TARGET-FILENAME. In the unix implementation, this will not rename across file systems.

 -- procedure+: delete-file filename
     Deletes the file named FILENAME.

 -- procedure+: ->truename filename
     This procedure attempts to discover and return the ``true name'' of the file associated with FILENAME within the file system.  An error of type condition-type:file-operation-error is signalled if the appropriate file cannot be located within the file system.

 -- procedure+: call-with-temporary-filename procedure
     call-with-temporary-filename generates a temporary filename, and calls PROCEDURE with that filename as its sole argument.  The filename is guaranteed not to refer to any existing file, and, barring unusual circumstances, it can be used to open an output file without error.  When PROCEDURE returns, if the file referred to by the filename exists, it is deleted; then, the value yielded by PROCEDURE is returned.  If PROCEDURE escapes from its continuation, and the file referred to by the filename exists, it is deleted.

 -- procedure+: file-directory? filename
     Returns #t if the file named FILENAME exists and is a directory.  Otherwise returns #f.  In operating systems that support symbolic links, if FILENAME names a symbolic link, this examines the file linked to, not the link itself.

 -- procedure+: file-symbolic-link? filename
     In operating systems that support symbolic links, if the file named FILENAME exists and is a symbolic link, this procedure returns the contents of the symbolic link as a newly allocated string.  The returned value is the name of the file that the symbolic link points to and must be interpreted relative to the directory of FILENAME.  If FILENAME either does not exist or is not a symbolic link, or if the operating system does not support symbolic links, this procedure returns #f.

 -- procedure+: file-readable? filename
     Returns #t if FILENAME names a file that can be opened for input; i.e. a readable file.  Otherwise returns #f.

 -- procedure+: file-writable? filename
     Returns #t if FILENAME names a file that can be opened for output; i.e. a writable file.  Otherwise returns #f.

 -- procedure+: file-access filename mode
     MODE must be an exact integer between 0 and 7 inclusive; it is a bitwise-encoded predicate selector with 1 meaning ``executable'', 2 meaning ``writable'', and 4 meaning ``readable''.  file-access returns #t if FILENAME exists and satisfies the predicates selected by MODE.  For example, if MODE is 5, then FILENAME must be both readable and executable.  If FILENAME doesn't exist, or if it does not satisfy the selected predicates, #f is returned.

 -- procedure+: file-modes filename
     If FILENAME names an existing file, file-modes returns an exact non-negative integer encoding the file's permissions.  The encoding of this integer is operating-system dependent, but typically it contains bits that indicate what users and processes are allowed to read, write, or execute the file.  If FILENAME does not name an existing file, #f is returned.

 -- procedure+: set-file-modes! filename modes
     FILENAME must name an existing file.  MODES must be an exact non-negative integer that could have been returned by a call to file-modes.  set-file-modes! modifies the file's permissions to be those encoded by MODES.

 -- procedure+: file-modification-time filename
     Returns the modification time of FILENAME as an exact integer. The result may be compared to other file times using ordinary integer arithmetic.  If FILENAME names a file that does not exist, file-modification-time returns #f.

     In operating systems that support symbolic links, if FILENAME names a symbolic link, file-modification-time returns the modification time of the file linked to.  An alternate procedure, file-modification-time-direct, returns the modification time of the link itself; in all other respects it is identical to file-modification-time.  For symmetry, file-modification-time-indirect is a synonym of file-modification-time.

 -- procedure+: file-access-time filename
     Returns the access time of FILENAME as an exact integer.  The result may be compared to other file times using ordinary integer arithmetic.  If FILENAME names a file that does not exist, file-access-time returns #f.

     Some operating systems don't implement access times; in those systems file-access-time returns an unspecified value.

     In operating systems that support symbolic links, if FILENAME names a symbolic link, file-access-time returns the access time of the file linked to.  An alternate procedure, file-access-time-direct, returns the access time of the link itself; in all other respects it is identical to file-access-time.  For symmetry, file-access-time-indirect is a synonym of file-access-time.

 -- procedure+: set-file-times! filename access-time modification-time
     FILENAME must name an existing file, while ACCESS-TIME and MODIFICATION-TIME must be valid file times that might have been returned by file-access-time and file-modification-time, respectively.  set-file-times! alters the access and modification times of the file specified by FILENAME to the values given by ACCESS-TIME and MODIFICATION-TIME, respectively.  For convenience, either of the time arguments may be specified as #f; in this case the corresponding time is not changed. set-file-times! returns an unspecified value.

 -- procedure+: file-attributes filename
     This procedure determines if the file named FILENAME exists, and returns information about it if so; if the file does not exist, it returns #f.  The information returned is a vector of 10 items:

      1. The file type: #t if the file is a directory, a character string (the name linked to) if a symbolic link, or #f for all other types of file.

      2. The number of links to the file.

      3. The user id of the file's owner, an exact non-negative integer.

      4. The group id of the file's group, an exact non-negative integer.

      5. The last access time of the file, an exact non-negative integer.

      6. The last modification time of the file, an exact non-negative integer.

      7. The last change time of the file, an exact non-negative integer.

      8. The size of the file in bytes.

      9. The mode string of the file.  This is a newly allocated string showing the file's mode bits.

      10. The inode number of the file, an exact non-negative integer.

     In operating systems that support symbolic links, if FILENAME names a symbolic link, file-attributes returns the attributes of the link itself.  An alternate procedure, file-attributes-indirect, returns the attributes of the file linked to; in all other respects it is identical to file-attributes.  For symmetry, file-attributes-direct is a synonym of file-attributes.

Directory Reader
================

 -- procedure+: directory-read directory [sort?]
     DIRECTORY must be an object that can be converted into a pathname by ->pathname.  The directory specified by DIRECTORY is read, and the contents of the directory is returned as a newly allocated list of absolute pathnames.  The result is sorted according to the usual sorting conventions for directories, unless SORT? is specified as #f.  If DIRECTORY has name, type, or version components, the returned list contains only those pathnames whose name, type, and version components match those of DIRECTORY; wild or #f as one of these components means ``match anything''.

Error System
************

This chapter is being rewritten and is not yet finished.

Graphics
********

MIT Scheme has a simple two-dimensional line-graphics interface that is suitable for many graphics applications.  In particular it is often used for plotting data points from experiments.  The interface is generic in that it can support different types of graphics devices in a uniform manner.  At the present time only two types of graphics device are implemented.

Procedures are available for drawing points, lines, and text; defining the coordinate system; clipping graphics output; controlling some of the drawing characteristics; and controlling the output buffer (for devices that perform buffering).  Additionally, devices may support custom operations, such as control of colors.

There are some constraints on the arguments to the procedures described in this chapter.  Any argument named GRAPHICS-DEVICE must be a graphics device object that was returned from a call to make-graphics-device.  Any argument that is a coordinate must be either an exact integer or an inexact real.

Opening and Closing of Graphics Devices
=======================================

 -- procedure+: graphics-type-available? graphics-device-type
     This predicate returns #t if the graphics system named by the symbol GRAPHICS-DEVICE-TYPE is implemented by the Scheme system. Otherwise it returns #f, in which case it is an error to attempt to make a graphics device using GRAPHICS-DEVICE-TYPE.

 -- procedure+: enumerate-graphics-device-types
     This procedure returns a list of symbols which are the names of all the graphics device types that are supported by the Scheme system.  The result is useful in deciding what additional arguments to supply to make-graphics-device, as each device type typically has a unique way of specifying the initial size, shape and other attributes.

 -- procedure+: make-graphics-device graphics-device-type object ...
     This operation creates and returns a graphics device object. GRAPHICS-DEVICE-TYPE is a symbol naming a graphics device type, and both the number and the meaning of the remaining arguments is determined by that type (see the description of each device type for details); GRAPHICS-DEVICE-TYPE must satisfy graphics-type-available?.  GRAPHICS-DEVICE-TYPE may also be #f, in which case the graphics device type is chosen by the system from what is available.  This allows completely portable graphics programs to be written provided no custom graphics operations are used. When GRAPHICS-DEVICE-TYPE is #f no further arguments may be given; each graphics device type will use some ``sensible'' defaults. If more control is required then the program should use one of the two procedures above to dispatch on the available types.

     This procedure opens and initializes the device, which remains valid until explicitly closed by the procedure graphics-close. Depending on the implementation of the graphics device, if this object is reclaimed by the garbage collector, the graphics device may remain open or it may be automatically closed.  While a graphics device remains open the resources associated with it are not released.

 -- procedure+: graphics-close graphics-device
     Closes GRAPHICS-DEVICE, releasing its resources.  Subsequently it is an error to use GRAPHICS-DEVICE.

Coordinates for Graphics
========================

Each graphics device has two different coordinate systems associated with it: device coordinates and virtual coordinates.  Device coordinates are generally defined by low-level characteristics of the device itself, and often cannot be changed.  Most device coordinate systems are defined in terms of pixels, and usually the upper-left-hand corner is the origin of the coordinate system, with X coordinates increasing to the right and Y coordinates increasing downwards.

In contrast, virtual coordinates are more flexible in the units employed, the position of the origin, and even the direction in which the coordinates increase.  A virtual coordinate system is defined by assigning coordinates to the edges of a device.  Because these edge coordinates are arbitrary real numbers, any Cartesian coordinate system can be defined.

All graphics procedures that use coordinates are defined on virtual coordinates.  For example, to draw a line at a particular place on a device, the virtual coordinates for the endpoints of that line are given.

When a graphics device is initialized, its virtual coordinate system is reset so that the left edge corresponds to an x-coordinate of -1, the right edge to x-coordinate 1, the bottom edge to y-coordinate -1, and the top edge to y-coordinate 1.

 -- procedure+: graphics-device-coordinate-limits graphics-device
     Returns (as multiple values) the device coordinate limits for GRAPHICS-DEVICE.  The values, which are exact non-negative integers, are: X-LEFT, Y-BOTTOM, X-RIGHT, and Y-TOP.

 -- procedure+: graphics-coordinate-limits graphics-device
     Returns (as multiple values) the virtual coordinate limits for GRAPHICS-DEVICE.  The values, which are real numbers, are: X-LEFT, Y-BOTTOM, X-RIGHT, and Y-TOP.

 -- procedure+: graphics-set-coordinate-limits graphics-device x-left y-bottom x-right y-top
     Changes the virtual coordinate limits of GRAPHICS-DEVICE to the given arguments.  X-LEFT, Y-BOTTOM, X-RIGHT, and Y-TOP must be real numbers.  Subsequent calls to graphics-coordinate-limits will return the new limits.  This operation has no effect on the device's displayed contents.

     Note: This operation usually resets the clip rectangle, although it is not guaranteed to do so.  If a clip rectangle is in effect when this procedure is called, it is necessary to redefine the clip rectangle afterwards.

Drawing Graphics
================

The procedures in this section provide the basic drawing capabilities of Scheme's graphics system.

 -- procedure+: graphics-clear graphics-device
     Clears the display of GRAPHICS-DEVICE.  Unaffected by the current drawing mode.

 -- procedure+: graphics-draw-point graphics-device x y
     Draws a single point on GRAPHICS-DEVICE at the virtual coordinates given by X and Y, using the current drawing mode.

 -- procedure+: graphics-erase-point graphics-device x y
     Erases a single point on GRAPHICS-DEVICE at the virtual coordinates given by X and Y.  This procedure is unaffected by the current drawing mode.

     This is equivalent to

          (lambda (device x y)
            (graphics-bind-drawing-mode device 0
              (lambda ()
                (graphics-draw-point device x y))))

 -- procedure+: graphics-draw-line graphics-device x-start y-start x-end y-end
     X-START, Y-START, X-END, and Y-END must be real numbers.  Draws a line on GRAPHICS-DEVICE that connects the points (X-START, Y-START) and (X-END, Y-END).  The line is drawn using the current drawing mode and line style.

 -- procedure+: graphics-draw-text graphics-device x y string
     Draws the characters of STRING at the point (X, Y) on GRAPHICS-DEVICE, using the current drawing mode.  The characteristics of the characters drawn are device-dependent, but all devices are initialized so that the characters are drawn upright, from left to right, with the leftmost edge of the leftmost character at X, and the baseline of the characters at Y.

The following two procedures provide an alternate mechanism for drawing lines, which is more akin to using a plotter.  They maintain a cursor, which can be positioned to a particular point and then dragged to another point, producing a line.  Sequences of connected line segments can be drawn by dragging the cursor from point to point.

Many graphics operations have an unspecified effect on the cursor.  The following exceptions are guaranteed to leave the cursor unaffected:

     graphics-device-coordinate-limits
     graphics-coordinate-limits
     graphics-enable-buffering
     graphics-disable-buffering
     graphics-flush
     graphics-bind-drawing-mode
     graphics-set-drawing-mode
     graphics-bind-line-style
     graphics-set-line-style

The initial state of the cursor is unspecified.

 -- procedure+: graphics-move-cursor graphics-device x y
     Moves the cursor for GRAPHICS-DEVICE to the point (X, Y).  The contents of the device's display are unchanged.

 -- procedure+: graphics-drag-cursor graphics-device x y
     Draws a line from GRAPHICS-DEVICE's cursor to the point (X, Y), simultaneously moving the cursor to that point.  The line is drawn using the current drawing mode and line style.

Characteristics of Graphics Output
==================================

Two characteristics of graphics output are so useful that they are supported uniformly by all graphics devices: drawing mode and line style.  A third characteristic, color, is equally useful (if not more so), but implementation restrictions prohibit a uniform interface.

The drawing mode, an exact integer in the range 0 to 15 inclusive, determines how the figure being drawn is combined with the background over which it is drawn to generate the final result. Initially the drawing mode is set to ``source'', so that the new output overwrites whatever appears in that place.  Useful alternative drawing modes can, for example, erase what was already there, or invert it.

Altogether 16 boolean operations are available for combining the source (what is being drawn) and the destination (what is being drawn over). The source and destination are combined by the device on a pixel-by-pixel basis as follows:

     Mode    Meaning
     ----    -------
     0       ZERO [erase; use background color]
     1       source AND destination
     2       source AND (NOT destination)
     3       source
     4       (NOT source) AND destination
     5       destination
     6       source XOR destination
     7       source OR destination
     8       NOT (source OR destination)
     9       NOT (source XOR destination)
     10      NOT destination
     11      source OR (NOT destination)
     12      NOT source
     13      (NOT source) OR destination
     14      (NOT source) OR (NOT destination)
     15      ONE [use foreground color]

The line style, an exact integer in the range 0 to 7 inclusive, determines which parts of a line are drawn in the foreground color, and which in the background color.  The default line style, ``solid'', draws the entire line in the foreground color. Alternatively, the ``dash'' style alternates between foreground and background colors to generate a dashed line.  This capability is useful for plotting several things on the same graph.

Here is a table showing the name and approximate pattern of the different styles.  A 1 in the pattern represents a foreground pixel, while a - represents a background pixel.  Note that the precise output for each style will vary from device to device.  The only style that is guaranteed to be the same for every device is ``solid''.

     Style   Name                    Pattern
     -----   -------                 -------
     0       solid                   1111111111111111
     1       dash                    11111111--------
     2       dot                     1-1-1-1-1-1-1-1-
     3       dash dot                1111111111111-1-
     4       dash dot dot            11111111111-1-1-
     5       long dash               11111111111-----
     6       center dash             111111111111-11-
     7       center dash dash        111111111-11-11-

 -- procedure+: graphics-bind-drawing-mode graphics-device drawing-mode thunk
 -- procedure+: graphics-bind-line-style graphics-device line-style thunk
     These procedures bind the drawing mode or line style, respectively, of GRAPHICS-DEVICE, invoke the procedure THUNK with no arguments, then undo the binding when THUNK returns.  The value of each procedure is the value returned by THUNK.  Graphics operations performed during THUNK's dynamic extent will see the newly bound mode or style as current.

 -- procedure+: graphics-set-drawing-mode graphics-device drawing-mode
 -- procedure+: graphics-set-line-style graphics-device line-style
     These procedures change the drawing mode or line style, respectively, of GRAPHICS-DEVICE.  The mode or style will remain in effect until subsequent changes or bindings.

Buffering of Graphics Output
============================

To improve performance of graphics output, most graphics devices provide some form of buffering.  By default, Scheme's graphics procedures flush this buffer after every drawing operation.  The procedures in this section allow the user to control the flushing of the output buffer.

 -- procedure+: graphics-enable-buffering graphics-device
     Enables buffering for GRAPHICS-DEVICE.  In other words, after this procedure is called, graphics operations are permitted to buffer their drawing requests.  This usually means that the drawing is delayed until the buffer is flushed explicitly by the user, or until it fills up and is flushed by the system.

 -- procedure+: graphics-disable-buffering graphics-device
     Disables buffering for GRAPHICS-DEVICE.  By default, all graphics devices are initialized with buffering disabled.  After this procedure is called, all drawing operations perform their output immediately, before returning.

     Note: graphics-disable-buffering flushes the output buffer if necessary.

 -- procedure+: graphics-flush graphics-device
     Flushes the graphics output buffer for GRAPHICS-DEVICE.  This operation has no effect for devices that do not support buffering, or if buffering is disabled for the device.

Clipping of Graphics Output
===========================

Scheme provides a rudimentary mechanism for restricting graphics output to a given rectangular subsection of a graphics device.  By default, graphics output that is drawn anywhere within the device's virtual coordinate limits will appear on the device.  When a clip rectangle is specified, however, output that would have appeared outside the clip rectangle is not drawn.

Note that changing the virtual coordinate limits for a device will usually reset the clip rectangle for that device, as will any operation that affects the size of the device (such as a window resizing operation).  However, programs should not depend on this.

 -- procedure+: graphics-set-clip-rectangle graphics-device x-left y-bottom x-right y-top
     Specifies the clip rectangle for GRAPHICS-DEVICE in virtual coordinates.  X-LEFT, Y-BOTTOM, X-RIGHT, and Y-TOP must be real numbers.  Subsequent graphics output is clipped to the intersection of this rectangle and the device's virtual coordinate limits.

 -- procedure+: graphics-reset-clip-rectangle graphics-device
     Eliminates the clip rectangle for GRAPHICS-DEVICE.  Subsequent graphics output is clipped to the virtual coordinate limits of the device.

Custom Graphics Operations
==========================

In addition to the standard operations, a graphics device may support custom operations.  For example, most devices have custom operations to control color.  graphics-operation is used to invoke custom operations.

 -- procedure+: graphics-operation graphics-device name object ...
     Invokes the graphics operation on GRAPHICS-DEVICE whose name is the symbol NAME, passing it the remaining arguments.  This procedure can be used to invoke the standard operations, as well as custom operations that are specific to a particular graphics device type.  The names of the standard graphics operations are formed by removing the graphics- prefix from the corresponding procedure. For example, the following are equivalent:

          (graphics-draw-point device x y)
          (graphics-operation device 'draw-point x y)

     For information on the custom operations for a particular device, see the documentation for its type.

Images
======

Some graphics device types support images, which are rectangular pieces of picture that may be drawn into a graphics device.  Images are often called something else in the host graphics system, such as bitmaps or pixmaps.  The operations supported vary between devices, so look under the different device types to see what operations are available.  All devices that support images support the following operations.

 -- operation+ on graphics-device: create-image width height
     Images are created using the create-image graphics operation, specifying the WIDTH and HEIGHT of the image in device coordinates (pixels).

          (graphics-operation device 'create-image 200 100)

     The initial contents of an image are unspecified.

     create-image is a graphics operation rather than a procedure because the kind of image returned depends on the kind of graphics device used and the options specified in its creation.  The image may be used freely with other graphics devices created with the same attributes, but the effects of using an image with a graphics device with different attributes (for example, different colors) is undefined. Under X, the image is display dependent.

 -- operation+ on graphics-device: draw-image x y image
     The image is copied into the graphics device at the specified position.

 -- operation+ on graphics-device: draw-subimage x y image im-x im-y w h
     Part of the image is copied into the graphics device at the specified (X, Y) position.  The part of the image that is copied is the rectangular region at IM-X and IM-Y and of width W and height H.  These four numbers are given in device coordinates (pixels).

 -- procedure+: image? object
     Returns #t if OBJECT is an image, otherwise returns #f.

 -- procedure+: image/destroy image
     This procedure destroys IMAGE, returning storage to the system. Programs should destroy images after they have been used because even modest images may use large amounts of memory.  Images are reclaimed by the garbage collector, but they may be implemented using memory outside of Scheme's heap.  If an image is reclaimed before being destroyed, the implementation might not deallocate that non-heap memory, which can cause a subsequent call to create-image to fail because it is unable to allocate enough memory.

 -- procedure+: image/height image
     Returns the height of the image in device coordinates.

 -- procedure+: image/width image
     Returns the width of the image in device coordinates.

 -- procedure+: image/fill-from-byte-vector image bytes
     The contents of IMAGE are set in a device-dependent way, using one byte per pixel from BYTES (a string).  Pixels are filled row by row from the top of the image to the bottom, with each row being filled from left to right.  There must be at least (* (image/height IMAGE) (image/width IMAGE)) bytes in BYTES.

Win32 Graphics
==============

MIT Scheme supports graphics on Microsoft Windows 3.1 and Microsoft Windows NT 3.1.  In addition to the usual operations, there are operations to control the size, position and colors of a graphics window.  Win32 devices support images, which are implemented as device independent bitmaps (DIBs).

The Win32 graphics device type is implemented as a top level window. graphics-enable-buffering is implemented and gives a 2x to 4x speedup on many graphics operations.  As a convenience, when buffering is enabled clicking on the graphics window's title bar effects a graphics-flush operation.  The user has the benefit of the increased performance and the ability to view the progress in drawing at the click of a mouse button.

Win32 Graphics Type
-------------------

Win32 graphics devices are created by specifying the symbol win32 as the GRAPHICS-DEVICE-TYPE argument to make-graphics-device.  The Win32 graphics device type is implemented as a top-level window and supports color drawing in addition to the standard Scheme graphics operations.

Graphics devices are opened as follows:

     (make-graphics-device 'win32 #!optional WIDTH HEIGHT PALETTE)

where WIDTH and HEIGHT specify the size, in pixels, of the drawing area in the graphics window (i.e. excluding the frame). PALETTE determines the colors available for drawing in the window.

When a color is specified for drawing, the nearest color available in the palette is used.  Permitted values for PALETTE are

'grayscale
     The window allocates colors from a grayscale palette of approximately 236 shades of gray.

'grayscale-128
     The window allocates colors from a grayscale palette of 128 shades of gray.

'standard
     The standard palette has good selection of colors and grays.

#f or 'system
     The colors available are those in the system palette.  There are usually 16 to 20 colors in the system palette and these are usually sufficent for simple applications like line drawings and x-vs-y graphs of mathematical functions.  Drawing with the system palette can be more efficient.

If PALETTE is not specified then the standard palette is used.

Custom Operations for Win32 Graphics
------------------------------------

Custom operations are invoked using the procedure graphics-operation.  For example,

     (graphics-operation device 'set-foreground-color "blue")

 -- operation+ on win32-graphics-device: set-background-color color-name
 -- operation+ on win32-graphics-device: set-foreground-color color-name
     These operations change the colors associated with a window. COLOR-NAME must be of one of the valid color specification forms listed below.  set-background-color and set-foreground-color change the colors to be used when drawing, but have no effect on anything drawn prior to their invocation.  Because changing the background color affects the entire window, we recommend calling graphics-clear on the window's device afterwards.

     The foreground color affects the drawing of text, points, lines, ellipses and filled polygons.

     Colors are specified in one of three ways:

     An integer
          This is the Win32 internal RGB value.

     By name
          A limited number of names are understood by the system. Names are strings, e.g. "red", "blue", "black". More names can be registered with the define-color operation.

     RGB (Red-Green-Blue) triples
          A triple is either a vector or list of three integers in the range 0--255 inclusive which specify the intensity of the red, green and blue components of the color.  Thus #(0 0 0) is black, (0 0 128) is dark blue and #(255 255 255) is white.

     If the color is not available in the graphics device then the nearest available color is used instead.

 -- operation+ on win32-graphics-device: define-color name spec
     Define the string NAME to be the color specified by SPEC. SPEC may be any acceptable color specification.  Note that the color names defined this way are available to any Win32 graphics device, and the names do not have to be defined for each device.

 -- operation+ on win32-graphics-device: find-color name
     Looks up a color previously defined by define-color.  This returns the color in its most efficient form for operations set-foreground-color or set-background-color.

 -- operation+ on win32-graphics-device: draw-ellipse left top right bottom
     Draw an ellipse.  LEFT, TOP, RIGHT and BOTTOM indicate the coordinates of the bounding rectangle of the ellipse. Circles are merely ellipses with equal width and height.  Note that the bounding rectangle has horizontal and vertical sides.  Ellipses with rotated axes cannot be drawn.  The rectangle applies to the center of the line used to draw the ellipse; if the line width has been set to greater than 1 then the ellipse will spill outside the bounding rectange by half of the line width.

 -- operation+ on win32-graphics-device: fill-polygon points
     Draws a filled polygon using the current foreground color. POINTS is a vector of real numbers. The numbers are in the order x1 y1 x2 y2 ... xn yn. For example,

          (graphics-operation device 'fill-polygon #(0 0 0 1 1 0))

     draws a solid triangular region between the points (0, 0), (0, 1) and (1, 0).

 -- operation+ on win32-graphics-device: load-bitmap pathname
     The graphics device contents and size are initialized from the windows bitmap file specified by PATHNAME.  If no file type is supplied then a ".BMP" extension is added.  If a clip rectangle is in effect when this procedure is called, it is necessary to redefine the clip rectangle afterwards.

 -- operation+ on win32-graphics-device: save-bitmap pathname
     The graphics device contents are saved as a bitmap to the file specified by PATHNAME.  If no file type is supplied then a ".BMP" extension is added.  The saved bitmap may be incorporated into documents or printed.

 -- operation+ on win32-graphics-device: move-window x y
     The graphics device window is moved to the screen position specified by X and Y.

 -- operation+ on win32-graphics-device: resize-window width height
     The graphics device window is resized to the specified WIDTH and HEIGHT in device coordinates (pixels).  If a clip rectangle is in effect when this procedure is called, it is necessary to redefine the clip rectangle afterwards.

 -- operation+ on win32-graphics-device: set-line-width width
     This operation sets the line width for future drawing of lines, points and ellipses.  It does not affect existing lines and has no effect on filled polygons.  The line width is specified in device units.  The default and initial value of this parameter is 1 pixel.

 -- operation+ on win32-graphics-device: set-window-name name
     This sets the window title to the string NAME.  The window is given the name "Scheme Graphics" at creation.

 -- operation+ on win32-graphics-device: set-font handle
     Sets the font for drawing text.  Currently not well supported.  If you can get a Win32 font handle it can be used here.

 -- operation+ on win32-graphics-device: copy-area source-x-left source-y-top width height destination-x-left destination-y-top
     This operation copies the contents of the rectangle specified by SOURCE-X-LEFT, SOURCE-Y-TOP, WIDTH, and HEIGHT to the rectangle of the same dimensions at DESTINATION-X-LEFT and DESTINATION-Y-TOP.

X Graphics
==========

MIT Scheme supports graphics in the X window system (version 11). Arbitrary numbers of displays may be opened, and arbitrary numbers of graphics windows may be created for each display.  A variety of operations is available to manipulate various aspects of the windows, to control their size, position, colors, and mapping.  The X graphics device type supports images, which are implemented as Xlib XImage objects.  X display, window, and image objects are automatically closed if they are reclaimed by the garbage collector.

X Graphics Type
---------------

A graphics device for X windows is created by passing the symbol x as the graphics device type name to make-graphics-device:

     (make-graphics-device 'x #!optional DISPLAY GEOMETRY SUPPRESS-MAP?)

where DISPLAY is either a display object, #f, or a string; GEOMETRY is either #f or a string; and SUPPRESS-MAP? is a boolean or a vector (see below).  A new window is created on the appropriate display, and a graphics device representing that window is returned.

DISPLAY specifies which X display the window is to be opened on; if it is #f or a string, it is passed as an argument to x-open-display, and the value returned by that procedure is used in place of the original argument.  GEOMETRY is an X geometry string, or #f which means to use the default geometry (which is specified as a resource).

SUPPRESS-MAP?, if given, may take two forms.  First, it may be a boolean: if #f (the default), the window is automatically mapped after it is created; otherwise, #t means to suppress this automatic mapping.  The second form is a vector of three elements.  The first element is a boolean with the same meaning as the boolean form of SUPPRESS-MAP?.  The second element is a string, which specifies an alternative resource name to be used for looking up the window's resources.  The third element is also a string, which specifies a class name for looking up the window's resources.  The default value for SUPPRESS-MAP? is #f.

The default resource and class names are "schemeGraphics" and "SchemeGraphics" respectively.

The window is initialized using the resource and class names specified by SUPPRESS-MAP?, and is sensitive to the following resource properties:

     Property        Class           Default
     --------        -----           -------
     geometry        Geometry        512x384+0+0
     font            Font            fixed
     borderWidth     BorderWidth     2
     internalBorder  BorderWidth     [border width]
     background      Background      white
     foreground      Foreground      black
     borderColor     BorderColor     [foreground color]
     cursorColor     Foreground      [foreground color]
     pointerColor    Foreground      [foreground color]

The window is created with a backing_store attribute of Always.  The window's name and icon name are initialized to "scheme-graphics".

Utilities for X Graphics
------------------------

 -- procedure+: x-open-display display-name
     Opens a connection to the display whose name is DISPLAY-NAME, returning a display object.  If unable to open a connection, #f is returned.  DISPLAY-NAME is normally a string, which is an X display name in the usual form; however, #f is also allowed, meaning to use the value of the unix environment variable DISPLAY.

 -- procedure+: x-close-display display
     Closes DISPLAY; after calling this procedure, it is an error to use DISPLAY for any purpose.  Any windows that were previously opened on DISPLAY are destroyed and their resources returned to the operating system.

 -- procedure+: x-close-all-displays
     Closes all open connections to X displays.  Equivalent to calling x-close-display on all open displays.

 -- procedure+: x-geometry-string x y width height
     This procedure creates and returns a standard X geometry string from the given arguments.  X and Y must be either exact integers or #f, while WIDTH and HEIGHT must be either exact non-negative integers or #f.  Usually either X and Y are both specified or both #f; similarly for WIDTH and HEIGHT.  If only one of the elements of such a pair is specified, it is ignored.

     Examples:

          (x-geometry-string #f #f 100 200) => "100x200"
          (x-geometry-string 2 -3 100 200) => "100x200+2-3"
          (x-geometry-string 2 -3 #f #f) => "+2-3"

     Note that the X and Y arguments cannot distinguish between +0 and -0, even though these have different meanings in X. If either of those arguments is 0, it means +0 in X terminology.  If you need to distinguish these two cases you must create your own geometry string using Scheme's string and number primitives.

Custom Operations on X Graphics Devices
---------------------------------------

Custom operations are invoked using the procedure graphics-operation.  For example,

     (graphics-operation device 'set-foreground-color "blue")

 -- operation+ on x-graphics-device: set-background-color color-name
 -- operation+ on x-graphics-device: set-foreground-color color-name
 -- operation+ on x-graphics-device: set-border-color color-name
 -- operation+ on x-graphics-device: set-mouse-color color-name
     These operations change the colors associated with a window. COLOR-NAME must be a string, which is the X server's name for the desired color.  set-border-color and set-mouse-color immediately change the border and mouse-cursor colors. set-background-color and set-foreground-color change the colors to be used when drawing, but have no effect on anything drawn prior to their invocation.  Because changing the background color affects the entire window, we recommend calling graphics-clear on the window's device afterwards.  Color names include both mnemonic names, like "red", and intensity names specified in the "#RRGGBB" notation.

 -- operation+ on x-graphics-device: set-border-width width
 -- operation+ on x-graphics-device: set-internal-border-width width
     These operations change the external and internal border widths of a window.  WIDTH must be an exact non-negative integer, specified in pixels.  The change takes place immediately.  Note that changing the internal border width can cause displayed graphics to be garbled; we recommend calling graphics-clear on the window's device after doing so.

 -- operation+ on x-graphics-device: set-font font-name
     Changes the font used when drawing text in a window.  FONT-NAME must be a string that is a font name known to the X server.  This operation does not affect text drawn prior to its invocation.

 -- operation+ on x-graphics-device: set-mouse-shape shape-number
     Changes the shape of the mouse cursor.  SHAPE-NUMBER is an exact non-negative integer that is used as an index into the mouse-shape font; when multiplied by 2 this number corresponds to an index in the file /usr/include/X11/cursorfont.h.

 -- operation+ on x-graphics-device: map-window
 -- operation+ on x-graphics-device: withdraw-window
     These operations control the mapping of windows.  They correspond directly to the Xlib procedures XMapWindow and XWithdrawWindow.

 -- operation+ on x-graphics-device: resize-window width height
     Changes the size of a window.  WIDTH and HEIGHT must be exact non-negative integers.  The operation corresponds directly to the Xlib procedure XResizeWindow.

     This operation resets the virtual coordinate system and the clip rectangle.

 -- operation+ on x-graphics-device: move-window x y
     Changes the position of a window on the display.  X and Y must be exact integers.  The operation corresponds directly to the Xlib procedure XMoveWindow.  Note that the coordinates X and Y do not take the external border into account, and therefore will not position the window as you might like.  The only reliable way to position a window is to ask a window manager to do it for you.

 -- operation+ on x-graphics-device: get-default resource property
     This operation corresponds directly to the Xlib procedure XGetDefault.  RESOURCE and PROPERTY must be strings. The operation returns the character string corresponding to the association of RESOURCE and PROPERTY; if no such association exists, #f is returned.

 -- operation+ on x-graphics-device: copy-area source-x-left source-y-top width height destination-x-left destination-y-top
     This operation copies the contents of the rectangle specified by SOURCE-X-LEFT, SOURCE-Y-TOP, WIDTH, and HEIGHT to the rectangle of the same dimensions at DESTINATION-X-LEFT and DESTINATION-Y-TOP.

 -- operation+ on x-graphics-device: font-structure font-name
     Returns a Scheme equivalent of the X font structure for the font named FONT-NAME.  If the string FONT-NAME does not name a font known to the X server, or names a 16-bit font, #f is returned.

 -- procedure+: x-font-structure/name font-structure
 -- procedure+: x-font-structure/direction font-structure
 -- procedure+: x-font-structure/all-chars-exist font-structure
 -- procedure+: x-font-structure/default-char font-structure
 -- procedure+: x-font-structure/min-bounds font-structure
 -- procedure+: x-font-structure/max-bounds font-structure
 -- procedure+: x-font-structure/start-index font-structure
 -- procedure+: x-font-structure/character-bounds font-structure
 -- procedure+: x-font-structure/max-ascent font-structure
 -- procedure+: x-font-structure/max-descent font-structure
     These procedures extract the components of the font description structure returned by the X graphics operation font-structure.  A more complete description of these components appears in documentation of the XLoadQueryFont Xlib call.  start-index is the index of the first character available in the font.  The min-bounds and max-bounds components are structures of type x-character-bounds, and the character-bounds component is a vector of the same type.

 -- procedure+: x-character-bounds/lbearing character-bounds
 -- procedure+: x-character-bounds/rbearing character-bounds
 -- procedure+: x-character-bounds/width character-bounds
 -- procedure+: x-character-bounds/ascent character-bounds
 -- procedure+: x-character-bounds/descent character-bounds
     These procedures extract components of objects of type x-character-bounds.  A more complete description of them appears in documentation of the XLoadQueryFont Xlib call.

Starbase Graphics
=================

On Hewlett-Packard computers under the HP-UX operating system, Scheme supports graphics through the Starbase graphics library.  Note that the default distribution of Scheme for HP computers does not include support for Starbase --- you must rebuild the microcode to get this support.

 -- variable+: starbase-graphics-device-type
     This is the device type for Starbase graphics devices.  A Starbase device is opened as follows:

          (make-graphics-device 'starbase DEVICE-NAME DRIVER-NAME)

     where DEVICE-NAME and DRIVER-NAME are strings that are used as the device and driver arguments to the Starbase gopen call. The device is opened with kind OUTDEV and mode 0.  The device is initialized to have a mapping mode of DISTORT, and a line color index of 1.

 -- operation+ on starbase-graphics-device: write-image-file filename invert?
     This operation writes an image of the Starbase device's display in the file specified by FILENAME.  The image is formatted to print on an HP Laserjet printer.  Normally pixels with a color index of 0 are not drawn by the printer, and all other pixels are; this results in the background being white and the foreground being black in the printed image.  If INVERT? is not #f, this is reversed: the background is printed as black and the foreground is not printed.

 -- operation+ on starbase-graphics-device: color-map-size
     Returns, as an exact non-negative integer, the number of entries in the color map for the device.

 -- operation+ on starbase-graphics-device: define-color color-index red green blue
     Defines the color associated with the color-map index COLOR-INDEX. COLOR-INDEX must be an exact non-negative integer strictly less than the number of entries in the color map.  RED, GREEN, and BLUE must be real numbers in the range 0 to 1 inclusive, which define the color to be put in the map.

 -- operation+ on starbase-graphics-device: set-line-color color-index
     Changes the foreground color used in graphics operations for this device.  COLOR-INDEX must be an exact non-negative integer strictly less than the number of entries in the color map.  Graphics drawn after this operation is invoked will appear in this new color.

The text drawn by a Starbase device is controlled by the following characteristics:

Aspect
     The aspect of a character is its height-to-width ratio, a real number.  By default, this has the value 1.

Height
     The height of a character in virtual device coordinates, a real number.  This is measured along the ``up vector'', which is defined by the slant of the character.  By default, the height is .1.

Rotation
     The rotation of a character defines the direction in which the characters are drawn.  It is specified as a real number in degrees, but only 4 values have any meaning: 0, 90, 180, and 270.  0 draws left-to-right with upright characters; 90 draws top-to-bottom with characters on their right side; 180 draws right-to-left with upside-down characters; 270 draws bottom-to-top with characters on their left side.  The default rotation is 0.

Slant
     The slant of a character defines the ``up vector''; it is a real number which is the tangent of the angle between the character's ``vertical'' (defined by the rotation), and the ``up vector'', measured clockwise.  The default slant is 0.

 -- operation+ on starbase-graphics-device: text-aspect
 -- operation+ on starbase-graphics-device: text-height
 -- operation+ on starbase-graphics-device: text-rotation
 -- operation+ on starbase-graphics-device: text-slant
     These operations return the current values of the text characteristics.

 -- operation+ on starbase-graphics-device: set-text-aspect aspect
 -- operation+ on starbase-graphics-device: set-text-height height
 -- operation+ on starbase-graphics-device: set-text-rotation rotation
 -- operation+ on starbase-graphics-device: set-text-slant slant
     These operations alter the current values of the text characteristics. They have no effect on text drawn prior to their invocation.

Win32 Package Reference
***********************

The Win32 implementation is still in a state of development.  It is expected that changes will be necessary when MIT Scheme is ported to Windows NT on the DEC Alpha architecture.  In particular, the current system is not arranged in a way that adequately distinguishes between issues that are a consequence of the NT operating system and those which are a consequence of the Intel x86 architecture.

Overview
========

The Win32 implementation is still in a state of development.  It is expected that changes will be necessary when MIT Scheme is ported to Windows NT on the DEC Alpha architecture.  In particular, the current system is not arranged in a way that adequately distinguishes between issues that are a consequence of the NT operating system and those which are a consequence of the Intel x86 architecture.

Thus this documentation is not definitive, it merely outlines how the current system works.  Parts of the system will change and any project implemented using the win32 system must plan for a re-implementation stage.

The Win32 implementation has several components:

  * Special microcode primitives.

  * A foreign function interface (FFI) for calling procedures in dynamically linked libraries (DLLs).

  * An interface for Edwin.

  * The Win32 package provides support for using the features of the Windows 3.1 and Windows NT 3.1 environments.

  * Device Independent Bitmap utilities.  These are used by the win32 Scheme Graphics implementation.  (The Scheme Graphics implementation is described in the Reference Manual).

Note that all the names in the Win32 support are part of the win32 package.  The names are bound in the (win32) environment, and do not appear as bindings in the user or root environments. An effect of this is that it is far easier to develop Win32 software in the (win32) package environment or a child environment.

Foreign Function Interface
==========================

The Win32 foreign function interface (FFI) is a primitive and fairly simple system for calling procedures written in C in a dynamically linked library (DLL).  Both user's procedures from a custom DLL and system procedures (e.g. MessageBox) are called using the same mechanism.

Warning: The FFI as it stands has several flaws which make it difficult to use reliably.  It is expected that both the interface to and the mechanisms used by the FFI will be changed in the future.  We provide it, and this documentation, only to give people an early start in accessing some of the features of Win32 from Scheme.  Should you use it in an experiment we welcome any feedback.

The FFI is designed for calling C procedures that use C data types rather than Scheme data objects.  Thus it is not possible to write and call a C procedure that returns, for example, a Scheme list.  The object returned will always be an integer (which may represent the address of a C data structure).

Warning: It is extremely dangerous to try to pass Scheme callback procedures to C procedures.  It is only possible by passing integer `handles' rather than the actual procedures, and even so, if a garbage collection occurs during the execution of the callback procedure objects in Scheme's heap will have moved.  Thus in a foreign procedure that has a callback and a string, after calling the callback the string value may no longer be valid.  Playing this game requires a profound knowledge of the implementation.

The interface to the FFI has two main components: a language for declaring the types of values passed to and returned from the foreign procedures and a form for declaring foreign procedures.

Windows Types
-------------

Foreign types are designed to represent a correspondence between a Scheme data type that is used to represent an object within the Scheme world and a C data type that represents the data object in the C world. Thus we cannot manipulate true C objects in Scheme, nor can we manipulate Scheme objects in C.

Each foreign type has four aspects that together ensure that the correspondence between the Scheme and C objects is maintained.  These aspects are all encoded as procedures that either check for validity or convert between representations.  Thus a foreign type is not a declarative type so much as a procedural description of how to pass the type.  The underlying foreign procedure call mechanism can pass integers and vector-like Scheme objects, and returns integer values.  All other objects must be translated into integers or some other basic type, and must be recovered from integers.

The aspects are:

check
     A predicate that returns #t if the argument is of an acceptable Scheme type, otherwise returns #f. The CHECK procedure is used for type-checking.

convert
     A procedure of one argument which returns a Scheme object of one of the basic types. It is used to convert an object into a `simpler' object that will eventually be converted into a C object. The legal simpler objects are integers and strings.

return-convert
     A procedure of one argument that, given an integer, returns a Scheme object of a type satisfying CHECK. Its purpose is to convert the result returned by the foreign procedure into a Scheme value.

revert
     Some C procedures modify one or more of their arguments.  These arguments are passed by reference, i.e. as a pointer to their address. Since a Scheme object might have a different memory layout and storage conventions, it must be passed by copy-in and copy-out rather than by reference. REVERT is a procedure of two parameters, the original object passed and the result of CONVERT on that object. REVERT may then inspect the converted object and copy back the changes to the original.

 -- special form+: define-windows-type name check convert return revert
 -- special form+: define-similar-windows-type name model [check [convert [return [revert]]]]
     Both forms define a windows type. The first form defines a type in terms of its aspects as described above. The second defines the type as being like another type, except for certain aspects, which are redefined. NAME is the name of the type. MODEL is the name of a type. CHECK, CONVERT, RETURN and REVERT are procedures or the value #f. A #f means use the default value, which in the second form means use the definition provided for MODEL. The defaults are

     check
          (lambda (x) #t), i.e. unchecked.

     convert
          (lambda (x) x), i.e. no translation performed.

     return
          (lambda (x) x), i.e. no translation performed.

     revert
          (lambda (x y) unspecific), i.e. no update performed

     The unchecked windows type (see below) is defined as:

          (define-windows-type unchecked #f #f #f #f)

     Windows types are not first class values, so they cannot be stored in variables or defined using define:

          (define my-type unchecked)                       error-->  Unbound variable
          (define-similar-windows-type my-type unchecked)  ;; the correct way

     Scheme characters must be converted to integers.  This is accomplished as follows:

          (define-windows-type char
             char?          ; check
             char->integer  ; convert
             integer->char  ; convert return value
             #f             ; cannot be passed by reference
          )

 -- windows type: unchecked
     The type which is not checked and undergoes only the basic conversion from a Scheme integer to a C integer or from a Scheme string to a C pointer to the first byte of the string. Returned unchecked values are returned as integers.

 -- windows type: bool
     Scheme booleans are analogous to C integers 0 and 1. Windows type bool have been defined as:

          (define-windows-type bool
             boolean?
             (lambda (x) (if x 1 0))
             (lambda (x) (if (eq? x 0) #f #t))
             #f)

 -- windows type: char
     Scheme characters are converted into C objects of type char, which are indistinguishable from small integers.

 -- windows type: int
 -- windows type: uint
 -- windows type: long
 -- windows type: ulong
 -- windows type: short
 -- windows type: ushort
 -- windows type: word
 -- windows type: byte
     Various integer types that are passed without conversion.

 -- windows type: string
     A string that is passed as a C pointer of type char* to the first character in the string.

 -- windows type: char*
     A string or #f.  The string is passed as a pointer to characters. The string is correctly null-terminated.  #f is passed as the null pointer.  This is an example where there is a more complex mapping between C objects and Scheme objects.  C's char* type is represented as one of two Scheme types depending on its value.  This allows us us to distinguish between the C string (pointer) that points to the empty sequence of characters and the null pointer (which doesnt point anywhere).

 -- windows type: handle
 -- windows type: hbitmap
 -- windows type: hbrush
 -- windows type: hcursor
 -- windows type: hdc
 -- windows type: hicon
 -- windows type: hinstance
 -- windows type: hmenu
 -- windows type: hpalette
 -- windows type: hpen
 -- windows type: hrgn
 -- windows type: hwnd
     Various kinds of Win32 handle.  These names correspond to the same, but all uppercase, names in the Windows C language header files.  Win32 API calls are the source of values of this type and the values are meaningless except as arguments to other Win32 API calls.  Currently these values are represented as integers but we expect that Win32 handles will in future be represented by allocated Scheme objects (e.g. records) that will allow predicates (e.g. hmenu?) and sensible interlocking with the garbage collector to free the programmer of the current tedious allocation and deallocation of handles.

 -- windows type: resource-id
     A Windows resource identifier is either a small integer or a string. In C, this distinction is possible because pointers look like larger integers, so a machine word representing a small integer can be distinguished from a machine word that is a pointer to the text of the name of the resource.

Windows Foreign Procedures
--------------------------

Foreign procedures are declared as callable entry-points in a module, usually a dynamically linked library (DLL).

 -- procedure+: find-module name
     Returns a module suitable for use in creating procedures with windows-procedure.  NAME is a string which is the name of a DLL file.  Internally, find-module uses the LoadLibrary Win32 API, so NAME should conform to the specifications for this call.  NAME should be either a full path name of a DLL, or the name of a DLL that resides in the same directory as the Scheme binary SCHEME.EXE or in the system directory.

     The module returned is a description for the DLL, and the DLL need not necessarily be linked at or immediately after this call.  DLL modules are linked on need and unlinked before Scheme exits and when there are no remaining references to entry points after a garbage-collection. This behaviour ensures that the Scheme system can run when a DLL is absent, provided the DLL is not actually used (i.e. no attempt is made to call a procedure in the DLL).

 -- variable+: gdi32.dll
     This variable is bound to the module describing the GDI32.DLL library, which contains the Win32 API graphics calls, e.g. LineTo.

 -- variable+: kernel32.dll
     This variable is bound to the module describing the KERNEL32.DLL library.

 -- variable+: user32.dll
     This variable is bound to the module describing the USER32.DLL library.  This module contains many useful Win32 API procedures, like MessageBox and SetWindowText.

 -- special form+: windows-procedure (name (parameter type) ...) return-type module entry-name [options]
     This form creates a procedure, and could be thought of as ``foreign-named-lambda''.  The form creates a Scheme procedure that calls the C procedure identified by the exported entry point ENTRY-NAME in the module identified by the value of MODULE. Both ENTRY-NAME and MODULE are evaluated at procedure creation time, so either may be expression.  ENTRY-NAME must evaluate to a string and MODULE must evaluate to a module as returned by find-module. These are the only parts of the form that are evaluated at procedure creation time.

     NAME is the name of the procedure and is for documentation purposes only.  This form does not define a procedure called NAME.  It is more like lambda.  The name might be used for debugging and pretty-printing.

     A windows procedure has a fixed number of parameters (i.e. no `rest' parameters or `varargs'), each of which is named and associated with a windows type TYPE.  Both the name PARAMETER and the windows type TYPE must be symbols and are not evaluated.  The procedure returns a value of the windows type RETURN-TYPE.

     The following example creates a procedure that takes a window handle (hwnd) and a string and returns a boolean (bool) result. The procedure does this by calling the SetWindowText entry in the module that is the value of the variable user32.dll.  The variable set-window-title is defined to have this procedure as it's value.

          (define set-window-title
            (windows-procedure (set-window-text (window hwnd) (text string))
              bool user32.dll "SetWindowText"))

          (set-window-title my-win "Hi")   =>  #t
                                           ;; Changes window's title/text

          set-window-title                 =>  #[compiled-procedure  ...]
          set-window-text                  error-->  Unbound variable

     When there are no OPTIONS the created procedure will (a) check its arguments against the types, (b) convert the arguments, (c) call the C procedure and (d) convert the returned value.  No reversion is performed, even if one of the TYPES has a reversion defined. (Reverted types are rare [I have never used one], so paying a cost for this unless it is used seems silly).

     The following options are allowed:

     with-reversions
          The reversions are included in the type conversions.

     expand
          A synonym for with-reversions.

     SCHEME CODE
          The SCHEME CODE is placed between steps (a) and (b) in the default process.  The Scheme code can enforce constraints on the arguments, including constraints between arguments such as checking that an index refers to a valid position in a string.

     If both options (i.e. with-reversions and Scheme code) are used, with-reversions must appear first.  There can be arbitrarily many Scheme expression.

Win32 API names and procedures
------------------------------

This section is a moving target.

The #define values from wingdi.h and winuser.h are available as bindings in the (win32) package environment.  The #define symbols are all uppercase; these have been translated to all lowercase Scheme identifiers, thus WM_LBUTTONUP is the scheme variable wm_lbuttonup.  As Scheme is case insensitive, the upper-case version may be used and probably should to make the code look more like conventional Windows code.  The Scheme bindings have been produced automagically.  Most of the #define-symbols contain an underscore so there are not many name clashes.  There is one very notable name clash, however: ERROR is #defined to 0, which shadows the scheme procedure error in the root package environment.  To signal an error, use access:

     ((access error ()) "Whine moan" ...)

The set of procedures is incomplete because procedures have been added on a by-need basis for the implementation of other parts of the system, e.g.  Scheme Graphics.  Look in the implementation for further details.

Win32 API procedure names have been uniformly converted into Scheme identifiers as follows:

  * A leading uppercase letter is translated into a lowercase letter.

  * Subsequent sequences of uppercase letters are translated into lowercase letters preceeded by a hyphen (minus symbol), i.e. hyphens are inserted at a lowercase to uppercase transition.

  * Predicates beginning with Is finally have a question-mark appended.

Example: applying these rules to IsWindow yields is-window?, and GetDC is translated into get-dc.

Device Independent Bitmap Utilities
===================================

The Device Independent Bitmap (DIB) utilities library DIBUTILS.DLL and the associated procedures in dib.scm in the Win32 system source is an example of how to use the foreign function interface to access and manipulate non-Scheme objects.

 -- windows type: dib
     In the C world a DIB is a handle to a piece of memory containing the bits that represent information about the image and the pixels of the image.  The handle is a machine-word sized piece of data which may be thought of as a 32 bit integer.  The handle may be null (i.e. zero), indicating that there is no block of memory describing the DIB.  The null value is usually returned by C functions that are supposed to create a DIB but failed, for some reason like the memory could not be allocated or a file could not be opened.

     In the Scheme world a DIB is a structure containing information about the bitmap (specifically the integer that represents the handle). We also include #f in the dib windows type to mirror the null handle error value.

          (define dib-result
            (lambda (handle)
              (if (= handle 0)
                  #f
                  (make-dib handle))))

          (define dib-arg
            (lambda (dib)
              (if dib
                  (cell-contents (dib-handle dib))
                  0)))

          (define-windows-type dib
            (lambda (thing) (or (dib? thing) (eq? thing #f)))
            dib-arg
            dib-result)

DIB procedures
--------------

The following procedures have typed parameters, using the same convention as windows-procedure.

 -- procedure+: open-dib (filename string)
     Return type: DIB.  Calls the OpenDIB entry of DIBUTILS.DLL.  If the return value is not #f then the file FILENAME was found, successfully opened, and the contents were suitable for loading into memory as a device independent bitmap.

 -- procedure+: write-dib (filename string) (dib dib)
     Return type: BOOL.  Calls the WriteDIB entry of DIBUTILS.DLL.  Returns #t if the file FILENAME could be opened and written to.  After this operation the file contains the bitmap data in a standard format that is understood by open-dib and various system utilities like the bitmap editor.  Any problems resulting in failure are signalled by a #f return value.

 -- procedure+: bitmap-from-dib (dib dib) (palette hpalette)
     Return type: HBITMAP. Calls the BitmapFromDib entry of DIBUTILS.DLL.  The returned value is a device dependent bitmap.  The colours from the DIB are matched against colors in PALETTE.

 -- procedure+: dib-from-bitmap (bitmap hbitmap) (style dword) (bits word) (palette hpalette)
     Return type: DIB. Returns a DIB containing the same image as the device dependent bitmap BITMAP. STYLE determines the kind of DIB, e.g. compression style. Calls the DibFromBitmap entry of DIBUTILS.DLL.

 -- procedure+: dib-blt (dest hdc) (x int) (y int) (w int) (h int) (src dib) (src-x int) (src-y int) (raster-op long)
     Return type: BOOL.  Calls the DibBlt entry of DIBUTILS.DLL.  Similar to the Win32 API BitBlt call, but draws a DIB rather than a piece of another device context.  Draws the DIB on device context HDC at position (X,Y).  A rectangle of width W and height H is copied from position (SRC-X,SRC-Y) of DIB. RASTER-OP is supposed to allow the source and destination to be combined but I don't think I got this right so stick to SRCCOPY.

 -- procedure+: %delete-dib (dib-handle handle)
     Return type: BOOL. Calls the DeleteDIB entry of DIBUTILS.DLL. Note that the parameter is a HANDLE, and not a DIB. This allows us to destroy a DIB and reclaim its memory by knowing only the handle value, and not needing the dib record. The importance of this is that if the dib record is GC-ed then a GC hook can reclaim the storage knowing only the handle.

 -- procedure+: delete-dib (dib dib)
     Return type: BOOL. This procedure calls %delete-dib to reclaim the storage occupied by a DIB. After being deleted, the DIB should not be used. This procedure allows the programmer to reclaim external heap storage rather than risking it running out before the next garbage collection.

 -- procedure+: dib-height (dib dib)
     Return type: INT. Calls the DibHeight expand entry of DIBUTILS.DLL, which returns the height of the bitmap in pixels.

 -- procedure+: dib-width (dib dib)
     Return type: INT. Calls the DibWidth entry of DIBUTILS.DLL, which returns the width of the bitmap in pixels.

 -- procedure+: copy-bitmap (bm hbitmap)
     Return type: HBITMAP. Calls the CopyBitmap of DIBUTILS.DLL, which creates a new bitmap with the same size and contents as the original.

 -- procedure+: create-dib (width int) (height int) (style int) (depth int) (palette hpalette)
     Return type: DIB. Calls the CreateDIB entry of DIBUTILS.DLL. Creates a DIB of WIDTH by HEIGHT pixels and DEPTH bits of colour information. The STYLE parameter determines how the bitmap is stored. I have only ever used BI_RGB. If DEPTH<=8 then the PALETTE determines the DIB's colour table.

 -- procedure+: crop-bitmap (bm hbitmap) (left int) (top int) (right int) (bottom int)
     Return type: HBITMAP. Calls the CropBitmap entry of DIBUTILS.DLL. Returns a new bitmap containing the image from a region of the original.

 -- procedure+: dib-set-pixels-unaligned dib (pixels string)
     Return type: BOOL. Calls the DIBSetPixelsUnaligned entry of DIBUTILS.DLL.  Stuffs bytes from PIXELS into the bitmap.  There are no alignment constraints on PIXELS (the usual way of doing this is to use the SetDIBits function which requires that every scan line of the bitmap is 32-bit word aligned, even if the scan lines are not a multiple of 4 bytes long).  doing this

Other parts of the DIB Utilities implementation
-----------------------------------------------

The DIBUTILS.DLL library is an ordinary DLL.  See the standard Microsoft Windows documentation on how to create DLLs.  Look at the code in the WIN32/DIBUTILS directory of the Scheme source.

Please note:

  * For the foreign function interface to find the procedures they must be declared as exports in the .DEF definition file.

  * To load the .DLL file use the find-module Scheme function. Look at WIN32/DIB.SCM to see how this is done.

  * The current system works with C procedures with the __stdcall and __cdecl calling conventions but not the __fastcall calling convention.