Trait TryExtendSafe 

pub trait TryExtendSafe<I: IntoIterator> {
    type Error;

    // Required method
    fn try_extend_safe(&mut self, iter: I) -> Result<(), Self::Error>;
}

Trait for extending a collection with a strong error guarantee.

Unlike TryExtend, this trait guarantees that the collection remains unchanged if an error occurs during extension.

Like with TryExtend, implementors may rely on Iterator::size_hint providing reliable bounds for the number of elements in the iterator in order to optimize their implementations. An iterator that violates the bounds returned by Iterator::size_hint may cause panics, produce incorrect results, or produce a result that violates container constraints, but must not result in undefined behavior.

Required Associated Types

type Error

The type of error that can occur during safe extension.

Required Methods

fn try_extend_safe(&mut self, iter: I) -> Result<(), Self::Error>

Tries to extends the collection providing a strong error guarantee.

On failure, the collection must remain unchanged. Implementors may need to buffer elements or use a more defensive algorithm to satisfy this guarantee.

For a faster basic-guarantee alternative, see TryExtend::try_extend.

Errors

Returns TryExtendSafe::Error if a failure occurs while extending the collection.

Examples

The provided HashMap implementation errors if a key collision occurs during extension.

let mut map = BTreeMap::from([(1, 2), (2, 3)]);
let err = map.try_extend_safe([(3, 4), (1, 5), (4, 6)]).expect_err("should collide");

assert_eq!(err.error.item, (1, 5), "item should be the colliding item");

let iterated_items: Vec<_> = err.into_iter().collect();

// iterator data can be recovered: [rejected item, ..collected, ..iterator]
assert_eq!(iterated_items, vec![(1, 5), (3, 4), (4, 6)]);

assert_eq!(map, BTreeMap::from([(1, 2), (2, 3)]), "map should be unchanged");

Implementations on Foreign Types

impl<K: Eq + Hash, V, S: BuildHasher + Clone, I> TryExtendSafe<I> for HashMap<K, V, S>

where I: IntoIterator<Item = (K, V)>,

type Error = CollectError<<I as IntoIterator>::IntoIter, HashMap<K, V, S>, <HashMap<K, V, S> as TryExtendOne>::Error>

fn try_extend_safe(&mut self, iter: I) -> Result<(), Self::Error>

impl<K: Eq + Hash, V, S: BuildHasher + Clone, I> TryExtendSafe<I> for HashMap<K, V, S>

where I: IntoIterator<Item = (K, V)>,

type Error = CollectError<<I as IntoIterator>::IntoIter, HashMap<K, V, S>, Collision<(K, V)>>

fn try_extend_safe(&mut self, iter: I) -> Result<(), Self::Error>

impl<K: Eq + Hash, V, S: BuildHasher + Clone, I> TryExtendSafe<I> for IndexMap<K, V, S>

where I: IntoIterator<Item = (K, V)>,

type Error = CollectError<<I as IntoIterator>::IntoIter, IndexMap<K, V, S>, <IndexMap<K, V, S> as TryExtendOne>::Error>

fn try_extend_safe(&mut self, iter: I) -> Result<(), Self::Error>

impl<K: Ord, V, I> TryExtendSafe<I> for BTreeMap<K, V>

where I: IntoIterator<Item = (K, V)>,

type Error = CollectError<<I as IntoIterator>::IntoIter, BTreeMap<K, V>, <BTreeMap<K, V> as TryExtendOne>::Error>

fn try_extend_safe(&mut self, iter: I) -> Result<(), Self::Error>

impl<T, const N: usize, I> TryExtendSafe<I> for ArrayVec<T, N>

where I: IntoIterator<Item = T>,

Extends an ArrayVec with strong error guarantee.

fn try_extend_safe(&mut self, iter: I) -> Result<(), Self::Error>

Appends iter to the ArrayVec, failing if iter produces more items than ArrayVec::remaining_capacity.

Errors

Returns a CollectError if iter produces more items than ArrayVec::remaining_capacity. This method provides a strong error guarantee. In the case of an error, the ArrayVec is not modified.

Panics

Panics if the iter’s size_hint is invalid.

Examples

let mut array: ArrayVec<i32, 4> = (1..=2).try_collect_ex()?;
array.try_extend_safe([3])?;
assert_eq!(*array, [1, 2, 3], "array should contain 3 items");

let err = array.try_extend_safe([4, 5]).expect_err("should fail with too many items");
assert_eq!(*array, [1, 2, 3], "array should be unchanged on error");

let collected: Vec<i32> = err.into_iter().collect();
assert_eq!(collected, [4, 5], "error should contain all unconsumed items");

type Error = CollectError<<I as IntoIterator>::IntoIter, ArrayVec<T, N>, CapacityError<T>>

impl<T: Eq + Hash, S: BuildHasher + Clone, I> TryExtendSafe<I> for HashSet<T, S>

where I: IntoIterator<Item = T>,

type Error = CollectError<<I as IntoIterator>::IntoIter, HashSet<T, S>, <HashSet<T, S> as TryExtendOne>::Error>

fn try_extend_safe(&mut self, iter: I) -> Result<(), Self::Error>

impl<T: Eq + Hash, S: BuildHasher + Clone, I> TryExtendSafe<I> for HashSet<T, S>

where I: IntoIterator<Item = T>,

type Error = CollectError<<I as IntoIterator>::IntoIter, HashSet<T, S>, <HashSet<T, S> as TryExtendOne>::Error>

fn try_extend_safe(&mut self, iter: I) -> Result<(), Self::Error>

impl<T: Eq + Hash, S: BuildHasher + Clone, I> TryExtendSafe<I> for IndexSet<T, S>

where I: IntoIterator<Item = T>,

type Error = CollectError<<I as IntoIterator>::IntoIter, IndexSet<T, S>, <IndexSet<T, S> as TryExtendOne>::Error>

fn try_extend_safe(&mut self, iter: I) -> Result<(), Self::Error>

impl<T: Ord, I> TryExtendSafe<I> for BTreeSet<T>

where I: IntoIterator<Item = T>,

type Error = CollectError<<I as IntoIterator>::IntoIter, BTreeSet<T>, <BTreeSet<T> as TryExtendOne>::Error>

fn try_extend_safe(&mut self, iter: I) -> Result<(), Self::Error>

Implementors