`type 'a t = Stdlib.Random.State.t -> 'a`

A random generator for values of type 'a.

`type 'a sized = int -> Stdlib.Random.State.t -> 'a`

Random generator with a size bound.

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

Create a constant generator.

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

Synonym for `return`

- since 0.8

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

Monadic bind for writing dependent generators. First generates an `'a` and then passes it to the given function, to generate a `'b`.

- since 0.90

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

Synonym for `bind` since 0.90

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

Applicative operator for composing a function generator and an argument generator into a result generator.

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

Synonym for `ap` since 0.90

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

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

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

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

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

`map3 f g1 g2 g3` transforms three generators `g1`, `g2`, and `g3` by applying `f` to each triple of generated elements.

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

`map4 f g1 g2 g3 g4` transforms four generators `g1`, `g2`, `g3`, and `g4` by applying `f` to each quadruple of generated elements.

- 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 g1 g2 g3 g4 g5` transforms five generators `g1`, `g2`, `g3`, `g4`, and `g5` by applying `f` to each quintuple of generated elements.

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

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

An infix synonym for `map`.

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

An infix synonym for `map`

- since 0.13

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

Constructs a generator that selects among a given list of generators.

- raises `Invalid_argument`

  or Failure if list is empty

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

Constructs a generator that selects among a given list of values.

- raises `Invalid_argument`

  or Failure if list is empty

- since 0.90

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

Constructs a generator that selects among a given list of values.

- raises `Invalid_argument`

  or Failure if list is empty

- deprecated

  use `oneof_list` instead.

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

Constructs a generator that selects among a given array of values.

- raises `Invalid_argument`

  or Failure if list is empty

- since 0.90

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

Constructs a generator that selects among a given array of values.

- raises `Invalid_argument`

  or Failure if list 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.

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

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

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

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

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

- deprecated

  use `oneof_array_weighted` instead.

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

Creates a generator of shuffled arrays.

- since 0.90

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

Shuffles the array in place.

- deprecated

  Consider using `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`

An alias for `shuffle_list_weighted` since 0.90.

- since 0.11

- deprecated

  use `shuffle_list_weighted` instead.

`val range_subset : size:int -> int -> int -> int array t`

`range_subset ~size:k low high` generates an array of length `k` of sorted distinct integers in the range `low..high` (included).

Complexity O(k log k), drawing `k` random integers.

- raises `Invalid_argument`

  outside the valid region `0 <= k <= high-low+1`.

- since 0.18

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

`array_subset k arr` generates a sub-array of `k` elements at distinct positions in the input array `arr`, in the same order.

Complexity O(k log k), drawing `k` random integers.

- raises `Invalid_argument`

  outside the valid region `0 <= size <= Array.length arr`.

- since 0.18

#### Primitive generators

`val unit : unit t`

The unit generator.

`val bool : bool t`

The boolean generator.

`val float : float t`

Generates floating point numbers.

`val float_pos : float t`

Generates positive floating point numbers (0. included).

`val float_neg : float t`

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

`val pfloat : float t`

Generates positive floating point numbers (0. included).

- deprecated

  use `float_pos` instead.

`val nfloat : float t`

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

- deprecated

  use `float_neg` instead.

`val float_bound_inclusive : float -> float t`

`float_bound_inclusive 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.

- since 0.11

`val float_bound_exclusive : float -> float t`

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

- raises `Invalid_argument`

  if `bound` is zero.

- since 0.11

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

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

- raises `Invalid_argument`

  if `high < low` or if the range is larger than `max_float`.

- since 0.11

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

Synonym for `float_range`

