#include <mersenne.hpp>

Public Member Functions
	TCODRandom (TCOD_random_algo_t algo=TCOD_RNG_CMWC, bool allocate=true)
	You can also create as many generators as you want with a random seed (the number of seconds since Jan 1 1970 at the time the constructor is called).
	TCODRandom (uint32_t seed, TCOD_random_algo_t algo=TCOD_RNG_CMWC)
	TCODRandom (TCOD_Random *mersenne)
	Take ownership of a TCOD_Random* pointer.
	TCODRandom (const TCODRandom &)=delete
TCODRandom &	operator= (const TCODRandom &)=delete
	TCODRandom (TCODRandom &&rhs)
TCODRandom &	operator= (TCODRandom &&rhs) noexcept
virtual	~TCODRandom ()
void	setDistribution (TCOD_distribution_t distribution)
int	getInt (int min, int max, int mean=0)
int	get (int min, int max, int mean=0)
float	getFloat (float min, float max, float mean=0.0f)
float	get (float min, float max, float mean=0.0f)
double	getDouble (double min, double max, double mean=0.0)
double	get (double min, double max, double mean=0.0f)
TCODRandom *	save () const
	You can save the state of a generator with :
void	restore (const TCODRandom *backup)
TCOD_dice_t	dice (const char *s)
int	diceRoll (TCOD_dice_t dice)
int	diceRoll (const char *s)
TCOD_Random *	get_data () noexcept
	Return this objects TCOD_Random* pointer.
const TCOD_Random *	get_data () const noexcept

Static Public Member Functions
static TCODRandom *	getInstance (void)
	The simplest way to get random number is to use the default generator.

Protected Attributes
TCOD_Random *	data {}

Friends
class	TCODNoise
class	TCODHeightMap
class	TCODNamegen
class	TCODNameGenerator

Detailed Description

This toolkit is an implementation of two fast and high quality pseudorandom number generators: a Mersenne twister generator, a Complementary-Multiply-With-Carry generator. CMWC is faster than MT (see table below) and has a much better period (1039460 vs. 106001). It is the default algo since libtcod 1.5.0.

Relative performances in two independent tests (lower is better) :

Algorithm	Numbers generated	Perf (1)	Perf (2)
MT	integer	62	50
MT	float	54	45
CMWC	integer	21	34
CMWC	float	32	27

For Python users:

Python already has great builtin random generators. But some parts of the Doryen library (noise, heightmap, ...) uses RNG as parameters. If you intend to use those functions, you must provide a RNG created with the library.

For C# users:

.NET already has great builtin random generators. But some parts of the Doryen library (noise, heightmap, ...) uses RNG as parameters. If you intend to use those functions, you must provide a RNG created with the library.

Constructor & Destructor Documentation

◆ TCODRandom() [1/3]

TCODRandom::TCODRandom	(	TCOD_random_algo_t	algo = TCOD_RNG_CMWC,
		bool	allocate = true )

You can also create as many generators as you want with a random seed (the number of seconds since Jan 1 1970 at the time the constructor is called).

Warning ! If you call this function several times in the same second, it will return the same generator.

TCODRandom::TCODRandom() // Defaults to ComplementaryMultiplyWithCarry TCODRandom::TCODRandom(TCODRandomType algo)

Parameters

algo	The PRNG algorithm the generator should be using.

◆ TCODRandom() [2/3]

TCODRandom::TCODRandom	(	uint32_t	seed,
		TCOD_random_algo_t	algo = TCOD_RNG_CMWC )

@noop random_init
@noop Generators with user defined seeds
@brief Finally, you can create generators with a specific seed. Those allow you to get a reproducible set of random numbers. You can for example save a dungeon in a file by saving only the seed used for its generation (provided you have a determinist generation algorithm)
@noop TCODRandom::TCODRandom (uint32_t seed, TCOD_random_algo_t algo = TCOD_RNG_CMWC);
@noop TCOD_random_t TCOD_random_new_from_seed (TCOD_random_algo_t algo, uint32_t seed);
@noop random_new_from_seed(seed, algo=RNG_CMWC)
@noop#
  TCODRandom::TCODRandom(uint32_t seed) // Defaults to ComplementaryMultiplyWithCarry
  TCODRandom::TCODRandom(uint32_t seed, TCODRandomType algo)
