diff options
| author |  Kurtis Rader <krader@skepticism.us> | 2015-12-28 20:31:12 -0800 |
|---|---|---|
| committer |  ridiculousfish <corydoras@ridiculousfish.com> | 2016-01-07 20:54:50 -0800 |
| commit | ef31aa94f8673482fca3e23e4ea0e88c60014526 (patch) | |
| tree | 87459a8bce0f1b51337028608031f671539559b8 /doc_src | |
| parent | bc3260402ad26664f704734c6b7168b4c647e970 (diff) | |
clarify the documentation of builtin random
The random builtin command may or may not produce values with a truly
random distribution. So make the documentation reflect that reality. Also,
make the command consistent with similar shells (e.g., bash, zsh) which
produce a range of [0..32767].
Resolves issue #1272.
Diffstat (limited to 'doc_src')
| -rw-r--r-- | doc_src/random.txt | 16 |
1 files changed, 13 insertions, 3 deletions
diff --git a/doc_src/random.txt b/doc_src/random.txt index 5e50232a..24b7b545 100644 --- a/doc_src/random.txt +++ b/doc_src/random.txt @@ -7,9 +7,19 @@ random [SEED] \subsection random-description Description -`random` outputs a random number from 0 to 32766, inclusive. - -If a `SEED` value is provided, it is used to seed the random number generator, and no output will be produced. This can be useful for debugging purposes, where it can be desirable to get the same random number sequence multiple times. If the random number generator is called without first seeding it, the current time will be used as the seed. +`random` outputs a psuedo-random number from 0 to 32767, inclusive. +Even ignoring the very narrow range of values you should not assume +this produces truly random values within that range. Do not use the +value for any cryptographic purposes. Even if you're using it to, for +example, generate unique identifiers you should be careful about handling +collisions; i.e., the same random number appearing more than once in a +given fish instance. + +If a `SEED` value is provided, it is used to seed the random number +generator, and no output will be produced. This can be useful for debugging +purposes, where it can be desirable to get the same random number sequence +multiple times. If the random number generator is called without first +seeding it, the current time will be used as the seed. \subsection random-example Example |