Trait bones_framework::prelude::TurboRand

pub trait TurboRand: TurboCore + GenCore {
    // Provided methods
    fn u128(&self, bounds: impl RangeBounds<u128>) -> u128 { ... }
    fn i128(&self, bounds: impl RangeBounds<i128>) -> i128 { ... }
    fn u64(&self, bounds: impl RangeBounds<u64>) -> u64 { ... }
    fn i64(&self, bounds: impl RangeBounds<i64>) -> i64 { ... }
    fn u32(&self, bounds: impl RangeBounds<u32>) -> u32 { ... }
    fn i32(&self, bounds: impl RangeBounds<i32>) -> i32 { ... }
    fn u16(&self, bounds: impl RangeBounds<u16>) -> u16 { ... }
    fn i16(&self, bounds: impl RangeBounds<i16>) -> i16 { ... }
    fn u8(&self, bounds: impl RangeBounds<u8>) -> u8 { ... }
    fn i8(&self, bounds: impl RangeBounds<i8>) -> i8 { ... }
    fn usize(&self, bounds: impl RangeBounds<usize>) -> usize { ... }
    fn isize(&self, bounds: impl RangeBounds<isize>) -> isize { ... }
    fn f32(&self) -> f32 { ... }
    fn f32_normalized(&self) -> f32 { ... }
    fn f64(&self) -> f64 { ... }
    fn f64_normalized(&self) -> f64 { ... }
    fn index(&self, bound: impl RangeBounds<usize>) -> usize { ... }
    fn bool(&self) -> bool { ... }
    fn chance(&self, rate: f64) -> bool { ... }
    fn sample<'a, T>(&self, list: &'a [T]) -> Option<&'a T> { ... }
    fn sample_iter<T>(&self, list: T) -> Option<<T as Iterator>::Item>
       where T: Iterator { ... }
    fn sample_mut<'a, T>(&self, list: &'a mut [T]) -> Option<&'a mut T> { ... }
    fn sample_multiple<'a, T>(&self, list: &'a [T], amount: usize) -> Vec<&'a T> { ... }
    fn sample_multiple_mut<'a, T>(
        &self,
        list: &'a mut [T],
        amount: usize,
    ) -> Vec<&'a mut T> { ... }
    fn sample_multiple_iter<T>(
        &self,
        list: T,
        amount: usize,
    ) -> Vec<<T as Iterator>::Item>
       where T: Iterator { ... }
    fn weighted_sample<'a, T, F>(
        &self,
        list: &'a [T],
        weight_sampler: F,
    ) -> Option<&'a T>
       where F: Fn((&T, usize)) -> f64 { ... }
    fn weighted_sample_mut<'a, T, F>(
        &self,
        list: &'a mut [T],
        weight_sampler: F,
    ) -> Option<&'a mut T>
       where F: Fn((&T, usize)) -> f64 { ... }
    fn shuffle<T>(&self, slice: &mut [T]) { ... }
    fn partial_shuffle<'a, T>(
        &self,
        slice: &'a mut [T],
        amount: usize,
    ) -> (&'a mut [T], &'a mut [T]) { ... }
    fn alphabetic(&self) -> char { ... }
    fn alphanumeric(&self) -> char { ... }
    fn lowercase(&self) -> char { ... }
    fn uppercase(&self) -> char { ... }
    fn digit(&self, radix: u8) -> char { ... }
    fn char(&self, bounds: impl RangeBounds<char>) -> char { ... }
}

Extension trait for automatically implementing all TurboRand methods, as long as the struct implements [TurboCore] & GenCore. All methods are provided as default implementations that build on top of [TurboCore] and GenCore, and thus are not recommended to be overridden, lest you potentially change the expected outcome of the methods.

Provided Methods

fn u128(&self, bounds: impl RangeBounds<u128>) -> u128

Returns a random u128 within a given range bound.

Panics

Panics if the range is empty or invalid.

fn i128(&self, bounds: impl RangeBounds<i128>) -> i128

Returns a random i128 within a given range bound.

Panics

Panics if the range is empty or invalid.

fn u64(&self, bounds: impl RangeBounds<u64>) -> u64

Returns a random u64 value.

Panics

Panics if the range is empty or invalid.

fn i64(&self, bounds: impl RangeBounds<i64>) -> i64

Returns a random i64 value.

Panics

Panics if the range is empty or invalid.

fn u32(&self, bounds: impl RangeBounds<u32>) -> u32

Returns a random u32 value.

Panics

Panics if the range is empty or invalid.

fn i32(&self, bounds: impl RangeBounds<i32>) -> i32

Returns a random i32 value.

Panics

Panics if the range is empty or invalid.

fn u16(&self, bounds: impl RangeBounds<u16>) -> u16

