1.1 Notational Conventions

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

• Errors
• Examples
• Entry Format

(+ 1 2)          ⇒  3

(+ 1 'foo)                      error→ Illegal datum

(begin (write 'foo) 'bar)
     -| foo
     ⇒ bar

1.2 Scheme Concepts

• Variable Bindings
• Environment Concepts
• Initial and Current Environments
• Static Scoping
• True and False
• External Representations
• Disjointness of Types
• Storage Model

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

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

1.3 Lexical Conventions

This section describes Scheme’s lexical conventions.

• Whitespace
• Delimiters
• Identifiers
• Uppercase and Lowercase
• Naming Conventions
• Comments
• Additional Notations

(  )  ;  "  '  `  |

[  ]  {  }

(list"Hi"name(+ 1 2))                   ⇒  ("Hi" "max" 3)

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

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

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

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

1.4 Expressions

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

• Literal Expressions
• Variable References
• Special Form Syntax
• Procedure Call Syntax

"abc"                                   ⇒  "abc"
145932                                  ⇒  145932
#t                                      ⇒  #t
#\a                                     ⇒  #\a

(define x 28)
x                                       ⇒  28

(keyword component …)

(operator operand …)

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

2.1 Lambda Expressions

extended standard special form: lambda formals expr expr … ¶

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

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

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

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

Required

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

Optional

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

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

Rest

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

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

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

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

(a b c)

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

(a b #!optional c)

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

(#!optional a b c)

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

a

(#!rest a)

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

(a b #!optional c d #!rest e)

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

Some examples of lambda expressions:

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

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

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

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

special form: named-lambda formals expression expression … ¶

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

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

2.2 Lexical Binding

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

extended standard special form: let ((variable init) …) expr expr … ¶

The inits are evaluated in the current environment (in some unspecified order), the variables are bound to fresh locations holding the results, the exprs are evaluated sequentially in the extended environment, and the value of the last expr is returned. Each binding of a variable has the exprs as its region.

MIT/GNU Scheme allows any of the inits to be omitted, in which case the corresponding variables are unassigned.

Note that the following are equivalent:

(let ((variable init) …) expr expr …)
((lambda (variable …) expr expr …) init …)

Some examples:

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

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

See Iteration, for information on “named let”.

extended standard special form: let* ((variable init) …) expr expr … ¶

let* is similar to let, but the bindings are performed sequentially from left to right, and the region of a binding is that part of the let* expression to the right of the binding. Thus the second binding is done in an environment in which the first binding is visible, and so on.

Note that the following are equivalent:

(let* ((variable1 init1)
       (variable2 init2)
       …
       (variableN initN))
   expr
   expr …)

(let ((variable1 init1))
  (let ((variable2 init2))
    …
      (let ((variableN initN))
        expr
        expr …)
    …))

An example:

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

extended standard special form: letrec ((variable init) …) expr expr … ¶

The variables are bound to fresh locations holding unassigned values, the inits are evaluated in the extended environment (in some unspecified order), each variable is assigned to the result of the corresponding init, the exprs are evaluated sequentially in the extended environment, and the value of the last expr is returned. Each binding of a variable has the entire letrec expression as its region, making it possible to define mutually recursive procedures.

MIT/GNU Scheme allows any of the inits to be omitted, in which case the corresponding variables are unassigned.

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

One restriction on letrec is very important: it shall be possible to evaluated each init without assigning or referring to the value of any variable. If this restriction is violated, then it is an error. The restriction is necessary because Scheme passes arguments by value rather than by name. In the most common uses of letrec, all the inits are lambda or delay expressions and the restriction is satisfied automatically.

extended standard special form: letrec* ((variable init) …) expr expr … ¶

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

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

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

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

standard special form: let-values ((formals init) …) expr expr … ¶

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

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

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

standard special form: let*-values ((formals init) …) expr expr … ¶

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

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

2.3 Dynamic Binding

standard special form: parameterize ((parameter value) …) expr expr … ¶

Note that both parameter and value are expressions. It is an error if the value of any parameter expression is not a parameter object.

A parameterize expression is used to change the values of specified parameter objects during the evaluation of the body expressions.

The parameter and value expressions are evaluated in an unspecified order. The body is evaluated in a dynamic environment in which each parameter is bound to the converted value—the result of passing value to the conversion procedure specified when the parameter was created. Then the previous value of parameter is restored without passing it to the conversion procedure. The value of the parameterize expression is the value of the last body expr.

The parameterize special form is standardized by SRFI 39 and by R7RS.

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

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

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

(f 12)                                  ⇒ "12"
(parameterize ((radix 2))
  (f 12))                               ⇒ "1100"
(f 12)                                  ⇒ "12"
(radix 16)                              error→ Wrong number of arguments
(parameterize ((radix 0))
  (f 12))                               error→ invalid radix

A dynamic binding changes the value of a parameter (see Parameters) object temporarily, for a dynamic extent. The set of all dynamic bindings at a given time is called the dynamic environment. The new values are only accessible to the thread that constructed the dynamic environment, and any threads created within that environment.

The extent of a dynamic binding is defined to be the time period during which calling the parameter returns the new value. Normally this time period begins when the body is entered and ends when it is exited, a contiguous time period. However Scheme has first-class continuations by which it is possible to leave the body and reenter it many times. In this situation, the extent is non-contiguous.

When the body is exited by invoking a continuation, the current dynamic environment is unwound until it can be re-wound to the environment captured by the continuation. When the continuation returns, the process is reversed, restoring the original dynamic environment.

The following example shows the interaction between dynamic binding and continuations. Side effects to the binding that occur both inside and outside of the body are preserved, even if continuations are used to jump in and out of the body repeatedly.

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

Evaluating ‘(complicated-dynamic-binding)’ writes the following on the console:

1
2
1
3
4

Commentary: the first two values written are the initial binding of variable and its new binding inside parameterize’s body. Immediately after they are written, the binding visible in the body is set to ‘3’, and outside-continuation is invoked, exiting the body. At this point, ‘1’ is written, demonstrating that the original binding of variable is still visible outside the body. Then we set variable to ‘4’ and reenter the body by invoking inside-continuation. At this point, ‘3’ is written, indicating that the binding modified in the body is still the binding visible in the body. Finally, we exit the body normally, and write ‘4’, demonstrating that the binding modified outside of the body was also preserved.

• Fluid-Let

2.4 Definitions

extended standard special form: define variable [expression] ¶

standard special form: define formals expression expression … ¶

Definitions are valid in some but not all contexts where expressions are allowed. Definitions may only occur at the top level of a program and at the beginning of a lambda body (that is, the body of a lambda, let, let*, letrec, letrec*, let-values, let*-values, parameterize, or “procedure define” expression). A definition that occurs at the top level of a program is called a top-level definition, and a definition that occurs at the beginning of a body is called an internal definition.

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

(define (name1 name2 …)
  expression
  expression …)

(define name1
  (named-lambda (name1 name2 …)
    expression
    expression …))

• Top-Level Definitions
• Internal Definitions

(define variable expression)

(set! variable expression)

(define add3
   (lambda (x) (+ x 3)))                ⇒  unspecified
(add3 3)                                ⇒  6

(define first car)                      ⇒  unspecified
(first '(1 2))                          ⇒  1

(define bar)                            ⇒  unspecified
bar                                     error→ Unassigned variable

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

2.5 Assignments

extended standard special form: set! variable [expression] ¶

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

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

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

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

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

2.6 Quoting

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

standard special form: quote datum ¶

(quote datum) evaluates to datum. Datum may be any external representation of a Scheme object (see External Representations). Use quote to include literal constants in Scheme code.

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

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

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

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

'"abc"                                  ⇒  "abc"
"abc"                                   ⇒  "abc"
'145932                                 ⇒  145932
145932                                  ⇒  145932
'#t                                     ⇒  #t
#t                                      ⇒  #t
'#\a                                    ⇒  #\a
#\a                                     ⇒  #\a

standard special form: quasiquote template ¶

“Backquote” or “quasiquote” expressions are useful for constructing a list or vector structure when most but not all of the desired structure is known in advance. If no commas appear within the template, the result of evaluating `template is equivalent (in the sense of equal?) to the result of evaluating 'template. If a comma appears within the template, however, the expression following the comma is evaluated (“unquoted”) and its result is inserted into the structure instead of the comma and the expression. If a comma appears followed immediately by an at-sign (@), then the following expression shall evaluate to a list; the opening and closing parentheses of the list are then “stripped away” and the elements of the list are inserted in place of the comma at-sign expression sequence.

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

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

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

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

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

`,(+ 2 3)                                ⇒  5

Quasiquote forms may be nested. Substitutions are made only for unquoted components appearing at the same nesting level as the outermost backquote. The nesting level increases by one inside each successive quasiquotation, and decreases by one inside each unquotation.

`(a `(b ,(+ 1 2) ,(foo ,(+ 1 3) d) e) f)
     ⇒  (a `(b ,(+ 1 2) ,(foo 4 d) e) f)

(let ((name1 'x)
      (name2 'y))
   `(a `(b ,,name1 ,',name2 d) e))
     ⇒  (a `(b ,x ,'y d) e)

The notations `template and (quasiquote template) are identical in all respects. ,expression is identical to (unquote expression) and ,@expression is identical to (unquote-splicing expression).

(quasiquote (list (unquote (+ 1 2)) 4))
     ⇒  (list 3 4)

'(quasiquote (list (unquote (+ 1 2)) 4))
     ⇒  `(list ,(+ 1 2) 4)
     i.e., (quasiquote (list (unquote (+ 1 2)) 4))

Unpredictable behavior can result if any of the symbols quasiquote, unquote, or unquote-splicing appear in a template in ways otherwise than as described above.

2.7 Conditionals

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

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

standard special form: if predicate consequent [alternative] ¶

Predicate, consequent, and alternative are expressions. An if expression is evaluated as follows: first, predicate is evaluated. If it yields a true value, then consequent is evaluated and its value is returned. Otherwise alternative is evaluated and its value is returned. If predicate yields a false value and no alternative is specified, then the result of the expression is unspecified.

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

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

standard special form: cond clause clause … ¶

Each clause has this form:

(predicate expression …)

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

(else expression expression …)

A cond expression does the following:

1. Evaluates the predicate expressions of successive clauses in order, until one of the predicates evaluates to a true value.
2. When a predicate evaluates to a true value, cond evaluates the expressions in the associated clause in left to right order, and returns the result of evaluating the last expression in the clause as the result of the entire cond expression.

   If the selected clause contains only the predicate and no expressions, cond returns the value of the predicate as the result.

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

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

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

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

Scheme supports an alternative clause syntax:

(predicate => recipient)

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

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

standard special form: case key clause clause … ¶

Key may be any expression. Each clause has this form:

((object …) expression expression …)

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

(else expression expression …)

A case expression does the following:

1. Evaluates key and compares the result with each object.
2. If the result of evaluating key is equivalent (in the sense of eqv?; see Equivalence Predicates) to an object, case evaluates the expressions in the corresponding clause from left to right and returns the result of evaluating the last expression in the clause as the result of the case expression.
3. If the result of evaluating key is different from every object, and if there’s an else clause, case evaluates its expressions and returns the result of the last one as the result of the case expression. If there’s no else clause, case returns an unspecified result. Programs should not depend on the value of a case expression that has no else clause.

For example,

(case (* 2 3)
   ((2 3 5 7) 'prime)
   ((1 4 6 8 9) 'composite))            ⇒  composite

(case (car '(c d))
   ((a) 'a)
   ((b) 'b))                            ⇒  unspecified

(case (car '(c d))
   ((a e i o u) 'vowel)
   ((w y) 'semivowel)
   (else 'consonant))                   ⇒  consonant

standard special form: and expression … ¶

The expressions are evaluated from left to right, and the value of the first expression that evaluates to a false value is returned. Any remaining expressions are not evaluated. If all the expressions evaluate to true values, the value of the last expression is returned. If there are no expressions then #t is returned.

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

standard special form: or expression … ¶

The expressions are evaluated from left to right, and the value of the first expression that evaluates to a true value is returned. Any remaining expressions are not evaluated. If all expressions evaluate to false values, the value of the last expression is returned. If there are no expressions then #f is returned.

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

2.8 Sequencing

The begin special form is used to evaluate expressions in a particular order.

standard special form: begin expression expression … ¶

The expressions are evaluated sequentially from left to right, and the value of the last expression is returned. This expression type is used to sequence side effects such as input and output.

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

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

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

case
cond
define          ;“procedure define” only
do
lambda
let
let*
letrec
letrec*
let-values
let*-values
named-lambda
parameterize

2.9 Iteration

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

extended standard special form: let name ((variable init) …) expr expr … ¶

MIT/GNU Scheme permits a variant on the syntax of let called “named let” which provides a more general looping construct than do, and may also be used to express recursions.

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

MIT/GNU Scheme allows any of the inits to be omitted, in which case the corresponding variables are unassigned.

Note: the following expressions are equivalent:

(let name ((variable init) …)
  expr
  expr …)

((letrec ((name
           (named-lambda (name variable …)
             expr
             expr …)))
   name)
 init …)

Here is an example:

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

     ⇒  ((6 1 3) (-5 -2))

extended standard special form: do ((variable init step) …) (test expression …) command … ¶

do is an iteration construct. It specifies a set of variables to be bound, how they are to be initialized at the start, and how they are to be updated on each iteration. When a termination condition is met, the loop exits with a specified result value.

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

Each iteration begins by evaluating test; if the result is false, then the command expressions are evaluated in order for effect, the step expressions are evaluated in some unspecified order, the variables are bound to fresh locations, the results of the steps are stored in the bindings of the variables, and the next iteration begins.

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

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

A step may be omitted, in which case the effect is the same as if (variable init variable) had been written instead of (variable init).

(do ((vec (make-vector 5))
      (i 0 (+ i 1)))
    ((= i 5) vec)
   (vector-set! vec i i))               ⇒  #(0 1 2 3 4)

(let ((x '(1 3 5 7 9)))
   (do ((x x (cdr x))
        (sum 0 (+ sum (car x))))
       ((null? x) sum)))                ⇒  25

2.10 Structure Definitions

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

special form: define-structure (name structure-option …) slot-description … ¶

Each slot-description takes one of the following forms:

slot-name
(slot-name default-init [slot-option value]*)

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

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

(define-structure foo a b c)

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

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

type descriptor

The name of the type descriptor is "rtd:" followed by the name of the structure, e.g. ‘rtd:foo’. The type descriptor satisfies the predicate record-type?.

constructor

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

predicate

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

accessors

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

modifiers

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

When options are not supplied, (name) may be abbreviated to name. This convention holds equally for structure-options and slot-options. Hence, these are equivalent:

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

as are

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

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

Possible slot-options are:

slot option: read-only value ¶

When given a value other than #f, this specifies that no modifier should be created for the slot.

slot option: type type-descriptor ¶

This is accepted but not presently used.

Possible structure-options are:

structure option: predicate [name] ¶

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

structure option: copier [name] ¶

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

structure option: print-procedure expression ¶

Evaluating expression must yield a procedure of two arguments, which is used to print instances of the structure. The procedure is a print method (see Custom Output).

structure option: constructor [name [argument-list]] ¶

This option controls the definition of constructor procedures. These constructor procedures are called “BOA constructors”, for “By Order of Arguments”, because the arguments to the constructor specify the initial contents of the structure’s slots by the order in which they are given. This is as opposed to “keyword constructors”, which specify the initial contents using keywords, and in which the order of arguments is irrelevant.

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

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

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

structure option: keyword-constructor [name] ¶

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

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

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

structure option: type-descriptor name ¶

This option cannot be used with the type or named options.

By default, structures are implemented as records. The name of the structure is defined to hold the type descriptor of the record defined by the structure. The type-descriptor option specifies a different name to hold the type descriptor.

(define-structure foo a b)
foo             ⇒ #[record-type 18]

(define-structure (bar (type-descriptor <bar>)) a b)
bar             error→ Unbound variable: bar
<bar>         ⇒ #[record-type 19]

structure option: conc-name [name] ¶

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

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

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

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

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

structure option: type representation-type ¶

This option cannot be used with the type-descriptor option.

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

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

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

structure option: named [expression] ¶

This is valid only in conjunction with the type option and specifies that the structure instances be tagged to make them identifiable as instances of this structure type. This option cannot be used with the type-descriptor option.

In the usual case, where expression is not given, the named option causes a type descriptor and predicate to be defined for the structure (recall that the type option without named suppresses their definition), and also defines a default print method for the structure instances (which can be overridden by the print-procedure option). If the default print method is not wanted then the print-procedure option should be specified as #f. This causes the structure to be printed in its native representation, as a list or vector, which includes the type descriptor. The type descriptor is a unique object, not a record type, that describes the structure instances and is additionally stored in the structure instances to identify them: if the representation type is vector, the type descriptor is stored in the zero-th slot of the vector, and if the representation type is list, it is stored as the first element of the list.

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

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

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

structure option: safe-accessors [boolean] ¶

This option allows the programmer to have some control over the safety of the slot accessors (and modifiers) generated by define-structure. If safe-accessors is not specified, or if boolean is #f, then the accessors are optimized for speed at the expense of safety; when compiled, the accessors will turn into very fast inline sequences, usually one to three machine instructions in length. However, if safe-accessors is specified and boolean is either omitted or #t, then the accessors are optimized for safety, will check the type and structure of their argument, and will be close-coded.

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

structure option: initial-offset offset ¶

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

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

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

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

• The default constructor procedure takes positional arguments, in the same order as specified in the definition of the structure. A keyword constructor may be specified by giving the option keyword-constructor.
• BOA constructors are described using Scheme lambda lists. Since there is nothing corresponding to &aux in Scheme lambda lists, this functionality is not implemented.
• By default, no copier procedure is defined.
• The side-effect procedure corresponding to the accessor foo is given the name set-foo!.
• Keywords are ordinary symbols – use foo instead of :foo.
• The option values false, nil, true, and t are treated as if the appropriate boolean constant had been specified instead.
• The print-function option is named print-procedure. Its argument is a procedure of two arguments (the structure instance and a textual output port) rather than three as in Common Lisp.
• By default, named structures are tagged with a unique object of some kind. In Common Lisp, the structures are tagged with symbols. This depends on the Common Lisp package system to help generate unique tags; MIT/GNU Scheme has no such way to generate unique symbols.
• The named option may optionally take an argument, which is normally the name of a variable (any expression may be used, but it is evaluated whenever the tag name is needed). If used, structure instances will be tagged with that variable’s value. The variable must be defined when define-structure is evaluated.
• The type option is restricted to the values vector and list.
• The include option is not implemented.

2.11 Macros

(This section is largely taken from the Revised^4 Report on the Algorithmic Language Scheme. The section on Syntactic Closures is derived from a document written by Chris Hanson. The section on Explicit Renaming is derived from a document written by William Clinger.)

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 datums, 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.

MIT/GNU Scheme also supports anonymous syntactic keywords. This means that it’s not necessary to bind a macro transformer to a syntactic keyword before it is used. Instead, any macro-transformer expression can appear as the first element of a form, and the form will be expanded by the transformer.

The macro definition facility consists of these 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.
• A standard high-level pattern language for specifying macro transformers, introduced by the syntax-rules special form.
• Two non-standard low-level languages for specifying macro transformers, syntactic closures and explicit renaming.

The syntactic keyword of a macro may shadow variable bindings, and local variable bindings may shadow keyword bindings. All macros defined using the pattern language are “hygienic” and “referentially transparent” and thus preserve Scheme’s lexical scoping:

• 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.
• 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 may surround the use of the macro.

• Binding Constructs for Syntactic Keywords
• Pattern Language
• Syntactic Closures
• Explicit Renaming

(make-syntactic-closure env '() 'a) ⇒ an alias

2.12 SRFI syntax

Several special forms have been introduced to support some of the Scheme Requests for Implementation (SRFI). Note that MIT/GNU Scheme has for some time supported SRFI 23 (error-reporting mechanism) and SRFI 30 (nested multi-line comments), since these SRFIs reflect existing practice rather than introducing new functionality.

• cond-expand (SRFI 0)
• receive (SRFI 8)
• and-let* (SRFI 2)
• define-record-type (SRFI 9)

(call-with-values
  (lambda ()
    (partition (precedes pivot) others))
  (lambda (fore aft)
    (append (qsort fore) (cons pivot (qsort aft)))))

(receive (fore aft) (partition (precedes pivot) others)
  (append (qsort fore) (cons pivot (qsort aft))))

(and-let* ((list (compute-list))
           ((pair? list))
           (item (car list))
           ((integer? item)))
  (sqrt item))

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

(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

4.1 Numerical types

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

number
complex
real
rational
integer

For example, 3 is an integer. Therefore 3 is also a rational, a real, and a complex. The same is true of the Scheme numbers that model 3. For Scheme numbers, these types are defined by the predicates number?, complex?, real?, rational?, and integer?.

There is no simple relationship between a number’s type and its representation inside a computer. Although most implementations of Scheme will offer at least two different representations of 3, these different representations denote the same integer.

Scheme’s numerical operations treat numbers as abstract data, as independent of their representation as possible. Although an implementation of Scheme may use fixnum, flonum, and perhaps other representations for numbers, this should not be apparent to a casual programmer writing simple programs.

It is necessary, however, to distinguish between numbers that are represented exactly and those that may not be. For example, indexes into data structures must be known exactly, as must some polynomial coefficients in a symbolic algebra system. On the other hand, the results of measurements are inherently inexact, and irrational numbers may be approximated by rational and therefore inexact approximations. In order to catch uses of inexact numbers where exact numbers are required, Scheme explicitly distinguishes exact from inexact numbers. This distinction is orthogonal to the dimension of type.

4.2 Exactness

Scheme numbers are either exact or inexact. A number is exact if it was written as an exact constant or was derived from exact numbers using only exact operations. A number is inexact if it was written as an inexact constant, if it was derived using inexact ingredients, or if it was derived using inexact operations. Thus inexactness is a contagious property of a number.

If two implementations produce exact results for a computation that did not involve inexact intermediate results, the two ultimate results will be mathematically equivalent. This is generally not true of computations involving inexact numbers since approximate methods such as floating point arithmetic may be used, but it is the duty of each implementation to make the result as close as practical to the mathematically ideal result.

Rational operations such as + should always produce exact results when given exact arguments. If the operation is unable to produce an exact result, then it may either report the violation of an implementation restriction or it may silently coerce its result to an inexact value. See Implementation restrictions.

With the exception of exact, the operations described in this section must generally return inexact results when given any inexact arguments. An operation may, however, return an exact result if it can prove that the value of the result is unaffected by the inexactness of its arguments. For example, multiplication of any number by an exact zero may produce an exact zero result, even if the other argument is inexact.

4.3 Implementation restrictions

Implementations of Scheme are not required to implement the whole tower of subtypes (see Numerical types), but they must implement a coherent subset consistent with both the purposes of the implementation and the spirit of the Scheme language. For example, an implementation in which all numbers are real may still be quite useful.¹

Implementations may also support only a limited range of numbers of any type, subject to the requirements of this section. The supported range for exact numbers of any type may be different from the supported range for inexact numbers of that type. For example, an implementation that uses flonums to represent all its inexact real numbers may support a practically unbounded range of exact integers and rationals while limiting the range of inexact reals (and therefore the range of inexact integers and rationals) to the dynamic range of the flonum format. Furthermore the gaps between the representable inexact integers and rationals are likely to be very large in such an implementation as the limits of this range are approached.

An implementation of Scheme must support exact integers throughout the range of numbers that may be used for indexes of lists, vectors, and strings or that may result from computing the length of a list, vector, or string. The length, vector-length, and string-length procedures must return an exact integer, and it is an error to use anything but an exact integer as an index. Furthermore any integer constant within the index range, if expressed by an exact integer syntax, will indeed be read as an exact integer, regardless of any implementation restrictions that may apply outside this range. Finally, the procedures listed below will always return an exact integer result provided all their arguments are exact integers and the mathematically expected result is representable as an exact integer within the implementation:

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

Implementations are encouraged, but not required, to support exact integers and exact rationals of practically unlimited size and precision, and to implement the above procedures and the / procedure in such a way that they always return exact results when given exact arguments. If one of these procedures is unable to deliver an exact result when given exact arguments, then it may either report a violation of an implementation restriction or it may silently coerce its result to an inexact number. Such a coercion may cause an error later.

An implementation may use floating point and other approximate representation strategies for inexact numbers. This report recommends, but does not require, that the IEEE 32-bit and 64-bit floating point standards be followed by implementations that use flonum representations, and that implementations using other representations should match or exceed the precision achievable using these floating point standards.

In particular, implementations that use flonum representations must follow these rules: A flonum result must be represented with at least as much precision as is used to express any of the inexact arguments to that operation. It is desirable (but not required) for potentially inexact operations such as sqrt, when applied to exact arguments, to produce exact answers whenever possible (for example the square root of an exact 4 ought to be an exact 2). If, however, an exact number is operated upon so as to produce an inexact result (as by sqrt), and if the result is represented as a flonum, then the most precise flonum format available must be used; but if the result is represented in some other way then the representation must have at least as much precision as the most precise flonum format available.

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

4.4 Syntax of numerical constants

A number may be written in binary, octal, decimal, or hexadecimal by the use of a radix prefix. The radix prefixes are #b (binary), #o (octal), #d (decimal), and #x (hexadecimal). With no radix prefix, a number is assumed to be expressed in decimal.

A numerical constant may be specified to be either exact or inexact by a prefix. The prefixes are #e for exact, and #i for inexact. An exactness prefix may appear before or after any radix prefix that is used. If the written representation of a number has no exactness prefix, the constant may be either inexact or exact. It is inexact if it contains a decimal point, an exponent, or a # character in the place of a digit, otherwise it is exact.

In systems with inexact numbers of varying precisions it may be useful to specify the precision of a constant. For this purpose, numerical constants may be written with an exponent marker that indicates the desired precision of the inexact representation. The letters s, f, d, and l specify the use of short, single, double, and long precision, respectively. (When fewer than four internal inexact representations exist, the four size specifications are mapped onto those available. For example, an implementation with two internal representations may map short and single together and long and double together.) In addition, the exponent marker e specifies the default precision for the implementation. The default precision has at least as much precision as double, but implementations may wish to allow this default to be set by the user.

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

4.5 Numerical operations

See Entry Format, for a summary of the naming conventions used to specify restrictions on the types of arguments to numerical routines. The examples used in this section assume that any numerical constant written using an exact notation is indeed represented as an exact number. Some examples also assume that certain numerical constants written using an inexact notation can be represented without loss of accuracy; the inexact constants were chosen so that this is likely to be true in implementations that use flonums to represent inexact numbers.

procedure: number? object ¶

procedure: complex? object ¶

procedure: real? object ¶

procedure: rational? object ¶

procedure: integer? object ¶

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

If z is an inexact complex number, then (real? z) is true if and only if (zero? (imag-part z)) is true. If x is an inexact real number, then (integer? x) is true if and only if (= x (round x)).

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

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

procedure: exact? z ¶

procedure: inexact? z ¶

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

procedure: exact-integer? object ¶

procedure: exact-nonnegative-integer? object ¶

procedure: exact-rational? object ¶

These procedures test for some very common types of numbers. These tests could be written in terms of simpler predicates, but are more efficient.

procedure: = z1 z2 z3 … ¶

procedure: < x1 x2 x3 … ¶

procedure: > x1 x2 x3 … ¶

procedure: <= x1 x2 x3 … ¶

procedure: >= x1 x2 x3 … ¶

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

These predicates are transitive. Note that the traditional implementations of these predicates in Lisp-like languages are not transitive.

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

procedure: zero? z ¶

procedure: positive? x ¶

procedure: negative? x ¶

procedure: odd? x ¶

procedure: even? x ¶

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

procedure: max x1 x2 … ¶

procedure: min x1 x2 … ¶

These procedures return the maximum or minimum of their arguments.

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

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

procedure: + z1 … ¶

procedure: * z1 … ¶

These procedures return the sum or product of their arguments.

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

procedure: - z1 z2 … ¶

procedure: / z1 z2 … ¶

With two or more arguments, these procedures return the difference or quotient of their arguments, associating to the left. With one argument, however, they return the additive or multiplicative inverse of their argument.

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

procedure: 1+ z ¶

procedure: -1+ z ¶

(1+ z) is equivalent to (+ z 1); (-1+ z) is equivalent to (- z 1).

procedure: abs x ¶

Returns a real number with the magnitude of x and nonnegative sign bit. If x is a NaN, then the result has nonnegative sign bit and the payload of x, and is quiet if and only if x is quiet. Never raises a floating-point exception—not even for signalling NaN.

Abs is limited to real numbers. For the complex magnitude, use magnitude instead.

(abs -7)                ⇒  7
(abs 0.)                ⇒  0.
(abs -0.)               ⇒  0.
(abs -inf.0)            ⇒  +inf.0
(abs -snan.123)         ⇒  +snan.123
(abs 1+2i)              error→

procedure: copysign x1 x2 ¶

Returns a real number with the magnitude of x1 and the sign of x2. If x1 is a NaN, then the result has the payload of x1 and is quiet if and only if x1 is quiet. Never raises a floating-point exception—not even for signalling NaN.

(copysign 123 -1)              ⇒  -123
(copysign 0. -1)               ⇒  -0.
(copysign -0. 0.)              ⇒  0.
(copysign -nan.123 0.)         ⇒  +nan.123
(copysign +snan.123 -0.)       ⇒  -snan.123

procedure: euclidean/ n1 n2 ¶

procedure: floor/ n1 n2 ¶

procedure: ceiling/ n1 n2 ¶

procedure: truncate/ n1 n2 ¶

procedure: round/ n1 n2 ¶

These procedures implement number-theoretic (integer) division. Given a numerator n1 and denominator n2, they return two values n3 and n4, respectively quotient (an integer) and remainder, such that

n1 = (n2 * n3) + n4,

0 <= |n4| < |n2|.

The procedures differ in choice of quotient and remainder:

• euclidean/ chooses the remainder n4 to be nonnegative, so that 0 <= n4 < n2.

  (euclidean/ 15 4)       ⇒  3, 3
  (euclidean/ 13 4)       ⇒  3, 1
  (euclidean/ 13 -4)      ⇒  -3, 1
  (euclidean/ +1 4)       ⇒  0, 1
  (euclidean/ 0 4)        ⇒  0, 0
  (euclidean/ -1 4)       ⇒  -1, 3
  (euclidean/ -13 4)      ⇒  -4, 3
  (euclidean/ -13 -4)     ⇒  4, 3
  

  The quotient part of euclidean division, which can be computed without the remainder using euclidean-quotient, is an odd function of the denominator:

  (- (euclidean-quotient n1 (- n2)))
  = (euclidean-quotient n1 n2)
  

  The remainder part of euclidean division, which can be computed without the quotient using euclidean-remainder, is an even function of the denominator:

  (euclidean-remainder n1 (- n2))
  = (euclidean-remainder n1 n2)
  

  When the denominator n2 is a positive power of two, the quotient n3 of euclidean division coincides with the result of an arithmetic shift:

  (shift-right n1 s)
  = (euclidean-quotient n1 (expt 2 s))
  

• truncate/ chooses the quotient to have absolute value n3 = floor(|n1/n2|); in other words, truncate/ rounds the quotient n3 toward zero.

  (truncate/ 15 4)        ⇒  3, 3
  (truncate/ 13 4)        ⇒  3, 1
  (truncate/ 13 -4)       ⇒  -3, 1
  (truncate/ +1 4)        ⇒  0, 1
  (truncate/ 0 4)         ⇒  0, 0
  (truncate/ -1 4)        ⇒  0, -1
  (truncate/ -13 4)       ⇒  -3, -1
  (truncate/ -13 -4)      ⇒  3, -1
  

  If the remainder n4 is nonzero, then it is negative if and only if the numerator n1 is negative. Like euclidean division, the quotient n3 is an odd function of the denominator n2 and the remainder n4 is an even function of the denominator n2.

• floor/ chooses the quotient n3 to be floor(n1/n2); in other words, floor/ rounds the quotient n3 toward negative infinity.

  (floor/ 15 4)           ⇒  3, 3
  (floor/ 13 4)           ⇒  3, 1
  (floor/ 13 -4)          ⇒  -4, -3
  (floor/ +1 4)           ⇒  0, 1
  (floor/ 0 4)            ⇒  0, 0
  (floor/ -1 4)           ⇒  -1, 3
  (floor/ -13 4)          ⇒  -4, 3
  (floor/ -13 -4)         ⇒  3, -1
  

  If the remainder n4 is nonzero, then it is negative if and only if the denominator n2 is negative. Like euclidean division, when the denominator n2 is a positive power of two, the quotient n3 from floor/ coincides with the result of an arithmetic shift.

• ceiling/ chooses the quotient n3 to be ceil(n1/n2); in other words, ceiling/ rounds the quotient n3 toward positive infinity.

  (ceiling/ 15 4)         ⇒  4, -1
  (ceiling/ 13 4)         ⇒  4, -3
  (ceiling/ 13 -4)        ⇒  -3, 1
  (ceiling/ +1 4)         ⇒  1, -3
  (ceiling/ 0 4)          ⇒  0, 0
  (ceiling/ -1 4)         ⇒  0, -1
  (ceiling/ -13 4)        ⇒  -3, -1
  (ceiling/ -13 -4)       ⇒  4, 3
  

  If the remainder n4 is nonzero, then it is negative if and only if the denominator n2 is nonnegative. Ceiling/ is useful for determining, given a number of units, how many blocks of a fixed number of units are needed to store that many units and how much space is wasted.

• round/ chooses the quotient n3 to be the integer nearest to n1/n2, or if it is exactly halfway between two integers, then the nearest even integer; in other words, round/ implements the default IEEE 754 rounding mode of round-to-nearest/ties-to-even.

  (round/ 15 4)           ⇒  4, -1
  (round/ 13 4)           ⇒  3, 1
  (round/ 13 -4)          ⇒  -3, 1
  (round/ +1 4)           ⇒  0, 1
  (round/ 0 4)            ⇒  0, 0
  (round/ -1 4)           ⇒  0, -1
  (round/ -13 4)          ⇒  -3, -1
  (round/ -13 -4)         ⇒  3, -1
  

  Round/ guarantees that 0 <= |n4| < n2/2. Like euclidean division, the quotient n3 is an odd function of the denominator n2 and the remainder n4 is an even function of the denominator n2.

These procedures may also be applied to any real numbers, and are subject to inexact contagion:

(truncate/ -13 -4.0)    ⇒  3.0, -1.0   ; inexact
(floor/ 4.56 1.0)       ⇒  4.0, 0.56
(floor/ #e4.56 1)       ⇒  4, 14/25
(euclidean/ 7.853981633974483 (atan 0 -1))
                        ⇒  2.0, 1.5707963267948966

(These are not useful for precise floating-point argument reduction modulo 2\pi, e.g., in cos, sin, etc.; for that you need to represent \pi in extended precision.)

procedure: euclidean-quotient n1 n2 ¶

procedure: euclidean-remainder n1 n2 ¶

procedure: floor-quotient n1 n2 ¶

procedure: floor-remainder n1 n2 ¶

procedure: ceiling-quotient n1 n2 ¶

procedure: ceiling-remainder n1 n2 ¶

procedure: truncate-quotient n1 n2 ¶

procedure: truncate-remainder n1 n2 ¶

procedure: round-quotient n1 n2 ¶

procedure: round-remainder n1 n2 ¶

These procedures return only the quotient or remainder part of an integer division. For example, (floor/ n1 n2) is equivalent to:

(values (floor-quotient n1 n2)
        (floor-remainder n1 n2))

procedure: quotient n1 n2 ¶

procedure: remainder n1 n2 ¶

procedure: modulo n1 n2 ¶

procedure: integer-floor n1 n2 ¶

procedure: integer-ceiling n1 n2 ¶

procedure: integer-truncate n1 n2 ¶

procedure: integer-round n1 n2 ¶

Historic aliases for integer division routines, not applicable to non-integral rational or real numbers:

• quotient is an alias for truncate-quotient
• remainder is an alias for truncate-remainder
• modulo is an alias for floor-remainder
• integer-floor is an alias for floor-quotient
• integer-ceiling is an alias for ceiling-quotient
• integer-truncate is an alias for truncate-quotient
• integer-round is an alias for round-quotient

procedure: integer-divide n1 n2 ¶

procedure: integer-divide-quotient qr ¶

procedure: integer-divide-remainder qr ¶

Historic alias for truncate/ with a special data structure instead of multiple return values, not applicable to non-integral rational or real arguments. If qr is the result of (integer-divide n1 n2), then (truncate/ n1 n2) is equivalent to:

(values (integer-divide-quotient qr)
        (integer-divide-remainder qr))

procedure: gcd n1 … ¶

procedure: lcm n1 … ¶

These procedures return the greatest common divisor or least common multiple of their arguments. The result is always non-negative.

(gcd 32 -36)            ⇒  4
(gcd)                   ⇒  0

(lcm 32 -36)            ⇒  288
(lcm 32.0 -36)          ⇒  288.0  ; inexact
(lcm)                   ⇒  1

procedure: modexp b e m ¶

Modular exponentiation. Returns b^e mod m. b, e, and m must be exact integers; m must be nonzero. Mathematically equivalent to (modulo (expt b e) m), but works even for large inputs for which the intermediate (expt b e) would overflow memory.

(modexp 1234 5678 90)   ⇒  46
(modexp 2 (expt 2 1024) 299)
                        ⇒  55

procedure: numerator q ¶

procedure: denominator q ¶

These procedures return the numerator or denominator of their argument; the result is computed as if the argument was represented as a fraction in lowest terms. The denominator is always positive. The denominator of 0 is defined to be 1.

(numerator (/ 6 4))     ⇒  3
(denominator (/ 6 4))   ⇒  2
(denominator (inexact (/ 6 4)))
                        ⇒  2.0

procedure: floor x ¶

procedure: ceiling x ¶

procedure: truncate x ¶

procedure: round x ¶

These procedures return integers. floor returns the largest integer not larger than x. ceiling returns the smallest integer not smaller than x. truncate returns the integer closest to x whose absolute value is not larger than the absolute value of x. round returns the closest integer to x, rounding to even when x is halfway between two integers.

Rationale: round rounds to even for consistency with the rounding modes required by the IEEE floating point standard.

Note: If the argument to one of these procedures is inexact, then the result will also be inexact. If an exact value is needed, the result should be passed to the exact procedure (or use one of the procedures below).

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

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

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

procedure: floor->exact x ¶

procedure: ceiling->exact x ¶

procedure: truncate->exact x ¶

procedure: round->exact x ¶

These procedures are similar to the preceding procedures except that they always return an exact result. For example, the following are equivalent

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

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

procedure: rationalize x y ¶

procedure: rationalize->exact x y ¶

rationalize returns the simplest rational number differing from x by no more than y. A rational number r1 is simpler than another rational number r2 if r1=p1/q1 and r2=p2/q2 (both in lowest terms) and |p1|<=|p2| and |q1|<=|q2|. Thus 3/5 is simpler than 4/7. Although not all rationals are comparable in this ordering (consider 2/7 and 3/5) any interval contains a rational number that is simpler than every other rational number in that interval (the simpler 2/5 lies between 2/7 and 3/5). Note that 0=0/1 is the simplest rational of all.

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

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

procedure: simplest-rational x y ¶

procedure: simplest-exact-rational x y ¶

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

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

procedure: exp z ¶

procedure: log z ¶

procedure: sin z ¶

procedure: cos z ¶

procedure: tan z ¶

procedure: asin z ¶

procedure: acos z ¶

procedure: atan z ¶

procedure: atan y x ¶

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

In general, the mathematical functions log, arcsine, arccosine, and arctangent are multiply defined. For nonzero real x, the value of log x is defined to be the one whose imaginary part lies in the range minus pi (exclusive) to pi (inclusive). log 0 is undefined. The value of log z when z is complex is defined according to the formula With log defined this way, the values of arcsine, arccosine, and arctangent are according to the following formulae: The above specification follows Common Lisp: the Language, which in turn cites Principal Values and Branch Cuts in Complex APL; refer to these sources for more detailed discussion of branch cuts, boundary conditions, and implementation of these functions. When it is possible these procedures produce a real result from a real argument.

procedure: log1p z ¶

procedure: expm1 z ¶

Equivalent to:

log1p z = log(1 + z).
expm1 z = exp(z) - 1,

However, for real numbers close to zero, or for complex numbers near the circle of radius 1 about -1, these provide better approximations than (log (+ 1 z)) or (- (exp z) 1):

• Floating-point numbers have much higher density around 0 than around 1, so naive translation from near 0 to near 1 loses precision, and naive computation of a number near 1 loses precision even if it is followed by translation to near 0.
• The condition number of log near 1 is unbounded, while the condition number of log1p near 0 is near 1:

  x f'(x)/f(x) = [x/(1 + x)]/log(1 + x).
  

  

  (Conversely, the condition number of log near 0 approaches 0, while the condition number of log1p near -1 is unbounded, so for inputs near 0 it is better to compute them via log rather than via log1p.)

• Similarly, although the condition number of exp near 0 is near 0, its value near 0 is near 1, and the condition number of y - 1 is unbounded for y near 1, so the intermediate error introduced by (exp z) may be amplified arbitrarily by then computing (- (exp z) 1). In contrast, the condition number of expm1 itself near 0 is near 1, so it does not inherently amplify errors:

  x f'(x)/f(x) = x e^x/(e^x - 1).
  

  

On real numbers, the forward relative error of this implementation is determined by the system’s math library, usually below 1ulp.

On complex numbers:

• The forward relative error in complex magnitude is bounded by a small multiple of the system math library’s error for exp, expm1, log, log1p, sin, and cos.
• The componentwise forward relative error of log1p is bounded by a small multiple of the system math library’s error for log and log1p.
• The componentwise forward relative error of expm1 is bounded by a small multiple of the system math library’s error for exp, expm1, log, log1p, sin, and cos—except on x + i y where x is near zero and e^{-x} is near \cos y.

procedure: versin z ¶

procedure: exsec z ¶

procedure: aversin z ¶

procedure: aexsec z ¶

Zero-centered trigonometric functions related to cosine but well-conditioned near zero:

versin z = 1 - cos z
exsec z = (1 - cos z)/cos z

Both functions are well-conditioned near zero on the real line:

x versin'(x)/versin(x) = x sin(x)/(1 - cos(x)),
x exsec'(x)/exsec(x) = x tan(x)/(1 - cos(x)).

procedure: logp1 z ¶

Alias for log1p.

procedure: exp2 z ¶

procedure: exp10 z ¶

procedure: exp2m1 z ¶

procedure: exp10m1 z ¶

procedure: log2 z ¶

procedure: log10 z ¶

procedure: log2p1 z ¶

procedure: log10p1 z ¶

Base-2 and base-10 variants of exp, expm1, log, and log1p.

procedure: log1mexp x ¶

procedure: log1pexp x ¶

Equivalent to:

log1mexp x = log (1 - e^x),
log1pexp x = log (1 + e^x).

Like log1p and expm1, these avoid numerical pathologies with the intermediate quantities 1 - e^x and 1 + e^x and inputs to log near 1.

• log1mexp computes the complement of a probability p in log-space \log p, and as such is a self-inverse. It is finite when x < 0; negative infinity when x = 0; and invalid otherwise.
• log1pexp is related to the logistic function 1/(1 + e^{-x}) — specifically, it differs from the logarithm of the logistic function only by the sign of the input and the output.

This implementation gives forward relative error bounded by ten times the forward relative error bound of the system math library’s log and exp, which is usually below 1ulp.

Beware that although the forward relative error of the MIT/GNU Scheme implementations of these functions is bounded, these functions are ill-conditioned for large negative inputs:

x f'(x)/f(x) = (+/- x exp(x))/((1 +/- e^x) log(1 +/- e^x)),
  --> x,  for x << 0.

procedure: logistic x ¶

procedure: logit x ¶

Logistic and logit functions. Equivalent to:

logistic x = exp(x)/[1 + exp(x)] = 1/[1 + exp(-x)],
logit p = log p/(1 - p).

These functions are inverses of one another. The logit function maps a probablity p in [0, 1] into log-odds x in the extended real line, and the logistic function maps back from log-odds to probabilities.

• The logistic function is defined on the entire real line, but is ill-conditioned for large negative x, with condition number

  x f'(x)/f(x) = x exp(-x)/[1 + exp(-x)].
  

  

  The identity

  logistic(-x) = 1 - logistic(x)
  

  may help to rearrange a computation, along with the logistic-1/2 function which ranges from -1/2 to +1/2 and centered at zero rather than from 0 to 1 and centered at 1/2.

  This implementation gives forward relative error bounded by at most seven times the forward relative error bound of the system math library’s exp, which is usually below 1ulp.

• The logit function is defined on the closed unit interval [0, 1], but is ill-conditioned near 1/2 and 1, with condition number

  x f'(x)/f(x) = 1/[(1 - p) log(p/(1 - p))].
  

  

  The identity

  logit(1 - p) = -logit(p)
  

  may help to rearrange a computation, along with the logit1/2+ function which is defined on -1/2 to +1/2 and centered at zero rather than on 0 to 1 and centered at 1/2.

  This implementation gives forward relative error bounded by at most ten times the forward relative error bound of the system math library’s log, which is usually below 1ulp.

procedure: logistic-1/2 x ¶

procedure: logit1/2+ x ¶

Equivalent to:

logistic-1/2 x = logistic(x) - 1/2,
logit1/2+ p = logit(1/2 + p).

Like logistic and logit, these functions are inverses of one another; unlike logistic and logit, their domains and codomains are both centered at zero.

• The logistic-1/2 function is well-conditioned on the entire real line, with maximum condition number 1 at 0:

  x f'(x)/f(x) = 2 x e^-x / (1 - (e^-x)^2).
  

  

  This implementation gives forward relative error bounded by 5 times the forward relative error bound of the system math library’s exp, which is usually below 1ulp.

• The logit1/2+ function is defined on [-1/2, +1/2], and is ill-conditioned near -1/2 and +1/2:

  x f'(x)/f(x) = x/[(1 - 4 x^2) logit(1/2 + x)].
  

  

  For points near -1/2 or +1/2, it may be better to compute logit of a point near 0 instead. This implementation gives forward relative error bounded by 34 times the forward relative error bound of the system math library’s log, which is usually below 1ulp.

procedure: log-logistic x ¶

procedure: logit-exp x ¶

Equivalent to:

log-logistic x = log(logistic(x)) = log [1/(1 + exp(-x))]
logit-exp x = logit(exp(x)) = log [exp(x)/(1 - exp(x))]

Like logistic and logit, these functions are inverses of one another.

• The loglogistic function maps log-odds on the extended real line to logprobability on the nonpositive half of the extended real line, and is illconditioned for large positive x:

  x f'(x)/f(x) = (-x exp(-x))/[(1 + exp(-x)) log(1 + exp(-x))]
  

  
• The logitexp function maps log-probability on the nonpositive half of the extended real line to log-odds on the extended real line, and is illconditioned near \log(1/2):

  x f'(x)/f(x) = x/[(1 - exp(x)) log(exp(x)/(1 - exp(x)))]
  

  

This implementation gives forward relative error bounded by ten times the forward relative error bound of the system math library’s log and exp, which is usually below 1ulp.

procedure: logsumexp list ¶

List must be a list of real numbers x1, x2, …, xn. Returns an approximation to:

log(exp(x1) + exp(x2) + … + exp(xn)).

The computation avoids intermediate overflow; logsumexp returns +inf.0 if and only if one of the inputs is +inf.0.

procedure: sin-pi* x ¶

procedure: cos-pi* x ¶

procedure: tan-pi* x ¶

procedure: versin-pi* x ¶

procedure: exsec-pi* x ¶

procedure: asin/pi x ¶

procedure: acos/pi x ¶

procedure: atan/pi x ¶

procedure: atan2/pi y x ¶

procedure: aversin/pi x ¶

procedure: aexsec/pi x ¶

These procedures compute the standard trigonometric functions in units of half-revolutions rather than units of radians. Mathematically, (sin-pi* x) computes \sin(\pi x) and (asin/pi x) computes \arcsin(x)/\pi, etc.

procedure: sqrt z ¶

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

procedure: rsqrt z ¶

Returns the reciprocal of the principal square root of z.

procedure: sqrt1pm1 z ¶

Returns

sqrt(1 + z) - 1

This function is well-conditioned except for z near -1; the condition number is:

(z/2) / (z - (sqrt(1 + z) - 1))

Using (sqrt1pm1 z) instead of (- (sqrt (+ 1 z)) 1) avoids loss of precision when z is near 0.

procedure: expt z1 z2 ¶

Returns z1 raised to the power z2:

procedure: compound z1 z2 ¶

procedure: compoundm1 z1 z2 ¶

Compound returns (1 + z1)^z2, and compoundm1 returns (1 + z1)^z2 - 1, with low relative error even for z1 near zero.

procedure: make-rectangular x1 x2 ¶

procedure: make-polar x3 x4 ¶

procedure: real-part z ¶

procedure: imag-part z ¶

procedure: magnitude z ¶

procedure: angle z ¶

procedure: conjugate z ¶

Suppose x1, x2, x3, and x4 are real numbers and z is a complex number such that Then make-rectangular and make-polar return z, real-part returns x1, imag-part returns x2, magnitude returns x3, and angle returns x4. In the case of angle, whose value is not uniquely determined by the preceding rule, the value returned will be the one in the range minus pi (exclusive) to pi (inclusive).

conjugate returns the complex conjugate of z.

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

procedure: inexact z ¶

procedure: exact->inexact z ¶

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

The procedure exact->inexact has been deprecated by R7RS.

procedure: exact z ¶

procedure: inexact->exact z ¶

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

The procedure inexact->exact has been deprecated by R7RS.

4.6 Numerical input and output

procedure: number->string number [radix] ¶

Radix must be an exact integer, either 2, 8, 10, or 16. If omitted, radix defaults to 10. The procedure number->string takes a number and a radix and returns as a string an external representation of the given number in the given radix such that

(let ((number number)
      (radix radix))
  (eqv? number
        (string->number (number->string number radix)
                        radix)))

is true. It is an error if no possible result makes this expression true.

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

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

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

Rationale: If number is an inexact number represented using flonums, and the radix is 10, then the above expression is normally satisfied by a result containing a decimal point. The unspecified case allows for infinities, NaNs, and non-flonum representations.

variable: flonum-parser-fast? ¶

This variable controls the behavior of string->number when parsing inexact numbers. Specifically, it allows the user to trade off accuracy against speed.

When set to its default value, #f, the parser provides maximal accuracy, as required by the Scheme standard. If set to #t, the parser uses faster algorithms that will sometimes introduce small errors in the result. The errors affect a few of the least-significant bits of the result, and consequently can be tolerated by many applications.

variable: flonum-unparser-cutoff ¶

This variable is deprecated; use param:flonum-printer-cutoff instead.

parameter: param:flonum-printer-cutoff ¶

This parameter controls the action of number->string when number is a flonum (and consequently controls all printing of flonums). This parameter may be called with an argument to set its value.

The value of this parameter is normally a list of three items:

rounding-type

One of the following symbols: normal, relative, or absolute. The symbol normal means that the number should be printed with full precision. The symbol relative means that the number should be rounded to a specific number of digits. The symbol absolute means that the number should be rounded so that there are a specific number of digits to the right of the decimal point.

precision

An exact integer. If rounding-type is normal, precision is ignored. If rounding-type is relative, precision must be positive, and it specifies the number of digits to which the printed representation will be rounded. If rounding-type is absolute, the printed representation will be rounded precision digits to the right of the decimal point; if precision is negative, the representation is rounded (- precision) digits to the left of the decimal point.

format-type

One of the symbols: normal, scientific, or engineering. This specifies the format in which the number will be printed.
scientific specifies that the number will be printed using scientific notation: x.xxxeyyy. In other words, the number is printed as a significand between zero inclusive and ten exclusive, and an exponent. engineering is like scientific, except that the exponent is always a power of three, and the significand is constrained to be between zero inclusive and 1000 exclusive. If normal is specified, the number will be printed in positional notation if it is “small enough”, otherwise it is printed in scientific notation. A number is “small enough” when the number of digits that would be printed using positional notation does not exceed the number of digits of precision in the underlying floating-point number representation; IEEE 754-2008 binary64 floating-point numbers have 17 digits of precision.

This three-element list may be abbreviated in two ways. First, the symbol normal may be used, which is equivalent to the list (normal 0 normal). Second, the third element of the list, format-type, may be omitted, in which case it defaults to normal.

The default value for param:flonum-printer-cutoff is normal. If it is bound to a value different from those described here, number->string issues a warning and acts as though the value had been normal.

Some examples of param:flonum-printer-cutoff:

(number->string (* 4 (atan 1 1)))
                                    ⇒  "3.141592653589793"
(parameterize ((param:flonum-printer-cutoff '(relative 5)))
  (number->string (* 4 (atan 1 1))))
                                    ⇒  "3.1416"
(parameterize ((param:flonum-printer-cutoff '(relative 5)))
  (number->string (* 4000 (atan 1 1))))
                                    ⇒  "3141.6"
(parameterize ((param:flonum-printer-cutoff '(relative 5 scientific)))
  (number->string (* 4000 (atan 1 1))))
                                    ⇒  "3.1416e3"
(parameterize ((param:flonum-printer-cutoff '(relative 5 scientific)))
  (number->string (* 40000 (atan 1 1))))
                                    ⇒  "3.1416e4"
(parameterize ((param:flonum-printer-cutoff '(relative 5 engineering)))
  (number->string (* 40000 (atan 1 1))))
                                    ⇒  "31.416e3"
(parameterize ((param:flonum-printer-cutoff '(absolute 5)))
  (number->string (* 4 (atan 1 1))))
                                    ⇒  "3.14159"
(parameterize ((param:flonum-printer-cutoff '(absolute 5)))
  (number->string (* 4000 (atan 1 1))))
                                    ⇒  "3141.59265"
(parameterize ((param:flonum-printer-cutoff '(absolute -4)))
  (number->string (* 4e10 (atan 1 1))))
                                    ⇒  "31415930000."
(parameterize ((param:flonum-printer-cutoff '(absolute -4 scientific)))
  (number->string (* 4e10 (atan 1 1))))
                                    ⇒  "3.141593e10"
(parameterize ((param:flonum-printer-cutoff '(absolute -4 engineering)))
  (number->string (* 4e10 (atan 1 1))))
                                    ⇒  "31.41593e9"
(parameterize ((param:flonum-printer-cutoff '(absolute -5)))
  (number->string (* 4e10 (atan 1 1))))
                                    ⇒  "31415900000."

procedure: string->number string [radix] ¶

Returns a number of the maximally precise representation expressed by the given string. Radix must be an exact integer, either 2, 8, 10, or 16. If supplied, radix is a default radix that may be overridden by an explicit radix prefix in string (e.g. "#o177"). If radix is not supplied, then the default radix is 10. If string is not a syntactically valid notation for a number, then string->number returns #f.

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

Note that a numeric representation using a decimal point or an exponent marker is not recognized unless radix is 10.

4.7 Bit operations

This section describes operations on exact integers as strings of bits in two’s-complement representation. All arguments must be exact integers.

procedure: bitwise-not x ¶

Bitwise complement. Equivalent to (- -1 x).

procedure: bitwise-and x1 x2 … ¶

procedure: bitwise-andc2 x1 x2 ¶

procedure: bitwise-andc1 x1 x2 ¶

procedure: bitwise-xor x1 x2 … ¶

procedure: bitwise-ior x1 x2 … ¶

procedure: bitwise-nor x1 x2 ¶

procedure: bitwise-eqv x1 x2 … ¶

procedure: bitwise-orc2 x1 x2 ¶

procedure: bitwise-orc1 x1 x2 ¶

procedure: bitwise-nand x1 x2 ¶

Bitwise operations. The ‘c1’/‘c2’ variants take the complement of their first or second operand, respectively; for example, (bitwise-andc2 x1 x2) is equivalent to (bitwise-and x1 (bitwise-not x2)).

The four bitwise operations that are associative are extended to arbitrary numbers of arguments with an appropriate identity:

(bitwise-and)           ⇒ -1
(bitwise-xor)           ⇒ 0
(bitwise-ior)           ⇒ 0
(bitwise-eqv)           ⇒ -1

procedure: shift-left x n ¶

procedure: shift-right x n ¶

procedure: arithmetic-shift x n ¶

Multiplication and integer division by 2^n: (shift-left x n) is equivalent to (* x (expt 2 n)), and (shift-left x n) is equivalent to (euclidean-quotient x (expt 2 n)).

Shift-left and shift-right require n to be nonnegative; arithmetic-shift is equivalent to shift-left for positive n, and equivalent to shift-right for the negation of negative n.

procedure: bit-mask size position ¶

Returns an integer with size consecutive bits set starting at position, zero-based, and all other bits clear. Both arguments must be nonnegative.

(bit-mask 0 123)        ⇒ 0
(bit-mask 4 3)          ⇒ #b1111000

procedure: bit-antimask size position ¶

Returns an integer with size consecutive bits clear starting at position, zero-based, and all other bits set. Both arguments must be nonnegative. Equivalent to (bitwise-not (bit-mask size position)).

(bit-antimask 0 123)    ⇒ -1
(bit-antimask 4 3)      ⇒ #b-1111001  ; ‘#b...10000111’

procedure: bit-count x ¶

Returns the number of 1 bits in x, if it is nonnegative, or the number of 0 bits, if it is negative. Sometimes known as ‘pop count’ or ‘population count’.

procedure: hamming-distance x y ¶

Returns the Hamming distance between x and y—that is, the number of bits that differ in corresponding positions of their finite representations, or -1 if they have opposite signs (meaning that they differ in an infinite number of positions). Equivalent to (bit-count (bitwise-xor x y)).

(hamming-distance 1 3)          ⇒ 1
(hamming-distance 7 8)          ⇒ 4
(hamming-distance -8 -9)        ⇒ 4
(hamming-distance 1 -1)         ⇒ -1

procedure: integer-length x ¶

Returns the number of bit positions needed to represent x in two’s-complement: zero when x is zero; the exact value of (ceiling (/ (log x) (log 2))) when x is positive; (integer-length (bitwise-not x)) when x is negative.

(integer-length -129)           ⇒ 9
(integer-length -128)           ⇒ 8
(integer-length -127)           ⇒ 7
(integer-length -1)             ⇒ 0
(integer-length 0)              ⇒ 0
(integer-length 1)              ⇒ 1
(integer-length 127)            ⇒ 7
(integer-length 128)            ⇒ 8

procedure: first-set-bit x ¶

Returns the zero-based position of the first set bit in x. For zero, returns -1.

procedure: set-bit n x ¶

procedure: clear-bit n x ¶

procedure: toggle-bit n x ¶

procedure: extract-bit n x ¶

procedure: bit-set? n x ¶

procedure: bit-clear? n x ¶

Set-bit returns the integer x with the bit at position n set. Clear-bit returns the integer x with the bit at position n clear. Toggle-bit returns the integer x with the bit at position n in the opposite state.

Extract-bit returns the bit at position n in x as an integer, 0 or 1. Bit-set? returns true if that bit is set, false if clear. Bit-clear? returns false if that bit is set, true if clear.

procedure: bit n ¶

procedure: bits n m ¶

(bit n) returns a mask with the nth bit set and all other bits clear. (bits n m) returns a mask with bits n through m set, inclusive and zero-based, and all other bits clear. n and m may occur in either order.

(bit 7)                 ⇒ 128
(bits 4 5)              ⇒ #b110000
(bits 5 4)              ⇒ #b110000

procedure: shiftout x mask ¶

procedure: shiftin x mask ¶

mask must be a nonnegative integer with a contiguous substring of bits set, representing a contiguous field of bits.

(shiftout x mask) returns the corresponding value of that field in x; that is, (bitwise-and (shift-right x n) mask), where n is the position of the first set bit in mask.

(shiftin x mask) returns an an integer with that field set to x; that is, (shift-left x n).

Intended to be used with bit and bits. For example:

(define foo:x (bits 0 3))
(define foo:y (bits 4 5))
(define foo:z (bits 6 7))

(define (make-foo x y z)
  (bitwise-ior (shiftin x foo:x)
               (shiftin y foo:y)
               (shiftin z foo:z)))

(define (foo-x foo) (shiftout foo foo:x))
(define (foo-y foo) (shiftout foo foo:y))
(define (foo-z foo) (shiftout foo foo:z))

(make-foo 1 2 3)                ⇒ #b11100001
(foo-z (make-foo 1 2 3))        ⇒ 3

4.8 Fixnum and Flonum Operations

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

• Fixnum Operations
• Flonum Operations
• Floating-Point Environment
• Floating-Point Exceptions
• Floating-Point Rounding Mode

(let loop ((n 1))
  (if (fix:fixnum? n)
      (loop (* n 2))
      (- n 1)))