- 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 nat : int t`

Generates small natural numbers.

`val int_pos_mid : int t`

Generates small natural numbers. Synonym for `nat`.

- since 0.90

`val big_nat : int t`

Generates natural numbers, possibly large.

- since 0.10

- deprecated

  use `map abs int` instead.

`val int_neg : int t`

Generates strictly negative integers uniformly (0 excluded).

- since 0.90

`val neg_int : int t`

Generates non-strictly negative integers (0 included).

- deprecated

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

`val int_pos : int t`

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

- since 0.90

`val pint : int t`

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

- deprecated

  use `int_pos` instead.

`val int : int t`

Generates integers uniformly.

`val int_small : int t`

Generated small signed integers.

- since 0.90

`val int_pos_small : int t`

Small integers (< 100)

- since 0.90

`val nat_small : int t`

Small integers (< 100) Synonym for `int_pos_small`.

- since 0.90

`val small_nat : int t`

Small integers (< 100)

- since 0.5.1

- deprecated

  use `nat_small` instead

`val small_int : int t`

Small UNSIGNED integers, for retrocompatibility.

- deprecated

  use `nat_small`.

`val small_signed_int : int t`

Small SIGNED integers, based on `small_nat`.

- since 0.5.2

- deprecated

  use `int_small` instead.

`val int_bound : int -> int t`

Uniform integer generator producing integers between `0` and `bound` (inclusive). For `bound < 2^{30} - 1` uses `Random.State.int` for integer generation.

- raises `Invalid_argument`

  if the argument is negative.

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

Uniform integer generator producing integers within `low,high` (inclusive).

- raises `Invalid_argument`

  if `low > high`.

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

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

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

- since 0.90

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

Synonym for `int_range`.

`val int32 : int32 t`

Generates `int32` values uniformly.

- since 0.24

`val int64 : int64 t`

Generates `int64` values uniformly.

- since 0.24

`val ui32 : int32 t`

Generates `int32` values.

- deprecated

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

`val ui64 : int64 t`

Generates `int64` values.

- deprecated

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

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

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

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

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

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

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

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

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

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

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

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

- deprecated

  use `array_size (return i) g` instead.

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

An option generator, with optional ratio.

- parameter ratio

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

- since 0.19 (renamed from [opt])

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

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

- since 0.18 ([?ratio] parameter)

- deprecated

  use `option` instead.

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

A result generator, with optional ratio.

- parameter ratio

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

- since 0.24

`val char : char t`

Generates characters upto character code 255.

`val char_printable : char t`

Generates printable ascii characters - either '\n' or in the range 32 to 126, inclusive.

- since 0.90

`val printable : char t`

Synonym for `char_printable`.

`val char_numeral : char t`

Generates numeral characters uniformly distributed over `'0'..'9'`.

- since 0.90

`val numeral : char t`

Synonym for `char_numeral`.

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

Generates chars between the two bounds, inclusive. Example: `char_range 'a' 'z'` for all lower case ascii letters.

- since 0.13

`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`).

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

- since 0.90

`val bytes : bytes t`

Builds a bytes generator. Bytes size is generated by `nat` and characters are generated by `char`.

Note: This had an optional `?gen` parameter removed in 0.90. Use `bytes_of` instead to pass a `char` generator.

- since 0.20

`val bytes_of : char t -> bytes t`

Builds a bytes generator using the given character generator.

- since 0.20

`val bytes_printable : bytes t`

Generator using the `printable` character generator.

- since 0.20

`val bytes_small : bytes t`

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

- since 0.20

`val bytes_small_of : char t -> bytes t`

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

- 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`).

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

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

- since 0.90

`val string : string t`

Builds a string generator. String size is generated by `nat` and characters are generated by `char`.

Note: This had an optional `?gen` parameter removed in 0.90. Use `string_of` instead to pass a `char` generator.

`val string_of : char t -> string t`

Builds a string generator using the given character generator.

- since 0.11

`val string_readable : string t`

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

- since 0.11

- deprecated

  use `string_printable`

`val string_printable : string t`

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

- since 0.18

`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`).

- deprecated

  use `string_small`

`val string_small : string t`

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

- since 0.20

`val string_small_of : char t -> string t`

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

- since 0.20

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

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

- since 0.90

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

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

- since 0.5.3

- deprecated

  use `list_small` instead.

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

Generate a list of elements from individual generators

- since 0.90

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

Generate a list of elements from individual generators

- 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

- since 0.90

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

Generate an array of elements from individual generators

- since 0.13

- deprecated

  use `flatten_array` instead.

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

Generate an option from an optional generator

- since 0.90

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

Generate an option from an optional generator

- 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 g`, an error from `Error e`

- since 0.90

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

Generate a result from `Ok g`, an error from `Error e`

- since 0.13

- deprecated

  use `flatten_result` instead.

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

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

- since 0.90

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

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

- since 0.10

- deprecated

  use `array_small` instead.

#### Tuple generators

Create tuple generators by composing individual element generators. For example, `Gen.(tup3 int char bool)` creates a `(int * char * bool)` triple generator by composing the `int`, `char`, and `bool` generators.

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

Generates pairs.

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

Generates triples.

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

Generates quadruples.

- since 0.5.1

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

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

Collapses a generator of generators to simply a generator.

- since 0.5

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

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

- since 0.5

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

Parametrized fixpoint combinator for generating recursive values.

The fixpoint is parametrized over an arbitrary 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 ('a is 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))]
                            ))

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

`nat_split2 n` generates pairs `(n1, n2)` of natural numbers with `n1 + n2 = n`.

This is useful to split sizes to combine sized generators.

- since 0.18

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

`pos_split2 n` generates pairs `(n1, n2)` of strictly positive (nonzero) natural numbers with `n1 + n2 = n`.

- raises `Invalid_argument`

  unless `n >= 2`.

This is useful to split sizes to combine sized generators.

- since 0.18

`val nat_split : size:int -> int -> int array t`

`nat_split ~size:k n` generates `k`-sized arrays `n1,n2,..nk` of natural numbers in `[0;n]` with `n1 + n2 + ... + nk = n`.

This is useful to split sizes to combine sized generators.

Complexity O(k log k).

- since 0.18

`val pos_split : size:int -> int -> int array t`

`pos_split ~size:k n` generates `k`-sized arrays `n1,n2,..nk` of strictly positive (non-zero) natural numbers with `n1 + n2 + ... + nk = n`.

This is useful to split sizes to combine sized generators.

Complexity O(k log k).

- raises `Invalid_argument`

  unless `0 < k <= n` or `0 = k = n`.

- since 0.18

`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

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

Binding operator alias for `map`.

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

Binding operator alias for `pair`.

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

Binding operator alias for `(>>=)`.

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

Binding operator alias for `pair`.

#### Debug generators

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

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

`generate ~n g` generates `n` instances of `g`.

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

`generate1 g` generates one instance of `g`.