package core

  1. Overview
  2. Docs
package core
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module Quickcheck.GeneratorSource

An 'a t a generates values of type 'a with a specific probability distribution.

Generators are constructed as functions that produce a value from a splittable pseudorandom number generator (see Splittable_random), with a ~size argument threaded through to bound the size of the result value and the depth of recursion.

There is no prescribed semantics for size other than that it must be non-negative. Non-recursive generators are free to ignore it, and recursive generators need only make sure it decreases in recursive calls and that recursion bottoms out at 0.

Sourceval create : (size:Base.Int.t -> random:Splittable_random.State.t -> 'a) -> 'a t
Sourceval generate : 'a t -> size:Base.Int.t -> random:Splittable_random.State.t -> 'a

Generators form a monad. t1 >>= fun x -> t2 replaces each value x in t1 with the values in t2; each value's probability is the product of its probability in t1 and t2.

This can be used to form distributions of related values. For instance, the following expression creates a distribution of pairs x,y where x <= y:

  Int.gen
  >>= fun x ->
  Int.gen_incl x Int.max_value
  >>| fun y ->
  x, y
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.

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

bind t ~f = 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 Caml.ignore. Some monads still do let ignore = ignore_m for historical reasons.

Sourcemodule Let_syntax : sig ... end

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

include Base.Applicative.S with type 'a t := 'a t
Sourceval return : 'a -> 'a t
Sourceval map : 'a t -> f:('a -> 'b) -> 'b 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 (>>|) : 'a t -> ('a -> 'b) -> 'b 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
Sourceval all : 'a t list -> 'a list t
Sourceval all_unit : unit t list -> unit t
Sourcemodule Applicative_infix : sig ... end
Sourceval size : Base.Int.t t

size = create (fun ~size _ -> size)

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

with_size t ~size = create (fun ~size:_ random -> generate t ~size random)

Sourceval bool : Base.Bool.t t
Sourceval char : Base.Char.t t
Sourceval char_digit : Base.Char.t t
Sourceval char_lowercase : Base.Char.t t
Sourceval char_uppercase : Base.Char.t t
Sourceval char_alpha : Base.Char.t t
Sourceval char_alphanum : Base.Char.t t
Sourceval char_print : Base.Char.t t
Sourceval char_whitespace : Base.Char.t t
Sourceval singleton : 'a -> 'a t
Sourceval doubleton : 'a -> 'a -> 'a t
Sourceval of_list : 'a Base.List.t -> 'a t

Produce any of the given values, weighted equally.

of_list [ v1 ; ... ; vN ] = union [ singleton v1 ; ... ; singleton vN ]

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

Combine arbitary generators, weighted equally.

union [ g1 ; ... ; gN ] = weighted_union [ (1.0, g1) ; ... ; (1.0, gN) ]

Sourceval of_sequence : p:Base.Float.t -> 'a Sequence.t -> 'a t

Generator for the values from a potentially infinite sequence. Chooses each value with probability p, or continues with probability 1-p. Must satisfy 0. < p && p <= 1..

Sourceval tuple2 : 'a t -> 'b t -> ('a * 'b) t
Sourceval tuple3 : 'a t -> 'b t -> 'c t -> ('a * 'b * 'c) t
Sourceval tuple4 : 'a t -> 'b t -> 'c t -> 'd t -> ('a * 'b * 'c * 'd) t
Sourceval tuple5 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> ('a * 'b * 'c * 'd * 'e) t
Sourceval tuple6 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t -> ('a * 'b * 'c * 'd * 'e * 'f) t
Sourceval variant2 : 'a t -> 'b t -> [ `A of 'a | `B of 'b ] t
Sourceval variant3 : 'a t -> 'b t -> 'c t -> [ `A of 'a | `B of 'b | `C of 'c ] t
Sourceval variant4 : 'a t -> 'b t -> 'c t -> 'd t -> [ `A of 'a | `B of 'b | `C of 'c | `D of 'd ] t
Sourceval variant5 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> [ `A of 'a | `B of 'b | `C of 'c | `D of 'd | `E of 'e ] t
Sourceval variant6 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t -> [ `A of 'a | `B of 'b | `C of 'c | `D of 'd | `E of 'e | `F of 'f ] t
Sourceval geometric : p:Base.Float.t -> Base.Int.t -> Base.Int.t t

geometric ~p init produces a geometric distribution (think "radioactive decay") that produces init with probability p, and otherwise recursively chooses from geometric ~p (init+1). Must satisfy 0. < p && p <= 1..

Sourceval small_non_negative_int : Base.Int.t t

small_non_negative_int produces a non-negative int of a tractable size, e.g. allocating a value of this size should not run out of memory.

Sourceval small_positive_int : Base.Int.t t

small_positive_int produces a positive int of a tractable size, e.g. allocating a value of this size should not run out of memory.

Sourceval fn : 'a Base_quickcheck.Observer.t -> 'b t -> ('a -> 'b) t

Generators for functions; take observers for inputs and a generator for outputs.

Sourceval fn2 : 'a Base_quickcheck.Observer.t -> 'b Base_quickcheck.Observer.t -> 'c t -> ('a -> 'b -> 'c) t
Sourceval fn3 : 'a Base_quickcheck.Observer.t -> 'b Base_quickcheck.Observer.t -> 'c Base_quickcheck.Observer.t -> 'd t -> ('a -> 'b -> 'c -> 'd) t
Sourceval compare_fn : 'a Base_quickcheck.Observer.t -> ('a -> 'a -> Base.Int.t) t

Generator for comparison functions; result is guaranteed to be a partial order.

Sourceval equal_fn : 'a Base_quickcheck.Observer.t -> ('a -> 'a -> Base.Bool.t) t

Generator for equality functions; result is guaranteed to be an equivalence relation.

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

filter_map t ~f produces y for every x in t such that f x = Some y.

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

filter t ~f produces every x in t such that f x = true.

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

Generator for recursive data type with multiple clauses. At size 0, chooses only among the non-recursive cases; at sizes greater than 0, chooses among non-recursive and recursive cases, calling the recursive cases with decremented size.

  type tree = Leaf | Node of tree * int * tree;;
  recursive_union [return Leaf] ~f:(fun self ->
    [let%map left = self
     and int = Int.gen
     and right = self
     in Node (left, int, right)])
Sourceval weighted_recursive_union : (Base.Float.t * 'a t) Base.List.t -> f:('a t -> (Base.Float.t * 'a t) Base.List.t) -> 'a t

Like recursive_union, with the addition of non-uniform weights for each clause.

Sourceval fixed_point : ('a t -> 'a t) -> 'a t

Fixed-point generator. Use size to bound the size of the value and the depth of the recursion. There is no prescribed semantics for size except that it must be non-negative. For example, the following produces a naive generator for natural numbers:

  fixed_point (fun self ->
    match%bind size with
    | 0 -> singleton 0
    | n -> with_size self ~size:(n-1) >>| Int.succ)
Sourceval weighted_union : (Base.Float.t * 'a t) Base.List.t -> 'a t

weighted_union alist produces a generator that combines the distributions of each t in alist with the associated weights, which must be finite positive floating point values.

Sourceval of_fun : (Base.Unit.t -> 'a t) -> 'a t

of_fun f produces a generator that lazily applies f.

It is recommended that f not be memoized. Instead, spread out the work of generating a whole distribution over many of_fun calls combined with weighted_union. This allows lazily generated generators to be garbage collected after each test and the relevant portions cheaply recomputed in subsequent tests, rather than accumulating without bound over time.

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

Generators for lists, choosing each element independently from the given element generator. list and list_non_empty distribute size among the list length and the sizes of each element. list_non_empty never generates the empty list. list_with_length generates lists of the given length, and distributes size among the sizes of the elements.

Sourceval list_non_empty : 'a t -> 'a Base.List.t t
Sourceval list_with_length : Base.Int.t -> 'a t -> 'a Base.List.t t
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct