On this page:
4.1 Booleans
not
4.2 Lists
empty
empty?
cons
cons?
first
rest
second
third
fourth
list-ref
length
append
reverse
member
map
map2
filter
foldl
foldr
build-list
4.3 Numbers
+
-
*
/
modulo
remainder
min
max
floor
ceiling
add1
sub1
=
>
<
>=
<=
zero?
odd?
even?
4.4 Symbols
symbol=?
string->symbol
symbol->string
4.5 Strings
string=?
string-append
string-length
substring
string-ref
to-string
4.6 Characters
char=?
string->list
list->string
4.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
s-exp-match?
4.8 Vector
make-vector
vector-ref
vector-set!
vector-length
4.9 Boxes
box
unbox
set-box!
4.10 Tuples
pair
fst
snd
4.11 Optional Values
none
some
some-v
none?
some?
4.12 Hash Tables
make-hash
hash
hash-ref
hash-set!
hash-remove!
hash-set
hash-remove
hash-keys
4.13 Parameters
make-parameter
parameter-ref
parameter-set!
4.14 Equality
equal?
eq?
4.15 Other Functions
identity
error
display
read
void
print-only-errors
call/  cc
s-exp-content
s-exp
tuple-content
tuple

4 Predefined Functions and Constants

4.1 Booleans

value

not : (Boolean -> Boolean)

Boolean negation.

Example:
> (not #t)

- Boolean

#f

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

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

4.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"

4.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 a 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\")"

4.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"

4.7 S-Expressions

For an introduction, see the tutorial section S-Expressions.

A S-expression typically represents program text. For example, placing a ' in from of any plait 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 plait values, including symbols, numbers, and lists, can be coerced to and from S-expression form.

The representation of an S-expression always reuses some other plait value, so conversion to and from an S-expression is a kind cast. For example, the s-exp-symbol? function determines whether an S-expression embeds an immediate symbol; in that case, s-exp->symbol extracts the symbol, while any other value passed to s-exp->symbol raises an exception. The symbol->s-exp function wraps a symbol as an S-expression.

For interoperability of S-expressions with untyped Racket programs, see s-exp-content and s-exp.

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-Exp

`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-Exp

`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-Exp

`"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-Exp

`#f

> (s-exp-boolean? `false)

- Boolean

#f

> (s-exp-symbol? `false)

- Boolean

#t

value

s-exp-list? : (S-Exp -> Boolean)

value

s-exp->list : (S-Exp -> (Listof S-Exp))

value

list->s-exp : ((Listof S-Exp) -> S-Exp)

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

(list `1 `2 `3)

> (list->s-exp (list `1 `2 `3))

- S-Exp

`(1 2 3)

> (list->s-exp (list 1 2 3))

eval:176.0: typecheck failed: S-Exp vs. Number

  sources:

   list->s-exp

   (list 1 2 3)

   1

For an introduction, see the tutorial section S-Expression Matching.

Compares the first S-expression, a pattern, to the second S-expression, a target.

To a first approximation, s-exp-match? is just equal? on the two S-expressions. Unlike equal?, however, certain symbols in the pattern and can match various S-expressions within the target.

For example, `NUMBER within a pattern matches any number in corresponding position within the target:

Examples:
> (s-exp-match? `(+ NUMBER NUMBER) `(+ 1 10))

- Boolean

#t

> (s-exp-match? `(+ NUMBER NUMBER) `(+ 1 x))

- Boolean

#f

> (s-exp-match? `(+ NUMBER NUMBER) `(- 1 10))

- Boolean

#f

The following symbol S-expressions are treated specially within the pattern:

Any other symbol in a pattern matches only itself in the target. For example, `+ matches only `+.

Examples:
> (s-exp-match? `NUMBER `10)

- Boolean

#t

> (s-exp-match? `NUMBER `a)

- Boolean

#f

> (s-exp-match? `SYMBOL `a)

- Boolean

#t

> (s-exp-match? `SYMBOL `"a")

- Boolean

#f

> (s-exp-match? `STRING `"a")

- Boolean

#t

> (s-exp-match? `STRING `("a"))

- Boolean

#f

> (s-exp-match? `ANY `("a"))

- Boolean

#t

> (s-exp-match? `ANY `10)

- Boolean

#t

> (s-exp-match? `any `10)

- Boolean

#f

> (s-exp-match? `any `any)

- Boolean

#t

> (s-exp-match? `(SYMBOL) `(a))

- Boolean

#t

> (s-exp-match? `(SYMBOL) `(a b))

- Boolean

#f

> (s-exp-match? `(SYMBOL SYMBOL) `(a b))

- Boolean

#t

> (s-exp-match? `((SYMBOL) SYMBOL) `((a) b))

- Boolean

#t

> (s-exp-match? `((SYMBOL) NUMBER) `((a) b))

- Boolean

#f

> (s-exp-match? `((SYMBOL) NUMBER ((STRING))) `((a) 5 (("c"))))

- Boolean

#t

> (s-exp-match? `(lambda (SYMBOL) ANY) `(lambda (x) x))

- Boolean

#t

> (s-exp-match? `(lambda (SYMBOL) ANY) `(function (x) x))

- Boolean

#f

> (s-exp-match? `(SYMBOL ...) `(a b))

- Boolean

#t

> (s-exp-match? `(a ...) `(a b))

- Boolean

#f

> (s-exp-match? `(a ...) `(a a))

- Boolean

#t

> (s-exp-match? `(a ...) `())

- Boolean

#t

> (s-exp-match? `(a ... b) `())

- Boolean

#f

> (s-exp-match? `(a ... b) `(b))

- Boolean

#t

> (s-exp-match? `(a ... b) `(a a a b))

- Boolean

#t

> (s-exp-match? `((a ...) b ...) `((a a a) b b b b))

- Boolean

#t

> (s-exp-match? `((a ...) b ...) `((a a a) b c b b))

- Boolean

#f

4.8 Vector

For an introduction, see the tutorial section State.

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 supports 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"

4.9 Boxes

For an introduction, see the tutorial section State.

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"

4.10 Tuples

For an introduction, see the tutorial section Tuples and Options.

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)

(values 1 "apple")

> (fst p)

- Number

1

> (snd p)

- String

"apple"

4.11 Optional Values

For an introduction, see the tutorial section Tuples and Options.

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

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

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

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

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

Input primitive.

value

void : (-> Void)

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

value

s-exp-content : no type

value

s-exp : no type

These functions have no type, so they cannot be used in a plait program. They can be used in untyped contexts to coerce a plait S-expression to a plain Racket S-expression and vice-versa.

value

tuple-content : no type

value

tuple : no type

These functions have no type, so they cannot be used in a plait program. They can be used in untyped contexts to coerce a plait tuple to an immutable vector and vice-versa.