Chapter 3

Basic Data Extensions

3.1  Void and Undefined

MzScheme returns the unique void value -- printed as #<void> -- for expressions that have unspecified results in R5RS. The procedure void takes any number of arguments and returns void:

Variables bound by letrec-values that are accessible but not yet initialized are bound to the unique undefined value, printed as #<undefined>.

3.2  Booleans

Unless otherwise specified, two instances of a particular MzScheme data type are equal? only when they are eq?. Two values are eqv? only when they are either eq?, = and have the same exactness, or both +nan.0.

The andmap and ormap procedures apply a test procedure to the elements of a list, returning immediately when the result for testing the entire list is determined. The arguments to andmap and ormap are the same as for map, but a single boolean value is returned as the result, rather than a list:

Examples:

(andmap positive? '(1 2 3)) ; => #t
(ormap eq? '(a b c) '(a b c)) ; => #t
(andmap positive? '(1 2 a)) ; => raises exn:application:type
(ormap positive? '(1 2 a)) ; => #t
(andmap positive? '(1 -2 a)) ; => #f
(andmap + '(1 2 3) '(4 5 6)) ; => 9
(ormap + '(1 2 3) '(4 5 6)) ; => 5

3.3  Numbers

A number in MzScheme is one of the following:

MzScheme extends the number syntax of R5RS in two ways:

The special inexact numbers +inf.0, -inf.0, and +nan.0 have no exact form. Dividing by an inexact zero returns +inf.0 or -inf.0, depending on the sign of the dividend. The infinities are integers, and they answer #t for both even? and odd?. The +nan.0 value is not an integer and is not = to itself, but +nan.0 is eqv? to itself.3 Similarly, (= 0.0 -0.0) is #t, but (eqv? 0.0 -0.0) is #f.

All multi-argument arithmetic procedures operate pairwise on arguments from left to right.

The string->number procedure works on all number representations and exact integer radix values in the range 2 to 16 (inclusive). The number->string procedure accepts all number types and the radix values 2, 8, 10, and 16; however, if an inexact number is provided with a radix other than 10, the exn:application:mismatch exception is raised.

The add1 and sub1 procedures work on any number:

The following procedures work on integers:

The following procedures work on exact integers in their (semi-infinite) two's complement representation:

The random procedure generates pseudo-random integers:

The following procedures convert between Scheme numbers and common machine byte representations:

3.4  Characters

MzScheme character values range over the characters for ``extended ASCII'' values 0 to 255 (where the ASCII extensions are platform-specific). The procedure char->integer returns the extended ASCII value of a character and integer->char takes an extended ASCII value and returns the corresponding character. If integer->char is given an integer that is not in 0 to 255 inclusive, the exn:application:type exception is raised.

The procedures char->latin-1-integer and latin-1-integer->char support conversions between characters in the platform-specific character set and platform-independent Latin-1 (ISO 8859-1) values:

For Unix and Mac OS, char->latin-1-integer and latin-1-integer->char are the same as char->integer and integer->char. For Windows, the platform-specific set and Latin-1 match except for the range #x80 to #x9F (which are unprintable control characters in Latin-1).

The character comparison procedures -- char=?, char<?, char-ci=?, etc. -- take two or more character arguments and check the arguments pairwise (like the numerical comparison procedures). Two characters are eq? whenever they are char=?. The expression (char<? char1 char2) produces the same result as (< (char->integer char1) (char->integer char2)), etc. The procedures char-whitespace?, char-alphabetic?, char-numeric?, char-upper-case?, and char-upper-case?, char-upcase, and char-downcase are fully portable; their results do not depend on the platform or locales.

In addition to the standard character procedures, MzScheme provides the following locale-sensitive procedures (see section 7.7.1.11):

For example, since ASCII character 112 is a lowercase ``p'' and Latin-1 character 246 is a lowercase ``ddoto'' (with an umlaut), (char-locale<? (integer->char 112) (integer->char 246)) tends to produce #f, though it always produces #t if the current locale is disabled.

3.5  Strings

A string can be mutable or immutable. When an immutable string is provided to a procedure like string-set!, the exn:application:type exception is raised.

String constants generated by read are immutable. (string->immutable-string string) returns an immutable string with the same content as string, and it returns string itself if string is immutable. (See also immutable? in section 3.8.)

(substring string start-k [end-k]) returns a mutable string, even if the string argument is immutable. The end-k argument defaults to (string-length string)

When a string is created with make-string without a fill value, it is initialized with the null character (#\nul) in all positions.

The string comparison procedures -- string=?, string<?, string-ci=?, etc. -- take two or more string arguments and check the arguments pairwise (like the numerical comparison procedures). String comparisons using the standard functions are fully portable; the results do not depend on the platform or locales.

In addition to the string character procedures, MzScheme provides the following locale-sensitive procedures (see section 7.7.1.11):

3.6  Symbols

For information about symbol parsing and printing, see section 14.3 and section 14.4, respectively.

MzScheme provides two ways of generating an uninterned symbol, i.e., a symbol that is not eq?, eqv?, or equal? to any other symbol, although it may print the same as another symbol:

Regular (interned) symbols are only weakly held by the internal symbol table. This weakness can never affect the result of a eq?, eqv?, or equal? test, but a symbol placed into a weak box (see section 13.1) or used as the key in a weak hash table (see section 3.12) may disappear.

3.7  Vectors

When a vector is created with make-vector without a fill value, it is initialized with 0 in all positions. A vector can be immutable, such as a vector returned by syntax-e, but vectors generated by read are mutable. (See also immutable? in section 3.8.)

(vector->immutable-vector vec) returns an immutable vector with the same content as vec, and it returns vec itself if vec is immutable. (See also immutable? in section 3.8.)

(vector-immutable v ···1) is like (vector v ···1) except that the resulting vector is immutable. (See also immutable? in section 3.8.)

3.8  Lists

A cons cell can be mutable or immutable. When an immutable cons cell is provided to a procedure like set-cdr!, the exn:application:type exception is raised. Cons cells generated by read are always mutable.

The global variable null is bound to the empty list.

(reverse! list) is the same as (reverse list), but list is destructively reversed using set-cdr! (i.e., each cons cell in list is mutated).

(append! list ···1) is like (append list), but it destructively appends the lists (i.e., except for the last list, the last cons cell of each list is mutated to append the lists; empty lists are essentially dropped).

(list* v ···1) is similar to (list v ···1) but the last argument is used directly as the cdr of the last pair constructed for the list:

(list* 1 2 3 4) ; => '(1 2 3 . 4)

(cons-immutable v1 v2) returns an immutable pair whose car is v1 and cdr is v2.

(list-immutable v ···1) is like (list v ···1), but using immutable pairs.

(list*-immutable v ···1) is like (list* v ···1), but using immutable pairs.

(immutable? v) returns #t if v is an immutable cons cell, string, vector, box, or hash table, #f otherwise.

The list-ref and list-tail procedures accept an improper list as a first argument. If either procedure is applied to an improper list and an index that would require taking the car or cdr of a non-cons-cell, the exn:application:mismatch exception is raised.

The member, memv, and memq procedures accept an improper list as a second argument. If the membership search reaches the improper tail, the exn:application:mismatch exception is raised.

The assoc, assv, and assq procedures accept an improperly formed association list as a second argument. If the association search reaches an improper list tail or a list element that is not a pair, the exn:application:mismatch exception is raised.

3.9  Boxes

MzScheme provides boxes, which are records that have a single field:

Two boxes are equal? if the contents of the boxes are equal?.

A box returned by syntax-e (see section 12.2.2) is immutable; if set-box! is applied to such a box, the exn:application:type exception is raised. A box produced by read (via #&) is mutable. (See also immutable? in section 3.8.)

3.10  Procedures

See section 4.6 for information on defining new procedure types.

3.10.1  Arity

MzScheme's procedure-arity procedure returns the input arity of a procedure:

Examples:

(procedure-arity cons) ; => 2
(procedure-arity list) ; => #<struct:arity-at-least>
(arity-at-least? (procedure-arity list)) ; => #t
(arity-at-least-value (procedure-arity list)) ; => 0
(arity-at-least-value (procedure-arity (lambda (x . y) x))) ; => 1
(procedure-arity (case-lambda [(x) 0] [(x y) 1])) ; => '(1 2)
(procedure-arity-includes? cons 2) ; => #t
(procedure-arity-includes? display 3) ; => #f

When compiling a lambda or case-lambda expression, MzScheme looks for a 'method-arity-error property attached to the expression (see section 12.6.2). If it is present with a true value, and if no case of the procedure accepts zero arguments, then the procedure is marked so that an exn:application:arity exception involving the procedure will hide the first argument, if one was provided. (Hiding the first argument is useful when the procedure implements a method, where the first argument is implicit in the original source). The property affects only the format of exn:application:arity exceptions, not the result of procedure-arity.

3.10.2  Primitives

A primitive procedure is a built-in procedure that is implemented in low-level language. Not all built-in procedures are primitives, but almost all R5RS procedures are primitives, as are most of the procedures described in this manual.

3.10.3  Procedure Names

See section 6.2.4 for information about the names of primitives, and the names inferred for lambda and case-lambda procedures.

3.11  Promises

The force procedure can only be applied to values returned by delay, and promises are never implicitly forced.

(promise? v) returns #t if v is a promise created by delay, #f otherwise.

3.12  Hash Tables

(make-hash-table [flag-symbol flag-symbol]) creates and returns a new hash table. If provided, each flag-symbol must one of the following:

By default, key comparisons use eq?. If the second flag-symbol is redundant, the exn:application:mismatch exception is raised.

Two hash tables are equal? if they are created with the same flags, and if they map the same keys to equal? values (where ``same key'' means either eq? or equal?, depending on the way the hash table compares keys).

(make-immutable-hash-table assoc-list [flag-symbol]) creates an immutable hash table. (See also immutable? in section 3.8.) The assoc-list must be a list of pairs, where the car of each pair is a key, and the cdr is the corresponding value. The mappings are added to the table in the order that they appear in assoc-list, so later mappings can hide earlier mappings. If the optional flag-symbol argument is provided, it must be 'equal, and the created hash table compares keys with equal?; otherwise, the created table compares keys with eq?.

(hash-table? v [flag-symbol flag-symbol]) returns #t if v was created by make-hash-table or make-immutable-hash-table with the given flag-symbols (or more), #f otherwise. Each provided flag-symbol must be a distinct flag supported by make-hash-table; if the second flag-symbol is redundant, the exn:application:mismatch exception is raised.

(hash-table-put! hash-table key-v v) maps key-v to v in hash-table, overwriting any existing mapping for key-v. If hash-table is immutable, the exn:application:type exception is raised.

(hash-table-get hash-table key-v [failure-thunk]) returns the value for key-v in hash-table. If no value is found for key-v, then the result of invoking failure-thunk (a procedure of no arguments) is returned. If failure-thunk is not provided, the exn:application:mismatch exception is raised when no value is found for key-v.

(hash-table-remove! hash-table key-v) removes the value mapping for key-v if it exists in hash-table. If hash-table is immutable, the en:application:type exception is raised.

(hash-table-map hash-table proc) applies the procedure proc to each element in hash-table, accumulating the results into a list. The procedure proc must take two arguments: a key and its value. See the caveat below about concurrent modification.

(hash-table-for-each hash-table proc) applies the procedure proc to each element in hash-table (for the side-effects of proc) and returns void. The procedure proc must take two arguments: a key and its value. See the caveat below about concurrent modification.

(eq-hash-code v) returns an exact integer; for any two eq? values, the returned integer is the same. Furthermore, for the result integer k and any other exact integer j, (= k j) implies (eq? k j).

(equal-hash-code v) returns an exact integer; for any two equal? values, the returned integer is the same. Furthermore, for the result integer k and any other exact integer j, (= k j) implies (eq? k j). If v contains a cycle through pairs, vectors, boxes, and inspectable structure fields, then equal-hash-code applied to v will loop indefinitely.

Caveat concerning concurrent modification: A hash table can be manipulated with hash-table-get, hash-table-put!, and hash-table-remove! concurrently by multiple threads, and the operations are protected by a table-specific semaphore as needed. A few caveats apply, however:

Caveat concerning mutable keys: If a key into an equal?-based hash table is mutated (e.g., a key string is modified with string-set!), then the hash table's behavior for put and get operations becomes unpredictable.


2 30 bits for a 32-bit architecture, 62 bits for a 64-bit architecture.

3 This definition of eqv? technically contradicts R5RS, but R5RS does not address strange ``numbers'' like +nan.0.

4 The random number generator uses a relatively standard Unix random() implementation in its degree-seven polynomial mode.

5 All fields of the arity-at-least structure type are accessible by all inspectors (see section 4.5).