hap.random is a random number generation library for the D programming language. It is intended as a replacement for Phobos’ std.random, and addresses a number of issues encountered in that module: in particular, hap.random implements random number generators and related entities as reference types rather than value types, which avoids a number of problems that can arise with the standard library RNGs. It is however largely derivative of std.random and to the greatest extent possible implements the same API, with some functional additions, notably the random distribution ranges.

The library name, hap, is Welsh for “random” or “chance”. :-)

The functionality implemented by this package is divided into four different groups:

• random number generators, deterministic pseudo-random algorithms;
• random distributions;
• random adaptors, such as shuffling or sampling objects;
• traits related to random number generation.

The hap.random package will import all of the above functionality. Alternatively, individual modules can be imported as required.

Experimental functionality, not fully developed but available as a technology preview, includes:

• random devices, non-deterministic sources of randomness.

This functionality will not be imported as part of the main hap.random package but can be imported via the individual modules. It should be used with some caution, as its API may change significantly in future releases.

Migration:
To use hap.random instead of std.random it should suffice to:

• replace import std.random with import hap.random
• insert new before every instantiation of an RNG. For example, instead of auto rng = Random(unpredictableSeed) put instead, auto rng = new Random(unpredictableSeed).
• optionally, the functions randomCover, randomSample and randomShuffle may be replaced by cover, sample and shuffle; however, this is optional, not required.

Note:
Currently only one function is known to produce different behaviour to its std.random counterpart: hap.random.distribution.dice uses a different algorithm to std.random.dice.

Warning:
Bear in mind that non-reference-type RNGs used in conjunction with this package will almost certainly generate erroneous results. In particular this package should not be used together with std.random itself.

License:
Boost License 1.0.

Authors:
Andrei Alexandrescu, Chris Cain, Andrej Mitrović, Masahiro Nakagawa, Joseph Rushton Wakeling

Source:
hap/random/package.d