Random Numbers

Random is the abstract base class for all random generators. See Random API Overview for generator selection and Working with Random Values for common value helpers. SecureRandom::isSecure() returns true, so inherited buildString(), buildByteBuffer(), and buildByteBlock() select sensitive storage before generated data is written. Non-secure generators return ordinary strings and byte storage through the same APIs.

Interface

class FastRandom : public erbsland::random::Random 

A fast pseudo-random generator for non-security use.

See: Random API Overview

Public Functions

FastRandom(): Create a generator with automatic seed data.

explicit FastRandom(uint64_t seed): Create a generator with an explicit seed for reproducible sequences.

virtual int32_t getInt32(int32_t minimum, int32_t maximum) override

Generate a random 32-bit signed integer in the inclusive range.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

virtual uint32_t getUInt32(uint32_t minimum, uint32_t maximum) override

Generate a random 32-bit unsigned integer in the inclusive range.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

virtual int64_t getInt64(int64_t minimum, int64_t maximum) override

Generate a random 64-bit signed integer in the inclusive range.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

virtual uint64_t getUInt64(uint64_t minimum, uint64_t maximum) override

Generate a random 64-bit unsigned integer in the inclusive range.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

virtual double getDouble(double minimum, double maximum) override

Generate a random floating-point value.

Parameters:

minimum – The lower bound. Reversed bounds are ordered automatically.
maximum – The upper bound. Reversed bounds are ordered automatically.

Returns:

A random floating-point value in the range supported by the generator.

virtual bool getBool() override

Generate a random boolean value.

Returns:: A random boolean value.

virtual void fillBytes(std::span<std::byte> destination) override

Fill the destination with random bytes.

Parameters:: destination – The byte span to fill. An empty span is accepted.

class Random

The common interface for random number generators.

See: Random API Overview

Subclassed by erbsland::random::FastRandom, erbsland::random::SecureRandom, erbsland::random::ThreadSafeFastRandom

Public Functions

virtual ~Random() = default: Destroy this random generator.

template<math::NativeInteger T> T selectInteger(T minimum, T maximum)

Create a random native integer in the inclusive range.

Template Parameters:

T – The native integer result type.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

template<math::NativeInteger T> T selectInteger(math::IntegerRange<T> range)

Create a random native integer in the inclusive range.

Template Parameters:: T – The native integer result type.
Parameters:: range – The inclusive integer range.
Returns:: A random integer in the inclusive range.

template<math::NativeInteger T> util::List<T> buildIntegerList(unit::ItemCount count, T minimum, T maximum)

Create a list of random native integers.

Template Parameters:

T – The native integer result type.

Parameters:

count – The number of values to build. Zero or infinite counts return an empty list.
minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A list with count random integers, or an empty list.

text::String buildString(unit::CpLength length, const text::CharSet &characters)

Create a random UTF-8 string with characters from the given set.

Parameters:

length – The number of Unicode code points to build. Zero or infinite lengths return an empty string.
characters – The character choices. An empty set returns an empty string.

Throws:

err::OutOfRangeError – If the length exceeds the maximum possible value.

Returns:

A random UTF-8 string, or an empty string.

mem::ByteBlock buildByteBlock(unit::ByteLength length)

Create a block of random bytes.

Parameters:: length – The number of bytes to build. Zero or infinite lengths return an empty block.
Returns:: A block with random bytes, or an empty block.

mem::ByteBuffer buildByteBuffer(unit::ByteLength length)

Create a deep-copying buffer of random bytes.

Parameters:: length – The number of bytes to build. Zero or infinite lengths return an empty buffer. Secure generators return a buffer with sensitive mode enabled.
Returns:: A buffer with random bytes, or an empty buffer.

unit::ItemIndex selectIndex(unit::ItemCount count)

Select a valid element index for a container with count elements.

Parameters:: count – The number of available elements.
Returns:: A random index in [0, count), or ItemIndex::noIndex() for zero or infinite counts.

template<typename T> T selectElement(std::span<const T> choices, const T &valueIfEmpty = {})

Select one random element from the given choices.

Template Parameters:

