4 Contracts

▼ |  | Unstable

1 | Guidelines for developing unstable libraries
2 | Bytes
3 | Classes and Objects
4 | Contracts
5 | Definitions
6 | Dictionaries
7 | Directories
8 | Exceptions
9 | Filesystem
10 | Functions
11 | Lists
12 | Net
13 | Path
14 | PLane T Packages
15 | Ports
16 | Pretty-Printing
17 | Regular Expressions
18 | Requiring Modules
19 | Sandboxed Evaluation
20 | Scribble Documentation
21 | Sets
22 | S-Expression Diff
23 | Source Locations
24 | Strings
25 | Structs
26 | Syntax
27 | Planet Package Macros
28 | Text Representations
29 | Multiple Values
30 | XML and CSS
31 | Polymorphic Contracts
32 | Finding Mutated Variables
33 | Find
34 | Interface-Oriented Programming for Classes
35 | Sequences
36 | Hash Tables
37 | Match
38 | Generics
39 | Mark Parameters
40 | Debugging
41 | Contracts for macro subexpressions
42 | GUI libraries

► | 4 | Contracts

4.1 | Flat Contracts
4.2 | Syntax Object Contracts
4.3 | Higher-Order Contracts

On this page:

non-empty-string?
non-empty-list?
non-empty-bytes?
non-empty-vector?
singleton-list?
port-number?
tcp-listen-port?
path-element?
if/ c
failure-result/ c
rename-contract
4.1`` Flat Contracts
nat/ c
pos/ c
truth/ c
4.2`` Syntax Object Contracts
syntax-datum/ c
syntax-listof/ c
syntax-list/ c
4.3`` Higher-Order Contracts
thunk/ c
unary/ c
binary/ c
predicate/ c
predicate-like/ c
comparison/ c
comparison-like/ c
sequence/ c
dict/ c

Version: 5.0.1.5
top← prev up next →

### 4`` Contracts

( require unstable/contract)

This library is unstable; compatibility will not be maintained. See Unstable for more information.

( non-empty-string? x) → boolean?
x : any/c

( non-empty-list? x) → boolean?
x : any/c

( non-empty-bytes? x) → boolean?
x : any/c

( non-empty-vector? x) → boolean?
x : any/c

Returns #t if x is of the appropriate data type (string, list, bytes, or vector, respectively) and is not empty; returns #f otherwise.

( singleton-list? x) → boolean?
x : any/c

Returns #t if x is a list of one element; returns #f otherwise.

port-number? : contract?

Equivalent to ( between/c 1 65535).

tcp-listen-port? : contract?

Equivalent to ( between/c 0 65535).

path-element? : contract?

Equivalent to ( or/c path-string? ( symbols 'up 'same)).

> > > The subsequent bindings were added by Ryan Culpepper.

( if/c predicate then-contract else-contract) → contract?
predicate : (-> any/c any/c)
then-contract : contract?
else-contract : contract?

Produces a contract that, when applied to a value, first tests the value with predicate; if predicate returns true, the then-contract is applied; otherwise, the else-contract is applied. The resulting contract is a flat contract if both then-contract and else-contract are flat contracts.

For example, the following contract enforces that if a value is a procedure, it is a thunk; otherwise it can be any (non-procedure) value:
( if/c procedure? (-> any) any/c)
Note that the following contract is not equivalent:
( or/c (-> any) any/c) ; wrong!
The last contract is the same as any/c because or/c tries flat contracts before higher-order contracts.

failure-result/c : contract?

A contract that describes the failure result arguments of procedures such as hash-ref.

Equivalent to ( if/c procedure? (-> any) any/c).

( rename-contract contract name) → contract?
contract : contract?
name : any/c

Produces a contract that acts like contract but with the name name.

The resulting contract is a flat contract if contract is a flat contract.

> > > The subsequent bindings were added by Carl Eastlund <cce@racket-lang.org>.