@param seed The 32 bits seed used to initialize the generator. Two generators created with the same seed will generate the same set of pseudorandom numbers.
@param algo The PRNG algorithm the generator should be using.
@noop

default generator TCODRandom * default = TCODRandom::getInstance(); another random generator TCODRandom * myRandom = new TCODRandom(); a random generator with a specific seed TCODRandom * myDeterministRandom = new TCODRandom(0xdeadbeef);

default generator TCOD_random_t default = TCOD_random_get_instance(); another random generator TCOD_random_t my_random = TCOD_random_new(TCOD_RNG_CMWC); a random generator with a specific seed TCOD_random_t my_determinist_random = TCOD_random_new_from_seed(TCOD_RNG_CMWC,0xdeadbeef);

default generator

default = libtcod.random_get_instance()

another random generator

my_random = libtcod.random_new()

a random generator with a specific seed

my_determinist_random = libtcod.random_new_from_seed(0xdeadbeef)

◆ TCODRandom() [3/3]

TCODRandom::TCODRandom ( TCOD_Random * mersenne )

inlineexplicit

Take ownership of a TCOD_Random* pointer.

embed:rst:leading-asterisk 
.. versionadded:: 1.16

◆ ~TCODRandom()

virtual TCODRandom::~TCODRandom ( )

virtual

@noop random_init
@noop Destroying a RNG
@brief To release resources used by a generator, use those functions :
  NB : do not delete the default random generator !
@noop TCODRandom::~TCODRandom()
@noop void TCOD_random_delete(TCOD_random_t mersenne)
@noop random_delete(mersenne)
@noop# void TCODRandom::Dispose()
@param mersenne In the C and Python versions, the generator handler, returned by the initialization functions.
@noop

create a generator TCODRandom *rnd = new TCODRandom(); use it ... destroy it delete rnd;

create a generator TCOD_random_t rnd = TCOD_random_new(); use it ... destroy it TCOD_random_delete(rnd);

create a generator

rnd = libtcod.random_new()

use it

...

destroy it

libtcod.random_delete(rnd)

Member Function Documentation

◆ get_data()

TCOD_Random * TCODRandom::get_data ( )

inlinenoexcept

Return this objects TCOD_Random* pointer.

embed:rst:leading-asterisk 
.. versionadded:: 1.16

◆ getDouble()

double TCODRandom::getDouble	(	double	min,
		double	max,
		double	mean = 0.0 )

inline

@noop random_use
@noop Getting a double
@brief To get a random double precision floating point number, using either the explicit or simplified API where applicable
@noop

explicit API: double TCODRandom::getDouble(double min, double max, double mean = 0.0f)

simplified API: double TCODRandom::get(double min, double max, double mean = 0.0f)

double TCOD_random_get_double(TCOD_random_t mersenne, double min, double max) double TCOD_random_get_double_mean(TCOD_random_t mersenne, double min, double max, double mean)

Parameters

mersenne	In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used.
min,max	Range of values returned. Each time you call this function, you get a number between (including) min and max
mean	This is used to set a custom mean, ie, not min+((max-min)/2). It can even be outside of the min-max range. Using a mean will force the use of a weighted (Gaussian) distribution, even if linear is set.

default generator TCODRandom * default = TCODRandom::getInstance(); int aRandomIntBetween0And1000 = default->getInt(0,1000); int anotherRandomInt = default->get(0,1000); another random generator TCODRandom *myRandom = new TCODRandom(); float aRandomFloatBetween0And1000 = myRandom->getFloat(0.0f,1000.0f); float anotherRandomFloat = myRandom->get(0.0f,1000.0f);

default generator int a_random_int_between_0_and_1000 = TCOD_random_get_float(NULL,0,1000); another random generator TCOD_random_t my_random = TCOD_random_new(); float a_random_float_between_0_and_1000 = TCOD_random_get_float(my_random,0.0f,1000.0f);

default generator

a_random_int_between_0_and_1000 = libtcod.random_get_float(0,0,1000)

another random generator

my_random = libtcod.random_new() a_random_float_between_0_and_1000 = libtcod.random_get_float(my_random,0.0,1000.0)

◆ getFloat()

