Module Base_quickcheck.GeneratorSource

Generators are sources of random values. Every randomized test needs a generator to produce its inputs.

Sourcetype +'a t

Basic Generators

These are good default generators for tests over types from OCaml and Base. They are designed to hit corner cases reasonably often, and also generate reasonably good coverage of common cases and arbitrary values.

Sourceval unit : Base.unit t
Sourceval bool : Base.bool t
Sourceval char : Base.char t
Sourceval string : Base.string t
Sourceval bytes : Base.bytes t
Sourceval int : Base.int t
Sourceval int32 : Base.int32 t
Sourceval int63 : Base.Int63.t t
Sourceval int64 : Base.int64 t
Sourceval nativeint : Base.nativeint t
Sourceval float : Base.float t
Sourceval sexp : Base.Sexp.t t
Sourceval option : 'a t -> 'a Base.option t
Sourceval list : 'a t -> 'a Base.list t
Sourceval array : 'a t -> 'a Base.array t
Sourceval ref : 'a t -> 'a Base.ref t
Sourceval lazy_t : 'a t -> 'a Base.Lazy.t t
Sourceval either : 'a t -> 'b t -> ('a, 'b) Base.Either.t t
Sourceval result : 'a t -> 'b t -> ('a, 'b) Base.Result.t t

This helper module type exists separately just to open Bigarray in its scope.

Sourceval fn : 'a Base_quickcheck__.Observer0.t -> 'b t -> ('a -> 'b) t

Generates random functions that use the given observer to perturb the pseudo-random state that is then used to generate the output value. The resulting functions are therefore deterministic, assuming the observer is deterministic.

