`type 'a t`

A random generator for values of type `'a`.

`type 'a sized = int -> 'a t`

Random generator with a size bound.

#### Primitive generators

`val unit : unit t`

The unit generator.

Does not shrink.

`val bool : bool t`

The boolean generator.

Shrinks towards `false`.

`val int : int t`

Generates integers uniformly.

Shrinks towards `0`.

`val int_small : int t`

Generates small signed integers.

Non-uniform: smaller numbers (in absolute value) are more likely than bigger numbers.

Shrinks towards `0`.

- since 0.90

`val int_pos : int t`

Generates non-strictly positive integers uniformly (`0` included).

Shrinks towards towards `0`.

- since 0.90

`val pint : ?origin:int -> int t`

Generates non-strictly positive integers uniformly (`0` included).

Shrinks towards `origin` if specified, otherwise towards `0`.

- deprecated

  use `int_pos` instead

`val int_pos_small : int t`

Small positive integers (< `100`, `0` included).

Non-uniform: smaller numbers are more likely than bigger numbers.

Shrinks towards `0`.

- since 0.90

`val nat_small : int t`

Small positive integers (< `100`, `0` included).

Synonym for `int_pos_small`.

- since 0.90

`val small_nat : int t`

Small positive integers (< `100`, `0` included).

Non-uniform: smaller numbers are more likely than bigger numbers.

Shrinks towards `0`.

- since 0.5.1

- deprecated

  use `nat_small` instead

`val nat : int t`

Generates natural numbers (< `10_000`).

Non-uniform: smaller numbers are more likely than bigger numbers.

Shrinks towards `0`.

`val int_pos_mid : int t`

Generates natural numbers (< `10_000`).

Synonym for `nat`.

- since 0.90

`val big_nat : int t`

Generates natural numbers, possibly large (< `1_000_000`).

Non-uniform: smaller numbers are more likely than bigger numbers.

Shrinks towards `0`.

- since 0.10

- deprecated

  use `map abs int` instead.

`val int_neg : int t`

Generates strictly negative integers uniformly (`0` excluded).

Shrinks towards `-1`.

- since 0.90

`val neg_int : int t`

Generates non-strictly negative integers (`0` included).

Non-uniform: smaller numbers (in absolute value) are more likely than bigger numbers.

Shrinks towards `0`.

- deprecated

  use `int_neg` or `map (fun i -> -i) nat` instead.

`val small_int : int t`

Small UNSIGNED integers, for retrocompatibility.

Shrinks towards `0`.

- deprecated

  use `nat_small`.

`val small_signed_int : int t`

Small SIGNED integers, based on `small_nat`.

Non-uniform: smaller numbers (in absolute value) are more likely than bigger numbers.

Shrinks towards `0`.

- since 0.5.2

- deprecated

  use `int_small` instead.

`val int_small_corners : unit -> int t`

As `int_small`, but each newly created generator starts with a list of corner cases before falling back on random generation.

Note that `int_small_corners ()` is stateful, meaning that once the list of corner cases has been emitted, subsequent calls will not reproduce them. As a consequence, in the following example, the first test fails with a counter example, whereas the second rerun does not:

      let gen = QCheck2.Gen.small_int_corners ()
      let t = QCheck2.Test.make ~name:"never max_int" gen (fun i -> i <> max_int)
      let _ = QCheck_base_runner.run_tests ~verbose:true [t;t]

- since 0.90

`val small_int_corners : unit -> int t`

As `small_int`, but each newly created generator starts with a list of corner cases before falling back on random generation.

Note that `small_int_corners ()` is stateful, meaning that once the list of corner cases has been emitted, subsequent calls will not reproduce them. As a consequence, in the following example, the first test fails with a counter example, whereas the second rerun does not:

      let gen = QCheck2.Gen.small_int_corners ()
      let t = QCheck2.Test.make ~name:"never max_int" gen (fun i -> i <> max_int)
      let _ = QCheck_base_runner.run_tests ~verbose:true [t;t]

- deprecated

  use `int_small_corners` instead.

`val int32 : int32 t`

Generates uniform `int32` values.

Shrinks towards `0l`.

`val ui32 : int32 t`

Generates `int32` values.

Shrinks towards `0l`.

- deprecated

  use `int32` instead, the name is wrong, values are signed.

`val int64 : int64 t`

Generates uniform `int64` values.

Shrinks towards `0L`.

`val ui64 : int64 t`

Generates `int64` values.

Shrinks towards `0L`.

- deprecated

  use `int64` instead, the name is wrong, values are signed.

