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 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, bound: u64) -> u64 { ... }
    fn bound_inclusive(&mut self, bound: u64) -> u64 { ... }
    fn range(&mut self, start: i64, end: i64) -> i64 { ... }
    fn range_inclusive(&mut self, start: i64, end: 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]) { ... }
}

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. That being said, the probability of your operating systems RNG failing is absurdly low. And in the case that is 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 need a generator of a different type (and 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 instead 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 states colliding will be vanishingly small.
assert!(rng1 != rng2);
assert!(rng1 != rng3);
assert!(rng2 != rng3);

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).

fn bool(&mut self) -> bool

Returns a bool with 50% odds of being true.

A simple coinflip.

Examples

use ya_rand::*;

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

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

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

Using Generator::bits when bound happens to be a power of 2 is faster and generates less assembly.

Examples

use ya_rand::*;

let mut rng = new_rng();
// Special case
assert!(rng.bound(0) == 0);
for i in 1..=4000 {
    let iters = 64.max(i * 2);
    for _ in 0..iters {
        assert!(rng.bound(i) < i);
    }
}

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

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

Examples

use ya_rand::*;

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

fn range(&mut self, start: i64, end: i64) -> i64

Returns a uniformly distributed i64 in the interval [start, end)

fn range_inclusive(&mut self, start: i64, end: i64) -> i64

Returns a uniformly distributed i64 in the interval [start, end]

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 mean = 0 and stddev = 1.

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.

fn f64_exponential(&mut self) -> f64

Returns an exponentially distributed f64 with lambda = 1.

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

Returns an exponentially distributed f64 with user-defined lambda.

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.

This method will only return None when the length of collection is zero.

Examples

use ya_rand::*;

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

let random_choice = rng.choose(&v).expect("Vector 'v' is not empty.");
assert!(v.contains(random_choice));

let random_choice = rng.choose(&v[HALF..]).expect("Still not empty.");
assert!(v[HALF..].contains(random_choice) == true);

// We randomly selected from the top half so we won't find
// our value in the bottom half.
assert!(v[..HALF].contains(random_choice) == false);

fn ascii_alphabetic(&mut self) -> char

Returns a randomly selected ASCII alphabetic character.

fn ascii_uppercase(&mut self) -> char

Returns a randomly selected ASCII uppercase character.

fn ascii_lowercase(&mut self) -> char

Returns a randomly selected ASCII lowercase character.

fn ascii_alphanumeric(&mut self) -> char

Returns a randomly selected ASCII alphanumeric character.

fn ascii_digit(&mut self) -> char

Returns a randomly selected ASCII digit character.

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). A slice pointer is used to avoid any bounds checks.

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);

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 SecureRng

impl Generator for Xoshiro256pp

impl Generator for Xoshiro512pp