std::generate_canonical
| Defined in header <random>
|
||
template< class RealType, std::size_t Bits, class Generator >
RealType generate_canonical( Generator& g );
|
(since C++11) | |
Generates a random floating point number in range [0, 1).
To generate enough entropy, generate_canonical() will call g() exactly k times, where k = max(1, ⌈ b / log2 R ⌉) and
b = std::min(Bits, std::size_t {std::numeric_limits<RealType>::digits}),R = g.max() - g.min() + 1.
Parameters
| g | - | generator to use to acquire entropy |
Return value
Floating point value in range [0, 1).
Exceptions
None except from those thrown by g.
Notes
Some existing implementations have a bug where they may occasionally return 1.0 if RealType is float GCC #63176 LLVM #18767 MSVC STL #1074. This is LWG issue 2524. Some implementations have avoided returning exactly 1.0 by subtracting a small value, infinitesimally skewing the statistical uniformity. The current Standard requirement is that when the random bits obtained would yield exactly 1.0, another whole round must be performed.
The specification provides no default for the number-of-bits argument, and the exact value for maximum precision is the unwieldy (e.g.) std::numeric_limits<double>::digits. For almost all uses, the best choice is -1u, with the same result.
For cases where the resulting value is close to zero, the Standard prescribes that only a fraction of the bits of entropy obtained should go into the result. The effect is that if all values generated less than, say, 0.001 are placed in a bucket, the number of different values that may appear would be many fewer than could be represented. Most implementations instead preserve as much of the obtained entropy as can be represented in the result.
Example
Produce random numbers with maximum randomness.
#include <iostream>
#include <random>
int main()
{
std::random_device rd;
std::mt19937 gen(rd());
for (int n = 0; n < 10; ++n)
std::cout << std::generate_canonical<double, -1u>(gen) << ' ';
std::cout << '\n';
}
Possible output:
0.208143 0.824147 0.0278604 0.343183 0.0173263 0.864057 0.647037 0.539467 0.0583497 0.609219
See also
(C++11) |
produces real values evenly distributed across a range (class template) |
