Struct cogs_gamedev::chance::WeightedPicker

pub struct WeightedPicker<T> { /* fields omitted */ }

It’s often helpful to have weighted probabilities. This struct serves as a sort of weighted bag; you can give it entries with various weights, and then randomly sample them.

This is the way Minecraft loot tables work, if this sounds familiar.

The algorithm used is Vose’s Alias Method (scroll to the bottom), which to be honest I absolutely do not understand. But it has O(n) creation and O(1) selection, so sounds good to me.

You can’t edit the probabilities after you’ve created it due to the algorithm.

Implementations

impl<T> WeightedPicker<T>

pub fn new(entries: Vec<(T, f64)>) -> Self

Initialize a WeightedPicker from the given items and weights.

Panics if you pass it an empty Vec.

let picker = WeightedPicker::new(vec![
    ("common", 10.0),
    ("uncommon", 5.0),
    ("rare", 2.0),
    ("legendary", 1.0),
    ("mythic", 0.1),
]);

let mut rng = rand::thread_rng();
for _ in 0..10 {
    println!("- {}", picker.get(&mut rng));
}

/*
    A sample output:
    - legendary
    - rare
    - uncommon
    - common
    - common
    - rare
    - uncommon
    - common
    - common
    - uncommon
*/

pub fn get<R: Rng + ?Sized>(&self, rng: &mut R) -> &T

Get an item from the list.

pub fn get_idx<R: Rng + ?Sized>(&self, rng: &mut R) -> usize

Get an index into the internal list. This is like WeightedPicker::get, but returns the index of the selected value instead of the value.

You can use this function to save some space by passing a vec where T is (), if you want usize outputs, I guess.

pub fn get_by_idx(&self, idx: usize) -> Option<&T>

Manually index into the picker’s array.

pub fn get_mut_by_idx(&mut self, idx: usize) -> Option<&mut T>

Manually index into the picker’s array. You can use this to mutate entries once they’ve been created.

Note there is no way to mutate probabilities after creation, nor any way to add or remove possible values.

pub fn pick<R: Rng + ?Sized>(items: Vec<(T, f64)>, rng: &mut R) -> T

The same as creating a WeightedPicker and then calling get, but you don’t need to actually make the WeightedPicker.

Trait Implementations

impl<T: Clone> Clone for WeightedPicker<T>

fn clone(&self) -> WeightedPicker<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for WeightedPicker<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.