3 Predefined Functions and Constants

top ← prev up next →

3 Predefined Functions and Constants

3.1 Booleans

value
true : boolean
value
false : boolean

Aliases for #t and #f.

value
not : (boolean -> boolean)

Boolean negation.

Example:

> (not true)
- boolean
#f

3.2 Lists

value
empty : (listof 'a)
value
empty? : ((listof 'a) -> boolean)
value
cons : ('a (listof 'a) -> (listof 'a))
value
cons? : ((listof 'a) -> boolean)
value
first : ((listof 'a) -> 'a)
value
rest : ((listof 'a) -> (listof 'a))

Essential list primitives: a list is either empty or cons of an item onto a list. The empty? predicate recognizes the empty list, a cons recognizes any other list. The first and rest functions select back out the two arguments to cons.

Examples:

> empty
- (listof 'a)
'()
> (cons 1 empty)
- (listof number)
'(1)
> (first (cons 1 empty))
- number
1
> (rest (cons 1 empty))
- (listof number)
'()
> (define my-list (cons 1 (cons 2 (cons 3 empty))))
> my-list
- (listof number)
'(1 2 3)
> (first my-list)
- number
1
> (rest my-list)
- (listof number)
'(2 3)
> (first (rest my-list))
- number
2
> (define also-my-list (list 1 2 3))
> also-my-list
- (listof number)
'(1 2 3)
> (rest also-my-list)
- (listof number)
'(2 3)

value
second : ((listof 'a) -> 'a)
value
third : ((listof 'a) -> 'a)
value
fourth : ((listof 'a) -> 'a)
value
list-ref : ((listof 'a) number -> 'a)

Shorthands for accessing the first of the rest of a list, and so on. The second argument to list-ref specifies the number of rests to use before a first, so it effectively counts list items from 0.

Examples:

> (define my-list (list 1 2 3))
> (second my-list)
- number
2
> (list-ref my-list 2)
- number
3

value
length : ((listof 'a) -> number)

Returns the number of items in a list.

Examples:

> (define my-list (cons 1 (cons 2 (cons 3 empty))))
> (length my-list)
- number
3

value
append : ((listof 'a) (listof 'a) -> (listof 'a))

Produces a list that has the items of the first given list followed by the items of the second given list.

Examples:

> (define my-list (list 1 2 3))
> (define my-other-list (list 3 4 5))
> (append my-list my-other-list)
- (listof number)
'(1 2 3 3 4 5)
> (append my-other-list my-list)
- (listof number)
'(3 4 5 1 2 3)

value
reverse : ((listof 'a) -> (listof 'a))

Returns a list that has the same elements as the given one, but in reverse order.

Example:

> (reverse (list 1 2 3))
- (listof number)
'(3 2 1)

value
member : ('a (listof 'a) -> boolean)

Determines whether a value is an item in a list. Item are compared using equal?.

Examples:

> (member 1 (list 1 2 3))
- boolean
#t
> (member 4 (list 1 2 3))
- boolean
#f

value
map : (('a -> 'b) (listof 'a) -> (listof 'b))

Applies a function in order to each element of a list and forms a new list with the results.

Examples:

> (map add1 (list 1 2 3))
- (listof number)
'(2 3 4)
> (map to-string (list 1 2 3))
- (listof string)
'("1" "2" "3")

value
map2 : (('a 'b -> 'c) (listof 'a) (listof 'b) -> (listof 'c))

Applies a function in order to each pair of elements from two lists in “parallel,” forming a new list with the results. An exception is raised if the two lists have different lengths.

Example:

> (map2 + (list 1 2 3) (list 3 4 5))
- (listof number)
'(4 6 8)

value
filter : (('a -> boolean) (listof 'a) -> (listof 'a))

Returns a list containing (in order) the items of a given list for which a given function returns true.

Examples:

> (filter even? (list 1 2 3 4))
- (listof number)
'(2 4)
> (filter odd? (list 1 2 3 4))
- (listof number)
'(1 3)

value
foldl : (('a 'b -> 'b) 'b (listof 'a) -> 'b)
value
foldr : (('a 'b -> 'b) 'b (listof 'a) -> 'b)

Applies a function to an accumulated value and each element of a list, each time obtaining a new accumulated value. The second argument to foldl or foldr is the initial accumulated value, and it is provided as the first argument in each call to the given function. While foldl applies the function or items in the list from from to last, foldr applies the function or items in the list from last to first.

Examples:

> (foldl + 10 (list 1 2 3))
- number
16
> (foldl (lambda (n r) (cons (to-string n) r)) empty (list 1 2 3))
- (listof string)
'("3" "2" "1")
> (foldr (lambda (n r) (cons (to-string n) r)) empty (list 1 2 3))
- (listof string)
'("1" "2" "3")

value
build-list : (number (number -> 'a) -> (listof 'a))

Creates a list of items produced by calling a given function on numbers starting from 0 a given number of times.

Example:

> (build-list 5 (lambda (v) (* v 10)))
- (listof number)
'(0 10 20 30 40)

3.3 Numbers

value
+ : (number number -> number)
value
- : (number number -> number)
value
* : (number number -> number)
value
/ : (number number -> number)
value
modulo : (number number -> number)
value
remainder : (number number -> number)
value
min : (number number -> number)
value
max : (number number -> number)
value
floor : (number -> number)
value
ceiling : (number -> number)
value
add1 : (number -> number)
value
sub1 : (number -> number)

Standard arithmetic functions.

Examples:

> (+ 1 2)
- number
3
> (- 10 9)
- number
1
> (/ 10 5)
- number
2
> (modulo 10 3)
- number
1
> (remainder 10 3)
- number
1
> (min 1 2)
- number
1
> (max 1 2)
- number
2
> (floor 10.1)
- number
10.0
> (ceiling 10.1)
- number
11.0
> (ceiling 10.1)
- number
11.0
> (add1 10)
- number
11
> (sub1 10)
- number
9

value
= : (number number -> boolean)
value
> : (number number -> boolean)
value
< : (number number -> boolean)
value
>= : (number number -> boolean)
value
<= : (number number -> boolean)
value
zero? : (number -> boolean)
value
odd? : (number -> boolean)
value
even? : (number -> boolean)

Standard number comparisons and predicates.

Examples:

> (= 1 1)
- boolean
#t
> (> 1 2)
- boolean
#f
> (< 1 2)
- boolean
#t
> (zero? 1)
- boolean
#f
> (odd? 1)
- boolean
#t
> (even? 1)
- boolean
#f

3.4 Symbols

value
symbol=? : (symbol symbol -> boolean)

Compares symbols

Examples:

> (symbol=? 'apple 'apple)
- boolean
#t
> (symbol=? 'apple 'Apple)
- boolean
#f

value
string->symbol : (string -> symbol)
value
symbol->string : (symbol -> string)

Converts between symbols and strings.

Examples:

> (string->symbol "apple")
- symbol
'apple
> (symbol->string 'apple)
- string
"apple"

3.5 Strings

value
string=? : (string string -> boolean)
value
string-append : (string string -> string)
value
string-length : (string -> number)
value
substring : (string number number -> string)
value
string-ref : (string number -> char)

Standard string primitives.

Examples:

> (string=? "apple" "apple")
- boolean
#t
> (string-append "apple" "banana")
- string
"applebanana"
> (string-length "apple")
- number
5
> (substring "apple" 1 3)
- string
"pp"
> (string-ref "apple" 0)
- char
#\a

value
to-string : ('a -> string)

Converts any value to its printed form as a string.

Examples:

> (to-string 1)
- string
"1"
> (to-string 'two)
- string
"'two"
> (to-string "three")
- string
"\"three\""
> (to-string (list 1 2 3))
- string
"'(1 2 3)"
> (to-string '(1 two "three"))
- string
"'(1 two \"three\")"

3.6 Characters

value
char=? : (char char -> boolean)

Compares characters.

Example:

> (char=? #\a #\b)
- boolean
#f

value
string->list : (string -> (listof char))
value
list->string : ((listof char) -> string)

Converts between a string and a list of characters.

Examples:

> (string->list "apple")
- (listof char)
'(#\a #\p #\p #\l #\e)
> (list->string (list #\a #\b #\c))
- string
"abc"

3.7 S-Expressions

A S-expression typically represents program text. For example, placing a ' in front of any plaitypus expression (which is the same as wrapping it with quote) creates an S-expression that contains the identifiers (as symbols), parenthesization (as lists), and other constants as the expression text. Various plaitypus values, including symbols, numbers, and lists, can be coerced to and from S-expression form.

The representation of an S-expression is always the same as some other plaitypus value, so conversion to and from an S-expression is effectively a cast. For example, the s-exp-symbol? function determines whether an S-expression is a symbol; in that case, s-exp->symbol acts the identity function to produce the symbol, while any other value passed to s-exp->symbol raises an exception. The symbol->s-exp function similarly acts as the identity function to view a symbol as an S-expression.

value
s-exp-symbol? : (s-expression -> boolean)
value
s-exp->symbol : (s-expression -> symbol)
value
symbol->s-exp : (symbol -> s-expression)

Checks whether an S-expression corresponds to a single symbol and casts it from or to such a form. If s-exp->symbol is given an S-expression for which s-exp-symbol? returns false, then s-exp->symbol raises an exception.

Examples:

> (s-exp-symbol? `apple)
- boolean
#t
> (s-exp->symbol `apple)
- symbol
'apple
> (s-exp->symbol '1)
- symbol
s-exp->symbol: not a symbol: 1
> (symbol->s-exp 'apple)
- s-expression
'apple

value
s-exp-number? : (s-expression -> boolean)
value
s-exp->number : (s-expression -> number)
value
number->s-exp : (number -> s-expression)

Checks whether an S-expression corresponds to a single symbol and casts it from or to such a form. If s-exp->number is given an S-expression for which s-exp-number? returns false, then s-exp->number raises an exception.

Examples:

> (s-exp-number? '1)
- boolean
#t
> (s-exp->number '1)
- number
1
> (number->s-exp 1)
- s-expression
1

value
s-exp-string? : (s-expression -> boolean)
value
s-exp->string : (s-expression -> string)
value
string->s-exp : (string -> s-expression)

Checks whether an S-expression corresponds to a single symbol and casts it from or to such a form. If s-exp->string is given an S-expression for which s-exp-string? returns false, then s-exp->string raises an exception.

Examples:

> (s-exp-string? '"apple")
- boolean
#t
> (s-exp->string '"apple")
- string
"apple"
> (string->s-exp "apple")
- s-expression
"apple"

value
s-exp-boolean? : (s-expression -> boolean)
value
s-exp->boolean : (s-expression -> boolean)
value
boolean->s-exp : (boolean -> s-expression)

Checks whether an S-expression corresponds to a single symbol and casts it from or to such a form. If s-exp->boolean is given an S-expression for which s-exp-boolean? returns false, then s-exp->boolean raises an exception.

Examples:

> (s-exp-boolean? '#f)
- boolean
#t
> (s-exp->boolean '#f)
- boolean
#f
> (boolean->s-exp #f)
- s-expression
#f
> (s-exp-boolean? `false)
- boolean
#f
> (s-exp-symbol? `false)
- boolean
#t

value
s-exp-list? : (s-expression -> boolean)
value
s-exp->list : (s-expression -> (listof s-expression))
value
list->s-exp : ((listof s-expression) -> s-expression)

Checks whether an S-expression corresponds to a single symbol and casts it from or to such a form. If s-exp->list is given an S-expression for which s-exp-list? returns false, then s-exp->list raises an exception. A list produced by s-exp->list always contains S-expression items.

Examples:

> (s-exp-list? '(1 2 3))
- boolean
#t
> (s-exp-list? '1)
- boolean
#f
> (s-exp->list '(1 2 3))
- (listof s-expression)
'(1 2 3)
> (list->s-exp (list '1 '2 '3))
- s-expression
'(1 2 3)
> (list->s-exp (list 1 2 3))
eval:168.0: typecheck failed: s-expression vs. number
  sources:
   list->s-exp
   1
   (list 1 2 3)

3.8 Vector

value
make-vector : (number 'a -> (vectorof 'a))
value
vector-ref : ((vectorof 'a) number -> 'a)
value
vector-set! : ((vectorof 'a) number 'a -> void)
value
vector-length : ((vectorof 'a) -> number)

A vector is similar to a list, but it support constant-time access to any item in the vector and does not support constant-time extension. In addition, vectors are mutable.

The make-vector function creates a vector of a given size and initializes all vector items to a given value. The vector-ref function accesses the value in a vector slot, and vector-set! changes the value in a slot. The vector-length function reports the number of slots in the vector.

Examples:

> (define vec (make-vector 10 "apple"))
> (vector-length vec)
- number
10
> (vector-ref vec 5)
- string
"apple"
> (vector-set! vec 5 "banana")
- void
> (vector-ref vec 5)
- string
"banana"
> (vector-ref vec 6)
- string
"apple"

3.9 Boxes

value
box : ('a -> (boxof 'a))
value
unbox : ((boxof 'a) -> 'a)
value
set-box! : ((boxof 'a) 'a -> void)

A box is like a vector with a single slot. Boxes are used primarily to allow mutation. For example, the value of a field in a variant instance cannot be modified, but the field’s value can be a box, and then the box’s content can be modified.

The box function creates a box with an initial value for its slot, unbox accesses the current value in a box’s slot, and set-box! changes the value.

Examples:

> (define b (box "apple"))
> (define b2 b)
> (unbox b)
- string
"apple"
> (set-box! b "banana")
- void
> (unbox b)
- string
"banana"
> (unbox b2)
- string
"banana"

3.10 Tuples

value
pair : ('a 'b -> ('a * 'b))
value
fst : (('a * 'b) -> 'a)
value
snd : (('a * 'b) -> 'b)

Shorthands for two-element tuples: the pair function creates a tuple, and the fst and snd functions access tuple items.

Examples:

> (define p (pair 1 "apple"))
> p
- (number * string)
'#(1 "apple")
> (fst p)
- number
1
> (snd p)
- string
"apple"

3.11 Optional Values

value
none : (-> (optionof 'a))
value
some : ('a -> (optionof 'a))
value
some-v : ((optionof 'a) -> 'a)
value
none? : ((optionof 'a) -> bool)
value
some? : ((optionof 'a) -> bool)

Defined as

(define-type (optionof 'a)
[none]
[some (v : 'a)])

3.12 Hash Tables

value
make-hash : ((listof ('a * 'b)) -> (hashof 'a 'b))
value
hash : ((listof ('a * 'b)) -> (hashof 'a 'b))
value
hash-ref : ((hashof 'a 'b) 'a -> (optionof 'b))

The make-hash function creates a mutable hash table that is initialized with a given mapping of keys to values (as a list of tuples pairing keys to values). The hash function similarly creates an immutable hash table that supports constant-time functional update.

The hash-ref function works on either kind of hash table to find the value for a given key. If the hash table contains a mapping for a given key, hash-ref returns the key’s value wrapped with some. Otherwise, hash-ref returns (none).

Examples:

> (define m-ht (make-hash (list (pair 1 "apple") (pair 2 "banana"))))
> (define i-ht (hash (list (pair 1 "apple") (pair 2 "banana"))))
> (hash-ref m-ht 1)
- (optionof string)
(some "apple")
> (hash-ref i-ht 1)
- (optionof string)
(some "apple")
> (hash-ref m-ht 3)
- (optionof string)
(none)

value
hash-set! : ((hashof 'a 'b) 'a 'b -> void)
value
hash-remove! : ((hashof 'a 'b) 'a -> void)

Changes the mapping of a mutable hash table. The hash-set! operation adds or changes the value for a given key, while hash-remove! deletes the mapping (if any) of a given key.

Providing an immutable hash table triggers an exception.

Examples:

> (define m-ht (make-hash (list (pair 1 "apple") (pair 2 "banana"))))
> (hash-ref m-ht 1)
- (optionof string)
(some "apple")
> (hash-ref m-ht 3)
- (optionof string)
(none)
> (hash-set! m-ht 3 "coconut")
- void
> (hash-set! m-ht 1 "Apple")
- void
> (hash-ref m-ht 1)
- (optionof string)
(some "Apple")
> (hash-ref m-ht 3)
- (optionof string)
(some "coconut")

value
hash-set : ((hashof 'a 'b) 'a 'b -> (hashof 'a 'b))
value
hash-remove : ((hashof 'a 'b) 'a -> (hashof 'a 'b))

Produces an immutable hash table that is like a given one, but with a mapping changed, added, or removed. The hash-set operation adds or changes the value for a given key in the result hash table, while hash-remove deletes the mapping (if any) of a given key in the result hash table.

Examples:

> (define i-ht (hash (list (pair 1 "apple") (pair 2 "banana"))))
> (hash-ref i-ht 1)
- (optionof string)
(some "apple")
> (define i-ht2 (hash-set (hash-set i-ht 1 "Apple")
3 "coconut"))
> (hash-ref i-ht2 1)
- (optionof string)
(some "Apple")
> (hash-ref i-ht2 3)
- (optionof string)
(some "coconut")
> (hash-ref i-ht 3)
- (optionof string)
(none)

value
hash-keys : ((hashof 'a 'b) -> (listof 'a))

Returns the keys mapped by a hash table, which can be mutable or immutable.

Examples:

> (define i-ht (hash (list (pair 1 "apple") (pair 2 "banana"))))
> (hash-keys i-ht)
- (listof number)
'(1 2)

3.13 Parameters

value
make-parameter : ('a -> (parameterof 'a))
value
parameter-ref : ((parameterof 'a) -> 'a)
value
parameter-set! : ((parameterof 'a) 'a -> void)

A parameter implements a kind dynamic binding. The make-parameter function creates a fresh parameter, parameter-ref accesses the parameter’s current value, and parameter-set! changes the parameter’s current value (i.e., at the nearest dynamic binding established with parameterize, if any).

3.14 Equality

value
equal? : ('a 'a -> boolean)

Compares two values for equality. Roughly, two values are equal? when they print the same, but opaque values such as functions are equal? only if they are eq?.

Examples:

> (equal? "apple" "apple")
- boolean
#t
> (equal? (values 1 'two "three") (values 1 'two "three"))
- boolean
#t

value
eq? : ('a 'a -> boolean)

Checks whether two values are exactly the same value, which amounts to checking pointer equality. The eq? function is well-defined on symbols (where it is equivalent to equal?), mutable data structures (where pointer equality corresponds to shared mutation), and the result of a single expression (such as comparing a identifier’s value to itself), but it should be avoided otherwise.

Examples:

> (eq? 'apple 'apple)
- boolean
#t
> (let ([get-one (lambda () 1)])
(eq? get-one get-one))
- boolean
#t

3.15 Other Functions

value
identity : ('a -> 'a)

Identity primitive.

value
error : (symbol string -> 'a)

Error primitive.

value
display : ('a -> void)

Output primitive.

value
read : (-> s-expression)

Input primitive.

value
print-only-errors : (boolean -> void)

Enables or disables the printing of tests that pass. Tests that fail always cause printing.

value
call/cc : ((('a -> 'b) -> 'a) -> 'a)

Passes the current continuation to the given function, and returns that function’s result.

The current continuation is itself represented as a function. Applying a continuation function discards the current continuation and replaces it with the called one, supplying the given value to that continuation.

top ← prev up next →

1	Definitions
2	Expressions
3	Predefined Functions and Constants
4	Types
5	Syntactic Literals
6	Type Checking and Inference
7	Untyped with Typed Syntax

3.1	Booleans
3.2	Lists
3.3	Numbers
3.4	Symbols
3.5	Strings
3.6	Characters
3.7	S-Expressions
3.8	Vector
3.9	Boxes
3.10	Tuples
3.11	Optional Values
3.12	Hash Tables
3.13	Parameters
3.14	Equality
3.15	Other Functions