Pixie Scheme III Dictionary

This document has two parts:

• A Command Summary, that describes the procedures, special forms, macros, and the like, that are built in to Pixie Scheme III.

• A Glossary, that describes various terms and concepts used in discussions of Lisps and Schemes in general, and in Pixie Scheme III and its documentation in particular.

As an aid to finding things, here are some alphabetical indexes for entries in the dictionary.

Index for commands that are part of the R5 standard:

A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z

Index for commands that are Pixie Scheme III enhancements that begin with "e::":

A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z

Index for commands that are Pixie Scheme III enhancements that begin with "c::":

A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z

This portion of the document is a command summary of the procedures, special forms, macros, and the like, that are provided as part of Pixie Scheme III. It includes all of the standard Scheme stuff that Pixie Scheme III provides, and also includes many other items that I have provided as enhancements.

The command summary is a supplement to the "R5 report", but definitely not a substitute for it.

The descriptions herein are specific to Pixie Scheme III. Pixie Scheme III generally follows the "R5" Scheme report, but there are many places in that report where some behavior of Scheme is left undefined, or is allowed to be implementation-dependent. In those cases, this document describes what Pixie Scheme III does. For example, the R5 report often does not define the return values of procedures that are called for side effects: Pixie Scheme III generally returns #t from such procedures, and the descriptions herein so indicate.

The command summary is arranged alphabetically, with a few exceptions. First, procedures that are enhancements -- that is, they are not part of R5 Scheme -- are listed at the very end. Their identifiers all begin with either "e::" or "c::". The procedures that begin with "e::" come before the procedures that begin with "c::".

Second, a few closely-related groups of procedures are presented together. They include:

• The standard Scheme procedures "caar", "cadr", and the like, which are compositions of two or more instances of either "car" or "cdr". There are twenty-eight such procedures.

• The enhancements "e::bit-and" and the like, which provide conventional bitwise operations on 64-bit integers. There are seven such procedures.

• The enhancements "e::list-print-depth", "e::set-list-print-depth!", and the like, which control how much of long or deeply-nested lists or vectors Pixie Scheme III prints. There are eight such procedures.

There are other such groups.

Pixie Scheme III does contain procedures and such that are not documented here; I have omitted many things used internally by the compiler, macro-generator, and so on, because they are complicated and more than likely to change in subsequent releases. I do not personally regard them as secrets. If you find something undocumented that you would like to know more about, send me EMail and ask, but don't count on any undocumented feature continuing to exist in future releases of Pixie Scheme III.

General notes about the command summary entries:

• Remember that a feature of Scheme procedures is that when a procedure is called, all of its arguments are evaluated before the procedure starts to run, even if the procedure doesn't actually use them. For example, if you invoke the procedure "+" with arguments that are procedure calls, as "(+ (foo) (bar))", then the procedures "foo" and "bar" will be called first, and whatever they return will be passed to "+" as arguments.

• In contrast to procedures, when a special form or macro starts to run, it is not true that all of its arguments are evaluated first. In essence, a special form gets to decide for itself when -- and whether -- to evaluate each of its arguments. For example, if you invoke the special form "and" with arguments that are procedure calls, as "(and (foo) (bar))", "and" will first call "foo", then will decide whether or not to call "bar" depending on the value that "foo" returns. Or for example, the special form "set!" never evaluates its first argument; it takes that argument to be an identifier to be used as a variable name.

• Note in particular, that the evaluation of arguments passed to procedures, special forms, macros, and the like, may cause side effects. The "Side Effects" sections in the entries that follow are intended to tell whether the operation of the procedure, special form, or macro discussed intrinsically causes side effects, though in particularly notorious cases I do mention side effects that stem from evaluation of arguments.

• Pixie Scheme III's built-in procedures, special forms, and macros are pretty good about checking for proper argument type and quantity, and will by and large report an error if any argument is of the incorrect type, or if there are too many arguments, or too few. Error-reporting is described in this command summary only in cases of particular interest.

• In the official standard for Scheme, the value returned by many procedures is not defined. Pixie Scheme III generally returns #t in such cases. That may change in the future.

And now, on to the command summary itself ...

*

Type:

Procedure.

Operation:

Arithmetic multiplication.

Arguments:

Zero or more numbers.

Side Effects:

None.

Returned Value:

A number: With two or more arguments, returns their product. With one argument, returns just the argument. With no arguments, returns 1.

For Example:

(* 2 3)        ;; ==> 6
(* 1 2 3 4 5)  ;; ==> 120
(* 2.5)        ;; ==> 2.5
(*)            ;; ==> 1

+

Type:

Procedure.

Operation:

Arithmetic addition.

Arguments:

Zero or more numbers.

Side Effects:

None.

Returned Value:

A number: The sum of its arguments, or 0 if there are no arguments.

For Example:

(+ 2 3)        ;; ==> 5
(+ 1 2 3 4 5)  ;; ==> 15
(+ 2.5)        ;; ==> 2.5
(+)            ;; ==> 0

-

Type:

Procedure.

Operation:

Arithmetic subtraction.

Arguments:

One or more numbers.

Side Effects:

None.

Returned Value:

A number: With two or more arguments, returns the first argument minus the sum of all the rest. With one argument, returns the argument subtracted from zero.

For Example:

(- 2 3)        ;; ==> -1
(- 1 2 3 4 5)  ;; ==> -13
(- 2.5)        ;; ==> -2.5
(-)            ;; ==> <error>

/

Type:

Procedure.

Operation:

Arithmetic division.

Arguments:

One or more numbers.

Side Effects:

None.

Returned Value:

A number: With two or more arguments, returns the first argument divided by the product of all the rest. With one argument, returns its reciprocal. Returns a nan or an inf, as appropriate, for any attempt to divide by zero.

For Example:

(/ 6 3)        ;; ==> 2
(/ 3 4 5)      ;; ==> 0.15
(/ .5)         ;; ==> 2.
(/)            ;; ==> <error>
(/ 0)          ;; ==> <error>
(/ 2 0)        ;; ==> <error>
(/ 2 3 4 0 5)  ;; ==> <error>

<

Type:

Procedure.

Operation:

Arithmetic comparison: Less than.

Arguments:

Two or more real numbers.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, each argument is less than the one to its right. Otherwise, returns #f. Ignores the exactness of the arguments.

For Example:

(< 2 3)    ;; ==> #t
(< 3 2)    ;; ==> #f
(< 2 2)    ;; ==> #f
(< 2 3 4)  ;; ==> #t
(< 4 3 2)  ;; ==> #f

<=

Type:

Procedure.

Operation:

Arithmetic comparison: Less than or equal to.

Arguments:

Two or more real numbers.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, each argument is less than or equal to the one to its right. Otherwise, returns #f. Ignores the exactness of the arguments.

For Example:

(<= 2 3)    ;; ==> #t
(<= 3 2)    ;; ==> #f
(<= 2 2)    ;; ==> #t
(<= 2 3 4)  ;; ==> #t
(<= 4 3 2)  ;; ==> #f

=

Type:

Procedure.

Operation:

Arithmetic comparison: Equality

Arguments:

Two or more numbers.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, all arguments are arithmetically equal. Otherwise, returns #f. Ignores the exactness of the arguments.

For Example:

(= 2 3)    ;; ==> #f
(= 3 2)    ;; ==> #f
(= 2 2)    ;; ==> #t
(= 2 3 4)  ;; ==> #f
(= 4 3 2)  ;; ==> #f
(= 4 (+ 2 2) (/ 20 5)) ;; ==> #t

>

Type:

Procedure.

Operation:

Arithmetic comparison: Greater than.

Arguments:

Two or more real numbers.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, each argument is greater than the one to its right. Otherwise, returns #f. Ignores the exactness of the arguments.

For Example:

(> 2 3)    ;; ==> #f
(> 3 2)    ;; ==> #t
(> 2 2)    ;; ==> #f
(> 2 3 4)  ;; ==> #f
(> 4 3 2)  ;; ==> #t

>***<

Type:

Variable.

Operation:

The operation of Pixie Scheme III sets or binds this variable to the third most recent quantity whose value was printed out by the "print" part of the top-level read-eval-print loop. That is, the variable is the previous value of >**<, which is in turn the previous value of >*<, which is the most recent quantity printed out by the read-eval-print loop. This quantity is updated after the print has taken place; it may be used while Pixie Scheme III is evaluating an expression in the "read" part of the read-eval-print loop. It forms part of a rudimentary command-history mechanism that is contained within Pixie Scheme III.

Arguments:

(Does not apply.)

Side Effects:

(Does not apply.)

Returned Value:

(Does not apply.)

For Example:

(+ 0 1)
(+ 0 2)
(+ 0 3)

;;  At this point, and continuing through the
;;  evaluation of the next Scheme expression, >***<
;;  has the value 1.

>**<

Type:

Variable.

Operation:

The operation of Pixie Scheme III sets or binds this variable to the next-to-last quantity whose value was printed out by the "print" part of the top-level read-eval-print loop. That is, the variable is the previous value of >*<, which is the most recent quantity printed out by the read-eval-print loop. This quantity is updated after the print has taken place; it may be used while Pixie Scheme III is evaluating an expression in the "read" part of the read-eval-print loop. It forms part of a rudimentary command-history mechanism that is contained within Pixie Scheme III.

Arguments:

(Does not apply.)

Side Effects:

(Does not apply.)

Returned Value:

(Does not apply.)

For Example:

(+ 0 1)
(+ 0 2)
(+ 0 3)

;;  At this point, and continuing through the
;;  evaluation of the next Scheme expression, >**<
;;  has the value 2.

>*<

Type:

Variable.

Operation:

The operation of Pixie Scheme III sets or binds this variable to the last quantity whose value was printed out by the "print" part of the top-level read-eval-print loop. The quantity is updated after the print has taken place; it may be used while Pixie Scheme III is evaluating an expression in the "read" part of the read-eval-print loop. It forms part of a rudimentary command-history mechanism that is contained within Pixie Scheme III.

Arguments:

(Does not apply.)

Side Effects:

(Does not apply.)

Returned Value:

(Does not apply.)

For Example:

(+ 0 1)
(+ 0 2)
(+ 0 3)

;;  At this point, and continuing through the
;;  evaluation of the next Scheme expression, >*<
;;  has the value 3.

>+++<

Type:

Variable.

Operation:

The operation of Pixie Scheme III sets or binds this variables to the third most recent Scheme expression that was passed as input to the "read" part of the top-level read-eval-print loop. That is, the variable is the previous value of >++<, which is in turn the previous value of >+<, which is the most recent quantity provided as input to the read-eval-print loop. This quantity is updated after the print has taken place; it may be used while Pixie Scheme III is evaluating an expression in the "read" part of the read-eval-print loop. It forms part of a rudimentary command-history mechanism that is contained within Pixie Scheme III.

Arguments:

(Does not apply.)

Side Effects:

(Does not apply.)

Returned Value:

(Does not apply.)

For Example:

(+ 0 1)
(+ 0 2)
(+ 0 3)

;;  At this point, and continuing through the
;;  evaluation of the next Scheme expression, >+++<
;;  has the value (+ 0 1).

>++<

Type:

Variable.

Operation:

The operation of Pixie Scheme III sets or binds this variables to the next-to-last Scheme expression that was passed as input to the "read" part of the top-level read-eval-print loop. That is, the variable is the previous value of >+<, which is the most recent quantity provided as input to the read-eval-print loop. This quantities is updated after the print has taken place; it may be used while Pixie Scheme III is evaluating an expression in the "read" part of the read-eval-print loop. It forms part of a rudimentary command-history mechanism that is contained within Pixie Scheme III.

Arguments:

(Does not apply.)

Side Effects:

(Does not apply.)

Returned Value:

(Does not apply.)

For Example:

(+ 0 1)
(+ 0 2)
(+ 0 3)

;;  At this point, and continuing through the
;;  evaluation of the next Scheme expression, >++<
;;  has the value (+ 0 2).

>+<

Type:

Variable.

Operation:

The operation of Pixie Scheme III sets or binds this variables to the last Scheme expression that was passed as input to the "read" part of the top-level read-eval-print loop. This quantity is updated after the print has taken place; it may be used while Pixie Scheme III is evaluating an expression in the "read" part of the read-eval-print loop. It forms part of a rudimentary command-history mechanism that is contained within Pixie Scheme III.

Arguments:

(Does not apply.)

Side Effects:

(Does not apply.)

Returned Value:

(Does not apply.)

For Example:

(+ 0 1)
(+ 0 2)
(+ 0 3)

;;  At this point, and continuing through the
;;  evaluation of the next Scheme expression, >+<
;;  has the value (+ 0 3).

>-<

Type:

Variable.

Operation:

While Pixie Scheme III is evaluating a Scheme expression that was provided as input to the "read" part of the top-level read-eval-print loop, ">-<" is bound to that expression itself. This value will become the value of ">+<" after the expression has been evaluated and its result printed.

Arguments:

(Does not apply.)

Side Effects:

(Does not apply.)

Returned Value:

(Does not apply.)

For Example:

(+ 0 1)
(+ 0 2)
(+ 0 3)

;;  At this point, the value of >-< is undefined.
;;  But suppose you type

(define a (list >-<))

;;  and then type return.  Then, while the "define"
;;  is being evaluated, >-< will have the value
;;  (define a (list >-<)), so when you subsequently
;;  type

a

;;  Pixie Scheme III will print 

((define a (list >-<)))

>=

Type:

Procedure.

Operation:

Arithmetic comparison: Greater than or equal to.

Arguments:

Two or more real numbers.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, each argument is greater than or equal to the one on its right. Otherwise, returns #f. Ignores the exactness of the arguments.

For Example:

(>= 2 3)    ;; ==> #f
(>= 3 2)    ;; ==> #t
(>= 2 2)    ;; ==> #t
(>= 2 3 4)  ;; ==> #f
(>= 4 3 2)  ;; ==> #t

abs

Type:

Procedure.

Operation:

Arithmetic absolute value.

Arguments:

One real number.

Side Effects:

None.

Returned Value:

A number: The absolute value of the argument.

For Example:

(abs 3)   ;; ==> 3
(abs -3)  ;; ==> 3

acos

Type:

Procedure.

Operation:

Mathematical inverse cosine, or arc-cosine, function.

Arguments:

One number, in the range [-1, 1].

Side Effects:

None.

Returned Value:

A number: A number in the range [0, pi], taken as an angle in radians, whose cosine is the argument.

For Example:

(acos 1)   ;; ==> 0
(acos 0)   ;; ==> 1.5707963267948966
(acos -1)  ;; ==> 3.1415926535897931
(acos +i)  ;; ==> 1.5707963267948966-0.8813735870195428i

