main.c

/**
* @license Apache-2.0
*
* Copyright (c) 2018 The Stdlib Authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*    http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

// Note: keep project includes in alphabetical order...
#include <stdlib.h>
#include <stdint.h>
#include <string.h>
#include "stdlib/random/base.h"
#include "stdlib/random/base/minstd.h"

// Define the LCG multiplier:
static const uint32_t A = 16807;

// Define the maximum signed 32-bit integer: 2147483647 => 0x7fffffff => 01111111111111111111111111111111
static const uint32_t MAX_INT32 = 0x7fffffff;

// Define the normalization constant:
static const double NORMALIZATION_CONSTANT = 2147483646.0; // MAX_INT32 - 1

/**
* Returns a pseudorandom integer.
*
* @private
* @param vstate  PRNG state
* @return        pseudorandom integer
*/
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 );

	// Retrieve the current state:
	uint32_t state = obj->state;

	// Explicitly cast to 64-bit to handle integer overflow:
	state = (A*(uint64_t)state) % MAX_INT32;

	// Update the PRNG state:
	obj->state = state;

	// Return the generated value:
	return (uint64_t)state;
}

/**
* 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.
*
* @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 pointer to a dynamically allocated MINSTD PRNG.
*
* ## Notes
*
* -   The user is responsible for freeing the allocated memory.
* -   A provided `seed` is mapped to the interval `[1,2147483646]`.
*
* @param seed  PRNG seed
* @return      pointer to a dynamically allocated PRNG or, if unable to allocate memory, a null pointer
*
* @example
* #include <stdlib.h>
* #include <stdio.h>
* #include <stdint.h>
* #include "stdlib/random/base.h"
* #include "stdlib/random/base/minstd.h"
*
* // Create a MINSTD PRNG:
* struct BasePRNGObject *obj = stdlib_base_minstd_prng_allocate( 12345 );
* if ( obj == NULL ) {
*     fprintf( stderr, "Error allocating memory.\n" );
*     exit( 1 );
* }
*
* uint64_t r = obj->prng->next( obj->state );
*
* // ...
*
* r = obj->prng->next( obj->state );
* r = obj->prng->next( obj->state );
*
* // ...
*
* // Free allocated memory:
* stdlib_base_minstd_prng_free( obj );
*/
struct BasePRNGObject * stdlib_base_minstd_prng_allocate( const int32_t seed ) {
	uint32_t iseed;

	struct BasePRNGObject *obj = malloc( sizeof( struct BasePRNGObject ) );
	if ( obj == NULL ) {
		return NULL;
	}
	stdlib_base_minstd_prng_state_t *state = malloc( sizeof( stdlib_base_minstd_prng_state_t ) );
	if ( state == NULL ) {
		free( obj ); // prevent memory leaks
		return NULL;
	}
	// Ensure that the provided seed is within allowed bounds...
	if ( seed == 0 ) {
		iseed = 1;
	} else if ( seed == MAX_INT32 ) {
		iseed = MAX_INT32 - 1;
	} else if ( seed < 0 ) {
		iseed = -seed;
	} else {
		iseed = seed;
	}
	state->seed = (uint32_t)iseed;
	state->state = (uint32_t)iseed;

	obj->prng = &minstd_prng;
	obj->state = state;

	return obj;
}

/**
* Frees a MINSTD PRNG's allocated memory.
*
* @param obj  PRNG object
*
* @example
* #include <stdlib.h>
* #include <stdio.h>
* #include <stdint.h>
* #include "stdlib/random/base.h"
* #include "stdlib/random/base/minstd.h"
*
* // Create a MINSTD PRNG:
* struct BasePRNGObject *obj = stdlib_base_minstd_prng_allocate( 12345 );
* if ( obj == NULL ) {
*     fprintf( stderr, "Error allocating memory.\n" );
*     exit( 1 );
* }
*
* uint64_t r = obj->prng->next( obj->state );
*
* // ...
*
* r = obj->prng->next( obj->state );
* r = obj->prng->next( obj->state );
*
* // ...
*
* // Free allocated memory:
* stdlib_base_minstd_prng_free( obj );
*/
void stdlib_base_minstd_prng_free( struct BasePRNGObject *obj ) {
	if ( obj == NULL || obj->prng != &minstd_prng ) {
		return;
	}
	free( obj->state );
	free( obj );
}

