Base Operations

Operations for basic number generation and basic random operations. More...

Collaboration diagram for Base Operations:

Topics
	Generator Instance Operations
	Operations for tgen generator instances.

Classes
struct	tgen::print
	Printer helper for standard types. More...
struct	tgen::println
	Printer helper for standard types, printing on a new line. More...
struct	tgen::unique_range< T >
	Unique generator for integral ranges. More...
struct	tgen::unique_container< T >
	Unique generator for containers. More...
struct	tgen::unique< Func, Args >
	Unique generator for discrete uniform functions. More...
struct	tgen::gen_base< Gen >
	Base class for generators (should not be instantiated). More...
struct	tgen::gen_instance_base< Inst >
	Base class for generator instances (should not be instantiated). More...

Macros
#define	tgen_ensure(cond, ...)
	Ensures condition is true.

Functions
template<typename T>
T	tgen::next (T n)
	Returns a random number up to value.
template<typename T>
T	tgen::next (T l, T r)
	Returns a random number in range.
template<typename T>
size_t	tgen::next_by_distribution (const std::vector< T > &distribution)
	Returns random index with given probabilities.
template<typename It>
void	tgen::shuffle (It first, It last)
	Shuffles range inplace, for random_access_iterator.
template<typename C, std::enable_if_t<!is_associative_container< C >::value and !is_generator_instance< C >::value, int > = 0>
C	tgen::shuffled (const C &container)
	Shuffles a container.
template<typename It>
It::value_type	tgen::any (It first, It last)
	Choses a random element from iterator range.
template<typename C, std::enable_if_t<!is_generator_instance< C >::value, int > = 0>
C::value_type	tgen::any (const C &container)
	Choses a random element from container.
template<typename C, typename T, std::enable_if_t<!is_generator_instance< C >::value, int > = 0>
C::value_type	tgen::any_by_distribution (const C &container, std::vector< T > distribution)
	Choses a random element with given probabilities.
template<typename C, std::enable_if_t<!is_generator_instance< C >::value, int > = 0>
C	tgen::choose (int k, const C &container)
	Chooses elements from container, as in a subsequence fixed length.

Detailed Description

Operations for basic number generation and basic random operations.

Examples

// Random number from 10 to 20.
int size = tgen::next(10, 20);
tgen_ensure(size <= 20);
 
// Several numbers in {5, 10, 15, 20}.
std::vector<int> v(size);
for (int& i : v) i = tgen::any({5, 10, 15, 20});
 
// Shuffles the numbers.
tgen::shuffle(v.begin(), v.end());
 
// Choses a subsequence of length 5.
v = tgen::choose(5, v);

Macro Definition Documentation

tgen_ensure

#define tgen_ensure	(		cond,
			... )

Ensures condition is true.

Parameters

cond	Condition to me ensured.
...	Empty or a string with an error message.

Exceptions

std::runtime_error

if cond is not true.

Examples

// Without error message:
tgen_ensure(a == b);
// With error message:
tgen_ensure(a == b, "values must be the same");

Definition at line 95 of file tgen.h.

Function Documentation

any() [1/2]

template<typename C, std::enable_if_t<!is_generator_instance< C >::value, int > = 0>

C::value_type tgen::any

(

const C &

container

)

Choses a random element from container.

Parameters

container

Container to choose from.

Also works with std::initializer_list.

Returns

A uniformly random element from container.

Complexity

O(1) for random_access_iterator, O(|container|) otherwise.

Examples

std::vector<int> v = {1, 2, 3, 4, 5};
int value = tgen::any(v);

Definition at line 635 of file tgen.h.

any() [2/2]

template<typename It>

It::value_type tgen::any	(	It	first,
		It	last )

Choses a random element from iterator range.

Parameters

first	First iterator of range.
last	First iterator outside of range.

Returns

A uniformly random element from the range [first, last).

Complexity

O(1) for random_access_iterator, O(|last - first|) otherwise.

Examples

std::set<int> st = {1, 2, 3, 4, 5};
int value = tgen::any(st.begin(), st.end());

Definition at line 624 of file tgen.h.