and

Type:

Macro.

Operation:

Boolean and.

Arguments:

Zero or more Scheme objects of any kind.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, all the arguments are true. (Recall that the only Scheme object that is false is #f.) With no arguments, returns #t. Otherwise, returns #f.

This macro operates by evaluating its arguments one at a time, from left to right. When and if any argument evaluates to false, "and" returns false immediately, without evaluating any more arguments.

For Example:

(and)        ;; ==> #t
(and #t)     ;; ==> #t
(and #f)     ;; ==> #f
(and #t #t)  ;; ==> #t
(and #f #t)  ;; ==> #f

(define (foo) (begin (display "foo ") #f))  ;; ==> foo
(define (bar) (begin (display "bar ") #t))  ;; ==> bar

(and (foo) (bar))                           ;; ==> foo #f
                                            ;;  It didn't print "bar".

angle

Type:

Procedure.

Operation:

Obtain the angle of a number.

Arguments:

One number.

Side Effects:

None.

Returned Value:

The angle of the number.

For Example:

(angle 1)   ;; ==> 0
(angle -1)  ;; ==> 3.1415926535897931
(angle +i)  ;; ==> 1.5707963267948966
(angle -i)  ;; ==> -1.5707963267948966

append

Type:

Procedure.

Operation:

Appends lists; that is, glues them together, head-to-tail. The last object "glued" need not be a list.

Arguments:

One or more arguments: All but the last of these must be proper lists. (A proper list is one that has finite length and is terminated by the empty list.) The last argument may be any Scheme object.

Side Effects:

None.

Returned Value:

Any Scheme object: With one argument, returns the argument. With more than one argument, builds a list from all but the last argument, by making copies of all of these lists and joining them in order, then makes the last argument be the cdr of the list so constructed, and returns that list.

For Example:

(append 1)                      ;; ==> 1
(append (list 1 2) (list 3 4))  ;; ==> (1 2 3 4)
(append (list 1 2) 3)           ;; ==> (1 2 . 3)

(define a (list 1 2 3))         ;; ==> a
(define b (list 4 5 6))         ;; ==> b
(define ab (append a b))        ;; ==> ab
a                               ;; ==> (1 2 3)
                                ;;  Not (1 2 3 4 5 6)
b                               ;; ==> (4 5 6)
ab                              ;; ==> (1 2 3 4 5 6)

;; But:

(set-cdr! (cddr b) 7)           ;; ==> #t
b                               ;; ==> (4 5 6 . 7)
ab                              ;; ==> (1 2 3 4 5 6 . 7)

(define c (list 1))             ;; ==> c
(set-cdr! c c)                  ;; ==> #t
c                               ;; ==> (1 1 1 1 1 1 1 1 1 1 1 ... ) 

(append c ab)                   ;; ==> <error>
                                ;; c is not a proper list.

apply

Type:

Procedure.

Operation:

Calls a procedure with a list of arguments.

Arguments:

Two or more arguments: The first must be a procedure, the last must be a proper list, and each of the others, if any, may be any Scheme object.

Side Effects:

None by itself, though the procedure applied may cause side effects of its own.

Returned Value:

Any Scheme object: Calls the given procedure -- the first argument -- with a list of arguments built as follows:

With two arguments, as in (apply proc args), where args is a list, "proc" is called with "args" as its arguments.

With more than two arguments, as in (apply proc arg1 arg2 ... argn args), "proc" is called with the argument list (append (list arg1 arg2 ... argn) args).

For Example:

(apply + (list 1 2))      ;; ==> 3   ;; Equivalent to (+ 1 2)
(apply + 1 2 (list 3 4))  ;; ==> 10  ;; Equivalent to 
                          ;;   (+ 1 2 3 4), and to
                          ;;   (apply + (list 1 2 3 4)

asin

Type:

Procedure.

Operation:

Mathematical inverse sine, or arc-sine, function.

Arguments:

One number, in the range [-1, 1].

Side Effects:

None.

Returned Value:

A number: A number in the range [-pi/2, pi/2], taken as an angle in radians, whose sine is the argument.

For Example:

(asin 1)   ;; ==> 1.5707963267948966
(asin 0)   ;; ==> 0
(asin -1)  ;; ==> -1.5707963267948966
(asin +i)  ;; ==> 0.8813735870195428i

assoc

Type:

Procedure.

Operation:

Look up a key-value pair in a list thereof, using "equal?" as the predicate for testing for the presence of the key.

Arguments:

Two arguments: The first may be any Scheme object; the second must be a proper list of pairs.

Side Effects:

None.

Returned Value:

A pair: Returns the first pair in the second argument whose car is "equal?" to the first argument, or returns #f if there is no such pair.

For Example:

(assoc 1 '((1 2) (3 4)))   ;; ==> (1 2)
(assoc 3 '((1 2) (3 4)))   ;; ==> (3 4)
(assoc 42 '((1 2) (3 4)))  ;; ==> #f

assq

Type:

Procedure.

Operation:

Look up a key-value pair in a list thereof, using "eq?" as the predicate for testing for the presence of the key.

Arguments:

Two arguments: The first may be any Scheme object; the second must be a proper list of pairs.

Side Effects:

None.

Returned Value:

A pair: Returns the first pair in the second argument whose car is "eq?" to the first argument, or returns #f if there is no such pair.

For Example:

(assq 1 '((1 2) (3 4)))   ;; ==> (1 2)
(assq 3 '((1 2) (3 4)))   ;; ==> (3 4)
(assq 42 '((1 2) (3 4)))  ;; ==> #f

(assq (list 1 2) '(((1 2) 'foo) ((3 4) 'bar))) ;; ==> #f

(define a (list 1 2))     ;; ==> a
(define pair-list (list (list a 'foo) (list (list 3 4) 'bar)))
                          ;; ==> pair-list

pair-list                 ;; ==> (((1 2) foo) ((3 4) bar))

(assq a pair-list)        ;; ==> ((1 2) foo) ;; The two "(1 2)"s refer
                          ;;      to the same object.

assv

Type:

Procedure.

Operation:

Look up a key-value pair in a list thereof, using "eqv?" as the predicate for testing for the presence of the key.

Arguments:

Two arguments: The first may be any Scheme object; the second must be a proper list of pairs.

Side Effects:

None.

Returned Value:

A pair: Returns the first pair in the second argument whose car is "eqv?" to the first argument, or returns #f if there is no such pair.

For Example:

(assv 1 '((1 2) (3 4)))   ;; ==> (1 2)
(assv 3 '((1 2) (3 4)))   ;; ==> (3 4)
(assv 42 '((1 2) (3 4)))  ;; ==> #f
(assv (list 1 2) '(((1 2) 'foo) ((3 4) 'bar)))  ;; ==> #f

(define a (list 1 2))     ;; ==> a
(define pair-list (list (list a 'foo) (list (list 3 4) 'bar)))
                          ;; ==> pair-list

pair-list                 ;; ==> (((1 2) foo) ((3 4) bar))
(assv a pair-list)        ;; ==> ((1 2) foo)

atan

Type:

Procedure.

Operation:

Mathematical inverse tangent, or arc-tangent, with one or two arguments. The two-argument version is called "atan2" by some.

Arguments:

One or two numbers.

Side Effects:

None.

Returned Value:

A number: With one argument, returns a number in the range [-pi/2, pi/2], taken as an angle in radians, whose tangent is the argument.

With two numbers, takes the arguments to be the coordinates of a point in the x/y plane, with the first argument being y and the second argument being x, and returns a number in the range (-pi, pi] which is the angle between the positive x-axis and the radius vector to that point. (The angle returned is negative if, and only if, y is negative.)

Note that (atan 0 0) returns 0. (The "R5" Scheme report appears to indicate that (atan 0 0) should return a value, but does not indicate what it should be.)

For Example:

(atan 1000)   ;; ==> 1.5697963271282296
(atan -1000)  ;; ==> -1.5697963271282296
(atan -1 0)   ;; ==> -1.5707963267948966
(atan 0 -1)   ;; ==> 3.1415926535897931
(atan +2i)    ;; ==> 1.5707963267948966+0.5493061443340549i

(atan -0.0000000001 -1000000000) ;; ==> -3.1415926535897931

(atan 0 0)    ;; ==> 0

begin

Type:

Special form.

Operation:

Evaluate a sequence of Scheme expressions in the order given.

Arguments:

One or more Scheme expressions of any kind.

Side Effects:

None.

Returned Value:

Any Scheme object: Causes the evaluation each of its arguments in turn, and returns whatever resulted from the evaluation of the last argument.

Note that "begin" does not create a new environment: Each evaluation that "begin" causes takes place in the environment where the "begin" was encountered.

For Example:

(begin 1 2 3 4)                                 ;; ==> 4
(begin (display "first ") (display "second "))  ;; ==> first second #t

;; In the top-level loop ...

(begin (define a 42) (define b 137))  ;; ==> b
a                                     ;; ==> 42
b                                     ;; ==> 137

boolean?

Type:

Procedure.

Operation:

Test whether its argument is a boolean.

Arguments:

One Scheme object of any kind.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is either #t or #f. Returns #f otherwise.

For Example:

(boolean? #t)        ;; ==> #t
(boolean? #f)        ;; ==> #t
(boolean 'whatever)  ;; ==> #f

call-with-current-continuation

Type:

Procedure.

Operation:

Creates an unnamed procedure of one argument, which encapsulates the current continuation in such a way that when that unnamed procedure is subsequently called, it will change the continuation that was present when the unnamed procedure was called to the continuation which is encapsulated. The unnamed procedure is passed as an argument to the procedure which is the argument to "call-with-current-continuation".

A continuation is in essence the entire internal state of the Scheme system. Thus when the unnamed procedure is called, it restores that state to whatever the state was when the unnamed procedure was created. If "call-with-current-continuation" was called during the middle of the execution of a particular Scheme procedure -- let's suppose that its name is "foo" -- then when the unnamed procedure thereby created is called, it will be as if "foo" was still running; "foo" will pick up right where "call-with-current-continuation" was called.

Recall that the unnamed procedure takes one argument. When it is called, whatever argument it was given appears in the restored continuation as if it had been returned from "call-with-current-continuation".

See the examples below for more details.

There is one rather technical caveat about the operation of "call-with-current-continuation": When the environment -- a complicated table of variable identifiers and their values -- is encapsulated into the current continuation, it is not copied; what is placed in the continuation is a reference, a pointer to the real environment. It is entirely possible that other Scheme procedures, such as "set!", will modify the real environment before the unnamed function created by "call-with-current-continuation" is called. Since the environment may have been modified, it is not correct to say that calling the unnamed function is guaranteed to restore the internal state of Scheme to what it was when the unnamed function was created.

The reason why the environment is not copied is that environments may be very large objects: They include everything in Scheme's memory that is not garbage. Thus there will often not be enough memory available to make a copy.

Arguments:

One argument, which must be a procedure that itself takes one argument.

Side Effects:

Saves the current state of Scheme in such a way that it can subsequently be restored at will.

Returned Value: Any Scheme object, or may never return:

The value returned will be either what the argument to "call-with-current-continuation" returns, or will be whatever value was passed to the unnamed procedure when -- and if -- that unnamed procedure was itself called.

For Example:

This first example is rather trivial. In it, the unnamed procedure prepared by "call-with-current-continuation" is passed as an argument to the predicate "procedure?", which does not call it -- "procedure?" simply affirms that that unnamed procedure is in fact a procedure, by returning #t.

(call-with-current-continuation procedure?)  ;; ==> #t

The second example is from the "R5" report. Let's discuss it in detail.

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

  ;; ==> -3

The procedure which is the argument to "call-with-current-continuation" begins on the second line of the example; it is the lambda expression that starts with "(lambda (exit) ...". The unnamed procedure created by "call-with-current-continuation" is passed to that lambda expression as an argument, and the lambda gives the unnamed procedure a name -- "exit".

The lambda expression itself uses the "for-each" procedure with another, shorter lambda expression, to test each number in the list of six numbers in the sixth line, to see whether it is negative. If the number is not negative, nothing happens -- the lambda expression goes on to the next number. If no number were negative, the "for-each" procedure that is running the test would end, and the outer lambda expression would returns #t, from the seventh line, so that "call-with-current-continuation" would thereby returns #t.

However, one of the numbers -- the fourth one -- is in fact negative; it's -3. When the test encounters it, the "if" will call "exit" with a value of -3. Since "exit" has as value the unnamed procedure originally created by "call-with-current-continuation", "exit" will immediately restore the continuation where it was created, and in effect, "call-with-current-continuation" will returns immediately, with a value of -3.

There are perhaps easier ways to find the first negative number in a list. Notwithstanding, this example illustrates how "call-with-current-continuation" can be used to returns a meaningful value from deep within a function, without somehow going back through all the intervening code. This facility is useful, for example, in reporting errors in a complicated process.

Continuations are complicated and confusing. It is unlikely that any introduction to them that is as short as this one can succeed in describing continuations adequately to a person who is not already familiar with them.

call-with-values

Type:

Procedure.

Operation:

Allow a procedure which returns multiple values to pass them as arguments to another procedure.

Arguments:

Two procedures. The first may return multiple values, via the "values" procedure. The second is the procedure to which the multiple values are intended to be passed; it will receive them as if they had been entered as individual arguments with the usual procedure-call syntax.

Side Effects:

None.

Returned Value:

Any Scheme object, or may not return: "call-with-values" in effect passes control to its second argument, and returns if and only if that procedure does, returning whatever that procedure returns.

For Example:

;; Here is a fancy way to add up the integers
;; from one through ten:  This example passes
;; the list returned by "values" to "+", just
;; as if you had entered
;;
;; (+ 1 2 3 4 5 6 7 8 9 10)

(call-with-values
  (lambda () (values 1 2 3 4 5 6 7 8 9 10))
  +)  ;; ==> 55

;; We could equally well just list the numbers:

(call-with-values
  (lambda () (values 1 2 3 4 5 6 7 8 9 10))
  list)

  ;; ==> (1 2 3 4 5 6 7 8 9 10)

;; This rather cute example is from the R5 report:
;; Remember that the procedure call "(*)" returns "1".

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

car

Type:

Procedure.

Operation:

Obtain the car of a pair.

Arguments:

One pair.

Side Effects:

None.

Returned Value:

Any Scheme object: The car of the argument.

For Example:

(car '(1 2))              ;; ==> 1
(car '(1 . 2))            ;; ==> 1
(car '(1))                ;; ==> 1
(car (list 1 2 3 4 5 6))  ;; ==> 1

cdr

Type:

Procedure.

Operation:

Obtain the cdr of a pair.

Arguments:

One pair.

Side Effects:

None.

Returned Value: Any Scheme object:

The cdr of the argument.

For Example:

(cdr '(1 2))              ;; ==> (2)
(cdr '(1 . 2))            ;; ==> 2
(cdr '(1))                ;; ==> ()
(cdr (list 1 2 3 4 5 6))  ;; ==> (2 3 4 5 6)

caar         cadr         cdar         cddr        

caaar       caadr       cadar       caddr      

cdaar       cdadr       cddar       cdddr      

caaaar     caaadr     caadar     caaddr    

cadaar     cadadr     caddar     cadddr    

cdaaar     cdaadr     cdadar     cdaddr    

cddaar     cddadr     cdddar     cddddr    

Type:

Procedures.

Operation:

Convenience procedures for accessing components of nested pairs.

Arguments:

One argument, which must be a pair, and whose car and cdr may also have specific type requirements, depending on the procedure.

Side Effects:

None.

Returned Value:

Any Scheme object:

Each of these procedures is a combination (technically, a composition) of from two to four applications of either "car" or "cdr". Two easy ways of figuring out which combination is intended are as follows:

Split the procedure name into individual letters, drop the initial "c" and the final "r", change each "a" into "the car of" and change each "d" into "the cdr of". Thus for example

cadar

becomes

c a d a r

which becomes

a d a 

which becomes

the car of the cdr of the car of 

And "(cadar x)" does indeed return the car of the cdr of the car of x.

Alternatively, in a particular procedure call, split the procedure name into individual letters, drop the initial "c" and the final "r", change each "a" into "car" and change each "d" into "cdr", and add enough parentheses to make sense. Thus for example:

(cadar x)

becomes

(c a d a r x)

which becomes

(a d a x)

which becomes

(car cdr car x)

which becomes

(car (cdr (car x)))

And "(cadar x)" does indeed return what "(car (cdr (car x)))" would.

Each of these procedures will report an error if its argument does not possess the correct pair structure to have the element that the procedure is intended to retrieve. Thus "(caddr (list 1 2))" will report an error, because "(list 1 2)" does not have a caddr.

For Example:

(define a (list 1 2 3 4 5 6))  ;; ==> a
(cadr a)                       ;; ==> 2
(cddr a)                       ;; ==> (3 4 5 6)
(cdar a)                       ;; ==> <error>
(caar a)                       ;; ==> <error>
(cdddr a)                      ;; ==> (4 5 6)
(cddddr a)                     ;; ==> (5 6)
(cadddr a)                     ;; ==> 4

(define b (list (list (list (list 'a))) 2 3 4))
                               ;; ==> b
b                              ;; ==> ((((a))) 2 3 4)
(car b)                        ;; ==> (((a)))
(caar b)                       ;; ==> ((a))
(caaar b)                      ;; ==> (a)
(caaaar b)                     ;; ==> a

;; et cetera ad nauseam

case

Type:

Macro.

Operation:

Evaluates an expression -- the "key" -- and compares the result (using "eqv?") to each element in the car of each of a series of lists -- the case clauses -- in turn. If a match is found, evaluates each element of the cdr of that case clause in left-to-right order, and returns whatever results from the evaluation of the last element.

If there is no match, there may be an "else" clause -- whose car is just "else" -- as the last clause of the case. If there is an "else" clause, evaluates each element of the cdr of the else clause in left-to-right order, and returns whatever results from the evaluation of the last element. If there is no match, and no else clause, returns #t.

Arguments:

One Scheme expression, followed by one or more proper lists, each of which has as its car either a proper list, or the symbol "else". The symbol "else" may only appear as the car of the last proper list of the "case" expression, and that last proper list need not necessarily begin with "else".

Side Effects:

None in its own right, but the evaluation of items in the clauses may cause arbitrary side effects.

Returned Value:

Arbitrary, depending on the clauses; may not return at all, depending on the clauses.

For Example:

(case (+ 1 0)
  ((1 3) 'first)
  ((2 3) 'second)
  (else 'third)
  )  ;; ==> first
(case 2
  ((1 3) 'first)
  ((2 3) 'second)
  (else 'third)
  )  ;; ==> second
(case 3
  ((1 3) 'first)
  ((2 3) 'second)
  (else 'third)
  )  ;; ==> first
(case 4
  ((1 3) 'first)
  ((2 3) 'second)
  (else 'third)
  )  ;; ==> third
(case 4
  ((1 3) 'first)
  ((2 3) 'second)
  )  ;; ==> #t

ceiling

Type:

Procedure.

Operation:

Arithmetic round up.

Arguments:

One real number.

Side Effects:

None.

Returned Value:

An integer: The smallest integer not smaller than the argument.

For Example:

(ceiling -6.5)  ;; ==> -6.
(ceiling 4)     ;; ==> 4

char->integer

Type:

Procedure.

Operation:

Convert a character to the integer that represents it; Pixie Scheme III uses the ASCII standard for representing characters by integers.

Arguments:

One character.

Side Effects:

None.

Returned Value:

An integer: The integer whose ASCII character is the argument.

For Example:

(char->integer #\C)        ;; ==> 67
(char->integer #\newline)  ;; ==> 10

char-alphabetic?

Type:

Procedure.

Operation:

Test whether the argument is a letter of the alphabet.

Arguments:

One character/

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a letter of the alphabet, in either upper case or lower case. Otherwise, returns false.

For Example:

(char-alphabetic? #\a)  ;; ==> #t
(char-alphabetic? #\!)  ;; ==> #f

char-ci<=?

Type:

Procedure.

Operation:

Case-independently test the whether the integer representation of the first argument is less than or equal to the integer representation of the second. Pixie Scheme III implements case-independence by converting any argument that is an upper-case letter to lower case before proceeding with the comparison.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Converts any argument that is an upper-case letter to lower case, and returns #t if, and only if, the integer whose ASCII character then represents the first argument is less than or equal to the integer whose ASCII character then represents the second argument. Otherwise, returns #f.

For Example:

(char-ci<=? #\a #\A)  ;; ==> #t
(char-ci<=? #\A #\b)  ;; ==> #t
(char-ci<=? #\a #\B)  ;; ==> #t
(char-ci<=? #\B #\a)  ;; ==> #f
(char-ci<=? #\b #\A)  ;; ==> #f
(char-ci<=? #\a #\[)  ;; ==> #f
(char-ci<=? #\A #\[)  ;; ==> #f

char-ci<?

Type:

Procedure.

Operation:

Case-independently test the whether the integer representation of the first argument is less than the integer representation of the second. Pixie Scheme III implements case-independence by converting any argument that is an upper-case letter to lower case before proceeding with the comparison.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Converts any argument that is an upper-case letter to lower case, and returns #t if, and only if, the integer whose ASCII character then represents the first argument is less than the integer whose ASCII character then represents the second argument. Otherwise, returns #f.

For Example:

(char-ci<? #\a #\A)  ;; ==> #f
(char-ci<? #\A #\b)  ;; ==> #t
(char-ci<? #\a #\B)  ;; ==> #t
(char-ci<? #\B #\a)  ;; ==> #f
(char-ci<? #\b #\A)  ;; ==> #f
(char-ci<? #\a #\[)  ;; ==> #f
(char-ci<? #\A #\[)  ;; ==> #f

char-ci=?

Type:

Procedure.

Operation:

Case-independently test the whether the integer representation of the first argument is equal to the integer representation of the second. Pixie Scheme III implements case-independence by converting any argument that is an upper-case letter to lower case before proceeding with the comparison.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Converts any argument that is an upper-case letter to lower case, and returns #t if, and only if, the integer whose ASCII character then represents the first argument is equal to the integer whose ASCII character then represents the second argument. Otherwise, returns #f.

For Example:

(char-ci=? #\a #\A)  ;; ==> #t
(char-ci=? #\A #\b)  ;; ==> #f
(char-ci=? #\a #\B)  ;; ==> #f
(char-ci=? #\B #\a)  ;; ==> #f
(char-ci=? #\b #\A)  ;; ==> #f
(char-ci=? #\a #\[)  ;; ==> #f
(char-ci=? #\A #\[)  ;; ==> #f

char-ci>=?

Type:

Procedure.

Operation:

Case-independently test the whether the integer representation of the first argument is greater than or equal to the integer representation of the second. Pixie Scheme III implements case-independence by converting any argument that is an upper-case letter to lower case before proceeding with the comparison.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Converts any argument that is an upper-case letter to lower case, and returns #t if, and only if, the integer whose ASCII character then represents the first argument is greater than or equal to the integer whose ASCII character then represents the second argument. Otherwise, returns #f.

For Example:

(char-ci>=? #\a #\A)  ;; ==> #t
(char-ci>=? #\A #\b)  ;; ==> #f
(char-ci>=? #\a #\B)  ;; ==> #f
(char-ci>=? #\B #\a)  ;; ==> #t
(char-ci>=? #\b #\A)  ;; ==> #t
(char-ci>=? #\a #\[)  ;; ==> #t
(char-ci>=? #\A #\[)  ;; ==> #t

char-ci>?

Type:

Procedure.

Operation:

Case-independently test the whether the integer representation of the first argument is greater than the integer representation of the second. Pixie Scheme III implements case-independence by converting any argument that is an upper-case letter to lower case before proceeding with the comparison.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Converts any argument that is an upper-case letter to lower case, and returns #t if, and only if, the integer whose ASCII character then represents the first argument is greater than the integer whose ASCII character then represents the second argument. Otherwise, returns #f.

For Example:

(char-ci>? #\a #\A)  ;; ==> #f
(char-ci>? #\A #\b)  ;; ==> #f
(char-ci>? #\a #\B)  ;; ==> #f
(char-ci>? #\B #\a)  ;; ==> #t
(char-ci>? #\b #\A)  ;; ==> #t
(char-ci>? #\a #\[)  ;; ==> #t
(char-ci>? #\A #\[)  ;; ==> #t

char-downcase

Type:

Procedure.

Operation:

Convert a character to lower case.

Arguments:

One character.

Side Effects:

None.

Returned Value:

A character: If the argument is an upper case letter, returns it in lower case, otherwise returns it unchanged.

For Example:

(char-downcase #\A)  ;; ==> #\a
(char-downcase #\a)  ;; ==> #\a
(char-downcase #\!)  ;; ==> #\!

char-lower-case?

Type:

Procedure.

Operation:

Test whether an alphabetic character is in lower case.

Arguments:

One alphabetic character.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is in lower case. Otherwise, returns #f.

For Example:

(char-lower-case? #\a)  ;; ==> #t
(char-lower-case? #\A)  ;; ==> #f
(char-lower-case? #\!)  ;; ==> <error>

char-numeric?

Type:

Procedure.

Operation:

Test whether a character is a decimal digit.

Arguments:

One character.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a decimal digit. Otherwise, returns #f.

For Example:

(char-numeric? #\3)  ;; ==> #t
(char-numeric? #\a)  ;; ==> #f

char-ready?

Type:

Procedure.

Operation:

Test whether there is a character or an eof-object ready to read on a port.

Arguments:

Either none, or one port.

Side Effects:

None.

Returned Value:

A boolean: The procedure performs a test for whether or not there is a character to be read from a port. If there is an argument, it is taken to be the port to be tested. If not, the port tested is whatever is returned by the procedure "current-input-port".

Returns #t if, and only if, there is either a character to be read from the port, or the port will return an end-of-file object. Otherwise, returns #f.

Interactive ports, such as the console (keyboard) will never return an end-of-file object.

For Example:

;; From the console, at top-level:

(char-ready ?) ;; ==> #t  ;; The character is the "return"
                           ;;   that sent the text
                           ;;   "(char-ready?)"
                           ;;   to Pixie Scheme III.

(define (foo) (read-char) (char-ready?)) ;; ==> foo
(foo) ;; ==> #f   ;; "read-char" read past the "return".

;; Suppose "port" is an input port to a file containing
;; just the text "abc".

(char-ready? port)  ;; ==> #t
(read-char port)    ;; ==> #\a
(char-ready? port)  ;; ==> #t
(read-char port)    ;; ==> #\b
(char-ready? port)  ;; ==> #t
(read-char port)    ;; ==> #\c
(char-ready? port)  ;; ==> #t
(read-char port)    ;; ==> #<End of File>  ;; How Pixie Scheme III
                                            ;; displays an 
                                            ;; end-of-file object.
(char-ready? port)  ;; ==> #t
(read-char port)    ;; ==> #<End of File>
(char-ready? port)  ;; ==> #t
(read-char port)    ;; ==> #<End of File>
(char-ready? port)  ;; ==> #t
(read-char port)    ;; ==> #<End of File>

;; To infinity, and beyond ...

char-upcase

Type:

Procedure.

Operation:

Convert a character to upper case.

Arguments:

One character.

Side Effects:

None.

Returned Value:

A character: If the argument is a lower case letter, returns it in upper case, otherwise returns it unchanged.

For Example:

(char-upcase #\A)  ;; ==> #\A
(char-upcase #\a)  ;; ==> #\A
(char-upcase #\!)  ;; ==> #\!

char-upper-case?

Type:

Procedure.

Operation:

Test whether an alphabetic character is in upper case.

Arguments:

One alphabetic character.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is in upper case. Otherwise, returns #f.

For Example:

(char-upper-case? #\a)  ;; ==> #f
(char-upper-case? #\A)  ;; ==> #t
(char-upper-case? #\!)  ;; ==> <error>

char-whitespace?

Type:

Procedure.

Operation:

Test whether a character is white space; that is, whether it is a space, tab, line feed, form feed, or carriage-return.

Arguments:

One character.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is white space. Otherwise, returns #t

For Example:

(char-whitespace? #\a)      ;; ==> #f
(char-whitespace? #\space)  ;; ==> #t

char<=?

Type:

Procedure.

Operation:

Test whether the integer representation of the first argument is less than or equal to the integer representation of the second.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the integer whose ASCII character represents the first argument is less than or equal to the integer whose ASCII character represents the second argument. Otherwise, returns #f.

For Example:

(char<=? #\a #\A)  ;; ==> #t
(char<=? #\A #\b)  ;; ==> #t
(char<=? #\a #\B)  ;; ==> #f
(char<=? #\B #\a)  ;; ==> #t
(char<=? #\b #\A)  ;; ==> #f
(char<=? #\a #\[)  ;; ==> #f
(char<=? #\A #\[)  ;; ==> #t

char<?

Type:

Procedure.

Operation:

Test whether the integer representation of the first argument is less than the integer representation of the second.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the integer whose ASCII character represents the first argument is less than to the integer whose ASCII character represents the second argument. Otherwise, returns #f.

For Example:

(char<? #\a #\A)  ;; ==> #f
(char<? #\A #\b)  ;; ==> #t
(char<? #\a #\B)  ;; ==> #f
(char<? #\B #\a)  ;; ==> #t
(char<? #\b #\A)  ;; ==> #f
(char<? #\a #\[)  ;; ==> #f
(char<? #\A #\[)  ;; ==> #t

char=?

Type:

Procedure.

Operation:

Test whether the first argument is equal to the second.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first argument is equal to the second. Otherwise, returns #f.

For Example:

(char=? #\a #\A)  ;; ==> #f
(char=? #\A #\b)  ;; ==> #f
(char=? #\a #\B)  ;; ==> #f
(char=? #\B #\a)  ;; ==> #f
(char=? #\b #\A)  ;; ==> #f
(char=? #\a #\[)  ;; ==> #f
(char=? #\A #\[)  ;; ==> #f

char>=?

Type:

Procedure.

Operation:

Test whether the integer representation of the first argument is greater than or equal to the integer representation of the second.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the integer whose ASCII character represents the first argument is greater than or equal to the integer whose ASCII character represents the second argument. Otherwise, returns #f.

For Example:

(char>=? #\a #\A)  ;; ==> #t
(char>=? #\A #\b)  ;; ==> #f
(char>=? #\a #\B)  ;; ==> #t
(char>=? #\B #\a)  ;; ==> #f
(char>=? #\b #\A)  ;; ==> #t
(char>=? #\a #\[)  ;; ==> #t
(char>=? #\A #\[)  ;; ==> #f

char>?

Type:

Procedure.

Operation:

Test whether the integer representation of the first argument is greater than the integer representation of the second.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the integer whose ASCII character represents the first argument is greater than the integer whose ASCII character represents the second argument. Otherwise, returns #f.

For Example:

(char>=? #\a #\A)  ;; ==> #f
(char>=? #\A #\b)  ;; ==> #f
(char>=? #\a #\B)  ;; ==> #t
(char>=? #\B #\a)  ;; ==> #f
(char>=? #\b #\A)  ;; ==> #t
(char>=? #\a #\[)  ;; ==> #t
(char>=? #\A #\[)  ;; ==> #f

char?

Type:

Procedure.

Operation:

Test whether the argument is a character.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a character. Otherwise, returns #f.

For Example:

(char? #\a)  ;; ==> #t
(char? #\!)  ;; ==> #t
(char? 42)   ;; ==> #f

complex?

Type:

Procedure.

Operation:

Test whether the argument is a complex number.

Arguments:

One scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a complex number. Otherwise, returns #f. Informally, "complex?" returns #t for every number except nans and infs, because every such number lies somewhere in the complex plane. All of Pixie Scheme III's numbers lie on the real axis, but they are nonetheless in the complex plane.

For Example:

(complex? 0)                  ;; ==> #t
(complex? (expt 10 1000000))  ;; ==> #f   ;; It's an inf.
(complex? #t)                 ;; ==> #f

cond

Type:

Macro.

Operation:

Examines a series of given clauses, each of which must be a proper list. For each clause in turn, evaluates the car of the list: If that car is true, the evaluates all the rest of the items in the list in turn, and returns whatever the last item evaluates to. If the car is false, goes on to the next given clause. If no given clause has a car that evaluates to true, returns #t. The last of the given clauses may start with the symbol "else", which is treated as if it were #t.

Arguments:

One or more proper lists, the last of which may have "else" as car.

Side Effects:

None in its own right, but the evaluation of items in the clauses may cause arbitrary side effects.

Returned Value:

Arbitrary, depending on the clauses; may not return at all, depending on the clauses.

For Example:

(cond (#f 1) (#f 2) (#f 3))            ;; ==> #t
(cond (#f 1) (#f 2) (#t 3))            ;; ==> 3
(cond (#f 1) (#f 2) (#t 3 4 (+ 5 6)))  ;; ==> 11
(cond (#f 1) (#f 2) (else 3))          ;; ==> 3
(cond 
  ((= (* 6 9) 42) 'peculiar)
  ((= (* 6 9) 54) 'mundane)
  )                                    ;; ==> mundane

cons

Type:

Procedure.

Operation:

Allocate storage for a newly-formed pair.

Arguments:

Two Scheme objects.

Side Effects:

Allocates main memory.

Returned Value:

A pair whose car is the first argument and whose cdr is the second argument. If the first argument is an item represented by a pointer to Scheme memory, then the car of the returned pair is "eq?" to the second argument. If the second argument is an item represented by a pointer to Scheme memory, then the cdr of the returned pair is "eq?" to the second argument.

For Example:

(cons 1 2)               ;; ==> (1 . 2)
(cons 'a '())            ;; ==> (a)
(cons 1 (list 2 3 4 5))  ;; ==> (1 2 3 4 5)

(cons (list 1 2 3) (list 4 5 6))
                         ;; ==> ((1 2 3) 4 5 6)

cos

Type:

Procedure.

Operation:

Mathematical cosine.

Arguments:

One number, taken to be an angle in radians.

Side Effects:

None.

Returned Value:

A number: The cosine of the argument.

For Example:

(cos 0)  ;; ==> 1
(cos 1.5707963267948966)
         ;; ==> 6.123031769111886e-17  ;;  Very nearly zero.
(cos 0.7853981633974483)
         ;; ==> 0.7071067811865476
(cos +i) ;; ==> 1.5430806348152437

current-input-port

Type:

Procedure.

Operation:

Returns the port from which input is presently being taken.

Arguments:

None.

Side Effects:

None.

Returned Value:

A port: The port from which input is presently being taken.

For Example:

;; When input is being taken from the keyboard:

(current-input-port)  ;; ==> #<Console Input Port>

current-output-port

Type:

Procedure.

Operation:

Returns the port from to which output is presently being sent.

Arguments:

None.

Side Effects:

None.

Returned Value:

A port: The port from which input is presently being taken.

For Example:

;; When input is being sent to the display:

(current-output-port)  ;; ==> #<Console Output Port>

define

Type:

Special form.

Operation:

Sets or binds an identifier to a value in the top-level environment, or, as an internal definition, in an environment associated with a procedure or special form.

Arguments:

There are three syntaxes:

First syntax: Two arguments, the first an identifier and the second any Scheme object.

Second syntax: Two or more arguments, the first a proper list of one or more identifiers, and the rest any Scheme objects.

Third syntax: Two or more arguments, the first a list of identifiers to which is appended a final identifier; that is, a list of the form (identifier1 identifier2 ... identifierN-1 . identifierN), the noteworthy feature being the dot before the final identifier, and the rest any Scheme objects.

Side Effects:

First Syntax: If the first argument has never had a value or binding in the relevant environment, gives it one. If a previous binding or value of the first argument does exist in the relevant environment, modifies it. In either case, the first argument ends up with the second argument as its value or binding, (depending on whether the second argument is of a kind that requires a binding).

In the case of internal definitions, the argument cannot have a previous binding, since the syntax restricts such definitions to the beginning of the lexical scope for the environment in question.

Second Syntax: The second syntax is shorthand, or "syntactic sugar" for binding an identifier to a lambda expression. The first element of the first argument is taken to be the identifier. The remaining elements of the first argument are taken to be the formal arguments to the lambda expression. The remaining arguments are taken to be the contents of the body of the lambda expression. Thus

(define (name var1 var2 ... varN)
  expression1
  expression2
    ...
  expressionN
  )

is equivalent to

(define name
  (lambda (var1 var2 ... varN)
    expression1
    expression2
      ...
    expressionN
    )
  )

Third Syntax: The second syntax is shorthand, or "syntactic sugar" for binding an identifier to a lambda expression. The first element of the first argument is taken to be the identifier. The remaining elements, of the first argument, except the one after the dot, are taken to be formal arguments to the lambda expression, and the identifier after the dot has bound to it a list of any remaining actual arguments to the lambda expression when it is called. The remaining arguments to "define" are taken to be the contents of the body of the lambda expression. Thus

(define (name var1 var2 ... varN-1 . varN)
  expression1
  expression2
    ...
  expressionN
  )

is equivalent to

(define name
  (lambda (var1 var2 ... varN-1 . varN)
    expression1
    expression2
      ...
    expressionN
    )
  )

and

(define (name . var)
  expression1
  expression2
    ...
  expressionN
  )

is equivalent to

(define name
  (lambda var
    expression1
    expression2
      ...
    expressionN
    )
  )

Returned Value:

First syntax: the first argument.

Second and third syntaxes: the first element of the first argument.

For Example:

(define a 42)      ;; ==> a
a                  ;; ==> 42

(define a 'foo)    ;; ==> a
a                  ;; ==> foo

(define (hypotenuse x y)
  (sqrt (+ (* x x) (* y y))))
                   ;; ==> hypotenuse
(hypotenuse 5 12)  ;; ==> 13

(define (foo a) (display a))  ;; ==> foo
(foo 1 2 3 4 5)               ;; ==> (1 2 3 4 5)#t

(define (foo b . c)
  (display b)
  (display c))     ;; ==> foo
(foo 1 2 3 4 5)    ;; ==> 1(2 3 4 5)#t

define-syntax

Type:

Macro.

Operation:

Define an hygienic macro at top-level.

Arguments:

One symbol and one <transformer spec>, the latter according to the grammar of "R5" report section 4.3.2.

Side Effects:

If the first argument has never had a value or binding in the top-level environment, gives it one. If a previous binding or value of the first argument does exist in the top-level environment, modifies it. In either case, the first argument ends up with the macro transformer corresponding to the second argument, as its a binding.

Returned Value:

The first argument.

For Example:

(define-syntax
   when
   (syntax-rules ()
     ((when test stmt) (if test stmt))
     ((when test stmt ...) (if test (begin stmt ...))
     )))
  ;; ==> when

(when #t 3)  ;; ==> 3
(when #f 3)  ;; ==> #f

(when #t (display "foo\n") (display "bar\n") 42)  ;; ==>
foo
bar
42

delay

Type:

Macro.

Operation:

Encapsulate a Scheme expression in such a way that it can be evaluated subsequently, by the "force" procedure, and its value then returned.

Arguments:

One Scheme object of any kind.

Side Effects:

None in its own right; side effects due to the eventual evaluation of the argument may occur, depending on the argument.

Returned Value:

A promise.

For Example:

;; Note how Pixie Scheme III displays a promise:

(delay (display "Carpe diem\n"))  ;; ==> #<Promise>

(define foo (delay (begin (display "Carpe diem\n") 123)))
                   ;; ==> foo
(force foo)        ;; ==>
Carpe diem         ;;  Side effect of evaluation.
123                ;;  The returned value.
(force foo)        ;; ==>
123                ;;  Evaluation happens only once --
                   ;;    the returned value is saved so
                   ;;    it may be returned repeatedly.
(force foo)        ;; ==> 123

display

Type:

Procedure.

Operation:

Output an external representation of a Scheme object in a form intended easily to be read by sentient beings. Contrast with "write", whose output is intended easily to be read by computers and programmers ...

Arguments:

One or two arguments. The first may be any Scheme object. The second, if present, must be an open output port.

Side Effects:

Writes output -- if there is a second argument, to that port, otherwise, to the current output port.

Returned Value:

#t

For Example:

(display "This string\nhas three\nembedded newlines.\n")  ;; ==>
This string
has three
embedded newlines.
#t
(display 5/7)  ;; ==> 0.7142857142857143#t

(let ((my-port (open-output-file "Foo")))
  (display 5/7 my-port)
  (close-output-port my-port))  ;; ==> #t  ;;  And writes to "Foo".

do

Type:

Macro.

Operation:

Perform iteration, testing a termination condition before each iteration; optionally, create an environment, with local variables, in which the iterations are to be performed, and with means of initializing those values and bindings, and of changing them during successive iterations.

CAUTION: Pixie Scheme's III implementation of "do" is abysmally slow, and uses vast amounts of memory.

Technical Note: Pixie Scheme III needs "do" because the R5 standard requires it. The present release provides a version that works, but I suggest that you avoid it when you can. I may get around to writing a better implementation some day, but that is a low-priority task: I don't use "do" much myself.

Arguments:

At least two:

The first argument is a proper list, each of whose arguments is a list of two or three elements. The first is an identifier, the second an initial value or binding for the identifier, and the third, if present, an expression to be evaluated after each iteration, whose evaluation provides the value or binding for the identifier for the next iteration.

The second argument is a proper list of two or more arguments. The first is a test to be evaluated before each iteration; if it evaluates to true, no further iterations are performed, the remaining elements of the second argument are evaluated in sequence, and the "do" returns the result of the last such evaluation. If the test evaluates to false, the next iteration is performed.

The remaining arguments are evaluated in sequence during each iteration.

Side Effects:

None in its own right, but possibly many in consequence of the nature of the arguments.

Note that Pixie Scheme III's present implementation of "do" is very slow and uses lots of memory.

Returned Value:

Any Scheme object, depending on the arguments; or the do may never return.

For Example:

(do ((vec (make-vector 3))
     (k 0 (+ k 1)))
    ((= k 3) vec)
  (vector-set! vec k (* k k)))  ;; ==> #(0 1 4)

The syntax of "do" is sometimes confusing. Let me put some comments and some extra words into the previous example, to make it clearer: Think of the italicized words as comments.

(do

    ;; List of initialization-and-update clauses:
    ;; Each specifies a variable name, its initial
    ;;   value, and any automatic update to it, that
    ;;   takes place after each pass through the loop.

    ((vec (make-vector 3))  ;; No automatic change to vec.
     (k   0 (+ k 1)))       ;; Change k to (+ k 1) after each loop.

  ;; Loop test and body follow ...

  (if (= k 3)
    then-return vec)        ;; ((= k 3)) would stop the do but
                            ;;   return an undefined value.
  else
    (vector-set! vec k (* k k))

  ;; Update variables as specified in the clauses for
  ;;   initialization-and-update -- e.g., replace k by
  ;;   (+ k 1) -- and then go back for another pass
  ;;   through the loop test and body.

  )

  ;; ==> #(0 1 4)

dynamic-wind

Type:

Procedure.

Operation:

Force two given procedures to be called when execution respectively enters and leaves the dynamic extent of another given procedure. The first argument is to be called on entry to the dynamic extent of the second, and the third on exit from the dynamic extent of the second.

Arguments:

Three procedures, each of which must accept no arguments.

Side Effects:

None in its own right, but the given procedures may have side effects of their own.

Returned Value:

Whatever the second argument returns, if it returns at all.

For Example:

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

  ;; ==> (connect talk1 disconnect connect talk2 disconnect)

else

Type:

Reserved identifier, for use in "cond", which see.

Operation:

None.

Arguments:

Does not apply.

Side Effects:

Does not apply.

Returned Value:

Does not apply.

For Example:

See "cond".

eof-object?

Type:

Procedure.

Operation:

Test whether the argument is an end-of-file object.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean. Returns #t if, and only if, the argument is an end-of-file object. Otherwise, returns #f.

For Example:

;; Suppose foo is an input port to a file containing
;; three characters, and that Pixie Scheme III has already
;; read those characters.

(eof-object? (read-char? foo))  ;; ==> #t
(eof-object? 42)                ;; ==> #f

eq?

Type:

Procedure.

Operation:

Test whether two Scheme objects are the same in the sense that either

(1) the objects are of the same kind, and the same region of Scheme main memory is used to store both, so that any alteration of one object necessarily alters the other (this form of identity is sometimes called "pointer equality"), or

(2) the objects are of the same kind, and each can be represented entirely within the 64-bit pointer field of a Scheme tagged pointer, and the necessary 64-bit representations are identical.

Technical Note: The behavior of "eq?" is allowed to be implementation-dependent; what Pixie Scheme III does is first make sure that the objects are the same kind, and if so, return #t if, and only if, their pointer fields are identical, or if they are certain objects such as #t, #f and '(), which do not require the pointer field at all.

Arguments:

Two Scheme objects.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if the two arguments are identical in the sense described in the "Operation" section above.. Otherwise, returns #f.

For Example:

(eq? 1 1)      ;; ==> #t
(eq? 1 2)      ;; ==> #f
(eq? #\a #\a)  ;; ==> #t
(eq? #\a #\b)  ;; ==> #f
(eq? #t #t)    ;; ==> #t
(eq? #t #f)    ;; ==> #f

(define a (list 1 2))    ;; ==> a
(define b (cons a '()))  ;; ==> b
(eq? a (car b))          ;; ==> #t

(define c (list 1 2))        ;; ==> c
(eq? a c)                    ;; ==> #f  
                             ;; Two different lists.

(eq? (list 1 2) (list 1 2))  ;; ==> #f  ;; Ditto.

equal?

Type:

Procedure.

Operation:

Test for equality of Scheme objects by recursively descending through pairs, lists, vectors, and strings, and applying "eqv?" to compare their contents where further recursive descent does not occur.

Arguments:

Two Scheme objects.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the arguments are equal in the sense described in the "Operation" section above. Otherwise, returns #f. May not return, if the data structures being compared are circular.

For Example:

(equal? 1 1)      ;; ==> #t
(equal? 1 2)      ;; ==> #f
(equal? #\a #\a)  ;; ==> #t
(equal? #\a #\b)  ;; ==> #f
(equal? #t #t)    ;; ==> #t
(equal? #t #f)    ;; ==> #f

(define a (list 1 2))    ;; ==> a
(define b (cons a '()))  ;; ==> b
(equal? a (car b))       ;; ==> #t

(define c (list 1 2))
(equal? a c)             ;; ==> #t
                         ;; Different lists notwithstanding.

(equal? (list 1 2) (list 1 2))  ;; ==> #t  ;; Ditto.

eqv?

Type:

Procedure.

Operation:

Test whether two Scheme objects should "normally be regarded as the same object" (according to the R5 report). What Pixie Scheme III does is return #t if the objects are "eq?", or if they are both numbers, both have the same value, and are either both exact or both inexact.

Technical Note: Much of the vagueness in the R5 definition of "eqv?" stems from the prospect that some Scheme implementations may upon occasion be able to prove that functions that do not have identical source code always return the same value when given the same arguments. Pixie Scheme III makes no pretensions of ever being able to do any such thing; it returns #t from an "eqv?" test on functions only in case of pointer identity.

Arguments:

Two Scheme objects.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if the arguments are "eq?". If not, returns #t if the arguments are both numbers, and have the same numeric value, and are either both exact or both inexact. Otherwise, returns #f.

For Example:

(eqv? 1 1)      ;; ==> #t
(eqv? 1 2)      ;; ==> #f
(eqv? #\a #\a)  ;; ==> #t
(eqv? #\a #\b)  ;; ==> #f
(eqv? #t #t)    ;; ==> #t
(eqv? #t #f)    ;; ==> #f

(define a (list 1 2))    ;; ==> a
(define b (cons a '()))  ;; ==> b
(eqv? a (car b))         ;; ==> #t

(define c (list 1 2))
(eqv? a c)                    ;; ==> #f
                              ;; Two different lists.

(eqv? (list 1 2) (list 1 2))  ;; ==> #f  ;; Ditto.

(eqv? 1 #e1.0)  ;; ==> #t
(eqv? 1 #i1.0)  ;; ==> #f

eval

Type:

Procedure.

Operation:

Evaluate an expression in a specified environment.

Arguments:

One Scheme object, and one instance of what is returned by one of the procedures "interaction-environment", "null-environment", or "scheme-machine-environment".

Side Effects:

None in its own right, but the side effects of evaluating an expression may be substantial.

Returned Value:

The result of the evaluation.

For Example:

(eval '(+ 2 2) (interaction-environment))
;; ==> 4
(eval '(+ 2 2) (scheme-report-environment 5))
;; ==> 4
(eval '(+ 2 2) (null-environment 5))
;; ==> <error>  ;; "+" is not defined in the null environment.
(eval '(if #t 2 3) (null-environment 5))
;; ==> 2
(define a 42)
;; ==> a
a
;; ==> 42
(let ((a 3)) a)
;; ==> 3
(let ((a 3)) (eval 'a (interaction-environment)))
;; ==> 42

even?

Type:

Procedure.

Operation:

Test whether an integer is even.

Arguments:

One integer.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is an even number. Otherwise, returns #f.

For Example:

(even? 42)   ;; ==> #t
(even? 137)  ;; ==> #f

exact->inexact

Type:

Procedure.

Operation:

Create an inexact representation of a number.

Arguments:

One number.

Side Effects:

None.

Returned Value:

An inexact number whose value is the same as the argument.

For Example:

(exact->inexact 1)    ;; ==> 1.
(exact->inexact #i1)  ;; ==> 1.
(exact->inexact +i)   ;; ==> 1.i

exact?

Type:

Procedure.

Operation:

Test whether a number is exact.

Arguments:

One number.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is exact. Otherwise, returns #f.

For Example:

(exact? 1)   ;; ==> #t
(exact? 1.)  ;; ==> #f

exp

Type:

Procedure.

Operation:

Mathematical exponentiation.

Arguments:

One number.

Side Effects:

None.

Returned Value:

A number: Returns the base of the natural logarithms raised to the argument.

For Example:

(exp 0)                    ;; ==> 1
(exp 1)                    ;; ==> 2.7182818284590451
(exp -2.5)                 ;; ==> 0.0820849986238988
(exp 3.1415926535897931i)  ;; ==> -1.+1.2246467991473532e-16i

expt

Type:

Procedure.

Operation:

Raise a number to a power.

Arguments:

Two numbers. Reports an error when Pixie Scheme's III numeric types cannot express the result, e.g., for the square root of -1.

Side Effects:

None.

Returned Value:

The first argument raised to the second argument.

For Example:

(expt 2 3)                          ;; ==> 8
(expt 3 2)                          ;; ==> 9
(expt 2 0.5)                        ;; ==> 1.4142135623730951
(expt 1.4142135623730951 0.5)       ;; ==> 1.189207115002721
(expt -1 0.5)                       ;; ==> 6.123233995736766e-17+1.i
(expt (exp 1) 3.1415926535897931i)  ;; ==> -1.+1.2246467991473532e-16i

floor

Type:

Procedure.

Operation:

Arithmetic round down.

Arguments:

One real number.

Side Effects:

None.

Returned Value:

An integer: The largest integer not larger than the argument.

For Example:

(floor -6.5)  ;; ==> -7.
(floor 4)   ;; ==> 4

for-each

Type:

Procedure.

Operation:

Call a procedure many times, with different arguments, in a specified order.

Arguments:

Two or more. The first argument is the procedure to call. The rest must all be proper lists of the same length, and the number of arguments beyond the first must equal the number of arguments with which the procedure is to be called. On the first call, the arguments passed to the procedure are the first elements of each list, in the same order as the lists. On the second call, the passed arguments are the second elements of the lists, and so on.

Side Effects:

None in its own right, but the intended purpose of "for-each" is to call a procedure repeatedly, for side effects, so there will likely be side effects, depending on the arguments.

Returned Value:

#t

For Example:

(define (make-sandwich first second bread)
  (display first)
  (display " and ")
  (display second)
  (display " on ")
  (display bread)
  (newline)
  'yum)  ;; ==> make-sandwich
(for-each
  make-sandwich
  (list "ham" "tuna" "tofu" "peanut butter")
  (list "cheese" "tomato" "sprouts" "asparagus")
  (list "rye" "whole wheat" "seven-grain" "banana bread")
  )  ;; ==>
ham and cheese on rye
tuna and tomato on whole wheat
tofu and sprouts on seven-grain
peanut butter and asparagus on banana bread
#t

force

Type:

Procedure.

Operation:

Cause the evaluation of a Scheme expression previously encapsulated as a promise, for lazy evaluation, by the "delay" procedure; or if that promise has already been forced, return whatever value it returned at that time.

Arguments:

One promise.

Side Effects:

None in its own right, though the evaluation of the promise may cause side effects, depending on the nature of the promise.

Returned Value:

As promised.

For Example:

;; Note how Pixie Scheme III displays a promise:

(delay (display "Carpe diem\n"))  ;; ==> #<Promise>

(define foo (delay (begin (display "Carpe diem\n") 123)))
    ;; ==> foo

(force foo)        ;; ==>
Carpe diem         ;; Side effect of evaluation.
123                ;; The returned value.
(force foo)        ;; ==>
123                ;; Evaluation happens only once --
                   ;;   the returned value is saved so
                   ;;   it may be returned repeatedly.
(force foo)        ;; ==>
123

gcd

Type:

Procedure.

Operation:

Mathematical greatest common divisor.

Arguments:

One or more integers.

Side Effects:

None.

Returned Value:

An integer: Returns the greatest common divisor of the two arguments.

For Example:

(gcd 28 98)                ;; ==> 14
(gcd 999999999999 209457)  ;; ==> 333

if

Type:

Macro.

Operation:

Conditional evaluation, based on a test.

Arguments:

Two or three Scheme objects.

Side Effects:

None in its own right, others depending on the arguments.

Returned Value:

Evaluates the first argument: If the result is true, evaluates the second argument and returns the result of so doing. If the first argument evaluates to false, and there is a third argument, returns the result of evaluating the third argument. If the first argument evaluates to false, and there is no third argument, returns #f.

For Example:

(if #t (+ 1 2) (+ 3 4))  ;; ==> 3
(if #f (+ 1 2) (+ 3 4))  ;; ==> 7
(if #f (+ 1 2))          ;; ==> #f

imag-part

Type:

Procedure.

Operation:

Obtain the imaginary part of a number.

Arguments:

One number.

Side Effects:

None.

Returned Value:

The imaginary part of the number.

For Example:

(imag-part 1)     ;; ==> 0
(imag-part +i)    ;; ==> 1
(imag-part 1.+i)  ;; ==> 1.

inexact->exact

Type:

Procedure.

Operation:

Create an exact representation of a number.

Arguments:

One number.

Side Effects:

None.

Returned Value:

An exact number whose value is the same as the argument.

For Example:

(inexact->exact 1)    ;; ==> 1
(inexact->exact #i1)  ;; ==> 1
(inexact->exact 1.i)  ;; ==> +i

inexact?

Type:

Procedure.

Operation:

Test whether a number is inexact.

Arguments:

One number.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is inexact. Otherwise, returns #f.

For Example:

(inexact? 1)   ;; ==> #f
(inexact? 1.)  ;; ==> #t

input-port?

Type:

Procedure.

Operation:

Test whether the argument is an input port.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is an input port. Otherwise, returns #f. Note that once an input port has been closed, it is no longer a port in the sense of the R5 report, because it cannot deliver characters on demand.

For Example:

(define foo (open-input-file "This.file.must.exist"))  ;; ==> foo
(input-port? foo)       ;; ==> #t
(close-input-port foo)  ;; ==> #t
(input-port? foo)       ;; ==> #f
(input-port? 42)        ;; ==> #f

integer->char

Type:

Procedure.

Operation:

Determine the ASCII character represented by the argument.

Arguments:

One integer in the range [0..127]

Side Effects:

None.

Returned Value:

A character: Returns the ASCII character represented by the argument.

For Example:

(integer->char 65)   ;; ==> #\A
(integer->char 128)  ;; ==> <error>

integer?

Type:

Procedure.

Operation:

Test whether the argument is an integer.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is an integer. Otherwise, returns #f.

For Example:

(integer? 3)    ;; ==> #t
(integer? 3.1)  ;; ==> #f

;; Technically, an integer is a real number with no fractional
;; part.  The floating-point representations used by Pixie
;; Scheme III do not contain enough bits to represent the
;; fractional parts of numbers of large absolute value, hence
;; such numbers are necessarily reported as integers.  Thus:

(integer? (/ 1.e100 3))  ;; ==> #t

;; Note that in Pixie Scheme III

(/ 1.e100 3)  ;; ==> 3.3333333333333332e99

;; which is 33333333333333332 followed by lots of zeros --
;; unarguably the external representation of an integer.

interaction-environment

Type:

Procedure.

Operation:

Return the Scheme environment in which expressions typed in the top-level read-eval-print loop are evaluated.

Arguments:

None.

Side Effects:

None.

Returned Value:

The top-level environment of Pixie Scheme III.

For Example:

(eval '(+ 2 2) (interaction-environment))
4

lambda

Type:

Special form.

Operation:

Create an unnamed procedure

Arguments:

Two or more. There are three syntaxes:

First syntax: Two or more arguments, the first a proper list of one or more identifiers, and the rest any Scheme objects.

Second syntax: Two or more arguments, the first a list of identifiers to which is appended a final identifier; that is, a list of the form (identifier1 identifier2 ... identifierN-1 . identifierN), the noteworthy feature being the dot before the final identifier, and the rest any Scheme objects.

Third syntax: Two or more arguments, the first an identifier and the rest any Scheme objects.

Side Effects:

None.

Returned Value:

A lambda expression. The arguments after the first are the body of the lambda expression. The meaning of the first argument varies:

First syntax: The first argument is a list of the formal arguments of the lambda expression.

Second syntax: All elements of the first argument before the dot are taken to be formal arguments to the lambda expression, and the identifier after the dot will have a list of any remaining actual arguments to the lambda expression bound to it when the lambda expression is called.

Third syntax: The first argument will have a list of all actual arguments to the lambda expression bound to it when the lambda expression is called.

For Example:

(define hypotenuse
  (lambda (x y)
    (sqrt (+ (* x x) (* y y)))))
                  ;; ==> hypotenuse
(hypotenuse 5 12) ;; ==> 13

(define foo
  (lambda a (display a)))  ;; ==> foo
(foo 1 2 3 4 5)            ;; ==> (1 2 3 4 5)#t

(define foo
  (lambda (b . c)
    (display b)
    (display c)))  ;; ==> foo
(foo 1 2 3 4 5)    ;; ==> 1(2 3 4 5)#t

lcm

Type:

Procedure.

Operation:

Mathematical least common multiple.

Arguments:

One or more integers.

Side Effects:

None.

Returned Value:

An integer: Returns the least common multiple of the arguments.

For Example:

(lcm 24 60)  ;; ==> 120
(lcm 99 88)  ;; ==> 792

length

Type:

Procedure.

Operation:

Find the length of a proper list.

Arguments:

One proper list.

Side Effects:

None.

Returned Value:

An integer: Returns the length of the list.

For Example:

(length (list 'a 'b 'c))  ;; ==> 3
(length '())              ;; ==> 0
(length '(1 2 . 3))       ;; ==> <error>

let

Type:

Macro.

Operation:

Creates an environment with local variables which have initial values or bindings, and evaluates expressions therein. The local variables created may not access each other in establishing their initial values. Contrast with "let*".

Arguments:

Two or more. The first is a list of two-element sublists, the first element in each sublist being an identifier and the second, when evaluated, being the initial value or binding for that identifier. All remaining arguments are the expressions to be evaluated, in the order given, in the environment so created.

Side Effects:

Creates a local environment. Other side effects possible, depending on the arguments.

Returned Value:

Whatever results from the evaluation of the last argument.

For Example:

(define a 'aa)  ;; ==> a
(define b 'bb)  ;; ==> b
(define c 'cc)  ;; ==> c
(let
  ((a c)   ;; Local a gets the top-level value of c, which is 'cc
   (b a)   ;; Local b gets the top-level value of a, which is 'aa
   (c b))  ;; Local c gets the top-level value of b, which is 'bb
  (list a b c))  ;; ==> (cc aa bb)  ;; The values local to the let.

let-syntax

Type:

Macro.

Operation:

Creates an environment with local variables whose bindings are the transformers of hygienic macros (according to the "R5" description thereof), and evaluates expressions therein. The local variables created may not access each other in establishing their initial values. Contrast with "letrec-syntax".

Arguments:

Two or more. The first is a list of two-element sublists, the first element in each sublist being an identifier and the second a <transformer spec>, according to the grammar of "R5" report section 4.3.2. All remaining arguments are the expressions to be evaluated, in the order given, in the environment so created.

Side Effects:

Creates a local environment. Other side effects possible, depending on the arguments.

Returned Value:

Whatever results from the evaluation of the last argument.

For Example:

(let ((x 'outer))
    (let-syntax ((m (syntax-rules () ((m) x))))
      (test::let ((x 'inner))
        (m))))

  ;; ==> outer

let*

Type:

Macro.

Operation:

Creates an environment with local variables which have initial values or bindings, and evaluates expressions therein. Each local variable created may access the local variables created before it when establishing its initial value. Contrast with "let".

Arguments:

Two or more. The first is a list of two-element sublists, the first element in each sublist being an identifier and the second, when evaluated, being the initial value or binding for that identifier. All remaining arguments are the expressions to be evaluated, in the order given, in the environment so created.

Side Effects:

Creates a local environment. Other side effects possible, depending on the arguments.

Returned Value:

Whatever results from the evaluation of the last argument.

For Example:

(define a 'a)    ;; ==> aa
(define b 'b)    ;; ==> bb
(define c 'c)    ;; ==> cc
(let*
  ((a c)   ;; Local a gets the top-level value of c, which is cc
   (b a)   ;; Local b gets the local value of a, which is cc
   (c b))  ;; Local c gets the local value of b, which is cc
  (list a b c))  ;; ==> (cc cc cc)  ;; The values local to the let.

letrec

Type:

Macro.

Operation:

Creates an environment with local variables which have initial values or bindings, and evaluates expressions therein. Each local variable created may access all local variables created by the letrec when establishing its initial value, which typically makes the most sense when what the variables are bound functions that reference one another.. Contrast with "let" and "let*".

Pixie Scheme III does NOT report an error if the local variables of a letrec are used in such a way that the initialization expressions are undefined: Pixie Scheme III handles "letrec" by creating a local environment in which the local variables all have values of '() -- the R5 report merely states that such pre-initialization values are undefined. Thus the example used for let and let* gives the following result for letrec:

(define a 'aa)   ;; ==> a
(define b 'bb)   ;; ==> b
(define c 'cc)   ;; ==> c
(letrec
  ((a c)   ;; Local a gets the top-level value of c, which is 'cc
   (b a)   ;; Local b gets the top-level value of a, which is 'aa
   (c b))  ;; Local c gets the top-level value of b, which is 'bb
  (list a b c))  ;; ==> (() () ())  ;; All uninitialized.

That latter result, however, need not obtain with other Scheme implementations.

Arguments:

Two or more. The first is a list of two-element sublists, the first element in each sublist being an identifier and the second, when evaluated, being the initial value or binding for that identifier. All remaining arguments are the expressions to be evaluated, in the order given, in the environment so created.

Side Effects:

Creates a local environment. Other side effects possible, depending on the arguments.

Returned Value:

Whatever results from the evaluation of the last argument.

For Example:

(letrec
  ((my-even? (lambda (n)
               (if (zero? n)
                 #t
                 (my-odd? (- n 1)))))
   (my-odd? (lambda (n)
              (if (zero? n)
                #f
                (my-even? (- n 1))))))
  (my-even? 42))  ;; ==> #t

letrec-syntax

Type:

Macro.

Operation:

Creates an environment with local variables which have initial bindings to transformers of hygienic macros, according to the "R5" description thereof. Evaluates expressions therein. Each local variable created may access all local variables created by the letrec-syntax when establishing its initial value, which typically makes the most sense when what the variables are macros that reference one another.. Contrast with "let-syntax".

Pixie Scheme III does NOT report an error if the local variables of a letrec-syntax are used in such a way that the initialization expressions are undefined: Pixie Scheme III handles "letrec-syntax" by creating a local environment in which the local variables all have values of '().

Arguments:

Two or more. The first is a list of two-element sublists, the first element in each sublist being an identifier and the second a <transformer spec>, according to the grammar of "R5" report section 4.3.2. All remaining arguments are the expressions to be evaluated, in the order given, in the environment so created.

Side Effects:

Creates a local environment. Other side effects possible, depending on the arguments.

Returned Value:

Whatever results from the evaluation of the last argument.

For Example:

(letrec-syntax
  ((my-or (syntax-rules ()
            ((my-or) #f)
            ((my-or e) e)
            ((my-or e1 e2 ...)
             (let ((temp e1))
               (if temp
                   temp
                   (my-or e2 ...)))))))
  (my-or))

  ;; ==> #f

list

Type:

Procedure.

Operation:

Make a list.

Arguments:

Zero or more Scheme objects.

Side Effects:

None.

Returned Value:

A list of the arguments, in order.

For Example:

(list)        ;; ==> ()
(list 1 2 3)  ;; ==> (1 2 3)

list->string

Type:

Procedure.

Operation:

Convert a list of characters to a string containing them in the given order.

Arguments:

One list of zero or more characters.

Side Effects:

None.

Returned Value:

A string whose characters are those in the list, in order.

For Example:

(list->string '())             ;; ==> ""
(list->string '(#\C #\a #\t))  ;; ==> "Cat"

list->vector

Type:

Procedure.

Operation:

Convert a list of Scheme objects to a vector containing them in the given order.

Arguments:

One list of zero or more Scheme objects.

Side Effects:

None.

Returned Value:

A vector whose elements are the elements of the list, in order.

For Example:

(list->vector '())  ;; ==> #()
(list->vector (list 1 (list 2 3 4) (* 6 7) "Foo"))
                    ;; ==> #(1 (2 3 4) 42 "Foo")

list-ref

Type:

Procedure.

Operation:

Obtain an element of a proper list, based on its position.

Arguments:

One proper list and one non-negative integer.

Side Effects:

None.

Returned Value:

A Scheme object: Returns the (zero-based) nth element of the first argument, where n is the second argument.

For Example:

(list-ref '(1 2 3) 0)  ;; ==> 1
(list-ref '(1 2 3) 1)  ;; ==> 2
(list-ref '(1 2 3) 2)  ;; ==> 3

list-tail

Type:

Procedure.

Operation:

Identify a sublist of a given list made by removing elements from the front of the given list.

Arguments:

One proper list and one non-negative integer.

Side Effects:

None.

Returned Value:

A list: Returns the list obtained from the first argument by removing its first n elements, where n is the second argument. The result shares structure with the first argument: Modifying the result, for example by set-car! or set-cdr!, will modify the first argument.

For Example:

(list-tail '(1 2 3) 0)  ;; ==> (1 2 3)
(list-tail '(1 2 3) 1)  ;; ==> (2 3)
(list-tail '(1 2 3) 2)  ;; ==> (3)
(list-tail '(1 2 3) 3)  ;; ==> ()

list?

Type:

Procedure.

Operation:

Test whether a Scheme object is a proper list.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a proper list. Otherwise, returns #f.

For Example:

(list '())            ;; ==> #t
(list '(1 2 3 4 5)    ;; ==> #f
(list '(1 2 3 4 . 5)  ;; ==> #f

(define a (list 1))   ;; ==> a
(set-cdr! a a)        ;; ==> #t
(list? a)             ;; ==> #f    ;; circular list

log

Type:

Procedure.

Operation:

Mathematical natural logarithm.

Arguments:

One nonnegative number.

Side Effects:

None.

Returned Value:

A number: Returns the natural logarithm of the argument.

For Example:

(log 1)                       ;; ==> 0
(log 2.7182818284590451)      ;; ==> 1.
(log (/ 2.7182818284590451))  ;; ==> -1.
(log -1)                      ;; ==> 3.1415926535897931i

magnitude

Type:

Procedure.

Operation:

Obtain the magnitude of a number.

Arguments:

One number.

Side Effects:

None.

Returned Value:

The magnitude of the number.

For Example:

(magnitude 1)     ;; ==> 1
(magnitude -1)    ;; ==> 1
(magnitude +i)    ;; ==> 1
(magnitude 1.+i)  ;; ==> 1.4142135623730951

make-polar

Type:

Procedure.

Operation:

Create a complex number from its magnitude and angle.

Arguments:

Two reals, the first the magnitude of the desired complex number, the second its angle. Note that R5 allows the magnitude to be negative.

Side Effects:

None.

Returned Value:

A number: The complex number constructed from the given magnitude and angle.

For Example:

(make-polar 1 0)                   ;; ==> 1
(make-polar -1 0)                  ;; ==> -1
(make-polar 1 1.5707963267948966)  ;; ==> 6.123233995736766e-17+1.i

make-rectangular

Type:

Procedure.

Operation:

Create a complex number from its real and imaginary parts.

Arguments:

Two reals, the first the real part of the desired complex number, the second the imaginary part.

Side Effects:

None.

Returned Value:

A number: The complex number constructed from the given real and imaginary part.

For Example:

(make-rectangular 1 1)  ;; ==> 1+i
(make-rectangular 0 1)  ;; ==> +i
(make-rectangular 1 0)  ;; ==> 1

make-string

Type:

Procedure.

Operation:

Create a string, and optionally fill it with a specific character.

Arguments:

Zero, one or two: The first a nonnegative integer, the second, if present, a character.

Side Effects:

None.

Returned Value:

A string: Returns a string whose length is the first argument. If the second argument is present, every character in the new string will be the same as the second argument. If there is no second argument, the string will be filled with blanks.

With no arguments, prompts the user to type a string in the Pixie Scheme III dialog panel. Enclosing double-quotes are not required in this case.

For Example:

(make-string 0)      ;; ==> ""
(make-string 3)      ;; ==> "   "
(make-string 3 #\q)  ;; ==> "qqq"
(make-string)        ;; Pixie Scheme III prompts the user to
                     ;;   type in a string.

make-vector

Type:

Procedure.

Operation:

Create a vector, and optionally fill it with a specific Scheme object.

Arguments:

One or two: The first a nonnegative integer, the second, if present, any Scheme object.

Side Effects:

None.

Returned Value:

A vector: Returns a vector whose length is the first argument. If the second argument is present, every character in the new vector will be the same as the second argument. If there is no second argument, the vector will be filled with the empty list.

For Example:

(make-vector 0)  ;; ==> #()
(make-vector 3)  ;; ==> #(() () ())
(make-vector 3 (list 1 2))
                 ;; ==> #((1 2) (1 2) (1 2))

map

Type:

Procedure.

Operation:

Call a procedure many times, with different arguments, in an unspecified order, and return a list of the results.

Arguments:

Two or more. The first argument is the procedure to call. The rest must all be proper lists of the same length, and the number of arguments beyond the first must equal the number of arguments with which the procedure is to be called. There will be as many calls of the procedure as there are elements in each list. There is no guarantee that the calls will be in any specified order, but for purposes of explanation, let us number them from one to N, N being the number of elements in each list.

On call number 1, the arguments passed to the procedure are the first elements of each list, in the same order as the lists. On call number 2, the passed arguments are the second elements of the lists, and so on.

Side Effects:

None in its own right, but there may be side effects of the procedure calls, depending on the arguments.

Returned Value:

A list of results of the call, in order from 1 to N, as outlined in the "Operation" section above.

For Example:

(define (make-sandwich first second bread)
  (display first)
  (display " and ")
  (display second)
  (display " on ")
  (display bread)
  (newline)
  (if (equal? bread "banana bread")
    'yech
    'yum))  ;; ==> make-sandwich
(map
  make-sandwich
  (list "ham" "tuna" "tofu" "peanut butter")
  (list "cheese" "tomato" "sprouts" "asparagus")
  (list "rye" "whole wheat" "seven-grain" "banana bread")
  )  ;; ==> ham and cheese on rye
     ;;     tuna and tomato on whole wheat
     ;;     tofu and sprouts on seven-grain
     ;;     peanut butter and asparagus on banana bread
     ;;     (yum yum yum yech)

max

Type:

Procedure.

Operation:

Arithmetic maximum.

Arguments:

Two or more real numbers.

Side Effects:

None.

Returned Value:

A number: Returns the maximum of the arguments.

For Example:

(max -17 23 -102.5 9)  ;; ==> 23

member

Type:

Procedure.

Operation:

Identify the first sublist of a list whose car is "equal?" to a given object.

Arguments:

Two: The first is any Scheme object, the second a proper list.

Side Effects:

None.

Returned Value:

Returns the first (longest) sublist of the second argument whose car is "equal?" to the first argument. If no such sublist exists, returns #f.

For Example:

(member 2 (list 1 2 3))        ;; ==> (2 3)
(member 'b '(a b c))           ;; ==> (b c)
(member (list 'a) '(b (a) c))  ;; ==> ((a) c)

memq

Type:

Procedure.

Operation:

Identify the first sublist of a list whose car is "eq?" to a given object.

Arguments:

Two: The first is any Scheme object, the second a proper list.

Side Effects:

None.

Returned Value:

Returns the first (longest) sublist of the second argument whose car is "eq?" to the first argument. If no such sublist exists, returns #f.

For Example:

(memq 2 (list 1 2 3))        ;; ==> (2 3)
(memq 'b '(a b c))           ;; ==> (b c)
(memq (list 'a) '(b (a) c))  ;; ==> #f

memv

Type:

Procedure.

Operation:

Identify the first sublist of a list whose car is "eqv?" to a given object.

Arguments:

Two: The first is any Scheme object, the second a proper list.

Side Effects:

None.

Returned Value:

Returns the first (longest) sublist of the second argument whose car is "eqv?" to the first argument. If no such sublist exists, returns #f.

For Example:

(memv 2 (list 1 2 3))        ;; ==> (2 3)
(memv 'b '(a b c))           ;; ==> (b c)
(memv (list 'a) '(b (a) c))  ;; ==> #f

min

Type:

Procedure.

Operation:

Arithmetic minimum

Arguments:

Two or more real numbers.

Side Effects:

None.

Returned Value:

A number: Returns the minimum of the arguments.

For Example:

(min -17 23 -102.5 9)  ;; ==> -102.5

modulo

Type:

Procedure.

Operation:

Mathematical modulus.

Arguments:

Two integers.

Side Effects:

None. o

Returned Value:

An integer: Returns the first argument modulo the second.

For Example:

(modulo 13 4)    ;; ==> 1
(modulo -13 4)   ;; ==> 3
(modulo 13 -4)   ;; ==> -3
(modulo -13 -4)  ;; ==> -1

negative?

Type:

Procedure.

Operation:

Test whether a number is negative.

Arguments:

One real number.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is negative. Otherwise, returns #f.

For Example:

(negative 0)   ;; ==> #f
(negative 1)  ; ;  ==> #f
(negative -1)  ;; ==> #t

newline

Type:

Procedure.

Operation:

Write a newline character, the ASCII character whose numeric representation is 10, to a port.

Arguments:

At most one, a port.

Side Effects:

Writes a newline to the given port, if there is an argument, or to the current output port, if not.

Returned Value:

#t

For Example:

(newline)      ;; ==> 
               ;;  Just wrote a newline.

;;  Suppose "foo" is an output port:

(newline foo)  ;; ==> #t  ;; Wrote a newline to foo

not

Type:

Procedure.

Operation:

Boolean negation.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is #f. Otherwise, returns #f.

For Example:

(not #f)   ;; ==> #t
(not 42)   ;; ==> #f
(not '())  ;; ==> #f

null-environment

Type:

Procedure.

Operation:

Return a Scheme environment which is supposed to contain only the syntactic keywords of Scheme, but which in Pixie Scheme III contains a few more bindings.

Arguments:

One, which must be the exact integer 5.

Side Effects:

None.

Returned Value:

The null environment of Pixie Scheme III, which contains bindings for the following symbols:

=>
and
begin
c::begin
c::if
c::lambda
c::set!
case
cond
define
delay
do
else
if
lambda
let
let*
letrec
or
quasiquote
quote
set!
unquote
unquote-splicing

The "extra" symbols are macros used in defining several of the syntactic keywords. I couldn't come up with any other reasonable place to put them.

For Example:

(eval '(if #t 2 3) (null-environment 5))
2

null?

Type:

Procedure.

Operation:

Test whether an object is the empty list.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is the empty list. Otherwise, returns #f.

For Example:

(null? #f)   ;; ==> #f
(null? 42)   ;; ==> #f
(null? '())  ;; ==> #t

number->string

Type:

Procedure.

Operation:

Create a string containing an external representation of a given number.

Arguments:

One or two: The first a number, the second an exact integer, either 2, 8, 10 or 16, corresponding to the radix in which the number is to be represented.

Side Effects:

None.

Returned Value:

A string: Returns a string representing the first argument in the given radix, if a second argument is present, or in radix 10 if there is no second argument. The result never contains a radix prefix. The result must be such that, informally, if you read it back in using "string->number" in the correct radix, the number you get is "eqv?" to the original argument.

For Example:

(number->string 10)     ;; ==> "10"
(number->string 10 2)   ;; ==> "1010"
(number->string 10 8)   ;; ==> "12"
(number->string 10 16)  ;; ==> "a"

number?

Type:

Procedure.

Operation:

Test whether a Scheme object is a number.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a number. Otherwise, returns #f. Pixie Scheme III considers nans and infs not to be numbers.

For Example:

(number? 'foo)                ;; ==> #f
(number? 1.234)               ;; ==> #t
(number? 1e10000)             ;; ==> #f  ;; inf
(number? (/ 1e10000 1e10000)  ;; ==> #f  ;; nan

odd?

Type:

Procedure.

Operation:

Test whether an integer is odd.

Arguments:

One integer.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is an odd number. Otherwise, returns #f.

Many people think that all numbers are odd. I do not sympathize, but perhaps that is because I am odd myself.

For Example:

(odd? 42)   ;; ==> #f
(odd? 137)  ;; ==> #t

or

Type:

Macro.

Operation:

Boolean or.

Arguments:

Zero or more Scheme objects of any kind.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, at least one of the arguments is true. (Recall that the only Scheme object that is false is #f.) With no arguments, returns #f. Otherwise, returns #f

This macro operates by evaluating its arguments one at a time, from left to right. When and if any argument evaluates to true, "or" returns true immediately, without evaluating any more arguments.

For Example:

(and)       ;; ==> #t
(or #t)     ;; ==> #t
(or #f)     ;; ==> #f
(or #t #t)  ;; ==> #t
(or #f #t)  ;; ==> #t
(or #f #f)  ;; ==> #f

(define (foo) (begin (display "foo ") #f)) ;; ==> foo
(define (bar) (begin (display "bar ") #t)) ;; ==> bar

(or (bar) (foo))                           ;; ==> bar #t
                                           ;; It didn't print "foo".

output-port?

Type:

Procedure.

Operation:

Test whether the argument is an output port.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is an output port. Otherwise, returns #f. Note that once an output port has been closed, it is no longer a port in the sense of the R5 report, because it cannot accept characters on demand.

For Example:

(define foo (open-output-file "Some.output.file"))  ;; ==> foo
(output-port? foo)                                  ;; ==> #t
(close-output-port foo)                             ;; ==> #t
(output-port? foo)                                  ;; ==> #f

(output-port? 42)                                   ;; ==> #f

pair?

Type:

Procedure.

Operation:

Test whether the argument is a pair.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a pair. Otherwise, returns #f.

For Example:

(pair? '(1 . 2))    ;; ==> #t
(pair? (list 1 2))  ;; ==> #t
(pair? '())         ;; ==> #f
(pair? 42)          ;; ==> #f

peek-char

Type:

Procedure.

Operation:

Obtain the next character available from an input port -- or hang waiting if none is available -- without doing anything to cause the port to advance to to the next character.

Arguments:

At most one, an input port.

Side Effects:

None.

Returned Value:

A character or an end-of file object: If there is an argument, obtain the result from that port. If there is no argument, obtain the result from the current input port. The procedure may not return immediately, if the port is to an interactive device, such as the keyboard, which has no character ready.

For Example:

;; Suppose that foo is an input port just opened to
;; a text file containing just one character, "a":

(peek-char foo)  ;; ==> #\a
(peek-char foo)  ;; ==> #\a
(peek-char foo)  ;; ==> #\a
(peek-char foo)  ;; ==> #\a

(read-char foo)  ;; ==> #\a

(peek-char foo)  ;; ==> #<End of File>

port?

Type:

Procedure.

Operation:

Test whether the argument is a port.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a port. Otherwise, returns #f. Note that once a port has been closed, it is no longer a port as Scheme uses the term, because it can neither accept nor provide characters on demand.

For Example:

(define foo (open-output-file "Some.output.file"))         ;; ==> foo
(define bar (open-input-file "Some.existing.input.file"))  ;; ==> bar
(port? foo)              ;; ==> #t
(port? bar)              ;; ==> #t
(close-output-port foo)  ;; ==> #t
(close-input-port bar)   ;; ==> #t
(port? foo)              ;; ==> #f
(port? bar)              ;; ==> #f
(port? 42)               ;; ==> #f

positive?

Type:

Procedure.

Operation:

Test whether a number is positive.

Arguments:

One real number.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is positive. Otherwise, returns #f.

For Example:

(positive 0)   ;; ==> #f
(positive 1)   ;; ==> #t
(positive -1)  ;; ==> #f

procedure?

Type:

Procedure.

Operation:

Test whether a Scheme object is a procedure.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a procedure. Returns #f otherwise.

Macros and special forms are not procedures.

For Example:

(procedure? +)                     ;; ==> #t
(procedure? (lambda (x) (+ x 1)))  ;; ==> #t
(procedure? lambda)                ;; ==> #f
(procedure? let)                   ;; ==> #f

quasiquote

Additional Syntax:

Backquote: `<whatever> is equivalent to (quasiquote <whatever>).

Type:

Macro.

Operation:

Instantiate literal data with an option for partial evaluation using "unquote" or "unquote-splicing". Thus, (quasiquote <whatever>) evaluates to <whatever>, but if any subexpression of <whatever> begins with either "unquote" or "unquote-splicing", or with their respective syntactic equivalents, "," or ",@", then that subexpression will be evaluated according to the rules for unquote or unquote-splicing before being inserted into <whatever>.

The macros "quasiquote", "unquote" and "unquote-splicing" may be nested within <whatever>: Starting with a nesting level of zero at the the left end of <whatever>, each "quasiquote" increases the nesting level by one, and each "unquote" or "unquote-splicing" reduces it by one, and normal evaluation occurs only when the nesting level thus determined is zero.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

The argument, with no further evaluation except as directed by "unquote" or by "unquote-splicing".

For Example:

(define foo "A string named foo")  ;; ==> foo
(quasiquote foo)                   ;; ==> foo
`foo                               ;; ==> foo
(quasiquote ,foo)                  ;; ==> "A string named foo."
`,foo                              ;; ==> "A string named foo."

(define a 42)         ;; ==> a
(quasiquote (+ 2 a))  ;; ==> (+ 2 a)
`(+ 2 a)              ;; ==> (+ 2 a)
`(+ 2 ,a)             ;; ==> (+ 2 42)

(define b (list 27 18 28))  ;; ==> b
`(+ 2 b)                    ;; ==> (+ 2 b)
`(+ 2 ,b)                   ;; ==> (+ 2 (27 18 28))  ;; Doesn't add up ....
`(+ 2 ,@b)                  ;; ==> (+ 2 27 18 2)

quote

Additional Syntax:

Quote: '<whatever> is equivalent to (quote <whatever>).

Type:

Special form.

Operation:

Instantiate literal data; that is, (quote <whatever>) evaluates to <whatever>.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

The argument, without further evaluation.

For Example:

(quote foo)      ;; ==> foo
'foo             ;; ==> foo
(quote (+ 2 2))  ;; ==> (+ 2 2)
'(+ 2 2)         ;; ==> (+ 2 2)

quotient

Type:

Procedure.

Operation:

Mathematical quotient.

Arguments:

Two integers.

Side Effects:

None.

Returned Value:

An integer: The quotient of the first number by the second.

For Example:

(quotient 13 4)    ;; ==> 3
(quotient -13 4)   ;; ==> -3
(quotient 13 -4)   ;; ==> -3
(quotient -13 -4)  ;; ==> 3

rational?

Type:

Procedure.

Operation:

Test whether the argument is a rational number.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a rational number. Otherwise, returns #f.

For Example:

(rational? #t)        ;; ==> #f
(rational? 1)         ;; ==> #t
(rational? 1.5)       ;; ==> #t
(rational? (sqrt 2))  ;; ==> #t

;; Note that in Pixie Scheme III

(sqrt 2)              ;; ==> 1.4142135623730951

;; which is 14142135623730951/10000000000000000
;; and thus is rational.

read

Type:

Procedure.

Operation:

Read one Scheme object from a port. What is read must "parse"; that is, it must be a valid external representation of a Scheme object, but "read" does not evaluate it.

Arguments:

At most one: If present, an input port.

Side Effects:

None.

Returned Value:

A Scheme object: If an argument is present, returns the next Scheme object available from that port, or an end-of-file object; if not, returns the next Scheme object available at the current input port, or an end-of-file object.

For Example:

;; Suppose "foo" is a newly-opened input port to a file containing
;; the text "(+ 2 2) No more".

(read foo)  ;; ==> (+ 2 2)
(read foo)  ;; ==> No
(read foo)  ;; ==> more
(read foo)  ;; ==> <End of File>

read-char

Type:

Procedure.

Operation:

Obtain the next character available from an input port -- or hang waiting if none is available.

Arguments:

At most one, an input port.

Side Effects:

Reads from a port.

Returned Value:

A character or an end-of file object: If there is an argument, obtain the result from that port. If there is no argument, obtain the result from the current input port. The procedure may not return immediately, if the port is to an interactive device, such as the keyboard, which has no character ready.

For Example:

;; Suppose that foo is an input port just opened to
;; a text file containing the text "abc":

(read-char foo)  ;; ==> #\a
(read-char foo)  ;; ==> #\b
(read-char foo)  ;; ==> #\c
(read-char foo)  ;; ==> #<End of File>
(read-char foo)  ;; ==> #<End of File>
(read-char foo)  ;; ==> #<End of File>

real-part

Type:

Procedure.

Operation:

Obtain the real part of a number.

Arguments:

One number.

Side Effects:

None.

Returned Value:

The real part of the number.

For Example:

(real-part 1)     ;; ==> 1
(real-part +i)    ;; ==> 0
(real-part 1.+i)  ;; ==> 1.

real?

Type:

Procedure.

Operation:

Test whether the argument is a real number.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a real number. Otherwise, returns #f.

For Example:

(real? #t)        ;; ==> #f
(real? 1)         ;; ==> #t
(real? 1.5)       ;; ==> #t
(real? (sqrt 2))  ;; ==> #t

remainder

Type:

Procedure.

Operation:

Mathematical remainder.

Arguments:

Two integers.

Side Effects:

None.

Returned Value:

An integer: The remainder of the first number when divided (in the sense of "quotient") by the second.

For Example:

(remainder 13 4)    ;; ==> 1
(remainder -13 4)   ;; ==> -1
(remainder 13 -4)   ;; ==> 1
(remainder -13 -4)  ;; ==> -1

reverse

Type:

Procedure.

Operation:

Reverse a proper list.

Arguments:

One proper list.

Side Effects:

None.

Returned Value:

A list: Returns a newly-created list whose elements are the elements of the argument in reverse order.

For Example:

(reverse '())           ;; ==> ()
(reverse (list 1 2 3))  ;; ==> (3 2 1)

round

Type:

Procedure.

Operation:

Arithmetic round to nearest integer.

Arguments:

One real number.

Side Effects:

None.

Returned Value:

An integer: The closest integer to the argument, rounding to even when the argument is half way between two integers.

For Example:

(round 3.49) ;; ==> 3.
(round 3.51) ;; ==> 4.
(round 3.5)  ;; ==> 4.
(round 2.5)  ;; ==> 2.

scheme-report-environment

Type:

Procedure.

Operation:

Return a Scheme environment which contains the bindings in the null environment, plus all other bindings that are either required by the R5 report or are optional and are supported by Pixie Scheme III.

Arguments:

One, which must be the exact integer 5.

Side Effects:

None.

Returned Value:

The Scheme-report environment of Pixie Scheme III.

For Example:

(eval '(+ 2 2) (scheme-report-environment 5))
4

set!

Type:

Special form.

Operation:

Change the value or binding of an identifier that already has a value or binding.

Arguments:

Two: The first, an identifier; the second, any Scheme object.

Side Effects:

Changes a pre-existing variable value or binding; informally, changes the value of a variable. The second argument becomes the value or binding of the first, in whatever environment the "set!" occurred in.

In the top-level environment, "define" may also be used to give new values or bindings to identifiers; however, in other environments, only "set!" has this capability.

Returned Value:

#t

For Example:

;;  Suppose that "a" has never had a value or binding.

(set! a 42)    ;; ==> <error>  ;;  No value to change.

(define a 23)  ;; ==> a
a              ;; ==> 23
(set! a 42)    ;; ==> #t
a              ;; ==> 42

set-car!

Type:

Procedure.

Operation:

Change the car of a pair to a new value.

Arguments:

Two: The first, a pair; the second, any Scheme object, to become the new car.

Side Effects:

Changes the pair.

Returned Value:

#t

For Example:

(define a (cons 1 2))  ;; ==> a
a                      ;; ==> (1 . 2)
(set-car! a 42)        ;; ==> #t
a                      ;; ==> (42 . 2)

set-cdr!

Type:

Procedure.

Operation:

Change the cdr of a pair to a new value.

Arguments:

Two: the first, a pair; the second, any Scheme object, to become the new cdr.

Side Effects:

Changes the pair.

Returned Value:

#t

For Example:

(define a (cons 1 2))  ;; ==> a
a                      ;; ==> (1 . 2)
(set-cdr! a 42)        ;; ==> #t
a                      ;; ==> (1 . 42)

sin

Type:

Procedure.

Operation:

Mathematical sine.

Arguments:

One number, taken to be an angle in radians.

Side Effects:

None.

Returned Value:

The sine of the argument.

For Example:

(sin 0)                   ;; ==> 0
(sin 1.5707963267948966)  ;; ==> 1.
(sin 0.7853981633974483)  ;; ==> 0.7071067811865475
(sin +i)                  ;; ==> 1.1752011936438014i

sqrt

Type:

Procedure.

Operation:

Mathematical square root.

Arguments:

One number.

Side Effects:

None.

Returned Value:

The square root of the argument.

For Example:

(sqrt 0)    ;; ==> 0
(sqrt 2.5)  ;; ==> 1.5811388300841898
(sqrt 4)    ;; ==> 2
(sqrt -1)   ;; ==> +i
(sqrt +i)   ;; ==> 0.7071067811865476+0.7071067811865475i

string

Type:

Procedure.

Operation:

Create a string containing a given list of characters.

Arguments:

Zero or more characters.

Side Effects:

None.

Returned Value:

A string containing the characters that were the arguments, in the same order

For Example:

(string)                ;; ==> ""
(string #\C #\a #\t)    ;; ==> "Cat"

string->list

Type:

Procedure.

Operation:

Make a list of the characters in a string.

Arguments:

One string.

Side Effects:

None.

Returned Value:

A list: Returns a list of the characters in the argument, in order.

For Example:

(string->list "Cat")  ;; ==> (#\C #\a #\t)

string->number

Type:

Procedure.

Operation:

Read the contents of a string as a number in a particular radix.

Arguments:

One or two: The first, the string to be read, the second an exact integer, either 2, 8, 10 or 16, corresponding to the radix in which the number is to be represented. If there is no second argument, the radix is taken to be 10. of the

Side Effects:

None.

Returned Value:

A number: Returns a number whose external representation in the given base is the given string.

For Example:

(string->number "123")            ;; ==> 123
(string->number "1001" 2)         ;; ==> 9
(string->number "1001" 8)         ;; ==> 513
(string->number "1001" 10)        ;; ==> 1001
(string->number "1001")           ;; ==> 1001
(string->number "1001" 16)        ;; ==> 4097
(string->number "-#i123###.e23")  ;; ==> -1.2300000000000001e28

string->symbol

Type:

Procedure.

Operation:

Create a Scheme identifier from the letters of the argument.

Arguments:

One string.

Side Effects:

None.

Returned Value:

A symbol: Returns a Scheme identifier whose characters are the same as those in the given string, in the same order.

For Example:

(string->symbol "Cat")  ;; ==> Cat  ;; Note the capitalization.

string-append

Type:

Procedure.

Operation:

Concatenate strings.

Arguments:

One or more strings.

Side Effects:

None.

Returned Value:

A string: Returns a string whose characters are the characters of the arguments, in order.

For Example:

(string-append "I " "see " "the " "cat.")
    ;; ==> "I see the cat."

string-ci<=?

Type:

Procedure.

Operation:

Convert two strings to lower case and test for lexicographic less than or equal to.

Lexicographic comparison compares strings character-by-character and defines their ordering based on the ASCII integers that represent the first characters at which they differ, if any. If one string ends before a difference occurs, the longer string is taken to be greater. If both strings end with no difference, the strings are taken to be equal.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically less than or equal to the second. Otherwise, returns #f.

For Example:

(string-ci<=? "aa" "aardvark")        ;; ==> #t
(string-ci<=? "Aa" "aardvark")        ;; ==> #t
(string-ci<=? "aa" "Aardvark")        ;; ==> #t
(string-ci<=? "aa" "pahoehoe")        ;; ==> #t
(string-ci<=? "pahoehoe" "aa")        ;; ==> #f
(string-ci<=? "aardvark" "aardvark")  ;; ==> #t

string-ci<?

Type:

Procedure.

Operation:

Convert two strings to lower case and test for lexicographic less than.

Lexicographic comparison compares strings character-by-character and defines their ordering based on the ASCII integers that represent the first characters at which they differ, if any. If one string ends before a difference occurs, the longer string is taken to be greater. If both strings end with no difference, the strings are taken to be equal.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically less than the second. Otherwise, returns #f.

For Example:

(string-ci<? "aa" "aardvark")        ;; ==> #t
(string-ci<? "Aa" "aardvark")        ;; ==> #t
(string-ci<? "aa" "Aardvark")        ;; ==> #t
(string-ci<? "aa" "pahoehoe")        ;; ==> #t
(string-ci<? "pahoehoe" "aa")        ;; ==> #f
(string-ci<? "aardvark" "aardvark")  ;; ==> #f

string-ci=?

Type:

Procedure.

Operation:

Convert two strings to lower case and test for lexicographic equality.

Lexicographic comparison compares strings character-by-character and defines their ordering based on the ASCII integers that represent the first characters at which they differ, if any. If one string ends before a difference occurs, the longer string is taken to be greater. If both strings end with no difference, the strings are taken to be equal.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically equality the second. Otherwise, returns #f.

For Example:

(string-ci=? "aa" "aardvark")        ;; ==> #f
(string-ci=? "Aa" "aardvark")        ;; ==> #f
(string-ci=? "aa" "Aardvark")        ;; ==> #f
(string-ci=? "aa" "pahoehoe")        ;; ==> #f
(string-ci=? "aardvark" "aardvark")  ;; ==> #t
(string-ci=? "aardvark" "AARDVARK")  ;; ==> #t

string-ci>=?

Type:

Procedure.

Operation:

Convert two strings to lower case and test for lexicographic greater than or equal to.

Lexicographic comparison compares strings character-by-character and defines their ordering based on the ASCII integers that represent the first characters at which they differ, if any. If one string ends before a difference occurs, the longer string is taken to be greater. If both strings end with no difference, the strings are taken to be equal.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically greater than or equal to the second. Otherwise, returns #f.

For Example:

(string-ci>=? "aa" "aardvark")        ;; ==> #f
(string-ci>=? "Aa" "aardvark")        ;; ==> #f
(string-ci>=? "aa" "Aardvark")        ;; ==> #f
(string-ci>=? "aa" "pahoehoe")        ;; ==> #f
(string-ci>=? "pahoehoe" "aa")        ;; ==> #t
(string-ci>=? "aardvark" "aardvark")  ;; ==> #t

string-ci>?

Type:

Procedure.

Operation:

Convert two strings to lower case and test for lexicographic greater than.

Lexicographic comparison compares strings character-by-character and defines their ordering based on the ASCII integers that represent the first characters at which they differ, if any. If one string ends before a difference occurs, the longer string is taken to be greater. If both strings end with no difference, the strings are taken to be equal.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically greater than the second. Otherwise, returns #f.

For Example:

(string-ci>? "aa" "aardvark")        ;; ==> #f
(string-ci>? "Aa" "aardvark")        ;; ==> #f
(string-ci>? "aa" "Aardvark")        ;; ==> #f
(string-ci>? "aa" "pahoehoe")        ;; ==> #f
(string-ci>? "pahoehoe" "aa")        ;; ==> #t
(string-ci>? "aardvark" "aardvark")  ;; ==> #f

string-copy

Type:

Procedure.

Operation:

Copy a string.

Arguments:

One string.

Side Effects:

None.

Returned Value:

A string: Returns a newly-allocated copy of the argument.

For Example:

(string-copy "Cat")  ;; ==> "Cat"

string-fill!

Type:

Procedure.

Operation:

Fill a string with a given character.

Arguments:

Two: The first a string, the second the character to fill with.

Side Effects:

Alters the string.

Returned Value:

#t

For Example:

(define a (make-string 2))  ;; ==> a
a                           ;; ==> "  "
(string-fill! a #\x)        ;; ==> #t
a                           ;; ==> "xx"

string-length

Type:

Procedure.

Operation:

Determine the length of a string.

Arguments:

One string.

Side Effects:

None.

Returned Value:

An integer: Returns the number of characters in the argument.

For Example:

(string-length "Cat")  ;; ==> 3

string-ref

Type:

Procedure.

Operation:

Get a specific character from a string.

Arguments:

Two: The first a string, the second a nonnegative integer, taken as the zero-based index of the character to return.

Side Effects:

None.

Returned Value:

A character: Returns the first argument's character that was at position N from the start of the string, N being the second argument. A value of zero for N returns the first character in the string.

For Example:

(string-ref "Cat" 0)  ;; ==> #\C
(string-ref "Cat" 1)  ;; ==> #\a
(string-ref "Cat" 2)  ;; ==> #\t

string-set!

Type:

Procedure.

Operation:

Set one character in a string to a new value.

Arguments:

Three: The first a string, the second a nonnegative integer, taken as the zero-based index of the character to change, the third the new character.

Side Effects:

Changes the string.

Returned Value:

#t

For Example:

(define a (make-string 3))  ;; ==> a
a                           ;; ==> "   "
(string-set! a 0 #\C)       ;; ==> #t
a                           ;; ==> "C  "
(string-set! a 1 #\a)       ;; ==> #t
a                           ;; ==> "Ca "
(string-set! a 2 #\t)       ;; ==> #t
a                           ;; ==> "Cat"

string<=?

Type:

Procedure.

Operation:

Test two strings for lexicographic less than or equal to.

Lexicographic comparison compares strings character-by-character and defines their ordering based on the ASCII integers that represent the first characters at which they differ, if any. If one string ends before a difference occurs, the longer string is taken to be greater. If both strings end with no difference, the strings are taken to be equal.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically less than or equal to the second. Otherwise, returns #f.

For Example:

(string<=? "aa" "aardvark")        ;; ==> #t
(string<=? "Aa" "aardvark")        ;; ==> #t
(string<=? "aa" "Aardvark")        ;; ==> #f
(string<=? "aa" "pahoehoe")        ;; ==> #t
(string<=? "aardvark" "aardvark")  ;; ==> #t

string<?

Type:

Procedure.

Operation:

Test two strings for lexicographic less than.

Lexicographic comparison compares strings character-by-character and defines their ordering based on the ASCII integers that represent the first characters at which they differ, if any. If one string ends before a difference occurs, the longer string is taken to be greater. If both strings end with no difference, the strings are taken to be equal.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically less than the second. Otherwise, returns #f.

For Example:

(string<? "aa" "aardvark")        ;; ==> #t
(string<? "Aa" "aardvark")        ;; ==> #t
(string<? "aa" "Aardvark")        ;; ==> #f
(string<? "aa" "pahoehoe")        ;; ==> #t
(string<? "aardvark" "aardvark")  ;; ==> #f

string=?

Type:

Procedure.

Operation:

Test two strings for lexicographic equality.

Lexicographic comparison compares strings character-by-character and defines their ordering based on the ASCII integers that represent the first characters at which they differ, if any. If one string ends before a difference occurs, the longer string is taken to be greater. If both strings end with no difference, the strings are taken to be equal.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically equality the second. Otherwise, returns #f.

For Example:

(string=? "aa" "aardvark")        ;; ==> #f
(string=? "Aa" "aardvark")        ;; ==> #f
(string=? "aa" "Aardvark")        ;; ==> #f
(string=? "aa" "pahoehoe")        ;; ==> #f
(string=? "aardvark" "aardvark")  ;; ==> #t
(string=? "aardvark" "AARDVARK")  ;; ==> #f