►The Racket Reference
▼8 Contracts
On this page:
->
->*
->i
->d
case->
dynamic->*
unconstrained-domain->
predicate/  c
the-unsupplied-arg
unsupplied-arg?
  top  ← prev  up  next → 

8.2 Function Contracts

A function contract wraps a procedure to delay checks for its arguments and results. There are three primary function contract combinators that have increasing amounts of expressiveness and increasing additional overheads. The first -> is the cheapest. It generates wrapper functions that can call the original function directly. Contracts built with ->* require packaging up arguments as lists in the wrapper function and then using either keyword-apply or apply. Finally, ->i is the most expensive (along with ->d), because it requires delaying the evaluation of the contract expressions for the domain and range until the function itself is called or returns.

The case-> contract is a specialized contract, designed to match case-lambda and unconstrained-domain-> allows range checking without requiring that the domain have any particular shape (see below for an example use).

syntax

(-> dom ... range)

(-> dom ... ellipsis dom-expr ... range)
 
dom = dom-expr
  | keyword dom-expr
     
range = range-expr
  | (values range-expr ...)
  | any
     
ellipsis = ...
Produces a contract for a function that accepts the argument specified by the dom-expr contracts and returns either a fixed number of results or completely unspecified results (the latter when any is specified).

Each dom-expr is a contract on an argument to a function, and each range-expr is a contract on a result of the function.

If the domain contain ... then the function accepts as many arguments as the rest of the contracts in the domain portion specify, as well as arbitrarily many more that match the contract just before the .... Otherwise, the contract accepts exactly the argument specified.

Using a -> between two whitespace-delimited .s is the same as putting the -> right after the enclosing opening parenthesis. See Lists and Racket Syntax or Reading Pairs and Lists for more information.

For example,

(integer? boolean? . -> . integer?)

produces a contract on functions of two arguments. The first argument must be an integer, and the second argument must be a boolean. The function must produce an integer.

Examples:
> (define/contract (maybe-invert i b)
    (-> integer? boolean? integer?)
    (if b (- i) i))
