Struct vec_mut_scan::VecGrowScan

pub struct VecGrowScan<'a, T: 'a> { /* fields omitted */ }

Forward scan over a vector with mutation, item insertion and removal.

Provides an iterator like interface over a vector which allows mutation, inserting new items before or after the current items, and removal of items.

If you do not need to insert new items, use VecMutScan instead.

Internally, the items are kept in the vector in order. When items are removed, a gap of uninitialized memory is created, and the items get moved as the iteration continues. When additional items are inserted, and there is no gap to be filled, the excess is stored in a VecDeque.

Overall, a linear number of moves is performed, but the exact number varies due to potential reallocations. If no items are inserted, every item is moved at most once.

Dropping the VecGrowScan mid-iteration keeps remaining items in the vector.

This does not implement the iterator trait, as the returned items borrow from this (i.e. this is a streaming iterator).

The next method returns VecGrowScanItem values, which auto dereference to the vector's item type but also provide a remove and replace method.

Implementations

impl<'a, T: 'a> VecGrowScan<'a, T>

pub fn new(vec: &mut Vec<T>) -> VecGrowScan<'_, T>

Begin a scan over a vector with mutation, insertion and removal.

pub fn next<'s>(&'s mut self) -> Option<VecGrowScanItem<'s, 'a, T>>

Advance to the next item of the vector.

This returns a reference wrapper that enables item removal (see VecGrowScanItem).

pub fn insert(&mut self, item: T)

Insert an item between the items that have been visited, and the items that haven't been visited yet. Inserted items are not returned during iteration.

let mut numbers = vec![1, 2, 4, 5];
let mut scan = VecGrowScan::new(&mut numbers);

assert_eq!(*scan.next().unwrap(), 1);
assert_eq!(*scan.next().unwrap(), 2);
scan.insert(3);
assert_eq!(*scan.next().unwrap(), 4);
assert_eq!(*scan.next().unwrap(), 5);
drop(scan);

assert_eq!(numbers, [1, 2, 3, 4, 5]);

pub fn insert_many(&mut self, iter: impl IntoIterator<Item = T>)

Insert a sequence of items between the items that have been visited, and the items that haven't been visited yet. Inserted items are not returned during iteration.

Equivalent to repeatedly calling insert, except that reallocations will be minimized with iterator size hints.

pub fn slices(&self) -> (&[T], &[T], &[T], &[T])

Access the whole vector.

This provides access to the whole vector at any point during the scan. In general while scanning, the vector content is not contiguous, and some of the contents may be kept out-of-place in a VecDeque. Thus the content is returned as four slices. The first three slices, in order, contain all elements already visited, while the fourth slice contains the remaining elements starting with the element that will be returned by the following next call.

This method is also present on the VecGrowScanItem reference wrapper returned by next, allowing access while that wrapper borrows this VecGrowScan.

pub fn slices_mut(&mut self) -> (&mut [T], &mut [T], &mut [T], &mut [T])

Access and mutate the whole vector.

This provides mutable access to the whole vector at any point during the scan. In general while scanning, the vector content is not contiguous, and some of the contents may be kept out-of-place in a VecDeque. Thus the content is returned as four slices. The first three slices, in order, contain all elements already visited, while the fourth slice contains the remaining elements starting with the element that will be returned by the following next call.

This method is also present on the VecGrowScanItem reference wrapper returned by next, allowing access while that wrapper borrows this VecGrowScan.

Trait Implementations

impl<'a, T: 'a> Drop for VecGrowScan<'a, T>

pub fn drop(&mut self)

Executes the destructor for this type.