On this page:
3.1 Booleans
true
false
not
3.2 Lists
empty
empty?
cons
cons?
first
rest
second
third
fourth
list-ref
length
append
reverse
member
map
map2
filter
foldl
foldr
build-list
3.3 Numbers
+
-
*
/
modulo
remainder
min
max
floor
ceiling
add1
sub1
=
>
<
>=
<=
zero?
odd?
even?
3.4 Symbols
symbol=?
string->symbol
symbol->string
3.5 Strings
string=?
string-append
string-length
substring
string-ref
to-string
3.6 Characters
char=?
string->list
list->string
3.7 S-Expressions
s-exp-symbol?
s-exp->symbol
symbol->s-exp
s-exp-number?
s-exp->number
number->s-exp
s-exp-string?
s-exp->string
string->s-exp
s-exp-boolean?
s-exp->boolean
boolean->s-exp
s-exp-list?
s-exp->list
list->s-exp
3.8 Vector
make-vector
vector-ref
vector-set!
vector-length
3.9 Boxes
box
unbox
set-box!
3.10 Tuples
pair
fst
snd
3.11 Optional Values
none
some
some-v
none?
some?
3.12 Hash Tables
make-hash
hash
hash-ref
hash-set!
hash-remove!
hash-set
hash-remove
hash-keys
3.13 Parameters
make-parameter
parameter-ref
parameter-set!
3.14 Equality
equal?
eq?
3.15 Other Functions
identity
error
display
read
print-only-errors
call/  cc

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

Compares symbols

Examples:
> (symbol=? 'apple 'apple)

- boolean

#t

> (symbol=? 'apple 'Apple)

- boolean

#f

Converts between symbols and strings.

Examples:
> (string->symbol "apple")

- symbol

'apple

> (symbol->string 'apple)

- string

"apple"

3.5 Strings

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 from of any plai-typed 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 plai-typed 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 plai-typed 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.

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

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

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"

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

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

   (list 1 2 3)

   1

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).

See also parameterize.

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.

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.