Struct stable_vec::StableVecFacade

pub struct StableVecFacade<T, C: Core<T>> { /* fields omitted */ }

A Vec<T>-like collection which guarantees stable indices and features O(1) deletion of elements.

Terminology and overview of a stable vector

A stable vector has slots. Each slot can either be filled or empty. There are three numbers describing a stable vector (each of those functions runs in O(1)):

• capacity(): the total number of slots (filled and empty).
• num_elements(): the number of filled slots.
• next_push_index(): the index of the first slot (i.e. with the smallest index) that was never filled. This is the index that is returned by push. This implies that all filled slots have indices smaller than next_push_index().

Here is an example visualization (with num_elements = 4).

     0   1   2   3   4   5   6   7   8   9   10
   ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
   │ a │ - │ b │ c │ - │ - │ d │ - │ - │ - │
   └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
                                     ↑       ↑
                       next_push_index       capacity

Unlike Vec<T>, StableVecFacade allows access to all slots with indices between 0 and capacity(). In particular, it is allowed to call insert with all indices smaller than capacity().

The Core implementation C

You might have noticed the type parameter C. There are actually multiple ways how to implement the abstact data structure described above. One might basically use a Vec<Option<T>>. But there are other ways, too.

Most of the time, you can simply use the alias StableVec which uses the DefaultCore. This is fine for almost all cases. That's why all documentation examples use that type instead of the generic StableVecFacade.

Implemented traits

This type implement a couple of traits. Some of those implementations require further explanation:

• Clone: the cloned instance is exactly the same as the original, including empty slots.
• Extend, FromIterator, From<AsRef<[T]>>: these impls work as if all of the source elements are just pushed onto the stable vector in order.
• PartialEq<Self>/Eq: empty slots, capacity, next_push_index and the indices of elements are all checked. In other words: all observable properties of the stable vectors need to be the same for them to be "equal".
• PartialEq<[B]>/PartialEq<Vec<B>>: capacity, next_push_index, empty slots and indices are ignored for the comparison. It is equivalent to sv.iter().eq(vec).

Overview of important methods

(there are more methods than mentioned in this overview)

Creating a stable vector

• new
• with_capacity
• FromIterator::from_iter

Adding and removing elements

• push
• insert
• remove

Accessing elements

• get and get_mut (returns Option<&T> and Option<&mut T>)
• the [] index operator (returns &T or &mut T)
• remove (returns Option<T>)

Stable vector specifics

• has_element_at
• next_push_index
• is_compact

Methods

impl<T, C: Core<T>> StableVecFacade<T, C>

pub fn new() -> Self

Constructs a new, empty stable vector.

The stable-vector will not allocate until elements are pushed onto it.

pub fn with_capacity(capacity: usize) -> Self

Constructs a new, empty stable vector with the specified capacity.

The stable-vector will be able to hold exactly capacity elements without reallocating. If capacity is 0, the stable-vector will not allocate any memory. See reserve for more information.

pub fn push(&mut self, elem: T) -> usize

Inserts the new element elem at index self.next_push_index and returns said index.

The inserted element will always be accessible via the returned index.

This method has an amortized runtime complexity of O(1), just like Vec::push.

Example

let mut sv = StableVec::new();
let star_idx = sv.push('★');
let heart_idx = sv.push('♥');

assert_eq!(sv.get(heart_idx), Some(&'♥'));

// After removing the star we can still use the heart's index to access
// the element!
sv.remove(star_idx);
assert_eq!(sv.get(heart_idx), Some(&'♥'));

pub fn insert(&mut self, index: usize, elem: T) -> Option<T>

Inserts the given value at the given index.

If the slot at index is empty, the elem is inserted at that position and None is returned. If there is an existing element x at that position, that element is replaced by elem and Some(x) is returned. The next_push_index is adjusted accordingly if index >= next_push_index().

Panics

Panics if the index is >= self.capacity().

Example

let mut sv = StableVec::new();
let star_idx = sv.push('★');
let heart_idx = sv.push('♥');

// Inserting into an empty slot (element was deleted).
sv.remove(star_idx);
assert_eq!(sv.num_elements(), 1);
assert_eq!(sv.insert(star_idx, 'x'), None);
assert_eq!(sv.num_elements(), 2);
assert_eq!(sv[star_idx], 'x');