`val float : float t`

Generates floating point numbers.

Shrinks towards `0.`.

`val float_pos : float t`

Generates positive floating point numbers (`0.` included).

Shrinks towards `0.`.

`val float_neg : float t`

Generates negative floating point numbers. (`-0.` included).

Shrinks towards `-0.`.

`val pfloat : float t`

Generates positive floating point numbers (`0.` included).

Shrinks towards `0.`.

- deprecated

  use `float_pos` instead.

`val nfloat : float t`

Generates negative floating point numbers. (`-0.` included).

Shrinks towards `-0.`.

- deprecated

  use `float_neg` instead.

`val char : char t`

Generates characters in the `0..255` range.

Shrinks towards `'a'`.

`val char_printable : char t`

Generates printable characters.

The exhaustive list of character codes is:

- `32` to `126`, inclusive
- `'\n'`

Shrinks towards `'a'` or lower character codes.

- since 0.90

`val printable : char t`

Synonym for `char_printable`.

`val char_numeral : char t`

Generates numeral characters `'0'..'9'`.

Shrinks towards `'0'`.

- since 0.90

`val numeral : char t`

Synonym for `char_numeral`.

`val bytes_size : ?gen:char t -> int t -> bytes t`

Builds a bytes generator from a (non-negative) size generator. Accepts an optional character generator (the default is `char`).

Shrinks on the number of characters first, then on the characters.

- since 0.20

`val bytes_size_of : int t -> char t -> bytes t`

Builds a bytes generator from a (non-negative) size generator and a character generator.

Shrinks on the number of characters first, then on the characters.

- since 0.90

`val bytes : bytes t`

Bytes generator using the `char` character generator. Bytes size is generated by `nat`. See also `bytes_of` and `bytes_printable` for versions with custom char generator.

Shrinks on the number of characters first, then on the characters.

- since 0.20

`val bytes_of : char t -> bytes t`

Builds a bytes generator using the given character generator.

Shrinks on the number of characters first, then on the characters.

- since 0.20

`val bytes_printable : bytes t`

Generator using the `printable` character generator.

Shrinks on the number of characters first, then on the characters.

- since 0.20

`val bytes_small : bytes t`

Builds a bytes generator using the `char` character generator, length is `nat_small`.

Shrinks on the number of characters first, then on the characters.

- since 0.20

`val bytes_small_of : char t -> bytes t`

Builds a bytes generator using the given character generator, length is `nat_small`.

Shrinks on the number of characters first, then on the characters.

- since 0.20

`val string_size : ?gen:char t -> int t -> string t`

Builds a string generator from a (non-negative) size generator. Accepts an optional character generator (the default is `char`).

Shrinks on the number of characters first, then on the characters.

`val string_size_of : int t -> char t -> string t`

Builds a string generator from a (non-negative) size generator and a character generator.

Shrinks on the number of characters first, then on the characters.

- since 0.90

`val string : string t`

Builds a string generator. String size is generated by `nat`. The default character generator is `char`. See also `string_of` and `string_printable` for versions with custom char generator.

Shrinks on the number of characters first, then on the characters.

`val string_of : char t -> string t`

Builds a string generator using the given character generator.

Shrinks on the number of characters first, then on the characters.

- since 0.11

`val string_printable : string t`

Builds a string generator using the `printable` character generator.

Shrinks on the number of characters first, then on the characters.

- since 0.11

`val string_small : string t`

Builds a string generator using the `char` characher generator, length is `nat_small`.

Shrinks on the number of characters first, then on the characters.

- since 0.20

`val string_small_of : char t -> string t`

Builds a string generator using the given characher generator, length is `nat_small`.

Shrinks on the number of characters first, then on the characters.

- since 0.20

`val small_string : ?gen:char t -> string t`

Builds a string generator, length is `nat_small`. Accepts an optional character generator (the default is `char`). Shrinks on the number of characters first, then on the characters. This function is kept for backward compatibility: The optional argument is in fact a mandatory `option`, see c-cube/qcheck#162. Use `string_small` instead.

- deprecated

  use `string_small` instead.

`val pure : 'a -> 'a t`

`pure a` creates a generator that always returns `a`.

Does not shrink.

- since 0.8

`val return : 'a -> 'a t`

Synonym for `pure`

`val make_primitive : gen:(Stdlib.Random.State.t -> 'a) -> shrink:('a -> 'a Stdlib.Seq.t) -> 'a t`

