Struct WeightedCollection 

pub struct WeightedCollection<T> {
    items: Vec<(T, f64)>,
    total_weight: f64,
}

A collection of items with associated weights for probabilistic selection.

Weights must be positive (> 0.0); items with non-positive weights are treated as having zero probability for pick_one / pick_index and are placed at the end of the shuffled output in into_shuffled.

Examples

use hopr_utils::statistics::WeightedCollection;

let wc = WeightedCollection::from(vec![("rare", 0.1), ("common", 10.0)]);
let picked = wc.pick_one().expect("non-empty collection");
assert!(picked == "rare" || picked == "common");

Fields

items: Vec<(T, f64)>

total_weight: f64

Pre-computed sum of positive weights (cached to avoid recomputing on every pick).

Implementations

impl<T> WeightedCollection<T>

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

Create a collection from pre-weighted items.

pub fn is_empty(&self) -> bool

Returns true if the collection contains no items.

pub fn len(&self) -> usize

Returns the number of items in the collection.

pub fn iter(&self) -> impl Iterator<Item = &(T, f64)>

Iterates over (item, weight) pairs.

pub fn total_weight(&self) -> f64

Returns the sum of positive weights in this collection.

pub fn probability_of(&self, weight: f64) -> f64

Returns the sampling probability that an entry carrying weight would receive in this collection — i.e. weight.max(0.0) / total_positive_weight.

Returns 0.0 if weight <= 0.0 or if the collection holds no positive-weight entries (empty or fully non-positive collection).

impl<T> WeightedCollection<T>

pub fn pick_index(&self) -> Option<usize>

Returns the index of a randomly selected item, weighted by probability proportional to its weight.

Returns None if the collection is empty or all weights are non-positive.

impl<T> WeightedCollection<T>

pub fn pick_ref(&self) -> Option<&T>

Pick a reference to one item at random, with probability proportional to its weight.

Returns None if the collection is empty or all weights are non-positive.

impl<T: Clone> WeightedCollection<T>

pub fn pick_one(&self) -> Option<T>

Pick one item at random, with probability proportional to its weight.

Returns None if the collection is empty or all weights are non-positive.

impl<T> WeightedCollection<T>

pub fn into_shuffled(self) -> Vec<T>

Consume the collection and return items in a weighted random permutation.

Uses the Efraimidis–Spirakis algorithm: each item is assigned a key random()^(1/weight) and the items are sorted by descending key. Higher-weight items appear earlier with higher probability, but all items retain a nonzero chance of appearing at any position.

Trait Implementations

impl<T> From<Vec<(T, f64)>> for WeightedCollection<T>

fn from(items: Vec<(T, f64)>) -> Self

Converts to this type from the input type.