Random

Random number generation, and other random value generation functions. More...

Topics
	Dice Operators
	Integral UDLs for dice throwing; for example, 3_d10 will return a random result of throwing three 10-sided dice.
	Geometry
	Sequences
	Functions that return the next or specific value in a random (known) sequence.

Classes
struct	ghassanpl::random::good_random_engine
	A good quality random engine that meets the standard library concept of a random bit generator. More...

Functions
template<typename INTEGER = uint64_t, typename RANDOM = std::default_random_engine>
constexpr INTEGER	ghassanpl::random::integer (RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns a random integer of the given type.
template<typename REAL = double, typename RANDOM = std::default_random_engine>
REAL	ghassanpl::random::percentage (RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns a random value between 0 and 1 of the given floating-point type.
template<typename REAL = double, typename RANDOM = std::default_random_engine>
REAL	ghassanpl::random::normal (RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns a random value of the given floating-point type in a normal distribution.
template<typename RANDOM = std::default_random_engine>
uint64_t	ghassanpl::random::dice (uint64_t n_sided, RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns the result of throwing an n_sided die (1-N).
template<typename RANDOM = std::default_random_engine>
uint64_t	ghassanpl::random::dice (uint64_t n_dice, uint64_t n_sided, RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns the result of throwing n_dice number of n_sided dice.
template<uint64_t N_SIDED, typename RANDOM = std::default_random_engine>
uint64_t	ghassanpl::random::dice (RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns the result of throwing an N_SIDED die (1-N).
template<uint64_t N_DICE, uint64_t N_SIDED, typename RANDOM = std::default_random_engine>
uint64_t	ghassanpl::random::dice (RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns the result of throwing N_DICE number of N_SIDED dice.
template<typename RANDOM = std::default_random_engine>
bool	ghassanpl::random::coin (RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns true or false randomly.
template<typename RANDOM = std::default_random_engine, std::integral T>
T	ghassanpl::random::in_integer_range (T from, T to, RANDOM &rng=::ghassanpl::random::default_random_engine)
template<typename RANDOM = std::default_random_engine, std::integral T>
T	ghassanpl::random::in_integer_range (T to, RANDOM &rng=::ghassanpl::random::default_random_engine)
template<typename RANDOM = std::default_random_engine, std::floating_point T>
T	ghassanpl::random::in_real_range (T from, T to, RANDOM &rng=::ghassanpl::random::default_random_engine)
template<typename RANDOM = std::default_random_engine, std::floating_point T>
T	ghassanpl::random::in_real_range (T to, RANDOM &rng=::ghassanpl::random::default_random_engine)
template<typename RANDOM = std::default_random_engine, typename T>
auto	ghassanpl::random::in_range (T from, T to, RANDOM &rng=::ghassanpl::random::default_random_engine)
template<typename T = float>
constexpr T	ghassanpl::random::halton_sequence (size_t index, size_t base=2)
template<typename RANDOM = std::default_random_engine>
bool	ghassanpl::random::with_probability (double probability, RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns true with the given 0-1 probability, false otherwise.
template<typename RANDOM = std::default_random_engine>
bool	ghassanpl::random::with_probability (double probability, double &result, RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns true with the given 0-1 probability, false otherwise; stores the result of the 0-1 "roll" in result.
template<typename RANDOM = std::default_random_engine>
bool	ghassanpl::random::one_in (size_t n, RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns true with a one-in-n chance.
template<typename RANDOM = std::default_random_engine, typename T>
void	ghassanpl::random::shuffle (T &cont, RANDOM &rng=::ghassanpl::random::default_random_engine)
	Shuffles the cont container (as if by std::shuffle).
template<typename RANDOM = std::default_random_engine, typename T>
auto	ghassanpl::random::iterator (T &cont, RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns an iterator to a random element in cont.
template<typename RANDOM = std::default_random_engine, typename T, typename PRED>
auto	ghassanpl::random::iterator_if (T &cont, PRED &&pred, RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns an iterator to a random element in cont that matches pred.
template<typename RANDOM = std::default_random_engine, typename T>
auto	ghassanpl::random::index (T &cont, RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns an index of a random element in cont.
template<typename RANDOM = std::default_random_engine, typename T, typename PRED>
auto	ghassanpl::random::index_if (T &cont, PRED &&pred, RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns an index of a random element in cont that matches pred.
template<typename RANDOM = std::default_random_engine, typename T>
auto *	ghassanpl::random::element (T &cont, RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns an pointer to a random element in cont.
template<typename RANDOM = std::default_random_engine, typename T, typename PRED>
auto *	ghassanpl::random::element_if (T &cont, PRED &&pred, RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns an pointer to a random element in cont that matches pred.
template<typename... T>
auto	ghassanpl::random::one_of (T &&... values)
	Returns one of its arguments at random.
template<typename RANDOM = std::default_random_engine, typename T>
auto	ghassanpl::random::one_of (std::initializer_list< T > values, RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns one of the values in values at random.
template<typename RANDOM = std::default_random_engine, typename T>
auto	ghassanpl::random::make_bag_randomizer (T &container, RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns an object that represents a random "bag" of iterators to objects in container.
template<typename T, typename RANDOM>
size_t	ghassanpl::random::option_with_probability (span< T const > option_probabilities, RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns an index of one of the options in option_probabilities, where its elements are the probability weights of their specific options.
template<typename RANGE, typename FUNC, typename RANDOM>
auto	ghassanpl::random::iterator_with_probability (RANGE &&range, FUNC &&prob_func, RANDOM &rng=::ghassanpl::random::default_random_engine)
	Returns an iterator to a random object in range, with the probability weights of an object being chosen given by prob_func(obj).

Variables
std::default_random_engine	ghassanpl::random::default_random_engine
	A thread-local random engine used by default by all random functions.

Detailed Description

Random number generation, and other random value generation functions.

Most of the random functions take, as their last argument, a random engine to use, but they are all defaulted to use the thread local default_random_engine variable.

Function Documentation

coin()

template<typename RANDOM = std::default_random_engine>

bool ghassanpl::random::coin ( RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns true or false randomly.

Definition at line 141 of file random.h.

dice() [1/4]

template<uint64_t N_DICE, uint64_t N_SIDED, typename RANDOM = std::default_random_engine>

uint64_t ghassanpl::random::dice ( RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns the result of throwing N_DICE number of N_SIDED dice.

Definition at line 128 of file random.h.

dice() [2/4]

template<uint64_t N_SIDED, typename RANDOM = std::default_random_engine>

uint64_t ghassanpl::random::dice ( RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns the result of throwing an N_SIDED die (1-N).

Definition at line 119 of file random.h.

dice() [3/4]

template<typename RANDOM = std::default_random_engine>

uint64_t ghassanpl::random::dice ( uint64_t n_dice, uint64_t n_sided, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns the result of throwing n_dice number of n_sided dice.

Definition at line 107 of file random.h.

dice() [4/4]

template<typename RANDOM = std::default_random_engine>

uint64_t ghassanpl::random::dice ( uint64_t n_sided, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns the result of throwing an n_sided die (1-N).

Definition at line 98 of file random.h.

element()

template<typename RANDOM = std::default_random_engine, typename T>

auto * ghassanpl::random::element ( T & cont, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns an pointer to a random element in cont.

Definition at line 345 of file random.h.

element_if()

template<typename RANDOM = std::default_random_engine, typename T, typename PRED>

auto * ghassanpl::random::element_if ( T & cont, PRED && pred, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns an pointer to a random element in cont that matches pred.

Definition at line 354 of file random.h.

halton_sequence()

template<typename T = float>

T ghassanpl::random::halton_sequence ( size_t index, size_t base = 2 )

nodiscardconstexpr

Definition at line 250 of file random.h.

in_integer_range() [1/2]

template<typename RANDOM = std::default_random_engine, std::integral T>

T ghassanpl::random::in_integer_range ( T from, T to, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Definition at line 167 of file random.h.

in_integer_range() [2/2]

template<typename RANDOM = std::default_random_engine, std::integral T>

T ghassanpl::random::in_integer_range ( T to, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Definition at line 176 of file random.h.

in_range()

template<typename RANDOM = std::default_random_engine, typename T>

auto ghassanpl::random::in_range ( T from, T to, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Definition at line 197 of file random.h.

in_real_range() [1/2]

template<typename RANDOM = std::default_random_engine, std::floating_point T>

T ghassanpl::random::in_real_range ( T from, T to, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Definition at line 182 of file random.h.

in_real_range() [2/2]

template<typename RANDOM = std::default_random_engine, std::floating_point T>

T ghassanpl::random::in_real_range ( T to, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Definition at line 191 of file random.h.

index()

template<typename RANDOM = std::default_random_engine, typename T>

auto ghassanpl::random::index ( T & cont, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns an index of a random element in cont.

Definition at line 331 of file random.h.

index_if()

template<typename RANDOM = std::default_random_engine, typename T, typename PRED>

auto ghassanpl::random::index_if ( T & cont, PRED && pred, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns an index of a random element in cont that matches pred.

Definition at line 338 of file random.h.

integer()

template<typename INTEGER = uint64_t, typename RANDOM = std::default_random_engine>

INTEGER ghassanpl::random::integer ( RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscardconstexpr

Returns a random integer of the given type.

Definition at line 62 of file random.h.

iterator()

template<typename RANDOM = std::default_random_engine, typename T>

auto ghassanpl::random::iterator ( T & cont, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns an iterator to a random element in cont.

Definition at line 300 of file random.h.

iterator_if()

template<typename RANDOM = std::default_random_engine, typename T, typename PRED>

auto ghassanpl::random::iterator_if ( T & cont, PRED && pred, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns an iterator to a random element in cont that matches pred.

Definition at line 310 of file random.h.

iterator_with_probability()

template<typename RANGE, typename FUNC, typename RANDOM>

auto ghassanpl::random::iterator_with_probability ( RANGE && range, FUNC && prob_func, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns an iterator to a random object in range, with the probability weights of an object being chosen given by prob_func(obj).

prob_func will be called at least twice per object.

Precondition

prob_func will never return < 0.0 \complexity O(1) space, O(2N) time

Definition at line 427 of file random.h.

make_bag_randomizer()

template<typename RANDOM = std::default_random_engine, typename T>

auto ghassanpl::random::make_bag_randomizer ( T & container, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns an object that represents a random "bag" of iterators to objects in container.

Using its next() function you can get a random iterator from the bag, guaranteeing that it wasn't retrieved before UNLESS all of the iterators have already been retrieved, in which case all iterators are returned to the bag, and a fresh one is drawn at random. You can also manually call shuffle() on it to put all the iterators back in the bag.

Definition at line 387 of file random.h.

normal()

template<typename REAL = double, typename RANDOM = std::default_random_engine>

REAL ghassanpl::random::normal ( RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns a random value of the given floating-point type in a normal distribution.

Definition at line 90 of file random.h.

one_in()

template<typename RANDOM = std::default_random_engine>

bool ghassanpl::random::one_in ( size_t n, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns true with a one-in-n chance.

Definition at line 282 of file random.h.

one_of() [1/2]

template<typename RANDOM = std::default_random_engine, typename T>

auto ghassanpl::random::one_of ( std::initializer_list< T > values, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns one of the values in values at random.

Definition at line 373 of file random.h.

one_of() [2/2]

template<typename... T>

auto ghassanpl::random::one_of ( T &&... values )

nodiscard

Returns one of its arguments at random.

Definition at line 363 of file random.h.

option_with_probability()

template<typename T, typename RANDOM>

size_t ghassanpl::random::option_with_probability ( span< T const > option_probabilities, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns an index of one of the options in option_probabilities, where its elements are the probability weights of their specific options.

\complexity O(N) space, O(N+logN) time

Definition at line 413 of file random.h.

percentage()

template<typename REAL = double, typename RANDOM = std::default_random_engine>

REAL ghassanpl::random::percentage ( RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns a random value between 0 and 1 of the given floating-point type.

Definition at line 70 of file random.h.

shuffle()

template<typename RANDOM = std::default_random_engine, typename T>

void ghassanpl::random::shuffle	(	T &	cont,
		RANDOM &	rng = ::ghassanpl::random::default_random_engine )

Shuffles the cont container (as if by std::shuffle).

Definition at line 290 of file random.h.

with_probability() [1/2]

template<typename RANDOM = std::default_random_engine>

bool ghassanpl::random::with_probability ( double probability, double & result, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns true with the given 0-1 probability, false otherwise; stores the result of the 0-1 "roll" in result.

Definition at line 274 of file random.h.

with_probability() [2/2]

template<typename RANDOM = std::default_random_engine>

bool ghassanpl::random::with_probability ( double probability, RANDOM & rng = ::ghassanpl::random::default_random_engine )

nodiscard

Returns true with the given 0-1 probability, false otherwise.

Definition at line 267 of file random.h.

Variable Documentation

default_random_engine

std::default_random_engine ghassanpl::random::default_random_engine

inlinethread_local

A thread-local random engine used by default by all random functions.

Definition at line 58 of file random.h.