feat(random): implement xorshift generator

---
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: passed
  - 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: passed
  - 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: passed
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---

Author: impawstarlight

lib/node_modules/@stdlib/random/base/xorshift/README.md

@@ -18,7 +18,7 @@ limitations under the License.
 
 -->
 
-# MINSTD
+# XORSHIFT
 
 > A linear congruential pseudorandom number generator ([LCG][lcg]) based on Park and Miller.
 
@@ -70,7 +70,7 @@ var rand = xorshift.factory({
 });
 
 var r = rand();
-// returns 20739838
+// returns 332584831
 ```
 
 or, for arbitrary length seeds, an array-like `object` containing signed 32-bit integers
@@ -83,7 +83,7 @@ var rand = xorshift.factory({
 });
 
 var r = rand();
-// returns 20739838
+// returns 332584831
 ```
 
 To return a generator having a specific initial state, set the generator `state` option.
@@ -130,7 +130,7 @@ Maximum possible value.
 
 ```javascript
 var max = xorshift.MAX;
-// returns 2147483646
+// returns 4294967295
 ```
 
 #### xorshift.seed
@@ -178,7 +178,7 @@ r = xorshift();
 
 // Get the current state:
 var state = xorshift.state;
-// returns <Int32Array>
+// returns <Uint32Array>
 
 r = xorshift();
 // returns <number>

lib/node_modules/@stdlib/random/base/xorshift/docs/types/index.d.ts

