Trait FallibleVec 

pub trait FallibleVec<T>: Sized {
    // Required methods
    fn try_extend<I: IntoIterator<Item = T>>(
        &mut self,
        iter: I,
    ) -> Result<(), TryReserveError>;
    fn try_push(&mut self, item: T) -> Result<(), TryReserveError>;
    fn try_insert(
        &mut self,
        index: usize,
        element: T,
    ) -> Result<(), TryReserveError>;
    fn try_resize_with<F: FnMut() -> T>(
        &mut self,
        new_len: usize,
        f: F,
    ) -> Result<(), TryReserveError>;
    fn try_splice_in<I: IntoIterator<Item = T>, A: Allocator>(
        &mut self,
        range: impl RangeBounds<usize>,
        replace_with: I,
        alloc: A,
    ) -> Result<(), TryReserveError>;
    fn try_extend_from_slice(
        &mut self,
        slice: &[T],
    ) -> Result<(), TryReserveError>
       where T: Clone;
    fn try_resize(
        &mut self,
        new_len: usize,
        item: T,
    ) -> Result<(), TryReserveError>
       where T: Clone;
}

Fallible allocation methods for Vec.

Required Methods

fn try_extend<I: IntoIterator<Item = T>>( &mut self, iter: I, ) -> Result<(), TryReserveError>

Extends the Vec using the items from the given iterator.

Panic safety

If a call to next() on iter panics, then all of the items previously returned from the iterator will be added to the Vec.

Examples

use fallible_vec::*;

let mut vec = try_vec![1, 2]?;
vec.try_extend([3, 4, 5])?;
assert_eq!(vec, [1, 2, 3, 4, 5]);

fn try_push(&mut self, item: T) -> Result<(), TryReserveError>

Appends an element to the back of a collection.

Examples

use fallible_vec::*;
let mut vec = try_vec![1, 2]?;
vec.try_push(3)?;
assert_eq!(vec, [1, 2, 3]);

fn try_insert( &mut self, index: usize, element: T, ) -> Result<(), TryReserveError>

Inserts an element at position index within the vector, shifting all elements after it to the right.

Panics

Panics if index > len.

Examples

use fallible_vec::*;

let mut vec = try_vec![1, 2, 3]?;
vec.try_insert(1, 4)?;
assert_eq!(vec, [1, 4, 2, 3]);
vec.try_insert(4, 5)?;
assert_eq!(vec, [1, 4, 2, 3, 5]);

fn try_resize_with<F: FnMut() -> T>( &mut self, new_len: usize, f: F, ) -> Result<(), TryReserveError>

Resizes the Vec in-place so that len is equal to new_len.

If new_len is greater than len, the Vec is extended by the difference, with each additional slot filled with the result of calling the closure f. The return values from f will end up in the Vec in the order they have been generated.

If new_len is less than len, the Vec is simply truncated.

This method uses a closure to create new values on every push. If you’d rather Clone a given value, use try_resize. If you want to use the Default trait to generate values, you can pass Default::default as the second argument.

Examples

use fallible_vec::*;

let mut vec = try_vec![1, 2, 3]?;
vec.try_resize_with(5, Default::default)?;
assert_eq!(vec, [1, 2, 3, 0, 0]);

let mut vec = vec![];
let mut p = 1;
vec.try_resize_with(4, || { p *= 2; p })?;
assert_eq!(vec, [2, 4, 8, 16]);

fn try_splice_in<I: IntoIterator<Item = T>, A: Allocator>( &mut self, range: impl RangeBounds<usize>, replace_with: I, alloc: A, ) -> Result<(), TryReserveError>

Removes the items in range and replaces them with replace_with using the provided allocator for temporary allocations.

Panic safety

If replace_with panics on a call to next() then the items that were previously returned by that iterator will either be added to the Vec or dropped. Some of the items after the splicing point (i.e., the end of range) in the Vec may be leaked.

Panics

Panics if the starting point is greater than the end point or if the end point is greater than the length of the vector.

Examples

use fallible_vec::*;
use std::alloc::System;

let mut v = try_vec_in![1, 2, 3, 4 => System]?;
let new = [7, 8, 9];
v.try_splice_in(1..3, new, System)?;
assert_eq!(&v, &[1, 7, 8, 9, 4]);

fn try_extend_from_slice(&mut self, slice: &[T]) -> Result<(), TryReserveError>

where T: Clone,

Clones and appends all elements in a slice to the Vec.

Iterates over slice, clones each element, and then appends it to this Vec. slice is traversed in-order.

Note that this function is same as try_extend except that it is specialized to work with slices instead. If and when Rust gets specialization this function will likely be deprecated (but still available).

Panic safety

If a call to clone for one of the items in slice panics, then all items before the panicking item will have been added to the Vec.

Examples

use fallible_vec::*;

let mut vec = try_vec![1]?;
vec.try_extend_from_slice(&[2, 3, 4])?;
assert_eq!(vec, [1, 2, 3, 4]);

fn try_resize(&mut self, new_len: usize, item: T) -> Result<(), TryReserveError>

where T: Clone,

Resizes the Vec in-place so that len is equal to new_len.

If new_len is greater than len, the Vec is extended by the difference, with each additional slot filled with item. If new_len is less than len, the Vec is simply truncated.

This method will clone the passed value. If you need more flexibility (or want to rely on Default instead of Clone), use try_resize_with. If you only need to resize to a smaller size, use Vec::truncate.

Panic safety

If a call to clone for item panics, then the Vec will be partially resized with all of the items cloned before the panic.

Examples

use fallible_vec::*;

let mut vec = try_vec!["hello"]?;
vec.try_resize(3, "world")?;
assert_eq!(vec, ["hello", "world", "world"]);

let mut vec = try_vec![1, 2, 3, 4]?;
vec.try_resize(2, 0)?;
assert_eq!(vec, [1, 2]);

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<T, A: Allocator> FallibleVec<T> for Vec<T, A>

Available on crate feature allocator_api only.

fn try_extend<I: IntoIterator<Item = T>>( &mut self, iter: I, ) -> Result<(), TryReserveError>

fn try_extend_from_slice(&mut self, slice: &[T]) -> Result<(), TryReserveError>

where T: Clone,

fn try_push(&mut self, item: T) -> Result<(), TryReserveError>

fn try_insert( &mut self, index: usize, element: T, ) -> Result<(), TryReserveError>

fn try_resize(&mut self, new_len: usize, item: T) -> Result<(), TryReserveError>

where T: Clone,

fn try_resize_with<F: FnMut() -> T>( &mut self, new_len: usize, f: F, ) -> Result<(), TryReserveError>

fn try_splice_in<I: IntoIterator<Item = T>, ATemp: Allocator>( &mut self, range: impl RangeBounds<usize>, replace_with: I, alloc: ATemp, ) -> Result<(), TryReserveError>

Implementors