`make_primitive ~gen ~shrink` creates a generator from a function `gen` that creates a random value (this function must only use the given `Random.State.t` for randomness) and a function `shrink` that, given a value `a`, returns a lazy list of "smaller" values (used when a test fails).

This lower-level function is meant to build generators for "primitive" types that can neither be built with other primitive generators nor through composition, or to have more control on the shrinking steps.

`shrink` must obey the following rules (for your own definition of "small"):

- `shrink a = Seq.empty` when `a` is the smallest possible value
- `shrink a` must return values strictly smaller than `a`, ideally from smallest to largest (for faster shrinking)
- `let rec loop a = match shrink a () with | Nil -> () | Cons (smaller_a, _) -> loop smaller_a` must end for all values `a` of type `'a` (i.e. there must not be an infinite number of shrinking steps).

⚠️ This is an unstable API as it partially exposes the implementation. In particular, the type of `Random.State.t` may very well change in a future version, e.g. if QCheck switches to another randomness library.

`val add_shrink_invariant : ('a -> bool) -> 'a t -> 'a t`

`add_shrink_invariant f gen` returns a generator similar to `gen` except all shrinks satisfy `f`. This way it's easy to preserve invariants that are enforced by generators, when shrinking values

- since 0.8

`val set_shrink : ('a -> 'a Stdlib.Seq.t) -> 'a t -> 'a t`

`set_shrink shrink gen` sets the shrinker to `shrink` for `gen`.

`val no_shrink : 'a t -> 'a t`

`no_shrink gen` returns a generator using `gen` but with shrinking disabled

#### Ranges

`val int_bound : int -> int t`

Uniform integer generator producing integers within `0..bound`.

Shrinks towards `0`.

- raises `Invalid_argument`

  if the argument is negative.

`val int_range : ?origin:int -> int -> int -> int t`

`int_range ?origin low high` is an uniform integer generator producing integers within `low..high` (inclusive).

Shrinks towards `origin` if specified, otherwise towards `0` (but always stays within the range).

Examples:

- `int_range ~origin:6 (-5) 15` will shrink towards `6`
- `int_range (-5) 15` will shrink towards `0`
- `int_range 8 20` will shrink towards `8` (closest to `0` within range)
- `int_range (-20) (-8)` will shrink towards `-8` (closest to `0` within range)

- raises `Invalid_argument`

  if any of the following holds:

  - `low > high`
  - `origin < low`
  - `origin > high`

`val (--) : int -> int -> int t`

`a -- b` is an alias for `int_range a b`. See `int_range` for more information.

`val float_bound_inclusive : ?origin:float -> float -> float t`

`float_bound_inclusive ?origin bound` returns a random floating-point number between `0.` and `bound` (inclusive). If `bound` is negative, the result is negative or zero. If `bound` is `0.`, the result is `0.`.

Shrinks towards `origin` if given, otherwise towards `0.`.

- since 0.11

`val float_bound_exclusive : ?origin:float -> float -> float t`

`float_bound_exclusive origin bound` returns a random floating-point number between `0.` and `bound` (exclusive). If `bound` is negative, the result is negative or zero.

Shrinks towards `origin` if given, otherwise towards `0.`.

- raises `Invalid_argument`

  if `bound` is `0.`.

- since 0.11

`val float_range : ?origin:float -> float -> float -> float t`

`float_range ?origin low high` generates floating-point numbers within `low` and `high` (inclusive).

Shrinks towards `origin` if specified, otherwise towards `0.` (but always stays within the range).

Examples:

- `float_range ~origin:6.2 (-5.8) 15.1` will shrink towards `6.2`
- `float_range (-5.8) 15.1` will shrink towards `0.`
- `float_range 8.5 20.1` will shrink towards `8.5` (closest to `0.` within range)
- `float_range (-20.1) (-8.5)` will shrink towards `-8.5` (closest to `0.` within range)

- raises `Invalid_argument`

  if any of the following holds:

  - `low > high`
  - `high -. low > max_float`
  - `origin < low`
  - `origin > high`

- since 0.11

`val (--.) : float -> float -> float t`

`a --. b` is an alias for `float_range ~origin:a a b`. See `float_range` for more information.

- since 0.11

`val float_exp : float -> float t`

`float_exp m` generates floating-point numbers following an exponential distribution with a mean of `m`.

- raises `Invalid_argument`

  if `m` is NaN.

- since 0.90

`val exponential : float -> float t`

Synonym for `float_exp`.

- since 0.23

`val char_range : ?origin:char -> char -> char -> char t`

