►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 a projection defining a contract’s behavior. This projection is a curried function of two arguments: the first application accepts a blame object, and the second accepts a value to protect with the contract.

If possible, use contract-late-neg-projection instead.

procedure

(contract-val-first-projection c)

 → (-> blame? (-> any/c (-> any/c any/c)))
  c : contract?
Produces a projection defining a contract’s behavior. This projection is similar to the result of contract-late-neg-projection except with an extra layer of currying.

If possible, use contract-late-neg-projection instead.

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.

Added in version 6.4.0.4 of package base.

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 →