►The Racket Reference
▼8 Contracts
On this page:
contract?
chaperone-contract?
impersonator-contract?
flat-contract?
list-contract?
contract-name
value-contract
has-contract?
value-blame
has-blame?
contract-late-neg-projection
contract-projection
contract-val-first-projection
make-none/  c
recursive-contract
opt/  c
define-opt/  c
contract-continuation-mark-key
contract-custom-write-property-proc
rename-contract
contract-first-order-okay-to-give-up?
contract-first-order-try-less-hard
if/  c
failure-result/  c
  top  ← prev  up  next → 

8.8 Contract Utilities

procedure

(contract? v) → boolean?

  v : any/c
Returns #t if its argument is a contract (i.e., constructed with one of the combinators described in this section or a value that can be used as a contract) and #f otherwise.

procedure

(chaperone-contract? v) → boolean?

  v : any/c
Returns #t if its argument is a chaperone contract, i.e., one that guarantees that it returns a value which passes chaperone-of? when compared to the original, uncontracted value.

procedure

(impersonator-contract? v) → boolean?

  v : any/c
Returns #t if its argument is an impersonator contract, i.e., a contract that is neither a chaperone contract nor a flat contract.

procedure

(flat-contract? v) → boolean?

  v : any/c
Returns #t when its argument is a contract that can be checked immediately (unlike, say, a function contract).

For example, flat-contract constructs flat contracts from predicates, and symbols, booleans, numbers, and other ordinary Racket values (that are defined as contracts) are also flat contracts.

procedure

(list-contract? v) → boolean?

  v : any/c
Recognizes certain contract? values that accept list?s.

A list contract is one that insists that its argument is a list?, meaning that the value cannot be cyclic and must either be the empty list or a pair constructed with cons and another list.

Added in version 6.0.1.13 of package base.

procedure

(contract-name c) → any/c

  c : contract?
Produces the name used to describe the contract in error messages.

procedure

