Revised(7) Scheme

1.1 Semantics

This section gives an overview of Scheme’s semantics. A detailed informal semantics is the subject of chapters Basic concepts through Standard procedures. For reference purposes, section Formal semantics provides a formal semantics of Scheme.

Scheme is a statically scoped programming language. Each use of a variable is associated with a lexically apparent binding of that variable.

Scheme is a dynamically typed language. Types are associated with values (also called objects) rather than with variables. Statically typed languages, by contrast, associate types with variables and expressions as well as with values.

All objects created in the course of a Scheme computation, including procedures and continuations, have unlimited extent. No Scheme object is ever destroyed. The reason that implementations of Scheme do not (usually!) run out of storage is that they are permitted to reclaim the storage occupied by an object if they can prove that the object cannot possibly matter to any future computation.

Implementations of Scheme are required to be properly tail-recursive. This allows the execution of an iterative computation in constant space, even if the iterative computation is described by a syntactically recursive procedure. Thus with a properly tail-recursive implementation, iteration can be expressed using the ordinary procedure-call mechanics, so that special iteration constructs are useful only as syntactic sugar. See section Proper tail recursion.

Scheme procedures are objects in their own right. Procedures can be created dynamically, stored in data structures, returned as results of procedures, and so on.

One distinguishing feature of Scheme is that continuations, which in most other languages only operate behind the scenes, also have “first-class” status. Continuations are useful for implementing a wide variety of advanced control constructs, including non-local exits, backtracking, and coroutines. See section Control features.

Arguments to Scheme procedures are always passed by value, which means that the actual argument expressions are evaluated before the procedure gains control, regardless of whether the procedure needs the result of the evaluation.

Scheme’s model of arithmetic is designed to remain as independent as possible of the particular ways in which numbers are represented within a computer. In Scheme, every integer is a rational number, every rational is a real, and every real is a complex number. Thus the distinction between integer and real arithmetic, so important to many programming languages, does not appear in Scheme. In its place is a distinction between exact arithmetic, which corresponds to the mathematical ideal, and inexact arithmetic on approximations. Exact arithmetic is not limited to integers.

1.2 Syntax

Scheme, like most dialects of Lisp, employs a fully parenthesized prefix notation for programs and other data; the grammar of Scheme generates a sublanguage of the language used for data. An important consequence of this simple, uniform representation is that Scheme programs and data can easily be treated uniformly by other Scheme programs. For example, the ‘eval’ procedure evaluates a Scheme program expressed as data.

The ‘read’ procedure performs syntactic as well as lexical decomposition of the data it reads. The ‘read’ procedure parses its input as data (section see External representations), not as program.

The formal syntax of Scheme is described in section Formal syntax.

1.3 Notation and terminology

• Base and optional features
• Error situations and unspecified behavior
• Entry format
• Evaluation examples
• Naming conventions

 <thing1> …

 <thing1> <thing2> …

(* 5 8)                                ==>  40

2.1 Identifiers

An identifier is any sequence of letters, digits, and “extended identifier characters” provided that it does not have a prefix which is a valid number. However, the . token (a single period) used in the list syntax is not an identifier.

All implementations of Scheme must support the following extended identifier characters:

! $ % & * + - . / : < = > ? @ ^ _ ~ 

Alternatively, an identifier can be represented by a sequence of zero or more characters enclosed within vertical lines (‘|’), analogous to string literals. Any character, including whitespace characters, but excluding the backslash and vertical line characters, can appear verbatim in such an identifier. In addition, characters can be specified using either an <inline hex escape> or the same escapes available in strings.

For example, the identifier |H\x65;llo| is the same identifier as Hello, and in an implementation that supports the appropriate Unicode character the identifier |\x3BB;| is the same as the identifier lambda. What is more, |\t\t| and |\x9;\x9;| are the same. Note that || is a valid identifier that is different from any other identifier.

Here are some examples of identifiers:

...                      +
+soup+                   <=?
->string                 a34kTMNs
lambda                   list->vector
q                        V17a
|two words|              |two\x20;words|
the-word-recursion-has-many-meanings

See section Lexical structure for the formal syntax of identifiers.

Identifiers have two uses within Scheme programs:

• Any identifier can be used as a variable or as a syntactic keyword (see sections see Variables; syntactic keywords; and regions and see Macros).
• When an identifier appears as a literal or within a literal (see section see Literal expressions), it is being used to denote a symbol (see section see Symbols).

In contrast with earlier revisions of the report [R5RS], the syntax distinguishes between upper and lower case in identifiers and in characters specified using their names. However, it does not distinguish between upper and lower case in numbers, nor in <inline hex escapes> used in the syntax of identifiers, characters, or strings. None of the identifiers defined in this report contain upper-case characters, even when they appear to do so as a result of the English-language convention of capitalizing the first word of a sentence.

The following directives give explicit control over case folding.

‘’#!fold-case ‘’#!no-fold-case

These directives can appear anywhere comments are permitted (see section see Whitespace and comments) but must be followed by a delimiter. They are treated as comments, except that they affect the reading of subsequent data from the same port. The ‘’#!fold-case directive causes subsequent identifiers and character names to be case-folded as if by ‘string-foldcase’ (see section see Strings). It has no effect on character literals. The ‘’#!no-fold-case directive causes a return to the default, non-folding behavior.

2.2 Whitespace and comments

Whitespace characters include the space, tab, and newline characters. (Implementations may provide additional whitespace characters such as page break.) Whitespace is used for improved readability and as necessary to separate tokens from each other, a token being an indivisible lexical unit such as an identifier or number, but is otherwise insignificant. Whitespace can occur between any two tokens, but not within a token. Whitespace occurring inside a string or inside a symbol delimited by vertical lines is significant.

The lexical syntax includes several comment forms. Comments are treated exactly like whitespace.

A semicolon (;) indicates the start of a line comment. The comment continues to the end of the line on which the semicolon appears.

Another way to indicate a comment is to prefix a <datum> (cf. section see External representations) with #; and optional <whitespace>. The comment consists of the comment prefix #;, the space, and the <datum> together. This notation is useful for “commenting out” sections of code.

Block comments are indicated with properly nested #| and |# pairs.

#|
   The FACT procedure computes the factorial
   of a non-negative integer.
|#
(define fact
  (lambda (n)
    (if (= n 0)
        #;(= n 1)
        1        ;Base case: return 1
        (* n (fact (- n 1))))))

2.3 Other notations

For a description of the notations used for numbers, see section Numbers.

. + -

These are used in numbers, and can also occur anywhere in an identifier. A delimited plus or minus sign by itself is also an identifier. A delimited period (not occurring within a number or identifier) is used in the notation for pairs (section see Pairs and lists), and to indicate a rest-parameter in a formal parameter list (section see Procedures). Note that a sequence of two or more periods is an identifier.

( )

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

'

The apostrophe (single quote) character is used to indicate literal data (section see Literal expressions).

