Struct scanmut::Remover

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

An object that can remove multiple elements from a Vec in a single scan through the Vec.

The Remover has a position in the Vec at which it inserts, called the index. Initially, the index is at the start of the Vec. This index can only be moved further towards end of the Vec, meaning that the indices of the removed objects must be monotonically increasing (i.e. the next index must be larger than the previous index).

Dropping the Remover without using the entire insertion capacity has a runtime cost proportional to the size of the merged elements. Dropping after using the entire insertion capacity has no runtime cost.

Leaking the Remover (through std::mem::forget or similar) may leak some items of the Vec and will leave the Vec in an unspecified but valid state

Example

use scanmut::Remover;

let mut items = vec!['a', 'b', 'c'];

let mut remover = Remover::new(&mut items);

assert_eq!(remover.index(), 0); // Initial index is at start of the vec
assert_eq!(remover.remove(), 'a');

assert_eq!(remover.index(), 1);  // Removing an element increments the index
remover.move_to(2);

assert_eq!(remover.index(), 2);
assert_eq!(remover.remove(), 'c');

assert_eq!(remover.index(), 3);

drop(remover);

assert_eq!(items, ['b']);

As calling Remover::remove will increment the index, it can be used to remove items in a row:

use scanmut::Remover;

let mut items = vec!['a', 'b', 'c', 'd'];

let mut remover = Remover::new(&mut items);

remover.move_to(1);
assert_eq!(remover.remove(), 'b');
assert_eq!(remover.remove(), 'c');
drop(remover);

assert_eq!(items, ['a', 'd']);

Implementations

impl<'a, T> Remover<'a, T>

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

Create a new new Remover for removing elements from a Vec.

pub fn index(&self) -> usize

The current index of this remover.

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

Returns a reference to the item at the current index or None if the remover is past the end of the underlying Vec.

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

Returns a mutable reference to the item at the current index or None if the remover is past the end of the underlying Vec.

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

Returns a pair of slices representing the current state of the Vec being removed from.

The first slice is the part of the Vec below the index. The second slice is the part of the Vec above or equal to the index.

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

Returns a pair of mutable slices representing the current state of the Vec being removed from.

The first slice is the part of the Vec below the index. The second slice is the part of the Vec above or equal to the index.

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

Moves this Remover to the given index in the Vec.

Panics

Panics if the index is less than or equal to the current index.

pub fn remove(&mut self) -> T

Removes an element from the Vec at the current index.

This also increments the index to the next position.

Panics

Panics if the index is at the end of the vec.

Trait Implementations

impl<'a, T: Debug> Debug for Remover<'a, T>

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

Formats the value using the given formatter.

impl<'a, T> Drop for Remover<'a, T>

pub fn drop(&mut self)

Executes the destructor for this type.