7.1 Data-structure Contracts

► |  | Reference: Racket

1 | Language Model
2 | Syntactic Forms
3 | Datatypes
4 | Structures
5 | Classes and Objects
6 | Units
7 | Contracts
8 | Pattern Matching
9 | Control Flow
10 | Concurrency
11 | Macros
12 | Input and Output
13 | Reflection and Security
14 | Operating System
15 | Memory Management
16 | Unsafe Operations
17 | Running Racket
| Bibliography
| Index

▼ | 7 | Contracts

7.1 | Data-structure Contracts
7.2 | Function Contracts
7.3 | Lazy Data-structure Contracts
7.4 | Attaching Contracts to Values
7.5 | Building New Contract Combinators
7.6 | Contract Utilities

On this page:

flat-contract
flat-named-contract
any/ c
none/ c
or/ c
and/ c
not/ c
=/ c
</ c
>/ c
<=/ c
>=/ c
between/ c
real-in
integer-in
natural-number/ c
string-len/ c
false/ c
printable/ c
one-of/ c
symbols
vectorof
vector-immutableof
vector/ c
vector-immutable/ c
box/ c
box-immutable/ c
listof
non-empty-listof
cons/ c
list/ c
syntax/ c
struct/ c
parameter/ c
hash/ c
flat-rec-contract
flat-murec-contract
any
promise/ c
new-∃/ c

top← prev up next →

#### 7.1`` Data-structure Contracts

A flat contract can be fully checked immediately for a given value.

( flat-contract predicate) → flat-contract?
predicate : ( any/c . -> . any/c)

Constructs a flat contract from predicate. A value satisfies the contract if the predicate returns a true value.

( flat-named-contract type-name predicate) → flat-contract?
type-name : any/c
predicate : ( or/c flat-contract? ( any/c . -> . any))

On predicates like flat-contract, but the first argument must be the (quoted) name of a contract used for error reporting. For example,

( flat-named-contract
'odd-integer
( lambda (x) ( and ( integer? x) ( odd? x))))

turns the predicate into a contract with the name odd-integer.

On flat contracts, the new flat contract is the same as the old except for the name.

any/c : flat-contract?

A flat contract that accepts any value.

When using this contract as the result portion of a function contract, consider using any instead; using any leads to better memory performance, but it also allows multiple results.

none/c : flat-contract?

A flat contract that accepts no values.

( or/c contract ...) → contract?
contract : contract?

Takes any number of contracts and returns a contract that accepts any value that any one of the contracts accepts, individually.

The or/c result tests any value by applying the contracts in order, from left to right, with the exception that it always moves the non-flat contracts (if any) to the end, checking them last. Thus, a contract such as ( or/c ( not/c real?) positive?) is guaranteed to only invoke the positive? predicate on real numbers.

If all of the arguments are procedures or flat contracts, the result is a flat contract. If only one of the arguments is a higher-order contract, the result is a contract that just checks the flat contracts and, if they don’t pass, applies the higher-order contract.

If there are multiple higher-order contracts, or/c uses contract-first-order-passes? to distinguish between them. More precisely, when an or/c is checked, it first checks all of the flat contracts. If none of them pass, it calls contract-first-order-passes? with each of the higher-order contracts. If only one returns true, or/c uses that contract. If none of them return true, it signals a contract violation. If more than one returns true, it also signals a contract violation. For example, this contract

( or/c (-> number? number?)
(-> string? string? string?))

does not accept a function like this one: ( lambda args ...) since it cannot tell which of the two arrow contracts should be used with the function.

( and/c contract ...) → contract?
contract : ( or/c contract? ( any/c . -> . any/c))

Takes any number of contracts and returns a contract that checks that accepts any value that satisfies all of the contracts, simultaneously.

If all of the arguments are procedures or flat contracts, the result is a flat contract.

The contract produced by and/c tests any value by applying the contracts in order, from left to right.

( not/c flat-contract) → flat-contract?
flat-contract : ( or/c flat-contract? ( any/c . -> . any/c))

Accepts a flat contracts or a predicate and returns a flat contract that checks the inverse of the argument.

(=/c z) → flat-contract?
z : real?

Returns a flat contract that requires the input to be a number and = to z.

(</c n) → flat-contract?
n : real?

Returns a flat contract that requires the input to be a number and < to n.

(>/c n) → flat-contract?
n : real?

Like </c, but for >.

(<=/c n) → flat-contract?
n : real?

Like </c, but for <=.

(>=/c n) → flat-contract?
n : real?

Like </c, but for >=.

( between/c n m) → flat-contract?
n : real?
m : real?

Returns a flat contract that requires the input to be a between n and m or equal to one of them.

( real-in n m) → flat-contract?
n : real?
m : real?

Returns a flat contract that requires the input to be a real number between n and m, inclusive.

( integer-in j k) → flat-contract?
j : exact-integer?
k : exact-integer?

Returns a flat contract that requires the input to be an exact integer between j and k, inclusive.

natural-number/c : flat-contract?

A flat contract that requires the input to be an exact non-negative integer.

( string-len/c len) → flat-contract?
len : exact-nonnegative-integer?

Returns a flat contract that recognizes strings that have fewer than len characters.

false/c : flat-contract?

This is just #f. It is here for backwards compatibility.

printable/c : flat-contract?

A flat contract that recognizes values that can be written out and read back in with write and read.

( one-of/c v ...+) → flat-contract?
v : any/c

