Struct DigitBinIndexGeneric 

pub struct DigitBinIndexGeneric<B: DigitBin> {
    pub root: Node<B>,
    pub precision: u8,
    /* private fields */
}

A data structure that organizes weighted items into bins based on their decimal digits to enable fast weighted random selection and updates.

This structure is a specialized radix tree optimized for sequential sampling (like in Wallenius’ distribution). It makes a deliberate engineering trade-off: it sacrifices a small, controllable amount of precision by binning items, but in return, it achieves O(P) performance for its core operations, where P is the configured precision. This is significantly faster than the O(log N) performance of general-purpose structures like a Fenwick Tree for its ideal use case.

Type Parameters

• B - The bin container type for leaf nodes. Must implement the DigitBin trait. Common choices are Vec<u32> for maximum speed with small bins, or RoaringBitmap for memory efficiency with large, sparse bins.

Examples

use digit_bin_index::DigitBinIndexGeneric;
// Use Vec<u32> for leaf bins
let mut index = DigitBinIndexGeneric::<Vec<u32>>::new();
// Or use RoaringBitmap for leaf bins
// let mut index = DigitBinIndexGeneric::<roaring::RoaringBitmap>::new();

Fields

root: Node<B>

The root node of the tree.

precision: u8

The precision (number of decimal places) used for binning.

Implementations

impl<B: DigitBin> DigitBinIndexGeneric<B>

pub fn new() -> Self

pub fn with_precision(precision: u8) -> Self

pub fn add(&mut self, individual_id: u64, weight: f64)

pub fn add_many(&mut self, items: &[(u64, f64)])

Adds multiple items to the index in a highly optimized batch operation.

This method is significantly faster than calling add in a loop for large collections of items. It works by first pre-processing the input items, grouping them by their shared weight path (e.g., all items with weight 0.123…). It then traverses the tree once per group, rather than once per item, drastically reducing function call overhead and improving CPU cache performance by performing aggregated updates at each node.

Arguments

• items - A slice of (individual_id, weight) tuples to add to the index.

pub fn remove(&mut self, individual_id: u64, weight: f64) -> bool

pub fn remove_many(&mut self, items: &[(u64, f64)]) -> bool

Removes multiple items from the index in a highly optimized batch operation.

This method is significantly faster than calling remove in a loop. It groups the items to be removed by their weight path and traverses the tree only once per group, performing aggregated updates on the way up.

The (id, weight) pairs must match items that are currently in the index. If a given pair is not found, it is silently ignored.

Arguments

• items - A slice of (id, weight) tuples to remove from the index.

pub fn select(&mut self) -> Option<(u64, f64)>

pub fn select_many(&mut self, num_to_draw: u64) -> Option<Vec<(u64, f64)>>

pub fn select_and_remove(&mut self) -> Option<(u64, f64)>

pub fn select_and_optionally_remove( &mut self, with_removal: bool, ) -> Option<(u64, f64)>

pub fn select_many_and_remove( &mut self, num_to_draw: u64, ) -> Option<Vec<(u64, f64)>>

pub fn select_many_and_optionally_remove( &mut self, num_to_draw: u64, with_removal: bool, ) -> Option<Vec<(u64, f64)>>

pub fn count(&self) -> u64

pub fn total_weight(&self) -> f64

pub fn print_stats_generic(&self)

Prints detailed statistics about the tree: node count, bin stats, and weight stats.

Trait Implementations

impl<B: Clone + DigitBin> Clone for DigitBinIndexGeneric<B>

fn clone(&self) -> DigitBinIndexGeneric<B>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<B: Debug + DigitBin> Debug for DigitBinIndexGeneric<B>

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

Formats the value using the given formatter.

impl<B: DigitBin> Default for DigitBinIndexGeneric<B>

fn default() -> Self

Returns the “default value” for a type.