8.11 Random generation

procedure
(contract-random-generate ctc [fuel fail]) → any/c
  ctc : contract?
  fuel : 5 = exact-nonnegative-integer?
  fail : (or/c #f (-> any) (-> boolean? any)) = #f

Attempts to randomly generate a value which will match the contract. The fuel argument limits how hard the generator tries to generate a value matching the contract and is a rough limit of the size of the resulting value.

The generator may fail to generate a value, either because some contracts do not have corresponding generators (for example, not all predicates have generators) or because there is not enough fuel. In either case, the function fail is invoked. If fail accepts an argument, it is called with #t when there is no generator for ctc and called with #f when there is a generator, but the generator ended up returning contract-random-generate-fail.

Example:

> (for/list ([i (in-range 10)])
(contract-random-generate (or/c integer? #f)))
'(1.0 85.0 -125.0 0 30.0 #f 11.0 #f 2147483647 123)

Changed in version 6.1.1.5 of package base: Allow fail to accept a boolean.

procedure
(contract-exercise val ...+) → void?
val : any/c

Attempts to get the vals to break their contracts (if any).

Uses value-contract to determine if any of the vals have a contract and, for those that do, uses information about the contract’s shape to poke and prod at the value. For example, if the value is function, it will use the contract to tell it what arguments to supply to the value.

Examples:

> (define/contract (returns-false x)
    (-> integer? integer?)
    ; does not obey its contract
    #f)
> (contract-exercise returns-false)
returns-false: broke its own contract
  promised: integer?
  produced: #f
  in: the range of
      (-> integer? integer?)
  contract from: (function returns-false)
  blaming: (function returns-false)
   (assuming the contract is correct)
  at: eval:2.0
> (define/contract (calls-its-argument-with-eleven f)
    (-> (-> integer? integer?) boolean?)
    ; f returns an integer, but
    ; we're supposed to return a boolean
    (f 11))
> (contract-exercise calls-its-argument-with-eleven)
calls-its-argument-with-eleven: broke its own contract
  promised: boolean?
  produced: 192
  in: the range of
      (-> (-> integer? integer?) boolean?)
  contract from:
      (function calls-its-argument-with-eleven)
  blaming: (function calls-its-argument-with-eleven)
   (assuming the contract is correct)
  at: eval:4.0

procedure
(contract-random-generate/choose c fuel) → (or/c #f (-> c))
c : contract?
fuel : exact-nonnegative-integer?

This function is like contract-random-generate, but it is intended to be used with combinators that generate values based on sub-contracts they have. It cannot be called, except during contract generation. It will never fail, but it might escape back to an enclosing call or to the original call to contract-random-generate.

It chooses one of several possible generation strategies, and thus it may not actually use the generator associated with c, but might instead use a stashed value that matches c that it knows about via contract-random-generate-stash.