Trait Generator 

pub trait Generator: Sized {
    // Required methods
    fn try_new() -> Result<Self, Error>;
    fn u64(&mut self) -> u64;

    // Provided methods
    fn new() -> Self { ... }
    fn usize(&mut self) -> usize { ... }
    fn u32(&mut self) -> u32 { ... }
    fn u16(&mut self) -> u16 { ... }
    fn u8(&mut self) -> u8 { ... }
    fn bits(&mut self, bit_count: u32) -> u64 { ... }
    fn bool(&mut self) -> bool { ... }
    fn bound(&mut self, max: u64) -> u64 { ... }
    fn bound_inclusive(&mut self, max: u64) -> u64 { ... }
    fn range(&mut self, min: i64, max: i64) -> i64 { ... }
    fn range_inclusive(&mut self, min: i64, max: i64) -> i64 { ... }
    fn f64(&mut self) -> f64 { ... }
    fn f32(&mut self) -> f32 { ... }
    fn f64_nonzero(&mut self) -> f64 { ... }
    fn f32_nonzero(&mut self) -> f32 { ... }
    fn f64_wide(&mut self) -> f64 { ... }
    fn f32_wide(&mut self) -> f32 { ... }
    fn f64_normal(&mut self) -> (f64, f64) { ... }
    fn f64_normal_distribution(&mut self, mean: f64, stddev: f64) -> (f64, f64) { ... }
    fn f64_exponential(&mut self) -> f64 { ... }
    fn f64_exponential_lambda(&mut self, lambda: f64) -> f64 { ... }
    fn choose<C>(&mut self, collection: C) -> Option<C::Item>
       where C: IntoIterator,
             C::IntoIter: ExactSizeIterator { ... }
    fn ascii_alphabetic(&mut self) -> char { ... }
    fn ascii_uppercase(&mut self) -> char { ... }
    fn ascii_lowercase(&mut self) -> char { ... }
    fn ascii_alphanumeric(&mut self) -> char { ... }
    fn ascii_digit(&mut self) -> char { ... }
    fn shuffle<T>(&mut self, slice: &mut [T]) { ... }
    fn shuffle_cloned<T: Clone>(&mut self, slice: &[T]) -> Vec<T> { ... }
}

Base trait that all RNGs must implement.

Required Methods

fn try_new() -> Result<Self, Error>

Creates a generator using randomness provided by the OS.

Unlike Generator::new, which will panic on failure, try_new propagates the error-handling responsibility to the user. But the probability of your operating systems RNG failing is absurdly low, and in the rare case that it does fail, that’s not really an issue most users are going to be able to address.

Stick to using crate::new_rng, unless you really need a generator of a different type (you probably don’t), then use new on your desired type.

fn u64(&mut self) -> u64

Returns a uniformly distributed u64 in the interval [0, 2⁶⁴).

Provided Methods

fn new() -> Self

Creates a generator using randomness provided by the OS.

It is recommended to use the top-level crate::new_rng instead of calling this function on a specific generator type.

Examples

use ya_rand::*;

// Recommended usage
let mut rng1 = new_rng();
// More explicit
let mut rng2 = ShiroRng::new();
// Even more explicit
let mut rng3 = Xoshiro256pp::new();
// Since these are all created using OS entropy, the odds of
// their initial states colliding is vanishingly small.
assert!(rng1 != rng2);
assert!(rng1 != rng3);
assert!(rng2 != rng3);

Safety

This function will panic if your OS rng fails to provide enough entropy. But this is extremely unlikely, and unless you’re working at the kernel level it’s not something you should ever be concerned with.

Since Windows 10 this function is infallible, thanks to modern Windows versions adopting a user-space cryptographic architecture that can’t fail during runtime.

fn usize(&mut self) -> usize

Returns a uniformly distributed usize in the interval [0, usize::MAX].

fn u32(&mut self) -> u32

Returns a uniformly distributed u32 in the interval [0, 2³²).

fn u16(&mut self) -> u16

Returns a uniformly distributed u16 in the interval [0, 2¹⁶).

fn u8(&mut self) -> u8

Returns a uniformly distributed u8 in the interval [0, 2⁸).

fn bits(&mut self, bit_count: u32) -> u64

Returns a uniformly distributed u64 in the interval [0, 2^bit_count).

The value of bit_count is clamped to 64.

fn bool(&mut self) -> bool

A simple coinflip, returning a bool that has a 50% chance of being true.

Examples

use ya_rand::*;

const ITERATIONS: u64 = 1 << 24;
let mut rng = new_rng();
let mut yes: u64 = 0;
let mut no: u64 = 0;
for _ in 0..ITERATIONS {
    if rng.bool() {
        yes += 1;
    } else {
        no += 1;
    }
}
// We expect the difference to be within ~5%.
let THRESHOLD: u64 = ITERATIONS / 20;
assert!(yes.abs_diff(no) <= THRESHOLD);

fn bound(&mut self, max: u64) -> u64

