Module `QCheck.Gen`Source

The Gen module offers combinators to build custom generators. Unlike the the 'a arbitrary record type, which comes with printers, shrinkers, etc. Gen.t represents a type for generation only.

Sourcetype 'a t = Stdlib.Random.State.t -> 'a

A random generator for values of type 'a.

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

Random generator with a size bound.

Sourceval return : 'a -> 'a t

Create a constant generator.

Sourceval pure : 'a -> 'a t

Synonym for return

since 0.8

Sourceval (>>=) : '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.

Sourceval (<*>) : ('a -> 'b) t -> 'a t -> 'b t

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

Sourceval map : ('a -> 'b) -> 'a t -> 'b t

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

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

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

Sourceval 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

Source

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

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

Sourceval (>|=) : 'a t -> ('a -> 'b) -> 'b t

An infix synonym for map.

Sourceval (<$>) : ('a -> 'b) -> 'a t -> 'b t

An infix synonym for map

since 0.13

Sourceval 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

Sourceval 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

Sourceval 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

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

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

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

Sourceval shuffle_a : 'a array -> unit t

Shuffles the array in place.

Sourceval shuffle_l : 'a list -> 'a list t

Creates a generator of shuffled lists.

Sourceval shuffle_w_l : (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.11

Sourceval 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

Sourceval 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

Sourceval unit : unit t

The unit generator.

Sourceval bool : bool t

The boolean generator.

Sourceval float : float t

Generates floating point numbers.

Sourceval pfloat : float t

Generates positive floating point numbers (0. included).

Sourceval nfloat : float t

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

Sourceval 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

Sourceval 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

Sourceval 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

Sourceval (--.) : float -> float -> float t

Synonym for float_range

since 0.11

Sourceval exponential : float -> float t

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

raises Invalid_argument
if m is NaN.

since 0.23

Sourceval nat : int t

Generates small natural numbers.

Sourceval big_nat : int t

Generates natural numbers, possibly large.

since 0.10

Sourceval neg_int : int t

Generates non-strictly negative integers (0 included).

Sourceval pint : int t

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

Sourceval int : int t

Generates integers uniformly.

Sourceval small_nat : int t

Small integers (< 100)

since 0.5.1

Sourceval small_int : int t

Small UNSIGNED integers, for retrocompatibility.

deprecated
use small_nat.

Sourceval small_signed_int : int t

Small SIGNED integers, based on small_nat.

since 0.5.2

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

Sourceval int_range : int -> int -> int t

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

raises Invalid_argument
if low > high.

Sourceval 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

Sourceval int_pos_corners : int list

Non-negative corner cases for int.

since 0.6

Sourceval int_corners : int list

All corner cases for int.

since 0.6

Sourceval (--) : int -> int -> int t

Synonym for int_range.

Sourceval int32 : int32 t

Generates int32 values uniformly.

since 0.24

Sourceval int64 : int64 t

Generates int64 values uniformly.

since 0.24

Sourceval ui32 : int32 t

Generates int32 values.

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

Sourceval ui64 : int64 t

Generates int64 values.

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

Sourceval list : 'a t -> 'a list t

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

Sourceval list_size : int t -> 'a t -> 'a list t

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

Sourceval list_repeat : int -> 'a t -> 'a list t

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

Sourceval array : 'a t -> 'a array t

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

Sourceval array_size : int t -> 'a t -> 'a array t

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

Sourceval array_repeat : int -> 'a t -> 'a array t

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

Sourceval 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])

Sourceval opt : ?ratio:float -> 'a t -> 'a option t

opt is an alias of option for backward compatibility.

since 0.18 ([?ratio] parameter)

Sourceval 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

Sourceval char : char t

Generates characters upto character code 255.

Sourceval printable : char t

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

Sourceval numeral : char t

Generates numeral characters.

Sourceval 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

Sourceval 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

Sourceval bytes : ?gen:char t -> bytes t

Builds a bytes generator. Bytes size is generated by nat. Accepts an optional character generator (the default is char). See also bytes_of and bytes_printable for versions without optional parameters.

since 0.20

Sourceval bytes_of : char t -> bytes t

Builds a bytes generator using the given character generator.

since 0.20

Sourceval bytes_printable : bytes t

Generator using the printable character generator.

since 0.20

Sourceval bytes_small : bytes t

Builds a bytes generator using the char character generator, length is small_nat

since 0.20

Sourceval bytes_small_of : char t -> bytes t

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

since 0.20

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

Sourceval string : ?gen:char t -> string t

Builds a string generator. String size is generated by nat. Accepts an optional character generator (the default is char). See also string_of and string_readable for versions without optional parameters.

Sourceval string_of : char t -> string t

Builds a string generator using the given character generator.

since 0.11

Sourceval string_readable : string t

deprecated see string_printable

Sourceval string_printable : string t

Builds a string generator using the printable character generator.

since 0.18

Sourceval small_string : ?gen:char t -> string t

Builds a string generator, length is small_nat Accepts an optional character generator (the default is char).

Sourceval string_small : string t

Builds a string generator using the char character generator, length is small_nat

since 0.20

Sourceval string_small_of : char t -> string t

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

since 0.20

Sourceval small_list : 'a t -> 'a list t

Generates lists of small size (see small_nat).

since 0.5.3

Sourceval flatten_l : 'a t list -> 'a list t

Generate a list of elements from individual generators

since 0.13

Sourceval flatten_a : 'a t array -> 'a array t

Generate an array of elements from individual generators

since 0.13

Sourceval flatten_opt : 'a t option -> 'a option t

Generate an option from an optional generator

since 0.13

Sourceval 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

Sourceval small_array : 'a t -> 'a array t

Generates arrays of small size (see small_nat).

since 0.10

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.

Sourceval pair : 'a t -> 'b t -> ('a * 'b) t

Generates pairs.

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

Generates triples.

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

Generates quadruples.

since 0.5.1

Sourceval tup2 : 'a t -> 'b t -> ('a * 'b) t

Combines two generators into a 2-tuple generator.

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

Combines three generators into a 3-tuple generator.

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

Combines four generators into a 4-tuple generator.

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

Source

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.

Source

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.

Source

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.

Source

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.

Sourceval join : 'a t t -> 'a t

Collapses a generator of generators to simply a generator.

since 0.5

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

Sourceval 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

Sourceval 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 ->
                             frequency
                               [1, map leaf nat;
                                2, map2 node (self (n/2)) (self (n/2))]
                        ))

Sourceval 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

Sourceval 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

Sourceval 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

Sourceval 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

Sourceval 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

Sourceval (let+) : 'a t -> ('a -> 'b) -> 'b t

Binding operator alias for map.

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

Binding operator alias for pair.

Sourceval (let*) : 'a t -> ('a -> 'b t) -> 'b t

Binding operator alias for (>>=).

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

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

generate ~n g generates n instances of g.

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

generate1 g generates one instance of g.

package qcheck-core

Module QCheck.GenSource

Primitive generators

Tuple generators

Debug generators

Module `QCheck.Gen`Source