time-to-botec

main.c (25696B)

---

 /**
 * @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.
 *
 *
 * ## Notice
 *
 * The original C code and copyright notice are from the [source implementation]{@link http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/MT2002/CODES/mt19937ar.c}. The implementation has been modified according to the styles and conventions of this project.
 *
 * ```text
 * Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura,
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 *   1. Redistributions of source code must retain the above copyright
 *      notice, this list of conditions and the following disclaimer.
 *
 *   2. Redistributions in binary form must reproduce the above copyright
 *      notice, this list of conditions and the following disclaimer in the
 *      documentation and/or other materials provided with the distribution.
 *
 *   3. The names of its contributors may not be used to endorse or promote
 *      products derived from this software without specific prior written
 *      permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * ```
 */
 
 // 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/mt19937.h"
 
 // Forward declarations:
 static inline int8_t next( struct BasePRNGObject *obj, uint64_t *out );
 static inline int8_t normalized( struct BasePRNGObject *obj, double *out );
 static inline void mt19937_free( struct BasePRNGObject *obj );
 
 static inline void create_state( uint32_t *state, const int32_t N, const uint32_t s );
 static inline void init_state( uint32_t *state, const int32_t N, const uint32_t *seed, const int64_t M );
 static inline void twist( uint32_t *state, const int32_t N );
 
 // Define the size of the state array (see refs):
 static const int32_t N = 624;
 
 // Define a (magic) constant used for indexing into the state array:
 static const int32_t M = 397;
 
 // Define an initial state (magic) constant: 19650218 => 00000001001010111101011010101010
 static const uint32_t SEED_ARRAY_INIT_STATE = 19650218;
 
 // Define a mask for the most significant `w-r` bits, where `w` is the word size (32 bits) and `r` is the separation point of one word (see refs): 2147483648 => 0x80000000 => 10000000000000000000000000000000
 static const uint32_t UPPER_MASK = 0x80000000;
 
 // Define a mask for the least significant `r` bits (see refs): 2147483647 => 0x7fffffff => 01111111111111111111111111111111
 static const uint32_t LOWER_MASK = 0x7fffffff;
 
 // Define a multiplier (see Knuth TAOCP Vol2. 3rd Ed. P.106): 1812433253 => 01101100000001111000100101100101
 static const uint32_t KNUTH_MULTIPLIER = 1812433253;
 
 // Define a (magic) multiplier: 1664525 => 00000000000110010110011000001101
 static const uint32_t MAGIC_MULTIPLIER_1 = 1664525;
 
 // Define a (magic) multiplier: 1566083941 => 01011101010110001000101101100101
 static const uint32_t MAGIC_MULTIPLIER_2 = 1566083941;
 
 // Define a tempering coefficient: 2636928640 => 0x9d2c5680 => 10011101001011000101011010000000
 static const uint32_t TEMPERING_COEFFICIENT_1 = 0x9d2c5680;
 
 // Define a tempering coefficient: 4022730752 => 0xefc60000 => 11101111110001100000000000000000
 static const uint32_t TEMPERING_COEFFICIENT_2 = 0xefc60000;
 
 // Define a constant vector `a` (see refs): 2567483615 => 0x9908b0df => 10011001000010001011000011011111
 static const uint32_t MATRIX_A = 0x9908b0df;
 
 // MAG01[x] = x * MATRIX_A; for x = {0,1}
 static const uint32_t MAG01[2] = { 0x0, MATRIX_A };
 
 // Define the maximum unsigned 32-bit integer: 4294967295 => 11111111111111111111111111111111
 static const uint32_t MAX_UINT32 = 4294967295;
 
 // Define the maximum "safe" double-precision floating-point integer:
 static const double FLOAT64_MAX_SAFE_INTEGER = 9007199254740991.0;
 
 // Define a normalization constant when generating double-precision floating-point numbers: 2^53 => 9007199254740992
 static const double FLOAT64_NORMALIZATION_CONSTANT = 1.0 / ( FLOAT64_MAX_SAFE_INTEGER+1.0 );
 
 // 2^26: 67108864
 static const double TWO_26 = 67108864.0;
 
 // 2^32: 2147483648 => 0x80000000 => 10000000000000000000000000000000
 static const uint32_t TWO_32 = 0x80000000;
 
 // 1 (as a 32-bit unsigned integer): 1 => 0x1 => 00000000000000000000000000000001
 static const uint32_t ONE = 0x1;
 
 // Define the maximum normalized pseudorandom double-precision floating-point number: ( (((2^32-1)>>>5)*2^26)+( (2^32-1)>>>6) ) / 2^53
 static const double MAX_NORMALIZED = FLOAT64_MAX_SAFE_INTEGER * FLOAT64_NORMALIZATION_CONSTANT;
 
 /**
 * MT19937 PRNG.
 *
 * @private
 */
 static const struct BasePRNG mt19937_prng = {
 	"mt19937",                                            // name
 	(uint64_t)1,                                          // min
 	(uint64_t)MAX_UINT32,                                 // max: (2^{32}-1)
 	0.0,                                                  // min (normalized)
 	MAX_NORMALIZED,                                       // max (normalized): (2^{53}-1)/2^{53}
 	sizeof( stdlib_base_random_mt19937_state_t ),         // state_size
 	&next,                                                // next()
 	&normalized,                                          // normalized()
 	&mt19937_free                                         // free()
 };
 
 /**
 * Returns a pseudorandom integer.
 *
 * ## Notes
 *
 * -   The function returns `-1` if unable to generate a pseudorandom integer and `0` otherwise.
 *
 * ## References
 *
 * -   Matsumoto, Makoto, and Takuji Nishimura. 1998. "Mersenne Twister: A 623-dimensionally Equidistributed Uniform Pseudo-random Number Generator." _ACM Transactions on Modeling and Computer Simulation_ 8 (1). New York, NY, USA: ACM: 3–30. doi:[10.1145/272991.272995][@matsumoto:1998a].
 *
 * @private
 * @param obj  PRNG object
 * @param out  output address
 * @return     status code
 */
 static inline int8_t next( struct BasePRNGObject *obj, uint64_t *out ) {
 	stdlib_base_random_mt19937_state_t *so;
 	uint32_t *state;
 	uint32_t r;
 	int32_t i;
 	if ( obj == NULL || obj->prng != &mt19937_prng ) {
 		return -1;
 	}
 	// Retrieve the state object:
 	so = (stdlib_base_random_mt19937_state_t *)( obj->state );
 
 	// Retrieve the current state and current state index:
 	state = so->state;
 	i = so->i;
 
 	// Determine if we need to update our internal state array:
 	if ( i >= N ) {
 		twist( so->state, N );
 		i = 0;
 	}
 	// Get the next state value:
 	r = so->state[ i ];
 
 	// Update the state index:
 	so->i = i + 1;
 
 	// Tempering transform to compensate for the reduced dimensionality of equidistribution:
 	r ^= r >> 11;
 	r ^= ( r << 7 ) & TEMPERING_COEFFICIENT_1;
 	r ^= ( r << 15 ) & TEMPERING_COEFFICIENT_2;
 	r ^= r >> 18;
 
 	// Set the output value:
 	*out = (uint64_t)( r );
 
 	return 0;
 }
 
 /**
 * Returns a pseudorandom double-precision floating-point number on the interval `[0,1)`.
 *
 * ## Method
 *
 * -   When generating normalized double-precision floating-point numbers, we first generate two pseudorandom integers \\( x \\) and \\( y \\) on the interval \\( [1,2^{32}-1) \\) for a combined \\( 64 \\) random bits.
 *
 * -   We would like \\( 53 \\) random bits to generate a 53-bit precision integer and, thus, want to discard \\( 11 \\) of the generated bits.
 *
 * -   We do so by discarding \\( 5 \\) bits from \\( x \\) and \\( 6 \\) bits from \\( y \\).
 *
 * -   Accordingly, \\( x \\) contains \\( 27 \\) random bits, which are subsequently shifted left \\( 26 \\) bits (multiplied by \\( 2^{26} \\), and \\( y \\) contains \\( 26 \\) random bits to fill in the lower \\( 26 \\) bits. When summed, they combine to comprise \\( 53 \\) random bits of a double-precision floating-point integer.
 *
 * -   As an example, suppose, for the sake of argument, the 32-bit PRNG generates the maximum unsigned 32-bit integer \\( 2^{32}-1 \\) twice in a row. Then,
 *
 *     ```c
 *     uint32_t x = 4294967295 >> 5; // 00000111111111111111111111111111
 *     uint32_t y = 4294967295 >> 6; // 00000011111111111111111111111111
 *     ```
 *
 *     Multiplying \\( x \\) by \\( 2^{26} \\) returns \\( 9007199187632128 \\), which, in binary, is
 *
 *     ```binarystring
 *     0 10000110011 11111111111111111111 11111100000000000000000000000000
 *     ```
 *
 *     Adding \\( y \\) yields \\( 9007199254740991 \\) (the maximum "safe" double-precision floating-point integer value), which, in binary, is
 *
 *     ```binarystring
 *     0 10000110011 11111111111111111111 11111111111111111111111111111111
 *     ```
 *
 * -   Similarly, suppose the 32-bit PRNG generates the following values
 *
 *     ```c
 *     uint32_t x = 1 >> 5;  // 0 => 00000000000000000000000000000000
 *     uint32_t y = 64 >> 6; // 1 => 00000000000000000000000000000001
 *     ```
 *
 *     Multiplying \\( x \\) by \\( 2^{26} \\) returns \\( 0 \\), which, in binary, is
 *
 *     ```binarystring
 *     0 00000000000 00000000000000000000 00000000000000000000000000000000
 *     ```
 *
 *     Adding \\( y \\) yields \\( 1 \\), which, in binary, is
 *
 *     ```binarystring
 *     0 01111111111 00000000000000000000 00000000000000000000000000000000
 *     ```
 *
 * -   As different combinations of \\( x \\) and \\( y \\) are generated, different combinations of double-precision floating-point exponent and significand bits will be toggled, thus generating pseudorandom double-precision floating-point numbers.
 *
 * ## Notes
 *
 * -   The function returns `-1` if unable to generate a pseudorandom number and `0` otherwise.
 *
 * ## References
 *
 * -   Harase, Shin. 2017. "Conversion of Mersenne Twister to double-precision floating-point numbers." _ArXiv_ abs/1708.06018 (September). <https://arxiv.org/abs/1708.06018>.
 *
 * @private
 * @param obj  PRNG object
 * @param out  output address
 * @return     status code
 */
 static inline int8_t normalized( struct BasePRNGObject *obj, double *out ) {
 	uint64_t x;
 	uint64_t y;
 	if ( obj == NULL || obj->prng != &mt19937_prng ) {
 		return -1;
 	}
 	next( obj, &x);
 	x >>= 5;
 
 	next( obj, &y );
 	y >>= 6;
 
 	// Note: casting `x` and `y` to doubles here is fine, as neither will ever exceed the maximum "safe" double-precision floating-point number:
 	*out = ( ((double)x*TWO_26)+(double)y ) * FLOAT64_NORMALIZATION_CONSTANT;
 
 	return 0;
 }
 
 /**
 * Frees a PRNG's allocated memory.
 *
 * @private
 * @param obj  PRNG object
 */
 static inline void mt19937_free( struct BasePRNGObject *obj ) {
 	if ( obj == NULL || obj->prng != &mt19937_prng ) {
 		return;
 	}
 	stdlib_base_random_mt19937_state_t *state = (stdlib_base_random_mt19937_state_t *)( obj->state );
 	free( state->seed );
 	free( obj->state );
 	free( obj );
 }
 
 /**
 * Returns an initial PRNG state.
 *
 * @private
 * @param state  pointer to state array
 * @param N      state array length
 * @param s      seed
 */
 static inline void create_state( uint32_t *state, const int32_t N, const uint32_t s ) {
 	int32_t i;
 
 	// Set the first element of the state array to the provided seed:
 	state[ 0 ] = s;
 
 	// Initialize the remaining state array elements:
 	for ( i = 1; i < N; i++ ) {
 		state[ i ] = (KNUTH_MULTIPLIER * (state[i-1] ^ (state[i-1]>>30)) + i);
 	}
 }
 
 /**
 * Initializes a PRNG state array according to a seed array.
 *
 * @private
 * @param state  pointer to state array
 * @param N      state array length
 * @param seed   pointer to seed array
 * @param M      seed array length
 */
 static inline void init_state( uint32_t *state, const int32_t N, const uint32_t *seed, const int64_t M ) {
 	int32_t i;
 	int64_t j;
 	int64_t k;
 
 	i = 1;
 	j = 0;
 	k = ( N > M ) ? N : M;
 	for ( ; k > 0; k-- ) {
 		state[ i ] = (state[i]^((state[i-1]^(state[i-1]>>30))*MAGIC_MULTIPLIER_1)) + seed[j] + j;
 		i += 1;
 		j += 1;
 		if ( i >= N ) {
 			state[ 0 ] = state[ N-1 ];
 			i = 1;
 		}
 		if ( j >= M ) {
 			j = 0;
 		}
 	}
 	for ( k = N-1; k > 0; k-- ) {
 		state[ i ] = (state[i]^((state[i-1]^(state[i-1]>>30))*MAGIC_MULTIPLIER_2)) - i;
 		i += 1;
 		if ( i >= N ) {
 			state[ 0 ] = state[ N-1 ];
 			i = 1;
 		}
 	}
 	// Ensure a non-zero initial state array:
 	state[ 0 ] = TWO_32; // MSB (most significant bit) is 1
 }
 
 /**
 * Updates a PRNG's internal state by generating the next `N` words.
 *
 * @private
 * @param state  pointer to a PRNG's internal state array
 * @param N      state array length
 */
 static inline void twist( uint32_t *state, const int32_t N ) {
 	uint32_t w;
 	int32_t i;
 	int32_t j;
 	int32_t k;
 
 	k = N - M;
 	for ( i = 0; i < k; i++ ) {
 		w = ( state[i]&UPPER_MASK ) | ( state[i+1]&LOWER_MASK );
 		state[ i ] = state[ i+M ] ^ ( w>>1 ) ^ MAG01[ w&ONE ];
 	}
 	j = N - 1;
 	for ( ; i < j; i++ ) {
 		w = ( state[i]&UPPER_MASK ) | ( state[i+1]&LOWER_MASK );
 		state[ i ] = state[ i-k ] ^ ( w>>1 ) ^ MAG01[ w&ONE ];
 	}
 	w = ( state[j]&UPPER_MASK ) | ( state[0]&LOWER_MASK );
 	state[ j ] = state[ M-1 ] ^ ( w>>1 ) ^ MAG01[ w&ONE ];
 }
 
 /**
 * Returns a pointer to a dynamically allocated PRNG.
 *
 * ## Notes
 *
 * -   The user is responsible for freeing the allocated memory.
 *
 * @param seed  pointer to a seed array
 * @param len   seed array length
 * @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/mt19937.h"
 *
 * // Define a PRNG seed:
 * uint32_t seed[] = { 12345 };
 *
 * // Create a PRNG:
 * struct BasePRNGObject *obj = stdlib_base_random_mt19937_allocate( seed, 1 );
 * if ( obj == NULL ) {
 *     fprintf( stderr, "Error allocating memory.\n" );
 *     exit( 1 );
 * }
 *
 * 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 );
 *
 * // ...
 *
 * status = obj->prng->next( obj, &r );
 *
 * // ...
 *
 * // Free allocated memory:
 * stdlib_base_random_mt19937_free( obj );
 */
 struct BasePRNGObject * stdlib_base_random_mt19937_allocate( const uint32_t *seed, const int64_t len ) {
 	stdlib_base_random_mt19937_state_t *state;
 	struct BasePRNGObject *obj;
 	uint32_t *iseed;
 
 	obj = malloc( sizeof( struct BasePRNGObject ) );
 	if ( obj == NULL ) {
 		return NULL;
 	}
 	state = malloc( sizeof( stdlib_base_random_mt19937_state_t ) );
 	if ( state == NULL ) {
 		free( obj ); // prevent memory leaks
 		return NULL;
 	}
 	obj->prng = &mt19937_prng;
 	obj->state = state;
 
 	// Create an internal copy of the provided seed array to prevent the inability to reproduce PRNG values based on the PRNG's stated seed due to external state mutation:
 	iseed = (uint32_t *)malloc( sizeof( uint32_t )*len );
 	if ( iseed == NULL ) {
 		free( obj ); // prevent memory leaks
 		free( state );
 		return NULL;
 	}
 	memcpy( iseed, seed, sizeof( uint32_t )*len );
 	state->seed = iseed;
 	state->seed_length = len;
 
 	// Initialize the PRNG state:
 	create_state( state->state, N, SEED_ARRAY_INIT_STATE );
 	init_state( state->state, N, iseed, len );
 
 	// Set the state index which determines when we need to update the PRNG's internal state:
 	state->i = N;
 
 	return obj;
 }
 
 /**
 * Frees a 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/mt19937.h"
 *
 * // Define a PRNG seed:
 * uint32_t seed[] = { 12345 };
 *
 * // Create a PRNG:
 * struct BasePRNGObject *obj = stdlib_base_random_mt19937_allocate( seed, 1 );
 * if ( obj == NULL ) {
 *     fprintf( stderr, "Error allocating memory.\n" );
 *     exit( 1 );
 * }
 *
 * 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 );
 *
 * // ...
 *
 * status = obj->prng->next( obj, &r );
 *
 * // ...
 *
 * // Free allocated memory:
 * stdlib_base_random_mt19937_free( obj );
 */
 void stdlib_base_random_mt19937_free( struct BasePRNGObject *obj ) {
 	if ( obj == NULL || obj->prng != &mt19937_prng ) {
 		return;
 	}
 	obj->prng->free( obj );
 }
 
 /**
 * Returns the PRNG seed length.
 *
 * ## Notes
 *
 * -   The function returns `-1` if unable to resolve a PRNG seed length and `0` otherwise.
 *
 * @param obj   PRNG object
 * @param len   output address
 * @return      status code
 *
 * @example
 * #include <stdlib.h>
 * #include <stdio.h>
 * #include <stdint.h>
 * #include "stdlib/random/base.h"
 * #include "stdlib/random/base/mt19937.h"
 *
 * // Define a PRNG seed:
 * uint32_t seed1[] = { 12345 };
 *
 * // Create a PRNG:
 * struct BasePRNGObject *obj = stdlib_base_random_mt19937_allocate( seed1, 1 );
 * if ( obj == NULL ) {
 *     fprintf( stderr, "Error allocating memory.\n" );
 *     exit( 1 );
 * }
 *
 * // ...
 *
 * // Get the seed length:
 * int64_t seed_length;
 * int8_t status = stdlib_base_random_mt19937_seed_length( obj, &seed_length );
 * if ( status != 0 ) {
 *     fprintf( stderr, "Error encountered when attempting to retrieve the PRNG seed length.\n" );
 *     exit( 1 );
 * }
 *
 * // Get the PRNG seed:
 * uint32_t *seed2 = (uint32_t *)malloc( sizeof( uint32_t )*seed_length );
 * if ( seed2 == NULL ) {
 *     fprintf( stderr, "Error allocating memory.\n" );
 *     exit( 1 );
 * }
 * status = stdlib_base_random_mt19937_seed( obj, seed2 );
 * 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_random_mt19937_free( obj );
 * free( seed2 );
 */
 int8_t stdlib_base_random_mt19937_seed_length( const struct BasePRNGObject *obj, int64_t *len ) {
 	if ( obj == NULL || obj->prng != &mt19937_prng ) {
 		return -1;
 	}
 	// Retrieve the state object:
 	const stdlib_base_random_mt19937_state_t *state = (stdlib_base_random_mt19937_state_t *)( obj->state );
 
 	// Set the seed length:
 	*len = (int64_t)( state->seed_length );
 
 	return 0;
 }
 
 /**
 * Returns a PRNG seed.
 *
 * ## Notes
 *
 * -   The function returns `-1` if unable to resolve a PRNG seed and `0` otherwise.
 *
 * @param obj   PRNG object
 * @param seed  output address
 * @return      status code
 *
 * @example
 * #include <stdlib.h>
 * #include <stdio.h>
 * #include <stdint.h>
 * #include "stdlib/random/base.h"
 * #include "stdlib/random/base/mt19937.h"
 *
 * // Define a PRNG seed:
 * uint32_t seed1[] = { 12345 };
 *
 * // Create a PRNG:
 * struct BasePRNGObject *obj = stdlib_base_random_mt19937_allocate( seed1, 1 );
 * if ( obj == NULL ) {
 *     fprintf( stderr, "Error allocating memory.\n" );
 *     exit( 1 );
 * }
 *
 * // ...
 *
 * // Get the seed length:
 * int64_t seed_length;
 * int8_t status = stdlib_base_random_mt19937_seed_length( obj, &seed_length );
 * if ( status != 0 ) {
 *     fprintf( stderr, "Error encountered when attempting to retrieve the PRNG seed length.\n" );
 *     exit( 1 );
 * }
 *
 * // Get the PRNG seed:
 * uint32_t *seed2 = (uint32_t *)malloc( sizeof( uint32_t )*seed_length );
 * if ( seed2 == NULL ) {
 *     fprintf( stderr, "Error allocating memory.\n" );
 *     exit( 1 );
 * }
 * status = stdlib_base_random_mt19937_seed( obj, seed2 );
 * 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_random_mt19937_free( obj );
 * free( seed2 );
 */
 int8_t stdlib_base_random_mt19937_seed( const struct BasePRNGObject *obj, uint32_t *seed ) {
 	if ( obj == NULL || obj->prng != &mt19937_prng ) {
 		return -1;
 	}
 	// Retrieve the state object:
 	const stdlib_base_random_mt19937_state_t *state = (stdlib_base_random_mt19937_state_t *)( obj->state );
 
 	// Copy the seed array:
 	memcpy( seed, state->seed, sizeof( uint32_t )*(state->seed_length) );
 
 	return 0;
 }
 
 /**
 * Returns a **copy** of the current 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 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/mt19937.h"
 *
 * // Define a PRNG seed:
 * uint32_t seed[] = { 12345 };
 *
 * // Create a PRNG:
 * struct BasePRNGObject *obj = stdlib_base_random_mt19937_allocate( seed, 1 );
 * if ( obj == NULL ) {
 *     fprintf( stderr, "Error allocating memory.\n" );
 *     exit( 1 );
 * }
 *
 * stdlib_base_random_mt19937_state_t *state = (stdlib_base_random_mt19937_state_t *)stdlib_base_random_mt19937_state( obj );
 * if ( state == NULL ) {
 *     fprintf( stderr, "Unable to retrieve PRNG state.\n" );
 *     exit( 1 );
 * }
 *
 * // Use the captured state to, e.g., sync another 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_random_mt19937_free( obj );
 *
 * free( state->seed );
 * free( state );
 */
 void * stdlib_base_random_mt19937_state( const struct BasePRNGObject *obj ) {
 	stdlib_base_random_mt19937_state_t *state;
 	stdlib_base_random_mt19937_state_t *so;
 	uint64_t nbytes;
 	uint32_t *seed;
 	if ( obj == NULL || obj->prng != &mt19937_prng ) {
 		return NULL;
 	}
 	state = (stdlib_base_random_mt19937_state_t *)malloc( obj->prng->state_size );
 	if ( state == NULL ) {
 		return NULL;
 	}
 	nbytes = sizeof( uint32_t ) * (state->seed_length);
 	seed = (uint32_t *)malloc( nbytes );
 	if ( seed == NULL ) {
 		free( state ); // prevent memory leaks
 		return NULL;
 	}
 	// Copy the state:
 	memcpy( state, obj->state, obj->prng->state_size );
 
 	// Explicitly copy the seed array to prevent external mutation:
 	so = (stdlib_base_random_mt19937_state_t *)( obj->state );
 	memcpy( seed, so->seed, nbytes );
 	state->seed = seed;
 
 	return (void *)state;
 }
 
 /**
 * Sets the 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/mt19937.h"
 *
 * // Define a PRNG seed:
 * uint32_t seed[] = { 12345 };
 *
 * // Create a PRNG:
 * struct BasePRNGObject *obj = stdlib_base_random_mt19937_allocate( seed, 1 );
 * if ( obj == NULL ) {
 *     fprintf( stderr, "Error allocating memory.\n" );
 *     exit( 1 );
 * }
 *
 * 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 );
 *
 * // ...
 *
 * status = obj->prng->next( obj, &r );
 *
 * // ...
 *
 * // Retrieve the current PRNG state...
 * stdlib_base_random_mt19937_state_t *state = (stdlib_base_random_mt19937_state_t *)stdlib_base_random_mt19937_state( obj );
 * if ( state == NULL ) {
 *     fprintf( stderr, "Error encountered when attempting to retrieve PRNG state.\n" );
 *     exit( 1 );
 * }
 *
 * // ...
 *
 * status = obj->prng->next( obj, &r );
 *
 * // ...
 *
 * status = obj->prng->next( obj, &r );
 *
 * // ...
 *
 * // Reset the PRNG to a previous state...
 * status = stdlib_base_random_mt19937_set( obj, (void *)state );
 * if ( status != 0 ) {
 *     fprintf( stderr, "Error encountered when attempting to set PRNG state.\n" );
 *     exit( 1 );
 * }
 *
 * // ...
 *
 * status = obj->prng->next( obj, &r );
 *
 * // ...
 *
 * status = obj->prng->next( obj, &r );
 *
 * // ...
 *
 * // Free allocated memory:
 * stdlib_base_random_mt19937_free( obj );
 *
 * free( state->seed );
 * free( state );
 */
 int8_t stdlib_base_random_mt19937_set( struct BasePRNGObject *obj, const void *state ) {
 	stdlib_base_random_mt19937_state_t *vstate;
 	uint64_t nbytes;
 	uint32_t *seed;
 	if ( obj == NULL || state == NULL || obj->prng != &mt19937_prng ) {
 		return -1;
 	}
 	// Copy the provided seed array:
 	vstate = ( stdlib_base_random_mt19937_state_t *)state;
 	nbytes = sizeof( uint32_t ) * ( vstate->seed_length );
 	seed = (uint32_t *)malloc( nbytes );
 	if ( seed == NULL ) {
 		return -1;
 	}
 	memcpy( seed, vstate->seed, nbytes );
 
 	// Retrieve the current PRNG state:
 	vstate = ( stdlib_base_random_mt19937_state_t *)( obj->state );
 
 	// Free the memory held by the current seed array:
 	free( vstate->seed );
 
 	// Overwrite the current state with the provided state:
 	memcpy( vstate, state, obj->prng->state_size );
 
 	// Update the seed array pointer:
 	vstate->seed = seed;
 
 	return 0;
 }