T – The element type.

Parameters:

choices – The available choices. Must not be empty unless valueIfEmpty shall be returned.
valueIfEmpty – The fallback value to return when choices is empty.

Returns:

A selected element, or valueIfEmpty for empty choices.

template<typename T> T selectElement(const std::vector<T> &choices, const T &valueIfEmpty = {})

Select one random element from the given choices.

Template Parameters:

T – The element type.

Parameters:

choices – The available choices. Must not be empty unless valueIfEmpty shall be returned.
valueIfEmpty – The fallback value to return when choices is empty.

Returns:

A selected element, or valueIfEmpty for empty choices.

template<typename T> T selectElement(std::initializer_list<T> choices, const T &valueIfEmpty = {})

Select one random element from the given choices.

Template Parameters:

T – The element type.

Parameters:

choices – The available choices. Must not be empty unless valueIfEmpty shall be returned.
valueIfEmpty – The fallback value to return when choices is empty.

Returns:

A selected element, or valueIfEmpty for empty choices.

template<typename T, typename Self> T selectElement(const util::List<T, Self> &choices, const T &valueIfEmpty = {})

Select one random element from the given choices.

Template Parameters:

T – The element type.
Self – The list CRTP type.

Parameters:

choices – The available choices. Must not be empty unless valueIfEmpty shall be returned.
valueIfEmpty – The fallback value to return when choices is empty.

Returns:

A selected element, or valueIfEmpty for empty choices.

template<typename T, typename Compare, typename Self> T selectElement(const util::Set<T, Compare, Self> &choices, const T &valueIfEmpty = {})

Select one random element from the given choices.

Template Parameters:

T – The element type.
Compare – The ordered-set comparison type.
Self – The ordered-set CRTP type.

Parameters:

choices – The available choices. Must not be empty unless valueIfEmpty shall be returned.
valueIfEmpty – The fallback value to return when choices is empty.

Returns:

A selected element, or valueIfEmpty for empty choices.

template<typename T, typename Hash, typename Equal, typename Self> T selectElement(const util::HashSet<T, Hash, Equal, Self> &choices, const T &valueIfEmpty = {})

Select one random element from the given choices.

Template Parameters:

T – The element type.
Hash – The hash-set hash type.
Equal – The hash-set equality type.
Self – The hash-set CRTP type.

Parameters:

choices – The available choices. Must not be empty unless valueIfEmpty shall be returned.
valueIfEmpty – The fallback value to return when choices is empty.

Returns:

A selected element, or valueIfEmpty for empty choices.

template<typename T> util::List<T> buildElementList(unit::ItemCount count, std::span<const T> choices)

Build a list by sampling elements with replacement.

Template Parameters:

T – The element type.

Parameters:

count – The number of elements to build. Zero or infinite counts return an empty list.
choices – The choices to sample from. Empty choices return an empty list.

Returns:

A list with sampled elements, or an empty list.

template<typename T, typename Self> util::List<T, Self>::Self buildElementList(unit::ItemCount count, const util::List<T, Self> &choices)

Build a list by sampling elements with replacement.

Template Parameters:

T – The element type.
Self – The list CRTP type.

Parameters:

count – The number of elements to build. Zero or infinite counts return an empty list.
choices – The choices to sample from. Empty choices return an empty list.

Returns:

A matching list with sampled elements, or an empty list.

template<typename T, typename Compare, typename Self> util::List<T> buildElementList(unit::ItemCount count, const util::Set<T, Compare, Self> &choices)

Build a list by sampling elements with replacement.

Template Parameters:

T – The element type.
Compare – The ordered-set comparison type.
Self – The ordered-set CRTP type.

Parameters:

count – The number of elements to build. Zero or infinite counts return an empty list.
choices – The choices to sample from. Empty choices return an empty list.

Returns:

A list with sampled elements, or an empty list.

template<typename T, typename Hash, typename Equal, typename Self> util::List<T> buildElementList(unit::ItemCount count, const util::HashSet<T, Hash, Equal, Self> &choices)

Build a list by sampling elements with replacement.

Template Parameters:

