Fast pseudo-random number generation library for MQL5, with a generic backend template<br/> supporting Xoshiro256**, 64-bit Mersenne Twister, and MQL5's native generator.
</p>
---
## Main Features
- **Backend-agnostic API**: `CRandom<TBackend>` exposes the same rich API (integers, longs, doubles, normal distribution, sampling) regardless of the underlying PRNG
- **Three interchangeable backends**: Xoshiro256** (SHA-256 seeded), 64-bit Mersenne Twister, and a thin wrapper over MQL5's native `MathRand()`
- **Unbiased bounded generation**: uses Lemire's fastrange method for `RandomInteger(min, max)` / `RandomLong(min, max)` without modulo bias
- **Sampling utilities**: `Shuffle`, `Sample` (without replacement), `SampleWithReplacement`, all Fisher-Yates based
Requires the `tsndep` package, available on [PyPI](https://pypi.org/project/tsndep). It automatically downloads and installs all declared dependencies.
---
## Quick Start
**1. Include the library:**
```mql5
#include "..\\Src\\Main.mqh"
#include "..\\Src\\Imp\\All.mqh"
```
**2. Use it:**
```mql5
TSN::CRandom<TSN::Xoshiro256> rng;
int n = rng.RandomInteger(1, 100);
```
---
## License
**[Read Full License](./LICENSE)**
By downloading or using this repository, you accept the license terms.
---
## Third-Party Code & References
This repository builds on external work. The full obligations of each source license apply independently of this project's own [NL-NC] license.
- **`Src/Imp/Xho/Xho.mqh`** (Xoshiro256** core: `Seed`, `nextUInt64`, `nextUInt32`, `rotl`) and the bulk of the public API in **`Src/Main.mqh`** (`RandomInteger`, `RandomDouble`, `RandomDoubleHighRes`, `RandomNormal`, `Shuffle`, `Sample`, `SampleWithReplacement`, `boundedUInt32`, `boundedUInt64`, `mulhi`) are adapted from [Xoshiro256](https://forge.mql5.io/amrali/Xoshiro256) by **Amr Ali**. The original class was reduced to its PRNG core and the public API layer was generalized into the `CRandom<TBackend>` template so it could be reused across multiple backends. The native `CryptEncode(CRYPT_HASH_SHA256, ...)` seeding call was replaced with `TSN::CCryptoHash::SHA256` from the TSN ecosystem's CryptoByLeo library.
- The underlying **xoshiro256\*\*** algorithm itself was created by David Blackman and Sebastiano Vigna, released into the public domain (CC0) — <https://prng.di.unimi.it/>.
- **`Src/Imp/MT64/MT64.mqh`** (64-bit Mersenne Twister) is based on the reference implementation described in the MQL5 article: <https://www.mql5.com/en/articles/14413>.
