randomize 2.1.0

A dead simple to use randomization library for rust.
docs.rs failed to build randomize-2.1.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Visit the last successful build: randomize-4.0.0-alpha.3

License:Apache2 CratesIO AppVeyor TravisCI

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.

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.