Version: 4.1.5

7.1Data-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 : (any/c . -> . any)

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.

 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.

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

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

 (

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

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