8.12 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)))
'(#f 0 #f 50304641.0 -51.0 146 #f -2147483647 #f 1342256854)

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

procedure
(contract-exercise [ #:fuel fuel
#:shuffle? shuffle?]
val ...+) → void?
  fuel : exact-nonnegative-integer? = 10
  shuffle? : any/c = #f
  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.

The argument fuel determines how hard contract-exercise tries to break the values. It controls both the number of exercise iterations and the size of the intermediate values generated during the exercises.

The argument shuffle? controls whether contract-exercise randomizes the exercise order or not. If shuffle? is not #f, contract-exercise would shuffle the order of the contracts in each exercise iteration.

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: 11
  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

Changed in version 7.0.0.18 of package base: Added the shuffle? optional argument.

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 must be called when contract-random-generate (and contract-exercise) creates the generators. To be more precise, contract-random-generate/choose is available only for the generate and exercise arguments in build-contract-property, build-chaperone-contract-property or build-flat-contract-property and only during the dynamic extent of the call to generate (and exercise). That is, after it receives the c and fuel arguments and before it returns the thunk (or the exerciser).

contract-random-generate/choose 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.