Skip to content

Commit 41768f5

Browse files
impawstarlightimpawstarlight
committed
docs: update docs and comments
--- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: passed - task: lint_repl_help status: passed - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: passed - task: lint_javascript_tests status: passed - task: lint_javascript_benchmarks status: passed - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: passed - task: lint_c_examples status: passed - task: lint_c_benchmarks status: passed - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: passed - task: lint_license_headers status: passed ---
1 parent 3386039 commit 41768f5

File tree

23 files changed

+152
-130
lines changed

23 files changed

+152
-130
lines changed

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

Lines changed: 24 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
33
@license Apache-2.0
44
5-
Copyright (c) 2018 The Stdlib Authors.
5+
Copyright (c) 2025 The Stdlib Authors.
66
77
Licensed under the Apache License, Version 2.0 (the "License");
88
you may not use this file except in compliance with the License.
@@ -20,7 +20,7 @@ limitations under the License.
2020

2121
# XORSHIFT
2222

23-
> A linear congruential pseudorandom number generator ([LCG][lcg]) based on Park and Miller.
23+
> A 32-bit xorshift pseudorandom number generator ([XORSHIFT][xorshift]) based on George Marsaglia.
2424
2525
<section class="usage">
2626

@@ -32,7 +32,7 @@ var xorshift = require( '@stdlib/random/base/xorshift' );
3232

3333
#### xorshift()
3434

35-
Returns a pseudorandom integer on the interval `[1, 2147483646]`.
35+
Returns a pseudorandom integer on the interval `[1, 4294967295]`.
3636

3737
```javascript
3838
var r = xorshift();
@@ -50,7 +50,7 @@ var r = xorshift.normalized();
5050

5151
#### xorshift.factory( \[options] )
5252

53-
Returns a linear congruential pseudorandom number generator ([LCG][lcg]).
53+
Returns a 32-bit xorshift pseudorandom number generator ([XORSHIFT][xorshift]).
5454

5555
```javascript
5656
var rand = xorshift.factory();
@@ -59,10 +59,10 @@ var rand = xorshift.factory();
5959
The function accepts the following `options`:
6060

6161
- **seed**: pseudorandom number generator seed.
62-
- **state**: an [`Int32Array`][@stdlib/array/int32] containing pseudorandom number generator state. If provided, the function ignores the `seed` option.
62+
- **state**: an [`Uint32Array`][@stdlib/array/uint32] containing pseudorandom number generator state. If provided, the function ignores the `seed` option.
6363
- **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`.
6464

65-
By default, a random integer is used to seed the returned generator. To seed the generator, provide either an `integer` on the interval `[1, 2147483646]`
65+
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]`
6666

6767
```javascript
6868
var rand = xorshift.factory({
@@ -73,13 +73,13 @@ var r = rand();
7373
// returns 332584831
7474
```
7575

76-
or, for arbitrary length seeds, an array-like `object` containing signed 32-bit integers
76+
or, for arbitrary length seeds, an array-like `object` containing unsigned 32-bit integers
7777

