feat: add xorshift32 pseudorandom number generator

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

@@ -0,0 +1,282 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2026 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.
+
+-->
+
+# Xorshift32
+
+> A 32-bit [xorshift32][xorshift32] pseudorandom number generator.
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var xorshift32 = require( '@stdlib/random/base/xorshift32' );
+```
+
+#### xorshift32()
+
+Returns a pseudorandom unsigned 32-bit integer on the interval `[0, 4294967295]`
+
+```javascript
+var r = xorshift32();
+// returns <number>
+```
+
+#### xorshift32.normalized()
+
+Returns a pseudorandom number on the interval [0, 1) with 53-bit precision.
+
+```javascript
+var r = xorshift32.normalized();
+// returns <number>
+```
+
+#### xorshift32.factory( \[options] )
+
+Returns a 32-bit [xorshift32][xorshift32] pseudorandom number generator.
+
+```javascript
+var rand = xorshift32.factory();
+```
+
+The function accepts the following options:
+
+-   **seed**: pseudorandom number generator seed. Must be an integer on the interval `[1, 4294967295]`. If a seed is not provided, one is automatically generated.
+-   **state**: a `Uint32Array` containing pseudorandom number generator state. If provided, the `seed` option is ignored.
+-   **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` .
+
+To seed the generator, provide a nonzero integer on the interval `[1, 4294967295]`:
+
+```javascript
+var rand = xorshift32.factory({
+    'seed': 1234
+});
+
+var r = rand();
+// returns <number>
+```
+
+To use a custom generator state, provide a `Uint32Array`:
+
+```javascript
+var rand1 = xorshift32.factory();
+var state = rand1.state;
+
+var rand2 = xorshift32.factory({
+    'state': state,
+    'copy': false
+});
+
+var r = rand2();
+// returns <number>
+```
+
+#### xorshift32.NAME
+
+The generator name.
+
+```javascript
+var str = xorshift32.NAME;
+// returns 'xorshift32'
+```
+
+#### xorshift32.MIN
+
+Minimum possible value.
+
+```javascript
+var min = xorshift32.MIN;
+// returns 1
+```
+
+#### xorshift32.MAX
+
+Maximum possible value.
+
+```javascript
+var max = xorshift32.MAX;
+// returns 4294967295
+```
+
+#### xorshift32.seed
+
+The value used to seed `xorshift32()`.
+
+```javascript
+// Generate pseudorandom values...
+var r;
+var i;
+for ( i = 0; i < 100; i++ ) {
+    r = xorshift32();
+}
+
+// Generate the same pseudorandom values...
+var rand = xorshift32.factory({
+    'seed': xorshift32.seed[ 0 ]
+});
+for ( i = 0; i < 100; i++ ) {
+    r = rand();
+}
+```
+
+#### xorshift32.seedLength
+
+Length of generator seed.
+
+```javascript
+var len = xorshift32.seedLength;
+// returns 1
+```
+
+#### xorshift32.state
+
+The current pseudorandom number generator state.
+
+```javascript
+var state = xorshift32.state;
+// returns <Uint32Array>
+```
+
+#### xorshift32.stateLength
+
+Length of generator state.
+
+```javascript
+var len = xorshift32.stateLength;
+// returns 6
+```
+
+#### xorshift32.byteLength
+
+Size of generator state in bytes.
+
+```javascript
+var nbytes = xorshift32.byteLength;
+// returns 24
+```
+
+#### xorshift32.toJSON()
+
+Serializes the pseudorandom number generator as a JSON object.
+
+```javascript
+var o = xorshift32.toJSON();
+// returns { 'type': 'PRNG', 'name': '...', 'state': {...}, 'params': [] }
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   [Xorshift32][xorshift32] is **not** cryptographically secure. Do not use it for cryptographic operations.
+-   The generator uses a single 32-bit internal state, making it extremely lightweight and fast.
+-   While the generator is very efficient, its statistical quality is lower than generators like Mersenne Twister. It is suitable for simulations and statistical applications, but not for security-sensitive use cases.
+-   The period of Xorshift32 is approximately 2^32 - 1.
+-   The generator state can be explicitly accessed and saved for reproducibility.
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var xorshift32 = require( '@stdlib/random/base/xorshift32' );
+
+// Generate pseudorandom numbers...
+var i;
+for ( i = 0; i < 100; i++ ) {
+    console.log( xorshift32() );
+}
+
+// Create a new pseudorandom number generator...
+var seed = 1234;
+var rand = xorshift32.factory({
+    'seed': seed
+});
+for ( i = 0; i < 100; i++ ) {
+    console.log( rand() );
+}
+
+// Create another pseudorandom number generator using a previous seed...
+rand = xorshift32.factory({
+    'seed': xorshift32.seed[ 0 ]
+});
+for ( i = 0; i < 100; i++ ) {
+    console.log( rand() );
+}
+```
+
+</section>
+
+<!-- /.examples -->
+
+* * *
+
+<section class="references">
+
+## References
+
+-   George Marsaglia. 2003. "Xorshift RNGs." **Journal of Statistical Software**, 8(14).
+
+</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/base/minstd][@stdlib/random/base/minstd]</span><span class="delimiter">: </span><span class="description">A linear congruential pseudorandom number generator (LCG) based on Park and Miller.</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">
+
+[xorshift32]: https://en.wikipedia.org/wiki/Xorshift
+
+<!-- <related-links> -->
+
+[@stdlib/random/base/minstd]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/random/base/minstd
+
+[@stdlib/random/base/randi]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/random/base/randi
+
+<!-- </related-links> -->
+
+</section>
+
+<!-- /.links -->