Chapter 9

Base library

This chapter describes Scheme’s (rnrs base (6))library, which exports many of the procedure and syntax bindings that are traditionally associated with Scheme.

Section 9.21 defines the rules that identify tail calls and tail contexts in base-library constructs.

9.1 Exported identifiers

All identifiers described in the entries of this chapter are exported by the (rnrs base (6)) library with level 0, with the exception of syntax-rulesand identifier-syntax, which are exported with level 1.

Rationale: The syntax-rules and identifier-syntax forms are used to create macro transformers and are thus needed only at expansion time, i.e., meta level 1.

In addition, the identifiers unquote, unquote-splicing, =>, elseare exported with level 0, and the identifiers ...and _are exported with level 1. A reference to any of these identifiers out of place is a syntax violation. The identifier set! (section 9.5.4) is exported at both levels 0 and 1.

Rationale: The identifiers unquote, unquote-splicing, =>, and else serve as literals in the syntax of one or more base-library syntactic forms; e.g., else serves as a literal in the syntax of cond and case. Bindings of these identifiers are exported from the base library so that they can be distinguished from other bindings of these identifiers or renamed on import. The identifiers ..., _, and set! serve as literals in the syntax of syntax-rules and identifier-syntax forms and are thus exported along with those forms with level 1.

9.2 Base types

No object satisfies more than one of the following predicates:

boolean? pair? symbol? number? char? string? vector? procedure? null?

These predicates define the base types boolean, pair, symbol, number, char (or character), string, vector, and procedure. Moreover, the empty list is a special object of its own type.

Note that, although there is a separate boolean type, any Scheme value can be used as a boolean value for the purpose of a conditional test; see section 4.6.

9.3 Definitions

Definitionsmay appear within a <toplevel body> (section 7.1), at the top of a <library body> (section 6.1), or at the top of a <body> (section 9.4).