`

The grave accent (backquote) character is used to indicate partly constant data (section see Quasiquotation).

, ,@

The character comma and the sequence comma at-sign are used in conjunction with quasiquotation (section see Quasiquotation).

"

The quotation mark character is used to delimit strings (section see Strings).

\

Backslash is used in the syntax for character constants (section see Characters) and as an escape character within string constants (section see Strings) and identifiers (section see Lexical structure).

[ ] { }

Left and right square and curly brackets (braces) are reserved for possible future extensions to the language.

#

The number sign is used for a variety of purposes depending on the character that immediately follows it:

#t #f

These are the boolean constants (section see Booleans), along with the alternatives #true and #false.

#\

This introduces a character constant (section see Characters).

#(

This introduces a vector constant (section see Vectors). Vector constants are terminated by ) .

# u8(

This introduces a bytevector constant (section see Bytevectors). Bytevector constants are terminated by ) .

#e #i #b #o #d #x

These are used in the notation for numbers (section see Syntax of numerical constants).

SHARP<n>= SHARP<n>#

These are used for labeling and referencing other literal data (section see Datum labels).

2.4 Datum labels

lexical syntax: SHARP<n>=<datum> ¶

lexical syntax: SHARP<n># ¶

The lexical syntax SHARP<n>=<datum> reads the same as <datum>, but also results in <datum> being labelled by <n>. It is an error if <n> is not a sequence of digits.

The lexical syntax SHARP<n># serves as a reference to some object labelled by SHARP<n>=; the result is the same object as the SHARP<n>= (see section see Equivalence predicates).

Together, these syntaxes permit the notation of structures with shared or circular substructure.

(let ((x (list 'a 'b 'c)))
  (set-cdr! (cddr x) x)
  x)                                   ==> #0=(a b c . #0#)

The scope of a datum label is the portion of the outermost datum in which it appears that is to the right of the label. Consequently, a reference SHARP<n># can occur only after a label SHARP<n>=; it is an error to attempt a forward reference. In addition, it is an error if the reference appears as the labelled object itself (as in SHARP<n>= SHARP<n>#), because the object labelled by SHARP<n>= is not well defined in this case.

It is an error for a <program> or <library> to include circular references except in literals. In particular, it is an error for ‘quasiquote’ (section see Quasiquotation) to contain them.

#1=(begin (display #\x) #1#)
                                       ==> error

3.1 Variables; syntactic keywords; and regions

An identifier can name either a type of syntax or a location where a value can be stored. An identifier that names a type of syntax is called a syntactic keyword and is said to be bound to a transformer for that syntax. An identifier that names a location is called a variable and is said to be bound to that location. The set of all visible bindings in effect at some point in a program is known as the environment in effect at that point. The value stored in the location to which a variable is bound is called the variable’s value. By abuse of terminology, the variable is sometimes said to name the value or to be bound to the value. This is not quite accurate, but confusion rarely results from this practice.

Certain expression types are used to create new kinds of syntax and to bind syntactic keywords to those new syntaxes, while other expression types create new locations and bind variables to those locations. These expression types are called binding constructs.

Those that bind syntactic keywords are listed in section Macros. The most fundamental of the variable binding constructs is the ‘lambda’ expression, because all other variable binding constructs (except top-level bindings) can be explained in terms of ‘lambda’ expressions. The other variable binding constructs are ‘let’, ‘let*’, ‘letrec’, ‘letrec*’, ‘let-values’, ‘let*-values’, and ‘do’ expressions (see sections see Procedures, see Binding constructs, and see Iteration).

Scheme is a language with block structure. To each place where an identifier is bound in a program there corresponds a region of the program text within which the binding is visible. The region is determined by the particular binding construct that establishes the binding; if the binding is established by a ‘lambda’ expression, for example, then its region is the entire ‘lambda’ expression. Every mention of an identifier refers to the binding of the identifier that established the innermost of the regions containing the use. If there is no binding of the identifier whose region contains the use, then the use refers to the binding for the variable in the global environment, if any (chapters see Expressions and see Standard procedures); if there is no binding for the identifier, it is said to be unbound.

3.2 Disjointness of types

No object satisfies more than one of the following predicates:

boolean?          bytevector?
char?             eof-object?
null?             number?
pair?             port?
procedure?        string?
symbol?           vector?

and all predicates created by ‘define-record-type’.

These predicates define the types boolean, bytevector, character, the empty list object, eof-object, number, pair, port, procedure, string, symbol, vector, and all record types.

Although there is a separate boolean type, any Scheme value can be used as a boolean value for the purpose of a conditional test. As explained in section Booleans, all values count as true in such a test except for #f. This report uses the word “true” to refer to any Scheme value except #f, and the word “false” to refer to #f.

3.3 External representations

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

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

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

An external representation can be written in a program to obtain the corresponding object (see ‘quote’, section see Literal expressions).

External representations can also be used for input and output. The procedure ‘read’ (section see Input) parses external representations, and the procedure ‘write’ (section see Output) generates them. Together, they provide an elegant and powerful input/output facility.

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

The syntax of external representations of various kinds of objects accompanies the description of the primitives for manipulating the objects in the appropriate sections of chapter Standard procedures.

3.4 Storage model

Variables and objects such as pairs, strings, vectors, and bytevectors implicitly denote locations or sequences of locations. A string, for example, denotes as many locations as there are characters in the string. A new value can be stored into one of these locations using the string-set! procedure, but the string continues to denote the same locations as before.

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

Every location is marked to show whether it is in use. No variable or object ever refers to a location that is not in use.

Whenever this report speaks of storage being newly allocated for a variable or object, what is meant is that an appropriate number of locations are chosen from the set of locations that are not in use, and the chosen locations are marked to indicate that they are now in use before the variable or object is made to denote them. Notwithstanding this, it is understood that the empty list cannot be newly allocated, because it is a unique object. It is also understood that empty strings, empty vectors, and empty bytevectors, which contain no locations, may or may not be newly allocated.

Every object that denotes locations is either mutable or immutable. Literal constants, the strings returned by symbol->string, and possibly the environment returned by ‘scheme-report-environment’ are immutable objects. All objects created by the other procedures listed in this report are mutable. It is an error to attempt to store a new value into a location that is denoted by an immutable object.

These locations are to be understood as conceptual, not physical. Hence, they do not necessarily correspond to memory addresses, and even if they do, the memory address might not be constant.

Rationale: In many systems it is desirable for constants (i.e. the values of literal expressions) to reside in read-only memory. Making it an error to alter constants permits this implementation strategy, while not requiring other systems to distinguish between mutable and immutable objects.

3.5 Proper tail recursion

Implementations of Scheme are required to be properly tail-recursive. Procedure calls that occur in certain syntactic contexts defined below are tail calls. A Scheme implementation is properly tail-recursive if it supports an unbounded number of active tail calls. A call is active if the called procedure might still return. Note that this includes calls that might be returned from either by the current continuation or by continuations captured earlier by ‘call-with-current-continuation’ that are later invoked. In the absence of captured continuations, calls could return at most once and the active calls would be those that had not yet returned. A formal definition of proper tail recursion can be found in [propertailrecursion].

Rationale:

Intuitively, no space is needed for an active tail call because the continuation that is used in the tail call has the same semantics as the continuation passed to the procedure containing the call. Although an improper implementation might use a new continuation in the call, a return to this new continuation would be followed immediately by a return to the continuation passed to the procedure. A properly tail-recursive implementation returns to that continuation directly.

Proper tail recursion was one of the central ideas in Steele and Sussman’s original version of Scheme. Their first Scheme interpreter implemented both functions and actors. Control flow was expressed using actors, which differed from functions in that they passed their results on to another actor instead of returning to a caller. In the terminology of this section, each actor finished with a tail call to another actor.

Steele and Sussman later observed that in their interpreter the code for dealing with actors was identical to that for functions and thus there was no need to include both in the language.

A tail call is 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. The same is true of all the bodies of ‘case-lambda’ expressions.

  (lambda <formals>
    <definition>* <expression>* <tail expression>)
  
  (case-lambda (<formals> <tail body>)*)
  
  
  

• 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 rules in the grammar given in chapter Formal syntax and semantics by replacing some occurrences of <body> with <tail body>, some occurrences of <expression> with <tail expression>, and some occurrences of <sequence> with <tail sequence>. Only those rules that contain tail contexts are shown here.

  (if <expression> <tail expression> <tail expression>)
  (if <expression> <tail expression>)
  
  (cond <cond clause>+)
  (cond <cond clause>* (else <tail sequence>))
  
  (case <expression>
    <case clause>+)
  (case <expression>
    <case clause>*
    (else <tail sequence>))
  
  (and <expression>* <tail expression>)
  (or <expression>* <tail expression>)
  
  (when <test> <tail sequence>)
  (unless <test> <tail sequence>)
  
  (let (<binding spec>*) <tail body>)
  (let <variable> (<binding spec>*) <tail body>)
  (let* (<binding spec>*) <tail body>)
  (letrec (<binding spec>*) <tail body>)
  (letrec* (<binding spec>*) <tail body>)
  (let-values (<mv binding spec>*) <tail body>)
  (let*-values (<mv binding spec>*) <tail body>)
  
  (let-syntax (<syntax spec>*) <tail body>)
  (letrec-syntax (<syntax spec>*) <tail body>)
  
  (begin <tail sequence>)
  
  (do (<iteration spec>*)
      (<test> <tail sequence>)
    <expression>*)
  
  where
  
  <cond clause> --> (<test> <tail sequence>)
  <case clause> --> ((<datum>*) <tail sequence>)
  
  <tail body> --> <definition>* <tail sequence>
  <tail sequence> --> <expression>* <tail expression>
  
  
  

• If a ‘cond’ or ‘case’ expression is in a tail context, and has a clause of the form ‘(<expression1> => <expression2>)’ then the (implied) call to the procedure that results from the evaluation of <expression2> is in a tail context. <expression2> itself is not in a tail context.

Certain procedures defined in this report are also required to perform tail calls. The first argument passed to apply and to call-with-current-continuation, and the second argument passed to call-with-values, must be called via a tail call. Similarly, eval must evaluate its first argument as if it were in tail position within the eval procedure.

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 ()
  (if (g)
      (let ((x (h)))
        x)
      (and (g) (f))))

Note: Implementations may recognize that some non-tail 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 implementation-dependent.)

4.1 Primitive expression types

• Variable references
• Literal expressions
• Procedure calls
• Procedures
• Conditionals
• Assignments
• Inclusion

4.2 Derived expression types

The constructs in this section are hygienic, as discussed in section Macros. For reference purposes, section Derived expression types gives syntax definitions that will convert most of the constructs described in this section into the primitive constructs described in the previous section.

• Conditionals
• Binding constructs
• Sequencing
• Iteration
• Delayed evaluation
• Dynamic bindings
• Exception handling
• Quasiquotation
• Case-lambda

4.3 Macros

Scheme programs can define and use new derived expression types, called macros. Program-defined expression types have the syntax

(<keyword> <datum> ...)

where <keyword> is an identifier that uniquely determines the expression type. This identifier is called the syntactic keyword, or simply keyword, of the macro. The number of the <datum>s, and their syntax, depends on the expression type.

Each instance of a macro is called a use of the macro. The set of rules that specifies how a use of a macro is transcribed into a more primitive expression is called the transformer of the macro.

The macro definition facility consists of two parts:

• A set of expressions used to establish that certain identifiers are macro keywords, associate them with macro transformers, and control the scope within which a macro is defined, and
• a pattern language for specifying macro transformers.

The syntactic keyword of a macro can shadow variable bindings, and local variable bindings can shadow syntactic bindings. Two mechanisms are provided to prevent unintended conflicts:

• If a macro transformer inserts a binding for an identifier (variable or keyword), the identifier will in effect be renamed throughout its scope to avoid conflicts with other identifiers. Note that a global variable definition may or may not introduce a binding; see section Variable definitions.
• If a macro transformer inserts a free reference to an identifier, the reference refers to the binding that was visible where the transformer was specified, regardless of any local bindings that surround the use of the macro.

In consequence, all macros defined using the pattern language are “hygienic” and “referentially transparent” and thus preserve Scheme’s lexical scoping. [Kohlbecker86], [ hygienic], [Bawden88], [macrosthatwork], [syntacticabstraction]

Implementations may provide macro facilities of other types.

• Binding constructs for syntactic keywords
• Pattern language
• Signaling errors in macro transformers

5.1 Programs

A Scheme program consists of one or more import declarations followed by a sequence of expressions and definitions. Import declarations specify the libraries on which a program or library depends; a subset of the identifiers exported by the libraries are made available to the program. Expressions are described in chapter Expressions. Definitions are either variable definitions, syntax definitions, or record-type definitions, all of which are explained in this chapter. They are valid in some, but not all, contexts where expressions are allowed, specifically at the outermost level of a <program> and at the beginning of a <body>.

At the outermost level of a program, (begin <expression or definition1> …) is equivalent to the sequence of expressions and definitions in the begin. Similarly, in a <body>, (begin <definition1> …) is equivalent to the sequence <definition1> …. Macros can expand into such ‘begin’ forms. For the formal definition, see Sequencing.

Import declarations and definitions cause bindings to be created in the global environment or modify the value of existing global bindings. The initial environment of a program is empty, so at least one import declaration is needed to introduce initial bindings.

Expressions occurring at the outermost level of a program do not create any bindings. They are executed in order when the program is invoked or loaded, and typically perform some kind of initialization.

Programs and libraries are typically stored in files, although in some implementations they can be entered interactively into a running Scheme system. Other paradigms are possible. Implementations which store libraries in files should document the mapping from the name of a library to its location in the file system.

5.2 Import declarations

An import declaration takes the following form:

(import <import-set> …)

An import declaration provides a way to import identifiers exported by a library. Each <import set> names a set of bindings from a library and possibly specifies local names for the imported bindings. It takes one of the following forms:

• <library name>
• (only <import set> <identifier> …)
• (except <import set> <identifier> …)
• (prefix <import set> <identifier>)
• (rename <import set>
• hspace*4em(<identifier1> <identifier2>) …)

In the first form, all of the identifiers in the named library’s export clauses are imported with the same names (or the exported names if exported with rename). The additional <import set> forms modify this set as follows:

• only produces a subset of the given <import set> including only the listed identifiers (after any renaming). It is an error if any of the listed identifiers are not found in the original set.
• except produces a subset of the given <import set>, excluding the listed identifiers (after any renaming). It is an error if any of the listed identifiers are not found in the original set.
• rename modifies the given <import set>, replacing each instance of <identifier1> with <identifier2>. It is an error if any of the listed <identifier1>s are not found in the original set.
• prefix automatically renames all identifiers in the given <import set>, prefixing each with the specified <identifier>.

In a program or library declaration, it is an error to import the same identifier more than once with different bindings, or to redefine or mutate an imported binding with a definition or with ‘set!’, or to refer to an identifier before it is imported. However, a REPL should permit these actions.

5.3 Variable definitions

A variable definition binds one or more identifiers and specifies an initial value for each of them. The simplest kind of variable definition takes one of the following forms:

• (define <variable> <expression>)
• (define (<variable> <formals>) <body>)

  <Formals> are either a sequence of zero or more variables, or a sequence of one or more variables followed by a space-delimited period and another variable (as in a lambda expression). This form is equivalent to

  
  (define <variable>
    (lambda (<formals>) <body>)).
  
  

• (define (<variable> . <formal>) <body>)

  <Formal> is a single variable. This form is equivalent to

  
  (define <variable>
    (lambda <formal> <body>)).
  
  

• Top level definitions
• Internal definitions
• Multiple-value definitions

(define <variable> <expression>)

(set! <variable> <expression>)

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

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

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

5.4 Syntax definitions

Syntax definitions have this form:

(define-syntax <keyword> <transformer spec>)

<Keyword> is an identifier, and the <transformer spec> is an instance of syntax-rules. Like variable definitions, syntax definitions can appear at the outermost level or nested within a body.

If the ‘define-syntax’ occurs at the outermost level, then the global syntactic environment is extended by binding the <keyword> to the specified transformer, but previous expansions of any global binding for <keyword> remain unchanged. Otherwise, it is an internal syntax definition, and is local to the <body> in which it is defined. Any use of a syntax keyword before its corresponding definition is an error. In particular, a use that precedes an inner definition will not apply an outer definition.

(let ((x 1) (y 2))
  (define-syntax swap!
    (syntax-rules ()
      ((swap! a b)
       (let ((tmp a))
         (set! a b)
         (set! b tmp)))))
  (swap! x y)
  (list x y))                          ==> (2 1)

Macros can expand into definitions in any context that permits them. However, it is an error for a definition to define an identifier whose binding has to be known in order to determine the meaning of the definition itself, or of any preceding definition that belongs to the same group of internal definitions. Similarly, it is an error for an internal definition to define an identifier whose binding has to be known in order to determine the boundary between the internal definitions and the expressions of the body it belongs to. For example, the following are errors:

(define define 3)

(begin (define begin list))

(let-syntax
    ((foo (syntax-rules ()
            ((foo (proc args ...) body ...)
             (define proc
               (lambda (args ...)
                 body ...))))))
  (let ((x 3))
    (foo (plus x y) (+ x y))
    (define foo x)
    (plus foo x)))

5.5 Record-type definitions

Record-type definitions are used to introduce new data types, called record types. Like other definitions, they can appear either at the outermost level or in a body. The values of a record type are called records and are aggregations of zero or more fields, each of which holds a single location. A predicate, a constructor, and field accessors and mutators are defined for each record type.

syntax: (define-record-type <name> ¶

hspace*4em<constructor> <pred> <field> …)

Syntax: <name> and <pred> are identifiers. The <constructor> is of the form

(<constructor name> <field name> …)

and each <field> is either of the form

(<field name> <accessor name>)

or of the form

(<field name> <accessor name> <modifier name>)

It is an error for the same identifier to occur more than once as a field name. It is also an error for the same identifier to occur more than once as an accessor or mutator name.

The ‘define-record-type’ construct is generative: each use creates a new record type that is distinct from all existing types, including Scheme’s predefined types and other record types — even record types of the same name or structure.

An instance of ‘define-record-type’ is equivalent to the following definitions:

• <name> is bound to a representation of the record type itself. This may be a run-time object or a purely syntactic representation. The representation is not utilized in this report, but it serves as a means to identify the record type for use by further language extensions.
• <constructor name> is bound to a procedure that takes as many arguments as there are <field name>s in the (<constructor name> …) subexpression and returns a new record of type <name>. Fields whose names are listed with <constructor name> have the corresponding argument as their initial value. The initial values of all other fields are unspecified. It is an error for a field name to appear in <constructor> but not as a <field name>.
• <pred> is bound to a predicate that returns #t when given a value returned by the procedure bound to <constructor name> and #f for everything else.
• Each <accessor name> is bound to a procedure that takes a record of type <name> and returns the current value of the corresponding field. It is an error to pass an accessor a value which is not a record of the appropriate type.
• Each <modifier name> is bound to a procedure that takes a record of type <name> and a value which becomes the new value of the corresponding field; an unspecified value is returned. It is an error to pass a modifier a first argument which is not a record of the appropriate type.

For instance, the following record-type definition

(define-record-type <pare>
  (kons x y)
  pare?
  (x kar set-kar!)
  (y kdr))

defines ‘kons’ to be a constructor, ‘kar’ and ‘kdr’ to be accessors, ‘set-kar!’ to be a modifier, and ‘pare?’ to be a predicate for instances of ‘<pare>’.

  (pare? (kons 1 2))                   ==> #t
  (pare? (cons 1 2))                   ==> #f
  (kar (kons 1 2))                     ==> 1
  (kdr (kons 1 2))                     ==> 2
  (let ((k (kons 1 2)))
    (set-kar! k 3)
    (kar k))                           ==> 3

5.6 Libraries

Libraries provide a way to organize Scheme programs into reusable parts with explicitly defined interfaces to the rest of the program. This section defines the notation and semantics for libraries.

• Library Syntax
• Library example

(define-library <library name>
  <library declaration> …)

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

5.7 The REPL

Implementations may provide an interactive session called a REPL (Read-Eval-Print Loop), where import declarations, expressions and definitions can be entered and evaluated one at a time. For convenience and ease of use, the global Scheme environment in a REPL must not be empty, but must start out with at least the bindings provided by the base library. 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 of ‘(scheme base)’ bindings can be found in Appendix Standard Libraries.

Implementations may provide an initial REPL environment which behaves as if all possible variables are bound to locations, most of which contain unspecified values. Top level REPL definitions in such an implementation are truly equivalent to assignments, unless the identifier is defined as a syntax keyword.

An implementation may provide a mode of operation in which the REPL reads its input from a file. Such a file is not, in general, the same as a program, because it can contain import declarations in places other than the beginning.

6.1 Equivalence predicates

A predicate is a procedure that always returns a boolean value (#t or #f). An equivalence predicate is the computational analogue of a mathematical equivalence relation; it is symmetric, reflexive, and transitive. Of the equivalence predicates described in this section, ‘eq?’ is the finest or most discriminating, ‘equal?’ is the coarsest, and ‘eqv?’ is slightly less discriminating than ‘eq?’.

procedure: eqv? obj1 obj2 ¶

The ‘eqv?’ procedure defines a useful equivalence relation on objects. Briefly, it returns #t if obj1 and obj2 are normally regarded as the same object. This relation is left slightly open to interpretation, but the following partial specification of ‘eqv?’ holds for all implementations of Scheme.

The ‘eqv?’ procedure returns #t if:

• obj1 and obj2 are both #t or both #f.
• obj1 and obj2 are both symbols and are the same symbol according to the ‘symbol=?’ procedure (section see Symbols).
• obj1 and obj2 are both exact numbers and are numerically equal (in the sense of ‘=’).
• obj1 and obj2 are both inexact numbers such that they are numerically equal (in the sense of ‘=’) and they 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, provided it does not result in a NaN value.
• obj1 and obj2 are both characters and are the same character according to the ‘char=?’ procedure (section see Characters).
• obj1 and obj2 are both the empty list.
• obj1 and obj2 are pairs, vectors, bytevectors, records, or strings that denote the same location in the store (section see Storage model).
• obj1 and obj2 are procedures whose location tags are equal (section see Procedures).

The ‘eqv?’ procedure returns #f if:

• obj1 and obj2 are of different types (section see Disjointness of types).
• one of obj1 and obj2 is #t but the other is #f.
• obj1 and obj2 are symbols but are not the same symbol according to the ‘symbol=?’ procedure (section see Symbols).
• one of obj1 and obj2 is an exact number but the other is an inexact number.
• obj1 and obj2 are both exact numbers and are numerically unequal (in the sense of ‘=’).
• obj1 and obj2 are both inexact numbers such that either they are numerically unequal (in the sense of ‘=’), or they do not 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, provided it does not result in a NaN value. As an exception, the behavior of ‘eqv?’ is unspecified when both obj1 and obj2 are NaN.
• obj1 and obj2 are characters for which the ‘char=?’ procedure returns #f.
• one of obj1 and obj2 is the empty list but the other is not.
• obj1 and obj2 are pairs, vectors, bytevectors, records, or strings that denote distinct locations.
• obj1 and obj2 are procedures that would behave differently (return different values or have different side effects) for some arguments.

(eqv? 'a 'a)                           ==>  #t
(eqv? 'a 'b)                           ==>  #f
(eqv? 2 2)                             ==>  #t
(eqv? 2 2.0)                           ==>  #f
(eqv? '() '())                         ==>  #t
(eqv? 100000000 100000000)             ==>  #t
(eqv? 0.0 +nan.0)                      ==>  #f
(eqv? (cons 1 2) (cons 1 2))           ==>  #f
(eqv? (lambda () 1)
      (lambda () 2))                   ==>  #f
(let ((p (lambda (x) x)))
  (eqv? p p))                          ==>  #t
(eqv? #f 'nil)                         ==>  #f

The following examples illustrate cases in which the above rules do not fully specify the behavior of ‘eqv?’. All that can be said about such cases is that the value returned by ‘eqv?’ must be a boolean.

(eqv? "" "")                           ==>  unspecified
(eqv? '#() '#())                       ==>  unspecified
(eqv? (lambda (x) x)
      (lambda (x) x))                  ==>  unspecified
(eqv? (lambda (x) x)
      (lambda (y) y))                  ==>  unspecified
(eqv? 1.0e0 1.0f0)                     ==>  unspecified
(eqv? +nan.0 +nan.0)                   ==>  unspecified

Note that ‘(eqv? 0.0 -0.0)’ will return #f if negative zero is distinguished, and #t if negative zero is not distinguished.

The next set of examples shows the use of ‘eqv?’ with procedures that have local state. The ‘gen-counter’ procedure must return a distinct procedure every time, since each procedure has its own internal counter. The ‘gen-loser’ procedure, however, returns operationally equivalent procedures each time, since the local state does not affect the value or side effects of the procedures. However, ‘eqv?’ may or may not detect this equivalence.

(define gen-counter
  (lambda ()
    (let ((n 0))
      (lambda () (set! n (+ n 1)) n))))
(let ((g (gen-counter)))
  (eqv? g g))                          ==>  #t
(eqv? (gen-counter) (gen-counter))
                                       ==>  #f
(define gen-loser
  (lambda ()
    (let ((n 0))
      (lambda () (set! n (+ n 1)) 27))))
(let ((g (gen-loser)))
  (eqv? g g))                          ==>  #t
(eqv? (gen-loser) (gen-loser))
                                       ==>  unspecified

(letrec ((f (lambda () (if (eqv? f g) 'both 'f)))
         (g (lambda () (if (eqv? f g) 'both 'g))))
  (eqv? f g))
                                       ==>  unspecified

(letrec ((f (lambda () (if (eqv? f g) 'f 'both)))
         (g (lambda () (if (eqv? f g) 'g 'both))))
  (eqv? f g))
                                       ==>  #f

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

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

The above definition of ‘eqv?’ allows implementations latitude in their treatment of procedures and literals: implementations may either detect or 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.

Note: If inexact numbers are represented as IEEE binary floating-point numbers, then an implementation of ‘eqv?’ that simply compares equal-sized inexact numbers for bitwise equality is correct by the above definition.

procedure: eq? obj1 obj2 ¶

The ‘eq?’ procedure is similar to ‘eqv?’ except that in some cases it is capable of discerning distinctions finer than those detectable by ‘eqv?’. It must always return #f when ‘eqv?’ also would, but may return #f in some cases where ‘eqv?’ would return #t.

On symbols, booleans, the empty list, pairs, and records, and also on non-empty strings, vectors, and bytevectors, ‘eq?’ and ‘eqv?’ are guaranteed to have the same behavior. On procedures, ‘eq?’ must return true if the arguments’ location tags are equal. On numbers and characters, ‘eq?’’s behavior is implementation-dependent, but it will always return either true or false. On empty strings, empty vectors, and empty bytevectors, ‘eq?’ may also behave differently from ‘eqv?’.

(eq? 'a 'a)                            ==>  #t
(eq? '(a) '(a))                        ==>  unspecified
(eq? (list 'a) (list 'a))              ==>  #f
(eq? "a" "a")                          ==>  unspecified
(eq? "" "")                            ==>  unspecified
(eq? '() '())                          ==>  #t
(eq? 2 2)                              ==>  unspecified
(eq? #\A #\A)                          ==>  unspecified
(eq? car car)                          ==>  #t
(let ((n (+ 2 3)))
  (eq? n n))                           ==>  unspecified
(let ((x '(a)))
  (eq? x x))                           ==>  #t
(let ((x '#()))
  (eq? x x))                           ==>  #t
(let ((p (lambda (x) x)))
  (eq? p p))                           ==>  #t

Rationale: It will usually be possible to implement ‘eq?’ much more efficiently than ‘eqv?’, for example, as a simple pointer comparison instead of as some more complicated operation. One reason is that it is not always possible to compute ‘eqv?’ of two numbers in constant time, whereas ‘eq?’ implemented as pointer comparison will always finish in constant time.

procedure: equal? obj1 obj2 ¶

The ‘equal?’ procedure, when applied to pairs, vectors, strings and bytevectors, recursively compares them, returning #t when the unfoldings of its arguments into (possibly infinite) trees are equal (in the sense of ‘equal?’) as ordered trees, and #f otherwise. It returns the same as ‘eqv?’ when applied to booleans, symbols, numbers, characters, ports, procedures, and the empty list. If two objects are ‘eqv?’, they must be ‘equal?’ as well. In all other cases, ‘equal?’ may return either #t or #f.

Even if its arguments are circular data structures, ‘equal?’ must always terminate.

(equal? 'a 'a)                         ==>  #t
(equal? '(a) '(a))                     ==>  #t
(equal? '(a (b) c)
        '(a (b) c))                    ==>  #t
(equal? "abc" "abc")                   ==>  #t
(equal? 2 2)                           ==>  #t
(equal? (make-vector 5 'a)
        (make-vector 5 'a))            ==>  #t
(equal? '#1=(a b . #1#)
        '#2=(a b a b . #2#))           ==>  #t
(equal? (lambda (x) x)
        (lambda (y) y))                ==>  unspecified

Note: A rule of thumb is that objects are generally ‘equal?’ if they print the same.

6.2 Numbers

It is important to distinguish between mathematical numbers, the Scheme numbers that attempt to model them, the machine representations used to implement the Scheme numbers, and notations used to write numbers. This report uses the types number, complex, real, rational, and integer to refer to both mathematical numbers and Scheme numbers.

• Numerical types
• Exactness
• Implementation restrictions
• Implementation extensions
• Syntax of numerical constants
• Numerical operations
• Numerical input and output

         number 
          complex number 
          real number 
          rational number 
          integer 

-                     *
+                     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

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

6.3 Booleans

The standard boolean objects for true and false are written as #t and #f. Alternatively, they can be written #true and #false, respectively. What really matters, though, are the objects that the Scheme conditional expressions (‘if’, ‘cond’, ‘and’, ‘or’, ‘when’, ‘unless’, ‘do’) treat as true or false. The phrase “a true value” (or sometimes just “true”) means any object treated as true by the conditional expressions, and the phrase “a false value” (or “false”) means any object treated as false by the conditional expressions.

Of all the Scheme values, only #f counts as false in conditional expressions. All other Scheme values, including #t, count as true.

Note: Unlike some other dialects of Lisp, Scheme distinguishes #f and the empty list from each other and from the symbol nil.

Boolean constants evaluate to themselves, so they do not need to be quoted in programs.

#t                                     ==>  #t
#f                                     ==>  #f
'#f                                    ==>  #f

procedure: not obj ¶

The ‘not’ procedure returns #t if obj is false, and returns #f otherwise.

(not #t)                               ==>  #f
(not 3)                                ==>  #f
(not (list 3))                         ==>  #f
(not #f)                               ==>  #t
(not '())                              ==>  #f
(not (list))                           ==>  #f
(not 'nil)                             ==>  #f

procedure: boolean? obj ¶

The ‘boolean?’ predicate returns #t if obj is either #t or #f and returns #f otherwise.

(boolean? #f)                          ==>  #t
(boolean? 0)                           ==>  #f
(boolean? '())                         ==>  #f

procedure: boolean=? boolean1 boolean2 boolean3 … ¶

Returns #t if all the arguments are #t or all are #f.

6.4 Pairs and lists

A pair (sometimes called a dotted pair) is a record structure with two fields called the car and cdr fields (for historical reasons). Pairs are created by the procedure ‘cons’. The car and cdr fields are accessed by the procedures ‘car’ and ‘cdr’. The car and cdr fields are assigned by the procedures ‘set-car!’ and ‘set-cdr!’.

Pairs are used primarily to represent lists. A list can be defined recursively as either the empty list or a pair whose cdr is a list. More precisely, the set of lists is defined as the smallest set X such that

• The empty list is in X.
• If list is in X, then any pair whose cdr field contains list is also in X.

The objects in the car fields of successive pairs of a list are the elements of the list. For example, a two-element list is a pair whose car is the first element and whose cdr is a pair whose car is the second element and whose cdr is the empty list. The length of a list is the number of elements, which is the same as the number of pairs.

The empty list is a special object of its own type. It is not a pair, it has no elements, and its length is zero.

Note: The above definitions imply that all lists have finite length and are terminated by the empty list.

The most general notation (external representation) for Scheme pairs is the “dotted” notation ‘(c1 . c2)’ where c1 is the value of the car field and c2 is the value of the cdr field. For example ‘(4 . 5)’ is a pair whose car is 4 and whose cdr is 5. Note that ‘(4 . 5)’ is the external representation of a pair, not an expression that evaluates to a pair.

A more streamlined notation can be used for lists: the elements of the list are simply enclosed in parentheses and separated by spaces. The empty list is written (). For example,

(a b c d e)

and

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

are equivalent notations for a list of symbols.

A chain of pairs not ending in the empty list is called an improper list. Note that an improper list is not a list. The list and dotted notations can be combined to represent improper lists:

(a b c . d)

is equivalent to

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

Whether a given pair is a list depends upon what is stored in the cdr field. When the set-cdr! procedure is used, an object can be a list one moment and not the next:

(define x (list 'a 'b 'c))
(define y x)
y                                      ==>  (a b c)
(list? y)                              ==>  #t
(set-cdr! x 4)                         ==>  unspecified
x                                      ==>  (a . 4)
(eqv? x y)                             ==>  #t
y                                      ==>  (a . 4)
(list? y)                              ==>  #f
(set-cdr! x x)                         ==>  unspecified
(list? x)                              ==>  #f

Within literal expressions and representations of objects read by the read procedure, the forms '<datum>, `<datum>, ,<datum>, and ,@<datum> denote two-element lists whose first elements are the symbols quote, quasiquote, unquote, and unquote-splicing, respectively. The second element in each case is <datum>. This convention is supported so that arbitrary Scheme programs can be represented as lists. That is, according to Scheme’s grammar, every <expression> is also a <datum> (see section see External representations). Among other things, this permits the use of the ‘read’ procedure to parse Scheme programs. See section External representations.

