Add support for serializing a PRNG as JSON

Author: kgryte

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

@@ -251,6 +251,15 @@ var sz = hypergeometric.byteLength;
 // returns <number>
 ```
 
+#### hypergeometric.toJSON()
+
+Serializes the pseudorandom number generator as a JSON object.
+
+```javascript
+var o = hypergeometric.toJSON();
+// returns { 'type': 'PRNG', 'name': '...', 'state': {...} }
+```
+
 </section>
 
 <!-- /.usage -->

lib/node_modules/@stdlib/random/base/hypergeometric/benchmark/benchmark.to_json.js

@@ -0,0 +1,48 @@
+/**
+* @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.
+*/
+
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench' );
+var isObject = require( '@stdlib/assert/is-plain-object' );
+var pkg = require( './../package.json' ).name;
+var rand = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg+':toJSON', function benchmark( b ) {
+	var o;
+	var i;
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		o = rand.toJSON();
+		if ( typeof o !== 'object' ) {
+			b.fail( 'should return an object' );
+		}
+	}
+	b.toc();
+	if ( !isObject( o ) ) {
+		b.fail( 'should return an object' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});

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

@@ -165,6 +165,20 @@
     --------
     > var sz = {{alias}}.byteLength;
 
+
+{{alias}}.toJSON()
+    Serializes the pseudorandom number generator as a JSON object.
+
+    Returns
+    -------
+    out: Object
+        JSON representation.
+
+    Examples
+    --------
+    > var o = {{alias}}.toJSON()
+    { 'type': 'PRNG', 'name': '...', 'state': {...} }
+
     See Also
     --------
 

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

@@ -23,10 +23,12 @@
 var setReadOnly = require( '@stdlib/utils/define-read-only-property' );
 var setReadOnlyAccessor = require( '@stdlib/utils/define-read-only-accessor' );
 var setReadWriteAccessor = require( '@stdlib/utils/define-read-write-accessor' );
+var setNonEnumerableReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' );
 var isObject = require( '@stdlib/assert/is-plain-object' );
 var randu = require( '@stdlib/random/base/mt19937' ).factory;
 var isNonNegativeInteger = require( '@stdlib/math/base/assert/is-nonnegative-integer' );
 var PINF = require( '@stdlib/constants/math/float64-pinf' );
+var typedarray2json = require( '@stdlib/array/to-json' );
 var validate = require( './validate.js' );
 var hypergeometric0 = require( './hypergeometric.js' );
 
@@ -115,6 +117,7 @@ function factory() {
 	setReadWriteAccessor( prng, 'state', getState, setState );
 	setReadOnlyAccessor( prng, 'stateLength', getStateLength );
 	setReadOnlyAccessor( prng, 'byteLength', getStateSize );
+	setNonEnumerableReadOnly( prng, 'toJSON', toJSON );
 	setReadOnly( prng, 'PRNG', rand );
 
 	rand = rand.normalized;
@@ -183,6 +186,24 @@ function factory() {
 		rand.state = s;
 	}
 
+	/**
+	* Serializes the pseudorandom number generator as a JSON object.
+	*
+	* ## Notes
+	*
+	* -   `JSON.stringify()` implicitly calls this method when stringifying a PRNG.
+	*
+	* @private
+	* @returns {Object} JSON representation
+	*/
+	function toJSON() {
+		var out = {};
+		out.type = 'PRNG';
+		out.name = prng.NAME;
+		out.state = typedarray2json( rand.state );
+		return out;
+	}
+
 	/**
 	* Returns a random number drawn from a hypergeometric distribution with bound parameters.
 	*

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

@@ -28,6 +28,7 @@ var isnan = require( '@stdlib/math/base/assert/is-nan' );
 var isUint32Array = require( '@stdlib/assert/is-uint32array' );
 var UINT32_MAX = require( '@stdlib/constants/math/uint32-max' );
 var Uint32Array = require( '@stdlib/array/uint32' );
+var typedarray2json = require( '@stdlib/array/to-json' );
 var factory = require( './../lib/factory.js' );
 
 
@@ -519,6 +520,21 @@ tape( 'attached to the returned function is the generator state size', function
 	t.end();
 });
 
+tape( 'attached to the returned function is a method to serialize the generator as a JSON object', function test( t ) {
+	var hypergeometric;
+	var o;
+
+	hypergeometric = factory();
+	t.equal( typeof hypergeometric.toJSON, 'function', 'has method' );
+
+	o = hypergeometric.toJSON();
+	t.equal( o.type, 'PRNG', 'has property' );
+	t.equal( o.name, hypergeometric.NAME, 'has property' );
+	t.deepEqual( o.state, typedarray2json( hypergeometric.state ), 'has property' );
+
+	t.end();
+});
+
 tape( 'when called without arguments, the function returns a PRNG that returns `NaN` when provided a population size equal to `NaN`', function test( t ) {
 	var hypergeometric;
 	var r;

lib/node_modules/@stdlib/random/base/hypergeometric/test/test.js

@@ -41,6 +41,11 @@ tape( 'attached to the main export is a method to generate pseudorandom number g
 	t.end();
 });
 
+tape( 'attached to the main export is a method to serialize a pseudorandom number generator as JSON', function test( t ) {
+	t.equal( typeof hypergeometric.toJSON, 'function', 'has method' );
+	t.end();
+});
+
 tape( 'attached to the main export is the generator name', function test( t ) {
 	t.equal( hypergeometric.NAME, 'hypergeometric', 'has property' );
 	t.end();