►Reference: Racket
▼7 Contracts
On this page:
contract?
chaperone-contract?
flat-contract?
flat-contract-predicate
value-contract
has-contract?
contract-stronger?
contract-first-order-passes?
contract-name
contract-first-order
contract-projection
make-none/ c
current-blame-format
recursive-contract
opt/ c
define-opt/ c
  top← prev  up  next → 

7.6 Contract Utilities

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

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

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

(flat-contract-predicate v) → (any/c . -> . any/c)
  v : flat-contract?
Extracts the predicate from a flat contract.

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

(has-contract? v) → boolean?
  v : any/c
Returns #t if v is a value that has a recorded contract attached to it.

(contract-stronger? x y) → boolean?
  x : contract?
  y : contract?
Returns #t if the contract x accepts either fewer or the same number of values as y does.

This function is conservative, so it may return #f when x does, in fact, accept fewer values.

Examples:

  > (contract-stronger? integer? integer?)

  #t

  > (contract-stronger? (between/c 25 75) (between/c 0 100))

  #t

  > (contract-stronger? (between/c 0 100) (between/c 25 75))

  #f

  > (contract-stronger? (between/c -10 0) (between/c 0 10))

  #f

  > (contract-stronger? (λ (x) (and (real? x) (<= x (random 10))))
                        (λ (x) (and (real? x) (<= x (+ 100 (random 10))))))

  #f

(contract-first-order-passes? contract v) → boolean?
  contract : contract?
  v : any/c
Returns a boolean indicating whether the first-order tests of contract pass for v.

If it returns #f, the contract is guaranteed not to hold for that value; if it returns #t, the contract may or may not hold. If the contract is a first-order contract, a result of #t guarantees that the contract holds.

(contract-name c) → any/c
  c : contract?
Produces the name used to describe the contract in error messages.

(contract-first-order c) → (-> any/c boolean?)
  c : contract?
Produces the first-order test used by or/c to match values to higher-order contracts.

(contract-projection c) → (-> blame? (-> any/c any/c))
  c : contract?
Produces the projection defining a contract’s behavior on protected values.

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

(current-blame-format) → (-> blame? any/c string? string?)
(current-blame-format proc) → void?
  proc : (-> blame? any/c string? string?)
This is a parameter that is used when constructing a contract violation error. Its value is procedure that accepts three arguments:

  • the blame object for the violation,

  • the value that the contract applies to, and

  • a message indicating the kind of violation.

The procedure then returns a string that is put into the contract error message. Note that the value is often already included in the message that indicates the violation.

Examples:

  (define (show-blame-error blame value message)
    (string-append
     "Contract Violation!\n"
     (format "Guilty Party: ~a\n" (blame-positive blame))
     (format "Innocent Party: ~a\n" (blame-negative blame))
     (format "Contracted Value Name: ~a\n" (blame-value blame))
     (format "Contract Location: ~s\n" (blame-source blame))
     (format "Contract Name: ~a\n" (blame-contract blame))
     (format "Offending Value: ~s\n" value)
     (format "Offense: ~a\n" message)))
  > (current-blame-format show-blame-error)
  > (define/contract (f x)
      (-> integer? integer?)
      (/ x 2))
  > (f 2)

  1

  > (f 1)

  Contract Violation!

  Guilty Party: (function f)

  Innocent Party: top-level

  Contracted Value Name: f

  Contract Location: #(struct:srcloc eval 4 0 4 1)

  Contract Name: (-> integer? integer?)

  Offending Value: 1/2

  Offense: expected <integer?>, given: 1/2

  > (f 1/2)

  Contract Violation!

  Guilty Party: top-level

  Innocent Party: (function f)

  Contracted Value Name: f

  Contract Location: #(struct:srcloc eval 4 0 4 1)

  Contract Name: (-> integer? integer?)

  Offending Value: 1/2

  Offense: expected <integer?>, given: 1/2

(recursive-contract contract-expr)
(recursive-contract contract-expr type)
Delays the evaluation of its argument until the contract is checked, making recursive contracts possible. If type is given, it describes the expected type of contract and must be one of the keywords #:impersonator, #:chaperone, or #:flat. If type is not given, an impersonator contract is created.

(opt/c contract-expr)
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 (due to less allocation).

(define-opt/c (id id ...) expr)
This defines a recursive contract and simultaneously optimizes it. Semantically, it 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.

  top← prev  up  next →