> (maybe-invert 1 #t)

-1

> (maybe-invert #f 1)

maybe-invert: contract violation

  expected: integer?

  given: #f

  in: the 1st argument of

      (-> integer? boolean? integer?)

  contract from: (function maybe-invert)

  blaming: top-level

   (assuming the contract is correct)

  at: eval:2.0

A domain specification may include a keyword. If so, the function must accept corresponding (mandatory) keyword arguments, and the values for the keyword arguments must match the corresponding contracts. For example:

(integer? #:invert? boolean? . -> . integer?)

is a contract on a function that accepts a by-position argument that is an integer and an #:invert? argument that is a boolean.

Examples:
> (define/contract (maybe-invert i #:invert? b)
    (-> integer? #:invert? boolean? integer?)
    (if b (- i) i))
> (maybe-invert 1 #:invert? #t)

-1

> (maybe-invert 1 #f)

maybe-invert: arity mismatch;

 the expected number of arguments does not match the given

number

  expected: 1 plus an argument with keyword #:invert?

  given: 2

  arguments...:

   1

   #f

As an example that uses an ..., this contract:

(integer? string? ... integer? . -> . any)

on a function insists that the first and last arguments to the function must be integers (and there must be at least two arguments) and any other arguments must be strings.

Examples:
> (define/contract (string-length/between? lower-bound s1 . more-args)
    (-> integer? string? ... integer? boolean?)
  
    (define all-but-first-arg-backwards (reverse (cons s1 more-args)))
    (define upper-bound (first all-but-first-arg-backwards))
    (define strings (rest all-but-first-arg-backwards))
    (define strings-length
      (for/sum ([str (in-list strings)])
        (string-length str)))
    (<= lower-bound strings-length upper-bound))
> (string-length/between? 4 "farmer" "john" 40)

#t

> (string-length/between? 4 "farmer" 'john 40)

string-length/between?: contract violation

  expected: string?

  given: 'john

  in: the repeated argument of

      (-> integer? string? ... integer? boolean?)

  contract from:

      (function string-length/between?)

  blaming: top-level

   (assuming the contract is correct)

  at: eval:2.0

> (string-length/between? 4 "farmer" "john" "fourty")

string-length/between?: contract violation

  expected: integer?

  given: "fourty"

  in: the last argument of

      (-> integer? string? ... integer? boolean?)

  contract from:

      (function string-length/between?)

  blaming: top-level

   (assuming the contract is correct)

  at: eval:2.0

If any is used as the last sub-form for ->, no contract checking is performed on the result of the function, and thus any number of values is legal (even different numbers on different invocations of the function).

Examples:
> (define/contract (multiple-xs n x)
    (-> natural? any/c any)
    (apply
     values
     (for/list ([_ (in-range n)])
       n)))
> (multiple-xs 4 "four")

4

4

4

4

If (values range-expr ...) is used as the last sub-form of ->, the function must produce a result for each contract, and each value must match its respective contract.

Examples:
> (define/contract (multiple-xs n x)
    (-> natural? any/c (values any/c any/c any/c))
    (apply
     values
     (for/list ([_ (in-range n)])
       n)))
> (multiple-xs 3 "three")

3

3

3

> (multiple-xs 4 "four")

multiple-xs: broke its own contract;

 expected 3 values, returned 4 values

  in: the range of

      (->

       natural?

       any/c

       (values any/c any/c any/c))

  contract from: (function multiple-xs)

  blaming: (function multiple-xs)

   (assuming the contract is correct)

  at: eval:2.0

Changed in version 6.4.0.5 of package base: Added support for ellipses

syntax

(->* (mandatory-dom ...) optional-doms rest pre range post)

 
mandatory-dom = dom-expr
  | keyword dom-expr
     
optional-doms = 
  | (optional-dom ...)
     
optional-dom = dom-expr
  | keyword dom-expr
     
rest = 
  | #:rest rest-expr
     
pre = 
  | #:pre pre-cond-expr
  | #:pre/desc pre-cond-expr
     
range = range-expr
  | (values range-expr ...)
  | any
     
post = 
  | #:post post-cond-expr
  | #:post/desc post-cond-expr
The ->* contract combinator produces contracts for functions that accept optional arguments (either keyword or positional) and/or arbitrarily many arguments. The first clause of a ->* contract describes the mandatory arguments, and is similar to the argument description of a -> contract. The second clause describes the optional arguments. The range of description can either be any or a sequence of contracts, indicating that the function must return multiple values.

If present, the rest-expr contract governs the arguments in the rest parameter. Note that the rest-expr contract governs only the arguments in the rest parameter, not those in mandatory arguments. For example, this contract:

(->* () #:rest (cons/c integer? (listof integer?)) any)

does not match the function

(λ (x . rest) x)

because the contract insists that the function accept zero arguments (because there are no mandatory arguments listed in the contract). The ->* contract does not know that the contract on the rest argument is going to end up disallowing empty argument lists.

The pre-cond-expr and post-cond-expr expressions are checked as the function is called and returns, respectively, and allow checking of the environment without an explicit connection to an argument (or a result). If the #:pre or #:post keywords are used, then a #f result is treated as a failure and any other result is treated as success. If the #:pre/desc or #:post/desc keyword is used, the result of the expression must be either a boolean, a string, or a list of strings, where #t means success and any of the other results mean failure. If the result is a string or a list of strings, the strings are expected to have at exactly one space after each newline and multiple are used as lines in the error message; the contract itself adds single space of indentation to each of the strings in that case. The formatting requirements are not checked but they match the recommendations in Error Message Conventions.

As an example, the contract

(->* () (boolean? #:x integer?) #:rest (listof symbol?) symbol?)

matches functions that optionally accept a boolean, an integer keyword argument #:x and arbitrarily more symbols, and that return a symbol.

syntax

(->i maybe-chaperone
     (mandatory-dependent-dom ...)
     dependent-rest
     pre-condition
     dependent-range
     post-condition)
(->i maybe-chaperone
     (mandatory-dependent-dom ...)
     (optional-dependent-dom ...)
     dependent-rest
     pre-condition
     dependent-range
     post-condition)
 
maybe-chaperone = #:chaperone
  | 
     
mandatory-dependent-dom = id+ctc
  | keyword id+ctc
     
optional-dependent-dom = id+ctc
  | keyword id+ctc
     
dependent-rest = 
  | #:rest id+ctc
     
pre-condition = 
  | 
#:pre (id ...)
boolean-expr pre-condition
  | 
#:pre/desc (id ...)
expr pre-condition
  | 
#:pre/name (id ...)
string boolean-expr pre-condition
     
dependent-range = any
  | id+ctc
  | un+ctc
  | (values id+ctc ...)
  | (values un+ctc ...)
     
post-condition = 
  | 
#:post (id ...)
boolean-expr post-condition
  | 
#:post/desc (id ...)
expr post-condition
  | 
#:post/name (id ...)
string boolean-expr post-condition
     
id+ctc = [id contract-expr]
  | [id (id ...) contract-expr]
     
un+ctc = [_ contract-expr]
  | [_ (id ...) contract-expr]
The ->i contract combinator differs from the ->* combinator in that each argument and result is named and these names can be used in the subcontracts and in the pre-/post-condition clauses. In other words, ->i expresses dependencies among arguments and results.

The optional first keyword argument to ->i indicates if the result contract will be a chaperone. If it is #:chaperone, all of the contract for the arguments and results must be chaperone contracts and the result of ->i will be a chaperone contract. If it is not present, then the result contract will not be a chaperone contract.

The first sub-form of a ->i contract covers the mandatory and the second sub-form covers the optional arguments. Following that is an optional rest-args contract, and an optional pre-condition. The pre-condition is introduced with the #:pre keyword followed by the list of names on which it depends. If the #:pre/name keyword is used, the string supplied is used as part of the error message; similarly with #:post/name. If #:pre/desc or #:post/desc is used, the the result of the expression is treated the same way as ->*.

The dependent-range non-terminal specifies the possible result contracts. If it is any, then any value is allowed. Otherwise, the result contract pairs a name and a contract or a multiple values return with names and contracts. In the last two cases, the range contract may be optionally followed by a post-condition; the post-condition expression is not allowed if the range contract is any. Like the pre-condition, the post-condition must specify the variables on which it depends.

Consider this sample contract:
(->i ([x number?]
      [y (x) (>=/c x)])
     [result (x y) (and/c number? (>=/c (+ x y)))])
It specifies a function of two arguments, both numbers. The contract on the second argument (y) demands that it is greater than the first argument. The result contract promises a number that is greater than the sum of the two arguments. While the dependency specification for y signals that the argument contract depends on the value of the first argument, the dependency sequence for result indicates that the contract depends on both argument values. In general, an empty sequence is (nearly) equivalent to not adding a sequence at all except that the former is more expensive than the latter. Since the contract for x does not depend on anything else, it does not come with any dependency sequence, not even ().

This example is like the previous one, except the x and y arguments are now optional keyword arguments, instead of mandatory, by-position arguments:
(->i ()
     (#:x [x number?]
      #:y [y (x) (>=/c x)])
     [result (x y)
      (and/c number?
             (if (and (number? x) (number? y))
                 (>=/c (+ x y))
                 any/c))])
The conditional in the range that tests x and y is necessary to cover the situation where x or y are not supplied by the calling context (meaning they might be bound to the-unsupplied-arg).

The contract expressions are not always evaluated in order. First, if there is no dependency for a given contract expression, the contract expression is evaluated at the time that the ->i expression is evaluated rather than the time when the function is called or returns. These dependency-free contract expressions are evaluated in the order in which they are listed. Second, the dependent contract sub-expressions are evaluated when the contracted function is called or returns in some order that satisfies the dependencies. That is, if a contract for an argument depends on the value of some other contract, the former is evaluated first (so that the argument, with its contract checked, is available for the other). When there is no dependency between two arguments (or the result and an argument), then the contract that appears earlier in the source text is evaluated first.

If all of the identifier positions of a range contract with a dependency are _s (underscores), then the range contract expressions are evaluated when the function is called instead of when it returns. Otherwise, dependent range expressions are evaluated when the function returns.

If there are optional arguments that are not supplied, then the corresponding variables will be bound to a special value called the-unsupplied-arg value. For example, in this contract:
(->i ([x (y) (if (unsupplied-arg? y)
                 real?
                 (>=/c y))])
     ([y real?])
     any)
the contract on x depends on y, but y might not be supplied at the call site. In that case, the value of y in the contract on x is the-unsupplied-arg and the ->i contract must check for it and tailor the contract on x to account for y not being supplied.

When the contract expressions for unsupplied arguments are dependent, and the argument is not supplied at the call site, the contract expressions are not evaluated at all. For example, in this contract, y’s contract expression is evaluated only when y is supplied:
(->i ()
     ([x real?]
      [y (x) (>=/c x)])
     any)
In contrast, x’s expression is always evaluated (indeed, it is evaluated when the ->i expression is evaluated because it does not have any dependencies).

syntax

(->d (mandatory-dependent-dom ...)
     dependent-rest
     pre-condition
     dependent-range
     post-condition)
(->d (mandatory-dependent-dom ...)
     (optional-dependent-dom ...)
     dependent-rest
     pre-condition
     dependent-range
     post-condition)
 
mandatory-dependent-dom = [id dom-expr]
  | keyword [id dom-expr]
     
optional-dependent-dom = [id dom-expr]
  | keyword [id dom-expr]
     
dependent-rest = 
  | #:rest id rest-expr
     
pre-condition = 
  | #:pre boolean-expr
  | #:pre-cond boolean-expr
     
dependent-range = any
  | [_ range-expr]
  | (values [_ range-expr] ...)
  | [id range-expr]
  | (values [id range-expr] ...)
     
post-condition = 
  | #:post-cond boolean-expr
This contract is here for backwards compatibility; any new code should use ->i instead.

This contract is similar to ->i, but is “lax”, meaning that it does not enforce contracts internally. For example, using this contract
(->d ([f (-> integer? integer?)])
     #:pre
     (zero? (f #f))
     any)
will allow f to be called with #f, trigger whatever bad behavior the author of f was trying to prohibit by insisting that f’s contract accept only integers.

The #:pre-cond and #:post-cond keywords are aliases for #:pre and #:post and are provided for backwards compatibility.

syntax

(case-> (-> dom-expr ... rest range) ...)

 
rest = 
  | #:rest rest-expr
     
range = range-expr
  | (values range-expr ...)
  | any
This contract form is designed to match case-lambda. Each argument to case-> is a contract that governs a clause in the case-lambda. If the #:rest keyword is present, the corresponding clause must accept an arbitrary number of arguments. The range specification is just like that for -> and ->*.

For example, this contract matches a function with two cases, one that accepts an integer, returning void, and one that accepts no arguments and returns an integer.
(case-> (-> integer? void?)
        (-> integer?))
Such a contract could be used to guard a function that controls access to a single shared integer.

procedure

(dynamic->* 
  [#:mandatory-domain-contracts mandatory-domain-contracts 
  #:optional-domain-contracts optional-domain-contracts 
  #:mandatory-keywords mandatory-keywords 
  #:mandatory-keyword-contracts mandatory-keyword-contracts 
  #:optional-keywords optional-keywords 
  #:optional-keyword-contracts optional-keyword-contracts 
  #:rest-contract rest-contract] 
  #:range-contracts range-contracts) 
 → contract?
  mandatory-domain-contracts : (listof contract?) = '()
  optional-domain-contracts : (listof contract?) = '()
  mandatory-keywords : (listof keyword?) = '()
  mandatory-keyword-contracts : (listof contract?) = '()
  optional-keywords : (listof keyword?) = '()
  optional-keyword-contracts : (listof contract?) = '()
  rest-contract : (or/c #f contract?) = #f
  range-contracts : (or/c #f (listof contract?))
Like ->*, except the number of arguments and results can be computed at runtime, instead of being fixed at compile-time. Passing #f as the #:range-contracts argument produces a contract like one where any is used with -> or ->*.

For many uses, dynamic->*’s result is slower than ->* (or ->), but for some it has comparable speed. The name of the contract returned by dynamic->* uses the -> or ->* syntax.

syntax

(unconstrained-domain-> range-expr ...)

Constructs a contract that accepts a function, but makes no constraint on the function’s domain. The range-exprs determine the number of results and the contract for each result.

Generally, this contract must be combined with another contract to ensure that the domain is actually known to be able to safely call the function itself.

For example, the contract

(provide
 (contract-out
  [f (->d ([size natural-number/c]
           [proc (and/c (unconstrained-domain-> number?)
                        (lambda (p)
                          (procedure-arity-includes? p size)))])
          ()
          [_ number?])]))

says that the function f accepts a natural number and a function. The domain of the function that f accepts must include a case for size arguments, meaning that f can safely supply size arguments to its input.

For example, the following is a definition of f that cannot be blamed using the above contract:

(define (f i g)
  (apply g (build-list i add1)))

value

predicate/c : contract?

Use this contract to indicate that some function is a predicate. It is semantically equivalent to (-> any/c boolean?).

This contract also includes an optimization so that functions returning #t from struct-predicate-procedure? are just returned directly, without being wrapped. This contract is used by provide/contract’s struct sub-form so that struct predicates end up not being wrapped.

value

the-unsupplied-arg : unsupplied-arg?

Used by ->i (and ->d) to bind optional arguments that are not supplied by a call site.

procedure

(unsupplied-arg? v) → boolean?

  v : any/c
A predicate to determine whether v is the-unsupplied-arg.

  top  ← prev  up  next →