Struct Buckets

Source

pub struct Buckets<T, const BUCKETS: usize> { /* private fields */ }

Expand description

The low-level primitive behind Vec: a lazily-initialized array implemented as a sequence of buckets with sizes of increasing powers of two.

The BUCKETS generic parameter controls the maximum capacity, and the inline size, of the type. See buckets_for_index_bits for a convenient way to calculate its desired value.

Implementations§

Source §

impl<T, const BUCKETS: usize> Buckets<T, BUCKETS>

Source

pub const fn new() -> Self

Construct a new, empty, Buckets.

Source

pub fn get(&self, index: Index<BUCKETS>) -> Option<&T>

Retrieve the value at the specified index, or None if it has not been allocated yet.

§Examples

let mut buckets = <Buckets<u8, 5>>::new();
let index = buckets::Index::new(20).unwrap();

assert_eq!(buckets.get(index), None);
buckets.get_or_alloc(index);
assert_eq!(*buckets.get(index).unwrap(), 0);

Source

pub fn get_mut(&mut self, index: Index<BUCKETS>) -> Option<&mut T>

Retrieve a unique reference to the value at the specified index, or None if it has not been allocated yet.

§Examples

let mut buckets = <Buckets<u8, 5>>::new();
let index = buckets::Index::new(20).unwrap();

assert_eq!(buckets.get_mut(index), None);
buckets.get_or_alloc(index);
assert_eq!(*buckets.get_mut(index).unwrap(), 0);

Source

pub unsafe fn get_unchecked(&self, index: Index<BUCKETS>) -> &T

Retrieve the value at the specified index, without performing bounds checking.

§Safety

The element must be allocated.

§Examples

let mut buckets = <Buckets<u8, 5>>::new();
let index = buckets::Index::new(20).unwrap();
buckets.reserve_mut(index);
assert_eq!(*unsafe { buckets.get_unchecked(index) }, 0);

Source

pub unsafe fn get_unchecked_mut(&mut self, index: Index<BUCKETS>) -> &mut T

Retrieve unique reference to the value at the specified index, without performing bounds checking.

§Safety

The element must be allocated.

§Examples

let mut buckets = <Buckets<u8, 5>>::new();
let index = buckets::Index::new(20).unwrap();
buckets.reserve_mut(index);
assert_eq!(*unsafe { buckets.get_unchecked_mut(index) }, 0);

Source

pub fn get_or_alloc(&self, index: Index<BUCKETS>) -> &T
where T: MaybeZeroable,

Retrieve the value at the specified index, or allocate the bucket if it hasn’t been allocated yet.

§Example

let mut buckets = <Buckets<u8, 5>>::new();

let index = buckets::Index::new(48).unwrap();
assert_eq!(*buckets.get_or_alloc(index), 0);

*buckets.get_mut(index).unwrap() += 3;
assert_eq!(*buckets.get_or_alloc(index), 3);

// Prior indices are not necessary allocated.
assert_eq!(buckets.get(buckets::Index::new(0).unwrap()), None);

§Panics

May panic if index is too large or allocation fails.

Source

pub fn get_or_alloc_mut(&mut self, index: Index<BUCKETS>) -> &mut T
where T: MaybeZeroable,

Retrieve a unique reference to the value at the specified index, or allocate the bucket if it hasn’t been allocated yet.

§Example

let mut buckets = <Buckets<u8, 5>>::new();

let index = buckets::Index::new(48).unwrap();
assert_eq!(*buckets.get_or_alloc_mut(index), 0);

*buckets.get_or_alloc_mut(index) += 3;
assert_eq!(*buckets.get(index).unwrap(), 3);

// Prior indices are not necessary allocated.
assert_eq!(buckets.get(buckets::Index::new(0).unwrap()), None);

§Panics

May panic if index is too large or allocation fails.

Source

pub fn reserve(&self, index: Index<BUCKETS>)
where T: MaybeZeroable,

Reserve capacity up to and including the provided index.

After calling this method, .get_or_alloc(n) is guaranteed not to allocate.

§Examples

let buckets = <Buckets<u8, 5>>::new();
let index = buckets::Index::new(20).unwrap();
assert_eq!(buckets.get(index), None);

buckets.reserve(index);
assert_eq!(*buckets.get(index).unwrap(), 0);

§Panics

May panic if index is too large or allocation fails.

Source

pub fn reserve_mut(&mut self, index: Index<BUCKETS>)
where T: MaybeZeroable,

Reserve capacity up to and including the provided index.

Unlike reserve, this method takes a mutable reference to the Buckets, avoiding synchronization.

§Examples

let mut buckets = <Buckets<u8, 5>>::new();
let index = buckets::Index::new(20).unwrap();

buckets.reserve_mut(index);
assert_eq!(*buckets.get(index).unwrap(), 0);

§Panics

May panic if index is too large or allocation fails.

Source

pub fn truncate(&mut self, n: Index<BUCKETS>)

Truncate the Buckets, keeping at least the first n elements.

This method truncates to the smallest capacity that preserves any items before n, but may include subsequent elements due to the bucket layout.

§Examples

let mut buckets = <Buckets<u8, 16>>::new();

// We reserve capacity for 1000 elements, so all elements will be present.
buckets.reserve_mut(buckets::Index::new(1000).unwrap());
assert_eq!(*buckets.get(buckets::Index::new(12).unwrap()).unwrap(), 0);
assert_eq!(*buckets.get(buckets::Index::new(1000).unwrap()).unwrap(), 0);

// If we truncate to a smaller capacity, the later elements will not be present.
buckets.truncate(buckets::Index::new(13).unwrap());
assert_eq!(*buckets.get(buckets::Index::new(12).unwrap()).unwrap(), 0);
assert_eq!(buckets.get(buckets::Index::new(1000).unwrap()), None);

Source

pub fn iter(&self) -> Iter<'_, T, BUCKETS> ⓘ

Iterate over (index, &value) pairs of the Buckets.

§Examples

let mut buckets = <Buckets<u8, 5>>::new();
buckets.reserve_mut(buckets::Index::new(25).unwrap());
assert!(25 < buckets.iter().count());

Source

pub fn iter_mut(&mut self) -> IterMut<'_, T, BUCKETS> ⓘ

Iterate over (index, &mut value) pairs of the Buckets.

§Examples

let mut buckets = <Buckets<u8, 5>>::new();
buckets.reserve_mut(buckets::Index::new(25).unwrap());
assert!(25 < buckets.iter_mut().count());

for (i, (_, val)) in buckets.iter_mut().enumerate() {
    *val = i as u8;
}
assert_eq!(*buckets.get(buckets::Index::new(10).unwrap()).unwrap(), 10);