Up

Module Core_random

This is a slightly modified version of the OCaml standard library's random.mli. We want Core's Random module to be different from OCaml's standard one:

  • We expose Random.State.default, so that user code can easily share the default random state if it wants.
  • We disallow Random.get_state, because it misleadingly makes a copy of random state. And it is what people naturally, albeit incorrectly, grab for when they want to use shared random state.

The fact that we construct our own default random state means that code using Core.Std.Random and code using OCaml's Random will not share the default state.

Signature

Pseudo-random number generators (PRNG).

Basic functions

Note that all of these "basic" functions mutate a global random state.

val init : int -> unit

Initialize the 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 : ?allow_in_tests:bool -> unit -> unit

Initialize the generator with a more-or-less random seed chosen in a system-dependent way. By default, self_init is disallowed in inline tests, as it's often used for no good reason and it just creates non deterministic failures for everyone. Passing ~allow_in_tests:true removes this restriction in case you legitimately want non-deterministic values, like in Filename.temp_dir.

val bits : unit -> int

Return 30 random bits in a nonnegative integer.

Before [3.12.0] used a different algorithm (affects all the following functions)
val int : int -> int

Random.int bound returns a random integer between 0 (inclusive) and bound (exclusive). bound must be greater than 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 float : float -> float

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

val bool : unit -> bool

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

Advanced functions
module State : sig .. end
The functions from module State manipulate the current state of the random generator explicitely. This allows using one or several deterministic PRNGs, even in a multi-threaded program, without interference from other parts of the program.
val get_state : unit -> [
| `Consider_using_Random_State_default
]

OCaml's Random.get_state makes a copy of the default state, which is almost certainly not what you want. State.default, which is the actual default state, is probably what you want.

val set_state : State.t -> unit

Set the state of the generator used by the basic functions.