T – The element type.
Hash – The hash-set hash type.
Equal – The hash-set equality type.
Self – The hash-set CRTP type.

Parameters:

count – The number of elements to build. Zero or infinite counts return an empty list.
choices – The choices to sample from. Empty choices return an empty list.

Returns:

A list with sampled elements, or an empty list.

template<typename T> util::List<T> buildUniqueElementList(unit::ItemCount count, std::span<const T> choices)

Build a list by sampling elements without replacement.

Template Parameters:

T – The element type.

Parameters:

count – The number of elements to build. Zero or infinite counts return an empty list.
choices – The choices to sample from. Empty choices return an empty list.

Returns:

A list with unique sampled elements. The list is capped to the number of choices.

template<typename T, typename Self> util::List<T, Self>::Self buildUniqueElementList(unit::ItemCount count, const util::List<T, Self> &choices)

Build a list by sampling elements without replacement.

Template Parameters:

T – The element type.
Self – The list CRTP type.

Parameters:

count – The number of elements to build. Zero or infinite counts return an empty list.
choices – The choices to sample from. Empty choices return an empty list.

Returns:

A matching list with unique sampled elements. The list is capped to the number of choices.

template<typename T, typename Compare, typename Self> util::List<T> buildUniqueElementList(unit::ItemCount count, const util::Set<T, Compare, Self> &choices)

Build a list by sampling elements without replacement.

Template Parameters:

T – The element type.
Compare – The ordered-set comparison type.
Self – The ordered-set CRTP type.

Parameters:

count – The number of elements to build. Zero or infinite counts return an empty list.
choices – The choices to sample from. Empty choices return an empty list.

Returns:

A list with unique sampled elements. The list is capped to the number of choices.

template<typename T, typename Hash, typename Equal, typename Self> util::List<T> buildUniqueElementList(unit::ItemCount count, const util::HashSet<T, Hash, Equal, Self> &choices)

Build a list by sampling elements without replacement.

Template Parameters:

T – The element type.
Hash – The hash-set hash type.
Equal – The hash-set equality type.
Self – The hash-set CRTP type.

Parameters:

count – The number of elements to build. Zero or infinite counts return an empty list.
choices – The choices to sample from. Empty choices return an empty list.

Returns:

A list with unique sampled elements. The list is capped to the number of choices.

template<typename T> void shuffle(std::span<T> values)

Shuffle a random-access span in place.

Template Parameters:: T – The element type.
Parameters:: values – The values to shuffle. Empty and single-element spans are unchanged.

template<typename T> void shuffle(std::vector<T> &values)

Shuffle a vector in place.

Template Parameters:: T – The element type.
Parameters:: values – The values to shuffle. Empty and single-element vectors are unchanged.

template<typename T, typename Self> void shuffle(util::List<T, Self> &values)

Shuffle a list in place.

Template Parameters:

T – The element type.
Self – The list CRTP type.

Parameters:

values – The values to shuffle. Empty and single-element lists are unchanged.

inline virtual bool isSecure() const noexcept

Test if this generator is suitable for security-sensitive random data.

Secure generators automatically mark byte blocks created by buildByteBlock() as sensitive.

virtual int32_t getInt32(int32_t minimum, int32_t maximum) = 0

Generate a random 32-bit signed integer in the inclusive range.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

virtual uint32_t getUInt32(uint32_t minimum, uint32_t maximum) = 0

Generate a random 32-bit unsigned integer in the inclusive range.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

virtual int64_t getInt64(int64_t minimum, int64_t maximum) = 0

Generate a random 64-bit signed integer in the inclusive range.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

virtual uint64_t getUInt64(uint64_t minimum, uint64_t maximum) = 0

Generate a random 64-bit unsigned integer in the inclusive range.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

virtual double getDouble(double minimum, double maximum) = 0

Generate a random floating-point value.

Parameters:

minimum – The lower bound. Reversed bounds are ordered automatically.
maximum – The upper bound. Reversed bounds are ordered automatically.

Returns:

A random floating-point value in the range supported by the generator.

virtual bool getBool() = 0

Generate a random boolean value.

Returns:: A random boolean value.

