Fix and add tests

Author: kgryte

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

@@ -232,6 +232,7 @@ var sz = mt19937.byteLength;
 
 -   [Mersenne Twister][mersenne-twister] is **not** a cryptographically secure PRNG, as the PRNG is based on a linear recursion. Any pseudorandom number sequence generated by a linear recursion is **insecure**, due to the fact that one can predict future generated outputs by observing a sufficiently long subsequence of generated values.
 -   Compared to other PRNGs, [Mersenne Twister][mersenne-twister] has a large state size (`~2.5kB`). Because of the large state size, beware of increased memory consumption when using the `factory()` method to create many [Mersenne Twister][mersenne-twister] PRNGs. When appropriate (e.g., when external state mutation is not a concern), consider sharing PRNG state.
+-   If PRNG state is "shared" (meaning a state array was provided during PRNG creation and **not** copied) and one sets the generator state to a state array having a different length, the PRNG internally allocates a new fixed block of memory for storing PRNG state. Hence, a created PRNG does **not** support updating **shared** state when state arrays differ in length.
 -   The PRNG has a period of `2^19937 - 1`.
 
 </section>

lib/node_modules/@stdlib/random/base/mt19937/test/test.factory.js

@@ -29,6 +29,7 @@ var isUint32Array = require( '@stdlib/assert/is-uint32array' );
 var Uint32Array = require( '@stdlib/array/uint32' );
 var kstest = require( '@stdlib/stats/kstest' );
 var minstd = require( '@stdlib/random/base/minstd-shuffle' );
+var gcopy = require( '@stdlib/blas/base/gcopy' );
 var factory = require( './../lib/factory.js' );
 
 
