Random numbers generation

Overview

Definition of API for generating random numbers. More…

// global functions

uintmax_t te_rand_unsigned(uintmax_t min, uintmax_t max);
intmax_t te_rand_signed(intmax_t min, intmax_t max);
static uintmax_t te_rand_unsigned_div(uintmax_t min, uintmax_t max, unsigned int div, unsigned int rem);
static intmax_t te_rand_signed_div(intmax_t min, intmax_t max, unsigned int div, unsigned int mod);
int te_rand_range_exclude(int min, int max, int exclude);

Detailed Documentation

Definition of API for generating random numbers.

Global Functions

uintmax_t te_rand_unsigned(uintmax_t min, uintmax_t max)

Generate a random unsigned number in a given range.

The function uses xoshiro256++ algorithm that is able to generate the full range of 64-bit numbers, see http://vigna.di.unimi.it/ftp/papers/ScrambledLinear.pdf.

The PRNG state is seeded based on the standard rand(), so that applications that use srand() would get reproducible results with this function as well.

Todo The current implementation is not well suited for multithreaded applications, just like the standard rand() used by rand_range(), however, the algorithm does support creation of robust parallel PRNGs, so it may be implemented, should it ever be needed.

Parameters:

min	Minimum value (inclusive).
max	Maximum value (inclusive).

Returns:

The next pseudo-random number between min and max.

intmax_t te_rand_signed(intmax_t min, intmax_t max)

Generate a random signed number in a given range.

See te_rand_unsigned() for details.

Parameters:

min	Minimum value (inclusive).
max	Maximum value (inclusive).

Returns:

The next pseudo-random number between min and max.

static uintmax_t te_rand_unsigned_div(uintmax_t min, uintmax_t max, unsigned int div, unsigned int rem)

Generate a random unsigned number in a given range such that its value modulo div is rem.

Parameters:

min	Minimum value (inclusive).
max	Maximum value (inclusive).
div	Divisor.
rem	Expected remainder.

Returns:

A random value such that it’s equal to rem modulo div.

static intmax_t te_rand_signed_div(intmax_t min, intmax_t max, unsigned int div, unsigned int mod)

Generate a random signed number in a given range such that its value modulo div is rem.

If rem is zero, the value will always be in the range between min and max. Otherwise, it may fall out of this range if min or max themselves are not equal to rem modulo div.

The function takes into account that in C the remainder is negative if the quotient is negative, so if the result of the function is negative, it will actually be so that: te_rand_signed_div(min, max, div, mod) % div == -mod.

Parameters:

min	Minimum value (inclusive).
max	Maximum value (inclusive).
div	Divisor.
rem	Expected remainder.

Returns:

A random value such that it’s equal to rem modulo div.

int te_rand_range_exclude(int min, int max, int exclude)

Choose a random value from a range excluding some value inside that range.

This function will use TE_FATAL_ERROR() if it is impossible to choose any value.

Parameters:

min	Range lower limit.
max	Range upper limit.
exclude	Value to exclude.

Returns:

Random number from the range [min, max].