This chapter describes Scheme’s (rnrs base (6))library, which exports many of the procedure and syntax bindings that are traditionally associated with Scheme.
Section 9.21 defines the rules that identify tail calls and tail contexts in baselibrary constructs.
All identifiers described in the entries of this chapter are exported by the (rnrs base (6)) library with level 0, with the exception of syntaxrulesand identifiersyntax, which are exported with level 1.
Rationale: The syntaxrules and identifiersyntax forms are used to create macro transformers and are thus needed only at expansion time, i.e., meta level 1.
In addition, the identifiers unquote, unquotesplicing, =>, elseare exported with level 0, and the identifiers ...and _are exported with level 1. A reference to any of these identifiers out of place is a syntax violation. The identifier set! (section 9.5.4) is exported at both levels 0 and 1.
Rationale: The identifiers unquote, unquotesplicing, =>, and else serve as literals in the syntax of one or more baselibrary syntactic forms; e.g., else serves as a literal in the syntax of cond and case. Bindings of these identifiers are exported from the base library so that they can be distinguished from other bindings of these identifiers or renamed on import. The identifiers ..., _, and set! serve as literals in the syntax of syntaxrules and identifiersyntax forms and are thus exported along with those forms with level 1.
No object satisfies more than one of the following predicates:
boolean? pair?
These predicates define the base types boolean, pair, symbol, number, char (or character), string, vector, and procedure. Moreover, the empty list is a special object of its own type.
Note that, although there is a separate boolean type, any Scheme value can be used as a boolean value for the purpose of a conditional test; see section 4.6.
Definitionsmay appear within a <toplevel body> (section 7.1), at the top of a <library body> (section 6.1), or at the top of a <body> (section 9.4).
A <definition> may be a variable definition (section 9.3.1 or keyword definition (section 9.3.1. Syntactic abstractions that expand into definitions or groups of definitions (packaged in a baselibrary begin, letsyntax, or letrecsyntax form; see section 9.5.7) may also appear wherever other definitions may appear.
The define form described in this section is a <definition>used to create variable bindings and may appear anywhere other definitions may appear.
A variable definition has one of the following forms:
(define <variable> <expression>) Binds <variable> to a new location before assigning the value of <expression> to it.
(define add3The continuation of <expression> should not be invoked more than once.
Implementation responsibilities: Implementations are not required to detect that the continuation of <expression> is invoked more than once. If the implementation detects this, it must raise an exception with condition type &assertion.
(define <variable>)
This form is equivalent to
(define <variable> <unspecified>)where <unspecified> is a sideeffectfree expression returning an unspecified value.
(define (<variable> <formals>) <body>)
<Formals> must be either a sequence of zero or more variables, or a sequence of one or more variables followed by a spacedelimited period and another variable (as in a lambda expression, see section 9.5.2). This form is equivalent to
(define <variable>
(define (<variable> . <formal>) <body>)
<Formal> must be a single variable. This form is equivalent to
(define <variable>
The definesyntax form described in this section is a <definition>used to create keyword bindings and may appear anywhere other definitions may appear.
Binds <keyword> to the value of <expression>, which must evaluate, at macroexpansion time, to a transformer (see library section on “Transformers”).
Keyword bindings established by definesyntax are visible throughout the body in which they appear, except where shadowed by other bindings, and nowhere else, just like variable bindings established by define. All bindings established by a set of definitions, whether keyword or variable definitions, are visible within the definitions themselves.
Implementation responsibilities: The implementation must check that the value of <expression> is a transformer when the evaluation produces a value.
For example:
(let ()
An implication of the lefttoright processing order (section 8) is that one definition can affect whether a subsequent form is also a definition. For example, the expression
(let ()
The behavior is unaffected by any binding for bindtozero that might appear outside of the let expression.
The <body> of a lambda, let, let*, letvalues, let*values, letrec, letrec* expression or that of a definition with a body consists of zero or more definitions followed by one or more expressions.
<definition> ... <expression_{1}> <expression_{2}> ...
Each identifier defined by a definition is local to the <body>. That is, the identifier is bound, and the region of the binding is the entire <body> (see section 4.2). For example,
(let ((x 5))
When baselibrary begin, letsyntax, or letrecsyntax forms occur in a body prior to the first expression, they are spliced into the body; see section 9.5.7. Some or all of the body, including portions wrapped in begin, letsyntax, or letrecsyntax forms, may be specified by a syntactic abstraction (see section 6.3.2).
An expanded <body> (see chapter 8) containing variable definitions can always be converted into an equivalent letrec* expression. For example, the let expression in the above example is equivalent to
(let ((x 5))
The entries in this section describe the expressions of the base language, which may occur in the position of the <expression> syntactic variable. The expressions also include the primitive expression types: constant literals, variable references, and procedure calls, as described in section 6.3.1.
Syntax: <Datum> should be a datum value.
Semantics: (quote <datum>) evaluates to the datum value denoted by <datum> (see section 3.3). This notation is used to include constants, including list and vector constants, in Scheme code.
(quote a) ⇒ a
As noted in section 3.3.5, (quote <datum>) may be abbreviated as ’<datum>:
’"abc" ⇒ "abc"
As noted in section 4.8, constants are immutable.
Syntax: <Formals> must be a formal arguments list as described below, and <body> is as described in section 9.4.
Semantics: A lambda expression evaluates to a procedure. The environment in effect when the lambda expression is 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 is extended by binding the variables in the formal argument list to fresh locations, and the resulting actual argument values are stored in those locations. Then, the expressions in the body of the lambda expression (which may contain definitions and thus represent a letrec* form, see section 9.4) are evaluated sequentially in the extended environment. The results of the last expression in the body are returned as the results of the procedure call.
(lambda (x) (+ x x)) ⇒ a procedure
<Formals> must have one of the following forms:
(<variable_{1}> ...): The procedure takes a fixed number of arguments; when the procedure is called, the arguments are stored in the bindings of the corresponding variables.
<variable>: The procedure takes any number of arguments; when the procedure is called, the sequence of actual arguments is converted into a newly allocated list, and the list is stored in the binding of the <variable>.
(<variable_{1}> ... <variable_{n}> . <variable_{n+1}>): If a spacedelimited period precedes the last variable, then the procedure takes n or more arguments, where n is the number of formal arguments before the period (there must be at least one). The value stored in the binding of the last variable is 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.
((lambda x x) 3 4 5 6) ⇒ (3 4 5 6)
It is a syntax violation for a <variable> to appear more than once in <formals>.
Syntax: <Test>, <consequent>, and <alternate> must be expressions.
Semantics: An if expression is evaluated as follows: first, <test> is evaluated. If it yields a true value(see section 4.6), 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
<Expression> is evaluated, and the resulting value is stored in the location to which <variable> is bound. <Variable> must be bound either in some regionenclosing the set! expression or at the top level of a library body. The result of the set! expression is unspecified.
(let ((x 2))
It is a syntax violation if <variable> refers to an immutable binding.
Syntax: Each <cond clause> must be of the form
(<test> <expression_{1}> ...)where <test> is any expression. Alternatively, a <cond clause> may be of the form
(<test> => <expression>)The last <cond clause> may be an “else clause”, which has the form
(else <expression_{1}> <expression_{2}> ...).Semantics: A cond expression is evaluated by evaluating the <test> expressions of successive <cond clause>s in order until one of them evaluates to a true value(see section 4.6). When a <test> evaluates to a true value, then the remaining <expression>s in its <cond clause> are evaluated in order, and the results of the last <expression> in the <cond clause> are returned as the results of the entire cond expression. If the selected <cond clause> contains only the <test> and no <expression>s, then the value of the <test> is returned as the result. If the selected <cond clause> uses the => alternate form, then the <expression> is evaluated. Its value must be a procedure. This procedure should accept one argument; it is 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 false values, and there is no else clause, then the result of the conditional expression is unspecified; if there is an else clause, then its <expression>s are evaluated, and the values of the last one are returned.
(cond ((> 3 2) ’greater)
A sample definition of cond in terms of simpler forms is in appendix B.
Syntax: <Key> must be an expression. Each <case clause> has one of the following forms:
((<datum_{1}> ...) <expression_{1}> <expression_{2}> ...)The second form, which specifies an “else clause”, may only appear as the last <case clause>. Each <datum> is an external representation of some object. The datums denoted by the <datum>s need not be distinct.
Semantics: A case expression is evaluated as follows. <Key> is evaluated and its result is compared against the datums denoted by the <datum>s of each <case clause> in turn, proceeding in order from left to right through the set of clauses. If the result of evaluating <key> is equivalent (in the sense of eqv?; see section 9.6) to a datum of a <case clause>, the corresponding <expression>s are evaluated from left to right and the results of the last expression in the <case clause> are returned as the results of the case expression. Otherwise, the comparison process continues. If the result of evaluating <key> is different from every datum in each set, 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.
(case (* 2 3)
Syntax: The <test>s must be expressions.
Semantics: If there are no <test>s, #t is returned. Otherwise, the <test> expressions are evaluated from left to right until a <test> returns #f or the last <test> is reached. In the former case, the and expression returns #f without evaluating the remaining expressions. In the latter case, the last expression is evaluated and its values returned.
(and (= 2 2) (> 2 1)) ⇒ #t
The and keyword could be defined in terms of if using syntaxrules (see section 9.20) as follows:
(definesyntax and
Syntax: The <test>s must be expressions.
Semantics: If there are no <test>s, #f is returned. Otherwise, the <test> expressions are evaluated from left to right until a <test> returns a true value val (see section 4.6) or the last <test> is reached. In the former case, the and expression returns val without evaluating the remaining expressions. In the latter case, the last expression is evaluated and its values returned.
(or (= 2 2) (> 2 1)) ⇒ #t
The or keyword could be defined in terms of if using syntaxrules (see section 9.20) as follows:
(definesyntax or
The four binding constructs let, let*, letrec, and letrec* give Scheme a block structure, like Algol 60. The syntax of the four constructs is identical, but they differ in the regions(see section 4.2) 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. In a letrec or letrec* expression, all the bindings are in effect while their initial values are being computed, thus allowing mutually recursive definitions. In a letrec expression, the initial values are computed before being assigned to the variables; in a letrec*, the evaluations and assignments are performed sequentially.
In addition, the binding constructs letvalues and let*values generalize let and let* to allow multiple variables to be bound to the results of expressions that evaluate to multiple values. They are analogous to let and let* in the way they establish regions: in a letvalues expression, the initial values are computed before any of the variables become bound; in a let*values expression, the bindings are performed sequentially.
Note: These forms are compatible with SRFI 11 [24].
Syntax: <Bindings> must have the form
((<variable_{1}> <init_{1}>) ...),where each <init> is an expression, and <body> is as described in section 9.4. It is a syntax violation 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))
See also named let, section 9.17.
Syntax: <Bindings> must have the form
((<variable_{1}> <init_{1}>) ...),where each <init> is an expression, and <body> is as described in section 9.4.
Semantics: The let* form is similar to let, but the <init>s are evaluated and bindings created sequentially from left to right, with the regionof each binding including the bindings to its right as well as <body>. Thus the second <init> is evaluated in an environment in which the first binding is visible and initialized, and so on.
(let ((x 2) (y 3))
Note: While the variables bound by a let expression must be distinct, the variables bound by a let* expression need not be distinct.
The let* keyword could be defined in terms of let using syntaxrules (see section 9.20) as follows:
(definesyntax let*
Syntax: <Bindings> must have the form
((<variable_{1}> <init_{1}>) ...),where each <init> is an expression, and <body> is as described in section 9.4. It is a syntax violation for a <variable> to appear more than once in the list of variables being bound.
Semantics: The <variable>s are bound to fresh locations, 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?
One restriction on letrec is very important: it should be possible to evaluate each <init> without assigning or referring to the value of any <variable>. The restriction is necessary because Scheme passes arguments by value rather than by name. In the most common uses of letrec, all the <init>s are lambda expressions and the restriction is satisfied automatically.
Implementation responsibilities: Implementations are only required to check this restriction to the extent that references to a <variable> during the evaluation of the <init> expressions (using one particular evaluation order and order of evaluating the <init> expressions) must be detected. If an implementation detects a violation of the restriction, it must raise an exception with condition type &assertion. Implementations are not required to detect that the continuation of each <init> is invoked more than once. However, if the implementation detects this, it must raise an exception with condition type &assertion.
Another restriction is that the continuation of each <init> should not be invoked more than once.
A sample definition of letrec in terms of simpler forms is in appendix B.
Syntax: <Bindings> must have the form
((<variable_{1}> <init_{1}>) ...),where each <init> is an expression, and <body> is as described in section 9.4. It is a syntax violation 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 lefttoright order to the result of evaluating the corresponding <init>, the <body> is evaluated in the resulting environment, and the values of the last expression in <body> are returned. Despite the lefttoright 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.
(letrec* ((p
One restriction on letrec* is very important: it must be 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>. The restriction is necessary because Scheme passes arguments by value rather than by name.
Implementation responsibilities: Implementations are only required to check this restriction to the extent that references to a <variable> during the evaluation of the <init> expressions (using one particular evaluation order) must be detected. If an implementation detects a violation of the restriction, it must raise an exception with condition type &assertion. Implementations are not required to detect that the continuation of each <init> is invoked more than once. However, if the implementation detects this, it must raise an exception with condition type &assertion.
Another restriction is that the continuation of each <init> should not be invoked more than once.
The letrec* keyword could be defined approximately in terms of let and set! using syntaxrules (see section 9.20) as follows:
(definesyntax letrec*
The syntax <undefined> represents an expression that returns something that, when stored in a location, causes an exception with condition type &assertion to be raised if an attempt to read from or write to the location occurs before the assignments generated by the letrec* transformation take place. (No such expression is defined in Scheme.)
Syntax: <Mvbindings> must have the form
((<formals_{1}> <init_{1}>) ...),where each <init> is an expression, and <body> is as described in section 9.4. It is a syntax violation for a variable to appear more than once in the list of variables that appear as part of the formals.
Semantics: The <init>s are evaluated in the current environment (in some unspecified order), and the variables occurring in the <formals> are bound to fresh locations containing 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 actual 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.If the <formals> do not match, an exception with condition type &assertion is raised.
(letvalues (((a b) (values 1 2))
A sample definition of letvalues in terms of simpler forms is in appendix B.
Syntax: <Mvbindings> must have the form
((<formals_{1}> <init_{1}>) ...),where each <init> is an expression, and <body> is as described in section 9.4.
The let*values form is similar to letvalues, but the <init>s are evaluated and bindings created sequentially from left to right, with the regionof the bindings of each <formals> including the bindings to its right as well as <body>. Thus the second <init> is evaluated in an environment in which the bindings of the first <formals> is visible and initialized, and so on.
(let ((a ’a) (b ’b) (x ’x) (y ’y))
Note: While all of the variables bound by a letvalues expression must be distinct, the variables bound by different <formals> of a let*values expression need not be distinct.
The following macro defines let*values in terms of let and letvalues:
(definesyntax let*values
The <begin> keyword has two different roles, depending on its context:
It may appear as a form in a <body> (see section 9.4), <library body> (see section 6.1), or <toplevel body> (see chapter 7), or directly nested in a begin form that appears in a body. In this case, the begin form must have the shape specified in the first header line. This use of begin acts as a splicing form—the forms inside the <body> are spliced into the surrounding body, as if the begin wrapper were not actually present.
A begin form in a <body> or <library body> must be nonempty if it appears after the first <expression> within the body.
It may appear as an ordinary expression and must have the shape specified in the second header line. In this case, 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)
The following macro, which uses syntaxrules (see section 9.20), defines begin in terms of lambda. Note that it covers only the expression case of begin.
(definesyntax begin
The following alternative expansion for begin does not make use of the ability to write more than one expression in the body of a lambda expression. It, too, covers only the expression case of begin.
(definesyntax begin
A predicate is a procedure that always returns a boolean value (#t or #f). An equivalence predicate is the computational analogue of a mathematical equivalence relation (it is symmetric, reflexive, and transitive). Of the equivalence predicates described in this section, eq? is the finest or most discriminating, and equal? is the coarsest. The eqv? predicate is slightly less discriminating than eq?.
The eqv? procedure defines a useful equivalence relation on objects. Briefly, it returns #t if obj_{1} and obj_{2} should normally be regarded as the same object and #f otherwise. This relation is left slightly open to interpretation, but the following partial specification of eqv? holds for all implementations of Scheme.
The eqv? procedure returns #t if one of the following holds:
Obj_{1} and obj_{2} are both booleans and are the same according to the boolean=? procedure (section 9.9).
Obj_{1} and obj_{2} are both symbols and are the same according to the symbol=? procedure (section 9.11).
Obj_{1} and obj_{2} are both exactnumbers and are numerically equal (see =, section 9.8).
Obj_{1} and obj_{2} are both inexactnumbers, are numerically equal (see =, section 9.8, and yield the same results (in the sense of eqv?) when passed as arguments to any other procedure that can be defined as a finite composition of Scheme’s standard arithmetic procedures.
Obj_{1} and obj_{2} are both characters and are the same character according to the char=? procedure (section 9.12).
Both obj_{1} and obj_{2} are the empty list.
Obj_{1} and obj_{2} are mutable objects such as pairs, vectors, strings, mutable records (library chapter on “Records”), ports (library section on “Port I/O”), and hashtables (library chapter on “Hash tables”) that denote the same locations in the store (section 4.8).
Obj_{1} and obj_{2} are records, and library section on “Mutability and equivalence” specifies that eqv? returns #t.
Obj_{1} and obj_{2} are recordtype descriptors that are specified to be eqv? in library section on “Procedural layer”.
The eqv? procedure returns #f if one of the following holds:
Obj_{1} and obj_{2} are of different types (section 9.2).
Obj_{1} is a record and obj_{2} is not, or vice versa (see library chapter on “Records”).
Obj_{1} and obj_{2} are records, and library section on “Mutability and equivalence” specifies that eqv? returns #f.
Obj_{1} and obj_{2} are booleans for which the boolean=? procedure returns #f.
Obj_{1} and obj_{2} are symbols for which the symbol=? procedure returns #f.
One of obj_{1} and obj_{2} is an exact number but the other is an inexact number.
Obj_{1} and obj_{2} are rational numbers for which the = procedure returns #f.
Obj_{1} and obj_{2} yield different results (in the sense of eqv?) when passed as arguments to any other procedure that can be defined as a finite composition of Scheme’s standard arithmetic procedures.
Obj_{1} and obj_{2} are characters for which the char=? procedure returns #f.
One of obj_{1} and obj_{2} is the empty list, but the other is not.
Obj_{1} and obj_{2} are mutable objects such as pairs, vectors, strings, mutable records (library chapter on “Records”), ports (library section on “Port I/O”), and hashtables (library chapter on “Hashtables”) that denote distinct locations.
Obj_{1} and obj_{2} are procedures that would behave differently (return different values or have different side effects) for some arguments.
Note: The eqv? procedure returning #t when obj_{1} and obj_{2} are numbers does not imply that = would also return #t when called with obj_{1} and obj_{2} as arguments.
(eqv? ’a ’a) ⇒ #t
The following examples illustrate cases in which the above rules do not fully specify the behavior of eqv?. All that can be said about such cases is that the value returned by eqv? must be a boolean.
(eqv? "" "") ⇒ unspecified
The next set of examples shows the use of eqv? with procedures that have local state. Calls to gencounter must return a distinct procedure every time, since each procedure has its own internal counter. Calls to genloser return procedures that behave pairwise equivalent when called. However, eqv? is not required to detect this equivalence.
(define gencounter
Since the effect of trying to modify constant objects (those returned by literal expressions) is unspecified, implementations are permitted, though not required, to share structure between constants where appropriate. Furthermore, a constant may be copied at any time by the implementation so as to exist simultaneously in different sets of locations, as noted in section 4.8. Thus the value of eqv? on constants is sometimes implementationdependent.
(eqv? ’(a) ’(a)) ⇒ unspecified
Note: Library section on “Procedural layer” elaborates on the semantics of eqv? on record objects.
Rationale: The above definition of eqv? allows implementations latitude in their treatment of procedures and literals: implementations are free either to detect or to fail to detect that two procedures or two literals are equivalent to each other, and can decide whether or not to merge representations of equivalent objects by using the same pointer or bit pattern to represent both. Moreover, they can use implementation techniques such as inlining and beta reduction that duplicate otherwise equivalent objects.
The eq? predicate is similar to eqv? except that in some cases it is capable of discerning distinctions finer than those detectable by eqv?.
The eq? and eqv? predicates are guaranteed to have the same behavior on symbols, booleans, the empty list, pairs, procedures, nonempty strings and vectors, and mutable records. The behavior of eq? on numbers and characters is implementationdependent, but it always returns either true or false, and returns true only when eqv? would also return true. The eq? predicate may also behave differently from eqv? on empty vectors and empty strings.
(eq? ’a ’a) ⇒ #t
Rationale: It is usually possible to implement eq? much more efficiently than eqv?, for example, as a simple pointer comparison instead of as some more complicated operation. One reason is that it may not be possible to compute eqv? of two numbers in constant time, whereas eq? implemented as pointer comparison will always finish in constant time. The eq? predicate may be used like eqv? in applications using procedures to implement objects with state since it obeys the same constraints as eqv?.
The equal? predicate returns #t if and only if the (possibly infinite) unfoldings of its arguments into regular trees are equal as ordered trees.
The equal? predicate treats pairs and vectors as nodes with outgoing edges, uses string=? to compare strings, uses bytevector=? to compare bytevectors (see library chapter on “Bytevectors”), and uses eqv? to compare other nodes.
(equal? ’a ’a) ⇒ #t
Returns #t if obj is a procedure, otherwise returns #f.
(procedure? car) ⇒ #t
The procedures described here implement arithmetic that is generic over the numerical tower described in chapter 2. The generic procedures described in this section accept both exact and inexact numbers as arguments, performing coercions and selecting the appropriate operations as determined by the numeric subtypes of their arguments.
Library chapter on “Arithmetic” describes libraries that define other numerical procedures.
The procedures listed below must return the correct exact result provided all their arguments are exact:
+  *
The procedures listed below must return the correct exact result provided all their arguments are exact, and no divisors are zero:
/
The general rule is that the generic operations return the correct exact result when all of their arguments are exact and the result is mathematically welldefined, but return an inexact result when any argument is inexact. Exceptions to this rule include sqrt, exp, log, sin, cos, tan, asin, acos, atan, expt, makepolar, magnitude, and angle, which are allowed (but not required) to return inexact results even when given exact arguments, as indicated in the specification of these procedures.
One general exception to the rule above is that an implementation may return an exact result despite inexact arguments if that exact result would be the correct result for all possible substitutions of exact arguments for the inexact ones. An example is (* 1.0 0) which may return either 0 (exact) or 0.0 (inexact).
The specification of the numerical operations is written as though infinities and NaNs are representable, and specifies many operations with respect to these numbers in ways that are consistent with the IEEE 754 standard for binary floating point arithmetic. An implementation of Scheme is not required to represent infinities and NaNs; however, an implementation must raise a continuable exception with condition type &noinfinities or &nonans (respectively; see library section on “Flonums”) whenever it is unable to represent an infinity or NaN as required by the specification. In this case, the continuation of the exception handler is the continuation that otherwise would have received the infinity or NaN value. This requirement also applies to conversions between numbers and external representations, including the reading of program source code.
Some operations are the semantic basis for several arithmetic procedures. The behavior of these operations is described in this section for later reference.
For various kinds of arithmetic (fixnum, flonum, exact, inexact, and generic), Scheme provides operations for performing integer division. They rely on mathematical operations div, mod, div_{0}, and mod_{0}, that are defined as follows:
div, mod, div_{0}, and mod_{0} each accept two real numbers x_{1} and x_{2} as operands, where x_{2} must be nonzero.
div returns an integer, and mod returns a real. Their results are specified by
x_{1} div x_{2}  =  n_{d} 
x_{1} mod x_{2}  =  x_{m} 
* where
Examples:
123 div 10  =  12 
123 mod 10  =  3 
123 div  10  =   12 
123 mod  10  =  3 
 123 div 10  =   13 
 123 mod 10  =  7 
 123 div  10  =  13 
 123 mod  10  =  7 
* div_{0} and mod_{0} are like div and mod, except the result of mod_{0} lies within a halfopen interval centered on zero. The results are specified by
x_{1} div_{0} x_{2}  =  n_{d} 
x_{1} mod_{0} x_{2}  =  x_{m} 
* where:
Examples:
123 div_{0} 10  =  12 
123 mod_{0} 10  =  3 
123 div_{0}  10  =   12 
123 mod_{0}  10  =  3 
 123 div_{0} 10  =   12 
 123 mod_{0} 10  =   3 
 123 div_{0}  10  =  12 
 123 mod_{0}  10  =   3 
*
Rationale: The halfopen symmetry about zero is convenient for some purposes.
In general, the transcendental functions log, sin^{1} (arcsine), cos^{1} (arccosine), and tan^{1} 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). log 0 is undefined.
The value of log z for nonreal z is defined in terms of log on real numbers as
where angle z is the angle of z = a · e^{ib} specified as:
angle z = b + 2 n 
with  ≤ angle z≤ and angle z = b + 2 n for some integer n.
With the oneargument version of log defined this way, the values of the twoargumentversion of log, sin^{1} z, cos^{1} z, tan^{1} z, and the twoargument version of tan^{1} are according to the following formulæ:
log z b  =  (log z/log b) 
sin^{1} z  =   i log (i z + (1  z^{2})^{1/2}) 
cos^{1} z  =  / 2  sin^{1} z 
tan^{1} z  =  (log (1 + i z)  log (1  i z)) / (2 i) 
tan^{1} x y  =  angle(x + yi) 
*
The range of tan^{1} x y is as in the following table. The asterisk (*) indicates that the entry applies to implementations that distinguish minus zero.

The above specification follows Steele [41], which in turn cites Penfield [33]; refer to these sources for more detailed discussion of branch cuts, boundary conditions, and implementation of these functions.
These numerical type predicates can be applied to any kind of argument, including nonnumbers. 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? (imagpart z)) and (exact? (imagpart z)) are both true.
If x is a real number, then (rational? x) is true if and only if there exist exact integers k_{1} and k_{2} such that (= x (/ k_{1} k_{2})) and (= (numerator x) k_{1}) and (= (denominator x) k_{2}) are all true. Thus infinities and NaNs are not rational numbers.
If q is a rational number, then (integer? q) is true if and only if (= (denominator q) 1) is true. If q is not a rational number, then (integer? q) is false.
(complex? 3+4i) ⇒ #t
Note: Except for number?, the behavior of these type predicates on inexact numbers is unreliable, because any inaccuracy may affect the result.
These numerical type predicates can be applied to any kind of argument, including nonnumbers. The realvalued? procedure returns #t if the object is a number and is equal in the sense of = to some real number, or if the object is a NaN, or a complex number whose real part is a NaN and whose imaginary part zero in the sense of zero?. The rationalvalued? and integervalued? procedures return #t if the object is a number and is equal in the sense of = to some object of the named type, and otherwise they return #f.
(realvalued? +nan.0) ⇒ #t
Rationale: These procedures test whether a given number can be coerced to the specified type without loss of numerical accuracy. Their behavior is different from the numerical type predicates in the previous entry, whose behavior is motivated by closure properties designed to enable statically predictable semantics and efficient implementation.
Note: The behavior of these type predicates on inexact numbers is unreliable, because any inaccuracy may affect the result.
These numerical predicates provide tests for the exactness of a quantity. For any Scheme number, precisely one of these predicates is true.
(exact? 5) ⇒ #t
The inexact procedure returns an inexact representation of z. If inexact numbers of the appropriate type have bounded precision, then the value returned is an inexact number that is nearest to the argument. If an exact argument has no reasonably close inexact equivalent, an exception with condition type &implementationviolation may be raised.
The exact procedure returns an exact representation of z. The value returned is the exact number that is numerically closest to the argument; in most cases, the result of this procedure should be numerically equal to its argument. If an inexact argument has no reasonably close exact equivalent, an exception with condition type &implementationviolation may be raised.
These procedures implement the natural onetoone correspondence between exact and inexact integers throughout an implementationdependent range.
The inexact and exact procedures are idempotent.
Given a real number x, these procedures compute the best IEEE754 single or double precision approximation to x and return that approximation as an inexact real.
Note: Both of the two conversions performed by these procedures (to IEEE754 single or double, and then to an inexact real) may lose precision, introduce error, or may underflow or overflow.
Rationale: The ability to round to IEEE754 single or double precision is occasionally needed for control of precision or for interoperability.
These procedures return #t if their arguments are (respectively): equal, monotonically increasing, monotonically decreasing, monotonically nondecreasing, or monotonically nonincreasing, and #f otherwise.
(= +inf.0 +inf.0) ⇒ #t
For any real number x that is neither infinite nor NaN:
(< inf.0 x +inf.0)) ⇒ #t
For any number z:
(= +nan.0 z) ⇒ #fFor any real number x:
(< +nan.0 x) ⇒ #f
These predicates are required to be transitive.
Note: The traditional implementations of these predicates in Lisplike languages are not transitive.
Note: While it is possible to compare inexact numbers using these predicates, the results may be unreliable because a small inaccuracy may affect the result; this is especially true of = and zero? (below).When in doubt, consult a numerical analyst.
These numerical predicates test a number for a particular property, returning #t or #f. See note above. The zero? procedure tests if the number is = to zero, positive? tests whether it is greater than zero, negative? tests whether it is less than zero, odd? tests whether it is odd, even? tests whether it is even, finite? tests whether it is not an infinity and not a NaN, infinite? tests whether it is an infinity, nan? tests whether it is a NaN.
(zero? +0.0) ⇒ #t
These procedures return the maximum or minimum of their arguments.
(max 3 4) ⇒ 4 ; exact
For any real number x:
(max +inf.0 x) ⇒ +inf.0
Note: If any argument is inexact, then the result is also 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 raise an exception with condition type &implementationrestriction.
These procedures return the sum or product of their arguments.
(+ 3 4) ⇒ 7
For any real number x that is neither infinite nor NaN:
(+ +inf.0 x) ⇒ +inf.0
For any real number x:
(+ +nan.0 x) ⇒ +nan.0
For any real number x that is not an exact 0:
(* +nan.0 x) ⇒ +nan.0
If any of these procedures are applied to mixed nonrational real and nonreal complex arguments, they either raise an exception with condition type &implementationrestriction or return an unspecified number.
Implementations that distinguish  0.0 should adopt behavior consistent with the following examples:
(+ 0.0 0.0) ⇒ 0.0
Rationale: This behavior is consistent with the IEEE floating point standard.
With two or more arguments, these procedures return the difference or quotient of their arguments, associating to the left. With one argument, however, they return the additive or multiplicative inverse of their argument.
( 3 4) ⇒ 1
If any of these procedures are applied to mixed nonrational real and nonreal complex arguments, they either raise an exception with condition type &implementationrestriction or return an unspecified number.
Implementations that distinguish  0.0 should adopt behavior consistent with the following examples:
( 0.0) ⇒ 0.0
Rationale: This behavior is consistent with the IEEE floating point standard.
Returns the absolute value of its argument.
(abs 7) ⇒ 7
These procedures implement numbertheoretic integer division and return the results of the corresponding mathematical operations specified in section 9.8.3.1. In each case, x_{1} must be neither infinite nor a NaN, and x_{2} must be nonzero; otherwise, an exception with condition type &assertion is raised.
(div x_{1} x_{2}) ⇒ x_{1} div x_{2}
These procedures return the greatest common divisor or least common multiple of their arguments. The result is always nonnegative.
(gcd 32 36) ⇒ 4
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
These procedures return inexact integers for inexact arguments that are not infinities or NaNs, and exact integers for exact rational arguments. For such arguments, floor returns the largest integer not larger than x. The ceiling procedure returns the smallest integer not smaller than x. The truncate procedure returns the integer closest to x whose absolute value is not larger than the absolute value of x. The round procedure 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 floating point standard.
Note: If the argument to one of these procedures is inexact, then the result is also inexact. If an exact value is needed, the result should be passed to the exact procedure.
Although infinities and NaNs are not integers, these procedures return an infinity when given an infinity as an argument, and a NaN when given a NaN.
(floor 4.3) ⇒ 5.0
The rationalize procedure returns the simplest rational number differing from x_{1} by no more than x_{2}. A rational number r_{1} is simpler than another rational number r_{2} if r_{1} = p_{1}/q_{1} and r_{2} = p_{2}/q_{2} (in lowest terms) and p_{1} ≤ p_{2} and q_{1} ≤ q_{2}. Thus 3/5 is simpler than 4/7. Although not all rationals are comparable in this ordering (consider 2/7 and 3/5) any interval contains a rational number that is simpler than every other rational number in that interval (the simpler 2/5 lies between 2/7 and 3/5). Note that 0 = 0/1 is the simplest rational of all.
(rationalize
These procedures compute the usual transcendental functions. The exp procedure computes the basee exponential of z. The log procedure with a single argument computes the natural logarithm of z (not the base ten logarithm); (log z_{1} z_{2}) computes the basez_{2} logarithm of z_{1}. The asin, acos, and atan procedures compute arcsine, arccosine, and arctangent, respectively. The twoargument variant of atan computes (angle (makerectangular x_{2} x_{1})).
See section 9.8.3.2 for the underlying mathematical operations. These procedures may return inexact results even when given exact arguments.
(exp +inf.0) ⇒ +inf.0
Returns the principal square root of z. For rational z, the result has either positive real part, or zero real part and nonnegative imaginary part. With log defined as in section 9.8.3.2, the value of (sqrt z) could be expressed as
The sqrt procedure may return an inexact result even when given an exact argument.
(sqrt 5)
Rationale: This behavior is consistent with the IEEE floating point standard.
The exactintegersqrt procedure returns two nonnegative exact integers s and r where k = s^{2} + r and k < (s + 1)^{2}.
(exactintegersqrt 4) ⇒ 2, 0
Returns z_{1} raised to the power z_{2}. For nonzero z_{1},
0.0^{z} is 1.0 if z = 0.0, and 0.0 if (realpart z) is positive. For other cases in which the first argument is zero, either an exception is raised with condition type &implementationrestriction, or an unspecified number is returned.
For an exact real z_{1} and an exact integer z_{2}, (expt z_{1} z_{2}) must return an exact result. For all other values of z_{1} and z_{2}, (expt z_{1} z_{2}) may return an inexact result, even when both z_{1} and z_{2} are exact.
(expt 5 3) ⇒ 125
Suppose x_{1}, x_{2}, x_{3}, and x_{4} are real numbers and z is a complex number such that
Then:
(makerectangular x_{1} x_{2}) ⇒ zwhere  ≤ x_{angle} ≤ with x_{angle} = x_{4} + 2 n for some integer n.
(angle 1.0) ⇒
Moreover, suppose x_{1}, x_{2} are such that either x_{1} or x_{2} is an infinity, then
(makerectangular x_{1} x_{2}) ⇒ z
The makepolar, magnitude, and angle procedures may return inexact results even when given exact arguments.
(angle 1) ⇒
Radix must be an exact integer, either 2, 8, 10, or 16. If omitted, radix defaults to 10. If a precision is specified, then z must be an inexact complex number, precision must be an exact positive integer, and radix must be 10. The number>string procedure 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 z) (radix radix))is true. If no possible result makes this expression true, an exception with condition type &implementationrestriction is raised.
Note: The error case can occur only when z is not a complex number or is a complex number with a nonrational real or imaginary part.
If a precision is specified, then the representations of the inexact real components of the result, unless they are infinite or NaN, specify an explicit <mantissa width> p, and p is the least p ≥ precision for which the above expression is true.
If z is inexact, the radix is 10, and the above expression and condition 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, trailing zeroes, and mantissa width) needed to make the above expression and condition true [5, 12]; otherwise the format of the result is unspecified.
Rationale: If z is an inexact number represented using binary floating point, 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 representations other than binary floating point.
The result returned by number>string never contains an explicit radix prefix.
Returns a number of the maximally precise representation expressed by the given string. Radix must be an exact integer, either 2, 8, 10, or 16. If supplied, radix is a default radix that may be overridden by an explicit radix prefix in string (e.g., "#o177"). If radix is not supplied, then the default radix is 10. If string is not a syntactically valid notation for a number, then string>number returns #f.
(string>number "100") ⇒ 100
The standard boolean objects for true and false are written as #t and #f.However, of all the standard Scheme values, only #f counts as false in conditional expressions. See section 4.6.
Note: Programmers accustomed to other dialects of Lisp should be aware that Scheme distinguishes both #f and the empty list from each other and from the symbol nil.
Returns #t if obj is false, and returns #f otherwise.
(not #t) ⇒ #f
Returns #t if obj is either #t or #f and returns #f otherwise.
(boolean? #f) ⇒ #t
Returns #t if the booleans are the same.
A pair (sometimes called a dotted pair) is a record structure with two fields called the car and cdr fields (for historical reasons). Pairs are created by the procedure cons. The car and cdr fields are accessed by the procedures car and cdr.
Pairs are used primarily to represent lists. A list can be defined recursively as either the empty listor a pair whose cdr is a list. More precisely, the set of lists is defined as the smallest set X such that
The empty list is in X.
If list is in X, then any pair whose cdr field contains list is also in X.
The objects in the car fields of successive pairs of a list are the elements of the list. For example, a twoelement list is a pair whose car is the first element and whose cdr is a pair whose car is the second element and whose cdr is the empty list. The length of a list is the number of elements, which is the same as the number of pairs.
The empty listis a special object of its own type. It is not a pair. It has no elements and its length is zero.
Note: The above definitions imply that all lists have finite length and are terminated by the empty list.
A chain of pairs not ending in the empty list is called an improper list. Note that an improper list is not a list. The list and dotted notations can be combined to represent improper lists:
(a b c . d)
is equivalent to
(a . (b . (c . d)))
Whether a given pair is a list depends upon what is stored in the cdr field.
Returns #t if obj is a pair, and otherwise returns #f.
(pair? ’(a . b)) ⇒ #t
Returns a newly allocated pair whose car is obj_{1} and whose cdr is obj_{2}. The pair is guaranteed to be different (in the sense of eqv?) from every existing object.
(cons ’a ’()) ⇒ (a)
Returns the contents of the car field of pair.
(car ’(a b c)) ⇒ a
Returns the contents of the cdr field of pair.
(cdr ’((a) b c d)) ⇒ (b c d)
These procedures are compositions of car and cdr, where for example caddr could be defined by
(define caddr (lambda (x) (car (cdr (cdr x))))).
Arbitrary compositions, up to four deep, are provided. There are twentyeight of these procedures in all.
Returns #t if obj is the empty list. Otherwise, returns #f.
Returns #t if obj is a list. Otherwise, returns #f. By definition, all lists are chains of pairs that have finite length and are terminated by the empty list.
(list? ’(a b c)) ⇒ #t
Returns a newly allocated list of its arguments.
(list ’a (+ 3 4) ’c) ⇒ (a 7 c)
Returns the length of list.
(length ’(a b c)) ⇒ 3
Returns a possibly improper list consisting of the elements of the first list followed by the elements of the other lists, with obj as the cdr of the final pair. An improper list results if obj is not a list.
(append ’(x) ’(y)) ⇒ (x y)
The resulting chain of pairs is always newly allocated, except that it shares structure with the obj argument.
Returns a newly allocated list consisting of the elements of list in reverse order.
(reverse ’(a b c)) ⇒ (c b a)
List should be a list of size at least k.
The listtail procedure returns the subchain of pairs of list obtained by omitting the first k elements.
(listtail ’(a b c d) 2) ⇒ (c d)
Implementation responsibilities: The implementation must check that list is a chain of pairs whose length is at least k. It should not check that it is a chain of pairs beyond this length.
List must be a list whose length is at least k + 1.
Returns the kth element of list.
(listref ’(a b c d) 2) ⇒ c
Implementation responsibilities: The implementation must check that list is a chain of pairs whose length is at least k + 1. It should not check that it is a list of pairs beyond this length.
The lists should all have the same length. Proc should accept as many arguments as there are lists and return a single value. Proc should not mutate any of the lists.
The map procedure applies proc elementwise to the elements of the lists and returns a list of the results, in order. Proc is always called in the same dynamic environment as map itself. The dynamic order in which proc is applied to the elements of the lists is unspecified. If multiple returns occur from map, the values returned by earlier returns are not mutated.
(map cadr ’((a b) (d e) (g h)))
Implementation responsibilities: The implementation should check that the lists all have the same length. The implementation must check the restrictions on proc to the extent performed by applying it as described.
The lists should all have the same length. Proc should accept as many arguments as there are lists. Proc should not mutate any of the lists.
The foreach procedure applies proc elementwise to the elements of the lists for its side effects, in order from the first elements to the last. Proc is always called in the same dynamic environment as foreach itself. The return values of foreach are unspecified.
(let ((v (makevector 5)))
Implementation responsibilities: The implementation should check that the lists all have the same length. The implementation must check the restrictions on proc to the extent performed by applying it as described.
Rationale: Implementations of foreach may or may not tailcall proc on the last elements.
Symbols are objects whose usefulness rests on the fact that two symbols are identical (in the sense of eq?, eqv? and equal?) if and only if their names are spelled the same way. This is exactly the property needed to represent identifiersin programs, and so most implementations of Scheme use them internally for that purpose. Symbols are useful for many other applications; for instance, they may be used the way enumerated values are used in C and Pascal.
A symbol literal is formed using quote.
Hello ⇒ Hello
Returns #t if obj is a symbol, otherwise returns #f.
(symbol? ’foo) ⇒ #t
Returns the name of symbol as an immutable string.
(symbol>string ’flyingfish)
Returns #t if the symbols are the same, i.e., if their names are spelled the same.
Returns the symbol whose name is string.
(eq? ’mISSISSIppi ’mississippi)
Characters are objects that represent Unicode scalar values [45].
Note: Unicode defines a standard mapping between sequences of code points(integers in the range 0 to #x10FFFF in the latest version of the standard) and humanreadable “characters”. More precisely, Unicode distinguishes between glyphs, which are printed for humans to read, and characters, which are abstract entities that map to glyphs (sometimes in a way that’s sensitive to surrounding characters). Furthermore, different sequences of code points sometimes correspond to the same character. The relationships among code points, characters, and glyphs are subtle and complex.Despite this complexity, most things that a literate human would call a “character” can be represented by a single code point in Unicode (though several codepoint sequences may represent that same character). For example, Roman letters, Cyrillic letters, Hebrew consonants, and most Chinese characters fall into this category. Thus, the “code point” approximation of “character” works well for many purposes. More specifically, Scheme characters correspond to Unicode scalar values, which includes all code points except those designated as surrogates. A surrogate is a code point in the range #xD800 to #xDFFF that is used in pairs in the UTF16 encoding to encode a supplementary character (whose code is in the range #x10000 to #x10FFFF).
Returns #t if obj is a character, otherwise returns #f.
Sv must be a Unicode scalar value, i.e., a nonnegative exact integer in [0, #xD7FF] ∪ [#xE000, #x10FFFF].
Given a character, char>integer returns its Unicode scalar value as an exact integer. For a Unicode scalar value sv, integer>char returns its associated character.
(integer>char 32) ⇒ #\space
These procedures impose a total ordering on the set of characters according to their Unicode scalar values.
(char<? #\z #\ß) ⇒ #t
Strings are sequences of characters.
The length of a string is the number of characters that it contains. This number is an exact, nonnegative integer that is fixed when the string is created. The valid indices of a string are the exact nonnegative integers less than the length of the string. The first character of a string has index 0, the second has index 1, and so on.
In phrases such as “the characters of string beginning with index start and ending with index end”, it is understood that the index start is inclusive and the index end is exclusive. Thus if start and end are the same index, a null substring is referred to, and if start is zero and end is the length of string, then the entire string is referred to.
Returns #t if obj is a string, otherwise returns #f.
Returns a newly allocated string of length k. If char is given, then all elements of the string are initialized to char, otherwise the contents of the string are unspecified.
Returns a newly allocated string composed of the arguments.
Returns the number of characters in the given string.
K must be a valid index of string. The stringref procedure returns character
k of string using zeroorigin indexing.
Note: Implementors are encouraged to make stringref run in constant time.
Returns #t if the strings are the same length and contain the same characters in the same positions. Otherwise, returns #f.
(string=? "Straße" "Strasse") ⇒ #f
These procedures are the lexicographic extensions to strings of the corresponding orderings on characters. For example, string<? is the lexicographic ordering on strings induced by the ordering char<? on characters. If two strings differ in length but are the same up to the length of the shorter string, the shorter string is considered to be lexicographically less than the longer string.
(string<? "z" "ß") ⇒ #t
String must be a string, and start and end must be exact integers satisfying
0 ≤ start ≤ end ≤ (stringlength string). 
The substring procedure returns a newly allocated string formed from the characters of string beginning with index start (inclusive) and ending with index end (exclusive).
Returns a newly allocated string whose characters form the concatenation of the given strings.
List must be a list of characters. The string>list procedure returns a newly allocated list of the characters that make up the given string. The list>string procedure returns a newly allocated string formed from the characters in list. The string>list and list>string procedures are inverses so far as equal? is concerned.
The strings must all have the same length. Proc should accept as many arguments as there are strings. The stringforeach procedure applies proc elementwise to the characters of the strings for its side effects, in order from the first characters to the last. Proc is always called in same dynamic environment as stringforeach itself. The return values of stringforeach are unspecified.
Analogous to foreach.
Returns a newly allocated copy of the given string.
Vectors are heterogeneous structures whose elements are indexed by integers. A vector typically occupies less space than a list of the same length, and the average time required to access a randomly chosen element is typically less for the vector than for the list.
The length of a vector is the number of elements that it contains. This number is a nonnegative integer that is fixed when the vector is created. The valid indicesof a vector are the exact nonnegative integers less than the length of the vector. The first element in a vector is indexed by zero, and the last element is indexed by one less than the length of the vector.
Like list constants, vector constants must be quoted:
’#(0 (2 2 2 2) "Anna")
Returns #t if obj is a vector. Otherwise the procedure returns #f.
Returns a newly allocated vector of k elements. If a second argument is given, then each element is initialized to fill. Otherwise the initial contents of each element is unspecified.
Returns a newly allocated vector whose elements contain the given arguments. Analogous to list.
(vector ’a ’b ’c) ⇒ #(a b c)
Returns the number of elements in vector as an exact integer.
K must be a valid index of vector. The vectorref procedure returns the contents of element
k of vector.
(vectorref ’#(1 1 2 3 5 8 13 21)
K must be a valid index of vector. The vectorset! procedure stores obj in element
k of vector. The value returned by vectorset! is unspecified.
Passing an immutable vector to vectorset! should cause an exception with condition type &assertion to be raised.
(let ((vec (vector 0 ’(2 2 2 2) "Anna")))
The vector>list procedure returns a newly allocated list of the objects contained in the elements of vector. The list>vector procedure returns a newly created vector initialized to the elements of the list list.
(vector>list ’#(dah dah didah))
Stores fill in every element of vector and returns the unspecified value.
The vectors must all have the same length. Proc should accept as many arguments as there are vectors and return a single value.
The vectormap procedure applies proc elementwise to the elements of the vectors and returns a vector of the results, in order. Proc is always called in same dynamic environment as vectormap itself. The dynamic order in which proc is applied to the elements of the vectors is unspecified.
Analogous to map.
The vectors must all have the same length. Proc should accept as many arguments as there are vectors. The vectorforeach procedure applies proc elementwise to the elements of the vectors for its side effects, in order from the first elements to the last. Proc is always called in same dynamic environment as vectorforeach itself. The return values of vectorforeach are unspecified.
Analogous to foreach.
Who must be a string or a symbol or #f. Message must be a string. The irritants are arbitrary objects.
These procedures raise an exception. Calling the error procedure means that an error has occurred, typically caused by something that has gone wrong in the interaction of the program with the external world or the user. Calling the assertionviolation procedure means that an invalid call to a procedure was made, either passing an invalid number of arguments, or passing an argument that it is not specified to handle.
The who argument should describe the procedure or operation that detected the exception. The message argument should describe the exceptional situation. The irritants should be the arguments to the operation that detected the operation.
The condition object provided with the exception (see library chapter on “Exceptions and conditions”) has the following condition types:
If who is not #f, the condition has condition type &who, with who as the value of the who field. In that case, who should identify the procedure or entity that detected the exception. If it is #f, the condition does not have condition type &who.
The condition has condition type &message, with message as the value of the message field.
The condition has condition type &irritants, and the irritants field has as its value a list of the irritants.
Moreover, the condition created by error has condition type &error, and the condition created by assertionviolation has condition type &assertion.
(define (fac n)
Rationale: The procedures encode a common pattern of raising exceptions.
An assert form is evaluated by evaluating <expression>. If <expression> returns a true value, that value is returned from the assert expression. If <expression> returns #f, an exception with condition types &assertion and &message is raised. The message provided in the condition object is implementationdependent.
Rationale: Implementations can (and are encouraged to) exploit the fact that assert is syntax to provide as much information as possible about the location of the assertion failure.
This chapter describes various primitive procedures which control the flow of program execution in special ways.
Args must be a list. Proc should accept n arguments, where n is number of args plus the length of args. Calls proc with the elements of the list (append (list arg_{1} ...) args) as the actual arguments.
(apply + (list 3 4)) ⇒ 7
Proc should accept one argument. The procedure callwithcurrentcontinuation (which is the same as the procedure call/cc) packages the current continuation (see the rationale below) as an “escape procedure”and passes it as an argument to proc. The escape procedure is a Scheme procedure that, if it is later called, will abandon whatever continuation is in effect at that later time and will instead use the continuation that was in effect when the escape procedure was created. Calling the escape procedure may cause the invocation of before and after thunks installed using dynamicwind.
The escape procedure accepts the same number of arguments as the continuation of the original call to callwithcurrentcontinuation.
The escape procedure that is passed to proc has unlimited extent just like any other procedure in Scheme. It may be stored in variables or data structures and may be called as many times as desired.
The following examples show only the most common ways in which callwithcurrentcontinuation is used. If all real uses were as simple as these examples, there would be no need for a procedure with the power of callwithcurrentcontinuation.
(callwithcurrentcontinuation
Rationale:A common use of callwithcurrentcontinuation is for structured, nonlocal exits from loops or procedure bodies, but in fact callwithcurrentcontinuation is useful for implementing a wide variety of advanced control structures.
Whenever a Scheme expression is evaluated there is a continuation wanting the result of the expression. The continuation represents an entire (default) future for the computation. Most of the time the continuation includes actions specified by user code, as in a continuation that will take the result, multiply it by the value stored in a local variable, add seven, and store the result in some other variable. Normally these ubiquitous continuations are hidden behind the scenes and programmers do not think much about them. On rare occasions, however, a programmer may need to deal with continuations explicitly. The callwithcurrentcontinuation procedure allows Scheme programmers to do that by creating a procedure that acts just like the current continuation.
Most programming languages incorporate one or more specialpurpose escape constructs with names like exit, return, or even goto. In 1965, however, Peter Landin [29] invented a general purpose escape operator called the Joperator. John Reynolds [36] described a simpler but equally powerful construct in 1972. The catch special form described by Sussman and Steele in the 1975 report on Scheme is exactly the same as Reynolds’s construct, though its name came from a less general construct in MacLisp. Several Scheme implementors noticed that the full power of the catch construct could be provided by a procedure instead of by a special syntactic construct, and the name callwithcurrentcontinuation was coined in 1982. This name is descriptive, but opinions differ on the merits of such a long name, and some people use the name call/cc instead.
Delivers all of its arguments to its continuation. The values procedure might be defined as follows:
(define (values . things)
The continuations of all nonfinal expressions within a sequence of expressions in lambda, begin, let, let*, letrec, letrec*, letvalues, let*values, case, cond, and do forms as well as the continuations of the before and after arguments to dynamicwind take an arbitrary number of values.
Except for these and the continuations created by callwithvalues, letvalues, and let*values, all other continuations take exactly one value. The effect of passing an inappropriate number of values to a continuation not created by callwithvalues, letvalues, or let*values is undefined.
Producer must be a procedure and should accept zero arguments. Consumer must be a procedure and should accept as many values as producer returns. Calls producer with no arguments and a continuation that, when passed some values, calls the consumer procedure with those values as arguments. The continuation for the call to consumer is the continuation of the call to callwithvalues.
(callwithvalues (lambda () (values 4 5))
Implementation responsibilities: After producer returns, the implementation must check that consumer accepts as many values as consumer has returned.
Before, thunk, and after must be procedures, and each should accept zero arguments. These procedures may return any number of values.
In the absence of any calls to escape procedures (see callwithcurrentcontinuation), dynamicwind behaves as if defined as follows.
(define dynamicwind
That is, before is called without arguments. If before returns, thunk is called without arguments. If thunk returns, after is called without arguments. Finally, if after returns, the values resulting from the call to thunk are returned.
Implementation responsibilities: The implementation must check the restrictions on thunk and after only if they are actually called.
Invoking an escape procedure to transfer control into or out of the dynamic extent of the call to thunk can cause additional calls to before and after. When an escape procedure created outside the dynamic extent of the call to thunk is invoked from within the dynamic extent, after is called just after control leaves the dynamic extent. Similarly, when an escape procedure created within the dynamic extent of the call to thunk is invoked from outside the dynamic extent, before is called just before control reenters the dynamic extent. In the latter case, if thunk returns, after is called even if thunk has returned previously. While the calls to before and after are not considered to be within the dynamic extent of the call to thunk, calls to the before and after thunks of any other calls to dynamicwind that occur within the dynamic extent of the call to thunk are considered to be within the dynamic extent of the call to thunk.
More precisely, an escape procedure transfers control out of the dynamic extent of a set of zero or more active dynamicwind thunk calls x ... and transfer control into the dynamic extent of a set of zero or more active dynamicwind thunk calls y .... It leaves the dynamic extent of the most recent x and calls without arguments the corresponding after thunk. If the after thunk returns, the escape procedure proceeds to the next most recent x, and so on. Once each x has been handled in this manner, the escape procedure calls without arguments the before thunk corresponding to the least recent y. If the before thunk returns, the escape procedure reenters the dynamic extent of the least recent y and proceeds with the next least recent y, and so on. Once each y has been handled in this manner, control is transferred to the continuation packaged in the escape procedure.
(let ((path ’())
“Named let” is a variant on the syntax of let which provides a more general looping construct than do and may also be used to express recursions. It has the same syntax and semantics as ordinary let except that <variable> is bound within <body> to a procedure whose formal arguments are the bound variables and whose body is <body>. Thus the execution of <body> may be repeated by invoking the procedure named by <variable>.
(let loop ((numbers ’(3 2 1 6 5))
p “Backquote” or “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 unquote or unquotesplicing forms appear within the <qq template>, the result of evaluating (quasiquote <qq template>) is equivalent to the result of evaluating (quote <qq template>).
If an (unquote <expression> ...) form appears inside a <qq template>, however, the <expression>s are evaluated (“unquoted”) and their results are inserted into the structure instead of the unquote form.
If an (unquotesplicing <expression> ...) form appears inside a <qq template>, then the <expression>s must evaluate to lists; the opening and closing parentheses of the lists are then “stripped away” and the elements of the lists are inserted in place of the unquotesplicing form.
unquotesplicing and multioperand unquote forms must appear only within a list or vector <qq template>.
As noted in section 3.3.5, (quasiquote <qq template>) may be abbreviated ‘<qq template>, (unquote <expression>) may be abbreviated ,<expression>, and (unquotesplicing <expression>) may be abbreviated ,@<expression>.
‘(list ,(+ 1 2) 4) ⇒ (list 3 4)
Quasiquote forms may 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 quasiquote expression may return either fresh, 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 equivalent to either of the following expressions:
’((1 2) 3 4 five 6)However, it is not equivalent to this expression:
(let ((a 3)) (list (list 1 2) a 4 ’five 6))It is a syntax violation if any of the identifiers quasiquote, unquote, or unquotesplicing appear in positions within a <qq template> otherwise than as described above.
The following grammar for quasiquote expressions is not contextfree. It is presented as a recipe for generating an infinite number of production rules. Imagine a copy of the following rules for D = 1, 2, 3, .... D keeps track of the nesting depth.
<qq template> → <qq template 1>
In <quasiquotation>s, a <list qq template D> can sometimes be confused with either an <unquotation D> or a <splicing unquotation D>. The interpretation as an <unquotation> or <splicing unquotation D> takes precedence.
The letsyntax and letrecsyntax forms are analogous to let and letrec but bind keywords rather than variables. Like a begin form, a letsyntax or letrecsyntax form may appear in a definition context, in which case it is treated as a definition, and the forms in the body must also be definitions. A letsyntax or letrecsyntax form may also appear in an expression context, in which case the forms within their bodies must be expressions.
Syntax: <Bindings> must have the form
((<keyword> <expression>) ...)Each <keyword> is an identifier, and each <expression> is an expression that evaluates, at macroexpansion time, to a transformer (see library chapter on “syntaxcase”). It is a syntax violation for <keyword> to appear more than once in the list of keywords being bound.
Semantics: The <form>s are expanded in the syntactic environment obtained by extending the syntactic environment of the letsyntax form with macros whose keywords are the <keyword>s, bound to the specified transformers. Each binding of a <keyword> has the <form>s as its region.
The <form>s of a letsyntax form are treated, whether in definition or expression context, as if wrapped in an implicit begin; see section 9.5.7. Thus definitions in the result of expanding the <form>s have the same region as any definition appearing in place of the letsyntax form would have.
Implementation responsibilities: The implementation must check that the value of each <expression> is a transformer when the evaluation produces a value.
(letsyntax ((when (syntaxrules ()
Syntax: Same as for letsyntax.
Semantics: The <form>s are expanded in the syntactic environment obtained by extending the syntactic environment of the letrecsyntax form with macros whose keywords are the <keyword>s, bound to the specified transformers. Each binding of a <keyword> has the <bindings> as well as the <form>s within its region, so the transformers can transcribe forms into uses of the macros introduced by the letrecsyntax form.
The <form>s of a letrecsyntax form are treated, whether in definition or expression context, as if wrapped in an implicit begin; see section 9.5.7. Thus definitions in the result of expanding the <form>s have the same region as any definition appearing in place of the letrecsyntax form would have.
Implementation responsibilities: The implementation must check that the value of each <expression> is a transformer when the <expression> evaluates to a value.
(letrecsyntax
The following example highlights how letsyntax and letrecsyntax differ.
(let ((f (lambda (x) (+ x 1))))
The two expressions are identical except that the letsyntax form in the first expression is a letrecsyntax form in the second. In the first expression, the f occurring in g refers to the letbound variable f, whereas in the second it refers to the keyword f whose binding is established by the letrecsyntax form.
Syntax: Each <literal> must be an identifier. Each <syntax rule> must have the following form:
(<srpattern> <template>)
An <srpattern> is a restricted form of <pattern>, namely, a nonempty <pattern> in one of four parenthesized forms below whose first subform is an identifier or an underscore _. A <pattern> is an identifier, constant, or one of the following.
(<pattern> ...)
An <ellipsis> is the identifier “...” (three periods).
A <template> is a pattern variable, an identifier that is not a pattern variable, a pattern datum, or one of the following.
(<subtemplate> ...)
A <subtemplate> is a <template> followed by zero or more ellipses.
Semantics: An instance of syntaxrules evaluates, at macroexpansion time, to 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 syntaxrules 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. It is a syntax violation when no match is found.
An identifier appearing within a <pattern> may be an underscore ( _ ), a literal identifier listed in the list of literals (<literal> ...), or an ellipsis ( ... ). All other identifiers appearing within a <pattern> are pattern variables. It is a syntax violation if an ellipsis or underscore appears in (<literal> ...).
While the first subform of <srpattern> may be an identifier, the identifier is not involved in the matching and is not considered a pattern variable or literal identifier.
Rationale: The identifier is most often the keyword used to identify the macro. The scope of the keyword is determined by the binding form or syntax definition that binds it to the associated macro transformer. If the keyword were a pattern variable or literal identifier, then the template that follows the pattern would be within its scope regardless of whether the keyword were bound by letsyntax, letrecsyntax, or definesyntax.
Pattern variables match arbitrary input subforms and are used to refer to elements of the input. It is a syntax violation if the same pattern variable appears more than once in a <pattern>.
Underscores also match arbitrary input subforms but are not pattern variables and so cannot be used to refer to those elements. Multiple underscores may appear in a <pattern>.
A literal identifier matches an input subform if and only if the input subform is an identifier and either both its occurrence in the input expression and its occurrence in the list of literals have the same lexical binding, or the two identifiers have the same name and both have no lexical binding.
A subpattern followed by an ellipsis can match zero or more elements of the input.
More formally, an input form F matches a pattern P if and only if one of the following holds:
P is an underscore ( _ ).
P is a pattern variable.
P is a literal identifier and F is an identifier such that both P and F would refer to the same binding if both were to appear in the output of the macro outside of any bindings inserted into the output of the macro. (If neither of two likenamed identifiers refers to any binding, i.e., both are undefined, they are considered to refer to the same binding.)
P is of the form (P_{1} ... P_{n}) and F is a list of n elements that match P_{1} through P_{n}.
P is of the form (P_{1} ... P_{n} . P_{x}) and F is a list or improper list of n or more elements whose first n elements match P_{1} through P_{n} and whose nth cdr matches P_{x}.
P is of the form (P_{1} ... P_{k} P_{e} <ellipsis> P_{m+1} ... P_{n}), where <ellipsis> is the identifier ... and F is a list of n elements whose first k elements match P_{1} 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}.
P is of the form (P_{1} ... P_{k} P_{e} <ellipsis> P_{m+1} ... P_{n} . P_{x}), where <ellipsis> is the identifier ... and F is a list or improper list of n elements whose first k elements match P_{1} through P_{k}, whose next m  k elements each match P_{e}, whose next n  m elements match P_{m+1} through P_{n}, and whose nth and final cdr matches P_{x}.
P is of the form #(P_{1} ... P_{n}) and F is a vector of n elements that match P_{1} through P_{n}.
P is of the form #(P_{1} ... P_{k} P_{e} <ellipsis> P_{m+1} ... P_{n}), where <ellipsis> is the identifier ... and F is a vector of n or more elements whose first k elements match P_{1} 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}.
P is a pattern datum (any nonlist, nonvector, nonsymbol datum) and F is equal to P in the sense of the equal? procedure.
When a macro use is transcribed according to the template of the matching <syntax rule>, pattern variables that occur in the template are replaced by the subforms they match in the input.
Pattern data and identifiers that are not pattern variables or ellipses are copied directly into the output. A subtemplate followed by an ellipsis expands into zero or more occurrences of the subtemplate. Pattern variables that occur in subpatterns followed by one or more ellipses may occur only in subtemplates that are followed by (at least) as many ellipses. These pattern variables are replaced in the output by the input subforms to which they are bound, distributed as specified. If a pattern variable is followed by more ellipses in the subtemplate than in the associated subpattern, the input form is replicated as necessary. The subtemplate must contain at least one pattern variable from a subpattern followed by an ellipsis, and for at least one such pattern variable, the subtemplate must be followed by exactly as many ellipses as the subpattern in which the pattern variable appears. (Otherwise, the expander would not be able to determine how many times the subform should be repeated in the output.) It is a syntax violation if the constraints of this paragraph are not met.
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 (... ...) produces a single ellipsis, .... This allows syntactic abstractions to expand into forms containing ellipses.
As an example, if let and cond are defined as in section 9.17 and appendix B then they are hygienic (as required) and the following is not an error.
(let ((=> #f))
The macro transformer for cond recognizes => as a local variable, and hence an expression, and not as the baselibrary identifier =>, which the macro transformer treats as a syntactic keyword. Thus the example expands into
(let ((=> #f))
instead of
(let ((=> #f))
which would result in an assertion violation.
Syntax: The <id>s must be identifiers.
Semantics: When a keyword is bound to a transformer produced by the first form of identifiersyntax, references to the keyword within the scope of the binding are replaced by <template>.
(define p (cons 4 5))
The second, more general, form of identifiersyntax permits the transformer to determine what happens when set! is used. In this case, uses of the identifier by itself are replaced by <template_{1}>, and uses of set! with the identifier are replaced by <template_{2}>.
(define p (cons 4 5))
A tail callis a procedure call that occurs in a tail context. Tail contexts are defined inductively. Note that a tail context is always determined with respect to a particular lambda expression.
The last expression within the body of a lambda expression, shown as <tail expression> below, occurs in a tail context.
(lambda <formals>
If one of the following expressions is in a tail context, then the subexpressions shown as <tail expression> are in a tail context. These were derived from specifications of the syntax of the forms described in this chapter by replacing some occurrences of <expression> with <tail expression>. Only those rules that contain tail contexts are shown here.
(if <expression> <tail expression> <tail expression>)
If a cond expression is in a tail context, and has a clause of the form (<expression_{1}> => <expression_{2}>) then the (implied) call to the procedure that results from the evaluation of <expression_{2}> is in a tail context. <expression_{2}> itself is not in a tail context.
Certain builtin procedures are also required to perform tail calls. The first argument passed to apply and to callwithcurrentcontinuation, and the second argument passed to callwithvalues, must be called via a tail call.
In the following example the only tail call is the call to f. None of the calls to g or h are tail calls. The reference to x is in a tail context, but it is not a call and thus is not a tail call.
(lambda ()
Note: Implementations are allowed, but not required, to recognize that some nontail calls, such as the call to h above, can be evaluated as though they were tail calls. In the example above, the let expression could be compiled as a tail call to h. (The possibility of h returning an unexpected number of values can be ignored, because in that case the effect of the let is explicitly unspecified and implementationdependent.)