Rudiments
Public Member Functions | Static Public Member Functions | List of all members
randomnumber Class Reference

Public Member Functions

 randomnumber ()
 
 ~randomnumber ()
 
bool setSeed (uint32_t seed)
 
bool generateNumber (uint32_t *result)
 
bool generateScaledNumber (int32_t lower, int32_t upper, int32_t *result)
 

Static Public Member Functions

static uint32_t getSeed ()
 
static uint32_t generateNumber (uint32_t seed)
 
static int32_t generateScaledNumber (uint32_t seed, int32_t lower, int32_t upper)
 
static int32_t scaleNumber (uint32_t number, int32_t lower, int32_t upper)
 
static uint32_t getRandMax ()
 
static bool needsMutex ()
 
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 generateNumber() 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 generateScaledNumber() may return the same value before all numbers in the range have been returned because it just scales the result of generateNumber() 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

◆ generateNumber() [1/2]

bool randomnumber::generateNumber ( 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.

◆ generateNumber() [2/2]

static uint32_t randomnumber::generateNumber ( 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.

◆ generateScaledNumber() [1/2]

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

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

Returns true on success and false on failure.

◆ generateScaledNumber() [2/2]

static int32_t randomnumber::generateScaledNumber ( 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.

◆ getRandMax()

static uint32_t randomnumber::getRandMax ( )
static

Returns the largest number that generateNumber() 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.

◆ needsMutex()

static bool randomnumber::needsMutex ( )
static

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

◆ scaleNumber()

static int32_t randomnumber::scaleNumber ( 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 needsMutex()). 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.