Rename file and add support for getting and setting PRNG state

Author: kgryte

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

@@ -150,6 +150,51 @@ for ( i = 0; i < 100; i++ ) {
 }
 ```
 
+#### chisquare.STATE
+
+Writable property for getting and setting the generator state.
+
+```javascript
+var r = chisquare( 2 );
+// returns <number>
+
+r = chisquare( 2 );
+// returns <number>
+
+// ...
+
+// Get a copy of the current state:
+var state = chisquare.STATE;
+// returns <Uint32Array>
+
+r = chisquare( 2 );
+// returns <number>
+
+r = chisquare( 2 );
+// returns <number>
+
+// Reset the state:
+chisquare.STATE = state;
+
+// Replay the last two pseudorandom numbers:
+r = chisquare( 2 );
+// returns <number>
+
+r = chisquare( 2 );
+// returns <number>
+
+// ...
+```
+
+#### chisquare.STATE_SIZE
+
+Size of generator state.
+
+```javascript
+var sz = chisquare.STATE_SIZE;
+// returns <number>
+```
+
 </section>
 
 <!-- /.usage -->

lib/node_modules/@stdlib/random/base/chisquare/docs/repl.txt

@@ -82,6 +82,45 @@
     --------
     > var seed = {{alias}}.SEED;
 
+
+{{alias}}.STATE
+    Generator state.
+
+    Examples
+    --------
+    > var r = {{alias}}( 2 )
+    <number>
+    > r = {{alias}}( 2 )
+    <number>
+    > r = {{alias}}( 2 )
+    <number>
+
+    // Get a copy of the current state:
+    > var state = {{alias}}.STATE
+    <Uint32Array>
+
+    > r = {{alias}}( 2 )
+    <number>
+    > r = {{alias}}( 2 )
+    <number>
+
+    // Set the state:
+    > {{alias}}.STATE = state;
+
+    // Replay the last two pseudorandom numbers:
+    > r = {{alias}}( 2 )
+    <number>
+    > r = {{alias}}( 2 )
+    <number>
+
+
+{{alias}}.STATE_SIZE
+    Size of generator state.
+
+    Examples
+    --------
+    > var sz = {{alias}}.STATE_SIZE;
+
     See Also
     --------
 

lib/node_modules/@stdlib/random/base/chisquare/lib/chisquare.js

@@ -18,36 +18,19 @@
 
 'use strict';
 
-// MODULES //
-
-var factory = require( './factory.js' );
-
-
-// MAIN //
-
 /**
-* Returns a pseudorandom number drawn from a chi-square distribution with degrees of freedom `k`.
+* Returns a pseudorandom number drawn from a chi-square distribution.
 *
-* @function chisquare
-* @type {Function}
+* @private
+* @param {Function} rgamma - PRNG for gamma distributed numbers
 * @param {PositiveNumber} k - degrees of freedom
 * @returns {number} pseudorandom number
-*
-* @example
-* var v = chisquare( 2 );
-* // returns <number>
-*
-* @example
-* var v = chisquare( 0 );
-* // returns NaN
-*
-* @example
-* var v = chisquare( NaN );
-* // returns NaN
 */
-var chisquare = factory();
+function sample( rgamma, k ) {
+	return rgamma( k/2.0, 0.5 );
+}
 
 
 // EXPORTS //
 
-module.exports = chisquare;
+module.exports = sample;

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

@@ -20,12 +20,13 @@
 
 // MODULES //
 
+var defineProperty = require( '@stdlib/utils/define-property' );
 var setReadOnly = require( '@stdlib/utils/define-read-only-property' );
 var isPositive = require( '@stdlib/assert/is-positive-number' ).isPrimitive;
 var isObject = require( '@stdlib/assert/is-plain-object' );
 var isnan = require( '@stdlib/math/base/assert/is-nan' );
 var rgamma = require( '@stdlib/random/base/gamma' ).factory;
-var chisquare0 = require( './_chisquare.js' );
+var chisquare0 = require( './chisquare.js' );
 
 
 // MAIN //
@@ -86,10 +87,37 @@ function factory() {
 	}
 	setReadOnly( prng, 'NAME', 'chisquare' );
 	setReadOnly( prng, 'SEED', rand.SEED );
+	defineProperty( prng, 'STATE', {
+		'configurable': false,
+		'enumerable': true,
+		'get': getState,
+		'set': setState
+	});
+	setReadOnly( prng, 'STATE_SIZE', rand.STATE_SIZE );
 	setReadOnly( prng, 'PRNG', rand.PRNG );
 
 	return prng;
 
+	/**
+	* Returns the current pseudorandom number generator state.
+	*
+	* @private
+	* @returns {Uint32Array} current state
+	*/
+	function getState() {
+		return rand.STATE;
+	}
+
+	/**
+	* Sets the pseudorandom number generator state.
+	*
+	* @private
+	* @param {Uint32Array} s - generator state
+	*/
+	function setState( s ) {
+		rand.STATE = s;
+	}
+
 	/**
 	* Returns a random number drawn from a chi-square distribution with bound `k`.
 	*

lib/node_modules/@stdlib/random/base/chisquare/lib/index.js

@@ -43,7 +43,7 @@
 // MODULES //
 
 var setReadOnly = require( '@stdlib/utils/define-read-only-property' );
-var chisquare = require( './chisquare.js' );
+var chisquare = require( './main.js' );
 var factory = require( './factory.js' );
 
 

lib/node_modules/@stdlib/random/base/chisquare/lib/_chisquare.js renamed to lib/node_modules/@stdlib/random/base/chisquare/lib/main.js

@@ -18,19 +18,36 @@
 
 'use strict';
 
+// MODULES //
+
+var factory = require( './factory.js' );
+
+
+// MAIN //
+
 /**
-* Returns a pseudorandom number drawn from a chi-square distribution.
+* Returns a pseudorandom number drawn from a chi-square distribution with degrees of freedom `k`.
 *
-* @private
-* @param {Function} rgamma - PRNG for gamma distributed numbers
+* @function chisquare
+* @type {Function}
 * @param {PositiveNumber} k - degrees of freedom
 * @returns {number} pseudorandom number
+*
+* @example
+* var v = chisquare( 2 );
+* // returns <number>
+*
+* @example
+* var v = chisquare( 0 );
+* // returns NaN
+*
+* @example
+* var v = chisquare( NaN );
+* // returns NaN
 */
-function sample( rgamma, k ) {
-	return rgamma( k/2.0, 0.5 );
-}
+var chisquare = factory();
 
 
 // EXPORTS //
 
-module.exports = sample;
+module.exports = chisquare;

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

@@ -23,8 +23,9 @@
 var tape = require( 'tape' );
 var ENV = require( '@stdlib/process/env' );
 var kstest = require( '@stdlib/stats/kstest' );
-var round = require( '@stdlib/math/base/special/round' );
+var now = require( '@stdlib/time/now' );
 var isnan = require( '@stdlib/math/base/assert/is-nan' );
+var isUint32Array = require( '@stdlib/assert/is-uint32array' );
 var factory = require( './../lib/factory.js' );
 
 
@@ -73,7 +74,7 @@ tape( 'the function returns a seeded pseudorandom number generator', function te
 	var r2;
 	var i;
 
-	seed = round( Date.now() / 1000 );
+	seed = now();
 
 	chisquare1 = factory( 35, {
 		'seed': seed
@@ -113,6 +114,18 @@ tape( 'attached to the returned function is the generator seed', function test(
 	t.end();
 });
 
+tape( 'attached to the returned function is the generator state', function test( t ) {
+	var chisquare = factory();
+	t.equal( isUint32Array( chisquare.STATE ), true, 'has `STATE` property' );
+	t.end();
+});
+
+tape( 'attached to the returned function is the generator state size', function test( t ) {
+	var chisquare = factory();
+	t.equal( typeof chisquare.STATE_SIZE, 'number', 'has `STATE_SIZE` property' );
+	t.end();
+});
+
 tape( 'the function throws an error if degrees of freedom `k` is not a positive number (no options)', function test( t ) {
 	var values;
 	var i;
@@ -123,7 +136,8 @@ tape( 'the function throws an error if degrees of freedom `k` is not a positive
 		'5',
 		null,
 		true,
-		undefined,
+		false,
+		void 0,
 		NaN,
 		[],
 		function noop() {}
@@ -151,7 +165,8 @@ tape( 'the function throws an error if degrees of freedom `k` is not a positive
 		'5',
 		null,
 		true,
-		undefined,
+		false,
+		void 0,
 		NaN,
 		[],
 		{},
@@ -178,7 +193,8 @@ tape( 'the function throws an error if  provided an options argument which is no
 		'abc',
 		null,
 		true,
-		undefined,
+		false,
+		void 0,
 		NaN,
 		[],
 		function noop() {}
@@ -205,7 +221,8 @@ tape( 'the function throws an error if provided an options argument which is not
 		5,
 		null,
 		true,
-		undefined,
+		false,
+		void 0,
 		NaN,
 		[],
 		function noop() {}
@@ -320,3 +337,33 @@ tape( 'the function returns a PRNG for generating random numbers from a chi-squa
 		t.end();
 	}
 });
+
+tape( 'the returned function supports setting the generator state', function test( t ) {
+	var chisquare;
+	var state;
+	var arr;
+	var i;
+
+	chisquare = factory( 4 );
+
+	// Move to a future state...
+	for ( i = 0; i < 100; i++ ) {
+		chisquare();
+	}
+	// Capture the current state:
+	state = chisquare.STATE;
+
+	// Move to a future state...
+	arr = [];
+	for ( i = 0; i < 100; i++ ) {
+		arr.push( chisquare() );
+	}
+	// Set the state:
+	chisquare.STATE = state;
+
+	// Replay previously generated values...
+	for ( i = 0; i < 100; i++ ) {
+		t.equal( chisquare(), arr[ i ], 'returns expected value. i: '+i+'.' );
+	}
+	t.end();
+});