`char_range ?origin low high` generates chars between `low` and `high`, inclusive. Example: `char_range 'a' 'z'` for all lower case ASCII letters.

Shrinks towards `origin` if specified, otherwise towards `low`.

- raises `Invalid_argument`

  if `low > high`.

- since 0.13

#### Choosing elements

`val oneof : 'a t list -> 'a t`

`oneof l` constructs a generator that selects among the given list of generators `l`.

Shrinks towards the first generator of the list.

- raises `Invalid_argument`

  or Failure if `l` is empty

`val oneof_list : 'a list -> 'a t`

`oneof_list l` constructs a generator that selects among the given list of values `l`.

Shrinks towards the first element of the list.

- raises `Invalid_argument`

  or Failure if `l` is empty

- since 0.90

`val oneofl : 'a list -> 'a t`

`oneofl l` constructs a generator that selects among the given list of values `l`.

Shrinks towards the first element of the list.

- raises `Invalid_argument`

  or Failure if `l` is empty

- deprecated

  use `oneof_list` instead.

`val oneof_array : 'a array -> 'a t`

`oneof_array a` constructs a generator that selects among the given array of values `a`.

Shrinks towards the first element of the array.

- raises `Invalid_argument`

  or Failure if `a` is empty

- since 0.90

`val oneofa : 'a array -> 'a t`

`oneofa a` constructs a generator that selects among the given array of values `a`.

Shrinks towards the first element of the array.

- raises `Invalid_argument`

  or Failure if `a` is empty

- deprecated

  use `oneof_array` instead.

`val oneof_weighted : (int * 'a t) list -> 'a t`

Constructs a generator that selects among a given list of generators. Each of the given generators are chosen based on a positive integer weight.

Shrinks towards the first element of the list.

- since 0.90

`val frequency : (int * 'a t) list -> 'a t`

Constructs a generator that selects among a given list of generators. Each of the given generators are chosen based on a positive integer weight.

Shrinks towards the first element of the list.

- deprecated

  use `oneof_weighted` instead.

`val oneof_list_weighted : (int * 'a) list -> 'a t`

Constructs a generator that selects among a given list of values. Each of the given values are chosen based on a positive integer weight.

Shrinks towards the first element of the list.

- since 0.90

`val frequencyl : (int * 'a) list -> 'a t`

Constructs a generator that selects among a given list of values. Each of the given values are chosen based on a positive integer weight.

Shrinks towards the first element of the list.

- deprecated

  use `oneof_list_weighted` instead.

`val oneof_array_weighted : (int * 'a) array -> 'a t`

Constructs a generator that selects among a given array of values. Each of the array entries are chosen based on a positive integer weight.

Shrinks towards the first element of the array.

- since 0.90

`val frequencya : (int * 'a) array -> 'a t`

Constructs a generator that selects among a given array of values. Each of the array entries are chosen based on a positive integer weight.

Shrinks towards the first element of the array.

- deprecated

  use `oneof_array_weighted` instead.

#### Shuffling elements

`val shuffle_array : 'a array -> 'a array t`

Returns a copy of the array with its elements shuffled.

- since 0.90

`val shuffle_a : 'a array -> 'a array t`

Returns a copy of the array with its elements shuffled.

- deprecated

  use `shuffle_array` instead.

`val shuffle_list : 'a list -> 'a list t`

Creates a generator of shuffled lists.

- since 0.90

`val shuffle_l : 'a list -> 'a list t`

Creates a generator of shuffled lists.

- deprecated

  use `shuffle_list` instead.

`val shuffle_list_weighted : (int * 'a) list -> 'a list t`

Creates a generator of weighted shuffled lists. A given list is shuffled on each generation according to the weights of its elements. An element with a larger weight is more likely to be at the front of the list than an element with a smaller weight. If we want to pick random elements from the (head of) list but need to prioritize some elements over others, this generator can be useful.

Example: given a weighted list `[1, "one"; 5, "five"; 10, "ten"]`, the generator is more likely to generate `["ten"; "five"; "one"]` or `["five"; "ten"; "one"]` than `["one"; "ten"; "five"]` because "ten" and "five" have larger weights than "one".

- since 0.90

`val shuffle_w_l : (int * 'a) list -> 'a list t`

A synonym for `shuffle_list_weighted` since 0.90

- since 0.11

- deprecated

  use `shuffle_list_weighted` instead.

#### Corner cases

`val graft_corners : 'a t -> 'a list -> unit -> 'a t`

`graft_corners gen l ()` makes a new generator that enumerates the corner cases in `l` and then behaves like `g`.

