Revised(7) Report on the Algorithmic Language Scheme

2.3.1 Base and optional features

Every identifier defined in this report appears in one or more of several libraries. Identifiers defined in the base library are not marked specially in the body of the report. This library includes the core syntax of Scheme and generally useful procedures that manipulate data. For example, the variable abs is bound to a procedure of one argument that computes the absolute value of a number, and the variable + is bound to a procedure that computes sums. The full list all the standard libraries and the identifiers they export is given in Appendix A. Standard Libraries.

All implementations of Scheme:

• Must provide the base library and all the identifiers exported from it.
• May provide or omit the other libraries given in this report, but each library must either be provided in its entirety, exporting no additional identifiers, or else omitted altogether.
• May provide other libraries not described in this report.
• May also extend the function of any identifier in this report, provided the extensions are not in conflict with the language reported here.
• Must support portable code by providing a mode of operation in which the lexical syntax does not conflict with the lexical syntax described in this report.

2.3.2 Error situations and unspecified behavior

When speaking of an error situation, this report uses the phrase “an error is signaled” to indicate that implementations must detect and report the error. An error is signaled by raising a non-continuable exception, as if by the procedure raise as described in Exceptions. The object raised is implementation-dependent and need not be distinct from objects previously used for the same purpose. In addition to errors signaled in situations described in this report, programmers can signal their own errors and handle signaled errors.

The phrase “an error that satisfies predicate is signaled” means that an error is signaled as above. Furthermore, if the object that is signaled is passed to the specified predicate (such as file-error? or read-error?), the predicate returns #t.

If such wording does not appear in the discussion of an error, then implementations are not required to detect or report the error, though they are encouraged to do so. Such a situation is sometimes, but not always, referred to with the phrase “an error.” In such a situation, an implementation may or may not signal an error; if it does signal an error, the object that is signaled may or may not satisfy the predicates error-object?, file-error?, or read-error?. Alternatively, implementations may provide non-portable extensions.

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

This report uses the phrase “may report a violation of an implementation restriction” to indicate circumstances under which an implementation is permitted to report that it is unable to continue execution of a correct program because of some restriction imposed by the implementation. Implementation restrictions are discouraged, but implementations are encouraged to report violations of implementation restrictions.

For example, an implementation may report a violation of an implementation restriction if it does not have enough storage to run a program, or if an arithmetic operation would produce an exact number that is too large for the implementation to represent.

If the value of an expression is said to be “unspecified,” then the expression must evaluate to some object without signaling an error, but the value depends on the implementation; this report explicitly does not say what value is returned.

Finally, the words and phrases “must,” “must not,” “shall,” “shall not,” “should,” “should not,” “may,” “required,” “recommended,” and “optional,” although not capitalized in this report, are to be interpreted as described in RFC 2119 [3]. They are used only with reference to implementer or implementation behavior, not with reference to programmer or program behavior.

2.3.3 Entry format

This section is incomplete. The Texinfo entry format differs from that of the R⁷RS PDF, and may be described here when the format is stable.

Chapters Expressions and Standard procedures are organized into entries. Each entry describes one language feature or a group of related features, where a feature is either a syntactic construct or a procedure.

[…]

It is an error for a procedure to be presented with an argument that it is not specified to handle. For succinctness, we follow the convention that if an argument name is also the name of a type listed in Disjointness of types, then it is an error if that argument is not of the named type. For example, the header line for vector-ref given above dictates that the first argument to vector-ref is a vector. The following naming conventions also imply type restrictions:

alist

association list (list of pairs)

boolean