@@ -29,12 +29,12 @@ interface Options {
 	/**
 	* Pseudorandom number generator seed.
 	*/
-	seed?: random.PRNGSeedMINSTD;
+	seed?: random.PRNGSeedXORSHIFT;
 
 	/**
 	* Pseudorandom number generator state.
 	*/
-	state?: random.PRNGStateMINSTD;
+	state?: random.PRNGStateXORSHIFT;
 
 	/**
 	* Specifies whether to copy a provided pseudorandom number generator state.
@@ -64,7 +64,7 @@ interface PRNG {
 	/**
 	* PRNG seed.
 	*/
-	readonly seed: random.PRNGSeedMINSTD;
+	readonly seed: random.PRNGSeedXORSHIFT;
 
 	/**
 	* PRNG seed length.
@@ -74,7 +74,7 @@ interface PRNG {
 	/**
 	* PRNG state.
 	*/
-	state: random.PRNGStateMINSTD;
+	state: random.PRNGStateXORSHIFT;
 
 	/**
 	* PRNG state length.

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

@@ -16,8 +16,8 @@
 * limitations under the License.
 */
 
-#ifndef STDLIB_RANDOM_BASE_MINSTD_H
-#define STDLIB_RANDOM_BASE_MINSTD_H
+#ifndef STDLIB_RANDOM_BASE_XORSHIFT_H
+#define STDLIB_RANDOM_BASE_XORSHIFT_H
 
 #include "stdlib/random/base/shared.h"
 #include <stdint.h>
@@ -66,4 +66,4 @@ int8_t stdlib_base_random_xorshift_set( struct BasePRNGObject *obj, const void *
 }
 #endif
 
-#endif // !STDLIB_RANDOM_BASE_MINSTD_H
+#endif // !STDLIB_RANDOM_BASE_XORSHIFT_H

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

@@ -30,20 +30,19 @@ var isObject = require( '@stdlib/assert/is-plain-object' );
 var isBoolean = require( '@stdlib/assert/is-boolean' ).isPrimitive;
 var isCollection = require( '@stdlib/assert/is-collection' );
 var isPositiveInteger = require( '@stdlib/assert/is-positive-integer' ).isPrimitive;
-var isInt32Array = require( '@stdlib/assert/is-int32array' );
+var isUint32Array = require( '@stdlib/assert/is-uint32array' );
 var format = require( '@stdlib/string/format' );
-var INT32_MAX = require( '@stdlib/constants/int32/max' );
-var Int32Array = require( '@stdlib/array/int32' );
+var UINT32_MAX = require( '@stdlib/constants/uint32/max' );
+var Uint32Array = require( '@stdlib/array/uint32' );
 var gcopy = require( '@stdlib/blas/base/gcopy' );
 var typedarray2json = require( '@stdlib/array/to-json' );
 var randint32 = require( './rand_int32.js' );
 
 
 // VARIABLES //
 
-var NORMALIZATION_CONSTANT = (INT32_MAX - 1)|0; // asm type annotation
-var MAX_SEED = (INT32_MAX - 1)|0; // asm type annotation
-var A = 16807|0; // asm type annotation
+var NORMALIZATION_CONSTANT = UINT32_MAX >>> 0; // asm type annotation
+var MAX_SEED = UINT32_MAX >>> 0; // asm type annotation
 
 // Define the state array schema version:
 var STATE_ARRAY_VERSION = 1; // NOTE: anytime the state array schema changes, this value should be incremented!!!
@@ -67,7 +66,7 @@ var STATE_FIXED_LENGTH = 5; // 1 (version) + 1 (num_sections) + 1 (state_length)
 * Verifies state array integrity.
 *
 * @private
-* @param {Int32Array} state - state array
+* @param {Uint32Array} state - state array
 * @param {boolean} FLG - flag indicating whether the state array was provided as an option (true) or an argument (false)
 * @returns {(Error|null)} an error or `null`
 */
@@ -108,13 +107,13 @@ function verifyState( state, FLG ) {
 * Returns a linear congruential pseudorandom number generator (LCG) based on Park and Miller.
 *
 * @param {Options} [options] - options
-* @param {PRNGSeedMINSTD} [options.seed] - pseudorandom number generator seed
-* @param {PRNGStateMINSTD} [options.state] - pseudorandom number generator state
+* @param {PRNGSeedXORSHIFT} [options.seed] - pseudorandom number generator seed
+* @param {PRNGStateXORSHIFT} [options.state] - pseudorandom number generator state
 * @param {boolean} [options.copy=true] - boolean indicating whether to copy a provided pseudorandom number generator state
 * @throws {TypeError} options argument must be an object
 * @throws {TypeError} a seed must be either a positive integer less than the maximum signed 32-bit integer or an array-like object containing integers less than the maximum signed 32-bit integer
 * @throws {RangeError} a numeric seed must be a positive integer less than the maximum signed 32-bit integer
-* @throws {TypeError} state must be an `Int32Array`
+* @throws {TypeError} state must be an `Uint32Array`
 * @throws {Error} must provide a valid state
 * @throws {TypeError} `copy` option must be a boolean
 * @returns {PRNG} LCG PRNG
@@ -132,7 +131,7 @@ function verifyState( state, FLG ) {
 * });
 *
 * var v = xorshift();
-* // returns 20739838
+* // returns 332584831
 */
 function factory( options ) {
 	var STATE;
@@ -156,8 +155,8 @@ function factory( options ) {
 		if ( hasOwnProp( options, 'state' ) ) {
 			state = options.state;
 			opts.state = true;
-			if ( !isInt32Array( state ) ) {
-				throw new TypeError( format( 'invalid option. `%s` option must be an Int32Array. Option: `%s`.', 'state', state ) );
+			if ( !isUint32Array( state ) ) {
+				throw new TypeError( format( 'invalid option. `%s` option must be an Uint32Array. Option: `%s`.', 'state', state ) );
 			}
 			err = verifyState( state, true );
 			if ( err ) {
@@ -166,14 +165,14 @@ function factory( options ) {
 			if ( opts.copy === false ) {
 				STATE = state;
 			} else {
-				STATE = new Int32Array( state.length );
+				STATE = new Uint32Array( state.length );
 				gcopy( state.length, state, 1, STATE, 1 );
 			}
 			// Create a state "view":
-			state = new Int32Array( STATE.buffer, STATE.byteOffset+((STATE_SECTION_OFFSET+1)*STATE.BYTES_PER_ELEMENT), 1 );
+			state = new Uint32Array( STATE.buffer, STATE.byteOffset+((STATE_SECTION_OFFSET+1)*STATE.BYTES_PER_ELEMENT), 1 );
 
 			// Create a seed "view":
-			seed = new Int32Array( STATE.buffer, STATE.byteOffset+((SEED_SECTION_OFFSET+1)*STATE.BYTES_PER_ELEMENT), state[ SEED_SECTION_OFFSET ] );
+			seed = new Uint32Array( STATE.buffer, STATE.byteOffset+((SEED_SECTION_OFFSET+1)*STATE.BYTES_PER_ELEMENT), state[ SEED_SECTION_OFFSET ] );
 		}
 		// If provided a PRNG state, we ignore the `seed` option...
 		if ( seed === void 0 ) {
@@ -187,7 +186,7 @@ function factory( options ) {
 					seed |= 0; // asm type annotation
 				} else if ( isCollection( seed ) && seed.length > 0 ) {
 					slen = seed.length;
-					STATE = new Int32Array( STATE_FIXED_LENGTH+slen );
+					STATE = new Uint32Array( STATE_FIXED_LENGTH+slen );
 
 					// Initialize sections:
 					STATE[ 0 ] = STATE_ARRAY_VERSION;
@@ -199,25 +198,25 @@ function factory( options ) {
 					gcopy.ndarray( slen, seed, 1, 0, STATE, 1, SEED_SECTION_OFFSET+1 );
 
 					// Create a state "view":
-					state = new Int32Array( STATE.buffer, STATE.byteOffset+((STATE_SECTION_OFFSET+1)*STATE.BYTES_PER_ELEMENT), 1 );
+					state = new Uint32Array( STATE.buffer, STATE.byteOffset+((STATE_SECTION_OFFSET+1)*STATE.BYTES_PER_ELEMENT), 1 );
 
 					// Create a seed "view":
-					seed = new Int32Array( STATE.buffer, STATE.byteOffset+((SEED_SECTION_OFFSET+1)*STATE.BYTES_PER_ELEMENT), slen );
+					seed = new Uint32Array( STATE.buffer, STATE.byteOffset+((SEED_SECTION_OFFSET+1)*STATE.BYTES_PER_ELEMENT), slen );
 
 					// Initialize the internal PRNG state:
 					state[ 0 ] = seed[ 0 ];
 				} else {
 					throw new TypeError( format( 'invalid option. `%s` option must be either a positive integer less than the maximum signed 32-bit integer or an array-like object containing integer values less than the maximum signed 32-bit integer. Option: `%s`.', 'seed', seed ) );
 				}
 			} else {
-				seed = randint32()|0; // asm type annotation
+				seed = randint32() >>> 0; // asm type annotation
 			}
 		}
 	} else {
-		seed = randint32()|0; // asm type annotation
+		seed = randint32() >>> 0; // asm type annotation
 	}
 	if ( state === void 0 ) {
-		STATE = new Int32Array( STATE_FIXED_LENGTH+1 );
+		STATE = new Uint32Array( STATE_FIXED_LENGTH+1 );
 
 		// Initialize sections:
 		STATE[ 0 ] = STATE_ARRAY_VERSION;
@@ -227,10 +226,10 @@ function factory( options ) {
 		STATE[ SEED_SECTION_OFFSET+1 ] = seed;
 
 		// Create a state "view":
-		state = new Int32Array( STATE.buffer, STATE.byteOffset+((STATE_SECTION_OFFSET+1)*STATE.BYTES_PER_ELEMENT), 1 );
+		state = new Uint32Array( STATE.buffer, STATE.byteOffset+((STATE_SECTION_OFFSET+1)*STATE.BYTES_PER_ELEMENT), 1 );
 
 		// Create a seed "view":
-		seed = new Int32Array( STATE.buffer, STATE.byteOffset+((SEED_SECTION_OFFSET+1)*STATE.BYTES_PER_ELEMENT), 1 );
+		seed = new Uint32Array( STATE.buffer, STATE.byteOffset+((SEED_SECTION_OFFSET+1)*STATE.BYTES_PER_ELEMENT), 1 );
 
 		// Initialize the internal PRNG state:
 		state[ 0 ] = seed[ 0 ];
@@ -243,7 +242,7 @@ function factory( options ) {
 	setReadOnlyAccessor( xorshift, 'byteLength', getStateSize );
 	setReadOnly( xorshift, 'toJSON', toJSON );
 	setReadOnly( xorshift, 'MIN', 1 );
-	setReadOnly( xorshift, 'MAX', INT32_MAX-1 );
+	setReadOnly( xorshift, 'MAX', UINT32_MAX );
 	setReadOnly( xorshift, 'normalized', normalized );
 
 	setReadOnly( normalized, 'NAME', xorshift.NAME );
@@ -262,11 +261,11 @@ function factory( options ) {
 	* Returns the PRNG seed.
 	*
 	* @private
-	* @returns {PRNGSeedMINSTD} seed
+	* @returns {PRNGSeedXORSHIFT} seed
 	*/
 	function getSeed() {
 		var len = STATE[ SEED_SECTION_OFFSET ];
-		return gcopy( len, seed, 1, new Int32Array( len ), 1 );
+		return gcopy( len, seed, 1, new Uint32Array( len ), 1 );
 	}
 
 	/**
@@ -317,11 +316,11 @@ function factory( options ) {
 	* -   The first element of each section following the preamble specifies the section length. The remaining section elements comprise the section contents.
 	*
 	* @private
-	* @returns {PRNGStateMINSTD} current state
+	* @returns {PRNGStateXORSHIFT} current state
 	*/
 	function getState() {
 		var len = STATE.length;
-		return gcopy( len, STATE, 1, new Int32Array( len ), 1 );
+		return gcopy( len, STATE, 1, new Uint32Array( len ), 1 );
 	}
 
 	/**
@@ -333,14 +332,14 @@ function factory( options ) {
 	* -   If PRNG state is "shared" and one sets the generator state to a state array of the same length, the PRNG state is updated (along with the state of all other PRNGs sharing the PRNG's state array).
 	*
 	* @private
-	* @param {PRNGStateMINSTD} s - generator state
-	* @throws {TypeError} must provide an `Int32Array`
+	* @param {PRNGStateXORSHIFT} s - generator state
+	* @throws {TypeError} must provide an `Uint32Array`
 	* @throws {Error} must provide a valid state
 	*/
 	function setState( s ) {
 		var err;
-		if ( !isInt32Array( s ) ) {
-			throw new TypeError( format( 'invalid argument. Must provide an Int32Array. Value: `%s`.', s ) );
+		if ( !isUint32Array( s ) ) {
+			throw new TypeError( format( 'invalid argument. Must provide an Uint32Array. Value: `%s`.', s ) );
 		}
 		err = verifyState( s, false );
 		if ( err ) {
@@ -356,15 +355,15 @@ function factory( options ) {
 		} else {
 			// Check if we can reuse allocated memory...
 			if ( s.length !== STATE.length ) {
-				STATE = new Int32Array( s.length ); // reallocate
+				STATE = new Uint32Array( s.length ); // reallocate
 			}
 			gcopy( s.length, s, 1, STATE, 1 );
 		}
 		// Create a new state "view":
-		state = new Int32Array( STATE.buffer, STATE.byteOffset+((STATE_SECTION_OFFSET+1)*STATE.BYTES_PER_ELEMENT), 1 );
+		state = new Uint32Array( STATE.buffer, STATE.byteOffset+((STATE_SECTION_OFFSET+1)*STATE.BYTES_PER_ELEMENT), 1 );
 
 		// Create a new seed "view":
-		seed = new Int32Array( STATE.buffer, STATE.byteOffset+((SEED_SECTION_OFFSET+1)*STATE.BYTES_PER_ELEMENT), STATE[ SEED_SECTION_OFFSET ] );
+		seed = new Uint32Array( STATE.buffer, STATE.byteOffset+((SEED_SECTION_OFFSET+1)*STATE.BYTES_PER_ELEMENT), STATE[ SEED_SECTION_OFFSET ] );
 	}
 
 	/**
@@ -387,16 +386,18 @@ function factory( options ) {
 	}
 
 	/**
-	* Generates a pseudorandom integer on the interval \\( [1,2^{31}-1) \\).
+	* Generates a pseudorandom integer on the interval \\( [1,2^{31}) \\).
 	*
 	* @private
 	* @returns {integer32} pseudorandom integer
 	*/
 	function xorshift() {
-		var s = state[ 0 ]|0; // asm type annotation
-		s = ( (A*s)%INT32_MAX )|0; // asm type annotation
+		var s = state[ 0 ] >>> 0; // asm type annotation
+		s ^= s << 13;
+		s ^= s >>> 17;
+		s ^= s << 5;
 		state[ 0 ] = s;
-		return s|0; // asm type annotation
+		return s >>> 0; // asm type annotation
 	}
 
 	/**