[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Message a011267 LONG message - part 3




   (HEUR).

 (POLAR m a)
   Express as a polar form complex number.  m and a are formats for
   the magnitude and angle respectively.  m and a default to (HEUR).

 (HEUR)
   Express heuristically, as in the MacLisp printer (see Steele),
   using the minimum number of digits required to get an expression
   which when coerced back to a number produces the original machine
   representation.  EXACT numbers are expressed as (INT) or (RAT).
   INEXACT numbers are expressed as (FLO H) or (SCI H) depending on
   their range.  Complex numbers are expressed in (RECT).  This is the
   normal default of the system printer.


The following modifiers may be added to a numerical format 
specification: 

 (EXACTNESS s)
   This controls the expression of the exactness label of a number.  s
   indicates whether the exactness is to be E (expressed) or S
   (suppressed).  s defaults to E.  If no exactness modifier is
   specified for a format the exactness is by default not expressed.

 (RADIX r s)
   This forces a number to be expressed in the radix r.  r may be B
   (binary), O (octal), D (decimal), or X (hex).  s indicates whether
   the radix label is to be E (expressed) or S (suppressed).  s
   defaults to E.  If no radix modifier is specified the default is 
   decimal and the label is suppressed.


 II.8.  Strings


Strings are written as sequences of characters enclosed within 
doublequotes (").  A doublequote can be written inside a string 
only by escaping it with a backslash (\), as in 

      "The word \"Recursion\" has many different meanings."

A backslash can be written inside a string only by escaping it 
with another backslash.  Scheme does not specify the effect of a 
backslash within a string that is not followed by either a 
doublequote or another backslash.  

A string may continue from one line to the next, but this is 
usually a bad idea because the exact effect varies from one 
computer system to another.  

Several of the string procedures involve characters or lists of 
characters.  Characters are written using the #\ notation of 
Common Lisp.  For example: 

        #a           ; lower case letter
        #A           ; upper case letter
        #(           ; the left parenthesis as a character
        #            ; the space character
        #space       ; the preferred way to notate a space character
        #newline     ; the newline character

The #\ notation is not an essential part of Scheme, however.  
Even implementations that support the #\ notation for input do 
not have to support it for output, and there is no requirement 
that the data type of characters be disjoint from data types 
such as integers or strings.  

This section defines no destructive operations on strings, but a 
much larger collection of string operations including 
destructive operations has been proposed by Chris Hanson and is 
under consideration.  


(string? obj)                                 essential procedure

Returns #!true if obj is a string, otherwise returns #!false.  


(string-equal? string1 string2)               essential procedure

Returns #!true if string1 and string2 are strings of the same 
length and have the same characters in the same positions.  


(string-less? string1 string2)                essential procedure

Returns #!true if string1 is lexicographically less than 
string2.  The ordering defined by string-less? varies from one 
computer system to another, but it is always an irreflexive 
total ordering on strings.  


(string-length string)                        essential procedure

Returns the number of characters in string.  


(string-ref string k)                         essential procedure

k must be a nonnegative integer less than the string-length of 
string.  Returns character k of string using zero-origin 
addressing.  

        (string-ref "abcde" 2)          -->  #c 


(string-append string1 string2)               essential procedure
(string-append string ...)                              procedure

Returns a string whose characters form the catenation of the 
given strings.  


(string->list string)                         essential procedure

Returns a list of the characters that make up string.  See 
list->string.  


(list->string char-list)                      essential procedure

char-list must be a proper list of characters.  Returns a string 
formed from the characters in char-list.  list->string and 
string->list are inverses so far as equal? is concerned.  
II.9.  Vectors 


Vectors are heterogenous mutable structures whose elements are 
indexed by integers.  The first element in a vector is indexed 
by zero, and the last element is indexed by one less than the 
length of the vector.  A vector of length 3 containing the 
number 0 in element 0, the list (2 2 2 2) in element 1, and the 
string "Anna" in element 2 can be written as 

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

Vectors are created by the constructor procedure make-vector.  
The elements are accessed and assigned by the procedures 
vector-ref and vector-set!.  


(vector? obj)                                 essential procedure

Returns #!true if obj is a vector, otherwise returns #!false.  


(make-vector size)                            essential procedure
(make-vector size fill)                                 procedure

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


(vector obj ...)                              essential procedure

Returns a newly allocated vector whose elements contain the 
given arguments.  Analogous to list.  

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


(vector-length vec)                           essential procedure

Returns the number of elements in the vector vec.  


(vector-ref vec k)                            essential procedure

Returns the contents of element k of the vector vec.  k must be 
a nonnegative integer less than the vector-length of vec.  

  (vector-ref '#(1 1 2 3 5 8 13 21) 5)  -->  8


(vector-set! vec k obj)                       essential procedure

Stores obj in element k of the vector vec.  k must be a 
nonnegative integer less than the vector-length of vec.  The 
value returned by vector-set! is not specified.  

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


(vector->list vec)                            essential procedure

Returns a list of the objects contained in the elements of vec.  
See list->vector.  

    (vector->list '#(dah dah didah))    -->  (dah dah didah)


(list->vector elts)                           essential procedure

Returns a newly created vector whose elements are initialized to 
the elements of the proper list elts.  

        (list->vector '(dididit dah))   -->  #(dididit dah)


(vector-fill! vec fill)                                 procedure

Stores fill in every element of the vector vec.  The value 
returned by vector-fill! is not specified.  
II.10.  The object table 


(object-hash obj)                                       procedure
(object-unhash n)                                       procedure

object-hash associates an integer with obj in a global table and 
returns obj.  object-hash guarantees that distinct objects (in 
the sense of eq?) are associated with distinct integers.  
object-unhash takes an integer and returns the object associated 
with that integer if there is one, returning false otherwise.  

Rationale: object-hash and object-unhash can be implemented 
using association lists and the assq procedure, but the intent 
is that they be efficient hash functions for general objects.  
II.11.  Procedures 


Procedures are created when lambda expressions are evaluated.  
Procedures do not have a standard printed representation because 
recursively defined procedures are conceptually infinite and may 
be implementationally circular.  

The most common thing to do with a procedure is to call it with 
zero or more arguments.  A Scheme procedure may also be stored 
in data structures or passed as an argument to procedures such 
as those described below.  


(apply proc args)                             essential procedure
(apply proc arg1 ... args)                              procedure

proc must be a procedure and args must be a proper list of 
arguments.  The first (essential) form calls proc with the 
elements of args as the actual arguments.  The second form is a 
generalization of the first that calls proc with the elements of 
(append (list arg1 ...) args) as the actual arguments.  

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

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

    ((compose 1+ *) 3 4)                -->  13


(mapcar f plist)                              essential procedure
(mapcar f plist1 plist2 ...)                            procedure

f must be a procedure of one argument and the plists must be 
proper lists.  If more than one plist is given, then the plists 
should all be the same length.  Applies f element-wise to the 
elements of the plists and returns a list of the results.  The 
order in which f is applied to the elements of the plists is not 
specified.  

    (mapcar cadr '((a b) (d e) (g h)))  -->  (b e h)

    (mapcar (lambda (n) (expt n n))
            '(1 2 3 4 5))               -->  (1 4 27 256 3125)

    (mapcar + '(1 2 3) '(4 5 6))        -->  (5 7 9)

    (define count 0)                    -->  unspecified
    (mapcar (lambda (ignored)
              (set! count (1+ count))
              count)
            '(a b c))                   -->  unspecified

The mapcar procedure often goes by the name of map in other 
advanced programming languages.  


(mapc f plist)                                essential procedure
(mapc f plist1 plist2 ...)                              procedure

The arguments to mapc are like the arguments to mapcar, but mapc 
calls f for its side effects rather than for its values.  Unlike 
mapcar, mapc is guaranteed to call f on the elements of the 
plists in order from the first element to the last, and the 
value returned by mapc is not specified.  

    (define v (make-vector 5))          -->  v

    (mapc (lambda (i)
            (vector-set! v i (* i i)))
          '(0 1 2 3 4))                 -->  unspecified

    v                                   -->  #(0 1 4 9 16)

The name of mapc is traditional and cannot otherwise be 
defended.  


(call-with-current-continuation f)                      procedure

The classic use of call-with-current-continuation is for 
structured, non-local exits from loops or procedure bodies, but 
in fact call-with-current-continuation is extremely useful for 
implementing a wide variety of advanced control structures.  

Whenever a Scheme expression is evaluated there is a 
continuation wanting the result of the expression.  The 
continuation represents an entire future for the computation.  
If the expression is evaluated at top level, for example, then 
the continuation will take the result, print it on the screen, 
prompt for the next input, evaluate it, and so on forever.  Most 
of the time the continuation includes actions specified by user 
code, as in a continuation that will take the result, multiply 
it by the value stored in a local variable, add seven, and give 
the answer to the top level continuation to be printed.  
Normally these ubiquitous continuations are hidden behind the 
scenes and programmers don't think much about them.  On rare 
occasions, however, when programmers need to do something fancy, 
then they may need to deal with continuations explicitly.  
call-with-current-continuation allows Scheme programmers to 
create a procedure that acts just like the current continuation.  


f must be a procedure of one argument.  
call-with-current-continuation packages up the current 
continuation as an "escape procedure" and passes it as an 
argument to f.  The escape procedure is an ordinary Scheme 
procedure of one argument that, if it is later passed a value, 
will ignore whatever continuation is in effect at that later 
time and will give the value instead to the continuation that 
was in effect when the escape procedure was created.  

The escape procedure created by call-with-current-continuation 
has unlimited extent just like any other procedure in Scheme.  
It may be stored in variables or data structures and may be 
called as many times as desired.  

The following examples show only the most common uses of 
call-with-current-continuation.  If all real programs were as 
simple as these examples, there would be no need for a procedure 
with the power of call-with-current-continuation.  

    (call-with-current-continuation
      (lambda (exit)
        (mapc (lambda (x)
                (if (negative? x)
                    (exit x)))
              '(54 0 37 -3 245 19))
        #!true))                        -->  -3

    (define list-length
      (lambda (obj)
        (call-with-current-continuation
          (lambda (return)
            ((rec loop (lambda (obj)
                         (cond ((null? obj) 0)
                               ((pair? obj)
                                (1+ (loop (cdr obj))))
                               (else (return #!false)))))
             obj)))))
                                        -->  list-length

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

    (list-length '(a b . c))            -->  #!false


Rationale: Most serious programming languages incorporate one or 
more special purpose escape constructs with names like exit, 
return, or even goto.  In 1965, however, Peter Landin invented a 
general purpose escape operator called the J-operator.  John 
Reynolds described a simpler but equally powerful construct in 
1972.  The catch special form described by Sussman and Steele in 
the 1975 report on Scheme is exactly the same as Reynolds's 
construct, though its name came from a less general construct in 
MacLisp.  The fact that the full power of Scheme's catch could 
be obtained using a procedure rather than a special form was 
noticed in 1982 by the implementors of Scheme 311, and the name 
call-with-current-continuation was coined later that year.  Some 
people think the name is good because its length discourages 
programmers from using the procedure casually; others have taken 
to calling the procedure call/cc.  
II.12.  Ports 


Ports represent input and output devices.  To Scheme, an input 
device is a Scheme object that can deliver characters upon 
command, while an output device is a Scheme object that can 
accept characters.  


(call-with-input-file string proc)            essential procedure
(call-with-output-file string proc)           essential procedure

proc is a procedure of one argument, and string is a string 
naming a file.  For call-with-input-file, the file must already 
exist; for call-with-output-file, the effect is unspecified if 
the file already exists.  Calls proc with one argument: the port 
obtained by opening the named file for input or output.  If the 
file cannot be opened, an error is signalled.  If the procedure 
returns, then the port is closed automatically and the value 
yielded by the procedure is returned.  If the current 
continuation ever changes in such a way as to make it doubtful 
that the procedure will return, the port may be closed 
automatically, but the exact interaction with escape procedures 
is unspecified.  

Rationale: Whether or not the port is closed when the procedure 
does not return is mainly a performance issue, of greatest 
importance when there is a small limit on the number of files 
that can be open at once.  The extreme generality of Scheme's 
escape procedures makes it impossible to know for certain 
whether a procedure will return, and procedures can in fact 
return more than once.  


(input-port? obj)                             essential procedure
(output-port? obj)                            essential procedure

Returns #!true if obj is an input port or output port 
(respectively), otherwise returns #!false.  


(current-input-port)                          essential procedure
(current-output-port)                         essential procedure

Returns the current default input or output port.  


(with-input-from-file string thunk)                     procedure
(with-output-to-file string thunk)                      procedure

thunk is a procedure of no arguments, and string is a string 
naming a file.  For with-input-from-file, the file must already 
exist; for with-output-to-file, the effect is unspecified if the 
file already exists.  The file is opened for input or output, an 
input or output port connected to it is made the default value 
returned by current-input-port or current-output-port, and the 
thunk is called with no arguments.  When the thunk returns, the 
port is closed and the previous default is restored.  
with-input-from-file and with-output-to-file return the value 
yielded by thunk.  Furthermore these procedures will attempt to 
close the default port and restore the previous default whenever 
the current continuation changes in such a way as to make it 
doubtful that the thunk will ever return.  See 
call-with-input-file and call-with-output-file.  


(open-input-file filename)                              procedure

Takes a string naming an existing file and returns an input port 
capable of delivering characters from the file.  If the file 
cannot be opened, an error is signalled.  


(open-output-file filename)                             procedure

Takes a string naming an output file to be created and returns 
an output port capable of writing characters to a new file by 
that name.  If the file cannot be opened, an error is signalled.  
If a file with the given name already exists, the effect is 
unspecified.  


(close-input-port port)                                 procedure
(close-output-port port)                                procedure

Closes the file associated with port, rendering the port 
incapable of delivering or writing characters.  The value 
returned is not specified.  
II.13.  Input 


The read procedure converts written representations of Scheme 
objects into the objects themselves.  The written 
representations for Scheme objects are described in the sections 
devoted to the operations on those objects, and the grubby 
details of lexical syntax are described in an appendix.  


(eof? obj)                                    essential procedure

Returns true iff obj is an end of file object.  The precise set 
of end of file objects will vary among implementations, but in 
any case no end of file objects will ever be a character or an 
object that can be read in using read.  


(read)                                        essential procedure
(read port)                                   essential procedure

Returns the next object parsable from the given input port, 
updating port to point to the first character past the end of 
the written representation of the object.  If an end of file is 
encountered in the input before any characters are found that 
can begin an object, then an end of file object is returned.  If 
an end of file is encountered after the beginning of an object's 
written representation, but the written representation is 
incomplete and therefore not parsable, an error is signalled.  
The port argument may be omitted, in which case it defaults to 
the value returned by current-input-port.  

Rationale: This corresponds to Common Lisp's 
read-preserving-whitespace, but for simplicity it is never an 
error to encounter end of file except in the middle of an 
object.  


(read-char)                                   essential procedure
(read-char port)                              essential procedure

Reads the next character available from the input port, updating 
the port to point to the following character.  If no more 
characters are available, an end of file object is returned.  
port may be omitted, in which case it defaults to the value 
returned by current-input-port.  


(listen?)                                               procedure
(listen? port)                                          procedure

Returns true if a character is ready on the input port so that a 
read-char operation will not hang, and returns false otherwise.  
If the port is at end of file then the value returned by listen? 
is unspecified.  port may be omitted, in which case it defaults 
to the value returned by current-input-port.  


(load filename)                               essential procedure

filename should be a string naming an existing file containing 
Scheme source code.  The load procedure reads expressions from 
the file and evaluates them sequentially as though they had been 
typed interactively.  It is not specified whether the results of 
the expressions are printed, however, nor is it specified 
whether the load procedure affects the values returned by 
current-input-stream and current-output-stream during the 
loading process.  load returns an unspecified value.  

Rationale: For portability load must operate on source files.  
Its operation on other kinds of files necessarily varies among 
implementations.  
II.14.  Output 


(write obj)                                   essential procedure
(write obj port)                              essential procedure

Writes a representation of obj to the given port.  Strings that 
appear in the written representation are enclosed in 
doublequotes, and within those strings backslash and doublequote 
characters are escaped by backslashes.  write returns an 
unspecified value.  The port argument may be omitted, in which 
case it defaults to the value returned by current-output-stream.  
See display.  


(display obj)                                 essential procedure
(display obj port)                            essential procedure

Writes a representation of obj to the given port.  Strings that 
appear in the written representation are not enclosed in 
doublequotes, and no characters are escaped within those 
strings.  display returns an unspecified value.  The port 
argument may be omitted, in which case it defaults to the value 
returned by current-output-stream.  See write.  

Rationale: Like Common Lisp's prin1 and princ, write is for 
producing machine-readable output and display is for producing 
human-readable output.  Implementations that allow 
"slashification" within symbols will probably want write but not 
display to slashify funny characters in symbols.  


(newline)                                     essential procedure
(newline port)                                essential procedure

Writes an end of line to port.  Exactly how this is done differs 
from one operating system to another.  Returns an unspecified 
value.  The port argument may be omitted, in which case it 
defaults to the value returned by current-output-port.  


(write-char char)                             essential procedure
(write-char char port)                        essential procedure

Writes the character char (not a written representation of the 
character) to the given port and returns an unspecified value.  
The port argument may be omitted, in which case it defaults to 
the value returned by current-output-port.  


(transcript-on filename)                                procedure
(transcript-off)                                        procedure

filename must be a string naming an output file to be created.  
The effect of transcript-on is to open the named file for 
output, and to cause a transcript of subsequent interaction 
between the user and the Scheme system to be written to the 
file.  The transcript is ended by a call to transcript-off, 
which closes the transcript file.  Only one transcript may be in 
progress at any time, though some implementations may relax this 
restriction.  The values returned by these procedures are 
unspecified.  

Rationale: These procedures are redundant in some systems, but 
systems that need them should provide them.  
References 




Harold Abelson and Gerald Jay Sussman with Julie Sussman, 
Structure and Interpretation of Computer Programs, MIT Press, 
1985.  

William Clinger, "The Scheme 311 compiler: an exercise in 
denotational semantics", Conference Record of the 1984 ACM 
Symposium on Lisp and Functional Programming, August 1984, pages 
356-364.  

Carol Fessenden, William Clinger, Daniel P Friedman, and 
Christopher Haynes, "Scheme 311 version 4 reference manual", 
Indiana University Computer Science Technical Report 137, 
February 1983.  

D Friedman, C Haynes, E Kohlbecker, and M Wand, "Scheme 84 
interim reference manual", Indiana University Computer Science 
Technical Report 153, January 1985.  

Christopher T Haynes, Daniel P Friedman, and Mitchell Wand, 
"Continuations and coroutines", Conference Record of the 1984 
ACM Symposium on Lisp and Functional Programming, August 1984, 
pages 293-298.  

Peter Landin, "A correspondence between Algol 60 and Church's 
lambda notation: Part I", Communications of the ACM 8, 2, 
February 1965, pages 89-101.  

MIT Scheme Manual, Seventh Edition, September 1984.  

Peter Naur et al, "Revised report on the algorithmic language 
Algol 60", Communications of the ACM 6, January 1963, pages 
1-17.  

Kent M Pitman, The Revised MacLisp Manual, MIT Artificial 
Intelligence Laboratory Technical Report 295, 21 May 1983 
(Saturday Evening Edition).  

Jonathan A Rees, Norman I Adams, James R Meehan, "The T manual", 
Fourth Edition, 10 January 1984.  

John Reynolds, "Definitional interpreters for higher order 
programming languages", ACM Conference Proceedings, 1972, pages 
717-740.  

Guy Lewis Steele Jr and Gerald Jay Sussman, "The revised report 
on Scheme, a dialect of Lisp", MIT Artificial Intelligence 
Laboratory Memo 452, January 1978.  

Guy L Steele, Rabbit: a compiler for Scheme, MIT Artificial 
Intelligence Laboratory Technical Report 474, May 1978.  

Guy L Steele, "An overview of Common Lisp", Conference Record of 
the 1982 ACM Symposium on Lisp and Functional Programming, 
August 1982, pages 98-107.  

Guy Lewis Steele Jr, Common Lisp: the Language, Digital Press, 
1984.  

Gerald Jay Sussman and Guy Lewis Steele Jr, "Scheme: an 
interpreter for extended lambda calculus", MIT Artificial 
Intelligence Laboratory Memo 349, December 1975.  

Gerald Jay Sussman, Jack Holloway, Guy L Steele, and Alan Bell, 
"Scheme-79 -- Lisp on a chip", IEEE Computer 14, 7, July 1981, 
pages 10-21.