A <definition> may be a variable definition (section 9.3.1 or keyword definition (section 9.3.1. Syntactic abstractions that expand into definitions or groups of definitions (packaged in a base-library begin, let-syntax, or letrec-syntax form; see section 9.5.7) may also appear wherever other definitions may appear.

9.3.1 Variable definitions

The define form described in this section is a <definition>used to create variable bindings and may appear anywhere other definitions may appear.

A variable definition has one of the following forms:

(define <variable> <expression>) Binds <variable> to a new location before assigning the value of <expression> to it.
(define add3 (lambda (x) (+ x 3))) (add3 3) ⇒ 6 (define first car) (first ’(1 2)) ⇒ 1
The continuation of <expression> should not be invoked more than once.

Implementation responsibilities: Implementations are not required to detect that the continuation of <expression> is invoked more than once. If the implementation detects this, it must raise an exception with condition type &assertion.
(define <variable>)

This form is equivalent to
(define <variable> <unspecified>)
where <unspecified> is a side-effect-free expression returning an unspecified value.
(define (<variable> <formals>) <body>)

<Formals> must be either a sequence of zero or more variables, or a sequence of one or more variables followed by a space-delimited period and another variable (as in a lambda expression, see section 9.5.2). This form is equivalent to
(define <variable> (lambda (<formals>) <body>)).
(define (<variable> . <formal>) <body>)

<Formal> must be a single variable. This form is equivalent to
(define <variable> (lambda <formal> <body>)).

9.3.2 Syntax definitions

The define-syntax form described in this section is a <definition>used to create keyword bindings and may appear anywhere other definitions may appear.

(define-syntax <keyword> <expression>) syntax

Binds <keyword> to the value of <expression>, which must evaluate, at macro-expansion time, to a transformer (see library section on “Transformers”).

Keyword bindings established by define-syntax are visible throughout the body in which they appear, except where shadowed by other bindings, and nowhere else, just like variable bindings established by define. All bindings established by a set of definitions, whether keyword or variable definitions, are visible within the definitions themselves.

Implementation responsibilities: The implementation must check that the value of <expression> is a transformer when the evaluation produces a value.

For example:

(let () (define even? (lambda (x) (or (= x 0) (odd? (- x 1))))) (define-syntax odd? (syntax-rules () ((odd? x) (not (even? x))))) (even? 10)) ⇒ #t

An implication of the left-to-right processing order (section 8) is that one definition can affect whether a subsequent form is also a definition. For example, the expression

(let () (define-syntax bind-to-zero (syntax-rules () ((bind-to-zero id) (define id 0)))) (bind-to-zero x) x) ⇒ 0

The behavior is unaffected by any binding for bind-to-zero that might appear outside of the let expression.

9.4 Bodies and sequences

The <body> of a lambda, let, let*, let-values, let*-values, letrec, letrec* expression or that of a definition with a body consists of zero or more definitions followed by one or more expressions.

<definition> ... <expression₁> <expression₂> ...

Each identifier defined by a definition is local to the <body>. That is, the identifier is bound, and the region of the binding is the entire <body> (see section 4.2). For example,

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

When base-library begin, let-syntax, or letrec-syntax forms occur in a body prior to the first expression, they are spliced into the body; see section 9.5.7. Some or all of the body, including portions wrapped in begin, let-syntax, or letrec-syntax forms, may be specified by a syntactic abstraction (see section 6.3.2).

An expanded <body> (see chapter 8) containing variable definitions can always be converted into an equivalent letrec* expression. For example, the let expression in the above example is equivalent to

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

9.5 Expressions

The entries in this section describe the expressions of the base language, which may occur in the position of the <expression> syntactic variable. The expressions also include the primitive expression types: constant literals, variable references, and procedure calls, as described in section 6.3.1.

9.5.1 Quotation

(quote <datum>) syntax

Syntax: <Datum> should be a datum value.

Semantics: (quote <datum>) evaluates to the datum value denoted by <datum> (see section 3.3). This notation is used to include constants, including list and vector constants, in Scheme code.

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

As noted in section 3.3.5, (quote <datum>) may be abbreviated as ’<datum>:

’"abc" ⇒ "abc" ’145932 ⇒ 145932 ’a ⇒ a ’#(a b c) ⇒ #(a b c) ’() ⇒ () ’(+ 1 2) ⇒ (+ 1 2) ’(quote a) ⇒ (quote a) ’’a ⇒ (quote a)

As noted in section 4.8, constants are immutable.

9.5.2 Procedures

(lambda <formals> <body>) syntax

Syntax: <Formals> must be a formal arguments list as described below, and <body> is as described in section 9.4.

Semantics: A lambda expression evaluates to a procedure. The environment in effect when the lambda expression is evaluated is remembered as part of the procedure. When the procedure is later called with some actual arguments, the environment in which the lambda expression was evaluated is extended by binding the variables in the formal argument list to fresh locations, and the resulting actual argument values are stored in those locations. Then, the expressions in the body of the lambda expression (which may contain definitions and thus represent a letrec* form, see section 9.4) are evaluated sequentially in the extended environment. The results of the last expression in the body are returned as the results of the procedure call.

(lambda (x) (+ x x)) ⇒ a procedure ((lambda (x) (+ x x)) 4) ⇒ 8 ((lambda (x) (define (p y) (+ y 1)) (+ (p x) x)) 5) ⇒ 11 (define reverse-subtract (lambda (x y) (- y x))) (reverse-subtract 7 10) ⇒ 3 (define add4 (let ((x 4)) (lambda (y) (+ x y)))) (add4 6) ⇒ 10

<Formals> must have one of the following forms:

(<variable₁> ...): The procedure takes a fixed number of arguments; when the procedure is called, the arguments are stored in the bindings of the corresponding variables.
<variable>: The procedure takes any number of arguments; when the procedure is called, the sequence of actual arguments is converted into a newly allocated list, and the list is stored in the binding of the <variable>.
(<variable₁> ... <variable_n> . <variable_n+1>): If a space-delimited period precedes the last variable, then the procedure takes n or more arguments, where n is the number of formal arguments before the period (there must be at least one). The value stored in the binding of the last variable is a newly allocated list of the actual arguments left over after all the other actual arguments have been matched up against the other formal arguments.

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

It is a syntax violation for a <variable> to appear more than once in <formals>.

9.5.3 Conditionals

(if <test> <consequent> <alternate>) syntax

(if <test> <consequent>) syntax

Syntax: <Test>, <consequent>, and <alternate> must be expressions.

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

(if (> 3 2) ’yes ’no) ⇒ yes (if (> 2 3) ’yes ’no) ⇒ no (if (> 3 2) (- 3 2) (+ 3 2)) ⇒ 1 (if #f #f) ⇒

9.5.4 Assignments

(set! <variable> <expression>) syntax

<Expression> is evaluated, and the resulting value is stored in the location to which <variable> is bound. <Variable> must be bound either in some regionenclosing the set! expression or at the top level of a library body. The result of the set! expression is unspecified.

(let ((x 2)) (+ x 1) (set! x 4) (+ x 1)) ⇒ 5

It is a syntax violation if <variable> refers to an immutable binding.

9.5.5 Derived conditionals

(cond <cond clause₁> <cond clause₂> ...) syntax

Syntax: Each <cond clause> must be of the form

(<test> <expression₁> ...)

where <test> is any expression. Alternatively, a <cond clause> may be of the form

(<test> => <expression>)

The last <cond clause> may be an “else clause”, which has the form

(else <expression₁> <expression₂> ...).

Semantics: A cond expression is evaluated by evaluating the <test> expressions of successive <cond clause>s in order until one of them evaluates to a true value(see section 4.6). When a <test> evaluates to a true value, then the remaining <expression>s in its <cond clause> are evaluated in order, and the results of the last <expression> in the <cond clause> are returned as the results of the entire cond expression. If the selected <cond clause> contains only the <test> and no <expression>s, then the value of the <test> is returned as the result. If the selected <cond clause> uses the => alternate form, then the <expression> is evaluated. Its value must be a procedure. This procedure should accept one argument; it is called on the value of the <test> and the values returned by this procedure are returned by the cond expression. If all <test>s evaluate to false values, and there is no else clause, then the result of the conditional expression is unspecified; if there is an else clause, then its <expression>s are evaluated, and the values of the last one are returned.

(cond ((> 3 2) ’greater) ((< 3 2) ’less)) ⇒ greater (cond ((> 3 3) ’greater) ((< 3 3) ’less) (else ’equal)) ⇒ equal (cond (’(1 2 3) => cadr) (else #f)) ⇒ 2

A sample definition of cond in terms of simpler forms is in appendix B.

(case <key> <case clause₁> <case clause₂> ...) syntax

Syntax: <Key> must be an expression. Each <case clause> has one of the following forms:

((<datum₁> ...) <expression₁> <expression₂> ...) (else <expression₁> <expression₂> ...)

The second form, which specifies an “else clause”, may only appear as the last <case clause>. Each <datum> is an external representation of some object. The datums denoted by the <datum>s need not be distinct.

Semantics: A case expression is evaluated as follows. <Key> is evaluated and its result is compared against the datums denoted by the <datum>s of each <case clause> in turn, proceeding in order from left to right through the set of clauses. If the result of evaluating <key> is equivalent (in the sense of eqv?; see section 9.6) to a datum of a <case clause>, the corresponding <expression>s are evaluated from left to right and the results of the last expression in the <case clause> are returned as the results of the case expression. Otherwise, the comparison process continues. If the result of evaluating <key> is different from every datum in each set, then if there is an else clause its expressions are evaluated and the results of the last are the results of the case expression; otherwise the result of the case expression is unspecified.

(case (* 2 3) ((2 3 5 7) ’prime) ((1 4 6 8 9) ’composite)) ⇒ composite (case (car ’(c d)) ((a) ’a) ((b) ’b)) ⇒ (case (car ’(c d)) ((a e i o u) ’vowel) ((w y) ’semivowel) (else ’consonant)) ⇒ consonant

(and <test₁> ...) syntax

Syntax: The <test>s must be expressions.

Semantics: If there are no <test>s, #t is returned. Otherwise, the <test> expressions are evaluated from left to right until a <test> returns #f or the last <test> is reached. In the former case, the and expression returns #f without evaluating the remaining expressions. In the latter case, the last expression is evaluated and its values returned.

(and (= 2 2) (> 2 1)) ⇒ #t (and (= 2 2) (< 2 1)) ⇒ #f (and 1 2 ’c ’(f g)) ⇒ (f g) (and) ⇒ #t

The and keyword could be defined in terms of if using syntax-rules (see section 9.20) as follows:

(define-syntax and (syntax-rules () ((and) #t) ((and test) test) ((and test1 test2 ...) (if test1 (and test2 ...) #f))))

(or <test₁> ...) syntax

Syntax: The <test>s must be expressions.

Semantics: If there are no <test>s, #f is returned. Otherwise, the <test> expressions are evaluated from left to right until a <test> returns a true value val (see section 4.6) or the last <test> is reached. In the former case, the and expression returns val without evaluating the remaining expressions. In the latter case, the last expression is evaluated and its values returned.

(or (= 2 2) (> 2 1)) ⇒ #t (or (= 2 2) (< 2 1)) ⇒ #t (or #f #f #f) ⇒ #f (or ’(b c) (/ 3 0)) ⇒ (b c)

The or keyword could be defined in terms of if using syntax-rules (see section 9.20) as follows:

(define-syntax or (syntax-rules () ((or) #f) ((or test) test) ((or test1 test2 ...) (let ((x test1)) (if x x (or test2 ...))))))

9.5.6 Binding constructs

The four binding constructs let, let*, letrec, and letrec* give Scheme a block structure, like Algol 60. The syntax of the four constructs is identical, but they differ in the regions(see section 4.2) they establish for their variable bindings. In a let expression, the initial values are computed before any of the variables become bound; in a let* expression, the bindings and evaluations are performed sequentially. In a letrec or letrec* expression, all the bindings are in effect while their initial values are being computed, thus allowing mutually recursive definitions. In a letrec expression, the initial values are computed before being assigned to the variables; in a letrec*, the evaluations and assignments are performed sequentially.

In addition, the binding constructs let-values and let*-values generalize let and let* to allow multiple variables to be bound to the results of expressions that evaluate to multiple values. They are analogous to let and let* in the way they establish regions: in a let-values expression, the initial values are computed before any of the variables become bound; in a let*-values expression, the bindings are performed sequentially.

Note: These forms are compatible with SRFI 11 [24].

(let <bindings> <body>) syntax

Syntax: <Bindings> must have the form

((<variable₁> <init₁>) ...),

where each <init> is an expression, and <body> is as described in section 9.4. It is a syntax violation for a <variable> to appear more than once in the list of variables being bound.

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

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

9.5.7 Sequencing

(begin <form> ...) syntax

(begin <expression> <expression> ...) syntax

The <begin> keyword has two different roles, depending on its context:

It may appear as a form in a <body> (see section 9.4), <library body> (see section 6.1), or <toplevel body> (see chapter 7), or directly nested in a begin form that appears in a body. In this case, the begin form must have the shape specified in the first header line. This use of begin acts as a splicing form—the forms inside the <body> are spliced into the surrounding body, as if the begin wrapper were not actually present.

A begin form in a <body> or <library body> must be non-empty if it appears after the first <expression> within the body.
It may appear as an ordinary expression and must have the shape specified in the second header line. In this case, the <expression>s are evaluated sequentially from left to right, and the values of the last <expression> are returned. This expression type is used to sequence side effects such as assignments or input and output.

(define x 0) (begin (set! x 5) (+ x 1)) ⇒ 6 (begin (display "4 plus 1 equals ") (display (+ 4 1))) ⇒ unspecified and prints 4 plus 1 equals 5

The following macro, which uses syntax-rules (see section 9.20), defines begin in terms of lambda. Note that it covers only the expression case of begin.

(define-syntax begin (syntax-rules () ((begin exp1 exp2 ...) ((lambda () exp1 exp2 ...)))))

The following alternative expansion for begin does not make use of the ability to write more than one expression in the body of a lambda expression. It, too, covers only the expression case of begin.

(define-syntax begin (syntax-rules () ((begin exp) exp) ((begin exp1 exp2 ...) (call-with-values (lambda () exp1) (lambda ignored (begin exp2 ...))))))

9.6 Equivalence predicates

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

(eqv? obj₁ obj₂) procedure

The eqv? procedure defines a useful equivalence relation on objects. Briefly, it returns #t if obj₁ and obj₂ should normally be regarded as the same object and #f otherwise. This relation is left slightly open to interpretation, but the following partial specification of eqv? holds for all implementations of Scheme.

The eqv? procedure returns #t if one of the following holds:

Obj₁ and obj₂ are both booleans and are the same according to the boolean=? procedure (section 9.9).
Obj₁ and obj₂ are both symbols and are the same according to the symbol=? procedure (section 9.11).
Obj₁ and obj₂ are both exactnumbers and are numerically equal (see =, section 9.8).
Obj₁ and obj₂ are both inexactnumbers, are numerically equal (see =, section 9.8, and yield the same results (in the sense of eqv?) when passed as arguments to any other procedure that can be defined as a finite composition of Scheme’s standard arithmetic procedures.
Obj₁ and obj₂ are both characters and are the same character according to the char=? procedure (section 9.12).
Both obj₁ and obj₂ are the empty list.
Obj₁ and obj₂ are mutable objects such as pairs, vectors, strings, mutable records (library chapter on “Records”), ports (library section on “Port I/O”), and hashtables (library chapter on “Hash tables”) that denote the same locations in the store (section 4.8).
Obj₁ and obj₂ are records, and library section on “Mutability and equivalence” specifies that eqv? returns #t.
Obj₁ and obj₂ are record-type descriptors that are specified to be eqv? in library section on “Procedural layer”.

The eqv? procedure returns #f if one of the following holds:

Obj₁ and obj₂ are of different types (section 9.2).
Obj₁ is a record and obj₂ is not, or vice versa (see library chapter on “Records”).
Obj₁ and obj₂ are records, and library section on “Mutability and equivalence” specifies that eqv? returns #f.
Obj₁ and obj₂ are booleans for which the boolean=? procedure returns #f.
Obj₁ and obj₂ are symbols for which the symbol=? procedure returns #f.
One of obj₁ and obj₂ is an exact number but the other is an inexact number.
Obj₁ and obj₂ are rational numbers for which the = procedure returns #f.
Obj₁ and obj₂ yield different results (in the sense of eqv?) when passed as arguments to any other procedure that can be defined as a finite composition of Scheme’s standard arithmetic procedures.
Obj₁ and obj₂ are characters for which the char=? procedure returns #f.
One of obj₁ and obj₂ is the empty list, but the other is not.
Obj₁ and obj₂ are mutable objects such as pairs, vectors, strings, mutable records (library chapter on “Records”), ports (library section on “Port I/O”), and hashtables (library chapter on “Hashtables”) that denote distinct locations.
Obj₁ and obj₂ are procedures that would behave differently (return different values or have different side effects) for some arguments.

Note: The eqv? procedure returning #t when obj₁ and obj₂ are numbers does not imply that = would also return #t when called with obj₁ and obj₂ as arguments.

(eqv? ’a ’a) ⇒ #t (eqv? ’a ’b) ⇒ #f (eqv? 2 2) ⇒ #t (eqv? ’() ’()) ⇒ #t (eqv? 100000000 100000000) ⇒ #t (eqv? (cons 1 2) (cons 1 2)) ⇒ #f (eqv? (lambda () 1) (lambda () 2)) ⇒ #f (eqv? #f ’nil) ⇒ #f (let ((p (lambda (x) x))) (eqv? p p)) ⇒ unspecified

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? +nan.0 +nan.0) ⇒ unspecified

The next set of examples shows the use of eqv? with procedures that have local state. Calls to gen-counter must return a distinct procedure every time, since each procedure has its own internal counter. Calls to gen-loser return procedures that behave pairwise equivalent when called. However, eqv? is not required to detect this equivalence.

(define gen-counter (lambda () (let ((n 0)) (lambda () (set! n (+ n 1)) n)))) (let ((g (gen-counter))) (eqv? g g)) ⇒ unspecified (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)) ⇒ unspecified (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 the effect of trying to modify constant objects (those returned by literal expressions) is unspecified, implementations are permitted, though not required, to share structure between constants where appropriate. Furthermore, a constant may be copied at any time by the implementation so as to exist simultaneously in different sets of locations, as noted in section 4.8. Thus the value of eqv? on constants is sometimes implementation-dependent.

(eqv? ’(a) ’(a)) ⇒ unspecified but see below (eqv? "a" "a") ⇒ unspecified (eqv? ’(b) (cdr ’(a b))) ⇒ unspecified (let ((x ’(a))) (eqv? x x)) ⇒ unspecified

Note: Library section on “Procedural layer” elaborates on the semantics of eqv? on record objects.

Rationale: The above definition of eqv? allows implementations latitude in their treatment of procedures and literals: implementations are free either to detect or to fail to detect that two procedures or two literals are equivalent to each other, and can decide whether or not to merge representations of equivalent objects by using the same pointer or bit pattern to represent both. Moreover, they can use implementation techniques such as inlining and beta reduction that duplicate otherwise equivalent objects.

(eq? obj₁ obj₂) procedure

The eq? predicate is similar to eqv? except that in some cases it is capable of discerning distinctions finer than those detectable by eqv?.

The eq? and eqv? predicates are guaranteed to have the same behavior on symbols, booleans, the empty list, pairs, procedures, non-empty strings and vectors, and mutable records. The behavior of eq? on numbers and characters is implementation-dependent, but it always returns either true or false, and returns true only when eqv? would also return true. The eq? predicate may also behave differently from eqv? on empty vectors and empty strings.

(eq? ’a ’a) ⇒ #t (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)) ⇒ unspecified (let ((x ’#())) (eq? x x)) ⇒ unspecified (let ((p (lambda (x) x))) (eq? p p)) ⇒ unspecified

Rationale: It is usually possible to implement eq? much more efficiently than eqv?, for example, as a simple pointer comparison instead of as some more complicated operation. One reason is that it may not be possible to compute eqv? of two numbers in constant time, whereas eq? implemented as pointer comparison will always finish in constant time. The eq? predicate may be used like eqv? in applications using procedures to implement objects with state since it obeys the same constraints as eqv?.

(equal? obj₁ obj₂) procedure

The equal? predicate returns #t if and only if the (possibly infinite) unfoldings of its arguments into regular trees are equal as ordered trees.

The equal? predicate treats pairs and vectors as nodes with outgoing edges, uses string=? to compare strings, uses bytevector=? to compare bytevectors (see library chapter on “Bytevectors”), and uses eqv? to compare other nodes.

(equal? ’a ’a) ⇒ #t (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? ’#vu8(1 2 3 4 5) (u8-list->bytevector ’(1 2 3 4 5)) ⇒ #t (equal? (lambda (x) x) (lambda (y) y)) ⇒ unspecified (let* ((x (list ’a)) (y (list ’a)) (z (list x y))) (list (equal? z (list y x)) (equal? z (list x x)))) ⇒ (#t #t)

9.7 Procedure predicate

(procedure? obj) procedure

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

9.8 Generic arithmetic

The procedures described here implement arithmetic that is generic over the numerical tower described in chapter 2. The generic procedures described in this section accept both exact and inexact numbers as arguments, performing coercions and selecting the appropriate operations as determined by the numeric subtypes of their arguments.

Library chapter on “Arithmetic” describes libraries that define other numerical procedures.

9.8.1 Propagation of exactness and inexactness

The procedures listed below must return the correct exact result provided all their arguments are exact:

+ - * max min abs numerator denominator gcd lcm floor ceiling truncate round rationalize expt real-part imag-part make-rectangular

The procedures listed below must return the correct exact result provided all their arguments are exact, and no divisors are zero:

/ div mod div-and-mod div0 mod0 div0-and-mod0

The general rule is that the generic operations return the correct exact result when all of their arguments are exact and the result is mathematically well-defined, but return an inexact result when any argument is inexact. Exceptions to this rule include sqrt, exp, log, sin, cos, tan, asin, acos, atan, expt, make-polar, magnitude, and angle, which are allowed (but not required) to return inexact results even when given exact arguments, as indicated in the specification of these procedures.

One general exception to the rule above is that an implementation may return an exact result despite inexact arguments if that exact result would be the correct result for all possible substitutions of exact arguments for the inexact ones. An example is (* 1.0 0) which may return either 0 (exact) or 0.0 (inexact).

9.8.2 Representability of infinities and NaNs

The specification of the numerical operations is written as though infinities and NaNs are representable, and specifies many operations with respect to these numbers in ways that are consistent with the IEEE 754 standard for binary floating point arithmetic. An implementation of Scheme is not required to represent infinities and NaNs; however, an implementation must raise a continuable exception with condition type &no-infinities or &no-nans (respectively; see library section on “Flonums”) whenever it is unable to represent an infinity or NaN as required by the specification. In this case, the continuation of the exception handler is the continuation that otherwise would have received the infinity or NaN value. This requirement also applies to conversions between numbers and external representations, including the reading of program source code.

9.8.3 Semantics of common operations

Some operations are the semantic basis for several arithmetic procedures. The behavior of these operations is described in this section for later reference.

9.8.3.1 Integer division

For various kinds of arithmetic (fixnum, flonum, exact, inexact, and generic), Scheme provides operations for performing integer division. They rely on mathematical operations div, mod, div₀, and mod₀, that are defined as follows:

div, mod, div₀, and mod₀ each accept two real numbers x₁ and x₂ as operands, where x₂ must be nonzero.

div returns an integer, and mod returns a real. Their results are specified by

x₁ div x₂	=	n_d
x₁ mod x₂	=	x_m

* where

Examples:

123 div 10	=	12
123 mod 10	=	3
123 div `-` 10	=	`-` 12
123 mod `-` 10	=	3
`-` 123 div 10	=	`-` 13
`-` 123 mod 10	=	7
`-` 123 div `-` 10	=	13
`-` 123 mod `-` 10	=	7

* div₀ and mod₀ are like div and mod, except the result of mod₀ lies within a half-open interval centered on zero. The results are specified by

x₁ div₀ x₂	=	n_d
x₁ mod₀ x₂	=	x_m

* where:

Examples:

123 div₀ 10	=	12
123 mod₀ 10	=	3
123 div₀ `-` 10	=	`-` 12
123 mod₀ `-` 10	=	3
`-` 123 div₀ 10	=	`-` 12
`-` 123 mod₀ 10	=	`-` 3
`-` 123 div₀ `-` 10	=	12
`-` 123 mod₀ `-` 10	=	`-` 3

Rationale: The half-open symmetry about zero is convenient for some purposes.

9.8.3.2 Transcendental functions

In general, the transcendental functions log, sin^-1 (arcsine), cos^-1 (arccosine), and tan^-1 are multiply defined. The value of log z is defined to be the one whose imaginary part lies in the range from - [r6rs-Z-G-D-3.gif] (inclusive if - 0.0 is distinguished, exclusive otherwise) to (inclusive). log 0 is undefined.

The value of log z for non-real z is defined in terms of log on real numbers as

where angle z is the angle of z = a · e^ib specified as:

angle z = b + 2 [r6rs-Z-G-D-3.gif]

with - [r6rs-Z-G-D-3.gif] ≤ angle z≤ and angle z = b + 2 n for some integer n.

With the one-argument version of log defined this way, the values of the two-argument-version of log, sin^-1 z, cos^-1 z, tan^-1 z, and the two-argument version of tan^-1 are according to the following formulæ:

log z b	=	(log z/log b)
sin^-1 z	=	`-` i log (i z + (1 `-` z²)^1/2)
cos^-1 z	=	/ 2 `-` sin^-1 z
tan^-1 z	=	(log (1 + i z) `-` log (1 `-` i z)) / (2 i)
tan^-1 x y	=	angle(x + yi)

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

	y condition	x condition	range of result r
	y = 0.0	x > 0.0	0.0
∗	y = + 0.0	x > 0.0	+ 0.0
∗	y = `-` 0.0	x > 0.0	`-` 0.0
	y > 0.0	x > 0.0	0.0 < r < (/2)
	y > 0.0	x = 0.0	(/2)
	y > 0.0	x < 0.0	(/2) < r <
	y = 0.0	x < 0
∗	y = + 0.0	x < 0.0
∗	y = `-` 0.0	x < 0.0	`-`
	y < 0.0	x < 0.0	`-` < r< `-` (/2)
	y < 0.0	x = 0.0	`-` (/2)
	y < 0.0	x > 0.0	`-` (/2) < r< 0.0
	y = 0.0	x = 0.0	undefined
∗	y = + 0.0	x = + 0.0	+ 0.0
∗	y = `-` 0.0	x = + 0.0	`-` 0.0
∗	y = + 0.0	x = `-` 0.0
∗	y = `-` 0.0	x = `-` 0.0	`-`
∗	y = + 0.0	x = 0	(/2)
∗	y = `-` 0.0	x = 0	`-` (/2)

The above specification follows Steele [41], which in turn cites Penfield [33]; refer to these sources for more detailed discussion of branch cuts, boundary conditions, and implementation of these functions.

9.8.4 Numerical operations

9.8.4.1 Numerical type predicates

(number? obj) procedure

(complex? obj) procedure

(real? obj) procedure

(rational? obj) procedure

(integer? obj) procedure

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

If z is a complex number, then (real? z) is true if and only if (zero? (imag-part z)) and (exact? (imag-part z)) are both true.

If x is a real number, then (rational? x) is true if and only if there exist exact integers k₁ and k₂ such that (= x (/ k₁ k₂)) and (= (numerator x) k₁) and (= (denominator x) k₂) are all true. Thus infinities and NaNs are not rational numbers.

If q is a rational number, then (integer? q) is true if and only if (= (denominator q) 1) is true. If q is not a rational number, then (integer? q) is false.

(complex? 3+4i) ⇒ #t (complex? 3) ⇒ #t (real? 3) ⇒ #t (real? -2.5+0.0i) ⇒ #f (real? -2.5+0i) ⇒ #t (real? -2.5) ⇒ #t (real? #e1e10) ⇒ #t (rational? 6/10) ⇒ #t (rational? 6/3) ⇒ #t (rational? 2) ⇒ #t (integer? 3+0i) ⇒ #t (integer? 3.0) ⇒ #t (integer? 8/4) ⇒ #t (number? +nan.0) ⇒ #t (complex? +nan.0) ⇒ #t (real? +nan.0) ⇒ #t (rational? +nan.0) ⇒ #f (complex? +inf.0) ⇒ #t (real? -inf.0) ⇒ #t (rational? -inf.0) ⇒ #f (integer? -inf.0) ⇒ #f

Note: Except for number?, the behavior of these type predicates on inexact numbers is unreliable, because any inaccuracy may affect the result.

(real-valued? obj) procedure

(rational-valued? obj) procedure

(integer-valued? obj) procedure

These numerical type predicates can be applied to any kind of argument, including non-numbers. The real-valued? procedure returns #t if the object is a number and is equal in the sense of = to some real number, or if the object is a NaN, or a complex number whose real part is a NaN and whose imaginary part zero in the sense of zero?. The rational-valued? and integer-valued? procedures return #t if the object is a number and is equal in the sense of = to some object of the named type, and otherwise they return #f.

(real-valued? +nan.0) ⇒ #t (real-valued? +nan.0+0i) ⇒ #t (real-valued? -inf.0) ⇒ #t (real-valued? 3) ⇒ #t (real-valued? -2.5+0.0i) ⇒ #t (real-valued? -2.5+0i) ⇒ #t (real-valued? -2.5) ⇒ #t (real-valued? #e1e10) ⇒ #t (rational-valued? +nan.0) ⇒ #f (rational-valued? -inf.0) ⇒ #f (rational-valued? 6/10) ⇒ #t (rational-valued? 6/10+0.0i) ⇒ #t (rational-valued? 6/10+0i) ⇒ #t (rational-valued? 6/3) ⇒ #t (integer-valued? 3+0i) ⇒ #t (integer-valued? 3+0.0i) ⇒ #t (integer-valued? 3.0) ⇒ #t (integer-valued? 3.0+0.0i) ⇒ #t (integer-valued? 8/4) ⇒ #t

Rationale: These procedures test whether a given number can be coerced to the specified type without loss of numerical accuracy. Their behavior is different from the numerical type predicates in the previous entry, whose behavior is motivated by closure properties designed to enable statically predictable semantics and efficient implementation.

Note: The behavior of these type predicates on inexact numbers is unreliable, because any inaccuracy may affect the result.

(exact? z) procedure

(inexact? z) procedure

These numerical predicates provide tests for the exactness of a quantity. For any Scheme number, precisely one of these predicates is true.

(exact? 5) ⇒ #t (inexact? +inf.0) ⇒ #t

9.8.4.2 Generic conversions

(inexact z) procedure

(exact z) procedure

The inexact procedure returns an inexact representation of z. If inexact numbers of the appropriate type have bounded precision, then the value returned is an inexact number that is nearest to the argument. If an exact argument has no reasonably close inexact equivalent, an exception with condition type &implementation-violation may be raised.

The exact procedure returns an exact representation of z. The value returned is the exact number that is numerically closest to the argument; in most cases, the result of this procedure should be numerically equal to its argument. If an inexact argument has no reasonably close exact equivalent, an exception with condition type &implementation-violation may be raised.

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

The inexact and exact procedures are idempotent.

(real->single x) procedure

(real->double x) procedure

Given a real number x, these procedures compute the best IEEE-754 single or double precision approximation to x and return that approximation as an inexact real.

Note: Both of the two conversions performed by these procedures (to IEEE-754 single or double, and then to an inexact real) may lose precision, introduce error, or may underflow or overflow.

Rationale: The ability to round to IEEE-754 single or double precision is occasionally needed for control of precision or for interoperability.

9.8.4.3 Arithmetic operations

(= z₁ z₂ z₃ ...) procedure

(< x₁ x₂ x₃ ...) procedure

(> x₁ x₂ x₃ ...) procedure

(<= x₁ x₂ x₃ ...) procedure

(>= x₁ x₂ x₃ ...) procedure

These procedures return #t if their arguments are (respectively): equal, monotonically increasing, monotonically decreasing, monotonically nondecreasing, or monotonically nonincreasing, and #f otherwise.

(= +inf.0 +inf.0) ⇒ #t (= -inf.0 +inf.0) ⇒ #f (= -inf.0 -inf.0) ⇒ #t

For any real number x that is neither infinite nor NaN:

(< -inf.0 x +inf.0)) ⇒ #t (> +inf.0 x -inf.0)) ⇒ #t

For any number z:

(= +nan.0 z) ⇒ #f

For any real number x:

(< +nan.0 x) ⇒ #f (> +nan.0 x) ⇒ #f

These predicates are required to be transitive.

Note: The traditional implementations of these predicates in Lisp-like languages are not transitive.

Note: While it is possible to compare inexact numbers using these predicates, the results may be unreliable because a small inaccuracy may affect the result; this is especially true of = and zero? (below).
When in doubt, consult a numerical analyst.

(zero? z) procedure

(positive? x) procedure

(negative? x) procedure

(odd? n) procedure

(even? n) procedure

(finite? x) procedure

(infinite? x) procedure

(nan? x) procedure

These numerical predicates test a number for a particular property, returning #t or #f. See note above. The zero? procedure tests if the number is = to zero, positive? tests whether it is greater than zero, negative? tests whether it is less than zero, odd? tests whether it is odd, even? tests whether it is even, finite? tests whether it is not an infinity and not a NaN, infinite? tests whether it is an infinity, nan? tests whether it is a NaN.

(zero? +0.0) ⇒ #t (zero? -0.0) ⇒ #t (zero? +nan.0) ⇒ #f (positive? +inf.0) ⇒ #t (negative? -inf.0) ⇒ #t (positive? +nan.0) ⇒ #f (negative? +nan.0) ⇒ #f (finite? +inf.0) ⇒ #f (finite? 5) ⇒ #t (finite? 5.0) ⇒ #t (infinite? 5.0) ⇒ #f (infinite? +inf.0) ⇒ #t

(max x₁ x₂ ...) procedure

(min x₁ x₂ ...) procedure

These procedures return the maximum or minimum of their arguments.

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

For any real number x:

(max +inf.0 x) ⇒ +inf.0 (min -inf.0 x) ⇒ -inf.0

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

(+ z₁ ...) procedure

(* z₁ ...) procedure

These procedures return the sum or product of their arguments.

(+ 3 4) ⇒ 7 (+ 3) ⇒ 3 (+) ⇒ 0 (+ +inf.0 +inf.0) ⇒ +inf.0 (+ +inf.0 -inf.0) ⇒ +nan.0 (* 4) ⇒ 4 (*) ⇒ 1 (* 5 +inf.0) ⇒ +inf.0 (* -5 +inf.0) ⇒ -inf.0 (* +inf.0 +inf.0) ⇒ +inf.0 (* +inf.0 -inf.0) ⇒ -inf.0 (* 0 +inf.0) ⇒ 0 or +nan.0 (* 0 +nan.0) ⇒ 0 or +nan.0 (* 1.0 0) ⇒ 0 or 0.0

For any real number x that is neither infinite nor NaN:

(+ +inf.0 x) ⇒ +inf.0 (+ -inf.0 x) ⇒ -inf.0

For any real number x:

(+ +nan.0 x) ⇒ +nan.0

For any real number x that is not an exact 0:

(* +nan.0 x) ⇒ +nan.0

If any of these procedures are applied to mixed non-rational real and non-real complex arguments, they either raise an exception with condition type &implementation-restriction or return an unspecified number.

Implementations that distinguish - 0.0 should