Returns a uniformly distributed u64 in the interval [0, max).

Using Generator::bits when max happens to be a power of 2 will be significantly faster.

Examples

use ya_rand::*;

let mut rng = new_rng();
// Special case: bound of 0 always returns 0.
assert!(rng.bound(0) == 0);
for i in 1..=2000 {
    for _ in 0..(i * 2) {
        assert!(rng.bound(i) < i);
    }
}

fn bound_inclusive(&mut self, max: u64) -> u64

Returns a uniformly distributed u64 in the interval [0, max].

It is expected that max != u64::MAX.

Examples

use ya_rand::*;

let mut rng = new_rng();
for i in 0..=2000 {
    for _ in 0..(i * 2) {
        assert!(rng.bound_inclusive(i) <= i);
    }
}

fn range(&mut self, min: i64, max: i64) -> i64

Returns a uniformly distributed i64 in the interval [min, max)

It is expected that min < max.

fn range_inclusive(&mut self, min: i64, max: i64) -> i64

Returns a uniformly distributed i64 in the interval [min, max]

It is expected that min <= max and max != i64::MAX.

fn f64(&mut self) -> f64

Returns a uniformly distributed f64 in the interval [0.0, 1.0).

fn f32(&mut self) -> f32

Returns a uniformly distributed f32 in the interval [0.0, 1.0).

fn f64_nonzero(&mut self) -> f64

Returns a uniformly distributed f64 in the interval (0.0, 1.0].

fn f32_nonzero(&mut self) -> f32

Returns a uniformly distributed f32 in the interval (0.0, 1.0].

fn f64_wide(&mut self) -> f64

Returns a uniformly distributed f64 in the interval (-1.0, 1.0).

fn f32_wide(&mut self) -> f32

Returns a uniformly distributed f32 in the interval (-1.0, 1.0).

fn f64_normal(&mut self) -> (f64, f64)

Returns two indepedent and normally distributed f64 values with a mean of 0.0 and a stddev of 1.0.

fn f64_normal_distribution(&mut self, mean: f64, stddev: f64) -> (f64, f64)

Returns two indepedent and normally distributed f64 values with user-defined mean and stddev.

It is expected that stddev.abs() != 0.0.

fn f64_exponential(&mut self) -> f64

Returns an exponentially distributed f64 with a lambda of 1.0.

fn f64_exponential_lambda(&mut self, lambda: f64) -> f64

Returns an exponentially distributed f64 with user-defined lambda.

It is expected that lambda.abs() != 0.0.

fn choose<C>(&mut self, collection: C) -> Option<C::Item>

where C: IntoIterator, C::IntoIter: ExactSizeIterator,

Returns a randomly chosen item from the iterator of collection.

Returns None when the length of the iterator is zero.

Examples

use ya_rand::*;

const SIZE: usize = 1738;
let mut rng = new_rng();
let mut v = [0; SIZE];
for i in 0..SIZE {
    v[i] = i;
}
let (top, bottom) = v.split_at(v.len() / 2);

// Sanity check.
let random_item = rng.choose(&v).expect("vector `v` is not empty");
assert!(v.contains(random_item) == true);

// Choose `random_item` from the top half of the array.
let random_item = rng.choose(top).expect("still not empty");
assert!(top.contains(random_item) == true);

// We're looking in the bottom half so we won't find the
// `random_item` from the top half.
assert!(bottom.contains(random_item) == false);

fn ascii_alphabetic(&mut self) -> char

Returns a randomly selected ASCII character from the pool of:

'A'..='Z', and'a'..='z'

fn ascii_uppercase(&mut self) -> char

Returns a randomly selected ASCII character from the pool of:

'A'..='Z'

fn ascii_lowercase(&mut self) -> char

Returns a randomly selected ASCII character from the pool of:

'a'..='z'

fn ascii_alphanumeric(&mut self) -> char

Returns a randomly selected ASCII character from the pool of:

'A'..='Z', 'a'..='z', and '0'..='9'

fn ascii_digit(&mut self) -> char

Returns a randomly selected ASCII character from the pool of:

'0'..='9'

fn shuffle<T>(&mut self, slice: &mut [T])

Performs a Fisher-Yates shuffle on the contents of slice.

This implementation is the modern variant introduced by Richard Durstenfeld. It is in-place and O(n).

Examples

use ya_rand::*;

let mut rng = new_rng();
let mut data = [0; 1738];
for i in 0..data.len() {
    data[i] = i;
}
assert!(data.is_sorted() == true);

rng.shuffle(&mut data);
assert!(data.is_sorted() == false);

fn shuffle_cloned<T: Clone>(&mut self, slice: &[T]) -> Vec<T>

Clones slice into a new Vec, calls Generator::shuffle on it, and returns the result.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl Generator for RomuQuad

impl Generator for RomuTrio

impl Generator for SecureRng

impl Generator for Xoshiro256pp

impl Generator for Xoshiro512pp