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)|
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.
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:
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).
|(->* (mandatory-dom ...) (optional-dom ...) rest range)|
The first two subforms of a ->d contract cover the mandatory and 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) ...)|
|(unconstrained-domain-> range-expr ...)|
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
|[f (->d ([size natural-number/c]|
|[proc (and/c (unconstrained-domain-> number?)|
|(procedure-arity-includes? p size)))])|
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)))|