@@ -349,7 +350,7 @@ tape( 'if provided a `state` option containing an unsupported section length, th
 	values = [];
 
 	v = new Uint32Array( 632 ); // >624+7
-	v[ 0 ] = 0;   // version
+	v[ 0 ] = 1;   // version
 	v[ 1 ] = 3;   // number of sections
 	v[ 2 ] = 624; // state length
 	v[ 627 ] = 2; // other length
@@ -358,7 +359,7 @@ tape( 'if provided a `state` option containing an unsupported section length, th
 	values.push( v );
 
 	v = new Uint32Array( 633 ); // >624+7
-	v[ 0 ] = 0;   // version
+	v[ 0 ] = 1;   // version
 	v[ 1 ] = 3;   // number of sections
 	v[ 2 ] = 624; // state length
 	v[ 627 ] = 2; // other length
@@ -388,7 +389,7 @@ tape( 'if provided a `state` option containing an incompatible seed length, the
 	values = [];
 
 	v = new Uint32Array( 631 ); // 624+7
-	v[ 0 ] = 0;   // version
+	v[ 0 ] = 1;   // version
 	v[ 1 ] = 3;   // number of sections
 	v[ 2 ] = 624; // state length
 	v[ 627 ] = 1; // other length
@@ -397,7 +398,7 @@ tape( 'if provided a `state` option containing an incompatible seed length, the
 	values.push( v );
 
 	v = new Uint32Array( 632 ); // >624+7
-	v[ 0 ] = 0;   // version
+	v[ 0 ] = 1;   // version
 	v[ 1 ] = 3;   // number of sections
 	v[ 2 ] = 624; // state length
 	v[ 627 ] = 1; // other length
@@ -1387,24 +1388,6 @@ tape( 'the function supports specifying a shared generator state', function test
 		'copy': false
 	});
 
-	// Replay previously generated values...
-	j = 0;
-	for ( i = 0; i < 50; i++ ) {
-		v1 = rand1();
-		v2 = rand2();
-		t.equal( v1, arr[ j ], 'returns expected value. i: '+j+'.' );
-		t.equal( v2, arr[ j+1 ], 'returns expected value. i: '+(j+1)+'.' );
-		j += 2; // stride
-	}
-
-	// Move to a future state...
-	for ( i = 0; i < 100; i++ ) {
-		v2 = rand2();
-	}
-
-	// Reset the (shared) state:
-	rand1.state = new Uint32Array( state );
-
 	// Replay previously generated values...
 	j = 0;
 	for ( i = 0; i < 50; i++ ) {
@@ -1506,3 +1489,152 @@ tape( 'the returned function supports setting the generator state (normalized)',
 	}
 	t.end();
 });
+
+tape( 'the returned function supports setting a compatible shared generator state', function test( t ) {
+	var mt19937;
+	var shared;
+	var state;
+	var rand1;
+	var rand2;
+	var arr;
+	var v1;
+	var v2;
+	var i;
+	var j;
+
+	mt19937 = factory();
+
+	// Move to a future state...
+	for ( i = 0; i < 100; i++ ) {
+		mt19937();
+	}
+	// Capture the current state:
+	state = mt19937.state;
+
+	// Move to a future state...
+	arr = [];
+	for ( i = 0; i < 100; i++ ) {
+		arr.push( mt19937() );
+	}
+
+	// Create a copy of the state (to prevent mutation) which will be shared by more than one PRNG:
+	shared = new Uint32Array( state );
+
+	// Create PRNGs using the captured state:
+	rand1 = factory({
+		'state': shared,
+		'copy': false
+	});
+	rand2 = factory({
+		'state': shared,
+		'copy': false
+	});
+
+	// Replay previously generated values...
+	j = 0;
+	for ( i = 0; i < 50; i++ ) {
+		v1 = rand1();
+		v2 = rand2();
+		t.equal( v1, arr[ j ], 'returns expected value. i: '+j+'.' );
+		t.equal( v2, arr[ j+1 ], 'returns expected value. i: '+(j+1)+'.' );
+		j += 2; // stride
+	}
+
+	// Move to a future state...
+	for ( i = 0; i < 100; i++ ) {
+		v2 = rand2();
+	}
+
+	// Reset the (shared) state:
+	rand1.state = new Uint32Array( state );
+
+	// Replay previously generated values...
+	j = 0;
+	for ( i = 0; i < 50; i++ ) {
+		v1 = rand1();
+		v2 = rand2();
+		t.equal( v1, arr[ j ], 'returns expected value. i: '+j+'.' );
+		t.equal( v2, arr[ j+1 ], 'returns expected value. i: '+(j+1)+'.' );
+		j += 2; // stride
+	}
+	t.end();
+});
+
+tape( 'the returned function does not support setting an incompatible shared generator state', function test( t ) {
+	var mt19937;
+	var shared;
+	var state;
+	var rand1;
+	var rand2;
+	var arr;
+	var v1;
+	var v2;
+	var s;
+	var i;
+	var j;
+
+	mt19937 = factory();
+
+	// Move to a future state...
+	for ( i = 0; i < 100; i++ ) {
+		mt19937();
+	}
+	// Capture the current state:
+	state = mt19937.state;
+
+	// Move to a future state...
+	arr = [];
+	for ( i = 0; i < 100; i++ ) {
+		arr.push( mt19937() );
+	}
+
+	// Create a copy of the state (to prevent mutation) which will be shared by more than one PRNG:
+	shared = new Uint32Array( state );
+
+	// Create PRNGs using the captured state:
+	rand1 = factory({
+		'state': shared,
+		'copy': false
+	});
+	rand2 = factory({
+		'state': shared,
+		'copy': false
+	});
+
+	// Replay previously generated values...
+	j = 0;
+	for ( i = 0; i < 50; i++ ) {
+		v1 = rand1();
+		v2 = rand2();
+		t.equal( v1, arr[ j ], 'returns expected value. i: '+j+'.' );
+		t.equal( v2, arr[ j+1 ], 'returns expected value. i: '+(j+1)+'.' );
+		j += 2; // stride
+	}
+
+	// Move to a future state...
+	for ( i = 0; i < 100; i++ ) {
+		v2 = rand2();
+	}
+
+	// Reset the (*previously* shared) state:
+	s = new Uint32Array( state.length+1 );
+	gcopy( state.length, state, 1, s, 1 );
+	s[ s.length-3 ] = 2;
+	s[ s.length-1 ] = 1234;
+	rand1.state = s;
+
+	// Attempt to replay previously generated values...
+	j = 0;
+	for ( i = 0; i < 50; i++ ) {
+		v1 = rand1();
+		v2 = rand2();
+
+		// `rand1()` state is not affected by `rand2()`:
+		t.equal( v1, arr[ i ], 'returns expected value. i: '+i+'.' );
+
+		// `rand2()` state was never reset:
+		t.notEqual( v2, arr[ j+1 ], 'does not return expected value. i: '+(j+1)+'.' );
+		j += 2; // stride
+	}
+	t.end();
+});