any_by_distribution()

template<typename C, typename T, std::enable_if_t<!is_generator_instance< C >::value, int > = 0>

C::value_type tgen::any_by_distribution	(	const C &	container,
		std::vector< T >	distribution )

Choses a random element with given probabilities.

Parameters

container	Container to choose from.
distribution	Probability distribution.

Also works with std::initializer_list.

Returns

For i in [0, container.size()-1], container[i] with probability proportional to distribution[i].

Complexity

O(1) for random_access_iterator, O(|container|) otherwise.

Examples

// Generates chars with custom odds.
int value = tgen::any_by_distribution({"a", "b", "c"}, {1, 2, 3});

Definition at line 653 of file tgen.h.

choose()

template<typename C, std::enable_if_t<!is_generator_instance< C >::value, int > = 0>

C tgen::choose	(	int	k,
		const C &	container )

Chooses elements from container, as in a subsequence fixed length.

Parameters

k	Number of elements to be chosen.
container	Container to choose from.

Also works with std::initializer_list.

Returns

A uniformly random subsequence of length k.

Complexity

O(|container|).

Examples

std::vector<int> v = {1, 2, 3, 4, 5};
v = tgen::choose(3, v); // Chooses 3 elements from v.

Definition at line 702 of file tgen.h.

next() [1/2]

template<typename T>

T tgen::next	(	T	l,
		T	r )

Returns a random number in range.

Template Parameters

T	type to be generated. Should be an arithmetic type: int, double, long long, char, etc.

Parameters

l	Left endpoint of the range.
r	Light endpoint of the range.

Returns

A random number in [l, r], chosen uniformly.

Complexity

O(1).

Examples

// Random value from 1 to 10.
int value = tgen::next(1, 10);

Definition at line 543 of file tgen.h.

next() [2/2]

template<typename T>

T tgen::next

(

T

n

)

Returns a random number up to value.

Template Parameters

T	type to be generated. Should be an arithmetic type: int, double, long long, char, etc.

Parameters

n	Endpoint of the range.

Returns

A random number in [0, n), chosen uniformly.

Complexity

O(1).

Examples

// Random value from 0 to 9.
int value = tgen::next(10);
// Probability 1/3:
bool odds = tgen::next<double>(3) < 1.0;

Definition at line 528 of file tgen.h.

next_by_distribution()

template<typename T>

size_t tgen::next_by_distribution

(

const std::vector< T > &

distribution

)

Returns random index with given probabilities.

Parameters

distribution

Probability distribution.

Returns

i in [0, distribution.size()-] with probability proportional to distribution[i].

Complexity

O(|distribution|).

Examples

// 0 or 1; 1000 times more likely to generate 1.
int value = tgen::next_by_distribution({1, 1000});

Definition at line 557 of file tgen.h.

shuffle()

template<typename It>

void tgen::shuffle	(	It	first,
		It	last )

Shuffles range inplace, for random_access_iterator.

Parameters

first	First iterator of range.
last	First iterator outside of range.

Shuffles [first, last) uniformly inplace. Works for std::vector, std::string, etc, but not std::set. For those, use tgen::shuffled(container).

Complexity

O(|last - first|).

Examples

std::vector<int> v = {1, 2, 3, 4, 5};
tgen::shuffle(v.begin(), v.end());

Definition at line 576 of file tgen.h.

shuffled()

template<typename C, std::enable_if_t<!is_associative_container< C >::value and !is_generator_instance< C >::value, int > = 0>

C tgen::shuffled ( const C & container )

nodiscard

Shuffles a container.

Parameters

container

Container to be shuffled.

Works for containers and std::initializer_list. If container is ordered (std::set, etc) or std::initializer_list, returns a std::vector (implemented in a different function).

Returns

The shuffled container.

Complexity

O(|container|).

Examples

std::vector<int> st = {1, 2, 3, 4, 5};
st = tgen::shuffled(st);
st = tgen::shuffled({1, 2, 3});
st = tgen::shuffled(std::set<int>({1, 2, 3}));

Definition at line 597 of file tgen.h.