Sourceval map_t_m : ('key, 'cmp) Base.Comparator.Module.t -> 'key t -> 'data t -> ('key, 'data, 'cmp) Base.Map.t t
Sourceval set_t_m : ('elt, 'cmp) Base.Comparator.Module.t -> 'elt t -> ('elt, 'cmp) Base.Set.t t
Sourceval map_tree_using_comparator : comparator:('key, 'cmp) Base.Comparator.t -> 'key t -> 'data t -> ('key, 'data, 'cmp) Base.Map.Using_comparator.Tree.t t
Sourceval set_tree_using_comparator : comparator:('elt, 'cmp) Base.Comparator.t -> 'elt t -> ('elt, 'cmp) Base.Set.Using_comparator.Tree.t t

Combining and Modifying Generators

Sourceval of_list : 'a Base.list -> 'a t

Produces any of the given values, weighted uniformly.

Sourceval union : 'a t Base.list -> 'a t

Chooses among the given generators, weighted uniformly; then chooses a value from that generator.

include Base.Applicative.S with type 'a t := 'a t
Sourceval both : 'a t -> 'b t -> ('a * 'b) t
Sourceval (<*>) : ('a -> 'b) t -> 'a t -> 'b t

same as apply

Sourceval (<*) : 'a t -> unit t -> 'a t
Sourceval (*>) : unit t -> 'a t -> 'a t
Sourceval apply : ('a -> 'b) t -> 'a t -> 'b t
Sourceval map2 : 'a t -> 'b t -> f:('a -> 'b -> 'c) -> 'c t
Sourceval map3 : 'a t -> 'b t -> 'c t -> f:('a -> 'b -> 'c -> 'd) -> 'd t
Sourcemodule Applicative_infix : sig ... end
include Base.Monad.S with type 'a t := 'a t
Sourceval (>>=) : 'a t -> ('a -> 'b t) -> 'b t

t >>= f returns a computation that sequences the computations represented by two monad elements. The resulting computation first does t to yield a value v, and then runs the computation returned by f v.

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

t >>| f is t >>= (fun a -> return (f a)).

Sourcemodule Monad_infix : sig ... end
Sourceval bind : 'a t -> f:('a -> 'b t) -> 'b t

bind t ~f = t >>= f

Sourceval return : 'a -> 'a t

return v returns the (trivial) computation that returns v.

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

map t ~f is t >>| f.

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

join t is t >>= (fun t' -> t').

Sourceval ignore_m : 'a t -> unit t

ignore_m t is map t ~f:(fun _ -> ()). ignore_m used to be called ignore, but we decided that was a bad name, because it shadowed the widely used Stdlib.ignore. Some monads still do let ignore = ignore_m for historical reasons.

Sourceval all : 'a t list -> 'a list t
Sourceval all_unit : unit t list -> unit t

Like all, but ensures that every monadic value in the list produces a unit value, all of which are discarded rather than being collected into a list.

Sourcemodule Let_syntax : sig ... end

These are convenient to have in scope when programming with a monad:

Size of Random Values

Base_quickcheck threads a size parameter through generators to limit the size of unbounded types. Users of Base_quickcheck often do not need to think about the size parameter; the default generators handle it sensibly. Generators of atomic types ignore it, generators of bounded-size containers like both and either thread it through unchanged, and generators of unbounded-size containers like list and set_t_m distribute the size they are given among their constituents.

The bindings below allow direct manipulation of the size parameter in cases where users want a custom treatment of sizes. There is no prescribed meaning of the size parameter for any given type other than that it must be non-negative. As a general guideline, however, the time and space used to generate a value should be proportional to the size parameter at most.

The size parameter should be treated as an upper bound but not as a lower bound, so for example a generator given a size parameter of 2 should have a chance to generate values of size 0 or 1 as well. If the size parameter is treated as a lower bound, then for example members of tuples will always be generated at the same size, and test cases for members of different size will not be covered.

Sourceval size : Base.int t

Returns the current size parameter.

Sourceval with_size : 'a t -> size:Base.int -> 'a t

Produces a generator that ignores the size parameter passed in by Base_quickcheck and instead uses the given ~size argument. Most often used with size to reduce the size when dispatching to generators for subparts of a value.

For example, here is a use of with_size and size to create a generator for optional lists. We are careful to generate None even at non-zero sizes; see the note above about not using size as a lower bound.

  let optional_list generator =
    let open Let_syntax in
    match%bind both size bool with
    | (0, _) | (_, false) -> return None
    | k, _ ->
      let%map elements = with_size ~size:(k-1) (list generator) in
      Some elements
Sourceval sizes : ?min_length:Base.int -> ?max_length:Base.int -> Base.unit -> Base.int Base.list t

Produces a list of sizes that distribute the current size among list elements. The min_length and max_length parameters can be used to bound the length of the result.

This is the distribution used by generators such as list to divide up size among elements.

This function is designed so that elements of list are always generated at strictly smaller size than the list itself. The technical invariant is: if size_list is generated by with_size ~size:n (sizes ~min_length ()), then:

  (List.length size_list - min_length) + (List.sum (module Int) size_list)
  <= n

Filtering Generators

Sourceval filter : 'a t -> f:('a -> Base.bool) -> 'a t

Produces values for which f returns true. If f returns false, retries with size incremented by 1. This avoids filter getting stuck if all values at a given size fail f; see the note above about not using size as a lower bound.

Sourceval filter_map : 'a t -> f:('a -> 'b Base.option) -> 'b t

When f produces Some x, produces x. If f returns None, retries with size incremented by 1, as with filter.

Generating Recursive Values

Sourceval recursive_union : 'a t Base.list -> f:('a t -> 'a t Base.list) -> 'a t

Ties the recursive knot to produce generators for recursive types that have multiple clauses, separating base cases from recursive cases. At size 0, only base cases are produced; at size n > 0, the base cases are produced at size n along with the recursive cases at size n-1. Raises if the list of base cases is empty or if the list of recursive cases is empty.

For example, here is a use of recursive_union to create a generator for an expression datatype.

  type exp =
    | Int  of int
    | Bool of bool
    | If   of exp * exp * exp
    | Add  of exp * exp

  let exp_generator =
    recursive_union
      [
        map int ~f:(fun i -> Int i);
        map bool ~f:(fun b -> Bool b);
      ]
      ~f:(fun exp ->
        let open Let_syntax in
        [
          (let%map a = exp and b = exp and c = exp in If (a, b, c));
          (let%map a = exp and b = exp in Add (a, b));
        ])
Sourceval fixed_point : ('a t -> 'a t) -> 'a t

Like recursive_union, without separate clauses or automatic size management. Useful for generating recursive types that don't fit the clause structure of recursive_union.

For example, here is a use of fixed_point to create a generator for N-ary trees. No manual size management is needed, as Generator.list guarantees to generate list elements at strictly smaller sizes than the list itself.

  type tree = Node of tree list
  let tree_generator =
    fixed_point (fun tree ->
      map (list tree) ~f:(fun trees -> Node trees))
Sourceval of_lazy : 'a t Base.Lazy.t -> 'a t

Creates a t that forces the lazy argument as necessary. Can be used to tie (mutually) recursive knots.

Custom Random Distributions

Sourceval of_weighted_list : (Base.float * 'a) Base.list -> 'a t

Produces one of the given values, chosen with the corresponding weight. Weights must be non-negative and must have a strictly positive sum.

Sourceval weighted_union : (Base.float * 'a t) Base.list -> 'a t

Produces one of the given generators, chosen with the corresponding weight, then chooses a value from that generator. Weights must be non-negative and must have a strictly positive sum.

Sourceval weighted_recursive_union : (Base.float * 'a t) Base.list -> f:('a t -> (Base.float * 'a t) Base.list) -> 'a t

Like recursive_union, with explicit weights for each clause. Weights must be non-negative and the recursive case weights must have a strictly positive sum.

Integer Distributions

Sourceval small_positive_or_zero_int : Base.int t

Produces an integer between 0 and an unspecified upper bound which is proportional to size. This is a good generator to use for sizes of values like strings which have a variable number of fixed-size elements.

Sourceval small_strictly_positive_int : Base.int t

Like small_positive_or_zero_int but with a minimum of 1.

Uniform Unbounded Distributions

These generators produce any value of the relevant integer type with uniform weight. The default generators for these types differ in that they give higher weight to corner cases, e.g. min_value and max_value.

Sourceval int_uniform : Base.int t
Sourceval int32_uniform : Base.int32 t
Sourceval int63_uniform : Base.Int63.t t
Sourceval int64_uniform : Base.int64 t
Sourceval nativeint_uniform : Base.nativeint t
Bounded Distributions

These generators produce any value between the given inclusive bounds, which must be given in nondecreasing order. Higher weight is given to corner cases, e.g. the bounds themselves.

Sourceval int_inclusive : Base.int -> Base.int -> Base.int t
Sourceval int32_inclusive : Base.int32 -> Base.int32 -> Base.int32 t
Sourceval int63_inclusive : Base.Int63.t -> Base.Int63.t -> Base.Int63.t t
Sourceval int64_inclusive : Base.int64 -> Base.int64 -> Base.int64 t
Sourceval nativeint_inclusive : Base.nativeint -> Base.nativeint -> Base.nativeint t
Uniform Bounded Distributions

These generators produce any value between the given inclusive bounds, which must be given in nondecreasing order. All values are given equal weight.

Sourceval int_uniform_inclusive : Base.int -> Base.int -> Base.int t
Sourceval int32_uniform_inclusive : Base.int32 -> Base.int32 -> Base.int32 t
Sourceval int63_uniform_inclusive : Base.Int63.t -> Base.Int63.t -> Base.Int63.t t
Sourceval int64_uniform_inclusive : Base.int64 -> Base.int64 -> Base.int64 t
Sourceval nativeint_uniform_inclusive : Base.nativeint -> Base.nativeint -> Base.nativeint t
Uniform in Log Space Distributions

These generators produce any value between the given inclusive, non-negative bounds, choosing bit-length in that range uniformly and then uniformly among values with that bit-length between the bounds. The bounds must be given in nondecreasing order.

Sourceval int_log_uniform_inclusive : Base.int -> Base.int -> Base.int t
Sourceval int32_log_uniform_inclusive : Base.int32 -> Base.int32 -> Base.int32 t
Sourceval int63_log_uniform_inclusive : Base.Int63.t -> Base.Int63.t -> Base.Int63.t t
Sourceval int64_log_uniform_inclusive : Base.int64 -> Base.int64 -> Base.int64 t
Sourceval nativeint_log_uniform_inclusive : Base.nativeint -> Base.nativeint -> Base.nativeint t
Log Space Distributions

Like the *_log_uniform_inclusive bindings above, but giving additional weight to corner cases, e.g. the given bounds.

Sourceval int_log_inclusive : Base.int -> Base.int -> Base.int t
Sourceval int32_log_inclusive : Base.int32 -> Base.int32 -> Base.int32 t
Sourceval int63_log_inclusive : Base.Int63.t -> Base.Int63.t -> Base.Int63.t t
Sourceval int64_log_inclusive : Base.int64 -> Base.int64 -> Base.int64 t
Sourceval nativeint_log_inclusive : Base.nativeint -> Base.nativeint -> Base.nativeint t
Geometric Distributions

These generators produce a geometric distribution with a given minimum and probabilty p. In other words, with probability p, the minimum is produced. Otherwise, a value is effectively produced from a geometric distribution with the same p and a minimum one higher, although the implementation can be more efficent than this. If the result overflows, the function returns max_value for the integer type.

Raises if p <. 0. || 1. <. p..

Sourceval int_geometric : Base.int -> p:Base.float -> Base.int t
Sourceval int32_geometric : Base.int32 -> p:Base.float -> Base.int32 t
Sourceval int63_geometric : Base.Int63.t -> p:Base.float -> Base.Int63.t t
Sourceval int64_geometric : Base.int64 -> p:Base.float -> Base.int64 t
Sourceval nativeint_geometric : Base.nativeint -> p:Base.float -> Base.nativeint t

Floating Point Distributions

Sourceval float_inclusive : Base.float -> Base.float -> Base.float t

Generates values between the given bounds, inclusive, which must be finite and in nondecreasing order. Weighted toward boundary values.

Sourceval float_uniform_exclusive : Base.float -> Base.float -> Base.float t

Generates values between the given bounds, exclusive, which must be finite and in increasing order, with at least one float value between them. Weighted approximately uniformly across the resulting range, rounding error notwithstanding.

Sourceval float_without_nan : Base.float t
Sourceval float_finite : Base.float t
Sourceval float_strictly_positive : Base.float t
Sourceval float_strictly_negative : Base.float t
Sourceval float_positive_or_zero : Base.float t
Sourceval float_negative_or_zero : Base.float t
Sourceval float_of_class : Base.Float.Class.t -> Base.float t

Character Distributions

Sourceval char_lowercase : Base.char t
Sourceval char_uppercase : Base.char t
Sourceval char_digit : Base.char t
Sourceval char_alpha : Base.char t
Sourceval char_alphanum : Base.char t
Sourceval char_whitespace : Base.char t
Sourceval char_print : Base.char t
Sourceval char_uniform_inclusive : Base.char -> Base.char -> Base.char t

String Distributions

Sourceval string_non_empty : Base.string t
Sourceval string_with_length : length:Base.int -> Base.string t
Sourceval string_of : Base.char t -> Base.string t
Sourceval string_non_empty_of : Base.char t -> Base.string t
Sourceval string_with_length_of : Base.char t -> length:Base.int -> Base.string t
Sourceval string_like : Base.string -> Base.string t

Produces strings similar to the input, with some number of edits.

Sexp Distributions

Sourceval sexp_of : Base.string t -> Base.Sexp.t t

Produces s-expressions whose atoms are chosen from the given string distribution.

List Distributions

Sourceval list_non_empty : 'a t -> 'a Base.list t
Sourceval list_with_length : 'a t -> length:Base.int -> 'a Base.list t
Sourceval list_filtered : 'a Base.list -> 'a Base.list t

Randomly drops elements from a list. The length of each result is chosen uniformly between 0 and the length of the input, inclusive.

Sourceval list_permutations : 'a Base.list -> 'a Base.list t

Produces permutations of the given list, weighted uniformly.

Bigarray Distributions

Sourceval bigarray1 : 'a t -> ('a, 'b) Bigarray.kind -> 'c Bigarray.layout -> length:Base.int Base.option -> ('a, 'b, 'c) Bigarray.Array1.t t

Low-Level Interface

These functions provide direct access to the pseudo-random state threaded through Base_quickcheck generators. Most users should not need these functions.

Sourceval perturb : 'a t -> Base.int -> 'a t

Passes in additional "salt" used to perturb the pseudo-random state used to generate random values. Generators' output is intended to be deterministic for any initial pseudorandom state, so perturb can be used to generate a new generator with the same distribution that nonetheless produces different values from the original for any given pseudo-random state.

Sourceval create : (size:Base.int -> random:Splittable_random.t -> 'a) -> 'a t

Creates a generator that calls the given function with the current size parameter and pseudorandom state.

Sourceval generate : 'a t -> size:Base.int -> random:Splittable_random.t -> 'a

Generates a random value using the given size and pseudorandom state. Useful when using create and dispatching to other existing generators.

Sourcemodule Debug : sig ... end