Re: Random Doc improvement

[Neil Jerram]

Stephen Uitti <address@hidden> writes:

> I've been scratching my head over random numbers.
[...]
> It really should say that (random) produces the same
> list of numbers every time, unless a state is
> specified.  And it should have an example showing use.

Thanks for pointing out that we could do with some more explanation
here.  I'm about to commit the addition below, loosely based on your
suggestions.  If you have any further comments, please let me know.

Regards,
        Neil


   Note that the initial value of `*random-state*' is the same every
time Guile starts up.  Therefore, if you don't pass a STATE parameter
to the above procedures, and you don't set `*random-state*' to
`(seed->random-state your-seed)', where `your-seed' is something that
_isn't_ the same every time, you'll get the same sequence of "random"
numbers on every run.

   For example, unless the relevant source code has changed, `(map
random (cdr (iota 30)))', if the first use of random numbers since
Guile started up, will always give:

     (map random (cdr (iota 19)))
     =>
     (0 1 1 2 2 2 1 2 6 7 10 0 5 3 12 5 5 12)

   To use the time of day as the random seed, you can use code like
this:

     (let ((time (gettimeofday)))
       (set! *random-state*
             (seed->random-state (+ (car time)
                                    (cdr time)))))

And then (depending on the time of day, of course):

     (map random (cdr (iota 19)))
     =>
     (0 0 1 0 2 4 5 4 5 5 9 3 10 1 8 3 14 17)

   For security applications, such as password generation, you should
use more bits of seed.  Otherwise an open source password generator
could be attacked by guessing the seed... but that's a subject for
another manual.