virtual void fillBytes(std::span<std::byte> destination) = 0

Fill the destination with random bytes.

Parameters:: destination – The byte span to fill. An empty span is accepted.

class RandomError : public erbsland::err::LogicError 

A random number generation error.

These exceptions are thrown when a random source cannot provide the requested data.

Public Functions

inline explicit RandomError(text::String reason) noexcept

Create a random error with a reason.

Parameters:: reason – The reason for the random error.

inline explicit RandomError(text::String reason, std::exception_ptr cause) noexcept

Create a random error with a reason and diagnostic cause.

Parameters:

reason – The reason for the random error.
cause – The diagnostic cause.

inline explicit RandomError(const std::string_view reason) noexcept: This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

inline explicit RandomError(const std::string_view reason, std::exception_ptr cause) noexcept: This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

class SecureRandom : public erbsland::random::Random 

A cryptographic random generator backed by the operating system entropy source.

Every method that draws random data throws random::RandomError if the system entropy source cannot provide data.

See: Secure Randomness

Public Functions

SecureRandom(): Create a secure generator using the system entropy source.

inline virtual bool isSecure() const noexcept override

Test if this generator is suitable for security-sensitive random data.

Secure generators automatically mark byte blocks created by buildByteBlock() as sensitive.

virtual int32_t getInt32(int32_t minimum, int32_t maximum) override

Generate a random 32-bit signed integer in the inclusive range.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

virtual uint32_t getUInt32(uint32_t minimum, uint32_t maximum) override

Generate a random 32-bit unsigned integer in the inclusive range.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

virtual int64_t getInt64(int64_t minimum, int64_t maximum) override

Generate a random 64-bit signed integer in the inclusive range.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

virtual uint64_t getUInt64(uint64_t minimum, uint64_t maximum) override

Generate a random 64-bit unsigned integer in the inclusive range.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

virtual double getDouble(double minimum, double maximum) override

Generate a random floating-point value.

Parameters:

minimum – The lower bound. Reversed bounds are ordered automatically.
maximum – The upper bound. Reversed bounds are ordered automatically.

Returns:

A random floating-point value in the range supported by the generator.

virtual bool getBool() override

Generate a random boolean value.

Returns:: A random boolean value.

virtual void fillBytes(std::span<std::byte> destination) override

Fill the destination with random bytes.

Parameters:: destination – The byte span to fill. An empty span is accepted.

class ThreadSafeFastRandom : public erbsland::random::Random 

A thread-safe fast pseudo-random generator for shared non-security use.

See: Random API Overview

Public Functions

ThreadSafeFastRandom(): Create a generator with automatic seed data.

explicit ThreadSafeFastRandom(uint64_t seed): Create a generator with an explicit seed for reproducible sequences.

virtual int32_t getInt32(int32_t minimum, int32_t maximum) override

Generate a random 32-bit signed integer in the inclusive range.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

virtual uint32_t getUInt32(uint32_t minimum, uint32_t maximum) override

Generate a random 32-bit unsigned integer in the inclusive range.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

virtual int64_t getInt64(int64_t minimum, int64_t maximum) override

Generate a random 64-bit signed integer in the inclusive range.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

virtual uint64_t getUInt64(uint64_t minimum, uint64_t maximum) override

Generate a random 64-bit unsigned integer in the inclusive range.

Parameters:

minimum – The lower inclusive bound. Reversed bounds are ordered automatically.
maximum – The upper inclusive bound. Reversed bounds are ordered automatically.

Returns:

A random integer in the inclusive range [minimum, maximum].

virtual double getDouble(double minimum, double maximum) override

Generate a random floating-point value.

Parameters:

minimum – The lower bound. Reversed bounds are ordered automatically.
maximum – The upper bound. Reversed bounds are ordered automatically.

Returns:

A random floating-point value in the range supported by the generator.

virtual bool getBool() override

Generate a random boolean value.

Returns:: A random boolean value.

virtual void fillBytes(std::span<std::byte> destination) override

Fill the destination with random bytes.

Parameters:: destination – The byte span to fill. An empty span is accepted.