feat: add C implementation for pcg32

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown
    status: na
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: na
  - task: lint_javascript_tests
    status: na
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: passed
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: na
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---

Author: impawstarlight

lib/node_modules/@stdlib/random/base/pcg32/include/stdlib/random/base/pcg32.h

@@ -33,14 +33,14 @@ extern "C" {
 * Declare an opaque type definition for the PRNG state.
 */
 typedef struct {
-	uint32_t seed;
-	uint32_t state;
+	uint64_t seed;
+	uint64_t state;
 } stdlib_base_random_pcg32_state_t;
 
 /**
 * Returns a pointer to a dynamically allocated PRNG.
 */
-struct BasePRNGObject * stdlib_base_random_pcg32_allocate( const int32_t seed );
+struct BasePRNGObject * stdlib_base_random_pcg32_allocate( const int64_t seed );
 
 /**
 * Frees a PRNG's allocated memory.
@@ -50,7 +50,7 @@ void stdlib_base_random_pcg32_free( struct BasePRNGObject *obj );
 /**
 * Returns a PRNG seed.
 */
-int8_t stdlib_base_random_pcg32_seed( const struct BasePRNGObject *obj, int32_t *out );
+int8_t stdlib_base_random_pcg32_seed( const struct BasePRNGObject *obj, int64_t *out );
 
 /**
 * Returns a copy of the current PRNG state.

lib/node_modules/@stdlib/random/base/pcg32/lib/factory.js

@@ -46,10 +46,10 @@ var randuint32 = require( './rand_uint32.js' );
 var NORMALIZATION_CONSTANT = UINT32_MAX + 1;
 var MAX_SEED = UINT32_MAX >>> 0; // asm type annotation
 
-// Define the LCG multiplier
+// Define the LCG multiplier:
 var MULTIPLIER = [ 0x5851F42D >>> 0, 0x4C957F2D >>> 0 ]; // asm type annotation
 
-// Define the LCG increment which controls the stream. #TODO: Make user definable like seed
+// Define the LCG increment: #TODO: Make user definable like seed
 var INCREMENT = [ 0xBEEF0000 >>> 0, 0x0000DEAD >>> 0 ]; // asm type annotation
 
 // Define the size of state as a multiple of 32-bits

lib/node_modules/@stdlib/random/base/pcg32/src/main.c

@@ -28,28 +28,31 @@ static inline int8_t normalized( struct BasePRNGObject *obj, double *out );
 static inline void pcg32_free( struct BasePRNGObject *obj );
 
 // Define the LCG multiplier:
-static const uint32_t A = 16807;
+static const uint64_t MULTIPLIER = 0x5851F42D4C957F2DULL;
 
-// Define the maximum signed 32-bit integer: 2147483647 => 0x7fffffff => 01111111111111111111111111111111
-static const uint32_t MAX_INT32 = 0x7fffffff;
+// Define the LCG increment: #TODO: Make user definable like seed
+static const uint64_t INCREMENT = 0xBEEF00000000DEADULL;
+
+// Define the maximum unsigned 32-bit integer: 4294967295 => 0xffffffff => 11111111111111111111111111111111
+static const uint32_t MAX_UINT32 = 0xffffffff;
 
 // Define the normalization constant:
-static const double NORMALIZATION_CONSTANT = 2147483646.0; // MAX_INT32 - 1
+static const double NORMALIZATION_CONSTANT = MAX_UINT32 + 1.0;
 
 /**
 * PCG32 PRNG.
 *
 */
 static const struct BasePRNG pcg32_prng = {
-	"pcg32",                                     // 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): (MAX-1)/MAX
-	sizeof( stdlib_base_random_pcg32_state_t ),  // state_size
-	&next,                                        // next()
-	&normalized,                                  // normalized()
-	&pcg32_free                                  // free()
+	"pcg32",                                    // name
+	(uint64_t)0,                                // min
+	(uint64_t)MAX_UINT32,                       // max: 2^{32}-1
+	0.0,                                        // min (normalized)
+	MAX_UINT32 / NORMALIZATION_CONSTANT,        // max (normalized): (MAX-1)/MAX
+	sizeof( stdlib_base_random_pcg32_state_t ), // state_size
+	&next,                                      // next()
+	&normalized,                                // normalized()
+	&pcg32_free                                 // free()
 };
 
 /**
@@ -64,23 +67,30 @@ static const struct BasePRNG pcg32_prng = {
 * @return     status code
 */
 static inline int8_t next( struct BasePRNGObject *obj, uint64_t *out ) {
+	uint32_t xorshifted;
+	uint64_t oldstate;
+	uint32_t output;
+	uint32_t rot;
+
 	if ( obj == NULL || obj->prng != &pcg32_prng ) {
 		return -1;
 	}
 	// Retrieve the state object:
 	stdlib_base_random_pcg32_state_t *so = (stdlib_base_random_pcg32_state_t *)( obj->state );
 
 	// Retrieve the current state:
-	uint32_t state = so->state;
-
-	// Explicitly cast to 64-bit to handle integer overflow:
-	state = (A*(uint64_t)state) % MAX_INT32;
+	oldstate = so->state;
 
 	// Update the PRNG state:
-	so->state = state;
+	so->state = oldstate * MULTIPLIER + INCREMENT;
+
+	// Apply output permutaion (XSH-RR)
+	xorshifted = ( ( oldstate >> 18 ) ^ oldstate ) >> 27;
+	rot = oldstate >> 59;
+	output = ( xorshifted >> rot ) | ( xorshifted << ( -rot & 31 ) );
 
 	// Set the output value:
-	*out = (uint64_t)state;
+	*out = (uint64_t)output;
 
 	return 0;
 }
@@ -97,13 +107,13 @@ static inline int8_t next( struct BasePRNGObject *obj, uint64_t *out ) {
 * @return     status code
 */
 static inline int8_t normalized( struct BasePRNGObject *obj, double *out ) {
-	uint64_t state;
-	int8_t status = next( obj, &state );
+	uint64_t output;
+	int8_t status = next( obj, &output );
 	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;
+	// Note: casting `output` to a double here is fine, as `output` will never exceed the maximum "safe" double-precision floating-point number:
+	*out = (double)output / NORMALIZATION_CONSTANT;
 
 	return 0;
 }
@@ -127,7 +137,7 @@ static inline void pcg32_free( struct BasePRNGObject *obj ) {
 * ## Notes
 *
 * -   The user is responsible for freeing the allocated memory.
-* -   A provided `seed` is mapped to the interval `[1,2147483646]`.
+* -   A provided `seed` is mapped to the interval `[0,18446744073709551615]`.
 *
 * @param seed  PRNG seed
 * @return      pointer to a dynamically allocated PRNG or, if unable to allocate memory, a null pointer
@@ -166,8 +176,8 @@ static inline void pcg32_free( struct BasePRNGObject *obj ) {
 * // Free allocated memory:
 * stdlib_base_random_pcg32_free( obj );
 */
-struct BasePRNGObject * stdlib_base_random_pcg32_allocate( const int32_t seed ) {
-	uint32_t iseed;
+struct BasePRNGObject * stdlib_base_random_pcg32_allocate( const uint64_t seed ) {
+	uint64_t output;
 
 	struct BasePRNGObject *obj = malloc( sizeof( struct BasePRNGObject ) );
 	if ( obj == NULL ) {
@@ -179,20 +189,17 @@ struct BasePRNGObject * stdlib_base_random_pcg32_allocate( const int32_t seed )
 		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;
+	// No need to check, any unsigned 64-bit integer is a valid seed
 
-	obj->prng = &pcg32_prng;
+	state->seed = seed;
+	state->state = 0;
 	obj->state = state;
+	obj->prng = &pcg32_prng;
+
+	// Initialize the internal PRNG state:
+	next( obj, &output );
+	state->state += seed;
+	next( obj, &output );
 
 	return obj;
 }
@@ -268,7 +275,7 @@ void stdlib_base_random_pcg32_free( struct BasePRNGObject *obj ) {
 *     exit( 1 );
 * }
 *
-* int32_t seed;
+* uint64_t seed;
 * int8_t status = stdlib_base_random_pcg32_seed( obj, &seed );
 * if ( status != 0 ) {
 *     fprintf( stderr, "Error encountered when attempting to retrieve the PRNG seed.\n" );
@@ -280,15 +287,15 @@ void stdlib_base_random_pcg32_free( struct BasePRNGObject *obj ) {
 * // Free allocated memory:
 * stdlib_base_random_pcg32_free( obj );
 */
-int8_t stdlib_base_random_pcg32_seed( const struct BasePRNGObject *obj, int32_t *out ) {
+int8_t stdlib_base_random_pcg32_seed( const struct BasePRNGObject *obj, uint64_t *out ) {
 	if ( obj == NULL || obj->prng != &pcg32_prng ) {
 		return -1;
 	}
 	// Retrieve the PCG32 state object:
 	const stdlib_base_random_pcg32_state_t *state = (stdlib_base_random_pcg32_state_t *)( obj->state );
 
 	// Set the output value:
-	*out = (int32_t)( state->seed );
+	*out = (uint64_t)( state->seed );
 
 	return 0;
 }