(**************************************************************************)
(*                                                                        *)
(*                                 OCaml                                  *)
(*                                                                        *)
(*               Damien Doligez, projet Para, INRIA Rocquencourt          *)
(*          Xavier Leroy, projet Cambium, College de France and Inria     *)
(*                                                                        *)
(*   Copyright 1996 Institut National de Recherche en Informatique et     *)
(*     en Automatique.                                                    *)
(*                                                                        *)
(*   All rights reserved.  This file is distributed under the terms of    *)
(*   the GNU Lesser General Public License version 2.1, with the          *)
(*   special exception on linking described in the file LICENSE.          *)
(*                                                                        *)
(**************************************************************************)

(** Pseudo-random number generators (PRNG).

    With multiple domains, each domain has its own generator that evolves
    independently of the generators of other domains.  When a domain is
    created, its generator is initialized by splitting the state
    of the generator associated with the parent domain.

    In contrast, all threads within a domain share the same domain-local
    generator.  Independent generators can be created with the {!Random.split}
    function and used with the functions from the {!Random.State} module.

    @before 5.0 Random value generation used a different algorithm.
    This affects all the functions in this module which return random values.
*)

(** {1 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 a cryptographically secure pseudorandom number
    generator 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.
*)

val int : int -> int
(** [Random.int bound] returns a random integer between 0 (inclusive)
     and [bound] (exclusive).  [bound] must be greater than 0 and less
     than 2{^30}.

    @raise Invalid_argument if [bound] <= 0 or [bound] >= 2{^30}.
*)

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 2{^31},
     then [Random.full_int bound] yields identical output
     across systems with varying [int] sizes.

     If [bound] is less than 2{^30},
     then [Random.full_int bound] is equal to {!Random.int}[ bound].

     If [bound] is at least 2{^30}
     (on 64-bit systems, or non-standard environments such as JavaScript),
     then [Random.full_int] returns a value
     whereas {!Random.int} raises {!Stdlib.Invalid_argument}.

    @raise Invalid_argument if [bound] <= 0.

    @since 4.13 *)

val int_in_range : min:int -> max:int -> int
(** [Random.int_in_range ~min ~max] returns a random integer
    between [min] (inclusive) and [max] (inclusive).
    Both [min] and [max] are allowed to be negative;
    [min] must be less than or equal to [max].

    If both bounds fit in 32-bit signed integers
    (that is, if -2{^31} <= [min] and [max] < 2{^31}),
    then [int_in_range] yields identical output
    across systems with varying [int] sizes.

    @raise Invalid_argument if [min > max].

    @since 5.2 *)

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.

    @raise Invalid_argument if [bound] <= 0.
*)

val int32_in_range : min:int32 -> max:int32 -> int32
(** [Random.int32_in_range ~min ~max] returns a random integer
    between [min] (inclusive) and [max] (inclusive).
    Both [min] and [max] are allowed to be negative;
    [min] must be less than or equal to [max].

    @raise Invalid_argument if [min > max].

    @since 5.2 *)

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.

    @raise Invalid_argument if [bound] <= 0.
*)

val nativeint_in_range : min:nativeint -> max:nativeint -> nativeint
(** [Random.nativeint_in_range ~min ~max] returns a random integer
    between [min] (inclusive) and [max] (inclusive).
    Both [min] and [max] are allowed to be negative;
    [min] must be less than or equal to [max].

    @raise Invalid_argument if [min > max].

    @since 5.2 *)

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.

    @raise Invalid_argument if [bound] <= 0.
*)

val int64_in_range : min:int64 -> max:int64 -> int64
(** [Random.int64_in_range ~min ~max] returns a random integer
    between [min] (inclusive) and [max] (inclusive).
    Both [min] and [max] are allowed to be negative;
    [min] must be less than or equal to [max].

    @raise Invalid_argument if [min > max].

    @since 5.2 *)

val float : float -> float
(** [Random.float 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. *)

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 *)

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 *)

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 *)

(** {1 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 : sig
  type t
  (** The type of PRNG states. *)

  val make : int array -> t
  (** Create a new state and initialize it with the given seed. *)

  val make_self_init : unit -> t
  (** Create a new state and initialize it with a random seed chosen
      in a system-dependent way.
      The seed is obtained as described in {!Random.self_init}. *)

  val copy : t -> t
  (** Return a copy of the given state. *)

  val bits : t -> int
  val int : t -> int -> int
  val full_int : t -> int -> int
  val int_in_range : t -> min:int -> max:int -> int
  val int32 : t -> Int32.t -> Int32.t
  val int32_in_range : t -> min:int32 -> max:int32 -> int32
  val nativeint : t -> Nativeint.t -> Nativeint.t
  val nativeint_in_range : t -> min:nativeint -> max:nativeint -> nativeint
  val int64 : t -> Int64.t -> Int64.t
  val int64_in_range : t -> min:int64 -> max:int64 -> int64
  val float : t -> float -> float
  val bool : t -> bool
  val bits32 : t -> Int32.t
  val bits64 : t -> Int64.t
  val nativebits : t -> Nativeint.t
  (** These functions are the same as the basic functions, except that they
      use (and update) the given PRNG state instead of the default one.
  *)

  val split : t -> t
  (** Draw a fresh PRNG state from the given PRNG state.
      (The given PRNG state is modified.)
      The new PRNG is statistically independent from the given PRNG.
      Data can be drawn from both PRNGs, in any order, without risk of
      correlation.  Both PRNGs can be split later, arbitrarily many times.
      @since 5.0 *)

  val to_binary_string : t -> string
  (** Serializes the PRNG state into an immutable sequence of bytes.
      See {!of_binary_string} for deserialization.

      The [string] type is intended here for serialization only, the
      encoding is not human-readable and may not be printable.

      Note that the serialization format may differ across OCaml
      versions.

      @since 5.1
  *)

  val of_binary_string : string -> t
  (** Deserializes a byte sequence obtained by calling
      {!to_binary_string}. The resulting PRNG state will produce the
      same random numbers as the state that was passed as input to
      {!to_binary_string}.

      @raise Failure if the input is not in the expected format.

      Note that the serialization format may differ across OCaml
      versions.

      Unlike the functions provided by the {!Marshal} module, this
      function either produces a valid state or fails cleanly with
      a [Failure] exception. It can be safely used on user-provided,
      untrusted inputs.

      @since 5.1
  *)
end

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

val split : unit -> State.t
(** Draw a fresh PRNG state from the current state of the domain-local
    generator used by the default functions.
    (The state of the domain-local generator is modified.)
    See {!Random.State.split}.
    @since 5.0 *)