►Reference: Racket
▼7 Contracts
On this page:
->
->*
->d
case->
unconstrained-domain->
  top← prev  up  next → 

7.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, ->d is the most expensive, 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).

(-> dom ... range)
 
dom = dom-expr
  | keyword dom-expr
     
range = range-expr
  | (values range-expr ...)
  | any
Produces a contract for a function that accepts a fixed number of arguments 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.

Using an -> between two whitespace-delimited .s is the same as putting the -> right after the enclosing open 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.

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? #:x boolean? . -> . integer?)

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

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

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.

(->* (mandatory-dom ...) (optional-dom ...) rest range)
 
mandatory-dom = dom-expr
  | keyword dom-expr
     
optional-dom = dom-expr
  | keyword dom-expr
     
rest = 
  | #:rest rest-expr
     
range = range-expr
  | (values range-expr ...)
  | any
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 last clause describes the range of the function. It 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.

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.

(->d (mandatory-dependent-dom ...)
     dependent-rest
     pre-cond
     dep-range)
(->d (mandatory-dependent-dom ...)
     (optional-dependent-dom ...)
     dependent-rest
     pre-cond
     dep-range)
 
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-cond = 
  | #:pre-cond boolean-expr
     
dep-range = any
  | [_ range-expr] post-cond
  | (values [_ range-expr] ...) post-cond
  | [id range-expr] post-cond
  | (values [id range-expr] ...) post-cond
     
post-cond = 
  | #:post-cond boolean-expr
The ->d is similar in shape to ->*, with two extensions: names have been added to each argument and result, which allows the contracts to depend on the values of the arguments and results, and pre- and post-condition expressions have been added in order to express contracts that are not naturally tied to a particular argument or result.

The first subforms of a ->d contract covers the mandatory and the second (optional) subform covers the optional arguments. Following that is an optional rest-args contract, and an optional pre-condition. The dep-range non-terminal covers the possible post-condition contracts. If it is any, then any result (or results) are allowed. Otherwise, the result contract can be a name and a result contract, or a multiple values return and, in either of the last two cases, it may be optionally followed by a post-condition.

Each of the ids on an argument (including the rest argument) is visible in all of the sub-expressions of ->d. Each of the ids on a result is visible in the subexpressions of the dep-range.

If the identifier position of the range contract is _ (an underscore), then the range contract expressions are evaluated when the function is called (and the underscore is not bound in the range). Otherwise the 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.

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

(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
   [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)))

  top← prev  up  next →