float TCODRandom::getFloat	(	float	min,
		float	max,
		float	mean = 0.0f )

inline

@noop random_use
@noop Getting a float
@brief To get a random floating point number, using either the explicit or simplified API where applicable
@noop

explicit API: float TCODRandom::getFloat(float min, float max, float mean = 0.0f)

simplified API: float TCODRandom::get(float min, float max, float mean = 0.0f)

float TCOD_random_get_float(TCOD_random_t mersenne, float min, float max) float TCOD_random_get_float_mean(TCOD_random_t mersenne, float min, float max, float mean)

Parameters

mersenne	In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used.
min,max	Range of values returned. Each time you call this function, you get a number between (including) min and max
mean	This is used to set a custom mean, ie, not min+((max-min)/2). It can even be outside of the min-max range. Using a mean will force the use of a weighted (Gaussian) distribution, even if linear is set.

default generator TCODRandom * default = TCODRandom::getInstance(); int aRandomIntBetween0And1000 = default->getInt(0,1000); int anotherRandomInt = default->get(0,1000); another random generator TCODRandom *myRandom = new TCODRandom(); float aRandomFloatBetween0And1000 = myRandom->getFloat(0.0f,1000.0f); float anotherRandomFloat = myRandom->get(0.0f,1000.0f);

default generator int a_random_int_between_0_and_1000 = TCOD_random_get_float(NULL,0,1000); another random generator TCOD_random_t my_random = TCOD_random_new(); float a_random_float_between_0_and_1000 = TCOD_random_get_float(my_random,0.0f,1000.0f);

default generator

a_random_int_between_0_and_1000 = libtcod.random_get_float(0,0,1000)

another random generator

my_random = libtcod.random_new() a_random_float_between_0_and_1000 = libtcod.random_get_float(my_random,0.0,1000.0)

◆ getInstance()

TCODRandom * TCODRandom::getInstance ( void )

static

The simplest way to get random number is to use the default generator.

The first time you get this generator, it is initialized by calling TCOD_random_new. Then, on successive calls, this function returns the same generator (singleton pattern).

Parameters

algo	The PRNG algorithm the generator should be using. Possible values are: TCOD_RNG_MT for Mersenne Twister, TCOD_RNG_CMWC for Complementary Multiply-With-Carry.

◆ getInt()

int TCODRandom::getInt	(	int	min,
		int	max,
		int	mean = 0 )

inline

@noop random_use
@noop random
@noop Using a generator
@noop Getting an integer
@brief Once you obtained a generator (using one of those methods), you can get random numbers using the following functions, using either the explicit or simplified API where applicable:
@noop

explicit API: int TCODRandom::getInt(int min, int max, int mean = 0)

simplified API: int TCODRandom::get(int min, int max, int mean = 0)

int TCOD_random_get_int(TCOD_random_t mersenne, int min, int max) int TCOD_random_get_int_mean(TCOD_random_t mersenne, int min, int max, int mean)

Parameters

mersenne	In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used..
min,max	Range of values returned. Each time you call this function, you get a number between (including) min and max
mean	This is used to set a custom mean, ie, not min+((max-min)/2). It can even be outside of the min-max range. Using a mean will force the use of a weighted (Gaussian) distribution, even if linear is set.

◆ restore()

void TCODRandom::restore ( const TCODRandom * backup )

@noop random_use
@noop Restoring a saved state
@brief And restore it later. This makes it possible to get the same series of number several times with a single generator.
@noop void TCODRandom::restore(const TCODRandom *backup)
@noop void TCOD_random_restore(TCOD_random_t mersenne, TCOD_random_t backup)
@noop random_restore(mersenne, backup)
@noop# void TCODRandom::restore(TCODRandom backup)
@param mersenne In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used.
@noop

default generator TCODRandom * default = TCODRandom::getInstance(); save the state TCODRandom *backup=default->save(); get a random number (or several) int number1 = default->getInt(0,1000); restore the state default->restore(backup); get a random number int number2 = default->getInt(0,1000); => number1 == number2

save default generator state TCOD_random_t backup=TCOD_random_save(NULL); get a random number int number1 = TCOD_random_get_float(NULL,0,1000); restore the state TCOD_random_restore(NULL,backup); get a random number int number2 = TCOD_random_get_float(NULL,0,1000); number1 == number2