Does not shrink if the test fails on a grafted value. Shrinks towards `gen` otherwise.

Note that `graft_corners gen l ()` is stateful, meaning that once the elements of `l` have been emitted, subsequent calls will not reproduce them. It is therefore recommended that separate tests each use a fresh generator.

- since 0.6

`val int_pos_corners : int list`

Non-negative corner cases for int.

- since 0.6

- deprecated

  define your own list of corner cases instead

`val int_corners : int list`

All corner cases for int.

- since 0.6

- deprecated

  define your own list of corner cases instead

#### Lists, arrays and options

`val list : 'a t -> 'a list t`

Builds a list generator from an element generator. List size is generated by `nat`.

Shrinks on the number of elements first, then on elements.

`val list_small : 'a t -> 'a list t`

Generates lists of small size (see `nat_small`).

Shrinks on the number of elements first, then on elements.

- since 0.90

`val small_list : 'a t -> 'a list t`

Generates lists of small size (see `nat_small`).

Shrinks on the number of elements first, then on elements.

- since 0.5.3

- deprecated

  use `list_small` instead.

`val list_size : int t -> 'a t -> 'a list t`

Builds a list generator from a (non-negative) size generator and an element generator.

Shrinks on the number of elements first, then on elements.

`val list_repeat : int -> 'a t -> 'a list t`

`list_repeat i g` builds a list generator from exactly `i` elements generated by `g`.

Shrinks on elements only.

- deprecated

  use `list_size (return i) g` instead.

`val array : 'a t -> 'a array t`

Builds an array generator from an element generator. Array size is generated by `nat`.

Shrinks on the number of elements first, then on elements.

`val array_size : int t -> 'a t -> 'a array t`

Builds an array generator from a (non-negative) size generator and an element generator.

Shrinks on the number of elements first, then on elements.

`val array_small : 'a t -> 'a array t`

Generates arrays of small size (see `nat_small`).

Shrinks on the number of elements first, then on elements.

- since 0.90

`val small_array : 'a t -> 'a array t`

Generates arrays of small size (see `nat_small`).

Shrinks on the number of elements first, then on elements.

- since 0.10

- deprecated

  use `array_small` instead.

`val array_repeat : int -> 'a t -> 'a array t`

`array_repeat i g` builds an array generator from exactly `i` elements generated by `g`.

Shrinks on elements only.

- deprecated

  use `array_size (return i) g` instead.

`val option : ?ratio:float -> 'a t -> 'a option t`

`option gen` is an `option` generator that uses `gen` when generating `Some` values.

Shrinks towards `None` then towards shrinks of `gen`.

- parameter ratio

  a float between `0.` and `1.` indicating the probability of a sample to be `Some _` rather than `None` (value is `0.85`).

- since 0.19 (renamed from [opt])

`val opt : ?ratio:float -> 'a t -> 'a option t`

`opt` is an alias of `option` for backward compatibility.

- deprecated

  use `option` instead.

`val result : ?ratio:float -> 'a t -> 'e t -> ('a, 'e) Stdlib.result t`

`result ~ratio okgen errgen` generates `Ok v` with `v` coming from `okgen` or `Error e` with `e` coming from `errgen`, depending on `ratio`.

- parameter ratio

  a float between `0.` and `1.` indicating the probability of a sample to be `Ok _` rather than `Error _`.

- since 0.24

#### Combining generators

`val pair : 'a t -> 'b t -> ('a * 'b) t`

`pair gen1 gen2` generates pairs.

Shrinks on `gen1` and then `gen2`.

`val triple : 'a t -> 'b t -> 'c t -> ('a * 'b * 'c) t`

`triple gen1 gen2 gen3` generates triples.

Shrinks on `gen1`, then `gen2` and then `gen3`.

`val quad : 'a t -> 'b t -> 'c t -> 'd t -> ('a * 'b * 'c * 'd) t`

`quad gen1 gen2 gen3 gen4` generates quadruples.

Shrinks on `gen1`, then `gen2`, then `gen3` and then `gen4`.

- since 0.5.1

#### Tuple of generators

##### Shrinks on `gen1`, then `gen2`, then ...

`val tup2 : 'a t -> 'b t -> ('a * 'b) t`

Combines two generators into a 2-tuple generator.

`val tup3 : 'a t -> 'b t -> 'c t -> ('a * 'b * 'c) t`

Combines three generators into a 3-tuple generator.

`val tup4 : 'a t -> 'b t -> 'c t -> 'd t -> ('a * 'b * 'c * 'd) t`

