Skip to content

Commit

Permalink
docs
Browse files Browse the repository at this point in the history
  • Loading branch information
rtmigo committed Mar 31, 2021
1 parent 247d311 commit 9c0faba
Showing 1 changed file with 34 additions and 31 deletions.
65 changes: 34 additions & 31 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -186,17 +186,20 @@ quoteOfTheDay = quotes[ random.nextInt(quotes.length) ];

# Compatibility

TL;DR `Xrandom`, `Qrandom`, `Drandom` work on all platforms. Others may not work on JS.
TL;DR `Xrandom`, `Qrandom`, `Drandom` work on all platforms. Others may not work
on JS.

The library is written in pure Dart. Therefore, it works wherever Dart works.

But some of the classes need full support for 64-bit integers.
**JavaScript** actually only supports **53 bits**. If your target platform is JavaScript, then the selection will have to be
narrowed down to the options marked with **[] checkmark in the JS column**. Trying
to create a incompatible object in JavaScript-transpiled code will lead to `UnsupportedError`.
But some of the classes need full support for 64-bit integers. *JavaScript**
actually only supports **53 bits**. If your target platform is JavaScript, then
the selection will have to be narrowed down to the options marked with **[]
checkmark in the JS column**. Trying to create a incompatible object in
JavaScript-transpiled code will lead to `UnsupportedError`.

If your code compiles to native (like in **Flutter** apps for **Android** and **iOS**),
**64-bit** generators will work best for you. For example, `Xorshift64` for speed or `Xoshiro256pp` for quality.
If your code compiles to native (like in **Flutter** apps for **Android** and
*iOS**), *64-bit** generators will work best for you. For example, `Xorshift64`
for speed or `Xoshiro256pp` for quality.

# More benchmarks

Expand All @@ -223,28 +226,28 @@ library.

# Consistency

The library has been thoroughly **tested to match [reference numbers](https://github.com/rtmigo/randomref)** generated
by the same algorithms implemented in C++. Not only `int`s, but also numbers
converted to `double` including all decimal places that the compiler takes
into account.

The sources in C are taken directly from scientific publications or the
reference implementations by the authors of the algorithms.
The Xorshift128+ results are also matched to reference values from
[JavaScript xorshift library](https://github.com/AndreasMadsen/xorshift),
which tested the 128+ similarly.

Therefore, the sequence generated for example by the
`Xoshiro128pp.nextRaw32()` with the seed `(1, 2, 3, 4)` is the same as the
[C99 code](https://prng.di.unimi.it/xoshiro128plusplus.c) will produce
with the same seed.

The `double` values will also be the same as if the upper bits of `uint64_t` type
were converted to `double_t` in C99 by unsafe pointer casting. No matter how
exotic pointer casting sounds for Dart, and even more so for JavaScript.
JavaScript doesn't even have any upper bits of `uint64_t`. But `double`s are
the same type everywhere, and their random values will be the same.

Testing is done in the GitHub Actions cloud on **Windows**, **Ubuntu**, and
**macOS** in **VM** and **Node.js** modes.
The library has been thoroughly **tested to match [reference
numbers](https://github.com/rtmigo/randomref)** generated by the same algorithms
implemented in C++. Not only `int`s, but also numbers converted to `double`
including all decimal places that the compiler takes into account.

The sources in C are taken directly from scientific publications or the
reference implementations by the authors of the algorithms. The Xorshift128+
results are also matched to reference values from [JavaScript xorshift
library](https://github.com/AndreasMadsen/xorshift), which tested the 128+
similarly.

Therefore, the sequence generated for example by the `Xoshiro128pp.nextRaw32()`
with the seed `(1, 2, 3, 4)` is the same as the [C99
code](https://prng.di.unimi.it/xoshiro128plusplus.c) will produce with the same
seed.

The `double` values will also be the same as if the upper bits of `uint64_t`
type were converted to `double_t` in C99 by unsafe pointer casting. No matter
how exotic pointer casting sounds for Dart, and even more so for JavaScript.
JavaScript doesn't even have any upper bits of `uint64_t`. But `double`s are the
same type everywhere, and their random values will be the same.

Testing is done in the GitHub Actions cloud on **Windows**, **Ubuntu**, and
*macOS** in **VM** and **Node.js** modes.

0 comments on commit 9c0faba

Please sign in to comment.