Struct Removing

Source
pub struct Removing<'a, T> { /* private fields */ }
Expand description

A cursor-like structure made for cheap iterative removing of elements from vector.

Essentially overhead of the process is one ptr::copy for each ignored element + one ptr::copy for the not yielded tail.

For the comparison with manual Vec::remove see self

Also, an analog to this may be VecDeque (if you need to only pop elements from either of ends) or (unstable as of writing this) [Vec::drain_filter] (if you need to remove all matching elements).

However note 2 differences between [Vec::drain_filter] and Removing:

  • Removing is not iterator (this makes it more universal but less convenient to use)
  • Removing does not remove elements from the vec when you drop it

The main method of this struct is next which returns Entry which can be used to mutate the vec.

§Examples

use vecrem::VecExt;

let mut vec: Vec<_> = (0..17).collect();
let mut out = Vec::new();
{
    let mut rem = vec.removing();

    while let Some(entry) = rem.next() {
        let value = *entry.value();
        if value >= 10 {
            break;
        }

        if value % 2 == 0 {
            out.push(entry.remove());
        }
    }
}

// All ignored and not yielded elements are in the original vec
assert_eq!(vec, [1, 3, 5, 7, 9, 10, 11, 12, 13, 14, 15, 16]);

assert_eq!(out, [0, 2, 4, 6, 8])

§forget behavior

In the same way as [Vec::drain_filter], for efficient work, Removing needs to temporarily break vec’s invariants leaving it in an inconsistent state. The state is made normal in Drop.

However in rust running destructors is not guaranteed (see mem::forget, ManuallyDrop). As such, on construction Removing sets vec’s len to 0 (and restores it in Drop), this means that if Removing gets leaked or forgotten - the elements of the vector are forgotten too.

use vecrem::VecExt;

let mut vec = vec![0, 1, 2, 3, 4];
core::mem::forget(vec.removing());
assert_eq!(vec, []);

Implementations§

Source§

impl<'a, T> Removing<'a, T>

Source

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

Creates new Removing instance from given vec.

See also: VecExt::removing

Source

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

Returns Entry for the next element.

Source

pub fn len(&self) -> usize

Returns number of remaining elements in this pseudo-iterator

§Examples
use vecrem::VecExt;

let mut vec = vec![0, 1, 2, 3, 4];
let mut rem = vec.removing();
assert_eq!(rem.len(), 5);

rem.next();
assert_eq!(rem.len(), 4);
Source

pub fn is_empty(&self) -> bool

Return true if all elements of the underling vector were either ignored or removed (i.e.: when next will return None)

Trait Implementations§

Source§

impl<T> Drop for Removing<'_, T>

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more

Auto Trait Implementations§

§

impl<'a, T> Freeze for Removing<'a, T>

§

impl<'a, T> RefUnwindSafe for Removing<'a, T>
where T: RefUnwindSafe,

§

impl<'a, T> Send for Removing<'a, T>
where T: Send,

§

impl<'a, T> Sync for Removing<'a, T>
where T: Sync,

§

impl<'a, T> Unpin for Removing<'a, T>

§

impl<'a, T> !UnwindSafe for Removing<'a, T>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.