Combines four generators into a 4-tuple generator.

`val tup5 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> ('a * 'b * 'c * 'd * 'e) t`

Combines five generators into a 5-tuple generator.

`val tup6 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t -> ('a * 'b * 'c * 'd * 'e * 'f) t`

Combines six generators into a 6-tuple generator.

`val tup7 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t -> 'g t -> ('a * 'b * 'c * 'd * 'e * 'f * 'g) t`

Combines seven generators into a 7-tuple generator.

`val tup8 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t -> 'g t -> 'h t -> ('a * 'b * 'c * 'd * 'e * 'f * 'g * 'h) t`

Combines eight generators into an 8-tuple generator.

`val tup9 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t -> 'g t -> 'h t -> 'i t -> ('a * 'b * 'c * 'd * 'e * 'f * 'g * 'h * 'i) t`

Combines nine generators into a 9-tuple generator.

#### Convert a structure of generator to a generator of structure

`val flatten_list : 'a t list -> 'a list t`

Generate a list of elements from individual generators.

Shrinks on the elements of the list, in the list order.

- since 0.90

`val flatten_l : 'a t list -> 'a list t`

Generate a list of elements from individual generators.

Shrinks on the elements of the list, in the list order.

- since 0.13

- deprecated

  use `flatten_list` instead.

`val flatten_array : 'a t array -> 'a array t`

Generate an array of elements from individual generators.

Shrinks on the elements of the array, in the array order.

- since 0.90

`val flatten_a : 'a t array -> 'a array t`

Generate an array of elements from individual generators.

Shrinks on the elements of the array, in the array order.

- since 0.13

- deprecated

  use `flatten_array` instead.

`val flatten_option : 'a t option -> 'a option t`

Generate an option from an optional generator.

Shrinks towards `None` then shrinks on the value.

- since 0.90

`val flatten_opt : 'a t option -> 'a option t`

Generate an option from an optional generator.

Shrinks towards `None` then shrinks on the value.

- since 0.13

- deprecated

  use `flatten_option` instead.

`val flatten_result : ('a t, 'e) Stdlib.result -> ('a, 'e) Stdlib.result t`

Generate a result from `Ok gen`, an error from `Error e`.

Shrinks on `gen` if `Ok gen`. Does not shrink if `Error e`.

- since 0.90

`val flatten_res : ('a t, 'e) Stdlib.result -> ('a, 'e) Stdlib.result t`

Generate a result from `Ok gen`, an error from `Error e`.

Shrinks on `gen` if `Ok gen`. Does not shrink if `Error e`.

- since 0.13

- deprecated

  use `flatten_result` instead.

`val join : 'a t t -> 'a t`

Collapses a generator of generators to a generator.

Shrinks on the generated generators.

- since 0.5

#### Influencing the size of generated values

`val sized : 'a sized -> 'a t`

Creates a generator from a size-bounded generator by first generating a size using `nat` and passing the result to the size-bounded generator.

Shrinks on the size first, then on the generator.

`val sized_size : int t -> 'a sized -> 'a t`

Creates a generator from a size-bounded generator by first generating a size using the integer generator and passing the result to the size-bounded generator.

Shrinks on the size first, then on the generator.

- since 0.5

#### Recursive data structures

`val fix : (('a -> 'b t) -> 'a -> 'b t) -> 'a -> 'b t`

Parametrized fixpoint combinator for generating recursive values.

The fixpoint is parametrized over an generator state `'a`, and the fixpoint computation may change the value of this state in the recursive calls.

In particular, this can be used for size-bounded generators (with `'a` as `int`). The passed size-parameter should decrease to ensure termination.

Example:

      type tree = Leaf of int | Node of tree * tree

      let leaf x = Leaf x
      let node x y = Node (x,y)

      let g = QCheck.Gen.(sized @@ fix
                            (fun self n -> match n with
                               | 0 -> map leaf nat
                               | n ->
                                 oneof_weighted
                                   [1, map leaf nat;
                                    2, map2 node (self (n/2)) (self (n/2))]
                            ))

`fix f` shrinks on the generators returned by `f`.

`val delay : (unit -> 'a t) -> 'a t`

Delay execution of some code until the generator is actually called. This can be used to manually implement recursion or control flow in a generator.

- since 0.17

### Composing generators

QCheck generators compose well: it means one can easily craft generators for new values or types from existing generators.

Part of the following documentation is greatly inspired by Gabriel Scherer's excellent Generator module documentation.

#### Functor