/**
* Returns a MINSTD PRNG seed.
*
* ## Notes
*
* -   The function returns `-1` if unable to resolve a PRNG seed and `0` otherwise.
*
* @param obj  PRNG object
* @param out  output address
* @return     status code
*
* @example
* #include <stdlib.h>
* #include <stdio.h>
* #include <stdint.h>
* #include "stdlib/random/base.h"
* #include "stdlib/random/base/minstd.h"
*
* // Create a MINSTD PRNG:
* struct BasePRNGObject *obj = stdlib_base_minstd_prng_allocate( 12345 );
* if ( obj == NULL ) {
*     fprintf( stderr, "Error allocating memory.\n" );
*     exit( 1 );
* }
*
* int32_t seed;
* int8_t status = stdlib_base_minstd_prng_seed( obj, &seed );
* if ( status != 0 ) {
*     fprintf( stderr, "Error encountered when attempting to retrieve the PRNG seed.\n" );
*     exit( 1 );
* }
*
* // Use the seed to, e.g., create another PRNG which will generate the same sequence...
*
* // Free allocated memory:
* stdlib_base_minstd_prng_free( obj );
*/
int8_t stdlib_base_minstd_prng_seed( const struct BasePRNGObject *obj, int32_t *out ) {
	if ( obj == NULL || obj->prng != &minstd_prng ) {
		return -1;
	}
	// Retrieve the MINSTD state object:
	const stdlib_base_minstd_prng_state_t *state = (stdlib_base_minstd_prng_state_t *)( obj->state );

	// Set the output value:
	*out = (int32_t)( state->seed );

	return 0;
}

/**
* Returns a **copy** of the current MINSTD PRNG state.
*
* ## Notes
*
* -   The user is responsible for freeing the allocated memory.
*
* @param obj  PRNG object
* @return     pointer to a copy of the PRNG's internal state
*
* @example
* #include <stdlib.h>
* #include <stdio.h>
* #include <stdint.h>
* #include "stdlib/random/base.h"
* #include "stdlib/random/base/minstd.h"
*
* // Create a MINSTD PRNG:
* struct BasePRNGObject *obj = stdlib_base_minstd_prng_allocate( 12345 );
* if ( obj == NULL ) {
*     fprintf( stderr, "Error allocating memory.\n" );
*     exit( 1 );
* }
*
* void *state = stdlib_base_minstd_prng_state( obj );
* if ( state == NULL ) {
*     fprintf( stderr, "Unable to retrieve PRNG state.\n" );
*     exit( 1 );
* }
*
* // Use the captured state to, e.g., sync another MINSTD PRNG or to reset a PRNG to a particular state in order to "replay" generated values at a later point in time...
*
* // Free allocated memory:
* stdlib_base_minstd_prng_free( obj );
*/
void * stdlib_base_minstd_prng_state( const struct BasePRNGObject *obj ) {
	if ( obj == NULL || obj->prng != &minstd_prng ) {
		return NULL;
	}
	void *state = malloc( obj->prng->state_size );
	if ( state == NULL ) {
		return NULL;
	}
	memcpy( state, obj->state, obj->prng->state_size );
	return state;
}

/**
* Sets the MINSTD PRNG state.
*
* ## Notes
*
* -   The function returns `-1` if unable to set a PRNG state and `0` otherwise.
*
* @param obj    PRNG object
* @param state  state
* @return       status code
*
* @example
* #include <stdlib.h>
* #include <stdio.h>
* #include <stdint.h>
* #include "stdlib/random/base.h"
* #include "stdlib/random/base/minstd.h"
*
* // Create a MINSTD PRNG:
* struct BasePRNGObject *obj = stdlib_base_minstd_prng_allocate( 12345 );
* if ( obj == NULL ) {
*     fprintf( stderr, "Error allocating memory.\n" );
*     exit( 1 );
* }
*
* uint64_t r = obj->prng->next( obj->state );
*
* // ...
*
* r = obj->prng->next( obj->state );
* r = obj->prng->next( obj->state );
*
* // ...
*
* // Retrieve the current PRNG state...
* void *state = stdlib_base_minstd_prng_state( obj );
* if ( state == NULL ) {
*     fprintf( stderr, "Error encountered when attempting to retrieve PRNG state.\n" );
*     exit( 1 );
* }
*
* // ...
*
* r = obj->prng->next( obj->state );
* r = obj->prng->next( obj->state );
*
* // ...
*
* // Reset the PRNG to a previous state...
* int8_t 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 );
*
* // ...
*
* // Free allocated memory:
* stdlib_base_minstd_prng_free( obj );
*/
int8_t stdlib_base_minstd_prng_set( struct BasePRNGObject *obj, const void *vstate ) {
	if ( obj == NULL || vstate == NULL || obj->prng != &minstd_prng ) {
		return -1;
	}
	memcpy( obj->state, vstate, obj->prng->state_size );
	return 0;
}