► |  | The Racket Reference

1 | Language Model
2 | Notation for Documentation
3 | Syntactic Forms
4 | Datatypes
5 | Structures
6 | Classes and Objects
7 | Units
8 | Contracts
9 | Pattern Matching
10 | Control Flow
11 | Concurrency and Parallelism
12 | Macros
13 | Input and Output
14 | Reflection and Security
15 | Operating System
16 | Memory Management
17 | Unsafe Operations
18 | Running Racket
| Bibliography
| Index

▼ | 8 | Contracts

8.1 | Data-structure Contracts
8.2 | Function Contracts
8.3 | Parametric Contracts
8.4 | Lazy Data-structure Contracts
8.5 | Structure Type Property Contracts
8.6 | Attaching Contracts to Values
8.7 | Building New Contract Combinators
8.8 | Contract Utilities
8.9 | racket/ contract/ base
8.10 | Legacy Contracts
8.11 | Random generation

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 →