// We can also reserve memory (create new empty slots) and insert into
// such a new slot. Note that that `next_push_index` gets adjusted.
sv.reserve_for(5);
assert_eq!(sv.insert(5, 'y'), None);
assert_eq!(sv.num_elements(), 3);
assert_eq!(sv.next_push_index(), 6);
assert_eq!(sv[5], 'y');

// Inserting into a filled slot replaces the value and returns the old
// value.
assert_eq!(sv.insert(heart_idx, 'z'), Some('♥'));
assert_eq!(sv[heart_idx], 'z');

pub fn remove(&mut self, index: usize) -> Option<T>

Removes and returns the element at position index. If the slot at index is empty, nothing is changed and None is returned.

This simply marks the slot at index as empty. The elements after the given index are not shifted to the left. Thus, the time complexity of this method is O(1).

Panic

Panics if index >= self.capacity().

Example

let mut sv = StableVec::new();
let star_idx = sv.push('★');
let heart_idx = sv.push('♥');

assert_eq!(sv.remove(star_idx), Some('★'));
assert_eq!(sv.remove(star_idx), None); // the star was already removed

// We can use the heart's index here. It has not been invalidated by
// the removal of the star.
assert_eq!(sv.remove(heart_idx), Some('♥'));
assert_eq!(sv.remove(heart_idx), None); // the heart was already removed

pub fn clear(&mut self)

Removes all elements from this collection.

After calling this, num_elements() will return 0. All indices are invalidated. However, no memory is deallocated, so the capacity stays as it was before. self.next_push_index is 0 after calling this method.

Example

let mut sv = StableVec::from(&['a', 'b']);

sv.clear();
assert_eq!(sv.num_elements(), 0);
assert!(sv.capacity() >= 2);

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

Returns a reference to the element at the given index, or None if there exists no element at that index.

If you are calling unwrap() on the result of this method anyway, rather use the index operator instead: stable_vec[index].

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

Returns a mutable reference to the element at the given index, or None if there exists no element at that index.

If you are calling unwrap() on the result of this method anyway, rather use the index operator instead: stable_vec[index].

pub unsafe fn get_unchecked(&self, index: usize) -> &T

Returns a reference to the element at the given index without checking the index.

Security

When calling this method self.has_element_at(index) has to be true, otherwise this method's behavior is undefined! This requirement implies the requirement index < self.next_push_index().

pub unsafe fn get_unchecked_mut(&mut self, index: usize) -> &mut T

Returns a mutable reference to the element at the given index without checking the index.

Security

When calling this method self.has_element_at(index) has to be true, otherwise this method's behavior is undefined! This requirement implies the requirement index < self.next_push_index().

pub fn has_element_at(&self, index: usize) -> bool

Returns true if there exists an element at the given index (i.e. the slot at index is not empty), false otherwise.

An element is said to exist if the index is not out of bounds and the slot at the given index is not empty. In particular, this method can also be called with indices larger than the current capacity (although, false is always returned in those cases).

Example

let mut sv = StableVec::new();
assert!(!sv.has_element_at(3));         // no: index out of bounds

let heart_idx = sv.push('♥');
assert!(sv.has_element_at(heart_idx));  // yes

sv.remove(heart_idx);
assert!(!sv.has_element_at(heart_idx)); // no: was removed

pub fn num_elements(&self) -> usize

Returns the number of existing elements in this collection.

As long as no element is ever removed, num_elements() equals next_push_index(). Once an element has been removed, num_elements() will always be less than next_push_index() (assuming [reordering_]make_compact() is not called).

Example

let mut sv = StableVec::new();
assert_eq!(sv.num_elements(), 0);

let heart_idx = sv.push('♥');
assert_eq!(sv.num_elements(), 1);

sv.remove(heart_idx);
assert_eq!(sv.num_elements(), 0);

pub fn next_push_index(&self) -> usize

Returns the index that would be returned by calling push(). All filled slots have indices below next_push_index().

Example

let mut sv = StableVec::from(&['a', 'b', 'c']);

let next_push_index = sv.next_push_index();
let index_of_d = sv.push('d');

assert_eq!(next_push_index, index_of_d);

