4 Predefined Functions and Constants

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🔗ℹ

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"

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

value
s-exp-symbol? : (S-Exp -> Boolean)
value
s-exp->symbol : (S-Exp -> Symbol)
value
symbol->s-exp : (Symbol -> 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

value
s-exp-number? : (S-Exp -> Boolean)
value
s-exp->number : (S-Exp -> Number)
value
number->s-exp : (Number -> S-Exp)

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

value
s-exp-string? : (S-Exp -> Boolean)
value
s-exp->string : (S-Exp -> String)
value
string->s-exp : (String -> S-Exp)

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"

value
s-exp-boolean? : (S-Exp -> Boolean)
value
s-exp->boolean : (S-Exp -> Boolean)
value
boolean->s-exp : (Boolean -> S-Exp)

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:167:0: typecheck failed: S-Exp vs. Number
  sources:
   list->s-exp
   (list 1 2 3)
   1

value
s-exp-match? : (S-Exp S-Exp -> Boolean)

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:

`NUMBER — matches any number S-expression
`STRING — matches any string S-expression
`SYMBOL — matches any symbol S-expression
`ANY — matches any S-expression
`... — within a list S-expression, matches any number of repetitions of the preceding S-expression within the list; only one `... can appear as an immediate element of a pattern list, and `... is not allowed within a pattern outside of a list or as the first element of a list

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 bx (box "apple"))
> (define bx2 bx)
> (unbox bx)
- String
"apple"
> (set-box! bx "banana")
- Void
> (unbox bx)
- String
"banana"
> (unbox bx2)
- 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).

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.

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.

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.

1	Tutorial
2	Definitions
3	Expressions
4	Predefined Functions and Constants
5	Types
6	Syntactic Literals
7	Type Checking and Inference
8	Untyped, Lazy, and Fuel Modes

4.1	Booleans
4.2	Lists
4.3	Numbers
4.4	Symbols
4.5	Strings
4.6	Characters
4.7	S-Expressions
4.8	Vector
4.9	Boxes
4.10	Tuples
4.11	Optional Values
4.12	Hash Tables
4.13	Parameters
4.14	Equality
4.15	Other Functions