CppUtils::Math::DeterministicRandomEngine

Deterministic, constexpr-compatible pseudo-random number generator (SplitMix64).

Description

Provides reproducible pseudo-random generation suitable for unit tests, fuzz testing, and property-based verification. Generates identical sequences across platforms for a given seed.

Related guide

See the Unit test guide section for detailed explanations and usage examples.

Public attributes

static constexpr constexpr auto defaultSeed = 0x123456789ABCDEF0ULL;

Default 64-bit seed used for deterministic pseudo-random initialization.

Public methods

explicit constexpr DeterministicRandomEngine::DeterministicRandomEngine(std::uint64_t seed = defaultSeed) noexcept;

Constructs a deterministic random engine with a given 64-bit seed.

Parameter	Description
seed	Initial seed (defaults to defaultSeed).

[[nodiscard]] constexpr auto DeterministicRandomEngine::seed() const noexcept -> std::uint64_t;

Returns the initial seed configured for this engine.

Returns: 64-bit unsigned integer seed.

constexpr auto DeterministicRandomEngine::nextUint64() noexcept -> std::uint64_t;

Advances the generator state and produces the next raw 64-bit pseudo-random integer.

Returns: Next pseudo-random std::uint64_t.

template <class Type>
constexpr auto DeterministicRandomEngine::random(Type minimum, Type maximum) noexcept -> Type;

Generates a pseudo-random value within the specified range [minimum, maximum].

Deduce the type automatically from parameters or specify it explicitly. Supports integral types, floating-point types, and booleans.

Template parameter	Description
Type	Arithmetic or boolean type.

Parameter	Description
minimum	Lower bound (inclusive).
maximum	Upper bound (inclusive).

Returns: Random value within [minimum, maximum].

template <class Type>
constexpr auto DeterministicRandomEngine::random() noexcept -> Type;

Generates a pseudo-random value of the requested type covering its standard range.

For integral types, covers [std::numeric_limits<Type>::min(), std::numeric_limits<Type>::max()]. For floating-point types, covers [0.0, 1.0]. For bool, returns true or false with a balanced 50% distribution.

Template parameter	Description
Type	Target arithmetic or boolean type.

Returns: Random value of type Type.

template <std::floating_point Float>
constexpr auto DeterministicRandomEngine::randomFloat(Float minimum = static_cast<Float>(0.0), Float maximum = static_cast<Float>(1.0)) noexcept -> Float;

Generates a floating-point number in [minimum, maximum] (defaults: 0.0 to 1.0).

Template parameter	Description
Float	Floating-point type.

Parameter	Description
minimum	Lower bound (inclusive).
maximum	Upper bound (inclusive).

Returns: Random floating-point value.

constexpr auto DeterministicRandomEngine::randomSize(std::size_t minimum, std::size_t maximum) noexcept -> std::size_t;

Generates a pseudo-random size within the specified bounds.

Parameter	Description
minimum	Lower bound (inclusive).
maximum	Upper bound (inclusive).

Returns: Random std::size_t in [minimum, maximum].

constexpr auto DeterministicRandomEngine::randomSize(std::size_t maximum) noexcept -> std::size_t;

Generates a pseudo-random size between 0 and maximum (inclusive).

Parameter	Description
maximum	Upper bound (inclusive).

Returns: Random std::size_t in [0, maximum].

constexpr auto DeterministicRandomEngine::randomSize() noexcept -> std::size_t;

Generates a pseudo-random size bounded by PTRDIFF_MAX.

The generated size is bounded within [0, std::numeric_limits<std::ptrdiff_t>::max()] (PTRDIFF_MAX) instead of SIZE_MAX, ensuring that the size never exceeds the maximum legal contiguous object size in C++, thereby preserving the validity of pointer arithmetic ([expr.add#5]) during memory allocation and container stress testing.

See also: Limitation de la plage de valeurs et borne PTRDIFF_MAX

Returns: Random std::size_t in [0, PTRDIFF_MAX].

constexpr auto DeterministicRandomEngine::randomString( std::size_t minimumLength = 0uz, std::size_t maximumLength = 32uz, std::string_view alphabet = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_ -") -> std::string;

Generates a pseudo-random string of variable length composed of characters from the given alphabet.

Parameter	Description
minimumLength	Minimum number of characters.
maximumLength	Maximum number of characters.
alphabet	View of available characters to sample from.

Returns: Randomly generated std::string.

constexpr auto DeterministicRandomEngine::randomBytes(std::size_t count) -> std::vector<std::byte>;

Allocates and fills a vector of bytes with pseudo-random data.

Parameter	Description
count	Number of bytes to generate.

Returns: Vector of random bytes.

template <std::ranges::random_access_range Range>
constexpr auto DeterministicRandomEngine::pickOne(const Range& collection) -> const auto&;

Picks a pseudo-random element by const reference from a random access range.

Template parameter	Description
Range	Range satisfying std::ranges::random_access_range.

Parameter	Description
collection	Collection to pick an element from.

Returns: Const reference to the randomly selected element.