Returns a random u16 value.

Panics

Panics if the range is empty or invalid.

fn i16(&self, bounds: impl RangeBounds<i16>) -> i16

Returns a random i16 value.

Panics

Panics if the range is empty or invalid.

fn u8(&self, bounds: impl RangeBounds<u8>) -> u8

Returns a random u8 value.

Panics

Panics if the range is empty or invalid.

fn i8(&self, bounds: impl RangeBounds<i8>) -> i8

Returns a random i8 value.

Panics

Panics if the range is empty or invalid.

fn usize(&self, bounds: impl RangeBounds<usize>) -> usize

Returns a random usize within a given range bound.

Panics

Panics if the range is empty or invalid.

fn isize(&self, bounds: impl RangeBounds<isize>) -> isize

Returns a random isize within a given range bound.

Panics

Panics if the range is empty or invalid.

fn f32(&self) -> f32

Returns a random f32 value between 0.0 and 1.0.

fn f32_normalized(&self) -> f32

Returns a random f32 value between -1.0 and 1.0.

fn f64(&self) -> f64

Returns a random f32 value between 0.0 and 1.0.

fn f64_normalized(&self) -> f64

Returns a random f32 value between -1.0 and 1.0.

fn index(&self, bound: impl RangeBounds<usize>) -> usize

Returns a usize value for stable indexing across different word size platforms.

fn bool(&self) -> bool

Returns a random boolean value.

Example

use turborand::prelude::*;

let rng = Rng::with_seed(Default::default());

assert_eq!(rng.bool(), true);

fn chance(&self, rate: f64) -> bool

Returns a boolean value based on a rate. rate represents the chance to return a true value, with 0.0 being no chance and 1.0 will always return true.

Panics

Will panic if rate is not a value between 0.0 and 1.0.

Example

use turborand::prelude::*;

let rng = Rng::with_seed(Default::default());

assert_eq!(rng.chance(1.0), true);

fn sample<'a, T>(&self, list: &'a [T]) -> Option<&'a T>

Samples a random item from a slice of values.

Example

use turborand::prelude::*;

let rng = Rng::with_seed(Default::default());

let values = [1, 2, 3, 4, 5, 6];

assert_eq!(rng.sample(&values), Some(&5));

fn sample_iter<T>(&self, list: T) -> Option<<T as Iterator>::Item>

where T: Iterator,

Samples a random item from an iterator of values. O(1) if the iterator provides an accurate Iterator::size_hint to allow for optimisations to kick in, else O(n) where n is the size of the iterator.

Example

use turborand::prelude::*;

let rng = Rng::with_seed(Default::default());

let mut values = [1, 2, 3, 4, 5, 6];

assert_eq!(rng.sample_iter(values.iter_mut()), Some(&mut 5));

fn sample_mut<'a, T>(&self, list: &'a mut [T]) -> Option<&'a mut T>

Samples a random &mut item from a slice of values.

NOTE: Mutable references must be dropped before more can be sampled from the source slice. If a sampling tries to yield a mutable reference that already exists, the compiler will complain.

Example

use turborand::prelude::*;

let rng = Rng::with_seed(Default::default());

let mut values = [1, 2, 3, 4, 5, 6];

let result1 = rng.sample_mut(&mut values);

assert_eq!(result1, Some(&mut 5));

let result2 = rng.sample_mut(&mut values);

assert_eq!(result2, Some(&mut 3));

fn sample_multiple<'a, T>(&self, list: &'a [T], amount: usize) -> Vec<&'a T>

Samples multiple unique items from a slice of values.

Example

use turborand::prelude::*;

let rng = Rng::with_seed(Default::default());

let values = [1, 2, 3, 4, 5, 6];

assert_eq!(rng.sample_multiple(&values, 2), vec![&6, &4]);

fn sample_multiple_mut<'a, T>( &self, list: &'a mut [T], amount: usize, ) -> Vec<&'a mut T>

Samples multiple unique items from a mutable slice of values.

NOTE: Mutable references must be dropped before more can be sampled from the source slice. If a sampling tries to yield a mutable reference that already exists, the compiler will complain.

Example

use turborand::prelude::*;

let rng = Rng::with_seed(Default::default());

let mut values = [1, 2, 3, 4, 5, 6];

assert_eq!(rng.sample_multiple_mut(&mut values, 2), vec![&mut 6, &mut 4]);

fn sample_multiple_iter<T>( &self, list: T, amount: usize, ) -> Vec<<T as Iterator>::Item>

where T: Iterator,

Samples multiple unique items from an iterator of values.

Example

use turborand::prelude::*;

let rng = Rng::with_seed(Default::default());

let values = [1, 2, 3, 4, 5, 6];

