randomnumber Class Reference

#include <randomnumber.h>

Inherits object.

Public Member Functions
	randomnumber ()
	~randomnumber ()
bool	setSeed (uint32_t seed)
bool	generate (uint32_t *result)
bool	generate (int32_t *result, int32_t lower, int32_t upper)
Public Member Functions inherited from object
virtual	~object ()

Static Public Member Functions
static uint32_t	getSeed ()
static uint32_t	generate (uint32_t seed)
static int32_t	generate (uint32_t seed, int32_t lower, int32_t upper)
static int32_t	scale (uint32_t number, int32_t lower, int32_t upper)
static uint32_t	getRandMax ()
static bool	getNeedsMutex ()
static void	setMutex (threadmutex *mtx)

Detailed Description

The randomnumber class provides methods for generating and scaling random numbers.

Superfluous background:

There is no such thing as true randomness. Many random number generators just return values from a highly divergent series. Others collect "entropy" from system hardware returning numbers that are actually associated with system activity but in an indiscernible way. In most cases, entropy-based systems are just used to seed systems that return values from a highly divergnet series.

If there is only one running process generating random numbers using a highly divergent series, successive calls to generate() will never return the same value until all numbers between 0 and the number returned by getRandMax() (usually 2^31-1 but could be 2^32-1 or 2^15-1 on some systems) have been returned. At that point, the entire sequence will repeat.

Calls to generate() with lower/upper parameters may return the same value before all numbers in the range have been returned because it just scales the result of generate() without lower/upper parameters which operates on a larger range.

Constructor & Destructor Documentation

randomnumber()

randomnumber::randomnumber

(

)

Creates a new instance of the randomnumber class.

~randomnumber()

randomnumber::~randomnumber

(

)

Deletes this instance of the randomnumber class.

Member Function Documentation

generate() [1/4]

bool randomnumber::generate	(	int32_t *	result,
		int32_t	lower,
		int32_t	upper )

Generates a random number between "lower" and "upper" and sets "result" to this number.

Returns true on success and false on failure.

generate() [2/4]

bool randomnumber::generate

(

uint32_t *

result

)

Generates a random number between 0 and the number given by getRandMax() (usually 2^31-1 but could be 2^32-1 or 2^15-1) and sets "result" to this number.

Returns true on success and false on failure.

generate() [3/4]

static uint32_t randomnumber::generate ( uint32_t seed )

static

Generates a random number between 0 and 2^32, based on seed, and returns it.

It is ok to use the result of this method as the seed for the next number.

generate() [4/4]

static int32_t randomnumber::generate ( uint32_t seed, int32_t lower, int32_t upper )

static

Generates a random number between 0 and the number given by getRandMax() (usually 2^31-1 but could be 2^32-1 or 2^15-1), based on "seed", scales that value to be between "lower" and "upper" and returns it.

It is NOT ok to use the result of this method as the seed for the next number.

getNeedsMutex()

static bool randomnumber::getNeedsMutex ( )

static

Returns true if this class needs a mutex to operate safely in a threaded environment and false otherwise.

getRandMax()

static uint32_t randomnumber::getRandMax ( )

static

Returns the largest number that generate() could possibly generate. This is usually 2^31-1 on 32 or 64 bit machines but there are exceptions where it is 2^32-1 or 2^15-1.

getSeed()

static uint32_t randomnumber::getSeed ( )

static

Generates a random number seed by first attempting to get one from /dev/urandom and if that fails, getting the number of seconds since 1970.

NOTE: If your application is multi-threaded, /dev/urandom is not accessible, and separate threads can call getSeed(), unsynchronized, then be sure to give the datetime and environment classes individual mutexes using datetime::setMutex() and environemnt::setMutex(), as on some platforms, getting the number of seconds since 1970 involves calling non-thread safe date/time-related functions as well as getting, and possibly setting, the TZ environment variable.

scale()

static int32_t randomnumber::scale ( uint32_t number, int32_t lower, int32_t upper )

static

Scales "number" to be between "lower" and "upper" and returns it.

It is NOT ok to use the result of this method as the seed for the next number.

setMutex()

static void randomnumber::setMutex ( threadmutex * mtx )

static

Allows you to supply a mutex is the class needs it (see getNeedsMutex()). If your application is not multithreaded, then there is no need to supply a mutex.

setSeed()

bool randomnumber::setSeed

(

uint32_t

seed

)

Sets the initial seed for this instance.