boolean value (#t or #f)

byte

exact integer 0 ≤ byte < 256

bytevector

bytevector

char

character

end

exact non-negative integer

k, k₁, … k_j, …

exact non-negative integer

letter

alphabetic character

list, list₁, … list_j, …

list (see Pairs and lists)

n, n₁, … n_j, …

integer

obj

any object

pair

pair

port

port

proc

procedure

q, q₁, … q_j, …

rational number

start

exact non-negative integer

string

string

symbol

symbol

thunk

zero-argument procedure

vector

vector

x, x₁, … x_j, …

real number

y, y₁, … y_j, …

real number

z, z₁, … z_j, …

complex number

The names start and end are used as indexes into strings, vectors, and bytevectors. Their use implies the following:

• It is an error if start is greater than end.
• It is an error if end is greater than the length of the string, vector, or bytevector.
• If start is omitted, it is assumed to be zero.
• If end is omitted, it assumed to be the length of the string, vector, or bytevector.
• The index start is always inclusive and the index end is always exclusive. As an example, consider a string. If start and end are the same, an empty substring is referred to, and if start is zero and end is the length of string, then the entire string is referred to.

2.3.4 Evaluation examples

The symbol ‘⇒’ used in program examples is read “evaluates to.” For example,

(* 5 8) ⇒ 40

means that the expression (* 5 8) evaluates to the object 40. Or, more precisely: the expression given by the sequence of characters “(* 5 8)” evaluates, in an environment containing the base library, to an object that can be represented externally by the sequence of characters “40.” See External representations for a discussion of external representations of objects.

2.3.5 Naming conventions

By convention, ‘?’ is the final character of the names of procedures that always return a boolean value. Such procedures are called predicates. Predicates are generally understood to be side-effect free, except that they may raise an exception when passed the wrong type of argument.

Similarly, ‘!’ is the final character of the names of procedures that store values into previously allocated locations (Storage model). Such procedures are called mutation procedures. The value returned by a mutation procedure is unspecified.

By convention, ‘->’ appears within the names of procedures that take an object of one type and return an analogous object of another type. For example, list->vector takes a list and returns a vector whose elements are the same as those of the list.

A command is a procedure that does not return useful values to its continuation.

A thunk is a procedure that does not accept arguments.

5.1.1 Variable references

syntax: ⟨variable⟩

An expression consisting of a variable (see Variables, syntactic keywords, and regions) is a variable reference. The value of the variable reference is the value stored in the location to which the variable is bound. It is an error to reference an unboundvariable.

(define x 28)
x ⇒ 28

5.1.2 Literal expressions

syntax: (quote ⟨datum⟩) syntax: ’⟨datum⟩ syntax: ⟨constant⟩

(quote ⟨datum⟩) evaluates to ⟨datum⟩. ⟨Datum⟩ can be any external representation of a Scheme object (See External representations (basic)). This notation is used to include literal constants in Scheme code.

(quote a)        ⇒ a
(quote #(a b c)) ⇒ #(a b c)
(quote (+ 1 2))  ⇒ (+ 1 2)

(quote ⟨datum⟩) can be abbreviated as '⟨datum⟩. The two notations are equivalent in all respects.

'a         ⇒ a
'#(a b c)  ⇒ #(a b c)
'()        ⇒ ()
'(+ 1 2)   ⇒ (+ 1 2)
'(quote a) ⇒ (quote a)
''a        ⇒ (quote a)

Numerical constants, string constants, character constants, vector constants, bytevector constants, and boolean constants evaluate to themselves; they need not be quoted.

'145932     ⇒ 145932
145932      ⇒ 145932
'"abc"      ⇒ "abc"
"abc"       ⇒ "abc"
'#\a        ⇒ #\a
#\a         ⇒ #\a
'#(a 10)    ⇒ #(a 10)
#(a 10)     ⇒ #(a 10)
'#u8(64 65) ⇒ #u8(64 65)
#u8(64 65)  ⇒ #u8(64 65)
'#t         ⇒ #t
#t          ⇒ #t

As noted in Storage model, it is an error to attempt to alter a constant (i.e. the value of a literal expression) using a mutation procedure like set-car! or string-set!.

5.1.3 Procedure calls

syntax: (⟨operator⟩ ⟨operand₁⟩ …)

A procedure call is written by enclosing in parentheses an expression for the procedure to be called followed by expressions for the arguments to be passed to it. The operator and operand expressions are evaluated (in an unspecified order) and the resulting procedure is passed the resulting arguments.

(+ 3 4)           ⇒ 7
((if #f + *) 3 4) ⇒ 12

The procedures in this document are available as the values of variables exported by the standard libraries. For example, the addition and multiplication procedures in the above examples are the values of the variables + and * in the base library. New procedures are created by evaluating lambda expressions (See Procedures).

Procedure calls can return any number of values (see values in Control features). Most of the procedures defined in this report return one value or, for procedures such as apply, pass on the values returned by a call to one of their arguments. Exceptions are noted in the individual descriptions.

Note: In contrast to other dialects of Lisp, the order of evaluation is unspecified, and the operator expression and the operand expressions are always evaluated with the same evaluation rules.

Note: Although the order of evaluation is otherwise unspecified, the effect of any concurrent evaluation of the operator and operand expressions is constrained to be consistent with some sequential order of evaluation. The order of evaluation may be chosen differently for each procedure call.

Note: In many dialects of Lisp, the empty list, (), is a legitimate expression evaluating to itself. In Scheme, it is an error.

5.1.4 Procedures

syntax: lambda ⟨formals⟩ ⟨body⟩ ¶

Syntax: ⟨Formals⟩ is a formal arguments list as described below, and ⟨body⟩ is a sequence of zero or more definitions followed by one or more expressions.

Semantics: A lambda expression evaluates to a procedure. The environment in effect when the lambda expression was evaluated is remembered as part of the procedure. When the procedure is later called with some actual arguments, the environment in which the lambda expression was evaluated will be extended by binding the variables in the formal argument list to fresh locations, and the corresponding actual argument values will be stored in those locations. (A fresh location is one that is distinct from every previously existing location.) Next, the expressions in the body of the lambda expression (which, if it contains definitions, represents a letrec* form—See Binding constructs) will be evaluated sequentially in the extended environment. The results of the last expression in the body will be returned as the results of the procedure call.

((lambda (x) (+ x x)) ⇒ a procedure
((lambda (x) (+ x x)) 4) ⇒ 8

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

(define add4
  (let ((x 4))
    (lambda (y) (+ x y))))
(add4 6) ⇒ 10

⟨Formals⟩ have one of the following forms:

• (⟨variable₁⟩ …): The procedure takes a fixed number of arguments; when the procedure is called, the arguments will be stored in fresh locations that are bound to the corresponding variables.
• ⟨variable⟩: The procedure takes any number of arguments; when the procedure is called, the sequence of actual arguments is converted into a newly allocated list, and the list is stored in a fresh location that is bound to ⟨variable⟩.
• (⟨variable₁⟩ … ⟨variable_n⟩ . ⟨variable_n+1⟩): If a space-delimited period precedes the last variable, then the procedure takes n or more arguments, where n is the number of formal arguments before the period (it is an error if there is not at least one). The value stored in the binding of the last variable will be a newly allocated list of the actual arguments left over after all the other actual arguments have been matched up against the other formal arguments.

It is an error for a ⟨variable⟩ to appear more than once in ⟨formals⟩.

((lambda x x) 3 4 5 6) ⇒ (3 4 5 6)
((lambda (x y . z) z)
 3 4 5 6)              ⇒ (5 6)

Each procedure created as the result of evaluating a lambda expression is (conceptually) tagged with a storage location, in order to make eqv? and eq? work on procedures (See Equivalence predicates).

5.1.5 Conditionals

syntax: if ⟨test⟩ ⟨consequent⟩ ⟨alternate⟩ ¶

syntax: if ⟨test⟩ ⟨consequent⟩ ¶

Syntax: ⟨Test⟩, ⟨consequent⟩, and ⟨alternate⟩ are expressions.

Semantics: An if expression is evaluated as follows: first, ⟨test⟩ is evaluated. If it yields a true value (See Booleans), then ⟨consequent⟩ is evaluated and its values are returned. Otherwise ⟨alternate⟩ is evaluated and its values are returned. If ⟨test⟩ yields a false value and no ⟨alternate⟩ is specified, then the result of the expression is unspecified.

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

5.1.6 Assignments

syntax: set! ⟨variable⟩ ⟨expression⟩ ¶

Semantics: ⟨Expression⟩ is evaluated, and the resulting value is stored in the location to which ⟨variable⟩ is bound. It is an error if ⟨variable⟩ is not bound either in some regionenclosing the set! expression or else globally. The result of the set! expression is unspecified.

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

5.1.7 Inclusion

syntax: include ⟨string₁⟩ ⟨string₂⟩… ¶

syntax: include-ci ⟨string₁⟩ ⟨string₂⟩… ¶

Semantics: Both include and include-ci take one or more filenames expressed as string literals, apply an implementation-specific algorithm to find corresponding files, read the contents of the files in the specified order as if by repeated applications of read, and effectively replace the include or include-ci expression with a begin expression containing what was read from the files. The difference between the two is that include-ci reads each file as if it began with the #!fold-case directive, while include does not.

Note: Implementations are encouraged to search for files in the directory which contains the including file, and to provide a way for users to specify other directories to search.

5.2.1 Conditionals

syntax: cond ⟨clause₁⟩ ⟨clause₂⟩… ¶

auxiliary syntax: else ¶

auxiliary syntax: => ¶

Syntax: ⟨Clauses⟩ take one of two forms, either

(⟨test⟩ ⟨expression1⟩ …)

where ⟨test⟩ is any expression, or

(⟨test⟩ => ⟨expression⟩)

The last ⟨clause⟩ can be an “else clause,” which has the form

(else ⟨expression1⟩ ⟨expression2⟩ …).

Semantics: A cond expression is evaluated by evaluating the ⟨test⟩ expressions of successive ⟨clause⟩s in order until one of them evaluates to a true value (See Booleans). When a ⟨test⟩ evaluates to a true value, the remaining ⟨expression⟩s in its ⟨clause⟩ are evaluated in order, and the results of the last ⟨expression⟩ in the ⟨clause⟩ are returned as the results of the entire cond expression.

If the selected ⟨clause⟩ contains only the ⟨test⟩ and no ⟨expression⟩s, then the value of the ⟨test⟩ is returned as the result. If the selected ⟨clause⟩ uses the => alternate form, then the ⟨expression⟩ is evaluated. It is an error if its value is not a procedure that accepts one argument. This procedure is then called on the value of the ⟨test⟩ and the values returned by this procedure are returned by the cond expression.

If all ⟨test⟩s evaluate to #f, and there is no else clause, then the result of the conditional expression is unspecified; if there is an else clause, then its ⟨expression⟩s are evaluated in order, and the values of the last one are returned.

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

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

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

syntax: case ⟨key⟩ ⟨clause₁⟩ ⟨clause₂⟩… ¶

Syntax: ⟨Key⟩ can be any expression. Each ⟨clause⟩ has the form

((⟨datum1⟩ …) ⟨expression1⟩ ⟨expression2⟩ …),

where each ⟨datum⟩ is an external representation of some object. It is an error if any of the ⟨datum⟩s are the same anywhere in the expression. Alternatively, a ⟨clause⟩ can be of the form

((⟨datum1⟩ …) => ⟨expression⟩)

The last ⟨clause⟩ can be an “else clause,” which has one of the forms

(else ⟨expression1⟩ ⟨expression2⟩ …)

or

(else => ⟨expression⟩).

Semantics: A case expression is evaluated as follows. ⟨Key⟩ is evaluated and its result is compared against each ⟨datum⟩. If the result of evaluating ⟨key⟩ is the same (in the sense of eqv?; See Equivalence predicates) to a ⟨datum⟩, then the expressions in the corresponding ⟨clause⟩ are evaluated in order and the results of the last expression in the ⟨clause⟩ are returned as the results of the case expression.

If the result of evaluating ⟨key⟩ is different from every ⟨datum⟩, then if there is an else clause, its expressions are evaluated and the results of the last are the results of the case expression; otherwise the result of the case expression is unspecified.

If the selected ⟨clause⟩ or else clause uses the => alternate form, then the ⟨expression⟩ is evaluated. It is an error if its value is not a procedure accepting one argument. This procedure is then called on the value of the ⟨key⟩ and the values returned by this procedure are returned by the case expression.

(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 => (lambda (x) x)))     ⇒  c

syntax: and ⟨test₁⟩… ¶

Semantics: The ⟨test⟩ expressions are evaluated from left to right, and if any expression evaluates to #f (See Booleans), then #f is returned. Any remaining expressions are not evaluated. If all the expressions evaluate to true values, the values of the last expression are 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

syntax: or ⟨test₁⟩… ¶

Semantics: The ⟨test⟩ expressions are evaluated from left to right, and the value of the first expression that evaluates to a true value (See Booleans) is returned. Any remaining expressions are not evaluated. If all expressions evaluate to #f or 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)

syntax: when ⟨test⟩ ⟨expression₁⟩ ⟨expression₂⟩… ¶

Syntax: The ⟨test⟩ is an expression.

Semantics: The test is evaluated, and if it evaluates to a true value, the expressions are evaluated in order. The result of the when expression is unspecified.

(when (= 1 1.0)
  (display "1")
  (display "2")) ⇒ unspecified
-| 12

syntax: unless ⟨test⟩ ⟨expression₁⟩ ⟨expression₂⟩… ¶

Syntax: The ⟨test⟩ is an expression.

Semantics: The test is evaluated, and if it evaluates to #f, the expressions are evaluated in order. The result of the unless expression is unspecified.

(unless (= 1 1.0)
  (display "1")
  (display "2")) ⇒ unspecified
-| nothing

syntax: cond-expand ⟨ce-clause₁⟩ ⟨ce-clause₂⟩… ¶

Syntax: The cond-expand expression type provides a way to statically expand different expressions depending on the implementation. A ⟨ce-clause⟩ takes the following form:

(⟨feature requirement⟩ ⟨expression⟩ …)

The last clause can be an “else clause,” which has the form

(else ⟨expression⟩ …)

A ⟨feature requirement⟩ takes one of the following forms:

• ⟨feature identifier⟩
• (library ⟨library name⟩)
• (and ⟨feature requirement⟩ …)
• (or ⟨feature requirement⟩ …)
• (not ⟨feature requirement⟩)

Semantics: Each implementation maintains a list of feature identifiers which are present, as well as a list of libraries which can be imported. The value of a ⟨feature requirement⟩ is determined by replacing each ⟨feature identifier⟩ and (library ⟨library name⟩) on the implementation’s lists with #t, and all other feature identifiers and library names with #f, then evaluating the resulting expression as a Scheme boolean expression under the normal interpretation of and, or, and not.

A cond-expand is then expanded by evaluating the ⟨feature requirement⟩s of successive ⟨ce-clause⟩s in order until one of them returns #t. When a true clause is found, the corresponding ⟨expression⟩s are expanded to a begin, and the remaining clauses are ignored. If none of the ⟨feature requirement⟩s evaluate to #t, then if there is an else clause, its ⟨expression⟩s are included. Otherwise, the behavior of the cond-expand is unspecified. Unlike cond, cond-expand does not depend on the value of any variables.

The exact features provided are implementation-defined, but for portability a core set of features is given in appendix B.

5.2.2 Binding constructs

The binding constructs let, let*, letrec, letrec*, let-values, and let*-values give Scheme a block structure, like Algol 60. The syntax of the first four constructs is identical, but they differ in the regions they establish for their variable bindings. In a let expression, the initial values are computed before any of the variables become bound; in a let* expression, the bindings and evaluations are performed sequentially; while in letrec and letrec* expressions, all the bindings are in effect while their initial values are being computed, thus allowing mutually recursive definitions. The let-values and let*-values constructs are analogous to let and let* respectively, but are designed to handle multiple-valued expressions, binding different identifiers to the returned values.

syntax: let ⟨bindings⟩ ⟨body⟩ ¶

Syntax: ⟨Bindings⟩ has the form

((⟨variable1⟩ ⟨init1⟩) …),

where each ⟨init⟩ is an expression, and ⟨body⟩ is a sequence of zero or more definitions followed by a sequence of one or more expressions as described in Expressions. It is an error for a ⟨variable⟩ to appear more than once in the list of variables being bound.

Semantics: The ⟨init⟩s are evaluated in the current environment (in some unspecified order), the ⟨variable⟩s are bound to fresh locations holding the results, the ⟨body⟩ is evaluated in the extended environment, and the values of the last expression of ⟨body⟩ are returned. Each binding of a ⟨variable⟩ has ⟨body⟩ as its region.

(let ((x 2) (y 3))
  (* x y))           ⇒ 6

(let ((x 2) (y 3))
  (let ((x 7)
        (z (+ x y)))
    (* z x)))        ⇒ 35

See also “named let,” Iteration.

syntax: let* ⟨bindings⟩ ⟨body⟩ ¶

Syntax: ⟨Bindings⟩ has the form

((⟨variable1⟩ ⟨init1⟩) …),

and ⟨body⟩ is a sequence of zero or more definitions followed by one or more expressions as described in Expressions.

Semantics: The let* binding construct is similar to let, but the bindings are performed sequentially from left to right, and the region of a binding indicated by (⟨variable⟩ ⟨init⟩) is that part of the let* expression to the right of the binding. Thus the second binding is done in an environment in which the first binding is visible, and so on. The ⟨variable⟩s need not be distinct.

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

syntax: letrec ⟨bindings⟩ ⟨body⟩ ¶

Syntax: ⟨Bindings⟩ has the form

((⟨variable1⟩ ⟨init1⟩) …),

and ⟨body⟩ is a sequence of zero or more definitions followed by one or more expressions as described in Expressions. It is an error for a ⟨variable⟩ to appear more than once in the list of variables being bound.

Semantics: The ⟨variable⟩s are bound to fresh locations holding unspecified values, the ⟨init⟩s are evaluated in the resulting environment (in some unspecified order), each ⟨variable⟩ is assigned to the result of the corresponding ⟨init⟩, the ⟨body⟩ is evaluated in the resulting environment, and the values of the last expression in ⟨body⟩ are returned. Each binding of a ⟨variable⟩ has the entire letrec expression as its region, making it possible to define mutually recursive procedures.

(letrec ((even?
          (lambda (n)
            (if (zero? n)
                #t
                (odd? (- n 1)))))
         (odd?
          (lambda (n)
            (if (zero? n)
                #f
                (even? (- n 1))))))
  (even? 88))
⇒ #t

One restriction on letrec is very important: if it is not possible to evaluate each ⟨init⟩ without assigning or referring to the value of any ⟨variable⟩, it is an error. The restriction is necessary because letrec is defined in terms of a procedure call where a lambda expression binds the ⟨variable⟩s to the values of the ⟨init⟩s. In the most common uses of letrec, all the ⟨init⟩s are lambda expressions and the restriction is satisfied automatically.

syntax: letrec* ⟨bindings⟩ ⟨body⟩ ¶

Syntax: ⟨Bindings⟩ has the form

((⟨variable1⟩ ⟨init1⟩) …),

and ⟨body⟩is a sequence of zero or more definitions followed by one or more expressions as described in Expressions. It is an error for a ⟨variable⟩ to appear more than once in the list of variables being bound.

Semantics: The ⟨variable⟩s are bound to fresh locations, each ⟨variable⟩ is assigned in left-to-right order to the result of evaluating the corresponding ⟨init⟩ (interleaving evaluations and assignments), the ⟨body⟩ is evaluated in the resulting environment, and the values of the last expression in ⟨body⟩ are returned. Despite the left-to-right evaluation and assignment order, each binding of a ⟨variable⟩ has the entire letrec* expression as its region, making it possible to define mutually recursive procedures.

If it is not possible to evaluate each ⟨init⟩ without assigning or referring to the value of the corresponding ⟨variable⟩ or the ⟨variable⟩ of any of the bindings that follow it in ⟨bindings⟩, it is an error. Another restriction is that it is an error to invoke the continuation of an ⟨init⟩ more than once.

;; Returns the arithmetic, geometric, and
;; harmonic means of a nested list of numbers
(define (means ton)
  (letrec*
     ((mean
        (lambda (f g)
          (f (/ (sum g ton) n))))
      (sum
        (lambda (g ton)
          (if (null? ton)
            (+)
            (if (number? ton)
                (g ton)
                (+ (sum g (car ton))
                   (sum g (cdr ton)))))))
      (n (sum (lambda (x) 1) ton)))
    (values (mean values values)
            (mean exp log)
            (mean / /))))

Evaluating (means '(3 (1 4))) returns three values: 8/3, 2.28942848510666 (approximately), and 36/19.

syntax: let-values ⟨mv binding spec⟩ ⟨body⟩ ¶

Syntax: ⟨Mv binding spec⟩ has the form

((⟨formals1⟩ ⟨init1⟩) …),

where each ⟨init⟩ is an expression, and ⟨body⟩ is zero or more definitions followed by a sequence of one or more expressions as described in Expressions. It is an error for a variable to appear more than once in the set of ⟨formals⟩.

Semantics: The ⟨init⟩s are evaluated in the current environment (in some unspecified order) as if by invoking call-with-values, and the variables occurring in the ⟨formals⟩ are bound to fresh locations holding the values returned by the ⟨init⟩s, where the ⟨formals⟩ are matched to the return values in the same way that the ⟨formals⟩ in a lambda expression are matched to the arguments in a procedure call. Then, the ⟨body⟩ is evaluated in the extended environment, and the values of the last expression of ⟨body⟩ are returned. Each binding of a ⟨variable⟩ has ⟨body⟩ as its region.

It is an error if the ⟨formals⟩ do not match the number of values returned by the corresponding ⟨init⟩.

(let-values (((root rem) (exact-integer-sqrt 32)))
  (* root rem)) ⇒ 35

syntax: let*-values ⟨mv binding spec⟩ ⟨body⟩ ¶

Syntax: ⟨Mv binding spec⟩ has the form

((⟨formals⟩ ⟨init⟩) …),

and ⟨body⟩ is a sequence of zero or more definitions followed by one or more expressions as described in Expressions. In each ⟨formals⟩, it is an error if any variable appears more than once.

The let*-values construct is similar to let-values, but the ⟨init⟩s are evaluated and bindings created sequentially from left to right, with the region of the bindings of each ⟨formals⟩ including the ⟨init⟩s to its right as well as ⟨body⟩. Thus the second ⟨init⟩ is evaluated in an environment in which the first set of bindings is visible and initialized, and so on.

(let ((a 'a) (b 'b) (x 'x) (y 'y))
  (let*-values (((a b) (values x y))
                ((x y) (values a b)))
    (list a b x y))) ⇒ (x y x y)

5.2.3 Sequencing

Both of Scheme’s sequencing constructs are named begin, but the two have slightly different forms and uses:

syntax: begin ⟨expression or definition⟩… ¶

This form of begin can appear as part of a ⟨body⟩, or at the outermost level of a ⟨program⟩, or at the REPL, or directly nested in a begin that is itself of this form. It causes the contained expressions and definitions to be evaluated exactly as if the enclosing begin construct were not present.

Rationale: This form is commonly used in the output of macros (See Macros) which need to generate multiple definitions and splice them into the context in which they are expanded.

syntax: begin ⟨expression₁⟩ ⟨expression₂⟩… ¶

This form of begin can be used as an ordinary expression. The ⟨expression⟩s are evaluated sequentially from left to right, and the values of the last ⟨expression⟩ are returned. This expression type is used to sequence side effects such as assignments or input and output.

(define x 0)

(and (= x 0)
     (begin (set! x 5)
            (+ x 1))) ⇒ 6

(begin (display "4 plus 1 equals ")
       (display (+ 4 1)))
       ⇒ unspecified
-| 4 plus 1 equals 5

Note that there is a third form of begin used as a library declaration. See Library syntax

5.2.4 Iteration

syntax: do ¶

(do ((⟨variable1⟩ ⟨init1⟩ ⟨step1⟩)
     …)
    (⟨test⟩ ⟨expression⟩ …)
  ⟨command⟩ …)

Syntax: All of ⟨init⟩, ⟨step⟩, ⟨test⟩, and ⟨command⟩ are expressions.

Semantics: A do expression is an iteration construct. It specifies a set of variables to be bound, how they are to be initialized at the start, and how they are to be updated on each iteration. When a termination condition is met, the loop exits after evaluating the ⟨expression⟩s.

A do expression is evaluated as follows: The ⟨init⟩ expressions are evaluated (in some unspecified order), the ⟨variable⟩s are bound to fresh locations, the results of the ⟨init⟩ expressions are stored in the bindings of the ⟨variable⟩s, and then the iteration phase begins.

Each iteration begins by evaluating ⟨test⟩; if the result is false (See Booleans), then the ⟨command⟩ expressions are evaluated in order for effect, the ⟨step⟩ expressions are evaluated in some unspecified order, the ⟨variable⟩s are bound to fresh locations, the results of the ⟨step⟩s are stored in the bindings of the ⟨variable⟩s, and the next iteration begins.

If ⟨test⟩ evaluates to a true value, then the ⟨expression⟩s are evaluated from left to right and the values of the last ⟨expression⟩ are returned. If no ⟨expression⟩s are present, then the value of the do expression is unspecified.

The region of the binding of a ⟨variable⟩ consists of the entire do expression except for the ⟨init⟩s. It is an error for a ⟨variable⟩ to appear more than once in the list of do variables.

A ⟨step⟩ can 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

syntax: let ⟨variable⟩ ⟨bindings⟩ ⟨body⟩ ¶

“Named let” is a variant on the syntax of let which provides a more general looping construct than do and can also be used to express recursion. It has the same syntax and semantics as ordinary let except that ⟨variable⟩ is bound within ⟨body⟩ to a procedure whose formal arguments are the bound variables and whose body is ⟨body⟩. Thus the execution of ⟨body⟩ can be repeated by invoking the procedure named by ⟨variable⟩.

(let loop ((numbers '(3 -2 1 6 -5))
           (nonneg '())
           (neg '()))
  (cond ((null? numbers) (list nonneg neg))
        ((>= (car numbers) 0)
         (loop (cdr numbers)
               (cons (car numbers) nonneg)
               neg))
        ((< (car numbers) 0)
         (loop (cdr numbers)
               nonneg
               (cons (car numbers) neg)))))
          ⇒ ((6 1 3) (-5 -2))

5.2.5 Delayed evaluation

lazy library syntax: 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 can be asked (by the force procedure) to evaluate ⟨expression⟩, and deliver the resulting value. The effect of ⟨expression⟩ returning multiple values is unspecified.

lazy library syntax: delay-force ⟨expression⟩ ¶

The expression (delay-force expression) is conceptually similar to (delay (force expression)), with the difference that forcing the result of delay-force will in effect result in a tail call to (force expression), while forcing the result of (delay (force expression)) might not. Thus iterative lazy algorithms that might result in a long series of chains of delay and force can be rewritten using delay-force to prevent consuming unbounded space during evaluation.

lazy library procedure: force promise ¶

The force procedure forces the value of a promise created by delay, delay-force, or make-promise. If no value has been computed for the promise, then a value is computed and returned. The value of the promise must be cached (or “memoized”) so that if it is forced a second time, the previously computed value is returned. Consequently, a delayed expression is evaluated using the parameter values and exception handler of the call to force which first requested its value. If promise is not a promise, it may be returned unchanged.

(force (delay (+ 1 2)))   ⇒  3
(let ((p (delay (+ 1 2))))
  (list (force p) (force p)))
                               ⇒  (3 3)

(define integers
  (letrec ((next
            (lambda (n)
              (delay (cons n (next (+ n 1)))))))
    (next 0)))
(define head
  (lambda (stream) (car (force stream))))
(define tail
  (lambda (stream) (cdr (force stream))))

(head (tail (tail integers)))
                               ⇒  2

The following example is a mechanical transformation of a lazy stream-filtering algorithm into Scheme. Each call to a constructor is wrapped in delay, and each argument passed to a deconstructor is wrapped in force. The use of (delay-force …) instead of (delay (force …)) around the body of the procedure ensures that an ever-growing sequence of pending promises does not exhaust available storage, because force will in effect force such sequences iteratively.

(define (stream-filter p? s)
  (delay-force
   (if (null? (force s))
       (delay '())
       (let ((h (car (force s)))
             (t (cdr (force s))))
         (if (p? h)
             (delay (cons h (stream-filter p? t)))
             (stream-filter p? t))))))

(head (tail (tail (stream-filter odd? integers)))) ⇒ 5

The following examples are not intended to illustrate good programming style, as delay, force, and delay-force are mainly intended for programs written in the functional style. However, they do illustrate the property that only one value is computed for a promise, no matter how many times it is forced.

(define count 0)
(define p
  (delay (begin (set! count (+ count 1))
                (if (> count x)
                    count
                    (force p)))))
(define x 5)
p                   ⇒ a promise
(force p)           ⇒ 6
p                   ⇒ a promise, still
(begin (set! x 10)
       (force p))   ⇒ 6

Various extensions to this semantics of delay, force and delay-force are supported in some implementations:

• Calling force on an object that is not a promise may simply return the object.
• It may be the case that there is no means by which a promise can be operationally distinguished from its forced value. That is, expressions like the following may evaluate to either #t or to #f, depending on the implementation:

  (eqv? (delay 1) 1)         ⇒ unspecified
  (pair? (delay (cons 1 2))) ⇒ unspecified
  

• Implementations may implement “implicit forcing,” where the value of a promise is forced by procedures that operate only on arguments of a certain type, like cdr and *. However, procedures that operate uniformly on their arguments, like list, must not force them.

  (+ (delay (* 3 7)) 13) ⇒ unspecified
  (car
    (list (delay (* 3 7)) 13)) ⇒ a promise
  

lazy library procedure: promise? obj ¶

The promise? procedure returns #t if its argument is a promise, and #f otherwise. Note that promises are not necessarily disjoint from other Scheme types such as procedures.

lazy library procedure: make-promise obj ¶

The make-promise procedure returns a promise which, when forced, will return obj. It is similar to delay, but does not delay its argument: it is a procedure rather than syntax. If obj is already a promise, it is returned.

5.2.6 Dynamic bindings

The dynamic extent of a procedure call is the time between when it is initiated and when it returns. In Scheme, call-with-current-continuation (section 6.10) allows reentering a dynamic extent after its procedure call has returned. Thus, the dynamic extent of a call might not be a single, continuous time period.

This sections introduces parameter objects, which can be bound to new values for the duration of a dynamic extent. The set of all parameter bindings at a given time is called the dynamic environment.

procedure: make-parameter init ¶

procedure: make-parameter init converter ¶

Returns a newly allocated parameter object, which is a procedure that accepts zero arguments and returns the value associated with the parameter object. Initially, this value is the value of (converter init), or of init if the conversion procedure converter is not specified. The associated value can be temporarily changed using parameterize, which is described below.

The effect of passing arguments to a parameter object is implementation-dependent.

syntax: parameterize (⟨param₁⟩ ⟨value₁⟩)… ⟨body⟩ ¶

Syntax: Both ⟨param₁⟩ and ⟨value₁⟩ are expressions.

It is an error if the value of any ⟨param⟩ expression is not a parameter object.

Semantics: A parameterize expression is used to change the values returned by specified parameter objects during the evaluation of the body.

The ⟨param⟩ and ⟨value⟩ expressions are evaluated in an unspecified order. The ⟨body⟩ is evaluated in a dynamic environment in which calls to the parameters return the results of passing the corresponding values to the conversion procedure specified when the parameters were created. Then the previous values of the parameters are restored without passing them to the conversion procedure. The results of the last expression in the ⟨body⟩ are returned as the results of the entire parameterize expression.

Note: If the conversion procedure is not idempotent, the results of (parameterize ((x (x))) …), which appears to bind the parameter x to its current value, might not be what the user expects.

If an implementation supports multiple threads of execution, then parameterize must not change the associated values of any parameters in any thread other than the current thread and threads created inside ⟨body⟩.

Parameter objects can be used to specify configurable settings for a computation without the need to pass the value to every procedure in the call chain explicitly.

(define radix
  (make-parameter
   10
   (lambda (x)
     (if (and (exact-integer? x) (<= 2 x 16))
         x
         (error "invalid radix")))))

(define (f n) (number->string n (radix)))

(f 12)                    ⇒ "12"
(parameterize ((radix 2))
  (f 12))                 ⇒ "1100"
(f 12)                    ⇒ "12"

(radix 16)                ⇒ unspecified

(parameterize ((radix 0))
  (f 12))                 ⇒ error

5.2.7 Exception handling

syntax: guard ¶

(guard (⟨variable⟩
       ⟨cond clause1⟩ ⟨cond clause2⟩ …)
   ⟨body⟩)

Syntax: Each ⟨cond clause⟩ is as in the specification of cond.

Semantics: The ⟨body⟩ is evaluated with an exception handler that binds the raised object (see raise in Exceptions) to ⟨variable⟩ and, within the scope of that binding, evaluates the clauses as if they were the clauses of a cond expression. That implicit cond expression is evaluated with the continuation and dynamic environment of the guard expression. If every ⟨cond clause⟩’s ⟨test⟩ evaluates to #f and there is no else clause, then raise-continuable is invoked on the raised object within the dynamic environment of the original call to raise or raise-continuable, except that the current exception handler is that of the guard expression.

See Exceptions for a more complete discussion of exceptions.

(guard (condition
         ((assq 'a condition) => cdr)
         ((assq 'b condition)))
  (raise (list (cons 'a 42))))
⇒ 42

(guard (condition
         ((assq 'a condition) => cdr)
         ((assq 'b condition)))
  (raise (list (cons 'b 23))))
⇒ (b . 23)

5.2.8 Quasiquotation

syntax: quasiquote ⟨qq template⟩ ¶

syntax: `⟨qq template⟩ ¶

auxiliary syntax: unquote ¶

auxiliary syntax: , ¶

auxiliary syntax: unquote-splicing ¶

auxiliary syntax: ,@ ¶

“Quasiquote” expressions are useful for constructing a list or vector structure when some but not all of the desired structure is known in advance. If no commas appear within the ⟨qq template⟩, the result of evaluating `⟨qq template⟩ is equivalent to the result of evaluating '⟨qq template⟩. If a comma appears within the ⟨qq template⟩, however, the expression following the comma is evaluated (“unquoted”) and its result is inserted into the structure instead of the comma and the expression. If a comma appears followed without intervening whitespace by a commercial at-sign (@), then it is an error if the following expression does not evaluate to a list; the opening and closing parentheses of the list are then “stripped away” and the elements of the list are inserted in place of the comma at-sign expression sequence. A comma at-sign normally appears only within a list or vector ⟨qq template⟩.

Note: In order to unquote an identifier beginning with , it is necessary to use either an explicit unquote or to put whitespace after the comma, to avoid colliding with the comma at-sign sequence.

`(list ,(+ 1 2) 4) ⇒ (list 3 4)

(let ((name 'a)) `(list ,name ',name))
  ⇒ (list a (quote a))

`(a ,(+ 1 2) ,@(map abs '(4 -5 6)) b)
  ⇒  (a 3 4 5 6 b)

`(( foo ,(- 10 3)) ,@(cdr '(c)) . ,(car '(cons)))
  ⇒ ((foo 7) . cons)

`#(10 5 ,(sqrt 4) ,@(map sqrt '(16 9)) 8)
  ⇒ #(10 5 2 4 3 8)

(let ((foo '(foo bar)) (@baz 'baz))
  `(list ,@foo , @baz))
  ⇒ (list foo bar baz)

Quasiquote expressions can be nested. Substitutions are made only for unquoted components appearing at the same nesting level as the outermost quasiquote. 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)

A quasiquote expression may return either newly allocated, mutable objects or literal structure for any structure that is constructed at run time during the evaluation of the expression. Portions that do not need to be rebuilt are always literal. Thus, (let ((a 3)) `((1 2) ,a ,4 ,'five 6)) may be treated as equivalent to either of the following expressions:

`((1 2) 3 4 five 6)

(let ((a 3))
  (cons '(1 2)
        (cons a (cons 4 (cons 'five '(6))))))

However, it is not equivalent to this expression:

(let ((a 3)) (list (list 1 2) a 4 'five 6))

The two notations `⟨qq template⟩ and (quasiquote ⟨qq template⟩) are identical in all respects. ,⟨expression⟩ is identical to (unquote ⟨expression⟩), and ,@⟨expression⟩ is identical to (unquote-splicing ⟨expression⟩). The write procedure may output either format.

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

It is an error if any of the identifiers quasiquote, unquote, or unquote-splicing appear in positions within a ⟨qq template⟩ otherwise than as described above.

5.2.9 Case-lambda

library syntax: case-lambda ⟨clause⟩… ¶

Syntax: Each ⟨clause⟩ is of the form (⟨formals⟩ ⟨body⟩), where ⟨formals⟩ and ⟨body⟩ have the same syntax as in a lambda expression.

Semantics: A case-lambda expression evaluates to a procedure that accepts a variable number of arguments and is lexically scoped in the same manner as a procedure resulting from a lambda expression. When the procedure is called, the first ⟨clause⟩ for which the arguments agree with ⟨formals⟩ is selected, where agreement is specified as for the ⟨formals⟩ of a lambda expression. The variables of ⟨formals⟩ are bound to fresh locations, the values of the arguments are stored in those locations, the ⟨body⟩ is evaluated in the extended environment, and the results of ⟨body⟩ are returned as the results of the procedure call.

It is an error for the arguments not to agree with the ⟨formals⟩ of any ⟨clause⟩.

(define range
  (case-lambda
   ((e) (range 0 e))
   ((b e) (do ((r '() (cons e r))
               (e (- e 1) (- e 1)))
              ((< e b) r)))))

(range 3)    ⇒ (0 1 2)
(range 3 5)  ⇒ (3 4)

5.3.1 Binding constructs for syntactic keywords

The let-syntax and letrec-syntax binding constructs are analogous to let and letrec, but they bind syntactic keywords to macro transformers instead of binding variables to locations that contain values. Syntactic keywords can also be bound globally or locally with define-syntax; See Syntax definitions.

syntax: let-syntax ⟨bindings⟩ ⟨body⟩ ¶

Syntax: ⟨Bindings⟩ has the form

((⟨keyword⟩ ⟨transformer spec⟩) …)

Each ⟨keyword⟩ is an identifier, each ⟨transformer spec⟩ is an instance of syntax-rules, and ⟨body⟩ is a sequence of zero or more definitions followed by one or more expressions. It is an error for a ⟨keyword⟩ to appear more than once in the list of keywords being bound.

Semantics: The ⟨body⟩ is expanded in the syntactic environment obtained by extending the syntactic environment of the let-syntax expression with macros whose keywords are the ⟨keyword⟩s, bound to the specified transformers. Each binding of a ⟨keyword⟩ has ⟨body⟩ as its region.

(let-syntax ((given-that (syntax-rules ()
                     ((given-that test stmt1 stmt2 ...)
                      (if test
                          (begin stmt1
                                 stmt2 ...))))))
  (let ((if #t))
    (given-that if (set! if 'now))
    if))                           ⇒ now

(let ((x 'outer))
  (let-syntax ((m (syntax-rules () ((m) x))))
    (let ((x 'inner))
      (m))))                       ⇒ outer

syntax: letrec-syntax ⟨bindings⟩ ⟨body⟩ ¶

Syntax: Same as for let-syntax.

Semantics: The ⟨body⟩ is expanded in the syntactic environment obtained by extending the syntactic environment of the letrec-syntax expression with macros whose keywords are the ⟨keyword⟩s, bound to the specified transformers. Each binding of a ⟨keyword⟩ has the ⟨transformer spec⟩s as well as the ⟨body⟩ within its region, so the transformers can transcribe expressions into uses of the macros introduced by the letrec-syntax expression.

(letrec-syntax
    ((my-or (syntax-rules ()
              ((my-or) #f)
              ((my-or e) e)
              ((my-or e1 e2 ...)
               (let ((temp e1))
                 (if temp
                     temp
                     (my-or e2 ...)))))))
  (let ((x #f)
        (y 7)
        (temp 8)
        (let odd?)
        (if even?))
    (my-or x
           (let temp)
           (if y)
           y)))      ⇒ 7

5.3.2 Pattern language

syntax: syntax-rules ¶

auxiliary syntax: _ ¶

auxiliary syntax: … ¶

A ⟨transformer spec⟩ has one of the following forms:

(syntax-rules (⟨pattern literal⟩ …)
  ⟨syntax rule⟩ …)
(syntax-rules ⟨ellipsis⟩ (⟨pattern literal⟩ …)
  ⟨syntax rule⟩ …)

Syntax: It is an error if any of the ⟨pattern literal⟩s, or the ⟨ellipsis⟩ in the second form, is not an identifier. It is also an error if ⟨syntax rule⟩ is not of the form

(⟨pattern⟩ ⟨template⟩)

The ⟨pattern⟩ in a ⟨syntax rule⟩ is a list ⟨pattern⟩ whose first element is an identifier.

A ⟨pattern⟩ is either an identifier, a constant, or one of the following

(⟨pattern⟩ …)
(⟨pattern⟩ ⟨pattern⟩ … . ⟨pattern⟩)
(⟨pattern⟩ … ⟨pattern⟩ ⟨ellipsis⟩ ⟨pattern⟩ …)
(⟨pattern⟩ … ⟨pattern⟩ ⟨ellipsis⟩ ⟨pattern⟩ …
  . ⟨pattern⟩)
#(⟨pattern⟩ …)
#(⟨pattern⟩ … ⟨pattern⟩ ⟨ellipsis⟩ ⟨pattern⟩ …)

and a ⟨template⟩ is either an identifier, a constant, or one of the following

(⟨element⟩ …)
(⟨element⟩ ⟨element⟩ … . ⟨template⟩)
(⟨ellipsis⟩ ⟨template⟩)
#(⟨element⟩ …)

where an ⟨element⟩ is a ⟨template⟩ optionally followed by an ⟨ellipsis⟩. An ⟨ellipsis⟩ is the identifier specified in the second form of syntax-rules, or the default identifier … (three consecutive periods) otherwise.

Semantics: An instance of syntax-rules produces a new macro transformer by specifying a sequence of hygienic rewrite rules. A use of a macro whose keyword is associated with a transformer specified by syntax-rules is matched against the patterns contained in the ⟨syntax rule⟩s, beginning with the leftmost ⟨syntax rule⟩. When a match is found, the macro use is transcribed hygienically according to the template.

An identifier appearing within a ⟨pattern⟩ can be an underscore (_), a literal identifier listed in the list of ⟨pattern literal⟩s, or the ⟨ellipsis⟩. All other identifiers appearing within a ⟨pattern⟩ are pattern variables.

The keyword at the beginning of the pattern in a ⟨syntax rule⟩ is not involved in the matching and is considered neither a pattern variable nor a literal identifier.

Pattern variables match arbitrary input elements and are used to refer to elements of the input in the template. It is an error for the same pattern variable to appear more than once in a ⟨pattern⟩.

Underscores also match arbitrary input elements but are not pattern variables and so cannot be used to refer to those elements. If an underscore appears in the ⟨pattern literal⟩s list, then that takes precedence and underscores in the ⟨pattern⟩ match as literals. Multiple underscores can appear in a ⟨pattern⟩.

Identifiers that appear in (⟨pattern literal⟩ …) are interpreted as literal identifiers to be matched against corresponding elements of the input. An element in the input matches a literal identifier if and only if it is an identifier and either both its occurrence in the macro expression and its occurrence in the macro definition have the same lexical binding, or the two identifiers are the same and both have no lexical binding.

A subpattern followed by ⟨ellipsis⟩ can match zero or more elements of the input, unless ⟨ellipsis⟩ appears in the ⟨pattern literal⟩s, in which case it is matched as a literal.

More formally, an input expression E matches a pattern P if and only if:

• P is an underscore (_).
• P is a non-literal identifier; or
• P is a literal identifier and E is an identifier with the same binding; or
• P is a list (P₁ … P_n) and E is a list of n elements that match P₁ through P_n, respectively; or
• P is an improper list (P₁ P₂ … P_n . P_n+1) and E is a list or improper list of n or more elements that match P₁ through P_n respectively, and whose nth tail matches P_n+1; or
• P is of the form (P₁ … P_k P_e ⟨ellipsis⟩ P_m+1 … P_n) where E is a proper list of n elements, the first k of which match P₁ through P_k, respectively, whose next m − k elements each match P_e, whose remaining n − m elements match P_m+1 through P_n; or
• P is of the form (P₁ … P_k P_e ⟨ellipsis⟩ P_m+1 … P_n . P_x) where E is a list or improper list of n elements, the first k of which match P₁ through P_k, whose next m − k elements each match P_e, whose remaining n − m elements match P_m+1 through P_n, and whose nth and final cdr matches P_x; or
• P is a vector of the form #(P₁ … P_n) and E is a vector of n elements that match P₁ through P_n; or
• P is of the form #(P₁ … P_k P_e ⟨ellipsis⟩ P_m+1 … P_n) where E is a vector of n elements the first k of which match P₁ through P_k, whose next m − k elements each match P_e, and whose remaining n − m elements match P_m+1 through P_n; or
• P is a constant and E is equal to P in the sense of the equal? procedure.

It is an error to use a macro keyword, within the scope of its binding, in an expression that does not match any of the patterns.

When a macro use is transcribed according to the template of the matching ⟨syntax rule⟩, pattern variables that occur in the template are replaced by the elements they match in the input. Pattern variables that occur in subpatterns followed by one or more instances of the identifier ⟨ellipsis⟩ are allowed only in subtemplates that are followed by as many instances of ⟨ellipsis⟩. They are replaced in the output by all of the elements they match in the input, distributed as indicated. It is an error if the output cannot be built up as specified.

Identifiers that appear in the template but are not pattern variables or the identifier ⟨ellipsis⟩ are inserted into the output as literal identifiers. If a literal identifier is inserted as a free identifier then it refers to the binding of that identifier within whose scope the instance of syntax-rules appears. If a literal identifier is inserted as a bound identifier then it is in effect renamed to prevent inadvertent captures of free identifiers.

A template of the form (⟨ellipsis⟩ ⟨template⟩) is identical to ⟨template⟩, except that ellipses within the template have no special meaning. That is, any ellipses contained within ⟨template⟩ are treated as ordinary identifiers. In particular, the template (⟨ellipsis⟩ ⟨ellipsis⟩⟨)⟩ produces a single ⟨ellipsis⟩. This allows syntactic abstractions to expand into code containing ellipses.

(define-syntax be-like-begin
  (syntax-rules ()
    ((be-like-begin name)
     (define-syntax name
       (syntax-rules ()
         ((name expr (... ...))
          (begin expr (... ...))))))))

(be-like-begin sequence)
(sequence 1 2 3 4) ⇒ 4

As an example, if let and cond are defined as in Derived expression types then they are hygienic (as required) and the following is not an error.

(let ((=> #f))
  (cond (#t => 'ok))) ⇒ ok

The macro transformer for cond recognizes => as a local variable, and hence an expression, and not as the base identifier =>, which the macro transformer treats as a syntactic keyword. Thus the example expands into

(let ((=> #f))
  (if #t (begin => 'ok)))

instead of

(let ((=> #f))
  (let ((temp #t))
    (if temp ('ok temp))))

which would result in an invalid procedure call.

5.3.3 Signaling errors in macro transformers

syntax: syntax-error ⟨message⟩ ⟨args⟩… ¶

syntax-error behaves similarly to error (Exceptions) except that implementations with an expansion pass separate from evaluation should signal an error as soon as syntax-error is expanded. This can be used as a syntax-rules ⟨template⟩ for a ⟨pattern⟩ that is an invalid use of the macro, which can provide more descriptive error messages. ⟨message⟩ is a string literal, and ⟨args⟩ arbitrary expressions providing additional information. Applications cannot count on being able to catch syntax errors with exception handlers or guards.

(define-syntax simple-let
  (syntax-rules ()
    ((_ (head ... ((x . y) val) . tail)
        body1 body2 ...)
     (syntax-error
      "expected an identifier but got"
      (x . y)))
    ((_ ((name val) ...) body1 body2 ...)
     ((lambda (name ...) body1 body2 ...)
       val ...))))

6.3.1 Top level definitions

At the outermost level of a program, a definition

(define ⟨variable⟩ ⟨expression⟩)

has essentially the same effect as the assignment expression

(set! ⟨variable⟩ ⟨expression⟩)

if ⟨variable⟩ is bound to a non-syntax value. However, if ⟨variable⟩ is not bound, or is a syntactic keyword, then the definition will bind ⟨variable⟩ to a new location before performing the assignment, whereas it would be an error to perform a set! on an unbound variable.

(define add3
  (lambda (x) (+ x 3)))
(add3 3)                ⇒ 6
(define first car)
(first '(1 2))          ⇒ 1

6.3.2 Internal definitions

Definitions can occur at the beginning of a ⟨body⟩ (that is, the body of a lambda, let, let*, letrec, letrec*, let-values, let*-values, let-syntax, letrec-syntax, parameterize, guard, or case-lambda). Note that such a body might not be apparent until after expansion of other syntax. Such definitions are known as internal definitions as opposed to the global definitions described above. The variables defined by internal definitions are 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

An expanded ⟨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))))

Just as for the equivalent letrec* expression, it is an error if it is not possible to evaluate each ⟨expression⟩ of every internal definition in a ⟨body⟩ without assigning or referring to the value of the corresponding ⟨variable⟩ or the ⟨variable⟩ of any of the definitions that follow it in ⟨body⟩.

It is an error to define the same identifier more than once in the same ⟨body⟩.

Wherever an internal definition can occur, (begin ⟨definition₁⟩ …) is equivalent to the sequence of definitions that form the body of the begin.

6.3.3 Multiple-value definitions

Another kind of definition is provided by define-values, which creates multiple definitions from a single expression returning multiple values. It is allowed wherever define is allowed.

syntax: define-values ⟨formals⟩ ⟨expression⟩ ¶

It is an error if a variable appears more than once in the set of ⟨formals⟩.

Semantics: ⟨Expression⟩ is evaluated, and the ⟨formals⟩ are bound to the return values in the same way that the ⟨formals⟩ in a lambda expression are matched to the arguments in a procedure call.

(define-values (x y) (exact-integer-sqrt 17))
(list x y) ⇒ (4 1)

(let ()
  (define-values (x y) (values 1 2))
  (+ x y)) ⇒ 3

6.6.1 Library syntax

A library definition takes the following form:

(define-library ⟨library name⟩
  ⟨library declaration⟩ …)

⟨library name⟩ is a list whose members are identifiers and exact non-negative integers. It is used to identify the library uniquely when importing from other programs or libraries. Libraries whose first identifier is scheme are reserved for use by this report and future versions of this report. Libraries whose first identifier is srfi are reserved for libraries implementing Scheme Requests for Implementation. It is inadvisable, but not an error, for identifiers in library names to contain any of the characters | \ ? * < " : > + [ ] / or control characters after escapes are expanded.

A ⟨library declaration⟩ is any of:

• (export ⟨export spec⟩ …)
• (import ⟨import set⟩ …)
• (begin ⟨command or definition⟩ …)
• (include ⟨filename₁⟩ ⟨filename₂⟩ …)
• (include-ci ⟨filename₁⟩ ⟨filename₂⟩ …)
• (include-library-declarations ⟨filename₁⟩ ⟨filename₂⟩ …)
• (cond-expand ⟨ce-clause₁⟩ ⟨ce-clause₂⟩ …)

An export declaration specifies a list of identifiers which can be made visible to other libraries or programs. An ⟨export spec⟩ takes one of the following forms:

• ⟨identifier⟩
• (rename ⟨identifier₁⟩ ⟨identifier₂⟩)

In an ⟨export spec⟩, an ⟨identifier⟩ names a single binding defined within or imported into the library, where the external name for the export is the same as the name of the binding within the library. A rename spec exports the binding defined within or imported into the library and named by ⟨identifier₁⟩ in each (⟨identifier₁⟩ ⟨identifier₂⟩) pairing, using ⟨identifier₂⟩ as the external name.

An import declaration provides a way to import the identifiers exported by another library. It has the same syntax and semantics as an import declaration used in a program or at the REPL (see Import declarations).

The begin, include, and include-ci declarations are used to specify the body of the library. They have the same syntax and semantics as the corresponding expression types. This form of begin is analogous to, but not the same as, the two types of begin defined in Sequencing.

The include-library-declarations declaration is similar to include except that the contents of the file are spliced directly into the current library definition. This can be used, for example, to share the same export declaration among multiple libraries as a simple form of library interface.

The cond-expand declaration has the same syntax and semantics as the cond-expand expression type, except that it expands to spliced-in library declarations rather than expressions enclosed in begin.

One possible implementation of libraries is as follows: After all cond-expand library declarations are expanded, a new environment is constructed for the library consisting of all imported bindings. The expressions from all begin, include and include-ci library declarations are expanded in that environment in the order in which they occur in the library. Alternatively, cond-expand and import declarations may be processed in left to right order interspersed with the processing of other declarations, with the environment growing as imported bindings are added to it by each import declaration.

When a library is loaded, its expressions are executed in textual order. If a library’s definitions are referenced in the expanded form of a program or library body, then that library must be loaded before the expanded program or library body is evaluated. This rule applies transitively. If a library is imported by more than one program or library, it may possibly be loaded additional times.

Similarly, during the expansion of a library (foo), if any syntax keywords imported from another library (bar) are needed to expand the library, then the library (bar) must be expanded and its syntax definitions evaluated before the expansion of (foo).

Regardless of the number of times that a library is loaded, each program or library that imports bindings from a library must do so from a single loading of that library, regardless of the number of import declarations in which it appears. That is, (import (only (foo) a)) followed by (import (only (foo) b)) has the same effect as (import (only (foo) a b)).

6.6.2 Library example

The following example shows how a program can be divided into libraries plus a relatively small main program [16]. If the main program is entered into a REPL, it is not necessary to import the base library.

(define-library (example grid)
  (export make rows cols ref each
          (rename put! set!))
  (import (scheme base))
  (begin
    ;; Create an NxM grid.
    (define (make n m)
      (let ((grid (make-vector n)))
        (do ((i 0 (+ i 1)))
            ((= i n) grid)
          (let ((v (make-vector m #false)))
            (vector-set! grid i v)))))
    (define (rows grid)
      (vector-length grid))
    (define (cols grid)
      (vector-length (vector-ref grid 0)))
    ;; Return #false if out of range.
    (define (ref grid n m)
      (and (< -1 n (rows grid))
           (< -1 m (cols grid))
           (vector-ref (vector-ref grid n) m)))
    (define (put! grid n m v)
      (vector-set! (vector-ref grid n) m v))
    (define (each grid proc)
      (do ((j 0 (+ j 1)))
          ((= j (rows grid)))
        (do ((k 0 (+ k 1)))
            ((= k (cols grid)))
          (proc j k (ref grid j k)))))))

(define-library (example life)
  (export life)
  (import (except (scheme base) set!)
          (scheme write)
          (example grid))
  (begin
    (define (life-count grid i j)
      (define (count i j)
        (if (ref grid i j) 1 0))
      (+ (count (- i 1) (- j 1))
         (count (- i 1) j)
         (count (- i 1) (+ j 1))
         (count i (- j 1))
         (count i (+ j 1))
         (count (+ i 1) (- j 1))
         (count (+ i 1) j)
         (count (+ i 1) (+ j 1))))
    (define (life-alive? grid i j)
      (case (life-count grid i j)
        ((3) #true)
        ((2) (ref grid i j))
        (else #false)))
    (define (life-print grid)
      (display "\x1B;[1H\x1B;[J")  ; clear vt100
      (each grid
            (lambda (i j v)
              (display (if v "*" " "))
              (when (= j (- (cols grid) 1))
                (newline)))))
    (define (life grid iterations)
      (do ((i 0 (+ i 1))
           (grid0 grid grid1)
           (grid1 (make (rows grid) (cols grid))
                  grid0))
          ((= i iterations))
        (each grid0
              (lambda (j k v)
                (let ((a (life-alive? grid0 j k)))
                  (set! grid1 j k a))))
        (life-print grid1)))))))

;; Main program.
(import (scheme base)
        (only (example life) life)
        (rename (prefix (example grid) grid-)
                (grid-make make-grid)))

;; Initialize a grid with a glider.
(define grid (make-grid 24 24))
(grid-set! grid 1 1 #true)
(grid-set! grid 2 2 #true)
(grid-set! grid 3 0 #true)
(grid-set! grid 3 1 #true)
(grid-set! grid 3 2 #true)

;; Run for 80 iterations.
(life grid 80)

7.2.1 Numerical types

Mathematically, numbers are arranged into a tower of subtypes in which each level is a subset of the level above it:

number
complex number
real number
rational number
integer

For example, 3 is an integer. Therefore 3 is also a rational, a real, and a complex number. 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 multiple internal representations of numbers, this ought not to be apparent to a casual programmer writing simple programs.

7.2.2 Exactness

It is useful to distinguish between numbers that are represented exactly and those that might 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.

A Scheme 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. In particular, an exact complex number has an exact real part and an exact imaginary part; all other complex numbers are inexact complex numbers.

If two implementations produce exact results for a computation that did not involve inexact intermediate results, the two ultimate results will be mathematically equal. 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. However, (/ 3 4) must not return the mathematically incorrect value 0. See Implementation restrictions.

Except for 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.

Specifically, the expression (* 0 +inf.0) may return 0, or +nan.0, or report that inexact numbers are not supported, or report that non-rational real numbers are not supported, or fail silently or noisily in other implementation-specific ways.

7.2.3 Implementation restrictions

Implementations of Scheme are not required to implement the whole tower of subtypes given in 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, implementations in which all numbers are real, or in which non-real numbers are always inexact, or in which exact numbers are always integer, are still quite useful.

Implementations may also support only a limited range of numbers of any type, subject to the requirements of this section. The supported range for exact numbers of any type may be different from the supported range for inexact numbers of that type. For example, an implementation that uses IEEE binary double-precision floating-point numbers to represent all its inexact real numbers may also 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 IEEE binary double 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 permitted as indexes of lists, vectors, bytevectors, and strings or that result from computing the length of one of these. The length, vector-length, bytevector-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, must be read as an exact integer, regardless of any implementation restrictions that apply outside this range. Finally, the procedures listed below will always return exact integer results provided all their arguments are exact integers and the mathematically expected results are representable as exact integers within the implementation:

• -
• *
• +
• abs
• ceiling
• denominator
• exact-integer-sqrt
• expt
• floor
• floor/
• floor-quotient
• floor-remainder
• gcd
• lcm
• max
• min
• modulo
• numerator
• quotient
• rationalize
• remainder
• round
• square
• truncate
• truncate/
• truncate-quotient
• truncate-remainder

It is recommended, but not required, that implementations 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 can cause an error later. Nevertheless, implementations that do not provide exact rational numbers should return inexact rational numbers rather than reporting an implementation restriction.

An implementation may use floating-point and other approximate representation strategies for inexact numbers. This report recommends, but does not require, that implementations that use floating-point representations follow the IEEE 754 standard, and that implementations using other representations should match or exceed the precision achievable using these floating-point standards [17]. In particular, the description of transcendental functions in IEEE 754-2008 should be followed by such implementations, particularly with respect to infinities and NaNs.

Although Scheme allows a variety of written notations for numbers, any particular implementation may support only some of them. For example, an implementation in which all numbers are real need not support the rectangular and polar notations for complex numbers. If an implementation encounters an exact numerical constant that it cannot represent as an exact number, then it may either report a violation of an implementation restriction or it may silently represent the constant by an inexact number.

7.2.4 Implementation extensions

Implementations may provide more than one representation of floating-point numbers with differing precisions. In an implementation which does so, an inexact result must be represented with at least as much precision as is used to express any of the inexact arguments to that operation. Although it is desirable for potentially inexact operations such as sqrt to produce exact answers when applied to exact arguments, if an exact number is operated upon so as to produce an inexact result, then the most precise representation available must be used. For example, the value of (sqrt 4) should be 2, but in an implementation that provides both single and double precision floating point numbers it may be the latter but must not be the former.

It is the programmer’s responsibility to avoid using inexact number objects with magnitude or significand too large to be represented in the implementation.

In addition, implementations may distinguish special numbers called positive infinity, negative infinity, NaN, and negative zero.

Positive infinity is regarded as an inexact real (but not rational) number that represents an indeterminate value greater than the numbers represented by all rational numbers. Negative infinity is regarded as an inexact real (but not rational) number that represents an indeterminate value less than the numbers represented by all rational numbers.

Adding or multiplying an infinite value by any finite real value results in an appropriately signed infinity; however, the sum of positive and negative infinities is a NaN. Positive infinity is the reciprocal of zero, and negative infinity is the reciprocal of negative zero. The behavior of the transcendental functions is sensitive to infinity in accordance with IEEE 754.

A NaN is regarded as an inexact real (but not rational) number so indeterminate that it might represent any real value, including positive or negative infinity, and might even be greater than positive infinity or less than negative infinity. An implementation that does not support non-real numbers may use NaN to represent non-real values like (sqrt -1.0) and (asin 2.0).

A NaN always compares false to any number, including a NaN. An arithmetic operation where one operand is NaN returns NaN, unless the implementation can prove that the result would be the same if the NaN were replaced by any rational number. Dividing zero by zero results in NaN unless both zeros are exact.

Negative zero is an inexact real value written -0.0 and is distinct (in the sense of eqv?) from 0.0. A Scheme implementation is not required to distinguish negative zero. If it does, however, the behavior of the transcendental functions is sensitive to the distinction in accordance with IEEE 754. Specifically, in a Scheme implementing both complex numbers and negative zero, the branch cut of the complex logarithm function is such that (imag-part (log -1.0-0.0i)) is −π rather than π.

Furthermore, the negation of negative zero is ordinary zero and vice versa. This implies that the sum of two or more negative zeros is negative, and the result of subtracting (positive) zero from a negative zero is likewise negative. However, numerical comparisons treat negative zero as equal to zero.

Note that both the real and the imaginary parts of a complex number can be infinities, NaNs, or negative zero.

7.2.5 Syntax of numerical constants

The syntax of the written representations for numbers is described formally in Formal syntax. Note that case is not significant in numerical constants.

A number can 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 can be specified to be either exact or inexact by a prefix. The prefixes are #e for exact, and #i for inexact. An exactness prefix can appear before or after any radix prefix that is used. If the written representation of a number has no exactness prefix, the constant is inexact if it contains a decimal point or an exponent. Otherwise, it is exact.

In systems with inexact numbers of varying precisions it can be useful to specify the precision of a constant. For this purpose, implementations may accept numerical constants written with an exponent marker that indicates the desired precision of the inexact representation. If so, the letter s, f, d, or l, meaning short, single, double, or long precision, respectively, can be used in place of e. The default precision has at least as much precision as double, but implementations may allow this default to be set by the user.

3.14159265358979F0
        Round to single — 3.141593
0.6L0
        Extend to long — .600000000000000

The numbers positive infinity, negative infinity, and NaN are written +inf.0, -inf.0 and +nan.0 respectively. NaN may also be written -nan.0. The use of signs in the written representation does not necessarily reflect the underlying sign of the NaN value, if any. Implementations are not required to support these numbers, but if they do, they must do so in general conformance with IEEE 754. However, implementations are not required to support signaling NaNs, nor to provide a way to distinguish between different NaNs.

There are two notations provided for non-real complex numbers: the rectangular notation a+bi, where a is the real part and b is the imaginary part; and the polar notation r@θ where r is the magnitude and θ is the phase (angle) in radians. These are related by the equation a + bi = r \cos\theta + (r \sin\theta)i. All of a, b, r, and θ are real numbers.

7.2.6 Numerical operations

The reader is referred to Error situations and unspecified behavior 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 IEEE binary doubles to represent inexact numbers.

procedure: number? obj ¶

procedure: complex? obj ¶

procedure: real? obj ¶

procedure: rational? obj ¶

procedure: integer? obj ¶

These numerical type predicates can be applied to any kind of argument, including non-numbers. They return #t if the object is of the named type, and otherwise they return #f. In general, if a type predicate is true of a number then all higher type predicates are also true of that number. Consequently, if a type predicate is false of a number, then all lower type predicates are also false of that number.

If z is a 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)).

The numbers +inf.0, -inf.0, and +nan.0 are real but not rational.

(complex? 3+4i)    ⇒ #t
(complex? 3)       ⇒ #t
(real? 3)          ⇒ #t
(real? -2.5+0i)    ⇒ #t
(real? -2.5+0.0i)  ⇒ #f
(real? #e1e10)     ⇒ #t
(real? +inf.0)     ⇒ #t
(real? +nan.0)     ⇒ #t
(rational? -inf.0) ⇒ #f
(rational? 3.5)    ⇒ #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 might affect the result.

Note: In many implementations the complex? procedure will be the same as number?, but unusual implementations may represent some irrational numbers exactly or may extend the number system to support some kind of non-complex numbers.

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.

(exact? 3.0)   ⇒ #f
(exact? #e3.0) ⇒ #t
(inexact? 3.)  ⇒ #t

procedure: exact-integer? z ¶

Returns #t if z is both exact and an integer; otherwise returns #f.

(exact-integer? 32)   ⇒ #t
(exact-integer? 32.0) ⇒ #f
(exact-integer? 32/5) ⇒ #f

inexact library procedure: finite? z ¶

The finite? procedure returns #t on all real numbers except +inf.0, -inf.0, and +nan.0, and on complex numbers if their real and imaginary parts are both finite. Otherwise it returns #f.

(finite? 3)          ⇒ #t
(finite? +inf.0)     ⇒ #f
(finite? 3.0+inf.0i) ⇒ #f

inexact library procedure: infinite? z ¶

The infinite? procedure returns #t on the real numbers +inf.0 and -inf.0, and on complex numbers if their real or imaginary parts or both are infinite. Otherwise it returns #f.

(infinite? 3)          ⇒ #f
(infinite? +inf.0)     ⇒ #t
(infinite? +nan.0)     ⇒ #f
(infinite? 3.0+inf.0i) ⇒ #t

inexact library procedure: nan? z ¶

The nan? procedure returns #t on +nan.0, and on complex numbers if their real or imaginary parts or both are +nan.0. Otherwise it returns #f.

(nan? +nan.0)      ⇒ #t
(nan? 32)          ⇒ #f
(nan? +nan.0+5.0i) ⇒ #t
(nan? 1+2i)        ⇒ #f

procedure: = z₁ z₂ z₃… ¶

procedure: < x₁ x₂ x₃… ¶

procedure: > x₁ x₂ x₃… ¶

procedure: <= x₁ x₂ x₃… ¶

procedure: >= x₁ x₂ x₃… ¶

These procedures return #t if their arguments are (respectively): equal, monotonically increasing, monotonically decreasing, monotonically non-decreasing, or monotonically non-increasing, and #f otherwise. If any of the arguments are +nan.0, all the predicates return #f. They do not distinguish between inexact zero and inexact negative zero.

These predicates are required to be transitive.

Note: The implementation approach of converting all arguments to inexact numbers if any argument is inexact is not transitive. For example, let big be (expt 2 1000), and assume that big is exact and that inexact numbers are represented by 64-bit IEEE binary floating point numbers. Then (= (- big 1) (inexact big)) and (= (inexact big) (+ big 1)) would both be true with this approach, because of the limitations of IEEE representations of large integers, whereas (= (- big 1) (+ big 1)) is false. Converting inexact values to exact numbers that are the same (in the sense of =) to them will avoid this problem, though special care must be taken with infinities.

Note: While it is not an error to compare inexact numbers using these predicates, the results are unreliable because a small inaccuracy can 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? n ¶

procedure: even? n ¶

These numerical predicates test a number for a particular property, returning #t or #f. See note above.

procedure: max x₁ x₂… ¶

procedure: min x₁ x₂… ¶

These procedures return the maximum or minimum of their arguments.

(max 3 4)   ⇒ 4    ; exact
(max 3.9 4) ⇒ 4.0  ; inexact

Note: If any argument is inexact, then the result will also be inexact (unless the procedure can prove that the inaccuracy is not large enough to affect the result, which is possible only in unusual implementations). If min or max is used to compare numbers of mixed exactness, and the numerical value of the result cannot be represented as an inexact number without loss of accuracy, then the procedure may report a violation of an implementation restriction.

procedure: + z₁… ¶

procedure: * z₁… ¶

These procedures return the sum or product of their arguments.

(+ 3 4) ⇒ 7
(+ 3)   ⇒ 3
(+)     ⇒ 0
(* 4)   ⇒ 4
(*)     ⇒ 1

procedure: - z ¶

procedure: - z₁ z₂… ¶

procedure: / z ¶

procedure: / z₁ z₂… ¶

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.

It is an error if any argument of / other than the first is an exact zero. If the first argument is an exact zero, an implementation may return an exact zero unless one of the other arguments is a NaN.

(- 3 4)   ⇒ -1
(- 3 4 5) ⇒ -6
(- 3)     ⇒ -3
(/ 3 4 5) ⇒ 3/20
(/ 3)     ⇒ 1/3

procedure: abs x ¶

The abs procedure returns the absolute value of its argument.

(abs -7) ⇒ 7

procedure: floor/ n₁ n₂ ¶

procedure: floor-quotient n₁ n₂ ¶

procedure: floor-remainder n₁ n₂ ¶

procedure: truncate/ n₁ n₂ ¶

procedure: truncate-quotient n₁ n₂ ¶

procedure: truncate-remainder n₁ n₂ ¶

These procedures implement number-theoretic (integer) division. It is an error if n is zero. The procedures ending in / return two integers; the other procedures return an integer. All the procedures compute a quotient n_q and remainder n_r such that n₁ = n₂n_q + n_r. For each of the division operators, there are three procedures defined as follows:

(⟨operator⟩/ n1 n2) ⇒ nq nr
(⟨operator⟩-quotient n1 n2) ⇒ nq
(⟨operator⟩-remainder n1 n2) ⇒ nr

The remainder n_r is determined by the choice of integer n_q: n_r = n₁ − n₂n_q. Each set of operators uses a different choice of n_q:

floor

n_q = \lfloor n_1 / n_2 \rfloor

truncate

n_q = truncate(n_1 / n_2)

For any of the operators, and for integers n₁ and n₂ with n₂ not equal to 0,

(= n1
   (+ (* n2 (⟨operator⟩-quotient n1 n2))
      (⟨operator⟩-remainder n1 n2)))
        ⇒ #t

provided all numbers involved in that computation are exact.

Examples:

(floor/ 5 2)        ⇒  2    1
(floor/ -5 2)       ⇒ -3    1
(floor/ 5 -2)       ⇒ -3   -1
(floor/ -5 -2)      ⇒  2   -1
(truncate/ 5 2)     ⇒  2    1
(truncate/ -5 2)    ⇒ -2   -1
(truncate/ 5 -2)    ⇒ -2    1
(truncate/ -5 -2)   ⇒  2   -1
(truncate/ -5.0 -2) ⇒  2.0 -1.0

procedure: quotient n₁ n₂ ¶

procedure: remainder n₁ n₂ ¶

procedure: modulo n₁ n₂ ¶

The quotient and remainder procedures are equivalent to truncate-quotient and truncate-remainder, respectively, and modulo is equivalent to floor-remainder.

Note: These procedures are provided for backward compatibility with earlier versions of this report.

procedure: gcd n₁… ¶

procedure: lcm n₁… ¶

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
  (inexact (/ 6 4)))  ⇒ 2.0

procedure: floor x ¶

procedure: ceiling x ¶

procedure: truncate x ¶

procedure: round x ¶

These procedures return integers. The floor procedure returns the largest integer not larger than x. The ceiling procedure 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, and round returns the closest integer to x, rounding to even when x is halfway between two integers.

Rationale:

The round procedure rounds to even for consistency with the default rounding mode specified by the IEEE 754 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 can be passed to the exact procedure. If the argument is infinite or a NaN, then it is returned.

(floor -4.3)          ⇒ -5.0
(ceiling -4.3)        ⇒ -4.0
(truncate -4.3)       ⇒ -4.0
(round -4.3)          ⇒ -4.0

(floor 3.5)           ⇒ 3.0
(ceiling 3.5)         ⇒ 4.0
(truncate 3.5)        ⇒ 3.0
(round 3.5)           ⇒ 4.0  ; inexact

(round 7/2)           ⇒ 4    ; exact
(round 7)             ⇒ 7

procedure: rationalize x y ¶

The rationalize procedure returns the simplest rational number differing from x by no more than y. A rational number r₁ is simpler than another rational number r₂ if r_1 = p_1/q_1 and r_2 = p_2/q_2 (in lowest terms) and |p_1| \leq |p_2| and |q_1| \leq |q_2|. Thus 3/5 is simpler than 4/7. Although not all rationals are comparable in this ordering (consider 2/7 and 3/5), any interval contains a rational number that is simpler than every other rational number in that interval (the simpler 2/5 lies between 2/7 and 3/5). Note that 0 = 0/1 is the simplest rational of all.

(rationalize (exact .3) 1/10) ⇒ 1/3    ; exact
(rationalize .3 1/10)         ⇒ #i1/3  ; inexact

inexact library procedure: exp z ¶

inexact library procedure: log z ¶

inexact library procedure: log z₁ z₂ ¶

inexact library procedure: sin z ¶

inexact library procedure: cos z ¶

inexact library procedure: tan z ¶

inexact library procedure: asin z ¶

inexact library procedure: acos z ¶

inexact library procedure: atan z ¶

inexact library procedure: atan y x ¶

These procedures compute the usual transcendental functions. The log procedure computes the natural logarithm of z (not the base ten logarithm) if a single argument is given, or the base-z₂ logarithm of z₁ if two arguments are given. The asin, acos, and atan procedures compute arcsine (sin⁻¹), arc-cosine (cos⁻¹), and arctangent (tan⁻¹), respectively. The two-argument variant of atan computes (angle (make-rectangular x y)) (see below), even in implementations that don’t support complex numbers.

In general, the mathematical functions log, arcsine, arc-cosine, and arctangent are multiply defined. The value of log z is defined to be the one whose imaginary part lies in the range from −π (inclusive if -0.0 is distinguished, exclusive otherwise) to π (inclusive). The value of log 0 is mathematically undefined. With log defined this way, the values of sin⁻¹ z, cos⁻¹ z, and tan⁻¹ z are according to the following formulæ:

\sin^{-1} z = -i \log (i z + \sqrt{1 - z^2})

\cos^{-1} z = \pi / 2 - \sin^{-1} z

\tan^{-1} z = (\log (1 + i z) - \log (1 - i z)) / (2 i)

However, (log 0.0) returns -inf.0 (and (log -0.0) returns -inf.0+πi) if the implementation supports infinities (and -0.0).

The range of (atan y x) is as in the following table. The asterisk (*) indicates that the entry applies to implementations that distinguish minus zero.

	y condition	x condition	range of result r
	y = 0.0	x > 0.0	0.0
∗	y = +0.0	x > 0.0	+0.0
∗	y = −0.0	x > 0.0	−0.0
	y > 0.0	x > 0.0	0.0 < r < π/2
	y > 0.0	x = 0.0	π/2
	y > 0.0	x < 0.0	π/2 < r < π
	y = 0.0	x < 0	π
∗	y = +0.0	x < 0.0	π
∗	y = −0.0	x < 0.0	−π
	y < 0.0	x < 0.0	−π < r < −π/2
	y < 0.0	x = 0.0	−π/2
	y < 0.0	x > 0.0	−π/2 < r< 0.0
	y = 0.0	x = 0.0	undefined
∗	y = +0.0	x = +0.0	+0.0
∗	y = −0.0	x = +0.0	−0.0
∗	y = +0.0	x = −0.0	π
∗	y = −0.0	x = −0.0	−π
∗	y = +0.0	x = 0	π/2
∗	y = −0.0	x = 0	−π/2

The above specification follows [34], which in turn cites [26]; 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: square z ¶

Returns the square of z. This is equivalent to (* z z).

(square 42)  ⇒ 1764
(square 2.0) ⇒ 4.0

inexact library procedure: sqrt z ¶

Returns the principal square root of z. The result will have either a positive real part, or a zero real part and a non-negative imaginary part.

(sqrt 9)  ⇒ 3
(sqrt -1) ⇒ +i

procedure: exact-integer-sqrt k ¶

Returns two non-negative exact integers s and r where k = s² + r and k < (s + 1)².

(exact-integer-sqrt 4) ⇒ 2 0
(exact-integer-sqrt 5) ⇒ 2 1

procedure: expt z₁ z₂ ¶

Returns z₁ raised to the power z₂. For nonzero z₁, this is

{z_1}^{z_2} = e^{z_2 \log {z_1}}

The value of 0^z is 1 if (zero? z), 0 if (real-part z) is positive, and an error otherwise. Similarly for 0.0^z, with inexact results.

complex library procedure: make-rectangular x₁ x₂ ¶

complex library procedure: make-polar x₃ x₄ ¶

complex library procedure: real-part z ¶

complex library procedure: imag-part z ¶

complex library procedure: magnitude z ¶

complex library procedure: angle z ¶

Let x₁, x₂, x₃, and x₄ be real numbers and z be a complex number such that

z = x_1 + x_{2}i = x_3 \cdot e^{i x_4}

Then all of

(make-rectangular x1 x2) ⇒ z
(make-polar x3 x4)       ⇒ z
(real-part z)                  ⇒ x1
(imag-part z)                  ⇒ x2
(magnitude z)                  ⇒ |x3|
(angle z)                      ⇒ xangle

are true, where −π ≤ x_angle ≤ π with x_angle = x₄ + 2πn for some integer n.

The make-polar procedure may return an inexact complex number even if its arguments are exact. The real-part and imag-part procedures may return exact real numbers when applied to an inexact complex number if the corresponding argument passed to make-rectangular was exact.

The magnitude procedure is the same as abs for a real argument, but abs is in the base library, whereas magnitude is in the optional complex library.

procedure: inexact z ¶

procedure: exact z ¶

The procedure inexact returns an inexact representation of z. The value returned is the inexact number that is numerically closest to the argument. For inexact arguments, the result is the same as the argument. For exact complex numbers, the result is a complex number whose real and imaginary parts are the result of applying inexact to the real and imaginary parts of the argument, respectively. If an exact argument has no reasonably close inexact equivalent (in the sense of =), then a violation of an implementation restriction may be reported.

The procedure exact returns an exact representation of z. The value returned is the exact number that is numerically closest to the argument. For exact arguments, the result is the same as the argument. For inexact non-integral real arguments, the implementation may return a rational approximation, or may report an implementation violation. For inexact complex arguments, the result is a complex number whose real and imaginary parts are the result of applying exact to the real and imaginary parts of the argument, respectively. If an inexact argument has no reasonably close exact equivalent, (in the sense of =), then a violation of an implementation restriction may be reported.

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

Note: These procedures were known in R⁵RS as exact->inexact and inexact->exact, respectively, but they have always accepted arguments of any exactness. The new names are clearer and shorter, as well as being compatible with R⁶RS.

7.2.7 Numerical input and output

procedure: number->string z ¶

procedure: number->string z radix ¶

It is an error if radix is not one of 2, 8, 10, or 16.

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 omitted, radix defaults to 10.

If z is inexact, the radix is 10, and the above expression can be satisfied by a result that contains a decimal point, then the result contains a decimal point and is expressed using the minimum number of digits (exclusive of exponent and trailing zeroes) needed to make the above expression true [4, 5]; otherwise the format of the result is unspecified.

The result returned by number->string never contains an explicit radix prefix.

Note: The error case can occur only when z is not a complex number or is a complex number with a non-rational real or imaginary part.

Rationale:

If z is an inexact number 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 unusual representations.

procedure: string->number string ¶

procedure: string->number string radix ¶

Returns a number of the maximally precise representation expressed by the given string. It is an error if radix is not 2, 8, 10, or 16.

If supplied, radix is a default radix that will be overridden if an explicit radix prefix is present 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, or would result in a number that the implementation cannot represent, then string->number returns #f. An error is never signaled due to the content of string.

(string->number "100")    ⇒ 100
(string->number "100" 16) ⇒ 256
(string->number "1e2")    ⇒ 100.0

Note: The domain of string->number may be restricted by implementations in the following ways. If all numbers supported by an implementation are real, then string->number is permitted to return #f whenever string uses the polar or rectangular notations for complex numbers. If all numbers are integers, then string->number may return #f whenever the fractional notation is used. If all numbers are exact, then string->number may return #f whenever an exponent marker or explicit exactness prefix is used. If all inexact numbers are integers, then string->number may return #f whenever a decimal point is used.

The rules used by a particular implementation for string->number must also be applied to read and to the routine that reads programs, in order to maintain consistency between internal numeric processing, I/O, and the processing of programs. As a consequence, the R⁵RS permission to return #f when string has an explicit radix prefix has been withdrawn.

7.13.1 Ports

Ports represent input and output devices. To Scheme, an input port is a Scheme object that can deliver data upon command, while an output port is a Scheme object that can accept data. Whether the input and output port types are disjoint is implementation-dependent.

Different port types operate on different data. Scheme implementations are required to support textual ports and binary ports, but may also provide other port types.

A textual port supports reading or writing of individual characters from or to a backing store containing characters using read-char and write-char below, and it supports operations defined in terms of characters, such as read and write.

A binary port supports reading or writing of individual bytes from or to a backing store containing bytes using read-u8 and write-u8 below, as well as operations defined in terms of bytes. Whether the textual and binary port types are disjoint is implementation-dependent.

Ports can be used to access files, devices, and similar things on the host system on which the Scheme program is running.

procedure: call-with-port port proc ¶

It is an error if proc does not accept one argument.

The call-with-port procedure calls proc with port as an argument. If proc returns, then the port is closed automatically and the values yielded by the proc are returned. If proc does not return, then the port must not be closed automatically unless it is possible to prove that the port will never again be used for a read or write operation.

Rationale:

Because Scheme’s escape procedures have unlimited extent, it is possible to escape from the current continuation but later to resume it. 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-port.

file library procedure: call-with-input-file string proc ¶

file library procedure: call-with-output-file string proc ¶

It is an error if proc does not accept one argument.

These procedures obtain a textual port obtained by opening the named file for input or output as if by open-input-file or open-output-file. The port and proc are then passed to a procedure equivalent to call-with-port.

procedure: input-port? obj ¶

procedure: output-port? obj ¶

procedure: textual-port? obj ¶

procedure: binary-port? obj ¶

procedure: port? obj ¶

These procedures return #t if obj is an input port, output port, textual port, binary port, or any kind of port, respectively. Otherwise they return #f.

procedure: input-port-open? port ¶

procedure: output-port-open? port ¶

Returns #t if port is still open and capable of performing input or output, respectively, and #f otherwise.

procedure: current-input-port ¶

procedure: current-output-port ¶

procedure: current-error-port ¶

Returns the current default input port, output port, or error port (an output port), respectively. These procedures are parameter objects, which can be overridden with parameterize (see Dynamic bindings). The initial bindings for these are implementation-defined textual ports.

file library procedure: with-input-from-file string thunk ¶

file library procedure: with-output-to-file string thunk ¶

The file is opened for input or output as if by open-input-file or open-output-file, and the new port is made to be the value returned by current-input-port or current-output-port (as used by (read), (write obj), and so forth). The thunk is then called with no arguments. When the thunk returns, the port is closed and the previous default is restored. It is an error if thunk does not accept zero arguments. Both procedures return the values yielded by thunk. If an escape procedure is used to escape from the continuation of these procedures, they behave exactly as if the current input or output port had been bound dynamically with parameterize.

file library procedure: open-input-file string ¶

file library procedure: open-binary-input-file string ¶

Takes a string for an existing file and returns a textual input port or binary input port that is capable of delivering data from the file. If the file does not exist or cannot be opened, an error that satisfies file-error? is signaled.

file library procedure: open-output-file string ¶

file library procedure: open-binary-output-file string ¶

Takes a string naming an output file to be created and returns a textual output port or binary output port that is capable of writing data to a new file by that name. If a file with the given name already exists, the effect is unspecified. If the file cannot be opened, an error that satisfies file-error? is signaled.

procedure: close-port port ¶

procedure: close-input-port port ¶

procedure: close-output-port port ¶

Closes the resource associated with port, rendering the port incapable of delivering or accepting data. It is an error to apply the last two procedures to a port which is not an input or output port, respectively. Scheme implementations may provide ports which are simultaneously input and output ports, such as sockets; the close-input-port and close-output-port procedures can then be used to close the input and output sides of the port independently.

These routines have no effect if the port has already been closed.

procedure: open-input-string string ¶

Takes a string and returns a textual input port that delivers characters from the string. If the string is modified, the effect is unspecified.

procedure: open-output-string ¶

Returns a textual output port that will accumulate characters for retrieval by get-output-string.

procedure: get-output-string port ¶

It is an error if port was not created with open-output-string.

Returns a string consisting of the characters that have been output to the port so far in the order they were output. If the result string is modified, the effect is unspecified.

(parameterize
    ((current-output-port
      (open-output-string)))
    (display "piece")
    (display " by piece ")
    (display "by piece.")
    (newline)
    (get-output-string (current-output-port)))

    ⇒ "piece by piece by piece.\n"

procedure: open-input-bytevector bytevector ¶

Takes a bytevector and returns a binary input port that delivers bytes from the bytevector.

procedure: open-output-bytevector ¶

Returns a binary output port that will accumulate bytes for retrieval by get-output-bytevector.

procedure: get-output-bytevector port ¶

It is an error if port was not created with open-output-bytevector.

Returns a bytevector consisting of the bytes that have been output to the port so far in the order they were output.

7.13.2 Input

If port is omitted from any input procedure, it defaults to the value returned by (current-input-port). It is an error to attempt an input operation on a closed port.

read library procedure: read ¶

read library procedure: read port ¶

The read procedure converts external representations of Scheme objects into the objects themselves. That is, it is a parser for the non-terminal ⟨datum⟩ (see External representations and Pairs and lists). It returns the next object parsable from the given textual input port, updating port to point to the first character past the end of the external representation of the object.

Implementations may support extended syntax to represent record types or other types that do not have datum representations.

If an end of file is encountered in the input before any characters are found that can begin an object, then an end-of-file object is returned. The port remains open, and further attempts to read will also return an end-of-file object. If an end of file is encountered after the beginning of an object’s external representation, but the external representation is incomplete and therefore not parsable, an error that satisfies read-error? is signaled.

procedure: read-char ¶

procedure: read-char port ¶

Returns the next character available from the textual input port, updating the port to point to the following character. If no more characters are available, an end-of-file object is returned.

procedure: peek-char ¶

procedure: peek-char port ¶

Returns the next character available from the textual input port, but without updating the port to point to the following character. If no more characters are available, an end-of-file object is returned.

Note: The value returned by a call to peek-char is the same as the value that would have been returned by a call to read-char with the same port. The only difference is that the very next call to read-char or peek-char on that port will return the value returned by the preceding call to peek-char. In particular, a call to peek-char on an interactive port will hang waiting for input whenever a call to read-char would have hung.

procedure: read-line ¶

procedure: read-line port ¶

Returns the next line of text available from the textual input port, updating the port to point to the following character. If an end of line is read, a string containing all of the text up to (but not including) the end of line is returned, and the port is updated to point just past the end of line. If an end of file is encountered before any end of line is read, but some characters have been read, a string containing those characters is returned. If an end of file is encountered before any characters are read, an end-of-file object is returned. For the purpose of this procedure, an end of line consists of either a linefeed character, a carriage return character, or a sequence of a carriage return character followed by a linefeed character. Implementations may also recognize other end of line characters or sequences.

procedure: eof-object? obj ¶

Returns #t if obj is an end-of-file object, otherwise returns #f. The precise set of end-of-file objects will vary among implementations, but in any case no end-of-file object will ever be an object that can be read in using read.

procedure: eof-object ¶

Returns an end-of-file object, not necessarily unique.

procedure: char-ready? ¶

procedure: char-ready? port ¶

Returns #t if a character is ready on the textual input port and returns #f otherwise. If char-ready returns #t then the next read-char operation on the given port is guaranteed not to hang. If the port is at end of file then char-ready? returns #t.

Rationale:

The char-ready? procedure exists to make it possible for a program to accept characters from interactive ports without getting stuck waiting for input. Any input editors associated with such ports must ensure that characters whose existence has been asserted by char-ready? cannot be removed from the input. 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-string k ¶

procedure: read-string k port ¶

Reads the next k characters, or as many as are available before the end of file, from the textual input port into a newly allocated string in left-to-right order and returns the string. If no characters are available before the end of file, an end-of-file object is returned.

procedure: read-u8 ¶

procedure: read-u8 port ¶

Returns the next byte available from the binary input port, updating the port to point to the following byte. If no more bytes are available, an end-of-file object is returned.

procedure: peek-u8 ¶

procedure: peek-u8 port ¶

Returns the next byte available from the binary input port, but without updating the port to point to the following byte. If no more bytes are available, an end-of-file object is returned.

procedure: u8-ready? ¶

procedure: u8-ready? port ¶

Returns #t if a byte is ready on the binary input port and returns #f otherwise. If u8-ready? returns #t then the next read-u8 operation on the given port is guaranteed not to hang. If the port is at end of file then u8-ready? returns #t.

procedure: read-bytevector k ¶

procedure: read-bytevector k port ¶

Reads the next k bytes, or as many as are available before the end of file, from the binary input port into a newly allocated bytevector in left-to-right order and returns the bytevector. If no bytes are available before the end of file, an end-of-file object is returned.

procedure: read-bytevector! bytevector ¶

procedure: read-bytevector! bytevector port ¶

procedure: read-bytevector! bytevector port start ¶

procedure: read-bytevector! bytevector port start end ¶

Reads the next end − start bytes, or as many as are available before the end of file, from the binary input port into bytevector in left-to-right order beginning at the start position. If end is not supplied, reads until the end of bytevector has been reached. If start is not supplied, reads beginning at position 0. Returns the number of bytes read. If no bytes are available, an end-of-file object is returned.

7.13.3 Output

If port is omitted from any output procedure, it defaults to the value returned by (current-output-port). It is an error to attempt an output operation on a closed port.

write library procedure: write obj ¶

write library procedure: write obj port ¶

Writes a representation of obj to the given textual output port. Strings that appear in the written representation are enclosed in quotation marks, and within those strings backslash and quotation mark characters are escaped by backslashes. Symbols that contain non-ASCII characters are escaped with vertical lines. Character objects are written using the #\ notation.

If obj contains cycles which would cause an infinite loop using the normal written representation, then at least the objects that form part of the cycle must be represented using datum labels as described in Datum labels. Datum labels must not be used if there are no cycles.

Implementations may support extended syntax to represent record types or other types that do not have datum representations.

The write procedure returns an unspecified value.

write library procedure: write-shared obj ¶

write library procedure: write-shared obj port ¶

The write-shared procedure is the same as write, except that shared structure must be represented using datum labels for all pairs and vectors that appear more than once in the output.

write library procedure: write-simple obj ¶

write library procedure: write-simple obj port ¶

The write-simple procedure is the same as write, except that shared structure is never represented using datum labels. This can cause write-simple not to terminate if obj contains circular structure.

write library procedure: display obj ¶

write library procedure: display obj port ¶

Writes a representation of obj to the given textual output port. Strings that appear in the written representation are output as if by write-string instead of by write. Symbols are not escaped. Character objects appear in the representation as if written by write-char instead of by write.

The display representation of other objects is unspecified. However, display must not loop forever on self-referencing pairs, vectors, or records. Thus if the normal write representation is used, datum labels are needed to represent cycles as in write.

Implementations may support extended syntax to represent record types or other types that do not have datum representations.

The display procedure returns an unspecified value.

Rationale:

The write procedure is intended for producing machine-readable output and display for producing human-readable output.

procedure: newline ¶

procedure: newline port ¶

Writes an end of line to textual output port. Exactly how this is done differs from one operating system to another. Returns an unspecified value.

procedure: write-char char ¶

procedure: write-char char port ¶

Writes the character char (not an external representation of the character) to the given textual output port and returns an unspecified value.

procedure: write-string string ¶

procedure: write-string string port ¶

procedure: write-string string port start ¶

procedure: write-string string port start end ¶

Writes the characters of string from start to end in left-to-right order to the textual output port.

procedure: write-u8 byte ¶

procedure: write-u8 byte port ¶

Writes the byte to the given binary output port and returns an unspecified value.

procedure: write-bytevector bytevector ¶

procedure: write-bytevector bytevector port ¶

procedure: write-bytevector bytevector port start ¶

procedure: write-bytevector bytevector port start end ¶

Writes the bytes of bytevector from start to end in left-to-right order to the binary output port.

procedure: flush-output-port ¶

procedure: flush-output-port port ¶

Flushes any buffered output from the buffer of port to the underlying file or device and returns an unspecified value.