Refactor functions for generating pseudorandom numbers

kgryte · kgryte · commit d86cba9e90a8 · 2018-08-15T19:54:20.000-07:00
diff --git a/lib/node_modules/@stdlib/random/base/include/stdlib/random/base.h b/lib/node_modules/@stdlib/random/base/include/stdlib/random/base.h
@@ -21,6 +21,9 @@
 
 #include <stdint.h>
 
+// Forward declaration.
+struct BasePRNGObject;
+
 /**
 * Base PRNG structure.
 */
@@ -44,10 +47,10 @@ struct BasePRNG {
 	const size_t state_size;
 
 	// Define a pointer to a function for returning the next generated value:
-	uint64_t (* const next)( void *BasePRNGObject );
+	int8_t (* const next)( struct BasePRNGObject *obj, uint64_t *out );
 
 	// Define a pointer to a function for returning the next generated value on the interval `[0,1)`:
-	double (* const normalized)( void *BasePRNGObject );
+	int8_t (* const normalized)( struct BasePRNGObject *obj, double *out );
 };
 
 /**
diff --git a/lib/node_modules/@stdlib/random/base/minstd/benchmark/c/benchmark.c b/lib/node_modules/@stdlib/random/base/minstd/benchmark/c/benchmark.c
@@ -128,6 +128,7 @@ double benchmark1() {
 */
 double benchmark2() {
 	double elapsed;
+	int8_t status;
 	uint64_t max;
 	uint64_t v;
 	double t;
@@ -142,15 +143,15 @@ double benchmark2() {
 
 	t = tic();
 	for ( i = 0; i < ITERATIONS; i++ ) {
-		v = obj->prng->next( obj->state );
-		if ( v > max ) {
+		status = obj->prng->next( obj, &v );
+		if ( status != 0 || v > max ) {
 			printf( "unexpected result\n" );
 			break;
 		}
 	}
 	elapsed = tic() - t;
 
-	if ( v > max ) {
+	if ( status != 0 || v > max ) {
 		printf( "unexpected result\n" );
 	}
 	stdlib_base_minstd_prng_free( obj );
@@ -165,6 +166,7 @@ double benchmark2() {
 */
 double benchmark3() {
 	double elapsed;
+	int8_t status;
 	double v;
 	double t;
 	int i;
@@ -177,15 +179,15 @@ double benchmark3() {
 
 	t = tic();
 	for ( i = 0; i < ITERATIONS; i++ ) {
-		v = obj->prng->normalized( obj->state );
-		if ( v != v ) {
+		status = obj->prng->normalized( obj, &v );
+		if ( status != 0 || v != v ) {
 			printf( "unexpected result\n" );
 			break;
 		}
 	}
 	elapsed = tic() - t;
 
-	if ( v != v ) {
+	if ( status != 0 || v != v ) {
 		printf( "unexpected result\n" );
 	}
 	stdlib_base_minstd_prng_free( obj );
diff --git a/lib/node_modules/@stdlib/random/base/minstd/examples/c/example.c b/lib/node_modules/@stdlib/random/base/minstd/examples/c/example.c
@@ -24,7 +24,9 @@
 int main() {
 	int8_t status;
 	int32_t seed;
+	uint64_t v;
 	int32_t i;
+	double d;
 
 	// Create a PRNG...
 	struct BasePRNGObject *obj = stdlib_base_minstd_prng_allocate( 12345 );
@@ -46,7 +48,12 @@ int main() {
 
 	printf( "\nPseudorandom integers...\n" );
 	for ( i = 0; i < 10; i++ ) {
-		printf( "%llu\n", obj->prng->next( obj->state ) );
+		status = obj->prng->next( obj, &v );
+		if ( status != 0 ) {
+			printf( "Unexpected result.\n" );
+			exit( 1 );
+		}
+		printf( "%llu\n", v );
 	}
 
 	printf( "\n" );
@@ -55,7 +62,12 @@ int main() {
 
 	printf( "\nPseudorandom doubles...\n" );
 	for ( i = 0; i < 10; i++ ) {
-		printf( "%0.16f\n", obj->prng->normalized( obj->state ) );
+		status = obj->prng->normalized( obj, &d );
+		if ( status != 0 ) {
+			printf( "Unexpected result.\n" );
+			exit( 1 );
+		}
+		printf( "%0.16f\n", d );
 	}
 
 	stdlib_base_minstd_prng_free( obj );
diff --git a/lib/node_modules/@stdlib/random/base/minstd/src/main.c b/lib/node_modules/@stdlib/random/base/minstd/src/main.c
@@ -23,6 +23,10 @@
 #include "stdlib/random/base.h"
 #include "stdlib/random/base/minstd.h"
 
+// Forward declarations:
+static inline int8_t next( struct BasePRNGObject *obj, uint64_t *out );
+static inline int8_t normalized( struct BasePRNGObject *obj, double *out );
+
 // Define the LCG multiplier:
 static const uint32_t A = 16807;
 
@@ -32,57 +36,79 @@ static const uint32_t MAX_INT32 = 0x7fffffff;
 // Define the normalization constant:
 static const double NORMALIZATION_CONSTANT = 2147483646.0; // MAX_INT32 - 1
 
+/**
+* MINSTD PRNG.
+*
+* @private
+*/
+static const struct BasePRNG minstd_prng = {
+	"minstd",                                   // name
+	(uint64_t)1,                                // min
+	(uint64_t)MAX_INT32-1,                      // max: (2^{31}-1) - 1
+	0.0,                                        // min (normalized)
+	(MAX_INT32-2) / NORMALIZATION_CONSTANT,     // max (normalized): (MIN-1)/MAX
+	sizeof( stdlib_base_minstd_prng_state_t ),  // state_size
+	&next,                                      // next()
+	&normalized                                 // normalized()
+};
+
 /**
 * Returns a pseudorandom integer.
 *
+* ## Notes
+*
+* -   The function returns `-1` if unable to generate a pseudorandom integer and `0` otherwise.
+*
 * @private
-* @param vstate  PRNG state
-* @return        pseudorandom integer
+* @param obj  PRNG object
+* @param out  output address
+* @return     status code
 */
-static inline uint64_t next( void *vstate ) {
-	// Cast the "void state" argument to a MINSTD state object:
-	stdlib_base_minstd_prng_state_t *obj = (stdlib_base_minstd_prng_state_t *)( vstate );
+static inline int8_t next( struct BasePRNGObject *obj, uint64_t *out ) {
+	if ( obj == NULL || obj->prng != &minstd_prng ) {
+		return -1;
+	}
+	// Retrieve the MINSTD state object:
+	stdlib_base_minstd_prng_state_t *so = (stdlib_base_minstd_prng_state_t *)( obj->state );
 
 	// Retrieve the current state:
-	uint32_t state = obj->state;
+	uint32_t state = so->state;
 
 	// Explicitly cast to 64-bit to handle integer overflow:
 	state = (A*(uint64_t)state) % MAX_INT32;
 
 	// Update the PRNG state:
-	obj->state = state;
+	so->state = state;
 
-	// Return the generated value:
-	return (uint64_t)state;
+	// Set the output value:
+	*out = (uint64_t)state;
+
+	return 0;
 }
 
 /**
 * Returns a pseudorandom double-precision floating-point number on the interval `[0,1)`.
 *
-* @private
-* @param vstate  PRNG state
-* @return        pseudorandom number
-*/
-static inline double normalized( void *vstate ) {
-	double state = (double)next( vstate );
-	return (state-1.0) / NORMALIZATION_CONSTANT;
-}
-
-/**
-* MINSTD PRNG.
+* ## Notes
+*
+* -   The function returns `-1` if unable to generate a pseudorandom number and `0` otherwise.
 *
 * @private
+* @param obj  PRNG object
+* @param out  output address
+* @return     status code
 */
-static const struct BasePRNG minstd_prng = {
-	"minstd",                                   // name
-	(uint64_t)1,                                // min
-	(uint64_t)MAX_INT32-1,                      // max: (2^{31}-1) - 1
-	0.0,                                        // min (normalized)
-	(MAX_INT32-2) / NORMALIZATION_CONSTANT,     // max (normalized): (MIN-1)/MAX
-	sizeof( stdlib_base_minstd_prng_state_t ),  // state_size
-	&next,                                      // next()
-	&normalized                                 // normalized()
-};
+static inline int8_t normalized( struct BasePRNGObject *obj, double *out ) {
+	uint64_t state;
+	int8_t status = next( obj, &state );
+	if ( status != 0 ) {
+		return -1;
+	}
+	// Note: casting `state` to a double here is fine, as `state` will never exceed the maximum "safe" double-precision floating-point number:
+	*out = ((double)state-1.0) / NORMALIZATION_CONSTANT;
+
+	return 0;
+}
 
 /**
 * Returns a pointer to a dynamically allocated MINSTD PRNG.
@@ -109,12 +135,20 @@ static const struct BasePRNG minstd_prng = {
 *     exit( 1 );
 * }
 *
-* uint64_t r = obj->prng->next( obj->state );
+* uint64_t r;
+* int8_t status = obj->prng->next( obj, &r );
+* if ( status != 0 ) {
+*     fprintf( stderr, "Unexpected result.\n" );
+*     exit( 1 );
+* }
+*
+* // ...
+*
+* status = obj->prng->next( obj, &r );
 *
 * // ...
 *
-* r = obj->prng->next( obj->state );
-* r = obj->prng->next( obj->state );
+* status = obj->prng->next( obj, &r );
 *
 * // ...
 *
@@ -171,12 +205,20 @@ struct BasePRNGObject * stdlib_base_minstd_prng_allocate( const int32_t seed ) {
 *     exit( 1 );
 * }
 *
-* uint64_t r = obj->prng->next( obj->state );
+* uint64_t r;
+* int8_t status = obj->prng->next( obj, &r );
+* if ( status != 0 ) {
+*     fprintf( stderr, "Unexpected result.\n" );
+*     exit( 1 );
+* }
+*
+* // ...
+*
+* status = obj->prng->next( obj, &r );
 *
 * // ...
 *
-* r = obj->prng->next( obj->state );
-* r = obj->prng->next( obj->state );
+* status = obj->prng->next( obj, &r );
 *
 * // ...
 *
@@ -314,12 +356,20 @@ void * stdlib_base_minstd_prng_state( const struct BasePRNGObject *obj ) {
 *     exit( 1 );
 * }
 *
-* uint64_t r = obj->prng->next( obj->state );
+* uint64_t r;
+* int8_t status = obj->prng->next( obj, &r );
+* if ( status != 0 ) {
+*     fprintf( stderr, "Unexpected result.\n" );
+*     exit( 1 );
+* }
+*
+* // ...
+*
+* status = obj->prng->next( obj, &r );
 *
 * // ...
 *
-* r = obj->prng->next( obj->state );
-* r = obj->prng->next( obj->state );
+* status = obj->prng->next( obj, &r );
 *
 * // ...
 *
@@ -332,22 +382,28 @@ void * stdlib_base_minstd_prng_state( const struct BasePRNGObject *obj ) {
 *
 * // ...
 *
-* r = obj->prng->next( obj->state );
-* r = obj->prng->next( obj->state );
+* status = obj->prng->next( obj, &r );
+*
+* // ...
+*
+* status = obj->prng->next( obj, &r );
 *
 * // ...
 *
 * // Reset the PRNG to a previous state...
-* int8_t status = stdlib_base_minstd_prng_set( obj, state );
+* status = stdlib_base_minstd_prng_set( obj, state );
 * if ( status != 0 ) {
 *     fprintf( stderr, "Error encountered when attempting to set PRNG state.\n" );
 *     exit( 1 );
 * }
 *
 * // ...
 *
-* r = obj->prng->next( obj->state );
-* r = obj->prng->next( obj->state );
+* status = obj->prng->next( obj, &r );
+*
+* // ...
+*
+* status = obj->prng->next( obj, &r );
 *
 * // ...
 *
