Struct stash::Stash

pub struct Stash<V, Ix = usize> { /* fields omitted */ }

An O(1) amortized table that reuses keys.

Guarantees and non-guarantees:

1. Stash is deterministic and keys do not depend on the inserted values. This means you can update two stashes in tandem and get the same keys back. This could be useful for, e.g., primary/secondary replication.
2. Keys will always be less than the maximum number of items that have ever been present in the Stash at any single point in time. In other words, if you never store more than n items in a Stash, the stash will only assign keys less than n. You can take advantage of this guarantee to truncate the key from a usize to some smaller type.
3. Except the guarantees noted above, you can assume nothing about key assignment or iteration order. They can change at any time.

An example use case is a file descriptor table.

Methods

impl<V> Stash<V, usize>

fn new() -> Self

Constructs a new, empty Stash<V, usize>.

This is a convenience method. Use Stash::default for a constructor that is generic in the type of index used.

The stash will not allocate until elements are put onto it.

Examples

use stash::Stash;

let mut stash: Stash<i32> = Stash::new();

fn with_capacity(capacity: usize) -> Self

Constructs a new, empty Stash<V, usize> with the specified capacity.

This is a convenience method. Use Stash::default for a constructor that is generic in the type of index used. In that case you can call reserve on the newly created stash to specify the capacity you need.

The stash will be able to hold exactly capacity elements without reallocating. If capacity is 0, the stash will not allocate.

It is important to note that this function does not specify the length of the returned stash , but only the capacity. (For an explanation of the difference between length and capacity, see the main Vec<T> docs in the std::vec module, 'Capacity and reallocation'.)

Examples

use stash::Stash;

let mut stash = Stash::with_capacity(10);

// The stash contains no items, even though it has capacity for more
assert_eq!(stash.len(), 0);

// These are all done without reallocating...
for i in 0i32..10 {
    let _ = stash.put(i);
}

// ...but this may make the stash reallocate
stash.put(11);

impl<V, Ix> Stash<V, Ix> where Ix: Index

fn capacity(&self) -> usize

Returns the number of elements the stash can hold without reallocating.

Examples

use stash::Stash;

let stash: Stash<i32> = Stash::with_capacity(10);
assert_eq!(stash.capacity(), 10);

fn len(&self) -> usize

The number of items in the stash.

Examples

use stash::Stash;

let mut stash = Stash::new();
assert_eq!(stash.len(), 0);
stash.put("a");
assert_eq!(stash.len(), 1);

fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more elements to be put into the given Stash<T>. The collection may reserve more space to avoid frequent reallocations.

Panics

Panics if the new capacity overflows usize.

Examples

use stash::Stash;

let mut stash: Stash<i32> = Stash::new();
let t1 = stash.put(1);
stash.reserve(10);
assert!(stash.capacity() >= 11);

fn reserve_exact(&mut self, additional: usize)

Reserves the minimum capacity for exactly additional more elements to be put into the given Stash<T>. Does nothing if the capacity is already sufficient.

Note that the allocator may give the collection more space than it requests. Therefore capacity can not be relied upon to be precisely minimal. Prefer reserve if future puts are expected.

Panics

Panics if the new capacity overflows usize.

Examples

use stash::Stash;

let mut stash: Stash<i32> = Stash::new();
let t1 = stash.put(1);
stash.reserve_exact(10);
assert!(stash.capacity() >= 11);

fn put(&mut self, value: V) -> Ix

Put a value into the stash.

Returns the index at which this value was stored.

Panics

Panics if the size of the Stash<V, Ix> would overflow the Ix index type.

fn extend<I>(&mut self, iter: I) -> Extend<I, Ix> where I: Iterator<Item=V>

Put all items in the iterator into the stash.

Returns an iterator over the indices where the items were inserted. The items are actually inserted as the Iterator is read. If the returned Iterator is dropped, the rest of the items will be inserted all at once.

fn iter(&self) -> Iter<V, Ix>

Iterate over the items in this Stash<V>.

Returns an iterator that yields (index, &value) pairs.

fn iter_mut(&mut self) -> IterMut<V, Ix>

Mutably iterate over the items in this Stash<V>.

Returns an iterator that yields (index, &mut value) pairs.

fn values(&self) -> Values<V>

Iterate over the values in this Stash<V> by reference.

fn values_mut(&mut self) -> ValuesMut<V>

Mutably iterate over the values in this Stash<V> by reference.

fn into_values(self) -> IntoValues<V>

Iterate over the values in this Stash<V> by value.

fn is_empty(&self) -> bool

Check if this Stash<V> is empty.

Returns true if this Stash<V> is empty.

fn take(&mut self, index: Ix) -> Option<V>

Take an item from a slot (if non empty).

unsafe fn take_unchecked(&mut self, index: Ix) -> V

Take an item from a slot (if non empty) without bounds or empty checking. So use it very carefully!

This can be safely used as long as the user does not mutate indices from put and is sure not to have taken the value associated with the given index.

fn get(&self, index: Ix) -> Option<&V>

Get a reference to the value at index.

unsafe fn get_unchecked(&self, index: Ix) -> &V

Get a reference to the value at index without bounds or empty checking. So use it very carefully!

This can be safely used as long as the user does not mutate indices from put and is sure not to have taken the value associated with the given index.

fn get_mut(&mut self, index: Ix) -> Option<&mut V>

Get a mutable reference to the value at index.

unsafe fn get_unchecked_mut(&mut self, index: Ix) -> &mut V

Get a mutable reference to the value at index without bounds or empty checking. So use it very carefully!

This can be safely used as long as the user does not mutate indices from put and is sure not to have taken the value associated with the given index.

fn clear(&mut self)

Clear the stash. Cleared stash will give the same keys as a new stash for subsequent puts.

Trait Implementations

impl<V: Clone, Ix: Clone> Clone for Stash<V, Ix>

fn clone(&self) -> Stash<V, Ix>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<V, Ix: Index> IntoIterator for Stash<V, Ix>

type Item = (Ix, V)

The type of the elements being iterated over.

type IntoIter = IntoIter<V, Ix>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, V, Ix: Index> IntoIterator for &'a Stash<V, Ix>

type Item = (Ix, &'a V)

The type of the elements being iterated over.

type IntoIter = Iter<'a, V, Ix>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, V, Ix: Index> IntoIterator for &'a mut Stash<V, Ix>

type Item = (Ix, &'a mut V)

The type of the elements being iterated over.

type IntoIter = IterMut<'a, V, Ix>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<V, Ix> Debug for Stash<V, Ix> where V: Debug, Ix: Debug + Index

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

Formats the value using the given formatter.

impl<'a, V, Ix: Index> Index<Ix> for Stash<V, Ix>

type Output = V

The returned type after indexing

fn index(&self, index: Ix) -> &V

The method for the indexing (container[index]) operation

impl<'a, V, Ix: Index> IndexMut<Ix> for Stash<V, Ix>

fn index_mut(&mut self, index: Ix) -> &mut V

The method for the mutable indexing (container[index]) operation

impl<V, Ix: Index> Default for Stash<V, Ix>

fn default() -> Self

Returns the "default value" for a type.