[](https://www.apache.org/licenses/LICENSE-2.0)
[](https://crates.io/crates/randomize)
[](https://ci.appveyor.com/project/Lokathor/randomize-rs)
[](https://travis-ci.org/Lokathor/randomize-rs)
# randomize-rs
A dead simple to use randomization library for rust. Mostly PCGs and such.
This library is core only.
This requires Nightly 1.33 2018-12-31 or later. The one where `NonZeroUFoo::get`
became `const`.
## Basic Usage
There are three families of PCG provided, with state used from `u8` up through
`u128`. PCGs in this crate are named by the _amount of state_ they hold, and
there are various methods on each PCG for same-size output (eg: `u64` from `u64`
state) or half-size output (eg: `u32` from `u64` state). In the case of a `u8`
state there's obviously no half-size output.
A good default generator to use is one with a `u64` state, along with the
`next_u32` method. This will pass the PractRand statistical tests up to at least
4 terabytes of output (probably more, but the tests take a very long time to run
and it's still going at the time of writing). Such a generator can also create
the occasional `u64` value, but if you want lots of `u64` values you should
probably use a generator with a `u128` for state.
```rust
use randomize::pcg::{PCGPickU64, PCGMemU64, PCGPhantomU64};
use typenum::consts::U5;
#[cfg(any(target_arch = "x86",target_arch = "x86_64"))]
let u: u64 = randomize::u64_from_rdtsc();
#[cfg(not(any(target_arch = "x86",target_arch = "x86_64")))]
let u: u64 = 1776;
let pick_gen = &mut PCGPickU64::seed(u, u);
let mem_gen = &mut PCGMemU64::seed(u);
let phantom_gen: &mut PCGPhantomU64<U5> = &mut PCGPhantomU64::seed(u);
println!("{}", pick_gen.next_u32());
```
There are also many PCGs provided with less than a `u64` for state, and also
some non-PCG generators. These are basically "just for fun", and won't pass
statistical tests.
## Features You Might Want That Are Currently Missing
* Bounded randomization (planned for v2.2)
* PCG Extension arrays (planned for v2.2)
## Stability
All types / functions / methods that are used or called by a benchmark or test
are considered to be a "stable" part of the crate.
The exact numeric output of any function _isn't_ considered to be stable, since
the main reason that the output streams would change in the first place is to
fix a math bug.