►The Racket Reference
▼7 Contracts
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
struct/ dc
parameter/ c
procedure-arity-includes/ c
hash/ c
prompt-tag/ c
continuation-mark-key/ c
flat-rec-contract
flat-murec-contract
any
promise/ c
  top← prev  up  next → 

7.1 Data-structure Contracts

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

procedure

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

procedure

(flat-named-contract type-name    
  predicate    
  [generator]) → flat-contract?
  type-name : any/c
  predicate : (or/c flat-contract? (any/c . -> . any))
  generator : (or/c #f (-> contract (-> int? any))) = #f
On predicates, behaves 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.

The generator argument adds a generator for the flat-named-contract. See contract-generate for more information.

value

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.

value

none/c : flat-contract?

A flat contract that accepts no values.

procedure

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

procedure

(and/c contract ...) → contract?

  contract : (or/c contract? (any/c . -> . any/c))
Takes any number of contracts and returns a contract 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.

procedure

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

procedure

(=/c z) → flat-contract?

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

procedure

(</c n) → flat-contract?

  n : real?
Returns a flat contract that requires the input to be a number and < than n.

procedure

(>/c n) → flat-contract?

  n : real?
Like </c, but for >.

procedure

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

  n : real?
Like </c, but for <=.

procedure

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

  n : real?
Like </c, but for >=.

procedure

(between/c 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 or equal to one of them.

procedure

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

  n : real?
  m : real?
An alias for between/c.

procedure

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

value

natural-number/c : flat-contract?

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

procedure

(string-len/c len) → flat-contract?

  len : exact-nonnegative-integer?
Returns a flat contract that recognizes strings that have fewer than len characters.

value

false/c : flat-contract?

An alias #f for backwards compatibility.

value

printable/c : flat-contract?

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

procedure

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

This is a backwards compatibility contract constructor. If neither #<void> nor #<undefined> are arguments, it simply passes its arguments to or/c.

procedure

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

  sym : symbol?
Accepts any number of symbols and returns a flat contract that recognizes those symbols.

This is a backwards compatibility constructor; it merely passes its arguments to or/c.

procedure

(vectorof c    
  [#:immutable immutable    
  #:flat? flat?]) → contract?
  c : contract?
  immutable : (or/c #t #f 'dont-care) = 'dont-care
  flat? : boolean? = #f
Returns a contract that recognizes vectors. The elements of the vector must match c.

If the flat? argument is #t, then the resulting contract is a flat contract, and the c argument must also be a flat contract. Such flat contracts will be unsound if applied to mutable vectors, as they will not check future operations on the vector.

If the immutable argument is #t and the c argument is a flat contract, the result will be a flat contract. If the c argument is a chaperone contract, then the result will be a chaperone contract.

When a higher-order vectorof contract is applied to a vector, the result is not eq? to the input. The result will be a copy for immutable vectors and a chaperone or impersonator of the input for mutable vectors.

procedure

(vector-immutableof c) → contract?

  c : contract?
Returns the same contract as (vectorof c #:immutable #t). This form exists for backwards compatibility.

procedure

(vector/c c    
  ...    
  [#:immutable immutable    
  #:flat? flat?]) → contract?
  c : contract?
  immutable : (or/c #t #f 'dont-care) = 'dont-care
  flat? : boolean? = #f
Returns a contract that recognizes vectors whose lengths match the number of contracts given. Each element of the vector must match its corresponding contract.

If the flat? argument is #t, then the resulting contract is a flat contract, and the c arguments must also be flat contracts. Such flat contracts will be unsound if applied to mutable vectors, as they will not check future operations on the vector.

If the immutable argument is #t and the c arguments are flat contracts, the result will be a flat contract. If the c arguments are chaperone contracts, then the result will be a chaperone contract.

When a higher-order vector/c contract is applied to a vector, the result is not eq? to the input. The result will be a copy for immutable vectors and a chaperone or impersonator of the input for mutable vectors.

procedure

(vector-immutable/c c ...) → contract?

  c : contract?
Returns the same contract as (vector/c c ... #:immutable #t). This form exists for reasons of backwards compatibility.

procedure

(box/c c    
  [#:immutable immutable    
  #:flat? flat?]) → contract?
  c : contract?
  immutable : (or/c #t #f 'dont-care) = 'dont-care
  flat? : boolean? = #f
Returns a contract that recognizes boxes. The content of the box must match c.

If the flat? argument is #t, then the resulting contract is a flat contract, and the c argument must also be a flat contract. Such flat contracts will be unsound if applied to mutable boxes, as they will not check future operations on the box.

If the immutable argument is #t and the c argument is a flat contract, the result will be a flat contract. If the c argument is a chaperone contract, then the result will be a chaperone contract.

When a higher-order box/c contract is applied to a box, the result is not eq? to the input. The result will be a copy for immutable boxes and either a chaperone or impersonator of the input for mutable boxes.

procedure

(box-immutable/c c) → contract?

  c : contract?
Returns the same contract as (box/c c #:immutable #t). This form exists for reasons of backwards compatibility.

procedure

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

procedure

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

procedure

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

  car-c : contract?
  cdr-c : contract?
Produces a contract that recognizes pairs whose 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.

procedure

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

procedure

(syntax/c c) → flat-contract?

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

syntax

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

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

Contracts for immutable fields must be either flat or chaperone contracts. Contracts for mutable fields may be impersonator contracts. If all fields are immutable and the contract-exprs evaluate to flat contracts, a flat contract is produced. If all the contract-exprs are chaperone contracts, a chaperone contract is produced. Otherwise, an impersonator contract is produced.

syntax

(struct/dc struct-id field-spec ...)

 
field-spec = [field-id maybe-lazy contract-expr]
  | 
[field-id (dep-field-id ...)
          maybe-lazy
          maybe-flat-or-impersonator
          maybe-dep-state
          contract-expr]
     
maybe-lazy = 
  | #:lazy
     
maybe-flat-or-impersonator = 
  | #:flat
  | #:impersonator
     
maybe-dep-state = 
  | #:depends-on-state
Produces a contract that recognizes instances of the structure type named by struct-id, and whose field values match the contracts produced by the field-specs.

If the field-spec lists the names of other fields, then the contract depends on values in those fields, and the contract-expr expression is evaluated each time a selector is applied, building a new contract for the fields based on the values of the dep-field-id fields. If the field is a dependent field, then it is assumed that the contract is a chaperone, but not always a flat contract (and theus the entire struct/dc contract is not a flat contract). If this is not the case, and the contract is always flat then the field must be annotated with the #:flat, or the field must be annotated with #:chaperone (in which case, it must be a mutable field).

If the #:lazy keyword appears, then the contract on the field is check lazily (only when a selector is applied); #:lazy contracts cannot be put on mutable fields.

If a dependent contract depends on some mutable state, then use the #:depends-on-state keyword argument (if a field’s dependent contract depends on a mutable field, this keyword is automatically inferred). The presence of this keyword means that the contract expression is evaluated each time the corresponding field is accessed (or mutated, if it is a mutable field). Otherwise, the contract expression for a dependent field contract is evaluated when the contract is applied to a value.

Contracts for immutable fields must be either flat or chaperone contracts. Contracts for mutable fields may be impersonator contracts. If all fields are immutable and the contract-exprs evaluate to flat contracts, a flat contract is produced. If all the contract-exprs are chaperone contracts, a chaperone contract is produced. Otherwise, an impersonator contract is produced.

As an example, the function bst/c below returns a contract for binary search trees whose values are all between lo and hi. The lazy annotations ensure that this contract does not change the running time of operations that do not inspect the entire tree.

(struct bt (val left right))
(define (bst/c lo hi)
  (or/c #f
        (struct/dc bt
                   [val (between/c lo hi)]
                   [left (val) #:lazy (bst lo val)]
                   [right (val) #:lazy (bst val hi)])))

procedure

(parameter/c c) → contract?

  c : contract?
Produces a contract on parameters whose values must match contract.

procedure

(procedure-arity-includes/c n) → flat-contract?

  n : exact-nonnegative-integer?
Produces a contract for procedures that accept n argument (i.e,. the procedure? contract is implied).

procedure

(hash/c key    
  val    
  [#:immutable immutable    
  #:flat? flat?]) → contract?
  key : chaperone-contract?
  val : contract?
  immutable : (or/c #t #f 'dont-care) = 'dont-care
  flat? : boolean? = #f
Produces a contract that recognizes hash tables with keys and values as specified by the key and val arguments.

If the flat? argument is #t, then the resulting contract is a flat contract, and the key and val arguments must also be flat contracts. Such flat contracts will be unsound if applied to mutable hash tables, as they will not check future operations on the hash table.

If the immutable argument is #t and the key and val arguments are flat contracts, the result will be a flat contract. If either the domain or the range is a chaperone contract, then the result will be a chaperone contract.

If the key argument is a chaperone contract, then the resulting contract can only be applied to equal?-based hash tables. When a higher-order hash/c contract is applied to a hash table, the result is not eq? to the input. The result will be a copy for immutable hash tables, and either a chaperone or impersonator of the input for mutable hash tables.

procedure

(prompt-tag/c contract ...) → contract?

  contract : contract?
Takes any number of contracts and returns a contract that recognizes continuation prompt tags and will check any aborts or prompt handlers that use the contracted prompt tag.

Each contract will check the corresponding value passed to an abort-current-continuation and handled by the handler of a call to call-with-continuation-prompt.

If all of the contracts are chaperone contracts, the resulting contract will also be a chaperone contract. Otherwise, the contract is an impersonator contract.

Examples:

> (define/contract tag
    (prompt-tag/c (-> number? string?))
    (make-continuation-prompt-tag))
> (call-with-continuation-prompt
    (lambda ()
      (number->string
        (call-with-composable-continuation
          (lambda (k)
            (abort-current-continuation tag k)))))
    tag
    (lambda (k) (k "not a number")))

tag: contract violation

  expected: number?, given: "not a number"

  in: the 1st argument of

      ...

      (prompt-tag/c (-> number? string?))

  contract from: (definition tag)

  blaming: top-level

  at: eval:2.0

procedure

(continuation-mark-key/c contract) → contract?

  contract : contract?
Takes a single contract and returns a contract that recognizes continuation marks and will check any mappings of marks to values or any accesses of the mark value.

If the argument contract is a chaperone contract, the resulting contract will also be a chaperone contract. Otherwise, the contract is an impersonator contract.

Examples:

> (define/contract mark-key
    (continuation-mark-key/c (-> symbol? (listof symbol?)))
    (make-continuation-mark-key))
> (with-continuation-mark
    mark-key
    (lambda (s) (append s '(truffle fudge ganache)))
    (let ([mark-value (continuation-mark-set-first
                       (current-continuation-marks) mark-key)])
      (mark-value "chocolate-bar")))

mark-key: contract violation

  expected: symbol?, given: "chocolate-bar"

  in: the 1st argument of

      ...

      (continuation-mark-key/c

       (-> symbol? (listof symbol?)))

  contract from: (definition mark-key)

  blaming: top-level

  at: eval:2.0

syntax

(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 a sexp is either two sexps 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.

syntax

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

syntax

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.

syntax

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

  top← prev  up  next →