7878
```javascript
79-
var Int32Array = require( '@stdlib/array/int32' );
79+
var Uint32Array = require( '@stdlib/array/uint32' );
8080

8181
var rand = xorshift.factory({
82-
'seed': new Int32Array( [ 1234 ] )
82+
'seed': new Uint32Array( [ 1234 ] )
8383
});
8484

8585
var r = rand();
@@ -234,8 +234,8 @@ var o = xorshift.toJSON();
234234

235235
## Notes
236236

237-
- The generator has a period of approximately `2.1e9` (see [Numerical Recipes in C, 2nd Edition](#references), p. 279).
238-
- An [LCG][lcg] is fast and uses little memory. On the other hand, because the generator is a simple [linear congruential generator][lcg], the generator has recognized shortcomings. By today's PRNG standards, the generator's period is relatively short. More importantly, the "randomness quality" of the generator's output is lacking. These defects make the generator unsuitable, for example, in Monte Carlo simulations and in cryptographic applications. For more on the advantages and disadvantages of [LCGs][lcg], see [Wikipedia][pros-cons].
237+
- The generator has a period of `2^32-1`.
238+
- 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.
239239
- 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.
240240
- 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).
241241

@@ -286,8 +286,7 @@ for ( i = 0; i < 100; i++ ) {
286286

287287
## References
288288

289-
- Park, S. K., and K. W. Miller. 1988. "Random Number Generators: Good Ones Are Hard to Find." _Communications of the ACM_ 31 (10). New York, NY, USA: ACM: 1192–1201. doi:[10.1145/63039.63042][@park:1988].
290-
- Press, William H., Brian P. Flannery, Saul A. Teukolsky, and William T. Vetterling. 1992. _Numerical Recipes in C: The Art of Scientific Computing, Second Edition_. Cambridge University Press.
289+
- 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].
291290

292291
</section>
293292

@@ -301,10 +300,12 @@ for ( i = 0; i < 100; i++ ) {
301300

302301
## See Also
303302

304-
- <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 linear congruential pseudorandom number generator (LCG).</span>
305-
- <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 linear congruential pseudorandom number generator (LCG) based on Park and Miller.</span>
306-
- <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 linear congruential pseudorandom number generator (LCG) based on Park and Miller.</span>
307-
- <span class="package-name">[`@stdlib/random/base/xorshift-shuffle`][@stdlib/random/base/xorshift-shuffle]</span><span class="delimiter">: </span><span class="description">A linear congruential pseudorandom number generator (LCG) whose output is shuffled.</span>
303+
<!--
304+
- <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>
305+
- <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>
306+
- <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>
307+
-->
308+
308309
- <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>
309310
- <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>
310311

@@ -316,23 +317,23 @@ for ( i = 0; i < 100; i++ ) {
316317

317318
<section class="links">
318319

319-
[lcg]: https://en.wikipedia.org/wiki/Linear_congruential_generator
320+
[xorshift]: https://en.wikipedia.org/wiki/Xorshift
320321

321-
[pros-cons]: https://en.wikipedia.org/wiki/Linear_congruential_generator#Advantages_and_disadvantages_of_LCGs
322+
[lfsr]: https://en.wikipedia.org/wiki/Linear-feedback_shift_register
322323

323-
[@park:1988]: http://dx.doi.org/10.1145/63039.63042
324+
[@marsaglia:2003]: https://doi.org/10.18637/jss.v008.i14
324325

325-
[@stdlib/array/int32]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/int32
326+
[@stdlib/array/uint32]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/uint32
326327

327328
<!-- <related-links> -->
328329

330+
<!--
329331
[@stdlib/random/array/xorshift]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/random/array/xorshift
330332
331333
[@stdlib/random/iter/xorshift]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/random/iter/xorshift
332334
333335
[@stdlib/random/streams/xorshift]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/random/streams/xorshift
334-
335-
[@stdlib/random/base/xorshift-shuffle]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/random/base/xorshift-shuffle
336+
-->
336337

337338
[@stdlib/random/base/mt19937]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/random/base/mt19937
338339

‎lib/node_modules/@stdlib/random/base/xorshift/benchmark/benchmark.factory.js‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* @license Apache-2.0
33
*
4-
* Copyright (c) 2018 The Stdlib Authors.
4+
* Copyright (c) 2025 The Stdlib Authors.
55
*
66
* Licensed under the Apache License, Version 2.0 (the "License");
77
* you may not use this file except in compliance with the License.
@@ -22,7 +22,7 @@
2222

2323
var bench = require( '@stdlib/bench' );
2424
var isnan = require( '@stdlib/math/base/assert/is-nan' );
25-
var Int32Array = require( '@stdlib/array/int32' );
25+
var Uint32Array = require( '@stdlib/array/int32' );
2626
var pkg = require( './../package.json' ).name;
2727
var factory = require( './../lib' ).factory;
2828

@@ -81,7 +81,7 @@ bench( pkg+':factory:seed=<array>', function benchmark( b ) {
8181

8282
opts = {};
8383

84-
seed = new Int32Array( 10 );
84+
seed = new Uint32Array( 10 );
8585
for ( i = 0; i < seed.length; i++ ) {
8686
seed[ i ] = 123 + i;
8787
}

‎lib/node_modules/@stdlib/random/base/xorshift/benchmark/benchmark.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* @license Apache-2.0
33
*
4-
* Copyright (c) 2018 The Stdlib Authors.
4+
* Copyright (c) 2025 The Stdlib Authors.
55
*
66
* Licensed under the Apache License, Version 2.0 (the "License");
77
* you may not use this file except in compliance with the License.

‎lib/node_modules/@stdlib/random/base/xorshift/benchmark/benchmark.to_json.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* @license Apache-2.0
33
*
4-
* Copyright (c) 2018 The Stdlib Authors.
4+
* Copyright (c) 2025 The Stdlib Authors.
55
*
66
* Licensed under the Apache License, Version 2.0 (the "License");
77
* you may not use this file except in compliance with the License.

‎lib/node_modules/@stdlib/random/base/xorshift/benchmark/c/Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
#/
22
# @license Apache-2.0
33
#
4-
# Copyright (c) 2018 The Stdlib Authors.
4+
# Copyright (c) 2025 The Stdlib Authors.
55
#
66
# Licensed under the Apache License, Version 2.0 (the "License");
77
# you may not use this file except in compliance with the License.

‎lib/node_modules/@stdlib/random/base/xorshift/benchmark/c/benchmark.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* @license Apache-2.0
33
*
4-
* Copyright (c) 2018 The Stdlib Authors.
4+
* Copyright (c) 2025 The Stdlib Authors.
55
*
66
* Licensed under the Apache License, Version 2.0 (the "License");
77
* you may not use this file except in compliance with the License.

‎lib/node_modules/@stdlib/random/base/xorshift/docs/repl.txt‎

Lines changed: 15 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,16 @@
11

22
{{alias}}()
3-
Returns a pseudorandom integer on the interval `[1, 2147483646]`.
3+
Returns a pseudorandom integer on the interval `[1, 4294967295]`.
44

5-
This pseudorandom number generator (PRNG) is a linear congruential
6-
pseudorandom number generator (LCG) based on Park and Miller.
5+
This pseudorandom number generator (PRNG) is a linear-feedback
6+
shift-register (LFSR) PRNG based on George Marsaglia.
77

8-
The generator has a period of approximately `2.1e9`.
8+
The generator has a period `2^32-1`.
99

10-
An LCG is fast and uses little memory. On the other hand, because the
11-
generator is a simple LCG, the generator has recognized shortcomings. By
12-
today's PRNG standards, the generator's period is relatively short. More
13-
importantly, the "randomness quality" of the generator's output is lacking.
14-
These defects make the generator unsuitable, for example, in Monte Carlo
15-
simulations and in cryptographic applications.
10+
Like all LFSRs, the parameters have to be chosen very carefully in order
11+
to achieve a long period. For execution in software, xorshift generators
12+
are among the fastest PRNGs, requiring very small code and state. However,
13+
they do not pass every statistical test without further refinement.
1614

1715
Returns
1816
-------
@@ -38,20 +36,19 @@
3836

3937

4038
{{alias}}.factory( [options] )
41-
Returns a linear congruential pseudorandom number generator (LCG).
42-
39+
Returns a 32-bit xorshift pseudorandom number generator.
4340
Parameters
4441
----------
4542
options: Object (optional)
4643
Options.
4744

4845
options.seed: integer|ArrayLikeObject<integer> (optional)
4946
Pseudorandom number generator seed. The seed may be either a positive
50-
signed 32-bit integer on the interval `[1, 2147483646]` or, for
51-
arbitrary length seeds, an array-like object containing signed 32-bit
47+
unsigned 32-bit integer on the interval `[1, 4294967295]` or, for
48+
arbitrary length seeds, an array-like object containing unsigned 32-bit
5249
integers.
5350

54-
options.state: Int32Array (optional)
51+
options.state: Uint32Array (optional)
5552
Pseudorandom number generator state. If provided, the `seed` option is
5653
ignored.
5754

@@ -77,7 +74,7 @@
7774
// Provide a seed:
7875
> rand = {{alias}}.factory( { 'seed': 1234 } );
7976
> r = rand()
80-
20739838
77+
332584831
8178

8279

8380
{{alias}}.NAME
@@ -104,7 +101,7 @@
104101
Examples
105102
--------
106103
> var v = {{alias}}.MAX
107-
2147483646
104+
4294967295
108105

109106

110107
{{alias}}.seed
@@ -137,7 +134,7 @@
137134

138135
// Get the current state:
139136
> var state = {{alias}}.state
140-
<Int32Array>
137+
<Uint32Array>
141138

142139
> r = {{alias}}()
143140
<number>

‎lib/node_modules/@stdlib/random/base/xorshift/docs/types/index.d.ts‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/*
22
* @license Apache-2.0
33
*
4-
* Copyright (c) 2019 The Stdlib Authors.
4+
* Copyright (c) 2025 The Stdlib Authors.
55
*
66
* Licensed under the Apache License, Version 2.0 (the "License");
77
* you may not use this file except in compliance with the License.
@@ -95,29 +95,29 @@ interface PRNG {
9595
}
9696

9797
/**
98-
* Interface for generating pseudorandom integers on the interval `[1, 2147483646]`.
98+
* Interface for generating pseudorandom integers on the interval `[1, 4294967295]`.
9999
*/
100100
interface NullaryFunction extends PRNG {
101101
/**
102-
* Returns a pseudorandom integer on the interval `[1, 2147483646]`.
102+
* Returns a pseudorandom integer on the interval `[1, 4294967295]`.
103103
*
104104
* @returns pseudorandom number
105105
*/
106106
(): number;
107107
}
108108

109109
/**
110-
* Interface for generating pseudorandom integers on the interval `[1, 2147483646]`.
110+
* Interface for generating pseudorandom integers on the interval `[1, 4294967295]`.
111111
*/
112112
interface Random extends PRNG {
113113
/**
114-
* Returns a pseudorandom integer on the interval `[1, 2147483646]`.
114+
* Returns a pseudorandom integer on the interval `[1, 4294967295]`.
115115
*
116116
* ## Notes
117117
*
118-
* - This pseudorandom number generator (PRNG) is a linear congruential pseudorandom number generator (LCG) based on Park and Miller.
119-
* - The generator has a period of approximately `2.1e9`.
120-
* - An LCG is fast and uses little memory. On the other hand, because the generator is a simple LCG, the generator has recognized shortcomings. By today's PRNG standards, the generator's period is relatively short. More importantly, the "randomness quality" of the generator's output is lacking. These defects make the generator unsuitable, for example, in Monte Carlo simulations and in cryptographic applications.
118+
* - This pseudorandom number generator (PRNG) is a 32-bit xorshift pseudorandom number generator based on George Marsaglia.
119+
* - The generator has a period of `2^32-1`.
120+
* - Like all LFSRs, 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.
121121
*
122122
* @returns pseudorandom number
123123
*
@@ -139,7 +139,7 @@ interface Random extends PRNG {
139139
normalized(): number;
140140

141141
/**
142-
* Returns a linear congruential pseudorandom number generator (LCG).
142+
* Returns a 32-bit xorshift pseudorandom number generator.
143143
*
144144
* @param options - function options
145145
* @param options.seed - pseudorandom number generator seed
@@ -164,13 +164,13 @@ interface Random extends PRNG {
164164
}
165165

166166
/**
167-
* Returns a pseudorandom integer on the interval `[1, 2147483646]`.
167+
* Returns a pseudorandom integer on the interval `[1, 4294967295]`.
168168
*
169169
* ## Notes
170170
*
171-
* - This pseudorandom number generator (PRNG) is a linear congruential pseudorandom number generator (LCG) based on Park and Miller.
172-
* - The generator has a period of approximately `2.1e9`.
173-
* - An LCG is fast and uses little memory. On the other hand, because the generator is a simple LCG, the generator has recognized shortcomings. By today's PRNG standards, the generator's period is relatively short. More importantly, the "randomness quality" of the generator's output is lacking. These defects make the generator unsuitable, for example, in Monte Carlo simulations and in cryptographic applications.
171+
* - This pseudorandom number generator (PRNG) is a 32-bit xorshift pseudorandom number generator based on George Marsaglia.
172+
* - The generator has a period of `2^32-1`.
173+
* - Like all LFSRs, 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.
174174
*
175175
* @returns pseudorandom number
176176
*

‎lib/node_modules/@stdlib/random/base/xorshift/docs/types/test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/*
22
* @license Apache-2.0
33
*
4-
* Copyright (c) 2019 The Stdlib Authors.
4+
* Copyright (c) 2025 The Stdlib Authors.
55
*
66
* Licensed under the Apache License, Version 2.0 (the "License");
77
* you may not use this file except in compliance with the License.

‎lib/node_modules/@stdlib/random/base/xorshift/examples/c/Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
#/
22
# @license Apache-2.0
33
#
4-
# Copyright (c) 2018 The Stdlib Authors.
4+
# Copyright (c) 2025 The Stdlib Authors.
55
#
66
# Licensed under the Apache License, Version 2.0 (the "License");
77
# you may not use this file except in compliance with the License.

0 commit comments

Comments
 (0)