feat(random): add a new pseudorandom number generator random/base/xorshift32

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

@@ -0,0 +1,346 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2025 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.
+
+-->
+
+# XORSHIFT
+
+> A 32-bit xorshift pseudorandom number generator ([XORSHIFT][xorshift]) based on George Marsaglia.
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var xorshift = require( '@stdlib/random/base/xorshift' );
+```
+
+#### xorshift()
+
+Returns a pseudorandom integer on the interval `[1, 4294967295]`.
+
+```javascript
+var r = xorshift();
+// returns <number>
+```
+
+#### xorshift.normalized()
+
+Returns a pseudorandom number on the interval `[0,1)`.
+
+```javascript
+var r = xorshift.normalized();
+// returns <number>
+```
+
+#### xorshift.factory( \[options] )
+
+Returns a 32-bit xorshift pseudorandom number generator ([XORSHIFT][xorshift]).
+
+```javascript
+var rand = xorshift.factory();
+```
+
+The function accepts the following `options`:
+
+-   **seed**: pseudorandom number generator seed.
+-   **state**: an [`Uint32Array`][@stdlib/array/uint32] containing pseudorandom number generator state. If provided, the function ignores the `seed` option.
+-   **copy**: `boolean` indicating whether to copy a provided pseudorandom number generator state. Setting this option to `false` allows sharing state between two or more pseudorandom number generators. Setting this option to `true` ensures that a returned generator has exclusive control over its internal state. Default: `true`.
+
+By default, a random integer is used to seed the returned generator. To seed the generator, provide either an `integer` on the interval `[1, 4294967295]`
+
+```javascript
+var rand = xorshift.factory({
+    'seed': 1234
+});
+
+var r = rand();
+// returns 332584831
+```
+
+or, for arbitrary length seeds, an array-like `object` containing unsigned 32-bit integers
+
+```javascript
+var Uint32Array = require( '@stdlib/array/uint32' );
+
+var rand = xorshift.factory({
+    'seed': new Uint32Array( [ 1234 ] )
+});
+
+var r = rand();
+// returns 332584831
+```
+
+To return a generator having a specific initial state, set the generator `state` option.
+
+```javascript
+// Generate pseudorandom numbers, thus progressing the generator state:
+var r;
+var i;
+for ( i = 0; i < 1000; i++ ) {
+    r = xorshift();
+}
+
+// Create a new PRNG initialized to the current state of `xorshift`:
+var rand = xorshift.factory({
+    'state': xorshift.state
+});
+
+// Test that the generated pseudorandom numbers are the same:
+var bool = ( rand() === xorshift() );
+// returns true
+```
+
+#### xorshift.NAME
+
+The generator name.
+
+```javascript
+var str = xorshift.NAME;
+// returns 'xorshift'
+```
+
+#### xorshift.MIN
+
+Minimum possible value.
+
+```javascript
+var min = xorshift.MIN;
+// returns 1
+```
+
+#### xorshift.MAX
+
+Maximum possible value.
+
+```javascript
+var max = xorshift.MAX;
+// returns 4294967295
+```
+
+#### xorshift.seed
+
+The value used to seed `xorshift()`.
+
+```javascript
+// Generate pseudorandom values...
+var r;
+var i;
+for ( i = 0; i < 100; i++ ) {
+    r = xorshift();
+}
+
+// Generate the same pseudorandom values...
+var rand = xorshift.factory({
+    'seed': xorshift.seed
+});
+for ( i = 0; i < 100; i++ ) {
+    r = rand();
+}
+```
+
+#### xorshift.seedLength
+
+Length of generator seed.
+
+```javascript
+var len = xorshift.seedLength;
+// returns <number>
+```
+
+#### xorshift.state
+
+Writable property for getting and setting the generator state.
+
+```javascript
+var r = xorshift();
+// returns <number>
+
+r = xorshift();
+// returns <number>
+
+// ...
+
+// Get the current state:
+var state = xorshift.state;
+// returns <Uint32Array>
+
+r = xorshift();
+// returns <number>
+
+r = xorshift();
+// returns <number>
+
+// Reset the state:
+xorshift.state = state;
+
+// Replay the last two pseudorandom numbers:
+r = xorshift();
+// returns <number>
+
+r = xorshift();
+// returns <number>
+
+// ...
+```
+
+#### xorshift.stateLength
+
+Length of generator state.
+
+```javascript
+var len = xorshift.stateLength;
+// returns <number>
+```
+
+#### xorshift.byteLength
+
+Size (in bytes) of generator state.
+
+```javascript
+var sz = xorshift.byteLength;
+// returns <number>
+```
+
+#### xorshift.toJSON()
+
+Serializes the pseudorandom number generator as a JSON object.
+
+```javascript
+var o = xorshift.toJSON();
+// returns { 'type': 'PRNG', 'name': '...', 'state': {...}, 'params': [] }
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   The generator has a period of `2^32-1`.
+-   Like all [LFSR][lfsr]s, the parameters have to be chosen very carefully in order to achieve a long period. For execution in software, xorshift generators are among the fastest PRNGs, requiring very small code and state. However, they do not pass every statistical test without further refinement.
+-   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 does **not** update the existing shared state and, instead, points to the newly provided state array. In order to synchronize PRNG output according to the new shared state array, the state array for **each** relevant PRNG must be **explicitly** set.
+-   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).
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var xorshift = require( '@stdlib/random/base/xorshift' );
+
+// Generate pseudorandom numbers...
+var i;
+for ( i = 0; i < 100; i++ ) {
+    console.log( xorshift() );
+}
+
+// Create a new pseudorandom number generator...
+var seed = 1234;
+var rand = xorshift.factory({
+    'seed': seed
+});
+for ( i = 0; i < 100; i++ ) {
+    console.log( rand() );
+}
+
+// Create another pseudorandom number generator using a previous seed...
+rand = xorshift.factory({
+    'seed': xorshift.seed
+});
+for ( i = 0; i < 100; i++ ) {
+    console.log( rand() );
+}
+```
+
+</section>
+
+<!-- /.examples -->
+
+* * *
+
+<section class="references">
+
+## References
+
+-   Marsaglia, G. 2003. "Xorshift RNGs." _Journal of Statistical Software_ 8 (14). Los Angeles, CA, USA: American Statistical Association: 1–6. doi:[10.18637/jss.v008.i14][@marsaglia:2003].
+
+</section>
+
+<!-- /.references -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+* * *
+
+## See Also
+
+<!--
+-   <span class="package-name">[`@stdlib/random/array/xorshift`][@stdlib/random/array/xorshift]</span><span class="delimiter">: </span><span class="description">create an array containing pseudorandom numbers generated using a 32-bit xorshift pseudorandom number generator based on George Marsaglia.</span>
+-   <span class="package-name">[`@stdlib/random/iter/xorshift`][@stdlib/random/iter/xorshift]</span><span class="delimiter">: </span><span class="description">create an iterator for a 32-bit xorshift pseudorandom number generator based on George Marsaglia.</span>
+-   <span class="package-name">[`@stdlib/random/streams/xorshift`][@stdlib/random/streams/xorshift]</span><span class="delimiter">: </span><span class="description">create a readable stream for a 32-bit xorshift pseudorandom number generator based on George Marsaglia.</span>
+-->
+
+-   <span class="package-name">[`@stdlib/random/base/mt19937`][@stdlib/random/base/mt19937]</span><span class="delimiter">: </span><span class="description">A 32-bit Mersenne Twister pseudorandom number generator.</span>
+-   <span class="package-name">[`@stdlib/random/base/randi`][@stdlib/random/base/randi]</span><span class="delimiter">: </span><span class="description">pseudorandom numbers having integer values.</span>
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+[xorshift]: https://en.wikipedia.org/wiki/Xorshift
+
+[lfsr]: https://en.wikipedia.org/wiki/Linear-feedback_shift_register
+
+[@marsaglia:2003]: https://doi.org/10.18637/jss.v008.i14
+
+[@stdlib/array/uint32]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/uint32
+
+<!-- <related-links> -->
+
+<!--
+[@stdlib/random/array/xorshift]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/random/array/xorshift
+
+[@stdlib/random/iter/xorshift]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/random/iter/xorshift
+
+[@stdlib/random/streams/xorshift]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/random/streams/xorshift
+-->
+
+[@stdlib/random/base/mt19937]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/random/base/mt19937
+
+[@stdlib/random/base/randi]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/random/base/randi
+
+<!-- </related-links> -->
+
+</section>
+
+<!-- /.links -->