docs

Author: rtmigo

README.md

@@ -8,16 +8,17 @@
 Classes that implement all-purpose, rock-solid **random number generators**.
 
 Library priorities:
-- perfect match of the numbers on all platforms
+- generation of identical bit-accurate numbers regardless of the platform
+- reproducibility of the same random results in the future
+- high-quality randomness
 - performance
-- quality of the numbers produced
 
 Algorithms are [Xoshiro](https://prng.di.unimi.it/) for **quality** and 
 [Xorshift](https://en.wikipedia.org/wiki/Xorshift) for **speed**.
 
 # Speed
 
-Generating 50 million of random numbers with AOT-compiled binary. 
+Generating 50 million random numbers with AOT-compiled binary. 
 
 | Time (lower is better) | nextInt | nextDouble | nextBool |
 |------------------------|---------|------------|----------|
@@ -176,8 +177,8 @@ All the benchmarks on this page are from AOT-compiled binaries running on AMD A9
 
 The library has been thoroughly **tested to match reference numbers** generated by C algorithms. The
 sources in C are taken directly from scientific publications or the reference implementations by the inventors of the algorithms. The Xorshift128+ results are also matched to reference
-values from [JavaScript xorshift library](https://github.com/AndreasMadsen/xorshift), that tested
+values from [JavaScript xorshift library](https://github.com/AndreasMadsen/xorshift), which tested
 the 128+ similarly.
 
-Testing is done in the GitHub Actions cloud on **Windows**, **Ubuntu** and **macOS** in **VM** and **Node.js** modes.
+Testing is done in the GitHub Actions cloud on **Windows**, **Ubuntu**, and **macOS** in **VM** and **Node.js** modes.
 

lib/src/00_errors.dart

@@ -1,3 +1,3 @@
 class Unsupported64Error extends UnsupportedError {
-  Unsupported64Error() : super("Not a 64 bit system.");
-}
+  Unsupported64Error() : super('Not a 64 bit system.');
+}

lib/src/00_ints.dart

@@ -3,8 +3,8 @@
 
 
 // declaring int64 as BigInt to avoid JavaScript compilation errors
-final int INT64_LOWER_7_BYTES = BigInt.parse("0x00FFFFFFFFFFFFFF").toInt();
-final int INT64_MAX_POSITIVE = BigInt.parse("0x7FFFFFFFFFFFFFFF").toInt();
+final int INT64_LOWER_7_BYTES = int.parse('0x00FFFFFFFFFFFFFF');
+final int INT64_MAX_POSITIVE = int.parse('0x7FFFFFFFFFFFFFFF');
 const UINT32_MAX = 0xFFFFFFFF;
 const INT64_SUPPORTED = (1<<62) > (1<<61); // true for 64-bit systems (not for JS)
 

lib/src/10_random_base.dart

@@ -3,6 +3,7 @@
 
 
 import 'dart:math';
+
 import '00_ints.dart';
 
 abstract class RandomBase32 implements Random {

lib/src/seeding.dart

@@ -1,3 +1,4 @@
+@pragma('vm:prefer-inline')
 int mess2to64A(int a, int b) {
   // "The mix method was inspired by the mixing step of the lcg64_shift random engine"
   // <https://medium.com/@jeneticsga/creating-random-seeds-with-java-3df09bd02188>
@@ -8,6 +9,7 @@ int mess2to64A(int a, int b) {
   return c;
 }
 
+@pragma('vm:prefer-inline')
 int mess2to64B(int b, int a) {
   // Same as [mess2to64A], but with arguments swapped.
   var c = a^b;
@@ -17,10 +19,12 @@ int mess2to64B(int b, int a) {
   return c;
 }
 
+@pragma('vm:prefer-inline')
 int mess2to64C(int a, int b) {
   return mess2to64A(a+0xb35a6012, b*0xdcde19b9);
 }
 
+@pragma('vm:prefer-inline')
 int mess2to64D(int a, int b) {
   return mess2to64B(a+0x93999086, b*0x87b4f97a);
 }

lib/src/splitmix64.dart

@@ -1,13 +1,11 @@
 // SPDX-FileCopyrightText: (c) 2021 Art Galkin <github.com/rtmigo>
 // SPDX-License-Identifier: MIT
 
-import 'dart:math';
 
-import 'package:xrandom/src/seeding.dart';
+import 'package:xrandom/src/10_random_base.dart';
 
 import '00_errors.dart';
 import '00_ints.dart';
-import 'package:xrandom/src/10_random_base.dart';
 
 /// Random number generator based on `splitmix64` algorithm by S. Vigna (2015).
 /// The reference implementation in C can be found in

lib/src/xorshift128.dart

@@ -1,10 +1,10 @@
 // SPDX-FileCopyrightText: (c) 2021 Art Galkin <github.com/rtmigo>
 // SPDX-License-Identifier: MIT
 
+import 'package:xrandom/src/10_random_base.dart';
 import 'package:xrandom/src/seeding.dart';
 
 import '00_ints.dart';
-import 'package:xrandom/src/10_random_base.dart';
 
 /// Random number generator based on `xorshift128` algorithm by G. Marsaglia (2003).
 /// The reference implementation in C can be found in
@@ -21,7 +21,7 @@ class Xorshift128 extends RandomBase32
       RangeError.checkValueInInterval(d!, 0, UINT32_MAX);
 
       if (a==0 && b==0 && c==0 && d==0) {
-        throw ArgumentError("The seed should not consist of only zeros..");
+        throw ArgumentError('The seed should not consist of only zeros..');
       }
 
       _a = a;
@@ -41,6 +41,7 @@ class Xorshift128 extends RandomBase32
   }
   late int _a, _b, _c, _d;
 
+  @override
   int nextInt32() {
 
     // algorithm from p.5 of "Xorshift RNGs"

lib/src/xorshift128plus.dart

@@ -1,12 +1,11 @@
 // SPDX-FileCopyrightText: (c) 2021 Art Galkin <github.com/rtmigo>
 // SPDX-License-Identifier: MIT
 
-import 'package:xrandom/src/seeding.dart';
+import 'package:xrandom/src/10_random_base.dart';
 import 'package:xrandom/src/splitmix64.dart';
 
 import '00_errors.dart';
 import '00_ints.dart';
-import 'package:xrandom/src/10_random_base.dart';
 
 /// Random number generator based on `xorshift128+` algorithm by S.Vigna (2015).
 /// The reference implementation in C can be found in <https://arxiv.org/abs/1404.0390> (V3).
@@ -39,6 +38,7 @@ class Xorshift128p extends RandomBase64 {
 
   late int _S0, _S1;
 
+  @override
   int nextInt64() {
     // algorithm from "Further scramblings of Marsaglia’s xorshift generators"
     // by Sebastiano Vigna

lib/src/xorshift32.dart

@@ -3,7 +3,6 @@
 
 
 import 'package:xrandom/src/10_random_base.dart';
-import 'package:xrandom/src/seeding.dart';
 
 /// Random number generator based on `xorshift32` algorithm by G. Marsaglia (2003).
 /// The reference implementation in C can be found in

lib/src/xorshift64.dart

@@ -1,14 +1,12 @@
 // SPDX-FileCopyrightText: (c) 2021 Art Galkin <github.com/rtmigo>
 // SPDX-License-Identifier: MIT
 
-import 'dart:math';
 
-import 'package:xrandom/src/seeding.dart';
+import 'package:xrandom/src/10_random_base.dart';
 import 'package:xrandom/src/splitmix64.dart';
 
 import '00_errors.dart';
 import '00_ints.dart';
-import 'package:xrandom/src/10_random_base.dart';
 
 /// Random number generator based on `xorshift64` algorithm by G. Marsaglia (2003).
 /// The reference implementation in C can be found in
@@ -22,7 +20,7 @@ class Xorshift64 extends RandomBase64 {
     }
     if (seed != null) {
       if (seed == 0) {
-        throw RangeError("The seed must be greater than 0.");
+        throw RangeError('The seed must be greater than 0.');
       }
       _state = seed;
     } else {