Accepts any number of atomic values and returns a flat contract that recognizes those values, using eqv? as the comparison predicate. For the purposes of one-of/c, atomic values are defined to be: characters, symbols, booleans, null keywords, numbers, void, and undefined.

( symbols sym ...+) → flat-contract?
sym : symbol?

Accepts any number of symbols and returns a flat contract that recognizes those symbols.

( vectorof c) → flat-contract?
c : ( or/c flat-contract? ( any/c . -> . any/c))

Accepts a flat contract (or a predicate that is converted to a flat contract via flat-contract) and returns a flat contract that checks for vectors whose elements match the original contract.

( vector-immutableof c) → contract?
c : ( or/c contract? ( any/c . -> . any/c))

Like vectorof, but the contract needs not be a flat contract. Beware that when this contract is applied to a value, the result is not eq? to the input.

( vector/c c ...) → flat-contract?
c : ( or/c flat-contract? ( any/c . -> . any/c))

Accepts any number of flat contracts (or predicates that are converted to flat contracts via flat-contract) and returns a flat-contract that recognizes vectors. The number of elements in the vector must match the number of arguments supplied to vector/c, and each element of the vector must match the corresponding flat contract.

( vector-immutable/c c ...) → contract?
c : ( or/c contract? ( any/c . -> . any/c))

Like vector/c, but the individual contracts need not be flat contracts. Beware that when this contract is applied to a value, the result is not eq? to the input.

( box/c c) → flat-contract?
c : ( or/c flat-contract? ( any/c . -> . any/c))

Returns a flat-contract that recognizes boxes. The content of the box must match c.

( box-immutable/c c) → contract?
c : ( or/c contract? ( any/c . -> . any/c))

Like box/c, but c need not be flat contract. Beware that when this contract is applied to a value, the result is not eq? to the input.

( listof c) → contract?
c : ( or/c contract? ( any/c . -> . any/c))

Returns a contract that recognizes a list whose every element matches the contract c. Beware that when this contract is applied to a value, the result is not necessarily eq? to the input.

( non-empty-listof c) → contract?
c : ( or/c contract? ( any/c . -> . any/c))

Returns a contract that recognizes non-empty lists whose elements match the contract c. Beware that when this contract is applied to a value, the result is not necessarily eq? to the input.

( cons/c car-c cdr-c) → contract?
car-c : contract?
cdr-c : contract?

Produces a contract the recognizes pairs first and second elements match car-c and cdr-c, respectively. Beware that when this contract is applied to a value, the result is not necessarily eq? to the input.

( list/c c ...) → contract?
c : ( or/c contract? ( any/c . -> . any/c))

Produces a contract for a list. The number of elements in the list must match the number of arguments supplied to list/c, and each element of the list must match the corresponding contract. Beware that when this contract is applied to a value, the result is not necessarily eq? to the input.

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

Produces a flat contract that recognizes syntax objects whose syntax-e content matches c.

( struct/c struct-id flat-contract-expr ...)

Produces a flat contract that recognizes instances of the structure type named by struct-id, and whose field values match the flat contracts produced by the flat-contract-exprs.

( parameter/c c) → contract?
c : contract?

Produces a contract on parameters whose values must match contract.

( hash/c key val [#:immutable immutable]) → contract?
key : contract?
val : contract?
immutable : ( or/c #t #f 'dont-care) = 'dont-care

Produces a contract that recognizes hash tables with keys and values as specified by the key and val arguments.

If the immutable argument is #f or 'dont-care, then the resulting contract is a flat contract, and the key and val arguments must also be flat contracts.

If immutable is #t, then the other arguments do not have to be flat contracts, the result is not a flat contract, and checking this contract involves making a copy of the hash-table.

( flat-rec-contract id flat-contract-expr ...)

Constructs a recursive flat contract. A flat-contract-expr can refer to id to refer recursively to the generated contract.

For example, the contract

( flat-rec-contract sexp
( cons/c sexp sexp)
number?
symbol?)

is a flat contract that checks for (a limited form of) S-expressions. It says that an sexp is either two sexp combined with cons, or a number, or a symbol.

Note that if the contract is applied to a circular value, contract checking will not terminate.}

( flat-murec-contract ([id flat-contract-expr ...] ...) body ...+)

A generalization of flat-rec-contract for defining several mutually recursive flat contracts simultaneously. Each id is visible in the entire flat-murec-contract form, and the result of the final body is the result of the entire form.

any

Represents a contract that is always satisfied. In particular, it can accept multiple values. It can only be used in a result position of contracts like ->. Using any elsewhere is a syntax error.

( promise/c expr)

Constructs a contract on a promise. The contract does not force the promise, but when the promise is forced, the contract checks that the result value meets the contract produced by expr.

( new-∃/c name) → contract?
name : symbol?

Constructs a new existential contract.

Existential contracts accept all values when in positive positions (e.g., function returns) and wraps the value in an opaque struct, hiding the precise value. In negative positions (e.g. function inputs), it accepts only values that were previously accepted in negative positions (by checking for the wrappers).

For example, this contract:

( let ([a ( new-∃/c 'a)])
(-> (-> a a)
any/c))

describes a function that accepts the identity function (or a non-terminating function) and returns an arbitrary value. That is, the first use of the a appears in a positive position and thus inputs to that function are wrapped with an opaque struct. Then, when the function returns, it is checked to see if the result is wrapped, since the second a appears in a negative position.
top← prev up next →