save default generator state

backup=libtcod.random_save(0)

get a random number

number1 = libtcod.random_get_float(0,0,1000)

restore the state

libtcod.random_restore(0,backup)

get a random number

number2 = libtcod.random_get_float(0,0,1000)

number1 == number2

◆ save()

TCODRandom * TCODRandom::save ( ) const

You can save the state of a generator with :

Parameters

mersenne In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used.

◆ setDistribution()

void TCODRandom::setDistribution ( TCOD_distribution_t distribution )

inline

@noop random_distro
@noop random
@noop Using a generator
@noop Setting the default RNG distribution
@brief Random numbers can be obtained using several different distributions. Linear is default, but if you wish to use one of the available Gaussian distributions, you can use this function to tell libtcod which is your preferred distribution. All random number getters will then use that distribution automatically to fetch your random numbers.

The distributions available are as follows:

TCOD_DISTRIBUTION_LINEAR This is the default distribution. It will return a number from a range min-max. The numbers will be evenly distributed, ie, each number from the range has the exact same chance of being selected.
TCOD_DISTRIBUTION_GAUSSIAN This distribution does not have minimum and maximum values. Instead, a mean and a standard deviation are used. The mean is the central value. It will appear with the greatest frequency. The farther away from the mean, the less the probability of appearing the possible results have. Although extreme values are possible, 99.7% of the results will be within the radius of 3 standard deviations from the mean. So, if the mean is 0 and the standard deviation is 5, the numbers will mostly fall in the (-15,15) range.
TCOD_DISTRIBUTION_GAUSSIAN_RANGE This one takes minimum and maximum values. Under the hood, it computes the mean (which falls right between the minimum and maximum) and the standard deviation and applies a standard Gaussian distribution to the values. The difference is that the result is always guaranteed to be in the min-max range.
TCOD_DISTRIBUTION_GAUSSIAN_INVERSE Essentially, this is the same as TCOD_DISTRIBUTION_GAUSSIAN. The difference is that the values near +3 and -3 standard deviations from the mean have the highest possibility of appearing, while the mean has the lowest.
TCOD_DISTRIBUTION_GAUSSIAN_RANGE_INVERSE Essentially, this is the same as TCOD_DISTRIBUTION_GAUSSIAN_RANGE, but the min and max values have the greatest probability of appearing, while the values between them, the lowest.

There exist functions to also specify both a min-max range AND a custom mean, which can be any value (possibly either min or max, but it can even be outside that range). In case such a function is used, the distributions will trigger a slightly different behaviour: TCOD_DISTRIBUTION_LINEAR TCOD_DISTRIBUTION_GAUSSIAN TCOD_DISTRIBUTION_GAUSSIAN_RANGE In these cases, the selected mean will have the highest probability of appearing.

TCOD_DISTRIBUTION_GAUSSIAN_INVERSE TCOD_DISTRIBUTION_GAUSSIAN_RANGE_INVERSE In these cases, the selected mean will appear with the lowest frequency.

Parameters

mersenne	In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used..
distribution	The distribution constant from the available set: TCOD_DISTRIBUTION_LINEAR TCOD_DISTRIBUTION_GAUSSIAN TCOD_DISTRIBUTION_GAUSSIAN_RANGE TCOD_DISTRIBUTION_GAUSSIAN_INVERSE TCOD_DISTRIBUTION_GAUSSIAN_RANGE_INVERSE

The documentation for this class was generated from the following file:

C:/Users/4b796/Projects/libtcod/src/libtcod/mersenne.hpp

Public Member Functions

Static Public Member Functions

Protected Attributes

Friends

Detailed Description

For Python users:

For C# users:

Constructor & Destructor Documentation

◆ TCODRandom() [1/3]

◆ TCODRandom() [2/3]

default generator

another random generator

a random generator with a specific seed

◆ TCODRandom() [3/3]

◆ ~TCODRandom()

create a generator

use it

destroy it

Member Function Documentation

◆ get_data()

◆ getDouble()

default generator

another random generator

◆ getFloat()

default generator

another random generator

◆ getInstance()

◆ getInt()

◆ restore()

save default generator state

get a random number

restore the state

get a random number

number1 == number2

◆ save()

◆ setDistribution()