* Randomizer::nextInt will throw on 32-bit with 64-bit engines
* Document Randomizer::nextInt return value
* Wording
* Apply suggestions from code review
---------
Co-authored-by: Tim Düsterhus <tim@bastelstu.be>
* random: Improve description for random_bytes() / getBytes()
* random: Improve description for random_int()
* random: Reference both bin2hex and base64_encode for random_bytes() / getBytes()
The spaces within a function call have been introduced in
ad458c5f01 and I have been trying to emulate
them, but failed due to muscle memory, resulting in very inconsistently
formatted examples.
Adjust the code examples purely stylistically, without changing their output:
- Remove the extra spaces within the function calls to match the commonly
accepted code style (e.g. PSR-12).
- Use `implode()` instead of the `join()` alias.
- Use comma instead of string concatenation when echo-ing.
- Consistently use "\n" to emit newlines, not `PHP_EOL`.
- Unify to double quotes.
These examples teach the readers bad practices, because they indicate that
seeding from the current time is reasonable (it is not). Users should ideally
use the `random_int()` function. If that is not possible, the
`Random\Randomizer` is the next best choice. If that's not an option either,
then relying on the random seed of the global Mt19937 is better than any manual
seeding that relies on the current time.
This patch reorders the engines in the overview to list the “Secure” engine
first, as that is the preferred engine for the majority of use cases. As a side
effect the CryptoSafeEngine interface is documented right after the Engine
interface.
The other engines remain sorted alphabetically.
* random: Add example for Xoshiro256StarStar::jump()
* random: Fix description of Xoshiro256StarStar::jumpLong()
* random: Add example to Xoshiro256StarStar::jumpLong()
* random: Use static closure in Xoshiro256StarStar::jump() example
Co-authored-by: Go Kudo <zeriyoshi@gmail.com>
It’s impossible to pass an integer that does not fall into the documented
range, making this useless information. Integers outside these ranges will be
converted into floats, making those a TypeError.
* random: Expand random fruit examples
Picking two of three elements and receiving the first two fails to properly
showcase randomness.
* random: Run fruit examples twice
This showcases that the result is actually different when trying again.
* random: Strip duplicated space in examples
