New/revised features for vlib/rand

[j-bm]

Describe the feature

Some issues with the current rand implementations (I believe these require a bit of discussion and agreement before submitting PRs. hence this Feature Request. The resulting PRs should be fairly simple.)

1. The float/double values are converted according to an undocumented method (of course I can read the code, but I would prefer not to. See 2.) and vlib rand.f32 returns 1.000000 but shouldn't #16707
2. The double values are variable precision. When converting a u64 to double, some random u64 values have leading zero bits and when there are enough of them a conversion to double results in loss of precision. The usual fix in other libraries is (a) count leading zeros (b) adjust the resulting exponent accordingly and (c) if you run out of remaining bits, fetch another u64 random value and shift into place. How about a different f64() such as f64cp() (constant precision) which includes this?
3. rand currently uses the buffer mechanism, which I am guessing is based on an assumption that the consumers will use a mix of u8/u16/f32/f64 etc. The buffer then maximizes utilization of the random generation process. However, random number generation in numerical work is almost 100% the same thing: a constant consumption of the same kind of values (f64 for example). How about an alternative implementation or API that avoids the buffer?
4. Some PRNGs need additional documentation and guidance, e.g. insufficiently large and random seeds could result in a long sequence of not-very-random values. A test of seeds (are they at least 40% ones?) could be added as an optional function.
5. Consider removing some PRNGs, e.g. mt19937 or provide caveats on their use

Use Case

Using pseudo-random number generators is often accompanied by a steep learning curve by users. We should be providing very clear feature options (buffer/nonbuffer, variable precision, guidance on seeds, etc) to help new and experienced users with the features available.

There's a line to be drawn of course: V docs and code are not a training course but V docs and examples should be carefully constructed to provide the guard-rails for the user.

Proposed Solution

PRs for these code items (if commenters think it is OK):

• add text describing conversions to f32/f64
• add code for the constant precision f64 call
• add examples showing effects of good/bad seeds, especially for the mt19937 mersenne twister

Other Information

No response

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

Version used

V 0.3.2 d7c244e

Environment details (OS name and version, etc.)

OpenBSD current version