package containers

  1. Overview
  2. Docs
package containers
Legend:
Library
Module
Module type
Parameter
Class
Class type

Random Generators

Documentation for the standard Random module

include module type of struct include Random end

Basic functions

val init : int -> unit

Initialize the domain-local generator, using the argument as a seed. The same seed will always yield the same sequence of numbers.

val full_init : int array -> unit

Same as Random.init but takes more data as seed.

val self_init : unit -> unit

Initialize the domain-local generator with a random seed chosen in a system-dependent way. If /dev/urandom is available on the host machine, it is used to provide a highly random initial seed. Otherwise, a less random seed is computed from system parameters (current time, process IDs, domain-local state).

val bits : unit -> int

Return 30 random bits in a nonnegative integer.

  • before 5.0.0

    used a different algorithm (affects all the following functions)

val full_int : int -> int

Random.full_int bound returns a random integer between 0 (inclusive) and bound (exclusive). bound may be any positive integer.

If bound is less than 230, Random.full_int bound is equal to Random.int bound. If bound is greater than 230 (on 64-bit systems or non-standard environments, such as JavaScript), Random.full_int returns a value, where Random.int raises Stdlib.Invalid_argument.

  • since 4.13.0
val int32 : Int32.t -> Int32.t

Random.int32 bound returns a random integer between 0 (inclusive) and bound (exclusive). bound must be greater than 0.

val nativeint : Nativeint.t -> Nativeint.t

Random.nativeint bound returns a random integer between 0 (inclusive) and bound (exclusive). bound must be greater than 0.

val int64 : Int64.t -> Int64.t

Random.int64 bound returns a random integer between 0 (inclusive) and bound (exclusive). bound must be greater than 0.

val bool : unit -> bool

Random.bool () returns true or false with probability 0.5 each.

val bits32 : unit -> Int32.t

Random.bits32 () returns 32 random bits as an integer between Int32.min_int and Int32.max_int.

  • since 4.14.0
val bits64 : unit -> Int64.t

Random.bits64 () returns 64 random bits as an integer between Int64.min_int and Int64.max_int.

  • since 4.14.0
val nativebits : unit -> Nativeint.t

Random.nativebits () returns 32 or 64 random bits (depending on the bit width of the platform) as an integer between Nativeint.min_int and Nativeint.max_int.

  • since 4.14.0

Advanced functions

The functions from module State manipulate the current state of the random generator explicitly. This allows using one or several deterministic PRNGs, even in a multi-threaded program, without interference from other parts of the program.

module State = Random.State
val get_state : unit -> State.t

get_state() returns a fresh copy of the current state of the domain-local generator (which is used by the basic functions).

val set_state : State.t -> unit

set_state s updates the current state of the domain-local generator (which is used by the basic functions) by copying the state s into it.

type state = Random.State.t
type 'a t = state -> 'a

Random generator for values of type 'a.

type 'a random_gen = 'a t
val return : 'a -> 'a t

return x is the generator that always returns x. Example: let random_int = return 4 (* fair dice roll *).

val flat_map : ('a -> 'b t) -> 'a t -> 'b t

flat_map f g st is f (g st) st.

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

Monadic bind.

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

map f g st is f (g st).

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

Delay evaluation. Useful for side-effectful generators that need some code to run for every call. Example:

let gensym = let r = ref 0 in fun () -> incr r; !r ;;

delay (fun () ->
  let name = gensym() in
  small_int >>= fun i -> return (name,i)
)
  • since 0.4
val choose : 'a t list -> 'a option t

Choose a generator within the list.

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

Like choose but without option.

val choose_array : 'a t array -> 'a option t

Choose a generator within the array.

val choose_return : 'a list -> 'a t

Choose among the list.

val replicate : int -> 'a t -> 'a list t

replicate n g makes a list of n elements which are all generated randomly using g.

val sample_without_duplicates : cmp:('a -> 'a -> int) -> int -> 'a t -> 'a list t

sample_without_replacement n g makes a list of n elements which are all generated randomly using g with the added constraint that none of the generated random values are equal.

  • since 2.4
val list_seq : 'a t list -> 'a list t

Build random lists from lists of random generators.

  • since 0.4
exception Pick_from_empty
  • since 0.16
val pick_list : 'a list -> 'a t

Pick an element at random from the list.

  • since 0.16
val pick_array : 'a array -> 'a t

Pick an element at random from the array.

  • since 0.16
val small_int : int t

A small int (100).

val int : int -> int t

Random int within the given range.

val int_range : int -> int -> int t

Inclusive range.

val small_float : float t

A reasonably small float (100.0).

  • since 0.6.1
val float : float -> float t

Random float within the given range.

  • since 0.6.1
val float_range : float -> float -> float t

Inclusive range. float_range a b assumes a < b.

  • since 0.6.1
val split : int -> (int * int) option t

Split a positive value n into n1,n2 where n = n1 + n2.

  • returns

    None if the value is too small.

val split_list : int -> len:int -> int list option t

Split a value n into a list of values whose sum is n and whose length is length. The list is never empty and does not contain 0.

  • returns

    None if the value is too small.

val retry : ?max:int -> 'a option t -> 'a option t

retry g calls g until it returns some value, or until the maximum number of retries was reached. If g fails, then it counts for one iteration, and the generator retries.

  • parameter max:

    maximum number of retries. Default 10.

val try_successively : 'a option t list -> 'a option t

try_successively l tries each generator of l, one after the other. If some generator succeeds its result is returned, else the next generator is tried.

val (<?>) : 'a option t -> 'a option t -> 'a option t

a <?> b is a choice operator. It first tries a, and returns its result if successful. If a fails, then b is returned.

val fix : ?sub1:('a t -> 'a t) list -> ?sub2:('a t -> 'a t -> 'a t) list -> ?subn:(int t * ('a list t -> 'a t)) list -> base:'a t -> int t -> 'a t

Recursion combinators, for building recursive values. The integer generator is used to provide fuel. The sub_ generators should use their arguments only once!

  • parameter sub1

    cases that recurse on one value.

  • parameter sub2

    cases that use the recursive gen twice.

  • parameter subn

    cases that use a list of recursive cases.

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

Let operators on OCaml >= 4.08.0, nothing otherwise

  • since 2.8
val let+ : 'a t -> ('a -> 'b) -> 'b t
val and+ : 'a t -> 'b t -> ('a * 'b) t
val let* : 'a t -> ('a -> 'b t) -> 'b t
val and* : 'a t -> 'b t -> ('a * 'b) t
Run a generator
val run : ?st:state -> 'a t -> 'a

Using a random state (possibly the one in argument) run a generator.

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