`Gen.t` is a functor (in the Haskell sense of "mappable"): it has a `map` function to transform a generator of `'a` into a generator of `'b`, given a simple function `'a -> 'b`.

      let even_gen : int Gen.t = Gen.map (fun n -> n * 2) Gen.int

      let odd_gen : int Gen.t = Gen.map (fun n -> n * 2 + 1) Gen.int

      let lower_case_string_gen : string Gen.t = Gen.map String.lowercase Gen.string_printable

      type foo = Foo of string * int
      let foo_gen : foo Gen.t =
        Gen.map (fun (s, n) -> Foo (s, n)) Gen.(pair string_printable int)

#### Applicative

`Gen.t` is applicative: it has a `map2` function to apply a function of 2 (or more) arguments to 2 (or more) generators.

Another equivalent way to look at it is that it has an `ap` function to apply a generator of functions to a generator of values. While at first sight this may look almost useless, it actually permits a nice syntax (using the operator alias `<*>`) for functions of any number of arguments.

      (* Notice that this looks suspiciously like the [foo] example above:
         this is no coincidence! [pair] is a special case of [map2] where
         the function wraps arguments in a tuple. *)
      type foo = Foo of string * int
      let foo_gen : foo Gen.t =
        Gen.map2 (fun s n -> Foo (s, n)) Gen.string_printable Gen.int

      let string_prefixed_with_keyword_gen : string Gen.t =
        Gen.map2 (fun prefix s -> prefix ^ s)
          (Gen.oneof_list ["foo"; "bar"; "baz"])
          Gen.string_printable

Applicatives are useful when you need several random values to build a new generator, and the values are unrelated. A good rule of thumb is: if the values could be generated in parallel, then you can use an applicative function to combine those generators.

Note that while `map2`, `map3`, `map4`, and `map5` are provided, you can use functions with more than 5 arguments (this is where the `<*>` operator alias shines):

      val complex_function : bool -> string -> int -> string -> int64 -> some_big_type

      (* Verbose version, using map3 and ap to mimic map5 *)
      let big_type_gen : some_big_type Gen.t = Gen.(
          ap (
            ap (
              map3 complex_function
                bool
                string_printable
                int)
              string_printable)
            int64)

      (* Sleeker syntax, using operators aliases for map and ap *)
      let big_type_gen : some_big_type Gen.t = Gen.(
          complex_function
          <$> bool
          <*> string_printable
          <*> int
          <*> string_printable
          <*> int64)

#### Monad

`Gen.t` is a monad: it has a `bind` function to return a generator (not a value) based on another generated value.

As an example, imagine you want to create a generator of `(int, string) result` that is an `Ok` 90% of the time and an `Error` 10% of the time. You can generate a number between 0 and 9 and return a generator of `int` (wrapped in an `Ok` using `map`) if the generated number is lower than 9, otherwise return a generator of `string` (wrapped in an `Error` using `map`):

      let int_string_result : (int, string) result Gen.t = Gen.(
          bind (int_range 0 9) (fun n ->
              if n < 9
              then map Result.ok int
              else map Result.error string_printable))

      (* Alternative syntax with operators *)
      let int_string_result : (int, string) result Gen.t = Gen.(
          int_range 0 9 >>= fun n ->
          if n < 9
          then int >|= Result.ok
          else string_printable >|= Result.error)

      (* Another alternative syntax with OCaml 4.08+ binding operators *)
      let int_string_result : (int, string) result Gen.t = Gen.(
          let* n = int_range 0 9 in
          if n < 9
          then int >|= Result.ok
          else string_printable >|= Result.error)

Note that this particular use case can be simplified by using `oneof_weighted`:

      let int_string_result : (int, string) result Gen.t = Gen.(
          oneof_weighted [
            (9, int >|= Result.ok);
            (1, string_printable >|= Result.error)
          ])

`val map : ('a -> 'b) -> 'a t -> 'b t`

`map f gen` transforms a generator `gen` by applying `f` to each generated element.

Shrinks towards the shrinks of `gen` with `f` applied to them.

`val (>|=) : 'a t -> ('a -> 'b) -> 'b t`

An infix synonym for `map`. Note the order of arguments is reversed (usually more convenient for composing).

`val (<$>) : ('a -> 'b) -> 'a t -> 'b t`

An infix synonym for `map`

- since 0.13

`val map2 : ('a -> 'b -> 'c) -> 'a t -> 'b t -> 'c t`

`map2 f gen1 gen2` transforms two generators `gen1` and `gen2` by applying `f` to each pair of generated elements.

Shrinks on `gen1` and then `gen2`.

`val map3 : ('a -> 'b -> 'c -> 'd) -> 'a t -> 'b t -> 'c t -> 'd t`

`map3 f gen1 gen2 gen3` transforms three generators `gen1`, `gen2`, and `gen3` by applying `f` to each triple of generated elements.

Shrinks on `gen1`, then `gen2`, and then `gen3`.

`val map4 : ('a -> 'b -> 'c -> 'd -> 'e) -> 'a t -> 'b t -> 'c t -> 'd t -> 'e t`

`map4 f gen1 gen2 gen3 gen4` transforms four generators `gen1`, `gen2`, `gen3`, and `gen4` by applying `f` to each quadruple of generated elements.

Shrinks on `gen1`, then `gen2`, `gen3`, and then `gen4`.

- since 0.25

`val map5 : ('a -> 'b -> 'c -> 'd -> 'e -> 'f) -> 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t`

`map5 f gen1 gen2 gen3 gen4 gen5` transforms five generators `gen1`, `gen2`, `gen3`, `gen4`, and `gen5` by applying `f` to each quintuple of generated elements.

Shrinks on `gen1`, then `gen2`, `gen3`, `gen4`, and then `gen5`.

- since 0.25

`val map_keep_input : ('a -> 'b) -> 'a t -> ('a * 'b) t`

`map_keep_input f g` transforms a generator `g` by applying `f` to each generated element. Returns both the generated element from `g` and the output from `f`.

Shrinks towards the shrinks of `g` with `f` applied to them.

- since 0.90

`val ap : ('a -> 'b) t -> 'a t -> 'b t`

`ap fgen gen` composes a function generator and an argument generator into a result generator.

Shrinks on `fgen` and then `gen`.

`val (<*>) : ('a -> 'b) t -> 'a t -> 'b t`

Synonym for `ap`

`val bind : 'a t -> ('a -> 'b t) -> 'b t`

`bind gen f` first generates a value of type `'a` with `gen` and then passes it to `f` to generate a value of type `'b`. This is typically useful when a generator depends on the value generated by another generator.

Shrinks on `gen` and then on the resulting generator.

`val (>>=) : 'a t -> ('a -> 'b t) -> 'b t`

Synonym for `bind`

`val (let+) : 'a t -> ('a -> 'b) -> 'b t`

Binding operator alias for `map`.

Example:

    let+ n = int_range 0 10 in
    string_of_int n

    (* is equivalent to *)

    map (fun n -> string_of_int n) (int_range 0 10)

`val (and+) : 'a t -> 'b t -> ('a * 'b) t`

Binding operator alias for `pair`.

Example:

    let+ n = int_range 0 10
    and+ b = bool in
    if b then string_of_int n else "Not a number"

    (* is equivalent to *)

    map
      (fun (n, b) -> if b then string_of_int n else "Not a number")
      (pair (int_range 0 10) bool)

`val (let*) : 'a t -> ('a -> 'b t) -> 'b t`

Binding operator alias for `bind`.

Example:

    let* n = int_range 0 9 in
    if n < 9
    then int >|= Result.ok
    else string_printable >|= Result.error

    (* is equivalent to *)

    bind (int_range 0 9) (fun n ->
        if n < 9
        then map Result.ok int
        else map Result.error string_printable)

`val (and*) : 'a t -> 'b t -> ('a * 'b) t`

Binding operator alias for `pair`.

Example:

    let* n = int_range 0 9
    and* b = bool in
    if n < 9 then int >|= Result.ok
    else if b then pure (Error "Some specific error")
    else string_printable >|= Result.error

    (* is equivalent to *)

    bind (pair (int_range 0 9) bool) (fun (n, b) ->
        if n < 9 then map Result.ok int
        else if b then pure (Error "Some specific error")
        else map Result.error string_printable)

### Debug generators

These functions should not be used in tests: they are provided for convenience to debug/investigate what values and shrinks a generator produces.

`val generate : ?rand:Stdlib.Random.State.t -> n:int -> 'a t -> 'a list`

`generate ~n gen` generates `n` values using `gen` (shrinks are discarded).

`val generate1 : ?rand:Stdlib.Random.State.t -> 'a t -> 'a`

`generate1 gen` generates one instance of `gen` (shrinks are discarded).

`val generate_tree : ?rand:Stdlib.Random.State.t -> 'a t -> 'a Tree.t`

`generate_tree ?rand gen` generates a random value and its shrinks using `gen`.