16 Level-0 Module Library

This section describes the classes required at level-0 and the operations defined on instances of those classes. The section is organized by module in alphabetical order. These sub-sections contain information about the predefined classes in EULISP that are necessary to make the language usable.

16.1 Characters

The defined name of this module is character.


16.1.1 character
syntax


Character literals are denoted by the extension glyph, called hash (#), followed by the character-extension glyph, called reverse solidus (\), followed by the name of the character. The syntax for the external representation of characters is defined in syntax table 16.1.1.1. For most characters, their name is the same as the glyph associated with the character, for example: the character “a” has the name “a” and has the external representation #\a. Certain characters in the group named special (see table 9.1 and also syntax table 16.1.1.1) form the syntax category special-character-token and are referred to using the digrams defined in table 16.1.1.


Table 3: Character digrams



Operation Digram


alert \a
backspace \b
delete \d
formfeed \f
linefeed \l
newline \n
return \r
tab \t
vertical tab \v
hex-insertion \x
string delimiter\"
string escape \\



Any character which does not have an external representation dealt with by cases described so far is represented by the digram #\x (see table 16.1.1) followed four hexadecimal digits. The value of the hexadecimal number represents the position of the character in the current character set. Examples of such character literals are #\x0000 and #\xabcd, which denote, respectively, the characters at position 0 and at position 43981 in the character set current at the time of reading or writing. The syntax for the external representation of characters is defined in syntax table 16.1.1.1 below:

16.1.1.1 Syntax

character:
literal-character-token
special-character-token
numeric-character-token
literal-character-token:
#\letter
#\decimal-digit
#\other-character
#\special-character
special-character-token:
#\\a
#\\b
#\\d
#\\f
#\\l
#\\n
#\\r
#\\t
#\\v
#\\"
#\\\
numeric-character-token:
#\\x hexadecimal-digit hexadecimal-digit
hexadecimal-digit hexadecimal-digit

NOTE 1 This text refers to the “current character set” but defines no means of selecting alternative character sets. This is to allow for future extensions and implementation-defined extensions which support more than one character set.


16.1.2 <character>
<object>  class


The class of all characters.


16.1.3 character?
function


Arguments

object :

Object to examine.

Result

Returns object if it is a character, otherwise ().


16.1.4 binary= <character>
method


Specialized Arguments

character1 <character> :

A character.

character2 <character> :

A character.

Result

If character1 is the same character as character2 the result is character1, otherwise the result is ().


16.1.5 binary< <character>
method


Specialized Arguments

character1 <character> :

A character.

character2 <character> :

A character.

Result

If both characters denote uppercase alphabetic or both denote lowercase alphabetic, the result is defined by alphabetical order. If both characters denote a digit, the result is defined by numerical order. In these three cases, if the comparison is t, the result is character1, otherwise it is (). Any other comparison is an error and the result of such comparisons is undefined.

Examples
(binary< #\A #\Z)#\A
(binary< #\a #\z) #\a
(binary< #\0 #\9) #\0
(binary< #\A #\a) undefined
(binary< #\A #\0) undefined
(binary< #\a #\0) undefined
See also

Method binary< <string> for


16.1.6 <string>
class


.


16.1.7 as-lowercase
generic function


Generic Arguments

object <object> :

An object to convert to lower case.

Result

An instance of the same class as object converted to lower case according to the actions of the appropriate method for the class of object.

See also

Another method as-lowercase <string> for <string>.


16.1.8 as-lowercase <character>
method


Specialized Arguments

character <character> :

A character.

Result

If character denotes an upper case character, a character denoting its lower case counterpart is returned. Otherwise the result is the argument.


16.1.9 as-uppercase
generic function


Generic Arguments

object <object> :

An object to convert to upper case.

Result

An instance of the same class as object converted to upper case according to the actions of the appropriate method for the class of object.

See also

Another method is defined on as-uppercase <string> for <string>.


16.1.10 as-uppercase <character>
method


Specialized Arguments

character <character> :

A character.

Result

If character denotes an lower case character, a character denoting its upper case counterpart is returned. Otherwise the result is the argument.


16.1.11 generic-print <character>
method


Specialized Arguments

character <character> :

Character to be ouptut on stream.

stream <stream> :

Stream on which character is to be ouptut.

Result

The character character.

Remarks

Output the interpretation of character on stream.


16.1.12 generic-write <character>
method


Specialized Arguments

character <character> :

Character to be ouptut on stream.

stream <stream> :

Stream on which character is to be ouptut.

Result

The character character.

Remarks

Output external representation of character on stream in the format #\name as described at the beginning of this section.

16.2 Collections

The defined name of this module is collection. A collection is defined as an instance of one of <list>, <string>, <vector>, <table> or any user-defined class for which a method is added to any of the collection manipulation functions. Collection does not name a class and does not form a part of the class hierarchy. This module defines a set of operators on collections as generic functions and default methods with the behaviours given here.

When iterating over a single collection, the order in which elements are processed might not be important, but as soon as more than one collection is involved, it is necessary to specify how the collections are aligned so that it is clear which elements of the collections will be processed together. This is quite straightforward in the cases of <list>, <string> and <vector>, since there is an intuitive natural order for the elements which allows them to be identified by a non-negative integer. Thus, when iterating over a combination of any of these, all the elements at index position i will be processed together, starting with the elements at position 0 and finishing with those at position n - 1 where n is the size of the smallest collection in the combination. The subset of collections which have natural order is called sequence and members of this set can be identified by the predicate sequence?, while collections in general can be identified by collection?.

Collection alignment is more complicated when tables are involved since they use explicit keys rather than natural order to identify their elements. In any iteration over a combination of collections including a table or some tables, the set of keys used is the intersection of the keys of the tables and the implicit keys of the other collection classes present; this identifies the elements of the collections with common keys. Thus, for an iteration to process any elements from the combination of a collection with natural order and a table, the table must have some integer keys and they must be in the range [0size) of the collection with natural order.

A conforming level-0 implementation must define methods on these functions to support operations on lists (16.12), strings (16.16), tables (16.18), vector (16.19) and any combination of these.


16.2.1 <collection>
<object>  class


The class of all collections.


16.2.2 <sequence>
<collection>  class


The class of all sequences, the subset of collections which have natural order.


16.2.3 <character-sequence>
<sequence>  class


The class of all sequences of characters e.g. <string>.


16.2.4 <collection-condition>
<condition>  condition


This is the condition class for all collection processing conditions.


16.2.5 accumulate
generic function


Generic Arguments

function <function> :

A function of two arguments.

obj <object> :

The object which is the initial value for the accumulation operation.

collection <collection> :

The collection which is the subject of the accumulation operation.

Result

The result is the result of the application of function to the accumulated result and successive elements of collection. The initial value of the accumulated result is supplied by obj.

Examples

Note that the order of the elements in the result of the second example depends on the hashing algorithm of the implementation and does not prescribe the result that any particular implementation must give.

(accumulate * 1 #(1 2 3 4 5)) 120
(accumulate
(lambda (a v) (cons v a))
()
(make <table>
’entries
’((1 . b) (0 . a) (2 . c))))
(c b a)


16.2.6 accumulate1
generic function


Generic Arguments

function <function> :

A function of two arguments.

collection <collection> :

The collection which is the subject of the accumulation operation.

Result

The result is the result of the application of function to the accumulated result and successive elements of collection starting with the second element. The initial value of the accumulated result is the first element of collection. The terms first and second correspond to the appropriate elements of a natural order collection, but no elements in particular of an explicit key collection. If collection is empty, the result is ().

Examples
(accumulate1
(lambda (a v)
(if (evenp v) (cons v a) a))
’(1 2 3 4 5))
(4 2)


16.2.7 all?
generic function


Generic Arguments

function <function> :

A function to be used as a predicate on the elements of the collection(s).

collection <collection> :

A collection.

more-collectionsopt :

More collections.

Result

The function is applied to argument lists constructed from corresponding successive elements of collection and more-collections. If the result is t for all elements of collection and more-collections the result of all? is t otherwise ().

Examples
(all? even? #(1 2 3 4))()
(all? even? #(2 4 6 8)) t
See also

any?.


16.2.8 any?
generic function


Generic Arguments

function <function> :

A function to be used as a predicate on the elements of the collection(s).

collection <collection> :

A collection.

more-collectionsopt :

More collections.

Result

The function is applied to argument lists constructed from corresponding successive elements of collection and more-collections. If the result is t, the result of any? is t and there are no further applications of function to elements of collection and more-collections. If any of the collections is exhausted, the result of any? is ().

Examples
(any? even? #(1 2 3 4)) t
(let ((x (list 1 2 3 4)))
(any? > x (cdr x)))
()
(any?
(lambda (a b) (= (% a b) 0))
#(3 2) ’(1 0))
t
See also

all?.


16.2.9 collection?
generic function


Generic Arguments

object <object> :

An object to examine.

Result

Returns t if object is a collection, otherwise ().

Remarks

This predicate does not return object because () is a collection.


16.2.10 concatenate
generic function


Generic Arguments

collection <collection> :

A collection.

more-collectionsopt :

More collections.

Result

The result is an object of the same class as collection.

Remarks

The contents of the result object depend on whether collection has natural order or not:

  1. If collection has natural order then the size of the result is the sum of the sizes of collection and more-collections. The result collection is initialized with the elements of collection followed by the elements of each of more-collections taken in turn. If any element cannot be stored in the result collection, for example, if the result is a string and some element is not a character, an error is signalled (condition class: collection-condition).
  2. If collection does not have natural order, then the result will contain associations for each of the keys in collection and more-collections. If any key occurs more than once, the associated value in the result is the value of the last occurrence of that key after processing collection and each of more-collections taken in turn.

Examples
(concatenate #(1) ’(2) "bc") #(1 2 #\b #\c))
(concatenate "a" ’(#\b)) "ab"
(concatenate
(make <table>)
’(a b)
"c")
#<table:  
  0 -> "c",  
  1 -> b>


16.2.11 delete
generic function


Generic Arguments

object <object> :

Object to be removed.

collection <collection> :

A collection.

testopt :

The function to be used to compare object—/ and the elements of collection.

Result

If there is an element of collection such that test returns t when applied to object—/ and that element, then the result is the modified collection, less that element. Otherwise, the result is collection.

Remarks

delete is destructive. The test function defaults to eql.


16.2.12 do
generic function


Generic Arguments

function <function> :

A function.

collection <collection> :

A collection.

more-collectionsopt :

More collections.

Result

The result is (). This operator is used for side-effect only. The function is applied to argument lists constructed from corresponding successive elements of collection and more-collections and the result is discarded. Application stops if any of the collections is exhausted.

Examples
(do prin ’(1 b #\c))1bc
(do write ’(1 b #\c))1b#\c


16.2.13 element
generic function


Generic Arguments

collection <collection> :

The object to be accessed or updated.

key <object> :

The object identifying the key of the element in collection.

Result

The value associated with key in collection.

Examples
(element "abc" 1) #\b
(element ’(a b c) 1) b
(element #(a b c) 1) b
(element
(make <table> fill-value: ’b)
1)
b


16.2.14 (setter element)
setter


Generic Arguments

collection <collection> :

The object to be accessed or updated.

key <object> :

The object identifying the key of the element in collection.

value <object> :

The object to replace the value associated with key in collection (for setter).

Result

The argument supplied as value, having updated the association of key in collection to refer to value.


16.2.15 empty?
generic function


Generic Arguments

collection <collection> :

The object to be examined.

Result

Returns t if collection is the object identified with the empty object for that class of collection.

Examples
(emptyp "") t
(emptyp ()) t
(emptyp #()) t
(emptyp (make <table>))t


16.2.16 fill
generic function


Generic Arguments

collection <collection> :

A collection to be (partially) filled.

object <object> :

The object with which to fill collection.

keysopt :

The keys with which object is to be associated.

Result

The result is ().

Remarks

This function side-effects collection by updating the values associated with each of the specified keys with obj. If no keys are specified, the whole collection is filled with obj. Otherwise, the key specification can take two forms:

  1. A collection, in which case the values of the collection are taken to be the keys of collection to be associated with obj.
  2. Two fixed precision integers, denoting the start and end keys, respectively, in a natural order collection to be associated with obj. An error is signalled (condition class: collection-condition) if collection does not have natural order. It is an error if the start and end do not specify an ascending sub-interval of the interval [0,size), where size is that of collection.


16.2.17 find-key
generic function


Generic Arguments

collection <collection> :

A collection.

test <function> :

A function.

skipopt :

An integer.

failureopt :

An integer.

Result

The function test is applied to successive elements of collection. If test returns t when applied to an element, then the result of find-key is the key associated with that element.

Remarks

The value skip, which defaults to zero, indicates how many successful tests are to be made before returning a result. The value failure, which defaults to (), is returned if no key satisfying the test was found. Note that skip and failure are positional arguments and that skip must be specified if failure is specified.


16.2.18 first
generic function


Generic Arguments

sequence <sequence> :

A sequence.

Result

The result is contents of index position 0 of sequence.


16.2.19 last
generic function


Generic Arguments

sequence <sequence> :

A sequence.

Result

The result is last element of sequence.


16.2.20 key-sequence
generic function


Generic Arguments

collection <collection> :

A collection.

Result

The result is a collection comprising the keys of collection.


16.2.21 map
generic function


Generic Arguments

function <function> :

A function.

collection <collection> :

A collection.

more-collectionsopt :

More collections.

Result

The result is an object of the same class as collection. The elements of the result are computed by the application of function to argument lists constructed from corresponding successive elements of collection and more-collections. Application stops if any of the collections is exhausted.

Examples
(map cons #(1 2) ’(3)) #((1 . 3))
(map
(lambda (f) (f 1 2))
#(+ - * %))
#(3 -1 2 1)


16.2.22 member
generic function


Generic Arguments

object <object> :

The object to be searched for in collection.

collection <collection> :

The collection to be searched.

testopt :

The function to be used to compare object and the elements of collection.

Result

Returns t if there is an element of collection such that the result of the application of test to object and that element is t. If test is not supplied, eql is used by default. Note that t denotes any value that is not () and that the class of the result depends on the class of collection. In particular, if collection is a list, the result of member is a list.

Examples
(member #\b "abc") t
(member ’b ’(a b c)) (b c)
(member ’b #(a b c)) t
(member
’b
(make <table>
’entries
’((1 . b) (0 . a) (2 . c))))
t


16.2.23 remove
generic function


Generic Arguments

object <object> :

Object to be removed.

collection <collection> :

A collection.

testopt :

The function to be used to compare object and the elements of collection.

Result

If there is an element of collection such that test returns t when applied to object and that element, then the result is a shallow copy of collection less that element. Otherwise, the result is collection.

Remarks

The test function defaults to eql.


16.2.24 reverse
generic function


Generic Arguments

collection <collection> :

A collection.

Result

The result is an object of the same class as collection whose elements are the same as those in collection, but in the reverse order with respect to the natural order of collection. If collection does not have natural order, the result is equal to the argument.

Examples
(reverse "abc") "cba"
(reverse ’(1 2 3))(3 2 1)
(reverse #(a b c))#(c b a)


16.2.25 reverse!
generic function


Generic Arguments

collection <collection> :

A collection.

Result

Destructively reverses the order of the elements in collection (see reverse) and returns it.


16.2.26 sequence?
generic function


Generic Arguments

object <object> :

An object to examine.

Result

Returns t if object is a sequence (has natural order), otherwise ().

Remarks

This predicate does not return object because () is a sequence.


16.2.27 size
generic function


Generic Arguments

collection <collection> :

The object to be examined.

Result

An integer which denotes the size of collection according to the method for the class of collection.

Examples
(size "") 0
(size ()) 0
(size #()) 0
(size (make <table>)) 0
(size "abc") 3
(size (cons 1 ())) 1
(size (cons 1 . 2)) 1
(size (cons 1 (cons 2 . 3))) 2
(size ’(1 2 3)) 3
(size #(a b c)) 3
(size (make <table> ’entries ’((0 . a)))1


16.2.28 slice
generic function


Generic Arguments

sequence <sequence> :

A sequence.

start <fpi> :

The index of the first element of the slice.

end <fpi> :

The index of the last element of the slice.

Result

The result is new sequence of the same class as sequence containing the elements of sequence from start up to but not including end.

Examples
(slice ’(a b c d) 1 3)(b c)


16.2.29 sort
generic function


Generic Arguments

sequence <sequence> :

A sequence.

comparator <function> :

A function.

Result

The result of sort is a new sequence comprising the elements of sequence ordered according to comparator.

Remarks

Methods on this function are only defined for <list> and <vector>.


16.2.30 sort!
generic function


Generic Arguments

sequence <sequence> :

A sequence.

comparator <function> :

A function.

Result

Destructively sorts the elements of sequence (see sort) and returns it.

Remarks

Methods on this function are only defined for <list> and <vector>.


16.2.31 (converter <list>)
converter


Specialized Arguments

collection <collection> :

A collection to be converted into a list.

Result

If collection is a list, the result is the argument. Otherwise a list is constructed and returned whose elements are the elements of collection. If collection has natural order, then the elements will appear in the result in the same order as in collection. If collection does not have natural order, the order in the resulting list is undefined.

See also

Conversion (16.4).


16.2.32 (converter <string>)
converter


Specialized Arguments

collection <collection> :

A collection to be converted into a string.

Result

If collection is a string, the result is the argument. Otherwise a string is constructed and returned whose elements are the elements of collection as long as all the elements of collection are characters. An error is signalled (condition class: conversion-condition) if any element of collection is not a character. If collection has natural order, then the elements will appear in the result in the same order as in collection. If collection does not have natural order, the order in the resulting string is undefined.

See also

Conversion (16.4).


16.2.33 (converter <table>)
converter


Specialized Arguments

collection <collection> :

A collection to be converted into a table.

Result

If collection is a table, the result is the argument. Otherwise a table is constructed and returned whose elements are the elements of collection. If collection has natural order, then the elements will be stored under integer keys in the range [0size), otherwise the keys used will be the keys associated with the elements of collection.

See also

Conversion (16.4).


16.2.34 (converter <vector>)
converter


Specialized Arguments

collection <collection> :

A collection to be converted into a vector.

Result

If collection is a vector, the result is the argument. Otherwise a vector is constructed and returned whose elements are the elements of collection. If collection has natural order, then the elements will appear in the result in the same order as in collection. If collection does not have natural order, the order in the resulting vector is undefined.

See also

Conversion (16.4).

16.3 Comparison

The defined name of this module is compare. There are three binary functions for comparing objects for equality, eq, eql, binary= and the n-ary = which uses binary=. The three binary functions are related in the following way:

(eq a b)(eql a b)(binary= a b)
(eq a b)⁄⇐(eql a b)⁄⇐(binary= a b)

There are four n-ary function for comparing objects by order, < and > which are implemented by the generic function binary<, <= and >= which are implemented by the generic functions binary< and binary=. There is also one binary function for comparing objects for inequality, !=. A summary of the comparison functions and the classes for which they have defined behaviour is given below:

eq: <object>×<object>


eql: <object>×<object> eq
<character>×<character>
<fpi>×
<fpi>
<double-float>×<double-float> binary=


binary=:<object>×<object>
<character>×<character>
<null>×<null>
<number>×<number> eql
<fpi>×
<fpi>
<double-float>×<double-float>
<double-float>×<fpi>
<fpi>×<double-float>
<cons>×<cons>
<string>×<string>
<vector>×<vector>


binary<: <character>×<character>
<symbol>×<symbol>
<fpi>×
<fpi>
<double-float>×<double-float>
<string>×<string>


=: <object>×<object> binary=
!=: <object>×<object>
<: <object>×<object> binary<
>: <object>×<object>
<=: <object>×<object>
>=: <object>×<object>


16.3.1 eq
function


Arguments

object1 :

An object.

object2 :

An object.

Result

Compares object1 and object2 and returns t if they are the same object, otherwise (). Same in this context means “identifies the same memory location”.

Remarks

In the case of numbers and characters the behaviour of eq might differ between processors because of implementation choices about internal representations. Therefore, eq might return t or () for numbers which are = and similarly for characters which are eql, depending on the implementation .

Examples
(eq ’a ’a) t
(eq ’a ’b) ()
(eq #\a #\a) t or ()
(eq 3 3) t or ()
(eq 3 3.0) ()
(eq 3.0 3.0) t or ()
(eq (cons ’a ’b) (cons ’a ’c)) ()
(eq (cons ’a ’b) (cons ’a ’b)) ()
(eq ’(a . b) ’(a . b)) t or ()
(let ((x (cons ’a ’b))) (eq x x))t
(let ((x ’(a . b))) (eq x x)) t
(eq "string" "string") t or ()
(eq #(’a ’b) #(’a ’b)) t or ()
(let ((x #(’a ’b))) (eq x x)) t


16.3.2 eql
function


Arguments

object1 :

An object.

object2 :

An object.

Result

If the class of object1 and of object2 is the same and is a subclass of <character> or <number>, the result is that of comparing them under binary= <character> or binary= <number> respectively. Otherwise the result is that of comparing them under eq.

Examples

Given the same set of examples as for eq, the same result is obtained except in the following cases:

(eql #\a #\a)t
(eql 3 3) t
(eql 3.0 3.0) t


16.3.3 binary=
generic function


Arguments

object1, <object> :

An object.

object2, <object> :

An object.

Result

Returns t or () according to the method for the class(es) of object1 and object2. It is an error if either or both of the arguments is self-referential.

See also

Class specific methods on binary= are defined for <character>, <list>, <number> (with specialisations for <fpi> and <double-float>), <string>, ??. All other cases are handled by the default method defined for <object>:


16.3.4 binary= <object>
method


Specialized Arguments

object1 <object> :

An object.

object2 <object> :

An object.

Result

The result is as if eql had been called with the arguments supplied.


16.3.5 binary<
generic function


Generic Arguments

object1 <object> :

An object.

object2 <object> :

An object.

Result

The first argument if it is less than the second, according to the method for the class of the arguments, otherwise ().

See also

Class specific methods on binary< are defined for <character>, <string>, <fpi> and <double-float>.


16.3.6 =
function


Arguments

number1 :

A non-empty sequence of numbers.

Result

Given one argument the result is t. Given more than one argument the result is determined by binary=, returning t if all the arguments are the same, otherwise ().


16.3.7 !=
function


Arguments

number1 :

A non-empty sequence of numbers.

Result

Given one argument the result is (). Given more than one argument the result is determined by binary=, returning () if all the arguments are the same, otherwise t.


16.3.8 <
function


Arguments

object1 :

A non-empty sequence of objects.

Result

Given one argument the result is t. Given more than one argument the result is t if the sequence of objects object1 up to objectn is strictly increasing according to the generic function binary<. Otherwise, the result is ().


16.3.9 >
function


Arguments

object1 :

A non-empty sequence of objects.

Result

Given one argument the result is t. Given more than one argument the result is t if the sequence of objects object1 up to objectn is strictly decreasing according to the generic function binary< applied to the arguments in reverse order. Otherwise, the result is ().


16.3.10 <=
function


Arguments

object1 :

A non-empty sequence of objects.

Result

Given one argument the result is t. Given more than one argument the result is t if the sequence of objects object1 up to objectn is strictly increasing according to the generic function binary< and binary=. Otherwise, the result is ().


16.3.11 >=
function


Arguments

object1 :

A non-empty sequence of objects.

Result

Given one argument the result is t. Given more than one argument the result is t if the sequence of objects object1 up to objectn is strictly decreasing according to the generic function binary< and binary= applied to the arguments in reverse order. Otherwise, the result is ().


16.3.12 max
function


Arguments

object1 :

A non-empty sequence of objects.

Result

The maximal element of the sequence of objects object1 up to objectn using the generic function binary<. Zero arguments is an error. One argument returns object1.


16.3.13 min
function


Arguments

object1 :

A non-empty sequence of objects.

Result

The minimal element of the sequence of objects object1 up to objectn using the generic function binary<. Zero arguments is an error. One argument returns object1.

16.4 Conversion

The defined name of this module is convert.

The mechanism for the conversion of an instance of one class to an instance of another is defined by a user-extensible framework which has some similarity to the setter mechanism.

To the user, the interface to conversion is via the function convert, which takes an object and some class to which the object is to be converted. The target class is used to access an associated converter function, in fact, a generic function, which is applied to the source instance, dispatching on its class to select the method which implements the appropriate conversion. Thus, having defined a new class to which it may be desirable to convert instances of other classes, the programmer defines a generic function:

(defgeneric (converter new-class) (instance))

Hereafter, new converter methods may be defined for new-class using a similar extended syntax for defmethod:

(defmethod (converter new-class)
           ((instance other-class)))

The conversion is implemented by defining methods on the converter for new-class which specialize on the source class. This is also how methods are documented in this text: by an entry for a method on the converter function for the target class. In general, the method for a given source class is defined in the section about that class, for example, converters from one kind of collection to another are defined in section 16.2, converters from string in section 16.16, etc..


16.4.1 convert
function


Arguments

object :

An instance of some class to be converted to an instance of class.

class :

The class to which object is to be converted.

Result

Returns an instance of class which is equivalent in some class-specific sense to object, which may be an instance of any type. Calls the converter function associated with class to carry out the conversion operation. An error is signalled (condition: <no-converter> ) if there is no associated function. An error is signalled (condition: <no-applicable-method> ) if there is no method to convert an instance of the class of object to an instance of class.


16.4.2 <conversion-condition>
<condition>  condition


This is the general condition class for all conditions arising from conversion operations.

Initialization Options

source <object> :

The object to be converted into an instance of target-class.

target-class <class> :

The target class for the conversion operation.

Remarks

Should be signalled by convert or a converter method.


16.4.3 <no-converter>
<conversion-condition>  condition


Initialization Options

source <object> :

The object to be converted into an instance of target-class.

target-class <class> :

The target class for the conversion operation.

Remarks

Should be signalled by convert if there is no associated function.


16.4.4 converter
function


Arguments

target-class :

The class whose set of conversion methods is required.

Result

The accessor returns the converter function for the class target-class. The converter is a generic-function with methods specialized on the class of the object to be converted.


16.4.5 (setter converter)
setter


Arguments

target-class :

The class whose converter function is to be replaced.

generic-function :

The new converter function.

Result

The new converter function. The setter function replaces the converter function for the class target-class by generic-function. The new converter function must be an instance of <generic-function>.

Remarks

Converter methods from one class to another are defined in the section pertaining to the source class.

See also

Converter methods are defined for collections (16.2), double float (16.6), fixed precision integer (16.9), string (16.16), symbol (16.17), vector (16.19).

16.5 Copying

The defined name of this module is copy.


16.5.1 deep-copy
generic function


Generic Arguments

object :

An object to be copied.

Result

Constructs and returns a copy of the source which is the same (under some class specific predicate) as the source and whose slots contain copies of the objects stored in the corresponding slots of the source, and so on. The exact behaviour for each class of object is defined by the most applicable method for object.

See also

Class specific sections which define methods on deep-copy: list (16.12), string (16.16), table (16.18) and vector (16.19).


16.5.2 deep-copy <object>
method


Specialized Arguments

object <object> :

An object.

Result

Returns object.


16.5.3 deep-copy <class>
method


Specialized Arguments

class <class> :

A class.

Result

Constructs and returns a new structure whose slots are initialized with copies (using deep-copy) of the contents of the slots of class.


16.5.4 shallow-copy
generic function


Generic Arguments

object :

An object to be copied.

Result

Constructs and returns a copy of the source which is the same (under some class specific predicate) as the source. The exact behaviour for each class of object is defined by the most applicable method for object.

See also

Class specific sections which define methods on shallow-copy: pair (16.12), string (16.16), table (16.18) and vector (16.19).


16.5.5 shallow-copy <object>
method


Specialized Arguments

object <object> :

An object.

Result

Returns object.


16.5.6 shallow-copy <class>
method


Specialized Arguments

class <class> :

A class.

Result

Constructs and returns a new structure whose slots are initialized with the contents of the correpsonding slots of struct.

16.6 Double Precision Floats

The defined name of this module is double. Arithmetic operations for <double-float> are defined by methods on the generic functions defined in the compare module (16.3):

binary=, binary<,

the number module (16.14):

binary+, binary-, binary*, binary/, binary-mod, negate, zero?

the float module (16.7):

ceiling, floor, round, truncate

and the elementary functions module (??):

acos, asin, atan, atan2, cos, sin, tan, cosh, sinh, tanh, exp, log, log10, pow, sqrt

The behaviour of these functions is defined in the modules noted above.


16.6.1 <double-float>
<float>  class


The class of all double precision floating point numbers.

The syntax for the exponent of a double precision floating point is given below:

double-exponent:
d signopt decimal-integer
D signopt decimal-integer

The general syntax for floating point numbers is given in syntax table 16.7.1.1.


16.6.2 double-float?
function


Arguments

object :

Object to examine.

Result

Returns object if it is a double float, otherwise ().

See also

float? (16.14).


16.6.3 most-positive-double-float <double-float>
constant


Remarks

The value of most-positive-double-float is that positive double precision floating point number closest in value to (but not equal to) positive infinity that the processor provides.


16.6.4 least-positive-double-float <double-float>
constant


Remarks

The value of least-positive-double-float is that positive double precision floating point number closest in value to (but not equal to) zero that the processor provides.


16.6.5 least-negative-double-float <double-float>
constant


Remarks

The value of least-negative-double-float is that negative double precision floating point number closest in value to (but not equal to) zero that the processor provides. Even if the processor provide negative zero, this value must not be negative zero.


16.6.6 most-negative-double-float <double-float>
constant


Remarks

The value of most-negative-double-float is that negative double precision floating point number closest in value to (but not equal to) negative infinity that the processor provides.


16.6.7 (converter <string>)
converter


Specialized Arguments

x <double-float> :

A double precision float.

Result

Constructs and returns a string, the characters of which correspond to the external representation of x as produced by generic-print, namely that specified in the syntax as [sign]float format 3.


16.6.8 (converter <fpi>)
converter


Specialized Arguments

x <double-float> :

A double precision float.

Result

A fixed precision integer.

Remarks

This function is the same as the <double-float> method of round. It is defined for the sake of symmetry.


16.6.9 generic-print <double-float>
method


Specialized Arguments

double <double-float> :

The double float to be output on stream.

stream <stream> :

The stream on which the representation is to be output.

Result

The double float supplied as the first argument.

Remarks

Outputs the external representation of double on stream, as an optional sign preceding the syntax defined by float format 3. Finer control over the format of the output of floating point numbers is provided by some of the formatting specifications of format (see section 16.8).


16.6.10 generic-write <double-float>
method


Specialized Arguments

double <double-float> :

The double float to be output on stream.

stream <stream> :

The stream on which the representation is to be output.

Result

The double float supplied as the first argument.

Remarks

Outputs the external representation of double on stream, as an optional sign preceding the syntax defined by float format 3. Finer control over the format of the output of floating point numbers is provided by some of the formatting specifications of format (see section 16.8).

16.7 Floating Point Numbers

The defined name of this module is float. This module defines the abstract class <float> and the behaviour of some generic functions on floating point numbers. Further operations on numbers are defined in the numbers module (16.14) and further operations on floating point numbers are defined in the elementary functions module (??). A concrete float class is defined in the double float module (16.6).


16.7.1 float
syntax


The syntax for the external representation of floating point literals is defined in syntax table 16.7.1.1. The representation used by write and ?? is that of a sign, a whole part and a fractional part without an exponent, namely that defined by float format 3. Finer control over the format of the output of floating point numbers is provided by some of the formatting specifications of format (section 16.8).

16.7.1.1 Syntax

float:
signopt unsigned-float exponentopt
unsigned-float:
float-format-1
float-format-2
float-format-3
float-format-1:
decimal-integer .
float-format-2:
. decimal-integer
float-format-3:
float-format-1 decimal-integer
exponent:
double-exponent

A floating point number has six forms of external representation depending on whether either or both the whole and the fractional part are specified and on whether an exponent is specified. In addition, a positive floating point number is optionally preceded by a plus sign and a negative floating point number is preceded by a minus sign. For example: +123. (float format 1), -.456 (float format 2), 123.456 (float format 3); and with exponents: +123456.D-3, 1.23455D2, -.123456D3.


16.7.2 <float>
<number>  class


The abstract class which is the superclass of all floating point numbers.


16.7.3 float?
function


Arguments

objext :

Object to examine.

Result

Returns object if it is a floating point number, otherwise ().


16.7.4 ceiling
generic function


Generic Arguments

float <float> :

A floating point number.

Result

Returns the smallest integral value not less than float expressed as a float of the same class as the argument.


16.7.5 floor
generic function


Generic Arguments

float <float> :

A floating point number.

Result

Returns the largest integral value not greater than float expressed as a float of the same class as the argument.


16.7.6 round
generic function


Arguments

float :

A floating point number.

Result

Returns the integer whose value is closest to float, except in the case when float is exactly half-way between two integers, when it is rounded to the one that is even.


16.7.7 truncate
generic function


Arguments

float :

A floating point number.

Result

Returns the greatest integer value whose magnitude is less than or equal to float.

16.8 Formatted-IO

The defined name of this module is formatted-io.
16.8.1 scan
function


Arguments

format-string :

A string containing format directives.

streamopt :

A stream from which input is to be taken.

Result

Returns a list of the objects read from stream.

Remarks

This function provides support for formatted input. The format-string specifies reading directives, and inputs are matched according to these directives. An error is signaled (condition: <scan-mismatch>) if the class of the object read is not compatible with the specified directive. The second (optional) argument specifies a stream from which to take input. If stream is not supplied, input is taken from stdin. Scan returns a list of the objects read in.

~a any:
any object.
~b binary:
an integer in binary format.
~c character:
a single character
~d decimal:
an integer decimal format.
~nopte:
a exponential-format floating-point number.
~noptf:
a fixed-format floating-point number.
~o octal:
an integer in octal format.
~r radix:
an integer in specified radix format.
~x hexadecimal:
an integer in hexadecimal format.
~% newline:
matches a newline character in the input.


16.8.2 <scan-mismatch>
??  condition


Initialization Options

format-string string :

The value of this option is the format string that was passed to scan.

input list :

The value of this option is a list of the items read by scan up to and including the object that caused the condition to be signaled.

Remarks

This condition is signalled by scan if the format string does not match the data input from stream.


16.8.3 sformat
function


Arguments

stream :

A stream.

format-string :

A string containing format directives.

object1 opt :

A sequence of objects to be output on stream.

Result

Returns stream and has the side-effect of outputting objects according the formats specified in format-string to stream. Characters are output as if the string were output by the ?? function with the exception of those prefixed by tilde—graphic representation ~—which are treated specially as detailed in the following list. These formatting directives are intentionally compatible with the facilities defined for the function fprintf in ISO/IEC 9899 : 1990 except for the prefix ~ rather than %.

~a any:
uses ?? to output the argument.
~b binary:
the argument must be an integer and is output in binary notation (syntax table 16.10.1.1).
~c character:
the argument must be a character and is output using write (syntax table 16.1.1.1).
~d decimal:
the argument must be an integer and is output using write (syntax table 16.10.1.1).
~mopt.nopte exponential-format floating-point:
the argument must be a floating point number. It is output in the style -optd.ddde±dd, in a field of width m characters, where there are n precision digits after the decimal point, or 6 digits, if n is not specified (syntax table 16.7.1.1). If the value to be output has fewer characters than m it is padded on the left with spaces.
~mopt.noptf fixed-format floating-point:
the argument must be a floating point number. It is output in the style -optddd.ddd, in a field of width m characters, where the are n precision digits after the decimal point, or 6 digits, if n is not specified (syntax table 16.7.1.1). The value is rounded to the appropriate number of digits. If the value to be output has fewer characters than m it is padded on the left with spaces.
~mopt.noptg generalized floating-point:
the argument must be a floating point number. It is output in either fixed-format or exponential notation as appropriate (syntax table 16.7.1.1).
~o octal:
the argument must be an integer and is output in octal notation (syntax table 16.10.1.1).
~nr radix:
the argument must be an integer and is output in radix n notation (syntax table 16.10.1.1).
~s s-expression:
uses write to output the argument (syntax table 9.5.0.5).
~noptt tab:
output sufficient spaces to reach the next tab-stop, if n is not specified, or the nth tab stop if it is.
~x hexadecimal:
the argument must be an integer and is output in hexadecimal notation (syntax table 16.10.1.1).
~% newline:
output a newline character.
~& conditional newline:
output a newline character using, if it cannot be determined that the output stream is at the beginning of a fresh line.
~~ tilde:
output a tilde character using ??.


16.8.4 format
function


Arguments

format-string :

A string containing format directives.

object1 opt :

A sequence of objects to be output on stdout.

Result

Returns stdout and has the side-effect of outputting objects according the formats specified in format-string (see sformat) to stdout.


16.8.5 fmt
function


Arguments

format-string :

A string containing format directives.

object1 opt :

A sequence of objects to be formatted into a string.

Remarks

Return the string created by formatting the objects according the formats specified in format-string (see sformat).

16.9 Fixed Precision Integers

The defined name of this module is fpi. Arithmetic operations for <fpi> are defined by methods on the generic functions defined in the compare module (16.3):

binary=, binary<,

the number module:

binary+, binary-, binary*, binary/, binary%, binary-gcd, binary-lcm, binary-mod, negate, zero?

and in the integer module:

even?

The behaviour of these functions is defined in the modules noted above.


16.9.1 <fpi>
<integer>  class


The class of all instances of fixed precision integers.


16.9.2 int?
function


Arguments

object :

Object to examine.

Result

Returns object if it is fixed precision integer, otherwise ().


16.9.3 most-positive-int <fpi>
constant


Remarks

This is an implementation-defined constant. A conforming processor must support a value greater than or equal to 32767 and greater than or equal to the value of maximum-vector-index.


16.9.4 most-negative-int <fpi>
constant


Remarks

This is an implementation-defined constant. A conforming processor must support a value less than or equal to -32768.


16.9.5 (converter <string>)
converter


Specialized Arguments

integer <fpi> :

An integer.

Result

Constructs and returns a string, the characters of which correspond to the external representation of integer in decimal notation.


16.9.6 (converter <double-float>)
converter


Specialized Arguments

integer <fpi> :

An integer.

Result

Returns a double float whose value is the floating point approximation to integer.


16.9.7 generic-print <fpi>
method


Specialized Arguments

integer <fpi> :

An integer to be output on stream.

stream <stream> :

The stream on which the representation is to be output.

Result

The fixed precision integer supplied as the first argument.

Remarks

Outputs external representation of integer on stream in decimal as defined by decimal integer at the beginning of this section.


16.9.8 generic-write <fpi>
method


Specialized Arguments

integer <fpi> :

An integer to be output on stream.

stream <stream> :

The stream on which the representation is to be output.

Result

The fixed precision integer supplied as the first argument.

Remarks

Outputs external representation of integer on stream in decimal as defined by decimal integer at the beginning of this section.

16.10 Integers

The defined name of this module is integer. This module defines the abstract class <integer> and the behaviour of some generic functions on integers. Further operations on numbers are defined in the numbers module (16.14). A concrete integer class is defined in the fixed precision integer module (16.9).


16.10.1 integer
syntax


A positive integer is has its external representation as a sequence of digits optionally preceded by a plus sign. A negative integer is written as a sequence of digits preceded by a minus sign. For example, 1234567890, -456, +1959.

Integer literals have an external representation in any base up to base 36. For convenience, base 2, base 8 and base 16 have distinguished notations—#b, #o and #x, respectively. For example: 1234, #b10011010010, #o2322 and #x4d2 all denote the same value.

The general notation for an arbitrary base is #baser, where base is an unsigned decimal number. Thus, the above examples may also be written: #10r1234, #2r10011010010, #8r2322, #16r4d2 or #36rya. The reading of any number is terminated on encountering a character which cannot be a constituent of that number. The syntax for the external representation of integer literals is defined below.

16.10.1.1 Syntax

integer:
signopt unsigned-integer
sign: one of
+ -
unsigned-integer:
binary-integer
octal-integer
decimal-integer
hexadecimal-integer
specified-base-integer
binary-integer:
#b binary-digit+
binary-digit: one of
0 1
octal-integer:
#o octal-digit+
octal-digit: one of
0 1 2 3 4 5 6 7
decimal-integer:
decimal-digit+
hexadecimal-integer:
#x hexadecimal-digit+
hexadecimal-digit:
decimal-digit
hex-lower-letter
hex-upper-letter
hex-lower-letter: one of
a b c d e f
hex-upper-letter: one of
A B C D E F
specified-base-integer:
# base-specification r
specified-base-digit
specified-base-digit*
base-specification:
{ 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 }
{ 1 | 2 } decimal-digit
3 { 0 | 1 | 2 | 3 | 4 | 5 | 6 }
specified-base-digit:
decimal-digit
letter

NOTE 1 At present this text does not define a class integer with variable precision. It is planned this should appear in a future version at level-1 of the language. The class will be named ??. The syntax given here is applicable to both fixed and variable precision integers.


16.10.2 <integer>
<number>  class


The abstract class which is the superclass of all integer numbers.


16.10.3 integer?
function


Arguments

object :

Object to examine.

Result

Returns object if it is an integer, otherwise ().


16.10.4 even?
generic function


Arguments

integer, <integer> :

An integer.

Result

Returns t if two divides integer, otherwise ().


16.10.5 odd?
function


Arguments

integer :

An integer.

Result

Returns the equivalent of the logical negation of even? applied to integer.

16.11 Keywords

The defined name of this module is keyword.
16.11.1 keyword
syntax


The syntax of keywords is very similar to that of identifiers and of symbols, including all the escape conventions, but are distinguished by a colon (:) suffix:

16.11.1.1 Syntax

keyword:
identifier:

It is an error to use a keyword where an identifier is expected, such as, for example, in lambda parameter lists or in let binding forms.

The matter of keywords appering in lambda parameter lists, for example, rest:, instead of the dot notation, is currently an open issue.

Operationally, the most important aspect of keywords is that each is unique, or, stated the other way around: the result of processing every syntactic token comprising the same sequence of characters which denote a keyword is the same object. Or, more briefly, every keyword with the same name denotes the same keyword. A consequence of this guarantee is that keywords may be compared using eq.


16.11.2 <keyword>
<name>  class


The class of all instance of <keyword>.

Initialization Options

string string :

The string containing the characters to be used to name the keyword. The default value for string is the empty string, thus resulting in the keyword with no name, written |:|.

What is the defined behaviour if the last character of string is colon?


16.11.3 keyword?
function


Arguments

object :

Object to examine.

Result

Returns object if it is a keyword.


16.11.4 keyword-name
function


Arguments

keyword :

A keyword.

Result

Returns a string which is binary= <string> to that given as the argument to the call to make which created keyword. It is an error to modify this string.


16.11.5 keyword-exists?
function


Arguments

string :

A string containing the characters to be used to determine the existence of a keyword with that name.

Result

Returns the keyword whose name is string if that keyword has already been constructed by make. Otherwise, returns ().


16.11.6 generic-print <keyword>
method


Specialized Arguments

keyword <keyword> :

The keyword to be output on stream.

stream <stream> :

The stream on which the representation is to be output.

Result

The keyword supplied as the first argument.

Remarks

Outputs the external representation of keyword on stream as described in the section on symbols, interpreting each of the characters in the name.


16.11.7 generic-write <keyword>
method


Specialized Arguments

keyword <keyword> :

The keyword to be output on stream.

stream <stream> :

The stream on which the representation is to be output.

Result

The keyword supplied as the first argument.

Remarks

Outputs the external representation of keyword on stream as described in the section on symbols. If any characters in the name would not normally be legal constituents of a keyword, the output is preceded and succeeded by multiple-escape characters.

Examples
(write (make <keyword> ’string "abc"))abc:
(write (make <keyword> ’string "a c")) |a c:|
(write (make <keyword> ’string ").(")) |).(:|


16.11.8 (converter <string>)
converter


Specialized Arguments

keyword <keyword> :

A keyword to be converted to a string.

Result

A string.

Remarks

This function is the same as keyword-name. It is defined for the sake of symmetry.

16.12 Lists

The name of this module is list. The class <list> is an abstract class and has two subclasses: <null> and <cons>. The only instance of <null> is the empty list. The combination of these two classes allows the creation of proper lists, since a proper list is one whose last pair contains the empty list in its cdr field. See also section 16.2 (collections) for further operations on lists.


16.12.1 <list>
<collection>  class


The class of all lists.


16.12.2 ()
syntax


Remarks

The empty list, which is the only instance of the class <null>, has as its external representation an open parenthesis followed by a close parenthesis. The empty list is also used to denote the boolean value false.


16.12.3 <null>
<list>  class


The class whose only instance is the empty list, denoted ().


16.12.4 null?
function


Arguments

object :

Object to examine.

Result

Returns t if object is the empty list, otherwise ().


16.12.5 generic-print <null>
method


Specialized Arguments

null :

The empty list.

stream :

The stream on which the representation is to be output.

Result

The empty list.

Remarks

Output the external representation of the empty list on stream as described above.


16.12.6 generic-write <null>
method


Specialized Arguments

null :

The empty list.

stream :

The stream on which the representation is to be output.

Result

The empty list.

Remarks

Output the external representation of the empty list on stream as described above.


16.12.7 pair
syntax


A pair is written as (object1 . object2), where object1 is called the car and object2 is called the cdr. There are two special cases in the external representation of pair. If object2 is the empty list, then the pair is written as (object1). If object2 is an instance of pair, then the pair is written as (object1 object3 . object4), where object3 is the car of object2 and object4 is the cdr with the above rule for the empty list applying. By induction, a list of length n is written as (object1objectn-1 . objectn), with the above rule for the empty list applying. The representations of object1 and object2 are determined by the external representations defined in other sections of this definition (see <character> (16.1), <double-float> (16.6), <fpi> (16.9), <string> (16.16), <symbol> (16.17) and <vector> (16.19), as well as instances of <cons> itself. The syntax for the external representation of pairs and lists is defined in syntax table 16.12.7.1.

16.12.7.1 Syntax

null:
()
pair:
( object . object )
list:
empty-list
proper-list
improper-list
empty-list:
()
proper-list:
( object+ )
improper-list:
( object+ . object )
Examples
() the empty list
(1) a list whose car is 1 and cdr is ()
(1 . 2)a pair whose car is 1 and cdr is 2
(1 2) a list whose car is 1 and cdr is (2)


16.12.8 <cons>
<list>  class


The class of all instances of <cons>. An instance of the class <cons> (also known informally as a dotted pair or a pair) is a 2-tuple, whose slots are called, for historical reasons, car and cdr. Pairs are created by the function cons and the slots are accessed by the functions car and cdr. The major use of pairs is in the construction of (proper) lists. A (proper) list is defined as either the empty list (denoted by ()) or a pair whose cdr is a proper list. An improper list is one containing a cdr which is not a list (see syntax table 16.12.7.1).

It is an error to apply car or cdr or their setter functions to anything other than a pair. The empty list is not a pair and (car ()) or (cdr ()) is an error.


16.12.9 cons?
function


Arguments

object :

Object to examine.

Result

Returns object if it is a pair, otherwise ().


16.12.10 atom?
function


Arguments

object :

Object to examine.

Result

Returns object if it is not a pair, otherwise ().


16.12.11 cons
function


Arguments

object1 :

An object. pair.

object2 :

An object. pair.

Result

Allocates a new pair whose slots are initialized with object1 in the car and object2 in the cdr.


16.12.12 car
function


Arguments

pair :

A pair.

Result

Given a pair, such as the result of (cons object1 object2), then the function car returns object1.


16.12.13 cdr
function


Arguments

pair :

A pair.

Result

Given a pair, such as the result of (cons object1 object2), then the function cdr returns object2.


16.12.14 (setter car)
setter


Arguments

pair :

A pair.

object :

An object.

Result

Given a pair, such as the result of (cons object1 object2), then the function (setter car) replaces object1 with object. The result is object.


16.12.15 (setter cdr)
setter


Arguments

pair :

A pair.

object :

An object.

Result

Given a pair, such as the result of (cons object1 object2), thenthe function (setter cdr) replaces object2 with object. The result is object.

Remarks

Note that if object is not a proper list, then the use of (setter cdr) might change pair into an improper list.


16.12.16 binary= <cons>
method


Specialized Arguments

pair1 <cons> :

A pair.

pair2 <cons> :

A pair.

Result

If the result of the conjunction of the pairwise application of binary= to the car fields and the cdr fields of the arguments is t the result is pair1 otherwise the result is ().


16.12.17 deep-copy <cons>
method


Specialized Arguments

pair <cons> :

A pair.

Result

Constructs and returns a copy of the list starting at pair copying both the car and the cdr slots of the list. The list can be proper or improper. Treatment of the objects stored in the car slot (and the cdr slot in the case of the final pair of an improper list) is determined by the deep-copy method for the class of the object.


16.12.18 shallow-copy <cons>
method


Specialized Arguments

pair <cons> :

A pair.

Result

Constructs and returns a copy of the list starting at pair but copying only the cdr slots of the list, terminating when a pair is encountered whose cdr slot is not a pair. The list beginning at pair can be proper or improper.


16.12.19 list
function


Arguments

object1 ... objectnopt :

A sequence of objects.

Result

Allocates a set of pairs each of which has been initialized with objecti in the car field and the pair whose car field contains objecti+1 in the cdr field. Returns the pair whose car field contains object1.

Examples
(list) ()
(list 1 2 3)(1 2 3)


16.12.20 generic-print <cons>
method


Specialized Arguments

pair <cons> :

The pair to be output on stream.

stream <stream> :

The stream on which the representation is to be output.

Result

The pair supplied as the first argument.

Remarks

Output the external representation of pair on stream as described at the beginning of this section. Uses generic-print to produce the external representation of the contents of the car and cdr slots of pair.


16.12.21 generic-write <cons>
method


Specialized Arguments

pair <cons> :

The pair to be output on stream.

stream <stream> :

The stream on which the representation is to be output.

Result

The pair supplied as the first argument.

Remarks

Output the external representation of pair on stream as described at the beginning of this section. Uses generic-write to produce the external representation of the contents of the car and cdr slots of pair.

16.13 Elementary Functions

The defined name of this module is mathlib. The functionality defined for this module is intentionally precisely that of the trigonmetric functions, hyperbolic functions, exponential and logarithmic functions and power functions defined for <math.h> in ISO/IEC 9899 : 1990 with the exceptions of frexp, ldexp and modf.


16.13.1 pi <double-float>
constant


Remarks

The value of pi is the ratio the circumference of a circle to its diameter stored to double precision floating point accuracy.


16.13.2 acos
generic function


Generic Arguments

float <float> :

A floating point number.

Result

Computes the principal value of the arc cosine of float which is a value in the range [0] radians. An error is signalled (condition-class: <domain-condition>) if float is not in the range [-1, +1].


16.13.3 asin
generic function


Generic Arguments

float <float> :

A floating point number.

Result

Computes the principal value of the arc sine of float which is a value in the range [-π∕2, +π∕2] radians. An error is signalled (condition-class: <domain-condition>) if float is not in the range [-1, +1].


16.13.4 atan
generic function


Generic Arguments

float <float> :

A floating point number.

Result

Computes the principal value of the arc tangent of float which is a value in the range [-π∕2, +π∕2] radians.


16.13.5 atan2
generic function


Generic Arguments

float1 <float> :

A floating point number.

float2 <float> :

A floating point number.

Result

Computes the principal value of the arc tangent of float1/float2, which is a value in the range [-π, +π] radians, using the signs of both arguments to determine the quadrant of the result. An error might be signalled (condition-class: <domain-condition>) if either float1 or float2 is zero.


16.13.6 cos
generic function


Generic Arguments

float <float> :

A floating point number.

Result

Computes the cosine of float (measured in radians).


16.13.7 sin
generic function


Generic Arguments

float <float> :

A floating point number.

Result

Computes the sine of float (measured in radians).


16.13.8 tan
generic function


Generic Arguments

float <float> :

A floating point number.

Result

Computes the tangent of float (measured in radians).


16.13.9 cosh
generic function


Generic Arguments

float <float> :

A floating point number.

Result

Computes the hyperbolic cosine of float. An error might be signalled (condition class: <range-condition>) if the magnitude of float is too large.


16.13.10 sinh
generic function


Generic Arguments

float <float> :

A floating point number.

Result

Computes the hyperbolic sine of float. An error might be signalled (condition class: <range-condition>) if the magnitude of float is too large.


16.13.11 tanh
generic function


Generic Arguments

float <float> :

A floating point number.

Result

Computes the hyperbolic tangent of float.


16.13.12 exp
generic function


Generic Arguments

float <float> :

A floating point number.

Result

Computes the exponential function of float. An error might be signalled (condition class: <range-condition>) if the magnitude of float is too large.


16.13.13 log
generic function


Generic Arguments

float <float> :

A floating point number.

Result

Computes the natural logarithm of float. An error is signalled (condition class: <domain-condition>) if float is negative. An error might be signalled (condition class: <range-condition>) if float is zero.


16.13.14 log10
generic function


Generic Arguments

float <float> :

A floating point number.

Result

Computes the base-ten logarithm of float. An error is signalled (condition class: <domain-condition>) if float is negative. An error might be signalled (condition class: <range-condition>) if float is zero.


16.13.15 pow
generic function


Generic Arguments

float1 <float> :

A floating point number.

float2 <float> :

A floating point number.

Result

Computes float1 raised to the power float2. An error is signalled (condition class: <domain-condition>) if float1 is negative and float2 is not integral. An error is signalled (condition class: <domain-condition>) if the result cannot be represented when float1 is zero and float2 is less than or equal to zero. An error might be signalled (condition class: <range-condition>) if the result cannot be represented.


16.13.16 sqrt
generic function


Generic Arguments

float <float> :

A floating point number.

Result

Computes the non-negative square root of float. An error is signalled (condition class: <domain-condition>) if float is negative.

16.14 Numbers

The defined name of this module is number.

Numbers can take on many forms with unusual properties, specialized for different tasks, but two classes of number suffice for the majority of needs, namely integers (<integer>, <fpi>) and floating point numbers (<float>, <double-float>). Thus, these only are defined at level-0.

Table 4 shows the initial number class hierarchy at level-0. The inheritance relationships by this diagram are part of this definition, but it is not defined whether they are direct or not. For example, <integer> and <float> are not necessarily direct subclasses of <number>, while the class of each number class might be a subclass of <number>. Since there are only two concrete number classes at level-0, coercion is simple, namely from <fpi> to <double-float>. Any level-0 version of a library module, for example, elementary-functions ??, need only define methods for these two classes. Mathematically, the reals are regarded as a superset of the integers and for the purposes of this definition we regard <float> as a superset of <integer> (even though this will cause representation problems when variable precision integers are introduced). Hence, <float> is referred to as being higher that <integer> and arithmetic involving instances of both classes will cause integers to be converted to an equivalent floating point value, before the calculation proceeds 3 3 (see in particular binary/, binary% and binary-mod).


Table 4: Level-0 number class hierarchy

<number>
<float>
<double-float>
<integer>
<fpi>


16.14.1 <number>
<object>  class


The abstract class which is the superclass of all number classes.


16.14.2 number?
function


Arguments

object :

Object to examine.

Result

Returns object if it is a number, otherwise ().


16.14.3 <arithmetic-condition>
<condition>  condition


Initialization Options

operator object :

The operator which signalled the condition.

operand-list list :

The operands passed to the operator.

Remarks

This is the general condition class for conditions arising from arithmetic operations.


16.14.4 <division-by-zero>
<arithmetic-condition>  condition


Signalled by any of binary/, binary% and binary-mod if their second argument is zero.


16.14.5 +
function


Arguments

number1 number2 ...opt :

A sequence of numbers.

Result

Computes the sum of the arguments using the generic function binary+. Given zero arguments, + returns 0 of class <integer>. One argument returns that argument. The arguments are combined left-associatively.


16.14.6 -
function


Arguments

number1 number2 ...opt :

A non-empty sequence of numbers.

Result

Computes the result of subtracting successive arguments—from the second to the last—from the first using the generic function binary-. Zero arguments is an error. One argument returns the negation of the argument, using the generic function negate. The arguments are combined left-associatively.


16.14.7 *
function


Arguments

number1 number2 ...opt :

A sequence of numbers.

Result

Computes the product of the arguments using the generic function binary*. Given zero arguments, * returns 1 of class <integer>. One argument returns that argument. The arguments are combined left-associatively.


16.14.8 /
function


Arguments

number1 number2 ...opt :

A non-empty sequence of numbers.

Result

Computes the result of dividing the first argument by its succeeding arguments using the generic function binary/. Zero arguments is an error. One argument computes the reciprocal of the argument. It is an error in the single argument case, if the argument is zero.


16.14.9 %
function


Arguments

number1 number2 ...opt :

A non-empty sequence of numbers.

Result

Computes the result of taking the remainder of dividing the first argument by its succeeding arguments using the generic function binary%. Zero arguments is an error. One argument returns that argument.


16.14.10 mod
function


Arguments

number1 number2 ...opt :

A non-empty sequence of numbers.

Result

Computes the largest integral value not greater than the result of dividing the first argument by its succeeding arguments using the generic function binary-mod. Zero arguments is an error. One argument returns number1.


16.14.11 gcd
function


Arguments

number1 number2 ...opt :

A non-empty sequence of numbers.

Result

Computes the greatest common divisor of number1 up to numbern using the generic function binary-gcd. Zero arguments is an error. One argument returns number1.


16.14.12 lcm
function


Arguments

number1 number2 ...opt :

A non-empty sequence of numbers.

Result

Computes the least common multiple of number1 up to numbern using the generic function binary-lcm. Zero arguments is an error. One argument returns number1.


16.14.13 abs
function


Arguments

number :

A number.

Result

Computes the absolute value of number.


16.14.14 zero?
generic function


Generic Arguments

number :

A number.

Result

Compares number with the zero element of the class of number using the generic function binary=.


16.14.15 negate
generic function


Generic Arguments

number <number> :

A number.

Result

Computes the additive inverse of number.


16.14.16 signum
function


Arguments

number :

A number.

Result

Returns number if zero? applied to number is t. Otherwise returns the result of converting ±1 to the class of number with the sign of number.


16.14.17 positive?
function


Arguments

number :

A number.

Result

Compares number against the zero element of the class of number using the generic function binary<.


16.14.18 negative?
function


Arguments

number :

A number.

Result

Compares number against the zero element of the class of number using the generic function binary<.


16.14.19 binary= <number>
method


Generic Arguments

number1 <number> :

A number.

number2 <number> :

A number.

Result

Returns t if number1 and number2 are numerically equal otherwise ();


16.14.20 binary+
generic function


Generic Arguments

number1 <number> :

A number.

number2 <number> :

A number.

Result

Computes the sum of number1 and number2.


16.14.21 binary-
generic function


Generic Arguments

number1 <number> :

A number.

number2 <number> :

A number.

Result

Computes the difference of number1 and number2.


16.14.22 binary*
generic function


Generic Arguments

number1 <number> :

A number.

number2 <number> :

A number.

Result

Computes the product of number1 and number2.


16.14.23 binary/
generic function


Generic Arguments

number1 <number> :

A number.

number2 <number> :

A number.

Result

Computes the division of number1 by number2 expressed as a number of the class of the higher of the classes of the two arguments. The sign of the result is positive if the signs the arguments are the same. If the signs are different, the sign of the result is negative. If the second argument is zero, the result might be zero or an error might be signalled (condition class: <division-by-zero>).


16.14.24 binary%
generic function


Generic Arguments

number1 <number> :

A number.

number2 <number> :

A number.

Result

Computes the value of number1-i*number2 expressed as a number of the class of the higher of the classes of the two arguments, for some integer i such that, if number2 is non-zero, the result has the same sign as number1 and magnitude less then the magnitude of number2. If the second argument is zero, the result might be zero or an error might be signalled (condition class: <division-by-zero>).


16.14.25 binary-mod
generic function


Generic Arguments

number1 <number> :

A number.

number2 <number> :

A number.

Result

Computes the largest integral value not greater than number1 number2 expressed as a number of the class of the higher of the classes of the two arguments, such that if number2 is non-zero, the result has the same sign as number2 and magnitude less than number2. If the second argument is zero, the result might be zero or an error might be signalled (condition class: <division-by-zero>).


16.14.26 binary-gcd
generic function


Generic Arguments

number1 <number> :

A number.

number2 <number> :

A number.

Result

Computes the greatest common divisor of number1 and number2.


16.14.27 binary-lcm
generic function


Generic Arguments

number1 <number> :

A number.

number2 <number> :

A number.

Result

Computes the lowest common multiple of number1 and number2.

16.15 Streams

The defined name of this module is stream.

The aim of the stream design presented here is an open architecture for programming with streams, which should be applicable when the interface to some object can be characterized by either serial access to, or delivery of, objects.

The two specific objectives are: (i) transfer of objects between a process and disk storage; (ii) transfer of objects between one process and another.

The fundamental purpose of a stream object in the scheme presented here is to provide an interface between two objects through the two functions read, for streams from which objects are received, and write, for streams to which objects are sent.

16.15.1 Stream classes


16.15.1 <stream>
<object>  class


This is the root of the stream class hierarchy and also defines the basic stream class.

Initialization Options

read-action <function> :

A function which is called by the <stream> generic-read <stream> method. The accessor for this slot is called stream-read-action.

write-action <function> :

A function which is called by the <stream>generic-write <stream> method. The accessor for this slot is called stream-write-action.

The following accessor functions are defined for <stream>

stream-lock : A lock, to be used to allow exclusive access to a stream. stream-source : An object to which the stream is connected and from which input is read. stream-sink : An object to which the stream is connected and to which ouptut is written. stream-buffer : An object which is used to buffer data by some subclasses of <stream>. Its default value is (). stream-buffer-size : The maximum number of objects that can be stored in stream-buffer. Its default value is 0.

The transaction unit of <stream> is <object>.


16.15.2 stream?
function


Arguments

object, <object> :

The object to be examined.

Result

Returns object if it is a stream, otherwise ().


16.15.3 from-stream
function


A constructor function of one argument for <stream> which returns a stream whose stream-read-action is the given argument.


16.15.4 to-stream
function


A constructor function of one argument for <stream> which returns a stream whose stream-write-action is the given argument.


16.15.5 <buffered-stream>
<stream>  class


This class specializes <stream> by the use of a buffer which may grow arbitrarily large. The transaction unit of <buffered-stream> is <object>.


16.15.6 <fixed-buffered-stream>
<buffered-stream>  class


This class specializes <buffered-stream> by placing a bound on the growth of the buffer. The transaction unit of <fixed-buffered-stream> is <object>.


16.15.7 <file-stream>
<fixed-buffered-stream>  class


This class specializes <fixed-buffered-stream> by providing an interface to data stored in files on disk. The transaction unit of <file-stream> is <character>. The following additional accessor functions are defined for <file-stream>: file-stream-filename : The path identifying the file system object associated with the stream. file-stream-mode : The mode of the connection between the stream and the file system object (usually either read or write). file-stream-buffer-position : A key identifying the current position in the stream’s buffer.


16.15.8 file-stream?
function


Arguments

object, <object> :

The object to be examined.

Result

Returns object if it is a <file-stream> otherwise ().


16.15.9 <string-stream>
<buffered-stream>  class


The class of the default string stream.


16.15.10 string-stream?
function


Arguments

object, <object> :

The object to be examined.

Result

Returns object if it is a <string-stream> otherwise ().

16.15.2 Stream operators


16.15.11 connect
function


Arguments

source :

The source object from which the stream will read data.

sink :

The sink object to which the stream will write data.

optionsopt :

An optional argument for specifying implementation-defined options.

Result

The return value is ().

Remarks

Connects source to sink according to the class-specific behaviours of generic-connect.


16.15.12 generic-connect
generic function


Generic Arguments

source <object> :

The source object from which the stream will read data.

sink <object> :

The sink object to which the stream will write data.

optionsopt <list> :

An optional argument for specifying implementation-defined options.

Remarks

Generic form of connect.


16.15.13 generic-connect <stream>
method


Specialized Arguments

source <stream> :

The stream which is to be the source of sink.

sink <stream> :

The stream which is to be the sink of source.

options <list> :

A list of implementation-defined options.

Result

The return value is ().

Remarks

Connects the source of sink to source and the sink of source to sink.


16.15.14 generic-connect <path>
method


Specialized Arguments

source <path> :

A path name.

sink <file-stream> :

The stream via which data will be received from the file named by path.

options <list> :

A list of implementation-defined options.

Result

The return value is ().

Remarks

Opens the object identified by the path source for reading and connects sink to it. Hereafter, sink may be used for reading data from sink, until sink is disconnected or reconnected. Implementation-defined options for the opening of files may be specified using the third argument.

See also

open-input-file.


16.15.15 generic-connect <file-stream>
method


Specialized Arguments

source <file-stream> :

The stream via which data will be sent to the file named by path.

sink <path> :

A path name.

options <list> :

A list of implementation-defined options.

Result

The return value is ().

Remarks

Opens the object identifed by the path sink for writing and connects source to it. Hereafter, source may be used for writing data to sink, until source is disconnected or reconnected. Implementation-defined options for the opening of files may be specified using the third argument.

See also

open-output-file.


16.15.16 reconnect
generic function


Generic Arguments

s1 <stream> :

A stream.

s2 <stream> :

A stream.

Result

The return value is ().

Remarks

Transfers the source and sink connections of s1 to s2, leaving s1 disconnected.


16.15.17 reconnect <stream>
method


Specialized Arguments

s1 <stream> :

A stream.

s2 <stream> :

A stream.

Result

The return value is ().

Remarks

Implements the reconnect operation for objects of class <stream>.


16.15.18 disconnect
generic function


Generic Arguments

s <stream> :

A stream.

Result

The return value is ().

Remarks

Disconnects the stream s from its source and/or its sink.


16.15.19 disconnect <stream>
method


Specialized Arguments

s <stream> :

A stream.

Result

The return value is ().

Remarks

Implements the diconnect operation for objects of class <stream>.


16.15.20 disconnect <file-stream>
method


Specialized Arguments

s <file-stream> :

A file stream.

Result

The return value is ().

Remarks

Implements the diconnect operation for objects of class <file-stream>. In particular, this involves closing the file associated with the stream s.

16.15.3 Stream objects


16.15.21 stdin <file-stream>
instance


Remarks

The standard input stream, which is a file-stream and whose transaction unit is therefore character. In Posix compliant configurations, this object is initialized from the Posix stdin object. Note that although stdin itself is a constant binding, it may be connected to different files by the reconnect operation.


16.15.22 lispin <stream>
instance


Remarks

The standard lisp input stream, and its transaction unit is object. This stream is initially connected to stdin (although not necessarily directly), thus a read operation on lispin will case characters to be read from stdin and construct and return an object corresponding to the next lisp expression. Note that although lispin itself is a constant binding, it may be connected to different source streams by the reconnect operation.


16.15.23 stdout <file-stream>
instance


Remarks

The standard output stream, which is a file-stream and whose transaction unit is therefore character. In Posix compliant configurations, this object is initialized from the Posix stdout object. Note that although stdout itself is a constant binding, itmay be connected to different files by the reconnect operation.


16.15.24 stderr <file-stream>
instance


Remarks

The standard error stream, which is a file-stream and whose transaction unit is therefore character. In Posix compliant configurations, this object is initialized from the Posix stderr object. Note that although stderr itself is a constant binding, it may be connected to different files by the reconnect operation.

16.15.4 Buffer management


16.15.25 fill-buffer
generic function


Generic Arguments

stream <buffered-stream> :

A stream.

Result

The buffer associated with stream is refilled from its source. Returns a count of the number of items read.

Remarks

This function is guaranteed to be called when an attempt is made to read from a buffered stream whose buffer is either empty, or from which all the items have been read.


16.15.26 fill-buffer <buffered-stream>
method


Specialized Arguments

stream <buffered-stream> :

A stream.


16.15.27 fill-buffer <file-stream>
method


Specialized Arguments

stream <file-stream> :

A stream.


16.15.28 flush-buffer
generic function


Generic Arguments

stream <buffered-stream> :

A stream.

Result

The contents of the buffer associated with stream is flushed to its sink. If this operation succeeds, a t value is returned, otherwise the result is ().

Remarks

This function is guaranteed to be called when an attempt is made to write to a buffered stream whose buffer is full.


16.15.29 flush-buffer <buffered-stream>
method


Specialized Arguments

stream <buffered-stream> :

A stream.

Result

The contents of the buffer associated with stream is flushed to its sink. If this operation succeeds, a t value is returned, otherwise the result is ().

Remarks

Implements the flush-buffer operation for objects of class <buffered-stream>.


16.15.30 flush-buffer <file-stream>
method


Specialized Arguments

stream <file-stream> :

A stream.

Result

The contents of the buffer associated with stream is flushed to its sink. If this operation succeeds, a t value is returned, otherwise the result is ().

Remarks

Implements the flush-buffer operation for objects of <file-stream>. This method is called both when the buffer is full and after a newline character is written to the buffer.


16.15.31 <end-of-stream>
??  condition


Initialization Options

stream <stream> :

A stream.

Remarks

Signalled by the default end of stream action, as a consequence of a read operation on stream, when it is at end of stream.

See also

generic-read.


16.15.32 end-of-stream
generic function


Generic Arguments

stream <buffered-stream> :

A stream.

Remarks

This function is guaranteed to be called when a read operation encounters the end of stream and the eos-error? argument to read has a non-() value.


16.15.33 end-of-stream <buffered-stream>
method


Specialized Arguments

stream <buffered-stream> :

A stream.

Remarks

Signals the end of stream condition.


16.15.34 end-of-stream <file-stream>
method


Specialized Arguments

stream <file-stream> :

A stream.

Remarks

Disconnects stream and signals the end of stream condition.

16.15.5 Reading from streams


16.15.35 <read-error>
<condition>  condition


Generic Arguments

stream <stream> :

A stream.

Remarks

Signalled by a read operation which fails in some manner other than when it is at end of stream.


16.15.36 read
function


Arguments

streamopt :

A stream.

eos-error?opt :

A boolean.

eos-valueopt :

Value to be returned to indicate end of stream.

Result

That of calling generic-read with the arguments supplied or defaulted as described.

Remarks

The stream defaults to lispin, eos-error? defaults to () and eos-value defaults to eos-default-value.


16.15.37 generic-read
generic function


Generic Arguments

stream <stream> :

A stream.

eos-error? <object> :

A boolean.

eos-value <object> :

Value to be returned to indicate end of stream.

Result

The next transaction unit from stream.

Remarks

If the end of stream is encountered and the value of eos-error? is (), the result is eos-value. If the end of stream is encountered and the value of eos-error? is non-(), the function ?? is called with the argument stream.


16.15.38 generic-read <stream>
method


Specialized Arguments

stream <stream> :

A stream.

eos-error? <object> :

A boolean.

eos-value <object> :

Value to be returned to indicate end of stream.

Result

That of calling the read-action of stream with the arguments stream, eos-error? and eos-value. Returns t.

Remarks

Implements the generic-read operation for objects of class <stream>.


16.15.39 generic-read <buffered-stream>
method


Specialized Arguments

stream <buffered-stream> :

A buffered stream.

eos-error? <object> :

A boolean.

eos-value <object> :

Value to be returned to indicate end of stream.

Result

The next object stored in the stream buffer. If the buffer is empty, the function fill-buffer is called. If the refilling operation did not succeed, the end of stream action is carried out as described under generic-read. Returns t.

Remarks

Implements the generic-read operation for objects of class <buffered-stream>.


16.15.40 generic-read <file-stream>
method


Specialized Arguments

stream <file-stream> :

A file stream.

eos-error? <object> :

A boolean.

eos-value <object> :

Value to be returned to indicate end of stream.

Result

The next object stored in the stream buffer. If the buffer is empty, the function fill-buffer is called. If the refilling operation did not succeed, the end of stream action is carried out as described under generic-read. Returns t.

Remarks

Implements the generic-read operation for objects of class <file-stream>.

16.15.6 Writing to streams


16.15.41 generic-write
generic function


Generic Arguments

object <object> :

An object to be written to stream.

stream <stream> :

Stream to which object is to be written.

Result

Returns object.

Remarks

Outputs the external representation of object on the output stream stream.

See also

The following generic-write methods are defined: generic-write <character>, generic-write <symbol>, generic-write <keyword>, generic-write <fpi>, generic-write <double-float>, generic-write <null>, generic-write <cons>, ??, generic-write <string>, generic-write <vector>, generic-write <stream>, generic-write <buffered-stream> and generic-write <file-stream>.


16.15.42 generic-write <stream>
method


Specialized Arguments

object <object> :

An object to be written to stream.

stream <stream> :

Stream to which object is to be written.


16.15.43 generic-write <buffered-stream>
method


Specialized Arguments

object <object> :

An object to be written to stream.

stream <buffered-stream> :

Stream to which object is to be written.


16.15.44 generic-write <file-stream>
method


Specialized Arguments

object <object> :

An object to be written to stream.

stream <file-stream> :

Stream to which object is to be written.


16.15.45 swrite
function


Arguments

stream :

Stream to which object is to be written.

object :

An object to be written to stream.

Result

Returns stream.

Remarks

Outputs the external representation of object on the output stream stream using generic-write.

See also

generic-write.


16.15.46 write
function


Arguments

object :

An object to be written to stream.

Result

Returns stdout.

Remarks

Outputs the external representation of object on stdout using generic-write.

See also

swrite, generic-write.

16.15.7 Additional functions


16.15.47 read-line
function


Arguments

stream :

A stream.

eos-error?opt :

A boolean.

eos-valueopt :

Value to be returned to indicate end of stream.

Result

A string.

Remarks

Reads a line (terminated by a newline character or the end of the stream) from the stream of characters which is stream. Returns the line as a string, discarding the terminating newline, if any. If the stream is already at end of stream, then the stream action is called: the default stream action is to signal an error: (condition class: <end-of-stream>).


16.15.48 generic-print
generic function


Generic Arguments

object <object> :

An object to be output on stream.

stream <stream> :

A character stream on which object is to be output.

Result

Returns object.

Remarks

Outputs the external representation of object on the output stream stream.

See also

??. The following generic-write methods are defined: generic-write <character>, generic-write <symbol>, generic-write <keyword>, generic-write <fpi>, generic-write <double-float>, generic-write <null>, generic-write <cons>, ??, generic-write <string> and generic-write <vector>.


16.15.49 sprint
function


Arguments

stream :

A character stream on which object is to be output.

object1 object2 ...opt :

A sequence of objects to be output on stream.

Result

Returns stream.

Remarks

Outputs the external representation of object1 object2 ... on the output stream stream using generic-print for each object.

See also

generic-print.


16.15.50 print
function


Arguments

object1 object2 ...opt :

A sequence of objects to be output on stdout.

Result

Returns stdout.

Remarks

Outputs the external representation of object1 object2 ... on the output stream stdout using ?? for each object.

See also

sprint and generic-print.


16.15.51 sflush
function


Arguments

stream :

A stream to flush.

Result

Returns stream.

Remarks

sflush causes any buffered data for the stream to be written to the stream. The stream remains open.


16.15.52 flush
function


Result

Returns stdout.

Remarks

flush causes any buffered data for stdout to be written to stdout.

See also

sflush.


16.15.53 sprin-char
function


Arguments

stream :

A stream.

char :

Character to be written to stream.

timesopt :

Integer count.

Result

Outputs char on stream. The optional count times defaults to 1.


16.15.54 prin-char
function


Arguments

char :

Character to be written to stdout.

timesopt :

Integer count.

Result

Outputs char on stdout. The optional count times defaults to 1.

See also

sprin-char.


16.15.55 sread
function


Arguments

stream :

A stream.

eos-error?opt :

A boolean.

eos-valueopt :

Value to be returned to indicate end of stream.

16.15.8 Convenience forms


16.15.56 open-input-file
function


Arguments

path :

A path identifying a file system object.

Result

Allocates and returns a new <file-stream> object whose source is connected to the file system object identified by path.


16.15.57 open-output-file
function


Arguments

path :

A path identifying a file system object.

Result

Allocates and returns a new <file-stream> object whose sink is connected to the file system object identified by path.


16.15.58 with-input-file
special operator


16.15.58.1 Syntax

with-input-file-form: <object>
( with-input-file path
body )
path:
string


16.15.59 with-output-file
special operator


16.15.59.1 Syntax

with-output-file-form: <object>
( with-output-file path
body )


16.15.60 with-source
special operator


16.15.60.1 Syntax

with-source-form: <object>
( with-source ( identifier form )
body )


16.15.61 with-sink
special operator


16.15.61.1 Syntax

with-sink-form: <object>
( with-sink ( identifier form )
body )

16.16 Strings

The defined name of this module is string. See also section 16.2 (collections) for further operations on strings.
16.16.1 string
syntax


String literals are delimited by the glyph called quotation mark ("). For example, "abcd".

Sometimes it might be desirable to include string delimiter characters in strings. The aim of escaping in strings is to fulfill this need. The string-escape glyph is defined as reverse solidus (\). String escaping can also be used to include certain other characters that would otherwise be difficult to denote. The set of named special characters (see § 9.1 and § 16.1) are included in strings using the character digrams defined in table 16.1.1. To allow arbitrary characters to appear in strings, the hex-insertion digram is followed by an integer denoting the position of the character in the current character set as for characters (see § 9.1). The syntax for the external representation of strings is defined in syntax table 16.16.1.1 below:

16.16.1.1 Syntax

string:
" string-constituent* "
string-constituent:
normal-string-constituent
digram-string-constituent
??
normal-string-constituent:
level-0-character other than " or \
digram-string-constituent: one of
\a \b \d \f \l \n \r \t \v \" \\
numeric-string-constituent:
\x hexadecimal-digit
\x hexadecimal-digit hexadecimal-digit
\x hexadecimal-digit hexadecimal-digit
hexadecimal-digit
\x hexadecimal-digit hexadecimal-digit
hexadecimal-digit hexadecimal-digit

Some examples of string literals appear in table 1.

Example 1: Examples of string literals


Example Contents


"a\nb" #\a, #\n and #\b
"c\\" #\c and #\\
"\x1 " #\x1 followed by #\space
"\xabcde"#\xabcd followed by #\e
"\x1\x2" #\x1 followed by #\x2
"\x12+" #\x12 followed by #\+
"\xabcg" #\xabc followed by #\g
"\x00abc"#\xab followed by #\c


NOTE 1 At present this document refers to the “current character set” but defines no means of selecting alternative character sets. This is to allow for future extensions and implementation-defined extensions which support more than one character set.

The function write outputs a re-readable form of any escaped characters in the string. For example, "a\n\\b" (input notation) is the string containing the characters #\n, #\a, #\\ and #\b. The function write produces "a\n\\b", whilst ?? produces

a  
\b

The function write outputs characters which do not have a glyph associated with their position in the character set as a hex insertion in which all four hex digits are specified, even if there are leading zeros, as in the last example in table 1. The function ?? outputs the interpretation of the characters according to the definitions in section 16.1 without the delimiting quotation marks.


16.16.2 <string>
<character-sequence>  class


The class of all instances of <string>.

Initialization Options

size <fpi> :

The number of characters in the string. Strings are zero-based and thus the maximum index is size-1. If not specified the size is zero.

fill-value: <character> :

A character with which to initialize the string. The default fill character is #\x0.

Examples
(make <string>) ""
(make <string> size: 2)"\x0000\x0000"
(make <string> size: 3 "aaa"
  fill-value: #\a)

16.16.3 string?
function


Arguments

object :

Object to examine.

Result

Returns object if it is a string, otherwise ().


16.16.4 (converter <symbol>)
converter


Specialized Arguments

string <string> :

A string to be converted to a symbol.

Result

If the result of symbol-exists? when applied to string is a symbol, that symbol is returned. If the result is (), then a new symbol is constructed whose name is string. This new symbol is returned.


16.16.5 binary= <string>
method


Specialized Arguments

string1 <string> :

A string.

string2 <string> :

A string.

Result

If the size of string1 is the same (under =) as that of string2, and the result of the conjunction of the pairwise application of binary= <character> to the elements of the arguments is t the result is string1. If not the result is ().


16.16.6 deep-copy <string>
method


Specialized Arguments

string <string> :

A string.

Result

Constructs and returns a copy of string in which each element is eql to the corresponding element in string.


16.16.7 shallow-copy <string>
method


Specialized Arguments

string <string> :

A string.

Result

Constructs and returns a copy of string in which each element is eql to the corresponding element in string.


16.16.8 binary< <string>
method


Specialized Arguments

string1 <string> :

A string.

string2 <string> :

A string.

Result

If the second argument is longer than the first, the result is (). Otherwise, if the sequence of characters in string1 is pairwise less than that in string2 according to binary< <character> the result is t. Otherwise the result is (). Since it is an error to compare lower case, upper case and digit characters with any other kind than themselves, so it is an error to compare two strings which require such comparisons and the results are undefined.

Examples
(< "a" "b") t
(< "b" "a") ()
(< "a" "a") ()
(< "a" "ab") t
(< "ab" "a") ()
(< "A" "B") t
(< "0" "1") t
(< "a1" "a2")t
(< "a1" "bb")t
(< "a1" "ab")undefined
See also

Method binary< <character> (16.3) for characters (16.1).


16.16.9 as-lowercase <string>
method


Specialized Arguments

string <string> :

A string.

Result

Returns a copy of string in which each character denoting an upper case character, is replaced by a character denoting its lower case counterpart. The result must not be eq to string.


16.16.10 as-uppercase <string>
method


Specialized Arguments

string <string> :

A string.

Result

Returns a copy of string in which each character denoting an lower case character, is replaced by a character denoting its upper case counterpart. The result must not be eq to string.


16.16.11 generic-print <string>
method


Specialized Arguments

string <string> :

String to be ouptut on stream.

stream <stream> :

Stream on which string is to be ouptut.

Result

The string string. Output external representation of string on stream as described in the introduction to this section, interpreting each of the characters in the string. The opening and closing quotation marks are not output.


16.16.12 generic-write <string>
method


Specialized Arguments

string <string> :

String to be ouptut on stream.

stream <stream> :

Stream on which string is to be ouptut.

Result

The string string. Output external representation of string on stream as described in the introduction to this section, replacing single characters with escape sequences if necessary. Opening and closing quotation marks are output.

16.17 Symbols

The defined name of this module is symbol.
16.17.1 symbol
syntax


A symbol is a literal identifier and hence has the same syntax 9.3.0.3:

16.17.1.1 Syntax

symbol:
identifier

Because there are two escaping mechanisms and because the first character of a token affects the interpretation of the remainder, there are many ways in which to input the same identifier. If this same identifier is used as a literal, i.e. a symbol, the results of processing each token denoting the identifier will be eq to one another. For example, the following tokens all denote the same symbol:

|123|, \123, |1|23, ||123, ||||123

which will be output by the function write as |123|. If output by write, the representation of the symbol will permit reconstruction by read—escape characters are preserved—so that equivalence is maintained between read and write for symbols. For example: |a(b| and abc.def are two symbols as output by write such that read can read them as two symbols. If output by ??, the escapes necessary to re-read the symbol will not be included. Thus, taking the same examples, ?? outputs a(b and abc.def, which read interprets as the symbol a followed by the start of a list, the symbol b and the symbol abc.def.

Computationally, the most important aspect of symbols is that each is unique, or, stated the other way around: the result of processing every syntactic token comprising the same sequence of characters which denote an identifier is the same object. Or, more briefly, every identifier with the same name denotes the same symbol.


16.17.2 <symbol>
<name>  class


The class of all instances of <symbol>.

Initialization Options

string string :

The string containing the characters to be used to name the symbol. The default value for string is the empty string, thus resulting in the symbol with no name, written ||.


16.17.3 symbol?
function


Arguments

object :

Object to examine.

Result

Returns object if it is a symbol.


16.17.4 gensym
function


Arguments

stringopt :

A string contain characters to be prepended to the name of the new symbol.

Result

Makes a new symbol whose name, by default, begins with the character #\g and the remaining characters are generated by an implementation-defined mechanism. Optionally, an alternative prefix string for the name may be specified. It is guaranteed that the resulting symbol did not exist before the call to gensym.


16.17.5 symbol-name
function


Arguments

symbol :

A symbol.

Result

Returns a string which is binary= <string> to that given as the argument to the call to make which created symbol. It is an error to modify this string.


16.17.6 symbol-exists?
function


Arguments

string :

A string containing the characters to be used to determine the existence of a symbol with that name.

Result

Returns the symbol whose name is string if that symbol has already been constructed by make. Otherwise, returns ().


16.17.7 generic-print <symbol>
method


Specialized Arguments

symbol <symbol> :

The symbol to be output on stream.

stream <stream> :

The stream on which the representation is to be output.

Result

The symbol supplied as the first argument.

Remarks

Outputs the external representation of symbol on stream as described in the introduction to this section, interpreting each of the characters in the name.


16.17.8 generic-write <symbol>
method


Specialized Arguments

symbol <symbol> :

The symbol to be output on stream.

stream <stream> :

The stream on which the representation is to be output.

Result

The symbol supplied as the first argument.

Remarks

Outputs the external representation of symbol on stream as described in the introduction to this section. If any characters in the name would not normally be legal constituents of an identifier or symbol, the output is preceded and succeeded by multiple-escape characters.

Examples
(write (make <symbol> ’string "abc"))abc
(write (make <symbol> ’string "a c")) |a c|
(write (make <symbol> ’string ").(")) |).(|


16.17.9 (converter <string>)
converter


Specialized Arguments

symbol <symbol> :

A symbol to be converted to a string.

Result

A string.

Remarks

This function is the same as symbol-name. It is defined for the sake of symmetry.

16.18 Tables

The defined name of this module is table. See also section 16.2 (collections) for further operations on tables.


16.18.1 <table>
<collection>  class


The class of all instances of <table>.

Initialization Options

comparator: <function> :

The function to be used to compare keys. The default comparison function is eql.

fill-value: <object> :

An object which will be returned as the default value for any key which does not have an associated value. The default fill value is ().

hash-function: <function> :

The function to be used to compute an unique key for each object stored in the table. This function must return a fixed precision integer. The hash function must also satisfy the constraint that if the comparison function returns t for any two objects, then the hash function must return the same key when applied to those two objects. The default is an implementation defined function which satisfies these conditions.


16.18.2 table?
function


Arguments

object :

Object to examine.

Result

Returns object if it is a table, otherwise ().


16.18.3 clear-table
function


Arguments

table :

A table.

Result

An empty table.

Remarks

All entries in table are deleted. The result is eq to the argument, which is to say that the argument is modified.


16.18.4 <hash-table>
<table>  class


Place holder for <hash-table> class.

16.19 Vectors

The defined name of this module is vector. See also section 16.2 (collections) for further operations on vectors.


16.19.1 vector
syntax


A vector is written as #(obj1objn). For example: #(1 2 3) is a vector of three elements, the integers 1, 2 and 3. The representations of obji are determined by the external representations defined in other sections of this definition (see <character> (16.1), <fpi> (16.9), <float> (16.7), <list> (16.12), <string> (16.16) and <symbol> (16.17), as well as instances of <vector> itself. The syntax for the external representation of vectors is defined below.

16.19.1.1 Syntax

vector:
#( object* )


16.19.2 <vector>
<sequence>  class


The class of all instances of <vector>.

Initialization Options

size: <fpi> :

The number of elements in the vector. Vectors are zero-based and thus the maximum index is size-1. If not supplied the size is zero.

fill-value: <object> :

An object with which to initialize the vector. The default fill value is ().

Examples
(make <vector>) #()
(make <vector> size: 2)#(() ())
(make <vector> size: 3 #(#\a #\a #\a)
  fill-value: #\a)


16.19.3 vector?
function


Arguments

object :

Object to examine.

Result

Returns object if it is a vector, otherwise ().


16.19.4 maximum-vector-index <integer>
constant


Remarks

This is an implementation-defined constant. A conforming processor must support a maximum vector index of at least 32767.


16.19.5 binary= <vector>
method


Specialized Arguments

vector1 <vector> :

A vector.

vector2 <vector> :

A vector.

Result

If the size of vector1 is the same (under =) as that of vector2, and the result of the conjunction of the pairwise application of binary= to the elements of the arguments t the result is vector1. If not the result is ().


16.19.6 deep-copy <vector>
method


Specialized Arguments

vector <vector> :

A vector.

Result

Constructs and returns a copy of vector, in which each element is the result of calling deep-copy on the corresponding element of vector.


16.19.7 shallow-copy <vector>
method


Specialized Arguments

vector <vector> :

A vector.

Result

Constructs and returns a copy of vector in which each element is eql to the corresponding element in vector.


16.19.8 generic-print <vector>
method


Specialized Arguments

vector <vector> :

A vector to be ouptut on stream.

stream <stream> :

A stream on which the representation is to be output.

Result

The vector supplied as the first argument.

Remarks

Output the external representation of vector on stream as described in the introduction to this section. Calls the generic function again to produce the external representation of the elements stored in the vector.


16.19.9 generic-write <vector>
method


Specialized Arguments

vector <vector> :

A vector to be ouptut on stream.

stream <stream> :

A stream on which the representation is to be output.

Remarks

Output the external representation of vector on stream as described in the introduction to this section. Calls the generic function again to produce the external representation of the elements stored in the vector.

16.20 Syntax of Level-0 objects

This section repeats the syntax for reading and writing of the various classes defined in §16.

object:
literal
list §16.12
symbol §16.17
literal:
boolean
character §16.1
float §16.7
integer §16.10
string §16.16
vector §16.19
boolean:
true
false
true:
t
object not ()
false:
()
??
character:
literal-character-token
special-character-token
numeric-character-token
literal-character-token:
#\letter
#\decimal-digit
#\other-character
#\special-character
special-character-token:
#\\a
#\\b
#\\d
#\\f
#\\l
#\\n
#\\r
#\\t
#\\v
#\\"
#\\\
numeric-character-token:
#\\x hexadecimal-digit hexadecimal-digit
hexadecimal-digit hexadecimal-digit
float:
signopt unsigned-float exponentopt
unsigned-float:
float-format-1
float-format-2
float-format-3
float-format-1:
decimal-integer .
float-format-2:
. decimal-integer
float-format-3:
float-format-1 decimal-integer
exponent:
double-exponent
double-exponent:
d signopt decimal-integer
D signopt decimal-integer
integer:
signopt unsigned-integer
sign: one of
+ -
unsigned-integer:
binary-integer
octal-integer
decimal-integer
hexadecimal-integer
specified-base-integer
binary-integer:
#b binary-digit+
binary-digit: one of
0 1
octal-integer:
#o octal-digit+
octal-digit: one of
0 1 2 3 4 5 6 7
decimal-integer:
decimal-digit+
hexadecimal-integer:
#x hexadecimal-digit+
hexadecimal-digit:
decimal-digit
hex-lower-letter
hex-upper-letter
hex-lower-letter: one of
a b c d e f
hex-upper-letter: one of
A B C D E F
specified-base-integer:
# base-specification r
specified-base-digit
specified-base-digit*
base-specification:
{ 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 }
{ 1 | 2 } decimal-digit
3 { 0 | 1 | 2 | 3 | 4 | 5 | 6 }
specified-base-digit:
decimal-digit
letter
keyword:
identifier:
null:
()
pair:
( object . object )
list:
empty-list
proper-list
improper-list
empty-list:
()
proper-list:
( object+ )
improper-list:
( object+ . object )
string:
" string-constituent* "
string-constituent:
normal-string-constituent
digram-string-constituent
??
normal-string-constituent:
level-0-character other than " or \
digram-string-constituent: one of
\a \b \d \f \l \n \r \t \v \" \\
numeric-string-constituent:
\x hexadecimal-digit
\x hexadecimal-digit hexadecimal-digit
\x hexadecimal-digit hexadecimal-digit
hexadecimal-digit
\x hexadecimal-digit hexadecimal-digit
hexadecimal-digit hexadecimal-digit
symbol:
identifier
vector:
#( object* )