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 : string?

predicate : (any/c . -> . any/c)

Like flat-contract, but the first argument must be a string used for error reporting. The string describes the type that the predicate checks for.

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 : (or/c contract? (any/c . -> . any/c))

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

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 signals an error indicating that the or/c contract is malformed.

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.

(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 : number?

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 : number?

Like </c, but for >.

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

n : number?

Like </c, but for <=.

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

n : number?

Like </c, but for >=.

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

n : number?

m : number?

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 : nonnegative-exact-integer?

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

false/c : flat-contract?

A flat contract that recognizes #f.

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.

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

(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-contracts 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.