32-bit PRNG (xorshift/generalized) More...
Typedefs | |
| typedef typedefCGUL_BEGIN_C struct cgul_random_xorshift32 * | cgul_random_xorshift32_t |
Functions | |
| CGUL_EXPORT cgul_random_xorshift32_t | cgul_random_xorshift32__new (cgul_exception_t *cex) |
| CGUL_EXPORT cgul_random_xorshift32_t | cgul_random_xorshift32__new_from_seed (cgul_exception_t *cex, cgul_uint32_t seed) |
| CGUL_EXPORT cgul_random_xorshift32_t | cgul_random_xorshift32__new_from_seed_array (cgul_exception_t *cex, cgul_uint32_t *seeds) |
| CGUL_EXPORT void | cgul_random_xorshift32__delete (cgul_random_xorshift32_t r) |
| CGUL_EXPORT void | cgul_random_xorshift32__allocate_seed_array (cgul_exception_t *cex, cgul_uint32_t **v, unsigned int *v_count) |
| CGUL_EXPORT cgul_uint32_t | cgul_random_xorshift32__next (cgul_exception_t *cex, cgul_random_xorshift32_t r) |
| CGUL_EXPORT cgul_uint32_t | cgul_random_xorshift32__next_in_range (cgul_exception_t *cex, cgul_random_xorshift32_t r, cgul_uint32_t range_max) |
| CGUL_EXPORT double | cgul_random_xorshift32__next_in_unit (cgul_exception_t *cex, cgul_random_xorshift32_t r) |
Detailed Description
32-bit xorshift pseudo-random number generator. This PRNG has a period of (2^4096 - 1). This PRNG has a longer period and uses less memory than cgul_random_lfg32 but is a little slower. It does well when statistically analyzed and is a good choice if cgul_random_cmwc32 cannot be used for some reason. This PRNG requires about 512 bytes to hold state information. The relevant papers discussing this PRNG can be found at the following URLs:
http://www.jstatsoft.org/v08/i14/paper
http://wwwmaths.anu.edu.au/~brent/pub/pub224.html
Typedef Documentation
§ cgul_random_xorshift32_t
| typedef typedefCGUL_BEGIN_C struct cgul_random_xorshift32* cgul_random_xorshift32_t |
Opaque pointer to a cgul_random_xorshift32 instance.
Function Documentation
§ cgul_random_xorshift32__new()
| CGUL_EXPORT cgul_random_xorshift32_t cgul_random_xorshift32__new | ( | cgul_exception_t * | cex | ) |
This is a convenience function that creates a new cgul_random_xorshift32 object seeding it with the value returned by time(), i.e., the 32-bit seconds since the epoch. The caller is responsible for freeing the object by calling cgul_random_xorshift32__delete(). If memory cannot be allocated, NULL is returned, and an exception is thrown.
- Parameters
-
[in,out] cex c-style exception
- Returns
- new
cgul_random_xorshift32instance
Referenced by cgul_random_xorshift32_cxx::cgul_random_xorshift32_cxx().
§ cgul_random_xorshift32__new_from_seed()
| CGUL_EXPORT cgul_random_xorshift32_t cgul_random_xorshift32__new_from_seed | ( | cgul_exception_t * | cex, |
| cgul_uint32_t | seed | ||
| ) |
This is a convenience function that creates a new cgul_random_xorshift32 object seeding it with seed. The caller is responsible for freeing the object by calling cgul_random_xorshift32__delete(). If memory cannot be allocated, NULL is returned, and an exception is thrown.
- Parameters
-
[in,out] cex c-style exception [in] seed seed value
- Returns
- new
cgul_random_xorshift32instance
Referenced by cgul_random_xorshift32_cxx::cgul_random_xorshift32_cxx().
§ cgul_random_xorshift32__new_from_seed_array()
| CGUL_EXPORT cgul_random_xorshift32_t cgul_random_xorshift32__new_from_seed_array | ( | cgul_exception_t * | cex, |
| cgul_uint32_t * | seeds | ||
| ) |
This is the correct way to create a new cgul_random_xorshift32 object by seeding it with the seeds array. It can be difficult, however, to acquire the requisite entropy to fill the entire array. The caller is responsible for freeing the object by calling cgul_random_xorshift32__delete(). If memory cannot be allocated or if all the seed values are zero, NULL is returned, and an exception is thrown.
The caller is responsible for making sure seeds has the correct number of elements. The easiest way to do this is by using cgul_random_xorshift32__allocate_seed_array() to allocate the array and get its size.
- Parameters
-
[in,out] cex c-style exception [in] seeds array of 32-bit values used to seed the PRNG
- Returns
- new
cgul_random_xorshift32instance
Referenced by cgul_random_xorshift32_cxx::cgul_random_xorshift32_cxx().
§ cgul_random_xorshift32__delete()
| CGUL_EXPORT void cgul_random_xorshift32__delete | ( | cgul_random_xorshift32_t | r | ) |
This method frees all internally allocated memory. Do not attempt to dereference r after calling this method.
- Parameters
-
[in] r cgul_random_xorshift32instance
Referenced by cgul_random_xorshift32_cxx::set_obj(), and cgul_random_xorshift32_cxx::~cgul_random_xorshift32_cxx().
§ cgul_random_xorshift32__allocate_seed_array()
| CGUL_EXPORT void cgul_random_xorshift32__allocate_seed_array | ( | cgul_exception_t * | cex, |
| cgul_uint32_t ** | v, | ||
| unsigned int * | v_count | ||
| ) |
This function allocates and returns an array of 32-bit seed values v where each element of the array is initialized to zero. The total number of 32-bit seed values in the array is returned in v_count. The caller should fill the array with true random values and create a new PRNG seeded with the values by calling cgul_random_xorshift32__new_from_seed_array(). The caller is responsible for calling free(*v). If an error occurs, an exception is thrown.
- Parameters
-
[in,out] cex c-style exception [out] v uninitialized array of 32-bit seed values [out] v_count count of the number of 32-bit values in v
Referenced by cgul_random_xorshift32_cxx::allocate_seed_array().
§ cgul_random_xorshift32__next()
| CGUL_EXPORT cgul_uint32_t cgul_random_xorshift32__next | ( | cgul_exception_t * | cex, |
| cgul_random_xorshift32_t | r | ||
| ) |
Return the next element in the pseudo-random number sequence. The random numbers returned are 32 bits wide and should have a period of (2^4096 - 1).
- Parameters
-
[in] cex c-style exception [in] r cgul_random_xorshift32instance
- Returns
- next element in the random number sequence
Referenced by cgul_random_xorshift32_cxx::next().
§ cgul_random_xorshift32__next_in_range()
| CGUL_EXPORT cgul_uint32_t cgul_random_xorshift32__next_in_range | ( | cgul_exception_t * | cex, |
| cgul_random_xorshift32_t | r, | ||
| cgul_uint32_t | range_max | ||
| ) |
If the value returned by cgul_random_xorshift32__next() is not the exact range that is needed, this method can limit the return value to [0, range_max). If range_max is zero, an exception is thrown.
This function should avoid the very small round off error associated with just scaling the value returned by cgul_random_xorshift32__next_in_unit(); however, this function is much slower.
- Parameters
-
[in,out] cex c-style exception [in] r cgul_random_xorshift32instance[in] range_max exclusive limit on the maximum value returned
- Returns
- next element in the random number sequence
Referenced by cgul_random_xorshift32_cxx::next_in_range().
§ cgul_random_xorshift32__next_in_unit()
| CGUL_EXPORT double cgul_random_xorshift32__next_in_unit | ( | cgul_exception_t * | cex, |
| cgul_random_xorshift32_t | r | ||
| ) |
Return the next element in the pseudo-random number sequence as type double on the range [0 - 1).
- Parameters
-
[in] cex c-style exception [in] r cgul_random_xorshift32instance
- Returns
- next element in the random number sequence
Referenced by cgul_random_xorshift32_cxx::next_in_unit().