(value-contract v) → (or/c contract? #f)

  v : has-contract?
Returns the contract attached to v, if recorded. Otherwise it returns #f.

To support value-contract and value-contract in your own contract combinators, use prop:contracted or impersonator-prop:contracted.

procedure

(has-contract? v) → boolean?

  v : any/c
Returns #t if v is a value that has a recorded contract attached to it.

procedure

(value-blame v) → (or/c blame? #f)

  v : has-blame?
Returns the blame object for the contract attached to v, if recorded. Otherwise it returns #f.

To support value-contract and value-blame in your own contract combinators, use prop:blame or impersonator-prop:blame.

Added in version 6.0.1.12 of package base.

procedure

(has-blame? v) → boolean?

  v : any/c
Returns #t if v is a value that has a contract with blame information attached to it.

Added in version 6.0.1.12 of package base.

procedure

(contract-late-neg-projection c)

 → (-> blame? (-> any/c (or/c #f any/c) any/c))
  c : contract?
Produces the projection defining a contract’s behavior.

The first argument, blame? object encapsulates information about the contract checking, mostly used to create a meaningful error message if a contract violation is detected. The resulting function’s first argument is the value that should have the contract and its second argument is a missing party for the blame object, to be passed to raise-contract-error.

If possible, use this function instead of contract-val-first-projection or contract-projection.

procedure

(contract-projection c) → (-> blame? (-> any/c any/c))

  c : contract?
Produces the projection defining a contract’s behavior. See also contract-late-neg-projection.

procedure

(contract-val-first-projection c)

 → (-> blame? (-> any/c (-> any/c any/c)))
  c : contract?
Produces the projection defining a contract’s behavior. See also contract-late-neg-projection.

procedure

(make-none/c sexp-name) → contract?

  sexp-name : any/c
Makes a contract that accepts no values, and reports the name sexp-name when signaling a contract violation.

syntax

(recursive-contract contract-expr recursive-contract-option ...)

(recursive-contract contract-expr type recursive-contract-option ...)
 
recursive-contract-option = #:list-contract?
  | #:extra-delay
     
type = #:impersonator
  | #:chaperone
  | #:flat
Delays the evaluation of its argument until the contract is checked, making recursive contracts possible. If type is not given, an impersonator contract is created.

If the recursive-contract-option #:list-contract? is given, then the result is a list-contract? and the contract-expr must evaluate to a list-contract?.

If the recursive-contract-option #:extra-delay is given, then the contract-expr expression is evaluated only when the first value to be checked against the contract is supplied to the contract. Without it, the contract-expr is evaluated earlier. This option is supported only when type is #:flat.

Examples:
> (define even-length-list/c
    (or/c null?
          (cons/c any/c
                  (cons/c any/c
                          (recursive-contract even-length-list/c #:flat)))))
> (even-length-list/c '(A B))

#t

> (even-length-list/c '(1 2 3))

#f

Changed in version 6.0.1.13 of package base: Added the #:list-contract? option.
Changed in version 6.7.0.3: Added the #:extra-delay option.

syntax

(opt/c contract-expr maybe-name)

 
maybe-name = 
  | #:error-name id
This optimizes its argument contract expression by traversing its syntax and, for known contract combinators, fuses them into a single contract combinator that avoids as much allocation overhead as possible. The result is a contract that should behave identically to its argument, except faster.

If the #:error-name argument is present, and contract-expr evaluates to a non-contract expression, then opt/c raises an error using id as the name of the primitive, instead of using the name opt/c.

Examples:
> (define/contract (f x)
    (opt/c '(not-a-contract))
    x)

opt/c: contract violation

  expected: contract?

  given: '(not-a-contract)

> (define/contract (f x)
    (opt/c '(not-a-contract) #:error-name define/contract)
    x)

define/contract: contract violation

  expected: contract?

  given: '(not-a-contract)

syntax

(define-opt/c (id id ...) expr)

This defines a recursive contract and simultaneously optimizes it. As long as the defined function terminates, define-opt/c behaves just as if the -opt/c were not present, defining a function on contracts (except that the body expression must return a contract). But, it also optimizes that contract definition, avoiding extra allocation, much like opt/c does.

For example,

(define-contract-struct bt (val left right))
 
(define-opt/c (bst-between/c lo hi)
  (or/c null?
        (bt/c [val (real-in lo hi)]
              [left (val) (bst-between/c lo val)]
              [right (val) (bst-between/c val hi)])))
 
(define bst/c (bst-between/c -inf.0 +inf.0))

defines the bst/c contract that checks the binary search tree invariant. Removing the -opt/c also makes a binary search tree contract, but one that is (approximately) 20 times slower.

Note that in some cases, a call to a function defined by define-opt/c may terminate, even if the corresponding define-based function would not terminate. This is a shortcoming in define-opt/c that we hope to understand and fix at some point, but have no concrete plans currently.

value

contract-continuation-mark-key : continuation-mark-key?

Key used by continuation marks that are present during contract checking. The value of these marks are the blame objects that correspond to the contract currently being checked.

procedure

(contract-custom-write-property-proc c    
  p    
  mode) → void?
  c : contract?
  p : output-port?
  mode : (or/c #f #t 0 1)
Prints c to p using the contract’s name.

Added in version 6.1.1.5 of package base.

procedure

(rename-contract contract name) → contract?

  contract : contract?
  name : any/c
Produces a contract that acts like contract but with the name name.

The resulting contract is a flat contract if contract is a flat contract.

Added in version 6.3 of package base.

syntax

(contract-first-order-okay-to-give-up?)

This form returns a boolean that controls the result of first-order contact checks. More specifically, if it returns #t, then a first-order check may return #t even when the entire first-order checks have not happened. If it returns #f then the first order checks must continue until a definitive answer is returned.

This will only return #t in the dynamic extent of or/c or first-or/c’s checking to determine which branch to use.

Added in version 6.3.0.9 of package base.

syntax

(contract-first-order-try-less-hard e)

Encourages first-order checks that happen in the dynamic-extent of e to be more likely to give up. That is, makes it more likely that contract-first-order-okay-to-give-up? might return #t.

If not in the dynamic-extent of or/c’s or first-or/c’s checking to determine the branch, then this form has no effect.

Added in version 6.3.0.9 of package base.

procedure

(if/c predicate then-contract else-contract) → contract?

  predicate : (-> any/c any/c)
  then-contract : contract?
  else-contract : contract?
Produces a contract that, when applied to a value, first tests the value with predicate; if predicate returns true, the then-contract is applied; otherwise, the else-contract is applied. The resulting contract is a flat contract if both then-contract and else-contract are flat contracts.

For example, the following contract enforces that if a value is a procedure, it is a thunk; otherwise it can be any (non-procedure) value:

(if/c procedure? (-> any) any/c)

Note that the following contract is not equivalent:

(or/c (-> any) any/c) ; wrong!

The last contract is the same as any/c because or/c tries flat contracts before higher-order contracts.

Added in version 6.3 of package base.

value

failure-result/c : contract?

A contract that describes the failure result arguments of procedures such as hash-ref.

Equivalent to (if/c procedure? (-> any) any/c).

Added in version 6.3 of package base.

  top  ← prev  up  next →