(doc-group random
  «Random numbers generation.»)

(defdoc *random-state*
  «The random state of the current process.

   The state isn't set (is `NIL`) until a call is made to any function
   that uses it.»
  :doc-group random
  :doc-see make-random-state
  :doc-see random-state?)

(defdoc (make-random-state (state NIL))
  «Return a new random state.

   If `state` is `NIL`, a copy of the random state of the current process
   (`*random-state*`) is returned. If `state` is `T`, the returned random
   state is a new one that has been randomly initialized. If an already
   existing random state is passed, the returned value is a copy of that
   state.»
  :doc-group random
  :doc-see *random-state*
  :doc-see random-state?
  :doc-see random)

(defdoc (random-state? state)
  «Return `T` if the argument is a random state object, `NIL` otherwise.»
  :doc-example
  «(random-state? 1)
   ; ↳ NIL»
  :doc-example
  «(random-state? (make-random-state))
   ; ↳ T»
  :doc-example
  «(random-state? *random-state*)
   ; ↳ T»
  :doc-group random
  :doc-see *random-state*
  :doc-see make-random-state)

(defdoc (random max (state NIL))
  «Return a random number in the range `[0, max]` (inclusive).

   The result is either an integer or a floating point number, depending
   on the type of the `max` argument, which has to be a positive number.

   Optional `state` can be specified, otherwise the random state of the
   current process (`*random-state*`) is used. State will be modified
   in-place.»
  :doc-example
  «(random 1)
   ; ↳ 1»
  :doc-example
  «(random 10000000000000000000000000000000000)
   ; ↳ 5312781302474765749507273681609477»
  :doc-example
  «(random 1.0)
   ; ↳ 0.69517»
  :doc-group random
  :doc-see make-random-state)