assert_eq!(rng.sample_multiple_iter(values.iter(), 2), vec![&6, &4]);

fn weighted_sample<'a, T, F>( &self, list: &'a [T], weight_sampler: F, ) -> Option<&'a T>

where F: Fn((&T, usize)) -> f64,

Stochastic Acceptance implementation of Roulette Wheel weighted selection. Uses a closure to return a rate value for each randomly sampled item to decide whether to return it or not. The returned f64 value must be between 0.0 and 1.0.

Returns None if given an empty list to sample from. For a list containing 1 item, it’ll always return that item regardless. Otherwise, operations are O(1) in complexity, and require no allocations.

Panics

If the returned value of the weight_sampler closure is not between 0.0 and 1.0.

Example

use turborand::prelude::*;

let rng = Rng::with_seed(Default::default());

let values = [1, 2, 3, 4, 5, 6];

let total = f64::from(values.iter().sum::<i32>());

assert_eq!(rng.weighted_sample(&values, |(&item, _)| item as f64 / total), Some(&4));

fn weighted_sample_mut<'a, T, F>( &self, list: &'a mut [T], weight_sampler: F, ) -> Option<&'a mut T>

where F: Fn((&T, usize)) -> f64,

Stochastic Acceptance implementation of Roulette Wheel weighted selection. Uses a closure to return a rate value for each randomly sampled item to decide whether to return it or not. The returned f64 value must be between 0.0 and 1.0.

Returns None if given an empty list to sample from. For a list containing 1 item, it’ll always return that item regardless. Otherwise, operations are O(1) in complexity, and require no allocations.

NOTE: Mutable references must be dropped before more can be sampled from the source slice. If a sampling tries to yield a mutable reference that already exists, the compiler will complain.

Panics

If the returned value of the weight_sampler closure is not between 0.0 and 1.0.

Example

use turborand::prelude::*;

let rng = Rng::with_seed(Default::default());

let mut values = [1, 2, 3, 4, 5, 6];

let total = f64::from(values.iter().sum::<i32>());

let result1 = rng.weighted_sample_mut(&mut values, |(&item, _)| item as f64 / total);

assert_eq!(result1, Some(&mut 4));

let result2 = rng.weighted_sample_mut(&mut values, |(&item, _)| item as f64 / total);

assert_eq!(result2, Some(&mut 5));

// We have to drop `result2` because the next sample will try to return the same
// value again. And rust won't allow two mutable references to exist at the same
// time
drop(result2);

let result3 = rng.weighted_sample_mut(&mut values, |(&item, _)| item as f64 / total);

// Weighted sample in this example will favour larger numbers, so 5 gets picked
// again.
assert_eq!(result3, Some(&mut 5));

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

Shuffles a slice randomly in O(n) time.

Example

use turborand::prelude::*;

let rng = Rng::with_seed(Default::default());

let values = [1, 2, 3, 4, 5];
let mut shuffled = values.clone();

rng.shuffle(&mut shuffled);

assert_ne!(&shuffled, &values);

fn partial_shuffle<'a, T>( &self, slice: &'a mut [T], amount: usize, ) -> (&'a mut [T], &'a mut [T])

Partially shuffles a slice by a given amount and returns the shuffled part and non-shuffled part.

Example

use turborand::prelude::*;

let rng = Rng::with_seed(Default::default());

let mut values = [1, 2, 3, 4, 5];

let (shuffled, rest) = rng.partial_shuffle(&mut values, 2);

assert_eq!(shuffled, &mut [2, 5]);
assert_eq!(rest, &mut [1, 4, 3]);

fn alphabetic(&self) -> char

Generates a random char in ranges a-z and A-Z.

fn alphanumeric(&self) -> char

Generates a random char in ranges a-z, A-Z and 0-9.

fn lowercase(&self) -> char

Generates a random char in the range a-z.

fn uppercase(&self) -> char

Generates a random char in the range A-Z.

fn digit(&self, radix: u8) -> char

Generate a random digit in the given radix.

Digits are represented by chars in ranges 0-9 and a-z.

Example

use turborand::prelude::*;

let rand = Rng::with_seed(Default::default());

let digit = rand.digit(16);

assert_eq!(&digit, &'2');

Panics

Panics if the radix is zero or greater than 36.

fn char(&self, bounds: impl RangeBounds<char>) -> char

Generates a random char in the given range.

Example

use turborand::prelude::*;

let rand = Rng::with_seed(Default::default());

let character = rand.char('a'..'Ç');

assert_eq!(character, '»');

Panics

Panics if the range is empty.

Object Safety

This trait is not object safe.

Implementors

impl<T> TurboRand for T

where T: TurboCore + GenCore + ?Sized,