procedure: pair? obj ¶

The ‘pair?’ predicate returns #t if obj is a pair, and otherwise returns #f.

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

procedure: cons obj1 obj2 ¶

Returns a newly allocated pair whose car is obj1 and whose cdr is obj2. The pair is guaranteed to be different (in the sense of ‘eqv?’) from every existing object.

(cons 'a '())                          ==>  (a)
(cons '(a) '(b c d))                   ==>  ((a) b c d)
(cons "a" '(b c))                      ==>  ("a" b c)
(cons 'a 3)                            ==>  (a . 3)
(cons '(a b) 'c)                       ==>  ((a b) . c)

procedure: car pair ¶

Returns the contents of the car field of pair. Note that it is an error to take the car of the empty list.

(car '(a b c))                         ==>  a
(car '((a) b c d))                     ==>  (a)
(car '(1 . 2))                         ==>  1
(car '())                              ==>  error

procedure: cdr pair ¶

Returns the contents of the cdr field of pair. Note that it is an error to take the cdr of the empty list.

(cdr '((a) b c d))                     ==>  (b c d)
(cdr '(1 . 2))                         ==>  2
(cdr '())                              ==>  error

procedure: set-car! pair obj ¶

Stores obj in the car field of pair.

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

procedure: set-cdr! pair obj ¶

Stores obj in the cdr field of pair.

procedure: caar pair ¶

procedure: cadr pair ¶

procedure: cdar pair ¶

procedure: cddr pair ¶

These procedures are compositions of ‘car’ and ‘cdr’ as follows:

(define (caar x) (car (car x)))
(define (cadr x) (car (cdr x)))
(define (cdar x) (cdr (car x)))
(define (cddr x) (cdr (cdr x)))

cxr library procedure: caaar pair ¶

cxr library procedure: caadr pair ¶

         …:          … ¶

cxr library procedure: cdddar pair ¶

cxr library procedure: cddddr pair ¶

These twenty-four procedures are further compositions of ‘car’ and ‘cdr’ on the same principles. For example, ‘caddr’ could be defined by

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

Arbitrary compositions up to four deep are provided.

procedure: null? obj ¶

Returns #t if obj is the empty list, otherwise returns #f.

procedure: list? obj ¶

Returns #t if obj is a list. Otherwise, it returns #f. By definition, all lists have finite length and are terminated by the empty list.

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

procedure: make-list k ¶

procedure: make-list k fill ¶

Returns a newly allocated list 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.

(make-list 2 3)                        ==>   (3 3)

procedure: list obj … ¶

Returns a newly allocated list of its arguments.

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

procedure: length list ¶

Returns the length of list.

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

procedure: append list … ¶

The last argument, if there is one, can be of any type. Returns a list consisting of the elements of the first list followed by the elements of the other lists. If there are no arguments, the empty list is returned. If there is exactly one argument, it is returned. Otherwise the resulting list is always newly allocated, except that it shares structure with the last argument. An improper list results if the last argument is not a proper list.

(append '(x) '(y))                     ==>  (x y)
(append '(a) '(b c d))                 ==>  (a b c d)
(append '(a (b)) '((c)))               ==>  (a (b) (c))

(append '(a b) '(c . d))               ==>  (a b c . d)
(append '() 'a)                        ==>  a

procedure: reverse list ¶

Returns a newly allocated list consisting of the elements of list in reverse order.

(reverse '(a b c))                     ==>  (c b a)
(reverse '(a (b c) d (e (f))))  
          ==>  ((e (f)) d (b c) a)

procedure: list-tail list k ¶

It is an error if list has fewer than k elements. Returns the sublist of list obtained by omitting the first k elements. The ‘list-tail’ procedure could be defined by

(define list-tail
  (lambda (x k)
    (if (zero? k)
        x
        (list-tail (cdr x) (- k 1)))))

procedure: list-ref list k ¶

The list argument can be circular, but it is an error if list has k or fewer elements. Returns the kth element of list. (This is the same as the car of (list-tail list k).)

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

procedure: list-set! list k obj ¶

It is an error if k is not a valid index of list. The ‘list-set!’ procedure stores obj in element k of list.

(let ((ls (list 'one 'two 'five!)))
  (list-set! ls 2 'three)
  ls)      
          ==>  (one two three)

(list-set! '(0 1 2) 1 "oops")  
          ==>  error  ; constant list

procedure: memq obj list ¶

procedure: memv obj list ¶

procedure: member obj list ¶

procedure: member obj list compare ¶

These procedures return the first sublist of list whose car is obj, where the sublists of list are the non-empty lists returned by (list-tail list k) for k less than the length of list. If obj does not occur in list, then #f (not the empty list) is returned. The ‘memq’ procedure uses ‘eq?’ to compare obj with the elements of list, while ‘memv’ uses ‘eqv?’ and ‘member’ uses compare, if given, and ‘equal?’ otherwise.

(memq 'a '(a b c))                     ==>  (a b c)
(memq 'b '(a b c))                     ==>  (b c)
(memq 'a '(b c d))                     ==>  #f
(memq (list 'a) '(b (a) c))            ==>  #f
(member (list 'a)
        '(b (a) c))                    ==>  ((a) c)
(member "B"
        '("a" "b" "c")
        string-ci=?)                   ==>  ("b" "c")
(memq 101 '(100 101 102))              ==>  unspecified
(memv 101 '(100 101 102))              ==>  (101 102)

procedure: assq obj alist ¶

procedure: assv obj alist ¶

procedure: assoc obj alist ¶

procedure: assoc obj alist compare ¶

It is an error if alist (for “association list”) is not a list of pairs. These procedures find the first pair in alist whose car field is obj, and returns that pair. If no pair in alist has obj as its car, then #f (not the empty list) is returned. The ‘assq’ procedure uses ‘eq?’ to compare obj with the car fields of the pairs in alist, while ‘assv’ uses ‘eqv?’ and ‘assoc’ uses compare if given and ‘equal?’ otherwise.

(define e '((a 1) (b 2) (c 3)))
(assq 'a e)                            ==>  (a 1)
(assq 'b e)                            ==>  (b 2)
(assq 'd e)                            ==>  #f
(assq (list 'a) '(((a)) ((b)) ((c))))
                                       ==>  #f
(assoc (list 'a) '(((a)) ((b)) ((c))))   
                                       ==>  ((a))
(assoc 2.0 '((1 1) (2 4) (3 9)) =)
                                       ==> (2 4)
(assq 5 '((2 3) (5 7) (11 13)))    
                                       ==>  unspecified
(assv 5 '((2 3) (5 7) (11 13)))    
                                       ==>  (5 7)

Rationale: Although they are often used as predicates, ‘memq’, ‘memv’, ‘member’, ‘assq’, ‘assv’, and ‘assoc’ do not have question marks in their names because they return potentially useful values rather than just #t or #f.

procedure: list-copy obj ¶

Returns a newly allocated copy of the given obj if it is a list. Only the pairs themselves are copied; the cars of the result are the same (in the sense of ‘eqv?’) as the cars of list. If obj is an improper list, so is the result, and the final cdrs are the same in the sense of ‘eqv?’. An obj which is not a list is returned unchanged. It is an error if obj is a circular list.

(define a '(1 8 2 8)) ; a may be immutable
(define b (list-copy a))
(set-car! b 3)        ; b is mutable
b                                      ==> (3 8 2 8)
a                                      ==> (1 8 2 8)

6.5 Symbols

Symbols are objects whose usefulness rests on the fact that two symbols are identical (in the sense of ‘eqv?’) if and only if their names are spelled the same way. For instance, they can be used the way enumerated values are used in other languages.

The rules for writing a symbol are exactly the same as the rules for writing an identifier; see sections Identifiers and Lexical structure.

It is guaranteed that any symbol that has been returned as part of a literal expression, or read using the ‘read’ procedure, and subsequently written out using the ‘write’ procedure, will read back in as the identical symbol (in the sense of ‘eqv?’).

Note: Some implementations have values known as “uninterned symbols,” which defeat write/read invariance, and also violate the rule that two symbols are the same if and only if their names are spelled the same. This report does not specify the behavior of implementation-dependent extensions.

procedure: symbol? obj ¶

Returns #t if obj is a symbol, otherwise returns #f.

(symbol? 'foo)                         ==>  #t
(symbol? (car '(a b)))                 ==>  #t
(symbol? "bar")                        ==>  #f
(symbol? 'nil)                         ==>  #t
(symbol? '())                          ==>  #f
(symbol? #f)                           ==>  #f

procedure: symbol=? symbol1 symbol2 symbol3 … ¶

Returns #t if all the arguments all have the same names in the sense of ‘string=?’.

Note: The definition above assumes that none of the arguments are uninterned symbols.

procedure: symbol->string symbol ¶

Returns the name of symbol as a string, but without adding escapes. It is an error to apply mutation procedures like string-set! to strings returned by this procedure.

(symbol->string 'flying-fish)     
                                       ==>  "flying-fish"
(symbol->string 'Martin)               ==>  "Martin"
(symbol->string
   (string->symbol "Malvina"))     
                                       ==>  "Malvina"

procedure: string->symbol string ¶

Returns the symbol whose name is string. This procedure can create symbols with names containing special characters that would require escaping when written, but does not interpret escapes in its input.

(string->symbol "mISSISSIppi")  
          ==>
  mISSISSIppi
(eqv? 'bitBlt (string->symbol "bitBlt"))     
          ==>  #t
(eqv? 'LollyPop
     (string->symbol
       (symbol->string 'LollyPop)))  
          ==>  #t
(string=? "K. Harper, M.D."
          (symbol->string
            (string->symbol "K. Harper, M.D.")))  
          ==>  #t

6.6 Characters

Characters are objects that represent printed characters such as letters and digits. All Scheme implementations must support at least the ASCII character repertoire: that is, Unicode characters U+0000 through U+007F. Implementations may support any other Unicode characters they see fit, and may also support non-Unicode characters as well. Except as otherwise specified, the result of applying any of the following procedures to a non-Unicode character is implementation-dependent.

Characters are written using the notation #\<character> or #\<character name> or #\x<hex scalar value>.

The following character names must be supported by all implementations with the given values. Implementations may add other names provided they cannot be interpreted as hex scalar values preceded by ‘x’.

#\alarm

; U+0007

#\backspace

; U+0008

#\delete

; U+007F

#\escape

; U+001B

#\newline

; the linefeed character, U+000A

#\null

; the null character, U+0000

#\return

; the return character, U+000D

#\space

; the preferred way to write a space

#\tab

; the tab character, U+0009

Here are some additional examples:

#\a

; lower case letter

#\A

; upper case letter

#\(

; left parenthesis

#\

; the space character

#\x03BB

; lambda (if character is supported)

#\iota

; iota (if character and name are supported)

Case is significant in #\<character>, and in #\<character name>, but not in ‘#\x’<hex scalar value>. If <character> in #\<character> is alphabetic, then any character immediately following <character> cannot be one that can appear in an identifier. This rule resolves the ambiguous case where, for example, the sequence of characters “#\ space” could be taken to be either a representation of the space character or a representation of the character “#\ s” followed by a representation of the symbol “pace.”

Characters written in the #\ notation are self-evaluating. That is, they do not have to be quoted in programs.

Some of the procedures that operate on characters ignore the difference between upper case and lower case. The procedures that ignore case have “-ci” (for “case insensitive”) embedded in their names.

procedure: char? obj ¶

Returns #t if obj is a character, otherwise returns #f.

procedure: char=? char1 char2 char3 … ¶

procedure: char<? char1 char2 char3 … ¶

procedure: char>? char1 char2 char3 … ¶

procedure: char<=? char1 char2 char3 … ¶

procedure: char>=? char1 char2 char3 … ¶

These procedures return #t if the results of passing their arguments to ‘char->integer’ are respectively equal, monotonically increasing, monotonically decreasing, monotonically non-decreasing, or monotonically non-increasing.

These predicates are required to be transitive.

char library procedure: char-ci=? char1 char2 char3 … ¶

char library procedure: char-ci<? char1 char2 char3 … ¶

char library procedure: char-ci>? char1 char2 char3 … ¶

char library procedure: char-ci<=? char1 char2 char3 … ¶

char library procedure: char-ci>=? char1 char2 char3 … ¶

These procedures are similar to ‘char=?’ et cetera, but they treat upper case and lower case letters as the same. For example, ‘(char-ci=? #\A #\a)’ returns #t.

Specifically, these procedures behave as if ‘char-foldcase’ were applied to their arguments before they were compared.

char library procedure: char-alphabetic? char ¶

char library procedure: char-numeric? char ¶

char library procedure: char-whitespace? char ¶

char library procedure: char-upper-case? letter ¶

char library procedure: char-lower-case? letter ¶

These procedures return #t if their arguments are alphabetic, numeric, whitespace, upper case, or lower case characters, respectively, otherwise they return #f.

Specifically, they must return #t when applied to characters with the Unicode properties Alphabetic, Numeric Type=Decimal, White Space, Uppercase, and Lowercase respectively, and #f when applied to any other Unicode characters. Note that many Unicode characters are alphabetic but neither upper nor lower case.

char library procedure: digit-value char ¶

This procedure returns the numeric value (0 to 9) of its argument if it is a numeric digit (that is, if ‘char-numeric?’ returns #t), or #f on any other character.

(digit-value #\3)                      ==> 3
(digit-value #\x0664)                  ==> 4
(digit-value #\x0AE6)                  ==> 0
(digit-value #\x0EA6)                  ==> #f

procedure: char->integer char ¶

procedure: integer->char n ¶

Given a Unicode character, ‘char->integer’ returns an exact integer between 0 and #xD7FF or between #xE000 and #x10FFFF which is equal to the Unicode scalar value of that character. Given a non-Unicode character, it returns an exact integer greater than #x10FFFF. This is true independent of whether the implementation uses the Unicode representation internally.

Given an exact integer that is the value returned by a character when ‘char->integer’ is applied to it, ‘integer->char’ returns that character.

char library procedure: char-upcase char ¶

char library procedure: char-downcase char ¶

char library procedure: char-foldcase char ¶

The ‘char-upcase’ procedure, given an argument that is the lowercase part of a Unicode casing pair, returns the uppercase member of the pair, provided that both characters are supported by the Scheme implementation. Note that language-sensitive casing pairs are not used. If the argument is not the lowercase member of such a pair, it is returned.

The ‘char-downcase’ procedure, given an argument that is the uppercase part of a Unicode casing pair, returns the lowercase member of the pair, provided that both characters are supported by the Scheme implementation. Note that language-sensitive casing pairs are not used. If the argument is not the uppercase member of such a pair, it is returned.

The ‘char-foldcase’ procedure applies the Unicode simple case-folding algorithm to its argument and returns the result. Note that language-sensitive folding is not used. If the character that results from folding is not supported by the implementation, the argument is returned. See UAX #44 [uax44] (part of the Unicode Standard) for details.

Note that many Unicode lowercase characters do not have uppercase equivalents.

6.7 Strings

Strings are sequences of characters. Strings are written as sequences of characters enclosed within quotation marks (‘"’). Within a string literal, various escape sequences represent characters other than themselves. Escape sequences always start with a backslash (\):

• ‘\a’ : alarm, U+0007
• ‘\b’ : backspace, U+0008
• ‘\t’ : character tabulation, U+0009
• ‘\n’ : linefeed, U+000A
• ‘\r’ : return, U+000D
• ‘\’" : double quote, U+0022
• ‘\\’ : backslash, U+005C
• ‘\|’ : vertical line, U+007C
• ‘\<intraline whitespace>*<line ending> <intraline whitespace>*’ : nothing
• ‘\x<hex scalar value>;’ : specified character (note the terminating semi-colon).

The result is unspecified if any other character in a string occurs after a backslash.

Except for a line ending, any character outside of an escape sequence stands for itself in the string literal. A line ending which is preceded by ‘\<intraline whitespace>’ expands to nothing (along with any trailing intraline whitespace), and can be used to indent strings for improved legibility. Any other line ending has the same effect as inserting a ‘\n’ character into the string.

Examples:

"The word \"recursion\" has many meanings."
"Another example:\ntwo lines of text"
"Here's text \ 
   containing just one line"
"\x03B1; is named GREEK SMALL LETTER ALPHA."

The length of a string is the number of characters that it contains. This number is an exact, non-negative integer that is fixed when the string is created. The valid indexes of a string are the exact non-negative integers less than the length of the string. The first character of a string has index 0, the second has index 1, and so on.

Some of the procedures that operate on strings ignore the difference between upper and lower case. The names of the versions that ignore case end with “‘-ci’” (for “case insensitive”).

Implementations may forbid certain characters from appearing in strings. However, with the exception of #\null, ASCII characters must not be forbidden. For example, an implementation might support the entire Unicode repertoire, but only allow characters U+0001 to U+00FF (the Latin-1 repertoire without #\null) in strings.

It is an error to pass such a forbidden character to ‘make-string’, ‘string’, ‘string-set!’, or ‘string-fill!’, as part of the list passed to ‘list->string’, or as part of the vector passed to ‘vector->string’ (see section see Vectors), or in UTF-8 encoded form within a bytevector passed to ‘utf8->string’ (see section see Bytevectors). It is also an error for a procedure passed to ‘string-map’ (see section see Control features) to return a forbidden character, or for ‘read-string’ (see section see Input) to attempt to read one.

procedure: string? obj ¶

Returns #t if obj is a string, otherwise returns #f.

procedure: make-string k ¶

procedure: make-string k char ¶

The ‘make-string’ procedure returns a newly allocated string of length k. If char is given, then all the characters of the string are initialized to char, otherwise the contents of the string are unspecified.

procedure: string char … ¶

Returns a newly allocated string composed of the arguments. It is analogous to ‘list’.

procedure: string-length string ¶

Returns the number of characters in the given string.

procedure: string-ref string k ¶

It is an error if k is not a valid index of string. The ‘string-ref’ procedure returns character k of string using zero-origin indexing.

There is no requirement for this procedure to execute in constant time.

procedure: string-set! string k char ¶

It is an error if k is not a valid index of string. The ‘string-set!’ procedure stores char in element k of string. There is no requirement for this procedure to execute in constant time.

(define (f) (make-string 3 #\*))
(define (g) "***")
(string-set! (f) 0 #\?)                ==>  unspecified
(string-set! (g) 0 #\?)                ==>  error
(string-set! (symbol->string 'immutable)
             0
             #\?)                      ==>  error

procedure: string=? string1 string2 string3 … ¶

Returns #t if all the strings are the same length and contain exactly the same characters in the same positions, otherwise returns #f.

char library procedure: string-ci=? string1 string2 string3 … ¶

Returns #t if, after case-folding, all the strings are the same length and contain the same characters in the same positions, otherwise returns #f. Specifically, these procedures behave as if ‘string-foldcase’ were applied to their arguments before comparing them.

procedure: string<? string1 string2 string3 … ¶

char library procedure: string-ci<? string1 string2 string3 … ¶

procedure: string>? string1 string2 string3 … ¶

char library procedure: string-ci>? string1 string2 string3 … ¶

procedure: string<=? string1 string2 string3 … ¶

char library procedure: string-ci<=? string1 string2 string3 … ¶

procedure: string>=? string1 string2 string3 … ¶

char library procedure: string-ci>=? string1 string2 string3 … ¶

These procedures return #t if their arguments are (respectively): monotonically increasing, monotonically decreasing, monotonically non-decreasing, or monotonically non-increasing.

These predicates are required to be transitive.

These procedures compare strings in an implementation-defined way. One approach is to make them the lexicographic extensions to strings of the corresponding orderings on characters. In that case, ‘string<?’ would be the lexicographic ordering on strings induced by the ordering ‘char<?’ on characters, and if the two strings differ in length but are the same up to the length of the shorter string, the shorter string would be considered to be lexicographically less than the longer string. However, it is also permitted to use the natural ordering imposed by the implementation’s internal representation of strings, or a more complex locale-specific ordering.

In all cases, a pair of strings must satisfy exactly one of ‘string<?’, ‘string=?’, and ‘string>?’, and must satisfy ‘string<=?’ if and only if they do not satisfy ‘string>?’ and ‘string>=?’ if and only if they do not satisfy ‘string<?’.

The “-ci” procedures behave as if they applied ‘string-foldcase’ to their arguments before invoking the corresponding procedures without “-ci”.

char library procedure: string-upcase string ¶

char library procedure: string-downcase string ¶

char library procedure: string-foldcase string ¶

These procedures apply the Unicode full string uppercasing, lowercasing, and case-folding algorithms to their arguments and return the result. In certain cases, the result differs in length from the argument. If the result is equal to the argument in the sense of ‘string=?’, the argument may be returned. Note that language-sensitive mappings and foldings are not used.

The Unicode Standard prescribes special treatment of the Greek letter Sigma, whose normal lower-case form is sigma but which becomes varsigma at the end of a word. See UAX #44 [uax44] (part of the Unicode Standard) for details. However, implementations of ‘string-downcase’ are not required to provide this behavior, and may choose to change Sigma to sigma in all cases.

procedure: substring string start end ¶

The ‘substring’ procedure returns a newly allocated string formed from the characters of string beginning with index start and ending with index end. This is equivalent to calling ‘string-copy’ with the same arguments, but is provided for backward compatibility and stylistic flexibility.

procedure: string-append string … ¶

Returns a newly allocated string whose characters are the concatenation of the characters in the given strings.

procedure: string->list string ¶

procedure: string->list string start ¶

procedure: string->list string start end ¶

procedure: list->string list ¶

It is an error if any element of list is not a character. The ‘string->list’ procedure returns a newly allocated list of the characters of string between start and end. ‘list->string’ returns a newly allocated string formed from the elements in the list list. In both procedures, order is preserved. ‘string->list’ and ‘list->string’ are inverses so far as ‘equal?’ is concerned.

procedure: string-copy string ¶

procedure: string-copy string start ¶

procedure: string-copy string start end ¶

Returns a newly allocated copy of the part of the given string between start and end.

procedure: string-copy! to at from ¶

procedure: string-copy! to at from start ¶

procedure: string-copy! to at from start end ¶

It is an error if at is less than zero or greater than the length of to. It is also an error if ‘(- (string-length to) at)’ is less than ‘(- end start)’. Copies the characters of string from between start and end to string to, starting at at. The order in which characters are copied is unspecified, except that if the source and destination overlap, copying takes place as if the source is first copied into a temporary string and then into the destination. This can be achieved without allocating storage by making sure to copy in the correct direction in such circumstances.

(define a "12345")
(define b (string-copy "abcde"))
(string-copy! b 1 a 0 2)
b                                      ==> "a12de"

procedure: string-fill! string fill ¶

procedure: string-fill! string fill start ¶

procedure: string-fill! string fill start end ¶

It is an error if fill is not a character.

The ‘string-fill!’ procedure stores fill in the elements of string between start and end.

6.8 Vectors

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 needed to access a randomly chosen element is typically less for the vector than for the list.

The length of a vector is the number of elements that it contains. This number is a non-negative integer that is fixed when the vector is created. The valid indexes of a vector are the exact non-negative integers less than the length of the vector. The first element in a vector is indexed by zero, and the last element is indexed by one less than the length of the vector.

Vectors are written using the notation #(obj …). For example, a vector of length 3 containing the number zero in element 0, the list ‘(2 2 2 2)’ in element 1, and the string ‘"Anna"’ in element 2 can be written as follows:

#(0 (2 2 2 2) "Anna")

Vector constants are self-evaluating, so they do not need to be quoted in programs.

procedure: vector? obj ¶

Returns #t if obj is a vector; otherwise returns #f.

procedure: make-vector k ¶

procedure: make-vector k fill ¶

Returns a newly allocated vector of k elements. If a second argument is given, then each element is initialized to fill. Otherwise the initial contents of each element is unspecified.

procedure: vector obj … ¶

Returns a newly allocated vector whose elements contain the given arguments. It is analogous to ‘list’.

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

procedure: vector-length vector ¶

Returns the number of elements in vector as an exact integer.

procedure: vector-ref vector k ¶

It is an error if k is not a valid index of vector. The ‘vector-ref’ procedure returns the contents of element k of vector.

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

procedure: vector-set! vector k obj ¶

It is an error if k is not a valid index of vector. The ‘vector-set!’ procedure stores obj in element k of vector.

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

(vector-set! '#(0 1 2) 1 "doe")  
          ==>  error  ; constant vector

procedure: vector->list vector ¶

procedure: vector->list vector start ¶

procedure: vector->list vector start end ¶

procedure: list->vector list ¶

The ‘vector->list’ procedure returns a newly allocated list of the objects contained in the elements of vector between start and end. The ‘list->vector’ procedure returns a newly created vector initialized to the elements of the list list.

In both procedures, order is preserved.

(vector->list '#(dah dah didah))  
          ==>  (dah dah didah)
(vector->list '#(dah dah didah) 1 2) 
          ==> (dah)
(list->vector '(dididit dah))   
          ==>  #(dididit dah)

procedure: vector->string vector ¶

procedure: vector->string vector start ¶

procedure: vector->string vector start end ¶

procedure: string->vector string ¶

procedure: string->vector string start ¶

procedure: string->vector string start end ¶

It is an error if any element of vector between start and end is not a character. The ‘vector->string’ procedure returns a newly allocated string of the objects contained in the elements of vector between start and end. The ‘string->vector’ procedure returns a newly created vector initialized to the elements of the string string between start and end.

In both procedures, order is preserved.

(string->vector "ABC")                 ==>   #(#\A #\B #\C)
(vector->string
  #(#\1 #\2 #\3) 
)
                      ==> "123"

procedure: vector-copy vector ¶

procedure: vector-copy vector start ¶

procedure: vector-copy vector start end ¶

Returns a newly allocated copy of the elements of the given vector between start and end. The elements of the new vector are the same (in the sense of ‘eqv?’) as the elements of the old.

(define a #(1 8 2 8)) ; a may be immutable
(define b (vector-copy a))
(vector-set! b 0 3)   ; b is mutable
b                                      ==> #(3 8 2 8)
(define c (vector-copy b 1 3))
c                                      ==> #(8 2)

procedure: vector-copy! to at from ¶

procedure: vector-copy! to at from start ¶

procedure: vector-copy! to at from start end ¶

It is an error if at is less than zero or greater than the length of to. It is also an error if ‘(- (vector-length to) at)’ is less than ‘(- end start)’. Copies the elements of vector from between start and end to vector to, starting at at. The order in which elements are copied is unspecified, except that if the source and destination overlap, copying takes place as if the source is first copied into a temporary vector and then into the destination. This can be achieved without allocating storage by making sure to copy in the correct direction in such circumstances.

(define a (vector 1 2 3 4 5))
(define b (vector 10 20 30 40 50))
(vector-copy! b 1 a 0 2)
b                                      ==> #(10 1 2 40 50)

procedure: vector-append vector … ¶

Returns a newly allocated vector whose elements are the concatenation of the elements of the given vectors.

(vector-append #(a b c) #(d e f)) 
          ==> #(a b c d e f)

procedure: vector-fill! vector fill ¶

procedure: vector-fill! vector fill start ¶

procedure: vector-fill! vector fill start end ¶

The ‘vector-fill!’ procedure stores fill in the elements of vector between start and end.

(define a (vector 1 2 3 4 5))
(vector-fill! a 'smash 2 4)
a 
          ==> #(1 2 smash smash 5)

6.9 Bytevectors

Bytevectors represent blocks of binary data. They are fixed-length sequences of bytes, where a byte is an exact integer in the range from 0 to 255 inclusive. A bytevector is typically more space-efficient than a vector containing the same values.

The length of a bytevector is the number of elements that it contains. This number is a non-negative integer that is fixed when the bytevector is created. The valid indexes of a bytevector are the exact non-negative integers less than the length of the bytevector, starting at index zero as with vectors.

Bytevectors are written using the notation #u8(byte …). For example, a bytevector of length 3 containing the byte 0 in element 0, the byte 10 in element 1, and the byte 5 in element 2 can be written as follows:

#u8(0 10 5)

Bytevector constants are self-evaluating, so they do not need to be quoted in programs.

procedure: bytevector? obj ¶

Returns #t if obj is a bytevector. Otherwise, #f is returned.

procedure: make-bytevector k ¶

procedure: make-bytevector k byte ¶

The ‘make-bytevector’ procedure returns a newly allocated bytevector of length k. If byte is given, then all elements of the bytevector are initialized to byte, otherwise the contents of each element are unspecified.

(make-bytevector 2 12)                 ==> #u8(12 12)

procedure: bytevector byte … ¶

Returns a newly allocated bytevector containing its arguments.

(bytevector 1 3 5 1 3 5)               ==>  #u8(1 3 5 1 3 5)
(bytevector)                           ==>  #u8()

procedure: bytevector-length bytevector ¶

Returns the length of bytevector in bytes as an exact integer.

procedure: bytevector-u8-ref bytevector k ¶

It is an error if k is not a valid index of bytevector. Returns the kth byte of bytevector.

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

procedure: bytevector-u8-set! bytevector k byte ¶

It is an error if k is not a valid index of bytevector. Stores byte as the kth byte of bytevector.

(let ((bv (bytevector 1 2 3 4)))
  (bytevector-u8-set! bv 1 3)
  bv) 
          ==> #u8(1 3 3 4)

procedure: bytevector-copy bytevector ¶

procedure: bytevector-copy bytevector start ¶

procedure: bytevector-copy bytevector start end ¶

Returns a newly allocated bytevector containing the bytes in bytevector between start and end.

(define a #u8(1 2 3 4 5))
(bytevector-copy a 2 4))               ==> #u8(3 4)

procedure: bytevector-copy! to at from ¶

procedure: bytevector-copy! to at from start ¶

procedure: bytevector-copy! to at from start end ¶

It is an error if at is less than zero or greater than the length of to. It is also an error if ‘(- (bytevector-length to) at)’ is less than ‘(- end start)’. Copies the bytes of bytevector from between start and end to bytevector to, starting at at. The order in which bytes are copied is unspecified, except that if the source and destination overlap, copying takes place as if the source is first copied into a temporary bytevector and then into the destination. This can be achieved without allocating storage by making sure to copy in the correct direction in such circumstances.

(define a (bytevector 1 2 3 4 5))
(define b (bytevector 10 20 30 40 50))
(bytevector-copy! b 1 a 0 2)
b                                      ==> #u8(10 1 2 40 50)

Note: This procedure appears in R⁶RS, but places the source before the destination, contrary to other such procedures in Scheme.

procedure: bytevector-append bytevector … ¶

Returns a newly allocated bytevector whose elements are the concatenation of the elements in the given bytevectors.

(bytevector-append #u8(0 1 2) #u8(3 4 5)) 
          ==> #u8(0 1 2 3 4 5)

procedure: utf8->string bytevector ¶

procedure: utf8->string bytevector start ¶

procedure: utf8->string bytevector start end ¶

procedure: string->utf8 string ¶

procedure: string->utf8 string start ¶

procedure: string->utf8 string start end ¶

It is an error for bytevector to contain invalid UTF-8 byte sequences. These procedures translate between strings and bytevectors that encode those strings using the UTF-8 encoding. The ‘utf8->string’ procedure decodes the bytes of a bytevector between start and end and returns the corresponding string; the ‘string->utf8’ procedure encodes the characters of a string between start and end and returns the corresponding bytevector.

(utf8->string #u8(#x41))               ==> "A"
(string->utf8 "lambda")                   ==> #u8(#xCE #xBB)

6.10 Control features

This section describes various primitive procedures which control the flow of program execution in special ways. Procedures in this section that invoke procedure arguments always do so in the same dynamic environment as the call of the original procedure. The ‘procedure?’ predicate is also described here.

procedure: procedure? obj ¶

Returns #t if obj is a procedure, otherwise returns #f.

(procedure? car)                       ==>  #t
(procedure? 'car)                      ==>  #f
(procedure? (lambda (x) (* x x)))   
                                       ==>  #t
(procedure? '(lambda (x) (* x x)))  
                                       ==>  #f
(call-with-current-continuation procedure?)
                                       ==>  #t

procedure: apply proc arg1 … args ¶

The ‘apply’ procedure calls proc with the elements of the list ‘(append (list arg1 …) args)’ as the actual arguments.

(apply + (list 3 4))                   ==>  7

(define compose
  (lambda (f g)
    (lambda args
      (f (apply g args)))))

((compose sqrt *) 12 75)               ==>  30

procedure: map proc list1 list2 … ¶

It is an error if proc does not accept as many arguments as there are lists and return a single value. The ‘map’ procedure applies proc element-wise to the elements of the lists and returns a list of the results, in order. If more than one list is given and not all lists have the same length, ‘map’ terminates when the shortest list runs out. The lists can be circular, but it is an error if all of them are circular. It is an error for proc to mutate any of the lists. 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)))   
          ==>  (b e h)

(map (lambda (n) (expt n n))
     '(1 2 3 4 5))                
          ==>  (1 4 27 256 3125)

(map + '(1 2 3) '(4 5 6 7))            ==>  (5 7 9)

(let ((count 0))
  (map (lambda (ignored)
         (set! count (+ count 1))
         count)
       '(a b)))                        ==>  (1 2) or (2 1)

procedure: string-map proc string1 string2 … ¶

It is an error if proc does not accept as many arguments as there are strings and return a single character. The ‘string-map’ procedure applies proc element-wise to the elements of the strings and returns a string of the results, in order. If more than one string is given and not all strings have the same length, ‘string-map’ terminates when the shortest string runs out. The dynamic order in which proc is applied to the elements of the strings is unspecified. If multiple returns occur from ‘string-map’, the values returned by earlier returns are not mutated.

(string-map char-foldcase "AbdEgH") 
          ==>  "abdegh"

(string-map
 (lambda (c)
   (integer->char (+ 1 (char->integer c))))
 "HAL")                
          ==>  "IBM"

(string-map
 (lambda (c k)
   ((if (eqv? k #\u) char-upcase char-downcase)
    c))
 "studlycaps xxx"
 "ululululul")   
          ==>   "StUdLyCaPs"

procedure: vector-map proc vector1 vector2 … ¶

It is an error if proc does not accept as many arguments as there are vectors and return a single value. The ‘vector-map’ procedure applies proc element-wise to the elements of the vectors and returns a vector of the results, in order. If more than one vector is given and not all vectors have the same length, ‘vector-map’ terminates when the shortest vector runs out. The dynamic order in which proc is applied to the elements of the vectors is unspecified. If multiple returns occur from ‘vector-map’, the values returned by earlier returns are not mutated.

(vector-map cadr '#((a b) (d e) (g h)))   
          ==>  #(b e h)

(vector-map (lambda (n) (expt n n))
            '#(1 2 3 4 5))                
          ==>  #(1 4 27 256 3125)

(vector-map + '#(1 2 3) '#(4 5 6 7))       
          ==>  #(5 7 9)

(let ((count 0))
  (vector-map
   (lambda (ignored)
     (set! count (+ count 1))
     count)
   '#(a b)))                           ==>  #(1 2) or #(2 1)

procedure: for-each proc list1 list2 … ¶

It is an error if proc does not accept as many arguments as there are lists. The arguments to ‘for-each’ are like the arguments to ‘map’, but ‘for-each’ calls proc for its side effects rather than for its values. Unlike ‘map’, ‘for-each’ is guaranteed to call proc on the elements of the lists in order from the first element(s) to the last, and the value returned by ‘for-each’ is unspecified. If more than one list is given and not all lists have the same length, ‘for-each’ terminates when the shortest list runs out. The lists can be circular, but it is an error if all of them are circular.

It is an error for proc to mutate any of the lists.

(let ((v (make-vector 5)))
  (for-each (lambda (i)
              (vector-set! v i (* i i)))
            '(0 1 2 3 4))
  v)                                   ==>  #(0 1 4 9 16)

procedure: string-for-each proc string1 string2 … ¶

It is an error if proc does not accept as many arguments as there are strings. The arguments to ‘string-for-each’ are like the arguments to ‘string-map’, but ‘string-for-each’ calls proc for its side effects rather than for its values. Unlike ‘string-map’, ‘string-for-each’ is guaranteed to call proc on the elements of the strings in order from the first element(s) to the last, and the value returned by ‘string-for-each’ is unspecified. If more than one string is given and not all strings have the same length, ‘string-for-each’ terminates when the shortest string runs out. It is an error for proc to mutate any of the strings.

(let ((v '()))
  (string-for-each
   (lambda (c) (set! v (cons (char->integer c) v)))
   "abcde")
  v)                                   ==>  (101 100 99 98 97)

procedure: vector-for-each proc vector1 vector2 … ¶

It is an error if proc does not accept as many arguments as there are vectors. The arguments to ‘vector-for-each’ are like the arguments to ‘vector-map’, but ‘vector-for-each’ calls proc for its side effects rather than for its values. Unlike ‘vector-map’, ‘vector-for-each’ is guaranteed to call proc on the elements of the vectors in order from the first element(s) to the last, and the value returned by ‘vector-for-each’ is unspecified. If more than one vector is given and not all vectors have the same length, ‘vector-for-each’ terminates when the shortest vector runs out. It is an error for proc to mutate any of the vectors.

(let ((v (make-list 5)))
  (vector-for-each
   (lambda (i) (list-set! v i (* i i)))
   '#(0 1 2 3 4))
  v)                                   ==>  (0 1 4 9 16)

procedure: call-with-current-continuation proc ¶

procedure: call/cc proc ¶

It is an error if proc does not accept one argument. The procedure ‘call-with-current-continuation’ (or its equivalent abbreviation ‘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 will cause the invocation of before and after thunks installed using dynamic-wind.

The escape procedure accepts the same number of arguments as the continuation to the original call to call-with-current-continuation. Most continuations take only one value. Continuations created by the ‘call-with-values’ procedure (including the initialization expressions of ‘define-values’, ‘let-values’, and ‘let*-values’ expressions), take the number of values that the consumer expects. The continuations of all non-final expressions within a sequence of expressions, such as in ‘lambda’, ‘case-lambda’, ‘begin’, ‘let’, ‘let*’, ‘letrec’, ‘letrec*’, ‘let-values’, ‘let*-values’, ‘let-syntax’, ‘letrec-syntax’, ‘parameterize’, ‘guard’, ‘case’, ‘cond’, ‘when’, and ‘unless’ expressions, take an arbitrary number of values because they discard the values passed to them in any event. The effect of passing no values or more than one value to continuations that were not created in one of these ways is unspecified.

The escape procedure that is passed to proc has unlimited extent just like any other procedure in Scheme. It can be stored in variables or data structures and can be called as many times as desired. However, like the ‘raise’ and ‘error’ procedures, it never returns to its caller.

The following examples show only the simplest ways in which ‘call-with-current-continuation’ is used. If all real uses were as simple as these examples, there would be no need for a procedure with the power of ‘call-with-current-continuation’.

(call-with-current-continuation
  (lambda (exit)
    (for-each (lambda (x)
                (if (negative? x)
                    (exit x)))
              '(54 0 37 -3 245 19))
    #t))                               ==>  -3

(define list-length
  (lambda (obj)
    (call-with-current-continuation
      (lambda (return)
        (letrec ((r
                  (lambda (obj)
                    (cond ((null? obj) 0)
                          ((pair? obj)
                           (+ (r (cdr obj)) 1))
                          (else (return #f))))))
          (r obj))))))

(list-length '(1 2 3 4))               ==>  4

(list-length '(a b . c))               ==>  #f

Rationale:

A common use of ‘call-with-current-continuation’ is for structured, non-local exits from loops or procedure bodies, but in fact ‘call-with-current-continuation’ is useful for implementing a wide variety of advanced control structures. In fact, ‘raise’ and ‘guard’ provide a more structured mechanism for non-local exits.

Whenever a Scheme expression is evaluated there is a continuation wanting the result of the expression. The continuation represents an entire (default) future for the computation. If the expression is evaluated at the REPL, for example, then the continuation might take the result, print it on the screen, prompt for the next input, evaluate it, and so on forever. Most of the time the continuation includes actions specified by user code, as in a continuation that will take the result, multiply it by the value stored in a local variable, add seven, and give the answer to the REPL’s continuation to be printed. Normally these ubiquitous continuations are hidden behind the scenes and programmers do not think much about them. On rare occasions, however, a programmer needs to deal with continuations explicitly. The ‘call-with-current-continuation’ procedure allows Scheme programmers to do that by creating a procedure that acts just like the current continuation.

procedure: values obj … ¶

Delivers all of its arguments to its continuation. The values procedure might be defined as follows:

(define (values . things)
  (call-with-current-continuation 
    (lambda (cont) (apply cont things))))

procedure: call-with-values producer consumer ¶

Calls its producer argument 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 call-with-values.

(call-with-values (lambda () (values 4 5))
                  (lambda (a b) b))
                                                   ==>  5

(call-with-values * -)                             ==>  -1

procedure: dynamic-wind before thunk after ¶

Calls thunk without arguments, returning the result(s) of this call. Before and after are called, also without arguments, as required by the following rules. Note that, in the absence of calls to continuations captured using call-with-current-continuation, the three arguments are called once each, in order. Before is called whenever execution enters the dynamic extent of the call to thunk and after is called whenever it exits that dynamic extent. The dynamic extent of a procedure call is the period between when the call is initiated and when it returns. The before and after thunks are called in the same dynamic environment as the call to ‘dynamic-wind’. In Scheme, because of ‘call-with-current-continuation’, the dynamic extent of a call is not always a single, connected time period. It is defined as follows:

• The dynamic extent is entered when execution of the body of the called procedure begins.
• The dynamic extent is also entered when execution is not within the dynamic extent and a continuation is invoked that was captured (using ‘call-with-current-continuation’) during the dynamic extent.
• It is exited when the called procedure returns.
• It is also exited when execution is within the dynamic extent and a continuation is invoked that was captured while not within the dynamic extent.

If a second call to ‘dynamic-wind’ occurs within the dynamic extent of the call to thunk and then a continuation is invoked in such a way that the afters from these two invocations of ‘dynamic-wind’ are both to be called, then the after associated with the second (inner) call to ‘dynamic-wind’ is called first.

If a second call to ‘dynamic-wind’ occurs within the dynamic extent of the call to thunk and then a continuation is invoked in such a way that the befores from these two invocations of ‘dynamic-wind’ are both to be called, then the before associated with the first (outer) call to ‘dynamic-wind’ is called first.

If invoking a continuation requires calling the before from one call to ‘dynamic-wind’ and the after from another, then the after is called first.

The effect of using a captured continuation to enter or exit the dynamic extent of a call to before or after is unspecified.

(let ((path '())
      (c #f))
  (let ((add (lambda (s)
               (set! path (cons s path)))))
    (dynamic-wind
      (lambda () (add 'connect))
      (lambda ()
        (add (call-with-current-continuation
               (lambda (c0)
                 (set! c c0)
                 'talk1))))
      (lambda () (add 'disconnect)))
    (if (< (length path) 4)
        (c 'talk2)
        (reverse path))))
    
          ==> (connect talk1 disconnect
               connect talk2 disconnect)

6.11 Exceptions

This section describes Scheme’s exception-handling and exception-raising procedures. For the concept of Scheme exceptions, see section Error situations and unspecified behavior. See also ‘guard’ for the ‘guard’ syntax.

Exception handlers are one-argument procedures that determine the action the program takes when an exceptional situation is signaled. The system implicitly maintains a current exception handler in the dynamic environment.

The program raises an exception by invoking the current exception handler, passing it an object encapsulating information about the exception. Any procedure accepting one argument can serve as an exception handler and any object can be used to represent an exception.

procedure: with-exception-handler handler thunk ¶

It is an error if handler does not accept one argument. It is also an error if thunk does not accept zero arguments. The ‘with-exception-handler’ procedure returns the results of invoking thunk. Handler is installed as the current exception handler in the dynamic environment used for the invocation of thunk.

(call-with-current-continuation
 (lambda (k)
  (with-exception-handler
   (lambda (x)
    (display "condition: ")
    (write x)
    (newline)
    (k 'exception))
   (lambda ()
    (+ 1 (raise 'an-error))))))
                                       ==> exception
          and prints  condition: an-error

(with-exception-handler
 (lambda (x)
  (display "something went wrong\n"))
 (lambda ()
  (+ 1 (raise 'an-error))))
          prints  something went wrong

After printing, the second example then raises another exception.

procedure: raise obj ¶

Raises an exception by invoking the current exception handler on obj. The handler is called with the same dynamic environment as that of the call to ‘raise’, except that the current exception handler is the one that was in place when the handler being called was installed. If the handler returns, a secondary exception is raised in the same dynamic environment as the handler. The relationship between obj and the object raised by the secondary exception is unspecified.

procedure: raise-continuable obj ¶

Raises an exception by invoking the current exception handler on obj. The handler is called with the same dynamic environment as the call to ‘raise-continuable’, except that: (1) the current exception handler is the one that was in place when the handler being called was installed, and (2) if the handler being called returns, then it will again become the current exception handler. If the handler returns, the values it returns become the values returned by the call to ‘raise-continuable’.

(with-exception-handler
  (lambda (con)
    (cond
      ((string? con)
       (display con))
      (else
       (display "a warning has been issued")))
    42)
  (lambda ()
    (+ (raise-continuable "should be a number")
       23)))
   prints: should be a number
                                       ==> 65

procedure: error message obj … ¶

Message should be a string. Raises an exception as if by calling ‘raise’ on a newly allocated implementation-defined object which encapsulates the information provided by message, as well as any objs, known as the irritants. The procedure ‘error-object?’ must return #t on such objects.

(define (null-list? l)
  (cond ((pair? l) #f)
        ((null? l) #t)
        (else
          (error
            "null-list?: argument out of domain"
            l))))

procedure: error-object? obj ¶

Returns #t if obj is an object created by ‘error’ or one of an implementation-defined set of objects. Otherwise, it returns #f. The objects used to signal errors, including those which satisfy the predicates ‘file-error?’ and ‘read-error?’, may or may not satisfy ‘error-object?’.

procedure: error-object-message error-object ¶

Returns the message encapsulated by error-object.

procedure: error-object-irritants error-object ¶

Returns a list of the irritants encapsulated by error-object.

procedure: read-error? obj ¶

procedure: file-error? obj ¶

Error type predicates. Returns #t if obj is an object raised by the ‘read’ procedure or by the inability to open an input or output port on a file, respectively. Otherwise, it returns #f.

6.12 Environments and evaluation

eval library procedure: environment list1 … ¶

This procedure returns a specifier for the environment that results by starting with an empty environment and then importing each list, considered as an import set, into it. (See section see Libraries for a description of import sets.) The bindings of the environment represented by the specifier are immutable, as is the environment itself.

r5rs library procedure: scheme-report-environment version ¶

If version is equal to ‘5’, corresponding to R⁵RS, ‘scheme-report-environment’ returns a specifier for an environment that contains only the bindings defined in the R⁵RS library. Implementations must support this value of version.

Implementations may also support other values of version, in which case they return a specifier for an environment containing bindings corresponding to the specified version of the report. If version is neither ‘5’ nor another value supported by the implementation, an error is signaled.

The effect of defining or assigning (through the use of ‘eval’) an identifier bound in a ‘scheme-report-environment’ (for example ‘car’) is unspecified. Thus both the environment and the bindings it contains may be immutable.

r5rs library procedure: null-environment version ¶

If version is equal to ‘5’, corresponding to R⁵RS, the ‘null-environment’ procedure returns a specifier for an environment that contains only the bindings for all syntactic keywords defined in the R⁵RS library. Implementations must support this value of version.

Implementations may also support other values of version, in which case they return a specifier for an environment containing appropriate bindings corresponding to the specified version of the report. If version is neither ‘5’ nor another value supported by the implementation, an error is signaled.

The effect of defining or assigning (through the use of ‘eval’) an identifier bound in a ‘scheme-report-environment’ (for example ‘car’) is unspecified. Thus both the environment and the bindings it contains may be immutable.

repl library procedure: interaction-environment ¶

This procedure returns a specifier for a mutable environment that contains an implementation-defined set of bindings, typically a superset of those exported by ‘(scheme base)’. The intent is that this procedure will return the environment in which the implementation would evaluate expressions entered by the user into a REPL.

eval library procedure: eval expr-or-def environment-specifier ¶

If expr-or-def is an expression, it is evaluated in the specified environment and its values are returned. If it is a definition, the specified identifier(s) are defined in the specified environment, provided the environment is not immutable. Implementations may extend ‘eval’ to allow other objects.

(eval '(* 7 3) (environment '(scheme base)))
                                                   ==>  21

(let ((f (eval '(lambda (f x) (f x x))
               (null-environment 5))))
  (f + 10))
                                                   ==>  20
(eval '(define foo 32)
      (environment '(scheme base)))
                                                   ==>  error is signaled

6.13 Input and output

• Ports
• Input
• Output