#### 4.1`` Flat Contracts

nat/c : flat-contract?

This contract recognizes natural numbers that satisfy exact-nonnegative-integer?.

pos/c : flat-contract?

This contract recognizes positive integers that satisfy exact-positive-integer?.

truth/c : flat-contract?

This contract recognizes Scheme truth values, i.e., any value, but with a more informative name and description. Use it in negative positions for arguments that accept arbitrary truth values that may not be booleans.

#### 4.2`` Syntax Object Contracts

( syntax-datum/c datum/c) → flat-contract?
datum/c : any/c

Recognizes syntax objects stx such that ( syntax->datum stx) satisfies datum/c.

( syntax-listof/c elem/c) → flat-contract?
elem/c : any/c

Recognizes syntax objects stx such that ( syntax->list stx) satisfies ( listof elem/c).

( syntax-list/c elem/c ...) → flat-contract?
elem/c : any/c

Recognizes syntax objects stx such that ( syntax->list stx) satisfies ( list/c elem/c ...).

#### 4.3`` Higher-Order Contracts

thunk/c : contract?

unary/c : contract?

binary/c : contract?

These contracts recognize functions that accept 0, 1, or 2 arguments, respectively, and produce a single result.

predicate/c : contract?

predicate-like/c : contract?

These contracts recognize predicates: functions of a single argument that produce a boolean result.

The first constrains its output to satisfy boolean?. Use predicate/c in positive position for predicates that guarantee a result of #t or #f.

The second constrains its output to satisfy truth/c. Use predicate-like/c in negative position for predicates passed as arguments that may return arbitrary values as truth values.

comparison/c : contract?

comparison-like/c : contract?

These contracts recognize comparisons: functions of two arguments that produce a boolean result.

The first constrains its output to satisfy boolean?. Use comparison/c in positive position for comparisons that guarantee a result of #t or #f.

The second constrains its output to satisfy truth/c. Use comparison-like/c in negative position for comparisons passed as arguments that may return arbitrary values as truth values.

( sequence/c elem/c ...) → contract?
elem/c : contract?

Wraps a sequence, obligating it to produce as many values as there are elem/c contracts, and obligating each value to satisfy the corresponding elem/c. The result is not guaranteed to be the same kind of sequence as the original value; for instance, a wrapped list is not guaranteed to satisfy list?.

Examples:

> ( define/contract predicates
( sequence/c (-> any/c boolean?))
( list integer? string->symbol))

> ( for ([P predicates])
( printf "~s\n" (P "cat")))

#f
eval:3.0: (definition predicates) broke the contract
(sequence/c (-> any/c boolean?))
on predicates; expected <boolean?>, given: 'cat

( dict/c key/c value/c) → contract?
key/c : contract?
value/c : contract?

Wraps a dictionary, obligating its keys to satisfy key/c and their corresponding values to satisfy value/c. The result is not guaranteed to be the same kind of dictionary as the original value; for instance, a wrapped hash table is not guaranteed to satisfy hash?.

Examples:

> ( define/contract table
( dict/c symbol? string?)
( make-immutable-hash ( list ( cons 'A "A") ( cons 'B 2) ( cons 3 "C"))))

> ( dict-ref table 'A)
"A"
> ( dict-ref table 'B)
eval:4.0: (definition table) broke the contract (dict/c
symbol? string?) on table; expected <string?>, given: 2
> ( dict-ref table 3)
eval:4.0: (definition table) broke the contract (dict/c
symbol? string?) on table; expected <symbol?>, given: 3

Warning: Bear in mind that key and value contracts are re-wrapped on every dictionary operation, and dictionaries wrapped in dict/c multiple times will perform the checks as many times for each operation. Especially for immutable dictionaries (which may be passed through a constructor that involves dict/c on each update), contract-wrapped dictionaries may be much less efficient than the original dictionaries.

top← prev up next →