pub fn capacity(&self) -> usize

Returns the number of slots in this stable vector.

pub fn is_empty(&self) -> bool

Returns true if this collection doesn't contain any existing elements.

This means that is_empty() returns true iff no elements were inserted or all inserted elements were removed again.

Example

let mut sv = StableVec::new();
assert!(sv.is_empty());

let heart_idx = sv.push('♥');
assert!(!sv.is_empty());

sv.remove(heart_idx);
assert!(sv.is_empty());

pub fn is_compact(&self) -> bool

Returns true if all existing elements are stored contiguously from the beginning (in other words: there are no empty slots with indices below self.next_push_index()).

Example

let mut sv = StableVec::from(&[0, 1, 2, 3, 4]);
assert!(sv.is_compact());

sv.remove(1);
assert!(!sv.is_compact());

Important traits for Iter<'a, T, C>

impl<'a, T, C: Core<T>> Iterator for Iter<'a, T, C> type Item = (usize, &'a T);

pub fn iter(&self) -> Iter<T, C>

Returns an iterator over indices and immutable references to the stable vector's elements. Elements are yielded in order of their increasing indices.

Note that you can also obtain this iterator via the IntoIterator impl of &StableVecFacade.

Example

let mut sv = StableVec::from(&[10, 11, 12, 13, 14]);
sv.remove(1);

let mut it = sv.iter().filter(|&(_, &n)| n <= 13);
assert_eq!(it.next(), Some((0, &10)));
assert_eq!(it.next(), Some((2, &12)));
assert_eq!(it.next(), Some((3, &13)));
assert_eq!(it.next(), None);

Important traits for IterMut<'a, T, C>

impl<'a, T, C: Core<T>> Iterator for IterMut<'a, T, C> type Item = (usize, &'a mut T);

pub fn iter_mut(&mut self) -> IterMut<T, C>

Returns an iterator over indices and mutable references to the stable vector's elements. Elements are yielded in order of their increasing indices.

Note that you can also obtain this iterator via the IntoIterator impl of &mut StableVecFacade.

Example

let mut sv = StableVec::from(&[10, 11, 12, 13, 14]);
sv.remove(1);

for (idx, elem) in &mut sv {
    if idx % 2 == 0 {
        *elem *= 2;
    }
}

assert_eq!(sv, vec![20, 24, 13, 28]);

Important traits for Values<'a, T, C>

impl<'a, T, C: Core<T>> Iterator for Values<'a, T, C> type Item = &'a T;

pub fn values(&self) -> Values<T, C>

Returns an iterator over immutable references to the existing elements of this stable vector. Elements are yielded in order of their increasing indices.

Example

let mut sv = StableVec::from(&[0, 1, 2, 3, 4]);
sv.remove(1);

let mut it = sv.values().filter(|&&n| n <= 3);
assert_eq!(it.next(), Some(&0));
assert_eq!(it.next(), Some(&2));
assert_eq!(it.next(), Some(&3));
assert_eq!(it.next(), None);

Important traits for ValuesMut<'a, T, C>

impl<'a, T, C: Core<T>> Iterator for ValuesMut<'a, T, C> type Item = &'a mut T;

pub fn values_mut(&mut self) -> ValuesMut<T, C>

Returns an iterator over mutable references to the existing elements of this stable vector. Elements are yielded in order of their increasing indices.

Through this iterator, the elements within the stable vector can be mutated.

Examples

let mut sv = StableVec::from(&[1.0, 2.0, 3.0]);

for e in sv.values_mut() {
    *e *= 2.0;
}

assert_eq!(sv, &[2.0, 4.0, 6.0] as &[_]);

Important traits for Indices<'_, T, C>

impl<'_, T, C: Core<T>> Iterator for Indices<'_, T, C> type Item = usize;

pub fn indices(&self) -> Indices<T, C>

Returns an iterator over all indices of filled slots of this stable vector. Indices are yielded in increasing order.

Example

let mut sv = StableVec::from(&['a', 'b', 'c', 'd']);
sv.remove(1);

let mut it = sv.indices();
assert_eq!(it.next(), Some(0));
assert_eq!(it.next(), Some(2));
assert_eq!(it.next(), Some(3));
assert_eq!(it.next(), None);

Simply using the for-loop:

let mut sv = StableVec::from(&['a', 'b', 'c', 'd']);

for index in sv.indices() {
    println!("index: {}", index);
}

pub fn reserve(&mut self, additional: usize)

Reserves memory for at least additional more elements to be inserted at indices >= self.next_push_index().

This method might allocate more than additional to avoid frequent reallocations. Does nothing if the current capacity is already sufficient. After calling this method, self.capacity() is ≥ self.next_push_index() + additional.

Unlike Vec::reserve, the additional reserved memory is not completely unaccessible. Instead, additional empty slots are added to this stable vector. These can be used just like any other empty slot; in particular, you can insert into it.

Example

let mut sv = StableVec::new();
let star_idx = sv.push('★');

// After we inserted one element, the next element would sit at index
// 1, as expected.
assert_eq!(sv.next_push_index(), 1);

sv.reserve(2); // insert two empty slots

// `reserve` doesn't change any of this
assert_eq!(sv.num_elements(), 1);
assert_eq!(sv.next_push_index(), 1);

// We can now insert an element at index 2.
sv.insert(2, 'x');
assert_eq!(sv[2], 'x');

// These values get adjusted accordingly.
assert_eq!(sv.num_elements(), 2);
assert_eq!(sv.next_push_index(), 3);

pub fn reserve_for(&mut self, index: usize)

Reserve enough memory so that there is a slot at index. Does nothing if index < self.capacity().

This method might allocate more memory than requested to avoid frequent allocations. After calling this method, self.capacity() >= index + 1.

Example

let mut sv = StableVec::new();
let star_idx = sv.push('★');

// Allocate enough memory so that we have a slot at index 5.
sv.reserve_for(5);
assert!(sv.capacity() >= 6);

// We can now insert an element at index 5.
sv.insert(5, 'x');
assert_eq!(sv[5], 'x');

// This won't do anything as the slot with index 3 already exists.
let capacity_before = sv.capacity();
sv.reserve_for(3);
assert_eq!(sv.capacity(), capacity_before);

pub fn reserve_exact(&mut self, additional: usize)

Like reserve, but tries to allocate memory for exactly additional more elements.

The underlying allocator might allocate more memory than requested, meaning that you cannot rely on the capacity of this stable vector having an exact value after calling this method.

pub fn remove_first(&mut self) -> Option<T>

Removes and returns the first element from this collection, or None if it's empty.

This method uses exactly the same deletion strategy as remove().

Example

let mut sv = StableVec::from(&[1, 2, 3]);
assert_eq!(sv.remove_first(), Some(1));
assert_eq!(sv, vec![2, 3]);

Note

This method needs to find the index of the first valid element. Finding it has a worst case time complexity of O(n). If you already know the index, use remove() instead.

pub fn remove_last(&mut self) -> Option<T>

Removes and returns the last element from this collection, or None if it's empty.

This method uses exactly the same deletion strategy as remove().

Example

let mut sv = StableVec::from(&[1, 2, 3]);
assert_eq!(sv.remove_last(), Some(3));
assert_eq!(sv, vec![1, 2]);

Note

This method needs to find the index of the last valid element. Finding it has a worst case time complexity of O(n). If you already know the index, use remove() instead.

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

Finds the first element and returns a reference to it, or None if the stable vector is empty.

This method has a worst case time complexity of O(n).

Example

let mut sv = StableVec::from(&[1, 2]);
sv.remove(0);
assert_eq!(sv.find_first(), Some(&2));

pub fn find_first_mut(&mut self) -> Option<&mut T>

Finds the first element and returns a mutable reference to it, or None if the stable vector is empty.

This method has a worst case time complexity of O(n).

Example

let mut sv = StableVec::from(&[1, 2]);
{
    let first = sv.find_first_mut().unwrap();
    assert_eq!(*first, 1);

    *first = 3;
}
assert_eq!(sv, vec![3, 2]);

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

Finds the last element and returns a reference to it, or None if the stable vector is empty.

This method has a worst case time complexity of O(n).

Example

let mut sv = StableVec::from(&[1, 2]);
sv.remove(1);
assert_eq!(sv.find_last(), Some(&1));

pub fn find_last_mut(&mut self) -> Option<&mut T>

Finds the last element and returns a mutable reference to it, or None if the stable vector is empty.

This method has a worst case time complexity of O(n).

Example

let mut sv = StableVec::from(&[1, 2]);
{
    let last = sv.find_last_mut().unwrap();
    assert_eq!(*last, 2);

    *last = 3;
}
assert_eq!(sv, vec![1, 3]);

pub fn first_filled_slot_from(&self, start: usize) -> Option<usize>

Performs a forwards search starting at index start, returning the index of the first filled slot that is found.

Specifically, if an element at index start exists, Some(start) is returned. If all slots with indices start and higher are empty (or don't exist), None is returned. This method can be used to iterate over all existing elements without an iterator object.

The inputs start >= self.next_push_index() are only allowed for convenience. For those start values, None is always returned.

Panics

Panics if start > self.capacity(). Note: start == self.capacity() is allowed for convenience, but always returns None.

Example

let mut sv = StableVec::from(&[0, 1, 2, 3, 4]);
sv.remove(1);
sv.remove(2);
sv.remove(4);

assert_eq!(sv.first_filled_slot_from(0), Some(0));
assert_eq!(sv.first_filled_slot_from(1), Some(3));
assert_eq!(sv.first_filled_slot_from(2), Some(3));
assert_eq!(sv.first_filled_slot_from(3), Some(3));
assert_eq!(sv.first_filled_slot_from(4), None);
assert_eq!(sv.first_filled_slot_from(5), None);

pub fn first_filled_slot_below(&self, start: usize) -> Option<usize>

Performs a backwards search starting at index start - 1, returning the index of the first filled slot that is found. For start == 0, None is returned.

Note: passing in start >= self.len() just wastes time, as those slots are never filled.

Panics

Panics if start > self.capacity(). Note: start == self.capacity() is allowed for convenience, but wastes time.

Example

let mut sv = StableVec::from(&[0, 1, 2, 3, 4]);
sv.remove(0);
sv.remove(2);
sv.remove(3);

assert_eq!(sv.first_filled_slot_below(0), None);
assert_eq!(sv.first_filled_slot_below(1), None);
assert_eq!(sv.first_filled_slot_below(2), Some(1));
assert_eq!(sv.first_filled_slot_below(3), Some(1));
assert_eq!(sv.first_filled_slot_below(4), Some(1));
assert_eq!(sv.first_filled_slot_below(5), Some(4));

pub fn first_empty_slot_from(&self, start: usize) -> Option<usize>

Performs a forwards search starting at index start, returning the index of the first empty slot that is found.

Specifically, if the slot at index start is empty, Some(start) is returned. If all slots with indices start and higher are filled, None is returned.

Panics

Panics if start > self.capacity(). Note: start == self.capacity() is allowed for convenience, but always returns None.

Example

let mut sv = StableVec::from(&[0, 1, 2, 3, 4, 5]);
sv.remove(1);
sv.remove(2);
sv.remove(4);

assert_eq!(sv.first_empty_slot_from(0), Some(1));
assert_eq!(sv.first_empty_slot_from(1), Some(1));
assert_eq!(sv.first_empty_slot_from(2), Some(2));
assert_eq!(sv.first_empty_slot_from(3), Some(4));
assert_eq!(sv.first_empty_slot_from(4), Some(4));

// Make sure we have at least one empty slot at the end
sv.reserve_for(6);
assert_eq!(sv.first_empty_slot_from(5), Some(6));
assert_eq!(sv.first_empty_slot_from(6), Some(6));

pub fn first_empty_slot_below(&self, start: usize) -> Option<usize>

Performs a backwards search starting at index start - 1, returning the index of the first empty slot that is found. For start == 0, None is returned.

If all slots with indices below start are filled, None is returned.

Example

let mut sv = StableVec::from(&[0, 1, 2, 3, 4, 5]);
sv.remove(1);
sv.remove(2);
sv.remove(4);

assert_eq!(sv.first_empty_slot_below(0), None);
assert_eq!(sv.first_empty_slot_below(1), None);
assert_eq!(sv.first_empty_slot_below(2), Some(1));
assert_eq!(sv.first_empty_slot_below(3), Some(2));
assert_eq!(sv.first_empty_slot_below(4), Some(2));
assert_eq!(sv.first_empty_slot_below(5), Some(4));
assert_eq!(sv.first_empty_slot_below(6), Some(4));

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

Finds the first element and returns its index, or None if the stable vector is empty.

This method has a worst case time complexity of O(n).

Example

let mut sv = StableVec::from(&[1, 2]);
sv.remove(0);
assert_eq!(sv.find_first_index(), Some(1));

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

Finds the last element and returns its index, or None if the stable vector is empty.

This method has a worst case time complexity of O(n).

Example

let mut sv = StableVec::from(&[1, 2]);
sv.remove(1);
assert_eq!(sv.find_last_index(), Some(0));

pub fn shrink_to_fit(&mut self)

Reallocates to have a capacity as small as possible while still holding self.next_push_index() slots.

Note that this does not move existing elements around and thus does not invalidate indices. This method also doesn't change what next_push_index returns. Instead, only the capacity is changed. Due to the underlying allocator, it cannot be guaranteed that the capacity is exactly self.next_push_index() after calling this method.

If you want to compact this stable vector by removing deleted elements, use the method make_compact or reordering_make_compact instead.

pub fn make_compact(&mut self)

Rearranges elements to reclaim memory. Invalidates indices!

After calling this method, all existing elements stored contiguously in memory. You might want to call shrink_to_fit() afterwards to actually free memory previously used by removed elements. This method itself does not deallocate any memory.

The next_push_index value is also changed by this method (if the stable vector wasn't compact before).

In comparison to reordering_make_compact(), this method does not change the order of elements. Due to this, this method is a bit slower.

Warning

This method invalidates the indices of all elements that are stored after the first empty slot in the stable vector!

pub fn reordering_make_compact(&mut self)

Rearranges elements to reclaim memory. Invalidates indices and changes the order of the elements!

After calling this method, all existing elements stored contiguously in memory. You might want to call shrink_to_fit() afterwards to actually free memory previously used by removed elements. This method itself does not deallocate any memory.

The next_push_index value is also changed by this method (if the stable vector wasn't compact before).

If you do need to preserve the order of elements, use make_compact() instead. However, if you don't care about element order, you should prefer using this method, because it is faster.

Warning

This method invalidates the indices of all elements that are stored after the first hole and it does not preserve the order of elements!

pub fn contains<U>(&self, item: &U) -> bool where
    U: PartialEq<T>, 

Returns true if the stable vector contains an element with the given value, false otherwise.

let mut sv = StableVec::from(&['a', 'b', 'c']);
assert!(sv.contains(&'b'));

sv.remove(1);   // 'b' is stored at index 1
assert!(!sv.contains(&'b'));

pub fn swap(&mut self, a: usize, b: usize)

Swaps the slot at index a with the slot at index b.

The full slots are swapped, including the element and the "filled" state. If you swap slots with an element in it, that element's index is invalidated, of course. This method automatically sets next_push_index to a larger value if that's necessary.

Panics

This panics if a or b are not smaller than self.capacity().

Example

let mut sv = StableVec::from(&['a', 'b', 'c', 'd']);
sv.reserve_for(5);
assert_eq!(sv.next_push_index(), 4);

// Swapping an empty slot with a filled one
sv.swap(0, 5);
assert_eq!(sv.get(0), None);
assert_eq!(sv.get(1), Some(&'b'));
assert_eq!(sv.get(2), Some(&'c'));
assert_eq!(sv.get(3), Some(&'d'));
assert_eq!(sv.get(4), None);
assert_eq!(sv.get(5), Some(&'a'));
assert_eq!(sv.next_push_index(), 6);

// Swapping two filled slots
sv.swap(1, 2);
assert_eq!(sv.get(0), None);
assert_eq!(sv.get(1), Some(&'c'));
assert_eq!(sv.get(2), Some(&'b'));
assert_eq!(sv.get(3), Some(&'d'));
assert_eq!(sv.get(4), None);
assert_eq!(sv.get(5), Some(&'a'));

// You can also swap two empty slots, but that doesn't change anything.
sv.swap(0, 4);
assert_eq!(sv.get(0), None);
assert_eq!(sv.get(1), Some(&'c'));
assert_eq!(sv.get(2), Some(&'b'));
assert_eq!(sv.get(3), Some(&'d'));
assert_eq!(sv.get(4), None);
assert_eq!(sv.get(5), Some(&'a'));

pub fn retain<P>(&mut self, should_be_kept: P) where
    P: FnMut(&T) -> bool, 

Retains only the elements specified by the given predicate.

Each element e for which should_be_kept(&e) returns false is removed from the stable vector.

Example

let mut sv = StableVec::from(&[1, 2, 3, 4, 5]);
sv.retain(|&e| e % 2 == 0);

assert_eq!(sv, &[2, 4] as &[_]);

pub fn retain_indices<P>(&mut self, should_be_kept: P) where
    P: FnMut(usize) -> bool, 

Retains only the elements with indices specified by the given predicate.

Each element with index i for which should_be_kept(i) returns false is removed from the stable vector.

Example

let mut sv = StableVec::new();
sv.push(1);
let two = sv.push(2);
sv.push(3);
sv.retain_indices(|i| i == two);

assert_eq!(sv, &[2] as &[_]);

pub fn extend_from_slice(&mut self, new_elements: &[T]) where
    T: Clone, 

Appends all elements in new_elements to this stable vector. This is equivalent to calling push() for each element.

Trait Implementations

impl<T: Debug, C: Core<T>> Debug for StableVecFacade<T, C>

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

Formats the value using the given formatter.

impl<Ta, Tb, Ca, Cb> PartialEq<StableVecFacade<Tb, Cb>> for StableVecFacade<Ta, Ca> where
    Ta: PartialEq<Tb>,
    Ca: Core<Ta>,
    Cb: Core<Tb>, 

fn eq(&self, other: &StableVecFacade<Tb, Cb>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A, B, C: Core<A>> PartialEq<[B]> for StableVecFacade<A, C> where
    A: PartialEq<B>, 

fn eq(&self, other: &[B]) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'other, A, B, C: Core<A>> PartialEq<&'other [B]> for StableVecFacade<A, C> where
    A: PartialEq<B>, 

fn eq(&self, other: &&'other [B]) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A, B, C: Core<A>> PartialEq<Vec<B>> for StableVecFacade<A, C> where
    A: PartialEq<B>, 

fn eq(&self, other: &Vec<B>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T: Eq, C: Core<T>> Eq for StableVecFacade<T, C>

impl<T, C: Core<T>> Index<usize> for StableVecFacade<T, C>

type Output = T

The returned type after indexing.

fn index(&self, index: usize) -> &T

Performs the indexing (container[index]) operation.

impl<T, C: Core<T>> IndexMut<usize> for StableVecFacade<T, C>

fn index_mut(&mut self, index: usize) -> &mut T

Performs the mutable indexing (container[index]) operation.

impl<'a, T, C: Core<T>> IntoIterator for &'a StableVecFacade<T, C>

type Item = (usize, &'a T)

The type of the elements being iterated over.

type IntoIter = Iter<'a, T, C>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T, C: Core<T>> IntoIterator for &'a mut StableVecFacade<T, C>

type Item = (usize, &'a mut T)

The type of the elements being iterated over.

type IntoIter = IterMut<'a, T, C>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T, C: Core<T>> IntoIterator for StableVecFacade<T, C>

type Item = (usize, T)

The type of the elements being iterated over.

type IntoIter = IntoIter<T, C>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T, C: Core<T>> FromIterator<T> for StableVecFacade<T, C>

fn from_iter<I>(iter: I) -> Self where
    I: IntoIterator<Item = T>, 

Creates a value from an iterator.

impl<T, C: Core<T>> Extend<T> for StableVecFacade<T, C>

fn extend<I>(&mut self, iter: I) where
    I: IntoIterator<Item = T>, 

Extends a collection with the contents of an iterator.

impl<T, S, C: Core<T>> From<S> for StableVecFacade<T, C> where
    S: AsRef<[T]>,
    T: Clone, 

fn from(slice: S) -> Self

Performs the conversion.

impl<T: Clone, C: Clone + Core<T>> Clone for StableVecFacade<T, C>

fn clone(&self) -> StableVecFacade<T, C>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T, C: Core<T>> Default for StableVecFacade<T, C>

fn default() -> Self

Returns the "default value" for a type.