Random Numbers
==============

This package also provides an implementation of the Common Lisp random
number generator.  It uses its own additive-congruential algorithm,
which is much more likely to give statistically clean random numbers
than the simple generators supplied by many operating systems.

 - Function: random* number &optional state
     This function returns a random nonnegative number less than
     NUMBER, and of the same type (either integer or floating-point).
     The STATE argument should be a `random-state' object which holds
     the state of the random number generator.  The function modifies
     this state object as a side effect.  If STATE is omitted, it
     defaults to the variable `*random-state*', which contains a
     pre-initialized `random-state' object.

 - Variable: *random-state*
     This variable contains the system "default" `random-state' object,
     used for calls to `random*' that do not specify an alternative
     state object.  Since any number of programs in the Emacs process
     may be accessing `*random-state*' in interleaved fashion, the
     sequence generated from this variable will be irreproducible for
     all intents and purposes.

 - Function: make-random-state &optional state
     This function creates or copies a `random-state' object.  If STATE
     is omitted or `nil', it returns a new copy of `*random-state*'.
     This is a copy in the sense that future sequences of calls to
     `(random* N)' and `(random* N S)' (where S is the new random-state
     object) will return identical sequences of random numbers.

     If STATE is a `random-state' object, this function returns a copy
     of that object.  If STATE is `t', this function returns a new
     `random-state' object seeded from the date and time.  As an
     extension to Common Lisp, STATE may also be an integer in which
     case the new object is seeded from that integer; each different
     integer seed will result in a completely different sequence of
     random numbers.

     It is legal to print a `random-state' object to a buffer or file
     and later read it back with `read'.  If a program wishes to use a
     sequence of pseudo-random numbers which can be reproduced later
     for debugging, it can call `(make-random-state t)' to get a new
     sequence, then print this sequence to a file.  When the program is
     later rerun, it can read the original run's random-state from the
     file.

 - Function: random-state-p object
     This predicate returns `t' if OBJECT is a `random-state' object,
     or `nil' otherwise.